slidemind 0.3.19 → 0.4.0

package/src/builders/transcribe.mjs

@@ -0,0 +1,1069 @@
+// Transcribe a concept spec into a slide JSX skeleton — mechanically.
+//
+// The spec (src/builders/concept-spec.mjs) is the add-in's vision inventory of
+// a mockup: every element with its rect in content-slot pixels, verbatim text,
+// role, fill, icon query, chart series, and every connector between ids. Each
+// line becomes one element here; nothing is regrouped, merged or dropped. The
+// agent's job starts AFTER this file exists: icons (the fetcher writes the
+// paths this skeleton already references), the residual defects view-draft
+// measures, and the side-by-side check against the PNG. Sims 2026-09-18/19
+// showed that a coding agent transcribing by hand loses elements at the first
+// write; a generator does not.
+//
+// Pure: no I/O. `scaffoldSlideJsx(spec, opts)` → JSX source.
+import { cleanText, dropChartMarks, dropStandIns, foldLabelsIntoShape, foldTextBlocks, textIsPrinted } from "./concept-spec.mjs";
+import { paragraphIndent } from "./text-blocks.mjs";
+import { bulletItems, textLines } from "./concept-text.mjs";
+import { paintOrdered, seatedAssets, textFrame } from "./concept-layout.mjs";
+import { applySeats } from "./seat.mjs";
+import { applyStacks, gridStacks, remapGrids, remapStacks } from "./stack.mjs";
+import { contrastRatio, hexToRgb, paletteRoles, deltaE, rankTokens, typeLadder } from "./design-tokens.mjs";
+import { chartJsx } from "./chart-jsx.mjs";
+import { centreHoles } from "./chart-hole.mjs";
+import { foldChartLabels } from "./chart-labels.mjs";
+import { geometryPath, nativeChartData, reconcileArc, repairCommands, scaleGeometry, writtenTop } from "./concept-geometry.mjs";
+import { applyLines, readLines, LINE_TOL } from "./concept-lines.mjs";
+import { illustrationOwner as plotOwner } from "./concept-relationships.mjs";
+import { strokeTraces } from "./line-fit.mjs";
+import { alignRails, bandNative, capAttr, chainNative, fitNative, lineDirective, loopCircles, nativePoints, nodePreset, ringNative, weightClass, LINE_WEIGHT_RUNGS_PX } from "./line-native.mjs";
+import { capRoutePx, headRoutePx, runsClear, seatLines, stretched } from "./placement.mjs";
+import { foldListMarkers } from "./concept-lists.mjs";
+import { LIST_HELPER, RUN_HELPER, blockChildren, markerAttrs, wrapRuns } from "./list-jsx.mjs";
+import { ICON_HELPER, KIT, KIT_EXTRAS, PARAGRAPH_HELPER } from "./kit-helpers.mjs";
+import { ICON_STYLE_WORDS, nameWords, glyphMarkOf, glyphMarkStrokes } from "./concept-marks.mjs";
+import { expandSketch, figureJsxAttrs, fitFigureToSlot } from "./figure-sketch.mjs";
+import { buildRepeats, remapRepeats, repeatGroups } 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 presets the exporter derives from a box's own border radius (contract E1).
+
+export { glyphMarkOf } from "./concept-marks.mjs";
+export { bulletItems, textLines, LIST_HELPER, ICON_HELPER, KIT, PARAGRAPH_HELPER };
+
+// An observed colour closer than this to a design token IS that token; beyond
+// it the design has no such colour (a green status dot on a blue/grey
+// palette) and the tone word decides — reported, never invented as raw hex.
+
+const q = (s) => JSON.stringify(String(s));
+// Roles set on the ramp's heading rungs (--fs-h3 bold and up): WCAG large text.
+const LARGE_ROLES = new Set(["number"]);
+// JSX text: braces and angle brackets are syntax, `\n` in the spec is the
+// image's own wrapping (the box width reproduces it).
+const escapeJsx = (s) =>
+  String(s)
+    .replace(/&/g, "&")
+    .replace(/[{}<>]/g, (c) => ({ "{": "&#123;", "}": "&#125;", "<": "&lt;", ">": "&gt;" })[c]);
+// The spec's `\n` is where the image breaks the line (concept-text.mjs textLines).
+const jsxText = (s) => textLines(s).map(escapeJsx).join("<br />");
+
+// The layout's chrome props from its `// PLACEHOLDERS: {...}` header: the
+// headline prop (role "headline"), the kicker prop (type "title"), and every
+// other chrome prop, which the skeleton leaves empty.
+/** The layout's own background colour, as its PLACEHOLDERS header states it. */
+export function layoutBackgroundHex(layoutSource) {
+  const m = /^\/\/\s*PLACEHOLDERS:\s*(\{.*\})\s*$/m.exec(layoutSource ?? "");
+  if (!m) return null;
+  try {
+    const hex = JSON.parse(m[1])?.background?.hex;
+    return hexToRgb(hex) ? hex : null;
+  } catch {
+    return null;
+  }
+}
+
+export function layoutChromeProps(layoutSource) {
+  const m = /^\/\/\s*PLACEHOLDERS:\s*(\{.*\})\s*$/m.exec(layoutSource ?? "");
+  const out = { headline: null, kicker: null, others: [] };
+  if (!m) return out;
+  let ph;
+  try {
+    ph = JSON.parse(m[1]);
+  } catch {
+    return out;
+  }
+  for (const c of ph.chrome ?? []) {
+    if (!c?.prop) continue;
+    if (c.role === "headline" && !out.headline) out.headline = c.prop;
+    else if (c.type === "title" && !out.kicker) out.kicker = c.prop;
+    else out.others.push(c.prop);
+  }
+  return out;
+}
+
+
+/** A use's normalized `{x, y}` fractions as an `object-position` value. */
+export const positionValue = (p) =>
+  `${Math.round((p?.x ?? 0.5) * 1000) / 10}% ${Math.round((p?.y ?? 0.5) * 1000) / 10}%`;
+
+/**
+ * The approved source region in the two forms one picture needs: the
+ * exporter's `<a:srcRect>` (OOXML 100000ths, `"l,t,r,b"`) and the browser's
+ * `object-view-box` inset — the same four numbers, so preview and export crop
+ * the same pixels. Null when the use asks for no crop.
+ */
+export function cropAttrs(crop) {
+  if (!crop) return null;
+  const k = (v) => Math.max(0, Math.min(100000, Math.round(v * 100000)));
+  const sides = [k(crop.x), k(crop.y), k(1 - (crop.x + crop.w)), k(1 - (crop.y + crop.h))];
+  const [l, t, r, b] = sides;
+  const pct = (v) => `${Math.round(v / 10) / 100}%`;
+  return { crop: sides.join(","), view: `inset(${pct(t)} ${pct(r)} ${pct(b)} ${pct(l)})` };
+}
+
+// The rung of the slide's ladder each role sets on.
+const ROLE_STEP = { subtitle: "body", section: "body", title: "body", body: "body", label: "small", caption: "small", badge: "small", number: "number" };
+/** KIT's ROLE block on the slide's ladder; the KIT's own map without a ramp. */
+const roleLadder = (block, ladder) => (ladder
+  ? block.replace(/(\n\s+(\w+): \{ fontSize: )"var\(--fs-[\w-]+\)"/g, (m, head, role) => (ROLE_STEP[role] ? `${head}"var(${ladder[ROLE_STEP[role]]})"` : m))
+  : block);
+
+/**
+ * One spec → one slide file. `slide` is the slide number (icon file names are
+ * `NN-<icon id>.svg`), `layout` the component name, `layoutSource` its JSX
+ * (for the chrome prop names). Returns `{ jsx, icons, warnings }` — `icons`
+ * is the fetcher's list: `{ id, file, query, color, colorHex }`.
+ *
+ * `normalize: false` for a re-scaffold after a settle pass: the row/centre
+ * normalizers below read the ORIGINAL image's intent, and re-running them on a
+ * spec the settle loop just moved snaps every member of a row back to the row
+ * median — a shift under 8% of the card height disappears entirely, so the
+ * overlap the pass measured ships anyway while `SETTLED: n changes` reports it
+ * as fixed.
+ *
+ * `bound` is `Map<useId, resolved>` — the deck's approved image uses already
+ * resolved to verified bytes (src/builders/spec-assets.mjs →
+ * `resolveBoundImageUses`). An image element that names one is placed from it
+ * and is left OUT of `icons`: the engine is never asked for a picture the user
+ * already supplied. Pure either way — the resolution happened in the caller.
+ */
+// The kinds a sketched figure may replace (never text, icons, images, charts, discs).
+const FIGURE_KINDS = new Set(["path", "shape", "panel", "card", "badge", "bar"]);
+
+/** Every colour a spec's reference paints (any `…Hex` field), as a palette. */
+function referencePalette(spec) {
+  const seen = new Map();
+  const walk = (v, key) => {
+    if (typeof v === "string") {
+      const rgb = key.endsWith("Hex") ? hexToRgb(v) : null;
+      const hex = rgb && `#${rgb.map((c) => c.toString(16).padStart(2, "0")).join("").toUpperCase()}`;
+      if (hex) seen.set(hex, { name: hex, hex, rgb });
+    } else if (v && typeof v === "object") {
+      for (const [k, c] of Object.entries(v)) walk(c, Array.isArray(v) ? key : k);
+    }
+  };
+  walk(spec, "");
+  return [...seen.values()];
+}
+
+export function scaffoldSlideJsx(spec, { slide, layout, layoutSource = "", tokens = [], ramp = null, contrastFloor = 4.5, normalize = true, bound = new Map(), literal = false }) {
+  // A whole-slide reconstruction is faithful to its reference, not to the
+  // design's token ladder (workflow/create.md): its palette is the colours the
+  // reference paints, written as those literal values.
+  if (literal) tokens = referencePalette(spec);
+  const nn = String(slide).padStart(2, "0");
+  const chrome = layoutChromeProps(layoutSource);
+  let byId = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  const lines = [];
+  const icons = [];
+  const warnings = applyLines(spec);
+  // The ids this skeleton deliberately leaves out, each also named in
+  // `warnings`: preservation seeding releases exactly these (edit-state.mjs).
+  const dropped = [];
+  const illustrationOwner = (e) => plotOwner(spec.elements ?? [], e);
+  const unmatched = new Map();
+  // The design's palette is authoritative: an observed colour becomes the
+  // design colour it perceptually IS (CIEDE2000 —
+  // the mockup's green is the design's green, its near-black navy is the
+  // design's ink). A colour far from every design colour is still drawn in
+  // the nearest one and named in a note.
+  const ref = (t) => (t.name.startsWith("#") ? t.name : `var(${t.name})`);
+  const tokenByVar = (v) => tokens.find((t) => ref(t) === v) ?? null;
+  const snapVar = (hex, prefer = /^--fg-/) => {
+    if (!hex || !tokens.length) return null;
+    const best = rankTokens(hex, tokens, { prefer })[0];
+    if (!best) return null;
+    // Far from every design colour: the reader's tone word (its role —
+    // accent, muted, dark) decides, and the colour is named in a note.
+    if (best.d > 20) {
+      if (!unmatched.has(hex)) unmatched.set(hex, best.t.name);
+      return null;
+    }
+    return ref(best.t);
+  };
+  const roles = paletteRoles(tokens);
+  // A reconstruction's palette has no semantic names, so no token is the
+  // accent: take the reference's most chromatic colour (its ink when it has
+  // none), or an accent with no hex of its own would paint nothing.
+  if (literal && !roles.tone.accent) {
+    const chroma = (t) => Math.max(...t.rgb) - Math.min(...t.rgb);
+    const vivid = [...tokens].sort((a, b) => chroma(b) - chroma(a))[0];
+    roles.tone.accent = roles.fill.accent = vivid && chroma(vivid) >= 40 ? vivid : roles.tone.dark;
+  }
+  const variable = (t) => t ? ref(t) : null;
+  const hexOf = new Map(tokens.map((t) => [variable(t), t.hex]));
+  const layoutBgHex = layoutBackgroundHex(layoutSource);
+  // The reader is shown this design's palette and may name the colour it
+  // means (`fillToken` / `colorToken`). A name this bundle lists is used when
+  // it is a plausible reading of the colour the image shows.
+  const palette = new Map(tokens.map((t) => [t.name, t]));
+  const namedVar = (name, observed = null) => {
+    if (typeof name !== "string" || !palette.has(name)) return null;
+    const d = observed ? deltaE(observed, palette.get(name).hex) : null;
+    return d == null || d <= 15 ? `var(${name})` : null;
+  };
+  // What a figure sits on in the image: the smallest painted element that
+  // contains it. Geometry, not the reader's parent or paint order.
+  const groundOf = (e) => (spec.elements ?? []).filter((p) => p !== e && p.fill && p.fill !== "none" && p.fillHex
+      && p.x <= e.x + 1 && p.y <= e.y + 1 && p.x + p.w >= e.x + e.w - 1 && p.y + p.h >= e.y + e.h - 1 && p.w * p.h > e.w * e.h)
+    .sort((a, b) => a.w * a.h - b.w * b.h)[0] ?? null;
+  // A fill is a design token: the reader's named token, else the token of its
+  // fill role, else the nearest token to what the image shows. Where the
+  // image draws the figure apart from its ground (or a clipped silhouette
+  // carries a shadow that never renders), it may not land on the ground's own
+  // colour: the next token that differs from the ground is taken.
+  const SILHOUETTES = new Set(["chevron", "triangle", "trapezoid", "arrow", "diamond", "hexagon", "pentagon", "parallelogram"]);
+  const silhouette = (e) => SILHOUETTES.has(e.shape) || (e.shape === "other" && Array.isArray(e.outline) && e.outline.length >= 3);
+  const fillMemo = new Map();
+  const fillVarOf = (e) => {
+    if (!e.fill || e.fill === "none") return null;
+    if (fillMemo.has(e.id)) return fillMemo.get(e.id);
+    fillMemo.set(e.id, null);
+    let pick = null;
+    if (e.fillHex && tokens.length) {
+      const named = namedVar(e.fillToken, e.fillHex);
+      const all = rankTokens(e.fillHex, tokens, { prefer: /^--bg-/ });
+      if (all[0]?.d > 20 && !unmatched.has(e.fillHex)) unmatched.set(e.fillHex, all[0].t.name);
+      const role = tokenByVar(variable(roles.fill[e.fill]));
+      const ranked = [...(named ? [tokenByVar(named)] : []), ...(role ? [role] : []), ...all.map((v) => v.t)];
+      const ground = groundOf(e);
+      const seenGround = ground ? ground.fillHex : layoutBgHex;
+      const paintedGround = ground ? paintHexOf(ground) : layoutBgHex;
+      const apartInImage = (seenGround && (deltaE(e.fillHex, seenGround) ?? 0) >= 3) || (e.elevated && silhouette(e));
+      const apart = (t) => !apartInImage || !paintedGround || (deltaE(t.hex, paintedGround) ?? Infinity) >= 3;
+      const t = ranked.find(apart) ?? ranked[0];
+      if (t && t !== ranked[0]) warnings.push(`${e.id}: ${ranked[0].name} would merge into the colour under it; ${t.name} keeps it apart as the image does`);
+      pick = t ? ref(t) : null;
+    }
+    pick ??= variable(roles.fill[e.fill]);
+    fillMemo.set(e.id, pick);
+    return pick;
+  };
+  // The paint of a drawn FIGURE (a silhouette, a sector): its fill only. A
+  // stroke is never svg — an outline the reader saw on a figure is named.
+  const svgPaint = (e) => {
+    if (e.stroke && Number(e.stroke.width) > 0) warnings.push(`${e.id}: a drawn figure's outline is not written (a stroke is a native line, never svg); outline it by hand if the concept needs it`);
+    return `fill=${fillVarOf(e) ? q(fillVarOf(e)) : `{FILL[${q(e.fill)}]}`}`;
+  };
+  // Check the emitted fill, not the model's unsnapped colour or a guessed
+  // palette extreme. Unknown backgrounds remain unknown and are reported.
+  const groundHexOf = (e) => {
+    let p = e;
+    const seen = new Set();
+    while (p && !seen.has(p.id)) {
+      seen.add(p.id);
+      if (p.fill && p.fill !== "none") return paintHexOf(p);
+      p = byId.get(p.parent);
+    }
+    const under = (spec.elements ?? []).filter((p) => p.id !== e.id && p.fill && p.fill !== "none"
+      && p.x <= e.x && p.y <= e.y && p.x + p.w >= e.x + e.w && p.y + p.h >= e.y + e.h)
+      .sort((a, b) => a.w * a.h - b.w * b.h)[0];
+    return under ? paintHexOf(under) : layoutBgHex;
+  };
+  // The colour a fill actually paints.
+  function paintHexOf(e) {
+    return hexOf.get(fillVarOf(e)) ?? null;
+  }
+  // The paint of an item's marker, when the reader named one (the concept's
+  // accent dots): a design colour, else nothing — the brand's marker applies.
+  const markerVar = (e) => (e.markerToken || e.markerHex ? namedVar(e.markerToken, e.markerHex) ?? snapVar(e.markerHex) : null);
+  const textPaint = (e, floor = contrastFloor) => {
+    // The reader's own pick, when it named one this palette lists.
+    const chosen = namedVar(e.colorToken, e.colorHex);
+    const colorVar = chosen
+      ?? snapVar(e.colorHex)
+      ?? variable(roles.tone[e.color ?? "dark"]);
+    const groundHex = groundHexOf(e);
+    if (!groundHex) {
+      if (tokens.length) warnings.push(`${e.id}: background colour unknown; contrast not verified`);
+      return { colorVar, tone: e.color };
+    }
+    const ratio = contrastRatio(hexOf.get(colorVar), groundHex);
+    if (ratio != null && ratio >= floor) return { colorVar, tone: e.color };
+    // A colour the reader CHOSE is never swapped out from under it: it judged
+    // the ground with the image in front of it, and a rule that overrules it
+    // silently is a second opinion the agent cannot see. Say so and move on.
+    if (chosen) {
+      warnings.push(
+        `${e.id}: the spec paints this text ${e.colorToken} on its background — ${ratio == null ? "contrast unknown" : `${ratio.toFixed(1)}:1`}, below ${floor}:1; change the colour in the JSX if the mockup disagrees`,
+      );
+      return { colorVar: chosen, tone: e.color };
+    }
+    // A deliberate colour — the image paints the words in a hue (a green
+    // gain, a red loss) and the design has that hue — is colour coding, not a
+    // readability accident: the design's own colour stays and the contrast is
+    // reported. Only neutral text is swapped for a more legible neutral.
+    const rgbSeen = hexToRgb(e.colorHex), rgbToken = hexToRgb(hexOf.get(colorVar));
+    const chroma = (c) => (c ? Math.max(...c) - Math.min(...c) : 0);
+    if (chroma(rgbSeen) >= 60 && chroma(rgbToken) >= 60 && (deltaE(hexOf.get(colorVar), groundHex) ?? 0) >= 25) {
+      warnings.push(`${e.id}: colour-coded text in ${colorVar.replace(/^var\((.*)\)$/, "$1")} on its background — ${ratio == null ? "contrast unknown" : `${ratio.toFixed(1)}:1`}, below ${floor}:1; kept, as the design's colour for what the image codes`);
+      return { colorVar, tone: e.color };
+    }
+    // No choice was made, so this colour is OUR match of an observed hex and
+    // repairing it is fair game.
+    const ranked = tokens.map((t) => ({ t, ratio: contrastRatio(t.hex, groundHex) }))
+      .filter((v) => v.ratio != null).sort((a, b) => b.ratio - a.ratio);
+    const best = ranked[0];
+    if (!best || best.ratio < floor) warnings.push(`${e.id}: palette cannot meet contrast ${floor}:1 on its rendered background`);
+    return { colorVar: best ? variable(best.t) : colorVar, tone: e.color };
+  };
+  const maps = (entries) => Object.fromEntries(Object.entries(entries).map(([k, t]) => [k, variable(t) ?? "inherit"]));
+  const kit = KIT.replace(/const FILL = .*?;/, `const FILL = ${JSON.stringify({ ...maps(roles.fill), none: "transparent" })};`)
+    .replace(/const TONE = .*?;/, `const TONE = ${JSON.stringify(maps(roles.tone))};`)
+    .replace(/const ROLE = \{[\s\S]*?\n  \};/, (block) => roleLadder(block, typeLadder(ramp, spec.typeStepOffset ?? 0)));
+  const slot = spec.slot;
+  // Also for a spec written before the read learned these: the model's
+  // stand-ins on painted boxes.
+  // A chart draws its own marks; anything inside its rect would be painted
+  // over the native chart a second time.
+  const read = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  spec.elements = dropChartMarks(spec.elements ?? []);
+  if (!ablated("foldListMarkers")) spec.elements = foldListMarkers(spec.elements, spec.connectors ?? [], spec.repeats ?? []);
+  // A chart's own legend and labels drawn beside it go back into the chart.
+  foldChartLabels(spec, warnings);
+  if (!ablated("dropStandIns")) dropStandIns(spec.elements ?? []);
+  if (normalize) {
+  }
+  // Folding drops the children it absorbed, so the index and any connector
+  // that named one have to follow it. Only those: a connector pointing at an
+  // element that never existed is the spec talking, and it still gets reported.
+  const beforeFold = new Set((spec.elements ?? []).map((e) => e.id));
+  if (!ablated("foldLabelsIntoShape")) spec.elements = foldLabelsIntoShape(spec.elements ?? [], { connectors: spec.connectors ?? [] });
+  // A block that still cannot be one text says so (text-blocks.mjs).
+  spec.elements = foldTextBlocks(spec.elements ?? [], { connectors: spec.connectors ?? [], notes: warnings });
+  byId = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  const absorbed = new Set([...beforeFold].filter((id) => !byId.has(id)));
+  spec.connectors = (spec.connectors ?? []).filter((c) => !absorbed.has(c.from) && !absorbed.has(c.to));
+  // Repeated organisms the reader declared: one template, one exact
+  // arrangement (repeat-groups.mjs) — before any line is fitted to the nodes.
+  if (normalize) {
+    warnings.push(...remapRepeats(spec, read), ...buildRepeats(spec).filter((n) => n.endsWith("kept as drawn")));
+    // A seated child keeps its seat in the template's size (seat.mjs), what
+    // stands in a doughnut's hole stays centred in its ring (chart-hole.mjs); a
+    // declared stack is laid out over the built members (stack.mjs).
+    applySeats(spec);
+    centreHoles(spec);
+    warnings.push(...remapStacks(spec, read), ...remapGrids(spec, read));
+    applyStacks(spec);
+  }
+
+  // What each id is in a declared stack (stack.mjs): "n:r" a part of row r,
+  // "n:gr" drawn in the gap under row r. Written onto the lines as `stack` /
+  // `data-sm-stack`, so every later reader and writer of the JSX keeps the
+  // rows together (settle.mjs parseTranscribedJsx rebuilds the stacks from it).
+  const stackMark = new Map();
+  (spec.stacks ?? []).forEach((g, gi) => {
+    g.rows.forEach((row, ri) => { for (const id of row) stackMark.set(id, `${gi + 1}:${ri + 1}`); });
+    for (const it of g.band?.between ?? []) stackMark.set(it.id, `${gi + 1}:g${it.gap + 1}:${Math.round((it.frac ?? 0.5) * 100) / 100}`);
+  });
+  // A grid's own divider (across its columns): "G<k>:g<r>:<f>" — GRIDS names the member stacks.
+  (spec.grids ?? []).forEach((grid, ki) => {
+    for (const it of grid.band?.between ?? []) stackMark.set(it.id, `G${ki + 1}:g${it.gap + 1}:${Math.round((it.frac ?? 0.5) * 100) / 100}`);
+  });
+  const gridsConst = (spec.grids ?? []).length
+    ? `  const GRIDS = ${JSON.stringify(Object.fromEntries((spec.grids ?? []).map((grid, ki) => [ki + 1, { stacks: gridStacks(spec, grid).map((g) => (spec.stacks ?? []).indexOf(g) + 1), rows: grid.rows }])))};\n`
+    : "";
+  const stackAttr = (id) => (stackMark.has(id) ? ` stack=${q(stackMark.get(id))}` : "");
+  // A divider between two paragraphs of one block: "block:after:frac" (block-dividers.mjs).
+  const divideMark = new Map();
+  for (const e of spec.elements ?? []) for (const d of e.dividers ?? []) divideMark.set(d.id, `${e.id}:${d.after}:${Math.round(d.frac * 100) / 100}`);
+  // ---- Every line, as ONE native object (line-native.mjs), decided before
+  // any element is written: a node a line glues to carries its preset, and an
+  // element a line stands for — a rule, a ring, a mark, a plot stroke, the
+  // arrowhead or end dot that became its cap — is written as the line only.
+  const { lines: readIn } = readLines(spec);
+  // The line id each connector is written under, from the list THIS skeleton
+  // read (`readLines` returns the connectors' lines first, in order): a spec
+  // index read elsewhere drifts once normalization filtered a connector out.
+  const connectorLines = (spec.connectors ?? []).map((c, i) => ({ id: readIn[i].id, from: c.from ?? null, to: c.to ?? null }));
+  // The reader connector a line was read from (its declared ids and width).
+  const rawConnector = (line) => (line.source?.kind === "connector" ? spec.connectors?.[line.source.index] ?? null : null);
+  const consumed = new Set(readIn.filter((l) => l.source?.kind !== "connector").map((l) => l.source.id));
+  const plotOf = new Map();
+  const dashOf = (d) => (d === "dashed" ? "dash" : d === "dotted" ? "sysDot" : "solid");
+  const drawnLines = [];
+  for (const e of spec.elements ?? []) {
+    if (consumed.has(e.id)) continue;
+    const owner = illustrationOwner(e);
+    // Rules (whatever words the reader put on one) and the strokes of a kept
+    // illustration: the lines the intake leaves to the writer.
+    const traces = e.kind === "rule" && (e.w > 0 || e.h > 0)
+      ? [e.w >= e.h ? [{ x: e.x, y: e.y + e.h / 2 }, { x: e.x + e.w, y: e.y + e.h / 2 }] : [{ x: e.x + e.w / 2, y: e.y }, { x: e.x + e.w / 2, y: e.y + e.h }]]
+      : owner ? strokeTraces(e) : [];
+    if (!traces.length) continue;
+    consumed.add(e.id);
+    if (owner) plotOf.set(e.id, owner.id);
+    traces.forEach((t, k) => drawnLines.push({
+      id: traces.length > 1 ? `${e.id}-${k + 1}` : e.id,
+      role: owner ? "plot" : "divider",
+      source: { kind: e.kind === "rule" ? "rule" : "path", id: e.id },
+      ends: [t[0], t.at(-1)].map((at) => ({ node: null, at, cap: { type: "none" }, contact: "none" })),
+      path: { kind: t.length === 2 ? "straight" : "curve", points: t, corners: "sharp" },
+      stroke: { widthPx: e.stroke?.width ?? null, colorHex: e.stroke?.colorHex ?? e.colorHex ?? (e.kind === "rule" ? e.fillHex : null) ?? null, token: e.stroke?.colorToken ?? e.colorToken ?? null, dash: dashOf(e.stroke?.dash ?? e.dash) },
+      read: { color: e.color ?? null },
+    }));
+  }
+  const allLines = [...readIn, ...drawnLines];
+  // A ring stays a glue target as a line shape (it has its own sites).
+  const nodes = new Map();
+  for (const e of spec.elements ?? []) {
+    if (consumed.has(e.id) && !readIn.some((l) => l.role === "frame" && l.source.id === e.id)) continue;
+    const n = nodePreset(e);
+    if (n) nodes.set(e.id, n);
+  }
+  const loops = loopCircles(allLines, nodes);
+  const natives = [];
+  for (const line of allLines) {
+    if (line.role === "frame") {
+      const n = ringNative(line.id, byId.get(line.source.id)?.geometry);
+      if (n) natives.push({ line, n });
+      continue;
+    }
+    const n = fitNative(line, nodes, loops.get(line.id) ?? null, { slot });
+    if (!n) {
+      const c = rawConnector(line);
+      warnings.push(c ? `connector ${c.from ?? "(point)"} -> ${c.to ?? "(point)"} names an unknown element; skipped` : `line ${line.id}: an end names no element on this slide and carries no point; skipped`);
+      dropped.push(line.id);
+      continue;
+    }
+    warnings.push(...n.notes);
+    natives.push({ line, n });
+  }
+  // Elbows off one site share one rail where the concept draws them so.
+  alignRails(natives.map(({ n }) => n));
+  const glueTargets = new Set(natives.flatMap(({ n }) => [n.from?.node, n.to?.node]).filter(Boolean));
+  // Width and colour are the design's tokens: the reader's weight class and
+  // the design colour its hex snaps to — never a measured px, never a hex.
+  // They are defaults; the agent weighs lines against the slide's shapes.
+  const accentVar = variable(roles.tone.accent);
+  const CLASS_COLOR = { "connector-accent": "var(--fg-accent)", "connector-muted": "var(--fg-3)" };
+  const CLASS_WEIGHT = { "connector-accent": "medium", "connector-muted": "default" };
+  const capIds = new Set();
+  // What a line is drawn on: the smallest painted element holding all of it.
+  // null when none does — a line between drawn figures has no one ground this
+  // can name, and the gate measures it on the render instead.
+  const lineGroundHex = (line) => {
+    const pts = [...(line.ends ?? []).map((end) => end.at), ...(line.path?.points ?? [])]
+      .filter((p) => p && Number.isFinite(p.x) && Number.isFinite(p.y));
+    if (!pts.length) return null;
+    const x0 = Math.min(...pts.map((p) => p.x)), x1 = Math.max(...pts.map((p) => p.x));
+    const y0 = Math.min(...pts.map((p) => p.y)), y1 = Math.max(...pts.map((p) => p.y));
+    const holder = (spec.elements ?? []).filter((p) => p.fill && p.fill !== "none" && p.w > 0 && p.h > 0
+      && p.x <= x0 && p.y <= y0 && p.x + p.w >= x1 && p.y + p.h >= y1)
+      .sort((a, b) => a.w * a.h - b.w * b.h)[0];
+    return holder ? paintHexOf(holder) : null;
+  };
+  const linePaint = (line, n) => {
+    const st = line.stroke ?? {};
+    // The width the READER declared (null when it declared none: the design
+    // default weight).
+    const declared = st.widthPx;
+    const colorVar = namedVar(st.token, st.colorHex) ?? snapVar(st.colorHex);
+    const tone = line.read?.color ?? null;
+    const className = (colorVar ? colorVar === accentVar || colorVar === CLASS_COLOR["connector-accent"] : tone === "accent") ? "connector-accent" : "connector-muted";
+    let color = colorVar ?? (tone && tone !== "accent" && roles.tone[tone] ? variable(roles.tone[tone]) : null);
+    const style = [];
+    const weight = weightClass(declared);
+    if (weight !== "default" && weight !== CLASS_WEIGHT[className]) style.push(`borderWidth: "var(--bw-${weight})"`);
+    const dash = st.dash === "dash" || st.dash === "sysDot" ? st.dash : null;
+    const w = st.widthPx ?? LINE_TOL.defaultWidthPx;
+    // The head the route carries: the concept's size, or the largest smaller
+    // one the gate accepts on this weight. ponytail: the canonical --bw-*
+    // rungs, not the brand's px (a brand bold wider than 4px can still refuse).
+    const strokePx = LINE_WEIGHT_RUNGS_PX[weight !== "default" ? weight : CLASS_WEIGHT[className]] ?? 0;
+    const caps = (line.ends ?? []).map((end, i) => {
+      const c = end.cap;
+      if (!c || !c.type || c.type === "none") return null;
+      // A dot larger than the largest oval line end, or on a route too short
+      // for even the smallest, stays the reader's drawn dot.
+      if (c.type === "oval" && (c.sizePx > LINE_TOL.capLen.lg * w || (c.from && headRoutePx("sm", strokePx) > capRoutePx(n, i) - 0.5))) return null;
+      if (c.from) capIds.add(c.from);
+      return capAttr(c, capRoutePx(n, i), strokePx);
+    });
+    // The image draws the line apart from what it sits on; a snap onto the
+    // ground's own colour draws nothing. Keep the visibility gate's floor
+    // (diagram-geometry.ts: 1.3:1 with a head or glued end, 1.05:1 for a
+    // plain rule) with the design colour nearest the one the image shows.
+    const ground = lineGroundHex(line);
+    const strokeHex = hexOf.get(color ?? CLASS_COLOR[className]);
+    const floor = caps.some(Boolean) || n?.from?.node || n?.to?.node ? 1.3 : 1.05;
+    if (ground && strokeHex && (contrastRatio(strokeHex, ground) ?? Infinity) < floor) {
+      const alt = rankTokens(st.colorHex ?? strokeHex, tokens).map((v) => v.t).find((t) => (contrastRatio(t.hex, ground) ?? 0) >= floor);
+      if (alt) {
+        warnings.push(`${line.id ?? line.source?.id ?? "a line"}: ${color ?? CLASS_COLOR[className]} would vanish into the colour it is drawn on; ${alt.name} keeps it visible`);
+        color = ref(alt);
+      }
+    }
+    if (color && color !== CLASS_COLOR[className]) style.push(`color: ${q(color)}`);
+    return { className, style, caps, dash, linecap: dash === "sysDot" ? "rnd" : null, strokePx };
+  };
+  // A free line (no glue, not a mark or a plot stroke) is seated among the
+  // shapes it runs through (placement.mjs); every other line paints last.
+  const lineOut = natives.map(({ line, n }) => {
+    const paint = linePaint(line, n);
+    const jsx = lineDirective(n, { ...paint, plotOwner: plotOf.get(line.source?.id) ?? null, stack: stackMark.get(line.id) ?? stackMark.get(line.source?.id) ?? null, divides: divideMark.get(line.id) ?? divideMark.get(line.source?.id) ?? null });
+    const free = !n.from?.node && !n.to?.node && line.role !== "mark" && !plotOf.has(line.source?.id);
+    return free ? { jsx, points: nativePoints(n), capped: paint.caps.some(Boolean), strokePx: paint.strokePx } : { jsx };
+  });
+
+  // Drawn figures the reader sketched: one <Figure> each, compiled exactly at
+  // render (figure-sketch.mjs) — straight edges straight, arcs on their
+  // circle, copies and mirrored halves identical. A figure a line glues to
+  // keeps its preset box: a custom outline has no connection sites.
+  const sketch = spec.sketch ? expandSketch(spec.sketch) : null;
+  if (sketch) warnings.push(...sketch.issues);
+  const elementById = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  const sketched = new Map([...(sketch?.figures ?? [])].filter(([id]) => {
+    const e = elementById.get(id);
+    return e && FIGURE_KINDS.has(e.kind) && e.fill && e.fill !== "none" && !glueTargets.has(id);
+  }).map(([id, props]) => {
+    const fit = fitFigureToSlot(props, slot);
+    if (fit.moved) warnings.push(`${id}: its figure reached outside the content slot; moved in`);
+    return [id, fit.props];
+  }));
+  const figureLine = (e, fig) => {
+    const fillVar = fillVarOf(e);
+    const attrs = [`id=${q(e.id)}`, figureJsxAttrs(fig), `fill=${fillVar ? q(fillVar) : `{FILL[${q(e.fill)}]}`}`];
+    if (e.stroke && Number(e.stroke.width) > 0) {
+      const v = namedVar(e.stroke.colorToken) ?? snapVar(e.stroke.colorHex);
+      attrs.push(`stroke=${v ? q(v) : `{TONE[${q(e.color ?? "dark")}]}`}`, `strokeWidth=${q(`var(--bw-${weightClass(e.stroke.width)})`)}`);
+    }
+    return `<Figure ${attrs.join(" ")} />`;
+  };
+  const seated = ablated("seatedAssets") ? new Map() : seatedAssets(spec.elements ?? [], {
+    skip: new Set([...consumed, ...capIds, ...sketched.keys()]),
+    glued: glueTargets,
+  });
+  const isMark = (e) => e.kind === "icon" && glyphMarkOf(e.icon?.query, e.icon?.keywords ?? []) != null;
+  const assetPaint = (e) => (e.kind === "icon" ? textPaint({ ...e, color: e.icon?.color === "white" ? "light" : e.icon?.color ?? "dark" }, 3) : {});
+  // Adds an engine asset's fetch row (flat or seated) and returns its reference.
+  const requestAsset = (e, paint = assetPaint(e)) => {
+    const file = `${nn}-${e.id}.asset`;
+    icons.push({ id: e.id, kind: e.kind, file, query: e.image?.query ?? e.icon?.query ?? e.id,
+      ...(e.icon?.keywords?.length ? { keywords: e.icon.keywords } : {}),
+      color: e.icon?.color ?? "dark", colorHex: e.kind === "icon" ? hexOf.get(paint.colorVar) ?? null : null,
+      // A picture fetched from a pictogram library (no photo engine) is a
+      // line drawing in its source colour, black: tint it the design accent.
+      ...(e.kind === "image" ? { tintHex: hexOf.get(variable(roles.tone.accent)) ?? null } : {}) });
+    return `./assets/${file}`;
+  };
+
+  // Where each element's JSX starts: a free line is seated before the first
+  // painted one it runs through (placement.mjs).
+  const placed = [];
+  for (const raw of paintOrdered(spec.elements ?? [])) {
+    if (consumed.has(raw.id) || capIds.has(raw.id)) continue;
+    placed.push({ el: raw, at: lines.length });
+    // One element that cannot be written is one element reported, never a
+    // slide (or a deck) lost: x58 lost a whole deck to one malformed arc.
+    try {
+    // A text on the slot's bottom edge is written a hair higher (writtenTop).
+    const top = writtenTop(raw, slot);
+    const e = top !== raw.y ? { ...raw, y: top } : raw;
+    const text = cleanText(e.text, { printed: textIsPrinted(e) });
+    const base = `id=${q(e.id)} x={${e.x}} y={${e.y}} w={${e.w}}${stackAttr(e.id)}`;
+    // A sketched figure: the shape is the Figure; its words (a named shape's
+    // label) ride on an unpainted box at the element's rect below.
+    const fig = sketched.get(e.id);
+    if (fig) {
+      lines.push(figureLine(e, fig));
+      if (text == null || e.kind === "path") continue;
+    }
+    // The lead-in and the emphasis spans the spec folded into this text.
+    const emphasise = (body, t = e) => {
+      if (t.leadIn) {
+        const lead = escapeJsx(t.leadIn.trim());
+        if (body.startsWith(lead)) body = `<b>${lead}</b>${body.slice(lead.length)}`;
+      }
+      for (const em of t.emphasis ?? []) {
+        const needle = escapeJsx(String(em).trim());
+        if (needle && body.includes(needle) && !body.includes(`<b>${needle}</b>`)) body = body.replace(needle, `<b>${needle}</b>`);
+      }
+      // The pieces of the sentence painted otherwise: one `<R>` each (text-blocks.mjs).
+      if (t.runs?.length) {
+        const role = t.role ?? (t.kind === "number" ? "number" : "body");
+        const floorOf = (r) => (LARGE_ROLES.has(r) ? 3 : contrastFloor);
+        const own = textPaint({ ...e, ...t }, floorOf(role));
+        body = wrapRuns(body, t.runs, (run) => {
+          const runRole = run.role ?? (run.kind === "number" ? "number" : role);
+          const paint = textPaint({ ...e, ...t, ...run }, floorOf(runRole));
+          const out = runRole !== role ? [`role=${q(runRole)}`] : [];
+          if (paint.colorVar && paint.colorVar !== own.colorVar) out.push(`colorVar=${q(paint.colorVar)}`);
+          else if (!paint.colorVar && paint.tone && paint.tone !== own.tone) out.push(`tone=${q(paint.tone)}`);
+          if (run.weight === "bold" && t.weight !== "bold") out.push("bold");
+          return out;
+        }, escapeJsx);
+      }
+      return body;
+    };
+    const textEl = (id, role) => {
+      const frame = textFrame(e);
+      const attrs = [`id=${q(id)}`, `x={${frame.x}}`, `y={${frame.y}}`, `w={${frame.w}}`];
+      if (stackMark.has(e.id)) attrs.push(`stack=${q(stackMark.get(e.id))}`);
+      if (frame.rotation) attrs.push(`h={${frame.h}}`, `rotation={${frame.rotation}}`);
+      if (e.placement === "center" && e.valign === "middle") attrs.push(`h={${e.h}}`, 'valign="middle"');
+      attrs.push(`role=${q(role)}`);
+      // WCAG's large text (≥24px, or bold ≥18.67px) reads at 3:1; holding a
+      // coloured heading to 4.5:1 turned it black (2.4% of coloured texts).
+      // The heading roles sit on those rungs of the ramp.
+      const paint = textPaint(e, LARGE_ROLES.has(role) ? 3 : contrastFloor);
+      if (paint.colorVar) attrs.push(`colorVar=${q(paint.colorVar)}`);
+      // A lone list item: a list of one, never a glyph typed into a paragraph.
+      if (e.marker) {
+        if (paint.tone) attrs.push(`tone=${q(paint.tone)}`);
+        const marker = markerVar(e);
+        if (marker) attrs.push(`markerVar=${q(marker)}`);
+        return `<L ${[...attrs, ...markerAttrs(e.marker)].join(" ")}><li>${emphasise(jsxText(text))}</li></L>`;
+      }
+      // One line in the image stays one line: no wrapping into the row below —
+      // unless the settle measured that its room cannot hold it (`wrap`,
+      // settle.mjs fitTextToImage): then it wraps inside its box instead of
+      // running past it.
+      if (!String(text).includes("\n") && String(text).trim().length <= 60 && !raw.wrap) attrs.push("nowrap");
+      if (e.weight === "bold") attrs.push("bold");
+      if (paint.tone) attrs.push(`tone=${q(paint.tone)}`);
+      if (e.align && e.align !== "left") attrs.push(`align=${q(e.align)}`);
+      return `<T ${attrs.join(" ")}>${emphasise(jsxText(text))}</T>`;
+    };
+    // A text block: one T placing the block, one P per paragraph, a run of
+    // items as one L (list-jsx.mjs). Each paragraph is painted and wrapped
+    // like a T of its own role; a block that is only a list is the L itself.
+    if (e.paragraphs?.length) {
+      const frame = textFrame(e);
+      const paintOf = (para) => {
+        const role = para.role ?? (para.kind === "number" ? "number" : "body");
+        return { role, paint: textPaint({ ...e, ...para }, LARGE_ROLES.has(role) ? 3 : contrastFloor) };
+      };
+      // Each paragraph is aligned by its own `align` (one block may mix them:
+      // a centred figure over a left label); an indent is written only where
+      // it is structure (paragraphIndent).
+      const attrs = (para, nowrap = false) => {
+        const { role, paint } = paintOf(para);
+        const out = [`role=${q(role)}`];
+        if (paint.colorVar) out.push(`colorVar=${q(paint.colorVar)}`);
+        const indent = paragraphIndent(para, e, spec.elements ?? []);
+        if (indent > 1) out.push(`indent={${indent}}`);
+        if (nowrap && !String(para.text).includes("\n") && String(para.text).trim().length <= 60 && !raw.wrap) out.push("nowrap");
+        if (nowrap && para.weight === "bold") out.push("bold");
+        if (paint.tone) out.push(`tone=${q(paint.tone)}`);
+        if (para.align && para.align !== "left") out.push(`align=${q(para.align)}`);
+        if (para.marker) {
+          const marker = markerVar({ ...e, ...para });
+          if (marker) out.push(`markerVar=${q(marker)}`);
+        }
+        return out;
+      };
+      const { children, single } = blockChildren(e.paragraphs, {
+        attrs,
+        para: (para) => `<P ${attrs(para, true).join(" ")}>${emphasise(jsxText(para.text), { ...e, ...para })}</P>`,
+        item: (para, head) => {
+          const body = emphasise(jsxText(para.text), { ...e, ...para });
+          const own = paintOf(para).paint;
+          const list = paintOf(head).paint;
+          if (own.colorVar === list.colorVar && own.tone === list.tone) return body;
+          return `<span style={{ color: ${own.colorVar ? q(own.colorVar) : `TONE[${q(own.tone ?? "dark")}]`} }}>${body}</span>`;
+        },
+      });
+      // `block`: this T is ONE text — two elements carrying it are that text split apart (lint, [split:error]).
+      const place = `id=${q(e.id)} x={${frame.x}} y={${frame.y}} w={${frame.w}}${stackAttr(e.id)} block=${q(e.id)}`;
+      lines.push(single ? children.replace("<L ", `<L ${place} `) : `<T ${place}>${children}</T>`);
+      continue;
+    }
+    if ((e.kind === "text" || e.kind === "number") && !(e.shape && e.fill && e.fill !== "none")) {
+      if (text == null) continue;
+      lines.push(textEl(e.id, e.role ?? (e.kind === "number" ? "number" : "body")));
+    } else if (e.kind === "icon" || e.kind === "image") {
+      // A bound original: the user's own picture. It is placed from the deck's
+      // registry and never joins the fetch list below — searching for a
+      // lookalike is exactly the substitution the contract exists to prevent —
+      // and it has no query to fall back to either (normalizeImagePayload drops
+      // one the moment a binding is present).
+      const useId = e.image?.assetUseId ?? null;
+      if (useId) {
+        const b = bound.get(useId);
+        if (!b) {
+          warnings.push(
+            `${e.id}: the spec binds image use ${useId}, which this deck's plan and registry do not resolve — nothing was searched for; import the source, record the use, then transcribe again`,
+          );
+          dropped.push(e.id);
+          continue;
+        }
+        const attrs = [base, `h={${e.h}}`, `src=${q(b.src)}`, `use=${q(useId)}`, `fit=${q(b.fit ?? "contain")}`, `pos=${q(positionValue(b.position))}`];
+        const crop = cropAttrs(b.crop);
+        if (crop) attrs.push(`crop=${q(crop.crop)}`, `view=${q(crop.view)}`);
+        lines.push(`<I ${attrs.join(" ")} />`);
+        for (const note of b.notes ?? []) warnings.push(`${e.id}: ${note}`);
+        if (b.slot) {
+          warnings.push(
+            `${e.id}: image use ${useId} names layout image slot "${b.slot}"; this skeleton places the picture at the concept's own rect instead`,
+          );
+        }
+        continue;
+      }
+      const paint = assetPaint(e);
+      // A mark of a few plain strokes is drawn, not searched for: the icon
+      // libraries carry pictures of things, and x51 missed every tick, chevron
+      // and ellipsis (23 of 79 misses), each shipping as an empty carrier. Its
+      // strokes are native line pieces with round caps (a chain group), an
+      // arrow one line with its head, an ellipsis three small discs. A seated
+      // mark is drawn at its carrier's centre.
+      const carrier = seated.get(raw.parent) === raw ? elementById.get(raw.parent) : null;
+      const mark = e.kind === "icon" ? glyphMarkStrokes(carrier ? { ...e, x: carrier.x + (carrier.w - e.w) / 2, y: carrier.y + (carrier.h - e.h) / 2 } : e) : null;
+      if (mark) {
+        const color = paint.colorVar ?? variable(roles.tone[paint.tone ?? "dark"]);
+        if (mark.kind === "dots") {
+          mark.dots.forEach((d, k) => lines.push(`<B id=${q(`${e.id}-${k + 1}`)} x={${d.x - d.r}} y={${d.y - d.r}} w={${2 * d.r}} h={${2 * d.r}} shape="circle"${color ? ` fillVar=${q(color)}` : ""} />`));
+          continue;
+        }
+        const pieces = mark.strokes.flatMap((st) => st.slice(1).map((p, i) => ({ object: "cxn", prst: "straightConnector1", av: {}, rot: 0, from: { point: st[i] }, to: { point: p }, start: st[i], end: p })));
+        let n = pieces.length === 1 ? { ...pieces[0], id: e.id } : chainNative(e.id, pieces);
+        // An arrow too short for even the smallest head grows to carry it,
+        // where that stays in the free room around the glyph.
+        const long = mark.kind === "arrow" ? stretched(n, Math.ceil(headRoutePx("sm"))) : null;
+        if (long && runsClear(long.start, long.end, (spec.elements ?? []).filter((o) => o.id !== e.id))) n = long;
+        lineOut.push({ jsx: lineDirective(n, {
+          className: "connector-muted",
+          style: color && color !== CLASS_COLOR["connector-muted"] ? [`color: ${q(color)}`] : [],
+          caps: [null, mark.kind === "arrow" ? capAttr({ type: "triangle", size: "med" }, capRoutePx(n, 1)) : null],
+          linecap: "rnd",
+        }) });
+        continue;
+      }
+      lines.push(`<I ${base} h={${e.h}} src=${q(requestAsset(e, paint))} />`);
+    } else if (e.kind === "rule") {
+      // Every rule with a length is a line (above); a rule with none draws nothing.
+      continue;
+    } else if (e.kind === "path" && e.geometry?.type === "arc" && Math.abs(e.geometry.sweep) >= 360 && !(e.fill && e.fill !== "none")) {
+      // A full unfilled ring the intake did not take as a line (it carries
+      // words): a native ellipse box with the design's line weight.
+      const g0 = e.geometry;
+      const ringVar = namedVar(e.stroke?.colorToken ?? e.colorToken, e.stroke?.colorHex ?? e.colorHex) ?? snapVar(e.stroke?.colorHex ?? e.colorHex);
+      lines.push(`<B id=${q(e.id)} x={${g0.cx - g0.rx}} y={${g0.cy - g0.ry}} w={${2 * g0.rx}} h={${2 * g0.ry}} shape="ellipse" style={{ borderWidth: ${q(`var(--bw-${weightClass(e.stroke?.width)})`)}, borderStyle: ${q(e.stroke?.dash === "dashed" ? "dashed" : "solid")}, borderColor: ${ringVar ? q(ringVar) : `TONE[${q(e.color ?? "muted")}]`} }} />`);
+    } else if (e.kind === "path" && ["arc", "sector"].includes(e.geometry?.type) && e.fill && e.fill !== "none" && e.geometry.innerRatio > 0 && e.geometry.innerRatio < 1) {
+      // A filled arc with a hole is a band: a native donut (full) or blockArc
+      // (a segment), filled with the design colour. The outline takes the
+      // fill's own colour at the lightest weight, so no second colour rims it.
+      const n = bandNative(e.id, reconcileArc(e.geometry, e));
+      if (!n) {
+        warnings.push(`${e.id}: its band geometry cannot be drawn; left out — redraw it by hand from the concept`);
+        dropped.push(e.id);
+        continue;
+      }
+      const fillVar = fillVarOf(e) ?? variable(roles.fill[e.fill]);
+      const fill = fillVar ? q(fillVar) : `FILL[${q(e.fill)}]`;
+      // A band is a shape: it paints in its place, under the labels on it.
+      lines.push(lineDirective(n, { className: "connector-muted", style: [`borderWidth: "var(--bw-hairline)"`, `color: ${fill}`, `fill: ${fill}`] }));
+    } else if (e.kind === "path" && e.geometry) {
+      // Only a closed outline can hold paint: an open spline or path is a
+      // line, and filling it drew a trend line as a wedge (x53 cloud 5, x54
+      // GTM 4) whatever fill the reader named.
+      const g0 = e.geometry;
+      const closed = g0.type === "sector" || (g0.type === "spline" && g0.closed === true)
+        || (g0.type === "path" && (g0.commands ?? []).some((c) => c?.op === "Z"));
+      // Every open stroke is a native line (above); one that reaches here
+      // could not be read as one — named, never drawn as svg.
+      if (!closed || !(e.fill && e.fill !== "none")) {
+        warnings.push(`${e.id}: a stroke whose points cannot be read as a line; left out — draw it as a native line directive from the concept`);
+        dropped.push(e.id);
+        continue;
+      }
+      const geom0 = g0.type === "path" ? { ...g0, commands: repairCommands(g0.commands, e) } : reconcileArc(g0, e);
+      let g = geometryPath(geom0);
+      // A drawn shape may not reach outside the content slot (the export
+      // refuses it). Where its extent does, its own coordinates are moved in —
+      // and shrunk uniformly only if it is larger than the slot — so it is
+      // never distorted and its svg stays 1:1. The reader's box is NOT the
+      // bound: it can contradict the reader's own points (x66 QBR 6).
+      const ext0 = g?.extent;
+      const out = ext0 && (ext0.x < -1 || ext0.y < -1 || ext0.x + ext0.w > slot.w + 1 || ext0.y + ext0.h > slot.h + 1);
+      if (out) {
+        const k = Math.min(1, slot.w / ext0.w, slot.h / ext0.h);
+        const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+        const to = { x: clamp(ext0.x, 0, slot.w - ext0.w * k), y: clamp(ext0.y, 0, slot.h - ext0.h * k) };
+        g = geometryPath(scaleGeometry(geom0, k, { x: ext0.x, y: ext0.y }, to)) ?? g;
+      }
+      // Never a rectangle in its place, and never the whole deck lost to it:
+      // the element is left out and named (x58: one bad arc aborted every
+      // slide and the agent hand-authored them).
+      if (!g) {
+        warnings.push(`${e.id}: its geometry cannot be drawn (${g0.type}); left out — redraw it by hand from the concept`);
+        dropped.push(e.id);
+        continue;
+      }
+      // A filled figure (a sector, a closed silhouette): its fill only, placed
+      // in the box it draws.
+      const r2 = (v) => Math.round(v * 100) / 100;
+      const b = g.extent ?? { x: g.x, y: g.y, w: g.w, h: g.h };
+      const [bx, by, bw, bh] = [b.x, b.y, Math.max(2, b.w), Math.max(2, b.h)].map(r2);
+      lines.push(`<div id=${q(e.id)} style={{ position: "absolute", left: ${bx}, top: ${by}, width: ${bw}, height: ${bh} }}><svg viewBox={\`${r2(bx - g.x)} ${r2(by - g.y)} ${bw} ${bh}\`} width={${bw}} height={${bh}} style={{ display: "block", overflow: "visible" }}><path d=${q(g.d)} ${svgPaint(e)} /></svg></div>`);
+    } else if (e.kind === "path" && Array.isArray(e.points) && e.points.length >= 2) {
+      // A filled silhouette (roof, arch, funnel side): one inline svg the size
+      // of its rect, points relative to it, fill only. An open stroke never
+      // reaches here as svg: it is a native line.
+      if (!(e.points.length >= 3 && e.fill && e.fill !== "none")) {
+        warnings.push(`${e.id}: a stroke whose points cannot be read as a line; left out — draw it as a native line directive from the concept`);
+        dropped.push(e.id);
+        continue;
+      }
+      const x0 = Math.min(...e.points.map((p) => p.x));
+      const y0 = Math.min(...e.points.map((p) => p.y));
+      const w = Math.max(2, Math.max(...e.points.map((p) => p.x)) - x0);
+      const h = Math.max(2, Math.max(...e.points.map((p) => p.y)) - y0);
+      const pts = e.points.map((p) => `${p.x - x0},${p.y - y0}`).join(" ");
+      lines.push(
+        `<div id=${q(e.id)} style={{ position: "absolute", left: ${x0}, top: ${y0}, width: ${w}, height: ${h} }}><svg viewBox={\`0 0 ${w} ${h}\`} width={${w}} height={${h}} style={{ display: "block", overflow: "visible" }}><polygon points="${pts}" ${svgPaint(e)} /></svg></div>`,
+      );
+    } else if (e.kind === "chart" && e.chart) {
+      const data = nativeChartData(e.chart);
+      if (!data) {
+        // Do not erase the observed marks or fabricate data when the model
+        // recognized a chart but did not recover a renderable payload.
+        lines.push(`{/* unresolved chart ${escapeJsx(e.id)}: observed marks retained; requires supported type and verified series */}`);
+        warnings.push(`chart ${e.id} has no readable values or an unsupported/inconsistent payload; observed marks retained, native chart unresolved — supply verified chart data, never invent values from an unlabeled illustration`);
+        dropped.push(e.id);
+        continue;
+      }
+      lines.push(chartJsx(e, spec, tokens, data, base, warnings));
+    } else {
+      const attrs = [base, `h={${e.h}}`];
+      if (!fig && e.fill && e.fill !== "none") attrs.push(`fill=${q(e.fill)}`);
+      const fillVar = fig ? null : fillVarOf(e);
+      if (fillVar) attrs.push(`fillVar=${q(fillVar)}`);
+      if (!fig && e.shape && e.shape !== "rect") attrs.push(`shape=${q(e.shape)}`);
+      const boxStyle = [];
+      // Legacy bar specs predate explicit strokes. An unfilled bar is an
+      // outline, but a transparent grouping shape is not.
+      const outline = fig ? null : e.stroke ?? (e.kind === "bar" && e.fill === "none" && !Object.hasOwn(e, "stroke") ? { width: null } : null);
+      if (outline && !(Number.isFinite(outline.width) && outline.width <= 0)) {
+        // The reader's weight as the design's weight token, never its px.
+        const strokeVar = namedVar(outline.colorToken) ?? snapVar(outline.colorHex);
+        boxStyle.push(`borderWidth: ${q(`var(--bw-${weightClass(outline.width)})`)}`, `borderStyle: ${q(outline.dash === "dashed" ? "dashed" : "solid")}`, `borderColor: ${strokeVar ? q(strokeVar) : `TONE[${q(e.color ?? "dark")}]`}`);
+      }
+      // A node a line glues to ALWAYS names the preset its sites were fitted
+      // on: the exporter's box rule reads a token radius differently (a
+      // pill-radius circle is not an ellipse to it), and a site index means
+      // nothing against another preset's site list (x74: every disc's
+      // bottom site 4 refused as out of range on a 4-site box).
+      if (glueTargets.has(e.id) && nodes.get(e.id)) {
+        const node = nodes.get(e.id);
+        attrs.push(`prst=${q(node.prst)}`);
+        const adj = Object.entries(node.av ?? {}).map(([k, v]) => `${k}:${Math.round(v)}`).join(",");
+        if (adj) attrs.push(`adj=${q(adj)}`);
+      }
+      if (!fig && e.shape === "ring" && !outline) boxStyle.push(`borderWidth: "var(--bw-medium)", borderStyle: "solid", borderColor: TONE.accent`);
+      // Silhouettes the box can take with a clip-path (x28: chevrons shipped
+      // as pale squares). A chevron/triangle points the way the row runs.
+      const CLIP = {
+        chevron: "polygon(0 0, 75% 0, 100% 50%, 75% 100%, 0 100%, 25% 50%)",
+        triangle: e.w >= e.h ? "polygon(0 0, 100% 50%, 0 100%)" : "polygon(0 100%, 50% 0, 100% 100%)",
+        trapezoid: "polygon(12% 0, 88% 0, 100% 100%, 0 100%)",
+        // A filled block arrow pointing the way its long side runs.
+        arrow: e.w >= e.h ? "polygon(0 28%, 62% 28%, 62% 0, 100% 50%, 62% 100%, 62% 72%, 0 72%)" : "polygon(28% 0, 72% 0, 72% 62%, 100% 62%, 50% 100%, 0 62%, 28% 62%)",
+        diamond: "polygon(50% 0, 100% 50%, 50% 100%, 0 50%)",
+        hexagon: e.w >= e.h ? "polygon(25% 0, 75% 0, 100% 50%, 75% 100%, 25% 100%, 0 50%)" : "polygon(50% 0, 100% 25%, 100% 75%, 50% 100%, 0 75%, 0 25%)",
+        pentagon: "polygon(50% 0, 100% 38%, 81% 100%, 19% 100%, 0 38%)",
+        parallelogram: "polygon(18% 0, 100% 0, 82% 100%, 0 100%)",
+      };
+      // A silhouette none of the named shapes draws: the outline the reader
+      // traced, relative to the box (the exporter fits a preset to it, or
+      // keeps it as a freeform).
+      const traced = e.shape === "other" && Array.isArray(e.outline) && e.outline.length >= 3 && e.w > 0 && e.h > 0
+        ? `polygon(${e.outline.map((p) => `${Math.round(((p.x - e.x) / e.w) * 1000) / 10}% ${Math.round(((p.y - e.y) / e.h) * 1000) / 10}%`).join(", ")})`
+        : null;
+      if (!fig && (CLIP[e.shape] || traced)) boxStyle.push(`clipPath: ${q(CLIP[e.shape] ?? traced)}`);
+      if (e.textInsets) for (const side of ["left", "right", "top", "bottom"]) {
+        const inset = e.textInsets[side];
+        if (Number.isFinite(inset) && inset >= 0) boxStyle.push(`padding${side[0].toUpperCase() + side.slice(1)}: ${inset}`);
+      }
+      // A shape's own words never sit flush with its edge (BP 04-02: badge
+      // labels clipped at the pill's side). On a badge, pill or round carrier
+      // they centre; elsewhere they keep the read alignment inside the
+      // design's inner padding. Folded words carry their measured insets.
+      const ownWords = text != null && !e.textInsets;
+      const centred = ownWords && (e.kind === "badge" || e.kind === "disc" || ["pill", "circle", "ring"].includes(e.shape));
+      const align = centred ? "center" : e.align;
+      if (ownWords && !centred && (align === "left" || align === "right")) boxStyle.push(`paddingLeft: "var(--sp-2)"`, `paddingRight: "var(--sp-2)"`);
+      if (align) boxStyle.push(`textAlign: ${q(align)}`);
+      if (e.elevated && !fig) attrs.push("shadow");
+      if (text == null) {
+        // A seated icon or picture rides inside, on one line: the box centres it.
+        const seat = seated.get(e.id);
+        const inner = seat && !isMark(seat) ? `<I id=${q(seat.id)} w={${Math.min(seat.w, e.w)}} h={${Math.min(seat.h, e.h)}} src=${q(requestAsset(seat))} />` : null;
+        if (inner) {
+          attrs.push(`align="center"`, `valign="middle"`);
+          consumed.add(seat.id);
+        }
+        if (boxStyle.length) attrs.push(`style={{ ${boxStyle.join(", ")} }}`);
+        lines.push(inner ? `<B ${attrs.join(" ")}>${inner}</B>` : `<B ${attrs.join(" ")} />`);
+      } else {
+        // A badge's digit, a disc's label: the words belong TO the shape. The
+        // type goes on the BOX, not on a span inside it — the export reads the
+        // anchor off the box that carries the run, so a span would ship a
+        // centred-looking preview and a top-anchored shape in PowerPoint. One
+        // shape with its own centred text body then sits in its middle on both
+        // axes, instead of at whatever rect the read gave a separate text box
+        // (a child's rect is the noisiest part of a spec — a glyph or digit
+        // half out of its disc, x37 cloud 2 and 6).
+        const paint = textPaint(e);
+        const v = paint.colorVar;
+        boxStyle.unshift(
+          // A digit on a disc or badge is a badge label, not a KPI number.
+          `...ROLE[${q(e.role === "number" || e.kind === "badge" ? "badge" : (e.role ?? "body"))}]`,
+          `color: ${v ? q(v) : `TONE[${q(paint.tone ?? "dark")}]`}`,
+          ...(e.weight === "bold" ? [`fontWeight: "var(--fw-bold)"`] : []),
+          `lineHeight: "var(--lh-tight)"`,
+        );
+        // Where the words sit is the geometry the reader measured (the fold
+        // pass derives it from the block's margins inside the box); a box's own
+        // one-line text centres. No shape name decides this.
+        attrs.push(`align=${q(align ?? "center")}`);
+        attrs.push(`valign=${q(e.valign ?? "middle")}`);
+        attrs.push(`style={{ ${boxStyle.join(", ")} }}`);
+        lines.push(`<B ${attrs.join(" ")}>${emphasise(jsxText(text))}</B>`);
+      }
+    }
+    } catch (err) {
+      warnings.push(`${raw.id}: not written — ${err?.message ?? err}; the rest of the slide stands`);
+    }
+  }
+  // Retained illustration marks have an owner even though no numeric chart
+  // can be emitted. Capture uses that ownership to reject a second, native
+  // plot placed on top later. Annotations (text/icons) are not plot marks.
+  const illustrations = (spec.elements ?? []).filter(e => e.kind === "chart" && !nativeChartData(e.chart));
+  for (const e of spec.elements ?? []) {
+    if (e.text != null || !["path", "rule", "bar", "shape"].includes(e.kind)) continue;
+    const owner = illustrations.find(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);
+    if (!owner) continue;
+    const at = lines.findIndex(line => line.includes(`id=${q(e.id)} `));
+    if (at < 0) continue;
+    const name = lines[at].startsWith("<div") ? "data-sm-plot-owner" : "plotOwner";
+    lines[at] = lines[at].replace(`id=${q(e.id)}`, `id=${q(e.id)} ${name}=${q(owner.id)}`);
+  }
+  // Lines paint above the shapes they join; a free rail, ring or divider
+  // paints behind the shapes on it (placement.mjs).
+  const painted = (e) => (e.fill && e.fill !== "none") || ["icon", "image", "chart"].includes(e.kind) || sketched.has(e.id);
+  const seats = placed.filter((p, k) => painted(p.el) && (placed[k + 1]?.at ?? lines.length) > p.at);
+  lines.splice(0, lines.length, ...seatLines(lines, seats, lineOut));
+  // Chrome props fill the layout's own placeholders, and a placeholder wraps
+  // its text at its own width and master size. The spec's `\n` is only where
+  // the MOCKUP wrapped, so it becomes a space (2026-09-27: a two-line headline
+  // shipped with the concept's break although its placeholder needed none;
+  // this retires the x37 keep-the-break and x51 char-estimate rules).
+  const flat = (t) => String(t ?? "").split("\n").join(" ").replace(/\s+/g, " ").trim();
+  if (unmatched.size) {
+    warnings.push(
+      `${unmatched.size} observed colour${unmatched.size === 1 ? "" : "s"} ha${unmatched.size === 1 ? "s" : "ve"} no token in this design (${[...unmatched].slice(0, 3).map(([h, n]) => `${h} nearest ${n}`).join(", ")}); the tone word decided`,
+    );
+  }
+  const props = [];
+  if (chrome.kicker) props.push(`${chrome.kicker}=${q(flat(spec.chrome?.kicker))}`);
+  if (chrome.headline) props.push(`${chrome.headline}=${q(flat(spec.chrome?.headline))}`);
+  // Meta chrome: the slide number as the layout's page number, nothing else
+  // (a layout's own placeholder copy must not ship). The spec's `footer` is
+  // deliberately NOT fed back: the mockup was painted over this layout's own
+  // chrome, so whatever the model read in the footer band — the wordmark, the
+  // date, the section, the page number — is what the layout already draws.
+  // Re-emitting it shipped a second wordmark next to the real one and, where
+  // the chrome renders the full strip, one crowded string in the footnote
+  // placeholder (x36 / hold-out 3: ten judged slides).
+  for (const p of chrome.others) {
+    if (/pagenumber|slidenum/i.test(p)) props.push(`${p}=${q(String(slide))}`);
+    else props.push(`${p}=""`);
+  }
+  if (!chrome.headline && !chrome.kicker) {
+    warnings.push(`layout ${layout} declares no chrome props the skeleton knows; the headline was not placed`);
+  }
+  const jsx =
+    `// Transcribed from the reader's inventory of the concept, at the painting's coordinates. Edit in place: align, even and centre what the painting only approximates; delete what it drew by accident (a chrome-band mark, a guide box, a stray stroke).\n` +
+    (literal ? `// A reconstruction: its colours are the reference's own values, not design tokens — keep them.\n` : "") +
+    `export default function Slide() {\n${kit}${(spec.stacks ?? []).length ? `  // Declared stacks (reader): how each one's rows are aligned and spaced.\n  const STACKS = ${JSON.stringify(Object.fromEntries((spec.stacks ?? []).map((g, gi) => [gi + 1, { align: g.align ?? "middle", spacing: g.spacing ?? "even" }])))};\n${gridsConst}` : ""}${KIT_EXTRAS}\n  return (\n    <${layout}${props.length ? " " + props.join(" ") : ""}>\n` +
+    `      <div style={{ position: "relative", width: ${slot.w}, height: ${slot.h} }}>\n` +
+    repeatGroups(spec).map((g) => `        {/* ${g.id}: ${g.members.map((m) => (m.ids ? `(${m.ids.join(" + ")})` : m.id)).join(", ")} are one organism (${g.arrangement}${g.hub ? ` around ${g.hub.id}` : ""}) — one size, one inner layout; change them alike. */}\n`).join("") +
+    lines.map((l) => `        ${l}`).join("\n") +
+    `\n      </div>\n    </${layout}>\n  );\n}\n`;
+  return { jsx, icons, warnings, dropped, connectorLines };
+}
+
+// The engine's own ranking is noise for icons: nine results come back inside
+// 0.002 of each other, so "first result" is a coin toss — the judge's most
+// frequent defect across every run is "several icons differ materially from
+// the concept" ("revenue growth chart" returned Decreasing-Chart first with
+// Increasing-Chart fourth; "marketing megaphone" returned Loudspeaker with
+// Megaphone fourth). The file name behind each result is the signal the score
+// is not, so pick by it: most query words matched, then the plainest name
+// (`Clock-1` over `School-Clock`), then the engine's order.
+// ponytail: overlap only — "revenue growth chart" still ties Increasing- and
+// Decreasing-Chart. Add a direction synonym/antonym table if wrong-direction
+// glyphs show up as more than the occasional defect.
+export function iconSearchQueries(query, keywords = []) {
+  const words = String(query).split(/\s+/).filter(Boolean);
+  const content = words.filter(w => !ICON_STYLE_WORDS.has(w.toLowerCase()));
+  // Never reduce a compound motif to its last noun ("magnifying glass" ->
+  // "glass", "check mark" -> "mark"). A retry keeps its semantic content; the
+  // reader's own synonyms follow, as the words a library names files with.
+  const own = new Set(content.map((w) => w.toLowerCase()));
+  const synonyms = keywords.map((k) => String(k).trim().toLowerCase()).filter((k) => k && !own.has(k) && !ICON_STYLE_WORDS.has(k));
+  return [...new Set([query, content.join(' '), ...synonyms].filter(Boolean))].slice(0, 4);
+}
+const motifWords = query => {
+  const words = nameWords(query).filter(w => !ICON_STYLE_WORDS.has(w));
+  // A shared object noun alone does not establish a compound motif.
+  return words.length > 1 ? words.filter(w => !['glass', 'coin'].includes(w)) : words;
+};
+
+const resultName = (r) => {
+  const raw = String(r?.sourceUrl ?? r?.title ?? "").split("/").pop() ?? "";
+  let name = raw;
+  try {
+    name = decodeURIComponent(raw);
+  } catch {
+    // A malformed escape: the raw segment still carries the words.
+  }
+  return name.replace(/\.[a-z0-9]+$/i, "");
+};
+
+/** How many of the query's words the result's file name carries. */
+// `keywords` are the reader's file-name synonyms for the motif (x51: "person
+// outline" never matched Male-2, "magnifying glass" never matched Search-Plus,
+// "speedometer gauge" never matched Speed-Meter). A synonym counts as a hit;
+// the query's own words still rank first.
+/** How many name hits make a full match for this motif (its own words, at most two). */
+export const iconMotifSize = (query) => Math.min(2, Math.max(1, motifWords(query).length));
+
+export function iconNameHits(query, result, keywords = []) {
+  const parts = nameWords(resultName(result));
+  if (!parts.length) return 0;
+  const own = motifWords(query);
+  const syn = [...new Set(keywords.flatMap((k) => nameWords(k)))].filter((w) => !own.includes(w) && !ICON_STYLE_WORDS.has(w));
+  return own.filter((w) => parts.includes(w)).length + (syn.some((w) => parts.includes(w)) ? 1 : 0);
+}
+
+export function pickIconResult(query, results, keywords = []) {
+  const list = Array.isArray(results) ? results.filter(r => r && iconNameHits(query, r, keywords) > 0) : [];
+  if (list.length < 2) return list[0] ?? null;
+  const score = (r) => {
+    const parts = nameWords(resultName(r));
+    if (!parts.length) return -Infinity;
+    return iconNameHits(query, r, keywords) * 10 - parts.length;
+  };
+  let best = list[0];
+  let bestScore = score(list[0]);
+  for (const r of list.slice(1)) {
+    const s = score(r);
+    if (s > bestScore) {
+      best = r;
+      bestScore = s;
+    }
+  }
+  return best;
+}