slidemind 0.3.20 → 0.4.1

package/src/builders/stack.mjs

@@ -0,0 +1,413 @@
+// A STACK the reader declares (`spec.stacks`, concept-stacks.ts): rows of one
+// structure repeated down a container — an icon disc, its text and the divider
+// under them, four times; steps along a timeline — each row listed as the ids
+// of its parts, with how a row's parts sit on the row's axis (`align`) and how
+// the rows are spaced (`spacing`: even gaps, or the gaps as drawn). Code builds
+// exactly that and nothing more: a row is laid out from its parts' CURRENT
+// sizes (a text's measured height), the rows are placed in the band the stack
+// owns inside its parent (what lies above and below the whole stack bounds it,
+// recorded once from the painting), and a divider listed with a row moves
+// with that row. Nothing here decides that a structure is a stack or that a
+// part is centred; a stack the reader did not declare changes nothing. This
+// replaced seating each row "middle" against the whole card (x101: four rows
+// collapsed onto the card's centre, their dividers through the text).
+import { translateElement } from "./concept-geometry.mjs";
+import { linePoints, linesWithin, moveLine, fixCopies, translateFigure } from "./repeat-groups.mjs";
+
+const half = (v) => Math.round(v * 2) / 2;
+const isText = (e) => (e.kind === "text" || e.kind === "number") && e.text != null;
+
+const horizontal = (c) => {
+  const pts = linePoints(c);
+  if (pts.length < 2) return null;
+  const ys = pts.map((p) => p.y);
+  if (Math.max(...ys) - Math.min(...ys) > 2) return null;
+  return { y: (Math.min(...ys) + Math.max(...ys)) / 2, x0: Math.min(...pts.map((p) => p.x)), x1: Math.max(...pts.map((p) => p.x)) };
+};
+
+/**
+ * Point the stack's rows at what survived normalization (a text block's lines
+ * folded into one element, a label into its shape, a rule into its line); a
+ * stack whose row lost every part is dropped with a note. `before`: the
+ * elements by id before normalization.
+ */
+export function remapStacks(spec, before) {
+  if (!spec.stacks?.length) return [];
+  const byId = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  const lines = new Set((spec.connectors ?? []).map((c) => c.id).filter(Boolean));
+  const into = new Map();
+  for (const e of spec.elements ?? []) for (const p of e.paragraphs ?? []) if (p.id && p.id !== e.id) into.set(p.id, e.id);
+  const resolve = (id) => {
+    if (byId.has(id) || lines.has(id)) return id;
+    if (into.has(id)) return into.get(id);
+    const old = before.get(id);
+    const words = String(old?.text ?? "").trim();
+    const p = old?.parent ? byId.get(old.parent) : null;
+    return words && p && String(p.text ?? "").includes(words) ? p.id : null;
+  };
+  const notes = [];
+  spec.stacks = spec.stacks.flatMap((g) => {
+    const rows = g.rows.map((row) => [...new Set(row.map(resolve).filter(Boolean))]);
+    if (rows.some((r) => !r.length)) {
+      notes.push(`${g.id}: a row did not survive normalization — kept as drawn`);
+      return [];
+    }
+    // A part in two rows (a text block folded across them) is no row's part.
+    if (new Set(rows.flat()).size < rows.flat().length) {
+      notes.push(`${g.id}: a part belongs to two of its rows after normalization — kept as drawn`);
+      return [];
+    }
+    return [{ ...g, rows, parent: g.parent && byId.has(g.parent) ? g.parent : null }];
+  });
+  return notes;
+}
+
+// The parts of a row, as elements and as lines.
+function partsOf(spec, row) {
+  const byId = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  const byLine = new Map((spec.connectors ?? []).filter((c) => c.id).map((c) => [c.id, c]));
+  return { elements: row.map((id) => byId.get(id)).filter(Boolean), lines: row.map((id) => byLine.get(id)).filter(Boolean) };
+}
+
+// A row's current extent along y, elements by `at`, lines by their points.
+export function rowExtent(spec, row, at) {
+  const { elements, lines } = partsOf(spec, row);
+  const ys = [
+    ...elements.flatMap((e) => { const r = { ...e, ...at(e) }; return [r.y, r.y + r.h]; }),
+    ...lines.flatMap((c) => linePoints(c).map((p) => p.y)),
+  ];
+  return ys.length ? { top: Math.min(...ys), bottom: Math.max(...ys) } : null;
+}
+
+/**
+ * A block may not span the rows of a declared stack: the row is the finer
+ * structure, and a text block folding a title with the bodies of three rows
+ * would make one element of three rows (x105 QBR 4: the reader declared both).
+ * The texts of such a block keep their block only within one row; a text in
+ * no row (the title over the rows) keeps nothing to fold with. Runs before
+ * the folds. Returns the ids unblocked.
+ */
+export function unblockStackRows(spec) {
+  const rowOf = new Map();
+  for (const g of spec.stacks ?? []) g.rows.forEach((row, i) => { for (const id of row) rowOf.set(id, `${g.id}:${i}`); });
+  if (!rowOf.size) return [];
+  const blocks = new Map();
+  for (const e of spec.elements ?? []) if (e.block) blocks.set(e.block, [...(blocks.get(e.block) ?? []), e]);
+  const out = [];
+  for (const members of blocks.values()) {
+    const rows = new Set(members.map((e) => rowOf.get(e.id)).filter(Boolean));
+    if (rows.size < 2 && !(rows.size === 1 && members.some((e) => !rowOf.has(e.id)))) continue;
+    for (const e of members) { delete e.block; out.push(e.id); }
+  }
+  return out;
+}
+
+/**
+ * What bounds the stack in its parent, read once from the painting: the
+ * siblings (not parts of the stack) that lie wholly above or below it in its
+ * columns, and the dividers inside the parent that are no row's part. Stored
+ * on the stack as `band`; measured from where those are NOW at every pass.
+ */
+export function recordStackBand(spec, g) {
+  const els = spec.elements ?? [];
+  const byId = new Map(els.map((e) => [e.id, e]));
+  const parts = new Set(g.rows.flat());
+  const p = g.parent ? byId.get(g.parent) : null;
+  const rows = g.rows.map((r) => rowExtent(spec, r, (o) => o)).filter(Boolean);
+  if (!rows.length) return null;
+  const top = Math.min(...rows.map((r) => r.top));
+  const bottom = Math.max(...rows.map((r) => r.bottom));
+  const members = g.rows.flat().map((id) => byId.get(id)).filter(Boolean);
+  const x0 = Math.min(...members.map((e) => e.x));
+  const x1 = Math.max(...members.map((e) => e.x + e.w));
+  const spans = (o) => o.x < x1 && x0 < o.x + o.w;
+  const sibs = els.filter((o) => !parts.has(o.id) && o.w > 0 && o.h > 0 && o.kind !== "rule" && (p ? o.parent === p.id : !o.parent) && o !== p);
+  // A rule between two paragraphs of one block is that block's (block-dividers.mjs), never a gap's.
+  const blockDividers = new Set(els.flatMap((e) => (e.dividers ?? []).map((d) => d.id)));
+  const seps = (p ? linesWithin(spec, p) : spec.connectors ?? []).filter((c) => c.id && !parts.has(c.id) && !blockDividers.has(c.id)).map((c) => ({ c, l: horizontal(c) })).filter((x) => x.l && x.l.x0 < x1 && x0 < x.l.x1);
+  const band = {
+    before: sibs.filter((o) => o.y + o.h <= top + 0.5 && spans(o)).map((o) => o.id),
+    after: sibs.filter((o) => o.y >= bottom - 0.5 && spans(o)).map((o) => o.id),
+    sepBefore: seps.filter((x) => x.l.y <= top + 0.5).sort((a, b) => b.l.y - a.l.y)[0]?.c.id ?? null,
+    sepAfter: seps.filter((x) => x.l.y >= bottom - 0.5).sort((a, b) => a.l.y - b.l.y)[0]?.c.id ?? null,
+    // The drawn gaps between rows (spacing "drawn") …
+    gaps: rows.slice(1).map((r, i) => r.top - rows[i].bottom),
+    lead: 0,
+    // … and each listed divider's drawn distance under its row's content, kept
+    // at every pass (a text that grew over its divider pushes it down).
+    lines: Object.fromEntries(g.rows.flatMap((row) => {
+      const { elements, lines } = partsOf(spec, row);
+      if (!elements.length) return [];
+      const bottom = Math.max(...elements.map((e) => e.y + e.h));
+      return lines.map((c) => { const ys = linePoints(c).map((p) => p.y); return [c.id, { lo: Math.min(...ys) - bottom, hi: Math.max(...ys) - bottom }]; });
+    })),
+  };
+  // … and the first row's drawn offset from the band's top.
+  band.lead = top - stackBand(spec, { ...g, band }).top;
+  // What is drawn BETWEEN two rows (a divider, a down-arrow) and listed with
+  // no row belongs to that gap: the rows the reader declared define the gap,
+  // and an element of the same parent lying inside it, across the stack's
+  // columns, is in it by containment — the same fact as `parent`, no symmetry
+  // read into it. It rides with its gap, at its drawn fraction of it (a
+  // divider in the middle of the gap stays in the middle).
+  const inGap = (y0, y1) => rows.findIndex((r, i) => i < rows.length - 1 && y0 >= r.bottom - 0.5 && y1 <= rows[i + 1].top + 0.5);
+  const frac = (i, y0, y1) => { const a = rows[i].bottom, b = rows[i + 1].top; return b > a ? ((y0 + y1) / 2 - a) / (b - a) : 0.5; };
+  band.between = [
+    ...sibs.filter((o) => spans(o)).map((o) => ({ o, i: inGap(o.y, o.y + o.h) })).filter((x) => x.i >= 0).map((x) => ({ id: x.o.id, line: false, gap: x.i, frac: frac(x.i, x.o.y, x.o.y + x.o.h) })),
+    ...(p ? linesWithin(spec, p) : spec.connectors ?? []).filter((c) => c.id && !parts.has(c.id) && !blockDividers.has(c.id)).map((c) => {
+      const pts = linePoints(c);
+      const xs = pts.map((q) => q.x), ys = pts.map((q) => q.y);
+      if (!pts.length || !(Math.min(...xs) < x1 && x0 < Math.max(...xs))) return null;
+      const i = inGap(Math.min(...ys), Math.max(...ys));
+      return i >= 0 ? { id: c.id, line: true, gap: i, frac: frac(i, Math.min(...ys), Math.max(...ys)) } : null;
+    }).filter(Boolean),
+  ];
+  return band;
+}
+
+/** The band the stack owns now: its parent's box cut by what lies beyond the stack. */
+export function stackBand(spec, g, at = (o) => o) {
+  const byId = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  const p = g.parent ? byId.get(g.parent) : null;
+  const slot = spec.slot;
+  let lo = p ? p.y : 0;
+  let hi = p ? p.y + p.h : slot.h;
+  const b = g.band;
+  if (!b) return { top: lo, bottom: hi };
+  const rect = (o) => ({ y: o.y, h: o.h, ...at(o) });
+  for (const id of b.before ?? []) { const o = byId.get(id); if (o) lo = Math.max(lo, rect(o).y + rect(o).h); }
+  for (const id of b.after ?? []) { const o = byId.get(id); if (o) hi = Math.min(hi, rect(o).y); }
+  const line = (id) => (id == null ? null : (spec.connectors ?? []).find((c) => c.id === id) ?? null);
+  const la = line(b.sepBefore) ? horizontal(line(b.sepBefore)) : null;
+  const lb = line(b.sepAfter) ? horizontal(line(b.sepAfter)) : null;
+  if (la) lo = Math.max(lo, la.y);
+  if (lb) hi = Math.min(hi, lb.y);
+  return hi - lo > 1 ? { top: lo, bottom: hi } : { top: p ? p.y : 0, bottom: p ? p.y + p.h : slot.h };
+}
+
+/**
+ * Build every declared stack: rows placed in the stack's band — equal gaps and
+ * margins (`even`), or the drawn lead and gaps (`drawn`) — each row's parts set
+ * on the row's axis by `align` (a line listed with a row moves with it, never
+ * re-aligned). `at(o)` gives a text's measured rect; `move(o, dy)` moves one
+ * element (the caller's, so a settle pass records the shift). Returns one
+ * line per row moved.
+ */
+export function applyStacks(spec, { at = (o) => o, move = null } = {}) {
+  const els = spec.elements ?? [];
+  const byId = new Map(els.map((e) => [e.id, e]));
+  const figures = new Set((spec.sketch?.figures ?? []).map((f) => f.id));
+  const deltas = new Map();
+  const movedCircles = new Set();
+  const kids = (id) => els.filter((o) => o.parent === id);
+  let moved = 0;
+  const shift = (e, dy) => {
+    if (!dy) return;
+    moved++;
+    if (move) move(e, dy);
+    else translateElement(e, 0, dy);
+    if (figures.has(e.id)) translateFigure(spec.sketch, e.id, 0, dy, deltas, movedCircles);
+    for (const k of kids(e.id)) shift(k, dy);
+  };
+  const changes = [];
+  // A declared grid: its member stacks' rows line up, row by row, in one
+  // shared layout (row i as tall as the tallest row i across the members, the
+  // first member's band and spacing); a divider drawn across the columns in a
+  // shared gap is placed once, at its drawn fraction of that gap.
+  const shared = new Map(); // stack id → [{ top, h }] from its grid
+  for (const grid of spec.grids ?? []) {
+    const members = gridStacks(spec, grid);
+    if (members.length < 2) continue;
+    const plans = members.map((g) => ({ g, rows: rowPlans(spec, g, at) })).filter((p) => p.rows && p.rows.length === grid.rows);
+    if (plans.length !== members.length) { changes.push(`${grid.id}: its columns do not all hold ${grid.rows} rows; laid out column by column`); continue; }
+    for (const p of plans) p.g.band ??= recordStackBand(spec, p.g);
+    // A member's own dividers lie in the GRID's gaps: their fraction is of the
+    // shared gap (the rows' union across the columns), so the same divider in
+    // every column lands on the same boundary. Recorded once, like the band.
+    const union = Array.from({ length: grid.rows }, (_, i) => ({ top: Math.min(...plans.map((p) => p.rows[i].ext.top)), bottom: Math.max(...plans.map((p) => p.rows[i].ext.bottom)) }));
+    for (const p of plans) {
+      if (p.g.band.gridFracs) continue;
+      for (const it of p.g.band.between ?? []) {
+        const c = it.line ? (spec.connectors ?? []).find((x) => x.id === it.id) : null;
+        const e = it.line ? null : byId.get(it.id);
+        const y = c ? (() => { const ys = linePoints(c).map((q) => q.y); return (Math.min(...ys) + Math.max(...ys)) / 2; })() : e ? e.y + e.h / 2 : null;
+        const a = union[it.gap]?.bottom, b = union[it.gap + 1]?.top;
+        if (y != null && a != null && b != null && b > a) it.frac = Math.min(1, Math.max(0, (y - a) / (b - a)));
+      }
+      p.g.band.gridFracs = true;
+    }
+    const lead = plans[0].g;
+    const band = stackBand(spec, lead, at);
+    const heights = Array.from({ length: grid.rows }, (_, i) => Math.max(...plans.map((p) => p.rows[i].ext.bottom - p.rows[i].ext.top)));
+    const total = heights.reduce((a, b) => a + b, 0);
+    const len = band.bottom - band.top;
+    const even = lead.spacing !== "drawn";
+    const gaps = even ? heights.map(() => (len - total) / (heights.length + 1)) : [lead.band.lead, ...lead.band.gaps];
+    if (even && gaps[0] < 0) { changes.push(`${grid.id}: its rows need ${Math.ceil(total - len)}px more than its columns hold; laid out column by column`); continue; }
+    const tops = [];
+    let top = band.top;
+    heights.forEach((h, i) => { top += gaps[i] ?? 0; tops.push({ top: half(top), h }); top += h; });
+    for (const p of plans) shared.set(p.g.id, tops);
+    grid.band ??= recordGridBand(spec, grid, members);
+    grid.placed = tops.map((t) => [t.top, t.top + t.h]);
+  }
+  for (const g of spec.stacks ?? []) {
+    if (new Set(g.rows.flat()).size < g.rows.flat().length) continue;
+    g.band ??= recordStackBand(spec, g);
+    if (!g.band) continue;
+    const band = stackBand(spec, g, at);
+    // A row: its elements (the content set on the row's axis) and its lines (a
+    // divider drawn under the content, which keeps that distance to the
+    // content's bottom — so it follows a text that grew).
+    const rows = g.rows.map((row) => {
+      const parts = partsOf(spec, row);
+      const rects = parts.elements.map((e) => ({ ...e, ...at(e) }));
+      if (!rects.length && !parts.lines.length) return null;
+      const content = rects.length
+        ? { top: Math.min(...rects.map((r) => r.y)), bottom: Math.max(...rects.map((r) => r.y + r.h)) }
+        : { top: Math.min(...parts.lines.flatMap((c) => linePoints(c).map((p) => p.y))), bottom: Math.max(...parts.lines.flatMap((c) => linePoints(c).map((p) => p.y))) };
+      const lineOff = parts.lines.map((c) => { const ys = linePoints(c).map((p) => p.y); const drawn = g.band.lines?.[c.id]; return { c, lo: drawn?.lo ?? Math.min(...ys) - content.bottom, hi: drawn?.hi ?? Math.max(...ys) - content.bottom }; });
+      const top = Math.min(content.top, ...lineOff.map((l) => content.bottom + l.lo));
+      const bottom = Math.max(content.bottom, ...lineOff.map((l) => content.bottom + l.hi));
+      return { ...parts, rects, content, lineOff, ext: { top, bottom }, contentOff: content.top - top };
+    }).filter(Boolean);
+    if (rows.length < 2) continue;
+    const heights = rows.map((r) => r.ext.bottom - r.ext.top);
+    const total = heights.reduce((a, b) => a + b, 0);
+    const len = band.bottom - band.top;
+    const even = g.spacing !== "drawn";
+    const gaps = even ? rows.map(() => (len - total) / (rows.length + 1)) : [g.band.lead, ...g.band.gaps];
+    if (even && gaps[0] < 0) { changes.push(`${g.id}: its rows need ${Math.ceil(total - len)}px more than ${g.parent ?? "the slide"} holds; left as drawn`); continue; }
+    let top = band.top;
+    const placed = []; // each row's [top, bottom] after this pass
+    const fixed = shared.get(g.id) ?? null;
+    rows.forEach((r, i) => {
+      top += gaps[i] ?? 0;
+      const rowTop = fixed ? fixed[i].top : half(top);
+      const rowH = fixed ? fixed[i].h : heights[i];
+      // In a grid row taller than this member's own content, the content sits
+      // by the stack's `align` within the shared row.
+      const slack = rowH - heights[i];
+      const contentTop = rowTop + r.contentOff + (g.align === "bottom" ? slack : g.align === "top" ? 0 : slack / 2);
+      const contentH = r.content.bottom - r.content.top;
+      const before = moved;
+      // A row's parts sit in COLUMNS (the icon; the title over its body): parts
+      // overlapping in x form one column, stacked as drawn; the column block is
+      // what `align` sets on the row's axis, never each part alone (x102 GTM 3:
+      // a title and its body both "middle" would land on one line).
+      // A part inside another part of the row (the icon on its disc) rides with
+      // it: moving both would move it twice.
+      const partIds = new Set(r.elements.map((e) => e.id));
+      const own = r.elements.filter((e) => !(e.parent && partIds.has(e.parent)));
+      const columns = [];
+      for (const e of [...own].sort((a, b) => a.y - b.y)) {
+        const hit = columns.find((col) => col.some((o) => o.x < e.x + e.w && e.x < o.x + o.w));
+        if (hit) hit.push(e); else columns.push([e]);
+      }
+      for (const col of columns) {
+        const rects = col.map((e) => ({ e, ...at(e) }));
+        const top0 = Math.min(...rects.map((q) => q.y));
+        const gapsIn = rects.slice(1).map((q, k) => q.y - (rects[k].y + rects[k].h));
+        const blockH = rects.reduce((n, q) => n + q.h, 0) + gapsIn.reduce((n, v) => n + v, 0);
+        const want = g.align === "top" ? contentTop : g.align === "bottom" ? contentTop + contentH - blockH : contentTop + (contentH - blockH) / 2;
+        let y = want;
+        rects.forEach((q, k) => {
+          shift(q.e, half(y - q.y));
+          y += q.h + (gapsIn[k] ?? 0);
+        });
+        void top0;
+      }
+      for (const { c, lo } of r.lineOff) {
+        const was = Math.min(...linePoints(c).map((p) => p.y));
+        const dy = half(contentTop + contentH + lo - was);
+        if (dy) { moveLine(c, 0, dy); moved++; }
+      }
+      const dyRow = half(rowTop - r.ext.top);
+      if (moved > before) changes.push(`${g.id}: row ${i + 1} ${dyRow >= 0 ? "+" : ""}${dyRow}px, its parts ${g.align === "top" ? "on its top" : g.align === "bottom" ? "on its bottom" : "on its axis"}`);
+      placed.push([rowTop, rowTop + rowH]);
+      top += rowH;
+    });
+    // What is drawn in a gap rides with it, at its drawn fraction of the gap.
+    placeBetween(g, placed);
+  }
+  // A grid's own dividers — drawn across its columns in a shared gap — once.
+  for (const grid of spec.grids ?? []) if (grid.placed && grid.band) placeBetween(grid, grid.placed);
+  fixCopies(spec.sketch, deltas);
+  return changes;
+
+  function placeBetween(owner, placed) {
+    for (const it of owner.band.between ?? []) {
+      const a = placed[it.gap]?.[1], b = placed[it.gap + 1]?.[0];
+      if (a == null || b == null) continue;
+      const want = a + (b - a) * it.frac;
+      if (it.line) {
+        const c = (spec.connectors ?? []).find((x) => x.id === it.id);
+        if (!c) continue;
+        const ys = linePoints(c).map((q) => q.y);
+        const dy = half(want - (Math.min(...ys) + Math.max(...ys)) / 2);
+        if (dy) { moveLine(c, 0, dy); moved++; changes.push(`${owner.id}: ${it.id} ${dy >= 0 ? "+" : ""}${dy}px with its gap`); }
+      } else {
+        const e = byId.get(it.id);
+        if (!e) continue;
+        const cur = { ...e, ...at(e) };
+        const dy = half(want - (cur.y + cur.h / 2));
+        if (dy) { shift(e, dy); changes.push(`${owner.id}: ${it.id} ${dy >= 0 ? "+" : ""}${dy}px with its gap`); }
+      }
+    }
+  }
+}
+
+// The rows of a stack as applyStacks reads them (extents on the current sizes), or null.
+function rowPlans(spec, g, at) {
+  const rows = g.rows.map((row) => rowExtent(spec, row, at) && { ext: rowExtent(spec, row, at) }).filter(Boolean);
+  return rows.length >= 2 ? rows : null;
+}
+
+/** The member stacks of a grid, in column order: by stack id (a repaired slide's marks) or by the column's card. */
+export function gridStacks(spec, grid) {
+  const stacks = spec.stacks ?? [];
+  if (grid.stacks?.length) return grid.stacks.map((id) => stacks.find((g) => g.id === id)).filter(Boolean);
+  return (grid.columns ?? []).map((col) => stacks.find((g) => g.parent === col) ?? stacks.find((g) => g.rows.flat().includes(col))).filter(Boolean);
+}
+
+/**
+ * What is drawn across a grid's columns between two of its rows (a divider
+ * running through every column), recorded once from the painting: lines
+ * spanning two or more member columns whose y lies between the rows' shared
+ * extents, with their drawn fraction of that gap.
+ */
+export function recordGridBand(spec, grid, members) {
+  const byId = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  const parts = new Set(members.flatMap((g) => g.rows.flat()));
+  const own = new Set(members.flatMap((g) => (g.band?.between ?? []).map((it) => it.id)));
+  const cols = members.map((g) => { const es = g.rows.flat().map((id) => byId.get(id)).filter(Boolean); return { x0: Math.min(...es.map((e) => e.x)), x1: Math.max(...es.map((e) => e.x + e.w)) }; });
+  const rows = Array.from({ length: grid.rows }, (_, i) => {
+    const exts = members.map((g) => rowExtent(spec, g.rows[i], (o) => o)).filter(Boolean);
+    return { top: Math.min(...exts.map((r) => r.top)), bottom: Math.max(...exts.map((r) => r.bottom)) };
+  });
+  const between = [];
+  for (const c of spec.connectors ?? []) {
+    if (!c.id || parts.has(c.id) || own.has(c.id)) continue;
+    const h = horizontal(c);
+    if (!h || cols.filter((col) => h.x0 < col.x1 && col.x0 < h.x1).length < 2) continue;
+    const i = rows.findIndex((r, k) => k < rows.length - 1 && h.y >= r.bottom - 0.5 && h.y <= rows[k + 1].top + 0.5);
+    if (i < 0) continue;
+    const a = rows[i].bottom, b = rows[i + 1].top;
+    between.push({ id: c.id, line: true, gap: i, frac: b > a ? (h.y - a) / (b - a) : 0.5 });
+  }
+  return { between };
+}
+
+/** Point a grid's columns at what survived normalization; a grid short of two columns is dropped with a note. */
+export function remapGrids(spec, before) {
+  if (!spec.grids?.length) return [];
+  const notes = [];
+  const byId = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  spec.grids = spec.grids.flatMap((grid) => {
+    const columns = (grid.columns ?? []).filter((id) => byId.has(id));
+    if (!grid.stacks?.length && columns.length < 2) { notes.push(`${grid.id}: fewer than two of its columns survived normalization — laid out column by column`); return []; }
+    return [{ ...grid, columns }];
+  });
+  void before;
+  return notes;
+}

