@jokerized/decksmith 0.9.2 → 0.9.4

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

@@ -1,30 +1,3 @@
-/**
- * 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. */
@@ -87,16 +60,37 @@ export declare function fitPlates(markup: string, frames: readonly Geo[] | Geo |
 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>`).
+ * are the probe's `tag:index[#id]@opacity`, ids in the probe deck's form
+ * (`sid-…`); an element without an id gets one (`SCENEID-lit<k>`). The opacity
+ * each holds is its tween's from state (every tween is a fromTo); a target
+ * without one is left alone.
  */
 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. */
+/**
+ * The lowest opacity a word is dimmed to: dark ink at 0.6 over a pale ground
+ * is ~4:1, a pack tone ~3:1 (the `dim_text` floor). The prompt asks for it.
+ */
+export declare const TEXT_ALPHA_MIN = 0.6;
+/** The ids in `markup` whose element is, or holds, words (an SVG <text>, or text of its own). */
+export declare function textHolders(markup: string): Set<string>;
+/**
+ * `dim_text`'s repair: every literal `opacity`/`autoAlpha` in (0, TEXT_ALPHA_MIN)
+ * in a `tl.*`/`gsap.set` whose targets — `#id` selectors, literally or through a
+ * top-level variable — include an element holding words, raised to
+ * TEXT_ALPHA_MIN. Undefined when there is nothing it can read to lift.
+ */
+export declare function liftText(f: Fragment): {
+    fragment: Fragment;
+    lifted: number;
+} | undefined;
 export interface RepairNote {
     /** Overlapping tweens on one property were untangled (`seek_order`). */
     untangled?: boolean;
+    /** Dimming opacities on words raised to `TEXT_ALPHA_MIN` (`dim_text`). */
+    lifted?: number;
     moved: number;
     /** Plates grown to hold their text (`fitPlates`). */
     grown?: number;

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

@@ -1,9 +1,10 @@
-import type { EmitContext, Scene } from "../emit/kit.js";
-import type { Beat } from "../types.js";
+import type { EmitContext, Scene, Theme } from "../emit/kit.js";
+import type { Beat, Format } 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";
+import type { DataBuild } from "./databuild.js";
+import type { Grammar } from "./grammar.js";
+import { type Box, type Staging } from "./shots.js";
 /** One beat's bespoke scene, ready to emit. */
 export interface BespokeEntry {
     /** Token form, already through `checkFragment`. */
@@ -24,6 +25,10 @@ export interface BespokeEntry {
         }>;
         duration: number;
     };
+    /** The camera grammar an illustrated scene is staged in (src/bespoke/grammar.ts). Absent: "tour". */
+    grammar?: Grammar;
+    /** A data scene's build (src/bespoke/databuild.ts), stamped on the scene for the deck gate. */
+    build?: DataBuild;
 }
 /** The file `build` writes beside a deck with the bespoke pass's account of itself. */
 export declare const BESPOKE_FILE = "bespoke.json";
@@ -36,8 +41,29 @@ export declare function bespokeRegion(beat: Beat, ctx: Pick<EmitContext, "format
     width: number;
     height: number;
 };
+/**
+ * ROUND 6: an illustrated scene is the whole frame. Its picture is a full-bleed
+ * shot behind the deck's own headline (which keeps its place and its entrance),
+ * so its box is the frame, and the headline's band at the top is the one place
+ * the scene's own words may not go (`chromeBand`).
+ */
+export declare function cineRegion(format: Format): {
+    width: number;
+    height: number;
+};
+/** How far down the frame the headline reaches, px: the scene's own words stay below it. */
+export declare function chromeBand(beat: Beat, ctx: Pick<EmitContext, "format" | "theme">): number;
 /** Whether a scene's script moves the shell's camera (`#SCENEID-cam`). */
 export declare function usesCamera(script: string): boolean;
+/**
+ * The shell's (round 6): every word under a scene's own camera keeps the size it
+ * declares. For each camera tween — the wrapper's `scale`, or the svg's
+ * `viewBox` — the words get the inverse scale about their own centres over the
+ * same span, so a push-in enlarges the drawing and never the type (the r1
+ * review found labels at 75-80px under zoom; `type_scale` holds the rendered
+ * size). Tweens marked `data: "shell"`, which `ui_motion` does not count.
+ */
+export declare function quietWords(sid: string): string;
 /**
  * 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
@@ -49,7 +75,7 @@ export declare function usesCamera(script: string): boolean;
 export declare function withArt(markup: string, art: ArtRef | undefined, box?: {
     width: number;
     height: number;
-}): string;
+}, clip?: string): 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
@@ -57,18 +83,37 @@ export declare function withArt(markup: string, art: ArtRef | undefined, box?: {
  */
 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.
+ * An illustrated entry's subjects in box px and the camera moves its shots
+ * compile to. In a depth scene (round 6) the subjects are where the depth
+ * planes put them.
  */
 export declare function staging(entry: BespokeEntry, box: {
     width: number;
     height: number;
 }): {
     subjects: Box[];
-    zones: Zone[];
-    moves: CamMove[];
+    staged: Staging;
 };
+/** The picture's subjects in box px: from its depth planes when it has them. */
+export declare function subjectsOf(art: ArtRef, box: {
+    width: number;
+    height: number;
+}): Box[];
+/**
+ * ROUND 6: the picture as depth planes, far to near, each a frame-sized layer
+ * the camera script moves at its own distance (shots.ts `planeFrame`). The
+ * backdrop's planes cover the frame; each subject is its own plane, holding a
+ * `.ds-life` wrapper its breathing moves. Then the air in front of them: the
+ * light that sweeps, the vignette, and the scrims under the headline and the
+ * subtitles. Nothing here is text, and the farthest plane keeps round 5's
+ * `#sid-plate` id (the gates read the backdrop's parallax off it). A plane in
+ * a push-in is mostly outside the frame by design, so each carries
+ * hyperframes' `data-layout-allow-overflow` (its `escaped_container` warning
+ * would otherwise send every scene to a critique call).
+ */
+export declare function depthLayers(sid: string, art: ArtRef, W: number, H: number, theme: Theme, band: number): string;
+/** `#rrggbb` with an alpha, as `rgba()`. */
+export declare function hexA(hex: string, a: number): string;
 /** 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). */

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

@@ -1,29 +1,36 @@
 /**
- * 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.
+ * Which beats get a bespoke scene: under `--design v2`, every beat that can
+ * have one — title, numbers, comparisons and closing claims as well as
+ * mechanisms. Until 2026-10-10 this picked 4-6 "mechanism" beats and left the
+ * rest to the archetype templates; the founder's verdict on those ("why do I
+ * need to see those hardcoded same UI blocks in every slide") is why the
+ * templates are now only the fallback for a scene that fails its gates.
  *
- * 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;
+ * WHAT NEVER QUALIFIES:
+ *  - a beat with no narration cue: 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`.
+ *  - a beat the planner marked `bespoke: false` that cites a figure or a table
+ *    of the paper — the two reasons the planner is told a `false` is for (a
+ *    real figure the viewer must see, a table read row by row).
+ *
+ * A `false` on a beat that cites NEITHER is not obeyed (2026-10-10). r3's
+ * b12 was one: a comparison citing only a section, which the planner kept as
+ * six grey row plates held still for 16 seconds — exactly the "hardcoded UI
+ * blocks" the founder named, and with nothing the archetype had to keep.
  *
- * 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.
+ * Deterministic, so the same storyboard always asks about the same beats and a
+ * cache hit is a cache hit. When the call cap cannot pay two calls for every
+ * beat (`max`), the most mechanical beats are drawn and the rest keep their
+ * archetype. Picks come back in deck order.
  */
 import type { z } from "zod";
 import type { Beat, segmentSchema } from "../types.js";
 type Segment = z.infer<typeof segmentSchema>;
 export interface Pick {
     beatId: string;
+    /** Priority when the cap cannot pay for every beat. */
     score: number;
     /** Why it scored what it did, for `bespoke.json`. */
     why: string[];
@@ -39,14 +46,14 @@ export interface Selection {
 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, by beat id. A beat without a cue 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. */
+    /**
+     * Most beats: what the call cap pays for at two calls a beat. When fewer
+     * than the eligible, the most mechanical win (a mechanism gains most from a
+     * scene that moves with the voice); the rest keep their archetype.
+     */
     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

@@ -9,18 +9,83 @@ export declare function contactSheets(sheets: ReadonlyArray<{
     frames: readonly SheetFrame[];
     path: string;
 }>, cols?: number): Promise<void>;
+/** The resolution planes are stored at, as a multiple of the frame: sharp up to this push-in. */
+export declare const PLANE_SCALE = 1.4;
+/**
+ * How out of focus a plane's soft twin is, frame px. Rack focus cross-fades a
+ * plane with this twin instead of tweening a CSS blur: MEASURED 2026-10-10 in
+ * the gates' browser (SwiftShader), a CSS \`filter: blur()\` on six frame-sized
+ * layers cost ~1.5s a frame (2.2s against 0.55s without), which made one deck's
+ * motion gates take 672s.
+ */
+export declare const SOFT_PX = 6;
+/** One backdrop plane as the deck stores it: frame-shaped, covering the frame at rest. */
+export interface PlaneCopy {
+    webp: Buffer;
+    /** The same plane out of focus: blurred `SOFT_PX`, stored at a quarter of the size. */
+    soft: Buffer;
+    /** Mean relative inverse depth of the band it holds (0 far .. 1 near); absent when flat. */
+    u?: number;
+}
+/** One subject, cut out of the subjects' picture: its own WebP and its box in frame px. */
+export interface SubjectCopy {
+    /** Which subject (0-based, the inspection's left-to-right order). */
+    index: number;
+    webp: Buffer;
+    soft: Buffer;
+    box: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+/**
+ * ROUND 6. The backdrop sliced into depth planes (src/bespoke/depth.ts), and
+ * each subject cut out on its own, every one already cropped to what covers
+ * `frame` and stored at `PLANE_SCALE` times it. A plane holds its depth band's
+ * real pixels; where a NEARER band covers it, it holds colours pushed and
+ * pulled in from its own band at quarter resolution — what a nearer plane
+ * uncovers when it slides — and it is transparent where nothing at or behind
+ * its band is. The farthest plane is opaque everywhere. Without a depth map
+ * (`depth` undefined) the backdrop is one plane. The pixel work runs at a
+ * quarter of the stored size and the full-size planes are composited by the
+ * canvas, so a picture takes ~3s, not minutes (MEASURED 2026-10-10: a per-pixel
+ * pass at full size did not finish in 10 minutes).
+ */
+export declare function depthPlanes(plate: Buffer, depth: Buffer | undefined, cuts: readonly number[], subjects: Buffer, boxes: ReadonlyArray<readonly [number, number, number, number]>, frame: {
+    width: number;
+    height: number;
+}, quality?: number): Promise<{
+    planes: PlaneCopy[];
+    subjects: SubjectCopy[];
+    scale: number;
+}>;
 /**
  * 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.
+ *
+ * ROUND 5, two layers. With a backdrop (`plate`) the subjects stand in front
+ * of it: the subjects' copy keeps its transparent ground (a picture drawn on a
+ * flat ground after all is keyed: its ground made transparent), the backdrop
+ * gets the feathered edges, and `composite` is the two as the box shows them
+ * (each scaled to cover the box, centred) — what the draft call is shown, with
+ * `boxed` drawn over it in the same coordinates.
  */
 export declare function pictureCopies(png: Buffer, boxes: ReadonlyArray<readonly [number, number, number, number]>, feather?: {
     width: number;
     height: number;
-}, quality?: number): Promise<{
+}, quality?: number, opts?: {
+    plate?: Buffer;
+    ground?: string;
+    cutout?: boolean;
+}): Promise<{
     webp: Buffer;
     boxed: Buffer;
     feathered: boolean;
+    plateWebp?: Buffer;
+    composite?: Buffer;
 }>;

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

@@ -21,7 +21,16 @@
  *
  * Shots closer than `MIN_HOLD` to the previous one are dropped: a shot the
  * audience cannot read is a shake.
+ *
+ * A SECOND GRAMMAR, `close-open` (2026-10-10): one grammar for every
+ * illustrated scene made every one of them move alike — r1's three illustrated
+ * scenes were the same tour of three subjects in a row, and read as a template.
+ * `close-open` OPENS CLOSE on the subject of the first shot, held from t=0, moves
+ * subject to subject, and opens out to the whole picture only at the reveal —
+ * the picture is discovered rather than surveyed. The pass alternates the two
+ * over a deck's illustrated beats in deck order.
  */
+import type { Grammar } from "./grammar.js";
 import type { UnitBox } from "./inspect.js";
 /** One entry of a scene's shot list: on cue `cue` (1-based), `at` of the way in, frame `subject` (0 = the whole picture). */
 export interface Shot {
@@ -44,8 +53,10 @@ export interface CamMove {
     x: number;
     y: number;
     ease: string;
-    /** The subject framed (0 = the whole picture). */
+    /** The subject framed (0 = the whole picture, or a two-shot). */
     subject: number;
+    /** What kind of move it is in its grammar (the report and the gates read it). */
+    kind?: "push" | "whip" | "track" | "cut" | "pull" | "two-shot" | "creep" | "reveal";
 }
 /** The camera's largest push-in: past it a picture turns to mush. */
 export declare const CAMERA_MAX_SCALE = 2.2;
@@ -59,15 +70,14 @@ export declare const REVEAL = 1.3;
 export declare const MIN_HOLD = 1.6;
 /** The establishing shot holds at least this long into the first cue. */
 export declare const ESTABLISH = 1.6;
+/** A held shot creeps this much further in, so a hold is never a still frame. */
+export declare const CREEP = 1.03;
 /**
- * The band at the top of an illustrated scene's box that the picture leaves
- * clear: the subjects' labels go above them (src/bespoke/callouts.ts), and a
- * picture that covered the whole box put its subjects' heads at its top edge,
- * where the only room for a label was across the subject's face (round 4's
- * first full run, en s2: "observations" over a robot's eyes).
+ * Where the picture sits in the box: covering all of it. Round 4 kept a 120px
+ * band clear at the top for the shell's subject labels; round 6 draws no
+ * labels (the narration and the subtitles name the subjects), so the band and
+ * its labels are gone.
  */
-export declare const ART_BAND = 120;
-/** Where the picture sits in the body box: under the band, covering the rest. */
 export declare function artPlacement(box: {
     width: number;
     height: number;
@@ -86,34 +96,208 @@ export declare function subjectsInBox(units: readonly UnitBox[], art: {
     width: number;
     height: number;
 }): Box[];
-/** The inverse of `subjectsInBox` for boxes inside the placement: box px back to shares of the picture. */
-export declare function unitsInPicture(boxes: readonly Box[], art: {
+/**
+ * The camera's scale and offset that frame `b` (origin 0 0), held to the box's
+ * edges. `sMax` is the picture's own ceiling (`sharpMax`): past it the push-in
+ * shows the picture's pixels; `sMin` the closest a framing may be widened to.
+ */
+export declare function frameOn(b: Box, W: number, H: number, sMax?: number, sMin?: number): {
+    s: number;
+    x: number;
+    y: number;
+};
+/** The camera that puts point (cx, cy) of the box at the centre of the view at scale `s`, held to the box. */
+export declare function frameAt(cx: number, cy: number, s: number, W: number, H: number): {
+    s: number;
+    x: number;
+    y: number;
+};
+/**
+ * EFFECTIVE RESOLUTION. The image tool draws ~1.57 megapixels whatever it is
+ * asked (MEASURED 2026-10-10: 1672x941, 1774x887, 1915x821 — no size control
+ * exists on the tool). Covering a ~1730px-wide box, one picture pixel already
+ * spans ~0.9-1.0 output pixels, so a 2.2x push-in shows each picture pixel
+ * over ~2.2 output pixels: round 4's push-ins looked soft. The shell now caps
+ * every push-in at the scale where a picture pixel spans at most 1/`EFF_MIN`
+ * output pixels (`sharpMax`), and the report and the gate read the effective
+ * resolution at the closest shot (`effectiveAt`).
+ *
+ * ROUND 6 raises the bar from 0.6 to 0.85: pictures are upscaled 2x before they
+ * are cut into planes (src/bespoke/depth.ts), so a 1.55x push-in can be sharp.
+ * A picture that could not be upscaled is still pushed in at `PUSH_FLOOR` (the
+ * staging wins) and the report says how soft it was.
+ */
+export declare const EFF_MIN = 0.85;
+/** Picture pixels per output pixel when the picture covers `box`'s placement at camera scale `s`. */
+export declare function effectiveAt(art: {
     width: number;
     height: number;
+    depth?: {
+        scale: number;
+    };
 }, box: {
     width: number;
     height: number;
-}): UnitBox[];
-/** The camera's scale and offset that frame `b` (origin 0 0), held to the box's edges. */
-export declare function frameOn(b: Box, W: number, H: number): {
-    s: number;
-    x: number;
-    y: number;
-};
+}, s: number): number;
+/** The closest the camera may push in on this picture and stay at `EFF_MIN` or sharper. */
+export declare function sharpMax(art: {
+    width: number;
+    height: number;
+    depth?: {
+        scale: number;
+    };
+} | undefined, box: {
+    width: number;
+    height: number;
+}): number;
 /**
  * The default shot list, for a scene whose own is missing or unusable: the
  * subjects in order, one per cue after the first (the first cue is the
  * establishing shot), so every subject the picture has is pointed at once.
  */
 export declare function defaultShots(cues: number, subjects: number): Shot[];
+/** One step of a wiped-on picture: from `t`, over `dur`, the picture shows up to `share` of the box's width. */
+export interface WipeStep {
+    t: number;
+    dur: number;
+    share: number;
+    /** The subject this step uncovers (0: the rest of the picture). */
+    subject: number;
+}
+/** Everything the shell's camera does in one illustrated scene (src/bespoke/grammar.ts). */
+export interface Staging {
+    grammar: Grammar;
+    /** Where the camera is at t=0: home, except a zoom-out, which opens close on `subject`. */
+    open: {
+        s: number;
+        x: number;
+        y: number;
+        subject?: number;
+    };
+    moves: CamMove[];
+    /** A wiped-on picture's steps (grammar "wipe"); empty otherwise. */
+    wipes: WipeStep[];
+}
+interface Timed {
+    t: number;
+    subject: number;
+}
+interface Ctx {
+    cues: ReadonlyArray<{
+        t0: number;
+        t1: number;
+    }>;
+    subjects: readonly Box[];
+    W: number;
+    H: number;
+    sMax: number;
+    first: {
+        t0: number;
+        t1: number;
+    };
+    last: {
+        t0: number;
+        t1: number;
+    };
+    /** Home, with the reveal finished, before the settled end frame. */
+    latest: number;
+    /** Nothing moves before the establishing shot has been held. */
+    earliest: number;
+}
 /**
- * The camera moves for one scene. `cues` on the scene's clock; `duration` the
- * scene's length (the end frame is photographed at `duration - 0.5`).
+ * The named subjects' shot times, fitted to the scene: each as the voice names
+ * it, but no earlier than the establishing shot or `gap` after the one before,
+ * and early enough that every later one still fits before the reveal — a
+ * subject named in the last second is shot a little early rather than not at
+ * all (MEASURED 2026-10-10: short scenes naming their second subject late held
+ * one push-in, and `shot_variety` sent them back). Subjects that cannot fit
+ * even so are dropped from the end.
  */
+export declare function scheduled(list: readonly Timed[], c: Pick<Ctx, "earliest" | "latest">, gap: number): Timed[];
+/**
+ * The camera of one illustrated scene in its grammar. `cues` on the scene's
+ * clock; `duration` the scene's length (the end frame is photographed at
+ * `duration - 0.5`); `sMax` the picture's sharpness ceiling (`sharpMax`).
+ */
+export declare function compileStaging(grammar: Grammar, shots: readonly Shot[], cues: ReadonlyArray<{
+    t0: number;
+    t1: number;
+}>, duration: number, subjects: readonly Box[], W: number, H: number, sMax?: number): Staging;
+/** Round 4's one grammar, `tour`: the moves alone. */
 export declare function compileShots(shots: readonly Shot[], cues: ReadonlyArray<{
     t0: number;
     t1: number;
-}>, duration: number, subjects: readonly Box[], W: number, H: number): CamMove[];
+}>, duration: number, subjects: readonly Box[], W: number, H: number, sMax?: number): CamMove[];
+/** The closest the camera gets in a staging (the open frame included). */
+export declare function closest(st: Pick<Staging, "open" | "moves">): number;
+/**
+ * ROUND 6: a depth plane's framing for a camera framing (src/bespoke/depth.ts).
+ *
+ * The camera's framing `f` is of the subjects' plane (distance 1): scale `s`
+ * and offset `x, y` with origin 0 0, which is what `#sid-cam` is given. Read as
+ * a pinhole camera looking at the frame's centre `c`, that framing is a dolly
+ * `tz = 1 - 1/s` and a truck `f·t = (c(1-s) - x) / s`. A plane at distance `z`
+ * then projects EXACTLY to scale `s_z = z / (z - tz)` and offset
+ * `c(1 - s_z) - f·t·s_z / z` — so a farther plane zooms and slides less, a
+ * nearer one more: parallax with no approximation (a multiplane image is a
+ * stack of homographies, and for fronto-parallel planes those are scale +
+ * offset). `z = 1` returns `f` itself.
+ *
+ * NO PLANE EVER NEEDS ENLARGING TO COVER THE FRAME. A plane's left edge lands
+ * at or left of the frame's exactly when `x <= 0` — the camera's own framing
+ * covers the box — whatever the plane's distance: substituting `s_z` and `f·t`,
+ * `x_z <= 0` reduces to `x / (s·z) <= 0`. The same holds at every edge, so the
+ * shell's framings (held to the box by `frameAt`) cover with every plane.
+ * (Round 6's first cut carried an overscan search; it never returned more than
+ * 1, and a reversed copy of it was caught by nothing — so it is gone, and the
+ * test holds this property instead.)
+ */
+export declare function planeFrame(f: {
+    s: number;
+    x: number;
+    y: number;
+}, z: number, W: number, H: number): {
+    s: number;
+    x: number;
+    y: number;
+};
+/**
+ * RACK FOCUS (round 6): what tells the audience where to look, instead of a
+ * label plate. A plane at distance `z` is blurred by how far it sits from the
+ * plane in focus, in dioptres (|1/z - 1/zf|, as a lens's circle of confusion
+ * grows), more in a close shot than in the whole view (a longer lens has less
+ * depth of field). px at the plane's own scale.
+ */
+export declare const BLUR_WIDE = 3.5;
+export declare const BLUR_CLOSE = 5;
+export declare const BLUR_MAX = 6;
+export declare function blurAt(z: number, focusZ: number, s: number): number;
+/**
+ * The blur as the deck draws it: the opacity of the plane's out-of-focus twin
+ * (src/bespoke/sheet.ts, blurred `BLUR_MAX`px) over the sharp plane. A CSS
+ * blur tween cost ~1.5s a frame in the gates' browser; a cross-fade costs
+ * nothing measurable.
+ */
+export declare function softAt(z: number, focusZ: number, s: number): number;
+/** What `cameraScript` moves besides the camera in a depth-staged scene (round 6). */
+export interface DepthStage {
+    /** Backdrop planes, far to near: `#sid-plate` is the farthest, `#sid-planeN` the rest. */
+    planes: ReadonlyArray<{
+        z: number;
+    }>;
+    /** The subjects' planes `#sid-subjK` (K 1-based), with their distances. */
+    subjects: ReadonlyArray<{
+        subject: number;
+        z: number;
+        box: Box;
+    }>;
+    /** The scene's length: the light's sweep and the subjects' breathing end before it. */
+    duration: number;
+}
+/** The element id of backdrop plane `i` (far to near). The farthest keeps round 5's `-plate`. */
+export declare function planeId(sid: string, i: number): string;
+/** The element id of subject `k`'s plane (1-based). Not `-sK`: a scene's own ids use that. */
+export declare function subjectId(sid: string, k: number): string;
 /**
  * The camera as GSAP source, for the shell to put before the scene's own
  * script. Every tween is a `fromTo` with explicit from-values and
@@ -122,7 +306,26 @@ export declare function compileShots(shots: readonly Shot[], cues: ReadonlyArray
  * centre of the view (x' = W/2 - (W/2 - x)·k), so a hold is never a still
  * frame; the next move starts from where the creep ended. Nothing moves after
  * the reveal: the end frame is the whole picture, exactly home.
+ *
+ * ROUND 6, with depth planes (`depth`): every camera tween has a twin on each
+ * plane at `planeFrame` of its values for the plane's distance — the
+ * parallax — with the plane's blur racked to the subject framed (`blurAt`);
+ * the light sweeps once; the subjects breathe; and wipe steps light the
+ * subjects in turn instead of uncovering a clip.
  */
-export declare function cameraScript(sid: string, moves: readonly CamMove[], W: number, H: number): string;
+export declare function cameraScript(sid: string, moves: readonly CamMove[], W: number, H: number, opts?: {
+    open?: {
+        s: number;
+        x: number;
+        y: number;
+        subject?: number;
+    };
+    wipes?: readonly WipeStep[];
+    /** Round 6: the depth planes that move with the camera, each at its own distance. */
+    depth?: DepthStage;
+}): string;
 /** What a scene's camera does, for the report and the prompt: one word per move. */
-export declare function shotSummary(moves: readonly CamMove[]): string;
+export declare function shotSummary(moves: readonly CamMove[], grammar?: string, open?: {
+    s: number;
+}): string;
+export {};

package/dist/types/build/files.d.ts

@@ -69,8 +69,15 @@ export declare function vendorScripts(out: string, composition: string): Promise
  * downloadable file at all. Named here because this set is the ONLY thing that
  * reaches the built deck — a poster left out is simply absent, and the deck's
  * own runtime reports it as `http_error 404`, a long way from this line.
+ *
+ * A PIECE IS WRITTEN, NOT COPIED. Its `src` is the author's animate scene file,
+ * and what the deck loads under the same name is that file assembled with the
+ * vendored kit (`assemblePiece`, src/build/piece.ts) — the containment proof
+ * below applies to it exactly as to an image.
  */
 export declare function copyAssets(sourceDir: string, out: string, figures: readonly {
+    id?: string;
+    kind?: string;
     src: string;
     poster?: string;
 }[], step: Step): Promise<string[]>;