@jokerized/decksmith 0.2.0 → 0.3.1

package/dist/mcp.js

@@ -127,6 +127,13 @@ var equationWalkParamsSchema = z.object({
   /** Walked in order, one hold-point each. */
   terms: z.array(termSchema).min(1).max(4)
 });
+var equationMorphParamsSchema = z.object({
+  eyebrow: z.string().optional(),
+  headline: z.string(),
+  fromId: z.string(),
+  toId: z.string(),
+  terms: z.array(termSchema).min(1).max(4)
+});
 var dataTableParamsSchema = z.object({
   eyebrow: z.string().optional(),
   headline: z.string(),
@@ -255,7 +262,22 @@ var stackParamsSchema = z.object({
   headline: z.string(),
   /** Drawn bottom-up as offset planes, revealed in order. */
   layers: z.array(z.object({ label: z.string(), note: z.string().optional() })).min(2).max(7),
-  note: z.string().optional()
+  note: z.string().optional(),
+  /**
+   * Tilt the slab stack away from the viewer, so the planes read as stacked in
+   * depth rather than merely offset up the page.
+   *
+   * OPTIONAL, and absent means flat — every storyboard written before this
+   * existed still parses, and every deck that does not ask for it emits exactly
+   * the bytes it did before.
+   *
+   * Degrees, and bounded at 18 rather than by taste: the tilt is paid for in
+   * declared type, because perspective shrinks the far half of the plane and
+   * invariant 5 is about what the audience SEES. At 18 degrees a 40px floor
+   * already needs 53.8px declared (`src/emit/depth.ts`), and past that a
+   * headline cannot spend enough and still fit its own line.
+   */
+  tilt: z.number().min(0).max(18).optional()
 });
 var splitSideSchema = z.object({
   label: z.string(),
@@ -288,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. */
@@ -320,6 +348,12 @@ var beatSchema = z.discriminatedUnion("archetype", [
     params: equationWalkParamsSchema,
     ...beatTail
   }),
+  z.object({
+    ...beatCore,
+    archetype: z.literal("equation-morph"),
+    params: equationMorphParamsSchema,
+    ...beatTail
+  }),
   z.object({
     ...beatCore,
     archetype: z.literal("data-table"),
@@ -377,7 +411,8 @@ var ARCHETYPE_FAMILY = {
   "bar-compare": "quantity",
   "line-chart": "quantity",
   "data-table": "quantity",
-  "equation-walk": "formal"
+  "equation-walk": "formal",
+  "equation-morph": "formal"
 };
 var storyboardSchema = z.object({
   sourceId: z.string(),
@@ -419,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.
@@ -676,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);
   }
@@ -708,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;
@@ -3082,7 +3149,7 @@ function locate(tex, term) {
   end = Math.max(end, hay.map[lastNorm + 1] ?? lastOrig + 1);
   return { start, end: Math.min(end, tex.length) };
 }
-function wrapTerms(tex, terms, beatId) {
+function wrapTerms(tex, terms, beatId, cls = (t2) => `term t-${t2.tone}`) {
   let parts = [{ text: tex, raw: true }];
   const used = [];
   const missing = [];
@@ -3098,7 +3165,7 @@ function wrapTerms(tex, terms, beatId) {
         1,
         { text: part.text.slice(0, at.start), raw: true },
         {
-          text: `\\htmlClass{term t-${term.tone}}{${part.text.slice(at.start, at.end)}}`,
+          text: `\\htmlClass{${cls(term)}}{${part.text.slice(at.start, at.end)}}`,
           raw: false
         },
         { text: part.text.slice(at.end), raw: true }
@@ -3131,6 +3198,24 @@ function statements(tex, stacked) {
   const parts = tex.split(/\\qquad|\\quad|\\\\/).map((s) => s.trim()).filter(Boolean);
   return parts.length > 0 ? parts : [tex];
 }
+function legendRows(sid, terms, theme) {
+  return terms.map(
+    (t2) => `<div class="leg" id="${sid}-leg-${t2.tone}"><span class="chip" id="${sid}-chip-${t2.tone}" style="color:${theme.tones[t2.tone]}"></span><span>${esc(t2.label)}</span></div>`
+  ).join("\n    ");
+}
+function legendCss(theme) {
+  return [
+    // `width:fit-content` + auto margins, not `align-items:center`: centring
+    // each row individually gave the legend a ragged left edge, because a short
+    // label indented its own chip further than a long one did. The column is
+    // centred as one block and the rows start on a shared spine.
+    ".legend{display:flex;flex-direction:column;gap:30px;width:fit-content;margin-inline:auto}",
+    `.leg{display:flex;gap:26px;align-items:baseline;max-width:1400px;font-size:48px;color:${theme.muted}}`,
+    // A common chip width, so the labels share a spine too — the glyphs inside
+    // are one symbol each and their natural widths differ by a few pixels.
+    `.chip{display:inline-block;min-width:72px;text-align:center;background:${theme.panel};border-radius:10px;padding:2px 20px;white-space:nowrap;font-weight:700}`
+  ].join("\n");
+}
 var equationWalk = (beat, ctx) => {
   const { sid, theme } = ctx;
   const p = beat.params;
@@ -3142,9 +3227,7 @@ var equationWalk = (beat, ctx) => {
   }
   const walk = wrapTerms(eq.tex, p.terms, beat.id);
   const terms = walk.used;
-  const legend = terms.map(
-    (t2) => `<div class="leg" id="${sid}-leg-${t2.tone}"><span class="chip" id="${sid}-chip-${t2.tone}" style="color:${theme.tones[t2.tone]}"></span><span>${esc(t2.label)}</span></div>`
-  ).join("\n    ");
+  const legend = legendRows(sid, terms, theme);
   const stacked = isPortrait(ctx.format);
   const raw2 = statements(eq.tex, stacked);
   const shown = statements(walk.tex, stacked);
@@ -3243,15 +3326,7 @@ var equationWalk = (beat, ctx) => {
       ".eqstack{display:flex;flex-direction:column;gap:32px}",
       // Transforms do not apply to inline boxes, and KaTeX spans are inline.
       ".term{display:inline-block}",
-      // `width:fit-content` + auto margins, not `align-items:center`: centring
-      // each row individually gave the legend a ragged left edge, because a short
-      // label indented its own chip further than a long one did. The column is
-      // centred as one block and the rows start on a shared spine.
-      ".legend{display:flex;flex-direction:column;gap:30px;width:fit-content;margin-inline:auto}",
-      `.leg{display:flex;gap:26px;align-items:baseline;max-width:1400px;font-size:48px;color:${theme.muted}}`,
-      // A common chip width, so the labels share a spine too — the glyphs inside
-      // are one symbol each and their natural widths differ by a few pixels.
-      `.chip{display:inline-block;min-width:72px;text-align:center;background:${theme.panel};border-radius:10px;padding:2px 20px;white-space:nowrap;font-weight:700}`,
+      legendCss(theme),
       // The block, not the term under discussion: which term that is, is a fact
       // about the paused timeline, and CSS cannot see it. The terms are also the
       // one thing here GSAP tints and swells, so a rule on them would win the
@@ -3261,6 +3336,117 @@ var equationWalk = (beat, ctx) => {
   };
 };
 
+// src/emit/archetypes/equation-morph.ts
+var MORPH_SECONDS = 1.6;
+var equationMorph = (beat, ctx) => {
+  const { sid, theme } = ctx;
+  const p = beat.params;
+  const find2 = (id2) => {
+    const eq = ctx.source.equations.find((e) => e.id === id2);
+    if (!eq)
+      throw new Error(`equation-morph ${beat.id}: no equation "${id2}" in source ${ctx.source.id}`);
+    return eq;
+  };
+  const a = find2(p.fromId);
+  const b = find2(p.toId);
+  const both = p.terms.filter((t2) => locate(a.tex, t2.tex) && locate(b.tex, t2.tex));
+  if (both.length === 0) {
+    throw new Error(
+      `equation-morph ${beat.id}: none of its ${p.terms.length} term(s) occur in both equations. Terms: ${p.terms.map((t2) => JSON.stringify(t2.tex)).join(", ")}. From: ${JSON.stringify(a.tex)}. To: ${JSON.stringify(b.tex)}`
+    );
+  }
+  const cls = (t2) => `term t-${t2.tone} ds-k-${t2.tone}`;
+  const wa = wrapTerms(a.tex, both, beat.id, cls).tex;
+  const wb = wrapTerms(b.tex, both, beat.id, cls).tex;
+  const size = Math.max(
+    MIN_FONT,
+    Math.min(
+      equationSize(a.tex.length > b.tex.length ? a.tex : b.tex),
+      Math.floor(contentW(ctx.format) / Math.max(texUnits(a.tex), texUnits(b.tex)))
+    )
+  );
+  const html = `${chrome(sid, p.eyebrow, p.headline, contentW(ctx.format))}
+<div class="eqslide">
+  <div class="morph" id="${sid}-morph" style="font-size:${size}px">
+    <div class="side" data-morph="a" id="${sid}-eqa"></div>
+    <div class="side" data-morph="b" id="${sid}-eqb"></div>
+  </div>
+  <div class="legend">
+    ${legendRows(sid, both, theme)}
+  </div>
+</div>`;
+  const setup = [
+    `var OPTS = ${OPTS};`,
+    `katex.render('${js(wa)}', document.getElementById("${sid}-eqa"), OPTS);`,
+    `katex.render('${js(wb)}', document.getElementById("${sid}-eqb"), OPTS);`,
+    ...both.map(
+      (t2) => `katex.render('${js(t2.tex)}', document.getElementById("${sid}-chip-${t2.tone}"), ${INLINE_OPTS});`
+    )
+  ];
+  const first = 1.8;
+  const at = Math.round(
+    Math.max(2.6, Math.min(beat.seconds - MORPH_SECONDS - 0.9, beat.seconds * 0.45)) * 100
+  ) / 100;
+  const tl = [
+    ...chromeIn(sid, p.eyebrow !== void 0),
+    tween(`#${sid}-morph`, { opacity: 0, y: 22 }, { opacity: 1, y: 0, duration: 0.7 }, 0.8),
+    ...both.map(
+      (t2, i) => tween(
+        `#${sid}-leg-${t2.tone}`,
+        { opacity: 0, x: -18 },
+        { opacity: 1, x: 0, duration: 0.5 },
+        1 + i * 0.15
+      )
+    ),
+    // ONE tween, on the host, driving the plugin. Its ease is "none" because the
+    // plan carries its own eases per segment; `pace` scales this duration and
+    // the plan, being in fractions of it, scales with it.
+    tween(
+      `#${sid}-morph`,
+      { dsMorph: 0 },
+      { dsMorph: 1, duration: MORPH_SECONDS, ease: "none" },
+      at
+    )
+  ];
+  return {
+    html,
+    tl,
+    setup,
+    // SEAM B: the plan is browser geometry after fonts, so it is built inside
+    // the ready gate, and the plugin tween above finds it on the host.
+    measure: [`DSMorph.build(document.getElementById("${sid}-morph"));`],
+    plugins: ["dsMorph"],
+    holds: holdsWithin([first, at + MORPH_SECONDS + 0.4], beat.seconds),
+    css: [
+      chromeCss(theme),
+      ".eqslide{display:flex;flex-direction:column;justify-content:space-evenly;gap:64px;flex:1;min-height:0}",
+      ".katex-display{margin:0 !important}",
+      // Both sides in one grid cell, so the host is as tall as the taller line
+      // and neither needs a guessed height; the overlay is absolute over it.
+      // Padded by the room an arc needs, so a bowing glyph stays inside its
+      // offset parent and the layout gate's `escaped_container` stays quiet; the
+      // bow is capped to the same 0.8em in `plan`.
+      `.morph{position:relative;display:grid;place-items:center;text-align:center;padding:0.8em 0.5em;color:${theme.fg}}`,
+      ".side{grid-area:1/1}",
+      // B is measured, never seen: the runtime lifts its glyphs into the overlay
+      // and drives them from there. Hidden by the sheet so nothing is captured
+      // before the gate has built the plan.
+      '.side[data-morph="b"]{visibility:hidden}',
+      ".ds-morph-layer{position:absolute;inset:0}",
+      ".term{display:inline-block}",
+      // Keys are tinted from the start, on BOTH lines — the colour is what lets
+      // a viewer follow a body across the move. Scoped under `.morph` because
+      // `equation-walk` tweens `.t-<tone>` from the foreground colour, and a
+      // bare rule on the class would win that cascade and cancel its walk.
+      ...["a", "b", "c", "d"].map(
+        (tone2) => `.morph .t-${tone2}{color:${theme.tones[tone2]}}`
+      ),
+      legendCss(theme),
+      ambient(sid, "-morph", BREATHE)
+    ].join("\n")
+  };
+};
+
 // src/emit/archetypes/grid.ts
 var LABEL = 42;
 var LH = 1.25;
@@ -4544,9 +4730,36 @@ var splitCompare = (beat, ctx) => {
   };
 };
 
+// src/emit/depth.ts
+var DEFAULT_POSE = { rotateX: 12, perspective: 1400 };
+function scaleAt(pose, dy) {
+  const t2 = pose.rotateX * Math.PI / 180;
+  const denom = pose.perspective - dy * Math.sin(t2);
+  if (denom <= 0) return 0;
+  return Math.cos(t2) * (pose.perspective / denom) ** 2;
+}
+var MODEL_SLACK = 0.98;
+function worstScale(pose, height) {
+  if (scaleAt(pose, height / 2) <= 0) return 0;
+  return scaleAt(pose, -height / 2) * MODEL_SLACK;
+}
+function tiltedFloor(pose, height, floor) {
+  const s = worstScale(pose, height);
+  return s > 0 ? floor / s : Number.POSITIVE_INFINITY;
+}
+function depthCss(sid, pose, part) {
+  return [
+    `#${sid} { perspective: ${pose.perspective}px; }`,
+    `#${sid} ${part} { transform: rotateX(${pose.rotateX}deg); transform-origin: 50% 50%; }`
+  ].join("\n");
+}
+
 // 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;
@@ -4567,15 +4780,20 @@ function stackLayout(p, format, face = "latin") {
 function labelWeight(i, count) {
   return i === count - 1 ? 700 : 600;
 }
+function floorFor(p, format) {
+  if (!p.tilt) return MIN_FONT;
+  return tiltedFloor({ ...DEFAULT_POSE, rotateX: p.tilt }, contentH(format), MIN_FONT);
+}
 function solve2(p, format, inline, face) {
   const width = contentW(format);
   const boxH = contentH(format);
+  const floor = floorFor(p, format);
   const count = p.layers.length;
   const k = isPortrait(format) ? "tall" : "wide";
   const riseMax = RISE_MAX[k];
   const syMax = SY_MAX[k];
   const tMax = T_MAX[k];
-  const noteW = (l) => inline && l.note !== void 0 ? textWidth(l.note, MIN_FONT, 400, 0, false, face) + 28 : 0;
+  const noteW = (l) => inline && l.note !== void 0 ? textWidth(l.note, floor, 400, 0, false, face) + 28 : 0;
   const want = Math.max(
     ...p.layers.map(
       (l, i) => textWidth(l.label, LABEL_SIZE2, labelWeight(i, count), 0, false, face) + noteW(l)
@@ -4590,7 +4808,7 @@ function solve2(p, format, inline, face) {
       (l, i) => (colW - noteW(l)) / Math.max(1, textWidth(l.label, 1, labelWeight(i, count), 0, false, face))
     )
   );
-  const labelSize = Math.max(MIN_FONT, Math.min(LABEL_SIZE2, labelRoom));
+  const labelSize = Math.max(floor, Math.min(LABEL_SIZE2, labelRoom));
   const lines = p.layers.map((l, i) => {
     const nw = noteW(l);
     const labelMaxW = Math.max(labelSize, colW - nw);
@@ -4598,14 +4816,14 @@ function solve2(p, format, inline, face) {
       label: wrap(l.label, labelSize, labelMaxW, labelWeight(i, count), 0, face),
       // Inline notes stay on one line by contract — the schema calls a note "one
       // short line" — and wrapping one would put its second line under the label.
-      note: l.note === void 0 ? [] : inline ? [l.note] : wrap(l.note, MIN_FONT, colW, 400, 0, face),
+      note: l.note === void 0 ? [] : inline ? [l.note] : wrap(l.note, floor, colW, 400, 0, face),
       noteW: nw,
       labelMaxW
     };
   });
   const blockH = Math.max(
     ...lines.map(
-      (l) => inline ? Math.max(l.label.length * labelSize, l.note.length * MIN_FONT) * 1.16 : l.label.length * labelSize * 1.16 + (l.note.length > 0 ? 6 + l.note.length * MIN_FONT * 1.16 : 0)
+      (l) => inline ? Math.max(l.label.length * labelSize, l.note.length * floor) * 1.16 : l.label.length * labelSize * 1.16 + (l.note.length > 0 ? 6 + l.note.length * floor * 1.16 : 0)
     )
   );
   const pad = Math.max(EDGE2, blockH / 2);
@@ -4625,6 +4843,7 @@ function solve2(p, format, inline, face) {
     // BOTH directions. A layout that fits the height and not the width is not a
     // layout that fits; it is one whose overflow is in the axis nothing measured.
     fits: room >= blockH + 10 && height <= free && wide,
+    floor,
     wide,
     inline,
     width,
@@ -4664,7 +4883,7 @@ var stack = (beat, ctx) => {
   const last = count - 1;
   if (!L.fits) {
     throw new Error(
-      `stack ${beat.id}: ${count} layers with ${p.layers.filter((l) => l.note).length} note(s) need ${Math.round(L.blockH)}px of label block against ${Math.round(L.avail)}px of room, at the ${MIN_FONT}px floor and with the notes already moved beside their labels. Nothing here may be set smaller, so the lever is upstream of this beat: drop a layer, or shorten the notes.`
+      `stack ${beat.id}: ${count} layers with ${p.layers.filter((l) => l.note).length} note(s) need ${Math.round(L.blockH)}px of label block against ${Math.round(L.avail)}px of room, at the ${Math.round(L.floor)}px floor and with the notes already moved beside their labels. Nothing here may be set smaller, so the lever is upstream of this beat: drop a layer, or shorten the notes.`
     );
   }
   const parts = {};
@@ -4686,7 +4905,7 @@ var stack = (beat, ctx) => {
     const dot = circle({ x: L.x0 + L.w + L.sx / 2 + 8, y: mid }, 6, { fill: tint });
     const block = L.lines[i] ?? { label: [], note: [], noteW: 0, labelMaxW: L.colW };
     const labelH = block.label.length * L.labelSize * 1.16;
-    const noteH = block.note.length > 0 ? 6 + block.note.length * MIN_FONT * 1.16 : 0;
+    const noteH = block.note.length > 0 ? 6 + block.note.length * L.floor * 1.16 : 0;
     const label = text(
       layer.label,
       { x: L.labelX, y: L.inline ? mid : mid - noteH / 2 },
@@ -4712,7 +4931,7 @@ var stack = (beat, ctx) => {
         { x: L.labelX, y: mid + labelH / 2 + 3 }
       ),
       {
-        size: MIN_FONT,
+        size: L.floor,
         fill: theme.muted,
         anchor: L.inline ? "end" : "start",
         maxWidth: L.inline ? void 0 : L.colW,
@@ -4723,8 +4942,8 @@ var stack = (beat, ctx) => {
     );
     const num2 = text(
       String(i + 1),
-      { x: NUM_X, y: mid },
-      { size: MIN_FONT, weight: 600, fill: theme.dim, anchor: "end", vAlign: "middle" }
+      { 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" });
   }).join("");
@@ -4746,6 +4965,8 @@ var stack = (beat, ctx) => {
 <div class="stnote" id="${sid}-note">${esc(p.note)}</div>` : "";
   const html = `${chrome(sid, p.eyebrow, p.headline, contentW(ctx.format))}
 <div class="stackwrap">${svg(id(sid, "stack"), L.width, L.height, body + probe3)}</div>${noteHtml}`;
+  const centre2 = (count - 1) / 2;
+  const enterFrom = (i) => p.tilt ? (i - centre2) * L.rise : 34;
   const first = 0.9;
   const step = Math.min(0.8, Math.max(0.4, (beat.seconds - first - 1.5) / count));
   const tl = [...chromeIn(sid, p.eyebrow !== void 0)];
@@ -4756,7 +4977,7 @@ var stack = (beat, ctx) => {
     tl.push(
       tween(
         `#${sid}-lay${i}`,
-        { opacity: 0, y: 34 },
+        { opacity: 0, y: enterFrom(i) },
         { opacity: 1, y: 0, duration: 0.55, ease: "power2.out" },
         at
       )
@@ -4799,8 +5020,12 @@ var stack = (beat, ctx) => {
       // The top plane is the focal point — last built, differently toned, and the
       // one the final hold sits on. Its entrance owns `opacity` and `transform`,
       // so the breath takes `filter`, the property nothing else writes.
-      ambient(sid, `-lay${last}`, BREATHE)
-    ].join("\n")
+      ambient(sid, `-lay${last}`, BREATHE),
+      // Absent unless the beat asked for it, so a flat stack emits the bytes it
+      // always did.
+      // `.stackwrap` and not the scene: the slabs lean, the headline does not.
+      p.tilt ? depthCss(sid, { ...DEFAULT_POSE, rotateX: p.tilt }, ".stackwrap") : ""
+    ].filter(Boolean).join("\n")
   };
 };
 
@@ -4815,6 +5040,7 @@ var emitters = {
   stack,
   "split-compare": splitCompare,
   "equation-walk": equationWalk,
+  "equation-morph": equationMorph,
   "line-chart": lineChart,
   // The ones that describe.
   title,
@@ -5007,6 +5233,7 @@ function round4(n3) {
 // src/emit/composition.ts
 var GSAP_SRC = "./vendor/gsap.min.js";
 var DRAWSVG_SRC = "./vendor/DrawSVGPlugin.min.js";
+var MORPH_SRC = "./vendor/ds-morph.js";
 var KATEX_JS = "./vendor/katex.min.js";
 var KATEX_CSS = "./katex/katex.min.css";
 function emitDeck(storyboard, source, format, runtimeJs, opts = {}) {
@@ -5097,6 +5324,7 @@ function layout(storyboard, source, format, opts = {}) {
   });
   let start = 0;
   let builds = false;
+  const plugins = /* @__PURE__ */ new Set();
   cuts.forEach((cut2, i) => {
     const { beat, sid, dive, inside, duration } = cut2;
     if (cut2.segments?.length) spoken[sid] = cut2.segments;
@@ -5111,6 +5339,7 @@ function layout(storyboard, source, format, opts = {}) {
     }
     if (scene.css) archetypeCss.add(scene.css.trim());
     if (scene.measure?.length) builds = true;
+    for (const p of scene.plugins ?? []) plugins.add(p);
     scenes.push(
       sceneHtml(
         sid,
@@ -5142,7 +5371,8 @@ function layout(storyboard, source, format, opts = {}) {
     spoken,
     total: start,
     cut,
-    builds
+    builds,
+    plugins
   };
 }
 function enteredParts(beats) {
@@ -5223,6 +5453,9 @@ function renderComposition(storyboard, format, laid) {
     <link rel="stylesheet" href="${FONT_BUNDLE_HREF}" />` : "";
   const island = format.navigable ? `
 ${emitIsland(slides)}` : "";
+  const morph = laid.plugins.has("dsMorph") ? `
+    <script src="${MORPH_SRC}"></script>
+    <script>gsap.registerPlugin(DSMorphPlugin);</script>` : "";
   return `<!doctype html>
 <html lang="${esc(storyboard.lang)}" data-resolution="${orientation}">
   <head>
@@ -5231,7 +5464,7 @@ ${emitIsland(slides)}` : "";
     <meta name="viewport" content="width=${format.width}, height=${format.height}" />
     <script src="${GSAP_SRC}"></script>
     <script src="${DRAWSVG_SRC}"></script>
-    <script>gsap.registerPlugin(DrawSVGPlugin);</script>
+    <script>gsap.registerPlugin(DrawSVGPlugin);</script>${morph}
     <link rel="stylesheet" href="${KATEX_CSS}" />
     <script src="${KATEX_JS}"></script>${fontLink}${fontFace}
     <style>
@@ -5942,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;
@@ -6138,6 +6382,7 @@ var REVEALS = {
   title: "1",
   "claim-figure": "2",
   "equation-walk": "one per term",
+  "equation-morph": "2",
   "data-table": "one per highlighted row, plus 1",
   "line-chart": "1",
   callout: "one per panel",
@@ -6169,9 +6414,9 @@ A beat is one idea, one visual, one hold. It carries:
              beat immediately before it. See RULE 11. Leave it off unless the
              source itself puts one inside the other.
 
-THE TWELVE ARCHETYPES
+THE THIRTEEN ARCHETYPES
 
-Eight of them DRAW: they build a vector graphic out of the source's own content
+Nine of them DRAW: they build a vector graphic out of the source's own content
 and reveal it stage by stage, so the viewer watches the idea assemble. Four only
 describe. The drawing ones are the default. The describing ones are what you
 fall back to when a point genuinely has no shape.
@@ -6249,6 +6494,14 @@ DRAWING ARCHETYPES \u2014 reach here first
                  An equation quoted to back a claim someone else is making is
                  evidence under another archetype, not a beat of its own.
 
+  equation-morph One equation becoming the next, the shared terms carried
+                 across. The tell: THE SOURCE DERIVES ONE LINE FROM ANOTHER \u2014 a
+                 substitution, a rearrangement, a special case \u2014 and the point
+                 is what moved. \`fromId\` and \`toId\` name two equations from
+                 the inventory. Each terms[].tex must appear verbatim in BOTH,
+                 and travels as one piece; a term in only one of them is
+                 dropped. Four terms maximum.
+
   line-chart     A trend the source states numerically but does not plot. The
                  tell: A QUANTITY MOVING ALONG AN ORDERED AXIS \u2014 over length, over
                  scale, over training. Points come from the source's numbers;
@@ -6522,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 `
 
@@ -6550,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 ? "" : `
@@ -6647,7 +6940,8 @@ function renderSource(source) {
   out.push("", "== EQUATIONS ==");
   for (const e of source.equations)
     out.push(`[equation ${e.id}] ${e.display ? "display" : "inline"} \u2014 ${e.tex}`);
-  if (!source.equations.length) out.push("(none \u2014 no equation-walk beat is possible)");
+  if (!source.equations.length)
+    out.push("(none \u2014 no equation-walk or equation-morph beat is possible)");
   out.push("", "== TABLES ==");
   for (const t2 of source.tables) {
     out.push(`[table ${t2.id}] ${t2.caption ?? "(no caption)"}`);
@@ -6719,6 +7013,10 @@ function assertRefsResolve(storyboard, source, opts = {}) {
       case "equation-walk":
         check3(beat, "equation", beat.params.equationId, "params.equationId");
         break;
+      case "equation-morph":
+        check3(beat, "equation", beat.params.fromId, "params.fromId");
+        check3(beat, "equation", beat.params.toId, "params.toId");
+        break;
       case "data-table": {
         check3(beat, "table", beat.params.tableId, "params.tableId");
         const table = source.tables.find((t2) => t2.id === beat.params.tableId);
@@ -6813,14 +7111,45 @@ function stripNulls(node) {
   }
   return out;
 }
-var SCHEMA = forStructuredOutput(z2.toJSONSchema(storyboardSchema, { io: "input" }));
+var PLANNER_INVISIBLE = /* @__PURE__ */ new Set(["tilt"]);
+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 = {};
+  for (const [key, value] of Object.entries(src)) {
+    if (key === "properties" && value && typeof value === "object") {
+      const kept = {};
+      for (const [prop, sub] of Object.entries(value))
+        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" || !hidden.has(r));
+      continue;
+    }
+    out[key] = hideFromPlanner(value, hidden);
+  }
+  return out;
+}
+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,
@@ -7943,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");
 }
@@ -8738,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);
@@ -9588,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."
   ),
@@ -9619,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);