slidemind 0.3.20 → 0.4.0

package/src/builders/concept-spec.mjs

@@ -0,0 +1,645 @@
+// Concept specs — the machine inventory of a mockup the add-in extracts with
+// a vision model (`POST /api/cli/brands/:id/concept-specs`), written by
+// `slidemind concepts` next to each PNG as `concept-slide-NN.spec.json`
+// (machine, slot pixels) and `concept-slide-NN.spec.txt` (the outline the agent
+// transcribes). `view-draft` counts the render against the JSON. Pure helpers
+// only; no I/O beyond the two readers.
+import fs from "node:fs";
+import path from "node:path";
+import { nativeChartData } from "./concept-geometry.mjs";
+import { centreHoles, holeIds, holeMembers } from "./chart-hole.mjs";
+import { foldChartLabels } from "./chart-labels.mjs";
+import { applyLines } from "./concept-lines.mjs";
+import { applyAround, applySeats, seatOf } from "./seat.mjs";
+import { applyStacks, remapGrids, remapStacks, unblockStackRows } from "./stack.mjs";
+import { foldTextBlocks } from "./text-blocks.mjs";
+import { cleanText, textIsPrinted, typeset } from "./concept-text.mjs";
+export { cleanText, textIsPrinted };
+import { fixedAspect } from "./concept-layout.mjs";
+import { foldListMarkers } from "./concept-lists.mjs";
+import { glyphMarkOf } from "./concept-marks.mjs";
+import { remapRepeats } from "./repeat-groups.mjs";
+
+// Measurement knob (scripts/fidelity): names of normalization steps to skip,
+// so a replay can show what each one contributes. Unset in production.
+const ablated = (name) => (process.env.SLIDEMIND_ABLATE ?? "").split(",").includes(name);
+
+/**
+ * The generation of the persisted spec shape, hashed into the fingerprint a
+ * spec is cached under (design decision 6, `slidemind concepts`).
+ *
+ * Bump it when the spec gains or changes a field an already-written spec cannot
+ * carry — `image.assetUseId` was the first. Every intent-bearing spec on disk is
+ * then refused for reuse and re-read; a spec for a slide with no image uses has
+ * no fingerprint at all and stays reusable, exactly as a legacy concept does.
+ *
+ * This is NOT the model's wire format (`schemaFormat: legacy | compact-v1`):
+ * both expand to the same persisted spec server-side, so switching between them
+ * would re-spend a vision pass for an identical file.
+ */
+export const SPEC_SCHEMA_VERSION = 1;
+
+/**
+ * One element's `image` payload, normalized (implementation guide §5).
+ *
+ * Two shapes reach this. `{query}` is what an add-in without the image-intent
+ * contract returns, and it stays valid — it comes back with `assetUseId: null`.
+ * `{query, assetUseId}` is a picture the user supplied: the bytes are resolved
+ * from the deck's registry by use id, so the binding wins and the query is
+ * dropped. Leaving the query would let the asset fetcher search for a lookalike
+ * and write it over the user's own file — the substitution the contract exists
+ * to prevent.
+ *
+ * Idempotent, so a spec re-read from disk normalizes to itself.
+ */
+export function normalizeImagePayload(image) {
+  if (image == null) return null;
+  const useId = typeof image.assetUseId === "string" ? image.assetUseId.trim() : "";
+  const assetUseId = useId || null;
+  return { query: assetUseId ? null : (image.query ?? null), assetUseId };
+}
+
+// A bare colour literal, and the kinds whose text is prose. `cleanText` cannot
+// use these — it sees a string with no element around it, and a slide may
+// legitimately print a hex; `dropStandIns` has the element and can tell.
+const HEX_ONLY = /^\s*#[0-9a-f]{3,8}\s*$/i;
+const TEXT_KINDS = new Set(["text", "number"]);
+
+// A layout's background tone from design.md's Layout Catalog entry
+// (`"tone":"light"|"dark"` in its Selection JSON); light when unknown.
+// Null when the layout is unknown to this bundle: the caller then trusts the
+// mockup's own background (`spec.background`, read by the vision model).
+export function layoutToneFor(bundleDir, layoutName) {
+  if (!bundleDir || !layoutName) return null;
+  try {
+    const md = fs.readFileSync(path.join(bundleDir, "design.md"), "utf8");
+    const start = md.indexOf(`### ${layoutName}\n`);
+    if (start < 0) return null;
+    const end = md.indexOf("\n### ", start + 4);
+    const section = md.slice(start, end < 0 ? undefined : end);
+    const m = /"tone"\s*:\s*"(light|dark)"/.exec(section);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+const DARK_FILLS = new Set(["dark", "accent"]);
+const LIGHT_FILLS = new Set(["white", "light", "muted"]);
+// Dark or light ground: the observed fill when the spec carries it (a green
+// status dot is dark ground for its white glyph), else the tone word.
+export function fillTone(e) {
+  if (e?.fillHex) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(e.fillHex);
+    if (m) {
+      const n = parseInt(m[1], 16);
+      const lum = (0.2126 * ((n >> 16) & 255) + 0.7152 * ((n >> 8) & 255) + 0.0722 * (n & 255)) / 255;
+      return lum < 0.5 ? "dark" : "light";
+    }
+  }
+  if (DARK_FILLS.has(e?.fill)) return "dark";
+  if (LIGHT_FILLS.has(e?.fill)) return "light";
+  return null;
+}
+
+// The mockup was drawn on ITS background; the slide is built on the layout's.
+// A spec whose text is `light` because the mockup was black would vanish on a
+// white layout (and vice versa), and a white card on a white slide has no
+// edge. So: text tone flips against the nearest painted ancestor's fill, else
+// the layout's tone; a card whose fill matches the background it sits on is
+// marked `elevated` (draw it with a shadow). Idempotent.
+export function normalizeForLayout(spec, { tone: layoutTone = null } = {}) {
+  const read = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  const relationNotes = applyLines(spec).filter((n) => !(spec.notes ?? []).includes(n));
+  if (relationNotes.length) spec.notes = [...(spec.notes ?? []), ...relationNotes];
+  // Lists first, while every mark still stands where the reader read it: an
+  // item's dot or tick goes (or the item's marker, before a carrier), the words
+  // lose a typed glyph, the items of one list share a block (concept-lists.mjs).
+  if (!ablated("foldListMarkers")) spec.elements = foldListMarkers(spec.elements ?? [], spec.connectors ?? [], spec.repeats ?? []);
+  // Relations the reader declared are built before anything reads a child's
+  // rect: a ring on its hub's centre, a child where its seat puts it (seat.mjs).
+  applyAround(spec);
+  applySeats(spec, { beforeFold: true });
+  // The layout's tone when the plan's layout exists; else the mockup's own
+  // background as the model read it; else light.
+  const tone = layoutTone ?? (spec.background === "dark" ? "dark" : "light");
+  // The plan's layout is authoritative: a concept drawn in the other tone is a
+  // concept-generation defect, said once and never answered by swapping layouts.
+  if (layoutTone && (spec.background === "dark" || spec.background === "light") && spec.background !== layoutTone) {
+    const note = `the concept was drawn on a ${spec.background} background but its planned layout is ${layoutTone}; transcribed onto the planned layout, colours adapted to it`;
+    if (!(spec.notes ?? []).includes(note)) spec.notes = [...(spec.notes ?? []), note];
+  }
+
+  const byId = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  // The painted element a box sits on: its parent chain first, else the
+  // smallest painted element whose rect contains the box's centre (the model
+  // often lists a label as a top-level element although it sits on an arch
+  // or a bar — x33 scratch: dark text on the accent beachhead arch).
+  const painted = (spec.elements ?? []).filter((x) => x.fill && x.fill !== "none");
+  // The painted element itself, so the caller can read the exact colour a text
+  // will sit ON and not just its light/dark bucket.
+  const groundElOf = (e) => {
+    let p = e.parent ? byId.get(e.parent) : null;
+    let guard = 0;
+    while (p && guard++ < 32) {
+      if (fillTone(p)) return p;
+      p = p.parent ? byId.get(p.parent) : null;
+    }
+    const cx = e.x + e.w / 2;
+    const cy = e.y + e.h / 2;
+    let best = null;
+    for (const c of painted) {
+      if (c === e || c.kind === "icon") continue;
+      if (cx < c.x || cx > c.x + c.w || cy < c.y || cy > c.y + c.h) continue;
+      // A ground lies UNDER the element, so it is larger than it: a shield
+      // drawn inside a white disc made the disc its own ground's child and it
+      // lost the lift that kept it visible on white (x54 cloud 5).
+      if (c.w * c.h <= (e.w || 0) * (e.h || 0)) continue;
+      if (!best || c.w * c.h < best.w * best.h) best = c;
+    }
+    return best;
+  };
+  const groundOf = (e) => {
+    const g = groundElOf(e);
+    return g ? (fillTone(g) ?? "light") : tone;
+  };
+  const backgroundOf = groundOf;
+  const WORDLESS = new Set(["rule", "icon", "image", "path", "chart"]);
+  // The chrome is slide copy too (x74N1's headlines carried the concept's
+  // em-dashes); it is written as JSX attribute strings, so a double quote
+  // becomes a single one.
+  for (const [k, v] of Object.entries(spec.chrome ?? {})) if (typeof v === "string") spec.chrome[k] = typeset(v, { quote: "'" });
+  for (const e of spec.elements ?? []) {
+    e.text = cleanText(e.text, { printed: textIsPrinted(e) });
+    // A bound original survives every pass below untouched: nothing here folds,
+    // drops or re-parents a picture. Normalizing the payload once, here, is
+    // what makes that true for a spec read back from disk too.
+    if (e.kind === "image") e.image = normalizeImagePayload(e.image);
+    // A rule, icon, picture, path or chart carries no words of its own. A
+    // card, disc, badge or shape may (x34 dropped a scorecard's fourth metric
+    // by treating a card's real text as a stand-in).
+    if (e.text != null && WORDLESS.has(e.kind)) e.text = null;
+    // A painted element's own text (a badge digit) sits on its own fill.
+    const own = e.fill && e.fill !== "none" ? fillTone(e) : null;
+    const bg = backgroundOf(e);
+    if (e.text != null || e.kind === "rule") {
+      const textBg = e.text != null && own ? own : bg;
+      if (textBg === "light" && e.color === "light") e.color = "dark";
+      if (textBg === "dark" && e.color === "dark") e.color = "light";
+      // The ground a reader actually sees this text on, carried through to the
+      // writer: the tone word above is the fallback, and the observed colour
+      // has to be checked against this or a misread glyph ships unreadable
+      // (dark type on the brand accent — 2.4:1).
+      if (e.text != null) {
+        const g = own ? e : groundElOf(e);
+        e.ground = textBg;
+        e.groundHex = g?.fillHex ?? null;
+      }
+    }
+    if ((e.kind === "card" || e.kind === "panel") && own) {
+      e.elevated = own === bg;
+    }
+    // A disc or badge painted the slide's own colour with no outline is
+    // invisible unless it keeps the lift the image drew it with (x51 GTM 1:
+    // four white loop nodes on white vanished, only their icons left).
+    if ((e.kind === "disc" || e.kind === "badge" || e.kind === "shape") && own && own === bg && !e.stroke) e.elevated = true;
+    // The reader saw whether it casts a shadow: that observation wins over
+    // the colour inference above.
+    if (typeof e.shadow === "boolean") e.elevated = e.shadow;
+    // Preserve the observed icon role. The writer checks its actual paint
+    // against the resolved background, just like text.
+    if (e.kind === "icon" && e.icon) {
+      e.icon.color ??= bg === "dark" ? "white" : "dark";
+    }
+  }
+  // A bold lead-in the model listed twice — once alone ("Owner:") and once as
+  // the start of the sentence at the same origin — renders as two texts on the
+  // same pixels. Fold the lead-in into the sentence as its `leadIn`.
+  const texts = (spec.elements ?? []).filter((e) => e.text != null && (e.kind === "text" || e.kind === "number"));
+  const dropped = new Set();
+  for (const a of texts) {
+    for (const b of texts) {
+      if (a === b || dropped.has(a.id) || dropped.has(b.id)) continue;
+      const near = Math.abs(a.x - b.x) <= 6 && Math.abs(a.y - b.y) <= 6;
+      const lead = String(a.text).trim().replace(/[:\s]+$/, "");
+      const bt = String(b.text).trim();
+      if (near && lead && bt.startsWith(lead) && bt.length > lead.length) {
+        b.leadIn = String(a.text).trim();
+        dropped.add(a.id);
+        continue;
+      }
+      // A short bold run the model listed on its own ("70/100") inside a
+      // sentence it also listed: an emphasis span, not a second text.
+      const overlapsRect = a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+      if (overlapsRect && lead.length >= 2 && bt.length > lead.length + 4 && bt.includes(lead) && (a.weight === "bold" || a.role === "number")) {
+        b.emphasis = [...(b.emphasis ?? []), lead];
+        dropped.add(a.id);
+      }
+    }
+  }
+  if (dropped.size) {
+    spec.elements = spec.elements.filter((e) => !dropped.has(e.id));
+    spec.connectors = (spec.connectors ?? []).filter((c) => !dropped.has(c.from) && !dropped.has(c.to));
+    if (spec.counts) spec.counts.elements = spec.elements.length;
+  }
+  // A connector runs over the slide background between its nodes (a white
+  // stroke over a white layout is invisible — x31 scratch: five such on one
+  // loop), unless both ends sit inside the same painted panel.
+  // A white stroke vanishes over every white card it crosses (x31 scratch:
+  // five loop edges refused for 1.00:1 contrast); the muted grey reads on a
+  // light and on a dark ground alike, so it is the light stroke's rendering.
+  for (const c of spec.connectors ?? []) {
+    if (c.color === "light") c.color = "muted";
+    if (tone === "dark" && c.color === "dark") c.color = "muted";
+  }
+  // An element that lies wholly outside the content slot cannot be drawn in
+  // it: it is chrome the concept image drew (a footer logo, a placeholder
+  // guide) that the reader listed as content. Named, then left out.
+  // The reader always maps into the slot it was given (`spec.slot`).
+  const slot = spec.slot;
+  const outside = (e) => slot && [e.x, e.y, e.w, e.h].every(Number.isFinite)
+    && (e.x >= slot.w - 1 || e.y >= slot.h - 1 || e.x + e.w <= 1 || e.y + e.h <= 1);
+  const gone = (spec.elements ?? []).filter(outside);
+  if (gone.length) {
+    spec.elements = spec.elements.filter((e) => !outside(e));
+    spec.notes = [...(spec.notes ?? []), ...gone.map((e) => `${e.id}: lies outside the content slot (chrome the concept drew) — not drawn`)];
+  }
+  spec.elements = dropChartMarks(spec.elements ?? []);
+  // A chart's legend, category and value labels drawn beside it are its own
+  // (chart-labels.mjs); after the list fold, so a legend row's marker goes too.
+  foldChartLabels(spec);
+  if (!ablated("dropStandIns")) dropStandIns(spec.elements ?? []);
+  const beforeFold = new Set((spec.elements ?? []).map((e) => e.id));
+  if (!ablated("foldLabelsIntoShape")) spec.elements = foldLabelsIntoShape(spec.elements ?? [], { connectors: spec.connectors ?? [] });
+  // A declared stack's rows are never folded into one block (stack.mjs).
+  unblockStackRows(spec);
+  const blockNotes = [];
+  spec.elements = foldTextBlocks(spec.elements ?? [], { connectors: spec.connectors ?? [], notes: blockNotes });
+  if (blockNotes.length) spec.notes = [...(spec.notes ?? []), ...blockNotes.filter((n) => !(spec.notes ?? []).includes(n))];
+  const kept = new Set((spec.elements ?? []).map((e) => e.id));
+  // Only the ends the fold absorbed: a connector naming an element that never
+  // existed is left for the writer to report.
+  const absorbed = new Set([...beforeFold].filter((id) => !kept.has(id)));
+  spec.connectors = (spec.connectors ?? []).filter((c) => !absorbed.has(c.from) && !absorbed.has(c.to));
+  const repeatNotes = remapRepeats(spec, read).filter((n) => !(spec.notes ?? []).includes(n));
+  if (repeatNotes.length) spec.notes = [...(spec.notes ?? []), ...repeatNotes];
+  // A folded text block takes its seat as one element (seat.mjs); what stands
+  // in a doughnut's hole is centred in its ring (chart-hole.mjs); a declared
+  // stack is laid out from what survived the folds (stack.mjs).
+  applySeats(spec);
+  centreHoles(spec);
+  const stackNotes = [...remapStacks(spec, read), ...remapGrids(spec, read)].filter((n) => !(spec.notes ?? []).includes(n));
+  if (stackNotes.length) spec.notes = [...(spec.notes ?? []), ...stackNotes];
+  applyStacks(spec);
+  spec.slideTone = tone;
+  return spec;
+}
+
+// Repetition and lowercase spelling are valid slide content. Only an
+// explicit absence/placeholder classification is sufficient to delete copy.
+// A chart draws its own bars, lines, axes and gridlines. The reader sometimes
+// inventories those marks a second time as painted rectangles sitting inside
+// the chart's own rect — 17 of them on one slide — and the writer then renders
+// a native PowerPoint chart AND paints its bars on top of it, so every bar
+// appears twice (reported on a built deck, cloud slide 8 at 0.58).
+//
+// Whatever lies wholly inside a chart belongs to that chart. Text and icons are
+// left alone: a label or a marker over a chart may be an annotation the chart
+// itself does not draw, and losing one is worse than a duplicate.
+const CHART_OWNED = new Set(["bar", "rule", "shape", "path", "card", "panel", "disc", "badge"]);
+export function dropChartMarks(elements) {
+  const charts = elements.filter((e) => e.kind === "chart" && e.w > 0 && e.h > 0 && nativeChartData(e.chart));
+  if (!charts.length) return elements;
+  // What the reader named in a doughnut's hole is drawn there (chart-hole.mjs).
+  const hole = holeMembers(elements);
+  const inside = (e, c) =>
+    e.x >= c.x - 2 && e.y >= c.y - 2 &&
+    e.x + e.w <= c.x + c.w + 2 && e.y + e.h <= c.y + c.h + 2;
+  return elements.filter((e) => {
+    if (e.kind === "chart" || !CHART_OWNED.has(e.kind) || hole.has(e.id)) return true;
+    // A labelled badge/callout is content, just like a standalone annotation.
+    // Mere containment does not establish that the chart will reproduce it.
+    if (cleanText(e.text, { printed: textIsPrinted(e) }) != null) return true;
+    return !charts.some((c) => c !== e && inside(e, c));
+  });
+}
+
+export function dropStandIns(elements) {
+  for (const e of elements) {
+    // The reader's `placeholder` flag means different things in different
+    // places, and reading it as one thing destroyed content. On a FREE-STANDING
+    // TEXT element it is provenance: the reader describing a region instead of
+    // transcribing it ("Market column"), which must go. On a PAINTED shape it
+    // is about the slot, not the words — and acting on it there deleted 31
+    // real, visible texts across x44/x45/x46, every numbered step marker
+    // ("1".."4", "01".."04", "30\nDAYS") plus whole banner sentences, with not
+    // one genuine invention among them. Those vanishing numbers are the
+    // recurring "numbered step markers rendered as solid blue circles without
+    // visible numbers" defect.
+    //
+    // The two are cleanly separable: of 347 flagged elements in those runs not
+    // one was a text kind — they were all discs, badges, cards and panels. So
+    // honour the flag where it is provenance and ignore it where it is not,
+    // splitting on the same TEXT_KINDS the paint rule below already uses. The
+    // stand-in grammar the reader really emits for "no text" ("/null", ">",
+    // "There is no text.") is removed by `cleanText` before this runs, by
+    // shape rather than by list, so nothing here is the only guard.
+    if (e.textSource === "placeholder" && TEXT_KINDS.has(e.kind)) e.text = null;
+
+    // The one case that IS paint rather than words: a bare
+    // colour literal on a painted box is that box's paint written where its
+    // words go. All eleven in x40 sat on a shape whose own fill they named — a
+    // white card reading "#FFFFFF", an accent disc "#0000FF" — and rendered as
+    // giant hex across the slide. A hex a slide really prints is a text
+    // element, and keeps its words.
+    if (e.text != null && !TEXT_KINDS.has(e.kind) && HEX_ONLY.test(String(e.text))) e.text = null;
+    // The reader's own machinery leaking into a shape's words: its schema's
+    // URL or definition path, or a refusal (x48/x52: "http://json-schema.org/
+    // schema#", "/definitions/concept_spec_compact_v1", "stroke", "As a
+    // language model, I cannot comply"). Agents stripped these by hand.
+    if (e.text != null && !TEXT_KINDS.has(e.kind) && SCHEMA_LEAK.test(String(e.text).trim())) e.text = null;
+    if (e.text != null && REFUSAL.test(String(e.text))) e.text = null;
+  }
+  return elements;
+}
+// Unambiguous only: a bare word ("stroke") may be a slide's own copy, and
+// repetition is not evidence (see the "slide canvas" test).
+const SCHEMA_LEAK = /^(?:https?:\/\/json-schema\.org\S*|\S*\/definitions\/\S*|#?\/?(?:\$schema|\$ref)\b\S*)$/i;
+const REFUSAL = /\b(?:as an? (?:ai|language model)|i (?:cannot|can't|am unable to|'m unable to) (?:comply|help|assist))\b/i;
+
+
+// A painted box whose only content is text IS a text-bearing shape — a circle,
+// a chip, a pill, a band, a card, it makes no difference. The reader lists the
+// words as their own elements, so the writer used to park a text box on top of
+// the shape: two objects in PowerPoint where the design has one, and the words
+// drift the moment anyone moves the box. Those lines are folded into the shape
+// as its own text body and the children are dropped.
+//
+// What stops a fold is lost content or geometry: a box holding an icon,
+// a chart or any non-text organism is a composition, and so is one whose texts
+// play different parts (a hero number above a caption, a card title above its
+// body). Where they belong stays where the image put them.
+//
+// The alignment comes from the geometry the reader measured — the text block's
+// margins inside its box — so a centred label centres and a paragraph in a
+// card keeps its corner.
+export function foldLabelsIntoShape(elements, { connectors = [] } = {}) {
+  const referenced = new Set(connectors.flatMap((c) => [c.from, c.to]));
+  const byId = new Map(elements.map((e) => [e.id, e]));
+  const kids = new Map();
+  for (const e of elements) {
+    if (!e.parent) continue;
+    if (!kids.has(e.parent)) kids.set(e.parent, []);
+    kids.get(e.parent).push(e);
+  }
+  const folded = new Set();
+  for (const [pid, children] of kids) {
+    if (children.some(e => e.textRotation)) continue;
+    const p = byId.get(pid);
+    if (!p || p.text != null) continue;
+    // These kinds use dedicated emitters and cannot carry native shape text.
+    if (["icon", "image", "chart", "path", "rule", "table", "text", "number"].includes(p.kind)) continue;
+    // Only a PAINTED box can carry text: an unfilled region is a layout area.
+    if (!p.fill || p.fill === "none") continue;
+    if (!(p.w > 0) || !(p.h > 0)) continue;
+    if (!children.length) continue;
+    // An icon or a picture can never BE a shape's text, so it does not stop
+    // the words from being one — it just has to keep out of their way, which
+    // is what the centring guard below decides.
+    const words = children.filter((c) => (c.kind === "text" || c.kind === "number") && c.text != null);
+    const others = children.filter((c) => !words.includes(c));
+    if (!words.length || others.length) continue;
+    // A fold must preserve references, list semantics, rich text and styles.
+    if (words.some((c) => referenced.has(c.id) || kids.has(c.id) || c.leadIn || c.emphasis?.length || c.paragraphs || c.marker
+      || /(?:^|\n)\s*(?:[•·▪◦‣\-–*✓✔]|\d+[.)])\s+/.test(c.text))) continue;
+    const signature = (c) => JSON.stringify([c.colorToken, c.colorHex, c.color, c.align]);
+    if (!words.every((c) => signature(c) === signature(words[0]))) continue;
+    if (others.some((c) => c.text != null)) continue;
+    const role = words[0].role ?? null;
+    const weight = words[0].weight ?? null;
+    if (!words.every((c) => (c.role ?? null) === role && (c.weight ?? null) === weight)) continue;
+    const lines = [...words].sort((a, b) => a.y - b.y);
+    // …and they have to be one BLOCK. Consecutive lines sit about a line apart;
+    // a real gap between them means two things in one box (a title up top, a
+    // body lower down), and joining those would swallow the space the design
+    // put there.
+    const contiguous = lines.every((c, i) => {
+      if (i === 0) return true;
+      const prev = lines[i - 1];
+      const gap = c.y - (prev.y + prev.h);
+      return gap >= 0 && gap <= 1.1 * Math.max(prev.h, c.h)
+        && Math.abs(c.x - prev.x) <= Math.min(c.w, prev.w) * 0.05
+        && Math.abs(c.w - prev.w) <= Math.min(c.w, prev.w) * 0.05;
+    });
+    if (!contiguous) continue;
+    // Where the block sits in its box decides how the shape holds its text.
+    const x0 = Math.min(...lines.map((c) => c.x));
+    const x1 = Math.max(...lines.map((c) => c.x + c.w));
+    const y0 = Math.min(...lines.map((c) => c.y));
+    const y1 = Math.max(...lines.map((c) => c.y + c.h));
+    const near = (a, b, span) => Math.abs(a - b) <= Math.max(4, 0.12 * span);
+    const left = x0 - p.x, right = p.x + p.w - x1;
+    const top = y0 - p.y, bottom = p.y + p.h - y1;
+    if ([left, right, top, bottom].some((v) => v < 0)) continue;
+    // Native text uses the same content rectangle, not the entire parent. A
+    // block that sits in the middle of its box within the reading's
+    // tolerance IS centred there: the few pixels the reader drifted do not
+    // become asymmetric padding.
+    // A round shape, pill or badge holding nothing but its words (a badge's
+    // digit) holds them in its middle, however far the reading drifted.
+    const round = (fixedAspect(p) || p.shape === "pill" || p.kind === "badge") && !others.length;
+    // The seat the reader declared for the words decides where they sit
+    // (seat.mjs); the measured margins stand in only where none was declared.
+    const seat = seatOf(lines[0]);
+    const declared = seat && lines.every((c) => JSON.stringify(seatOf(c)) === JSON.stringify(seat)) ? seat : null;
+    const centred = declared ? declared.x === "center" && ["middle", "span"].includes(declared.y) : (near(left, right, p.w) && near(top, bottom, p.h)) || round;
+    p.textInsets = centred ? { left: 0, right: 0, top: 0, bottom: 0 } : { left, right, top, bottom };
+    // The horizontal alignment is the reader's word, never measured margins;
+    // a round shape, pill or badge holds its words in its middle.
+    p.align = round ? "center" : declared ? { left: "left", center: "center", right: "right", span: "center" }[declared.x] ?? lines[0].align ?? "left" : lines[0].align ?? (centred ? "center" : "left");
+    p.valign = declared ? { top: "top", middle: "middle", bottom: "bottom", span: "middle" }[declared.y] ?? "middle" : centred || near(top, bottom, p.h) ? "middle" : top <= bottom ? "top" : "bottom";
+    // Folding hands the words the whole box to lay out in. That is safe when
+    // nothing else is in there, and when something is — an icon above them —
+    // only if the words are centred, because a block pinned to one edge would
+    // be dragged across whatever shares the box.
+    if (others.length && p.align !== "center") continue;
+    p.text = lines.map((c) => String(c.text)).join("\n");
+    p.role = role;
+    p.weight = weight;
+    p.color = lines[0].color ?? p.color;
+    p.colorHex = lines[0].colorHex ?? null;
+    p.colorToken = lines[0].colorToken ?? null;
+    if ("ground" in lines[0]) p.ground = lines[0].ground;
+    if ("groundHex" in lines[0]) p.groundHex = lines[0].groundHex;
+    for (const c of lines) folded.add(c.id);
+  }
+  if (!folded.size) return elements;
+  return elements.filter((e) => !folded.has(e.id));
+}
+
+
+
+// Text blocks (title + body, the pieces of a sentence) fold in text-blocks.mjs.
+export { foldTextBlocks } from "./text-blocks.mjs";
+
+export { canonicalLayoutName, contentSlotFromLayoutSource, foldLayoutName } from "./layout-names.mjs";
+export { layoutSlotNote, plannedLayoutSlot, specAuthorNotes, unplacedUseNotes, unresolvedUseNote } from "./slide-prep.mjs";
+
+// The spec is a machine intermediate, not a document: it lives under the
+// deck's state/, nobody edits it, and the slide JSX is the only thing a
+// person or an agent touches (2026-09-20: the `.spec.txt` outline and the
+// spec-editing workflow were retired — "the output thrice").
+export function specFileFor(deckDir, slideNumber) {
+  return path.join(deckDir, "state", "concept-specs", `concept-slide-${String(slideNumber).padStart(2, "0")}.json`);
+}
+
+export function readSpec(deckDir, slideNumber) {
+  const candidates = [
+    specFileFor(deckDir, slideNumber),
+    // Decks specced before the move kept it next to the PNG.
+    path.join(deckDir, "concepts", `concept-slide-${String(slideNumber).padStart(2, "0")}.spec.json`),
+  ];
+  for (const f of candidates) {
+    try {
+      return JSON.parse(fs.readFileSync(f, "utf8"));
+    } catch {}
+  }
+  return null;
+}
+
+export function writeSpec(deckDir, slideNumber, spec) {
+  const file = specFileFor(deckDir, slideNumber);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(spec, null, 2) + "\n");
+  return file;
+}
+
+export function listSpecSlides(deckDir) {
+  const out = new Set();
+  for (const dir of [path.join(deckDir, "state", "concept-specs"), path.join(deckDir, "concepts")]) {
+    try {
+      for (const f of fs.readdirSync(dir)) {
+        const m = /^concept-slide-(\d+)(?:\.spec)?\.json$/.exec(f);
+        if (m) out.add(Number(m[1]));
+      }
+    } catch {}
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
+// The spec's counts as the draft check's expectation: `{ arrows, charts, icons }`.
+export function expectedCountsFromSpec(spec) {
+  const normalized = spec?.elements ? structuredClone(spec) : spec;
+  if (normalized?.elements) applyLines(normalized);
+  const c = normalized?.counts;
+  if (!c) return null;
+  const elements = normalized.elements ?? [];
+  const kept = new Set(foldListMarkers(structuredClone(elements), normalized.connectors ?? [], normalized.repeats ?? []).map((e) => e.id));
+  // Only the icons the list fold took in come off the icon count; a dot drawn
+  // as a disc was never one.
+  const foldedIcons = elements.filter((e) => e.kind === "icon" && !kept.has(e.id)).length;
+  // A chart-like illustration without readable numbers is NOT an obligation
+  // to fabricate a native chart. This is the same eligibility test the writer
+  // uses before replacing the observed marks.
+  const charts = elements.filter(e => e.kind === "chart" && e.w > 0 && e.h > 0 && nativeChartData(e.chart)).length;
+  // Marks the transcriber draws rather than fetches or glues are shapes, not
+  // icons or connectors, in the render.
+  const drawnMarks = elements.filter((e) => e.kind === "icon" && glyphMarkOf(e.icon?.query, e.icon?.keywords ?? [])).length;
+  // A link the reader listed twice is drawn once. `arrows` counts headed
+  // connectors only (applyLines), so only headed repeats come off it.
+  const end = (id, p) => id ?? JSON.stringify(p ?? null);
+  const headed = (normalized.connectors ?? []).filter((x) => (x.arrow ?? "end") !== "none");
+  const repeats = headed.length - new Set(headed.map((x) => `${end(x.from, x.fromPoint)}>${end(x.to, x.toPoint)}`)).size;
+  return { arrows: Math.max(0, (c.arrows ?? 0) - repeats), charts, icons: Math.max(0, (c.icons ?? 0) - foldedIcons - drawnMarks) };
+}
+
+const q = (s) => JSON.stringify(s);
+
+// One line per element, children indented under their parent — what the agent
+// reads instead of the picture. Geometry is slot pixels, origin top-left of
+// the content slot; every token in the line maps onto a JSX attribute.
+export function specOutline(spec, { slide } = {}) {
+  const lines = [];
+  lines.push(
+    `slide ${slide ?? "?"} · content slot ${spec.slot.w}×${spec.slot.h}px (origin = slot top-left; the mockup's body was mapped onto it) · slide background ${spec.slideTone ?? "light"}`,
+  );
+  const ch = spec.chrome ?? {};
+  const chrome = [];
+  if (ch.kicker) chrome.push(`kicker ${q(ch.kicker)}`);
+  if (ch.headline) chrome.push(`headline ${q(ch.headline)}`);
+  if (ch.footer) chrome.push(`footer ${q(ch.footer)}`);
+  lines.push(`chrome (layout props): ${chrome.join(" · ") || "none read"}`);
+  lines.push("");
+  lines.push("id  kind fill shape [shadow]  @ x,y wxh  text role weight tone align  [fillToken colorToken]  [icon:query colour | image:query | asset-use:useid | chart]");
+  const byParent = new Map();
+  for (const e of spec.elements ?? []) {
+    const k = e.parent ?? "";
+    if (!byParent.has(k)) byParent.set(k, []);
+    byParent.get(k).push(e);
+  }
+  const fmt = (e) => {
+    const parts = [e.id, e.kind];
+    if (e.fill && e.fill !== "none") parts.push(e.fill);
+    if (e.shape && e.shape !== "rect") parts.push(e.shape);
+    if (e.elevated) parts.push("shadow");
+    parts.push(`@ ${e.x},${e.y} ${e.w}x${e.h}`);
+    const text = cleanText(e.text, { printed: textIsPrinted(e) });
+    // A text block: its paragraphs in order, each with its own role; a list
+    // item is named by its marker (the design draws the glyph).
+    if (e.paragraphs?.length) parts.push(`block[${e.paragraphs.map((p) => [p.marker ? `${p.marker}-item` : null, q(p.text), p.role, p.weight === "bold" ? "bold" : null].filter(Boolean).join(" ")).join(" | ")}]`);
+    else if (text != null) parts.push(e.marker ? `${e.marker}-item ${q(text)}` : q(text));
+    if (e.leadIn) parts.push(`lead-in:${q(e.leadIn)}`);
+    if (e.role && !e.paragraphs?.length) parts.push(e.role);
+    if (e.weight === "bold" && !e.paragraphs?.length) parts.push("bold");
+    if (e.color) parts.push(e.color);
+    if (e.align && e.align !== "left") parts.push(e.align);
+    for (const key of ["fillToken", "colorToken"]) if (e[key]) parts.push(`${key}:${q(e[key])}`);
+    // A bound original is named by the use id the slide's `data-asset-use` must
+    // carry — never by a search query, which it does not have.
+    if (e.image?.assetUseId) parts.push(`asset-use:${q(e.image.assetUseId)}`);
+    else if (e.image?.query) parts.push(`image:${q(e.image.query)}`);
+    if (e.icon) parts.push(`icon:${q(e.icon.query)} ${e.icon.color}`);
+    if (e.points?.length) parts.push(`points:${e.points.map((p) => `${p.x},${p.y}`).join(" ")}`);
+    if (e.geometry) parts.push(`geometry:${JSON.stringify(e.geometry)}`);
+    if (e.chart) {
+      const series = (e.chart.series ?? [])
+        .map((s) => `${q(s.name)}=[${(s.values ?? []).join(",")}]`)
+        .join(" ");
+      parts.push(
+        `chart:${e.chart.type} categories=[${(e.chart.categories ?? []).map(q).join(",")}] ${series} labels=[${(e.chart.labels ?? []).map(q).join(",")}]` +
+          (e.chart.type === "waterfall" ? ` totals=[${(e.chart.totals ?? []).join(",")}]${e.chart.connectors ? " connectors" : ""}` : "") +
+          (holeIds(e).length ? ` hole=[${holeIds(e).join(",")}]` : ""),
+      );
+    }
+    return parts.join("  ");
+  };
+  const seen = new Set();
+  const emit = (parentKey, depth) => {
+    for (const e of byParent.get(parentKey) ?? []) {
+      if (seen.has(e.id)) continue;
+      seen.add(e.id);
+      lines.push(`${"  ".repeat(depth)}${fmt(e)}`);
+      emit(e.id, depth + 1);
+    }
+  };
+  emit("", 0);
+  // Elements whose parent chain never reaches a root (defensive).
+  for (const e of spec.elements ?? []) if (!seen.has(e.id)) lines.push(fmt(e));
+  lines.push("");
+  const cons = spec.connectors ?? [];
+  lines.push(
+    cons.length
+      ? `connectors (${cons.length}): ${cons
+          .map((c) => `${c.from ?? `(${Math.round(c.fromPoint?.x)},${Math.round(c.fromPoint?.y)})`} -> ${c.to ?? `(${Math.round(c.toPoint?.x)},${Math.round(c.toPoint?.y)})`} ${c.route} arrow=${c.arrow} ${c.style} ${c.color}`)
+          .join(" · ")}`
+      : "connectors: none",
+  );
+  const c = spec.counts ?? {};
+  lines.push(
+    `counts: cards=${c.cards ?? 0} icons=${c.icons ?? 0} arrows=${c.arrows ?? 0} charts=${c.charts ?? 0} elements=${c.elements ?? 0}`,
+  );
+  if (spec.repeats?.length) lines.push(`repeats: ${spec.repeats.map((g) => `${g.members.map((m) => (Array.isArray(m) ? `(${m.join(" + ")})` : m)).join(", ")} (${g.arrangement}${g.hub ? ` around ${g.hub}` : ""})`).join(" · ")} — each set is one organism: one size, one inner layout`);
+  if (spec.notes?.length) lines.push(`notes: ${spec.notes.join(" · ")}`);
+  lines.push(`END OF SPEC — ${spec.elements?.length ?? 0} elements, ${spec.connectors?.length ?? 0} connectors. Full JSON remains authoritative for all fields.`);
+  return lines.join("\n") + "\n";
+}