@jokerized/decksmith 0.1.4 → 0.3.0

package/dist/types/plan/duration.d.ts

@@ -23,10 +23,27 @@
  * else, so hitting 60s over 12 slides needs a shorter sentence AND a faster
  * animation. Neither alone gets there; that is the whole content of this file.
  *
+ * WHICH SLIDE COUNT THE BUDGET IS STRUCK AT. `prefs.slides` is what was ASKED
+ * FOR and `beats` is what the planner came back with, and they are routinely not
+ * the same number — four of the last five real plans came back short. Every
+ * derived number here is `duration / count`, so striking the budget at the
+ * request while the deck has fewer beats paces each scene for a slide shorter
+ * than the one it is: eight beats against a sixty-second target were paced for
+ * five-second beats that are really seven and a half, and the video came in
+ * under its target with every gate green and nothing anywhere saying so. So
+ * every caller holding a storyboard passes its `beats.length`. The two that
+ * cannot are `systemPrompt`, which builds the prompt before a plan exists, and
+ * the MCP `estimate`, which is a pre-flight with no plan at all; they get the
+ * request, which is the only number they have. The SHORTFALL itself is not this
+ * file's to report — `scanBeatCount` in src/verify/index.ts reports it, because
+ * a beat count is arithmetic rather than a judgement and a prompt rule alone can
+ * always be met cosmetically.
+ *
  * Everything here is pure arithmetic over preferences, so it is testable with no
  * planner, no TTS and no ffmpeg.
  */
 import type { Prefs } from "../prefs.js";
+import type { Source } from "../types.js";
 /**
  * Characters of text per second of speech.
  *
@@ -174,6 +191,17 @@ export declare const FF_BEAT_SECONDS = 8;
  * for both put 60 seconds at eight slides when the reference is twelve.
  */
 export declare const MIN_BEAT_SECONDS = 4;
+/**
+ * The longest a slide may sit and still be one thought.
+ *
+ * Past twenty seconds a beat stops being a slide and becomes a section of a
+ * lecture: the demo sits at 20.5s and is already the slowest thing this project
+ * ships. It was the bare `20` inside `slidesFor`'s tempo clamp; it is named
+ * because that function now uses it twice — once to stop a long target from
+ * flattening into a handful of enormous beats, and once as the floor a thin
+ * DOCUMENT may shorten the deck to. Both are the same rule.
+ */
+export declare const MAX_BEAT_SECONDS = 20;
 /**
  * Subtitle rate a short-form viewer will take, as against broadcast television.
  *
@@ -247,10 +275,27 @@ export declare const SHORT_FORM_CPS = 22;
  * IT COSTS A STEP, KNOWINGLY. The demo's real p95 cue at `+20%` is 21.321,
  * inside the ceiling of 22 — but this predicts 22.13 for that step and refuses
  * it, so the deck takes `+10%` and speaks slower than the artifact proves it
- * could. A central estimate of ~1.26 would admit `+20%` and track the artifact
- * to within 0.6%; it would also under-predict on about half of future runs. The
- * trade was made deliberately in favour of never being under, on a statistic
- * measured once over 39 cues.
+ * could. It also costs the 60-second case its full sentence: twelve slides at
+ * low density plan 66 characters against the 72 of `EXPLAINING_CHARS`, where
+ * ~1.26 would plan exactly 72.
+ *
+ * 1.26 IS NOT AVAILABLE, THOUGH, and it is worth writing down why because the
+ * arithmetic above makes it look free. **The floor is 1.2784**, which is this
+ * deck's own `DEMO_P95_CUE_CPS / SPEECH_CPS.latin` — 18.409 / 14.4 — and
+ * `test/duration.test.ts` fails anything under it, one-sided and on purpose.
+ * A constant below the anchor's measured ratio admits a step whose captions are
+ * over the ceiling, which is exactly the 1.17 bug this replaced.
+ *
+ * The five ratios in the table above centre on 1.2604 and tempt you under that
+ * floor. They are a DIFFERENT synthesis of the same text: edge-tts does not
+ * repeat itself, and the `+0%` re-run came back at 1.2467 where the artifact in
+ * `demo/audio` sits at 1.2784. The shipped artifact wins — it is the deck that
+ * actually exists. So the honest range is [1.2784, 1.2945], the second number
+ * being the highest ratio the re-run saw, and 1.30 clears both.
+ *
+ * The 60-second sentence is therefore not bought back by tuning this. It is
+ * bought with seconds or with slides, which is what the rest of this file has
+ * said all along, and 90s plans 102.
  *
  * `test/duration.test.ts` pins the `+0%` end against the artifact.
  */
