@jokerized/decksmith 0.9.0 → 0.9.1

package/dist/types/bespoke/art.d.ts

@@ -0,0 +1,173 @@
+import type { Theme } from "../emit/kit.js";
+import type { Runner } from "../plan/codex.js";
+import type { UnitBox } from "./inspect.js";
+/** Bump with any change to the art prompt: it is part of every art key, and so of every scene key. */
+export declare const ART_VERSION = "art-2";
+/** A picture bigger than this is not one the tool made for a slide. */
+export declare const MAX_ART_BYTES: number;
+/** Effort for the art call: MEASURED 2026-10-09, low drew the pictures above in 36-49s. */
+export declare const ART_EFFORT = "low";
+/** One beat's illustration, as a deck uses it. */
+export interface ArtRef {
+    /** Content key: the cache name and the deck's file name. */
+    key: string;
+    /** The file name under the deck's `assets/bespoke/` (WebP when it could be encoded). */
+    name: string;
+    /** Where the deck's bytes are now (the cache), for `build` to copy. */
+    file: string;
+    width: number;
+    height: number;
+    /** What the picture shows, left to right, in the illustrator's words. */
+    depicts: string;
+    /** The PNG as drawn: what the scene call is shown. Absent: `file` is that PNG. */
+    png?: string;
+    /** The PNG with its subjects boxed and numbered, for the draft call (src/bespoke/sheet.ts). */
+    boxed?: string;
+    /** The subjects, left to right, as shares of the picture (src/bespoke/inspect.ts). */
+    subjects?: UnitBox[];
+    /** What the inspection measured, for the report. */
+    check?: ArtCheck;
+    /** The deck's copy carries its own feathered edges (alpha): the shell adds no CSS mask. */
+    feathered?: boolean;
+}
+/** What the inspection said about the picture kept, and how many draws it took. */
+export interface ArtCheck {
+    /** `flatness().score`; flat at `FLAT_MIN` or more. */
+    flat: number;
+    flatOk: boolean;
+    /** Writing found in it, or null when nothing could read it. */
+    text: string[] | null;
+    /** Draws made for this beat (2 when the first was rejected). */
+    attempts: number;
+    /** Why a draw was rejected, per rejected draw. */
+    rejected: string[];
+}
+/** What the illustrator is told about one beat. Paper-derived fields are untrusted. */
+export interface ArtBrief {
+    lang: string;
+    headline: string;
+    intent: string;
+    claim?: string;
+    narration?: string;
+    /** A short excerpt of the paper; untrusted. */
+    context: string;
+    theme: Theme;
+    pack: string;
+}
+/** The illustrator's reply. `--output-schema` holds it to this. */
+export declare const ART_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["ok", "file", "reason", "depicts"];
+    readonly properties: {
+        readonly ok: {
+            readonly type: "boolean";
+        };
+        readonly file: {
+            readonly anyOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "null";
+            }];
+        };
+        readonly reason: {
+            readonly anyOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "null";
+            }];
+        };
+        readonly depicts: {
+            readonly type: "string";
+        };
+    };
+};
+/** The art key: everything the picture is drawn from. */
+export declare function artKey(brief: ArtBrief, model: string): string;
+/**
+ * The deck's picture style, word for word the same in every art call of every
+ * deck, so the pictures of one deck look like one illustrator's. ROUND 4: round
+ * 3 asked for "flat vector … soft gradients and gentle shading, a little depth"
+ * and got soft 3D toy renders — the shading words won. This names the look by
+ * what it is made of (flat fills, hard edges) and forbids, by name, every way
+ * a picture turns into a render.
+ */
+export declare const ART_STYLE = "STYLE \u2014 FLAT 2D VECTOR, strictly. The look of a modern explainer channel's flat illustration (Kurzgesagt-like flat design) or a vector editorial infographic: every shape is ONE solid, uniform colour with crisp hard edges, like cut paper; simple geometric forms with rounded corners; a darker flat shape of the same hue may mark a side or a fold (a hard-edged shape, never a blend). Characters and objects are simplified and iconic, drawn front-on or in clean side view. FORBIDDEN, every one: gradients of any kind, airbrushed or soft shading, ambient occlusion, glossy or specular highlights, reflections, rim light, soft or drop shadows (not even under the subjects), glow, blur, depth of field, texture, grain, noise, 3D rendering, clay, plastic, vinyl-toy or Pixar-style characters, isometric 3D, photorealism, outlines thinner than the shapes they bound. If in doubt, flatter.";
+export declare function artPrompt(b: ArtBrief, retry?: string): string;
+/** Width and height from a PNG's IHDR, or undefined when the bytes are not a PNG. */
+export declare function pngSize(bytes: Buffer): {
+    width: number;
+    height: number;
+} | undefined;
+/** `$CODEX_HOME`, else `~/.codex` — where the image tool saves what it draws. */
+export declare function codexHome(env?: NodeJS.ProcessEnv): string;
+interface ArtMeta {
+    version: 1;
+    key: string;
+    width: number;
+    height: number;
+    depicts: string;
+    model: string;
+    artVersion: string;
+    subjects?: UnitBox[];
+    check?: ArtCheck;
+    feathered?: boolean;
+}
+/** Copies a picture may have beside its PNG: the deck's WebP, the draft call's boxed PNG. */
+export interface ArtCopies {
+    webp?: Buffer;
+    boxed?: Buffer;
+    /** The WebP's edges are feathered into transparency for the beat's box. */
+    feathered?: boolean;
+}
+/**
+ * Pictures beside the scene cache, under `art/`: `<key>.png` (as drawn),
+ * `<key>.webp` (the deck's copy), `<key>.boxed.png` (subjects numbered, for the
+ * draft call) and `<key>.json`.
+ */
+export declare class ArtCache {
+    readonly dir: string;
+    constructor(dir: string);
+    private ref;
+    get(key: string): Promise<ArtRef | undefined>;
+    put(key: string, bytes: Buffer, meta: Omit<ArtMeta, "version" | "key">, copies?: ArtCopies): Promise<ArtRef>;
+}
+export interface DrawArtOptions {
+    run: Runner;
+    /** Scratch: the prompt, the schema and the reply go here. */
+    work: string;
+    tag: string;
+    model: string;
+    timeoutMs: number;
+    /** `-c` overrides: tool-less except the image tool (`artCodexConfig`). */
+    config: readonly string[];
+    bin?: string;
+    onUsage?: (tokens: number) => void;
+    /** Where the image tool saves: `codexHome()` unless a test says otherwise. */
+    home?: string;
+    /** Why the previous picture of this beat was rejected, for the second attempt. */
+    retry?: string;
+}
+/**
+ * One art call. Resolves to the picture's bytes and what it depicts, or throws
+ * with the reason — which the pass reports, and then draws the beat without.
+ */
+export declare function drawArt(brief: ArtBrief, opts: DrawArtOptions): Promise<{
+    bytes: Buffer;
+    width: number;
+    height: number;
+    depicts: string;
+}>;
+/**
+ * The picture at `path`, if it is one the image tool saved: inside
+ * `<home>/generated_images/`, after symlinks; a PNG by its magic bytes; under
+ * the size cap. Anything else is refused by name — the path is model output.
+ */
+export declare function readPicture(path: string, home: string): Promise<Buffer>;
+/** Copy every illustration a bespoke map uses into `<out>/assets/bespoke/`. */
+export declare function copyArt(entries: Iterable<{
+    art?: ArtRef;
+}>, out: string): Promise<string[]>;
+/** Where a deck's page finds an illustration. */
+export declare function artHref(art: ArtRef): string;
+export {};

