@jokerized/decksmith 0.1.3 → 0.2.0

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>;

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

@@ -23,10 +23,27 @@
  * else, so hitting 60s over 12 slides needs a shorter sentence AND a faster
  * animation. Neither alone gets there; that is the whole content of this file.
  *
+ * WHICH SLIDE COUNT THE BUDGET IS STRUCK AT. `prefs.slides` is what was ASKED
+ * FOR and `beats` is what the planner came back with, and they are routinely not
+ * the same number — four of the last five real plans came back short. Every
+ * derived number here is `duration / count`, so striking the budget at the
+ * request while the deck has fewer beats paces each scene for a slide shorter
+ * than the one it is: eight beats against a sixty-second target were paced for
+ * five-second beats that are really seven and a half, and the video came in
+ * under its target with every gate green and nothing anywhere saying so. So
+ * every caller holding a storyboard passes its `beats.length`. The two that
+ * cannot are `systemPrompt`, which builds the prompt before a plan exists, and
+ * the MCP `estimate`, which is a pre-flight with no plan at all; they get the
+ * request, which is the only number they have. The SHORTFALL itself is not this
+ * file's to report — `scanBeatCount` in src/verify/index.ts reports it, because
+ * a beat count is arithmetic rather than a judgement and a prompt rule alone can
+ * always be met cosmetically.
+ *
  * Everything here is pure arithmetic over preferences, so it is testable with no
  * planner, no TTS and no ffmpeg.
  */
 import type { Prefs } from "../prefs.js";
+import type { Source } from "../types.js";
 /**
  * Characters of text per second of speech.
  *
@@ -174,6 +191,17 @@ export declare const FF_BEAT_SECONDS = 8;
  * for both put 60 seconds at eight slides when the reference is twelve.
  */
 export declare const MIN_BEAT_SECONDS = 4;
