@jokerized/decksmith 0.3.0 → 0.3.2

package/dist/types/deck/player-element.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/deck/player.d.ts

@@ -0,0 +1,37 @@
+/** One stop, as a host sees it. */
+export interface PlayerStop {
+    i: number;
+    label: string;
+    notes?: string;
+}
+export declare class DecksmithPlayer extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    /** Every stop the deck reported, empty until `ds-ready`. */
+    get stops(): PlayerStop[];
+    /** Where the deck is now. */
+    get at(): number;
+    /** Whether the deck answered the handshake. */
+    get connected(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, was: string | null, now: string | null): void;
+    next(): void;
+    prev(): void;
+    go(at: number): void;
+    play(on?: boolean): void;
+}
+/**
+ * Register the element, once.
+ *
+ * GUARDED AND PARAMETERISED because `customElements.define` throws on a
+ * duplicate name, and a host page that imports this twice — two bundlers, or a
+ * hot reload — should get a no-op rather than an exception that takes the page
+ * down. The tag is an argument so a consumer whose page already owns
+ * `decksmith-player` can mount it under another name.
+ *
+ * NOT called at import time. A module with a side effect cannot be imported for
+ * its types, and `player-element.ts` exists precisely so the side-effecting
+ * entry point is a separate file a consumer opts into.
+ */
+export declare function define(tag?: string): void;

package/dist/types/deck/protocol.d.ts

@@ -0,0 +1,80 @@
+/**
+ * What a host page and a deck say to each other.
+ *
+ * ONE FILE, IMPORTED BY BOTH ENDS, so `tsc` checks the sender against the
+ * receiver. The alternative — a string literal in the runtime and a matching one
+ * in the element — is two copies of a contract that drift the first time a field
+ * is added, and the drift is invisible because `postMessage` takes `any` and a
+ * message nobody understands is simply ignored.
+ *
+ * WHY A BRIDGE AT ALL, rather than hosting the deck in the page. A deck is a
+ * whole document with its own fonts, GSAP, KaTeX, a vendored player and a ready
+ * gate, and `frameOf` in runtime.ts can only reach a SAME-ORIGIN frame — it
+ * returns null otherwise and the runtime merely warns, so a deck served from
+ * another origin would navigate perfectly and paint nothing, silently. Keeping
+ * the frame keeps that same-origin pair inside one directory, where it is always
+ * true, and makes the host link `postMessage`, which does not care about origin.
+ *
+ * VERSION COUPLING IS THE HAZARD. Every deck published before this existed has
+ * no listener, and a deck is a static artifact that outlives the tool that made
+ * it. So silence is a SUPPORTED state, not an error: the element times out, says
+ * so with a distinct code, and leaves the deck usable — it is still a deck in a
+ * frame, and its own keyboard still works.
+ */
+/** The channel name, on every message in both directions. */
+export declare const CHANNEL = "decksmith-deck";
+/** Sent by the host once the frame has loaded, to open the conversation. */
+export interface Hello {
+    channel: typeof CHANNEL;
+    type: "hello";
+}
+/**
+ * The deck's answer, and the only message that establishes the host's origin.
+ *
+ * NOTHING IS POSTED TO "*" AFTER THIS. A stop carries the slide's speaker
+ * notes, and any page on the internet can put a deck in a frame — posting
+ * wildcard would hand an arbitrary framer the presenter's notes. The origin is
+ * taken from the `hello` event and every later message is addressed to it.
+ */
+export interface Ready {
+    channel: typeof CHANNEL;
+    type: "ready";
+    /** Every stop the deck can land on, in order. */
+    stops: {
+        i: number;
+        label: string;
+        notes?: string;
+    }[];
+    /** Where it is now. */
+    at: number;
+}
+/** Where the deck landed, after any move. */
+export interface Stopped {
+    channel: typeof CHANNEL;
+    type: "stop";
+    at: number;
+    total: number;
+    label: string;
+    notes?: string;
+    playing: boolean;
+}
+/** What a host may ask for. Deliberately small: everything else is a deck concern. */
+export type Command = {
+    channel: typeof CHANNEL;
+    type: "next";
+} | {
+    channel: typeof CHANNEL;
+    type: "prev";
+} | {
+    channel: typeof CHANNEL;
+    type: "go";
+    at: number;
+} | {
+    channel: typeof CHANNEL;
+    type: "play";
+    on: boolean;
+};
+export type FromDeck = Ready | Stopped;
+export type ToDeck = Hello | Command;
+/** A message from us, rather than from anything else sharing the window. */
+export declare function isOurs(data: unknown): data is FromDeck | ToDeck;