package/dist/types/bespoke/cache.d.ts

@@ -0,0 +1,69 @@
+import type { Fragment } from "./contract.js";
+/** Bump when the shape of an entry changes. */
+export declare const CACHE_VERSION = 1;
+/** What a key is computed from. Every field is part of the scene's meaning. */
+export interface KeyInput {
+    promptVersion: string;
+    contractVersion: string;
+    /** `codex exec --model`, or `"default"` for the account's own. */
+    model: string;
+    lang: string;
+    beat: {
+        id: string;
+        archetype: string;
+        intent: string;
+        claim?: string;
+        narration?: string;
+        params: unknown;
+    };
+    /** The paper excerpts and equations the prompt quoted, verbatim. */
+    context: string;
+    /** Scene-relative cue windows and their words. */
+    cues: ReadonlyArray<{
+        t0: number;
+        t1: number;
+        text: string;
+    }>;
+    duration: number;
+    holds: readonly number[];
+    region: {
+        width: number;
+        height: number;
+    };
+    /** The pack: name, colours, faces. */
+    pack: unknown;
+    /** The illustration's art key (src/bespoke/art.ts), when the scene was drawn around one. */
+    art?: string;
+}
+export interface CacheEntry {
+    version: number;
+    key: string;
+    verdict: "accepted" | "rejected";
+    fragment?: Fragment;
+    /** Why it was rejected, or which round's scene was kept. */
+    note: string;
+    /** Codex calls it took to reach this verdict. */
+    calls: number;
+    model: string;
+    promptVersion: string;
+    /**
+     * `GATES_VERSION` when the verdict was reached. A rejection is the gates'
+     * opinion, so one from other gates is not trusted; an acceptance is re-gated
+     * on every build anyway.
+     */
+    gates?: string;
+    /** The art key of the illustration the scene places, when it has one. */
+    art?: string;
+}
+/** JSON with sorted keys, so two equal objects hash equal whatever order they were built in. */
+export declare function canonical(value: unknown): string;
+export declare function cacheKey(input: KeyInput): string;
+/** `$XDG_CACHE_HOME/decksmith/bespoke`, else `~/.cache/decksmith/bespoke`. */
+export declare function defaultCacheDir(env?: NodeJS.ProcessEnv): string;
+export declare class SceneCache {
+    readonly dir: string;
+    constructor(dir: string);
+    get(key: string): Promise<CacheEntry | undefined>;
+    /** Written to a temp name and renamed, so a reader never sees half an entry. */
+    put(entry: CacheEntry): Promise<void>;
+}

