@jokerized/decksmith 0.8.0 → 0.9.1

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

@@ -0,0 +1,34 @@
+import type { DeckNarration } from "../emit/composition.js";
+import type { Finding, Format, Source, Storyboard } from "../types.js";
+import { type CamSample, type Layout, type SceneWindow } from "../verify/scenes.js";
+import type { GateFn } from "./pipeline.js";
+import type { Measured } from "./prompt.js";
+import type { BespokeMap } from "./scene.js";
+export interface ProbeDeck {
+    storyboard: Storyboard;
+    source: Source;
+    format: Format;
+    narration: DeckNarration;
+    theme: string;
+    /** Where the source's assets live (`build` copies them from here). */
+    assetsFrom: string;
+    /** Scratch: probe decks and contact sheets go here. */
+    work: string;
+    onStep?: (message: string) => void;
+}
+/** Which scene a `verify` finding is about, if it says. */
+export declare function attribute(f: Finding, windows: readonly SceneWindow[]): string | undefined;
+/**
+ * A console error no scene id names fails every scene probed with it — unless
+ * the value it quotes appears in exactly one candidate, which is then the
+ * culprit: an SVG parse error quotes the bad attribute. MEASURED 2026-10-09:
+ * one draft's broken path sent all five drafts of a deck to critique.
+ */
+export declare function pinPageErrors(findings: Finding[], candidates: BespokeMap, sidOf: ReadonlyMap<string, string>): Finding[];
+/**
+ * What an illustrated scene's frames say about its staging: the distinct
+ * push-ins held at cue ends, whether it opens wide, and how many subjects are
+ * named by a label within reach at the end. Empty for a scene with no subjects.
+ */
+export declare function stagingMeasures(rows: readonly Layout[], cams: readonly CamSample[], open?: number): Partial<Measured>;
+export declare function browserGate(deck: ProbeDeck): GateFn;

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