+/**
+ * The longest a slide may sit and still be one thought.
+ *
+ * Past twenty seconds a beat stops being a slide and becomes a section of a
+ * lecture: the demo sits at 20.5s and is already the slowest thing this project
+ * ships. It was the bare `20` inside `slidesFor`'s tempo clamp; it is named
+ * because that function now uses it twice — once to stop a long target from
+ * flattening into a handful of enormous beats, and once as the floor a thin
+ * DOCUMENT may shorten the deck to. Both are the same rule.
+ */
+export declare const MAX_BEAT_SECONDS = 20;
 /**
  * Subtitle rate a short-form viewer will take, as against broadcast television.
  *
@@ -212,13 +240,66 @@ export declare const SHORT_FORM_CPS = 22;
  * takes `+10%` and lands at 21.9. Wrong in the OUTPUT, not in a gate — no gate
  * looks at this, which is why it survived.
  *
- * SCALE-INVARIANCE IS ASSUMED, and is the one thing here not measured: the ratio
- * is taken at `+0%` and applied at every step, on the reasoning that speeding the
- * voice up shrinks the cue windows and the breaths between them together.
- * Measuring it at `+10%` and `+20%` means synthesising the demo again at those
- * rates. `test/duration.test.ts` pins the `+0%` end against the artifact.
+ * SCALE-INVARIANCE IS MEASURED, and it holds. The ratio is taken at `+0%` and
+ * applied at every step, on the reasoning that speeding the voice up shrinks the
+ * cue windows and the breaths between them together. `scripts/measure-cue-rate.mjs`
+ * re-synthesised all 37 segments at all five steps — `+0%` included, in one
+ * session, because edge-tts does not repeat itself and a fresh rate judged
+ * against a stored baseline measures the drift instead:
+ *
+ * ```
+ *   rate    meanCps   p95 cue   p95/mean   median/mean
+ *   +0%      14.509    18.089     1.2467        1.0601
+ *   +10%     15.752    20.392     1.2945        1.0653
+ *   +20%     17.148    21.321     1.2434        1.0567
+ *   +30%     18.540    23.263     1.2548        1.0572
+ *   +40%     20.205    25.515     1.2628        1.0663
+ * ```
+ *
+ * No trend in rate — so this stays a constant rather than becoming a function of
+ * the step. The p95 column wobbles because p95 over 39 cues IS THE SECOND-HIGHEST
+ * CUE, one window wide; `median/mean` is flat to within a percent, and it is the
+ * honest read on whether the distribution's shape moves. It does not.
+ *
+ * IT AND `RATE_STEPS` ARE ONE UNIT, and they moved together — 2026-08-02, from
+ * the run above. Read that table's `speedup` note before changing either.
+ *
+ * WHY 1.30 AND NOT 1.2945. It has to sit above EVERY ratio the run observed,
+ * because the number it feeds is a ceiling on caption readability and being
+ * under it means shipping captions faster than `SHORT_FORM_CPS`. The old 1.28
+ * was below the `+10%` reading and got away with it only because the speedups
+ * beside it were inflated by more — two errors cancelling, which is not a margin
+ * anyone can reason about. Correcting the speedups removed that cover, so this
+ * had to rise with them.
+ *
+ * IT COSTS A STEP, KNOWINGLY. The demo's real p95 cue at `+20%` is 21.321,
+ * inside the ceiling of 22 — but this predicts 22.13 for that step and refuses
+ * it, so the deck takes `+10%` and speaks slower than the artifact proves it
+ * could. It also costs the 60-second case its full sentence: twelve slides at
+ * low density plan 66 characters against the 72 of `EXPLAINING_CHARS`, where
+ * ~1.26 would plan exactly 72.
+ *
+ * 1.26 IS NOT AVAILABLE, THOUGH, and it is worth writing down why because the
+ * arithmetic above makes it look free. **The floor is 1.2784**, which is this
+ * deck's own `DEMO_P95_CUE_CPS / SPEECH_CPS.latin` — 18.409 / 14.4 — and
+ * `test/duration.test.ts` fails anything under it, one-sided and on purpose.
+ * A constant below the anchor's measured ratio admits a step whose captions are
+ * over the ceiling, which is exactly the 1.17 bug this replaced.
+ *
+ * The five ratios in the table above centre on 1.2604 and tempt you under that
+ * floor. They are a DIFFERENT synthesis of the same text: edge-tts does not
+ * repeat itself, and the `+0%` re-run came back at 1.2467 where the artifact in
+ * `demo/audio` sits at 1.2784. The shipped artifact wins — it is the deck that
+ * actually exists. So the honest range is [1.2784, 1.2945], the second number
+ * being the highest ratio the re-run saw, and 1.30 clears both.
+ *
+ * The 60-second sentence is therefore not bought back by tuning this. It is
+ * bought with seconds or with slides, which is what the rest of this file has
+ * said all along, and 90s plans 102.
+ *
+ * `test/duration.test.ts` pins the `+0%` end against the artifact.
  */
-export declare const CUE_OVERHEAD = 1.28;
+export declare const CUE_OVERHEAD = 1.3;
 /** Broadcast subtitle practice. Past this the captions stop being readable. */
 export declare const COMFORTABLE_CPS = 17;
 /** How far playback may be sped up before the captions are the problem. */
@@ -261,6 +342,29 @@ export declare const SPEAKING_STOPS: Record<Prefs["narration"]["density"], numbe
  * `+60%` it is 28.5 and the caption is gone before it is read. `+50%` is
  * excluded for measuring slower than the step below it.
  *
