@jokerized/decksmith 0.4.1 → 0.5.0

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

@@ -0,0 +1,102 @@
+import type { DeckNarration } from "../emit/composition.js";
+import type { Source, Storyboard } from "../types.js";
+/** Progress, for a caller that has somewhere to put it. */
+type Step = (message: string) => void;
+/**
+ * Where a narrated deck keeps its voice, in the built deck and inside a pack
+ * alike. One name in one place: the emitter writes it into the island, `build`
+ * copies into it, `pack` stores under it, and `unpack` restores it — and none of
+ * them has to agree with the others by memory.
+ */
+export declare const AUDIO_DIR = "audio";
+/** The mp3s an island names, deduplicated and in a stable order. */
+export declare function audioNames(narration: {
+    beats: Record<string, {
+        audio: string;
+    }[]>;
+}): string[];
+/**
+ * Vendor KaTeX's stylesheet and woff2 fonts beside the deck.
+ *
+ * The HyperFrames compiler inlines `<script src>` but not `<link rel=stylesheet>`,
+ * so a CDN-linked stylesheet is fetched — with its fonts — during capture. That
+ * breaks "no network at render time" (invariant 4) and makes equation decks
+ * nondeterministic in a way that took four experiments to corner. The frame that
+ * finally showed it differed by exactly one glyph, the caligraphic W of
+ * `\mathcal{W}`, present in one render and not the other — a font that had
+ * arrived by that frame on one run and not on the next.
+ *
+ * Only woff2 is copied. KaTeX ships woff2, woff and ttf of every family; every
+ * browser this deck will ever open in reads woff2, and the other two are three
+ * quarters of the payload. The rewrite drops their `url(...)` entries so nothing
+ * requests a file that is not there.
+ */
+export declare function vendorKatex(out: string): Promise<string[]>;
+/**
+ * The scripts a deck runs, copied beside it.
+ *
+ * Pinned by package.json rather than by a URL, so the version that renders is
+ * the version that was installed and tested. See the note on GSAP_SRC in
+ * src/emit/composition.ts for why this is not left to the compiler's inliner.
+ *
+ * WHAT THE HEAD LOADS, AND NOTHING ELSE. `composition` is read rather than
+ * `laid.plugins` threaded out of `emit`, because the question this is answering
+ * is literally "which of these does the page ask for" — and asking the page
+ * cannot drift from the page. It also makes the conditional plugins honest on
+ * disk as well as in the head: MorphSVG is 21,195 bytes that a deck without a
+ * reshape neither loads NOR carries, which is the rule `PLUGINS` states.
+ */
+export declare function vendorScripts(out: string, composition: string): Promise<string[]>;
+/**
+ * `assets/` beside source.json, if there is one. Absent is the ordinary case.
+ *
+ * NAMED FILES ONLY, never the directory.
+ *
+ * This was `cp(from, ..., { recursive: true })`, which copied whatever happened
+ * to be beside the figures. Two costs, one of them a hole: the shipped demo
+ * carried 640 KB of JPEGs no beat referenced, and — since a deck is served over
+ * HTTP from a directory a stranger's upload contributed to — an `.svg` or
+ * `.html` that rode along was served from the deck's own path. The CSP sandbox
+ * now covers that, but a file that never arrives needs no containment.
+ *
+ * `fonts/` is the one directory that comes along, because `refreshFont` writes
+ * the subsetted bundle into it and the stylesheet names its own files.
+ *
+ * A CLIP CONTRIBUTES TWO FILES, and forgetting the second is a 404 at run time
+ * rather than a build error: `poster` is what the video shows before its first
+ * frame decodes, and what a player-page clip degrades to when there is no
+ * downloadable file at all. Named here because this set is the ONLY thing that
+ * reaches the built deck — a poster left out is simply absent, and the deck's
+ * own runtime reports it as `http_error 404`, a long way from this line.
+ */
+export declare function copyAssets(sourceDir: string, out: string, figures: readonly {
+    src: string;
+    poster?: string;
+}[], step: Step): Promise<string[]>;
+/**
+ * Copy the spoken audio into the deck. Only the files the island references: an
+ * audio directory is content-addressed and accumulates every take ever made, and
+ * shipping the ones a re-edit orphaned would double a deck's size for nothing.
+ *
+ * `narration.dir`, NOT the `AUDIO_DIR` constant, and the difference is not a
+ * preference. `dir` is the string the emitter wrote into the island, so it is
+ * what the built page asks the network for; copying to a name the page does not
+ * name is a 404 per sentence and silence for the whole deck. `AUDIO_DIR` is
+ * where `dir` COMES FROM — `loadNarration` and the server both set it — which is
+ * why the two have never disagreed, and exactly why nothing would have caught
+ * them if they had.
+ */
+export declare function copyAudio(from: string, narration: DeckNarration, out: string, step: Step): Promise<string[]>;
+/**
+ * The planner writes headlines the source never contained, so the subset `ingest`
+ * cut can be missing glyphs — and a missing glyph falls back silently, which is
+ * the failure invariant 9 exists to prevent. Re-cut over the text the deck really
+ * renders. The bundle is content-hashed, so this is a no-op when nothing new
+ * appeared, and a build that cannot reach the font service keeps what it copied.
+ *
+ * Every glyph a document or plan can put on screen: serializing the whole object
+ * over-collects ids and TeX, but those are ASCII and the bundle only exists for
+ * CJK — over-collecting costs a few bytes, under-collecting costs a tofu box.
+ */
+export declare function refreshFont(storyboard: Storyboard, source: Source, out: string, step: Step): Promise<string | undefined>;
+export {};

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