package/dist/types/deck/runtime.d.ts

@@ -57,3 +57,39 @@ export declare function parseHash(hash: string): Pos | null;
  * longer emit falls back to its slide rather than to nothing.
  */
 export declare function findStop(stops: readonly Stop[], pos: Pos): number;
+interface Player extends HTMLElement {
+    ready?: boolean;
+    seek: (t: number) => void;
+    pause?: () => void;
+}
+/** Only what we call on a GSAP timeline. */
+interface Seekable {
+    seek: (t: number) => void;
+}
+interface Frame {
+    doc: Document;
+    timelines: Record<string, Seekable>;
+}
+/**
+ * The composition, reached through the player's iframe.
+ *
+ * Same-origin only, which means a deck must be served over http — opening
+ * `deck.html` from the filesystem gives the iframe an opaque origin and we
+ * cannot drive it. `present()` says so out loud rather than rendering blank.
+ */
+export declare function frameOf(player: Player): Frame | null;
+/** One player-page video, keyed in the island by the scene that draws its still. */
+export interface ClipSpec {
+    /** Already in embeddable form — `embedUrl` in src/pack/media.ts did that at build time. */
+    url: string;
+    /** The figure's caption. It titles the frame, which is all a screen reader gets. */
+    title: string;
+}
+/**
+ * Read the island, defensively, for the same reason `parseNarration` is
+ * defensive: a deck built before this existed has no island, and one built by a
+ * newer emitter may carry fields this reader has never heard of. Neither may do
+ * anything worse than leave the poster alone.
+ */
+export declare function parseClips(json: string | null | undefined): Record<string, ClipSpec>;
+export {};

package/dist/types/emit/archetypes/claim-figure.d.ts

@@ -1,9 +1,2 @@
-/**
- * A claim from the source, shown next to the figure that backs it.
- *
- * The layout is chosen from the figure's own aspect ratio rather than being a
- * parameter: EXPERIMENT-002 full-bled a 1.98-aspect figure and pushed its
- * caption 200px off-canvas. Only a genuine strip earns the full width.
- */
 import type { Emitter } from "../kit.js";
 export declare const claimFigure: Emitter<"claim-figure">;

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

@@ -25,6 +25,8 @@ import type { BeatOf, Format } from "../../types.js";
 import type { Emitter } from "../kit.js";
 import { type Face } from "../svg.js";
 type Params = BeatOf<"stack">["params"];
