@jokerized/decksmith 0.8.0 → 0.9.1

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

@@ -1,7 +1,2 @@
-/**
- * Labelled panels side by side — the archetype for the things a paper does not
- * put in a figure: a contradiction between two tables, a caveat, a limit on what
- * was actually tested. Panels appear one at a time so each can be spoken to.
- */
 import type { Emitter } from "../kit.js";
 export declare const callout: Emitter<"callout">;

package/dist/types/emit/archetypes/claim-figure.d.ts

@@ -1,2 +1,17 @@
+import { type Fit } from "../fit.js";
 import type { Emitter } from "../kit.js";
+type Mode = "tall" | "wide" | "beside";
+/** One way to draw the beat, predicted. */
+export interface Arrangement {
+    mode: Mode;
+    claimSize: number;
+    plate: {
+        w: number;
+        h: number;
+    };
+    fit: Fit;
+}
+/** The arrangement to draw: the classic mode unless another fills clearly more. */
+export declare function choose(options: readonly Arrangement[]): Arrangement;
 export declare const claimFigure: Emitter<"claim-figure">;
+export {};

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/index.d.ts

@@ -1,10 +1,3 @@
-/**
- * The explanatory vocabulary, indexed by archetype.
- *
- * The mapped type is the point: adding an archetype to `Beat` without an emitter
- * beside it fails to compile, which is the only guarantee that keeps the union in
- * `types.ts` honest.
- */
 import type { Archetype, Beat } from "../../types.js";
 import type { EmitContext, Emitter, Scene } from "../kit.js";
 export declare const emitters: {

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,9 +11,12 @@
  * timeline, wraps whatever the emitter returns, and closes the document.
  */
 import type { z } from "zod";
+import { type BespokeMap } from "../bespoke/scene.js";
+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 Scene } from "./kit.js";
+import type { Beat, Design, Format, NarrationCanvas, Source, Storyboard, segmentSchema } from "../types.js";
+import type { FitManifest } from "./fit.js";
+import { type EmitContext, type Scene } from "./kit.js";
 /** A built deck. `page` is present only for navigable formats. */
 export interface Deck {
     composition: string;
@@ -27,6 +30,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 +71,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;
@@ -107,6 +130,12 @@ export interface DeckOptions {
      * (`vendorInter` in src/build/files.ts), for the same reason.
      */
     fontCss?: string;
+    /**
+     * `--design v2 --bespoke`: beats drawn by a generated scene, keyed by beat id
+     * (src/bespoke/). Absent on every other build, which is what keeps them
+     * byte-identical. A deck that carries one also carries `BESPOKE_CSP`.
+     */
+    bespoke?: BespokeMap;
 }
 /**
  * Both artifacts from one layout pass.
@@ -118,7 +147,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.
  *
@@ -219,7 +269,35 @@ export declare function speechPlan(open: number, holds: readonly number[], segme
     starts: number[];
     end: number;
 };
+/**
+ * Where a bespoke scene's stops go and when its sentences are spoken, worked out
+ * with the same functions `layout` stages with — so the cue times the model is
+ * given are the times the deck will have. See `bespokeHolds` for why the voice
+ * does not move.
+ *
+ * `ctx` must not carry the bespoke map: this stages the ARCHETYPE first.
+ */
+export declare function bespokeStaging(beat: Beat, ctx: EmitContext, segments: readonly Segment[], speed: number): {
+    holds: number[];
+    open: number;
+};
 export declare function emitComposition(storyboard: Storyboard, source: Source, format: Format, opts?: DeckOptions): string;
+/**
+ * The policy a composition carrying a generated scene runs under.
+ *
+ * The static walk in src/bespoke/contract.ts refuses every NAME that reaches the
+ * network, eval, storage or navigation; this refuses the BEHAVIOUR, so a scene
+ * that spelled its way past the walk still gets nothing. No `connect-src`, no
+ * frames, no plugins, and no `unsafe-eval` — `Function("…")` assembled from
+ * fragments throws here. `'unsafe-inline'` stays because every scene's timeline
+ * is an inline script, as it is in every deck; what it buys an attacker is
+ * nothing a scene could not already write. Local files only (`'self'`), which is
+ * every vendored script, stylesheet, font and figure a deck ships.
+ *
+ * Only on a deck with a bespoke scene: a `<meta>` in every head would move the
+ * bytes of every deck ever built.
+ */
+export declare const BESPOKE_CSP: string;
 /** Shipped beside the deck so a built artifact needs no network to navigate. */
 export declare const PLAYER_FILE = "hyperframes-player.global.js";
 /**
@@ -228,4 +306,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,10 @@
  * 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 { BespokeMap } from "../bespoke/scene.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 +161,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 +234,32 @@ 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;
+    /**
+     * `--design v2 --bespoke` only: the beats drawn by a generated scene instead
+     * of their archetype, keyed by beat id (src/bespoke/scene.ts). `emitScene`
+     * reads it, so every caller that stages a beat — `planCut`, `layout`, the
+     * timing manifest — sees the same scene. ABSENT ON EVERY OTHER BUILD, and
+     * absent means the archetype, byte for byte.
+     */
+    bespoke?: BespokeMap;
 }
 /**
  * A value in a GSAP vars payload that is JavaScript rather than data.
@@ -317,6 +375,14 @@ export interface Scene {
      * seeking that deck navigation performs.
      */
     tl: Tween[];
+    /**
+     * A bespoke scene's generated script, and nothing else's. Run inside this
+     * scene's timeline closure as `function (tl, root) { "use strict"; … }`, after
+     * `tl` exists and before the shell's own tweens are appended to it. Checked
+     * by src/bespoke/contract.ts before it can get here; an archetype never sets
+     * it, so every archetype scene is the bytes it was.
+     */
+    script?: string;
     /** Statements run as the document parses, before anything else, e.g.
      * `katex.render(...)`. Anything that CHANGES layout belongs here, so that a
      * `measure` below reads the finished document. */
@@ -389,6 +455,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 +585,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;
+}[];