@jokerized/decksmith 0.8.0 → 0.9.1

package/README.md

@@ -220,6 +220,49 @@ Arrow keys, Space and PageUp/PageDown step; clicking the left or right third doe
 notes; `f` is fullscreen; `m` mutes the voice and `s` hides the subtitles. Every step is
 deep-linkable (`#3` is slide 3, `#3.2` its second reveal).
 
+### The v2 player (`--design v2`)
+
+`build --design v2` (or `"design": "v2"` in the storyboard or config) gives `deck.html` the
+v2 player; everything else about the build is unchanged. A deck that is already built
+gets it without rebuilding:
+
+```bash
+decksmith repack out/            # writes out/deck2.html beside deck.html, never over it
+```
+
+`repack` swaps the inlined runtime, marks the page and checks that every JSON island is
+byte-identical — no Chrome, no TTS, no re-render.
+
+- **One control bar**: play/pause, the counter, narration speed (0.75–2×), `CC`, caption
+  size (S/M/L/XL) and fullscreen — or, in a window too narrow for those beside a caption,
+  play and one settings menu. **It never covers text.** It docks under the slide in spare
+  letterbox (a portrait phone); over the slide's empty bottom padding when that holds a
+  40px target (a slide about 720px tall or more), where it hides 2.5s after the last
+  pointer move while the deck plays; otherwise in a band under the slide that it shares
+  side by side with the captions, whose text is padded in past the buttons.
+  `test/deck-page.test.ts` measures controls against caption text and against every glyph
+  the slide draws, at six viewports.
+- **Play/pause** pauses the voice where it is and carries on from the same word. A deck
+  opens paused; stepping while paused moves the slide silently.
+- **Speed** sets the narration's `playbackRate` live, on the sentence already playing, and
+  divides the reveal glides and every autoplay wait by the same factor so they keep pace.
+  A stop with no narration holds for its reveal and 1.5s at 1×, not the author's gap.
+- **Captions** are sized from the slide (3% of its height, 13px floor; L and XL keep floors
+  of 16 and 19px so the size control works on a phone) and the slide gives up only one
+  two-line strip for them: 84% of the frame at 1080p, 83% in an 800×450 embed (v0.8.0: 77%
+  and 69%), 100% in a portrait letterbox. Long cues are cut to two lines of the strip's
+  actual width, which also splits Japanese and Chinese.
+- **Keys:** Space steps forward (Space is the presenter's key, not play); `Enter` plays and
+  pauses; `c` (or `s`) captions; `<`/`>` speed; `+`/`-` caption size. Letter keys fall back
+  to the physical key under a Korean or Japanese IME. Anything held with Cmd, Ctrl or Alt
+  is left to the browser.
+- **Preferences** — speed, captions on/off, size — come from `?speed=1.25&cc=0&ccsize=l`
+  (this visit only), else from `localStorage` (`decksmith.prefs.v1`), else the defaults.
+  When the viewer changes one, the deck posts
+  `{ type: "decksmith:prefs", speed, cc, ccsize }` to its parent so an embedding site can
+  keep it per user (a cross-site iframe's storage is partitioned), and it applies the same
+  message when the parent sends it. Check `event.origin` on your side.
+
 Stepping forward *plays* the reveal rather than cutting to it — the step layer sweeps the
 composition's timelines across frames instead of seeking once. Backward steps, `Home`/`End`
 and deep links cut, because entrance tweens run in reverse look like elements un-drawing
@@ -784,8 +827,11 @@ invalidates a storyboard you have already edited.
 | `lang` | the source's | plan | BCP-47. Drives the copy, the voice, and the font subset |
 | `tone` | `plain` | plan | `plain` · `academic` · `conversational` · `punchy` |
 | `density` | `normal` | plan | `sparse` · `normal` · `dense` — how much text a slide may carry |
-| `theme` | `ink` | emit | `ink` · `paper` · `mono` |
+| `theme` | `ink` | emit | `ink` · `paper` · `mono`, or a v2 style pack by name (see Themes) |
+| `design` | `classic` | narrate, emit | `classic` is the v0.8.0 look byte for byte · `v2` is the redesign: the v2 player (see "The v2 player") and a style pack per deck when no theme is named |
+| `packSeed` | the source id | narrate, emit | what `design: v2` hashes to pick a pack; pass a paper id so its languages share one |
 | `animationSpeed` | `1` | emit | multiplies every duration, hold and beat length. Below 1 is faster |
+| `design` | `classic` | emit | `classic` (the 0.8 look, byte-identical) · `v2` (the redesign — see [v2 motion](#v2-motion)) |
 | `narration.voice` | picked for `lang`+`tone` | narrate | an explicit edge-tts voice id |
 | `narration.rate` | `+0%` | narrate | edge-tts prosody |
 | `narration.pitch` | `+0Hz` | narrate | edge-tts prosody |
@@ -832,8 +878,8 @@ why `slideCount` did nothing.
 decksmith.config.json: unknown preference "narration.speed". Valid: enabled, voice, rate, pitch, subtitles.
 ```
 
-On the command line: `--slides --lang --tone --density` on `plan`, `--theme --speed` on
-`build`, `--voice --rate --pitch --no-subtitles` on `narrate`, `--images --image-provider
+On the command line: `--slides --lang --tone --density` on `plan`, `--theme --design
+--pack-seed --speed` on `build` (`--design --pack-seed` on `narrate` too), `--voice --rate --pitch --no-subtitles` on `narrate`, `--images --image-provider
 --image-model --image-style --image-max` on `plan` and `illustrate`, and all but the image
 flags on `pack`, which records the preferences the deck was made under — whether it was
 illustrated is read off the storyboard itself, the way `narration.enabled` is read off the
@@ -841,9 +887,255 @@ narration beside it.
 
 A preference sitting at its default says nothing, so a stored artifact wins over it and
 loses to anything you type. `plan` stamps `lang` and `theme` into the storyboard it
-writes; `build` then uses the storyboard's unless `--theme` or a config file restates one.
+writes (and `design`, only when one was asked for); `build` then uses the storyboard's
+unless `--theme`/`--design` or a config file restates one.
 Language is never overridden at build time — it describes copy that is already written.
 
+`--design v2` (or `"design": "v2"` in the config file) lets the build vary each beat's
+layout: bars as rows or columns, a pipeline as a row, a stair or a column, a claim beside,
+mirrored against or above its figure, a comparison as columns or rows, and the headline on
+top, in a left rail or under the body. The choice is made by code, deterministically, per
+paper — never by the planner — and it never moves a stop, so narration stays aligned.
+`build` writes the choices to `out/look.json`. Without the flag the deck is the classic one,
+byte for byte. See `.planning/2026-10-07-v2-layout-director.md`.
+
+## v2 motion
+
+`--design v2` replaces the 0.8 deck's single motion — every scene fading up the same
+eyebrow and headline, every seam the same 0.4s dissolve, nothing moving once a slide has
+built — with a grammar planned per deck (`src/emit/motion.ts`):
+
+- **Entrances.** Six verbs — `rise`, `slide`, `snap`, `focus`, `wipe`, `mask` — one per
+  scene, chosen from the source id and beat id, never the same twice in a row, with the
+  stock `rise` capped at a quarter of the deck.
+- **Seams.** `dissolve`, `push`, `lift`, `wipe`, `zoom`, picked from how two neighbouring
+  beats relate (same family → push, a role boundary → zoom, a title → lift, into the close
+  → dissolve), never repeated back to back, and at least three kinds in a deck of ten or
+  more beats. A beat `inside` the one before keeps the camera dive.
+- **Emphasis while the narrator talks.** The part a sentence is about pulses, glows or is
+  underlined, starting on a cue boundary of that sentence inside the quiet stretch after
+  its stop, and is back at rest before the next reveal — so every frame a gate captures
+  at a stop is unchanged.
+
+All of it is `fromTo` tweens with no callbacks, seeded rather than random, and keeps every
+hold, every scene window and `timing.json` exactly as `classic` writes them. In `deck.html`
+a v2 deck also glides through the seam into the next slide (0.8 cut to its first stop,
+already built) and, while a stop's audio plays, seeks the scene through that stop's quiet
+stretch on the audio clock so the emphasis lands on the same word as in the video. Both
+are off under `prefers-reduced-motion`.
+
+## v2 bespoke scenes (`--bespoke`)
+
+The archetypes finish building in about five seconds and then hold still while the voice
+keeps talking. `build --design v2 --bespoke` hands four to six beats per deck to Codex
+instead: for each, a GSAP + SVG scene written for that beat, keyed to its narration cues,
+that keeps explaining for as long as the sentence runs. Everything else stays v2. It is off
+unless asked for; v2 without it, and classic, emit the bytes they did.
+
+```bash
+decksmith build storyboard.json --source source.json -o deck --design v2 --bespoke
+# bespoke: b03-action-loop.draft in 121s …
+# bespoke: b05-backbone — every gate passed and the rubric probe is clean; no critique call
+# bespoke: 4 of 5 beats drawn bespoke, 7 Codex call(s), 190985 tokens, 343s
+```
+
+**Which beats.** A deterministic rule (`src/bespoke/select.ts`): mechanism archetypes
+(pipeline, equation-walk/-morph, line-chart, stack, grid, split-/bar-compare, and figures
+last), mechanism words in en/ko/ja/zh, a cited equation, and the beat's weight; ties
+broken by a hash. Never a title, callout or table, a beat with no narration, or a beat a
+camera dives through. `plan --bespoke` lets the planner mark beats `bespoke: true|false`;
+`false` is obeyed, `true` is a strong hint.
+
+**Per beat:** illustration → draft → static contract → probe deck (a real build with every
+`verify` gate plus the motion gates, photographed at every cue) → the rubric probe → at most
+one critique-and-fix call with the contact sheet and the measures attached (`codex exec -i`)
+→ static contract → probe again → repair rounds. A draft that passed every gate and is clean
+by the rubric probe is kept without the critique call; one that fails only on what the
+repair fixes, and is otherwise clean, is repaired instead of critiqued. A beat that does not
+pass keeps its archetype — the deck is never failed. If the fix round breaks a draft that
+passed, the draft is kept.
+
+**The illustration** (`src/bespoke/art.ts`, `src/bespoke/inspect.ts`). Every bespoke beat
+but a data beat gets ONE picture from the image tool of the same Codex account
+(`codex exec` with every tool off but `image_generation`; no API key — the account's own
+login, as for the scenes), all of a deck's pictures asked for at once before the drafts
+queue for their lanes. The illustrator is given the beat (fenced, untrusted), the pack's
+colours and one fixed style paragraph — flat 2D vector, solid fills with hard edges; no
+gradients, shading, shadows, gloss, 3D, clay or toy renders, by name — and asked for three
+or four subjects doing the method, big, left to right, with empty ground between them and
+NO text. Each picture is then inspected locally, for free: its subjects are the connected
+regions that are not its flat ground (boxed, left to right); its flatness is how much of
+it sits in its 16 commonest colours minus how much of it is soft shading (`FLAT_MIN`,
+calibrated on round 3's 21 renders against 12 flat pictures); and its writing is read by
+macOS Vision, once per script (en, ko, ja, zh), through a small Swift helper compiled once
+into `~/.cache/decksmith/tools`. A picture with writing, a shaded render or one whose
+subjects touch is redrawn ONCE with the reason; of two refused pictures the one without
+writing and the flatter is kept, and one with writing never is. Off macOS the text check
+reports `unchecked` in `bespoke.json` rather than passing. The deck gets a WebP with its
+edges feathered into transparency for its box (~30-75 KB against 1.3 MB of PNG; a CSS mask
+on the picture cost ~0.7s a probe frame); the draft call is shown the PNG and a copy with
+the subjects boxed and numbered (`-i`). The shell places it: `<image data-art="1">` with no
+href gets the href and a fixed placement covering the body box (`slice`), so the subjects'
+boxes are known in box px before the scene is written. It is read only from
+`$CODEX_HOME/generated_images/` (after symlinks), only as a PNG by its magic bytes, under
+12 MB. `--bespoke-art <n>` (default 6; `bespoke.art`) caps pictures per deck, counted apart
+from `--bespoke-calls`; a beat whose picture cannot be had is drawn without one.
+
+**Data beats** (line-chart, bar-compare, data-table) get no picture: their scene is asked
+for the chart that builds with the voice — axes draw, bars grow with their counters, the
+line traces, the named value lights — from the beat's own numbers, never a table painted
+over an illustration (`data_over_picture`).
+
+**The camera** of an illustrated scene is the shell's, staged in one grammar
+(`src/bespoke/shots.ts`). The scene names its `shots` — on which cue, how far into it, which
+subject — and the shell compiles them: an ESTABLISHING shot of the whole picture for at
+least 1.6s, a PUSH IN (1.1s, power3.inOut) that frames the named subject and its label at
+1.6-2.2x, a move straight to the next subject, a 3% creep while a shot is held, and a
+REVEAL back to the whole picture at the last cue; shots closer than 1.6s are dropped. Every
+camera tween is a `fromTo` with explicit from-values, and no two touch. The scene's own
+script may not move `#sN-cam` (`script_camera`). A scene without a picture still moves the
+wrapper itself (`scale`/`x`/`y`, arithmetic in the prompt). A scene with a moving camera is
+clipped to its box and marked `data-ds-clip`, so `verify` does not count what a push-in
+carries past the canvas edge as off-canvas.
+
+**The labels** of an illustrated scene are the shell's too (`src/bespoke/callouts.ts`). The
+scene says what each subject is called (`labels`); the shell gives each subject a zone just
+above it (or across its top when there is no room), as wide as half the gap to each
+neighbour, and sets the name there on a plate — 56px, shrinking to 44, then two lines —
+with a leader line to a dot on the subject, entering as the camera first arrives on it (or
+at the reveal). The zones are in the draft prompt, which tells the scene to keep its own
+drawing out of them; a name that does not fit even on two lines at 44px is refused
+statically (`labels`). Round 4's first run, with the scene placing its own labels on the
+subjects, put them there and then failed four scenes in five on their own plates and
+leader lines crossing their text.
+
+**Repair** (`src/bespoke/repair.ts`), no model call. On `text_overlap`,
+`graphic_crosses_text` or `svg_text_overprint`, each colliding label's unit (the text, or
+the smallest `<g>` holding it and its plate) gets one constant offset — the smallest, in
+8px rings over sixteen directions in a fixed order — that clears every other label by 16px,
+every visible stroke sample by 10px and every shape painted over it, inside the box, at
+every frame the probe measured, camera scale included; it is written as a wrapping
+`<g transform="translate()">`. A label never moves farther than 0.8 of its own height
+(at least 32px): a collision that needs more is left to the critique round. On
+`end_dimmed`, the elements dimming parts the scene had lit are tweened back to full
+strength just before the end; on `camera_end`, the camera is tweened home. On `seek_order`,
+two tweens on one target animating one property over overlapping time — which a timeline
+resolves one way seeking forward and the other seeking back — are untangled in favour of
+the later one (the earlier is shortened to end where it starts, or loses that target or
+property when both start together; `src/bespoke/untangle.ts`). A repaired scene goes
+through the static contract and is gated again (at most two repair rounds).
+
+**What the model is shown** (`src/bespoke/prompt.ts`): the beat, its cues, the paper's
+excerpts (fenced, untrusted), the contract, motion-design rules with numbers (one focal
+element per cue at 88-120px, the rest dimmed but kept; fill the box; paint it with filled
+shapes; at least three kinds of motion, one of flow, camera, counter or morph; the end
+frame a summary), text widths measured in the pack's own font, and two of four hand-made
+reference scenes (`src/bespoke/references.ts`: a routing mechanism with particle flow and
+a counter, a camera zoom into one block, a traced curve whose gap morphs into the headline
+number, a scatter whose dots travel into a bell, and — first, for a beat with an
+illustration — a scene built on its picture), picked for the beat's archetype and painted
+in the pack's colours. `test/bespoke-references.test.ts` runs each reference
+through every gate and the rubric probe in a real deck, so a reference that stops passing
+stops being one. Parts a cue introduces are `<g data-cue="N">` groups (semantic grouping,
+after Vector Prism, arXiv 2512.14336). MorphSVG is registered for a deck only when one of
+its scenes morphs.
+
+**The rubric probe** (`rubricProbe`, free: it reads what the probe measured) sends a
+passing draft to the critique round when any of these is off: the drawing paints under 12%
+of its box at the end (round 1's scenes painted 4-16%), more than half its parts are still
+dimmed at the end, no label reaches 88px (not asked of an illustrated scene, whose picture
+is its focus and whose names are the shell's), fewer than three kinds of motion or none of
+flow/camera/counter/morph, an illustrated scene that holds fewer than two push-ins, does not
+open wide, or names fewer than two subjects on them, a cue whose picture changes by under
+0.5% of the frame, or a warning about the scene. The critique round scores the frames against a six-line rubric
+(fills the stage, one focus per cue, motion explains, legible hierarchy, the pack, sync),
+is told the measures and every finding with the colliding labels' coordinates, and returns
+the fixed scene.
+
+**Caps**, checked before every call: `--bespoke-calls` (default 12; two per beat) and
+`--bespoke-seconds` (default 1800). A quota or rate-limit answer stops every further call.
+Codex runs only through the account's own CLI (`--bespoke-cli`, `--bespoke-model`), never
+an API key, five calls in flight (`bespoke.concurrency` in the config file), at
+`bespoke.effort` reasoning (default `medium`; `default` keeps the account's), from the
+scratch directory, and with its tools off: shell, apps, plugins, browser, image
+generation (the illustration call alone keeps it), web search and every MCP server the
+account configured. A bespoke call is a
+text transform; with tools on, the agent spent its first turns reading the account's own
+instruction files and skills (measured: 56,679 input tokens over several turns and
+135-488s for a draft that tool-less took one turn of 18,247 and 166s). A paced deck (`--speed`/`--duration` other than 1×) and non-16:9 formats are
+skipped, with a line saying so.
+
+**Cache.** Keyed by everything a scene is drawn from — the beat's words and params, the
+quoted excerpts, the cue windows, the stops, the box, the pack, the prompt and contract
+versions, the model, the illustration's key — under `~/.cache/decksmith/bespoke`
+(`--bespoke-cache`); pictures under its `art/`, keyed by the beat's words, the pack's
+colours, the art prompt's version and the model. A rebuild costs no calls. A beat the gates rejected after its critique round is cached as rejected;
+a fallback the beat did not earn (cap, quota, timeout) is not.
+
+**What a generated scene may run.** Three layers. (1) A static walk before anything is
+built or opened (`src/bespoke/contract.ts`, acorn): GSAP timeline calls with literal vars
+at explicit seconds, `gsap.set`, scoped `root.querySelector`, `Math` minus `random`, local
+code; `window`, `document`, `fetch`, `eval`, timers, storage, navigation, callbacks and
+function-valued tween vars are refused by name; CSS must be scoped to the scene with no
+at-rules, `url()` or animation; markup is SVG and inline HTML with no handlers, SMIL or
+external references, and `<image>` only as the beat's illustration (`data-art="1"`, no
+href — the shell writes it); path data must be numbers and commands (a word in a `d`
+attribute is a console error that used to fail every scene probed with it). (2) A CSP `<meta>` in every composition that carries one —
+`connect-src 'none'`, no `unsafe-eval`, local files only — and a probe that fails a scene
+on any page error, request or navigation (an error that names no scene fails every scene
+probed with it, unless the value it quotes is in exactly one candidate, which is then the
+one failed). (3) The player's frame is sandboxed
+(`allow-scripts allow-same-origin allow-downloads`). The paper's text reaches the model
+fenced as untrusted data. The static walk is not a proof against obfuscation — a
+property name assembled from parts at run time gets past it — which is what (2) and (3)
+are for; and (3) isolates only when decks are served from another origin than the host.
+
+**The motion gates** (`src/verify/scenes.ts`) run on every scene `bespoke.json` lists, as
+errors: `static_hold` (the picture must change during every cue), `graphic_crosses_text`
+(a visible stroke through a label — a curve whose bounding box contains a label is not
+its plate — or a shape painted over one), `seek_order` (the frame must not depend on what
+was seeked before it, beyond 1500px of rasterising noise — counted on changed AREAS: a pixel
+counts when it and its 8 neighbours changed, so a picture re-rasterised a hair differently
+on its first paint, an outline round every subject, 12,698px raw, counts 309), `stage_fill` (the settled
+drawing's bounding box covers 80% of its box), `type_hierarchy` (one label of 64px or
+more at the end; not asked of an illustrated scene), `stray_marker` (an SVG marker painted where its line is not drawn),
+`early_reveal` (a `data-cue="N"` group showing more than 0.5s before cue N),
+`shot_variety` (an illustrated scene opens on the whole picture and the camera — sampled
+every 0.5s, no screenshot — HOLDS push-ins at 1.5x or closer on at least two different
+subjects; round 3's 1.1-1.4x pans are not push-ins), `label_anchor` (a label that names a
+subject sits within 96px of its box and covers no other subject by more than a quarter of
+itself, and at the end at least two subjects are named that way), `data_over_picture`
+(five or more numbers on the illustration),
+`cue_groups` (no such groups, or one naming a cue the scene does not have), `end_dimmed`
+(at the settled frame, more than 10% of the parts the scene had shown lit are left under
+0.6 opacity — a part drawn translucent from the start is not counted) and `camera_end` (the
+camera, or a viewBox, not home at the settled frame). Content
+outside a clipping `<svg>` — a camera zoomed in — is neither off the frame nor crossing
+anything. Overlap and crossing findings carry the labels' boxes in the body box's px.
+`seek_order` also runs on every other scene of a v2 deck, as a warning; it is what found
+the equation-walk bug fixed alongside this (22,037px before, 0 after). Below the tolerance
+and not traced: v2's equation-walk on the narrated demo differs by 529px on one KaTeX
+glyph when reached from past the scene's end.
+
+`build` writes `bespoke.json` beside the deck: what was drawn and from where (cache,
+draft, critique), why each fallback, calls, tokens, seconds, the stages' wall clock, each
+picture's inspection (subjects, flatness, writing, draws) and each scene's staging
+measures. The full motion probe that `verify` would run again on a generated scene is
+skipped by `build` when the pass already ran it on the same bytes at the same scene id
+(`gatedAt`); `build` still seeks it with the deck's other scenes. `decksmith verify <dir>`
+always runs it. Set
+`DECKSMITH_BESPOKE_WORK=<dir>` to keep the prompts, replies and contact sheets.
+
+**Costs** (measured on four HypePaper decks, twice each, see
+[`.planning/2026-10-09-v2-bespoke-round4.md`](.planning/2026-10-09-v2-bespoke-round4.md)):
+an illustration takes 60-120s, a draft 90-220s and a critique 70-120s; a deck's pass took
+380-730s for 5-8 scene calls plus 3-7 pictures (redraws included) and 153-227k tokens, and
+the whole `build` 466-812s on a Mac with 9-23% memory free — three builds of eight under ten
+minutes. The pictures add 128-348 KB of WebP to a deck (round 3: 6-7 MB of PNG). Round 3
+took 593-742s and 214-325k tokens; round 1 13-31 minutes and 540-705k. A rebuild from the
+cache makes 0 calls. None of that fits a 300-second build timeout: a host running this has
+to give `build` that long, or run it off the request path.
+
 ## Themes
 
 Three, each a position rather than a hue.
@@ -862,6 +1154,41 @@ naming a family the deck does not declare falls back silently.
 A theme is a name and a palette, and that is the whole extension point: a new one is a
 file in `src/emit/themes/` plus a line in `THEMES`. No archetype learns it exists.
 
+### v2 style packs
+
+Six more, each a whole look rather than a palette: its own typeface pairing and type
+scale, ground and accent, eyebrow treatment, figure framing and surface.
+
+| Pack | Ground | Headline / body | Title | Lists | Bars | Leans to |
+|---|---|---|---|---|---|---|
+| `signal` | violet-black, Magma accent | Space Grotesk / Inter | glowing headline | ticks | pills | foot headlines |
+| `blueprint` | navy, cyan | IBM Plex Sans / IBM Plex Sans | drawing frame with corner marks | numbers | square, on dashed tracks | rail headlines |
+| `atlas` | espresso, amber | Source Serif 4 / Inter | centred, frontispiece rule | dots | slightly rounded | top headlines |
+| `folio` | cream, oxblood | Source Serif 4 / Source Serif 4 | masthead rules | numbers | square, no tracks | top headlines, versus |
+| `chalk` | cool white, ultramarine | Space Grotesk / IBM Plex Sans | highlighter under each word | cards | rounded, outlined | foot headlines, tables |
+| `journal` | sage, forest | IBM Plex Sans / Source Serif 4 | side bar down the title | ruled rows | slightly rounded, outlined tracks | rail headlines |
+
+The forms are the pack's `forms` (list marks, Director affinity) and its `skin` (title,
+bars), which may set only paint: colours, shadows, radii, outlines and SVG stroke/fill
+opacity, never a box. In a Korean, Japanese or Chinese deck a pack's serif roles are set
+in Noto Serif KR/JP/SC, bundled beside the sans.
+
+`--theme <pack>` forces one. `--design v2` picks one when nobody named a theme (a
+storyboard's default `ink` counts as nobody): a weighted, deterministic hash of the
+source id (or `--pack-seed`), leaning mildly toward packs that suit the deck's mix of
+archetypes. Over the 176 HypePaper storyboards on disk the busiest pack carries 20.5% of
+decks. With narration on disk, a pack that would stage a beat with a different stop count
+than the narration was recorded at, or that would leave out a beat the storyboard's own
+theme draws, is skipped for the next one; if none fits, the storyboard's own theme is kept.
+So `--design v2` never breaks a narrated rebuild and never costs a slide.
+
+Each pack's faces ship beside a Latin deck, vendored from `@fontsource-variable/*` like
+Inter, and are measured by their own width tables (`src/emit/faces.ts`, written by
+`node scripts/measure-faces.mjs --write`). A CJK deck keeps its Noto bundle first in every
+stack — Noto Serif for a role the pack sets in a serif, Noto Sans otherwise — so the glyph
+shapes change with the pack in every language.
+The packs' interfaces are written up in `.planning/2026-10-07-v2-style-packs.md`.
+
 ## Narration
 
 ```sh
@@ -1278,6 +1605,8 @@ src/prefs.ts          the three-layer preference resolver
 src/emit/kit.ts       the seam between the deck shell and the archetype emitters
 src/emit/archetypes/  one emitter per archetype
 src/emit/themes/      one palette per file; the registry is the extension point
+src/emit/type.ts      type specs: the v2 packs' faces and chrome scale, read by chromeHeight and chromeCss
+src/emit/faces.ts     measured width tables for the packs' Latin faces (generated)
 src/images/           the three rungs a brief is drawn through, and the illustrate step
 src/narrate/          edge-tts, one segment per stop
 src/pack/             the .deck container and its bake/link/embed policy