@jokerized/decksmith 0.7.0 → 0.9.0

package/dist/types/emit/archetypes/equation-walk.d.ts

@@ -10,7 +10,14 @@ import type { Term } from "../../types.js";
 import type { Emitter, Theme } from "../kit.js";
 export declare const OPTS = "{ displayMode: true, trust: function (c) { return c.command === \"\\\\htmlClass\"; }, strict: false, output: \"html\" }";
 export declare const INLINE_OPTS = "{ displayMode: false, trust: function (c) { return c.command === \"\\\\htmlClass\"; }, strict: false, output: \"html\" }";
-/** Where `term` sits in `tex`, comparing normal forms. Null when it is absent. */
+/**
+ * Where `term` sits in `tex`, comparing normal forms. Null when it is absent.
+ *
+ * The span starts at the first matched character's token — with the `\left`
+ * that sizes it, when the term opens on a sized delimiter — and ends where the
+ * last matched character's token ends. Never further: whatever follows the term
+ * in the equation, a `\right` included, is not the term's.
+ */
 export declare function locate(tex: string, term: string): {
     start: number;
     end: number;
@@ -36,7 +43,47 @@ cls?: (t: Term) => string): {
     tex: string;
     used: Term[];
     missing: Term[];
+    broken: Term[];
 };
+/** What `prepareWalk` decided about one equation and its terms. */
+export interface PreparedWalk {
+    /** The TeX to render, repaired and term-wrapped. Absent when `plain`. */
+    tex?: string;
+    /** The repaired TeX without wrappers, for measuring. The source TeX when `plain`. */
+    raw: string;
+    /** Set when KaTeX refuses the equation even after repair. */
+    plain?: {
+        error: string;
+    };
+    used: Term[];
+    missing: Term[];
+    notes: string[];
+}
+/**
+ * Everything the walk needs to draw one equation, decided in Node — so `plan`
+ * can report it and `build` cannot ship a `katex.render` call that throws.
+ *
+ * The equation is parsed and, if KaTeX refuses it, repaired (`repairTex`). Each
+ * term is repaired the same way, so a term spelled with the paper's own macro
+ * still finds it once both are drawn as names. Then the terms are wrapped, each
+ * wrapping parsed before it is kept.
+ *
+ * An equation no repair makes parseable is DEGRADED, not dropped and not
+ * shipped: `plain` is set and the slide shows the TeX source as text, with the
+ * terms still marked so the walk still walks. `notes` says, in words, every
+ * repair, degradation and dropped term — `plan` prints them and `build` reports
+ * them as the beat's warnings.
+ */
+export declare function prepareWalk(eq: {
+    id: string;
+    tex: string;
+}, terms: readonly Term[], beatId: string): PreparedWalk;
+/**
+ * A legend chip's contents: the term's TeX for KaTeX when it parses inline
+ * (repaired if it had to be), and its source as plain text when it does not —
+ * a chip is where a viewer reads WHICH symbol, so it is never left empty.
+ */
+export declare function chipSetup(sid: string, term: Term): string;
 /**
  * Display equations want to live between 68px and 108px.
  *
@@ -58,6 +105,18 @@ cls?: (t: Term) => string): {
 export declare function equationSize(tex: string): number;
 /** Estimated rendered width of a display, in ems. */
 export declare function texUnits(tex: string): number;
+/**
+ * Grow each legend chip to hold the glyphs KaTeX set in it.
+ *
+ * A chip is a painted box with 2px of vertical padding, and the layout gate
+ * measures text against the nearest painted box. `x^{\text{gt}}_{<i}` or a
+ * `\frac` sets glyph boxes above and below the line box, so the chip failed
+ * `text_box_overflow` on its own superscript — measured on HypePaper deck
+ * 0ef77cae: the `gt` sat 10px above the chip's top edge. Padding is added only
+ * where a glyph box actually crosses an edge, so a chip that already held its
+ * term is untouched.
+ */
+export declare function chipFit(sid: string, terms: Term[]): string[];
 /** One row per term: a chip KaTeX fills in `setup`, and the label. Shared with the morph. */
 export declare function legendRows(sid: string, terms: Term[], theme: Theme): string;
 export declare function legendCss(theme: Theme): string;

package/dist/types/emit/archetypes/grid.d.ts

