@jokerized/decksmith 0.9.5 → 0.9.7

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

@@ -0,0 +1,179 @@
+/**
+ * SECTION COVERAGE: a plan of an analysis covers every part the analysis has,
+ * in the order a talk covers them.
+ *
+ * The measured failure (2026-10-10, the EM-SNN ko deck): the source is a paper
+ * analysis with sections Q1 problem, Q2 related work, Q3 method, Q4 experiments,
+ * Q5 future directions, Q6 summary, Q8 limits. The plan opened on a title,
+ * spent twelve beats on the method and the numbers, and closed on one callout:
+ * the problem got the title slide only, and the related work, the future
+ * directions and the summary got nothing. Nothing checked, so nothing said.
+ *
+ * So the parts are DETECTED from the headings, generically — a lexicon over
+ * en/ko/ja/zh heading words, not this paper's Q-numbers — and the plan is held
+ * to them the way `variety.ts` holds it to its shapes: `codexPlanner` sends a
+ * plan that misses one back once, naming what is missing, and refuses the
+ * repair if it still does.
+ *
+ * WHAT IT DOES NOT DO. It never decides a document is a paper analysis from one
+ * lucky word: fewer than `MIN_PARTS` distinct parts and the check is off, and
+ * every deck planned before this is planned as it was (the same caution
+ * `prefs.genre` records about heading lexicons in general). A heading the
+ * lexicon does not know is not required; it is still in the source, and the
+ * planner may cover it where it fits.
+ *
+ * Also here, because they share the repair round: the literal-scene truth
+ * gate (a number on screen the source never states, an op parameter not
+ * stated IN ITS ROLE, a variant the source never names, example material
+ * without its tag, a formula its table does not bear out, a picture that
+ * names a beat with no picture).
+ */
+import type { BeatPart, LiteralKindDoc, Source, Storyboard } from "../types.js";
+/** The order a deck covers its parts in. */
+export declare const PART_ORDER: readonly BeatPart[];
+/** What each part is, for the prompt and the findings. */
+export declare const PART_NAMES: Record<BeatPart, string>;
+/** Fewer distinct parts than this and the source is not treated as an analysis. */
+export declare const MIN_PARTS = 3;
+/** The part a heading names, or undefined. */
+export declare function partOfHeading(heading: string): BeatPart | undefined;
+export interface SourcePart {
+    part: BeatPart;
+    /** Sections of this part that carry text, in source order: each must be cited. */
+    sections: Array<{
+        id: string;
+        heading: string;
+    }>;
+}
+/**
+ * The parts this source has, in deck order, or `[]` when it is not an analysis.
+ *
+ * A section takes its parent's part when the parent has one (the subsections of
+ * "Experiments" are experiments, whatever they are called), and its own
+ * heading's part otherwise. The document's title heading is not a section of
+ * any part. Only sections with text are listed: an empty parent is covered by
+ * covering its children.
+ *
+ * Back matter — an appendix, the references, the acknowledgements — and
+ * everything under or after the references is in no part: a talk is not held to its appendix. Two
+ * arXiv papers (FlashAttention, Chinchilla; 2026-10-14) each had 32 sections
+ * to cite for a 14-slide deck, about half of them appendix, and every plan was
+ * refused for missing one or for running long to cite them all.
+ */
+export declare function sourceParts(source: Source): SourcePart[];
+/**
+ * Where a plan departs from the source's parts, as sentences a repair can act
+ * on. Empty when the source has no detected parts.
+ */
+export declare function coverageFindings(storyboard: Storyboard, source: Source): string[];
+/**
+ * Advice for a plan whose source is about pictures: at least three of its own
+ * figures are captioned as views, frames or qualitative examples, and no beat
+ * runs `region` or `operate`. r1 drew a driving paper's only imagery at 55%
+ * width beside text, its panels unreadable, with neither verb used once. Sent
+ * back once with the other findings; a plan that still ignores it is kept.
+ */
+export declare function pictureFindings(storyboard: Storyboard, source: Source): string[];
+/**
+ * Advice for a plan that draws its MECHANISM as slideware, sent back once with
+ * the other findings (as `pictureFindings` is): r2 never chose \`operate\` or
+ * \`evolve\` on two papers and drew their method beats as two bullet columns, a
+ * chain of name cards and a 2×2 grid of numbers.
+ *
+ *  - a beat of part "method" with no \`literal\`, drawn as words, is routed to
+ *    the verb its evidence allows: a flow showing a figure it cites, place
+ *    curves or evolve on an equation, else operate on example vectors or
+ *    evolve (an update over steps, lanes of serial against parallel work);
+ *  - a flow chain whose stages are mostly names (no count, figure or layer);
+ *  - a beat whose claim states two or more of the source's numbers, drawn as
+ *    words, is a place strip, plane or combos;
+ *  - a split-compare with two lines or fewer a side is a setup detail: a
+ *    caption of the result beat that uses it.
+ *
+ * Advice, not a refusal: whether a verb is honest for a beat depends on what the
+ * source prints, which a heuristic cannot settle; the planner gets one look.
+ */
+export declare function slidewareFindings(storyboard: Storyboard, source: Source): string[];
+/**
+ * Advice: an eyebrow or a scene's slot words left in English in a deck in another
+ * script (r3: "SPECULATIVE DECODING" over a Korean scene): two or more Latin
+ * words, no letter of another script, not all of them names (an acronym, a model
+ * with a digit). Names (items, rows, members) are the source's own and not checked.
+ */
+export declare function latinWordFindings(storyboard: Storyboard): string[];
+/** The most of a deck's spoken time text-only beats may take. */
+export declare const TEXT_SHARE = 0.2;
+/** The longest a kinetic statement may be spoken over, seconds. */
+export declare const KINETIC_SECONDS = 8;
+/**
+ * Advice against a deck that is mostly text: r3 opened one deck with 75s of
+ * bullet columns, held kinetic statements at 2–11% fill for 22–29s, and spent
+ * about a third of its runtime on split-compare, callout, kinetic and
+ * hero-number. Measured by the narration each beat speaks (its characters at the
+ * deck language's speaking rate): text-only beats at most `TEXT_SHARE` of it,
+ * never two in a row, and a kinetic beat at most `KINETIC_SECONDS`.
+ */
+export declare function textShareFindings(storyboard: Storyboard): string[];
+/**
+ * What breaks a kind's claim bans (src/types.ts `LiteralKindDoc.mustNotClaim`):
+ * a banned claim in `said` (the beat's takeaway and the scene's labels). Empty
+ * when it keeps them.
+ */
+export declare function literalTruthProblems(rules: Pick<LiteralKindDoc, "mustNotClaim">, said: readonly string[]): string[];
+/**
+ * The source's numbers in reading order, signs kept, references left out. A
+ * list "[0.5,0.25]" or "1,2,3" is its numbers one by one; "1,000" is one
+ * thousand; "1e-3" is one number.
+ */
+export declare function numberSequence(source: string): number[];
+/**
+ * Whether a number is grounded IN ITS ROLE: some occurrence of the value, as a
+ * whole token, either carries the symbol the source binds to it there (then
+ * the plan must give that symbol, and the symbol must stand within 40
+ * characters of the role's nouns somewhere), or is unbound and itself stands
+ * within 40 characters of them. `mustBind`: only a binding grounds it (a
+ * formula's own symbol). Returns why not, or undefined.
+ */
+export declare function paramProblem(value: string, symbol: string | undefined, nouns: RegExp, role: string, text: string, mustBind?: boolean): string | undefined;
+/**
+ * Why a formula is not grounded by its checks: each check passes under
+ * interval arithmetic (src/literal/formula.ts) with its numbers in order in
+ * one passage; every variable takes two values or more; and where two checks
+ * or more sit in one passage (a flattened table), EVERY row of it at their
+ * period, shaped like them, passes too — a plan cannot pick the rows that fit.
+ * When the checks' rows also print a fixed parameter, every row printing THAT
+ * value: the other rows are another curve's.
+ */
+export declare function formulaProblems(expr: string, checks: ReadonlyArray<{
+    inputs: ReadonlyArray<{
+        name: string;
+        value: string;
+    }>;
+    output: string;
+}>, fixed: ReadonlyArray<{
+    name: string;
+    value: string;
+}>, _text: string, ps: readonly string[]): string[];
+/**
+ * Fills the slots whose words the code knows (2026-10-15): the `example` tag on
+ * a scene running on example material, and an op chain's `input` and `output`
+ * titles. Left to the planner, FlashAttention's b02 (unseen-paper round 15) was
+ * refused for its missing tag alone, and its b11 first for a chain's `input`. A
+ * slot the planner did fill is kept as written.
+ */
+export declare function withStockLabels(storyboard: Storyboard, source: Source): Storyboard;
+/**
+ * The literal-scene checks no schema can express. Run on every plan; a plan
+ * with no `literal` has nothing to find.
+ *
+ * `takeaways` asks for a takeaway on every beat but the title, which is what a
+ * plan shown the field (src/plan/codex.ts) was asked for. `panels`, when the
+ * caller could read the figures, holds a `region`'s `panel` to the panels the
+ * build will find.
+ */
+export declare function literalFindings(storyboard: Storyboard, source: Source, 
+/** `panels`: each source figure's panel count as the build finds it (`figurePanels`). */
+opts?: {
+    takeaways?: boolean;
+    panels?: Readonly<Record<string, number>>;
+}): string[];

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