+/** Where the numerals' right edge lands once the type floor has moved. */
+export declare function numSpine(floor: number): number;
 export interface StackLayout {
     /**
      * The type floor this layout solved against, which is `MIN_FONT` for a flat

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

@@ -137,6 +137,39 @@ export interface EmitContext {
      * `hyperframes lint` rejects it (`unscoped_gsap_selector`).
      */
     sid: string;
+    /**
+     * WHERE THIS SCENE BEGINS ON THE DECK'S OWN CLOCK, in seconds, ALREADY ROUNDED
+     * to invariant 10's three places — the identical number the scene wrapper
+     * publishes as `data-start`. Write it; do not round it again, because two
+     * roundings of one number is how a byte moves.
+     *
+     * Everything else an archetype emits is scene-relative, and that is the right
+     * default: an emitter that knew where it sat in the deck would be an emitter a
+     * cut could invalidate. ONE thing is not expressible that way. A `<video>` is
+     * timed by the RUNTIME, not by this scene's timeline, and the runtime reads
+     * `data-start` as an ABSOLUTE composition second — so a clip that declares a
+     * scene-relative start is seeked into a window that has already passed.
+     *
+     * MEASURED, because the alternative looked right on paper. hyperframes'
+     * compiler injects `data-start="0" data-hf-auto-start=""` into a media tag
+     * that declares no timing, and its runtime resolves that marker against the
+     * enclosing `[data-composition-id]`, which is exactly this scene — so the
+     * marker ought to have been enough. Rendered at 0.8.27, on a two-beat deck
+     * whose clip is red for 2s, green for 2s then blue for 2s and whose second
+     * scene starts at 7s: with the marker the plate is BLUE at composition 9.5s,
+     * 10.5s and 12.5s — the clip's last frame, frozen, because the render placed
+     * it at second 0 and it had ended before the scene began. With `data-start="7"`
+     * the same frames are green, green, blue: clip seconds 2.5, 3.5 and 5.5. Every
+     * gate is green over both.
+     *
+     * OPTIONAL, because the shell is not the only caller: an archetype test calls
+     * `emitScene` with a context it builds by hand, and twelve of the thirteen
+     * emitters have no use for this. The one that does refuses by name when it is
+     * missing rather than inventing a second, i.e. wrong, clock. `planCut` passes
+     * a provisional 0 for the same reason it passes provisional scene ids — its
+     * pass exists to measure holds, and every scene it emits is thrown away.
+     */
+    start: number;
 }
 /**
  * A value in a GSAP vars payload that is JavaScript rather than data.

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

@@ -82,11 +82,20 @@ export declare function codexImages(opts?: CodexImagesOptions): ImageProvider;
  * 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 size an SVG declares, for `sizeOf` in ./illustrate.ts and for anything
+ * else that already imports this module.
+ *
+ * It USED to live here, as a regex for `viewBox="0 0 %d %d"` over the first 200
+ * bytes — four integers, no units, no preamble — which is exactly the SVG
+ * `drawSvg` above writes and nothing else. Figure ingest needs to measure an SVG
+ * a stranger wrote, so the reader was generalised and moved to src/source/assets.ts
+ * beside the other formats. It moved THERE rather than staying here because
+ * that module imports nothing but node and the schemas: the reverse would put
+ * the Codex runner and this file's OpenAI adapter on the import path of every
+ * source parse, for two integers.
+ */
+export { svgSize } from "../source/assets.js";
 /** The last rung. Pure, so it cannot fail, so `illustrate` always finishes. */
 export declare function toolSvg(): ImageProvider;
 /**

package/dist/types/index.d.ts

@@ -8,12 +8,25 @@ import { type Format, type Source, type Storyboard } from "./types.js";
  */
 export { parseMarkdown } from "./source/markdown.js";
 export type { ParseOptions } from "./source/markdown.js";
+/**
+ * A web page in, a markdown document and a directory of files out — the step
+ * BEFORE `parseMarkdown`, not a replacement for it. Separate because it needs a
+ * browser and the network, which `parseMarkdown` deliberately does not.
+ *
+ * `attachClips` is exported with it because a harvest is not finished without
+ * it: the markdown dialect has no way to say `kind: "clip"`, so a page's videos
+ * come back beside the document and this is what puts them into the source. It
+ * runs BEFORE `fetchFigures`, which passes a clip through untouched.
+ */
+export { attachClips, harvest, toMarkdown } from "./source/harvest.js";
+export type { Block, Harvested, HarvestedClip, HarvestOptions } from "./source/harvest.js";
 /**
  * Figures referenced by URL, downloaded beside the source. Separate from
  * `parseMarkdown` because it touches the network and a server may want to fetch
  * through its own client instead.
  */
 export { fetchFigures } from "./source/assets.js";
