@jokerized/decksmith 0.3.0 → 0.3.1

package/dist/index.js

@@ -290,10 +290,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. */
@@ -440,6 +446,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" });
@@ -6135,6 +6176,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;
@@ -6724,6 +6835,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 `
 
@@ -6752,7 +6903,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 ? "" : `
@@ -7063,8 +7214,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 = {};
@@ -7072,28 +7226,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,
@@ -9127,24 +9285,25 @@ async function verify(dir, opts = {}, storyboard, kept, source) {
     check(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
     ]
   };
@@ -9329,6 +9488,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) {
@@ -9712,13 +9897,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");
 }
@@ -10451,6 +10637,7 @@ export {
   assertInsideResolves,
   assertRefsResolve,
   barCompareParamsSchema,
+  beatRoleSchema,
   beatSchema,
   buildDeck,
   bundleFont,
@@ -10517,7 +10704,9 @@ export {
   sampleTimes,
   scanBeatCount,
   scanHeadlines,
+  scanNarrationDrift,
   scanNarrationLead,
+  scanPaperArc,
   scanRepeatedObject,
   scanUnusedFigures,
   sectionSchema,

package/dist/mcp.js

@@ -310,10 +310,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. */
@@ -448,6 +454,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.
@@ -705,7 +731,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);
   }
@@ -737,8 +766,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;
@@ -4719,6 +4757,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;
@@ -4901,7 +4942,7 @@ var stack = (beat, ctx) => {
     );
     const num2 = 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(num2 + leader + dot + label + note, { id: id(sid, "cap", i), class: "cap" });
@@ -6134,6 +6175,17 @@ 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";
+}
+
 // src/plan/duration.ts
 var SPEECH_CPS = { latin: 14.4, cjk: 6.5 };
 var LAST_HOLD_SECONDS = 4.2;
@@ -6723,6 +6775,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 `
 
@@ -6751,7 +6843,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 ? "" : `
@@ -7020,8 +7112,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 = {};
@@ -7029,28 +7124,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,
@@ -8173,13 +8272,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");
 }
@@ -8968,6 +9068,7 @@ function parseOptions(fields) {
   if (str(fields.lang) !== void 0) patch.lang = requireLang(str(fields.lang));
   if (str(fields.tone) !== void 0) patch.tone = str(fields.tone);
   if (str(fields.density) !== void 0) patch.density = str(fields.density);
+  if (str(fields.genre) !== void 0) patch.genre = str(fields.genre);
   if (str(fields.duration) !== void 0)
     patch.duration = num("duration", fields.duration);
   if (str(fields.speed) !== void 0) patch.animationSpeed = num("speed", fields.speed);
@@ -9818,6 +9919,9 @@ var settingsSchema = z4.object({
   ),
   tone: z4.enum(["plain", "academic", "conversational", "punchy"]).optional(),
   density: z4.enum(["sparse", "normal", "dense"]).optional().describe("How much text a SLIDE carries. A different axis from narration_density."),
+  genre: z4.enum(["general", "paper"]).optional().describe(
+    "DECLARED, never detected. `paper` asks for a research-talk shape \u2014 an introduction and background at the front, a limitations slide and then a conclusion at the end \u2014 and reports where the deck missed it. There is no detector: the documents this tool ingests are analyses OF papers, rewritten in a way that drops the headings a detector would need, so nothing infers this and absent means `general`."
+  ),
   duration: z4.number().min(10).max(1800).optional().describe(
     "Target seconds. Sets the pace, derives the slide count when you give none, and overrides animation_speed. Call decksmith_estimate_length first \u2014 a short target buys its words by saying less, not by playing faster."
   ),
@@ -9849,6 +9953,7 @@ function fieldsFor(s) {
   put("lang", s.lang);
   put("tone", s.tone);
   put("density", s.density);
+  put("genre", s.genre);
   put("duration", s.duration);
   put("slides", s.slides);
   put("speed", s.animation_speed);

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/index.d.ts

@@ -111,7 +111,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";
 /**