@jokerized/decksmith 0.8.0 → 0.9.1

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

@@ -0,0 +1,111 @@
+/**
+ * Type specs: the typographic half of a v2 style pack.
+ *
+ * A pack used to be a palette (`themes/`), and every deck set the same Inter at
+ * the same 42/64/40 scale, which is half of why the founder's verdict on 219
+ * decks was "always the same". A `TypeSpec` is the rest of a look: which face
+ * draws the headline and which draws the body, the eyebrow's size, case, weight
+ * and tracking, the headline's size, weight, tracking and leading, and how the
+ * title slide's big headline grows.
+ *
+ * EVERY NUMBER HERE IS GEOMETRY, which is why this is not CSS. `chromeHeight`
+ * charges the chrome from these numbers and `chromeCss` draws it from the same
+ * numbers, so the two cannot disagree. A spec is chosen by the font stack a theme
+ * declares (see `faceOf` in svg.ts), so every emitter that already threads a
+ * `Face` gets the right measurement without learning that packs exist.
+ *
+ * `CLASSIC_TYPE` is today's look, number for number. It is never looked up by
+ * stack: any stack no spec claims — `ink`, `mono`, `paper`, a user's own theme —
+ * measures as classic, which is what keeps v0.8.0's bytes.
+ */
+import type { MeasuredFace } from "./faces.js";
+/** A Latin face a deck can be measured in. `inter` is svg.ts's own table. */
+export type LatinFace = "inter" | MeasuredFace;
+export interface TypeSpec {
+    /** Stable id, for messages and the gallery. */
+    key: string;
+    /** Face of everything but the chrome. Measured with this face's table. */
+    body: LatinFace;
+    /** Face of the eyebrow, the headline and the title slide's headline. */
+    display: LatinFace;
+    /**
+     * The body stack. It IDENTIFIES the spec (`faceOf` matches its tail), so no two
+     * specs may share one; the display family rides in it after Inter, where it
+     * never draws, purely so a stack names its pair. See `stackFor`.
+     */
+    stack: string;
+    /** The chrome's stack: display face, then Inter for any glyph it lacks. */
+    displayStack: string;
+    /** `color` is a palette role, so one spec suits a light and a dark pack. */
+    eyebrow: {
+        size: number;
+        weight: 400 | 500 | 600 | 700;
+        tracking: number;
+        upper: boolean;
+        lh: number;
+        gap: number;
+        color: "muted" | "accent";
+    };
+    headline: {
+        size: number;
+        weight: 400 | 500 | 600 | 700;
+        tracking: number;
+        lh: number;
+    };
+    /** `fitText`'s bounds for the title slide, and how the big headline is set. */
+    title: {
+        lo: number;
+        hi: number;
+        weight: 400 | 500 | 600 | 700;
+        tracking: number;
+    };
+}
+/** The CSS family a face is declared under — what `vendorFace` writes. */
+export declare function familyOf(face: LatinFace): string;
+/**
+ * `"<body>", "Inter", "<display>", system-ui, sans-serif`, with duplicates gone.
+ *
+ * Inter second, always: every Latin deck vendors it, and `measure-faces.mjs`
+ * measured each face with Inter as its fallback, so a glyph the face lacks is
+ * drawn by the face the table assumed. The display family after Inter never
+ * draws a glyph; it is there so (body, display) pairs give distinct stacks.
+ */
+export declare function stackFor(body: LatinFace, display: LatinFace): string;
+/** Today's chrome, exactly. `title.ts` exported these numbers before specs existed. */
+export declare const CLASSIC_TYPE: TypeSpec;
+/**
+ * The v2 type specs. Five pairings, each a different voice rather than a
+ * different size of the same one:
+ *
+ * - `grotesk-inter`: a geometric grotesk headline, tight and large, over Inter.
+ * - `plex`: IBM Plex Sans throughout, a little compact — engineering drawings.
+ * - `serif-inter`: a text serif headline at display size over Inter.
+ * - `serif`: Source Serif 4 throughout, the eyebrow in sentence case — a journal.
+ * - `grotesk-plex`: Space Grotesk headline over a Plex body.
+ * - `plex-serif`: a Plex headline over a serif body, the inverse of `serif-inter`.
+ *
+ * HEIGHT. A one-line eyebrow plus a one-line headline costs at most classic's
+ * 146px in every spec, so a pack's bigger type comes out of its leading and
+ * gaps rather than out of the body's room. Measured why: `serif` at 44/70 cost
+ * a real deck a six-bar chart (`costsNothing` in themes/pick.ts now refuses
+ * such a pack, but a pack that rarely needs refusing is the better pack).
+ *
+ * FLOORS. Every eyebrow is at least 40px (invariant 5). Title tracking is never
+ * positive: `fitText` measures untracked, so only a tightening is free.
+ */
+export declare const TYPES: Readonly<Record<string, TypeSpec>>;
+/**
+ * The spec a theme's stack names, or undefined for classic.
+ *
+ * Exact, after the one prefix `deckLook` adds: a CJK deck puts its bundled Noto
+ * family first and keeps the pack's stack behind it. A stack that merely
+ * CONTAINS a spec's families — a user's own theme — is not that spec.
+ */
+export declare function typeForStack(fontStack: string): TypeSpec | undefined;
+/** One line box, the way `title.ts` has always rounded it. */
+export declare function lineBox(size: number, lh: number): number;
+/**
+ * A tracking value as the CSS this project has always written: `.14em`,
+ * `-.015em`, `0`. Leading zero dropped, so the classic chrome is byte-identical.
+ */
+export declare function em(tracking: number): string;

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
+import type { BespokeMap } from "./bespoke/scene.js";
 import { type DeckNarration } from "./emit/composition.js";
 import type { Cut } from "./plan/select.js";