@@ -0,0 +1,182 @@
+/**
+ * The two prompts a bespoke beat may cost: generate, then — only when the
+ * gates or the rubric probe found something — critique-and-fix with the
+ * rendered frames attached.
+ *
+ * Production differs from the 2026-10-07 spike where it must:
+ *  - the shell draws the eyebrow and headline and owns the exit, so the model
+ *    draws only the body, into a box of known size;
+ *  - GSAP callbacks are refused outright (invariant 11), and every tween's vars
+ *    are a literal at an explicit second, so `checkScript` can read them;
+ *  - the scene id is the token `SCENEID`, so the cached scene fits any slot;
+ *  - the paper's text is fenced and labelled as untrusted data.
+ *
+ * ROUND 2 (2026-10-08) is about the LOOK, and grounds it in three places:
+ *  - worked examples (src/bespoke/references.ts) instead of adjectives — the
+ *    model is shown two complete scenes at the bar, in the deck's own palette;
+ *  - motion-design rules with numbers, from what 3Blue1Brown, Kurzgesagt-style
+ *    motion graphics, keynote diagram reveals and Distill figures have in
+ *    common: one focal element per cue, everything else dimmed but kept;
+ *    identity kept through change (transform, don't replace); a camera that
+ *    moves to the part being named; numbers that count; big, flat, few;
+ *  - semantic groups (Vector Prism, arXiv 2512.14336): parts that move
+ *    together are one `<g data-cue>`, which is also what `early_reveal` reads.
+ * The critique round judges against an explicit rubric (TheoremExplainAgent,
+ * arXiv 2502.19400, found free-form VLM judgement unreliable on layout; a rubric
+ * with measured numbers attached is what it can act on) and returns the fix.
+ *
+ * The placement grid is Code2Video's visual anchor prompt (arXiv 2510.01174).
+ */
+import type { Theme } from "../emit/kit.js";
+import { type Box, CAMERA_MAX_SCALE } from "./shots.js";
+export { CAMERA_MAX_SCALE };
+/** Bump with any change to either prompt or to a reference: it is part of every cache key. */
+export declare const PROMPT_VERSION = "bespoke-5";
+/** Bump with any change to what `checkFragment` accepts. Also part of every key. */
+export declare const CONTRACT_VERSION = "contract-4";
+/** What the model is told about one beat. */
+export interface Brief {
+    lang: string;
+    eyebrow?: string;
+    headline: string;
+    intent: string;
+    claim?: string;
+    narration?: string;
+    archetype: string;
+    /** The old archetype's params, for wording only. */
+    params: unknown;
+    /** Paper excerpts and equations, quoted. Untrusted. */
+    context: string;
+    cues: ReadonlyArray<{
+        t0: number;
+        t1: number;
+        text: string;
+    }>;
+    /** Scene length, seconds. */
+    duration: number;
+    /** The body box, reference px. */
+    region: {
+        width: number;
+        height: number;
+    };
+    theme: Theme;
+    /** Pack name, for the art direction line. */
+    pack: string;
+    /**
+     * The beat's illustration, attached to the call as an image (src/bespoke/art.ts),
+     * and its subjects in body-box px, left to right (src/bespoke/inspect.ts):
+     * what the labels are anchored to and the shots frame.
+     */
+    art?: {
+        depicts: string;
+        width: number;
+        height: number;
+        subjects?: Box[];
+        /** Where the shell draws each subject's label (src/bespoke/callouts.ts), and its longest fit. */
+        zones?: Array<Box & {
+            subject: number;
+            chars: number;
+        }>;
+    };
+    /** A data beat (a chart or a table): built as a chart, never on a picture. */
+    data?: boolean;
+}
+/** What the probe measured about a candidate, quoted to the critique round. */
+export interface Measured {
+    /** Bounding box of the drawing over the body box, settled frame. */
+    fill?: number;
+    /** Share of a 6x4 grid over the box something is drawn in. */
+    cells?: number;
+    /** Largest label at the settled frame, px. */
+    maxType?: number;
+    /** Share of the box the settled drawing paints (filled shapes count, hairlines barely). */
+    mass?: number;
+    /** Share of the drawn parts left dimmed (under 0.6 opacity) at the end. */
+    dimmed?: number;
+    /** Motion kinds the script asks for (`motionKinds`). */
+    kinds?: readonly string[];
+    /** Per cue, the largest share of the frame that changed during it. */
+    cueChange?: readonly number[];
+    /** How many subjects the scene's illustration has. */
+    subjects?: number;
+    /** Distinct push-ins the held frames show (illustrated scenes, `shotsOf`). */
+    shots?: number;
+    /** Whether the first cue opens on the whole picture. */
+    establishing?: boolean;
+    /** Subjects named by a label within reach of them, at the end. */
+    anchored?: number;
+    /** The farthest a subject's label sits from it, box px, at the end. */
+    anchorMax?: number;
+}
+/** The structured reply. `--output-schema` holds the model to it. */
+export declare const REPLY_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["review", "plan", "markup", "css", "script", "shots", "labels"];
+    readonly properties: {
+        readonly review: {
+            readonly type: "string";
+        };
+        readonly plan: {
+            readonly type: "string";
+        };
+        readonly markup: {
+            readonly type: "string";
+        };
+        readonly css: {
+            readonly type: "string";
+        };
+        readonly script: {
+            readonly type: "string";
+        };
+        readonly labels: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["subject", "text"];
+                readonly properties: {
+                    readonly subject: {
+                        readonly type: "integer";
+                    };
+                    readonly text: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly shots: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["cue", "at", "subject"];
+                readonly properties: {
+                    readonly cue: {
+                        readonly type: "integer";
+                    };
+                    readonly at: {
+                        readonly type: "number";
+                    };
+                    readonly subject: {
+                        readonly type: "integer";
+                    };
+                };
+            };
+        };
+    };
+};
+/** The subjects as the prompt lists them: box px, left to right. */
+export declare function subjectLines(subjects: readonly Box[]): string;
+/** The first call: draw this beat. */
+export declare function generatePrompt(b: Brief): string;
+/** The rubric the critique round scores, and the probe reads off the measures. */
+export declare const RUBRIC: readonly ["FILLS THE STAGE: the drawing uses the whole box (>= 80% of its area, no empty third or band) with visual mass — filled shapes, not hairlines", "ONE FOCUS PER CUE: in every cue one element is clearly what to look at; the rest is dimmed", "MOTION EXPLAINS: the moves are the idea (flow, transform, morph, camera, counter), at least three kinds, nothing decorative, nothing still while the voice speaks; the camera goes where the voice is", "LEGIBLE HIERARCHY: focal label/number 88px+, labels 52px+, nothing under 44px, high contrast, no collisions or clipping", "CONSISTENT WITH THE PACK: only the pack's colours, big flat shapes, strokes 5-8px, the deck's font", "IN SYNC: each cue's change starts within 0.5s of its words and nothing appears before the cue that names it"];
+/** The second call: score the frames against the rubric, then fix what is wrong. */
+export declare function critiquePrompt(b: Brief, current: {
+    markup: string;
+    css: string;
+    script: string;
+    shots?: readonly unknown[];
+    labels?: readonly unknown[];
+}, findings: readonly string[], legend: string | undefined, measured?: Measured): string;

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

