@jokerized/decksmith 0.1.0

package/dist/types/narrate/voices.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Which voice says it.
+ *
+ * A voice id is not a preference the user should have to hold: `edge-tts
+ * --list-voices` prints several hundred rows, a wrong id fails at synthesis time
+ * with an unhelpful error, and the interesting choice — language and register —
+ * is already in `prefs`. So the table below maps (lang, tone) to an id that was
+ * read off this machine's own `--list-voices`, and an explicit
+ * `prefs.narration.voice` always wins over it.
+ *
+ * Multilingual neural voices are preferred wherever Microsoft ships one: they
+ * are the newer models, they read a foreign proper noun mid-sentence without
+ * switching accent, and they are the closest thing here to a presenter rather
+ * than a reader.
+ */
+import type { z } from "zod";
+import type { prefsSchema } from "../types.js";
+type Prefs = z.infer<typeof prefsSchema>;
+/**
+ * Pick the voice for these preferences.
+ *
+ * An unlisted language falls back to the English multilingual row, which speaks
+ * some forty languages: the accent will be wrong, but a deck that narrates in a
+ * borrowed accent is worth more than one that fails to narrate at all.
+ */
+export declare function pickVoice(prefs: Prefs): string;
+/** The languages with a voice of their own. Everything else borrows English's. */
+export declare function narratableLangs(): string[];
+export {};

package/dist/types/pack/media.d.ts

@@ -0,0 +1,61 @@
+import type { z } from "zod";
+import type { mediaSchema } from "../types.js";
+import type { PackFiles } from "./pack.js";
+export type Media = z.infer<typeof mediaSchema>;
+/** What the caller asks for, before the URL gets a say. */
+export interface AssetRequest {
+    id: string;
+    /** An http(s) URL, a `data:` URL, or a local path. */
+    url: string;
+    /** The caller's choice. Ignored for player URLs, which are always embedded. */
+    prefer: "bake" | "link";
+    mime?: string;
+}
+/**
+ * Injected so tests never reach the network, and so a caller can supply its own
+ * cache. `mime` is whatever the transport knows — a sniffed type is better than
+ * a guessed extension.
+ */
+export type Fetcher = (url: string) => Promise<{
+    bytes: Uint8Array;
+    mime?: string;
+}>;
+export interface MediaPlan {
+    media: Media[];
+    /** Paths under `media/`, ready to hand to `writePack`. */
+    files: PackFiles;
+    bakedCount: number;
+    /**
+     * Baking everything on a figure-heavy paper is the difference between a 2MB
+     * pack and a 200MB one, so the total is reported rather than discovered.
+     */
+    bakedBytes: number;
+    /** Ids the caller wanted baked that travel as link or embed instead. */
+    demoted: string[];
+    /** Ids the caller wanted linked that had to be baked — see `policyFor`. */
+    promoted: string[];
+}
+/** A player URL is one whose host is in the list, or a subdomain of one. */
+export declare function isEmbed(url: string): boolean;
+/**
+ * The final policy for one asset.
+ *
+ * Baking requires confidence that the URL points at a file. A local path or a
+ * `data:` URL is one by construction; a remote URL has to end in an extension we
+ * recognise. Without that we would happily bake an HTML error page under a
+ * `.jpg`-shaped id, so an unrecognised shape stays a `link` even when the caller
+ * asked to bake it.
+ *
+ * A local path is baked even under `--link`, and that is not the caller being
+ * overridden for its own good — it is that there is no link to keep. `ingest`
+ * downloads every figure and rewrites `src` to the local copy, so by pack time
+ * the original URL is gone and "link" could only record this machine's
+ * filesystem layout. That packs clean, unpacks clean, and rebuilds into a deck
+ * whose <img>s point at nothing; the lint gate calls it missing_local_asset on
+ * the recipient's machine, which is the worst possible place to find out.
+ */
+export declare function policyFor(url: string, prefer: "bake" | "link"): Media["policy"];
+/** Resolve every asset, fetching only the ones that end up baked. */
+export declare function planMedia(assets: AssetRequest[], fetcher?: Fetcher): Promise<MediaPlan>;
+/** One line a CLI can print, because a user should know which pack they got. */
+export declare function mediaSummary(plan: MediaPlan): string;