@@ -626,3 +626,5 @@ export declare function playbackWarning(factor: number, p95: number): string | u
  * looked at the alternative and wants the fast video anyway.
  */
 export declare function playbackRefusal(actualSeconds: number, targetSeconds: number, p95: number): string | undefined;
+/** CJK writes far more meaning per character, so it is read out far slower. */
+export declare function charsPerSecond(lang: string): number;

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

@@ -0,0 +1,46 @@
+import type { Source, Storyboard } from "../types.js";
+import { type Runner } from "./codex.js";
+type Box = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** The prompt for one panel: its things, numbered, one tight box each. */
+export declare function locatePrompt(things: readonly string[]): string;
+/** The boxes a reply gives, in order, or why it gives none. */
+export declare function readBoxes(reply: unknown, n: number): Box[] | string;
+interface PassOpts {
+    run?: Runner;
+    model?: string;
+    onBeat?: (id: string) => void;
+    /** Told a beat whose scene could not be read twice over; that beat loses its scene. Absent: refused. */
+    onDrop?: (id: string, why: string) => void;
+}
+/**
+ * The storyboard with every marked `region`'s boxes found (any box the planner
+ * wrote is a guess and is replaced). Fails loudly, naming the beat, when a
+ * panel's things cannot be found twice over.
+ */
+export declare function locateMarks(storyboard: Storyboard, source: Source, assetsDir: string, opts?: PassOpts): Promise<Storyboard>;
+type Step = {
+    lead?: string;
+    parts: Array<{
+        text: string;
+        tag: string;
+    }>;
+};
+/** The prompt for a trace: what to read, the tags, the rows exactly as printed. */
+export declare function transcribePrompt(read: string, tags: ReadonlyArray<{
+    tag: string;
+    label: string;
+}>): string;
+/** The rows a reply gives, or why it gives none. */
+export declare function readSteps(reply: unknown, tags: readonly string[]): Step[] | string;
+/**
+ * The storyboard with every figure `trace`'s rows transcribed from its panel.
+ * The steps are the figure's, so the truth gate does not hold their numbers to
+ * the prose (src/plan/coverage.ts); what no gate sees is a misread glyph.
+ */
+export declare function transcribeTraces(storyboard: Storyboard, source: Source, assetsDir: string, opts?: PassOpts): Promise<Storyboard>;
+export {};

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

