@jokerized/decksmith 0.9.3 → 0.9.4

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

@@ -1,8 +1,9 @@
 import type { Theme } from "../emit/kit.js";
 import type { Runner } from "../plan/codex.js";
+import type { DepthInfo } from "./depth.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";
+export declare const ART_VERSION = "art-4";
 /** 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. */
@@ -23,12 +24,75 @@ export interface ArtRef {
     png?: string;
     /** The PNG with its subjects boxed and numbered, for the draft call (src/bespoke/sheet.ts). */
     boxed?: string;
+    /** The backdrop with the subjects over it as the box shows them: what the draft call sees first. */
+    composite?: 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;
+    /**
+     * ROUND 5: the subjects are drawn on a transparent ground (`cutout`) in
+     * front of a BACKDROP of their setting, drawn in the same call: the scene is
+     * a full environment, and the two layers move at different rates (parallax).
+     */
+    cutout?: boolean;
+    plate?: PlateRef;
+    /** The subjects, as the illustrator names them (the deck's repetition check reads these). */
+    motifs?: string[];
+    /** The setting, in the illustrator's words. */
+    setting?: string;
+    /** Vision's feature print of the subjects over the pack's ground (src/bespoke/inspect.ts). */
+    print?: number[];
+    /** ROUND 6: the picture as depth planes the shell's camera moves through (src/bespoke/depth.ts). */
+    depth?: DepthRef;
+}
+/** One backdrop plane: frame-shaped, at distance `z` (the subjects' plane is 1). */
+export interface PlaneRef {
+    name: string;
+    file: string;
+    z: number;
+    /** Its out-of-focus twin (rack focus cross-fades to it; src/bespoke/sheet.ts `SOFT_PX`). */
+    soft: {
+        name: string;
+        file: string;
+    };
+}
+/** One subject cut out on its own plane: its box in frame px, 1-based `subject`. */
+export interface SubjectPlaneRef extends PlaneRef {
+    subject: number;
+    box: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+/** A picture's depth planes (round 6), for the frame they were cut for. */
+export interface DepthRef {
+    /** The frame the planes cover, px: a picture is re-cut for another. */
+    frame: {
+        width: number;
+        height: number;
+    };
+    /** The picture's own pixels per frame px at rest (after any upscale), at most `PLANE_SCALE`. */
+    scale: number;
+    /** Backdrop planes, far to near. */
+    planes: PlaneRef[];
+    subjects: SubjectPlaneRef[];
+    info: DepthInfo;
+}
+/** A picture's backdrop: its own files beside the subjects'. */
+export interface PlateRef {
+    /** The file name under the deck's `assets/bespoke/`. */
+    name: string;
+    /** Where the deck's bytes are (the cache). */
+    file: string;
+    /** The PNG as drawn. */
+    png: string;
+    width: number;
+    height: number;
 }
 /** What the inspection said about the picture kept, and how many draws it took. */
 export interface ArtCheck {
@@ -53,12 +117,19 @@ export interface ArtBrief {
     context: string;
     theme: Theme;
     pack: string;
+    /** The scene's visual device (`assignDevices`): the picture shows what that device acts on. */
+    device?: string;
+    /** The deck plan's setting and subjects for this picture (`assignDevices`, round 5). */
+    setting?: string;
+    subjects?: readonly string[];
+    /** A data beat (round 6: illustrated too): the subjects are the quantities. */
+    data?: boolean;
 }
 /** 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 required: readonly ["ok", "file", "plate", "reason", "depicts", "setting", "subjects"];
     readonly properties: {
         readonly ok: {
             readonly type: "boolean";
@@ -70,6 +141,13 @@ export declare const ART_SCHEMA: {
                 readonly type: "null";
             }];
         };
+        readonly plate: {
+            readonly anyOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "null";
+            }];
+        };
         readonly reason: {
             readonly anyOf: readonly [{
                 readonly type: "string";
@@ -80,6 +158,15 @@ export declare const ART_SCHEMA: {
         readonly depicts: {
             readonly type: "string";
         };
+        readonly setting: {
+            readonly type: "string";
+        };
+        readonly subjects: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
     };
 };
 /** The art key: everything the picture is drawn from. */
@@ -93,7 +180,18 @@ export declare function artKey(brief: ArtBrief, model: string): string;
  * 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;
+/**
+ * Subjects the illustrator reaches for when an idea is abstract, and which
+ * then turn up in every picture of a deck: round 4's pictures were a friendly
+ * robot in 34 of 38 (MEASURED 2026-10-10, both runs of four decks). Forbidden
+ * unless the beat itself is about one (`stockAllowed`).
+ */
+export declare const STOCK_MOTIFS: readonly ["robot", "android", "cyborg", "mascot", "humanoid", "brain", "light bulb", "lightbulb", "gear", "cog", "computer monitor", "laptop", "magnifying glass"];
+/** The stock motifs this beat's own words name, which it may therefore draw. */
+export declare function stockAllowed(b: Pick<ArtBrief, "headline" | "intent" | "claim" | "narration" | "context">): string[];
+export declare function artPrompt(b: ArtBrief, retry?: string, avoid?: readonly string[]): string;
+/** Whether a pack's ground is dark (relative luminance under 0.2): its backdrops must be lit. */
+export declare function darkGround(hex: string): boolean;
 /** 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;
@@ -112,6 +210,51 @@ interface ArtMeta {
     subjects?: UnitBox[];
     check?: ArtCheck;
     feathered?: boolean;
+    cutout?: boolean;
+    plate?: {
+        width: number;
+        height: number;
+    };
+    motifs?: string[];
+    setting?: string;
+    print?: number[];
+    depth?: {
+        frame: {
+            width: number;
+            height: number;
+        };
+        scale: number;
+        planes: Array<{
+            z: number;
+        }>;
+        subjects: Array<{
+            z: number;
+            subject: number;
+            box: SubjectPlaneRef["box"];
+        }>;
+        info: DepthInfo;
+    };
+}
+/** What `ArtCache.putDepth` stores: the planes' bytes with their distances. */
+export interface DepthCopies {
+    frame: {
+        width: number;
+        height: number;
+    };
+    scale: number;
+    planes: Array<{
+        webp: Buffer;
+        soft: Buffer;
+        z: number;
+    }>;
+    subjects: Array<{
+        webp: Buffer;
+        soft: Buffer;
+        z: number;
+        subject: number;
+        box: SubjectPlaneRef["box"];
+    }>;
+    info: DepthInfo;
 }
 /** Copies a picture may have beside its PNG: the deck's WebP, the draft call's boxed PNG. */
 export interface ArtCopies {
@@ -119,6 +262,10 @@ export interface ArtCopies {
     boxed?: Buffer;
     /** The WebP's edges are feathered into transparency for the beat's box. */
     feathered?: boolean;
+    /** The backdrop's deck copy (feathered WebP), when there is a backdrop. */
+    plateWebp?: Buffer;
+    /** What the draft call is shown: the backdrop with the subjects over it, as the box shows them. */
+    composite?: Buffer;
 }
 /**
  * Pictures beside the scene cache, under `art/`: `<key>.png` (as drawn),
@@ -129,8 +276,12 @@ export declare class ArtCache {
     readonly dir: string;
     constructor(dir: string);
     private ref;
+    private depthRef;
+    /** Store a picture's depth planes (round 6) beside it, and return the picture with them. */
+    putDepth(key: string, d: DepthCopies): Promise<ArtRef | undefined>;
+    private write;
     get(key: string): Promise<ArtRef | undefined>;
-    put(key: string, bytes: Buffer, meta: Omit<ArtMeta, "version" | "key">, copies?: ArtCopies): Promise<ArtRef>;
+    put(key: string, bytes: Buffer, meta: Omit<ArtMeta, "version" | "key">, copies?: ArtCopies, plate?: Buffer): Promise<ArtRef>;
 }
 export interface DrawArtOptions {
     run: Runner;
@@ -147,17 +298,28 @@ export interface DrawArtOptions {
     home?: string;
     /** Why the previous picture of this beat was rejected, for the second attempt. */
     retry?: string;
+    /** What the deck's other pictures show, so this one shows something else. */
+    avoid?: readonly 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<{
+/** What one art call drew: the subjects, and the backdrop when the tool drew one. */
+export interface Drawn {
     bytes: Buffer;
     width: number;
     height: number;
     depicts: string;
-}>;
+    setting: string;
+    motifs: string[];
+    plate?: {
+        bytes: Buffer;
+        width: number;
+        height: number;
+    };
+}
+export declare function drawArt(brief: ArtBrief, opts: DrawArtOptions): Promise<Drawn>;
 /**
  * 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
@@ -170,4 +332,8 @@ export declare function copyArt(entries: Iterable<{
 }>, out: string): Promise<string[]>;
 /** Where a deck's page finds an illustration. */
 export declare function artHref(art: ArtRef): string;
+/** Where a deck's page finds one of a picture's depth planes. */
+export declare function planeHref(p: {
+    name: string;
+}): string;
 export {};

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

@@ -34,6 +34,16 @@ export interface KeyInput {
     pack: unknown;
     /** The illustration's art key (src/bespoke/art.ts), when the scene was drawn around one. */
     art?: string;
+    /**
+     * The scene's visual device and its idea (`assignDevices`): both are in its
+     * prompt. The beat's own only — no other beat's device is in a scene's
+     * prompt, so editing one beat does not re-key the scenes after it.
+     */
+    device?: string;
+    idea?: string;
+    /** The camera grammar and the data build (round 5): both shape the prompt and the scene. */
+    grammar?: string;
+    build?: string;
 }
 export interface CacheEntry {
     version: number;

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

@@ -0,0 +1,66 @@
+/**
+ * Gate `card_row`: a generated scene whose main visual is the template the
+ * bespoke pass exists to replace — a row of cards, a column of panels, a grid
+ * of tiles. Round 2 and round 4 both recorded scenes that "still speak the
+ * language of labelled cards and connectors"; the prompt forbids it, and this
+ * is the cheap check that it was obeyed.
+ *
+ * STATIC, from the markup alone: every `<rect>` with literal geometry, moved by
+ * the `translate`/`scale` (and the `rotate(0)` or axis-aligned `matrix`) of the
+ * `<g>`s around it and by the `x`/`y`/`viewBox` of a nested `<svg>`, outside
+ * `<defs>`, clip paths, masks, patterns and symbols (a reveal's clip rect is not
+ * a card); and every `<div>` placed by `left`/`top`/`width`/`height` in px, in
+ * its inline style or in a `#id` rule of the scene's css. A card is a
+ * rect at least `MIN_SIDE` of the box on each side and under `MAX_W`/`MAX_H` of
+ * it (a ground or a band is not one). Cards are "alike" when both sides agree
+ * within `ALIKE`. The scene is flagged when three or more alike cards share a
+ * row (centres within half a card's height) or a column, or four make a grid —
+ * and together they cover at least `MIN_AREA` of the box, so a legend's swatches
+ * or a counter's plate never trip it.
+ *
+ * What it cannot see: cards drawn as `<path>`, positioned only by the script,
+ * placed by a `<use>`, rotated, or laid out by flex/grid/class rules rather than
+ * px boxes. It is a heuristic for the commonest case, not proof of a good scene
+ * — the critique round and a person judge the rest.
+ *
+ * A DATA beat is never asked (src/bespoke/pipeline.ts): its prompt asks for
+ * bars, and four bars of close values (PSNR 35.4 against 36.2) are alike
+ * rectangles in a row by every measure here.
+ */
+/** A card's sides, as shares of the body box. */
+export declare const MIN_SIDE = 0.08;
+export declare const MAX_W = 0.6;
+export declare const MAX_H = 0.8;
+/** Two cards are alike when each side is within this share of the other's. */
+export declare const ALIKE = 0.2;
+/** The cards of a row must cover this share of the box between them. */
+export declare const MIN_AREA = 0.12;
+/**
+ * Bump with any change to what `cardRow` flags. Part of the gate stamp a cached
+ * rejection carries (src/bespoke/pipeline.ts `GATE_STAMP`), so loosening this
+ * check releases the scenes it refused instead of keeping them archetypes.
+ */
+export declare const CARDS_VERSION = "cards-2:0.08/0.6/0.8/0.2/0.12";
+interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * The cards the markup draws, in box px. `css` is the scene's stylesheet: a
+ * `<div>` placed and sized by its `#id` rule is read like one placed inline.
+ */
+export declare function cardsOf(markup: string, box: {
+    width: number;
+    height: number;
+}, css?: string): Rect[];
+/**
+ * Why the scene's main visual is a card row or a tile grid, or undefined when
+ * it is not. The message names what was found, for the critique round.
+ */
+export declare function cardRow(markup: string, box: {
+    width: number;
+    height: number;
+}, css?: string): string | undefined;
+export {};

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

@@ -1,4 +1,3 @@
-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 {
@@ -10,11 +9,6 @@ export interface Fragment {
      * 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 {
@@ -40,8 +34,6 @@ export interface FragmentContext {
     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[];

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

@@ -0,0 +1,50 @@
+/**
+ * DATA BUILDS: how a data beat's chart comes on, chosen per beat so no two
+ * data beats of a deck build alike.
+ *
+ * WHY. Round 4 drew data beats as clean charts that build — and every one of
+ * them built the same way: bars grow from zero while their counters count up,
+ * no camera. An explainer varies the verb with the point: a ranking RACES, a
+ * trend is TRACED with a callout on the moment that matters, a gap is the
+ * DELTA highlighted, several series side by side are SMALL MULTIPLES lit one
+ * after another. And the camera works on a chart as on a picture: it pushes
+ * in on the value the voice names and pulls back for the whole.
+ *
+ * Each build is checked statically (`checkBuild`): the scene declares it on
+ * its root group (`data-build`) and carries the marks the build is made of
+ * (round 6: the camera is the scene's choice, no longer required — r1's smoke
+ * deck lost a data beat to that rule alone); the shell stamps it on the scene (`data-ds-build`) so the
+ * deck gate (`verify`) refuses two data beats that build alike.
+ *
+ * ROUND 6 dropped the bar race: bars growing from zero and sliding to their
+ * rank are the animated UI the founder called old-fashioned, and `ui_motion`
+ * refuses them. A chart's marks stand at their size and come on by drawing or
+ * fading; the camera and the voice carry the comparison.
+ */
+/** A data beat's build. */
+export type DataBuild = "line-callout" | "delta" | "small-multiples";
+export declare const BUILDS: readonly DataBuild[];
+/**
+ * The build for a data beat of `archetype`, given the builds of the data beats
+ * before it in deck order: the best fit the deck has not used; past three data
+ * beats, the best fit that is not the previous one.
+ */
+export declare function chooseBuild(archetype: string, prior: readonly DataBuild[]): DataBuild;
+/** What each build is, as the prompt says it. */
+export declare const BUILD_NOTES: Readonly<Record<DataBuild, string>>;
+/** One reason a data scene does not build as asked. */
+export interface BuildFinding {
+    rule: "data_build";
+    message: string;
+}
+/**
+ * Whether a data scene builds as `build` asks: it declares the build on a
+ * group, carries the marks the build is made of, animates them the build's
+ * way. Markup and script are the fragment's (token form).
+ */
+export declare function checkBuild(f: {
+    markup: string;
+    script: string;
+}, build: DataBuild): BuildFinding[];
+/** The data builds of a deck's kept data scenes, in deck order, and which repeat. */
+export declare function buildRepeats(seq: readonly string[]): string[];

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

@@ -0,0 +1,127 @@
+import type { DepthCopies } from "./art.js";
+/** The Core ML package's directory name. */
+export declare const DEPTH_MODEL_NAME = "DepthAnythingV2SmallF16.mlpackage";
+/** The ncnn model the upscaler is run with (x2). */
+export declare const UPSCALE_MODEL = "realesr-animevideov3";
+/** How the planes of one picture were made, for the report. */
+export interface DepthInfo {
+    /** "depth-anything-v2-small" when the model ran; "flat" when it did not. */
+    model: "depth-anything-v2-small" | "flat";
+    /** Why it is flat. */
+    reason?: string;
+    /** 2 when the picture was upscaled before slicing; 1 when it was not (and why). */
+    upscale: number;
+    upscaleReason?: string;
+}
+/** `~/.cache/decksmith`, where the optional models live. */
+export declare function decksmithCache(env?: NodeJS.ProcessEnv): string;
+/** The depth model's path, or the reason there is none. */
+export declare function depthModel(env?: NodeJS.ProcessEnv, platform?: string): Promise<{
+    path: string;
+} | {
+    reason: string;
+}>;
+/** The upscaler's binary and its models folder, or the reason there is none. */
+export declare function upscaler(env?: NodeJS.ProcessEnv): Promise<{
+    bin: string;
+    models: string;
+} | {
+    reason: string;
+}>;
+/**
+ * The Swift helper: `depth <model> <in.png> <out.png>`. The package is compiled
+ * on first use and the compiled model kept beside the helper, so later pictures
+ * skip the compile. CPU only: the answer is cached per picture, and the CPU's
+ * is the one that does not change with what else the GPU is doing.
+ */
+export declare const DEPTH_SWIFT = "import Foundation\nimport CoreML\nimport CoreImage\nimport ImageIO\nimport Vision\n\nlet a = CommandLine.arguments\nfunc fail(_ m: String) -> Never { FileHandle.standardError.write((m + \"\\n\").data(using: .utf8)!); exit(1) }\nguard a.count == 5 else { fail(\"usage: depth <model.mlpackage> <compiled dir> <in.png> <out.png>\") }\nlet pkg = URL(fileURLWithPath: a[1])\nlet compiled = URL(fileURLWithPath: a[2])\ndo {\n  if !FileManager.default.fileExists(atPath: compiled.path) {\n    let tmp = try MLModel.compileModel(at: pkg)\n    try? FileManager.default.createDirectory(at: compiled.deletingLastPathComponent(), withIntermediateDirectories: true)\n    let staged = compiled.deletingLastPathComponent().appendingPathComponent(UUID().uuidString + \".mlmodelc\")\n    try FileManager.default.moveItem(at: tmp, to: staged)\n    if (try? FileManager.default.moveItem(at: staged, to: compiled)) == nil { try? FileManager.default.removeItem(at: staged) }\n  }\n  let cfg = MLModelConfiguration()\n  cfg.computeUnits = .cpuOnly\n  let model = try MLModel(contentsOf: compiled, configuration: cfg)\n  guard let (inName, inDesc) = model.modelDescription.inputDescriptionsByName.first,\n        let c = inDesc.imageConstraint,\n        let outName = model.modelDescription.outputDescriptionsByName.keys.first else { fail(\"not an image model\") }\n  guard let src = CGImageSourceCreateWithURL(URL(fileURLWithPath: a[3]) as CFURL, nil),\n        let img = CGImageSourceCreateImageAtIndex(src, 0, nil) else { fail(\"cannot read the picture\") }\n  let fv = try MLFeatureValue(cgImage: img, constraint: c, options: [.cropAndScale: VNImageCropAndScaleOption.scaleFill.rawValue])\n  let out = try model.prediction(from: MLDictionaryFeatureProvider(dictionary: [inName: fv]))\n  guard let pb = out.featureValue(for: outName)?.imageBufferValue else { fail(\"no depth image\") }\n  try CIContext().writePNGRepresentation(of: CIImage(cvPixelBuffer: pb), to: URL(fileURLWithPath: a[4]), format: .RGBA8, colorSpace: CGColorSpace(name: CGColorSpace.sRGB)!)\n  print(\"{\\\"width\\\":\\(CVPixelBufferGetWidth(pb)),\\\"height\\\":\\(CVPixelBufferGetHeight(pb))}\")\n} catch { fail(\"\\(error)\") }\n";
+/**
+ * The backdrop's depth as a grey RGBA PNG (Depth Anything's relative inverse
+ * depth: brighter is nearer; RGBA because the repository's PNG reader takes
+ * no greyscale), at the model's own 518x392. Rejects with why.
+ */
+export declare function estimateDepth(png: string, out: string, toolDir: string, model: string): Promise<void>;
+/** `in.png` upscaled 2x into `out.png`, alpha kept. Rejects with why. */
+export declare function upscale2x(png: string, out: string, up: {
+    bin: string;
+    models: string;
+}): Promise<void>;
+/**
+ * Where to cut the backdrop into planes: depth quantiles of its pixels (a far
+ * plane for the farther half, a middle and a near one), merged where two
+ * planes would sit closer than `MIN_SEPARATION` in depth — a plane that moves
+ * like its neighbour is bytes for nothing. `values` is the depth map's pixels
+ * (0..255). Returns the cut points (0..1, ascending) — none for a flat picture.
+ */
+export declare const CUT_QUANTILES: readonly [0.5, 0.82];
+export declare const MIN_SEPARATION = 0.12;
+export declare function depthCuts(values: ArrayLike<number>): number[];
+/**
+ * The nearest and farthest a plane may be put, in subject-plane units. A plane
+ * at z zooms by z / (z - (1 - 1/s)) when the camera pushes to s: MEASURED
+ * 2026-10-10 on the first r6 deck, a foreground plane at 0.6 swung to 2.7x on a
+ * 1.6x push and filled half the frame with a blurred wall. At 0.8 it is 1.9x.
+ */
+export declare const Z_NEAR = 0.8;
+export declare const Z_FAR = 3;
+/** Subjects stay within this range of the reference plane: their boxes are the camera's targets. */
+export declare const SUBJECT_Z: readonly [number, number];
+/**
+ * A plane's distance from the camera, from its relative inverse depth `u`
+ * (0 far .. 1 near), with the subjects' typical `u` at distance 1 — the plane
+ * the shell's camera frames (`#sid-cam`). Depth Anything's output is affine-
+ * invariant disparity, so `0.35` stands in for its unknown shift: a far wall
+ * at u≈0.1 lands at ~2x the subjects' distance, a near floor at ~0.75x.
+ */
+export declare function zOf(u: number, uRef: number): number;
+/** A subject's distance: where it stands on the backdrop, held near the reference plane. */
+export declare function subjectZ(uFoot: number, uRef: number): number;
+/**
+ * The depth under each subject's foot (the bottom centre of its box, a little
+ * inside), read from the backdrop's depth map. Boxes are shares of the
+ * picture; `depth` is the map, row-major, `w` x `h`.
+ */
+export declare function footDepths(depth: ArrayLike<number>, w: number, h: number, boxes: ReadonlyArray<readonly [number, number, number, number]>): number[];
+/** What `cutPicture` is given: a drawn picture, and where to work. */
+export interface CutInput {
+    /** The subjects' picture (transparent ground), or the whole picture when there is no backdrop. */
+    subjects: Buffer;
+    /** The backdrop, when the illustrator drew one. */
+    plate?: Buffer;
+    /** The subjects' boxes, shares of the subjects' picture (src/bespoke/inspect.ts). */
+    boxes: ReadonlyArray<readonly [number, number, number, number]>;
+    /** The frame the planes must cover, px. */
+    frame: {
+        width: number;
+        height: number;
+    };
+    /** Scratch for the intermediate PNGs. */
+    work: string;
+    tag: string;
+    /** Where the compiled helpers live (the inspection's). */
+    toolDir: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * A drawn picture cut into depth planes for the shell's camera: upscaled 2x
+ * when the upscaler is there, its backdrop's depth estimated when the model is
+ * there, sliced (sheet.ts `depthPlanes`), and every plane and subject given a
+ * distance. Each optional step that cannot run is recorded in `info` and the
+ * cut goes on without it; only a Chrome that cannot draw the planes throws.
+ */
+export declare function cutPicture(i: CutInput): Promise<DepthCopies>;
+/** A flat picture's backdrop distance: it moves at half the subjects' zoom, as round 5's did. */
+export declare const FLAT_Z = 2;
+/** The subjects' depth is at least this much nearer than the backdrop's farthest band (relative inverse depth). */
+export declare const REF_BEHIND = 0.15;
+/**
+ * The depth the camera's plane (distance 1) is put at: the subjects' median
+ * foot, held IN the scene — at least `REF_BEHIND` nearer than the backdrop's
+ * farthest band and no nearer than its nearest — whatever the feet read (a
+ * subject drawn high in its picture can land on the far wall of the
+ * backdrop's map). MEASURED 2026-10-10: one picture's feet read farther than
+ * every backdrop band, every plane landed nearer than the subjects, and the
+ * backdrop zoomed MORE than they did (shot_variety: "no parallax").
+ * `bands` are the planes' mean depths, far to near.
+ */
+export declare function referenceDepth(feet: readonly number[], bands: readonly number[]): number;

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

@@ -0,0 +1,73 @@
+/**
+ * SHOT GRAMMARS: how the shell's camera tells one illustrated scene, chosen per
+ * beat by what the narration is doing, and never the same on two scenes in a row.
+ *
+ * WHY. Round 4 staged every illustrated scene in one grammar — the whole
+ * picture, a push in on each subject the voice names, the whole again. That is
+ * how an explainer cuts one shot, and also, scene after scene, the "same
+ * animation every card" the founder dislikes, one level up. An explainer
+ * editor picks the move by the sentence: two things weighed against each other
+ * get a rack between them; a process gets a camera that travels along it; a
+ * "turns out" gets a close detail that pulls back to show where it sits; a
+ * number gets a hard cut to the thing measured. So does this file:
+ *
+ *   tour      establish → push in on each named subject → reveal (round 4's)
+ *   follow    establish → push in on the first subject → TRACK along the
+ *             others at one scale, slow and continuous (a process, a pipeline)
+ *   rack      establish → A → whip to B → back to A → a two-shot of both →
+ *             reveal (a comparison, a cause and its effect)
+ *   zoom-out  OPENS CLOSE on the key detail, pulls back to a two-subject
+ *             frame, then to the whole (a reveal of context)
+ *   wipe      the picture is wiped on subject by subject as the voice names
+ *             each, the camera wide and creeping (a reveal, a sequence)
+ *   cutaway   wide, and HARD CUTS to a close insert of what is measured, then
+ *             back (a number, a detail)
+ *   parallax  a slow lateral truck across the scene at a medium scale, the
+ *             backdrop sliding slower than the subjects (a setting, a definition)
+ *
+ * The role is read from the beat deterministically (archetype, then the
+ * narration's own words in en/ko/zh/ja); the grammar is the role's best fit
+ * that the deck has not just used. `chooseGrammar` is a pure function of the
+ * role and the grammars before it, so it slots into the up-front, deck-order
+ * device pass (`assignDevices`) as one more field beside a beat's device.
+ */
+/** What the narration of a beat is doing, rhetorically. */
+export type Role = "compare" | "cause" | "process" | "reveal" | "quantify" | "define";
+export declare const ROLES: readonly Role[];
+/** How the shell's camera tells an illustrated scene. */
+export type Grammar = "tour" | "follow" | "rack" | "zoom-out" | "wipe" | "cutaway" | "parallax";
+export declare const GRAMMARS: readonly Grammar[];
+/** Each role's grammars, best fit first. Every grammar appears for every role, so a choice always exists. */
+export declare const FIT: Readonly<Record<Role, readonly Grammar[]>>;
+/**
+ * The role a beat plays: its archetype's prior (two, or one for a generic
+ * layout) against the narration's own signals (each match one, at most three
+ * per role). Ties go to the more specific role.
+ */
+export declare function roleOf(beat: {
+    archetype: string;
+    intent?: string;
+    claim?: string;
+    narration?: string;
+}): Role;
+/**
+ * The grammar for a beat of role `role`, given the grammars of the illustrated
+ * beats before it in deck order: best fit first, one the deck has not used,
+ * else one not used by the last two — so never the previous one.
+ * Deterministic.
+ */
+export declare function chooseGrammar(role: Role, prior: readonly Grammar[]): Grammar;
+/** `chooseGrammar` over a deck's beats in order. */
+export declare function assignGrammars(roles: readonly Role[]): Grammar[];
+/**
+ * A deck's grammars as the gate reads them: how many distinct ones, and which
+ * consecutive pairs repeat. `seq` is the deck's illustrated scenes in order.
+ */
+export declare function grammarRepeats(seq: readonly string[]): {
+    distinct: number;
+    adjacent: Array<[number, string]>;
+};
+/** The wanted diversity of `n` illustrated scenes: all different up to four, then at least four. */
+export declare function diversityWanted(n: number): number;
+/** What the prompt tells a scene its grammar does, so its shot list and its own motion fit it. */
+export declare const GRAMMAR_NOTES: Readonly<Record<Grammar, string>>;