package/dist/types/bespoke/callouts.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The labels of an illustrated scene, drawn by the shell ON their subjects.
+ *
+ * WHY THE SHELL AND NOT THE SCENE. Round 3's labels were plates in a row along
+ * the top of the box. Round 4's first run (2026-10-09, en deck) asked the scene
+ * to put each label on its subject itself: the labels went on their subjects
+ * (3-4 of 3-4 within 96px in every draft), and four of five scenes then failed
+ * on their own plates and leader lines running through their own text — the
+ * model guesses a label's width, and at 56px a guess is wrong by more than the
+ * plate's margin. The shell knows the width (the same estimator the archetypes
+ * lay out with), so the scene says WHAT each subject is called (`labels`) and
+ * the shell says WHERE: a plate in a zone just above the subject (or across
+ * its top when there is no room above), a leader line to a dot on it, entering
+ * when the camera first arrives on that subject. One grammar for every deck.
+ *
+ * Zones are fixed from the subjects alone, before the scene is written, so the
+ * prompt can tell the scene where they are and to keep its own drawing out.
+ */
+import type { Theme } from "../emit/kit.js";
+import type { Box, CamMove } from "./shots.js";
+/** One subject's label, as the scene names it. */
+export interface Label {
+    subject: number;
+    text: string;
+}
+/** Where a subject's label goes: its zone (box px), and the dot its leader ends on. */
+export interface Zone extends Box {
+    subject: number;
+    /** "above" the subject, or across its "top" inside it. */
+    side: "above" | "top";
+    dot: {
+        x: number;
+        y: number;
+    };
+}
+/** The label's size, and the floor it may shrink to to fit its zone. */
+export declare const LABEL_PX = 56;
+export declare const LABEL_MIN_PX = 44;
+/**
+ * Each subject's label zone: centred over the subject, as wide as half the
+ * distance to each neighbour allows (so neighbours' zones never meet), above
+ * the subject when there is room, else across its top.
+ */
+export declare function calloutZones(subjects: readonly Box[], W: number): Zone[];
+/** How a label is set: its size and its line(s). */
+export interface Fit {
+    fs: number;
+    lines: string[];
+}
+/**
+ * How a label fits its zone: one line from `LABEL_PX` down to `LABEL_MIN_PX`,
+ * else two lines (the plate grows away from the subject, as far as the box
+ * allows), else not at all.
+ */
+export declare function fitLabel(text: string, zone: Zone, theme: Theme, boxH?: number): Fit | undefined;
+/**
+ * Roughly how many characters fit a zone at the floor size, for the prompt
+ * ("at most N characters"): Latin lowercase if the deck is Latin, else the
+ * deck's script, at `LABEL_MIN_PX`. The fit itself is `fitLabel`'s.
+ */
+export declare function longestFit(zone: Zone, theme: Theme): number;
+/** What the camera frames for a subject: the subject and its label zone together. */
+export declare function withZone(s: Box, z: Zone | undefined): Box;
+/** When each subject's label enters: as the camera arrives on it, else at the reveal. */
+export declare function entrances(moves: readonly CamMove[], subjects: number): Map<number, number>;
+/**
+ * The labels as markup and GSAP for the shell to put in the scene: a layer of
+ * `<g data-subject="K">` groups (so `label_anchor` measures them like any
+ * label), each hidden until its entrance, then the plate rises in, the leader
+ * draws to the dot. Labels that do not fit their zone are left out (the
+ * static check refuses a scene that has one, so this is belt and braces).
+ */
+export declare function calloutLayer(sid: string, labels: readonly Label[], zones: readonly Zone[], moves: readonly CamMove[], theme: Theme, W: number, H: number): {
+    markup: string;
+    script: string;
+};

