@jokerized/decksmith 0.1.4 → 0.3.0

package/dist/types/emit/morph-runtime.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The keyed equation morph — TransformMatchingTex, for the DOM.
+ *
+ * Two KaTeX renderings in, one seek-evaluable plan out. `build()` runs once in
+ * the browser, inside the ready gate (Seam B), and bakes every number; the
+ * plan is then driven by a GSAP PLUGIN — `render(ratio)` is part of being
+ * seeked, so it fires under `suppressEvents` where an `onUpdate` would not
+ * (invariant 11). Nothing here runs on a callback.
+ *
+ * Four phases, kept separate on purpose:
+ *   1. LIFT   — pull every ink-bearing leaf out of KaTeX's nested boxes into a
+ *               flat absolutely-positioned overlay. Removes clipping, vlist
+ *               stacking and transform-on-inline entirely.
+ *   2. GROUP  — collect leaves into the units that move as one body. An author
+ *               key makes a group; an unkeyed leaf is its own group.
+ *   3. MATCH  — decide which group of A becomes which group of B.
+ *   4. PLAN   — a similarity transform per group, as per-leaf segments.
+ *
+ * `evaluate()` turns a plan and a progress into styles. It is a pure function
+ * of its arguments — two seeks to one time write the same strings — which is
+ * what makes the render byte-identical across browser processes, measured on
+ * the spike this is ported from (`experiments/013-vocabulary/morph/`).
+ *
+ * Bundled to an IIFE by `scripts/build.mjs`, vendored beside GSAP by the CLI,
+ * and loaded only by a deck that has a morph in it. The pure halves — `group`,
+ * `match`, `plan`, `evaluate` — are exported for the tests, which is why the
+ * window registration at the bottom is guarded.
+ */
+/** The class prefix an author key is carried on: `\htmlClass{ds-k-<key>}{...}`. */
+export declare const KEY_PREFIX = "ds-k-";
+export interface Leaf {
+    el: HTMLElement;
+    key: string;
+    sig: string;
+    text: string;
+    /** Font size in layout px. */
+    fs: number;
+    /** Centre and box, in the host's own layout px. */
+    cx: number;
+    cy: number;
+    w: number;
+    h: number;
+}
+export interface Group {
+    ident: string;
+    key: string;
+    leaves: Leaf[];
+    cx: number;
+    cy: number;
+    w: number;
+    h: number;
+    fs: number;
+    text: string;
+}
+/**
+ * The unit that moves as one body.
+ *
+ * This is the whole quality argument of the file. Matching GLYPH BY GLYPH is
+ * what a naive reading of TransformMatchingTex suggests and it is visibly
+ * wrong: in `a^2+b^2=c^2 -> c^2-b^2=a^2` the three `2`s are interchangeable
+ * under any text-plus-class identity, so they pair left-to-right and stay put
+ * while their bases cross over. The audience sees the letters swap and the
+ * exponents refuse to follow, which asserts something false about the algebra.
+ *
+ * Manim does not avoid this by being cleverer — `MathTex("a^2", "+", "b^2",
+ * ...)` is the AUTHOR splitting the expression into the parts meant to
+ * survive. `\htmlClass{ds-k-<key>}{...}` is the same act, and it is the only
+ * mechanism here that produces a correct morph on an ambiguous pair.
+ *
+ * A group's identity is its key alone, not its contents, so `ds-k-exp` can
+ * carry `x^2` onto `x^3`: the body moves and its contents dissolve.
+ */
+export declare function group(items: Leaf[]): Group[];
+export interface Match {
+    pairs: [number, number][];
+    dropA: number[];
+    addB: number[];
+}
+/**
+ * Bucket by identity, then pair NEAREST FIRST within a bucket.
+ *
+ * Document order — the spike's rule — sends the wrong twin across the slide:
+ * `F = E(I), X = W(F)` has two `=` and its successor one, and pairing the
+ * first `=` with it flew a glyph 800px over the equation while the `=` sitting
+ * 40px from its destination faded out. Nearest-first is what a viewer expects
+ * of a symbol that did not move. Ties fall to document order, so it is still a
+ * pure function of the two layouts.
+ */
+export declare function match(A: Group[], B: Group[]): Match;
+export type Prop = "x" | "y" | "s" | "o";
+export type Ease = "none" | "power1.in" | "power1.out" | "power2.in" | "power2.out" | "power2.inOut";
+/**
+ * One property of one leaf, over one slice of the morph.
+ *
+ * Times are FRACTIONS of the morph, not seconds: the plan is evaluated against
+ * the plugin tween's ratio, so `pace()` scaling the tween's `duration` scales
+ * all of this with it, and the plan never has to know how long it takes.
+ */
+export interface Step {
+    el: HTMLElement;
+    prop: Prop;
+    from: number;
+    to: number;
+    at: number;
+    dur: number;
+    ease: Ease;
+}
+/**
+ * One similarity transform per matched group, expressed per leaf.
+ *
+ * A group's leaves move RIGIDLY: every leaf gets the same scale and the
+ * translation that the group's own centre-to-centre move implies for its
+ * position within the body. `a^2` therefore arrives with its exponent still
+ * attached, which is the whole reason groups exist.
+ *
+ * The B side is placed by the INVERSE transform — B's leaves start where they
+ * would sit inside A's box — so when the contents differ the two renderings
+ * dissolve into each other while sharing one trajectory.
+ *
+ * `arc` bows the path. Two glyphs swapping ends of an equation travel the same
+ * straight line in opposite directions and pile up in the middle, which reads
+ * as a collision rather than an exchange. The bow is two segments on `y` — out
+ * over the first half, back over the second — against one on `x` that runs
+ * the whole way.
+ */
+export declare function plan(A: Group[], B: Group[], m: Match, opt: {
+    arc?: boolean;
+}): Step[];
+export interface MorphPlan {
+    leaves: {
+        el: HTMLElement;
+        side: "a" | "b";
+    }[];
+    steps: Step[];
+}
+/**
+ * Write the morph at progress `v` in [0, 1] into every leaf's style.
+ *
+ * Every leaf is written every time, from its resting state forward — A drawn,
+ * B hidden, nothing moved — so a cold seek to any progress produces the same
+ * strings as a walk to it. That is the property the capture depends on.
+ */
+export declare function evaluate(p: MorphPlan, v: number): void;
+export interface Stats {
+    groupsA: number;
+    groupsB: number;
+    leavesA: number;
+    leavesB: number;
+    matched: number;
+    dropped: number;
+    added: number;
+}
+/**
+ * Build the morph inside `host`, which must already contain two rendered KaTeX
+ * roots marked `data-morph="a"` and `data-morph="b"`. Runs in `measure`, after
+ * fonts; the plan is kept for the plugin tween on the same host to find.
+ */
+export declare function build(host: HTMLElement, opt?: {
+    arc?: boolean;
+}): Stats;
+interface PluginState {
+    plan: MorphPlan;
+    end: number;
+}
+/**
+ * `dsMorph` as a GSAP property: `tl.fromTo(host, { dsMorph: 0 }, { dsMorph: 1 })`.
+ *
+ * A plugin's `render` is called by the timeline as part of being seeked, so
+ * this runs under `suppressEvents` — the capture path — where an `onUpdate`
+ * does not. The tween's own ease must be "none": the plan carries its eases
+ * per segment, and a second ease on top would warp every one of them.
+ */
+export declare const DSMorphPlugin: {
+    name: string;
+    init(this: PluginState, target: Element, value: unknown): void;
+    render(ratio: number, d: PluginState): void;
+};
+export {};

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