+ * THE SPEEDUPS BELOW ARE NOT FROM THAT TABLE. They were, and they were too high
+ * at every step. The table above times ONE 72-character sentence, and a short
+ * sentence carries proportionally more silence at its ends, so dividing its
+ * total duration overstates what the prosody rate does to speech itself.
+ * Re-measured over the anchor deck's 37 segments and 196 seconds:
+ *
+ * ```
+ *   step    was      is    from
+ *   +10%  1.187   1.086    meanCps 15.752 / 14.509
+ *   +20%  1.252   1.182    meanCps 17.148 / 14.509
+ *   +30%  1.394   1.278    meanCps 18.540 / 14.509
+ *   +40%  1.533   1.393    meanCps 20.205 / 14.509
+ * ```
+ *
+ * `CUE_OVERHEAD` rose from 1.28 to 1.30 in the same commit and for this reason:
+ * it was below the cue ratio measured at `+10%` and only safe because these
+ * numbers were inflated by more. Neither is a safe edit alone — see the
+ * paragraph there. One run of `scripts/measure-cue-rate.mjs` produces both.
+ *
+ * THE TABLE ABOVE STILL EARNS ITS PLACE, because it is the only measurement of
+ * `+50%` and `+60%` anyone has taken, and what it says about them is why this
+ * list stops at `+40%`. The re-measurement covered these five steps only.
+ *
  * Latin-measured. A CJK deck gets the same steps, which is a guess of the same
  * kind `SPEECH_CPS.cjk` already is — replace it the first time one is narrated.
  */
