@jokerized/decksmith 0.8.0 → 0.9.1

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;

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

@@ -0,0 +1,244 @@
+/**
+ * The v2 motion grammar: how a scene ARRIVES, how it HANDS OFF to the next one,
+ * and what MOVES while the narrator is talking about it.
+ *
+ * v0.8.0 had one of each, measured over 124 HypePaper scenes: 114 opened with
+ * the same eyebrow-then-headline fade-up, all 115 seams were one 0.4s
+ * `power2.in` dissolve, two eases carried 85% of 1,591 tweens, and once a slide
+ * had built, nothing on it moved while the voice explained it. That is the
+ * founder's "the animation is always the same", and this module is the answer
+ * for `design: "v2"` decks only. `classic` never reaches it, so every v0.8.0
+ * byte and golden is unchanged.
+ *
+ * FOUR RULES EVERYTHING HERE OBEYS, each of them an AGENTS.md invariant:
+ *
+ * 1. Pure and seeded. Every choice is a function of the storyboard (`fnv1a` of
+ *    the source id and the beat id), never of a clock or `Math.random`, so two
+ *    builds of one storyboard are byte-identical (invariant 4).
+ * 2. `fromTo` only, no callbacks. Every tween is a `Tween`, which cannot be
+ *    written without its `from` (invariant 2), and nothing here hangs state off
+ *    `onUpdate` (invariant 11). Emphasis and seam tweens carry
+ *    `immediateRender: false` so they never paint at build time over an
+ *    element's own entrance.
+ * 3. Holds, `open` and scene lengths never move. A restyled entrance keeps every
+ *    tween's position and duration, so `openSeconds`, `beatSeconds` and the
+ *    timing manifest (`holdsFor` in src/render/timing.ts re-emits scenes WITHOUT
+ *    this module) all still agree. Emphasis lives strictly inside a hold window
+ *    and is back at rest before the window closes, so every frame a gate
+ *    captures at a hold is the frame v0.8.0 would have captured there.
+ * 4. Up, never down. Emphasis grows a part (`LIFT`) and never shrinks one: the
+ *    type floor reads declared sizes, so a part scaled below 1 at a hold would
+ *    pass at a size it is not drawn at.
+ *
+ * INTERFACE, for the other v2 tracks (player, fit, style, layout):
+ *
+ * - `planMotion(seed, beats)` → which entrance verb each scene uses, which seam
+ *   joins each pair, and the order emphasis kinds are tried in. A style pack
+ *   that wants to bias the grammar should filter `ENTRANCES`/`SEAMS` before
+ *   calling it rather than post-edit its answer, so the no-repeat rules still
+ *   hold.
+ * - `restyleEntrance(scene, sid, verb)` rewrites an emitted scene's own
+ *   entrance tweens. It only rewrites tweens it recognises (`isEntrance`), so an
+ *   archetype added later is left alone rather than broken.
+ * - `seamOut`/`seamIn` are the handoff tweens for the outgoing and incoming
+ *   scene roots; `composition.ts` appends them where it used to append the one
+ *   dissolve.
+ * - `emphasize(...)` adds the during-narration motion and returns the
+ *   `HoldWindow`s the deck player needs (`deck.html`'s
+ *   `application/decksmith-motion+json` island, read by src/deck/motion.ts).
+ */
+import type { Archetype, BeatRole } from "../types.js";
+import { type Scene, type Tween } from "./kit.js";
+/**
+ * How a scene's parts arrive. Six, so the no-repeat rule always has at least
+ * four to choose from after excluding the previous scene's verb and a capped
+ * `rise`.
+ *
+ * | verb  | what moves                                   | ease          |
+ * |-------|----------------------------------------------|---------------|
+ * | rise  | fade up from below (v0.8.0's, kept, capped)  | power3.out    |
+ * | slide | in from the reading side                     | expo.out      |
+ * | snap  | scale up from 0.9 with a small overshoot     | back.out(1.7) |
+ * | focus | out of a blur (HTML) / short rise (SVG)      | circ.out      |
+ * | wipe  | clip-path opens left to right (HTML)         | power4.inOut  |
+ * | mask  | clip-path opens bottom-up while rising (HTML)| power4.out    |
+ *
+ * `focus`, `wipe` and `mask` touch `filter`/`clip-path`, which are only applied
+ * to HTML elements this module can SEE are HTML (an id whose tag it read in the
+ * scene's markup). An SVG part or a class selector gets the verb's transform
+ * fallback instead, because clip-path on an SVG child clips against a reference
+ * box nobody measured.
+ */
+export declare const ENTRANCES: readonly ["rise", "slide", "snap", "focus", "wipe", "mask"];
+export type Entrance = (typeof ENTRANCES)[number];
+/**
+ * How one scene hands off to the next. `dive` is the existing camera move and is
+ * never chosen here — a beat that is `inside` the previous one keeps it.
+ *
+ * | seam     | outgoing root                    | incoming root          |
+ * |----------|----------------------------------|------------------------|
+ * | dissolve | opacity → 0, power2.in (v0.8.0)  | —                      |
+ * | push     | xPercent 0 → −4, opacity → 0     | xPercent 4 → 0         |
+ * | lift     | yPercent 0 → −4, opacity → 0     | yPercent 4 → 0         |
+ * | wipe     | clip-path closes left to right   | —                      |
+ * | zoom     | scale 1 → 1.04, opacity → 0      | scale 0.96 → 1         |
+ *
+ * 4% is under the scene's own padding at every format (110px of 1920 is 5.7%,
+ * 84px of 1080 is 7.8%), so a mid-seam frame never puts content off the canvas
+ * for the layout gate's grid samples to find.
+ */
+export declare const SEAMS: readonly ["dissolve", "push", "lift", "wipe", "zoom"];
+export type Seam = (typeof SEAMS)[number] | "dive";
+/** What moves while the narrator talks about a part: grow, glow, underline. */
+export declare const EMPHASES: readonly ["pulse", "glow", "underline"];
+export type Emphasis = (typeof EMPHASES)[number];
+/** Every ease this module writes. A test pins that nothing else appears. */
+export declare const MOTION_EASES: readonly ["power3.out", "expo.out", "back.out(1.7)", "circ.out", "power4.inOut", "power4.out", "power2.in", "power2.inOut", "sine.out", "sine.inOut"];
+/**
+ * FNV-1a, 32-bit. The seeded choice every v2 decision is made with: stable
+ * across platforms and Node versions, which a `Math.random` with a seed is not.
+ */
+export declare function fnv1a(s: string): number;
+/** What `planMotion` needs to know about a beat. */
+export interface MotionBeat {
+    id: string;
+    archetype: Archetype;
+    role?: BeatRole | undefined;
+    inside?: {
+        beat: string;
+    } | undefined;
+}
+export interface MotionPlan {
+    /** One per beat, in order. */
+    entrances: Entrance[];
+    /** One per adjacent pair: `seams[i]` joins beat `i` to beat `i + 1`. */
+    seams: Seam[];
+    /** Per beat, the order emphasis kinds are tried in (the first that fits wins). */
+    emphases: Emphasis[][];
+}
+/**
+ * At most this share of a deck's scenes open with `rise`, the one verb that
+ * reads as v0.8.0's stock fade-up. The plan's target is "modal entrance ≤ 40%".
+ */
+export declare const RISE_SHARE = 0.25;
+/**
+ * The deck's motion, decided once for the whole storyboard.
+ *
+ * ENTRANCES: each beat hashes into the verbs still allowed to it — never the
+ * previous beat's, and `rise` only while under `RISE_SHARE`. Hash-then-filter
+ * rather than a rotation so two decks with the same archetype sequence still
+ * move differently, which is the cross-deck sameness the critic flagged.
+ *
+ * SEAMS are chosen by the RELATION between the two beats first, then varied:
+ * same family (two quantity beats) → `push`, a lateral continuation; a role
+ * boundary (`background` → `limitations`) → `zoom`, a chapter break; into or
+ * out of a title → `lift`; any other family change → `wipe`; into the closing
+ * beat → `dissolve`. A seam that would repeat the previous one is replaced by a
+ * hashed pick from the rest. Then, for a deck of 10+ beats with fewer than three
+ * kinds, the earliest replaceable seams are rotated through the missing kinds.
+ * `inside` is the camera's and stays `dive`.
+ */
+export declare function planMotion(seed: string, beats: readonly MotionBeat[]): MotionPlan;
+/**
+ * Rotate missing seam kinds into the earliest positions where the swap keeps
+ * both neighbours different and does not remove the last use of a kind.
+ * In place; deterministic because it walks in index order.
+ */
+export declare function ensureSeamKinds(seams: Seam[], want: number): void;
+/**
+ * A tween this module may restyle: an opacity 0 → 1 reveal whose `from` only
+ * moves opacity and position/scale, rendered immediately (the element's own
+ * first appearance). Dims, restores, draw-ons, pulses and anything with
+ * `immediateRender: false` are someone else's and stay exactly as emitted.
+ */
+export declare function isEntrance(t: Tween): boolean;
+/** The tag of the element an `#id` selector names in this markup, if it is one. */
+export declare function tagOf(html: string, target: string): string | undefined;
+/**
+ * One scene's entrances, re-voiced in `verb`. Positions and durations are
+ * untouched (rule 3 at the top), so this cannot move a hold or the voice.
+ */
+export declare function restyleEntrance(scene: Scene, sid: string, verb: Entrance): Scene;
+/**
+ * When the incoming chrome may start, in unpaced seconds: once the outgoing
+ * scene's handoff (`HANDOFF_SECONDS`, 0.4) has taken it below half opacity,
+ * which a `power2.in` fade does at 0.32.
+ *
+ * WHY. v0.8.0's eyebrow starts at 0.15 on GSAP's default `power1.out`, which is
+ * still under 0.5 opacity by the time the old scene fades past half. v2's eases
+ * are faster off the mark — `expo.out` is at 0.75 a fifth of the way in — so an
+ * eyebrow starting at 0.15 is legible over the outgoing headline, the collision
+ * `HANDOFF_SECONDS` warns about. So the chrome's START moves to here and its END
+ * stays where it was: `openSeconds` reads only the ends, so the voice starts at
+ * the same instant. `test/motion.test.ts` checks every verb against every seam.
+ */
+export declare const SEAM_CLEAR = 0.3;
+/**
+ * The OUTGOING half of a seam: tweens on `#sid` starting where its slide ends
+ * (`at`) and running `over` seconds into the next scene's window, exactly where
+ * the v0.8.0 dissolve ran. `dissolve` is byte-for-byte `handoffStatement`'s
+ * tween, so a v2 deck whose plan says dissolve hands off as v0.8.0 did.
+ */
+export declare function seamOut(kind: Exclude<Seam, "dive">, sid: string, at: number, over: number): Tween[];
+/**
+ * The INCOMING half, on the next scene's own timeline from its 0. Settles by
+ * `firstHold - 0.05`, so the frame at the first stop is the frame v0.8.0 drew
+ * there; a scene that holds sooner than `over` gets no incoming move at all.
+ */
+export declare function seamIn(kind: Seam, sid: string, over: number, firstHold: number): Tween[];
+/** A narrated stop's quiet stretch, scene-relative. See `emphasize`. */
+export interface HoldWindow {
+    /** Stop index within the scene (the narration segment's `stop`). */
+    stop: number;
+    /** The hold itself: where the deck lands for this stop. */
+    at: number;
+    /** Where this stop's sentence starts on the scene's clock (may be < `at`). */
+    from: number;
+    /** The first moment after `at` that belongs to the next stop's reveal, or the scene's end. */
+    to: number;
+}
+/** What `emphasize` needs to know about a narration segment. */
+export interface SpokenSegment {
+    stop: number;
+    seconds: number;
+    cues: readonly {
+        start: number;
+    }[];
+}
+export declare const EMPH_TOTAL: number;
+/** `#rrggbb` → `rgba(r, g, b, a)`, or undefined for anything else. */
+export declare function rgba(hex: string, a: number): string | undefined;
+/**
+ * Motion DURING the narration hold, timed to what is being said.
+ *
+ * There is no word timing, so the clock is the narration's own cue boundaries:
+ * each segment speaks about its stop's subject (`subjectOf`), and the subject is
+ * emphasised at the first cue boundary — the sentence's start counts — at which
+ * it is on screen and settled, inside a stretch where nothing else is arriving.
+ *
+ * THE STRETCHES. After stop `k`'s hold the scene is quiet until the first tween
+ * that starts later (the next stop's reveal); after the LAST hold it is quiet to
+ * the scene's end, which is where most narration lands because the reveals play
+ * under the voice (`speechPlan`). An emphasis for stop `k` may use any stretch
+ * from `k` on — in the video every part is still there — and must be back at
+ * rest before the stretch closes, so every hold frame is untouched (rule 3).
+ *
+ * `windows` is the deck player's half. A presented deck holds still at each stop
+ * while its audio plays; `src/deck/motion.ts` seeks the scene through the
+ * stop's own stretch on the audio's clock, `from + audio.currentTime`, so the
+ * same emphasis lands on the same word there. Only a stop's OWN stretch is
+ * offered, because seeking into a later one would show the next reveal early.
+ */
+export declare function emphasize(scene: Scene, sid: string, opts: {
+    segments: readonly SpokenSegment[];
+    /** `speechPlan(open, holds, segments).starts` — where each segment starts. */
+    starts: readonly number[];
+    /** The scene's slide length (before any handoff or camera tail). */
+    end: number;
+    /** Per-scene try order, from `planMotion`. */
+    kinds: readonly Emphasis[];
+    accent: string;
+}): {
+    scene: Scene;
+    windows: HoldWindow[];
+};

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

