slidemind 0.3.19 → 0.4.0

package/src/builders/concept-geometry.mjs

@@ -0,0 +1,370 @@
+// Explicit geometry, never inferred from a noisy polygon. Coordinates are in
+// slot pixels; angles are clockwise degrees from three o'clock.
+export function geometryPath(g) {
+  if (g?.type === 'spline') return splinePath(g.points, g.closed);
+  if (g?.type === 'path') return commandPath(g.commands);
+  if (!g || !['arc', 'sector'].includes(g.type)) return null;
+  const { cx, cy, rx, ry, start, sweep } = g;
+  // An open arc is a stroke: its hole ratio means nothing (the reader wrote 1
+  // on four ring arcs, x58 cloud 6, and the whole transcribe refused).
+  const innerRatio = g.type === 'arc' ? 0 : (g.innerRatio ?? 0);
+  if (![cx, cy, rx, ry, start, sweep, innerRatio].every(Number.isFinite) ||
+      rx <= 0 || ry <= 0 || sweep === 0 || Math.abs(sweep) > 360 ||
+      innerRatio < 0 || innerRatio >= 1) return null;
+  const n = (v) => String(Math.round(v * 1e6) / 1e6);
+  const point = (angle, ratio = 1) => {
+    const a = angle * Math.PI / 180;
+    return `${n(rx + rx * ratio * Math.cos(a))} ${n(ry + ry * ratio * Math.sin(a))}`;
+  };
+  // Split full circles (SVG's coincident-endpoint arc draws nothing) and use
+  // at most half-circle arcs for consistent preview/export interpretation.
+  const arc = (angle, extent, ratio) => {
+    const count = Math.ceil(Math.abs(extent) / 180);
+    return Array.from({ length: count }, (_, i) =>
+      `A ${n(rx * ratio)} ${n(ry * ratio)} 0 0 ${extent > 0 ? 1 : 0} ${point(angle + extent * (i + 1) / count, ratio)}`).join(' ');
+  };
+  let d = `M ${point(start)} ${arc(start, sweep, 1)}`;
+  if (g.type === 'sector') {
+    d += innerRatio > 0
+      ? ` L ${point(start + sweep, innerRatio)} ${arc(start + sweep, -sweep, innerRatio)} Z`
+      : ` L ${n(rx)} ${n(ry)} Z`;
+  }
+  return { x: cx - rx, y: cy - ry, w: rx * 2, h: ry * 2, d, extent: arcExtent(g) };
+}
+
+// The box an arc or sector covers: its outer rim, its inner rim (or centre),
+// sampled along the sweep.
+export function arcExtent(g) {
+  const { cx, cy, rx, ry, start, sweep } = g;
+  const inner = g.type === 'sector' ? (g.innerRatio ?? 0) : null;
+  const pts = [];
+  const steps = Math.max(8, Math.ceil(Math.abs(sweep) / 5));
+  for (let i = 0; i <= steps; i++) {
+    const a = (start + (sweep * i) / steps) * Math.PI / 180;
+    pts.push([cx + rx * Math.cos(a), cy + ry * Math.sin(a)]);
+    if (inner != null) pts.push([cx + rx * inner * Math.cos(a), cy + ry * inner * Math.sin(a)]);
+  }
+  const xs = pts.map((p) => p[0]), ys = pts.map((p) => p[1]);
+  return { x: Math.min(...xs), y: Math.min(...ys), w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys) };
+}
+
+const iou = (a, b) => {
+  const w = Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x));
+  const h = Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+  const i = w * h;
+  return i ? i / (a.w * a.h + b.w * b.h - i) : 0;
+};
+
+/**
+ * An arc's angles, reconciled with the box the reader measured around it.
+ * The reader's box and sweep size are reliable; its start angle and sweep
+ * direction are not (x61 QBR 6: a right-hand sector read with a sweep that
+ * drew it over the left one). When the angles draw somewhere the box does
+ * not, the start and direction that best cover the box win; the sweep size
+ * is kept. Returns the geometry to draw.
+ */
+export function reconcileArc(g, box) {
+  if (!g || !['arc', 'sector'].includes(g.type) || !(box?.w > 0 && box?.h > 0)) return g;
+  if (![g.cx, g.cy, g.rx, g.ry, g.start, g.sweep].every(Number.isFinite) || !g.sweep || Math.abs(g.sweep) >= 360) return g;
+  const fit = iou(arcExtent(g), box);
+  if (fit >= 0.8) return g;
+  let best = { g, fit };
+  // Rotated only, never reversed: an arc's direction says which end carries
+  // its head, and a reversed arc covering the same extent put the head on the
+  // wrong end (x67 cloud 6, a clockwise cycle drawn backwards).
+  for (let start = 0; start < 360; start += 5) {
+    const c = { ...g, start };
+    const f = iou(arcExtent(c), box);
+    if (f > best.fit + 1e-9) best = { g: c, fit: f };
+  }
+  return best.fit > fit + 0.1 ? best.g : g;
+}
+
+// The reader can observe points ON a contour; Bezier handles are invisible.
+// Centripetal Catmull-Rom interpolates those ordered observations without
+// asking a vision model to invent control points. Straight/cornered shapes
+// still use explicit M/L/Q/C/Z commands.
+function splinePath(input, closed = false) {
+  if (!Array.isArray(input) || input.some(p => !Number.isFinite(p?.x) || !Number.isFinite(p?.y))) return null;
+  const points = input.filter((p,i) => !i || p.x !== input[i-1].x || p.y !== input[i-1].y);
+  if (closed && points.length > 1 && points[0].x === points.at(-1).x && points[0].y === points.at(-1).y) points.pop();
+  if (points.length < (closed ? 3 : 2)) return null;
+  const n = points.length;
+  const at = i => {
+    if (closed) return points[(i+n)%n];
+    if (i < 0) return {x:2*points[0].x-points[1].x,y:2*points[0].y-points[1].y};
+    if (i >= n) return {x:2*points[n-1].x-points[n-2].x,y:2*points[n-1].y-points[n-2].y};
+    return points[i];
+  };
+  const commands = [{op:'M',...points[0]}];
+  for (let i=0;i<(closed?n:n-1);i++) {
+    const [a,b,c,d]=[at(i-1),at(i),at(i+1),at(i+2)];
+    const dt=(p,q)=>Math.max(1e-6,Math.sqrt(Math.hypot(q.x-p.x,q.y-p.y)));
+    const ab=dt(a,b),bc=dt(b,c),cd=dt(c,d);
+    const control = k => [
+      b[k]+bc*((b[k]-a[k])/ab-(c[k]-a[k])/(ab+bc)+(c[k]-b[k])/bc)/3,
+      c[k]-bc*((c[k]-b[k])/bc-(d[k]-b[k])/(bc+cd)+(d[k]-c[k])/cd)/3,
+    ];
+    const [x1,x2]=control('x'),[y1,y2]=control('y');
+    commands.push({op:'C',x1,y1,x2,y2,x:c.x,y:c.y});
+  }
+  if (closed) commands.push({op:'Z'});
+  return commandPath(commands);
+}
+
+// Structured path commands keep control points, subpaths and winding intact.
+// Bounds include the control hull, so a curve cannot be clipped to its chord.
+function commandPath(commands) {
+  if (!Array.isArray(commands) || !commands.length || commands[0]?.op !== 'M') return null;
+  const fields = { M: ['x', 'y'], L: ['x', 'y'], Q: ['x1', 'y1', 'x', 'y'], C: ['x1', 'y1', 'x2', 'y2', 'x', 'y'], Z: [] };
+  const xs = [], ys = [];
+  for (const c of commands) {
+    if (!c || !Object.hasOwn(fields, c.op)) return null;
+    const keys = fields[c.op];
+    if (!keys.every(k => Number.isFinite(c[k]))) return null;
+    for (let i = 0; i < keys.length; i += 2) { xs.push(c[keys[i]]); ys.push(c[keys[i + 1]]); }
+  }
+  const x = Math.min(...xs), y = Math.min(...ys);
+  const d = commands.map(c => c.op + (fields[c.op].length ? ' ' + fields[c.op].map((k, i) =>
+    String(Math.round((c[k] - (i % 2 ? y : x)) * 1e6) / 1e6)).join(' ') : '')).join(' ');
+  // What the curve actually covers (sampled), not its control hull: the box a
+  // shape is placed in is the box it draws.
+  const pts = [];
+  let cur = null, start = null;
+  for (const c of commands) {
+    if (c.op === 'M') { cur = { x: c.x, y: c.y }; start = cur; pts.push(cur); continue; }
+    if (c.op === 'Z') { cur = start; continue; }
+    const p0 = cur;
+    for (let i = 1; i <= 16; i++) {
+      const t = i / 16, u = 1 - t;
+      if (c.op === 'L') pts.push({ x: p0.x + (c.x - p0.x) * t, y: p0.y + (c.y - p0.y) * t });
+      else if (c.op === 'Q') pts.push({ x: u * u * p0.x + 2 * u * t * c.x1 + t * t * c.x, y: u * u * p0.y + 2 * u * t * c.y1 + t * t * c.y });
+      else pts.push({ x: u ** 3 * p0.x + 3 * u * u * t * c.x1 + 3 * u * t * t * c.x2 + t ** 3 * c.x, y: u ** 3 * p0.y + 3 * u * u * t * c.y1 + 3 * u * t * t * c.y2 + t ** 3 * c.y });
+    }
+    cur = { x: c.x, y: c.y };
+  }
+  const ex = Math.min(...pts.map((p) => p.x)), ey = Math.min(...pts.map((p) => p.y));
+  const extent = { x: ex, y: ey, w: Math.max(2, Math.max(...pts.map((p) => p.x)) - ex), h: Math.max(2, Math.max(...pts.map((p) => p.y)) - ey) };
+  return { x, y, w: Math.max(2, Math.max(...xs) - x), h: Math.max(2, Math.max(...ys) - y), d, extent };
+}
+
+/**
+ * The geometry mapped by p' = (p - from) * k + to: uniform scale k about
+ * `from`, landing at `to`. Used to fit a shape into the box it was measured in
+ * by changing its own coordinates, so the svg that draws it stays 1:1 with its
+ * coordinate plane.
+ */
+export function scaleGeometry(g, k, from, to) {
+  const X = (x) => (x - from.x) * k + to.x, Y = (y) => (y - from.y) * k + to.y;
+  if (g.type === 'spline') return { ...g, points: g.points.map((p) => ({ ...p, x: X(p.x), y: Y(p.y) })) };
+  if (g.type === 'path') return { ...g, commands: g.commands.map((c) => {
+    const o = { ...c };
+    for (const key of ['x', 'x1', 'x2']) if (Number.isFinite(o[key])) o[key] = X(o[key]);
+    for (const key of ['y', 'y1', 'y2']) if (Number.isFinite(o[key])) o[key] = Y(o[key]);
+    return o;
+  }) };
+  if (g.type === 'arc' || g.type === 'sector') return { ...g, cx: X(g.cx), cy: Y(g.cy), rx: g.rx * k, ry: g.ry * k };
+  return g;
+}
+
+/**
+ * The top the slide writer gives an element (transcribe.mjs): a text that sits
+ * on the slot's bottom edge in the image is a hair taller in our rung, so it
+ * is written 4px higher — the export gate refuses a slide over 2px. A move
+ * into or out of that band is no plain translation of the render.
+ */
+export const writtenTop = (e, slot) => (e.text != null && e.y + e.h >= slot.h - 2 ? Math.max(0, e.y - 4) : e.y);
+
+export function translateElement(e, dx, dy) {
+  e.x += dx;
+  e.y += dy;
+  if (e.textFrame) { e.textFrame.x += dx; e.textFrame.y += dy; }
+  for (const p of [...(e.points ?? []), ...(e.outline ?? [])]) { p.x += dx; p.y += dy; }
+  const g = e.geometry;
+  if (g?.type === 'spline') {
+    for (const p of g.points ?? []) { p.x += dx; p.y += dy; }
+  } else if (g?.type === 'path') {
+    for (const c of g.commands ?? []) {
+      for (const k of ['x', 'x1', 'x2']) if (Number.isFinite(c[k])) c[k] += dx;
+      for (const k of ['y', 'y1', 'y2']) if (Number.isFinite(c[k])) c[k] += dy;
+    }
+  } else if (g) { g.cx += dx; g.cy += dy; }
+}
+
+// Only payloads this compiler can represent may replace the observed marks.
+// In particular, no invented zeroes, truncated series or guessed chart type.
+export function nativeChartData(chart) {
+  if (!chart || !['column', 'bar', 'line', 'area', 'pie', 'doughnut', 'waterfall'].includes(chart.type)) return null;
+  const series = chart.series;
+  if (!Array.isArray(series) || !series.length) return null;
+  const n = series[0]?.values?.length;
+  if (!n || !series.every(s => Array.isArray(s.values) && s.values.length === n && s.values.every(Number.isFinite))) return null;
+  if (['pie', 'doughnut', 'waterfall'].includes(chart.type) && series.length !== 1) return null;
+  const categories = chart.categories ?? [];
+  if (!Array.isArray(categories) || categories.length > n) return null;
+  const data = {
+    categories: [...categories, ...Array(n - categories.length).fill(' ')],
+    series: series.map(s => ({ name: s.name, values: [...s.values] })),
+  };
+  // A waterfall carries what the reader judged on the painting: which bars
+  // stand on the axis, and whether lines join each bar to the next.
+  if (chart.type === 'waterfall') {
+    data.totals = Array.isArray(chart.totals)
+      ? [...new Set(chart.totals.filter(i => Number.isInteger(i) && i >= 0 && i < n))].sort((a, b) => a - b)
+      : null;
+    data.connectors = chart.connectors === true;
+  }
+  return data;
+}
+
+/**
+ * A reader's path commands made drawable against the element they belong to.
+ * The reader writes `M` as a whole segment (start in x1/y1, next point in
+ * x/y) and fills unused fields with 0, which maps far outside the slide:
+ * x53 cloud 2 drew `»` as half-strokes and `</>` as a 400px diagonal (11 of 30
+ * command paths). A point well outside the element's own rect is not part of
+ * its outline; a subpath that loses its start restarts at its next point.
+ */
+export function repairCommands(commands, rect) {
+  if (!Array.isArray(commands) || !rect || !(rect.w > 0) || !(rect.h > 0)) return commands;
+  const padX = Math.max(8, rect.w * 0.5), padY = Math.max(8, rect.h * 0.5);
+  const inside = (x, y) => Number.isFinite(x) && Number.isFinite(y)
+    && x >= rect.x - padX && x <= rect.x + rect.w + padX && y >= rect.y - padY && y <= rect.y + rect.h + padY;
+  const out = [];
+  let open = false;
+  for (const c of commands) {
+    if (!c) continue;
+    if (c.op === 'Z') { if (open) out.push({ op: 'Z' }); open = false; continue; }
+    if (c.op === 'M' && inside(c.x1, c.y1) && (c.x1 !== c.x || c.y1 !== c.y)) {
+      out.push({ op: 'M', x: c.x1, y: c.y1 });
+      open = true;
+      if (inside(c.x, c.y)) out.push({ op: 'L', x: c.x, y: c.y });
+      continue;
+    }
+    if (!inside(c.x, c.y)) continue;
+    const controls = c.op === 'Q' ? [['x1', 'y1']] : c.op === 'C' ? [['x1', 'y1'], ['x2', 'y2']] : [];
+    const straight = controls.some(([kx, ky]) => !inside(c[kx], c[ky]));
+    if (c.op === 'M' || !open) { out.push({ op: 'M', x: c.x, y: c.y }); open = true; continue; }
+    out.push(straight ? { op: 'L', x: c.x, y: c.y } : { ...c });
+  }
+  return out.length >= 2 ? out : commands;
+}
+
+/**
+ * The two ends of a free path with the direction the line runs there: `start`
+ * points back out of the path, `end` points forward. Slot coordinates. Null
+ * when the geometry has no open ends to put a head on.
+ */
+export function pathEnds(e) {
+  const g = e?.geometry;
+  const seg = (p, q) => ({ at: q, dir: { x: q.x - p.x, y: q.y - p.y } });
+  if (g?.type === 'arc') {
+    const rad = (d) => (d * Math.PI) / 180;
+    const pt = (d) => ({ x: g.cx + g.rx * Math.cos(rad(d)), y: g.cy + g.ry * Math.sin(rad(d)) });
+    const tan = (d, sign) => ({ x: -g.rx * Math.sin(rad(d)) * sign, y: g.ry * Math.cos(rad(d)) * sign });
+    const sign = g.sweep >= 0 ? 1 : -1;
+    return { start: { at: pt(g.start), dir: tan(g.start, -sign) }, end: { at: pt(g.start + g.sweep), dir: tan(g.start + g.sweep, sign) } };
+  }
+  let pts = null;
+  if (g?.type === 'spline' && !g.closed) pts = g.points;
+  else if (g?.type === 'path' && !(g.commands ?? []).some((c) => c?.op === 'Z')) {
+    pts = [];
+    for (const c of g.commands ?? []) {
+      if (c?.op === 'C' && Number.isFinite(c.x2)) pts.push({ x: c.x2, y: c.y2 });
+      else if (c?.op === 'Q' && Number.isFinite(c.x1)) pts.push({ x: c.x1, y: c.y1 });
+      if (Number.isFinite(c?.x) && Number.isFinite(c?.y)) pts.push({ x: c.x, y: c.y });
+    }
+  } else if (!g && Array.isArray(e?.points)) pts = e.points;
+  if (!pts || pts.length < 2) return null;
+  return { start: seg(pts[1], pts[0]), end: seg(pts.at(-2), pts.at(-1)) };
+}
+
+/**
+ * A waterfall's total columns when the reader named none: the first bar, and
+ * every later bar whose value is the running sum of the steps before it (17.8,
+ * +0.9, +0.3 → 19.0) — an identity in the data, not a guess from the drawing.
+ * The rest are steps.
+ */
+export function waterfallSubtotals(values) {
+  const out = [0];
+  let run = values[0] ?? 0;
+  for (let i = 1; i < values.length; i++) {
+    const v = values[i];
+    if (Math.abs(v - run) <= Math.max(1e-6, Math.abs(run) * 0.005)) out.push(i);
+    else run += v;
+  }
+  return out;
+}
+
+/**
+ * A waterfall as native stacked columns, the construction PowerPoint users
+ * build by hand and fully editable (ChartEx waterfalls are Phase B: lint refuses
+ * authoring them, and LibreOffice renders none). The reader names the totals
+ * (`data.totals`): they stand on the axis at their own value. Every other bar is
+ * a step that starts where the bar before it ends, left to right; a run with no
+ * total before it starts at 0. A total that is not where the steps arrive is
+ * built as declared and reported in `mismatches`, never moved.
+ *
+ * Series in stack order (`index` names them):
+ *   base   invisible; lifts a bar to its end nearer the axis. A bar wholly
+ *          under the axis hangs from it; one that crosses the axis has none;
+ *   bars   the visible bar (its part above the axis when it crosses);
+ *   below  the part under the axis of a bar that crosses it (only if any);
+ *   change invisible, as tall as each step's change, on top of the step: a
+ *          label at its base sits just above the bar and reads the change —
+ *          stacked columns cannot set a label beyond a bar's end. Only for the
+ *          steps in `labelled`;
+ *   connectors  one line per gap at the level the earlier bar ends, when the
+ *          image draws them.
+ */
+export function waterfallAsStacked(data, { labelled = [] } = {}) {
+  const values = data.series[0].values;
+  const declared = Array.isArray(data.totals) && data.totals.length > 0;
+  const totals = new Set(declared ? data.totals : waterfallSubtotals(values));
+  const decimals = Math.max(0, ...values.map((v) => (String(v).split('.')[1] ?? '').length));
+  const tolerance = Math.max(1e-9, 0.5 * 10 ** -Math.min(decimals, 6));
+  const base = [], bars = [], below = [], ends = [], mismatches = [];
+  let run = 0;
+  let stepsSince = false;
+  values.forEach((v, i) => {
+    let lo, hi, end;
+    if (totals.has(i)) {
+      if (stepsSince && Math.abs(run - v) > tolerance) mismatches.push({ index: i, running: Number(run.toFixed(Math.min(decimals, 6))), total: v });
+      lo = Math.min(0, v); hi = Math.max(0, v); end = v; stepsSince = false;
+    } else {
+      end = run + v; lo = Math.min(run, end); hi = Math.max(run, end); stepsSince = true;
+    }
+    run = end;
+    ends.push(end);
+    if (lo >= 0) { base.push(lo); bars.push(hi - lo); below.push(null); }
+    else if (hi <= 0) { base.push(hi); bars.push(lo - hi); below.push(null); }
+    else { base.push(0); bars.push(hi); below.push(lo); }
+  });
+  const round = (x) => (x == null ? null : Number(x.toFixed(Math.min(decimals + 2, 10))));
+  const series = [
+    { name: 'Waterfall base', values: base.map(round), grouping: 'stacked' },
+    { name: data.series[0].name, values: bars.map(round), grouping: 'stacked' },
+  ];
+  const index = { base: 0, bars: 1, below: null, change: null, connectors: [] };
+  if (below.some((x) => x != null)) {
+    index.below = series.push({ name: 'Below axis', values: below.map(round), grouping: 'stacked' }) - 1;
+  }
+  const steps = new Set(labelled.filter((i) => !totals.has(i)));
+  if (steps.size) {
+    index.change = series.push({ name: 'Change label', values: values.map((v, i) => (steps.has(i) ? round(Math.abs(v)) : null)), grouping: 'stacked' }) - 1;
+  }
+  if (data.connectors) {
+    for (let i = 0; i < values.length - 1; i++) {
+      const line = values.map(() => null);
+      line[i] = line[i + 1] = round(ends[i]);
+      index.connectors.push(series.push({ name: `Connector ${i + 1}`, values: line, kind: 'line' }) - 1);
+    }
+  }
+  return {
+    data: { categories: data.categories, series },
+    index,
+    totals: [...totals].sort((a, b) => a - b),
+    declared,
+    mismatches,
+  };
+}