@@ -344,7 +389,16 @@ export interface DurationPlan {
     chars?: number;
     /** Seconds of speech one beat can afford. Absent without a target. */
     speechSeconds?: number;
-    /** The per-beat length the target implies. Absent without a target. */
+    /**
+     * The per-beat length the target implies, at the count the plan was struck at.
+     * Absent without a target.
+     *
+     * A BUDGET, NOT THE ANSWER, and the name collides with the thing that IS the
+     * answer. `beatSeconds` in src/emit/composition.ts — `max(authored·speed,
+     * lastHold + SETTLE, speechEnd + SETTLE)` — is what actually sizes a scene,
+     * and it never sees this number. `speed` is the only value this file sends
+     * into the emitted timeline; everything else here is advice to the planner.
+     */
     beatSeconds?: number;
     /** Said, never fatal: what the target costs, or cannot buy. */
     warnings: string[];
@@ -359,8 +413,14 @@ export interface DurationPlan {
  * `duration` set OVERRIDES `animationSpeed`: the target owns the pace, because
  * the two cannot both be honoured and the target is the one the user stated a
  * number for. Said in a warning rather than silently.
+ *
+ * `beats` is the count the budget is struck at, and it defaults to the count
+ * that was asked for. Pass the storyboard's own `beats.length` wherever one is
+ * in hand — see the header for why, and for the two callers that structurally
+ * cannot. The default is not a convenience: it is the right answer for those
+ * two, and it is what keeps a run where the planner hit its number identical.
  */
-export declare function durationPlan(prefs: Prefs): DurationPlan;
+export declare function durationPlan(prefs: Prefs, beats?: number): DurationPlan;
 /**
  * How many slides a target should have, by TEMPO.
  *
@@ -387,11 +447,90 @@ export declare function durationPlan(prefs: Prefs): DurationPlan;
  *     30s ->  8    120s -> 12    600s -> 30
  *     60s -> 12    300s -> 15
  *
+ * AND HOW MUCH THE DOCUMENT HAS TO SAY, which is the half that was missing. The
+ * table above is flat at twelve from 48s to 240s no matter what it is pointed
+ * at: a four-page workshop note and a forty-page survey both got twelve beats,
+ * because the only input was a clock. Tempo says how long a beat may LAST; it
+ * cannot say how many points exist to spend beats on. So `source`, when the
+ * caller has one, scales the tempo count by what the document actually contains
+ * (`sourcePoints`), bounded by `SUPPLY_RANGE` because the measure is coarse and
+ * its authority should be too.
+ *
+ *     60s + a thin note  ->  6      240s + a thin note  -> 12
+ *     60s + a full paper -> 15      240s + a full paper -> 17
+ *
+ * The clock still wins at both ends. Sixty seconds cannot hold seventeen beats
+ * at `MIN_BEAT_SECONDS` apiece, so a rich document against a short target spends
+ * its extra points on nothing; and past four minutes `MAX_BEAT_SECONDS` holds
+ * the count up, so a thin note asked for a long video does not become six
+ * forty-second slides. Only where the clock leaves room does the document move
+ * the number — which is most of the range people actually ask for.
+ *
+ * WHO CAN PASS A SOURCE. The CLI's `plan` verb reads `source.json` before it
+ * resolves preferences, so it can and does. `parseOptions` (src/server/options.ts)
+ * derives the count while the upload is still a form, before anything is
+ * ingested, and the MCP `estimate` is a pre-flight with no document at all;
+ * both get the tempo number, which is what they got before. Omitting the
+ * argument is therefore not a degraded path, it is the old behaviour, byte for
+ * byte.
+ *
  * This is the DEFAULT, never an override. `slides` is one of the three knobs the
  * owner asked to hold — "user can give you the number of slides they want in the
- * video with duration of their choice" — so an explicit count is obeyed.
+ * video with duration of their choice" — so an explicit count is obeyed, which
+ * is `loadPrefs`'s business: it calls this only when nobody named a number.
+ */
+export declare function slidesFor(prefs: Prefs, source?: Source): number;
+/**
+ * Characters of section prose one beat is worth.
+ *
+ * A GUESS, and marked one the way `SPEECH_CPS.cjk` is: no full-length document
+ * is stored in this repository to measure against — `demo/source.json` is a
+ * 231-character stub whose twelve beats were written by hand, and the fixture
+ * papers are 1.9 KB each. What matters is this number's RATIO to
+ * `REFERENCE_POINTS`, and the two are set together so an eight-section
+ * conference paper — around 30k characters, five figures, two tables, four
+ * equations — comes out above the reference rather than at it. Replace both with
+ * a measurement the first time a corpus of real sources exists.
+ */
+export declare const PROSE_CHARS_PER_BEAT = 1800;
+/**
+ * The supply a document needs to earn the tempo's own beat count.
+ *
+ * Twenty points is roughly a solid conference paper minus its trimmings. Below
+ * it the deck shortens, above it the deck lengthens, and `SUPPLY_RANGE` decides
+ * how far either can go.
+ */
+export declare const REFERENCE_POINTS = 20;
+/**
+ * How far the document may move the tempo's count, as a multiplier.
+ *
+ * Bounded rather than open because `sourcePoints` is a proxy and a proxy should
+ * not be trusted past the range where it is obviously right. Half is the
+ * shortest a deck of a real document should get before the answer is "this is
+ * not enough source"; one and a half keeps a rich paper under the twenty-second
+ * beat that makes a deck a lecture. A survey with a hundred points is not worth
+ * a hundred beats, and the clamp is what says so.
+ */
+export declare const SUPPLY_RANGE: {
+    readonly min: 0.5;
+    readonly max: 1.5;
+};
+/**
+ * How many distinct points a document offers a deck.
+ *
+ * Two supplies, added, because they are genuinely different things to make a
+ * beat out of: PROSE, which carries the argument, and EXHIBITS — the figures,
+ * tables and equations the authors made on purpose because a sentence was not
+ * enough. RULE 2 in the prompt tells the planner every figure should earn a
+ * beat, so a document with eight of them is asking for a longer deck than one
+ * with none, and this is where that is counted rather than hoped for.
+ *
+ * Headings are deliberately NOT counted. A section boundary is a formatting
+ * decision — one author writes six headings over 20k characters and another
+ * writes twenty-four over the same prose — so counting them would measure the
+ * template rather than the document.
  */
-export declare function slidesFor(prefs: Prefs): number;
+export declare function sourcePoints(source: Source): number;
 /**
  * How fast this deck speaks.
  *
@@ -442,12 +581,48 @@ export declare function p95CueRate(cues: readonly {
     text: string;
 }[]): number;
 /**
- * Whether this deck's own captions survive being sped up this much.
- *
- * Computed from the deck's MEASURED p95 cue rate against broadcast practice, not
- * from a hardcoded ceiling: a deck whose captions already run at 18 cps has no
- * headroom at all, and one written in short lines has plenty. Warns, never
- * refuses — how readable a caption has to be is the user's call, and they can
- * only make it if they are told the number.
+ * What is wrong with speeding this deck up this much — everything that is.
+ *
+ * TWO CEILINGS, AND THEY ARE NOT THE SAME KIND OF THING. The caption one is
+ * computed from the deck's MEASURED p95 cue rate against broadcast practice
+ * rather than from a constant: a deck whose captions already run at 18 cps has
+ * no headroom at all, one written in short lines has plenty. That one stays
+ * pure advice — how readable a caption has to be is the user's call, and they
+ * can only make it if they are told the number. `MAX_PLAYBACK` is the other,
+ * and `playbackRefusal` below turns it into a refusal, because time-stretched
+ * audio is not a matter of taste.
+ *
+ * BOTH CLAUSES, NOT THE FIRST ONE. This used to `return` out of the caption
+ * branch, which meant a dense deck — every deck this tool plans is dense, by
+ * construction — could only ever be told about the ceiling that is advisory,
+ * and never about the one that is enforced. The measured shape: 2.14× on a
+ * 19.6 cps deck printed "readable captions cap out near 0.87×" and suppressed
+ * "past the 1.25× that reads comfortably", so the only line naming an
+ * enforceable limit was the one the user did not get.
  */
 export declare function playbackWarning(factor: number, p95: number): string | undefined;
+/**
+ * Why this target cannot be reached from this deck, when it cannot.
+ *
+ * `MAX_PLAYBACK` IS THE ONE THAT CAN BE ENFORCED. The caption ceiling cannot
+ * be, and the arithmetic is not close: `COMFORTABLE_CPS / DEMO_P95_CUE_CPS` is
+ * 17/18.409 = 0.92 on this project's own anchor deck, so a caption-derived
+ * limit is already breached at 1× and would refuse every speed-up there is —
+ * `--duration` would be dead on arrival. Every deck DeckSmith plans is denser
+ * than 17 cps by construction; see `CUE_OVERHEAD`. So the captions warn and
+ * the playback factor refuses, and `test/duration.test.ts` pins the reason.
+ *
+ * REFUSING IS NOT NEW POLICY, it is the policy the planner already keeps.
+ * `durationPlan` sizes a deck so the residual gap fits inside `MAX_PLAYBACK`,
+ * and `test/duration.test.ts` asserts exactly that at 60s, 120s, 180s and
+ * 240s. A 2.14× request is not a tight fit that slipped — it is 71% past a
+ * bound the rest of the file treats as arithmetic. What was shipping instead
+ * was a video nobody could follow, announced by a mid-render log line that 40
+ * lines of capture progress scrolled away.
+ *
+ * Both remedies are named because the honest one is not the flag: the length
+ * of a deck is decided at plan time by how much it says, so the fix is fewer
+ * words or more seconds, and `--allow-fast-playback` is for the person who has
+ * looked at the alternative and wants the fast video anyway.
+ */
+export declare function playbackRefusal(actualSeconds: number, targetSeconds: number, p95: number): string | undefined;

package/dist/types/plan/prompt.d.ts

@@ -43,5 +43,11 @@ export declare function systemPrompt(prefs: Prefs): string;
  * planner's other entry points keep working unchanged.
  */
 export declare const SYSTEM: string;
-/** The document plus every id the model is allowed to cite, and nothing else. */
+/**
+ * The document plus every id the model is allowed to cite, and nothing else.
+ *
+ * The figure block carries two facts beyond the caption — the section the image
+ * sat under and the prose that refers to it — because a planner that cannot see
+ * the picture has nothing else to decide what the picture is FOR.
+ */
 export declare function renderSource(source: Source): string;

package/dist/types/plan/refs.d.ts

@@ -1,7 +1,39 @@
 import type { Source, Storyboard } from "../types.js";
-export declare function assertRefsResolve(storyboard: Storyboard, source: Source): void;
+/** A slot that asks for a picture nobody has drawn yet: a brief with no `figureId` beside it. */
+export interface PendingIllustration {
+    beatId: string;
+    /** The field the figure id will land in, e.g. `params.left.figureId`. */
+    where: string;
+}
 /**
- * Every `inside` names a part the previous beat actually draws.
+ * Every pending slot, in beat order. A claim-figure without a `figureId` is
+ * pending by construction — the schema insists on one of the two — and a
+ * split-compare side is pending only when it carries a brief, because a side
+ * with neither is a list.
+ */
+export declare function pendingIllustrations(storyboard: Storyboard): PendingIllustration[];
+/**
+ * Whether this deck was illustrated — the fact a pack records as
+ * `images.enabled`, the way `narration.enabled` records whether it was spoken.
+ * A brief with a figure the source really has is the trace `illustrate` leaves;
+ * a brief alone is a picture still owed, which `assertRefsResolve` refuses
+ * before anyone asks this; a figure alone is an ordinary figure.
+ */
+export declare function hasIllustrations(storyboard: Storyboard, source: Source): boolean;
+export interface RefsOptions {
+    /**
+     * What a pending illustration means here. `refuse`, the default, is right for
+     * every reader that needs the figure — `build` would otherwise emit a slide
+     * around a picture that does not exist. Only the planner and the `plan` verb
+     * say `allow`, and only when images are on: a brief is what they were asked
+     * to produce, and `illustrate` is the step that makes it resolve.
+     */
+    pending?: "allow" | "refuse";
+}
+export declare function assertRefsResolve(storyboard: Storyboard, source: Source, opts?: RefsOptions): void;
+/**
+ * Every `inside` names a part the previous beat actually draws — and, where the
+ * plan said which part it meant, the RIGHT one.
  *
  * THE SAME SHAPE AS THE CHECK ABOVE, one level in: a schema proves `inside` has
  * a beat and an element, and cannot prove the element exists. RULE 11 says only a
@@ -9,6 +41,11 @@ export declare function assertRefsResolve(storyboard: Storyboard, source: Source
  * entering, and a real plan asked to fly into `stage1` of an ANNOTATED-FIGURE —
  * which has notes and leader lines and no stages at all.
  *
+ * AND ONE LEVEL IN AGAIN, because existing is not enough. `element` is an index,
+ * so a plan that means the second stage and writes the third names a part that
+ * does exist; `partLabelProblem` compares `inside.label` — what the plan says is
+ * there — against what the archetype reports drawing.
+ *
  * WHY IT MOVED HERE. The emitter already refuses this, so nothing shipped
  * broken. But it refuses at BUILD, which is after `narrate` has spent a minute
  * and a dozen network round trips synthesising speech for a storyboard that was
@@ -17,6 +54,7 @@ export declare function assertRefsResolve(storyboard: Storyboard, source: Source
  *
  * Cheap enough to be exact rather than a table: the previous beat is emitted and
  * `enterableIds` is asked what it drew, so this cannot drift from the emitter the
- * way a hardcoded list of archetype interiors would.
+ * way a hardcoded list of archetype interiors would. The same `Scene` carries
+ * `parts`, so the label comparison rides along for nothing.
  */
 export declare function assertInsideResolves(storyboard: Storyboard, source: Source): void;

package/dist/types/prefs.d.ts

@@ -1,13 +1,15 @@
 import type { z } from "zod";
-import { prefsSchema } from "./types.js";
+import { prefsSchema, type Source } from "./types.js";
 export type Prefs = z.infer<typeof prefsSchema>;
 /**
- * A partial Prefs. `narration` is the one nested object, so it is the one place
- * a patch merges rather than replaces: `--voice` must not wipe a `rate` the
- * config file set.
+ * A partial Prefs. `narration` and `images` are the two nested objects, so they
+ * are the two places a patch merges rather than replaces: `--voice` must not
+ * wipe a `rate` the config file set, and `--image-style` must not wipe its
+ * `provider`.
  */
-export type PrefsPatch = Partial<Omit<Prefs, "narration">> & {
+export type PrefsPatch = Partial<Omit<Prefs, "narration" | "images">> & {
     narration?: Partial<Prefs["narration"]>;
+    images?: Partial<Prefs["images"]>;
 };
 export declare const CONFIG_FILE = "decksmith.config.json";
 /**
@@ -16,8 +18,15 @@ export declare const CONFIG_FILE = "decksmith.config.json";
  * `cwd` is where the search for a config file starts; the search stops at the
  * filesystem root. Returns a fully-populated Prefs — every consumer downstream
  * reads fields, never optionals.
+ *
+ * `source` is the document the deck is being planned FROM, when the caller has
+ * already read one. It is optional because most callers have not: `build`,
+ * `narrate` and `pack` work from a storyboard that was planned long ago, and
+ * `illustrate` never needed a beat count. Only the planning path passes it, and
+ * only so `slidesFor` can size the deck to what the document contains rather
+ * than to a clock — see its header for what changes when it is absent.
  */
-export declare function loadPrefs(overrides?: PrefsPatch, cwd?: string): Promise<Prefs>;
+export declare function loadPrefs(overrides?: PrefsPatch, cwd?: string, source?: Source): Promise<Prefs>;
 /**
  * Turn CLI flags into a patch. Values arrive as strings from commander and are
  * not validated here beyond the numbers: `loadPrefs` runs them through the
@@ -40,4 +49,10 @@ export interface PrefFlags {
     subtitles?: boolean;
     /** `--narration-density`. Spelled apart from `density`, which is a slide's. */
     narrationDensity?: string;
+    /** `--images`. A boolean like `narrate`, so `flags()` in cli.ts reads it beside `--no-subtitles`. */
+    images?: boolean;
+    imageProvider?: string;
+    imageModel?: string;
+    imageStyle?: string;
+    imageMax?: string | number;
 }

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

@@ -0,0 +1,99 @@
+/**
+ * The capture path, as a thing other code can drive.
+ *
+ * "Look at the artifact" is this project's strongest gate — six of its bugs
+ * shipped past green gates and every one was caught by a human looking at a
+ * frame. So the frame a human looks at has to be the frame the renderer would
+ * produce, and `hyperframes snapshot` is NOT that frame: it calls
+ * `player.renderSeek(t)` with no options, so `suppressEvents` is falsy and a
+ * GSAP `onUpdate` FIRES. Invariant 11 says the capture path suppresses events,
+ * so callback-driven motion plays under snapshot and renders frozen. Snapshot is
+ * permissive in exactly the direction that hides the project's most dangerous
+ * failure shape, and it was measured lying about CSS 3D as well — at t=3.9s it
+ * produced a flat, un-rotated frame where the render produced correct
+ * perspective (see `.planning/2026-09-04-css-3d-spike.md`).
+ *
+ * `fidelity` already drove the right path privately, and was measured doing so:
+ * against `experiments/015-decision/out/vocab-18.mp4`, a real render, at all
+ * twelve of its holds, it agreed to a worst case of 0.11 and a mean of 0.03
+ * percentage points — the residual being H.264 quantisation. This module is that
+ * code lifted out from under the ink arithmetic so the gate and a person asking
+ * for a PNG go through the same three calls: inject the pinned runtime,
+ * `renderSeek(t, { suppressEvents: true })`, then `Page.captureScreenshot` with
+ * the renderer's own clip.
+ */
+/**
+ * The browser `render` already uses.
+ *
+ * `@puppeteer/browsers` and `puppeteer-core` are DIRECT dependencies of this
+ * package. They arrive with hyperframes too — a hard dependency of any verb that
+ * opens a browser — but relying on that made module imports resolve through
+ * somebody else's dependency tree, and the day hyperframes swaps its automation
+ * library those verbs break for a reason nothing in this repo mentions. They are
+ * still imported DYNAMICALLY, which is a different concern: a machine that
+ * cannot supply a browser must degrade rather than throw after the capture has
+ * already run.
+ *
+ * `need` completes the error message, because the three callers want different
+ * advice from it — captions can fall back to a sidecar, `frames` cannot. This
+ * was two copies until `frames` became the third caller the older of them said
+ * to promote it on.
+ */
+export declare function chromePath(need?: string): Promise<string>;
+type Browser = Awaited<ReturnType<typeof import("puppeteer-core").launch>>;
+type Page = Awaited<ReturnType<Browser["newPage"]>>;
+/** An open deck, seekable and photographable. Close it. */
+export interface DeckPage {
+    /** The canvas the deck declares, which is also the screenshot's clip. */
+    width: number;
+    height: number;
+    /** Commit the frame at an absolute time, events suppressed. */
+    seek(t: number): Promise<void>;
+    /** PNG bytes of the frame currently committed. */
+    shoot(): Promise<Buffer>;
+    /** For callers that need to read the DOM at a stop, as `fidelity` does. */
+    page: Page;
+    close(): Promise<void>;
+}
+export interface OpenOptions {
+    timeoutMs?: number;
+}
+/**
+ * Open `dir`'s deck in the renderer's own browser, ready to seek.
+ *
+ * Throws for every environmental reason — no Chrome, no `index.html`, no canvas
+ * size. Callers that must not fail a build over the environment (the `fidelity`
+ * gate) catch it; callers a person invoked directly (`frames`) let it surface,
+ * because a person who asked for a PNG and got nothing needs to hear why.
+ */
+export declare function openDeck(dir: string, opts?: OpenOptions): Promise<DeckPage>;
+/** One written frame. */
+export interface CapturedFrame {
+    t: number;
+    path: string;
+    bytes: number;
+}
+/**
+ * What one frame is called.
+ *
+ * The index leads, zero-padded to the width of the largest, because a directory
+ * listing is how these actually get looked at and lexical order is what a file
+ * browser gives you: `t10.000s` sorts before `t3.900s`, so the reader opens the
+ * wrong frame and believes it. Padding the INDEX rather than the time keeps the
+ * two orders — asked-for and on-disk — identical without deciding how many
+ * digits a deck's duration might need.
+ *
+ * The time is still in the name, to 3 decimals, because that is the thing a
+ * reader is checking against and invariant 10 says 3 decimals is what the
+ * renderer rounds to. A frame whose filename disagreed with the timeline would
+ * be worse than one with no time in it at all.
+ */
+export declare function frameName(index: number, t: number, total: number): string;
+/**
+ * Write a PNG per requested time into `outDir`.
+ *
+ * Times are rounded to 3 decimals to match invariant 10, so a filename names
+ * exactly the instant the renderer would.
+ */
+export declare function captureFrames(dir: string, times: readonly number[], outDir: string, opts?: OpenOptions): Promise<CapturedFrame[]>;
+export {};

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

@@ -103,8 +103,20 @@ export interface RenderOptions {
      * length is decided at plan time by how much it says, and this closes whatever
      * gap survived that. A video already inside the target is left alone rather
      * than padded — dead air is worse than eight seconds short.
+     *
+     * A gap wider than `MAX_PLAYBACK` is refused, not closed; see the check after
+     * `readTiming` and `playbackRefusal`.
      */
     targetSeconds?: number;
+    /**
+     * Speed past `MAX_PLAYBACK` anyway.
+     *
+     * For the person who has read the refusal, cannot re-plan, and wants the fast
+     * video regardless. It does not silence anything: both clauses of
+     * `playbackWarning` still print, and the summary still carries the factor and
+     * the caption rate it bought.
+     */
+    allowFastPlayback?: boolean;
     /** Leave the per-piece intermediates on disk. */
     keep?: boolean;
     /** Progress, one line at a time. */
@@ -119,5 +131,11 @@ export interface RenderResult {
     burned: boolean;
     /** What `targetSeconds` cost, if anything. 1 means the file was not respeeded. */
     playback: number;
+    /**
+     * p95 characters per second of the subtitles AS SHIPPED — measured off the
+     * cues that were written, so at `playback > 1` it is already the sped-up rate
+     * a viewer actually reads at rather than the deck's rate at rest.
+     */
+    captionCps: number;
 }
 export declare function render(opts: RenderOptions): Promise<RenderResult>;

package/dist/types/server/options.d.ts

@@ -61,6 +61,13 @@ export interface JobOptions {
     prefs: Prefs;
     narrate: boolean;
     video: boolean;
+    /**
+     * Run the `illustrate` stage between `plan` and `build`. The same bit lands in
+     * `prefs.images.enabled`, which is what lets the planner write a brief; this
+     * copy is what `stagesFor` reads, the way `narrate` is read beside
+     * `prefs.narration.enabled`.
+     */
+    images: boolean;
     /**
      * Whether the REQUEST said so, as opposed to the schema defaulting.
      *

package/dist/types/server/pipeline.d.ts

@@ -1,3 +1,4 @@
+import { type ImageProvider, type Runner } from "../index.js";
 import type { JobOptions } from "./options.js";
 import type { JobHandle, JobResult, Stage } from "./queue.js";
 import { type Upload } from "./upload.js";
@@ -15,6 +16,19 @@ export interface PipelineInput {
      * owner's own box, own papers), it is fetched with a count and a timeout.
      */
     fetchRemoteFigures: boolean;
+    /**
+     * The rungs `illustrate` draws through. A test injects the tool's own SVG and
+     * nothing else; absent, the stage resolves its providers from the environment
+     * at call time, like `narrate` does — so there is no server option to plumb
+     * and nothing to configure but the env vars.
+     */
+    imageChain?: ImageProvider[];
+    /**
+     * The planner's `Runner`, handed straight to `codexPlanner`. The seam
+     * test/plan.test.ts already drives the parse path through; here it is what
+     * lets a test carry a job PAST `plan` — into `illustrate` — without a Codex.
+     */
+    run?: Runner;
 }
 /** Which rows the step list should have, decided before anything runs. */
 export declare function stagesFor(options: JobOptions): Stage[];

package/dist/types/server/queue.d.ts

@@ -15,7 +15,7 @@
  */
 import { type JobError } from "./errors.js";
 export type JobState = "queued" | "running" | "done" | "error";
-export type Stage = "ingest" | "plan" | "narrate" | "build" | "render";
+export type Stage = "ingest" | "plan" | "illustrate" | "narrate" | "build" | "render";
 export type StepState = "pending" | "running" | "done" | "skipped" | "error";
 export interface StepView {
     name: Stage;