@@ -285,7 +389,16 @@ export interface DurationPlan {
     chars?: number;
     /** Seconds of speech one beat can afford. Absent without a target. */
     speechSeconds?: number;
-    /** The per-beat length the target implies. Absent without a target. */
+    /**
+     * The per-beat length the target implies, at the count the plan was struck at.
+     * Absent without a target.
+     *
+     * A BUDGET, NOT THE ANSWER, and the name collides with the thing that IS the
+     * answer. `beatSeconds` in src/emit/composition.ts — `max(authored·speed,
+     * lastHold + SETTLE, speechEnd + SETTLE)` — is what actually sizes a scene,
+     * and it never sees this number. `speed` is the only value this file sends
+     * into the emitted timeline; everything else here is advice to the planner.
+     */
     beatSeconds?: number;
     /** Said, never fatal: what the target costs, or cannot buy. */
     warnings: string[];
@@ -300,8 +413,14 @@ export interface DurationPlan {
  * `duration` set OVERRIDES `animationSpeed`: the target owns the pace, because
  * the two cannot both be honoured and the target is the one the user stated a
  * number for. Said in a warning rather than silently.
+ *
+ * `beats` is the count the budget is struck at, and it defaults to the count
+ * that was asked for. Pass the storyboard's own `beats.length` wherever one is
+ * in hand — see the header for why, and for the two callers that structurally
+ * cannot. The default is not a convenience: it is the right answer for those
+ * two, and it is what keeps a run where the planner hit its number identical.
  */
-export declare function durationPlan(prefs: Prefs): DurationPlan;
+export declare function durationPlan(prefs: Prefs, beats?: number): DurationPlan;
 /**
  * How many slides a target should have, by TEMPO.
  *
@@ -328,11 +447,90 @@ export declare function durationPlan(prefs: Prefs): DurationPlan;
  *     30s ->  8    120s -> 12    600s -> 30
  *     60s -> 12    300s -> 15
  *
+ * AND HOW MUCH THE DOCUMENT HAS TO SAY, which is the half that was missing. The
+ * table above is flat at twelve from 48s to 240s no matter what it is pointed
+ * at: a four-page workshop note and a forty-page survey both got twelve beats,
+ * because the only input was a clock. Tempo says how long a beat may LAST; it
+ * cannot say how many points exist to spend beats on. So `source`, when the
+ * caller has one, scales the tempo count by what the document actually contains
+ * (`sourcePoints`), bounded by `SUPPLY_RANGE` because the measure is coarse and
+ * its authority should be too.
+ *
+ *     60s + a thin note  ->  6      240s + a thin note  -> 12
+ *     60s + a full paper -> 15      240s + a full paper -> 17
+ *
+ * The clock still wins at both ends. Sixty seconds cannot hold seventeen beats
+ * at `MIN_BEAT_SECONDS` apiece, so a rich document against a short target spends
+ * its extra points on nothing; and past four minutes `MAX_BEAT_SECONDS` holds
+ * the count up, so a thin note asked for a long video does not become six
+ * forty-second slides. Only where the clock leaves room does the document move
+ * the number — which is most of the range people actually ask for.
+ *
+ * WHO CAN PASS A SOURCE. The CLI's `plan` verb reads `source.json` before it
+ * resolves preferences, so it can and does. `parseOptions` (src/server/options.ts)
+ * derives the count while the upload is still a form, before anything is
+ * ingested, and the MCP `estimate` is a pre-flight with no document at all;
+ * both get the tempo number, which is what they got before. Omitting the
+ * argument is therefore not a degraded path, it is the old behaviour, byte for
+ * byte.
+ *
  * This is the DEFAULT, never an override. `slides` is one of the three knobs the
  * owner asked to hold — "user can give you the number of slides they want in the
- * video with duration of their choice" — so an explicit count is obeyed.
+ * video with duration of their choice" — so an explicit count is obeyed, which
+ * is `loadPrefs`'s business: it calls this only when nobody named a number.
+ */
+export declare function slidesFor(prefs: Prefs, source?: Source): number;
+/**
+ * Characters of section prose one beat is worth.
+ *
+ * A GUESS, and marked one the way `SPEECH_CPS.cjk` is: no full-length document
+ * is stored in this repository to measure against — `demo/source.json` is a
+ * 231-character stub whose twelve beats were written by hand, and the fixture
+ * papers are 1.9 KB each. What matters is this number's RATIO to
+ * `REFERENCE_POINTS`, and the two are set together so an eight-section
+ * conference paper — around 30k characters, five figures, two tables, four
+ * equations — comes out above the reference rather than at it. Replace both with
+ * a measurement the first time a corpus of real sources exists.
  */
-export declare function slidesFor(prefs: Prefs): number;
+export declare const PROSE_CHARS_PER_BEAT = 1800;
+/**
+ * The supply a document needs to earn the tempo's own beat count.
+ *
+ * Twenty points is roughly a solid conference paper minus its trimmings. Below
+ * it the deck shortens, above it the deck lengthens, and `SUPPLY_RANGE` decides
+ * how far either can go.
+ */
+export declare const REFERENCE_POINTS = 20;
+/**
+ * How far the document may move the tempo's count, as a multiplier.
+ *
+ * Bounded rather than open because `sourcePoints` is a proxy and a proxy should
+ * not be trusted past the range where it is obviously right. Half is the
+ * shortest a deck of a real document should get before the answer is "this is
+ * not enough source"; one and a half keeps a rich paper under the twenty-second
+ * beat that makes a deck a lecture. A survey with a hundred points is not worth
+ * a hundred beats, and the clamp is what says so.
+ */
+export declare const SUPPLY_RANGE: {
+    readonly min: 0.5;
+    readonly max: 1.5;
+};
+/**
+ * How many distinct points a document offers a deck.
+ *
+ * Two supplies, added, because they are genuinely different things to make a
+ * beat out of: PROSE, which carries the argument, and EXHIBITS — the figures,
+ * tables and equations the authors made on purpose because a sentence was not
+ * enough. RULE 2 in the prompt tells the planner every figure should earn a
+ * beat, so a document with eight of them is asking for a longer deck than one
+ * with none, and this is where that is counted rather than hoped for.
+ *
+ * Headings are deliberately NOT counted. A section boundary is a formatting
+ * decision — one author writes six headings over 20k characters and another
+ * writes twenty-four over the same prose — so counting them would measure the
+ * template rather than the document.
+ */
+export declare function sourcePoints(source: Source): number;
 /**
  * How fast this deck speaks.
  *
@@ -383,12 +581,48 @@ export declare function p95CueRate(cues: readonly {
     text: string;
 }[]): number;
 /**
- * Whether this deck's own captions survive being sped up this much.
- *
- * Computed from the deck's MEASURED p95 cue rate against broadcast practice, not
- * from a hardcoded ceiling: a deck whose captions already run at 18 cps has no
- * headroom at all, and one written in short lines has plenty. Warns, never
- * refuses — how readable a caption has to be is the user's call, and they can
- * only make it if they are told the number.
+ * What is wrong with speeding this deck up this much — everything that is.
+ *
+ * TWO CEILINGS, AND THEY ARE NOT THE SAME KIND OF THING. The caption one is
+ * computed from the deck's MEASURED p95 cue rate against broadcast practice
+ * rather than from a constant: a deck whose captions already run at 18 cps has
+ * no headroom at all, one written in short lines has plenty. That one stays
+ * pure advice — how readable a caption has to be is the user's call, and they
+ * can only make it if they are told the number. `MAX_PLAYBACK` is the other,
+ * and `playbackRefusal` below turns it into a refusal, because time-stretched
+ * audio is not a matter of taste.
+ *
+ * BOTH CLAUSES, NOT THE FIRST ONE. This used to `return` out of the caption
+ * branch, which meant a dense deck — every deck this tool plans is dense, by
+ * construction — could only ever be told about the ceiling that is advisory,
+ * and never about the one that is enforced. The measured shape: 2.14× on a
+ * 19.6 cps deck printed "readable captions cap out near 0.87×" and suppressed
+ * "past the 1.25× that reads comfortably", so the only line naming an
+ * enforceable limit was the one the user did not get.
  */
 export declare function playbackWarning(factor: number, p95: number): string | undefined;
+/**
+ * Why this target cannot be reached from this deck, when it cannot.
+ *
+ * `MAX_PLAYBACK` IS THE ONE THAT CAN BE ENFORCED. The caption ceiling cannot
+ * be, and the arithmetic is not close: `COMFORTABLE_CPS / DEMO_P95_CUE_CPS` is
+ * 17/18.409 = 0.92 on this project's own anchor deck, so a caption-derived
+ * limit is already breached at 1× and would refuse every speed-up there is —
+ * `--duration` would be dead on arrival. Every deck DeckSmith plans is denser
+ * than 17 cps by construction; see `CUE_OVERHEAD`. So the captions warn and
+ * the playback factor refuses, and `test/duration.test.ts` pins the reason.
+ *
+ * REFUSING IS NOT NEW POLICY, it is the policy the planner already keeps.
+ * `durationPlan` sizes a deck so the residual gap fits inside `MAX_PLAYBACK`,
+ * and `test/duration.test.ts` asserts exactly that at 60s, 120s, 180s and
+ * 240s. A 2.14× request is not a tight fit that slipped — it is 71% past a
+ * bound the rest of the file treats as arithmetic. What was shipping instead
+ * was a video nobody could follow, announced by a mid-render log line that 40
+ * lines of capture progress scrolled away.
+ *
+ * Both remedies are named because the honest one is not the flag: the length
+ * of a deck is decided at plan time by how much it says, so the fix is fewer
+ * words or more seconds, and `--allow-fast-playback` is for the person who has
+ * looked at the alternative and wants the fast video anyway.
+ */
+export declare function playbackRefusal(actualSeconds: number, targetSeconds: number, p95: number): string | undefined;

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

@@ -43,5 +43,11 @@ export declare function systemPrompt(prefs: Prefs): string;
  * planner's other entry points keep working unchanged.
  */
 export declare const SYSTEM: string;
-/** The document plus every id the model is allowed to cite, and nothing else. */
+/**
+ * The document plus every id the model is allowed to cite, and nothing else.
+ *
+ * The figure block carries two facts beyond the caption — the section the image
+ * sat under and the prose that refers to it — because a planner that cannot see
+ * the picture has nothing else to decide what the picture is FOR.
+ */
 export declare function renderSource(source: Source): string;