package/dist/types/bespoke/contract.d.ts

@@ -0,0 +1,57 @@
+import { type Label } from "./callouts.js";
+import type { Shot } from "./shots.js";
+/** What a model hands back for one beat. Token form: ids are `SCENEID-…`. */
+export interface Fragment {
+    markup: string;
+    css: string;
+    script: string;
+    /**
+     * An illustrated scene's shot list: which subject of the picture the shell's
+     * camera frames on which cue (src/bespoke/shots.ts). Absent on any other scene.
+     */
+    shots?: Shot[];
+    /**
+     * An illustrated scene's subject labels, which the shell draws ON their
+     * subjects (src/bespoke/callouts.ts). Absent on any other scene.
+     */
+    labels?: Label[];
+}
+/** One reason a fragment may not be used. */
+export interface StaticFinding {
+    rule: string;
+    message: string;
+}
+/** The placeholder scene id a fragment is written against. */
+export declare const SID_TOKEN = "SCENEID";
+/** Bounds on what one scene may weigh. A scene that needs more is not a scene. */
+export declare const MAX_SCRIPT = 40000;
+export declare const MAX_MARKUP = 60000;
+export declare const MAX_CSS = 12000;
+/** The fragment with the real scene id in place of the token. */
+export declare function instantiate(f: Fragment, sid: string): Fragment;
+/** Every reason this fragment may not be built. Empty means it may. */
+export declare function checkFragment(f: Fragment, ctx?: FragmentContext): StaticFinding[];
+export declare function scopedSelector(selector: string): boolean;
+/** What `checkFragment` needs to know about the beat beyond the fragment. */
+export interface FragmentContext {
+    /** Whether the beat has an illustration a scene may place (`<image data-art="1">`). */
+    art?: boolean;
+    /** How many subjects the illustration's inspection found (src/bespoke/inspect.ts). */
+    subjects?: number;
+    /** How many narration cues the scene has, for its shot list. */
+    cues?: number;
+    /** Whether a label's text fits its subject's zone (src/bespoke/callouts.ts `fitLabel`). */
+    labelFits?: (text: string, subject: number) => boolean;
+}
+export declare function checkMarkup(markup: string, ctx?: FragmentContext): StaticFinding[];
+export declare function checkCss(css: string): StaticFinding[];
+export declare function checkScript(script: string): StaticFinding[];
+/**
+ * The kinds of motion a scene's timeline uses, read off its tweens' vars —
+ * for the report, and for the rubric probe that decides whether a scene that
+ * passed every gate still needs the critique round. Static, so it is a
+ * statement about what the script ASKS for; the frames say whether it shows.
+ */
+export declare const MOTION_KINDS: readonly ["draw", "morph", "camera", "counter", "stagger", "flow", "move", "scale", "focus", "recolor"];
+export type MotionKind = (typeof MOTION_KINDS)[number];
+export declare function motionKinds(script: string): MotionKind[];

