@jokerized/decksmith 0.8.0 → 0.9.0

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,104 @@
+/**
+ * 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 equations leans to the serif packs, one that is mostly bars and tables
+ * to the grotesk and drafting ones. 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.
+ *
+ * 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 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;

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

@@ -0,0 +1,111 @@
+/**
+ * Type specs: the typographic half of a v2 style pack.
+ *
+ * A pack used to be a palette (`themes/`), and every deck set the same Inter at
+ * the same 42/64/40 scale, which is half of why the founder's verdict on 219
+ * decks was "always the same". A `TypeSpec` is the rest of a look: which face
+ * draws the headline and which draws the body, the eyebrow's size, case, weight
+ * and tracking, the headline's size, weight, tracking and leading, and how the
+ * title slide's big headline grows.
+ *
+ * EVERY NUMBER HERE IS GEOMETRY, which is why this is not CSS. `chromeHeight`
+ * charges the chrome from these numbers and `chromeCss` draws it from the same
+ * numbers, so the two cannot disagree. A spec is chosen by the font stack a theme
+ * declares (see `faceOf` in svg.ts), so every emitter that already threads a
+ * `Face` gets the right measurement without learning that packs exist.
+ *
+ * `CLASSIC_TYPE` is today's look, number for number. It is never looked up by
+ * stack: any stack no spec claims — `ink`, `mono`, `paper`, a user's own theme —
+ * measures as classic, which is what keeps v0.8.0's bytes.
+ */
+import type { MeasuredFace } from "./faces.js";
+/** A Latin face a deck can be measured in. `inter` is svg.ts's own table. */
+export type LatinFace = "inter" | MeasuredFace;
+export interface TypeSpec {
+    /** Stable id, for messages and the gallery. */
+    key: string;
+    /** Face of everything but the chrome. Measured with this face's table. */
+    body: LatinFace;
+    /** Face of the eyebrow, the headline and the title slide's headline. */
+    display: LatinFace;
+    /**
+     * The body stack. It IDENTIFIES the spec (`faceOf` matches its tail), so no two
+     * specs may share one; the display family rides in it after Inter, where it
+     * never draws, purely so a stack names its pair. See `stackFor`.
+     */
+    stack: string;
+    /** The chrome's stack: display face, then Inter for any glyph it lacks. */
+    displayStack: string;
+    /** `color` is a palette role, so one spec suits a light and a dark pack. */
+    eyebrow: {
+        size: number;
+        weight: 400 | 500 | 600 | 700;
+        tracking: number;
+        upper: boolean;
+        lh: number;
+        gap: number;
+        color: "muted" | "accent";
+    };
+    headline: {
+        size: number;
+        weight: 400 | 500 | 600 | 700;
+        tracking: number;
+        lh: number;
+    };
+    /** `fitText`'s bounds for the title slide, and how the big headline is set. */
+    title: {
+        lo: number;
+        hi: number;
+        weight: 400 | 500 | 600 | 700;
+        tracking: number;
+    };
+}
+/** The CSS family a face is declared under — what `vendorFace` writes. */
+export declare function familyOf(face: LatinFace): string;
+/**
+ * `"<body>", "Inter", "<display>", system-ui, sans-serif`, with duplicates gone.
+ *
+ * Inter second, always: every Latin deck vendors it, and `measure-faces.mjs`
+ * measured each face with Inter as its fallback, so a glyph the face lacks is
+ * drawn by the face the table assumed. The display family after Inter never
+ * draws a glyph; it is there so (body, display) pairs give distinct stacks.
+ */
+export declare function stackFor(body: LatinFace, display: LatinFace): string;
+/** Today's chrome, exactly. `title.ts` exported these numbers before specs existed. */
+export declare const CLASSIC_TYPE: TypeSpec;
+/**
+ * The v2 type specs. Five pairings, each a different voice rather than a
+ * different size of the same one:
+ *
+ * - `grotesk-inter`: a geometric grotesk headline, tight and large, over Inter.
+ * - `plex`: IBM Plex Sans throughout, a little compact — engineering drawings.
+ * - `serif-inter`: a text serif headline at display size over Inter.
+ * - `serif`: Source Serif 4 throughout, the eyebrow in sentence case — a journal.
+ * - `grotesk-plex`: Space Grotesk headline over a Plex body.
+ * - `plex-serif`: a Plex headline over a serif body, the inverse of `serif-inter`.
+ *
+ * HEIGHT. A one-line eyebrow plus a one-line headline costs at most classic's
+ * 146px in every spec, so a pack's bigger type comes out of its leading and
+ * gaps rather than out of the body's room. Measured why: `serif` at 44/70 cost
+ * a real deck a six-bar chart (`costsNothing` in themes/pick.ts now refuses
+ * such a pack, but a pack that rarely needs refusing is the better pack).
+ *
+ * FLOORS. Every eyebrow is at least 40px (invariant 5). Title tracking is never
+ * positive: `fitText` measures untracked, so only a tightening is free.
+ */
+export declare const TYPES: Readonly<Record<string, TypeSpec>>;
+/**
+ * The spec a theme's stack names, or undefined for classic.
+ *
+ * Exact, after the one prefix `deckLook` adds: a CJK deck puts its bundled Noto
+ * family first and keeps the pack's stack behind it. A stack that merely
+ * CONTAINS a spec's families — a user's own theme — is not that spec.
+ */
+export declare function typeForStack(fontStack: string): TypeSpec | undefined;
+/** One line box, the way `title.ts` has always rounded it. */
+export declare function lineBox(size: number, lh: number): number;
+/**
+ * A tracking value as the CSS this project has always written: `.14em`,
+ * `-.015em`, `0`. Leading zero dropped, so the classic chrome is byte-identical.
+ */
+export declare function em(tracking: number): string;