# Logo workshop guide

The workshop creates **Mulle Meck bygger bilar** and **Mulle Meck bygger båtar**.
Both original SVGs remain unchanged. The generated logos are separate files.

## Start

From the workspace root, run:

```sh
uv run python main.py
```

Open the address printed in the terminal. The server binds only to `127.0.0.1`.
If port 8000 is occupied, it chooses a free port. Use `--port 0` to request a free port immediately.
Stop the server with Ctrl+C.

Alternatively, open `studio/index.html` directly in a browser.
The HTML, JavaScript, and CSS use local assets. There are no network fonts, libraries, or analytics.
Keep the studio files together; the HTML is the entry point, not a standalone copy of the entire application.

On a first visit, both editions start with **#44 / Capital Tight Equal**. Later visits restore your saved composition.

## Browse and edit

The page opens with the editor, followed by a full-width gallery. The grid adapts to your screen width.
Use **Columns** to choose 3, 2, or 1 logos per row on a wide screen. Narrow screens show fewer columns. Choose an edition and family above the grid.
The editor stays visible above the gallery. Click a logo to load its settings and return to the editor.
Use **Edit current logo** in the header to return to your current composition.

The **Based on** banner identifies the starting alternative and marks later changes as **Edited**. Its gallery card stays highlighted. Saved settings and undo/redo retain the source separately for each edition. Older settings are matched only when they exactly equal a known alternative; otherwise the source is shown as unrecorded.

## Adjust the composition

The **Explore a wider range** gallery contains 92 compositions for each edition. Select a family to narrow the gallery.
Click a card to load its exact settings, including capitalization and horizontal rules. All settings remain editable.
See the [exploration guide](exploration/README.md) for comparison sheets, exports, geometry data, and the custom batch format.

Start with one of the four cards under **Try a stronger hierarchy**. **Title first** is the recommended balance; **Compact** keeps the supporting text larger. **Small signature** and **Offset** provide quieter or right-aligned alternatives. See the [comparison and exported files](variations/README.md).

Presets apply to the current edition and preserve case, color, tracking, and pair corrections. They reset layer transforms and row gap; undo restores the previous layout. Add `?preset=title-first` to the editor address to open that preset directly; optionally add `&edition=batar`.

1. Select **Bilar** or **Båtar**. Each edition retains its own settings.
2. Select a lettering layer in the inspector, or click its visible lettering on the canvas.
3. Drag to move it, or enter exact horizontal and vertical offsets.
4. Set size and rotation. All user scaling preserves the layer's aspect ratio.
5. Use **Gap below name** to set the space between the two rows.

The three layers are:

| Layer | Artwork | Placement behavior |
| --- | --- | --- |
| MULLE MECK | Original red and black paths | Uniform scale, rigid rotation, and translation only |
| bygger / Bygger | Regular Clarendon paths | Calibrated original pairs; inferred spacing for new pairs |
| bilar / båtar | Original subject paths | Follows the verb's width and bottom alignment, plus your offsets |

Moving the verb moves the subject with it. Subject offsets let you adjust the relationship independently.
Changing verb width also moves the subject horizontally. Changing subject size preserves its bottom alignment before manual offsets.
Independent rotations are available; rotating only the verb does not rotate the subject with it.
Offsets marked px use SVG user units, not screen pixels at the current zoom level.

**Fit name to the phrase** sets the name to approximately 94% of the phrase width.
It preserves the name's manual position. You can then adjust its offsets to align it as desired.

## Lettering

**Normal font · one line** uses ordinary Clarendon letter spacing, a native word space, uniform scaling, and a level baseline. Candidates 49–56 demonstrate the supplied reference direction. Candidates 57–80 expand it with all four capitalization combinations and varied spacing.
Choose **Newest 24 · same baseline** in the gallery filter to see the latest additions.

**Phrase layout** switches between original subject artwork and one continuous Clarendon line.
Continuous mode gives both words the same font scale and baseline. Use the verb controls to move, scale, or rotate the whole phrase.
Subject transforms are linked in this mode. **Word space** controls separation in font units.
Candidates 25–40 demonstrate this mode; candidates 01–24 remain unchanged.

The first-letter selector switches between lowercase **bygger** and capital **Bygger**.
Lowercase is the default, following the requested sentence. Both alternatives are also exported as starter files.