@@ -1,5 +1,5 @@
 import { type Prefs } from "../prefs.js";
-import { type Source } from "../types.js";
+import { type LiteralKindDoc, type Source } from "../types.js";
 /**
  * How many sentences each archetype wants, because it is how many stops it has.
  *
@@ -20,6 +20,19 @@ import { type Source } from "../types.js";
  * and the only alternative to a checked table is prose nobody verifies.
  */
 export declare const REVEALS: Record<string, string>;
+/**
+ * A kind's claim bans (src/types.ts `LiteralKindDoc`), under its slots:
+ * `literalFindings` checks the same entries, so the planner is told exactly
+ * what will be refused. Empty for a kind with none.
+ */
+export declare function ruleDocs(d: Pick<LiteralKindDoc, "mustNotClaim">): string;
+/**
+ * The prompt blocks that depend on the SOURCE, not just the preferences: the
+ * parts it must cover, when it has them, and the literal kinds, when the build
+ * draws scenes. Empty for a source with no parts and a classic plan, so those
+ * prompts are byte-for-byte what they were.
+ */
+export declare function sourceBlocks(source: Source, prefs: Prefs): 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

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

@@ -12,7 +12,8 @@
  * So the rule is a minimum, not an invitation, and it is CHECKED: the prompt
  * (src/plan/prompt.ts) states these numbers by importing them from here, and
  * `codexPlanner` (src/plan/codex.ts) runs `varietyFindings` on what comes back,