@@ -1,19 +1,5 @@
-/**
- * Geometry, text metrics and SVG strings. Nothing above that.
- *
- * Six diagrammatic archetypes draw vector graphics that the source document
- * never contained. Left to themselves each would re-derive the same four things
- * — how wide a label renders, where N things go across a canvas, how to draw an
- * arrowhead, how to escape a caption — and they would each get them slightly
- * wrong in a different way. `line-chart` shipped 3.6px from clipping because it
- * guessed its own em-factor; that guess now lives here, once.
- *
- * This module knows about characters, boxes and paths. It does not know what a
- * pipeline stage or a receptive field is — that knowledge belongs to the emitter
- * that composes these primitives, and putting it here is how a primitive layer
- * turns into six hand-rolled one-offs wearing a shared import.
- */
 import { type Tween, type Vars } from "./kit.js";
+import { type LatinFace, type TypeSpec } from "./type.js";
 export interface Pt {
     x: number;
     y: number;
@@ -145,7 +131,49 @@ export declare function id(sid: string, part: string, i?: number): string;
  * why the auto-detection below still runs underneath: the parameter can only
  * widen what a run is charged, never narrow it.
  */
-export type Face = "latin" | "cjk" | "hangul";
+export type Script = "latin" | "cjk" | "hangul";
+/**
+ * A v2 style pack's face: the script as above, the Latin face that draws the
+ * run, and the pack's type spec (`./type.ts`).
+ *
+ * An OBJECT rather than a fourth string, and only ever built by `faceOf` and
+ * `displayFace`, because every emitter already threads a `Face` through to
+ * `textWidth` and `chrome*` without looking inside it. That is what lets a pack
+ * change both the width table and the chrome's scale with no emitter learning
+ * packs exist: the measurement rides on the value they already pass.
+ *
+ * `glyphs` only matters when `script` is `"latin"`. A CJK deck draws its Latin
+ * in the bundled Noto face whatever the pack says, and is measured as it always
+ * was.
+ */
+export interface PackFace {
+    readonly script: Script;
+    readonly glyphs: LatinFace;
+    readonly type: TypeSpec;
+    /**
+     * A CJK deck whose pack sets this role in a serif: the bundle's Noto Serif
+     * draws the run, not Noto Sans. Han and kana are the same 1.0em in both;
+     * Hangul is 0.966em against 0.920, and the Latin inside a run is about 7%
+     * wider (measured 2026-10-08, Chrome 145, KR/JP/SC at 400 and 700). See
+     * `CJK_SERIF_HANGUL` and `CJK_SERIF_LATIN`.
+     */
+    readonly cjkSerif?: boolean;
+}
+/**
+ * A bare `Script` is the classic face, exactly as before packs: Inter's table and
+ * `CLASSIC_TYPE`. Every theme that is not a v2 pack still measures as one, so
+ * its bytes do not move.
+ */
+export type Face = Script | PackFace;
+/** The script a face sets in. */
+export declare function scriptOf(face: Face): Script;
+/** The chrome's type spec. A bare script is classic. */
+export declare function typeOf(face: Face): TypeSpec;
+/**
+ * The same face, measured as the pack's DISPLAY face — what the eyebrow, the
+ * headline and the title slide's headline are set in. Identity for classic.
+ */
+export declare function displayFace(face: Face): Face;
 /**
  * The face a theme's stack will use, from the family `familyFor` put in front.
  *
@@ -161,6 +189,16 @@ export declare function textWidth(text: string, fontSize: number, weight?: numbe
  * one unbroken "word".
  */
 export declare function wrap(text: string, fontSize: number, maxWidth: number, weight?: number, tracking?: number, face?: Face): string[];
+/**
+ * Whether `wrap` would have to cut a word letter by letter to set `text` at
+ * this size and width — "Rectified-flo" / "w". `wrap` does that as a last
+ * resort, which is right for a box that cannot be any wider; a layout that is
+ * CHOOSING a size (v2's growth, a layout variant) asks this first and takes a
+ * size at which no word is cut. A run with Han or kana in it breaks between
+ * characters by the script's own rules, so it never counts; Hangul words are
+ * space-separated and do.
+ */
+export declare function cutsWord(text: string, fontSize: number, maxWidth: number, weight?: number, face?: Face): boolean;
 /** The SVG root. Width and height match the viewBox so px and user units agree. */
 export declare function svg(elementId: string, w: number, h: number, body: string): string;
 export declare function rect(b: Box, a?: Attrs): string;

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

@@ -1,7 +1,7 @@
 import type { Format, Storyboard } from "../types.js";
 import { type Scene } from "./kit.js";
 import { type DeckTheme } from "./themes/index.js";
-export { type DeckTheme, ink, mono, paper, resolveTheme, THEME_NAMES, THEMES, } from "./themes/index.js";
+export { type DeckTheme, ink, mono, PACKS, paper, resolveTheme, THEME_NAMES, THEMES, } from "./themes/index.js";
 /**
  * The theme a storyboard's scenes are staged with, and the font family it ships.
  *

package/dist/types/emit/themes/index.d.ts

@@ -13,6 +13,7 @@
 import type { Theme } from "../kit.js";
 import { ink } from "./ink.js";
 import { mono } from "./mono.js";
+import { PACKS } from "./packs.js";
 import { paper } from "./paper.js";
 /**
  * `Theme` plus what only the shared stylesheet reads.
@@ -25,7 +26,24 @@ import { paper } from "./paper.js";
 export interface DeckTheme extends Theme {
     /** `body`'s font-weight. Omitted means 400, which is what `ink` and `paper` want. */
     bodyWeight?: number;
+    /**
+     * A v2 style pack's ground, so a picker can keep light and dark both in use.
+     * Absent on the classic themes, which are never picked — only named.
+     */
+    ground?: "dark" | "light";
+    /**
+     * A v2 pack's finish: CSS appended after the base stylesheet. It may change
+     * only what no measurement reads — colour, radius, shadow, decoration, the
+     * body's `background-image`, absolutely positioned pseudo-elements. See
+     * `./packs.ts`; the rule is enforced in `test/style-packs.test.ts`.
+     */
+    skin?: string;
 }
