@jokerized/decksmith 0.2.0 → 0.3.0

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(),
@@ -320,6 +342,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 +405,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(),
@@ -3082,7 +3111,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 +3127,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 +3160,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 +3189,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 +3288,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 +3298,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,6 +4692,30 @@ 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;
@@ -4567,15 +4739,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 +4767,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 +4775,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 +4802,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 +4842,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 +4864,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 +4890,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,
@@ -4724,7 +4902,7 @@ 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" }
+      { 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 +4924,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 +4936,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 +4979,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 +4999,7 @@ var emitters = {
   stack,
   "split-compare": splitCompare,
   "equation-walk": equationWalk,
+  "equation-morph": equationMorph,
   "line-chart": lineChart,
   // The ones that describe.
   title,
@@ -5007,6 +5192,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 +5283,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 +5298,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 +5330,8 @@ function layout(storyboard, source, format, opts = {}) {
     spoken,
     total: start,
     cut,
-    builds
+    builds,
+    plugins
   };
 }
 function enteredParts(beats) {
@@ -5223,6 +5412,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 +5423,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>
@@ -6138,6 +6330,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 +6362,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 +6442,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;
@@ -6647,7 +6848,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 +6921,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,7 +7019,31 @@ function stripNulls(node) {
   }
   return out;
 }
-var SCHEMA = forStructuredOutput(z2.toJSONSchema(storyboardSchema, { io: "input" }));
+var PLANNER_INVISIBLE = /* @__PURE__ */ new Set(["tilt"]);
+function hideFromPlanner(node) {
+  if (Array.isArray(node)) return node.map(hideFromPlanner);
+  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 (!PLANNER_INVISIBLE.has(prop)) kept[prop] = hideFromPlanner(sub);
+      out.properties = kept;
+      continue;
+    }
+    if (key === "required" && Array.isArray(value)) {
+      out.required = value.filter((r) => typeof r !== "string" || !PLANNER_INVISIBLE.has(r));
+      continue;
+    }
+    out[key] = hideFromPlanner(value);
+  }
+  return out;
+}
+var SCHEMA = hideFromPlanner(
+  forStructuredOutput(z2.toJSONSchema(storyboardSchema, { io: "input" }))
+);
 async function codexPlanner(source, opts = {}) {
   const prefs = opts.prefs ?? prefsSchema.parse({});
   const dir = await mkdtemp(join3(tmpdir(), "decksmith-plan-"));

package/dist/types/emit/archetypes/equation-morph.d.ts

@@ -0,0 +1,2 @@
+import type { Emitter } from "../kit.js";
+export declare const equationMorph: Emitter<"equation-morph">;

package/dist/types/emit/archetypes/equation-walk.d.ts

@@ -1,2 +1,64 @@
-import type { Emitter } from "../kit.js";
+/**
+ * An equation, walked one symbol at a time.
+ *
+ * This is the most valuable thing the vocabulary does: the reader is never shown
+ * a wall of TeX and left to find the symbol being discussed. Each term is wrapped
+ * in `\htmlClass{term t-<tone>}{...}` so KaTeX emits a real element for it, which
+ * GSAP then tints and swells in step with its legend row.
+ */
+import type { Term } from "../../types.js";
+import type { Emitter, Theme } from "../kit.js";
+export declare const OPTS = "{ displayMode: true, trust: function (c) { return c.command === \"\\\\htmlClass\"; }, strict: false, output: \"html\" }";
+export declare const INLINE_OPTS = "{ displayMode: false, trust: function (c) { return c.command === \"\\\\htmlClass\"; }, strict: false, output: \"html\" }";
+/** Where `term` sits in `tex`, comparing normal forms. Null when it is absent. */
+export declare function locate(tex: string, term: string): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Wrap each term where it first occurs, and report which ones were wrapped.
+ *
+ * Segments are tracked as raw/wrapped so a later term cannot match inside an
+ * earlier term's `\htmlClass{...}` and produce nested markup that highlights the
+ * wrong span.
+ *
+ * A term that cannot be found is DROPPED rather than thrown on, and the caller
+ * drops its legend row with it — the two go together, which is what keeps this
+ * honest. Silently highlighting nothing is the failure this archetype exists to
+ * avoid, and a legend line pointing at an unhighlighted symbol is that failure;
+ * a shorter legend is not. Losing an entire deck to one mis-spelled term is a
+ * worse answer than either. If NOTHING matches, the beat has no work to do and
+ * that is still an error.
+ */
+export declare function wrapTerms(tex: string, terms: Term[], beatId: string, 
+/** The class the wrapper carries; the morph adds its key to the walk's tint. */
+cls?: (t: Term) => string): {
+    tex: string;
+    used: Term[];
+    missing: Term[];
+};
+/**
+ * Display equations want to live between 68px and 108px.
+ *
+ * The equation is the whole argument of this archetype and it was the smallest
+ * thing on the slide — 72px of TeX centred in a 1700px box, measured at 46% fill
+ * with a 1920x316 band under it. It is sized off the source length rather than
+ * off `textWidth` because TeX is not the string that gets set: `\mathcal{W}(F)`
+ * is fourteen characters and three glyphs.
+ *
+ * This is the *wanted* size, not the final one. The old comment here claimed
+ * "KaTeX's own `\displaystyle` box will shrink to the container if the estimate
+ * runs wide". It does not — it overflows, silently, because the composition is
+ * the size it says it is and no gate reads past the canvas edge. At 9:16 that
+ * truncated `X = \mathcal{W}(F)` to "X =" and then left the legend explaining a
+ * symbol the viewer could not see, which is worse than a clip: the slide
+ * asserted something false. `statements` and the `size` cap below are what make
+ * the claim true.
+ */
+export declare function equationSize(tex: string): number;
+/** Estimated rendered width of a display, in ems. */
+export declare function texUnits(tex: string): number;
+/** One row per term: a chip KaTeX fills in `setup`, and the label. Shared with the morph. */
+export declare function legendRows(sid: string, terms: Term[], theme: Theme): string;
+export declare function legendCss(theme: Theme): string;
 export declare const equationWalk: Emitter<"equation-walk">;

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

@@ -12,7 +12,7 @@ export declare const emitters: {
 };
 /**
  * Dispatch a beat to its emitter. The cast is the one place the pairing is taken
- * on trust: `emitters[beat.archetype]` is a union of twelve emitters and TypeScript
+ * on trust: `emitters[beat.archetype]` is a union of thirteen emitters and TypeScript
  * will not narrow the key and the beat together. The table above already proves
  * every archetype has exactly one emitter of the right shape.
  */

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

@@ -26,6 +26,13 @@ import type { Emitter } from "../kit.js";
 import { type Face } from "../svg.js";
 type Params = BeatOf<"stack">["params"];
 export interface StackLayout {
+    /**
+     * The type floor this layout solved against, which is `MIN_FONT` for a flat
+     * beat and larger for a tilted one. The emitter reads it back so the notes it
+     * draws are set at the same floor the solver reserved room for — they were
+     * pinned to `MIN_FONT` directly, which under a tilt drew them below it.
+     */
+    floor: number;
     /**
      * False when the rise the canvas allows is shorter than the tallest label
      * block — i.e. adjacent labels would overlap. `stackLayout` re-composes rather