@@ -1,16 +1,2 @@
-/**
- * A field, and the windows that move over it.
- *
- * Attention spans, receptive fields, patches, pooling kernels, token sequences —
- * every paper draws these as a rectangle over a lattice, and every slide deck
- * then writes "8x8 shifted windows" in a bullet and calls it explained. The
- * content of the idea is *which cells* and *how many of them*, and a sentence
- * cannot show that; a lattice with the rectangle lit on it shows nothing else.
- *
- * Everything here is solved from the box that is actually free after the chrome
- * and the note, so a 24x16 feature map and a 2x1 pair of patches are the same
- * code. A constant cell size would be right for one grid and wrong for the other
- * twenty-three, and nobody would ever find out which.
- */
 import type { Emitter } from "../kit.js";
 export declare const grid: Emitter<"grid">;

package/dist/types/emit/archetypes/line-chart.d.ts

@@ -1,11 +1,3 @@
-/**
- * A chart the source never drew.
- *
- * Papers report sweeps as tables and leave the shape of the curve to the reader.
- * Drawing it is the whole point of this archetype, so everything here is derived
- * from the data — the scale especially. A hardcoded axis is how a chart ends up
- * asserting something the numbers do not.
- */
 import type { Emitter } from "../kit.js";
 export interface Scale {
     min: number;

package/dist/types/emit/archetypes/pipeline.d.ts

@@ -43,6 +43,8 @@ type Loop = {
 export interface PipeLayout {
     /** Label type size. Never below `MIN_FONT`, whatever the labels cost. */
     size: number;
+    /** A stage note's type size: `NOTE` in classic, grown with the label in v2. */
+    note: number;
     /**
      * Position and extent along the flow axis: `x`/`w` read as x/width across a
      * row, and as y/height down a column. One field rather than two so the emitter
@@ -69,6 +71,18 @@ export interface PipeLayout {
     loopW: number;
     svgH: number;
 }
+/**
+ * v2: how far the diagram may grow, and into what. Absent is v0.8.0 exactly.
+ *
+ * `budget` is the height the SVG may take (the region less the wrapper's margin
+ * and the note); `region` is the whole body region, which bounds a box's height
+ * at `GROWN_BOX_H` of it — the plan's `MAX_BOX_H = 0.8·region.h`. The label's
+ * preferred size grows by `GROWTH` and `fitBoxes` still shrinks it to the width.
+ */
+export interface PipeGrow {
+    budget: number;
+    region: number;
+}
 /**
  * All the geometry, with no SVG in sight.
  *
@@ -76,6 +90,6 @@ export interface PipeLayout {
  * archetype must never get wrong, and asserting it against numbers beats
  * asserting it against a rendered string.
  */
-export declare function pipeLayout(stageW: number, stages: readonly Stage[], loop?: Loop, face?: Face): PipeLayout;
+export declare function pipeLayout(stageW: number, stages: readonly Stage[], loop?: Loop, face?: Face, grow?: PipeGrow): PipeLayout;
 export declare const pipeline: Emitter<"pipeline">;
 export {};

package/dist/types/emit/archetypes/stack.d.ts

@@ -109,6 +109,6 @@ export interface StackLayout {
  * composition changes rather than the type: the note moves beside its label, on
  * the same line, right-aligned against the spine.
  */
-export declare function stackLayout(p: Params, format: Format, face?: Face): StackLayout;
+export declare function stackLayout(p: Params, format: Format, face?: Face, grow?: boolean): StackLayout;
 export declare const stack: Emitter<"stack">;
 export {};

package/dist/types/emit/composition.d.ts

@@ -11,8 +11,10 @@
  * timeline, wraps whatever the emitter returns, and closes the document.
  */
 import type { z } from "zod";
+import { type Direction } from "../plan/direct.js";
 import { type Cut } from "../plan/select.js";
-import type { Format, NarrationCanvas, Source, Storyboard, segmentSchema } from "../types.js";
+import type { Design, Format, NarrationCanvas, Source, Storyboard, segmentSchema } from "../types.js";
+import type { FitManifest } from "./fit.js";
 import { type Scene } from "./kit.js";
 /** A built deck. `page` is present only for navigable formats. */
 export interface Deck {
@@ -27,6 +29,17 @@ export interface Deck {
      * PASS. `build` prints every casualty's reason; see src/cli.ts.
      */
     cut: Cut;
+    /**
+     * v2 only: each drawn scene's predicted fill, for `fit.json`. Absent on a
+     * classic build, which writes no manifest and so is not graded for fill.
+     */
+    fit?: FitManifest;
+    /**
+     * `--design v2` only: the look the Director chose for each kept beat, and the
+     * deck's sameness numbers. `build` writes it to `out/look.json`. Absent on a
+     * classic build.
+     */
+    looks?: Direction;
 }
 type Segment = z.infer<typeof segmentSchema>;
 /**
@@ -57,6 +70,15 @@ export interface DeckNarration {
 export interface DeckOptions {
     /** Overrides `storyboard.theme`. Any name in the registry. */
     theme?: string;
+    /**
+     * Overrides `storyboard.design`. Absent or `classic` emits v0.8.0's bytes.
+     * `v2` marks deck.html for the v2 player (`markV2`), lets the archetypes grow
+     * into their regions and fills `Deck.fit` (see `../emit/fit.ts`), and runs
+     * the Director (src/plan/direct.ts) over the kept beats so each is drawn in
+     * the look it chose (src/emit/look.ts), and turns on the motion grammar in
+     * `motion.ts`: varied entrances, seams and emphasis during narration.
+     */
+    design?: Design;
     /** Multiplies every duration, hold, and beat length. 1 leaves bytes untouched. */
     speed?: number;
     narration?: DeckNarration;
@@ -118,7 +140,28 @@ export interface DeckOptions {
  * and because HyperFrames' own navigation is dead at 0.7.71/0.7.72 and still
  * dead at 0.8.27 as at 0.7.90 (EXPERIMENT-003), so the presented one has to be ours.
  */
-export declare function emitDeck(storyboard: Storyboard, source: Source, format: Format, runtimeJs: string, opts?: DeckOptions): Deck;
+export declare function emitDeck(storyboard: Storyboard, source: Source, format: Format, runtimeJs: string, options?: DeckOptions): Deck;
+/**
+ * How a v2 deck breaks and tracks CJK text. Empty for any other language.
+ *
+ * KOREAN BREAKS BETWEEN WORDS. Browsers break Hangul between any two syllables
+ * by default, and v2's narrow rail headlines and grown text made that happen on
+ * most rail slides: "생성 조건/인", "가장 높은 종/합 점수", "서로 다/른" (review,
+ * 2026-10-08: 8 of 8 rail headlines on one deck, against 1 break in total on
+ * the classic layouts). `keep-all` breaks only at spaces — which is also how
+ * `wrap` in svg.ts has always MEASURED Korean, so the layout's line counts and
+ * the browser's now agree — and `break-word` still breaks a single word wider
+ * than its line rather than letting it overflow, as `wrap` does.
+ *
+ * JAPANESE AND CHINESE keep breaking between characters, under the strict
+ * kinsoku rules, so a line never opens on small kana or closing punctuation.
+ *
+ * NO TRACKING ON A CJK EYEBROW. Letter-spacing made for Latin capitals pulls
+ * Hangul and kanji apart until "생성 결과의 실패" reads "생 성  결 과 의  실 패".
+ * Tracking only ever made the eyebrow wider, so dropping it never adds a line
+ * the chrome was not charged for.
+ */
+export declare function cjkTypesetCss(lang: string): string;
 /**
  * The beats this format actually draws, and why the rest are not there.
  *
@@ -228,4 +271,6 @@ export declare const PLAYER_FILE = "hyperframes-player.global.js";
  * determinism scan above all — do not apply to it.
  */
 export declare const DECK_PAGE = "deck.html";
+/** A literal `</script>` inside the bundle would close the tag that carries it. */
+export declare function closeSafe(code: string): string;
 export {};

package/dist/types/emit/faces.d.ts

@@ -0,0 +1,22 @@
+/**
+ * GENERATED by `node scripts/measure-faces.mjs --write`. Do not edit by hand.
+ *
+ * Advance tables for the Latin faces the v2 style packs set, measured in Chrome
+ * from the vendored @fontsource-variable packages — the files a built deck
+ * ships. Same recipe as Inter's `ADVANCE` in svg.ts: isolated advances with
+ * kerning off, max over 400/500/600/700 after dividing by that weight's factor,
+ * rounded up. `test/svg.test.ts` holds the result against drawn widths read
+ * out of the same browser. Re-run the script, never re-type a number.
+ */
+export interface FaceMetrics {
+    /** The CSS family a deck names it by — what `vendorFace` declares. */
+    family: string;
+    /** Mean advance ratio against 400, per weight the type scales use. */
+    weight: Readonly<Record<400 | 500 | 600 | 700, number>>;
+    tabularFigure: number;
+    tabularSeparator: number;
+    kernSlack: number;
+    advance: Readonly<Record<string, number>>;
+}
+export type MeasuredFace = "source-serif-4" | "space-grotesk" | "ibm-plex-sans";
+export declare const FACE_METRICS: Readonly<Record<MeasuredFace, FaceMetrics>>;

package/dist/types/emit/fit.d.ts

@@ -0,0 +1,127 @@
+/**
+ * THE FIT ENGINE'S VOCABULARY — what "full" means, in one place, for both the
+ * emitter that predicts it and the gate that measures it.
+ *
+ * WHY THIS EXISTS. Every archetype's solver could only SHRINK: `BAR_MAX = 96`,
+ * `MAX_BOX_H = 340`, a 50px claim, panels capped at their content plus a fifth.
+ * Whatever the region had left over, `.scene`'s `justify-content: center` turned
+ * into dead air above and below the slide. Measured on v0.8.0 decks (redesign
+ * plan 2026-10-07 §1): bar-compare and pipeline fill 51% of the canvas, and
+ * about 39% of final holds are hollow. Under `design: "v2"` an archetype GROWS
+ * into its region instead — type, marks and gaps, each up to its own cap — and
+ * reports how full it predicts the result to be.
+ *
+ * THE MEASURE: MAIN-AXIS FILL. The body region is the content box below the
+ * chrome: `contentW` wide, `contentH - chromeHeight` tall (`bodyRegion`). The
+ * main axis is the VERTICAL one, because that is the axis `.scene` stacks the
+ * chrome and the body along and therefore the axis every pixel of centring slack
+ * lands on — width is already spent by every landscape archetype (bar rails, a
+ * pipeline row, split columns all run the full measure), which is exactly why a
+ * width-or-height maximum called those slides FULL while they read as a thin
+ * band through the middle. So:
+ *
+ *   fill = (painted extent of the body, top to bottom) / (region height)
+ *
+ * The body's own top margin is not ink, so a body that uses every pixel it is
+ * given reads a little under 1. `verify/fill.ts` measures the same ratio on the
+ * rendered frame — pixels, not DOM boxes — and `fit.json` carries this file's
+ * prediction beside it, so the model is checked against the browser on every v2
+ * build rather than trusted (AGENTS.md: a gate passing is not evidence).
+ *
+ * THE BANDS are ResearchStudio-Reel's (2607.04438 §A2), with the action the
+ * plan assigns each: EMPTY < 0.70 (grow, or the next variant), SPARSE < 0.90
+ * (grow to the caps, spread gaps), FULL ≤ 1.00 (leave it), SPILLAGE ≤ 1.10
+ * (shrink gaps, then type, toward 40), OVERFLOW beyond (refuse, as today).
+ *
+ * PURE ARITHMETIC, AND IMPORTS NOTHING FROM AN ARCHETYPE. `title.ts` owns the
+ * chrome's type scale and every archetype imports it; a helper here that
+ * imported it back would be a cycle. Callers pass the region they computed with
+ * `bodyBudget`.
+ */
+import type { Design } from "../types.js";
+/** Below this the frame reads as hollow: a band through the middle of the slide. */
+export declare const EMPTY_BELOW = 0.7;
+/** At or above this the region is used; growth stops being worth its cost. */
+export declare const FULL_AT = 0.9;
+/** Past the region's bottom edge, into the padding. */
+export declare const SPILL_ABOVE = 1;
+/** Past this a layout is not tight, it is wrong. */
+export declare const OVERFLOW_ABOVE = 1.1;
+export type FillBand = "empty" | "sparse" | "full" | "spillage" | "overflow";
+/** Which of the five bands a main-axis fill falls in. */
+export declare function fillBand(fill: number): FillBand;
+/**
+ * What an archetype predicts about its own final hold, in reference px.
+ *
+ * In memory only — `Scene.fit`, like `Scene.parts`, is never serialised into the
+ * composition, so a classic build cannot move a byte because of it. The shell
+ * collects it into `fit.json` for v2 builds (`FIT_FILE`).
+ */
+export interface Fit {
+    /** `ink / region`, rounded to three places (invariant 10's precision). */
+    fill: number;
+    /** Height of the body region: content box below the chrome. */
+    region: number;
+    /** Predicted painted extent of the body, top of its first mark to bottom of its last. */
+    ink: number;
+}
+/** A prediction, rounded once here so two builds of one storyboard agree to the byte. */
+export declare function fitOf(ink: number, region: number): Fit;
+/**
+ * The growth factor the plan names for type and marks: `min(constant × G, …)`.
+ *
+ * 1.6, from density §2.1 — a 50px claim may set at 72 at most (50 × 1.44 is
+ * under it), a 96px bar at 153, a 46px bar label at 73. Each archetype applies
+ * it to its OWN caps and then still has to fit the region; G is a ceiling on
+ * how far a short beat may be blown up, not a target.
+ */
+export declare const GROWTH = 1.6;
+/**
+ * The largest scale in `[lo, hi]` whose layout height fits `budget`.
+ *
+ * `height(s)` must be monotone non-decreasing in `s`, which every layout here is:
+ * bigger type wraps to at least as many lines and each line is taller. Bisection
+ * to 1/128 of a step, then FLOORED onto that grid, so the answer is a short
+ * decimal that prints identically on every build (invariant 10) and never
+ * exceeds the budget it was solved for. `lo` is returned when even `lo` does not
+ * fit — the caller's own overflow refusal is what handles that case, exactly as
+ * it did before growth existed.
+ */
+export declare function growToFit(height: (scale: number) => number, budget: number, lo?: number, hi?: number): number;
+/**
+ * The share of its real measure v2 sets HTML text against when it predicts a
+ * line count it is about to GROW into.
+ *
+ * `wrap` is a width table, and the browser is a line breaker with rules the
+ * table does not know: kinsoku keeps `、` and `。` off the start of a line, so a
+ * Japanese sentence the table sets on three lines of eleven sets on four of ten.
+ * Classic got away with it because nothing it drew was sized to the last line —
+ * a 50px claim in a 560px column had air. Growth removes the air on purpose, so
+ * a miss of one line becomes a caption pushed 105px through the bottom of the
+ * slide: MEASURED on six ja/zh claim-figure and callout beats at 1.08–1.11 fill
+ * before this existed. SVG text is exempt — `text()` places its own lines from
+ * the same `wrap`, so there the prediction IS the drawing.
+ */
+export declare const MEASURE_SLACK = 0.92;
+/** Whether this emit is the v2 vocabulary. Absent means classic: every test context, every older caller. */
+export declare function isV2(ctx: {
+    design?: Design;
+}): boolean;
+/**
+ * The manifest a v2 build writes beside `index.html`, and `verify` reads back.
+ *
+ * Its PRESENCE is what marks a deck as v2 to the gate: `verify` runs on a deck
+ * directory, and the only trustworthy statement about how that deck was built is
+ * the one the build wrote into it — the same reasoning `readReserve` gives for
+ * `timing.json`.
+ */
+export declare const FIT_FILE = "fit.json";
+export interface FitManifest {
+    design: "v2";
+    scenes: {
+        id: string;
+        beat: string;
+        archetype: string;
+        fit?: Fit;
+    }[];
+}

package/dist/types/emit/kit.d.ts

@@ -6,7 +6,9 @@
  * and nothing else. Adding a domain means adding an emitter — the shell never
  * learns what a camera frustum or an orderbook is.
  */
-import type { Archetype, BeatOf, Format, Source } from "../types.js";
+import type { Archetype, BeatOf, Design, Format, Source } from "../types.js";
+import type { Fit } from "./fit.js";
+import type { Look } from "./look.js";
 /**
  * `.scene`'s padding, in reference px. `contentW`/`contentH` are what is left.
  *
@@ -158,6 +160,35 @@ export interface Theme {
         d: string;
     };
     fontStack: string;
+    /**
+     * The chrome's stack — eyebrow, headline, the title slide's headline — when a
+     * v2 style pack sets it in a face of its own. Absent means `fontStack`, which
+     * is every classic theme. Which spec it belongs to is read off `fontStack`
+     * (`faceOf`), so the two are declared together by the pack (`src/emit/type.ts`).
+     */
+    displayStack?: string;
+    /**
+     * A v2 style pack's component forms: how it draws the parts every deck has,
+     * so two packs differ in FORM and not only in colour (review, 2026-10-08:
+     * "one template in four colours"). Absent on every classic theme, which is
+     * what keeps a classic build's bytes v0.8.0's.
+     */
+    forms?: PackForms;
+}
+/** How a pack marks a list item. `tick` is the classic coloured bar. */
+export type ListForm = "tick" | "number" | "dot" | "card" | "rule";
+export interface PackForms {
+    list?: ListForm;
+    /**
+     * Which looks this pack leans towards, as score bonuses the Director adds
+     * (src/plan/direct.ts): by placement, and by `archetype:variant`. So the
+     * same storyboard opens differently under two packs instead of every deck's
+     * second slide being the same two-column comparison.
+     */
+    affinity?: {
+        placement?: Partial<Record<"top" | "rail" | "foot", number>>;
+        variant?: Readonly<Record<string, number>>;
+    };
 }
 export interface EmitContext {
     source: Source;
@@ -202,6 +233,24 @@ export interface EmitContext {
      * pass exists to measure holds, and every scene it emits is thrown away.
      */
     start: number;
+    /**
+     * `prefs.design`. ABSENT MEANS CLASSIC, and that is the contract that keeps
+     * v0.8.0's bytes: every hand-built test context, `narrate`, `refs` and
+     * `timing` omit it, and an emitter reads it only through `isV2` in `./fit.ts`.
+     * Those last three only count stops, and stop counts are identical under both
+     * designs by construction (test/fit.test.ts holds it), so they do not need it.
+     */
+    design?: Design;
+    /**
+     * `--design v2` only: the arrangement the Director chose for this beat — a
+     * body variant and where the chrome sits. See src/emit/look.ts.
+     *
+     * ABSENT ON EVERY CLASSIC BUILD, and absent means the classic scene byte for
+     * byte. The measuring passes (`planCut`, `narrate`, `timing`, `refs`) never set
+     * it either, which is safe because a look may change geometry and never time:
+     * the Director rejects any look whose holds or chrome landing differ.
+     */
+    look?: Look;
 }
 /**
  * A value in a GSAP vars payload that is JavaScript rather than data.
@@ -389,6 +438,29 @@ export interface Scene {
     holds: number[];
     /** CSS this archetype needs. Deduplicated by the shell, emitted once. */
     css?: string;
+    /**
+     * The archetype's own prediction of how full its final hold is — v2 only.
+     * In memory, never serialised into the composition (like `parts`); the shell
+     * collects it into `fit.json` and `verify/fill.ts` holds it against the
+     * browser. See `./fit.ts` for what the number means.
+     */
+    fit?: Fit;
+    /**
+     * How much of its body box this scene's body fills along the axis it grows
+     * on, 0–1: the drawn height over the height it was given. Optional, in-memory
+     * only — never serialised, so it moves no byte. The `--design v2` Director
+     * prefers the look that fills more (src/plan/direct.ts); an emitter that does
+     * not report it is scored as neither full nor hollow.
+     */
+    fill?: number;
+    /**
+     * The area, in reference px², at which this scene paints the paper's own
+     * figure — the image, not the white plate around it. In-memory only. The
+     * Director refuses a look that shrinks it well below what the classic look
+     * gives (`FIGURE_FLOOR` in src/plan/direct.ts): a figure is often the most
+     * informative thing in the deck, and v2 was trading it for a rail headline.
+     */
+    figureArea?: number;
 }
 export type Emitter<A extends Archetype> = (beat: BeatOf<A>, ctx: EmitContext) => Scene;
 /** Escape text destined for HTML text content or a quoted attribute. */
@@ -496,4 +568,34 @@ export declare function settle(target: string, at: number, seconds?: number, ori
  * transform on an inline box is a no-op, and the rise would render as a plain
  * fade with every gate green.
  */
-export declare function words(text: string, cls?: string): string;
+export declare function words(text: string, cls?: string, opts?: {
+    unspaced?: boolean;
+}): string;
+/**
+ * A word-by-word stagger that lands by the stop, however many atoms there are.
+ *
+ * The rise is timed against a fixed hold, so its last atom must start in the
+ * window eight words used to: a CJK claim split per character is 30-60 atoms,
+ * and at a flat 0.05s the second half of the sentence would still be invisible
+ * when the deck stopped on it. Past `full` atoms the spacing shrinks so the
+ * spread stays `base · (full − 1)`. v2 only; classic keeps its flat stagger.
+ */
+export declare function staggerFor(count: number, base: number, full?: number): number;
+/**
+ * The units `words(…, { unspaced: true })` sets, each an `inline-block` that
+ * rises on its own and is never broken across a line.
+ *
+ * WHY A CJK RUN IS NOT ONE ATOM. Split on whitespace alone, "每个查询只选取最相关的"
+ * is a single inline-block: it cannot wrap inside itself, so it jumps whole to
+ * its own line, and a mixed claim came out "每个查询只选取最 / 相关的 / k 个历史帧；不同 /
+ * token / …" (review, 2026-10-08, zh s10). Han and kana break between any two
+ * characters, so here each character is its own atom, Latin inside the run
+ * ("token", "k") stays one, and kinsoku punctuation rides on its neighbour.
+ * Hangul is spaced like Latin and stays word by word.
+ *
+ * `spaced`: whether whitespace separated this atom from the one before it.
+ */
+export declare function wordAtoms(text: string): {
+    text: string;
+    spaced: boolean;
+}[];

package/dist/types/emit/look.d.ts

@@ -0,0 +1,138 @@
+/**
+ * WHERE THE HEADLINE SITS, AND WHICH ARRANGEMENT A BEAT'S BODY TAKES — the
+ * `--design v2` layout vocabulary. Nothing here runs on a classic build.
+ *
+ * WHY THIS EXISTS. Measured over the 219 storyboards HypePaper built 2026-10-04..07
+ * (3,536 beats): four archetypes are 72% of every beat, each has exactly one
+ * arrangement, and 92.7% of scenes open on the same eyebrow + 64px headline block
+ * across the top of the slide. The founder's complaint — "the designs are always
+ * the same" — is that number. A `Look` is the two choices that change it without
+ * touching what a beat SAYS:
+ *
+ *   - `placement`: where the chrome (eyebrow + headline) sits. `top` is today's
+ *     slide; `rail` sets it in a left column with the body beside it; `foot` puts
+ *     the body first and anchors the headline under it.
+ *   - `variant`: one of a small set of arrangements an archetype can draw its
+ *     body in — bars as rows or as columns, a pipeline as a row, a stair or a
+ *     column, a claim beside or above its figure, a comparison as columns or rows.
+ *
+ * THE ONE RULE A LOOK MAY NEVER BREAK: it changes geometry, never TIME. A look
+ * draws the same stops at the same seconds as the classic scene (`holds`) and its
+ * chrome lands when the classic chrome lands (`openSeconds`). That is what keeps
+ * narration aligned: `narrate` counted stops from the classic emitter,
+ * `render/timing.ts` re-derives holds from it, and `assertHoldsAgree` refuses a
+ * deck whose island disagrees. The Director (`src/plan/direct.ts`) checks this
+ * per candidate and drops any look that moves a hold, so a variant with a timing
+ * bug degrades to the classic scene instead of shipping misaligned audio.
+ *
+ * WHY THE CLASSIC LOOK IS `undefined` AND NOT `{variant: "...", placement: "top"}`.
+ * A classic build must emit the bytes v0.8.0 emitted. Every emitter treats an
+ * absent `ctx.look` and the default look identically (`frameOf` returns the
+ * classic frame for both), and only a non-default look writes anything new.
+ *
+ * INTERFACE FOR THE OTHER v2 TRACKS. `EmitContext.look` is the only field this
+ * adds to the emit seam. A track that changes type scale or motion reads the
+ * frame it is given; a track that changes fill can report `Scene` numbers the
+ * Director may later score on (see `direct.ts`, "fill").
+ */
+import type { Archetype, Beat, Format } from "../types.js";
+import type { EmitContext, Tween } from "./kit.js";
+import { type Face } from "./svg.js";
+export type Placement = "top" | "rail" | "foot";
+/** What `build --design v2` writes beside the deck: the Director's decisions. */
+export declare const LOOK_FILE = "look.json";
+export interface Look {
+    /** One of `VARIANTS[archetype]`. The first entry is the classic arrangement. */
+    variant: string;
+    placement: Placement;
+}
+/**
+ * The arrangements each archetype can draw, classic first.
+ *
+ * Only the four archetypes that carry 72% of beats have more than one. The other
+ * nine stay classic: their volume is too small to move the sameness numbers, and
+ * every variant is one more geometry that has to stay inside the 40px floor and
+ * the canvas with no gate that sees a clip.
+ */
+export declare const VARIANTS: Readonly<Partial<Record<Archetype, readonly string[]>>>;
+/** The classic look for an archetype: its first variant, chrome on top. */
+export declare function classicLook(archetype: Archetype): Look;
+/**
+ * The variant an emitter should draw. Absent look → the classic one, so a
+ * classic build and a v2 build that chose the classic look are one code path.
+ */
+export declare function variantOf(ctx: EmitContext, archetype: Archetype): string;
+/**
+ * `archetype:variant@placement` — what the sameness metrics count. Two beats
+ * with the same signature look the same at a glance; two with different ones do
+ * not, whatever their text says.
+ */
+export declare function signature(archetype: Archetype, look?: Look): string;
+/**
+ * Whether the canvas is wide enough to set a headline in a column beside the
+ * body. 16:9 only in practice: at 1:1 the rail would be 292px and a 64px
+ * headline would set three words a line.
+ */
+export declare function railable(format: Format): boolean;
+/**
+ * The looks the Director may choose between for one beat, before any is emitted.
+ *
+ * Not the full variant × placement product: some pairs are geometry nobody
+ * should draw. A claim set beside its figure inside a 1,058px rail body leaves
+ * the figure a 440px column, and a pipeline column across the full 1,700px top
+ * body is a stack of slabs. Off 16:9 only the classic variant is offered, at
+ * either end of the slide — the portrait arrangements ARE the stacked variants.
+ */
+export declare function candidates(beat: Beat, format: Format): Look[];
+/** The rail's share of the content width, and the channel between rail and body. */
+export declare const RAIL_SHARE = 0.34;
+export declare const RAIL_GAP = 72;
+export declare const FOOT_SEP: number;
+/**
+ * The box a body lays out in, and how the chrome is set around it.
+ *
+ * Every emitter that has variants asks for one of these in place of the
+ * `contentW` / `bodyBudget` / `chrome()` trio it used before. For the classic
+ * frame each member is EXACTLY that trio — same arguments, same strings — which
+ * is what keeps a classic build byte-identical (test/look.test.ts holds it).
+ */
+export interface Frame {
+    readonly placement: Placement;
+    /** Width the body lays out in, reference px. */
+    readonly w: number;
+    /** The column a closing note under the body sets in. */
+    readonly noteW: number;
+    /**
+     * Height the body may take: the content box less the chrome when the chrome
+     * is stacked with the body, less `below` (a note, a caption band), less the
+     * body's own top margin `top`. `floor` is `bodyBudget`'s last resort.
+     */
+    budget(below?: number, top?: number, floor?: number): number;
+    /** The scene's HTML: chrome and body in this placement's arrangement. */
+    compose(body: string): string;
+    /** Scoped CSS this placement needs. Empty for the classic frame. */
+    readonly css: string;
+    /** Tweens this placement adds (the rail's accent bar, an aside). Never a hold. */
+    readonly tl: Tween[];
+}
+/**
+ * What a frame needs to know about the beat beyond its chrome: which figures
+ * the body already draws, so an aside never repeats one, and the beat's own
+ * evidence, which is the only place an aside may come from.
+ */
+export interface FrameInput {
+    eyebrow: string | undefined;
+    headline: string;
+    /** Figure ids the body draws. */
+    drawn?: readonly (string | undefined)[];
+    /** The beat's `evidence`. An aside is drawn only from a figure cited here. */
+    evidence?: readonly {
+        kind: string;
+        id: string;
+    }[];
+}
+export declare function frameOf(ctx: EmitContext, input: FrameInput): Frame;
+/** The rail column's width for a format. Exported for the viability check. */
+export declare function railWidth(format: Format): number;
+/** The chrome's height set in the rail, accent bar included. */
+export declare function railChromeHeight(format: Format, eyebrow: string | undefined, headline: string, face: Face): number;