package/dist/types/pack/pack.d.ts

@@ -0,0 +1,16 @@
+import type { z } from "zod";
+import { packSchema } from "../types.js";
+export type Pack = z.infer<typeof packSchema>;
+/** Everything in the archive except `deck.json`, keyed by its path inside it. */
+export type PackFiles = Record<string, Uint8Array>;
+/** Write `out`, returning the size of the pack so a caller can report it. */
+export declare function writePack(pack: Pack, files: PackFiles, out: string): Promise<number>;
+export declare function readPack(path: string): Promise<{
+    pack: Pack;
+    files: PackFiles;
+}>;
+/** The parse half of `readPack`, separated so bytes from anywhere can be checked. */
+export declare function openPack(bytes: Uint8Array, label?: string): {
+    pack: Pack;
+    files: PackFiles;
+};

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

@@ -0,0 +1,24 @@
+import type { Prefs } from "../prefs.js";
+import { type Source, type Storyboard } from "../types.js";
+export declare const SCHEMA: unknown;
+export interface CodexOptions {
+    /** Left unset by default: use whatever model the user's Codex is configured for. */
+    model?: string;
+    timeoutMs?: number;
+    /**
+     * What the person asking for the deck chose. Omitted means the schema's
+     * defaults, which is what a bare `codexPlanner(source)` has always sent.
+     */
+    prefs?: Prefs;
+    /** 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: {
+    prompt: string;
+    schemaPath: string;
+    outPath: string;
+    model?: string;
+    timeoutMs: number;
+}) => Promise<void>;
+export declare function codexPlanner(source: Source, opts?: CodexOptions): Promise<Storyboard>;

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

@@ -0,0 +1,394 @@
+/**
+ * A target duration, a slide count and a narration density, turned into the
+ * numbers the rest of the pipeline needs.
+ *
+ * WHY THIS IS NOT A SPEED SLIDER. `beatSeconds` (src/emit/composition.ts) is
+ * `max(authored, lastHold + spoken)`, and on the narrated demo the spoken term
+ * wins by a mile: 195.9s of speech across 37 stops. Multiplying every tween by
+ * `animationSpeed` scales the two terms it does not need to and leaves the one
+ * that decides the length untouched, so a duration control built on that knob
+ * alone would quietly do nothing. Measured, not reasoned: the demo is 246.5s at
+ * `animationSpeed: 1` and 208.6s at 0.25 — a 4× faster animation buys 15%.
+ *
+ * WHY THE BUDGET DIVIDES BY STOPS. `planSegments` cuts a beat's narration one
+ * sentence per stop, and the demo has 12 beats and 37 stops. A 60-second target
+ * spread over 37 stops is 1.6s each — 24 characters, four words. That is not
+ * narration, which is why low density means FEWER NARRATED STOPS rather than
+ * shorter sentences: one sentence per beat gives 12 stops and 5 seconds each.
+ *
+ * WHY BOTH KNOBS ARE STILL NEEDED. Once only one stop per beat speaks, the
+ * binding term flips: the demo drops to 116.9s, and what holds it there is
+ * `lastHold` — a six-stage pipeline reveals its last stage at 7.8s no matter how
+ * short its sentence is. `lastHold` scales with `animationSpeed` and nothing
+ * 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.
+ *
+ * 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";
+/**
+ * Characters of text per second of speech.
+ *
+ * `latin` is MEASURED on demo/audio/narration.json: 2829 characters over 195.9
+ * seconds is 14.44, and the per-cue mean is 15.03. `cjk` is a GUESS — a Korean
+ * or Japanese character carries several times the Latin one, and no narrated CJK
+ * deck exists in this repo to measure. It is here so a Korean deck's budget is
+ * wrong by a little rather than by 2×; replace it with a measurement the first
+ * time one is narrated.
+ */
+export declare const SPEECH_CPS: {
+    readonly latin: 14.4;
+    readonly cjk: 6.5;
+};
+/**
+ * Seconds from a scene's start to its LAST hold, at `animationSpeed: 1`.
+ *
+ * MEASURED as the mean over the demo's twelve beats (50.5s / 12), from
+ * `emitScene(beat).holds` rather than from anything authored. It is the floor a
+ * beat cannot go under without cutting off its own final reveal, and it is why
+ * the speech budget below is `beat − lastHold`, not `beat`.
+ *
+ * ponytail: one mean over twelve beats, not a per-archetype table. The spread is
+ * real (1.9s for a title, 7.8s for a six-stage pipeline), so a deck of nothing
+ * but pipelines will overshoot — which the bounded playback retime then closes.
+ * Predict per-beat from `REVEALS` if that stops being good enough.
+ */
+export declare const LAST_HOLD_SECONDS = 4.2;
+/** Stops per beat, measured: 37 stops over the demo's 12 beats. */
+export declare const STOPS_PER_BEAT = 3.1;
+/**
+ * How much of a beat is reserved for its reveal schedule rather than its speech.
+ *
+ * ponytail: one tuned constant. Today's narrated demo sits at 0.20 (50.5s of
+ * holds in 246.5s of deck) because speech dominates; at one sentence per beat it
+ * sits at 0.43. 0.35 splits the difference and leaves speech the majority, which
+ * is the right way round for a narrated deck. Lower it if the animation reads as
+ * rushed, raise it if the voice sounds crammed.
+ */
+export declare const MOTION_SHARE = 0.35;
+/** Below this a "sentence" is a fragment. About five words of English. */
+export declare const MIN_SENTENCE_CHARS = 30;
+/**
+ * The scene chrome's settle time at `animationSpeed: 1`, in seconds.
+ *
+ * The eyebrow runs at 0.15s over 0.5s and the headline at 0.3s over 0.6s, so the
+ * headline lands at 0.9s and that is when the voice may start. `openSeconds` in
+ * src/emit/composition.ts reads the real number off the real scene; this is the
+ * same number in closed form, because the budget has to be struck before any
+ * scene exists to measure. They agree by construction on every archetype that
+ * uses the shared chrome, and the emitter's measured value is what the deck is
+ * actually built with.
+ */
+export declare const OPEN_SECONDS_AT_SPEED = 0.9;
+/** Stillness after the last word, before the cut. `HANDOFF_SECONDS`. */
+export declare const SETTLE_SECONDS = 0.4;
+/**
+ * The sentence length this deck aims for: what "explains something" measures.
+ *
+ * MEASURED on `demo/storyboard.json`, the deck every other number in this file
+ * is measured against: 39 narration sentences, mean 72.1 characters, median 74,
+ * first quartile 59.
+ *
+ * IT WAS 60 — the first quartile — and that was the wrong number twice over. It
+ * was picked as a FLOOR, "below this a slide captions rather than explains", and
+ * the owner then rejected two decks that cleared it, both times in the same
+ * words: too short to explain the paper. A floor is what a deck must not go
+ * under; a target is what it should hit. `fastEnough` reads this as a target, so
+ * a bar set at the worst quarter of the deck that works produced decks at the
+ * worst quarter of the deck that works.
+ *
+ * So it is the MEAN of the deck that works. At a 60-second target over twelve
+ * slides that is reached at a `+10%` speaking rate, against the `+30%` the
+ * first-quartile bar demanded — more words AND more readable captions, because
+ * the seconds came from overlapping speech with motion rather than from speed.
+ *
+ * Distinct from `MIN_SENTENCE_CHARS`, which is where a sentence stops being a
+ * sentence at all. Between the two the deck is perfectly buildable and thin,
+ * and that is a thing to be TOLD rather than prevented — the arithmetic is not
+ * wrong, it is just what the requested slide count costs, and only the author
+ * can decide whether to spend slides or seconds to buy it back.
+ *
+ * RAISE THIS to make every deck say more, at the cost of the subtitle: the
+ * physical ceiling is the speech time a target has (`duration - slides * quiet`)
+ * times the fastest rate `RATE_STEPS` allows, which at 60s over twelve slides is
+ * about 94 characters a slide.
+ */
+export declare const EXPLAINING_CHARS = 72;
+/**
+ * Sentences a beat needs before its narration can be a story rather than a label.
+ *
+ * TWO, and it is the demo that says so rather than taste. `demo/storyboard.json`
+ * writes 39 sentences over 12 beats — 3.25 each — and every bit of its
+ * storytelling lives in the second and third: "Then the field is cut into
+ * windows...", "Only at the very end does the decoder upsample...", "That loop is
+ * a single tick...", "So this is not the cheap option, and the paper never claims
+ * it is." The flow is INSIDE a beat, between its own sentences.
+ *
+ * Reduce that same deck to its FIRST sentence per beat — which is literally what
+ * a 60-second target over twelve slides buys — and the deck that works reads like
+ * this:
+ *
+ *     The encoder does the heavy lifting first.
+ *     The encoder turns the low-resolution image into a dense feature field.
+ *     The first tick is worth almost a full decibel.
+ *
+ * Twelve disconnected statements. So one sentence per beat cannot flow no matter
+ * who writes it, and the owner's complaint — "they don't have a flow, just
+ * sentence by sentence" — is arithmetic, not prose quality.
+ *
+ * THAT CONCLUSION IS TRUE OF A LECTURE AND FALSE OF A TEASER, which is why this
+ * only governs beats longer than `FF_BEAT_SECONDS`. A conference fast-forward
+ * talk runs one sentence a slide across a dozen slides and flows perfectly well,
+ * because its flow comes from the SCRIPT being continuous — the prompt's "the
+ * deck is one script, not N captions" — rather than from paragraphs inside each
+ * beat. The demo is a four-minute deck, and reading its shape onto a
+ * sixty-second teaser is what produced five slides and 133 words a minute.
+ *
+ * WHY THIS IS A COUNT AND NOT A COHESION SCORE. The obvious check is to measure
+ * connectives and anaphora in the finished narration. It was built and then
+ * defeated: prefixing one discourse marker to each of the twelve rejected
+ * sentences — changing no content, no claim, no relation — moved the score from
+ * 42% to 92%, ABOVE the hand-written demo's 74%. That is §9's lesson exactly, so
+ * the thing measured here is the BUDGET, which is not a judgement and cannot be
+ * written around.
+ */
+export declare const SENTENCES_PER_BEAT = 2;
+/**
+ * Beat length below which a deck is a fast-forward talk rather than a lecture.
+ *
+ * The conference teaser: sixty seconds, a dozen slides, the voice never stopping.
+ * A beat this short cannot afford a leisurely delivery, so `fastEnough` stops
+ * asking for the SLOWEST rate that clears a sentence and takes the FASTEST the
+ * captions can carry — which is the difference between 133 words a minute and
+ * 180, on the same seconds.
+ */
+export declare const FF_BEAT_SECONDS = 8;
+/**
+ * The shortest a slide may be and still be seen.
+ *
+ * A fast-forward talk runs four to six seconds a slide; under four the deck is
+ * flicking rather than presenting, and the build has no room to read. This is the
+ * floor `slidesFor` clamps the beat length to, distinct from `FF_BEAT_SECONDS`,
+ * which is the threshold that decides how fast the voice goes — using one number
+ * for both put 60 seconds at eight slides when the reference is twelve.
+ */
+export declare const MIN_BEAT_SECONDS = 4;
+/**
+ * Subtitle rate a short-form viewer will take, as against broadcast television.
+ *
+ * `COMFORTABLE_CPS` is 17 and comes from broadcast practice, where the viewer is
+ * across a room and did not choose the subtitle. A one-minute research teaser is
+ * neither. The anchor is this project's own artifact: `demo/audio/narration.json`
+ * — the deck every other number here is measured against — runs a p95 of 18.41
+ * cps, already past the broadcast bar, and nobody has ever complained about it.
+ *
+ * 22 is that with the headroom a fast-forward talk needs, and it is the ceiling
+ * rather than a target: `fastEnough` only goes as fast as the beat requires.
+ */
+export declare const SHORT_FORM_CPS = 22;
+/**
+ * How much faster a CUE reads, at its p95, than the deck's mean spoken rate.
+ *
+ * TWO things at once, deliberately, because `fastEnough` has only one number to
+ * multiply: a cue spans the words and not the breath around them, and the CUE
+ * that decides whether captions are readable is the fastest one, not the average.
+ * So this converts a mean spoken cps into a p95 CUE cps — the quantity
+ * `SHORT_FORM_CPS` is a ceiling on.
+ *
+ * MEASURED on `demo/audio/narration.json`, this project's anchor deck, whose 37
+ * segments carry 39 cues. Its mean segment rate is 14.440 cps — `SPEECH_CPS.latin`
+ * to three figures, which is where that constant comes from — and its p95 cue
+ * rate is 18.409. That is a ratio of 1.278, and 1.28 rounds AWAY from admitting a
+ * step, which is the safe direction for a ceiling.
+ *
+ * IT SAID 1.17 UNTIL NOW, and 1.17 was never reconcilable with the file it lives
+ * in: `SHORT_FORM_CPS` two constants above already quotes the same deck's p95 at
+ * 18.41, and 18.41/14.4 is 1.28, not 1.17. The old table paired a `.srt` against
+ * an arithmetic speech rate and got 16.6 cps at `+0%` where the anchor artifact
+ * reads 18.41 — a measurement of something that is not this. What shipped from it
+ * was a fast-forward deck at `+20%` (speedup 1.252), whose captions land at
+ * 14.4 x 1.252 x 1.278 = 23.0 cps against a ceiling of 22. At 1.28 the same deck
+ * 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.
+ */
+export declare const CUE_OVERHEAD = 1.28;
+/** 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. */
+export declare const MAX_PLAYBACK = 1.25;
+/**
+ * How many of a beat's stops may speak, by narration density.
+ *
+ * `high` is today's behaviour — one sentence per reveal, every stop narrated.
+ * The lower two lean on `planSegments`'s existing rule: given fewer sentences
+ * than stops it fills the early ones and leaves the rest SILENT, deliberately,
+ * rather than inventing copy to fill a reveal.
+ */
+export declare const SPEAKING_STOPS: Record<Prefs["narration"]["density"], number>;
+/**
+ * What edge-tts's `--rate` actually buys, MEASURED — not what it says it buys.
+ *
+ * Synthesised on `en-US-AndrewMultilingualNeural` over a 72-character demo
+ * sentence, which speaks in 4.416s at `+0%` (16.30 cps, within 1% of the
+ * `SPEECH_CPS.latin` measured across the whole narrated demo):
+ *
+ * ```
+ *   rate    seconds   chars/sec   speedup   p95 cue cps
+ *   +0%       4.416       16.30     1.000          16.7
+ *   +10%      3.720       19.35     1.187          19.9
+ *   +20%      3.528       20.41     1.252          21.0
+ *   +30%      3.168       22.73     1.394          23.6
+ *   +40%      2.880       25.00     1.533          26.0
+ *   +50%      2.904       24.79     1.521          25.7   <- SLOWER than +40%
+ *   +60%      2.640       27.27     1.673          28.5
+ * ```
+ *
+ * TWO THINGS THIS TABLE EXISTS TO SAY. The nominal percentage overshoots — the
+ * first 10% buys 19% — so a linear model would under-speak every deck. And the
+ * curve is not monotonic: `+50%` came back slower than `+40%`, so the prosody
+ * rate is not a clean multiplier and interpolating between these points would be
+ * inventing data. A table of what was observed is the honest shape.
+ *
+ * WHY IT STOPS AT +40%. The subtitle, not the ear. At `+40%` the p95 cue rate is
+ * 26.0 cps, already half again over the `COMFORTABLE_CPS` broadcast practice; at
+ * `+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.
+ *
+ * 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.
+ */
+export declare const RATE_STEPS: readonly (readonly [rate: string, speedup: number])[];
+export interface DurationPlan {
+    /** Effective `animationSpeed`. Derived when `duration` is set, else the pref. */
+    speed: number;
+    /** Stops per beat allowed to speak. `Infinity` means every one. */
+    speakingStops: number;
+    /**
+     * edge-tts `--rate` for the narration. Derived when `duration` is set — a
+     * short target buys its words by speaking faster before it buys them by
+     * saying less. `"+0%"` whenever the budget already affords a real sentence.
+     */
+    rate: string;
+    /**
+     * Sentences this beat's budget affords. 1 means the deck can only caption; see
+     * `SENTENCES_PER_BEAT`. Absent when no duration was asked for.
+     */
+    sentences?: number;
+    /** Characters per narration sentence. Absent when no duration was asked for. */
+    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. */
+    beatSeconds?: number;
+    /** Said, never fatal: what the target costs, or cannot buy. */
+    warnings: string[];
+}
+/**
+ * The two derived numbers, from the three the user chose.
+ *
+ * `duration` unset returns the preferences untouched — `speed` is whatever
+ * `animationSpeed` says and there is no character budget — so a deck built
+ * without a target is byte-for-byte the deck this file did not exist for.
+ *
+ * `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.
+ */
+export declare function durationPlan(prefs: Prefs): DurationPlan;
+/**
+ * How many slides a target should have, by TEMPO.
+ *
+ * WHAT THIS REPLACED, and why it was wrong. It used to return the most slides a
+ * target could carry while every beat still afforded two sentences, which gave
+ * FIVE slides for a minute. The owner, watching it: "in auto mode the number of
+ * slides is too conservative when it's 1 minute... in their fast-forward
+ * presentation they never use stupidly small number of slides."
+ *
+ * He is describing the conference fast-forward talk — the one-minute teaser an
+ * author gives before the session — and that is the right reference for a short
+ * target. Those run ten to fifteen slides in sixty seconds, about five seconds
+ * each, with the voice carrying straight over the cuts. The two-sentence floor
+ * was derived from `demo/storyboard.json`, which is a FOUR-MINUTE deck at twenty
+ * seconds a beat, and applying its shape to a teaser is what produced five
+ * slides and 133 words per minute against a fast-forward talk's 160-190.
+ *
+ * So the anchor is the beat LENGTH, and the two references agree on twelve
+ * slides: a fast-forward talk is 12 beats in 60s, the demo is 12 beats in 246s.
+ * What changes with duration is how long each beat lasts, not how many there
+ * are — until the beat would run past twenty seconds, where a deck stops being
+ * one thought a slide and starts being a lecture.
+ *
+ *     30s ->  8    120s -> 12    600s -> 30
+ *     60s -> 12    300s -> 15
+ *
+ * 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.
+ */
+export declare function slidesFor(prefs: Prefs): number;
+/**
+ * How fast this deck speaks.
+ *
+ * TWO REGIMES, and which one applies is decided by the beat length.
+ *
+ * A LECTURE (`beatSeconds` over `FF_BEAT_SECONDS`) takes the SLOWEST step that
+ * lifts a sentence to something which explains — speech is sped up only as far as
+ * the shortfall needs, so a target with room to spare is spoken at `+0%` and its
+ * deck does not move a byte.
+ *
+ * A FAST-FORWARD TALK takes the FASTEST step the captions can carry. Below eight
+ * seconds a beat there is no such thing as spare room: every second not carrying
+ * a word is information the viewer does not get, and the owner's whole complaint
+ * — "you must utilize every single second" — is that this function was being
+ * thrifty with seconds nobody wanted saved. The ceiling is `SHORT_FORM_CPS`
+ * against the DECK'S OWN measured cue rate, not a constant, because how fast a
+ * caption can run depends on how densely this deck happens to be written.
+ *
+ * Measured on the sixty-second target: the slow rule gave `+10%` and 133 words a
+ * minute; the fast rule gives `+30%` and 180, which is conference teaser pace.
+ */
+export declare function fastEnough(chars: number, cps?: number, beatSeconds?: number): readonly [rate: string, speedup: number];
+/**
+ * What the finished video must be sped up by to hit its target.
+ *
+ * Returns 1 when it is already at or under the target — a video is never
+ * SLOWED to fill a duration, because padding a deck with dead air is worse than
+ * a deck that is 8 seconds short.
+ */
+export declare function playbackFactor(actualSeconds: number, targetSeconds: number): number;
+/**
+ * `atempo` is clamped to [0.5, 2.0] per instance, so anything past 2× is a
+ * chain of equal factors whose product is the whole. Two at 1.7 make 2.89.
+ */
+export declare function tempoChain(factor: number): number[];
+/**
+ * The 95th percentile of characters per second across a deck's subtitle cues.
+ *
+ * The p95 rather than the mean, and the deck's OWN cues rather than a constant:
+ * how much faster a video can safely play is a property of how densely this deck
+ * happens to be written, and the worst few cues are what a viewer notices. The
+ * demo measures 18.41 — already over broadcast practice, so it has no headroom
+ * at all, which is a fact worth telling someone before they ask for 1.5×.
+ */
+export declare function p95CueRate(cues: readonly {
+    start: number;
+    end: number;
+    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.
+ */
+export declare function playbackWarning(factor: number, p95: number): string | undefined;

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

@@ -0,0 +1,47 @@
+/**
+ * What the model is told, and what it is told about.
+ *
+ * Planning quality is the product, and this file is where it is won or lost —
+ * the schema only guarantees the storyboard is well-formed, never that it is a
+ * good explanation of this particular document.
+ *
+ * `renderSource` deliberately puts every citable id next to its caption. The
+ * model cannot cite an id it was never shown, so the inventory is the cheapest
+ * defence against the failure mode that actually happens: a plausible-looking
+ * `figureId` that exists in no source.
+ */
+import type { Prefs } from "../prefs.js";
+import { type Source } from "../types.js";
+/**
+ * How many sentences each archetype wants, because it is how many stops it has.
+ *
+ * MEASURED from `emitScene(beat).holds.length`, not reasoned about. The prose this
+ * replaced said "a pipeline of four stages wants five sentences" and the emitter
+ * produces FOUR — and a planning document that set out to correct it guessed six.
+ * Three different numbers for one archetype, none of them from the emitter.
+ *
+ * It matters because `narrate` cuts the audio sentence by sentence across the
+ * stops (`planSegments`): too few and the last reveals are silent, too many and
+ * everything after the first surplus sentence is heard over the wrong picture.
+ * The prompt was wrong for most archetypes, so the voice ran ahead of the
+ * animation in the shipped product by construction.
+ *
+ * `test/prompt.test.ts` recomputes every row from `emitScene` and fails if one
+ * drifts. That test is the reason this table is allowed to exist as text: the
+ * prompt is built before any beat exists, so it cannot call `emitScene` itself,
+ * and the only alternative to a checked table is prose nobody verifies.
+ */
+export declare const REVEALS: Record<string, string>;
+/**
+ * The rules, then the preferences the person asking for the deck chose. They go
+ * last because they are the part the model is most likely to drift from, and the
+ * end of a prompt is the part it holds hardest.
+ */
+export declare function systemPrompt(prefs: Prefs): string;
+/**
+ * The default prompt, for callers that have no preferences in hand. Kept so the
+ * 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. */
+export declare function renderSource(source: Source): string;

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

@@ -0,0 +1,22 @@
+import type { Source, Storyboard } from "../types.js";
+export declare function assertRefsResolve(storyboard: Storyboard, source: Source): void;
+/**
+ * Every `inside` names a part the previous beat actually draws.
+ *
+ * THE SAME SHAPE AS THE CHECK ABOVE, one level in: a schema proves `inside` has
+ * a beat and an element, and cannot prove the element exists. RULE 11 says only a
+ * pipeline's `stageN`, a grid's `rgnN` and a stack's `layN` have interiors worth
+ * entering, and a real plan asked to fly into `stage1` of an ANNOTATED-FIGURE —
+ * which has notes and leader lines and no stages at all.
+ *
+ * WHY IT MOVED HERE. The emitter already refuses this, so nothing shipped
+ * broken. But it refuses at BUILD, which is after `narrate` has spent a minute
+ * and a dozen network round trips synthesising speech for a storyboard that was
+ * never going to build. `plan` is where the author is being told to read the file
+ * anyway, and emitting a scene is cheap — the emitters build strings.
+ *
+ * Cheap enough to be exact rather than a table: the previous beat is emitted and
+ * `enterableIds` is asked what it drew, so this cannot drift from the emitter the
+ * way a hardcoded list of archetype interiors would.
+ */
+export declare function assertInsideResolves(storyboard: Storyboard, source: Source): void;