-import { type Format, type Source, type Storyboard } from "./types.js";
+import { type Design, type Format, type Source, type Storyboard } from "./types.js";
 /**
  * Markdown (and LaTeX-ish markdown) in, typed `Source` out. The one parser we
  * have; a consumer that already holds structured text can skip it and hand
@@ -103,10 +104,22 @@ export type { Deck, DeckNarration, DeckOptions } from "./emit/composition.js";
  * itself, exported so it can be run against a budget no `Format` states.
  */
 export { selectBeats } from "./plan/select.js";
+/**
+ * `--design v2`: the Director that picks each beat's look, the look vocabulary
+ * it picks from, and the sameness numbers it reports. Exported so an eval can
+ * measure a corpus of storyboards without building each one.
+ */
+export { direct, summarize } from "./plan/direct.js";
+export type { BeatLook, Direction, LookSummary } from "./plan/direct.js";
+export { candidates, classicLook, LOOK_FILE, signature, VARIANTS } from "./emit/look.js";
+export type { Look, Placement } from "./emit/look.js";
 export type { Cut, Dangling, Dropped, DropRule, SelectionBudget } from "./plan/select.js";
 /** Themes are a named, closed set; a consumer needs to enumerate and validate. */
 export { resolveTheme, THEME_NAMES, THEMES } from "./emit/themes/index.js";
 export type { DeckTheme } from "./emit/themes/index.js";
+export { PACKS } from "./emit/themes/packs.js";
+export { chooseLook, type Design, type LookChoice, pickTheme, rankPacks, } from "./emit/themes/pick.js";
+export { TYPES, type TypeSpec } from "./emit/type.js";
 /**
  * The gates. `verify` is ours plus HyperFrames'; `check` is HyperFrames' alone
  * and needs its CLI. A build that never opens a browser can still run `verify`
@@ -137,7 +150,25 @@ export type { CheckOptions } from "./verify/check.js";
  * verdict. `verify` runs it; nothing else has to.
  */
 export { gradeOverprint, MIN_OVERLAP, overprints } from "./verify/overprint.js";
+/**
+ * Motion variety measured off a built composition: modal-entrance share, seam
+ * kinds, ease shares. The M4 exit metrics; see experiments/019-motion.
+ */
+export { motionStats, topTwoEaseShare } from "./verify/motion.js";
+export type { MotionStats } from "./verify/motion.js";
 export type { Overprint, Overprinted, TextRun } from "./verify/overprint.js";