+export { fetchGuarded, isBlockedAddress } from "./net/fetch.js";
 /**
  * Subset a CJK webfont over the glyphs a deck actually renders. Exported
  * because invariant 9 — a font stack naming a family the bundle does not
@@ -111,7 +124,7 @@ export { verify } from "./verify/index.js";
  * 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 { scanBeatCount, scanNarrationDrift, scanPaperArc, 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/tools.d.ts

@@ -26,6 +26,10 @@ export declare const settingsSchema: z.ZodObject<{
         normal: "normal";
         dense: "dense";
     }>>;
+    genre: z.ZodOptional<z.ZodEnum<{
+        general: "general";
+        paper: "paper";
+    }>>;
     duration: z.ZodOptional<z.ZodNumber>;
     slides: z.ZodOptional<z.ZodInt>;
     animation_speed: z.ZodOptional<z.ZodNumber>;
@@ -63,6 +67,10 @@ export declare const estimateSchema: z.ZodObject<{
             normal: "normal";
             dense: "dense";
         }>>;
+        genre: z.ZodOptional<z.ZodEnum<{
+            general: "general";
+            paper: "paper";
+        }>>;
         duration: z.ZodOptional<z.ZodNumber>;
         slides: z.ZodOptional<z.ZodInt>;
         animation_speed: z.ZodOptional<z.ZodNumber>;
@@ -82,6 +90,7 @@ export declare const estimateSchema: z.ZodObject<{
 export declare const createSchema: z.ZodObject<{
     document_path: z.ZodOptional<z.ZodString>;
     document_text: z.ZodOptional<z.ZodString>;
+    document_url: z.ZodOptional<z.ZodString>;
     settings: z.ZodOptional<z.ZodObject<{
         format: z.ZodOptional<z.ZodEnum<{
             [x: string]: string;
@@ -101,6 +110,10 @@ export declare const createSchema: z.ZodObject<{
             normal: "normal";
             dense: "dense";
         }>>;
+        genre: z.ZodOptional<z.ZodEnum<{
+            general: "general";
+            paper: "paper";
+        }>>;
         duration: z.ZodOptional<z.ZodNumber>;
         slides: z.ZodOptional<z.ZodInt>;
         animation_speed: z.ZodOptional<z.ZodNumber>;
@@ -209,6 +222,25 @@ export declare function deckTools(opts: McpOptions): {
             state: import("../server/queue.js").StepState;
         }[];
         log: string[];
+    } | {
+        harvest_warnings: string[];
+        next: string;
+        deck_path?: string | undefined;
+        slides?: number | undefined;
+        duration_seconds?: number | undefined;
+        warnings?: string[] | undefined;
+        storyboard_path: string;
+        error?: import("../server/errors.js").JobError | undefined;
+        job_id: string;
+        state: import("../server/queue.js").JobState;
+        stage: import("../server/queue.js").Stage | undefined;
+        queue_position: number | undefined;
+        elapsed_seconds: number;
+        steps: {
+            name: import("../server/queue.js").Stage;
+            state: import("../server/queue.js").StepState;
+        }[];
+        log: string[];
     }>;
     /** Poll, blocking up to `wait_seconds` for the job to move on. */
     status(input: z.infer<typeof statusSchema>): Promise<{

package/dist/types/net/fetch.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The one guarded door out of this process for a URL somebody else chose.
+ *
+ * Two holes made this file. `src/source/assets.ts` fetched a figure with a bare
+ * `fetch(src)` — no timeout, no size cap, no idea what came back. And
+ * `src/server/pipeline.ts` grew an SSRF pre-check, `reachable()`, which resolves
+ * the hostname, refuses the private ranges, and then hands the URL to `fetch`,
+ * which resolves it again. A pre-check the socket never honours stops the naive
+ * class and nothing else: a public host that 302s to 169.254.169.254 walks
+ * straight past it, because the address that was checked is not the address that
+ * got connected to.
+ *
+ * WHY THIS IS node:http/node:https AND NOT `fetch`. Exactly one reason, and it
+ * is the reason the file exists: `fetch` gives no way to say "connect to THIS
+ * address". `http.request` takes a `lookup`, so the address this module
+ * validated is the address the socket opens, and the second DNS answer that
+ * would have been a rebinding attack is never asked for. Everything else here —
+ * the manual redirect walk, the streaming cap, the timeout, the content-type
+ * check — could have been written over `fetch`. The pin could not, and
+ * pipeline.ts's own comment named that gap and called it unclosable. It was
+ * closable; it just needed a different client.
+ *
+ * WHAT IS STILL OPEN, because a guard that oversells itself is worse than none:
+ *  - Resolution is `dns.lookup`, the OS resolver, so `/etc/hosts` and any local
+ *    override are honoured. That is deliberate — it is how this machine resolves
+ *    every other name — but it does mean a poisoned hosts file is trusted.
+ *  - A hostname with several A records is refused if ANY of them is blocked, and
+ *    the socket is pinned to the first. That is stricter than a browser and is
+ *    the intended trade: a round-robin where one member is internal is not a
+ *    host this process wants to talk to at all.
+ *  - Nothing here bounds how many of these run at once. The caller owns that.
+ */
+export declare function isBlockedAddress(ip: string): string | null;
+export interface GuardOptions {
+    /**
+     * Cap on the body, applied to DECODED bytes — see `readCapped` and `decode`
+     * for the two places it is enforced and why it takes both.
+     */
+    maxBytes: number;
+    /** Whole-call budget: DNS, connect, every hop, and reading the body. */
+    timeoutMs: number;
+    /**
+     * Refuse unless the response's bare media type matches. Matched against the
+     * type WITHOUT its parameters, so `/^image\//` and `/^text\/html$/` both do
+     * what they look like against `text/html; charset=utf-8`.
+     */
+    accept?: RegExp;
+    /**
+     * Extra request headers, lowercased on the way in. `authorization` and
+     * `cookie` are dropped the moment a redirect changes origin.
+     */
+    headers?: Record<string, string>;
+    /**
+     * TEST SEAM, and the only way to point this at a server on this machine.
+     *
+     * It exempts loopback from the address block and lifts the 80/443 rule, which
+     * together is exactly what it takes to drive a `node:http` server on an
+     * ephemeral port through this module's real code path — see test/net.test.ts,
+     * which is the only caller. It relaxes NOTHING else: link-local, the private
+     * ranges, the non-http schemes, the hop cap, the size cap, the timeout and the
+     * content-type check all still apply, which is what makes those tests evidence
+     * about the guard rather than about a bypass of it. Nothing in src passes it.
+     */
+    allowLoopback?: boolean;
+}
+export interface Fetched {
+    bytes: Buffer;
+    /** The `Content-Type` header as sent, parameters and all — a caller decoding
+     * text needs the charset, and dropping it here would lose it for good. */
+    contentType: string;
+    /** The URL the bytes actually came from, after redirects. What a caller must
+     * resolve relative links against, and what it should cache under. */
+    url: string;
+}
+/**
+ * Fetch `url`, refusing loudly at the first thing that looks wrong.
+ *
+ * Every refusal names the URL, what was wrong with it, and what to do; a caller
+ * surfacing `err.message` to a user is giving them something actionable.
+ */
+export declare function fetchGuarded(url: string, opts: GuardOptions): Promise<Fetched>;

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

@@ -37,6 +37,18 @@ export interface MediaPlan {
 }
 /** A player URL is one whose host is in the list, or a subdomain of one. */
 export declare function isEmbed(url: string): boolean;
+/**
+ * Every origin an embed can come from, deduped.
+ *
+ * DERIVED FROM THE RULES ABOVE RATHER THAN RESTATED BESIDE THEM, because the
+ * served deck's `frame-src` names exactly this list (src/server/http.ts): a host
+ * added here and forgotten there is a frame the browser refuses, and CSP refuses
+ * it the way CSP refuses everything — an empty rectangle and a line in a console
+ * nobody has open.
+ */
+export declare const EMBED_ORIGINS: readonly string[];
+/** The embeddable form of a player page, or undefined when we cannot say. */
+export declare function embedUrl(url: string): string | undefined;
 /**
  * The final policy for one asset.
  *

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

@@ -0,0 +1,82 @@
+/**
+ * The paper arc: what a research-talk deck must open and close with.
+ *
+ * A research talk has a shape a general explainer does not. It opens on the
+ * problem and on the ground the work stands on, and it closes on what the work
+ * does NOT do and then on what to take away. DeckSmith's planner writes the
+ * opening well already — 13 of 15 committed full-deck runs open with a `title` —
+ * and the ending badly: 10 of 15 close with a `callout`, but ZERO of 15 carry
+ * two, because the limitation arrives as a subordinate clause inside the
+ * conclusion ("The idea works, but the strongest lightweight models remain
+ * ahead") rather than as its own slide. Splitting that clause into a slide is
+ * the actual behaviour change this module asks for.
+ *
+ * WHY THIS FILE EXISTS AT ALL, rather than the rule living where it is enforced:
+ * three directories read this definition and none of them can own it — the
+ * prompt (src/plan/prompt.ts) asks the model for the arc, the scan
+ * (src/verify/index.ts) reports where a plan missed it, and the cut
+ * (src/plan/select.ts) refuses to delete a beat that carries a role. Restating
+ * the rule three times is how the three fall out of step; deriving it from one
+ * table is how they cannot.
+ *
+ * WHAT THIS MODULE DELIBERATELY DOES NOT DO. It never decides that a document is
+ * a research paper. `prefs.genre` is declared by the author and nothing here
+ * sniffs it — see the field's own note in src/types.ts for the measurement that
+ * settled that. And it never requires a beat the source cannot support: RULE 3
+ * forbids inventing a baseline or a result, so a source that says nothing about
+ * prior work honestly yields no `background` beat, and this file's job is then
+ * to report the gap rather than to have manufactured one.
+ */
+import type { Prefs } from "../prefs.js";
+import type { Beat, BeatRole, Storyboard } from "../types.js";
+/** Every structural job, in the order a deck performs them. */
+export declare const ARC_ROLES: readonly BeatRole[];
+/**
+ * Roles required at a given deck length, and why the list shortens.
+ *
+ * Four reserved slides out of five is not a deck, it is a table of contents. At
+ * `--duration 60` a deck is about five beats, so asking for the full arc there
+ * is asking for something nobody could deliver, and a gate that fires on the
+ * impossible is one people learn to ignore. The thresholds:
+ *
+ *   n >= 8   the full arc. 8 is this project's own definition of a full-deck
+ *            run — the corpus count of "15 committed full-deck plans" is beats
+ *            >= 8 — not a number chosen here.
+ *   5..7     the ending only. An `intro` is what the planner already writes
+ *            unprompted 13 times in 15, and `background` is the beat most likely
+ *            to have no source material behind it, so those two are the ones to
+ *            give up first when the budget is short.
+ *   n < 5    nothing. There is no room for a shape.
+ *
+ * Read off the beat count the plan actually came back with, not off
+ * `prefs.slides`: the floor the author asked for and the deck the planner
+ * returned are different numbers, and `scanBeatCount` already owns the gap
+ * between them.
+ */
+export declare function requiredRoles(beatCount: number): readonly BeatRole[];
+/** Whether the paper arc was asked for at all. Declared, never sniffed. */
+export declare function paperArcRequested(prefs: Pick<Prefs, "genre">): boolean;
+/** The beats carrying a structural role, by role. Later duplicates are reported, not kept. */
+export declare function arcBeats(storyboard: Storyboard): Map<BeatRole, Beat[]>;
+/**
+ * Ids of every beat carrying a role — what the cut refuses to release.
+ *
+ * Takes a beat list rather than a Storyboard because the cut works over the
+ * surviving beats, not over the plan.
+ */
+export declare function arcIds(beats: readonly Beat[]): Set<string>;
+/**
+ * Where a plan departs from the arc it was asked for, as sentences.
+ *
+ * ORDER IS CHECKED, NOT JUST PRESENCE, and only where order is the point. The
+ * user's requirement is specifically that the deck END on the conclusion with
+ * limitations immediately before it — an ending is a position, not a topic — so
+ * those two are checked against the last two slots. The opening pair is checked
+ * for presence and for being early, because "the first couple of slides" is a
+ * region rather than an index, and a deck that opens title, problem, background
+ * is not wrong.
+ *
+ * Returns an empty array when the arc was not requested, when the deck is too
+ * short to carry it, or when the plan satisfied it.
+ */
+export declare function arcProblems(storyboard: Storyboard, prefs: Pick<Prefs, "genre" | "slides">): string[];

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

@@ -1,5 +1,11 @@
 import type { Prefs } from "../prefs.js";
 import { type Source, type Storyboard } from "../types.js";
+/** The schema for one run. `role` is present only when the paper arc was asked for. */
+export declare function schemaFor(prefs: Pick<Prefs, "genre">): unknown;
+/**
+ * The default-preferences schema, unchanged and still exported: `general` hides
+ * `role`, so these bytes are what they have always been.
+ */
 export declare const SCHEMA: unknown;
 export interface CodexOptions {
     /** Left unset by default: use whatever model the user's Codex is configured for. */

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

@@ -48,6 +48,7 @@ export declare const SYSTEM: string;
  *
  * 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.
+ * the picture has nothing else to decide what the picture is FOR. A clip carries
+ * one more: what the deck can actually show of it, which is a still.
  */
 export declare function renderSource(source: Source): string;

package/dist/types/prefs.d.ts

@@ -39,6 +39,7 @@ export interface PrefFlags {
     lang?: string;
     tone?: string;
     density?: string;
+    genre?: string;
     duration?: string | number;
     theme?: string;
     speed?: string | number;

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

@@ -60,20 +60,6 @@ export interface AudioInput {
     file: string;
     delayMs: number;
 }
-/**
- * Delay every segment onto one track and sum them.
- *
- * `amix` with `normalize=0` sums rather than averaging: the default divides by
- * the input count, which on a 37-segment deck would render the narration 31 dB
- * down and sound exactly like a bug in the TTS. The segments never overlap — the
- * timing model gives each one the video's undivided attention — so summing is
- * safe. `dropout_transition=0` stops amix ramping the gain as inputs end.
- *
- * Every input is resampled and laid out identically first, because amix refuses
- * a mismatch and edge-tts emits 24 kHz mono while the video wants 48 kHz.
- * `apad` runs the track out to the video's length so the mux does not have to
- * choose between a short audio stream and `-shortest` truncating the picture.
- */
 export declare function audioGraph(inputs: readonly AudioInput[], seconds: number, 
 /**
  * ffmpeg input index of the first mp3. 1 when the video is the only other