@@ -158,8 +158,10 @@ export interface Voice {
  * So this split decides what the strip says, and whether anything retries
  * unasked. It does NOT decide whether a person may retry: a gesture re-arms
  * either failure (see `unlock`), because someone asking is not the same as us
- * guessing. And no gate here can see any of it — nothing in the suite opens
- * deck.html or plays a sound.
+ * guessing. `test/deck-page.test.ts` now opens deck.html and asserts the strip
+ * NAMES an unplayable segment instead of going quiet — it was one of the four
+ * regressions that gate was proved against. Nothing still plays a sound, so
+ * which of the two failures a real browser hits is untested.
  *
  * `NotSupportedError` is the unplayable one — observed rather than taken from
  * the spec: a source that cannot be fetched at all rejects `play()` with

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

@@ -109,7 +109,39 @@ export declare function zoomOf(format: Format): number;
  * afford it.
  */
 export declare function contentW(format: Format): number;
+/**
+ * REFERENCE PX, WHICH IS WHY THE RESERVE IS CONVERTED HERE. `format.captionReserve`
+ * is measured on the CANVAS — `bandReserve` derives it from `burnStyle`'s
+ * ratios, which are canvas ratios — and everything on this side of the codebase
+ * does its arithmetic in reference px, which `refHeight` has already scaled. At
+ * 1080x1920 the canvas-to-reference factor is 2560/1920, so a 301px reserve is
+ * 402 reference px; subtracting the canvas number raw would under-reserve by a
+ * quarter and put the ink back under the band.
+ *
+ * `Math.ceil`, not `round`: a fractional px of reserve that gets rounded away is
+ * a fractional px of ink inside the band.
+ *
+ * SUBTRACTING HERE IS NOT ENOUGH ON ITS OWN, and the design note this implements
+ * was wrong about that. It claimed every archetype lays out into `contentH`, so
+ * that one subtraction would move all of them. Ten of them — `bar-compare`,
+ * `callout`, `claim-figure`, `data-table`, `equation-morph`, `equation-walk`,
+ * `grid`, `index`, `line-chart`, `pipeline` — never mention `contentH` at all.
+ * What actually bounds them is `.scene`'s CSS padding in `theme.ts`, which
+ * centres their content in the box the stylesheet leaves. MEASURED: subtracting
+ * only here moved the 9x16 demo's worst stop by nothing at all — 0.529% of the
+ * frame was ink inside the band both before and after, byte for byte.
+ *
+ * So the reserve comes off BOTH, and the pair is exactly the hazard the header
+ * of this file warns about: a stylesheet that disagrees with the arithmetic
+ * clips at the canvas edge, and no gate reads the stylesheet.
+ *
+ * NOT IN `PAD_Y` ITSELF. The padding is symmetric and the reserve is not — a
+ * symmetric version would throw away as much off the TOP of every slide for
+ * nothing. `theme.ts` adds it to the bottom only.
+ */
 export declare function contentH(format: Format): number;
+/** `format.captionReserve`, canvas px, expressed in this file's reference px. */
+export declare function reserveRef(format: Format): number;
 export interface Theme {
     bg: string;
     fg: string;

package/dist/types/index.d.ts

@@ -226,7 +226,10 @@ export interface BuildDeckOptions {
     narration?: DeckNarration;
     /** Directory holding those mp3s now; they are copied into the deck. */
     audioFrom?: string;
-    /** Directory whose `assets/` is copied in. Defaults to `out`'s neighbours. */
+    /**
+     * Directory whose `assets/` is copied in. Absent, nothing is. Only the files
+     * `source.figures` names travel, plus `fonts/` — see `copyAssets`.
+     */
     assetsFrom?: string;
     /** Progress lines. Silent by default: a library that prints is a library you
      *  cannot run inside a request handler. */
@@ -242,10 +245,11 @@ export interface BuildDeckOptions {
  * which a caller may not have and may not want on the request path; call it
  * yourself when you do.
  *
- * NOTE: this is the same sequence as `build` in src/cli.ts, written out a second
- * time rather than shared, because that file is owned elsewhere this pass. The
- * next person to touch cli.ts should delete its copy and call this — two
- * implementations of "what a deck directory contains" is exactly the kind of
- * drift that ends in a deck that opens locally and 404s in production.
+ * The file work is `src/build/files.ts`, which `build` in src/cli.ts calls too —
+ * it used to be written out twice, and the three ways the copies had already
+ * drifted are recorded in that module's header. Anything a deck directory
+ * contains beyond `index.html` and its two manifests goes there, not here, so
+ * the two callers cannot answer "what does a deck directory contain" differently
+ * again.
  */
 export declare function buildDeck(storyboard: Storyboard, source: Source, outDir: string, opts?: BuildDeckOptions): Promise<BuildResult>;

package/dist/types/render/render.d.ts

@@ -27,10 +27,22 @@ export interface SubtitlePlan {
  */
 export declare function subtitlePlan(mode: SubtitleMode): SubtitlePlan;
 /**
- * WHAT A REAL FIX NEEDS. Making the band optional did not stop it covering the
- * slide; it only means you can now choose not to be covered. Anyone who wants
- * `--subtitles burn` to be safe rather than merely available has to do this, and
- * the shape of it is not obvious, so it is written down once here.
+ * WHAT A REAL FIX NEEDED — BUILT, on 2026-09-12, as `build --reserve-captions`.
+ * The five steps below are the plan it was built from and they are kept because
+ * four of them are still the reason the code is shaped this way. Step 3 is kept
+ * for the opposite reason: it was WRONG, and the correction is the useful part.
+ *
+ * WHERE IT IS NOW. `bandReserve` (src/types.ts) is the one source for the band's
+ * box; `Format.captionReserve` carries it; `contentH` AND `.scene`'s padding
+ * both give it up; `fidelity`'s `ink_in_caption_reserve` fails a deck that draws
+ * into it; and `render --subtitles burn` refuses a deck whose `timing.json`
+ * reserved nothing. Measured on the twelve-beat demo at 1080x1920 over 31 stops:
+ * reserved, 0 of 31 stops put ink in the band; the same deck unreserved and
+ * judged against the same band, 1 of 31 at 0.529% of the frame.
+ *
+ * Making the band optional did not stop it covering the slide; it only meant you
+ * could choose not to be covered. The shape of the real fix was not obvious, so
+ * it was written down here first.
  *
  * THE MEASUREMENT. At 1080x1920 the band is 862x120px and `burnStyle`'s
  * `marginV` puts its baseline 173px off the bottom, so it occupies the bottom
@@ -58,14 +70,30 @@ export declare function subtitlePlan(mode: SubtitleMode): SubtitlePlan;
  *     `--reserve-captions` flag. It belongs on `Format` and not on `DeckOptions`
  *     because it changes the drawable box, which is what a format IS.
  *
- *  3. THE DRAWABLE BOX SHRINKS, IN ONE PLACE. `contentH` in src/emit/kit.ts
- *     becomes `height - 2·padY - captionReserve`. That is the whole geometric
- *     change: every archetype was audited for this and none of the twelve reads
- *     `format.height` directly — only `title.ts`, and only to ask which way up
- *     the canvas is. They all lay out into `contentH`, so subtracting there moves
- *     all of them at once. Note it must NOT go into `padY`: the padding is
- *     symmetric and the reserve is not, and a symmetric version would throw away
- *     as much off the top for nothing.
+ *  3. THE DRAWABLE BOX SHRINKS, IN ONE PLACE — AND THIS STEP WAS WRONG. It said
+ *     `contentH` in src/emit/kit.ts becomes `height - 2·padY - captionReserve`,
+ *     and that "they all lay out into `contentH`, so subtracting there moves all
+ *     of them at once."
+ *
+ *     They do not. TEN of the archetypes never mention `contentH` —
+ *     `bar-compare`, `callout`, `claim-figure`, `data-table`, `equation-morph`,
+ *     `equation-walk`, `grid`, `index`, `line-chart`, `pipeline`. What bounds
+ *     them is `.scene`'s CSS padding in src/emit/theme.ts, which centres their
+ *     content in whatever box the stylesheet leaves. The audit behind the
+ *     original claim asked which archetypes read `format.height`, which is a
+ *     different question and has a comforting answer.
+ *
+ *     MEASURED, because the plan read convincingly enough to ship on: with the
+ *     subtraction in `contentH` alone, the 9x16 demo's worst stop was 0.529% of
+ *     the frame in ink inside the band — identical, to the digit, to the same
+ *     deck with no reserve at all. So the reserve is taken in BOTH places, and
+ *     they are the exact pair src/emit/kit.ts's own header warns about: a
+ *     stylesheet that disagrees with the arithmetic, which no gate reads.
+ *
+ *     Still true, and still the reason it is not simply `padY`: the padding is
+ *     symmetric and the reserve is not. `theme.ts` adds it to the bottom only,
+ *     and emits the two-value padding unchanged when the reserve is 0, so a deck
+ *     that reserves nothing is byte-identical to one built before this existed.
  *
  *  4. A GATE, OR THIS REGRESSES. `src/verify/check.ts` must fail a deck whose
  *     audience text falls inside the reserve — invariant 5 with a new floor. A

package/dist/types/render/timing.d.ts

@@ -100,6 +100,17 @@ export interface Timing {
     /** Directory holding the mp3s, relative to the deck. `""` when silent. */
     audioDir: string;
     voice: string;
+    /**
+     * Canvas px the deck's layout gave up at the bottom for a burned caption, 0
+     * if it gave up none. Recorded because the burn decision is taken at RENDER
+     * time and the layout was fixed at BUILD time: without this, `--subtitles
+     * burn` over a deck built before the reserve existed silently puts the band
+     * back on the slide's own text, which is the defect that started all of this.
+     *
+     * Optional, and absent reads as 0: every `timing.json` already on disk was
+     * written without it, and those decks did reserve nothing.
+     */
+    captionReserve?: number;
     scenes: TimedScene[];
     segments: TimedSegment[];
 }

package/dist/types/types.d.ts

@@ -2439,7 +2439,71 @@ export interface Format {
      * failure. Omitted when every destination for the format agrees on `maxSeconds`.
      */
     warnSeconds?: number;
+    /**
+     * Canvas px of the bottom of the frame reserved for a burned-in caption, which
+     * the drawable box gives up. 0 — the default — means nothing is reserved.
+     *
+     * ON `Format` AND NOT ON `DeckOptions`, because it changes the drawable box,
+     * and the drawable box is what a format IS. Two decks built from one
+     * storyboard, one reserving and one not, are different formats in every sense
+     * that matters downstream: different `contentH`, different archetype layouts,
+     * different type sizes. `id` is left alone — the profile's pacing, budget and
+     * navigability are unchanged — but `writeTiming` records the number so
+     * `render` can refuse to burn over a deck that never made room. See the
+     * design note above `RenderOptions` in src/render/render.ts.
+     *
+     * Optional in the TYPE for the same reason as `maxSeconds`: every test fixture
+     * that needs a canvas would otherwise have to invent a reserve it does not
+     * care about, and absent must read as "reserved nothing", which is the state
+     * every deck built before this existed is actually in.
+     */
+    captionReserve?: number;
 }
+/**
+ * THE ONE SOURCE FOR THE BAND'S BOX, because a second copy of these ratios is
+ * exactly how the collision came back.
+ *
+ * These live in `types.ts` rather than beside `burnStyle` (src/render/ffmpeg.ts)
+ * for a layering reason that is not negotiable: `src/emit` may not import
+ * `src/render` — the dependency runs the other way, `src/render/timing.ts`
+ * imports four things out of `src/emit`. The emitter is the side that has to
+ * shrink its drawable box, so the numbers have to sit where BOTH can reach
+ * them, and `Format` is already here.
+ *
+ * `burnStyle` reads these; it does not restate them.
+ */
+export declare const CAPTION_FONT_RATIO = 0.037;
+export declare const CAPTION_MARGIN_V_RATIO = 0.09;
+export declare const CAPTION_MARGIN_X_RATIO = 0.04;
+/** The `--line` default `captionPage` writes, as a multiple of the font size. */
+export declare const CAPTION_LINE_RATIO = 1.6;
+/**
+ * Two, and it is bounded rather than hoped for: `splitCue` caps a cue at 84
+ * characters and `wrap` breaks it near the middle, and `burnStyle`'s font size
+ * is chosen so the longer half still fits one line with 9% to spare. A third
+ * line is the failure that sizing exists to prevent, so reserving for two is
+ * reserving for the worst case that can actually occur.
+ */
+export declare const CAPTION_MAX_LINES = 2;
+/** The burned band's font size at this canvas width. */
+export declare function captionFontSize(width: number): number;
+/**
+ * The bottom strip the burned caption may occupy, `marginV` included, in CANVAS
+ * px — everything `src/emit` must therefore keep its ink out of.
+ *
+ * AN UPPER BOUND, DELIBERATELY, and derived from the CSS rather than from a
+ * browser. `captionPage` declares `line-height: round(F * 1.6)` and the real
+ * painted line box is whatever the font actually produces, which is smaller: at
+ * 1080x1920 this returns **301px** against the **293px** measured off two
+ * rendered frames in `.planning/EXPERIMENT-010-reconcile.md`. Eight px of slack,
+ * on the safe side. A bound that needed a browser to compute could not be read
+ * by the emitter at all, which is the whole reason the collision survived this
+ * long — the band's height was only known after layout, an hour too late.
+ *
+ * Under-reserving reintroduces the defect silently, so if these two ever have to
+ * disagree, this one is the one that must be larger.
+ */
+export declare function bandReserve(width: number, height: number): number;
 /** A real place a built file gets uploaded, and the length it stops accepting at. */
 export interface Destination {
     /** What a person would call it. Printed in budget findings. */

package/dist/types/verify/fidelity.d.ts

@@ -162,7 +162,37 @@ export interface Measured extends Stop {
     ink: number;
     /** Where the band began, as a fraction of frame height. Reported for triage. */
     bandTop: number;
+    /**
+     * Non-background pixels inside the caption RESERVE, over the whole frame's
+     * pixels. `undefined` on a deck that reserved nothing — there is no band to
+     * be inside, and 0 would read as "measured and clear".
+     */
+    reserveInk?: number;
 }
+/**
+ * Ink is allowed in the reserve up to this fraction of the whole frame, and the
+ * number is measured rather than chosen.
+ *
+ * MEASURED on the twelve-beat demo at `short-9x16`, 1080x1920, 31 stops, the two
+ * builds differing only in `--reserve-captions`:
+ *
+ * | build | stops with ink in the band | worst |
+ * | --- | --- | --- |
+ * | `--reserve-captions` | 0 of 31 | 0 |
+ * | the same deck, unreserved, judged against the same band | 1 of 31 | 0.529% |
+ *
+ * So on a correct build the strip is background and anything at all is a real
+ * intrusion. The tolerance exists only so a stray antialiased edge cannot fail a
+ * build, and it is an ORDER OF MAGNITUDE below `INK_FLOOR`: one short headline
+ * is 0.15% of the frame, so 0.01% cannot be a glyph and can only be a fringe.
+ *
+ * NOT fitted to the failing case: the intrusion it has to catch is 0.529%, fifty
+ * times this, so the gate is not balanced on a margin. And note what the control
+ * is worth — the first version of this fix subtracted the reserve from
+ * `contentH` alone, and the reserved build measured 0.529% too, identically.
+ * The gate is what found that; no other gate in the stack moved.
+ */
+export declare const RESERVE_INK_TOLERANCE = 0.0001;
 export interface FidelityOptions {
     floor?: number;
     /**
@@ -172,7 +202,15 @@ export interface FidelityOptions {
      */
     stops?: readonly Stop[];
     timeoutMs?: number;
+    /** Override the reserve read off `timing.json`. For tests and the 015 harness. */
+    captionReserve?: number;
 }
+/**
+ * The caption reserve this deck was BUILT with, in canvas px, out of its own
+ * `timing.json`. 0 when the file is missing, unparseable, or predates the field
+ * — all three mean the same thing: nothing was reserved.
+ */
+export declare function readReserve(timingText: string | null): number;
 export interface FidelityReport {
     stops: Measured[];
     /**
@@ -236,6 +274,23 @@ export declare function readStops(timing: string | null, deckPage: string | null
  * is named because that is the frame to open.
  */
 export declare function gradeFidelity(rows: readonly Measured[], floor?: number): Finding[];
+/**
+ * Ink that got into the strip the burned caption is going to occupy.
+ *
+ * WHY THIS RULE EXISTS AT ALL. `contentH` already subtracts the reserve, so on
+ * a correct build this can never fire — which is exactly the argument for
+ * having it. The geometry is one refactor, one new archetype, or one absolute
+ * position away from being undone, and the failure is invisible to every other
+ * gate in the stack: the deck passes, the video renders, the band lands on the
+ * slide's own text, and the only way anyone finds out is by opening a frame.
+ * That is the failure mode this project keeps producing, and a purely geometric
+ * fix with no gate is how it comes back.
+ *
+ * An ERROR, not a warning. The deck asked for the reserve — `--reserve-captions`
+ * is typed on purpose — so ink inside it is the build failing to deliver the
+ * thing it was told to deliver, not a note about taste.
+ */
+export declare function gradeReserve(rows: readonly Measured[], tolerance?: number): Finding[];
 /**
  * Seek every declared stop and count the ink below its caption.
  *

package/dist/types/verify/index.d.ts

@@ -60,11 +60,16 @@ export declare function verify(dir: string, opts?: VerifyOptions, storyboard?: S
 /**
  * Every mp3 the narration island promises is actually in the deck.
  *
- * Nothing else notices this. `hyperframes check` never opens `deck.html`, and
- * the runtime treats a missing file exactly like a browser that refused to
- * autoplay — it clears the subtitles and moves on. So a deck that lost its audio
+ * Nothing else notices this in a BUILD. `hyperframes check` never opens
+ * `deck.html`, and the runtime treats a missing file exactly like a browser that
+ * refused to autoplay — it clears the subtitles and moves on. So a deck that lost its audio
  * on the way to a web host presents in silence and says nothing about why, which
  * is the failure mode a gate exists for.
+ *
+ * `test/deck-page.test.ts` does now open `deck.html` in a browser, and asserts
+ * that an unplayable segment is NAMED in the flag strip rather than going quiet.
+ * That is a test, not a build gate: it runs on a deck the suite builds, and says
+ * nothing about the deck a user is shipping. This still has to exist.
  */
 export declare function scanNarration(page: string, files: ReadonlySet<string>): Finding[];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jokerized/decksmith",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Turn a source document into an animated explanation deck.",
   "type": "module",
   "license": "MIT",
@@ -63,7 +63,7 @@
     "commander": "^14.0.1",
     "fflate": "^0.8.3",
     "gsap": "^3.14.2",
-    "hyperframes": "0.8.33",
+    "hyperframes": "0.8.35",
     "katex": "^0.16.11",
     "puppeteer-core": "^25.3.0",
     "remark-gfm": "^4.0.1",