@jokerized/decksmith 0.1.3 → 0.2.0

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;