- * asks once for a repair, and refuses a plan that still breaks it. One table,
+ * asks for up to three repairs, redraws a beat still beside its own shape on
+ * its own (`shapesFor`), and refuses a plan that still breaks it. One table,
  * read by both, so the sentence the model is given and the check it is held to
  * cannot drift apart.
  *
@@ -47,6 +48,29 @@ export declare const SCENE_SHARE = 0.6;
 export declare const PANEL_ARCHETYPES: ReadonlySet<Archetype>;
 /** At most this share of a picture deck's beats are panels: five of fourteen. */
 export declare const PANEL_SHARE = 0.36;
+/**
+ * At most this many `kinetic` beats a deck. r1 of the literal verbs run had
+ * seven in one deck: two lines of type in the left third of a blank field, 75%
+ * empty and still for 13-15s each. One thesis is a kinetic; seven are a deck
+ * with nothing to show.
+ */
+export declare const KINETIC_MAX = 1;
+/** A plan may come back at most this many times the beats asked for. */
+export declare const SLIDES_OVER = 1.5;
+/**
+ * Where a plan is too LONG, as sentences — a separate group from the variety
+ * rules because its repair drops beats, which a variety repair may not.
+ *
+ * Over `SLIDES_OVER` × `slides`: r1 came back with 36 beats against 16, and
+ * 638s. 1.3 was the rule until Chinchilla (2026-10-15, 21 sections to cover)
+ * was refused at 19 and 20 beats against 14 in two of its last five rounds,
+ * three repairs each, never merged under 18. 1.5 still refuses r1's 2.25.
+ *
+ * And a setup beat whose next beat is its results — "navsim-metrics"
+ * then "navsim-results", seven times in one deck — is one point said twice:
+ * the metrics belong in the results' caption.
+ */
+export declare function sizeFindings(storyboard: Storyboard, slides: number): string[];
 /** How many panel beats a deck of `beats` may carry, given whether it may ask for pictures. */
 export declare function panelsAllowed(beats: number, images: Prefs["images"]): number;
 /** How many stage beats a deck of `beats` must carry, given the picture cap. */
@@ -67,6 +91,16 @@ export declare function scenesRequired(beats: number, images: Prefs["images"]):
  * the cards-on-paper the share exists to refuse.
  */
 export declare function isScene(beat: Beat, design?: Design): boolean;
+/**
+ * The shapes, of those `offered`, that beat `i` may be redrawn as: not either
+ * neighbour's, not a title past the first beat, and not one that tips the
+ * kinetic or panel cap. What the last-resort redraw of one beat
+ * (src/plan/codex.ts) offers in its schema, so the shape cannot be wrong.
+ *
+ * ponytail: the A/B/A/B and scene-share rules are not foreseen here; the plan
+ * is checked whole after the redraw, and refused if one of them broke.
+ */
+export declare function shapesFor(storyboard: Storyboard, i: number, offered: readonly Archetype[], images: Prefs["images"]): Archetype[];
 /**
  * Every way `storyboard` breaks the variety rule, as sentences the planner can
  * act on. Empty is a pass.

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

@@ -51,7 +51,7 @@ import type { z } from "zod";
 import type { BespokeMap } from "../bespoke/scene.js";
 import { type Cue } from "../deck/subtitles.js";
 import { type DeckNarration } from "../emit/composition.js";
-import type { Beat, Format, Source, Storyboard, segmentSchema } from "../types.js";
+import type { Beat, Design, Format, Source, Storyboard, segmentSchema } from "../types.js";
 type Segment = z.infer<typeof segmentSchema>;
 /** Written beside `index.html` by `build`; read by `render`. */
 export declare const TIMING_FILE = "timing.json";
@@ -221,6 +221,12 @@ export interface TimingInput {
     theme?: string;
     /** `DeckOptions.bespoke`, exactly as `emitDeck` was given it. */
     bespoke?: BespokeMap;
+    /**
+     * The design the composition was emitted in (`emitDeck`'s, else the
+     * storyboard's). Holds DO depend on it: staged without it, a v2 hero number's
+     * hold was classic's reel roll, 0.04s off the island's (r3 C s16).
+     */
+    design?: Design;
 }
 /**
  * One pass over the built deck, producing the manifest `render` consumes.

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

@@ -170,6 +170,7 @@ export type Block = {
     kind: "table";
     columns: string[];
     rows: string[][];
+    caption?: string;
 } | {
     kind: "image";
     src: string;