+/**
+ * The classic three, then the v2 packs. Every one is reachable by `--theme`,
+ * which is also how a storyboard or a caller forces a pack; `--design v2` picks
+ * among `PACKS` when nobody named one (`./pick.ts`).
+ */
 export declare const THEMES: Readonly<Record<string, DeckTheme>>;
 /** Sorted, so an error message and a `--help` listing agree without coordinating. */
 export declare const THEME_NAMES: readonly string[];
@@ -37,4 +55,4 @@ export declare const THEME_NAMES: readonly string[];
  * someone presents it.
  */
 export declare function resolveTheme(name: string): DeckTheme;
-export { ink, mono, paper };
+export { ink, mono, PACKS, paper };

package/dist/types/emit/themes/packs.d.ts

@@ -0,0 +1,15 @@
+import type { DeckTheme } from "./index.js";
+/** Magma, HypePaper's brand accent, on a violet-black ground. Grotesk display. */
+export declare const signal: DeckTheme;
+/** Navy drafting film, a cyan rule, a faint grid. IBM Plex throughout. */
+export declare const blueprint: DeckTheme;
+/** Espresso ground, amber accent, a serif headline over Inter. Matted figures. */
+export declare const atlas: DeckTheme;
+/** Cream stock, oxblood accent, Source Serif throughout. A journal page. */
+export declare const folio: DeckTheme;
+/** Cool white, ultramarine accent, a grotesk headline over Plex. Dotted ground. */
+export declare const chalk: DeckTheme;
+/** Sage ground, forest accent, a Plex headline over a serif body. Tabbed plates. */
+export declare const journal: DeckTheme;
+/** The packs `--design v2` chooses among, in a fixed order the picker hashes into. */
+export declare const PACKS: Readonly<Record<string, DeckTheme>>;

