@jokerized/decksmith 0.3.0 → 0.3.1

package/dist/cli.js

@@ -293,10 +293,16 @@ var insideSchema = z.object({
    */
   label: z.string().optional()
 });
+var beatRoleSchema = z.enum(["intro", "background", "limitations", "conclusion"]);
 var beatCore = {
   id: z.string(),
   /** What the viewer should understand after this beat. */
   intent: z.string(),
+  /**
+   * OPTIONAL, and only ever present when `prefs.genre` is `paper`. The
+   * structural job this beat does; see `beatRoleSchema`.
+   */
+  role: beatRoleSchema.optional(),
   /** Optional: this beat happens inside a named part of the beat before it. */
   inside: insideSchema.optional(),
   /** The source sentence or equation this beat is accountable to. */
@@ -443,6 +449,26 @@ var prefsSchema = z.object({
   tone: z.enum(["plain", "academic", "conversational", "punchy"]).default("plain"),
   /** How much text a slide may carry before it should have been a diagram. */
   density: z.enum(["sparse", "normal", "dense"]).default("normal"),
+  /**
+   * What kind of document is being explained, DECLARED and never sniffed.
+   *
+   * `paper` asks the planner for the shape a research talk has: open on the
+   * problem and the ground the work stands on, close on what it does not do and
+   * then what to take away. `general` is every deck built before this existed
+   * and changes nothing — no prompt block, no `role` in the planner's schema, no
+   * scan.
+   *
+   * WHY DECLARED. A ten-role heading lexicon (en/ko/ja/zh, numbered-prefix
+   * tolerant) run over all 351 markdown files in this repository scored 345 of
+   * them at zero role hits and none at three or more. `src/source/markdown.ts`
+   * says why in its first line: the input is a hypepaper-style ANALYSIS of a
+   * paper, a rewrite that has already discarded the headings a detector would
+   * key on. A classifier here would be a guess with a confidence score attached,
+   * and it would guess wrong on the Korean fixture. So the author says so once —
+   * `--genre paper`, or one line in a `decksmith.config.json` above a directory
+   * of papers — and every run under it costs no further typing.
+   */
+  genre: z.enum(["general", "paper"]).default("general"),
   /**
    * How long the finished thing should run, in seconds. Optional: absent means
    * "as long as it takes", which is what every deck built before this did.
@@ -703,7 +729,10 @@ function selectBeats(storyboard, budget2, seconds = {}) {
   const protectedIds = protect(live, len, cap);
   const keep = knapsack(live, len, cap, protectedIds);
   if (!keep) {
-    const all = knapsack(live, len, cap, /* @__PURE__ */ new Set());
+    const ends = new Set(
+      [live[0]?.id, live[live.length - 1]?.id].filter((id2) => !!id2)
+    );
+    const all = knapsack(live, len, cap, ends) ?? knapsack(live, len, cap, /* @__PURE__ */ new Set());
     const chosen = all ?? [live[0]];
     return budgetDrops(live, chosen, dropped, storyboard, len, cap, budget2, false);
   }
@@ -735,8 +764,17 @@ function protect(live, len, cap) {
   }
   const picture = cheapest && !ids.has(cheapest.id) ? [cheapest] : [];
   for (const b of picture) ids.add(b.id);
+  const byId = new Map(live.map((b) => [b.id, b]));
+  const roled = [];
+  for (const b of live) {
+    if (!b.role) continue;
+    for (let hop = b; hop && !ids.has(hop.id); hop = byId.get(hop.inside?.beat ?? "")) {
+      ids.add(hop.id);
+      roled.push(hop);
+    }
+  }
   const ends = /* @__PURE__ */ new Set([first?.id, last?.id]);
-  const releasable = [...tier, ...coverage, ...picture].filter((b) => !ends.has(b.id)).sort((a, b) => rate(a) - rate(b) || len(b) - len(a));
+  const releasable = [...tier, ...coverage, ...picture, ...roled].filter((b) => !ends.has(b.id)).sort((a, b) => rate(a) - rate(b) || len(b) - len(a));
   const cost = () => live.filter((b) => ids.has(b.id)).reduce((s, b) => s + len(b), 0);
   for (const b of releasable) {
     if (cost() <= cap) break;
@@ -4717,6 +4755,9 @@ function depthCss(sid, pose, part) {
 // src/emit/archetypes/stack.ts
 var GAP3 = 44;
 var NUM_X = 48;
+function numSpine(floor) {
+  return Math.round(NUM_X * floor * 100 / MIN_FONT) / 100;
+}
 var PROBE_X = 16;
 var PROBE_H = 46;
 var NUM_W = 70;
@@ -4899,7 +4940,7 @@ var stack = (beat, ctx) => {
     );
     const num = text(
       String(i + 1),
-      { x: NUM_X, y: mid },
+      { x: numSpine(L.floor), y: mid },
       { size: L.floor, weight: 600, fill: theme.dim, anchor: "end", vAlign: "middle" }
     );
     return group(slab(L.x0, y0, L, tint, lift2, stroke), { id: id(sid, "lay", i), class: "lay" }) + group(num + leader + dot + label + note2, { id: id(sid, "cap", i), class: "cap" });
@@ -5669,6 +5710,76 @@ import { tmpdir } from "node:os";
 import { join as join3 } from "node:path";
 import { z as z2 } from "zod";
 
+// src/plan/arc.ts
+var ARC_ROLES = ["intro", "background", "limitations", "conclusion"];
+function requiredRoles(beatCount) {
+  if (beatCount >= 8) return ARC_ROLES;
+  if (beatCount >= 5) return ["limitations", "conclusion"];
+  return [];
+}
+function paperArcRequested(prefs) {
+  return prefs.genre === "paper";
+}
+function arcBeats(storyboard) {
+  const by = /* @__PURE__ */ new Map();
+  for (const beat of storyboard.beats) {
+    if (!beat.role) continue;
+    by.set(beat.role, [...by.get(beat.role) ?? [], beat]);
+  }
+  return by;
+}
+function arcProblems(storyboard, prefs) {
+  if (!paperArcRequested(prefs)) return [];
+  const beats = storyboard.beats;
+  const need = requiredRoles(Math.min(prefs.slides, beats.length));
+  if (!need.length) return [];
+  const out = [];
+  const by = arcBeats(storyboard);
+  for (const role of need) {
+    const held = by.get(role) ?? [];
+    if (held.length === 0) {
+      out.push(
+        `No beat carries role "${role}". A paper deck is meant to have one, and the source may not support it \u2014 write the beat, or drop \`--genre paper\` for this document.`
+      );
+      continue;
+    }
+    if (held.length > 1) {
+      out.push(
+        `${held.length} beats carry role "${role}" (${held.map((b) => b.id).join(", ")}). A structural job belongs to one slide.`
+      );
+    }
+  }
+  const last = beats[beats.length - 1];
+  if (need.includes("conclusion") && by.has("conclusion") && last?.role !== "conclusion") {
+    out.push(
+      `The deck ends on "${last?.id}" (${last?.archetype}), not on its conclusion. The conclusion is the last thing the viewer sees or it is not a conclusion.`
+    );
+  }
+  const limIdx = beats.findIndex((b) => b.role === "limitations");
+  const conIdx = beats.findIndex((b) => b.role === "conclusion");
+  if (need.includes("limitations") && limIdx >= 0 && conIdx >= 0 && limIdx !== conIdx - 1) {
+    out.push(
+      `The limitations beat is not the slide immediately before the conclusion. The two are a pair and the caveat comes first.`
+    );
+  }
+  const openingWindow = beats.slice(0, 3).map((b) => b.role);
+  for (const role of need.filter((r) => r === "intro" || r === "background")) {
+    if (by.has(role) && !openingWindow.includes(role)) {
+      out.push(
+        `The "${role}" beat is not in the first three slides. It is what the rest of the deck is understood against, so it has to arrive before the mechanism does.`
+      );
+    }
+  }
+  const lim = by.get("limitations")?.[0];
+  const con = by.get("conclusion")?.[0];
+  if (lim && con && lim.archetype === con.archetype) {
+    out.push(
+      `The limitations and conclusion beats are both \`${lim.archetype}\`. Two of the same picture running is what RULE 1 forbids; draw the conclusion where the source states it.`
+    );
+  }
+  return out;
+}
+
 // src/plan/duration.ts
 var SPEECH_CPS = { latin: 14.4, cjk: 6.5 };
 var LAST_HOLD_SECONDS = 4.2;
@@ -6258,6 +6369,46 @@ ${REVEAL_COUNTS}` : `  - ${n3 === 1 ? "ONE SENTENCE" : `${n3} SENTENCES`} FOR TH
     miss its duration.`;
   return { sentences, length };
 }
+function paperArc(slides) {
+  const asked = requiredRoles(slides);
+  const full = asked.includes("intro");
+  return `
+
+PAPER ARC \u2014 this source was declared a research paper.
+
+Four beats have a structural job, and each one NAMES its job in \`role\`. Every
+other beat leaves \`role\` off. A role is a job, not a heading: never write
+"Related work" or "Conclusion" as a headline, because RULE 8 still applies to
+all four.
+${full ? `
+  role: "intro"        Near the front. What problem exists and who has it, in
+                       the viewer's own terms. This is the opening RULE 6
+                       already asks for, named so the deck can be checked.
+  role: "background"   In the first three beats. What people did before this
+                       work, and where that ran out. Take it from what the
+                       source itself says about earlier approaches \u2014 if the
+                       source says nothing about them, leave the role off
+                       rather than inventing a literature (RULE 3).` : `
+This deck is short, so only the ENDING is required \u2014 an opening the deck
+already has is not worth a slide of its own here.`}
+  role: "limitations"  THE SECOND-TO-LAST beat. What the work does not do, in
+                       the source's own admission. Not a hedge inside another
+                       beat's sentence: its own slide.
+  role: "conclusion"   THE LAST beat, with nothing after it. What the viewer
+                       should carry away.
+
+  - The closing pair is TWO beats and they must not share an archetype (RULE 1).
+    A limitation the source admits to is usually a panel; the conclusion is the
+    claim the deck lands, so draw it where the source states it \u2014 bars, a
+    contrast, the figure that settles it \u2014 and fall back to a panel only when it
+    genuinely has no shape.
+  - Give all four a weight of 0.8 or above. A short cut keeps the
+    highest-weighted beats, and a structural beat below 0.8 is one the deck
+    loses at the first budget.
+  - If the source does not support one of these, LEAVE IT OUT. A slide that
+    admits a limitation the paper never admits is worse than no slide.
+`;
+}
 function illustrations(images) {
   return `
 
@@ -6286,7 +6437,7 @@ nothing, so it can never dangle.
 }
 function systemPrompt(prefs) {
   const plan = durationPlan(prefs);
-  return `${rules(cadenceFor(prefs, plan))}${prefs.images.enabled ? illustrations(prefs.images) : ""}
+  return `${rules(cadenceFor(prefs, plan))}${paperArcRequested(prefs) ? paperArc(prefs.slides) : ""}${prefs.images.enabled ? illustrations(prefs.images) : ""}
 
 PREFERENCES \u2014 chosen by the person who asked for this deck.
 ${prefs.duration === void 0 ? "" : `
@@ -6597,8 +6748,11 @@ function stripNulls(node) {
   return out;
 }
 var PLANNER_INVISIBLE = /* @__PURE__ */ new Set(["tilt"]);
-function hideFromPlanner(node) {
-  if (Array.isArray(node)) return node.map(hideFromPlanner);
+function plannerInvisible(prefs) {
+  return paperArcRequested(prefs) ? PLANNER_INVISIBLE : /* @__PURE__ */ new Set([...PLANNER_INVISIBLE, "role"]);
+}
+function hideFromPlanner(node, hidden) {
+  if (Array.isArray(node)) return node.map((n3) => hideFromPlanner(n3, hidden));
   if (node === null || typeof node !== "object") return node;
   const src = node;
   const out = {};
@@ -6606,28 +6760,32 @@ function hideFromPlanner(node) {
     if (key === "properties" && value && typeof value === "object") {
       const kept = {};
       for (const [prop, sub] of Object.entries(value))
-        if (!PLANNER_INVISIBLE.has(prop)) kept[prop] = hideFromPlanner(sub);
+        if (!hidden.has(prop)) kept[prop] = hideFromPlanner(sub, hidden);
       out.properties = kept;
       continue;
     }
     if (key === "required" && Array.isArray(value)) {
-      out.required = value.filter((r) => typeof r !== "string" || !PLANNER_INVISIBLE.has(r));
+      out.required = value.filter((r) => typeof r !== "string" || !hidden.has(r));
       continue;
     }
-    out[key] = hideFromPlanner(value);
+    out[key] = hideFromPlanner(value, hidden);
   }
   return out;
 }
-var SCHEMA = hideFromPlanner(
-  forStructuredOutput(z2.toJSONSchema(storyboardSchema, { io: "input" }))
-);
+function schemaFor(prefs) {
+  return hideFromPlanner(
+    forStructuredOutput(z2.toJSONSchema(storyboardSchema, { io: "input" })),
+    plannerInvisible(prefs)
+  );
+}
+var SCHEMA = schemaFor({ genre: "general" });
 async function codexPlanner(source, opts = {}) {
   const prefs = opts.prefs ?? prefsSchema.parse({});
   const dir = await mkdtemp(join3(tmpdir(), "decksmith-plan-"));
   try {
     const schemaPath = join3(dir, "storyboard.schema.json");
     const outPath = join3(dir, "storyboard.json");
-    await writeFile3(schemaPath, JSON.stringify(SCHEMA));
+    await writeFile3(schemaPath, JSON.stringify(schemaFor(prefs)));
     await (opts.run ?? runCodex)({
       prompt: buildPrompt(source, prefs),
       schemaPath,
@@ -7692,6 +7850,7 @@ function prefsFromFlags(flags2) {
   if (flags2.lang !== void 0) patch.lang = flags2.lang;
   if (flags2.tone !== void 0) patch.tone = flags2.tone;
   if (flags2.density !== void 0) patch.density = flags2.density;
+  if (flags2.genre !== void 0) patch.genre = flags2.genre;
   if (flags2.duration !== void 0) patch.duration = number("--duration", flags2.duration);
   if (flags2.theme !== void 0) patch.theme = flags2.theme;
   if (flags2.speed !== void 0) patch.animationSpeed = number("--speed", flags2.speed);
@@ -8443,13 +8602,14 @@ function pieceArgs(source, fromFrame, motion, freeze, fps, out) {
     out
   ];
 }
+var LOUDNESS = "loudnorm=I=-16:TP=-1.5:LRA=11,aresample=48000";
 function audioGraph(inputs, seconds, first = 1) {
   const lines = inputs.map(
     (input, i) => `[${first + i}:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,adelay=${input.delayMs}:all=1[d${i}]`
   );
   const labels = inputs.map((_, i) => `[d${i}]`).join("");
   lines.push(
-    `${labels}amix=inputs=${inputs.length}:normalize=0:dropout_transition=0:duration=longest,apad=whole_dur=${seconds.toFixed(3)}[aout]`
+    `${labels}amix=inputs=${inputs.length}:normalize=0:dropout_transition=0:duration=longest,${LOUDNESS},apad=whole_dur=${seconds.toFixed(3)}[aout]`
   );
   return lines.join(";\n");
 }
@@ -9998,24 +10158,25 @@ async function verify(dir, opts = {}, storyboard, kept, source) {
     check2(dir, { ...opts, at: stops.map((s) => s.t) }),
     opts.fidelity === false ? null : fidelity(dir, { stops })
   ]);
-  const seen = [...ours, ...frames2?.findings ?? []];
+  const storyboardFindings = storyboard ? [
+    ...scanDiagrammatic(storyboard),
+    ...scanHeadlines(storyboard),
+    ...scanRepeatedObject(storyboard),
+    // Needs the source as well, and says nothing without it — the same
+    // silence `scanNarrationLead` keeps when its manifest is missing.
+    ...source ? scanUnusedFigures(storyboard, source) : []
+  ] : [];
+  const seen = [...ours, ...frames2?.findings ?? [], ...storyboardFindings];
   return {
     passed: verdict.passed && seen.every((f) => f.severity !== "error"),
     findings: [
       ...seen,
-      // `scanBeatCount` is deliberately NOT here. It needs the preferences the
-      // deck was asked for, and `verify <dir>` is handed a built directory and
-      // nothing else — the same gating `scanNarrationLead` gets above, and for
-      // the same reason: a check that cannot see its inputs must not report that
-      // it found nothing. It runs at `plan` and `build`, where prefs exist.
-      ...storyboard ? [
-        ...scanDiagrammatic(storyboard),
-        ...scanHeadlines(storyboard),
-        ...scanRepeatedObject(storyboard),
-        // Needs the source as well, and says nothing without it — the same
-        // silence `scanNarrationLead` keeps when its manifest is missing.
-        ...source ? scanUnusedFigures(storyboard, source) : []
-      ] : [],
+      // `scanBeatCount` and `scanPaperArc` are deliberately NOT here. Both need
+      // the preferences the deck was asked for, and `verify <dir>` is handed a
+      // built directory and nothing else — the same gating `scanNarrationLead`
+      // gets above, and for the same reason: a check that cannot see its inputs
+      // must not report that it found nothing. They run at `plan` and `build`,
+      // where prefs exist.
       ...verdict.findings
     ]
   };
@@ -10200,6 +10361,32 @@ function scanBeatCount(storyboard, prefs) {
     }
   ];
 }
+function scanPaperArc(storyboard, prefs) {
+  return arcProblems(storyboard, prefs).map((message) => ({
+    severity: "warning",
+    gate: "storyboard",
+    rule: "paper_arc",
+    message
+  }));
+}
+function scanNarrationDrift(storyboard, narration) {
+  const flat = (s) => (s ?? "").replace(/\s+/g, " ").trim();
+  const stale = [];
+  for (const beat of storyboard.beats) {
+    const segments = narration.beats[beat.id];
+    if (!segments?.length || !flat(beat.narration)) continue;
+    if (flat(segments.map((s) => s.text).join(" ")) !== flat(beat.narration)) stale.push(beat.id);
+  }
+  if (!stale.length) return [];
+  return [
+    {
+      severity: "error",
+      gate: "storyboard",
+      rule: "narration_drift",
+      message: `The recorded narration does not say what ${stale.length} beat(s) say they say: ${stale.join(", ")}. narration.json is keyed by beat id and carries no link to the plan it was made for, so a storyboard whose beats were renumbered or rewritten keeps matching ids and speaks the wrong slide. Re-run \`decksmith narrate\` for this storyboard \u2014 the audio cache is keyed by TEXT, so lines that did not change are not re-synthesised.`
+    }
+  ];
+}
 var LEAD_SECONDS = 1;
 var EMPHASISED = /* @__PURE__ */ new Set(["equation-walk", "data-table"]);
 function scanNarrationLead(beats, timing) {
@@ -10379,7 +10566,10 @@ var HYPERFRAMES_JSON = `${JSON.stringify(
 )}
 `;
 function planFlags(cmd) {
-  return cmd.option("--lang <bcp47>", "language of the deck's copy").option("--tone <tone>", "plain | academic | conversational | punchy").option("--density <level>", "sparse | normal | dense");
+  return cmd.option("--lang <bcp47>", "language of the deck's copy").option("--tone <tone>", "plain | academic | conversational | punchy").option("--density <level>", "sparse | normal | dense").option(
+    "--genre <genre>",
+    "general | paper \u2014 paper asks for an intro, background, limitations and conclusion"
+  );
 }
 function lengthFlags(cmd) {
   return cmd.option("--duration <s>", "target length of the finished video, in seconds (10\u20131800)").option("--slides <n>", "target beat count (3\u201340)").option(
@@ -10406,6 +10596,7 @@ function flags(o) {
     "lang",
     "tone",
     "density",
+    "genre",
     "duration",
     "narrationDensity",
     "theme",
@@ -10475,6 +10666,11 @@ imageFlags(
   }
   for (const f of [
     ...scanBeatCount(storyboard, prefs),
+    // Silent unless `--genre paper` was declared. Here for the same reason
+    // `scanBeatCount` is: the fix is a beat in a file the author has open, and
+    // this is the last moment before a minute of TTS is spent on a deck that
+    // does not end where it was asked to.
+    ...scanPaperArc(storyboard, prefs),
     ...scanHeadlines(storyboard),
     ...scanRepeatedObject(storyboard),
     // A figure the plan ignored is cheapest to fix here, where the answer is one
@@ -10548,7 +10744,7 @@ voiceFlags(
 });
 lookFlags(
   sizeFlags(
-    lengthFlags(program.command("build")).description("Emit the composition, write its assets, and run the gates.").argument("<storyboard>", "storyboard.json, edited to taste").requiredOption("--source <file>", "source.json the storyboard was planned from").requiredOption("-o, --out <dir>", "directory to write the deck into").option("--format <id>", `output profile: ${Object.keys(FORMATS).join(" | ")}`, "deck-16x9").option("--min-weight <n>", "keep only beats at or above this weight \u2014 see the budget gate").option("--narration <file>", `${NARRATION_FILE} from \`decksmith narrate\``).option("--no-narration", "ignore narration sitting beside the storyboard").option("--no-fidelity", "skip the frame check \u2014 only for a machine with no browser")
+    lengthFlags(program.command("build")).description("Emit the composition, write its assets, and run the gates.").argument("<storyboard>", "storyboard.json, edited to taste").requiredOption("--source <file>", "source.json the storyboard was planned from").requiredOption("-o, --out <dir>", "directory to write the deck into").option("--format <id>", `output profile: ${Object.keys(FORMATS).join(" | ")}`, "deck-16x9").option("--min-weight <n>", "keep only beats at or above this weight \u2014 see the budget gate").option("--genre <genre>", "general | paper \u2014 report when a paper deck lacks its arc").option("--narration <file>", `${NARRATION_FILE} from \`decksmith narrate\``).option("--no-narration", "ignore narration sitting beside the storyboard").option("--no-fidelity", "skip the frame check \u2014 only for a machine with no browser")
   )
 ).action(
   async (sbPath, o) => {
@@ -10562,6 +10758,10 @@ lookFlags(
     await mkdir9(out, { recursive: true });
     const found = await findNarration(sbPath, o.narration);
     const narration = found ? await loadNarration(found) : void 0;
+    if (narration) {
+      const drift2 = scanNarrationDrift(storyboard, narration);
+      if (drift2.length > 0) throw new Error(drift2[0]?.message ?? "narration drift");
+    }
     if (narration && !format.navigable) {
       step(`build: ${format.id} renders linearly, so its narration is timing only`);
     }
@@ -10612,6 +10812,8 @@ lookFlags(
     step(
       `build: ${cut.kept.length}${of} beats at ${format.width}\xD7${format.height} in ${look}${floor > 0 ? ` (${floor} below minWeight ${format.minWeight})` : ""} \u2192 ${join15(out, "index.html")}`
     );
+    for (const f of scanPaperArc({ ...storyboard, beats: cut.kept }, prefs))
+      step(`build: ${f.message}`);
     reportCut(cut);
     if (deck.page) step(`build: navigable deck \u2192 ${join15(out, DECK_PAGE)}`);
     await gate(out, false, storyboard, cut.kept, o.fidelity !== false, source);