package/src/builders/storyboard-markdown.mjs

@@ -1,11 +1,11 @@
 // Storyboard-markdown: segment a plan.md into alternating markdown / storyboard
 // runs, splice an edited storyboard fence back in, and pull the red-thread beats
-// out of the `## Red thread` section. Ported 1:1 from the add-in's
-// src/ui/src/pages/plan-review/storyboard-markdown.ts (TS types dropped; regexes
-// and control flow identical). Ships into the plan gate's browser bundle in one
-// shared IIFE with storyboard-schema and the other plan modules, so module-scope
-// helpers use an `sm` prefix to stay collision-free; exported names match the
-// add-in exactly. The import below is a single line on purpose — the browser
+// out of the `## Red thread` section. Canonical here: the add-in's plan review
+// and runtime import a byte-identical mirror (scripts/sync-transcription-runtime.mjs),
+// typed by src/ui/src/pages/plan-review/storyboard-markdown.ts. Ships into the
+// plan gate's browser bundle in one shared IIFE with storyboard-schema and the
+// other plan modules, so module-scope helpers use an `sm` prefix to stay
+// collision-free. The import below is a single line on purpose — the browser
 // bundler strips lines matching `import … from "…";`.
 import { parseStoryboardCanvas, serializeStoryboardCanvas, STORYBOARD_CANVAS_LANG } from "./storyboard-schema.mjs";
 