@@ -0,0 +1,73 @@
+/**
+ * Hand-made reference scenes: the bar a generated scene is held to, shown to
+ * the model as worked examples (few-shot) and run through every gate by
+ * test/bespoke-references.test.ts, so a reference that stops passing a gate
+ * stops being a reference.
+ *
+ * WHY EXAMPLES AND NOT MORE PROSE. Round 1's prompt said "use the whole box",
+ * "keep it alive", "64px for the key quantity" and the model drew 40-56px boxes
+ * and arrows in two thirds of the frame. Code2Video (arXiv 2510.01174) and
+ * TheoremExplainAgent (arXiv 2502.19400) both found layout and visual quality
+ * respond to concrete anchors and examples far more than to adjectives. Each
+ * reference is a complete scene in the contract's own token form, written to the
+ * motion-design habits round 1 lacked:
+ *
+ *  - THE STAGE IS FILLED: every reference spans >= 85% of its box at the end.
+ *  - HIERARCHY: one 88-120px focal element per cue; labels 48-60px; nothing
+ *    under 44px.
+ *  - ONE FOCUS PER CUE: what the voice is naming is lit (accent, full opacity);
+ *    what it is not is dimmed to ~0.3 — never removed, so the viewer keeps place.
+ *  - IDENTITY IS KEPT: a thing that changes state moves or morphs into the new
+ *    state (3Blue1Brown's transforms) instead of cutting to a new drawing.
+ *  - SEMANTIC GROUPS (Vector Prism, arXiv 2512.14336): each part is a <g> with a
+ *    descriptive id and `data-cue`, and motion is attached to groups.
+ *  - A RICHER VERB SET, chosen to fit: flow (particles), camera (viewBox zoom),
+ *    counters (textContent + snap), morph (morphSVG), staggered builds, draws.
+ *  - ARROWHEADS ARE SHAPES, not markers, and appear when their line arrives.
+ *
+ * Colours are `{{token}}` placeholders filled from the deck's pack, so the
+ * examples are in the palette the model must use. All are written for a
+ * 1700x732 body box; the prompt says how to adapt to the real one.
+ */
+import type { Theme } from "../emit/kit.js";
+import type { Fragment } from "./contract.js";
+export interface Reference {
+    name: string;
+    /** What it demonstrates, one line, quoted in the prompt. */
+    shows: string;
+    /** Archetypes whose beats this reference suits best (selection order). */
+    fits: readonly string[];
+    /** The narration cues the script is timed to (scene seconds). */
+    cues: ReadonlyArray<{
+        t0: number;
+        t1: number;
+        text: string;
+    }>;
+    duration: number;
+    fragment: Fragment;
+    /** An illustrated reference's subjects, box px: what the prompt would list for its picture. */
+    subjects?: ReadonlyArray<{
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }>;
+}
+/** The box every reference is drawn for. */
+export declare const REFERENCE_BOX: {
+    readonly width: 1700;
+    readonly height: 732;
+};
+export declare const REFERENCES: readonly Reference[];
+/** Whether a reference places the beat's illustration (and so needs a beat that has one). */
+export declare function placesArt(r: Reference): boolean;
+/** A reference with its `{{token}}` colours filled from `theme`. */
+export declare function paint(f: Fragment, theme: Theme): Fragment;
+/**
+ * The two references a beat is shown: the best fit for its archetype first,
+ * then the best fit that teaches a DIFFERENT motion, so every prompt carries
+ * at least two verbs beyond fade-and-draw. An illustrated beat leads with the
+ * staged reference and is never shown a scene that moves its own camera (the
+ * shell's shots do that); a data beat leads with the chart that builds.
+ */
+export declare function pickReferences(archetype: string, n?: number, art?: boolean, data?: boolean): Reference[];

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