package/dist/types/emit/themes/pick.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Which v2 pack a deck wears, when nobody said.
+ *
+ * DETERMINISTIC: a pure function of the storyboard's beats and a seed, so the
+ * same deck is the same bytes on every build (invariant 4 is about render time,
+ * but a pick that moved between builds would be the same failure one step
+ * earlier). The seed is the source id unless the caller passes one — HypePaper
+ * should pass the PAPER id, so a paper's en and ko decks share a look.
+ *
+ * WEIGHTED BY CONTENT, so the hash is not the only voice. Each pack carries an
+ * affinity for the four archetype families (`ARCHETYPE_FAMILY`): a deck that is
+ * mostly structure leans to the drafting pack, one that is mostly bars and
+ * tables to the grotesk one. The lean is mild — every pack keeps a floor
+ * weight — because the founder's complaint is sameness across decks, and a
+ * strong content rule would put every paper of one field on one pack.
+ *
+ * DARK ONLY. The pick ranks the dark packs (`PICKED`); a light one is worn only
+ * when named. The founder, 2026-10-11: "I prefer dark theme".
+ *
+ * Rendezvous hashing: each pack draws `-ln(u) / weight` from its own hash of
+ * (seed, pack) and the smallest draw wins. That is a weighted choice whose
+ * probabilities are exactly the normalised weights, and the full ordering is a
+ * ready-made fallback list — the next pack is the next-smallest draw, so a
+ * caller that must refuse one (narration staged against another look) moves
+ * along it without re-rolling anything.
+ */
+import { type Format, type Source, type Storyboard } from "../../types.js";
+import { type DeckNarration } from "../composition.js";
+/** 32-bit FNV-1a. Stable across platforms and Node versions, unlike any Map order. */
+export declare function fnv1a(text: string): number;
+/** A pack's weight for this deck: 1, plus its affinity times the family mix. */
+export declare function packWeights(beats: Storyboard["beats"]): Record<string, number>;
+/** Every pickable pack, most-preferred first, for this deck and seed. */
+export declare function rankPacks(beats: Storyboard["beats"], seed: string): string[];
+/** The design generation a build emits. `classic` is v0.8.0, byte for byte. */
+export type Design = "classic" | "v2";
+export interface LookChoice {
+    /** `--theme` or a config file. Always wins: a named theme is a forced one. */
+    stated?: string | undefined;
+    storyboard: Pick<Storyboard, "theme" | "beats" | "sourceId">;
+    design: Design;
+    /** Overrides `storyboard.sourceId` as the hash seed. */
+    seed?: string | undefined;
+    /**
+     * Whether this build can wear a pack. `build` passes a check that the pack
+     * stages every beat with the stop count the narration was recorded at; a pack
+     * it refuses is skipped for the next in the ranking.
+     */
+    accepts?: (name: string) => boolean;
+}
+/**
+ * The theme name a build, a narration or a timing pass should stage with.
+ *
+ * Classic: what it always was, `stated ?? storyboard.theme`.
+ *
+ * v2: a stated theme still wins, and so does a storyboard that names anything
+ * but `ink` — that is the storyboard forcing a look. `ink` is the schema's
+ * DEFAULT, so it is indistinguishable from "nobody said" once parsed, and is
+ * read that way (as `--theme ink` is: the CLI treats a default value as
+ * unstated). The v0.8.0 look is `--design classic`, not a v2 deck in ink.
+ * Otherwise the first ranked pack `accepts` allows; if it allows none, the
+ * storyboard's own theme. Never throws.
+ *
+ * NOT "what any narration on disk was staged against", which this used to say:
+ * once `narrate` ran under v2 it staged under its own pick. `narrate` and
+ * `build` agree because both rank with the same seed and both refuse a pack
+ * that drops a beat (`pickTheme` below); give them the same `--pack-seed`.
+ */
+export declare function chooseLook(c: LookChoice): string;
+/**
+ * The theme every entry point builds with: the CLI's `build` and `narrate`,
+ * the library's `buildDeck` and the server pipeline all come here, so the same
+ * input is the same deck whichever one made it. (Before, only the CLI picked a
+ * pack; a v2 deck from the library or the server stayed in ink.)
+ *
+ * `narration` is the recording on disk, when there is one: a pack must stage
+ * every beat at the stop count it was recorded at. `narrate` itself has none
+ * yet and asks only the other half — that no beat is dropped — which is what
+ * keeps its pick and `build`'s the same.
+ */
+export declare function pickTheme(storyboard: Storyboard, source: Source, format: Format, opts: {
+    stated?: string | undefined;
+    design: Design;
+    seed?: string | undefined;
+    speed: number;
+    narration?: DeckNarration | undefined;
+}): string;
+/**
+ * The `accepts` a build hands `chooseLook`: a pack may cost this deck nothing.
+ *
+ * Two ways it could, both found on real decks:
+ *
+ * - A beat staged with a different stop count than the narration on disk was
+ *   recorded at. `planCut` throws for that (`assertNarrationStaging`).
+ * - A beat the storyboard's own theme draws but the pack refuses. Measured: an
+ *   en deck in `folio` lost a six-bar bar-compare ("need 660px of the 653px")
+ *   because the pack's chrome is a few px taller. That is a whole slide gone for
+ *   a look, which is never a trade worth making silently, so the pack is
+ *   skipped for the next one in the ranking instead.
+ *
+ * Pure: it only runs `planCut`, the same pass the build makes, once per pack it
+ * is asked about plus once for the baseline.
+ */
+export declare function costsNothing(storyboard: Storyboard, source: Source, format: Format, opts: {
+    speed: number;
+    narration?: DeckNarration | undefined;
+}): (name: string) => boolean;