@jokerized/decksmith 0.9.4 → 0.9.6

package/dist/types/literal/kinds/recap.d.ts

@@ -0,0 +1,16 @@
+/**
+ * recap — the earlier scenes' own computed layers, in order: every one as a tile,
+ * the one being spoken also large, then the result the source reports.
+ */
+import type { Literal } from "../../types.js";
+import { type KindImpl } from "../kind.js";
+/**
+ * Whether a scene leaves a picture a recap can bring back (`files.thumb`): an
+ * operate on a picture, an evolve that streams tiles or noises a picture, a
+ * region, a flow whose stage shows an earlier layer, a prior-work with a
+ * `from` lane. A word form, a table and a scene on vectors leave none. The
+ * plan check holds a recap to this (src/plan/coverage.ts), so a plan the build
+ * would refuse goes back to the planner.
+ */
+export declare function leavesPicture(lit: Literal): boolean;
+export declare const recapKind: KindImpl;

package/dist/types/literal/kinds/region.d.ts

@@ -0,0 +1,56 @@
+/**
+ * region — the things in a picture the source says matter, picked out (the
+ * approved look, .planning/designs/2026-10-12-verb-looks/5-region.png): the
+ * picture large on the left, a numbered box on each thing with its number
+ * outside the box, the numbered list of what each means on the right, then the
+ * `outcome` the source draws from them, under a rule. The picture's legend
+ * sits under it. Each thing is revealed with its line; the outcome last.
+ *
+ * The boxes are never the planner's guess: `plan` finds each `thing` in the
+ * panel the scene shows (src/plan/locate.ts) and writes its box, as fractions of
+ * that panel, into the storyboard. The panel is cut as `findPanels` cuts it, at
+ * plan and at build alike. The picture is zoomed onto its marks only as far as
+ * its own pixels allow (`MAX_UPSCALE`) and never past `CONTEXT` of the panel:
+ * a stop sign alone says nothing.
+ */
+import type { KindImpl } from "../kind.js";
+import { type Rgb } from "../kit.js";
+import type { MechanismResult } from "./common.js";
+import { type VerbCtx } from "./stage.js";
+type Ctx = VerbCtx<"region">;
+/** The longest side a figure is read at: its own pixels, up to this. */
+export declare const FIGURE_SIDE = 3200;
+/** A figure at its own pixels (at most `FIGURE_SIDE` a side). */
+export declare function readFigure(image: string): Promise<Rgb>;
+/** How many panels the build will cut a figure file into (`findPanels`). */
+export declare function figurePanels(image: string): Promise<number>;
+/** The picture a marked scene shows: the figure's `panel` (1-based), or all of it. */
+export declare function panelOf(fig: Rgb, panel: number | undefined): Rgb;
+/** The most a figure is magnified over its own pixels: past it a crop shows its blur. */
+export declare const MAX_UPSCALE = 2;
+export declare function region(c: Ctx): MechanismResult;
+/** A box in figure pixels. */
+export interface PanelBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * A figure's panels, from its pixels: recursive XY-cut along blank gutters.
+ *
+ * The ground is the colour of the figure's border; a pixel is ink when it
+ * differs from it by more than 0.1 on any channel. A box is trimmed to its ink,
+ * then split at the middle of its widest blank run of rows or columns, if that
+ * run is at least 1.5% of the figure's side and leaves two parts big enough to
+ * be panels (each side 12% of the figure's shorter side, each 3% of its area);
+ * failing that, at a gutter that splits off a part too small to be a panel —
+ * before panels side by side, or a filled title band off one — which is
+ * dropped. What cannot be split is a panel. Read in rows (top to bottom, a row
+ * being panels whose tops are within 10% of the figure's height), left to right in
+ * each. Deterministic: the same figure gives the same panels.
+ */
+export declare function findPanels(img: Rgb): PanelBox[];
+/** region as the build's kind: it reads its figure at the figure's own pixels. */
+export declare const regionKind: KindImpl;
+export {};

package/dist/types/literal/kinds/stage.d.ts

@@ -0,0 +1,108 @@
+import type { Fragment } from "../../bespoke/contract.js";
+import type { Theme } from "../../emit/kit.js";
+import type { Literal, LiteralKind } from "../../types.js";
+import { type KindImpl, type KindSpec } from "../kind.js";
+import { type Cue, type Layers } from "../kit.js";
+import type { Tensor } from "../ops.js";
+import { type Frame, type Measure, type MechanismResult, type Prim, type Raster, type Region, type Rgb } from "./common.js";
+/** What an earlier scene left that a later one may reuse: its layers and its computed arrays. */
+export interface Earlier {
+    kind: string;
+    layers: Layers;
+    labels: Record<string, string>;
+}
+/** What a verb's run is given. */
+export interface VerbCtx<K extends LiteralKind> {
+    lit: Extract<Literal, {
+        kind: K;
+    }>;
+    labels: Readonly<Record<string, string>>;
+    region: Region;
+    theme: Theme;
+    measure: Measure;
+    /** Plan time: the material is a placeholder; check and lay out, as the build will. */
+    dry: boolean;
+    /** The picture, when the verb reads one (a placeholder at plan time). */
+    image?: Rgb;
+    earlier: ReadonlyMap<string, Earlier>;
+    /** Figure id → absolute file, for a stage showing the source's own figure. */
+    assets: Readonly<Record<string, string>>;
+    /** The beat's headline: an item it names is the scene's subject (src/literal/kind.ts `subjectOf`). */
+    headline?: string;
+}
+export type VerbRun<K extends LiteralKind> = (c: VerbCtx<K>) => MechanismResult;
+/**
+ * A verb laid out inside the room its camera push takes, for a diagram whose
+ * words reach the region's edges (a plot, a chain of cards). The push scales
+ * the camera's material about its middle by `PUSH`, so it grows (PUSH-1)/2 of
+ * a side each way: laid out that much in, and with the clip grown by the same
+ * (`Frame.pad`), nothing is cut while it leans in. Measured on r1: a plot's
+ * "0.8" printed as ").8" and the outer cards of a chain lost their first and
+ * last glyphs, while the push ran.
+ */
+export declare function withPushRoom<K extends LiteralKind>(run: VerbRun<K>): VerbRun<K>;
+/** Text lines as primitives, top-down from y. */
+export declare function textLines(lines: readonly string[], x: number, y: number, size: number, role: Extract<Prim, {
+    p: "text";
+}>["role"], extra?: Partial<Extract<Prim, {
+    p: "text";
+}>>, anchor?: "start" | "middle" | "end"): Prim[];
+/** The band under the scene for its example tag and caption: its height, 0 when neither is given. */
+export declare function bandHeight(labels: Readonly<Record<string, string>>, region: Region, measure: Measure): number;
+/** Run a verb with its band reserved; the band is added to every frame. */
+export declare function runVerb<K extends LiteralKind>(run: VerbRun<K>, c: VerbCtx<K>): MechanismResult;
+/** A synthetic picture for plan-time checks: deterministic, with edges and texture. */
+export declare function placeholderPicture(w?: number, h?: number): Rgb;
+/** The picture at its own aspect, at most `maxSide` on its longer side. */
+export declare function readPicture(image: string, maxSide: number): Promise<Rgb>;
+/** The display scale of one-channel arrays drawn side by side: one scale, so a weaker map looks weaker. */
+export declare function sharedScale(ts: readonly Tensor[]): number;
+/** An array as a raster to draw: RGB as itself, one channel on the theme's accent (signed: grey around mid). */
+export declare function rasterOf(t: Tensor, scaleTo?: number): Raster;
+/** Write a result's rasters under `dir`; the layers carry the frames and how each raster is painted. */
+export declare function writeLayers(r: MechanismResult, beatId: string, dir: string): Promise<Layers>;
+/** Copy the source's own figures a result references (`fig:<id>`) beside the layers. */
+export declare function copyFigures(r: MechanismResult, assets: Readonly<Record<string, string>>, beatId: string, dir: string, files: Record<string, string>): Promise<void>;
+/** The axis-aligned box a primitive covers. */
+export declare function boxOf(p: Prim): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Where the camera tours a finished frame: the centre of each step's camera
+ * material (its `cam` primitives revealed on that step), the last step first.
+ */
+export declare function tourOf(frame: Frame, steps: number): Array<{
+    x: number;
+    y: number;
+}>;
+/** The opacity a `preview` frame's parts stand at until they are spoken. */
+export declare const PREVIEW = 0.3;
+/** The most a sentence's camera push waits for its reveals, seconds after the sentence starts. */
+export declare const PUSH_LEAD = 1.2;
+/** Seconds before a scene's end its camera is back at rest (start of the return). */
+export declare const FINAL_REST = 2.2;
+/** How far the camera pushes in on a frame's material once its reveals are out. */
+export declare const PUSH = 1.07;
+/** The fragment of staged frames on the narration's sentences. */
+export declare function stagedFragment(kind: LiteralKind, L: Layers, region: Region, cues: readonly Cue[], spec: KindSpec, theme: Theme, href: (file: string) => string): Fragment;
+/**
+ * The share of the region a frame's material covers: its pictures, filled
+ * shapes and plotted lines, on an 8px grid. Text and outlines do not count. Pure,
+ * read off the primitives that ship.
+ */
+export declare function frameFill(frame: Frame, region: Region): number;
+/** How large a verb reads its picture. */
+export interface VerbOpts {
+    /** Longest side the picture is read at; 0: the verb reads no picture. */
+    pictureSide: number;
+    /** The beat whose picture the verb reads (absent: none). */
+    pictureOf?: (lit: Literal) => string | undefined;
+}
+/** A verb drawn on the stage, as the build's `KindImpl`. */
+export declare function verbKind<K extends LiteralKind>(kind: K, run: VerbRun<K>, opts: VerbOpts): KindImpl;
+/** Why a verb cannot be drawn, at plan time: its run on placeholder material. Empty when it can. */
+export declare function verbProblems<K extends LiteralKind>(kind: K, run: VerbRun<K>, lit: Literal, region: Region, theme: Theme): string[];
+export type { Frame, MechanismResult, Prim, Raster, Region };

package/dist/types/literal/kinds/svg.d.ts

@@ -0,0 +1,65 @@
+/**
+ * One frame of a mechanism kind as SVG: what the framework draws, and what the
+ * preview strips and the judge frames are rasterised from. Pure: rasters are
+ * referenced by `href(layer)`, slot texts come from `text(slot, vars)`, and
+ * every colour is a style-pack token (fg, muted, dim, rule, panel, accent,
+ * tones): a heat layer is a white alpha mask the theme colours here, so one
+ * computed file serves a dark pack and a light one. The ground (`bg`) is the
+ * shell's: it is painted only in a preview (`ground: true`), and read only to
+ * judge contrast against.
+ *
+ * Also the contrast arithmetic (WCAG 2 relative luminance) the tests hold the
+ * frames to, and the backdrop lookup a text with role "auto" is resolved by.
+ */
+import type { Theme } from "../../emit/kit.js";
+import type { DataRgb, Prim, Role } from "./common.js";
+/** An sRGB colour, 0..255 per channel. */
+export type Rgb8 = [number, number, number];
+export declare function hex(c: string): Rgb8;
+export declare function roleRgb(theme: Theme, role: Role): Rgb8;
+/** The heat ramp: the panel colour at 0, the accent at 1. */
+export declare function heatRgb(theme: Theme, t: number): Rgb8;
+/** Tone weights (a, b, c, d) mixed over the panel: hue from their proportions, strength from their sum. */
+export declare function mixRgb(theme: Theme, w: readonly number[]): Rgb8;
+/** A filled shape's fill, or undefined when it has none. */
+export declare function fillRgb(theme: Theme, p: {
+    fill?: Role;
+    heat?: number;
+    mix?: number[];
+    rgb?: DataRgb;
+}): Rgb8 | undefined;
+/** WCAG 2 contrast ratio, 1..21. */
+export declare function contrastRatio(a: Rgb8, b: Rgb8): number;
+/** Where a primitive sits, for finding what is under it. */
+export declare function anchorOf(p: Prim): [number, number];
+/**
+ * The colour under prims[index] at its anchor: the last opaque filled rect or
+ * circle drawn before it that contains the point, else the ground. Undefined
+ * when a picture is under it (its colour is the data's, not the theme's).
+ * `containersOnly`: look through marks (another series' head, a start dot) to
+ * the panel or ground they sit on — how a mark is judged.
+ */
+export declare function backdropOf(prims: readonly Prim[], index: number, theme: Theme, containersOnly?: boolean): Rgb8 | undefined;
+/** A text's colour: its role's, or for "auto" the ink or the panel colour, whichever reads better on its backdrop. */
+export declare function textRgb(prims: readonly Prim[], index: number, theme: Theme): Rgb8;
+/**
+ * An "auto" text's halo: when neither ink nor panel reaches 4.5:1 on a
+ * mid-tone fill (a bright accent at half strength), the text gets a 6px
+ * outline in the other colour, and that outline is what it is read against.
+ */
+export declare function textHalo(prims: readonly Prim[], index: number, theme: Theme): Rgb8 | undefined;
+/** How a raster layer is drawn: a picture as itself, a heat mask in a theme colour at an opacity. */
+export type LayerPaint = {
+    mask: Role;
+    alpha: number;
+} | undefined;
+export interface Draw {
+    theme: Theme;
+    href: (layer: string) => string;
+    text: (slot: string, vars: Readonly<Record<string, string | number>>) => string;
+    paint: (layer: string) => LayerPaint;
+    /** Prefix of every id this frame defines (masks), so two frames in one page never collide. */
+    ids: string;
+}
+/** One primitive as SVG; `prims` and `index` place it among what is drawn under it. */
+export declare function primSvg(prims: readonly Prim[], index: number, d: Draw): string;

package/dist/types/literal/kinds/table.d.ts

@@ -0,0 +1,19 @@
+/**
+ * table — numbers and claims the source reports, cited, rows lit in spoken
+ * order, winning or missing cells marked. A row the headline names (by its
+ * first cell) is the subject: lit, with its name in the accent, from the first
+ * frame to the last — r3 dimmed the method's own row at both holds.
+ */
+import { type KindImpl } from "../kind.js";
+/**
+ * Which rows light on which step: spoken order, spread over the cues when there
+ * are more rows than cues — the LATER steps take the extra rows, since a
+ * narration names its point first and then elaborates.
+ */
+export declare function rowSteps(highlight: readonly number[], cues: number): number[][];
+/**
+ * Column widths that fit `W`: water-filling from the narrowest column, so a
+ * short column keeps its natural width and only the widest ones wrap.
+ */
+export declare function fitColumns(natural: readonly number[], W: number): number[];
+export declare const tableKind: KindImpl;

package/dist/types/literal/kinds/tex.d.ts

@@ -0,0 +1,6 @@
+import type { Measure } from "./common.js";
+/** The box of `tex` set in display style at `px`, in px: an estimate, with a margin. */
+export declare function texBox(tex: string, px: number, measure: Measure): {
+    w: number;
+    h: number;
+};

package/dist/types/literal/kinds-shared.d.ts

@@ -0,0 +1,15 @@
+/** Helpers more than one kind shares: a picture's own size, tile ratios. */
+export declare function nativeSize(image: string): Promise<{
+    w: number;
+    h: number;
+}>;
+/** How many copies of the smallest value tile the largest (0: too close to be worth it). */
+export declare const tiles: (vals: readonly number[]) => number;
+/**
+ * The ratio line a tiled group prints ("35 ÷ 20 = 1.75"), or undefined when the
+ * group does not tile. One function, so the truth gate checks the very number
+ * the scene draws (src/plan/coverage.ts `literalTexts`).
+ */
+export declare function tileRatio(items: ReadonlyArray<{
+    value: string;
+}>): string | undefined;

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

@@ -0,0 +1,86 @@
+import type { Theme } from "../emit/kit.js";
+import { type LITERAL_KIND_NAMES } from "../types.js";
+type LiteralKindName = (typeof LITERAL_KIND_NAMES)[number];
+/** An RGB picture, 0..1 per channel, row-major. */
+export interface Rgb {
+    w: number;
+    h: number;
+    d: Float32Array;
+}
+/** Decode any picture ffmpeg reads, resampled (area) to w×h. */
+export declare function readRgb(file: string, w: number, h: number): Promise<Rgb>;
+/** Write RGBA bytes as a PNG (lossless) or a JPEG (`.jpg`, photographs only). */
+export declare function writeRaster(out: string, w: number, h: number, rgba: Uint8Array): Promise<void>;
+export declare function toRgba(img: Rgb): Uint8Array;
+/** A grey map (0..1) as RGBA: `color` at `alpha` = value, or grey levels when no colour. */
+export declare function mapRgba(v: Float32Array, color?: [number, number, number]): Uint8Array;
+export declare function clamp255(x: number): number;
+export interface Layers {
+    /** File names under `LITERAL_DIR`. */
+    files: Record<string, string>;
+    /** Numbers the fragment draws (profiles, grids, traces). */
+    data: Record<string, unknown>;
+    /** The arrays a verb computed, in memory, for a later verb to stream (`evolve` from). */
+    material?: Material;
+}
+/** What a verb computed that a later one may take as input. */
+export interface Material {
+    /** The last output. */
+    final?: import("./ops.js").Tensor;
+    /** Pieces of it (crops, tiles), in order. */
+    tiles?: import("./ops.js").Tensor[];
+}
+export declare const r3: (n: number) => number;
+export declare const round3: (n: number) => number;
+export declare const px: (n: number) => string;
+/** Escape a label for markup. */
+export declare const esc: (s: string) => string;
+/** The scene's tween lines, every one `fromTo` (invariant 2), every selector `#SCENEID-…` (invariant 3). */
+export declare class Tl {
+    lines: string[];
+    private seen;
+    /**
+     * An element's FIRST tween renders its "from" state at once (GSAP's default),
+     * so whatever enters later is hidden from the scene's first frame; every
+     * later tween of it waits for its own start (`immediateRender: false`), so it
+     * cannot overwrite the earlier one's state when the timeline is built.
+     */
+    fromTo(id: string, from: Record<string, unknown>, to: Record<string, unknown>, at: number): void;
+    /** Fade in (opacity 0→1) at `at`. */
+    show(id: string, at: number, dur?: number, extra?: {
+        from?: Record<string, unknown>;
+        to?: Record<string, unknown>;
+    }): void;
+    hide(id: string, at: number, dur?: number): void;
+    get script(): string;
+}
+export interface Cue {
+    t0: number;
+    t1: number;
+    /** This sentence opens a narration stop: a hold sits at its start (src/bespoke/scene.ts `bespokeHolds`). */
+    stop?: boolean;
+}
+/**
+ * The stretches of [from, to] in which no tween of a scene's script runs —
+ * what a viewer sees as the picture standing still. Read off the emitted
+ * script (`tl.fromTo(..., {...duration...}, at)`), so it measures what ships.
+ * A tween with no duration runs GSAP's default 0.5s. Pure; the tests hold
+ * every kind to a ceiling with it (r1 of an early literal deck had 13 stretches
+ * of 6–9s where nothing moved).
+ */
+export declare function stillSpans(script: string, from: number, to: number): Array<[number, number]>;
+/**
+ * A scene's words by slot (src/types.ts `LITERAL_KIND_DOCS`). Throws on a slot the
+ * kind does not declare — a fragment reading an undocumented slot is a bug,
+ * since the planner was never told to fill it — and on a required one the
+ * plan left out: no kind has a default, in any language or for any paper.
+ * `{name}` in the text is replaced by the computed `vars[name]`.
+ */
+export declare function slotText(kind: LiteralKindName, labels: Readonly<Record<string, string>>, slot: string, vars?: Readonly<Record<string, string | number>>): string;
+export declare const LABEL: 44;
+export declare const SMALL: 40;
+/** A label as positioned HTML. Never below 40px (invariant 5). */
+export declare function label(id: string, text: string, x: number, y: number, size: number, color: string, extra?: string): string;
+export declare const ON_PHOTO = "color:#fff;text-shadow:0 2px 10px rgba(0,0,0,.75),0 0 2px rgba(0,0,0,.9);font-weight:600";
+export declare function baseCss(theme: Theme): string;
+export {};

package/dist/types/literal/ops.d.ts

@@ -0,0 +1,56 @@
+/**
+ * THE OP LIBRARY the `operate` and `evolve` verbs compose: a small set of
+ * general operations on arrays, pure and deterministic. What each op is, its
+ * variants and the words that ground them are one table, `LITERAL_OPS` in
+ * src/types.ts, read by the planner's prompt and the truth gate; this file is
+ * only the arithmetic, so the three cannot drift.
+ *
+ * An array is a `Tensor`: h rows × w columns × c channels, row-major with the
+ * channels interleaved. A picture is c = 3, a map c = 1, a vector h = 1, a
+ * matrix c = 1. Every op takes the list of earlier outputs (the input first)
+ * and returns one new array; none of them knows what a paper is. Kernels are
+ * applied as correlation (as image libraries do), edges replicated.
+ *
+ * Nothing here is learned and nothing has a default a paper would have to
+ * state: every parameter comes from the plan, grounded by the gate.
+ */
+import type { LiteralOpName } from "../types.js";
+export interface Tensor {
+    h: number;
+    w: number;
+    c: number;
+    d: Float32Array;
+}
+export declare const tensor: (h: number, w: number, c: number, d?: ArrayLike<number>) => Tensor;
+/** A matrix (rows of equal length) as a tensor. */
+export declare function fromRows(rows: readonly (readonly number[])[]): Tensor;
+export declare const fromVector: (v: readonly number[]) => Tensor;
+/** One step of a chain, its parameters already read as numbers. */
+export interface OpStep {
+    op: LiteralOpName;
+    how?: string;
+    stat?: "mean" | "var" | "std";
+    over?: "all" | "channel" | "row";
+    params: Readonly<Record<string, number>>;
+    weights?: readonly (readonly number[])[];
+    /** Indexes into the list of outputs (0 = the input). */
+    of?: readonly number[];
+    expr?: string;
+}
+/** The kernels a NAME fixes: their numbers are the name (definitional). */
+export declare const NAMED_KERNELS: Readonly<Record<string, readonly (readonly number[])[]>>;
+export declare function statOf(v: ArrayLike<number>, stat: "mean" | "var" | "std" | "min" | "max" | "sum"): number;
+/** The kernel a conv step applies. */
+export declare function kernelOf(step: OpStep, oneD: boolean): number[][];
+/** θ per group: the stated one, or scale × the group's statistic. */
+export declare function thresholds(t: Tensor, step: OpStep): number[];
+/** One op on the list of outputs so far (the input first); returns its output. */
+export declare function runOp(step: OpStep, list: readonly Tensor[]): Tensor;
+/** Every output of a chain, after the inputs: `[...inputs, out1, …, outN]`. */
+export declare function runChain(inputs: readonly Tensor[], chain: readonly OpStep[]): Tensor[];
+/** Deterministic standard normals (mulberry32 + Box–Muller). */
+export declare function seededNormals(seed: number): () => number;
+/** An EXAMPLE degradation of an input: never the paper's, always tagged as an example. */
+export declare function degrade(t: Tensor, how: "contrast" | "noise" | "blur", amount: number): Tensor;
+/** ᾱ_t for t = 1..T: linear β (Ho et al.) or the cosine ᾱ (Nichol & Dhariwal). */
+export declare function alphaBars(schedule: "linear" | "cosine", T: number, betaStart?: number, betaEnd?: number): Float64Array;

package/dist/types/literal/registry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * EVERY KIND THE BUILD DRAWS, by name: one entry per name in src/types.ts
+ * `LITERAL_KIND_NAMES`, a `Record` so a name added there does not compile
+ * until it is drawn here, and nothing is registered at run time.
+ *
+ * - THE VERBS compose general operations on the source's own numbers:
+ *   operate (an op chain on a picture, vectors or a matrix), evolve (a state
+ *   under a stated rule), flow (stages), place (items on
+ *   axes, and the word forms: margins, lengths, combos, sets) and region
+ *   (the things in a picture, marked). Most are drawn on the stage
+ *   (./kinds/stage.ts).
+ * - THE CROSS-CUTTING KINDS: recap (earlier scenes' own layers), prior-work
+ *   (families by what an earlier scene computed or by their numbers) and
+ *   table (the last resort).
+ */
+import type { LiteralKind } from "../types.js";
+import type { KindImpl } from "./kind.js";
+/** How large a verb reads its picture, for display (region reads its figure at its own pixels). */
+export declare const PICTURE_SIDE = 768;
+export declare const KINDS: Readonly<Record<LiteralKind, KindImpl>>;

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

@@ -1,10 +1,15 @@
 import { type Prefs } from "../prefs.js";
 import { type Source, type Storyboard } from "../types.js";
-/** The schema for one run. `role` is present only when the paper arc was asked for. */
-export declare function schemaFor(prefs: Pick<Prefs, "genre" | "bespoke" | "design">): unknown;
 /**
- * The default-preferences schema, unchanged and still exported: `general` hides
- * `role`, so these bytes are what they have always been.
+ * The schema for one run. `role` is present only when the paper arc was asked
+ * for; `part` only when `source` has parts to cover.
+ */
+export declare function schemaFor(prefs: Pick<Prefs, "genre" | "bespoke" | "design"> & {
+    images?: Prefs["images"];
+}, source?: Source): unknown;
+/**
+ * The default-preferences schema, still exported: `general` hides `role`, and
+ * images default off, so it hides the picture briefs too (0.9.5).
  */
 export declare const SCHEMA: unknown;
 export interface CodexOptions {
@@ -18,8 +23,16 @@ export interface CodexOptions {
     prefs?: Prefs;
     /** Swappable so a test can drive the real parse path without spawning anything. */
     run?: Runner;
-    /** Told what the first plan broke, before the one repair round is asked for. */
+    /** Told what a plan broke, before each repair round (at most `REPAIRS`) is asked for. */
     onRepair?: (broken: readonly string[]) => void;
+    /** Told each deck answer's beat count and the beats that carry a literal scene. */
+    onAnswer?: (beats: number, scenes: readonly string[]) => void;
+    /** Told a scene is redrawn on its own, after the deck, and why. */
+    onScene?: (beat: string, broken: readonly string[]) => void;
+    /** Told the beats whose scene was dropped (still broken after its own repairs, or broken only by a symbolic quantity), and why. */
+    onDropScenes?: (beats: readonly string[], why: readonly string[]) => void;
+    /** Each source figure's panel count as the build will cut it, when the caller read them. */
+    panels?: Readonly<Record<string, number>>;
 }
 export interface RunnerArgs {
     prompt: string;
@@ -47,6 +60,16 @@ export interface RunnerArgs {
 /** What the planner needs from the outside world: a prompt in, a final message out. */
 export type Runner = (args: RunnerArgs) => Promise<void>;
 export declare function codexPlanner(source: Source, opts?: CodexOptions): Promise<Storyboard>;
+/**
+ * A plan Codex answered that this source cannot build — out of the schema's
+ * bounds, a picture brief with images off, an id the source lacks — with what
+ * is wrong and the JSON it came as, for the repair rounds.
+ */
+export declare class PlanRejected extends Error {
+    readonly problems: string[];
+    readonly plan: unknown;
+    constructor(message: string, problems: string[], plan: unknown);
+}
 /**
  * The `codex` command line for a run, and the environment it needs.
  *