@@ -0,0 +1,121 @@
+/**
+ * Deterministic repair of a generated scene the gates refused for a reason a
+ * person would fix by hand in seconds — instead of throwing the scene away.
+ *
+ * ROUND 2 LOST 4 OF 21 BEATS to `text_overlap` / `graphic_crosses_text` after
+ * the critique round: big type collides more, and a model fixing one collision
+ * by rewriting coordinates makes the next one. Round 2 also kept three scenes
+ * that ended on a frame of ghosts. None of that needs another model call:
+ *
+ *  - LABEL COLLISIONS are solved as constraint relaxation over the frames the
+ *    probe measured. Each colliding label's unit — the `<text>`, or the
+ *    smallest `<g>` holding it with its plate and no other label — gets ONE
+ *    constant offset, the smallest (in rings of `STEP` px, sixteen directions
+ *    in a fixed order) that clears every other label by `LABEL_GAP`, every
+ *    stroke sample by `STROKE_GAP`, every shape painted over it, and stays in
+ *    the box, at EVERY measured frame, with the camera's scale at each frame
+ *    applied. The offset becomes a wrapping `<g transform="translate()">` in
+ *    the markup, so the scene's own tweens on the unit are untouched.
+ *  - A DIMMED END (`end_dimmed`): the elements dimming parts the scene had lit
+ *    are tweened back to opacity 1 just before the scene ends.
+ *  - A CAMERA LEFT ZOOMED (`camera_end`): the camera is tweened home.
+ *
+ * Every repair is appended as ordinary contract code (a `tl.to` with literal
+ * vars at a literal second, or a wrapper `<g>`), goes through `checkFragment`
+ * like a model's, and is gated again before it is used. Deterministic: the same
+ * geometry gives the same bytes, so a repaired scene caches like any other.
+ */
+import type { Geo, Layout } from "../verify/scenes.js";
+import { type Fragment } from "./contract.js";
+/** Error rules this module can fix. A scene failing anything else is not repaired. */
+export declare const REPAIRABLE: Set<string>;
+/** Clearance a moved label keeps from every other label, px. */
+export declare const LABEL_GAP = 16;
+/** Clearance from every visible stroke sample, px. */
+export declare const STROKE_GAP = 10;
+/** Ring step, px. */
+export declare const STEP = 8;
+/**
+ * The farthest a label may move: its own height times this, at least
+ * `MIN_REACH` px. A nudge, not a relocation — MEASURED 2026-10-09 with a flat
+ * 320px reach, the solver cleared a two-line label's overlap by carrying its
+ * second line onto the illustration, away from its plate: every gate passed and
+ * the label no longer read as one. A collision that needs more than this is the
+ * critique round's to redesign.
+ */
+export declare const REACH = 0.8;
+export declare const MIN_REACH = 32;
+/** The `error <rule>:` lines of a gate's findings, by rule. */
+export declare function errorRules(findings: readonly string[]): string[];
+/** Whether every error in `findings` is one this module can fix (and there is one). */
+export declare function repairable(findings: readonly string[]): boolean;
+/** One unit's offset, in the units of the unit's parent (screen px / its scale). */
+export interface Move {
+    u: string;
+    dx: number;
+    dy: number;
+}
+/**
+ * Offsets that clear every collision in `frames`, or the units it could not
+ * clear. Pure: the probe measured `frames` (src/verify/scenes.ts, `geo`).
+ */
+export declare function solveNudges(frames: readonly Geo[]): {
+    moves: Move[];
+    unresolved: string[];
+};
+/** Each move as a wrapping `<g transform="translate(dx dy)">`, applied from the end so positions hold. */
+export declare function applyMoves(markup: string, moves: readonly Move[]): string;
+/**
+ * A PLATE TOO SMALL FOR ITS TEXT — the commonest crossing round 4 still lost
+ * scenes to (MEASURED 2026-10-09: zh run a, three of three fallbacks were a
+ * summary plate whose own border ran through its CJK text; en, a token disc
+ * round its own symbol). The model guesses a label's width. At a measured frame
+ * where the label is at scale 1 (camera home), a filled `<rect>` or `<circle>`
+ * painted before a label and covering at least half of it, but not all of it
+ * with a margin, is that label's plate, and it is grown — by the deltas the
+ * measured boxes call for, so a plate inside a translated group grows in its
+ * own units — to hold the label with `PLATE_PAD` of the label's height round
+ * it. Only a plate whose markup size IS its measured size (no scale between,
+ * not resized by a tween) is touched; anything else is left to the nudges.
+ */
+export declare const PLATE_PAD = 0.3;
+export declare function fitPlates(markup: string, frames: readonly Geo[] | Geo | undefined): {
+    markup: string;
+    grown: number;
+};
+/** When the end-state repairs land: after the last cue starts, finished before the end frame. */
+export declare function settleAt(duration: number, lastCueStart: number): number;
+/**
+ * Bring the elements dimming lit parts back to full strength at `at`. Targets
+ * are the probe's `tag:index[#id]`, ids in the probe deck's form (`sid-…`);
+ * an element without an id gets one (`SCENEID-lit<k>`).
+ */
+export declare function relight(f: Fragment, targets: readonly string[], at: number, sid: string): Fragment;
+/** Send the camera home at `at`: the shell's wrapper, or the svg's viewBox. */
+export declare function homeCamera(f: Fragment, camOff: string, at: number): Fragment;
+/** What a repair did, for the report. */
+export interface RepairNote {
+    /** Overlapping tweens on one property were untangled (`seek_order`). */
+    untangled?: boolean;
+    moved: number;
+    /** Plates grown to hold their text (`fitPlates`). */
+    grown?: number;
+    relit: number;
+    camera: boolean;
+    rules: string[];
+}
+/**
+ * The repaired scene, or undefined when the findings include something this
+ * cannot fix or the solver cannot clear every collision. Never a model call.
+ */
+export declare function repairScene(f: Fragment, g: {
+    findings: readonly string[];
+    layout?: readonly Layout[];
+    sid?: string;
+}, scene: {
+    duration: number;
+    lastCueStart: number;
+}): {
+    fragment: Fragment;
+    note: RepairNote;
+} | undefined;

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