package/src/builders/concept-intent.mjs

@@ -0,0 +1,200 @@
+// What image intent each concept mockup was generated FROM.
+//
+//   <workspace>/state/concept-intent.json
+//   { "version": 1, "slides": { "3": { "fingerprint": "<sha256>" } } }
+//
+// A concept PNG on disk is reused as-is by `slidemind concepts` — that fast
+// path is what keeps a timed-out harness from regenerating a deck's mockups
+// (and it is load-bearing; see the comment at its call site). But a mockup made
+// before the user attached a screenshot, or before they changed what the
+// screenshot is FOR, no longer depicts the plan it is supposed to depict, and
+// reusing it silently carries that mistake all the way into the .pptx.
+//
+// So each slide's concept output records the canonical fingerprint of the
+// intent it was made under (design decision 6: instruction, crop, fit, use set
+// and source digests count; display names and workspace paths do not). On the
+// next run the fingerprints are recomputed and compared:
+//
+//   * a slide with no uses and no entry is a LEGACY concept — valid, reused,
+//     nothing recorded;
+//   * a slide that has uses but no entry is stale (the mockup predates them);
+//   * a changed fingerprint is stale;
+//   * an entry whose slide no longer has uses is stale too — the picture was
+//     generated with an image the plan has since dropped.
+//
+// Stale means STALE, not regenerated behind the user's back: the command
+// deletes exactly the affected derived outputs (that slide's PNG and its spec)
+// and lets its normal generation path refill them. Nothing here reads, writes
+// or knows about slide JSX — a hand-edited slide is never touched by a concept
+// being out of date.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { statePath } from "../lib/deck-paths.mjs";
+
+export const CONCEPT_INTENT_FILE = "concept-intent.json";
+const VERSION = 1;
+
+export function conceptIntentPath(workspaceDir) {
+  return statePath(workspaceDir, CONCEPT_INTENT_FILE);
+}
+
+/**
+ * The recorded fingerprints, `{ [slide: number]: string }`.
+ *
+ * An absent or unreadable file is an empty record on purpose: this sidecar is
+ * cache bookkeeping, and the failure it can cause — regenerating a mockup that
+ * did not need it — is the harmless direction. Every other image-intent file
+ * refuses to be read loosely, because losing THOSE loses an obligation.
+ */
+export function readConceptIntent(workspaceDir) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(conceptIntentPath(workspaceDir), "utf8"));
+  } catch {
+    return {};
+  }
+  if (!parsed || parsed.version !== VERSION || typeof parsed.slides !== "object") return {};
+  const out = {};
+  for (const [key, entry] of Object.entries(parsed.slides ?? {})) {
+    const slide = Number(key);
+    const fingerprint = entry?.fingerprint;
+    if (Number.isInteger(slide) && slide > 0 && typeof fingerprint === "string") {
+      out[slide] = fingerprint;
+    }
+  }
+  return out;
+}
+
+function write(workspaceDir, slides) {
+  const file = conceptIntentPath(workspaceDir);
+  const numbers = Object.keys(slides)
+    .map(Number)
+    .sort((a, b) => a - b);
+  if (!numbers.length) {
+    fs.rmSync(file, { force: true });
+    return null;
+  }
+  const doc = { version: VERSION, slides: {} };
+  for (const slide of numbers) doc.slides[slide] = { fingerprint: slides[slide] };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Write-then-rename, like every other deck sidecar: a reader sees the old
+  // record or the new one, never half of either.
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(doc, null, 2) + "\n");
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/**
+ * Record what the named slides were generated under.
+ *
+ * `fingerprints` is a `Map<slide, string|null>` (or a plain object). A null
+ * fingerprint means the slide has no image uses, so its entry is REMOVED —
+ * "nothing recorded" is exactly what a legacy no-intent concept looks like, and
+ * it is what makes the two states round-trip. Slides the map does not mention
+ * keep whatever they had.
+ */
+export function recordConceptIntent(workspaceDir, fingerprints) {
+  const next = readConceptIntent(workspaceDir);
+  for (const [slide, fingerprint] of entriesOf(fingerprints)) {
+    if (fingerprint) next[slide] = fingerprint;
+    else delete next[slide];
+  }
+  return write(workspaceDir, next);
+}
+
+/**
+ * The slides whose concept output no longer matches the intent it was made
+ * under, in ascending order.
+ *
+ * @param {string} workspaceDir
+ * @param {Map<number, string|null>|Record<number, string|null>} fingerprints
+ *   the intent fingerprint of each slide NOW (null = no image uses).
+ */
+export function staleConceptSlides(workspaceDir, fingerprints) {
+  const recorded = readConceptIntent(workspaceDir);
+  const stale = [];
+  for (const [slide, fingerprint] of entriesOf(fingerprints)) {
+    if ((recorded[slide] ?? null) !== (fingerprint ?? null)) stale.push(slide);
+  }
+  return stale.sort((a, b) => a - b);
+}
+
+/** Forget every slide the plan no longer has (same sweep that prunes its PNG). */
+export function pruneConceptIntent(workspaceDir, keepSlides) {
+  const keep = new Set([...(keepSlides ?? [])].map(Number));
+  const recorded = readConceptIntent(workspaceDir);
+  const next = {};
+  for (const [slide, fingerprint] of Object.entries(recorded)) {
+    if (keep.has(Number(slide))) next[slide] = fingerprint;
+  }
+  if (Object.keys(next).length === Object.keys(recorded).length) return null;
+  return write(workspaceDir, next);
+}
+
+function* entriesOf(fingerprints) {
+  const entries =
+    fingerprints instanceof Map ? fingerprints.entries() : Object.entries(fingerprints ?? {});
+  for (const [slide, fingerprint] of entries) {
+    const n = Number(slide);
+    if (Number.isInteger(n) && n > 0) yield [n, fingerprint ?? null];
+  }
+}
+
+// What each mockup was made WITH beyond its pixels, as the concept route
+// returned it: the slide it continues (only when generation applied the plan's
+// link — another layout, a frame or a failed predecessor drops it) and the
+// approved image uses a user's own blueprint mockup does not show.
+//
+//   <workspace>/state/concept-notes.json   { "4": { "continues": 3 } }
+//
+// Cache bookkeeping like the record above: unreadable reads as empty.
+export const CONCEPT_NOTES_FILE = "concept-notes.json";
+
+export function readConceptNotes(workspaceDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(statePath(workspaceDir, CONCEPT_NOTES_FILE), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Record the notes of the mockups just written; every other slide keeps its own. */
+export function recordConceptNotes(workspaceDir, images, keepSlides) {
+  const keep = new Set([...(keepSlides ?? [])].map(Number));
+  const notes = Object.fromEntries(Object.entries(readConceptNotes(workspaceDir)).filter(([s]) => keep.has(Number(s))));
+  for (const img of images) {
+    const n = Number(img?.slideNumber);
+    if (!Number.isInteger(n) || n < 1) continue;
+    const note = {
+      ...(Number.isInteger(img.continues) ? { continues: img.continues } : {}),
+      ...(img.pendingUseIds?.length ? { pendingUseIds: img.pendingUseIds.map(String) } : {}),
+    };
+    if (Object.keys(note).length) notes[n] = note;
+    else delete notes[n];
+  }
+  const file = statePath(workspaceDir, CONCEPT_NOTES_FILE);
+  if (!Object.keys(notes).length) return fs.rmSync(file, { force: true });
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(notes, null, 2) + "\n");
+  fs.renameSync(tmp, file);
+}
+
+/** The agent's lines for the mockups on disk — the add-in's concept intro, same words. */
+export function conceptNoteLines(notes, slides) {
+  const on = [...slides].map(Number).sort((a, b) => a - b).filter((n) => notes[n]);
+  const continuing = on.filter((n) => Number.isInteger(notes[n].continues)).map((n) => `slide ${n} continues slide ${notes[n].continues}`);
+  const pending = on.filter((n) => notes[n].pendingUseIds?.length).map((n) => `slide ${n} (${notes[n].pendingUseIds.join(", ")})`);
+  return [
+    ...(continuing.length
+      ? [`Sequenced slides: ${continuing.join("; ")}. A continuing slide is its predecessor one step later — build it from the predecessor's JSX and change only what its own content changes.`]
+      : []),
+    ...(pending.length
+      ? [`These mockups are the user's own blueprint image for their slide and therefore show ONLY it: ${pending.join("; ")}. The approved image uses named in brackets are not in the mockup and are yours to compose — check IMAGE USES, and never treat the mockup as the finished slide.`]
+      : []),
+  ];
+}

package/src/builders/concept-layout.mjs

@@ -0,0 +1,79 @@
+// Geometry contracts shared by normalization, transcription and settling.
+import { cleanText, textIsPrinted } from './concept-text.mjs';
+
+// Text rotation describes an UNROTATED frame, centred on the observed rect.
+export function textFrame(e) {
+  if (!e) return {};
+  const rotation = Number.isFinite(e.textRotation) ? e.textRotation : 0;
+  if (e.textFrame && ['x', 'y', 'w', 'h'].every(k => Number.isFinite(e.textFrame[k])) && e.textFrame.w > 0 && e.textFrame.h > 0) {
+    return { ...e, ...e.textFrame, rotation };
+  }
+  const a = Math.abs(rotation % 180) * Math.PI / 180;
+  const c = Math.abs(Math.cos(a)), s = Math.abs(Math.sin(a));
+  const determinant = c * c - s * s;
+  if (!rotation || Math.abs(determinant) < 0.01) return { ...e, rotation };
+  const w = (c * e.w - s * e.h) / determinant;
+  const h = (c * e.h - s * e.w) / determinant;
+  if (!(w > 0 && h > 0)) return { ...e, rotation };
+  return { ...e, x: e.x + (e.w - w) / 2, y: e.y + (e.h - h) / 2, w, h, rotation };
+}
+
+export function fixedAspect(e) {
+  return e.shape === 'circle' || e.shape === 'ellipse' || e.shape === 'ring' || e.kind === 'disc' || e.geometry != null;
+}
+
+const CARRIER_KINDS = new Set(['panel', 'card', 'disc', 'badge', 'shape']);
+
+// An icon or picture the reader put ON a carrier (a disc, badge or tile) is
+// seated there: the writer nests it in the carrier, whose flexbox centres it,
+// so the pair exports centred and grouped, and moves as one — two absolute
+// boxes drifted 0.5–3px apart. The relation is the reader's declared `parent`,
+// never inferred from geometry (bb782591); the rect only checks that the asset
+// sits in the carrier's middle. Ids in `skip` (drawn as lines, figures) take
+// part in neither role; an asset a line glues to (`glued`) or that holds
+// children of its own stays where it was drawn.
+// Returns Map(carrier id → asset).
+export function seatedAssets(elements, { skip = new Set(), glued = new Set() } = {}) {
+  const byId = new Map(elements.map(e => [e.id, e]));
+  const childCount = new Map();
+  for (const e of elements) if (e.parent) childCount.set(e.parent, (childCount.get(e.parent) ?? 0) + 1);
+  const painted = p => (p.fill && p.fill !== 'none') || p.shape === 'ring'
+    || (p.stroke && !(Number.isFinite(p.stroke.width) && p.stroke.width <= 0));
+  const seats = new Map();
+  for (const a of elements) {
+    if (!['icon', 'image'].includes(a.kind) || a.image?.assetUseId || skip.has(a.id) || glued.has(a.id) || childCount.has(a.id)) continue;
+    const p = byId.get(a.parent);
+    if (!p || skip.has(p.id) || !CARRIER_KINDS.has(p.kind) || !painted(p) || cleanText(p.text, { printed: textIsPrinted(p) }) != null) continue;
+    if (childCount.get(p.id) !== 1 || !(p.w > 0 && p.h > 0)) continue;
+    // A seat the reader declared (seat.mjs) is the relation; the rect check
+    // stands in only where none was declared.
+    const declared = a.seat?.x === 'center' && a.seat?.y === 'middle';
+    const dx = a.x + a.w / 2 - (p.x + p.w / 2), dy = a.y + a.h / 2 - (p.y + p.h / 2);
+    if (!declared && (Math.abs(dx) > p.w / 4 || Math.abs(dy) > p.h / 4)) continue;
+    seats.set(p.id, a);
+  }
+  return seats;
+}
+
+// Paint containers before their content even when the reader interleaves a
+// foreground label with a later, unrelated background. Stable within a layer.
+// Native charts own their marks and are foreground, just like images/text.
+// A shape that carries its own label (a card header bar, a pill) is a shape:
+// its words ride on it, so it keeps the reader's order among the shapes. As
+// foreground it painted over every shape the reader drew after it — the disc
+// that straddles a header bar came out half covered (x113 PM 2, x112 GTM 2,
+// x109 QBR 6, x108 cloud 1: 14 flips in x108–x113, every one of them a disc
+// or chevron buried under a labelled shape the reader drew earlier).
+export function paintOrdered(elements) {
+  const foreground = e => ['text', 'number', 'icon', 'image', 'chart', 'table'].includes(e.kind);
+  const byId = new Map(elements.map(e => [e.id, e]));
+  const pending = [...elements], placed = new Set(), ordered = [];
+  while (pending.length) {
+    const eligible = pending.filter(e => !byId.has(e.parent) || placed.has(e.parent));
+    // A container's own label does not make its children go behind it.
+    // Parent-before-child is a dependency, not a comparator exception.
+    const next = eligible.find(e => !foreground(e)) ?? eligible[0] ?? pending[0];
+    ordered.push(next); placed.add(next.id); pending.splice(pending.indexOf(next), 1);
+  }
+  return ordered;
+}