+/**
+ * The frame gate on its own, and the fill measure it carries: one browser over
+ * a built deck, every stop seeked and captured. `verify` runs it beside `check`;
+ * exported so an eval can read `fills` — main-axis fill at each scene's last
+ * hold, on a classic deck as on a v2 one — without running the slower half.
+ * `fillBand` and `FIT_FILE` are the definition and the manifest both sides use.
+ */
+export { fidelity } from "./verify/fidelity.js";
+export type { FidelityReport } from "./verify/fidelity.js";
+export { fillBand, FIT_FILE } from "./emit/fit.js";
+export type { Fit, FillBand, FitManifest } from "./emit/fit.js";
+export type { FillRow } from "./verify/fill.js";
 /**
  * The determinism gate: render the deck twice and compare. Separate from
  * `verify` because it costs two full renders — minutes, not milliseconds — so
@@ -190,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. */
@@ -221,8 +263,17 @@ export interface BuildDeckOptions {
     onBeatWarning?: (beatId: string, warning: string) => void;
     /** Any name in `THEME_NAMES`. Overrides `storyboard.theme`. */
     theme?: string;
+    /** `classic` (default) or `v2`. Overrides `storyboard.design`. See `designSchema`. */
+    design?: Design;
+    /** v2: the seed the style pack is ranked by. Default `storyboard.sourceId`. */
+    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/plan/direct.d.ts

@@ -0,0 +1,66 @@
+import type { EmitContext, Scene, Theme } from "../emit/kit.js";
+import { type Look } from "../emit/look.js";
+import type { Archetype, Beat, Design, Format, Source } from "../types.js";
+export interface DirectOptions {
+    source: Source;
+    format: Format;
+    theme: Theme;
+    /** Normally `storyboard.sourceId`. */
+    seed: string;
+    /**
+     * The design every candidate is emitted under. `v2` from `emitDeck`, so each
+     * look is measured as the fit engine will actually draw it; absent in tests
+     * that exercise the Director on its own.
+     */
+    design?: Design;
+    /** The emitter. `emitScene` unless a test substitutes one that misbehaves. */
+    emit?: (beat: Beat, ctx: EmitContext) => Scene;
+}
+/** One beat's decision, as `out/look.json` records it. */
+export interface BeatLook {
+    beat: string;
+    archetype: Archetype;
+    variant: string;
+    placement: Look["placement"];
+    signature: string;
+    /** The chosen look's `Scene.fill`, when its emitter reports one. */
+    fill?: number;
+    /** Candidates that drew and kept the classic timing. Always ≥ 1. */
+    viable: number;
+    /** Candidates that were refused, and why — the emitter's own sentence. */
+    refused: {
+        signature: string;
+        reason: string;
+    }[];
+}
+export interface Direction {
+    /** One per beat, in order: what `EmitContext.look` is set to. */
+    looks: Look[];
+    beats: BeatLook[];
+    summary: LookSummary;
+}
+export interface LookSummary {
+    beats: number;
+    distinct: number;
+    /** Share of beats whose chrome sits on top of the slide (title excluded from the numerator). */
+    modalChrome: number;
+    /** Adjacent pairs with the same signature. */
+    adjacentRepeats: number;
+    /** The four most-used signatures' share of beats. */
+    top4: number;
+}
+export declare function direct(beats: readonly Beat[], opts: DirectOptions): Direction;
+/**
+ * The least share of the classic look's figure area another look may draw the
+ * figure at. The review (2026-10-08) measured v2's rail and foot looks shrinking
+ * the paper's own figure to 43-61% of its classic area (ja s4, ko s6, en s5) to
+ * make room for a headline: fill went up because white plate and bigger text
+ * count as ink, and the most informative thing on the slide got smaller. A
+ * look that keeps 80% or more is still a different slide; one below it is not
+ * worth the variety.
+ */
+export declare const FIGURE_FLOOR = 0.8;
+/** The sameness numbers for one deck. Also used by the corpus measurement. */
+export declare function summarize(beats: readonly Pick<BeatLook, "archetype" | "signature" | "placement">[]): LookSummary;
+/** 32-bit FNV-1a. Deterministic, dependency-free, and enough to spread ties. */
+export declare function fnv1a(s: string): number;

package/dist/types/prefs.d.ts

@@ -1,5 +1,5 @@
 import type { z } from "zod";
-import { prefsSchema, type Source } from "./types.js";
+import { type Design, prefsSchema, type Source } from "./types.js";
 export type Prefs = z.infer<typeof prefsSchema>;
 /**
  * A partial Prefs. `narration` and `images` are the two nested objects, so they
@@ -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";
 /**
@@ -33,6 +34,16 @@ export declare function loadPrefs(overrides?: PrefsPatch, cwd?: string, source?:
  * schema, so there is exactly one place that decides what a legal tone is.
  */
 export declare function prefsFromFlags(flags: PrefFlags): PrefsPatch;
+/**
+ * The design a build uses: a `--design` flag or a config file, else what the
+ * storyboard was planned under, else `classic`.
+ *
+ * NOT `stated()`, which treats a value at its default as unsaid. `design` has
+ * no default — it is optional in the schema — so an explicit `classic` is
+ * distinguishable from silence, and it IS the rollback: it has to win over a
+ * storyboard planned under v2.
+ */
+export declare function designFor(prefs: Pick<Prefs, "design">, recorded?: Design): Design;
 /** The flag surface the CLI exposes. Every one optional: absent means unstated. */
 export interface PrefFlags {
     slides?: string | number;
@@ -42,6 +53,10 @@ export interface PrefFlags {
     genre?: string;
     duration?: string | number;
     theme?: string;
+    /** `--design classic | v2`. */
+    design?: string;
+    /** `--pack-seed`: what v2 hashes to pick a pack. */
+    packSeed?: string;
     speed?: string | number;
     narrate?: boolean;
     voice?: string;
@@ -56,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.

package/dist/types/source/fonts.d.ts

@@ -6,10 +6,20 @@ export interface FontBundle {
     /** The woff2 basenames written into `dir`, beside `fonts.css`. */
     files: string[];
 }
+/**
+ * The serif companion to `familyFor`: what a v2 pack whose type spec sets a role
+ * in a serif draws that role's CJK in. Without it every CJK deck set its
+ * headlines in Noto Sans whatever the pack said, so the font change that makes
+ * a serif pack a serif pack disappeared for three languages out of four
+ * (review, 2026-10-08).
+ */
+export declare function serifFamilyFor(lang: string): string | null;
 /** The CJK family a language needs subset, or null: the deck ships Inter (`vendorInter`). */
 export declare function familyFor(lang: string): string | null;
 /**
  * Write `dir/fonts.css` plus its woff2 for `lang`, covering `glyphs`. Returns
  * null for languages the renderer already resolves, which needs no bundle.
  */
-export declare function bundleFont(lang: string, glyphs: string, dir: string): Promise<FontBundle | null>;
+export declare function bundleFont(lang: string, glyphs: string, dir: string, opts?: {
+    serif?: boolean;
+}): Promise<FontBundle | null>;