@@ -0,0 +1,97 @@
+import type { EmitContext, Scene } from "../emit/kit.js";
+import type { Beat } from "../types.js";
+import { type ArtRef } from "./art.js";
+import { type Zone } from "./callouts.js";
+import { type Fragment } from "./contract.js";
+import { type Box, type CamMove } from "./shots.js";
+/** One beat's bespoke scene, ready to emit. */
+export interface BespokeEntry {
+    /** Token form, already through `checkFragment`. */
+    fragment: Fragment;
+    /** Scene-relative seconds, one per stop, from `bespokeHolds`. */
+    holds: number[];
+    /** The beat's illustration, when it has one: `<image data-art="1">` shows it (src/bespoke/art.ts). */
+    art?: ArtRef;
+    /**
+     * The narration cues on the scene's clock and its length, from the same
+     * timing the cue windows came from: what the shell's camera is timed to
+     * (src/bespoke/shots.ts). Present on an illustrated scene.
+     */
+    stage?: {
+        cues: ReadonlyArray<{
+            t0: number;
+            t1: number;
+        }>;
+        duration: number;
+    };
+}
+/** The file `build` writes beside a deck with the bespoke pass's account of itself. */
+export declare const BESPOKE_FILE = "bespoke.json";
+/** Keyed by beat id: a scene id is a position, and a cut can move it. */
+export type BespokeMap = Readonly<Record<string, BespokeEntry>>;
+/** Space the body box leaves under the chrome — the same 34px `bodyBudget` charges by default. */
+export declare const BODY_TOP = 34;
+/** The box the generated drawing gets, in reference px. The prompt quotes it. */
+export declare function bespokeRegion(beat: Beat, ctx: Pick<EmitContext, "format" | "theme">): {
+    width: number;
+    height: number;
+};
+/** Whether a scene's script moves the shell's camera (`#SCENEID-cam`). */
+export declare function usesCamera(script: string): boolean;
+/**
+ * The illustration's href AND its placement, written by the shell into the
+ * scene's one `<image data-art="1">` — the contract refuses an href from the
+ * model, so the deck only ever references a file the build copied under its
+ * own name; and the picture always covers the body box (`slice`), so the
+ * subject boxes the camera and the labels are anchored to are where the
+ * picture's subjects are, whatever the scene wrote.
+ */
+export declare function withArt(markup: string, art: ArtRef | undefined, box?: {
+    width: number;
+    height: number;
+}): string;
+/**
+ * The subjects' boxes as the gates see them: invisible rects inside the camera
+ * (so they move with it), after the scene's markup (so the repair pass's
+ * `tag:index` addresses of the scene's own elements do not shift).
+ */
+export declare function subjectLayer(subjects: readonly Box[], width: number, height: number): string;
+/**
+ * An illustrated entry's subjects in body px, its labels' zones, and the camera
+ * moves its shots compile to — each push-in framing the subject together with
+ * its label's zone, so the label the camera arrives for is in the shot.
+ */
+export declare function staging(entry: BespokeEntry, box: {
+    width: number;
+    height: number;
+}): {
+    subjects: Box[];
+    zones: Zone[];
+    moves: CamMove[];
+};
+/** CSS feather for an illustration's edges: 6% at the sides, 10% top and bottom. */
+export declare const ART_FEATHER = "-webkit-mask-image:linear-gradient(to right,transparent,#000 6%,#000 94%,transparent),linear-gradient(to bottom,transparent,#000 10%,#000 90%,transparent);-webkit-mask-composite:source-in;mask-composite:intersect";
+/** Whether a scene's script tweens `morphSVG` (MorphSVGPlugin must be registered first). */
+export declare function usesMorph(script: string): boolean;
+export declare function bespokeScene(beat: Beat, ctx: EmitContext, entry: BespokeEntry): Scene;
+/**
+ * Where a bespoke scene's stops go, given the stops its archetype had and the
+ * narration that will be spoken over it.
+ *
+ * THE STOP COUNT IS KEPT, because `narrate` recorded the narration against it
+ * and `assertNarrationStaging` refuses a deck whose beats moved. Only the
+ * POSITIONS move: an archetype's holds sit where its reveals land, all inside
+ * the first few seconds; a bespoke scene keeps explaining for the whole of the
+ * speech, so a stop belongs where its sentence starts.
+ *
+ * WHY THIS LEAVES THE VOICE WHERE IT WAS. `speechPlan` starts sentence i at
+ * `max(end of i-1, hold[stop_i])`. The new hold of every speaking stop past the
+ * first IS that start, computed with the old holds, so recomputing with the new
+ * ones returns the same starts; the first sentence starts at `open` regardless.
+ * The last hold never moves earlier than the archetype's own, so `beatSeconds`'
+ * `lastHold + SETTLE` term cannot shrink the scene either.
+ *
+ * Silent stops (narration density below `high`) are spread evenly between the
+ * speaking stops either side of them.
+ */
+export declare function bespokeHolds(archetypeHolds: readonly number[], starts: ReadonlyMap<number, number>, speechEnd: number): number[];

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

