@jokerized/decksmith 0.9.0 → 0.9.2

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

@@ -0,0 +1,128 @@
+/**
+ * The camera of an illustrated scene, owned by the shell: STAGED SHOTS, not
+ * pans. Round 3 let each scene move the camera itself and it mostly drifted at
+ * 1.1-1.4x — a different gentle pan in every scene, and the founder's bar is
+ * an explainer's camera: an establishing shot of the whole picture, a push in
+ * on the subject the voice is naming, a cut-like move to the next, and a pull
+ * back that reveals the whole again for the summary.
+ *
+ * So the scene names, per cue, WHICH subject the shot is on (its `shots`), and
+ * this file turns that into the camera — one fixed grammar, the same in every
+ * scene of every deck, which is also what makes two runs of a deck move alike:
+ *
+ *   1. ESTABLISHING: the whole picture at scale 1 from the start, for at least
+ *      `ESTABLISH` seconds of the first cue (a slow 3% creep, so it is alive);
+ *   2. PUSH IN on the subject a shot names, starting at its time, `MOVE`s,
+ *      power3.inOut, framed on the subject's box (padded) at `CLOSE_MIN` to
+ *      `CAMERA_MAX_SCALE`; a held shot creeps 3% further so it never freezes;
+ *   3. a shot on another subject is a move straight there (no pull-out between);
+ *   4. REVEAL: back to the whole picture at the start of the last cue (or after
+ *      the last push has been held `MIN_HOLD`), home before the end frame.
+ *
+ * Shots closer than `MIN_HOLD` to the previous one are dropped: a shot the
+ * audience cannot read is a shake.
+ */
+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 {
+    cue: number;
+    at: number;
+    subject: number;
+}
+/** A box in the body box's px. */
+export interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** One camera move: from the previous framing to this one, starting at `t`. */
+export interface CamMove {
+    t: number;
+    dur: number;
+    s: number;
+    x: number;
+    y: number;
+    ease: string;
+    /** The subject framed (0 = the whole picture). */
+    subject: number;
+}
+/** The camera's largest push-in: past it a picture turns to mush. */
+export declare const CAMERA_MAX_SCALE = 2.2;
+/** The smallest scale that is a close shot: below it a push reads as a nudge (round 3's 1.1-1.4). */
+export declare const CLOSE_MIN = 1.6;
+/** Seconds a move takes. */
+export declare const MOVE = 1.1;
+/** The reveal is slower: the picture opens out. */
+export declare const REVEAL = 1.3;
+/** A shot is held at least this long before the next move. */
+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;
+/**
+ * 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).
+ */
+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;
+}): Box;
+/**
+ * Where the picture's subjects sit in the body box, when the picture covers
+ * its placement (`artPlacement`) with `preserveAspectRatio="xMidYMid slice"`
+ * (the shell places it so): scaled to cover and centred, so a share of the
+ * picture maps through that scale and offset. A subject cut off by more than
+ * half is not pointed at; the rest are clipped to the placement.
+ */
+export declare function subjectsInBox(units: readonly UnitBox[], art: {
+    width: number;
+    height: number;
+}, box: {
+    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: {
+    width: number;
+    height: 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;
+};
+/**
+ * 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[];
+/**
+ * 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`).
+ */
+export declare function compileShots(shots: readonly Shot[], cues: ReadonlyArray<{
+    t0: number;
+    t1: number;
+}>, duration: number, subjects: readonly Box[], W: number, H: number): CamMove[];
+/**
+ * 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
+ * `immediateRender:false`, so a frame never depends on seek history. Between
+ * two moves the held shot creeps `CREEP` further in about the point at the
+ * 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.
+ */
+export declare function cameraScript(sid: string, moves: readonly CamMove[], W: number, H: number): 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;

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

@@ -0,0 +1,5 @@
+/**
+ * The script with every overlap it can read removed, or undefined when it
+ * found none to remove. Bounded: at most 40 fixes.
+ */
+export declare function untangle(script: string): string | undefined;

package/dist/types/emit/archetypes/index.d.ts

@@ -1,10 +1,3 @@
-/**
- * The explanatory vocabulary, indexed by archetype.
- *
- * The mapped type is the point: adding an archetype to `Beat` without an emitter
- * beside it fails to compile, which is the only guarantee that keeps the union in
- * `types.ts` honest.
- */
 import type { Archetype, Beat } from "../../types.js";
 import type { EmitContext, Emitter, Scene } from "../kit.js";
 export declare const emitters: {

package/dist/types/emit/composition.d.ts

@@ -11,11 +11,12 @@
  * timeline, wraps whatever the emitter returns, and closes the document.
  */
 import type { z } from "zod";
+import { type BespokeMap } from "../bespoke/scene.js";
 import { type Direction } from "../plan/direct.js";
 import { type Cut } from "../plan/select.js";
-import type { Design, Format, NarrationCanvas, Source, Storyboard, segmentSchema } from "../types.js";
+import type { Beat, Design, Format, NarrationCanvas, Source, Storyboard, segmentSchema } from "../types.js";
 import type { FitManifest } from "./fit.js";
-import { type Scene } from "./kit.js";
+import { type EmitContext, type Scene } from "./kit.js";
 /** A built deck. `page` is present only for navigable formats. */
 export interface Deck {
     composition: string;
@@ -129,6 +130,12 @@ export interface DeckOptions {
      * (`vendorInter` in src/build/files.ts), for the same reason.
      */
     fontCss?: string;
+    /**
+     * `--design v2 --bespoke`: beats drawn by a generated scene, keyed by beat id
+     * (src/bespoke/). Absent on every other build, which is what keeps them
+     * byte-identical. A deck that carries one also carries `BESPOKE_CSP`.
+     */
+    bespoke?: BespokeMap;
 }
 /**
  * Both artifacts from one layout pass.
@@ -262,7 +269,35 @@ export declare function speechPlan(open: number, holds: readonly number[], segme
     starts: number[];
     end: number;
 };
+/**
+ * Where a bespoke scene's stops go and when its sentences are spoken, worked out
+ * with the same functions `layout` stages with — so the cue times the model is
+ * given are the times the deck will have. See `bespokeHolds` for why the voice
+ * does not move.
+ *
+ * `ctx` must not carry the bespoke map: this stages the ARCHETYPE first.
+ */
+export declare function bespokeStaging(beat: Beat, ctx: EmitContext, segments: readonly Segment[], speed: number): {
+    holds: number[];
+    open: number;
+};
 export declare function emitComposition(storyboard: Storyboard, source: Source, format: Format, opts?: DeckOptions): string;
+/**
+ * The policy a composition carrying a generated scene runs under.
+ *
+ * The static walk in src/bespoke/contract.ts refuses every NAME that reaches the
+ * network, eval, storage or navigation; this refuses the BEHAVIOUR, so a scene
+ * that spelled its way past the walk still gets nothing. No `connect-src`, no
+ * frames, no plugins, and no `unsafe-eval` — `Function("…")` assembled from
+ * fragments throws here. `'unsafe-inline'` stays because every scene's timeline
+ * is an inline script, as it is in every deck; what it buys an attacker is
+ * nothing a scene could not already write. Local files only (`'self'`), which is
+ * every vendored script, stylesheet, font and figure a deck ships.
+ *
+ * Only on a deck with a bespoke scene: a `<meta>` in every head would move the
+ * bytes of every deck ever built.
+ */
+export declare const BESPOKE_CSP: string;
 /** Shipped beside the deck so a built artifact needs no network to navigate. */
 export declare const PLAYER_FILE = "hyperframes-player.global.js";
 /**

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

@@ -6,6 +6,7 @@
  * and nothing else. Adding a domain means adding an emitter — the shell never
  * learns what a camera frustum or an orderbook is.
  */
+import type { BespokeMap } from "../bespoke/scene.js";
 import type { Archetype, BeatOf, Design, Format, Source } from "../types.js";
 import type { Fit } from "./fit.js";
 import type { Look } from "./look.js";
@@ -251,6 +252,14 @@ export interface EmitContext {
      * the Director rejects any look whose holds or chrome landing differ.
      */
     look?: Look;
+    /**
+     * `--design v2 --bespoke` only: the beats drawn by a generated scene instead
+     * of their archetype, keyed by beat id (src/bespoke/scene.ts). `emitScene`
+     * reads it, so every caller that stages a beat — `planCut`, `layout`, the
+     * timing manifest — sees the same scene. ABSENT ON EVERY OTHER BUILD, and
+     * absent means the archetype, byte for byte.
+     */
+    bespoke?: BespokeMap;
 }
 /**
  * A value in a GSAP vars payload that is JavaScript rather than data.
@@ -366,6 +375,14 @@ export interface Scene {
      * seeking that deck navigation performs.
      */
     tl: Tween[];
+    /**
+     * A bespoke scene's generated script, and nothing else's. Run inside this
+     * scene's timeline closure as `function (tl, root) { "use strict"; … }`, after
+     * `tl` exists and before the shell's own tweens are appended to it. Checked
+     * by src/bespoke/contract.ts before it can get here; an archetype never sets
+     * it, so every archetype scene is the bytes it was.
+     */
+    script?: string;
     /** Statements run as the document parses, before anything else, e.g.
      * `katex.render(...)`. Anything that CHANGES layout belongs here, so that a
      * `measure` below reads the finished document. */

package/dist/types/emit/themes/pick.d.ts

@@ -9,11 +9,14 @@
  *
  * WEIGHTED BY CONTENT, so the hash is not the only voice. Each pack carries an
  * affinity for the four archetype families (`ARCHETYPE_FAMILY`): a deck that is
- * mostly equations leans to the serif packs, one that is mostly bars and tables
- * to the grotesk and drafting ones. The lean is mild — every pack keeps a floor
+ * mostly structure leans to the drafting pack, one that is mostly bars and
+ * tables to the grotesk one. The lean is mild — every pack keeps a floor
  * weight — because the founder's complaint is sameness across decks, and a
  * strong content rule would put every paper of one field on one pack.
  *
+ * DARK ONLY. The pick ranks the dark packs (`PICKED`); a light one is worn only
+ * when named. The founder, 2026-10-11: "I prefer dark theme".
+ *
  * Rendezvous hashing: each pack draws `-ln(u) / weight` from its own hash of
  * (seed, pack) and the smallest draw wins. That is a weighted choice whose
  * probabilities are exactly the normalised weights, and the full ordering is a
@@ -27,7 +30,7 @@ import { type DeckNarration } from "../composition.js";
 export declare function fnv1a(text: string): number;
 /** A pack's weight for this deck: 1, plus its affinity times the family mix. */
 export declare function packWeights(beats: Storyboard["beats"]): Record<string, number>;
-/** Every pack, most-preferred first, for this deck and seed. */
+/** Every pickable pack, most-preferred first, for this deck and seed. */
 export declare function rankPacks(beats: Storyboard["beats"], seed: string): string[];
 /** The design generation a build emits. `classic` is v0.8.0, byte for byte. */
 export type Design = "classic" | "v2";

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+import type { BespokeMap } from "./bespoke/scene.js";
 import { type DeckNarration } from "./emit/composition.js";
 import type { Cut } from "./plan/select.js";
 import { type Design, type Format, type Source, type Storyboard } from "./types.js";
@@ -220,6 +221,17 @@ export { guardTmpdir } from "./tmpdir.js";
  * consumers restate the halves they need.
  */
 export * from "./types.js";
+/**
+ * `--design v2 --bespoke`: generated scenes for a few mechanism beats per deck.
+ * The pass, its contract checker, its selection rule and its cache are all
+ * exported so a host can run them on its own schedule.
+ */
+export { BESPOKE_FILE, type BespokeEntry, type BespokeMap, bespokeScene } from "./bespoke/scene.js";
+export { checkFragment, type Fragment, instantiate } from "./bespoke/contract.js";
+export { selectBespoke } from "./bespoke/select.js";
+export { cacheKey, SceneCache } from "./bespoke/cache.js";
+export { type BespokeReport, type BespokeResult, bespokePass, type GateFn, } from "./bespoke/pipeline.js";
+export { browserGate } from "./bespoke/probe.js";
 /** Where the emitted deck's parts came from and where they went. */
 export interface BuildResult {
     /** Absolute path of the directory written. */
@@ -257,6 +269,11 @@ export interface BuildDeckOptions {
     packSeed?: string;
     /** Multiplies every duration and hold. 1 leaves the bytes untouched. */
     speed?: number;
+    /**
+     * `--design v2` only: beats drawn by a generated scene (src/bespoke/), from
+     * `bespokePass`. Absent on every other build, which keeps their bytes.
+     */
+    bespoke?: BespokeMap;
     /** Default `FORMATS["deck-16x9"]`. */
     format?: Format;
     /** From `narrate`. `dir` is where the mp3s sit relative to `deck.html`. */

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

@@ -33,6 +33,14 @@ export interface RunnerArgs {
      * `cwd` to fence the writes to.
      */
     sandbox?: "read-only" | "workspace-write";
+    /** Images attached to the prompt (`codex exec -i`). The bespoke critique round sends its frames. */
+    images?: string[];
+    /** The CLI to run. Absent: `codex` on PATH. */
+    bin?: string;
+    /** Told the run's token count when the CLI reports one. */
+    onUsage?: (tokens: number) => void;
+    /** Extra `-c key=value` overrides, in order (see `leanCodexConfig`). */
+    config?: readonly string[];
 }
 /** What the planner needs from the outside world: a prompt in, a final message out. */
 export type Runner = (args: RunnerArgs) => Promise<void>;
@@ -48,5 +56,33 @@ export declare function codexCommand(args: RunnerArgs): {
     argv: string[];
     env?: NodeJS.ProcessEnv;
 };
+/**
+ * Features that give a `codex exec` run TOOLS. A call that is a pure text
+ * transform — a prompt in, a schema-held JSON reply out — needs none of them,
+ * and with them the agent spends turns on the account's own setup instead:
+ * MEASURED 2026-10-08 on one bespoke draft prompt, the default config ran
+ * `cat` on the user's global AGENTS.md and an animation skill before
+ * answering — 56,679 input tokens over several turns and 135-488s — where the
+ * same prompt with these off was one turn of 18,247 input tokens.
+ */
+export declare const TOOL_FEATURES: readonly ["shell_tool", "unified_exec", "apps", "plugins", "multi_agent", "browser_use", "computer_use", "image_generation", "skill_search", "tool_suggest"];
+/**
+ * `-c` overrides for a tool-less, single-turn `codex exec`: every tool feature
+ * off, web search off, and every MCP server the account configured disabled by
+ * name (the config's own names, read once per process with `codex mcp list`;
+ * a name the config does not define cannot be disabled, only invented). If the
+ * list cannot be read, the features alone still remove the shell.
+ */
+export declare function leanCodexConfig(bin?: string, list?: (bin: string) => Promise<string>): Promise<string[]>;
+/**
+ * `leanCodexConfig` with ONE tool back: the image tool, for the bespoke pass's
+ * illustration call (src/bespoke/art.ts). The shell stays off — the agent
+ * reports where the tool saved the picture and the caller reads it from there —
+ * and so does `view_image`, which would spend the call's tokens looking at a
+ * picture the scene call is shown anyway. MEASURED 2026-10-09: 42s and 19k
+ * tokens for one picture this way, against 49s and 45k with the agent asked to
+ * inspect it.
+ */
+export declare function artCodexConfig(bin?: string, list?: (bin: string) => Promise<string>): Promise<string[]>;
 /** The production `Runner`: `codex exec` on PATH, stdin in, a file out. */
 export declare function runCodex(args: RunnerArgs): Promise<void>;

package/dist/types/prefs.d.ts

@@ -7,9 +7,10 @@ export type Prefs = z.infer<typeof prefsSchema>;
  * wipe a `rate` the config file set, and `--image-style` must not wipe its
  * `provider`.
  */
-export type PrefsPatch = Partial<Omit<Prefs, "narration" | "images">> & {
+export type PrefsPatch = Partial<Omit<Prefs, "narration" | "images" | "bespoke">> & {
     narration?: Partial<Prefs["narration"]>;
     images?: Partial<Prefs["images"]>;
+    bespoke?: Partial<NonNullable<Prefs["bespoke"]>>;
 };
 export declare const CONFIG_FILE = "decksmith.config.json";
 /**
@@ -70,4 +71,12 @@ export interface PrefFlags {
     imageModel?: string;
     imageStyle?: string;
     imageMax?: string | number;
+    /** `--bespoke`: generated scenes for a few mechanism beats (v2 only). */
+    bespoke?: boolean;
+    bespokeCalls?: string | number;
+    bespokeSeconds?: string | number;
+    bespokeModel?: string;
+    bespokeCli?: string;
+    bespokeCache?: string;
+    bespokeArt?: string | number;
 }

package/dist/types/render/capture.d.ts

@@ -107,6 +107,12 @@ export interface DeckPage {
 }
 export interface OpenOptions {
     timeoutMs?: number;
+    /**
+     * Collect what the page did that a deck must not: script errors, console
+     * errors (a CSP refusal is one), and any request or navigation that is not
+     * a local file. Registered before the page loads, so load-time ones count.
+     */
+    watch?: string[];
 }
 /**
  * Open `dir`'s deck in the renderer's own browser, ready to seek.

package/dist/types/render/timing.d.ts

@@ -48,6 +48,7 @@
  * rendering a deck whose audio is aimed at the wrong frames.
  */
 import type { z } from "zod";
+import type { BespokeMap } from "../bespoke/scene.js";
 import { type Cue } from "../deck/subtitles.js";
 import { type DeckNarration } from "../emit/composition.js";
 import type { Beat, Format, Source, Storyboard, segmentSchema } from "../types.js";
@@ -218,6 +219,8 @@ export interface TimingInput {
     beats?: readonly Beat[];
     narration?: DeckNarration;
     theme?: string;
+    /** `DeckOptions.bespoke`, exactly as `emitDeck` was given it. */
+    bespoke?: BespokeMap;
 }
 /**
  * One pass over the built deck, producing the manifest `render` consumes.