@jokerized/decksmith 0.7.0 → 0.9.0

package/dist/types/build/files.d.ts

@@ -1,4 +1,5 @@
 import type { DeckNarration } from "../emit/composition.js";
+import { type LatinFace } from "../emit/type.js";
 import type { Source, Storyboard } from "../types.js";
 /** Progress, for a caller that has somewhere to put it. */
 type Step = (message: string) => void;
@@ -99,6 +100,17 @@ export declare function copyAudio(from: string, narration: DeckNarration, out: s
  * CJK — over-collecting costs a few bytes, under-collecting costs a tofu box.
  *
  * A Latin deck gets `vendorInter` instead: nothing to subset, nothing to fetch.
+ * On a v2 style pack it also gets the pack's own faces (`vendorFace`), named by
+ * the pack's type spec — `theme` is the name the build resolved, as `--theme`.
+ * A CJK deck needs none of them: the Noto bundle is first in every stack and
+ * covers Latin, so the pack's faces would ship and never draw.
  */
-export declare function refreshFont(storyboard: Storyboard, source: Source, out: string, step: Step): Promise<string | undefined>;
+export declare function refreshFont(storyboard: Storyboard, source: Source, out: string, step: Step, theme?: string): Promise<string | undefined>;
+/**
+ * A v2 pack's face, vendored exactly the way Inter is: the package's `wght`
+ * subsets copied whole, declared under the name the pack's stack uses, `block`
+ * not `swap`. These are the files `scripts/measure-faces.mjs` measured, so the
+ * width table in `src/emit/faces.ts` describes what the deck draws.
+ */
+export declare function vendorFace(face: Exclude<LatinFace, "inter">, dir: string): Promise<string>;
 export {};

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

@@ -0,0 +1,64 @@
+/**
+ * The deck player's half of v2 motion: what moves between stops and during them.
+ *
+ * Two things a presented deck never showed before, both only for a deck whose
+ * page carries the `application/decksmith-motion+json` island — a `design: v2`
+ * build. A classic deck has no island and every function here answers "nothing
+ * to do", so it presents exactly as it did.
+ *
+ * 1. THE SEAM. A step to the next slide plays only when the span is short
+ *    (`MAX_SPAN` in runtime.ts). From a narrated slide's last stop it never is —
+ *    the voice made the scene long — so every slide change CUT to the next
+ *    slide's first stop, already built: the seam and the whole entrance were
+ *    never seen in deck.html, only in the mp4. `seamLead` says where to cut TO
+ *    instead: the next slide's own start, so the glide that follows plays the
+ *    handoff and the entrance, one to two seconds, as the video does.
+ *
+ * 2. THE HOLD. At a stop the deck seeks once and holds still while the audio
+ *    plays, so emphasis written into the scene's quiet stretch (`emphasize` in
+ *    src/emit/motion.ts) would never run. `holdTime` maps the audio clock onto
+ *    that stretch — `from + audio.currentTime`, clamped to it — so a part pulses
+ *    on the word it pulses on in the video. Still SEEK, NOT PLAY (invariant 1):
+ *    the runtime seeks to a time derived from the audio element's clock, the way
+ *    captions already follow it, and nothing runs a timeline on its own.
+ *
+ * Reduced motion turns both off at the call site in runtime.ts: the step cuts and
+ * the hold holds, which is what the deck did for everyone before.
+ */
+import type { SlideSpec, Stop } from "./runtime.js";
+export declare const MOTION_ISLAND = "script[type=\"application/decksmith-motion+json\"]";
+/** One narrated stop's quiet stretch, absolute composition seconds. */
+export interface HoldSpan {
+    stop: number;
+    /** The stop's own time — where the deck lands. */
+    at: number;
+    /** Where the stop's sentence starts on the composition clock. */
+    from: number;
+    /** The last time this stop may show before the next stop's reveal begins. */
+    to: number;
+}
+export interface Motion {
+    /** Glide through seams on slide changes. */
+    seams: boolean;
+    /** Keyed by scene id. */
+    holds: Record<string, HoldSpan[]>;
+}
+/**
+ * The island, or null. Defensive in the way `parseNarration` is: this ships
+ * inside decks that outlive the code that wrote them, so a malformed entry is
+ * dropped rather than allowed to break the player.
+ */
+export declare function parseMotion(json: string | null | undefined): Motion | null;
+/** The stretch belonging to this stop, matched by time (fragments are 3dp). */
+export declare function spanFor(motion: Motion, stop: Stop): HoldSpan | undefined;
+/** Composition time to show `seconds` into this stop's audio. */
+export declare function holdTime(span: HoldSpan, seconds: number): number;
+/** Longest entrance a seam glide will play — a slide's first stop is rarely past 2.5s. */
+export declare const MAX_SEAM_SPAN = 4;
+/**
+ * Where a forward step onto the next slide should start its glide, or null for
+ * "decide as before". Only a step from the previous slide onto this slide's
+ * FIRST stop, only when the ordinary policy would have cut (the span is longer
+ * than `maxSpan`), and only when the entrance itself is short enough to watch.
+ */
+export declare function seamLead(from: number, prev: Stop | undefined, next: Stop, slides: readonly SlideSpec[], maxSpan: number): number | null;

package/dist/types/deck/playback.d.ts

@@ -0,0 +1,206 @@
+/** The meta tag a v2 deck page carries. Read by the runtime, written by the emitter and `repack`. */
+export declare const PLAYER_META = "decksmith-player";
+export declare const PLAYER_MARKER = "<meta name=\"decksmith-player\" content=\"2\" />";
+/**
+ * `page` with the v2 marker as the first thing in its head. Idempotent: a page
+ * that already names a player version is returned with that tag replaced, so
+ * marking twice — or repacking a repacked deck — changes nothing.
+ */
+export declare function markV2(page: string): string;
+/**
+ * Narration speeds a viewer can choose. The list YouTube and video.js offer,
+ * minus 0.5 (edge-tts at half speed is a different voice, not a slower one).
+ * Gecko mutes outside 0.25–4, so every entry plays everywhere.
+ */
+export declare const RATES: readonly [0.75, 1, 1.25, 1.5, 1.75, 2];
+export type CaptionSize = "s" | "m" | "l" | "xl";
+export declare const CAPTION_SIZES: readonly CaptionSize[];
+/** Multipliers on the M caption font. 80–160%, inside FCC 79.103's 50–200%. */
+export declare const CAPTION_SCALE: Readonly<Record<CaptionSize, number>>;
+/**
+ * What a viewer chose. `speed` is the narration's playbackRate and divides
+ * every glide and silent dwell; `cc` shows the caption strip; `ccsize` scales it.
+ * Mute is deliberately not here: it is a moment's choice, not a preference.
+ */
+export interface PlayerPrefs {
+    speed: number;
+    cc: boolean;
+    ccsize: CaptionSize;
+}
+export declare const DEFAULT_PREFS: PlayerPrefs;
+/** The localStorage key. Versioned so a later shape never misreads this one. */
+export declare const PREFS_KEY = "decksmith.prefs.v1";
+/**
+ * The message a v2 deck posts to its parent whenever the VIEWER changes a
+ * preference, and accepts from its parent to apply one. Not on the `CHANNEL`
+ * protocol in ./protocol.ts on purpose: that one waits for a `hello` handshake
+ * before it says anything, and HypePaper embeds a plain iframe that never sends
+ * one. Posted to "*" because it carries nothing but three playback settings —
+ * never notes, never position. A host must still check `event.origin`.
+ *
+ *   { type: "decksmith:prefs", speed: 1.25, cc: true, ccsize: "m" }
+ *
+ * Incoming, every field is optional; whatever is valid is applied and saved.
+ */
+export declare const PREFS_MESSAGE = "decksmith:prefs";
+export interface PrefsMessage extends PlayerPrefs {
+    type: typeof PREFS_MESSAGE;
+}
+/** The nearest offered rate, or undefined for anything that is not a positive number. */
+export declare function snapRate(v: unknown): number | undefined;
+/**
+ * Whatever is valid in `raw`, and nothing else. Reads a stored blob, a host
+ * message and a parsed query string alike, so a deck handed garbage keeps its
+ * own defaults instead of throwing.
+ */
+export declare function cleanPrefs(raw: unknown): Partial<PlayerPrefs>;
+/** `?speed=1.25&cc=0&ccsize=l`, as a partial. Unknown and invalid params are ignored. */
+export declare function prefsFromQuery(search: string): Partial<PlayerPrefs>;
+/** A stored blob, read defensively: anything unparseable is "nothing stored". */
+export declare function prefsFromStored(text: string | null | undefined): Partial<PlayerPrefs>;
+/**
+ * Precedence, lowest first: default, stored, URL. A host message arriving later
+ * is applied on top of whatever this produced.
+ */
+export declare function resolvePrefs(stored: Partial<PlayerPrefs>, query: Partial<PlayerPrefs>): PlayerPrefs;
+/** One step up or down the rate list, clamped at both ends. */
+export declare function stepRate(current: number, dir: 1 | -1): number;
+/** "1×", "1.25×", "0.75×" — the speed button's face. */
+export declare function rateLabel(rate: number): string;
+/** Caption font as a fraction of the slide's short side, at size M. */
+export declare const CAPTION_RATIO = 0.03;
+/** Below this a caption is not read, whatever the slide size. */
+export declare const CAPTION_MIN_PX = 13;
+export declare const CAPTION_MAX_PX = 56;
+/**
+ * The floor per size. Every size has the 13px floor, but on a stage small
+ * enough for it to bind, L and XL used to land on it too, and the size control
+ * then changed nothing at all on the phone embed — the one place a viewer most
+ * needs it. Each larger size keeps a floor of its own instead, so a step up is
+ * always a step up. S cannot go under the floor M is on: below 13px a caption
+ * is not read.
+ */
+export declare const CAPTION_FLOOR_PX: Readonly<Record<CaptionSize, number>>;
+/**
+ * The strip, in caption fonts: two lines at line-height 1.25 (2.5) plus a
+ * quarter-font of air above and below. Two lines is the budget `splitCue` and
+ * `splitForScreen` cut every cue to.
+ */
+export declare const STRIP_FONTS = 3;
+export declare const CAPTION_LINE_HEIGHT = 1.25;
+/** The smallest control target (plan QW2), and the largest a big screen gets. */
+export declare const BTN_MIN = 40;
+export declare const BTN_MAX = 52;
+/** A bar is its buttons plus this much air. */
+export declare const BAR_AIR = 8;
+/**
+ * Where the control bar lives. The rule it exists for: A CONTROL NEVER COVERS
+ * TEXT — not a caption, and not the slide's own text either.
+ *
+ * - `letterbox`: under the slide and its strip, in space the viewport has spare
+ *   (a portrait phone, a tall embed). Costs nothing.
+ * - `pad`: over the slide's bottom PADDING — the band every composition leaves
+ *   empty of text (`.scene`'s `PAD_Y`, less a margin; see `safeBottomFor`).
+ *   Only when the bar fits inside it at a full 40px target, i.e. on a slide
+ *   about 720px tall or more. Costs nothing; it hides when idle.
+ * - `band`: a strip of its own under the slide, shared side by side with the
+ *   captions when they are on, so it costs at most the difference between the
+ *   bar and the caption strip. Everything smaller than the two cases above.
+ *
+ * v2 used to put the bar inside the slide's box on every screen. Measured on the
+ * preview decks (2026-10-08 review), it covered the foot headline in 12 of 12
+ * cases at 390x844 and 11 of 12 at 800x450: on a small slide a 48px bar is a
+ * fifth of the height, and no layout can keep a fifth of itself empty.
+ */
+export type Dock = "letterbox" | "pad" | "band";
+export interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface Stage {
+    /** The slide's box, in CSS px. */
+    slideW: number;
+    slideH: number;
+    slideX: number;
+    slideY: number;
+    /** Caption font and strip height. Both 0 with captions off. */
+    capFont: number;
+    capH: number;
+    /** Where the control bar sits, and its box. */
+    dock: Dock;
+    bar: Box;
+    /** Button size, px. */
+    btn: number;
+    /** One settings button instead of speed, CC, size and full screen. */
+    compact: boolean;
+    /** Space between the bar's edges and its outermost buttons. */
+    barInset: number;
+    /** The caption strip's box, and the padding each side that its text never enters. */
+    strip: Box;
+    stripPad: number;
+    /** Two caption lines at this measure, in caption ems, for `splitForScreen`. */
+    cueEm: number;
+}
+/**
+ * Where the slide, its caption strip and the control bar go in a `vw`×`vh`
+ * viewport. `safeBottom` is the share of the slide's height at its foot that the
+ * composition keeps free of text (`safeBottomFor`); 0 means "assume none".
+ *
+ * NOT CIRCULAR. The v0.8.0 rule sized the caption from the viewport width and
+ * the critic's first fix sized it from the stage rect — but the stage is the
+ * viewport minus the strip, and the strip is a multiple of the font. Solving
+ * once for the slide height that leaves exactly one strip below it,
+ *
+ *   H0 = min(vw / aspect,  vh / (1 + STRIP_FONTS · CAPTION_RATIO · scale · short))
+ *
+ * (`short` is the slide's short side over its height: 1 for landscape), and
+ * deriving the font from THAT, gives a font that does not depend on the result
+ * it determines. The floor can only make the strip taller than the solve
+ * assumed, so the final height is re-clamped against the real strip.
+ *
+ * Slide, strip and (in the letterbox) bar are centred as one block: on a
+ * portrait phone the caption and the controls sit under the slide rather than
+ * at the bottom of the screen, and the slide gives up nothing for either.
+ */
+export declare function stageGeometry(vw: number, vh: number, aspect: number, captions: {
+    on: boolean;
+    size: CaptionSize;
+}, opts?: {
+    safeBottom?: number;
+}): Stage;
+/**
+ * The share of a composition's height at its foot that no layout draws text in:
+ * `.scene`'s bottom padding (`PAD_Y`, in reference px) less a margin, over the
+ * reference height. 16:9 at 1920x1080 is (84 − 16) / 1080 ≈ 6.3%.
+ *
+ * NOT FOR A FORMAT THAT RESERVES A CAPTION BAND: burned captions live there.
+ * Decks never do (`captionReserve` is a video setting), and an unknown shape
+ * reads as 0, which only ever moves the bar into a band of its own.
+ */
+export declare function safeBottomFor(width: number, height: number): number;
+/** Reference px kept between the lowest text a layout may set and the bar's top. */
+export declare const SAFE_MARGIN = 16;
+export type KeyAction = "next" | "prev" | "first" | "last" | "play" | "captions" | "faster" | "slower" | "bigger" | "smaller" | "mute" | "notes" | "video" | "escape" | "fullscreen";
+export interface KeyLike {
+    key: string;
+    /** The physical key, layout-independent: `KeyC` whatever the IME makes of it. */
+    code?: string;
+    isComposing?: boolean;
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    repeat?: boolean;
+}
+/**
+ * The v2 keymap. Founder's call (2026-10-07): Space is NEXT SLIDE, as it is in
+ * every presenter; Enter is play/pause.
+ *
+ * Any key held with Cmd, Ctrl or Alt belongs to the browser — v0.8.0 took
+ * Cmd+F for fullscreen and swallowed find. Toggles ignore auto-repeat, so a
+ * held `c` does not strobe the captions; stepping keys repeat on purpose.
+ */
+export declare function keyAction(e: KeyLike): KeyAction | null;
+/** One size step, clamped. */
+export declare function stepSize(current: CaptionSize, dir: 1 | -1): CaptionSize;

package/dist/types/deck/repack.d.ts

@@ -0,0 +1,10 @@
+/** The islands of a deck page, in order, exactly as written. */
+export declare function islandsOf(page: string): string[];
+/**
+ * `page` with `runtimeJs` as its player and the v2 marker in its head.
+ * Idempotent: repacking a repacked page with the same runtime returns it unchanged.
+ *
+ * Throws, rather than writing something half-right, on a page that is not a
+ * deck page or whose runtime script cannot be found where the emitter puts it.
+ */
+export declare function repackDeckPage(page: string, runtimeJs: string): string;

package/dist/types/deck/runtime.d.ts

@@ -1,4 +1,4 @@
-import { type Narration } from "./subtitles.js";
+import { type Cue, type Narration } from "./subtitles.js";
 /** One entry of the slideshow island's `slides` array. */
 export interface SlideSpec {
     sceneId: string;
@@ -49,6 +49,7 @@ export interface TransitionPlan {
  */
 export declare function planTransition(fromT: number, toT: number, opts?: {
     reducedMotion?: boolean;
+    rate?: number;
 }): TransitionPlan;
 /**
  * How long autoplay waits on the stop it is on, or `null` for "do not set a
@@ -75,7 +76,27 @@ export declare function dwellMs(opts: {
     playing: boolean;
     heard: boolean;
     gapMs: number;
+    /** The viewer's speed. Every wait is divided by it, after it is clamped. */
+    rate?: number;
+    /**
+     * v2: the stop has no narration segment at all — silent BY DESIGN, not a
+     * segment that failed to play. Its reveal is the whole of its content, so the
+     * deck waits for the reveal (`revealMs`, already at the viewer's speed) and a
+     * beat to take it in, then moves on. See `SILENT_HOLD`.
+     */
+    silent?: boolean;
+    revealMs?: number;
 }): number | null;
+/**
+ * How long a v2 deck playing itself holds a stop that has nothing to say, after
+ * its reveal has played, at 1x. Measured on the four preview decks (review,
+ * 2026-10-08): every one has 5–9 such stops, and at MAX_DWELL each they were
+ * 40–65s of silence against 227–303s of speech — 15–22% of the deck at 1x and a
+ * quarter to a third of it at 2x, the "slow" the founder heard. The linear
+ * render folds these stops into the sentence before them; this is the player's
+ * nearest equivalent: let the reveal land, give it a moment, go on.
+ */
+export declare const SILENT_HOLD = 1500;
 /** `#3` is slide 3; `#3.2` is slide 3, second fragment. Both 1-based. */
 export declare function formatHash(pos: Pos): string;
 export declare function parseHash(hash: string): Pos | null;
@@ -145,6 +166,32 @@ export declare function showingAt(slide: SlideSpec, clip: number, t: number): bo
  * export does not reach deck.html.
  */
 export declare function paint(frame: Frame, slides: readonly SlideSpec[], t: number): void;
+export interface ChromeV2 extends ReturnType<typeof mountChrome> {
+    controls: HTMLElement;
+    speed: HTMLButtonElement;
+    speedMenu: HTMLElement;
+    cc: HTMLButtonElement;
+    size: HTMLButtonElement;
+    sizeMenu: HTMLElement;
+    fs: HTMLButtonElement;
+    /** Compact mode's one settings button, and its menu (speed, captions, size, full screen). */
+    more: HTMLButtonElement;
+    moreMenu: HTMLElement;
+    /** A polite live region: setting changes are announced, cue text never is. */
+    say: HTMLElement;
+}
+/** Whether this deck page asked for the v2 player. See `PLAYER_META`. */
+export declare function wantsV2(doc: Pick<Document, "querySelector">): boolean;
+declare function mountChrome(doc: Document): {
+    chrome: HTMLDivElement;
+    fill: HTMLElement;
+    play: HTMLButtonElement;
+    video: HTMLButtonElement;
+    count: HTMLElement;
+    notes: HTMLElement;
+    flags: HTMLElement;
+    subs: HTMLElement;
+};
 export interface Voice {
     /**
      * Arrive at a stop: cut whatever was speaking, start this stop from zero.
@@ -161,6 +208,16 @@ export interface Voice {
     hush: () => void;
     toggleMute: () => void;
     toggleSubtitles: () => void;
+    /** Captions on or off, absolutely. The v2 player's preferences call this; the v0.8.0 key toggles. */
+    setSubtitles: (on: boolean) => void;
+    /**
+     * The narration speed, applied to the element that is speaking NOW as well as
+     * to every later one. Both halves matter and each was a separate bug in the
+     * plan: setting it only on the next `src` leaves the current sentence at the
+     * old speed, and setting only `playbackRate` is undone by the `load()` every
+     * stop runs, which resets it to `defaultPlaybackRate`.
+     */
+    setRate: (rate: number) => void;
     /** Called when the segment for the CURRENT stop finishes of its own accord. */
     onEnded: (fn: () => void) => void;
     /**
@@ -181,6 +238,25 @@ export interface Voice {
      * load — see `refused` for why the second one is never retried unasked.
      */
     unlock: () => void;
+    /**
+     * Called once per animation frame while the current stop's audio plays, with
+     * its `currentTime` — the clock v2's hold motion seeks by (src/deck/motion.ts).
+     */
+    onProgress: (fn: (seconds: number) => void) => void;
+    /**
+     * Pause the sentence where it is: the element stops, its clock stops, and the
+     * hold motion that seeks by that clock stops with it. v2's Enter. Unlike
+     * `hush`, the source is kept, so `resume` can carry on from the same word.
+     */
+    pause: () => void;
+    /**
+     * Carry on with the paused sentence from where it stopped. False when there
+     * is nothing to carry on — no segment here, it already finished, or a step
+     * has since dropped it — and the caller should speak the stop afresh.
+     */
+    resume: () => boolean;
+    /** Re-cut the current stop's captions after the strip changed width. */
+    refit: () => void;
 }
 /**
  * Was that `play()` rejection the autoplay policy, or an audio file we will
@@ -246,6 +322,25 @@ export declare function refused(err: unknown): boolean;
 export declare function mountVoice(doc: Document, narration: Narration, ui: {
     subs: HTMLElement;
     flags: HTMLElement;
+}, opts?: {
+    /**
+     * Whether the flag strip says "subtitles off". The v0.8.0 player has no other
+     * way to show it; the v2 player's CC button does, and saying it twice is a
+     * nag on top of the slide.
+     */
+    flagSubtitles?: boolean;
+    /**
+     * The v2 player. Only it has a speed, a hold motion and captions cut to the
+     * strip's width, so only it touches `playbackRate`, reports progress, or
+     * re-cuts cues. A classic deck's voice is v0.8.0's, call for call.
+     */
+    v2?: boolean;
+    /**
+     * How a v2 deck cuts a segment's cues for the strip it has NOW. Asked on
+     * every arrival and by `refit`, because the strip's width changes with the
+     * window and with the controls beside it.
+     */
+    cut?: (cues: readonly Cue[]) => Cue[];
 }): Voice;
 /** One player-page video, keyed in the island by the scene that draws its still. */
 export interface ClipSpec {

package/dist/types/deck/subtitles.d.ts

@@ -76,11 +76,39 @@ export declare const CUE_MAX_CHARS = 84;
  * that many pieces does the packing: same number of captions, no orphan.
  */
 export declare function splitCue(cue: Cue, max?: number): Cue[];
+/**
+ * Two caption lines' worth of text, in ems, at the narrowest stage the v2
+ * player is laid out for: a 358px-wide phone, where the caption is at its 13px
+ * floor and the strip's side padding leaves ~329px — 25.3em a line. 44 keeps
+ * ~13% for the slack a word-wrapping browser leaves at each line end. Every
+ * larger stage has MORE ems a line (the font scales with the slide, the width
+ * with the window), so a cue that fits here fits everywhere. Latin text at 0.56
+ * em a character comes to ~78 characters, a little under `CUE_MAX_CHARS`.
+ */
+export declare const SCREEN_CUE_EM = 44;
+/** A caption's width in ems, by the same measure `splitForScreen` packs with. */
+export declare function cueEm(text: string): number;
+/**
+ * `splitCue` for the v2 player's screen: the budget is two caption LINES in
+ * ems, not 84 characters. The difference is every CJK deck. 84 Japanese
+ * characters are 84em — four lines on a phone — and `splitCue` cannot split
+ * them at all, because it breaks only at spaces and Japanese and Chinese have
+ * none. Same even-split rule as `splitCue` (decide the piece count, then pack to
+ * the narrowest width that keeps it), so no piece is an orphaned word.
+ *
+ * Used only by a v2 deck page. The render path and the v0.8.0 player keep
+ * `splitCue`, so neither a burned caption nor an old deck moves.
+ */
+export declare function splitForScreen(cue: Cue, budgetEm?: number): Cue[];
 /**
  * Parse the island's text. Anything malformed reads as "no narration", which is
  * the deck we shipped yesterday and is always a safe answer.
  */
-export declare function parseNarration(text: string | null | undefined): Narration | null;
+export declare function parseNarration(text: string | null | undefined, 
+/** How a long cue is cut. `splitCue` unless a v2 deck page says `splitForScreen`. */
+opts?: {
+    split?: (cue: Cue) => Cue[];
+}): Narration | null;
 /**
  * The cue on screen at `t`, or null in a gap.
  *

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

@@ -79,7 +79,7 @@ export interface FigureLayout {
 export declare function planFigure(stageW: number, notes: FigureNote[], fig: {
     width: number;
     height: number;
-}, stageH: number, tall?: boolean, face?: Face): FigureLayout;
+}, stageH: number, tall?: boolean, face?: Face, upscale?: number): FigureLayout;
 /**
  * Height the stage may spend, once the chrome and the caption have taken theirs.
  * A budget, not a size — `planFigure` gives back only what it used.

package/dist/types/emit/archetypes/bar-compare.d.ts

@@ -1,30 +1,2 @@
-/**
- * Magnitudes, drawn.
- *
- * A table of figures makes the viewer do arithmetic: "1.592 against 0.930" is two
- * numbers and a subtraction. The same pair as two bars is one glance. So nothing
- * here is decoration — the bar lengths carry the entire claim, which is why the
- * scale is derived from the data and anchored at zero. A bar chart whose baseline
- * is not zero is a chart that asserts a ratio the numbers do not support, and it
- * would pass every gate we have.
- *
- * Three decisions worth knowing before changing anything:
- *
- * 1. Every bar sits in a full-width rail. The rail is what makes a dwarfed bar
- *    legible (see MIN_LEN) — the eye reads "almost none of the extent" rather
- *    than "nothing was drawn".
- * 2. Values count up rather than fade in, and they count on the same decimal grid
- *    their printed string is on, so the number GSAP lands on is byte-identical to
- *    the one in the static SVG.
- * 3. The bars are one reveal, not N. Holding on bar 3 of 8 asks the viewer to
- *    compare it against bars that have not been drawn yet.
- *
- * A label gutter beside the rails is a landscape idea. At 9:16 the demo's five
- * names took 340px of an 860px box, so 40% of the width was spent naming bars
- * that then had 60% left to differ in. Portrait puts the label on its own line
- * above the rail instead and hands the whole width to the comparison — which is
- * also where the height it needs comes from, since portrait has height to spare
- * and width it does not.
- */
 import type { Emitter } from "../kit.js";
 export declare const barCompare: Emitter<"bar-compare">;

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

@@ -1,2 +1,42 @@
+/**
+ * An equation becoming the next one.
+ *
+ * The keyed morph — the 3Blue1Brown move — and the one thing in the vocabulary
+ * that shows a DERIVATION rather than a statement: the terms the author keys
+ * travel from where they sit in the first line to where they sit in the second,
+ * as rigid bodies, and everything else dissolves. Which terms are keyed is the
+ * animation: `a^2+b^2=c^2` to `c^2-b^2=a^2` is a glyph riot unkeyed and a
+ * three-body exchange keyed, on the same two strings.
+ *
+ * The keying reuses `equation-walk`'s: a term is located in the TeX by normal
+ * form and wrapped in `\htmlClass{term t-<tone> ds-k-<tone>}{...}`, so KaTeX
+ * emits a real element the runtime can find. It must be found in BOTH lines
+ * to be a key at all — a term on one side only is dropped, with its legend
+ * row, exactly as the walk drops a term it cannot place.
+ *
+ * Geometry is measured in the browser, after fonts (Seam B), and the morph
+ * reaches the timeline as ONE typed `fromTo` on the host driving a GSAP plugin.
+ * See `src/emit/morph-runtime.ts` for why that, and not a callback.
+ */
+import type { BeatOf, Source, Term } from "../../types.js";
 import type { Emitter } from "../kit.js";
+/**
+ * Both lines and their keys, decided in Node — the morph's half of what
+ * `prepareWalk` is to the walk, so `plan` can report what `build` will do.
+ * Throws where the emitter would: a line KaTeX refuses even repaired, or no key.
+ */
+export declare function prepareMorph(beat: BeatOf<"equation-morph">, source: Source): {
+    a: {
+        id: string;
+        tex: string;
+    };
+    b: {
+        id: string;
+        tex: string;
+    };
+    wa: string;
+    wb: string;
+    both: Term[];
+    notes: string[];
+};
 export declare const equationMorph: Emitter<"equation-morph">;