The independent **Subject first letter** selector switches between source **bilar/båtar** and **Bilar/Båtar**.
The capital option fits Clarendon B to the source subject typography and preserves the remaining source letters.
Its placement is an inferred extension; see the [capital subject measurements](exploration/README.md#capitalized-subject-measured-facts-and-inference).

**Tracking adjustment** adds spacing between every pair in the verb.
**Fine letter spacing** adds a correction to one pair, after the starting spacing and tracking adjustment.
These controls use font units; the supplied font has 1000 units per em.
The B-y control applies only to the capital alternative. The b-y control applies only to lowercase.

The new g-e pair would intersect under the initial mean-tracking estimate.
The defaults now separate new pairs by at least the original g-g contour clearance.
This is a documented design inference, not a historical kerning setting recovered from the source.
Manual negative adjustments can override that clearance, so inspect the preview after tightening pairs.

See [new-letter spacing](extension_analysis.md) for the exact starting advances and the distinction between facts and design choices.

Phrase color affects the verb and subject. The original red and black name artwork keeps its original colors.
The i dot and å ring remain part of their original subject artwork.

## Preview and keyboard controls

The **Horizontal rules** section controls none, left, right, or both sides.
Set length, separate right-side length, thickness, text gap, vertical offset, and color.
Enable **Double line** and set its separation for parallel rules.
Rule vertical offset is measured from the combined phrase's bounding-box center. Rules stay horizontal when lettering layers rotate.
Rules follow the phrase bounds as you move or resize the words, and are included in export bounds.
Their color follows the phrase unless you disable **Follow phrase color**.

- Turn on **Guides** to show layer bounds. Guides are never exported.
- Focus the canvas and press an arrow key to move the selected layer by one SVG unit.
- Hold Shift with an arrow key to move ten units.
- Use Ctrl/Command+Z to undo; Ctrl/Command+Shift+Z or Ctrl/Command+Y to redo.
- Use Ctrl/Command with the mouse wheel to zoom. **Fit view** restores automatic framing.
- Choose white, dark, or checkerboard preview backgrounds.

The source reference below the canvas remains unedited.
Downloaded SVGs fit all transformed layers with zero padding, including both SVGs in the ZIP. The padding control applies only to the preview and PNG exports.
Preview zoom does not affect the exported geometry.

## Save and restore

The editor attempts to save both editions automatically in this browser's local storage.
Storage availability can differ when opening local files or using a private browser window.
If storage is unavailable, the header says **Session only · save settings**.

Use **Save settings** to download a JSON project containing both editions.
Use **Open settings** to restore that project. Invalid settings are rejected without partially changing the current project.
The reset buttons are undoable during the current session. Undo history does not survive a page reload.

## Export

- **Download SVG:** current edition, outlined paths, no installed font required.
- **Download PNG:** current edition at 1×, 2×, 3×, or 4× resolution.
- **Both SVGs:** one ZIP containing the current settings for both editions.

Exports are transparent by default. Enable **Include preview background in exports** to add white or dark background artwork.
The checkerboard represents transparency; when background export is enabled for that preview, it exports white.
Large PNG exports are limited to 16,000 pixels on either axis and 80 million pixels overall.
Reduce resolution or extreme layer offsets if the editor reports that the image is too large.

SVG metadata records the settings, source and font hashes, and spacing-policy provenance.
SVG layer IDs are `mulle-meck`, `bygger`, and `subject`, for further editing in vector software.
For the full editable project, retain the settings JSON as well as the exported SVG.

## Starter files

- [Lowercase car logo](logos/mulle-meck-bygger-bilar.svg)
- [Lowercase boat logo](logos/mulle-meck-bygger-batar.svg)
- [Capital car alternative](logos/mulle-meck-bygger-bilar-capital.svg)
- [Capital boat alternative](logos/mulle-meck-bygger-batar-capital.svg)
- [Default settings](logos/default-settings.json)
- [Both editions preview](logos/editions.png)

## Reproduce the assets

```sh
uv sync --locked
uv run python prepare_studio.py
node export_logos.cjs
uv run python verify_studio.py
node tests/engine.test.cjs
```

The first command installs the locked Python dependencies.
The preparation script reuses the earlier font analysis, measures the boat SVG, and packages the source path assets.
It retains candidate-font scores, model comparisons, final convergence results, and visual diagnostics in `results/boats/`.
Pass `--refit` to repeat the boat optimization.

The same JavaScript layout engine drives the editor and command-line exports.
To export a project saved by the editor:

```sh
node export_logos.cjs --settings path/to/settings.json --output results/my-logos
```

Browser integration checks use a separate local Chromium instance and Node.js 22 or later:

```sh
chromium --headless --disable-gpu --remote-debugging-port=9222 --user-data-dir=/tmp/mulle-workshop-test about:blank
```

In another terminal:

```sh
node tests/browser.cjs
```

The browser runner checks desktop and mobile layouts, inputs, settings, transparent PNG output, ZIP contents, and native pointer dragging.
It saves screenshots and a JSON report. It can also accept a running editor URL as its first argument.
Some sandboxed environments require a separate permission to bind or access localhost.

The technical reports distinguish measured source geometry from the inferred new-pair spacing and flipped composition.
The reconstructed font contours closely match the source; they do not reproduce every traced corner or counter exactly.

Candidates **81–92** add larger, shared-baseline phrases at 84%, 89%, and 94% of MULLE MECK’s width. All previous 80 candidates remain unchanged.