package/dist/types/bespoke/inspect.d.ts

@@ -0,0 +1,69 @@
+import { type Frame } from "../verify/fidelity.js";
+/** A subject's box as a share of the picture: x, y, w, h in 0..1. */
+export type UnitBox = [number, number, number, number];
+/** At most this many subjects are named, largest first. */
+export declare const MAX_SUBJECTS = 5;
+/**
+ * The ground: the median colour of the picture's outer frame (2% each side).
+ * The illustrator is asked for the pack's exact background; what comes back is
+ * close to it, and the frame is what the scene's feathered edge blends into.
+ */
+export declare function groundOf(f: Frame): [number, number, number];
+/**
+ * The subjects' boxes, left to right, as shares of the picture. Components of
+ * the foreground mask after a small dilation (so a subject's own parts join),
+ * boxed on the UNdilated cells, specks dropped, the largest `MAX_SUBJECTS` kept.
+ */
+export declare function subjectBoxes(f: Frame, ground?: [number, number, number]): UnitBox[];
+/** How flat a picture is drawn: the measures `flatEnough` reads. */
+export interface Flatness {
+    /** Share of the subjects' pixel pairs that differ a little (shading), 0..1. */
+    soft: number;
+    /** Share of the subjects' pixels in their 16 commonest colours (4 bits a channel), 0..1. */
+    palette: number;
+    /** `palette - soft`: high for flat fills with hard edges, low for a shaded render. */
+    score: number;
+    /** Share of the picture that is not ground. */
+    coverage: number;
+}
+export declare function flatness(f: Frame, ground?: [number, number, number]): Flatness;
+/**
+ * The flat-art bar on `score`. CALIBRATED 2026-10-09 on 21 round-3 pictures
+ * (soft 3D toy renders by eye: 0.04-0.46, one at 0.557 — a shaded robot beside
+ * a big flat curtain) and 58 pictures drawn by the round-4 prompt (0.48-0.84).
+ * First set at 0.57, it refused two pictures at 0.56 and 0.565 that are flat by
+ * eye (many small flat colours), each a 60s redraw on the critical path; the
+ * one round-4 picture under 0.52 (0.48) has soft shading on its figures. So
+ * 0.52: 20 of 21 round-3 renders refused, no flat picture seen refused. The
+ * margin is thin both ways; a near miss costs one redraw, never the picture
+ * (`illustrate` keeps the flatter of two attempts).
+ */
+export declare const FLAT_MIN = 0.52;
+export declare function flatEnough(m: Flatness): boolean;
+/** One run of text Vision read, with its box as shares of the picture (top-left origin). */
+export interface ReadText {
+    s: string;
+    c: number;
+    b: UnitBox;
+    l?: string;
+}
+/** Whether a run is writing and not a shape Vision guessed at: confident, or long and fairly sure. */
+export declare function isWriting(t: ReadText): boolean;
+/**
+ * The Swift helper: Vision's accurate recogniser, once per script the decks
+ * are written in (one request with all four reads only Latin reliably —
+ * MEASURED 2026-10-09: 학습 단계, 学習の流れ, 训练过程 were found only by their own
+ * language's pass). Prints one JSON line per file.
+ */
+export declare const OCR_SWIFT = "import Foundation\nimport Vision\nimport ImageIO\nfunc run(_ img: CGImage, _ langs: [String]) -> [[String: Any]] {\n  let req = VNRecognizeTextRequest()\n  req.recognitionLevel = .accurate\n  req.usesLanguageCorrection = false\n  req.recognitionLanguages = langs\n  try? VNImageRequestHandler(cgImage: img, options: [:]).perform([req])\n  var out: [[String: Any]] = []\n  for o in req.results ?? [] {\n    guard let c = o.topCandidates(1).first else { continue }\n    let b = o.boundingBox\n    out.append([\"s\": c.string, \"c\": c.confidence, \"b\": [b.minX, 1 - b.maxY, b.width, b.height], \"l\": langs[0]])\n  }\n  return out\n}\nfor path in CommandLine.arguments.dropFirst() {\n  guard let src = CGImageSourceCreateWithURL(URL(fileURLWithPath: path) as CFURL, nil),\n        let img = CGImageSourceCreateImageAtIndex(src, 0, nil) else {\n    print(\"{\\\"error\\\":\\\"unreadable\\\"}\"); continue\n  }\n  var out: [[String: Any]] = []\n  for langs in [[\"en-US\"], [\"ko-KR\"], [\"ja-JP\"], [\"zh-Hans\"]] { out += run(img, langs) }\n  let data = try! JSONSerialization.data(withJSONObject: [\"texts\": out])\n  print(String(data: data, encoding: .utf8)!)\n}\n";
+/** The writing in a picture; rejects (with why) when nothing here can read it. */
+export declare function readText(png: string, toolDir: string): Promise<ReadText[]>;
+/** Everything the inspection says about one picture. */
+export interface Inspection {
+    subjects: UnitBox[];
+    flat: Flatness;
+    /** Writing found, or null when no reader was available (`unread` says why). */
+    text: string[] | null;
+    unread?: string;
+}
+export declare function inspectPicture(bytes: Buffer, file: string, toolDir: string): Promise<Inspection>;

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