@@ -13,7 +13,7 @@
  * that composes these primitives, and putting it here is how a primitive layer
  * turns into six hand-rolled one-offs wearing a shared import.
  */
-import { type Vars } from "./kit.js";
+import { type Tween, type Vars } from "./kit.js";
 export interface Pt {
     x: number;
     y: number;
@@ -47,18 +47,54 @@ export declare function n(v: number): string;
  */
 export declare function nv(v: number): number;
 /**
- * The `from` vars of a stroke draw-on, with the path fully hidden.
+ * The `from` and `to` vars of a stroke draw-on, measured by the browser.
  *
- * The length is rounded UP rather than to two decimals, and then given a pixel
- * of slack, because GSAP writes `strokeDashoffset` back as an integer px: a
- * leader of length 720.21 came to rest at an offset of 720 and left 0.21px of
- * the dash exposed at the path start, which `stroke-linecap: round` paints as a
- * full-width dot. A yellow dot therefore sat on the grid one reveal before its
- * own region was drawn — inside the frame, above the type floor, and invisible
- * to every gate. Any offset between the length and twice it is still inside the
- * pattern's gap, so the slack costs nothing.
+ * The `drawFrom` this replaced needed the emitter to know the path's length at
+ * BUILD time —
+ * `Math.hypot(knee.x - start.x, knee.y - start.y) + b.w` in annotated-figure,
+ * `perimeter(b)` in grid — which is arithmetic about a shape the browser is
+ * going to measure anyway, kept in step by hand. DrawSVG asks the path.
+ *
+ * It also retires a bug the hand-computed version had. GSAP writes
+ * `strokeDashoffset` back as an integer px, so a leader of length 720.21 came to
+ * rest at an offset of 720 and left 0.21px of dash exposed at the path start,
+ * which `stroke-linecap: round` paints as a full-width dot: a yellow dot sat on
+ * the grid one reveal before its own region was drawn, inside the frame, above
+ * the type floor, and invisible to every gate. That is why the old `drawFrom`
+ * rounded up and added a pixel of slack. A percentage has no remainder to leave.
+ *
+ * Safe under capture because a plugin's `render()` is part of being seeked,
+ * unlike a callback — see `DRAWSVG_SRC` in composition.ts for the measurement.
+ * Anything drawn this way still obeys invariant 2: it is a `fromTo`, always.
+ */
+export declare const DRAW_FROM: Vars;
+export declare const DRAW_TO: Vars;
+/**
+ * Something travels a polyline — a pulse along an arrow, a marker ring along a
+ * curve, a highlight down a divider: one `x`/`y` `fromTo` per leg, each leg's
+ * share of `seconds` proportional to its length, `ease: "none"` until the last
+ * leg, which settles with `power2.out`. Only the first leg renders
+ * immediately; every later one is `immediateRender: false` and starts exactly
+ * where the leg before it ended, so the route reads as one motion under any
+ * seek. `x`/`y` are TRANSLATIONS, so author the traveller at the origin —
+ * `<circle r="6">` — and give the route in the same user space as the parts it
+ * passes. A transform rather than `attr: { cx, cy }` so one verb moves an SVG
+ * dot and an HTML rule alike; not MotionPath, which is not loaded.
+ *
+ * ONE CALL PER ELEMENT. The first leg's immediate render is the one that
+ * (element, x/y) gets; a second route on the same element would need
+ * `immediateRender: false` and a `from` equal to the first route's end, which
+ * is not where a second route starts. A pulse per arrow, not one pulse reused.
+ *
+ * Every leg starts where the last one ended, printed at two places, and lint
+ * reads `at + duration` back in floating point: 0.1 + 0.2 is 0.30000000000000004,
+ * which `overlapping_gsap_tweens` reports as a 4e-17s overlap with the leg at
+ * 0.3 (measured on 0.7.90). So a leg whose float sum overshoots its successor
+ * is shortened by a hundredth — a rest at the corner under one frame long —
+ * and the corner itself, and the arrival at `at + seconds`, stay where they
+ * were scheduled.
  */
-export declare function drawFrom(length: number): Vars;
+export declare function travel(target: string, route: readonly Pt[], at: number, seconds: number): Tween[];
 /** Scene-scoped element id. Every timeline selector is built from one of these. */
 export declare function id(sid: string, part: string, i?: number): string;
 /**
@@ -68,13 +104,36 @@ export declare function id(sid: string, part: string, i?: number): string;
  * Every archetype sizes its boxes and padding through this function. When two of
  * them disagree about how wide "Reconstruction" is, one of them clips.
  */
-export declare function textWidth(text: string, fontSize: number, weight?: number, tracking?: number, tabular?: boolean): number;
+/**
+ * Which face actually draws a run.
+ *
+ * A deck that bundles a CJK family sets EVERY run in it, ASCII included, because
+ * `fontStack` puts that family ahead of Inter and it covers Latin. So the face is
+ * a property of the DECK, not of the characters in one run — and a run of pure
+ * ASCII inside a Korean deck is drawn by the Korean face even though nothing in
+ * it is Korean.
+ *
+ * `"latin"` is not "no CJK in this string"; it is "this deck bundles no CJK
+ * family". Passing it for a run that does contain CJK would be a lie, which is
+ * why the auto-detection below still runs underneath: the parameter can only
+ * widen what a run is charged, never narrow it.
+ */
+export type Face = "latin" | "cjk" | "hangul";
+/**
+ * The face a theme's stack will use, from the family `familyFor` put in front.
+ *
+ * Korean is split out because it is the one character the four bundled families
+ * disagree about: KR draws the middle dot at 0.561em where JP, SC and TC draw it
+ * on the em grid at 1.0.
+ */
+export declare function faceOf(fontStack: string): Face;
+export declare function textWidth(text: string, fontSize: number, weight?: number, tracking?: number, tabular?: boolean, face?: Face): number;
 /**
  * Greedy word wrap to `maxWidth`. A word wider than the line is broken by
  * character — which is also how Korean and Chinese wrap, since they arrive as
  * one unbroken "word".
  */
-export declare function wrap(text: string, fontSize: number, maxWidth: number, weight?: number, tracking?: number): string[];
+export declare function wrap(text: string, fontSize: number, maxWidth: number, weight?: number, tracking?: number, face?: Face): string[];
 /** The SVG root. Width and height match the viewBox so px and user units agree. */
 export declare function svg(elementId: string, w: number, h: number, body: string): string;
 export declare function rect(b: Box, a?: Attrs): string;
@@ -100,6 +159,11 @@ export interface TextOptions {
     vAlign?: "baseline" | "middle";
     class?: string;
     id?: string;
+    /**
+     * The face the deck's stack will draw this in. Only consulted when `maxWidth`
+     * makes this text wrap — an unwrapped run is measured by nothing here.
+     */
+    face?: Face;
 }
 export declare function text(content: string, at: Pt, o: TextOptions): string;
 export interface ArrowOptions {

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

@@ -16,6 +16,7 @@ import { type Scene } from "./kit.js";
 import type { DeckTheme } from "./themes/index.js";
 export { type DeckTheme, ink, mono, paper, resolveTheme, THEME_NAMES, THEMES, } from "./themes/index.js";
 /** Where `ingest` writes the subsetted font bundle, relative to the deck. */
+export declare const FONT_BUNDLE_DIR = "assets/fonts";
 export declare const FONT_BUNDLE_HREF = "assets/fonts/fonts.css";
 /** A luminance breath. Safe on an element an entrance tween already moves. */
 export declare const BREATHE = "ds-breathe 6s ease-in-out infinite alternate";

package/dist/types/images/illustrate.d.ts

@@ -0,0 +1,34 @@
+import type { Prefs } from "../prefs.js";
+import { type Source, type Storyboard } from "../types.js";
+import { type ImageProvider } from "./providers.js";
+export interface IllustrateOpts {
+    prefs: Prefs;
+    /** `<dir of source.json>/assets`. Created if missing. */
+    assetsDir: string;
+    /** Tests inject; the default is `imageChain(prefs.images, resolveImageBackend())`. */
+    chain?: ImageProvider[];
+    /** Progress lines. Silent by default, for the reason `buildDeck` gives. */
+    onStep?: (message: string) => void;
+}
+export interface Illustrated {
+    beatId: string;
+    figureId: string;
+    /** Which rung drew it. */
+    provider: string;
+    /** The figure's `src`: a file name under `assetsDir`. */
+    src: string;
+    /** Found on disk from an earlier run; no provider was asked. */
+    cached: boolean;
+}
+/**
+ * Draw every pending brief. Always finishes: the tool rung is last and pure.
+ *
+ * Returns fresh objects parsed through the schemas; the ones passed in are not
+ * touched, so a caller that keeps the old storyboard around still holds the
+ * pending one.
+ */
+export declare function illustrate(storyboard: Storyboard, source: Source, opts: IllustrateOpts): Promise<{
+    storyboard: Storyboard;
+    source: Source;
+    illustrated: Illustrated[];
+}>;

package/dist/types/images/providers.d.ts

@@ -0,0 +1,108 @@
+import { type Runner } from "../plan/codex.js";
+import type { ImagesPrefs } from "../types.js";
+export type ImageAspect = "landscape" | "square" | "portrait";
+export interface ImageRequest {
+    /** The scene. Never text, labels, numbers or charts — nothing in a picture can be read or checked. */
+    prompt: string;
+    /** `images.style`, folded into every prompt. */
+    style: string;
+    aspect: ImageAspect;
+    /**
+     * `images.model`, for the separate backend only; the Codex and tool rungs
+     * ignore it. Carried on the request rather than baked into the provider
+     * because the provider is resolved from the environment before any
+     * preferences are known, and a `--image-model` that changed only the cache
+     * key would be a flag that does nothing.
+     */
+    model?: string;
+}
+export interface ImageResult {
+    bytes: Buffer;
+    mime: "image/png" | "image/jpeg" | "image/svg+xml";
+    width: number;
+    height: number;
+}
+/**
+ * One rung. `check` is separate from `generate` for the reason `SpeechProvider`
+ * splits them: a missing key is reported before a picture is asked for, not
+ * two minutes into one.
+ */
+export interface ImageProvider {
+    readonly id: string;
+    /** Throws with an actionable sentence. */
+    check(): Promise<void>;
+    generate(req: ImageRequest): Promise<ImageResult>;
+}
+/** Pixels per aspect — the backend's `size`, and the tool's viewBox. */
+export declare const SIZE: Readonly<Record<ImageAspect, {
+    width: number;
+    height: number;
+}>>;
+export interface OpenAiImagesOptions {
+    apiKey: string;
+    /** `POST {baseUrl}/images/generations`. LocalAI and most gateways speak this. */
+    baseUrl?: string;
+    /** Default when the request names none. */
+    model?: string;
+    /** Injected by tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * Any OpenAI-compatible images endpoint.
+ *
+ * Errors are shaped here rather than passed through: the message is status plus
+ * the API's `error.code` (or `type`), never its text and never a URL, so it can
+ * go straight into a job log a stranger reads. The key is used exactly once,
+ * on the generation request — a `url` in the answer is fetched bare, and only
+ * when it sits on the backend's own origin, because following an arbitrary URL
+ * with or without the key is how a gateway's answer becomes an open proxy.
+ */
+export declare function openaiImages(opts: OpenAiImagesOptions): ImageProvider;
+export interface CodexImagesOptions {
+    /** Injected by tests; `runCodex` otherwise. */
+    run?: Runner;
+    timeoutMs?: number;
+}
+/**
+ * The main account, drawing with its own image tool.
+ *
+ * `codex exec` runs in a scratch directory under `workspace-write`, which
+ * `codexCommand` fences to that directory and nothing else, and is asked to
+ * leave one PNG there. An account without the tool answers `ok:false` and says
+ * why; that reason is the error, verbatim, because it is the one thing the
+ * user can act on. Whether non-interactive `codex exec` exposes the tool at all
+ * is the hypothesis the design's live run settles — this code is written for
+ * either answer.
+ */
+export declare function codexImages(opts?: CodexImagesOptions): ImageProvider;
+/**
+ * The picture the tool draws for itself: six to ten overlapping shapes in one
+ * accent and the ink, seeded from the brief. Not an illustration of the scene —
+ * a stable, text-free composition that keeps the slide's layout honest until
+ * something better draws it. Same request, same bytes.
+ */
+export declare function drawSvg(req: ImageRequest): string;
+/** The size the tool wrote into its own SVG. `imageSize` is raster-only on purpose. */
+export declare function svgSize(bytes: Buffer): {
+    width: number;
+    height: number;
+};
+/** The last rung. Pure, so it cannot fail, so `illustrate` always finishes. */
+export declare function toolSvg(): ImageProvider;
+/**
+ * The backend the environment names, or nothing.
+ *
+ * Environment only, mirroring `DECKSMITH_TTS`: a key is never a preference,
+ * never in a config file and never in a `.deck`. Naming a backend without its
+ * key, or naming one this build does not have, throws HERE — at `illustrate`
+ * on the CLI, in the server's preflight, in MCP `capabilities` — and nowhere
+ * at import, so a broken deployment is a sentence in the log rather than a
+ * process that will not start.
+ */
+export declare function resolveImageBackend(env?: NodeJS.ProcessEnv): ImageProvider | undefined;
+/**
+ * The rungs, in the order `illustrate` tries them, for one preference.
+ * `auto` is all three; `codex` skips the backend; `svg` is the tool alone — no
+ * network, no spend, and a deck whose every picture is reproducible.
+ */
+export declare function imageChain(images: ImagesPrefs, backend?: ImageProvider): ImageProvider[];

package/dist/types/index.d.ts

@@ -34,7 +34,7 @@ export type { CodexOptions, Runner } from "./plan/codex.js";
  * not contain. `buildDeck` does not call it — a caller assembling a storyboard
  * by hand wants this before it spends a render on a dangling ref.
  */
-export { assertInsideResolves, assertRefsResolve } from "./plan/refs.js";
+export { assertInsideResolves, assertRefsResolve, hasIllustrations } from "./plan/refs.js";
 /** The prompt, so a consumer driving its own model can reproduce our planning. */
 export { renderSource, systemPrompt } from "./plan/prompt.js";
 /**
@@ -42,8 +42,22 @@ export { renderSource, systemPrompt } from "./plan/prompt.js";
  * turned into the two derived ones. Pure arithmetic over preferences, so a
  * caller can ask what a target costs before spending a plan on it.
  */
-export { COMFORTABLE_CPS, durationPlan, slidesFor, LAST_HOLD_SECONDS, MAX_PLAYBACK, MIN_SENTENCE_CHARS, MOTION_SHARE, p95CueRate, playbackFactor, playbackWarning, SPEAKING_STOPS, SPEECH_CPS, STOPS_PER_BEAT, tempoChain, } from "./plan/duration.js";
+export { COMFORTABLE_CPS, durationPlan, slidesFor, LAST_HOLD_SECONDS, MAX_PLAYBACK, MIN_SENTENCE_CHARS, MOTION_SHARE, p95CueRate, playbackFactor, playbackRefusal, playbackWarning, SPEAKING_STOPS, SPEECH_CPS, STOPS_PER_BEAT, tempoChain, } from "./plan/duration.js";
 export type { DurationPlan } from "./plan/duration.js";
+/**
+ * Pictures for the beats that asked for one. `illustrate` is a plan-time step
+ * like `narrate` — it writes files beside the source and rewrites both
+ * documents — so a server runs it between `plan` and `build` and hands the
+ * returned objects on; nothing after it knows a figure was generated.
+ * `resolveImageBackend` and `imageChain` are the two halves of "where the
+ * pictures come from": the environment names a backend, the preference says
+ * where the chain starts, and a caller that wants neither injects its own
+ * `ImageProvider[]` — which is how a server's tests never spawn Codex.
+ */
+export { illustrate } from "./images/illustrate.js";
+export type { Illustrated, IllustrateOpts } from "./images/illustrate.js";
+export { imageChain, resolveImageBackend } from "./images/providers.js";
+export type { ImageAspect, ImageProvider, ImageRequest, ImageResult, } from "./images/providers.js";
 /**
  * Text-to-speech over a storyboard. Needs the `edge-tts` binary on PATH, which
  * is why it is a separate call and not a `buildDeck` option.
@@ -87,12 +101,17 @@ export type { DeckTheme } from "./emit/themes/index.js";
  */
 export { verify } from "./verify/index.js";
 /**
- * The storyboard advisory `plan` prints and `verify` folds in: a headline that
- * recites the visual's own labels as a list. Exported because it is pure over a
- * storyboard — no browser, no built deck — so a caller can run it on a plan
- * before spending anything on it, which is the only moment it is worth acting on.
- */
-export { scanHeadlines, scanNarrationLead, scanRepeatedObject } from "./verify/index.js";
+ * The storyboard advisories `plan` prints: a headline that recites the visual's
+ * own labels as a list, one object drawn twice, a name spoken before it is drawn,
+ * a source figure the deck never uses, and a plan that came back under the slide
+ * count it was asked for. Exported because they are pure over a storyboard — no
+ * browser, no built deck — so a caller can run them on a plan before spending
+ * anything on it, which is the only moment they are worth acting on. All but
+ * `scanBeatCount` also fold into `verify`; that one needs the preferences the
+ * deck was asked for, which a built directory does not carry — and
+ * `scanUnusedFigures` folds in only where the source was passed alongside.
+ */
+export { scanBeatCount, scanHeadlines, scanNarrationLead, scanRepeatedObject, scanUnusedFigures, } from "./verify/index.js";
 export { check, parseCheckReport, sampleTimes } from "./verify/check.js";
 export type { CheckOptions } from "./verify/check.js";
 /**

package/dist/types/mcp/prereqs.d.ts

@@ -15,6 +15,24 @@ export interface Prereq {
  * probe is therefore advisory — hence the honest `neededFor` naming both stages.
  */
 export declare function prereqs(): Promise<Prereq[]>;
+/**
+ * Where pictures would come from, asked the same way and for the same reason.
+ *
+ * Not a `Prereq`, because nothing has to be installed: the last rung is an SVG
+ * the tool draws itself, so a request for illustrations never fails for lack of
+ * a backend. What CAN be wrong is a backend the environment names and cannot
+ * use — DECKSMITH_IMAGES set, the key not — and that is a misconfiguration to
+ * report before the plan is paid for, not a stage to skip. `why` is the
+ * library's own sentence, which names the variable and never carries the key.
+ *
+ * `env` is injected in tests, like `probe`: which backend this machine happens
+ * to name is not what a test is about.
+ */
+export declare function imageBackend(env?: NodeJS.ProcessEnv): {
+    backend: string | null;
+    ok: boolean;
+    why?: string;
+};
 /** The ones a job with these options actually needs, and which are missing. */
 export declare function missingFor(found: readonly Prereq[], opts: {
     narrate: boolean;

package/dist/types/mcp/tools.d.ts

@@ -39,6 +39,7 @@ export declare const settingsSchema: z.ZodObject<{
         low: "low";
     }>>;
     video: z.ZodOptional<z.ZodBoolean>;
+    images: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type Settings = z.infer<typeof settingsSchema>;
 export declare const capabilitiesSchema: z.ZodObject<{}, z.core.$strip>;
@@ -75,6 +76,7 @@ export declare const estimateSchema: z.ZodObject<{
             low: "low";
         }>>;
         video: z.ZodOptional<z.ZodBoolean>;
+        images: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const createSchema: z.ZodObject<{
@@ -112,6 +114,7 @@ export declare const createSchema: z.ZodObject<{
             low: "low";
         }>>;
         video: z.ZodOptional<z.ZodBoolean>;
+        images: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     wait_seconds: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
@@ -132,6 +135,13 @@ export interface McpOptions {
      * probe, so the server itself is unchanged.
      */
     probe?: () => Promise<Prereq[]>;
+    /**
+     * The environment the image backend is resolved from, for `capabilities` and
+     * the refusal in `create`. Injected for the reason `probe` is. The pipeline
+     * itself still reads `process.env` when its `illustrate` stage runs — in a
+     * server the two are the same object, and a test never lets a job get there.
+     */
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * The four tools, over one queue.
@@ -143,6 +153,11 @@ export interface McpOptions {
 export declare function deckTools(opts: McpOptions): {
     /** Formats, themes, every setting's range, and what is actually installed. */
     capabilities(): Promise<{
+        images: {
+            backend: string | null;
+            ok: boolean;
+            why?: string;
+        };
         prerequisites: Prereq[];
         root: string;
         work: string;
@@ -155,6 +170,14 @@ export declare function deckTools(opts: McpOptions): {
      * the author what their settings cost ("60s over 12 slides leaves 85
      * characters a slide, which is one sentence"), and an MCP that swallowed
      * them would ship the exact failure this project keeps having.
+     *
+     * EVERY NUMBER HERE IS AT THE REQUESTED SLIDE COUNT, which is the only one a
+     * pre-flight has — there is no plan yet, so there are no beats to strike the
+     * budget at. `create` below builds the deck at the count the planner returns
+     * (see `durationPlan`'s header), so a plan that comes back short reports
+     * different numbers than this did, and `scanBeatCount` says by how much. The
+     * field names carry it: `slides` is the request, and everything `_per_slide`
+     * is per requested slide.
      */
     estimate(input: z.infer<typeof estimateSchema>): {
         slides: number;

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

@@ -13,12 +13,34 @@ export interface CodexOptions {
     /** Swappable so a test can drive the real parse path without spawning anything. */
     run?: Runner;
 }
-/** What the planner needs from the outside world: a prompt in, a final message out. */
-export type Runner = (args: {
+export interface RunnerArgs {
     prompt: string;
     schemaPath: string;
     outPath: string;
     model?: string;
     timeoutMs: number;
-}) => Promise<void>;
+    /** Where the agent runs. Absent means wherever this process is, which planning never cares about. */
+    cwd?: string;
+    /**
+     * `read-only` unless said otherwise. `workspace-write` exists for the one
+     * caller that needs a file back — `illustrate`'s Codex rung — and needs a
+     * `cwd` to fence the writes to.
+     */
+    sandbox?: "read-only" | "workspace-write";
+}
+/** What the planner needs from the outside world: a prompt in, a final message out. */
+export type Runner = (args: RunnerArgs) => Promise<void>;
 export declare function codexPlanner(source: Source, opts?: CodexOptions): Promise<Storyboard>;
+/**
+ * The `codex` command line for a run, and the environment it needs.
+ *
+ * Pure, and exported for that reason: the argv is a contract with a binary
+ * nothing in the test suite may spawn, so it is pinned by reading this rather
+ * than by running it.
+ */
+export declare function codexCommand(args: RunnerArgs): {
+    argv: string[];
+    env?: NodeJS.ProcessEnv;
+};
+/** The production `Runner`: `codex exec` on PATH, stdin in, a file out. */
+export declare function runCodex(args: RunnerArgs): Promise<void>;