@@ -30,8 +30,30 @@ function smCleanRedThreadLine(line) {
     .trim();
 }
 
+/**
+ * The authoring contract ends the red thread with one `Frame: cover · closing`
+ * (or `Frame: none`) line naming the frame slides. It is a declaration ABOUT the
+ * deck, not a move in it, and reading it as one did real damage: it minted a
+ * phantom "Frame: none" rail card, and it pushed the move count past the
+ * `### Slide N` count, which is the exact condition that turns the whole
+ * backbone read-only — no insert, no reorder, no rename.
+ */
+const SM_FRAME_LINE_RE = /^Frame\s*:/i;
+
+/** The plan's `Frame:` declaration, verbatim, or null when it carries none. */
+export function extractFrameLine(markdown) {
+  const section = findRedThreadSection(markdown);
+  if (!section) return null;
+  for (const raw of markdown.slice(section.bodyStart, section.bodyEnd).split("\n")) {
+    const line = smCleanRedThreadLine(raw);
+    if (line && SM_FRAME_LINE_RE.test(line)) return line;
+  }
+  return null;
+}
+
 function smSplitRedThreadBody(body) {
-  const lines = body.split("\n").map(smCleanRedThreadLine).filter(Boolean);
+  const lines = body.split("\n").map(smCleanRedThreadLine).filter(Boolean)
+    .filter((line) => !SM_FRAME_LINE_RE.test(line));
   if (lines.length !== 1) return lines;
   const [line] = lines;
   if (!line) return [];
@@ -87,6 +109,11 @@ export function splitPlanMarkdownIntoSegments(markdown) {
       data: parsed.data,
       error: parsed.error,
       warnings: parsed.warnings,
+      // The typed issues behind an `error`, when the fence failed on its image
+      // uses — `{code, assetId?, useId?, slide?, message, action}` from the
+      // image-intent contract. Absent on every other parse failure, so a
+      // consumer that ignores it reads exactly as before.
+      ...(parsed.issues ? { issues: parsed.issues } : {}),
       start: matchStart,
       end: matchEnd,
       lineOffset,
@@ -117,9 +144,11 @@ export function replaceStoryboardSegment(markdown, segment, nextData) {
   )}`;
 }
 
-// Deck-level layout knob: binds EVERY valid storyboard fence to `layout`.
-// Fences are spliced last-to-first so earlier offsets stay valid; malformed
-// fences are left untouched. Mirrors the add-in's setStoryboardLayoutForAll.
+// Deck-level layout knob: binds EVERY valid body storyboard fence to `layout`.
+// The user picked this in the review, so agent-side hints (`layoutSelection`,
+// canvas geometry) never veto it — only frames stay put. Fences are spliced
+// last-to-first so earlier offsets stay valid; malformed fences are left
+// untouched. Mirrors the add-in's setStoryboardLayoutForAll (b939ea372).
 export function setStoryboardLayoutForAll(markdown, layout, options = []) {
  let next = markdown;
  const target = options.find((option) => option.componentName === layout);
@@ -129,29 +158,43 @@ export function setStoryboardLayoutForAll(markdown, layout, options = []) {
  for (const segment of boards.reverse()) {
   if (segment.type !== "storyboard" || !segment.data) continue;
   const data = segment.data;
-  const current = options.find((option) => option.componentName === data.layout);
-  if (data.role === "frame" || data.layoutSelection === "explicit") continue;
-  if (!current || (!current.canvasBounds && !current.contentAreas?.length)) continue;
-  // Specialized geometries stay put. Bulk defaults change equivalent canvases only.
-  if (JSON.stringify(current.contentAreas ?? current.canvasBounds) !== JSON.stringify(target.contentAreas ?? target.canvasBounds)) continue;
-  if (data.layout === layout) continue;
+  if (data.role === "frame" || data.layout === layout) continue;
   next = replaceStoryboardSegment(next, segment, { ...data, role: "body", layout,
-   layoutKey: target.layoutKey, layoutSelection: "automatic", layoutReason: undefined });
+   layoutKey: target.layoutKey, layoutSelection: "explicit", layoutReason: undefined });
  }
  return next;
 }
 
-/** Change only verified counterparts; preserve explicit layout choices. */
-export function setStoryboardStyle(markdown, tone, options) {
+const SM_FRAME_JOBS = ["cover", "agenda", "divider", "closing", "quote"];
+const smHasCanvas = (option) => Boolean(option?.canvasBounds || option?.contentAreas?.length);
+
+// CLI-only (the plan gate's design picker): move every storyboard whose layout
+// the design in `options` lacks onto that design's nearest equivalent. A frame
+// slide keeps its job (cover → the design's first cover layout); a body slide
+// takes the first content layout with as many content areas as its old one
+// (`previous` is the old design's option list), else the first content layout.
+// Options arrive ranked, so "first" is the design's own preference. Boards
+// whose layout the design has, or for which it offers nothing, stay as they are.
+export function remapStoryboardLayouts(markdown, options = [], previous = []) {
+ const names = new Set(options.map((option) => option.componentName));
+ const content = options.filter((option) => smHasCanvas(option) && (option.job ?? "content") === "content");
  let next = markdown;
- for (const segment of splitPlanMarkdownIntoSegments(markdown).reverse()) {
-  if (segment.type !== "storyboard" || !segment.data || segment.data.layoutSelection === "explicit") continue;
-  const current = options.find((option) => option.componentName === segment.data.layout);
-  if (!current?.selection?.counterpartKey || current.selection.tone === tone) continue;
-  const targets = options.filter((option) => option.selection?.counterpartKey === current.selection.counterpartKey && option.selection?.tone === tone);
-  if (targets.length !== 1) continue;
-  next = replaceStoryboardSegment(next, segment, { ...segment.data, layout: targets[0].componentName,
-   layoutKey: targets[0].layoutKey, layoutSelection: "automatic", layoutReason: undefined });
+ const boards = splitPlanMarkdownIntoSegments(markdown).filter((segment) => segment.type === "storyboard" && segment.data);
+ for (const segment of boards.reverse()) {
+  const data = segment.data;
+  if (!data.layout || names.has(data.layout)) continue;
+  const old = previous.find((option) => option.componentName === data.layout) ?? null;
+  const job = data.role === "frame" ? data.frameKind : old?.job;
+  let target = null;
+  if (data.role === "frame" || SM_FRAME_JOBS.includes(job)) {
+   target = options.find((option) => option.job === job) ?? null;
+  } else {
+   const areas = old?.contentAreas?.length ?? 0;
+   target = (areas && content.find((option) => (option.contentAreas?.length ?? 0) === areas)) || content[0] || null;
+  }
+  if (!target) continue;
+  next = replaceStoryboardSegment(next, segment, { ...data, layout: target.componentName,
+   layoutKey: target.layoutKey, layoutSelection: "automatic", layoutReason: undefined });
  }
  return next;
 }