@@ -0,0 +1,207 @@
+import { type DeckNarration } from "../emit/composition.js";
+import { type Runner } from "../plan/codex.js";
+import type { Prefs } from "../prefs.js";
+import type { Beat, Format, Source, Storyboard } from "../types.js";
+import { type Layout } from "../verify/scenes.js";
+import { type ArtCheck, type ArtCopies } from "./art.js";
+import { type Label } from "./callouts.js";
+import { type Inspection } from "./inspect.js";
+import { type Measured } from "./prompt.js";
+import { type RepairNote } from "./repair.js";
+import { type BespokeMap } from "./scene.js";
+import { type Skip } from "./select.js";
+import { type Shot } from "./shots.js";
+export type BespokePrefs = NonNullable<Prefs["bespoke"]>;
+/** What a gate round says about one beat's candidate scene. */
+export interface GateResult {
+    /** One line per finding, fed verbatim to the critique round. */
+    findings: string[];
+    failed: boolean;
+    /** A contact sheet of the probe frames, for `codex exec -i`. */
+    sheet?: string;
+    /** What each cell of the sheet is. */
+    legend?: string;
+    /** What the probe measured: the rubric probe reads it, the critique round is told it. */
+    metrics?: Measured;
+    /** Warnings about the scene itself (not the storyboard's), by rule. Any one sends it to critique. */
+    warnings?: string[];
+    /** Every graded frame's layout with its repair geometry (src/bespoke/repair.ts reads it). */
+    layout?: Layout[];
+    /** The scene id the probe deck drew it at (to read ids in `layout` back to token form). */
+    sid?: string;
+}
+/** Which probe: the drafts, the final candidates, or a repair round's. */
+export type GateRound = "draft" | "final" | "repair";
+/** Builds a deck with these candidates, gates each, and says what it found — keyed by beat id. */
+export type GateFn = (candidates: BespokeMap, round: GateRound) => Promise<Map<string, GateResult>>;
+export interface BespokeInput {
+    storyboard: Storyboard;
+    source: Source;
+    format: Format;
+    narration: DeckNarration;
+    /** The resolved pack name, as `build` picked it. */
+    theme: string;
+    speed: number;
+    prefs: BespokePrefs;
+    /** Builds and gates a probe deck. `build` passes the browser gate (src/bespoke/probe.ts). */
+    gate: GateFn;
+    onStep?: (message: string) => void;
+    /** Swappable for tests; the production runner is `codex exec`. */
+    run?: Runner;
+    now?: () => number;
+    /** Scratch for prompts, replies and sheets. Default: a temp dir, removed at the end. */
+    work?: string;
+    /** Where the image tool saves pictures. Default `$CODEX_HOME` or `~/.codex` (tests point it elsewhere). */
+    codexHome?: string;
+    /** Inspects a drawn picture (src/bespoke/inspect.ts); swappable so tests need no Swift or Vision. */
+    inspect?: (bytes: Buffer, file: string) => Promise<Inspection>;
+    /** Draws the deck's WebP and the boxed copy (src/bespoke/sheet.ts); swappable so tests need no Chrome. */
+    copies?: (png: Buffer, boxes: Inspection["subjects"], box: {
+        width: number;
+        height: number;
+    }) => Promise<ArtCopies>;
+}
+export interface SceneReport {
+    beat: string;
+    archetype: string;
+    status: "bespoke" | "fallback";
+    /** Where the scene came from, when there is one. */
+    from?: "cache" | "draft" | "critique";
+    /** Why it fell back, or a note on the scene kept. */
+    reason?: string;
+    calls: number;
+    /** The last round's findings, for whoever reads this file. */
+    findings: string[];
+    key?: string;
+    /** The scene id it was drawn at, filled in once the deck is emitted. */
+    sid?: string;
+    /** Motion kinds the kept scene's script uses. */
+    kinds?: string[];
+    /** The probe's measures of the kept scene (or of the last candidate, on a fallback). */
+    metrics?: Measured;
+    /** Whether a critique call was made, skipped because the rubric probe was clean, or never reached. */
+    critique?: "ran" | "skipped" | "none";
+    /** The illustration the scene was built around, and what its inspection said. */
+    art?: {
+        key: string;
+        depicts: string;
+        subjects?: number;
+        check?: ArtCheck;
+    };
+    /** A data beat: drawn as a chart, never on a picture. */
+    data?: boolean;
+    /** Why there is none, when one was wanted. */
+    artNote?: string;
+    /** What the deterministic repair did to the kept scene (src/bespoke/repair.ts). */
+    repair?: RepairNote & {
+        rounds: number;
+    };
+    /** The kept scene passed only after a repair: without one, this beat fell back. */
+    savedByRepair?: boolean;
+    /**
+     * The scene id the probe deck had it at when the gates passed the kept bytes:
+     * `build` skips re-running the full motion gates on a scene at that same id
+     * (it still seeks it), because the pass already ran them on exactly this scene.
+     */
+    gatedAt?: string;
+}
+export interface BespokeReport {
+    version: 1;
+    model: string;
+    promptVersion: string;
+    contractVersion: string;
+    gates: string;
+    caps: {
+        calls: number;
+        seconds: number;
+    };
+    calls: number;
+    tokens: number;
+    seconds: number;
+    quota: boolean;
+    /**
+     * Illustrations: the deck's cap, calls made, pictures used (drawn or cached),
+     * redraws made after a rejection, and pictures rejected for text / for style.
+     */
+    art: {
+        cap: number;
+        calls: number;
+        used: number;
+        redraws: number;
+        rejectedText: number;
+        rejectedStyle: number;
+        rejectedSubjects: number;
+    };
+    /** Wall seconds of the pass's stages, for profiling (`build` adds its own). */
+    stages?: Record<string, number>;
+    scenes: SceneReport[];
+    skipped: Skip[];
+}
+export interface BespokeResult {
+    map: BespokeMap;
+    report: BespokeReport;
+}
+/** Repair rounds after the final gates, each one probe build of the repaired scenes only. */
+export declare const REPAIR_ROUNDS = 2;
+export declare class Budget {
+    readonly cap: number;
+    readonly deadline: number;
+    readonly now: () => number;
+    calls: number;
+    /** Illustration calls, capped apart from `calls` (`prefs.art`). */
+    art: number;
+    /** Second draws after a rejected picture: one per beat at most, under the same cap plus one each. */
+    redraws: number;
+    rejectedText: number;
+    rejectedStyle: number;
+    rejectedSubjects: number;
+    tokens: number;
+    quota: boolean;
+    constructor(cap: number, deadline: number, now: () => number);
+    /** Undefined if a call may go ahead (and is counted), else why not. */
+    take(): string | undefined;
+    /** As `take`, for an illustration call against its own cap. */
+    takeArt(cap: number): string | undefined;
+    /** One redraw of a rejected picture: not against the art cap, but against the clock and the quota. */
+    takeRedraw(): string | undefined;
+    seconds(): number;
+}
+/** Below this share of the frame, a cue "barely moves" by the rubric's measure (static_hold's floor is 0.015%). */
+export declare const RUBRIC_CUE_CHANGE = 0.005;
+/** The focal size the prompt asks for; the gate's floor is `KEY_TYPE_PX`. */
+export declare const RUBRIC_FOCAL_PX = 88;
+/**
+ * The share of its box a settled drawing should paint. MEASURED 2026-10-08:
+ * round 1's sixteen scenes painted 3.9-15.6% (median ~9%) — thin outlines and
+ * small captions — and round 2's first twenty 10-57% (median ~25%).
+ */
+export declare const RUBRIC_MASS = 0.12;
+/**
+ * More than this share of the drawn parts under 0.6 opacity at the settled
+ * frame, and the end is not a summary. Round 2's first full run left zh s6 and
+ * en s6 ending on a frame of ghosts with one lit part.
+ */
+export declare const RUBRIC_DIMMED = 0.5;
+/**
+ * The rubric probe: is a scene that passed every gate also clean by the
+ * rubric's MEASURABLE half? Free — it reads what the probe already measured —
+ * and it decides whether the critique call (~4 minutes, ~30k tokens) is spent.
+ * Empty means clean. What it cannot measure (is this the right picture for the
+ * sentence?) it does not pretend to; that is the reason a clean scene is still
+ * looked at by a person in the preview.
+ */
+export declare function rubricProbe(m: Measured | undefined, warnings?: readonly string[], art?: boolean): string[];
+/**
+ * Archetypes whose beat IS its numbers. Round 3 illustrated them like any other
+ * beat and the scene painted the table over the picture (ja s12: nine numbers
+ * on a robot). A data beat gets no picture and the chart that builds instead.
+ */
+export declare const DATA_ARCHETYPES: readonly string[];
+export declare function isDataBeat(beat: Pick<Beat, "archetype">): boolean;
+/** A reply's labels, kept only where they are the shape the schema promised. */
+export declare function readLabels(raw: unknown): Label[];
+/** A reply's shot list, kept only where it is the shape the schema promised. */
+export declare function readShots(raw: unknown): Shot[];
+/** The paper the prompt may quote for this beat: its cited sections, equations and figure captions. */
+export declare function contextFor(beat: Beat, source: Source): string;
+export declare function bespokePass(input: BespokeInput): Promise<BespokeResult>;