@@ -0,0 +1,52 @@
+/**
+ * Which beats get a bespoke scene. A deterministic rule, so the same storyboard
+ * always asks the model about the same beats, and a cache hit is a cache hit.
+ *
+ * WHAT IS WORTH A MODEL CALL. A bespoke scene earns its cost where the fixed
+ * vocabulary is weakest: a beat that explains a MECHANISM — a process, an
+ * equation, a curve, a comparison — and that the narration talks over for many
+ * seconds while the v2 archetype has finished building after five (measured in
+ * the spike: v2's s3 and s7 froze for 15-20s of speech). Title cards, callouts
+ * and tables say a thing rather than show one, so they never qualify.
+ *
+ * WHAT NEVER QUALIFIES, whatever it scores:
+ *  - a beat with no narration: its cues are the keyframes, and without them a
+ *    generated scene has nothing to stay in step with;
+ *  - a beat a camera enters or leaves (`inside`): the dive is aimed at a part
+ *    the archetype drew, which a bespoke scene does not draw;
+ *  - a beat the planner marked `bespoke: false`.
+ *
+ * The planner's `bespoke: true` is a strong hint, not an order: it adds a large
+ * bonus, so it wins a tie with anything, but an ineligible beat stays ineligible.
+ */
+import type { z } from "zod";
+import type { Beat, segmentSchema } from "../types.js";
+type Segment = z.infer<typeof segmentSchema>;
+export interface Pick {
+    beatId: string;
+    score: number;
+    /** Why it scored what it did, for `bespoke.json`. */
+    why: string[];
+}
+export interface Skip {
+    beatId: string;
+    reason: string;
+}
+export interface Selection {
+    picked: Pick[];
+    skipped: Skip[];
+}
+export interface SelectOptions {
+    /** Hashed with each beat id to break ties, so two decks tie differently. */
+    seed: string;
+    /** Narration, by beat id. A beat without segments is ineligible. */
+    narration?: Readonly<Record<string, readonly Segment[]>>;
+    /** Fewest beats to aim for when that many are eligible. Default 4. */
+    min?: number;
+    /** Most beats. Default 6; the call cap may lower it further. */
+    max?: number;
+}
+/** The number of beats a deck of `n` kept beats aims for: a third, held to [min, max]. */
+export declare function target(n: number, min?: number, max?: number): number;
+export declare function selectBespoke(beats: readonly Beat[], opts: SelectOptions): Selection;
+export {};

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

@@ -0,0 +1,26 @@
+export interface SheetFrame {
+    label: string;
+    png: Buffer;
+}
+/** Columns of 640x360 cells; the frames are 1920x1080. */
+export declare function contactSheet(frames: readonly SheetFrame[], path: string, cols?: number): Promise<void>;
+/** Several contact sheets in one Chrome (a probe round draws one per scene). */
+export declare function contactSheets(sheets: ReadonlyArray<{
+    frames: readonly SheetFrame[];
+    path: string;
+}>, cols?: number): Promise<void>;
+/**
+ * The deck's copy of an illustration, and the draft call's copy with its
+ * subjects boxed and numbered, drawn on a canvas by the same Chrome. WebP,
+ * because a flat picture's PNG is 1-2 MB and its WebP at 0.84 is ~5-10% of
+ * that (round 3 shipped 7-10 MB of PNG per deck); the repository has no image
+ * encoder, and Chrome is already every gate's dependency.
+ */
+export declare function pictureCopies(png: Buffer, boxes: ReadonlyArray<readonly [number, number, number, number]>, feather?: {
+    width: number;
+    height: number;
+}, quality?: number): Promise<{
+    webp: Buffer;
+    boxed: Buffer;
+    feathered: boolean;
+}>;