slidemind 0.3.19 → 0.4.0

package/src/builders/line-native.mjs

@@ -0,0 +1,895 @@
+// Every stroke a slide draws is ONE native PowerPoint object from a closed
+// alphabet (the nativeLinesV1 directive contract): a connector (`cxnSp`,
+// straight / bent / curved, glued at a real connection site of its node's own
+// preset or free at a point), an open preset shape (`arc`, brackets, braces),
+// or — when no single preset draws a free stroke within tolerance — a group
+// chain of straight and arc pieces. Never a custGeom, never an svg.
+//
+// `fitNative` chooses the preset and its adjust values by MEASUREMENT: every
+// candidate is evaluated with the one ECMA evaluator (preset-eval.mjs, the same
+// code the exporter and the preview use) and scored by its ordered distance
+// from the path the concept draws. Closed forms seed it (a circle for an arc,
+// the trace's box for a bracket, a grid over the adjusts for a connector) and
+// coordinate descent refines at most three adjusts. `lineDirective` writes the
+// result as the contract's JSX. Width and colour are NOT decided here: the
+// caller passes design tokens (the reader's weight class, never a pixel
+// measurement), and the agent sets final weights by proportion.
+//
+// Shared by both clients; mirrored by scripts/sync-transcription-runtime.mjs —
+// no Node or CLI imports here.
+
+import { evalPreset, presetAdjusts, presetSites } from "./preset-eval.mjs";
+import { pathDistance, pathErrors, pointRef, sanitizeTrace, segmentHitsRect, contains, traceLength } from "./line-fit.mjs";
+import { headRoutePx } from "./placement.mjs";
+
+/** OOXML angle unit: 60000ths of a degree. */
+const DEG = 60000;
+
+/**
+ * Every tolerance and search bound the fitter uses, in one table. Calibrated
+ * on the dev set, never per slide or per design.
+ */
+export const NATIVE_TOL = Object.freeze({
+  // A free stroke is ONE preset when its worst point is within
+  // max(freePx, freeFrac · length) of the concept; else it is a chain.
+  freePx: 2,
+  freeFrac: 0.04,
+  // A glyph mark's pieces are held to this (it is a few px across).
+  markPx: 1,
+  // A connector's handle may overshoot its box by at most this (a U-turn out
+  // of two same-side sites), beyond which it draws a loop the concept lacks.
+  adjOvershoot: 100000,
+  // A glued connector further than max(gluedPx, gluedFrac · length) from the
+  // concept is still the one glued connector, and the distance is warned.
+  gluedPx: 18,
+  gluedFrac: 0.15,
+  // An arc piece whose radius exceeds this × its length is a straight line
+  // (no off-slide circles for a slightly bent stroke).
+  straightRadiusSpan: 4,
+  // Curves are one loop when one circle holds all their points within this
+  // share of its radius.
+  loopFrac: 0.12,
+  maxChainPieces: 12,
+  // Connection sites tried per glued end: the nearest ones to where the
+  // concept attaches.
+  siteCandidates: 2,
+  // Seed configurations given a coarse descent, per preset; the leaders
+  // overall given the fine one.
+  seedsPerConfig: 2,
+  refinePerPreset: 3,
+  refineFinal: 4,
+  // A crossing of a text or picture the concept does not cross costs this
+  // while fitting the concept; the settle router, which only clears
+  // crossings, weighs one as never worth taking.
+  crossPenaltyPx: 30,
+  routeCrossPenaltyPx: 1000,
+  // Moving a settled connector's end to another site costs this.
+  siteChangePx: 40,
+  // Each adjust handle a preset needs costs this much distance: a simpler
+  // preset wins a tie.
+  adjustBiasPx: 0.75,
+  // Elbows off one site whose knees lie within this share one rail.
+  railPx: 12,
+  // Two ends closer than this are the same point.
+  samePointPx: 0.5,
+});
+
+/**
+ * The canonical design weight rungs (`--bw-*`), px. A reader's declared stroke
+ * width snaps to the nearest rung; the BRAND's own values never enter here, so
+ * a design changing its `--bw-*` changes no emitted JSX. No width = `default`.
+ */
+export const LINE_WEIGHT_RUNGS_PX = Object.freeze({ hairline: 1, medium: 2, bold: 4 });
+
+/** The weight class of a reader's declared width (px), or "default" for none. */
+export function weightClass(px) {
+  if (!(Number.isFinite(px) && px > 0)) return "default";
+  let best = null;
+  for (const [name, rung] of Object.entries(LINE_WEIGHT_RUNGS_PX)) {
+    if (!best || Math.abs(px - rung) < Math.abs(px - best[1])) best = [name, rung];
+  }
+  return best[0];
+}
+
+export const CONNECTOR_PRESETS = Object.freeze([
+  "straightConnector1",
+  "bentConnector2", "bentConnector3", "bentConnector4", "bentConnector5",
+  "curvedConnector2", "curvedConnector3", "curvedConnector4", "curvedConnector5",
+]);
+/** Open presets a free stroke may be, mirrored forms included through flips. */
+const OPEN_SHAPES = Object.freeze(["leftBracket", "leftBrace"]);
+const MIRRORED = Object.freeze({ leftBracket: "rightBracket", leftBrace: "rightBrace" });
+const FAMILY_BY_KIND = Object.freeze({
+  curve: CONNECTOR_PRESETS.filter((p) => !p.startsWith("bent")),
+  arc: CONNECTOR_PRESETS.filter((p) => !p.startsWith("bent")),
+  orthogonal: CONNECTOR_PRESETS.filter((p) => !p.startsWith("curved")),
+});
+const FLIPS = [[false, false], [true, false], [false, true], [true, true]];
+
+const dist = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+const finite = (p) => Number.isFinite(p?.x) && Number.isFinite(p?.y);
+const r1 = (v) => Math.round(v * 10) / 10;
+const norm360 = (deg) => ((deg % 360) + 360) % 360;
+const adjustNames = (prst) => Object.keys(presetAdjusts(prst));
+
+// ---- Geometry of one candidate, evaluated by the shared evaluator.
+
+/** The stroked outline of an evaluated preset: its first stroke-only path. */
+function strokeOf(evaluated) {
+  const paths = evaluated.paths ?? [];
+  const path = paths.find((p) => p.stroke && !p.fill) ?? paths.find((p) => p.stroke) ?? paths[0];
+  return path?.polylines?.[0]?.points ?? null;
+}
+
+/**
+ * A connector preset placed between two points exactly as the exporter places
+ * it (contract §1): the box whose corners are S and E (turned 90° about their
+ * midpoint for rot 90/270), flips chosen so the path starts on S and ends on E.
+ * Returns `{ points, flipH, flipV }` or null.
+ */
+export function connectorGeometry(prst, S, E, rot = 0, av = {}) {
+  const turned = rot === 90 || rot === 270;
+  const dx = Math.abs(E.x - S.x), dy = Math.abs(E.y - S.y);
+  const w = turned ? dy : dx, h = turned ? dx : dy;
+  const x = (S.x + E.x) / 2 - w / 2, y = (S.y + E.y) / 2 - h / 2;
+  const eps = 1e-6 * Math.max(1, w, h);
+  // Every connector preset runs corner to corner, so the flips depend only on
+  // the turn and the direction from S to E: the one that worked is tried first.
+  const key = `${rot}|${E.x >= S.x}|${E.y >= S.y}`;
+  const known = FLIP_BY_DIRECTION.get(key);
+  for (const [flipH, flipV] of known ? [known, ...FLIPS] : FLIPS) {
+    const pts = strokeOf(evalPreset(prst, w, h, av, { x, y, rot: rot * DEG, flipH, flipV }));
+    if (pts?.length >= 2 && dist(pts[0], S) <= eps + 1e-3 && dist(pts.at(-1), E) <= eps + 1e-3) {
+      if (w > eps && h > eps) FLIP_BY_DIRECTION.set(key, [flipH, flipV]);
+      return { points: pts, flipH, flipV };
+    }
+  }
+  return null;
+}
+const FLIP_BY_DIRECTION = new Map();
+
+/** An open preset shape in its (unrotated) box, `rot` in degrees. */
+export function shapeGeometry(prst, box, av = {}, rot = 0, flipH = false, flipV = false) {
+  return strokeOf(evalPreset(prst, box.w, box.h, av, { x: box.x, y: box.y, rot: rot * DEG, flipH, flipV }));
+}
+
+/** A NativeLine's outline in slot px (a chain concatenates its pieces). */
+export function nativePoints(n) {
+  if (n.object === "grp") return n.children.flatMap(nativePoints);
+  if (n.object === "cxn") return connectorGeometry(n.prst, n.start, n.end, n.rot, n.av)?.points ?? [];
+  return shapeGeometry(n.prst, n.box, n.av, n.rot, n.flipH, n.flipV) ?? [];
+}
+
+// ---- Nodes: the preset a glue target exports as, and its real sites.
+
+const CLIP_ADJ = { chevron: 0.25, trapezoid: 0.12, parallelogram: 0.18 };
+// Presets whose outline their box (or its inscribed ellipse) describes.
+const OUTLINE_BOX = new Set(["rect", "roundRect", "ellipse"]);
+// Painted boxes (B), and the other placed elements (text, icons, charts),
+// which export as plain rectangles whatever their spec shape says.
+const BOX_KINDS = new Set(["card", "panel", "disc", "badge", "shape", "bar"]);
+const NODE_KINDS = new Set([...BOX_KINDS, "text", "number", "icon", "image", "chart"]);
+// A text on a painted shape is written as that shape (the transcriber's B).
+const drawnAsBox = (e) => BOX_KINDS.has(e.kind) || ((e.kind === "text" || e.kind === "number") && e.shape && e.fill && e.fill !== "none");
+
+/**
+ * The preset a node exports as — the same rule the helpers emit it with — or
+ * null when it has no preset (a traced outline, a turned triangle): such a node
+ * cannot be glued to, and an end on it stays a free point.
+ * `rect` overrides the element's own rect (a measured render).
+ */
+export function nodePreset(e, rect = null) {
+  if (!e) return null;
+  const g = e.geometry;
+  if (e.kind === "path" && g?.type === "arc" && Math.abs(g.sweep) >= 360 && g.rx > 0 && g.ry > 0) {
+    return { prst: "ellipse", av: {}, box: rect ?? { x: g.cx - g.rx, y: g.cy - g.ry, w: 2 * g.rx, h: 2 * g.ry } };
+  }
+  // A band segment is written as its blockArc (or a full band as its donut)
+  // and glues at that preset's own sites.
+  if (e.kind === "path" && ["arc", "sector"].includes(g?.type) && e.fill && e.fill !== "none" && g.innerRatio > 0 && g.innerRatio < 1) {
+    const band = bandNative(e.id, g);
+    return band ? { prst: band.prst, av: band.av, box: rect ?? band.box } : null;
+  }
+  const box = rect ?? { x: e.x, y: e.y, w: e.w, h: e.h };
+  // Only an element the helpers draw as a box: a drawn figure or a stroke is
+  // no shape PowerPoint can glue to.
+  if (!(box.w > 0 && box.h > 0) || !NODE_KINDS.has(e.kind)) return null;
+  const s = drawnAsBox(e) ? e.shape : null;
+  if (s === "circle" || s === "ring" || s === "ellipse") return { prst: "ellipse", av: {}, box };
+  if (s === "rounded") return { prst: "roundRect", av: {}, box };
+  if (s === "pill") return { prst: "roundRect", av: { adj: 50000 }, box };
+  if (s === "diamond") return { prst: "diamond", av: {}, box };
+  if (s in CLIP_ADJ) {
+    // The helpers' clip polygons as the preset draws them: the notch/slant is
+    // a share of the WIDTH, the preset's adjust a share of the short side.
+    if (s === "chevron" && box.w < box.h) return null;
+    return { prst: s, av: { adj: Math.round((CLIP_ADJ[s] * box.w / Math.min(box.w, box.h)) * 100000) }, box };
+  }
+  if (!s || s === "rect" || !drawnAsBox(e)) return { prst: "rect", av: {}, box };
+  return null;
+}
+
+/** A node's connection sites in slot px, in cxnLst order (index = site). */
+export function nodeSites(node) {
+  return presetSites(node.prst, node.box.w, node.box.h, node.av ?? {}, { x: node.box.x, y: node.box.y });
+}
+
+// ---- Circles and ellipses through a trace.
+
+function solve3(m, v) {
+  const det = (a) => a[0][0] * (a[1][1] * a[2][2] - a[1][2] * a[2][1]) - a[0][1] * (a[1][0] * a[2][2] - a[1][2] * a[2][0]) + a[0][2] * (a[1][0] * a[2][1] - a[1][1] * a[2][0]);
+  const d = det(m);
+  if (Math.abs(d) < 1e-12) return null;
+  return [0, 1, 2].map((k) => det(m.map((row, i) => row.map((c, j) => (j === k ? v[i] : c)))) / d);
+}
+
+/** Least-squares (Kåsa) circle through points: `{ cx, cy, rx, ry }` or null. */
+export function circleFit(pts) {
+  if (pts.length < 3) return null;
+  const mx = pts.reduce((s, p) => s + p.x, 0) / pts.length, my = pts.reduce((s, p) => s + p.y, 0) / pts.length;
+  let sxx = 0, sxy = 0, syy = 0, sx = 0, sy = 0, sxz = 0, syz = 0, sz = 0;
+  for (const p of pts) {
+    const x = p.x - mx, y = p.y - my, z = x * x + y * y;
+    sxx += x * x; sxy += x * y; syy += y * y; sx += x; sy += y; sxz += x * z; syz += y * z; sz += z;
+  }
+  const s = solve3([[sxx, sxy, sx], [sxy, syy, sy], [sx, sy, pts.length]], [-sxz, -syz, -sz]);
+  if (!s) return null;
+  const cx = -s[0] / 2, cy = -s[1] / 2, r2 = cx * cx + cy * cy - s[2];
+  if (!(r2 > 0)) return null;
+  const r = Math.sqrt(r2);
+  return { cx: cx + mx, cy: cy + my, rx: r, ry: r };
+}
+
+/** Least-squares axis-aligned ellipse A·x² + C·y² + D·x + E·y = 1 (centred on the mean). */
+function ellipseFit(pts) {
+  if (pts.length < 5) return null;
+  const mx = pts.reduce((s, p) => s + p.x, 0) / pts.length, my = pts.reduce((s, p) => s + p.y, 0) / pts.length;
+  const rows = pts.map((p) => { const x = p.x - mx, y = p.y - my; return [x * x, y * y, x, y]; });
+  const n = 4, ata = Array.from({ length: n }, () => Array(n).fill(0)), atb = Array(n).fill(0);
+  for (const r of rows) for (let i = 0; i < n; i++) { atb[i] += r[i]; for (let j = 0; j < n; j++) ata[i][j] += r[i] * r[j]; }
+  // Gaussian elimination.
+  for (let c = 0; c < n; c++) {
+    let piv = c;
+    for (let r = c + 1; r < n; r++) if (Math.abs(ata[r][c]) > Math.abs(ata[piv][c])) piv = r;
+    if (Math.abs(ata[piv][c]) < 1e-12) return null;
+    [ata[c], ata[piv]] = [ata[piv], ata[c]];
+    [atb[c], atb[piv]] = [atb[piv], atb[c]];
+    for (let r = 0; r < n; r++) {
+      if (r === c) continue;
+      const f = ata[r][c] / ata[c][c];
+      for (let k = c; k < n; k++) ata[r][k] -= f * ata[c][k];
+      atb[r] -= f * atb[c];
+    }
+  }
+  const [A, C, D, E] = atb.map((v, i) => v / ata[i][i]);
+  if (!(A > 0 && C > 0)) return null;
+  const cx = -D / (2 * A), cy = -E / (2 * C);
+  const k = 1 + A * cx * cx + C * cy * cy;
+  if (!(k > 0)) return null;
+  return { cx: cx + mx, cy: cy + my, rx: Math.sqrt(k / A), ry: Math.sqrt(k / C) };
+}
+
+// ---- Scoring and search.
+
+// What a search descends on: the ordered RMS, with the worst point weighed in
+// (the max alone is flat almost everywhere). Selection reports the max.
+const searchError = (a, b) => { const e = pathErrors(a, b); return e.rms + 0.25 * e.max; };
+
+/**
+ * How far a native line may run from the concept's trace: a glued connector is
+ * held to its nodes' real sites, a free stroke to the ink. The draft check
+ * (draft-lines.mjs) uses the same rule, so the fitter's own output passes it.
+ */
+export const toleranceFor = (trace, glued) => glued
+  ? Math.max(NATIVE_TOL.gluedPx, NATIVE_TOL.gluedFrac * traceLength(trace))
+  : Math.max(NATIVE_TOL.freePx, NATIVE_TOL.freeFrac * traceLength(trace));
+
+function crossings(points, obstacles = [], skip = []) {
+  let hits = 0;
+  for (const t of obstacles) {
+    if (skip.some((r) => r && (contains(r, t) || (!t.text && !t.content && contains(t, r))))) continue;
+    const box = { x: t.x - 2, y: t.y - 2, w: t.w + 4, h: t.h + 4 };
+    for (let i = 0; i + 1 < points.length; i++) if (segmentHitsRect(points[i], points[i + 1], box)) { hits++; break; }
+  }
+  return hits;
+}
+
+/** Coordinate descent on a preset's adjusts; `score(av)` → number. */
+function descend(av0, names, score, first = 32000, last = 250) {
+  let best = { av: { ...av0 }, score: score(av0) };
+  for (let step = first; step >= last; step /= 2) {
+    for (let round = 0; round < 24; round++) {
+      let moved = false;
+      for (const n of names) for (const s of [step, -step]) {
+        const av = { ...best.av, [n]: Math.round(best.av[n] + s) };
+        const sc = score(av);
+        if (sc < best.score - 1e-9) { best = { av, score: sc }; moved = true; }
+      }
+      if (!moved) break;
+    }
+  }
+  return best;
+}
+
+// Seed values for a connector's adjusts: overshoot included for a one-handle
+// preset (a U-turn out of two same-side sites).
+const SEEDS_1 = [-30000, 15000, 50000, 85000, 130000];
+const SEEDS_2 = [15000, 40000, 65000, 90000];
+const SEEDS_3 = [20000, 50000, 80000];
+function seedGrid(names) {
+  if (!names.length) return [{}];
+  const values = [SEEDS_1, SEEDS_2, SEEDS_3][names.length - 1] ?? SEEDS_3;
+  let out = [{}];
+  for (const n of names) out = out.flatMap((av) => values.map((v) => ({ ...av, [n]: v })));
+  return out;
+}
+
+const inRange = (av) => Object.values(av).every((v) => v >= -NATIVE_TOL.adjOvershoot && v <= 100000 + NATIVE_TOL.adjOvershoot);
+
+// A bent connector whose handle folds a leg to nothing IS the simpler preset:
+// that candidate is left to the preset that draws it without the extra leg.
+const collapsed = (prst, pts) => prst.startsWith("bent") && pts.some((p, i) => i > 0 && dist(p, pts[i - 1]) < 1);
+
+function sitesNear(node, target, k) {
+  const sites = nodeSites(node);
+  if (!target) return sites.slice(0, k);
+  return [...sites].sort((a, b) => dist(a, target) - dist(b, target)).slice(0, k);
+}
+
+/**
+ * The best connector between two ends. `ends[i]` is `{ node, preset }` (glued;
+ * the site is searched) or `{ point }` (free). `trace` is the concept's path
+ * (null: reader declared a relation with no drawn path). `keep` fixes the
+ * preset (settle keeps a line's family). Returns a NativeLine (`object: "cxn"`).
+ */
+function fitConnector(ends, trace, { prsts = CONNECTOR_PRESETS, obstacles = [], keep = [null, null], crossPenalty = NATIVE_TOL.crossPenaltyPx, tol = null } = {}) {
+  const [a, b] = ends;
+  const centre = (n) => ({ x: n.box.x + n.box.w / 2, y: n.box.y + n.box.h / 2 });
+  const hasTrace = trace?.length >= 2;
+  // Where a glued end looks for its sites: the concept's attach point, else
+  // toward the other end.
+  const targetOf = (other, at) => (hasTrace ? at : other.point ?? centre(other.preset));
+  const options = (e, other, at, kept) => {
+    if (!e.node) return [{ point: e.point, x: e.point.x, y: e.point.y }];
+    const all = nodeSites(e.preset);
+    const near = sitesNear(e.preset, targetOf(other, at), NATIVE_TOL.siteCandidates);
+    if (kept != null && all[kept] && !near.includes(all[kept])) near.push(all[kept]);
+    return near.map((s) => ({ node: e.node, site: s.idx, x: s.x, y: s.y, angle: s.angle, changed: kept != null && s.idx !== kept }));
+  };
+  const A = options(a, b, hasTrace ? trace[0] : null, keep[0]), B = options(b, a, hasTrace ? trace.at(-1) : null, keep[1]);
+  const skip = [a.preset?.box, b.preset?.box];
+  const seen = hasTrace ? crossings(trace, obstacles, skip) : 0;
+  // A leg that leaves a glued site against its outward direction, where the
+  // concept gives no path to say so.
+  const against = (pts, end, atStart) => {
+    if (end.angle == null || pts.length < 2) return 0;
+    const [p, q] = atStart ? [pts[0], pts.find((r) => dist(r, pts[0]) > 1) ?? pts[1]] : [pts.at(-1), [...pts].reverse().find((r) => dist(r, pts.at(-1)) > 1) ?? pts.at(-2)];
+    const dir = Math.atan2(q.y - p.y, q.x - p.x) * 180 / Math.PI;
+    const d = Math.abs(((dir - end.angle + 540) % 360) - 180);
+    return d > 60 ? 1 : 0;
+  };
+  const scoreOf = (pts, s, e) => {
+    let v = hasTrace ? searchError(pts, trace) : traceLength(pts) + 50 * (against(pts, s, true) + against(pts, e, false));
+    v += NATIVE_TOL.siteChangePx * ((s.changed ? 1 : 0) + (e.changed ? 1 : 0));
+    if (obstacles.length) v += crossPenalty * Math.max(0, crossings(pts, obstacles, skip) - seen);
+    return v;
+  };
+  const seeds = [];
+  for (const prst of prsts) {
+    const names = adjustNames(prst);
+    for (const rot of prst === "straightConnector1" ? [0] : [0, 90]) for (const s of A) for (const e of B) {
+      if (dist(s, e) < NATIVE_TOL.samePointPx) continue;
+      for (const av of seedGrid(names)) {
+        const g = connectorGeometry(prst, s, e, rot, av);
+        if (!g || collapsed(prst, g.points)) continue;
+        seeds.push({ prst, rot, s, e, av, names, score: scoreOf(g.points, s, e) });
+      }
+    }
+  }
+  if (!seeds.length) return null;
+  // The best seeds of each prst/rot/site configuration (two: a three-handle
+  // preset has more than one basin).
+  const byConfig = new Map();
+  for (const c of seeds) {
+    const key = `${c.prst}|${c.rot}|${c.s.site ?? "p"}|${c.e.site ?? "p"}`;
+    byConfig.set(key, [...(byConfig.get(key) ?? []), c]);
+  }
+  const leaders = [...byConfig.values()].flatMap((list) => list.sort((x, y) => x.score - y.score).slice(0, NATIVE_TOL.seedsPerConfig));
+  // Every preset's best configurations get a coarse descent (so a preset whose
+  // seeds landed badly still competes); the leaders then a fine one.
+  const refine = (c, first, last) => {
+    if (!c.names.length) return c;
+    const r = descend(c.av, c.names, (av) => { const g = connectorGeometry(c.prst, c.s, c.e, c.rot, av); return g && inRange(av) && !collapsed(c.prst, g.points) ? scoreOf(g.points, c.s, c.e) : Infinity; }, first, last);
+    return { ...c, av: r.av, score: r.score };
+  };
+  const total = (c) => c.score + NATIVE_TOL.adjustBiasPx * c.names.length;
+  const coarse = [];
+  for (const prst of prsts) {
+    const mine = leaders.filter((c) => c.prst === prst).sort((x, y) => x.score - y.score).slice(0, NATIVE_TOL.refinePerPreset);
+    coarse.push(...mine.map((c) => refine(c, 16000, 4000)));
+  }
+  coarse.sort((x, y) => total(x) - total(y));
+  const end = (x) => (x.node ? { node: x.node, site: x.site } : { point: { x: x.x, y: x.y } });
+  const nativeOf = (c) => {
+    const n = { object: "cxn", prst: c.prst, av: c.av, rot: c.rot, from: end(c.s), to: end(c.e), start: { x: c.s.x, y: c.s.y }, end: { x: c.e.x, y: c.e.y } };
+    n.devPx = hasTrace ? pathDistance(nativePoints(n), trace) : null;
+    return n;
+  };
+  const native = nativeOf(coarse.slice(0, NATIVE_TOL.refineFinal).map((c) => refine(c, 2000, 250)).sort((x, y) => total(x) - total(y))[0]);
+  if (!(hasTrace && tol != null && native.devPx > tol)) return native;
+  // No preset follows the concept at these sites: every candidate misses by
+  // about as much, so the fewest legs win (within one tolerance of the best) —
+  // never a detour pinned at an adjust's limit that draws a loop the concept
+  // lacks.
+  const legs = (n) => { const pts = nativePoints(n); let k = 0; for (let i = 1; i < pts.length; i++) if (dist(pts[i], pts[i - 1]) > 1) k++; return k; };
+  const plain = coarse.map(nativeOf).filter((n) => n.devPx <= native.devPx + tol);
+  return plain.sort((x, y) => legs(x) - legs(y) || x.devPx - y.devPx)[0] ?? native;
+}
+
+/** The arc on a circle (or ellipse) that draws `pts`, or null when it would be a straight line. */
+function fitArc(pts, circle = null, slot = null) {
+  if (pts.length < 3) return null;
+  const tryOne = (c) => {
+    if (!c || !(c.rx > 0 && c.ry > 0)) return null;
+    // A short stroke on a huge circle is a straight line read as bowed — but
+    // a loop's own circle is given, not guessed from this one stroke.
+    if (!circle && Math.max(c.rx, c.ry) > NATIVE_TOL.straightRadiusSpan * Math.max(1, traceLength(pts))) return null;
+    // A circle guessed from one stroke stays inside the content slot: a gentle
+    // bend is a curved connector, not a sliver of a circle far off the slide.
+    if (!circle && slot && (c.cx - c.rx < -1 || c.cy - c.ry < -1 || c.cx + c.rx > slot.w + 1 || c.cy + c.ry > slot.h + 1)) return null;
+    const ang = (p) => Math.atan2(p.y - c.cy, p.x - c.cx) * 180 / Math.PI;
+    let sweep = 0;
+    for (let i = 1; i < pts.length; i++) sweep += ((ang(pts[i]) - ang(pts[i - 1]) + 540) % 360) - 180;
+    if (Math.abs(sweep) < 1) return null;
+    // The preset runs clockwise from adj1 to adj2 (y down): a counter-clockwise
+    // stroke is the same arc drawn from its other end.
+    const reversed = sweep < 0;
+    const [a0, a1] = reversed ? [ang(pts.at(-1)), ang(pts[0])] : [ang(pts[0]), ang(pts.at(-1))];
+    const box = { x: c.cx - c.rx, y: c.cy - c.ry, w: 2 * c.rx, h: 2 * c.ry };
+    const av = { adj1: Math.round(norm360(a0) * DEG), adj2: Math.round(norm360(a1) * DEG) };
+    const n = { object: "sp", prst: "arc", av, rot: 0, flipH: false, flipV: false, box, reversed };
+    const drawn = nativePoints(n);
+    // A loop's own circle may reach past the slot's edge (the arc shape's box
+    // is the whole circle, and no gate measures a line by its box: slot-fit
+    // skips line directives) — only its stroke stays inside. Refusing the box
+    // broke every loop drawn near the slot's edge into curved connectors and
+    // straight chains (66452cbd).
+    if (circle && slot && drawn.some((p) => p.x < -1 || p.y < -1 || p.x > slot.w + 1 || p.y > slot.h + 1)) return null;
+    n.score = pathDistance(reversed ? [...drawn].reverse() : drawn, pts);
+    return n;
+  };
+  if (circle) return tryOne(circle);
+  const round = tryOne(circleFit(pts));
+  const oval = tryOne(ellipseFit(pts));
+  return [round, oval].filter(Boolean).sort((x, y) => x.score - y.score)[0] ?? null;
+}
+
+/**
+ * A loop member's path on its loop's ONE circle, in the trace's direction: a
+ * reader samples each arc at a few scattered points, and its end points stop
+ * short of a node or run into it. A glued end whose node the circle passes
+ * through starts at that node's centre angle, and the part inside the node's
+ * outline is cut away, so the arc meets the node where the circle does.
+ */
+function loopTrace(trace, c, ends, box, round, n = 48) {
+  const ang = (p) => Math.atan2(p.y - c.cy, p.x - c.cx);
+  const at = (a) => ({ x: c.cx + c.rx * Math.cos(a), y: c.cy + c.ry * Math.sin(a) });
+  let sweep = 0;
+  for (let i = 1; i < trace.length; i++) sweep += ((ang(trace[i]) - ang(trace[i - 1]) + 3 * Math.PI) % (2 * Math.PI)) - Math.PI;
+  if (Math.abs(sweep) < 1e-3) return trace;
+  const endAngle = (e, p) => {
+    const b = box(e);
+    if (!b) return ang(p);
+    const centre = { x: b.x + b.w / 2, y: b.y + b.h / 2 };
+    const a = ang(centre);
+    return dist(at(a), centre) < Math.min(b.w, b.h) / 2 ? a : ang(p);
+  };
+  const a0 = endAngle(ends[0], trace[0]);
+  const a1 = endAngle(ends[1], trace.at(-1));
+  const dir = Math.sign(sweep), turn = 2 * Math.PI;
+  const span = dir * ((((a1 - a0) * dir) % turn + turn) % turn);
+  if (Math.abs(span) < 1e-3) return trace;
+  const pts = Array.from({ length: n + 1 }, (_, i) => at(a0 + (span * i) / n));
+  return sanitizeTrace(pts, box(ends[0]), box(ends[1]), { fromRound: round(ends[0]), toRound: round(ends[1]) });
+}
+
+/** The bracket or brace (any turn/mirror) that draws `pts`, or null. */
+function fitOpenShape(pts) {
+  const xs = pts.map((p) => p.x), ys = pts.map((p) => p.y);
+  const bb = { x: Math.min(...xs), y: Math.min(...ys), w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys) };
+  if (bb.w < 1 || bb.h < 1) return null;
+  const c = { x: bb.x + bb.w / 2, y: bb.y + bb.h / 2 };
+  const back = [...pts].reverse();
+  const seeds = [];
+  for (const prst of OPEN_SHAPES) for (const rot of [0, 90]) {
+    const box = rot ? { x: c.x - bb.h / 2, y: c.y - bb.w / 2, w: bb.h, h: bb.w } : bb;
+    for (const [flipH, flipV] of FLIPS) for (const reversed of [false, true]) {
+      const av = presetAdjusts(prst);
+      const score = (v) => { const g = shapeGeometry(prst, box, v, rot, flipH, flipV); return g ? searchError(g, reversed ? back : pts) : Infinity; };
+      seeds.push({ prst, rot, box, flipH, flipV, reversed, av, score, s: score(av) });
+    }
+  }
+  seeds.sort((x, y) => x.s - y.s);
+  let best = null;
+  for (const c2 of seeds.slice(0, NATIVE_TOL.refinePerPreset * OPEN_SHAPES.length)) {
+    const names = adjustNames(c2.prst);
+    // A curl radius or apex position lives inside the box.
+    const r = descend(c2.av, names, (v) => (Object.values(v).every((x) => x >= 0 && x <= 100000) ? c2.score(v) : Infinity), 8000, 125);
+    const total = r.score + NATIVE_TOL.adjustBiasPx * names.length;
+    if (!best || total < best.total) best = { ...c2, av: r.av, score: r.score, total };
+  }
+  if (!best) return null;
+  const n = { object: "sp", prst: best.prst, av: best.av, rot: best.rot, flipH: best.flipH, flipV: best.flipV, box: best.box, reversed: best.reversed };
+  n.score = pathDistance(nativePoints(n), best.reversed ? back : pts);
+  return n;
+}
+
+/** One straight or arc piece for a chain (`straight`: never an arc). */
+function fitPiece(pts, slot = null, straightOnly = false) {
+  const straight = { object: "cxn", prst: "straightConnector1", av: {}, rot: 0, from: { point: pts[0] }, to: { point: pts.at(-1) }, start: pts[0], end: pts.at(-1) };
+  straight.score = pathDistance([pts[0], pts.at(-1)], pts);
+  const arc = pts.length >= 3 && !straightOnly ? fitArc(pts, null, slot) : null;
+  return arc && arc.score < straight.score ? arc : straight;
+}
+
+// The index of the point farthest from the chord of pts (Ramer–Douglas–Peucker).
+function farthest(pts) {
+  const a = pts[0], b = pts.at(-1);
+  const len = dist(a, b) || 1;
+  let k = Math.floor(pts.length / 2), best = -1;
+  for (let i = 1; i < pts.length - 1; i++) {
+    const d = Math.abs((b.x - a.x) * (a.y - pts[i].y) - (a.x - pts[i].x) * (b.y - a.y)) / len;
+    if (d > best) { best = d; k = i; }
+  }
+  return k;
+}
+
+/** The fewest straight/arc pieces that draw a free stroke within `tol`. */
+function fitChain(trace, tol, slot = null, straightOnly = false) {
+  const pieces = [];
+  const split = (pts, depth) => {
+    const piece = fitPiece(pts, slot, straightOnly);
+    if (piece.score <= tol || pts.length <= 2 || depth >= 6) { pieces.push(piece); return; }
+    const k = farthest(pts);
+    split(pts.slice(0, k + 1), depth + 1);
+    split(pts.slice(k), depth + 1);
+  };
+  split(trace, 0);
+  return pieces.slice(0, NATIVE_TOL.maxChainPieces);
+}
+
+function unionBox(children) {
+  const pts = children.flatMap((c) => (c.object === "sp" ? [{ x: c.box.x, y: c.box.y }, { x: c.box.x + c.box.w, y: c.box.y + c.box.h }] : [c.start, c.end]));
+  const x = Math.min(...pts.map((p) => p.x)), y = Math.min(...pts.map((p) => p.y));
+  return { x, y, w: Math.max(1, Math.max(...pts.map((p) => p.x)) - x), h: Math.max(1, Math.max(...pts.map((p) => p.y)) - y) };
+}
+
+// One piece is the line itself; several are a group.
+const chainOrPiece = (id, pieces) => (pieces.length === 1 ? { ...pieces[0], devPx: pieces[0].score } : { ...chainNative(id, pieces), devPx: null });
+
+/** A chain of free pieces as one group NativeLine. */
+export function chainNative(id, pieces) {
+  const children = pieces.map((p, i) => ({ ...p, id: `${id}-${i + 1}` }));
+  return { object: "grp", id, children, box: unionBox(children) };
+}
+
+/**
+ * The native object for one Line (concept-lines.mjs). `nodes`: Map id →
+ * `nodePreset` result (a glued end whose node has none is a free point).
+ * `loop`: a shared circle `{ cx, cy, rx, ry }` for a loop member.
+ * Returns a NativeLine `{ id, object, prst, av, rot, flipH, flipV, from, to,
+ * start, end, box, children, reversed, devPx, tolPx, notes }`, or null when the
+ * Line has no drawable ends.
+ */
+export function fitNative(line, nodes = new Map(), loop = null, opts = {}) {
+  const notes = [];
+  const raw = (line.path?.points ?? []).filter(finite);
+  const ends = line.ends.map((end, i) => {
+    const preset = end.node ? nodes.get(end.node) : null;
+    if (end.node && preset) return { node: end.node, preset };
+    if (end.node) notes.push(`${line.id}: ${end.node} has no native preset to glue to; that end is a free point`);
+    const at = finite(end.at) ? end.at : raw[i === 0 ? 0 : raw.length - 1];
+    return finite(at) ? { point: { x: at.x, y: at.y } } : null;
+  });
+  if (ends.some((e) => !e)) return null;
+  const glued = ends.some((e) => e.node);
+  // The trace is cut where it runs inside a node's own outline — for the
+  // outlines its box describes (a band's box is its whole circle).
+  const box = (e) => (OUTLINE_BOX.has(e.preset?.prst) ? e.preset.box : null);
+  const round = (e) => e.preset?.prst === "ellipse";
+  let trace = raw.length >= 2 ? sanitizeTrace(raw, box(ends[0]), box(ends[1]), { fromRound: round(ends[0]), toRound: round(ends[1]) }) : null;
+  if (!glued && trace) {
+    // A free stroke's ends ARE the ink's ends.
+    trace = [ends[0].point, ...trace.slice(1, -1), ends[1].point];
+  }
+  if (loop && trace?.length >= 3) trace = loopTrace(trace, loop, ends, box, round);
+  const tol = trace ? toleranceFor(trace, glued) : null;
+  // The reader's own word on the path's character: a curve is never given
+  // sharp elbows, an orthogonal path never a curve.
+  const family = FAMILY_BY_KIND[line.path?.kind] ?? CONNECTOR_PRESETS;
+  opts = { ...opts, prsts: opts.prsts ?? family };
+  // A glued fit that misses the concept because a node has no connection
+  // site near where the concept attaches (a band ring's three sites): that
+  // end is freed onto the ink when that brings the line within tolerance —
+  // glue that draws a different line is worse than a free end on the right one.
+  const freedWhereNoSite = (fit) => {
+    // The farthest sites first; then any end whose site sits more than half a
+    // tolerance off the ink (its glue alone may carry the line out).
+    for (const reach of [tol, tol / 2]) {
+      const r = freeBeyond(fit, reach);
+      if (r) return r;
+    }
+    return null;
+  };
+  const freeBeyond = (fit, reach) => {
+    const opt = ends.map((e, i) => {
+      if (!e.node) return e;
+      const at = i === 0 ? trace[0] : trace.at(-1);
+      return Math.min(...nodeSites(e.preset).map((q) => dist(q, at))) > reach ? { point: { x: at.x, y: at.y }, freed: e.node } : e;
+    });
+    if (!opt.some((e) => e.freed)) return null;
+    const refit = fitConnector(opt, trace, { ...opts, tol });
+    if (!refit || !(refit.devPx < fit.devPx) || refit.devPx > tol) return null;
+    for (const e of opt) if (e.freed) notes.push(`[line:note] ${line.id}: ${e.freed} has no connection site near where the concept attaches — that end is free on the ink`);
+    return refit;
+  };
+  let n;
+  // A loop member is the loop's own arc: the circle is what the concept draws,
+  // and a connector glued at side sites leaves along its box's axis where the
+  // circle crosses at an angle — it can only bend back onto the circle, an
+  // S-wobble per edge (36da373d: four curvedConnector4/5 within tolerance
+  // made a round ring wavy). A glued connector draws a loop member only when
+  // no arc on the circle fits the slot.
+  if (glued && !(loop && trace && fitArc(trace, loop, opts.slot))) {
+    // A relation is ONE glued connector, never a chain.
+    n = fitConnector(ends, trace, { ...opts, tol });
+    const off = n && tol != null && n.devPx > tol;
+    // A loop member no glued connector follows is the loop's own arc: one
+    // circle for the whole loop, drawn free (its ends sit on the ink).
+    const arc = off && loop ? fitArc(trace, loop, opts.slot) : null;
+    if (arc && arc.score < n.devPx) {
+      n = { ...arc, devPx: arc.score };
+      notes.push(`[line:warn] ${line.id}: drawn as an arc on its loop's circle — no connector glued at the nodes' sites follows it within ${Math.round(tol)}px`);
+    } else if (off && (n = freedWhereNoSite(n) ?? n) && n.devPx > tol) {
+      // Glue is kept: the end sits at the node's nearest real site and the
+      // distance is named (the plan's I3), never silently re-shaped.
+      notes.push(`[line:warn] ${line.id}: the glued connector runs ${Math.round(n.devPx)}px from the concept's line (tolerance ${Math.round(tol)}px) — the closest a ${n.prst} glued at the nodes' own sites can draw it`);
+    }
+  } else if (loop && trace && fitArc(trace, loop, opts.slot)) {
+    // A free loop member is an arc on the loop's ONE circle.
+    const arc = fitArc(trace, loop, opts.slot);
+    n = { ...arc, devPx: arc.score };
+    if (arc.score > tol) notes.push(`[line:warn] ${line.id}: an arc on its loop's circle, ${Math.round(arc.score)}px from the concept's own stroke`);
+  } else if (line.role === "mark" && trace) {
+    // A glyph mark (tick, cross, chevron, plus) is its straight strokes with
+    // round caps: three vertices of a chevron always fit an arc exactly, and a
+    // bowed chevron is a malformed one.
+    const pieces = fitChain(trace, Math.max(NATIVE_TOL.markPx, NATIVE_TOL.freeFrac * traceLength(trace)), opts.slot, true);
+    n = chainOrPiece(line.id, pieces);
+    if (n?.object === "grp") n.mark = true;
+  } else if (!trace || trace.length === 2 || line.path?.kind === "straight") {
+    const [s, e] = ends.map((x) => x.point);
+    n = dist(s, e) < NATIVE_TOL.samePointPx ? null : { object: "cxn", prst: "straightConnector1", av: {}, rot: 0, from: { point: s }, to: { point: e }, start: s, end: e, devPx: trace ? pathDistance([s, e], trace) : 0 };
+  } else {
+    // Candidates compared on the smooth error (a tie on the worst point is
+    // noise); the tolerance is held on the worst point.
+    const judged = (cand, bias) => {
+      const drawn = nativePoints(cand);
+      const e = pathErrors(cand.reversed ? [...drawn].reverse() : drawn, trace);
+      return { n: cand, dev: e.max, score: e.rms + 0.25 * e.max + bias };
+    };
+    const cands = [];
+    const cxn = fitConnector(ends, trace, { ...opts, tol });
+    if (cxn) cands.push(judged(cxn, NATIVE_TOL.adjustBiasPx * adjustNames(cxn.prst).length));
+    // An arc's angles are closed form, not searched: no adjust bias.
+    const arc = fitArc(trace, loop, opts.slot);
+    if (arc) cands.push(judged(arc, 0));
+    // A connector already on the ink leaves nothing for a bracket to win.
+    if (!(cxn?.devPx <= NATIVE_TOL.freePx / 2)) {
+      const shape = fitOpenShape(trace);
+      if (shape) cands.push(judged(shape, NATIVE_TOL.adjustBiasPx * adjustNames(shape.prst).length));
+    }
+    const best = cands.sort((x, y) => x.score - y.score)[0];
+    if (best && best.dev <= tol) n = { ...best.n, devPx: best.dev };
+    else n = chainOrPiece(line.id, fitChain(trace, tol, opts.slot));
+  }
+  if (!n) return null;
+  return { ...n, id: line.id, tolPx: tol, notes };
+}
+
+/**
+ * A bus: elbows leaving (or entering) one site of one node on the same turn
+ * whose knees nearly coincide share ONE rail — each member's adjust is set so
+ * its knee sits on the members' common coordinate. Mutates `natives`
+ * (NativeLines); returns the rails it aligned, as notes.
+ */
+export function alignRails(natives) {
+  const notes = [];
+  const groups = new Map();
+  for (const n of natives) {
+    if (n?.object !== "cxn" || n.prst !== "bentConnector3") continue;
+    for (const [end, key] of [[n.from, "from"], [n.to, "to"]]) {
+      if (!end?.node) continue;
+      const k = `${key}|${end.node}|${end.site}|${n.rot}`;
+      groups.set(k, [...(groups.get(k) ?? []), n]);
+    }
+  }
+  const axis = (n) => (n.rot === 90 ? "y" : "x");
+  const knee = (n) => n.start[axis(n)] + (n.end[axis(n)] - n.start[axis(n)]) * (n.av.adj1 ?? 50000) / 100000;
+  for (const [k, members] of groups) {
+    const usable = members.filter((n) => Math.abs(n.end[axis(n)] - n.start[axis(n)]) > 1);
+    if (usable.length < 2) continue;
+    const knees = usable.map(knee);
+    if (Math.max(...knees) - Math.min(...knees) > NATIVE_TOL.railPx) continue;
+    const rail = knees.reduce((s, v) => s + v, 0) / knees.length;
+    for (const n of usable) n.av = { ...n.av, adj1: Math.round(((rail - n.start[axis(n)]) / (n.end[axis(n)] - n.start[axis(n)])) * 100000) };
+    notes.push(`${usable.map((n) => n.id).join(", ")}: one rail at ${Math.round(rail)}px (${k.split("|")[1]})`);
+  }
+  return notes;
+}
+
+/**
+ * Loop members share ONE circle (a reader's per-arc circles scatter; the loop
+ * it saw is one). Curved Lines the reader gave one `loop` id are members
+ * however far one was drawn off the ring — the id is the reader's word on the
+ * structure, the drawing is a generated image's. Lines without an id join a
+ * group when the circle fitted over all their points holds every member within
+ * `loopFrac` of its radius. A round node the circle encloses, its centre
+ * within `loopFrac` of the circle's, is the loop's hub: the circle is centred
+ * on it. `nodes`: Map id → `nodePreset` result. Returns Map lineId → circle.
+ */
+export function loopCircles(lines, nodes = new Map()) {
+  const cand = [];
+  for (const l of lines) {
+    if (!["arc", "curve"].includes(l.path?.kind)) continue;
+    const pts = (l.path.points ?? []).filter(finite);
+    if (pts.length >= 3 && circleFit(pts)) cand.push({ l, pts });
+  }
+  const fits = (members) => {
+    const c = circleFit(members.flatMap((x) => x.pts));
+    if (!c) return null;
+    const worst = Math.max(...members.flatMap((x) => x.pts.map((p) => Math.abs(Math.hypot(p.x - c.cx, p.y - c.cy) - c.rx))));
+    return worst <= NATIVE_TOL.loopFrac * c.rx ? c : null;
+  };
+  const declared = new Map();
+  const groups = [];
+  for (const x of cand) {
+    const id = loopId(x.l.loop);
+    if (id) {
+      if (!declared.has(id)) declared.set(id, []);
+      declared.get(id).push(x);
+      continue;
+    }
+    const g = groups.find((gr) => fits([...gr, x]));
+    if (g) g.push(x);
+    else groups.push([x]);
+  }
+  const out = new Map();
+  const assign = (g, c) => {
+    if (!c) return;
+    const hubbed = onHub(c, g.flatMap((x) => x.pts), nodes);
+    for (const x of g) out.set(x.l.id, hubbed);
+  };
+  for (const g of declared.values()) if (g.length >= 2) assign(g, circleFit(g.flatMap((x) => x.pts)));
+  for (const g of groups) if (g.length >= 2) assign(g, fits(g));
+  return out;
+}
+
+// The reader numbers a loop's strokes (1, 2, …); anything else is no loop.
+const loopId = (v) => (Number.isInteger(v) ? String(v) : null);
+
+/** `c` centred on the round node it encloses near its centre (radius refitted), else `c`. */
+function onHub(c, pts, nodes) {
+  let hub = null;
+  for (const n of nodes.values()) {
+    if (n?.prst !== "ellipse") continue;
+    const h = { x: n.box.x + n.box.w / 2, y: n.box.y + n.box.h / 2 };
+    const off = Math.hypot(h.x - c.cx, h.y - c.cy);
+    if (Math.max(n.box.w, n.box.h) / 2 >= c.rx || off > NATIVE_TOL.loopFrac * c.rx) continue;
+    if (!hub || off < hub.off) hub = { ...h, off };
+  }
+  if (!hub) return c;
+  const r = pts.reduce((s, p) => s + Math.hypot(p.x - hub.x, p.y - hub.y), 0) / pts.length;
+  return { cx: hub.x, cy: hub.y, rx: r, ry: r };
+}
+
+/**
+ * A filled band read as an arc with a hole: `donut` for a full ring,
+ * `blockArc` for a segment (clockwise from adj1 to adj2, thickness adj3).
+ * `g`: `{ cx, cy, rx, ry, start, sweep, innerRatio }` (parametric degrees).
+ */
+export function bandNative(id, g) {
+  if (!(g?.rx > 0 && g?.ry > 0 && g.innerRatio > 0 && g.innerRatio < 1)) return null;
+  const box = { x: g.cx - g.rx, y: g.cy - g.ry, w: 2 * g.rx, h: 2 * g.ry };
+  const thick = Math.min(50000, Math.round(((1 - g.innerRatio) / 2) * 100000));
+  if (Math.abs(g.sweep) >= 360) return { id, object: "sp", prst: "donut", av: { adj: thick }, rot: 0, flipH: false, flipV: false, box };
+  const visual = (t) => norm360(Math.atan2(g.ry * Math.sin(t * Math.PI / 180), g.rx * Math.cos(t * Math.PI / 180)) * 180 / Math.PI);
+  const [a, b] = g.sweep >= 0 ? [g.start, g.start + g.sweep] : [g.start + g.sweep, g.start];
+  return { id, object: "sp", prst: "blockArc", av: { adj1: Math.round(visual(a) * DEG), adj2: Math.round(visual(b) * DEG), adj3: thick }, rot: 0, flipH: false, flipV: false, box };
+}
+
+/** A stroked full ring nothing glues to: an unfilled `ellipse` shape. */
+export function ringNative(id, g) {
+  if (!(g?.rx > 0 && g?.ry > 0)) return null;
+  return { id, object: "sp", prst: "ellipse", av: {}, rot: 0, flipH: false, flipV: false, box: { x: g.cx - g.rx, y: g.cy - g.ry, w: 2 * g.rx, h: 2 * g.ry } };
+}
+
+/**
+ * Re-solve a glued connector after its nodes moved (settle): the preset and
+ * the glue stay; rot, adjusts and — only where it pays for itself — a site are
+ * searched again. `n`: the directive as parsed (`{ prst, from, to }`, a glued
+ * end `{ node, site }`, a free one `{ point }`); `nodes`: Map id → nodePreset
+ * over the measured rects; `trace`: the concept's path, or null.
+ */
+export function resolveGlued({ prst, from, to }, nodes, { trace = null, obstacles = [], crossPenalty } = {}) {
+  const end = (ref) => (ref.node ? (nodes.get(ref.node) ? { node: ref.node, preset: nodes.get(ref.node) } : null) : { point: ref.point });
+  const ends = [end(from), end(to)];
+  if (ends.some((e) => !e)) return null;
+  const n = fitConnector(ends, trace, { prsts: [prst], obstacles, keep: [from.site ?? null, to.site ?? null], ...(crossPenalty != null ? { crossPenalty } : {}) });
+  if (n && trace?.length >= 2) n.devPx = pathDistance(nativePoints(n), trace);
+  return n;
+}
+
+// ---- The directive the exporter reads (contract §§1–3).
+
+const adjAttr = (av) => {
+  const entries = Object.entries(av ?? {});
+  return entries.length ? ` data-adj="${entries.map(([k, v]) => `${k}:${Math.round(v)}`).join(",")}"` : "";
+};
+const CAP_TYPES = new Set(["triangle", "stealth", "arrow", "oval", "diamond"]);
+const CAP_SIZE = { sm: "sm", md: "med", med: "med", lg: "lg" };
+
+/**
+ * A Line end's cap as `type:w:len`, or null: the concept's size, or the
+ * largest smaller one its route of `routePx` carries — sm when none does (the
+ * render gate then names the connector).
+ */
+export function capAttr(cap, routePx = Infinity, strokePx = 0) {
+  if (!cap || !CAP_TYPES.has(cap.type)) return null;
+  const sizes = ["lg", "med", "sm"];
+  const fits = sizes.slice(sizes.indexOf(CAP_SIZE[cap.size] ?? "med")).find((k) => headRoutePx(k, strokePx) <= routePx - 0.5);
+  const s = fits ?? "sm";
+  return `${cap.type}:${s}:${s}`;
+}
+
+const q = (s) => JSON.stringify(String(s));
+
+/**
+ * One NativeLine as JSX. `paint`: `{ className, style: ["borderWidth: …", …],
+ * caps: [start, end] (`type:w:len` or null), dash, linecap, plotOwner }`. A
+ * closed preset's fill is a `fill: …` style entry (CSS `fill`, contract §2).
+ * Coordinates are slot px; `origin` shifts them into a group's frame.
+ */
+export function lineDirective(n, paint = {}, origin = { x: 0, y: 0 }) {
+  const cls = paint.className ?? "connector-muted";
+  const owner = `${paint.plotOwner ? ` data-sm-plot-owner=${q(paint.plotOwner)}` : ""}${paint.stack ? ` data-sm-stack=${q(paint.stack)}` : ""}${paint.divides ? ` data-sm-divides=${q(paint.divides)}` : ""}`;
+  // A mirrored bracket or brace is its own preset — and runs the other way
+  // (a flipped leftBracket goes bottom→top, a rightBracket top→bottom).
+  const renamed = n.object === "sp" && MIRRORED[n.prst] && n.flipH;
+  const [capS, capE] = Boolean(n.reversed) !== Boolean(renamed) ? [paint.caps?.[1], paint.caps?.[0]] : [paint.caps?.[0], paint.caps?.[1]];
+  const caps = `${capS ? ` data-cap-start="${capS}"` : ""}${capE ? ` data-cap-end="${capE}"` : ""}`;
+  const dash = paint.dash && paint.dash !== "solid" ? ` data-dash="${paint.dash}"` : "";
+  const linecap = paint.linecap && paint.linecap !== "flat" ? ` data-linecap="${paint.linecap}"` : "";
+  const style = [...(paint.style ?? [])];
+  if (n.object === "grp") {
+    const b = n.box;
+    const kids = n.children.map((c, i) => lineDirective(c, {
+      ...paint, plotOwner: null,
+      caps: [i === 0 ? paint.caps?.[0] : null, i === n.children.length - 1 ? paint.caps?.[1] : null],
+      // Round caps join a glyph's strokes; a plain chain keeps its own.
+      linecap: n.mark ? "rnd" : paint.linecap,
+    }, { x: b.x, y: b.y }));
+    return `<div data-sm-line-group id=${q(n.id)}${owner} style={{ position: "absolute", left: ${r1(b.x - origin.x)}, top: ${r1(b.y - origin.y)}, width: ${r1(b.w)}, height: ${r1(b.h)} }}>${kids.join("")}</div>`;
+  }
+  if (n.object === "cxn") {
+    const ref = (e, p) => (e.node ? `#${e.node}` : pointRef({ x: p.x - origin.x, y: p.y - origin.y }));
+    const site = (e, k) => (e.node ? ` data-${k}-site="${e.site}"` : "");
+    const rot = n.rot ? ` data-rot="${n.rot}"` : "";
+    return `<div data-connector id=${q(n.id)}${owner} data-from="${ref(n.from, n.start)}"${site(n.from, "from")} data-to="${ref(n.to, n.end)}"${site(n.to, "to")} data-prst="${n.prst}"${adjAttr(n.av)}${rot}${caps}${dash}${linecap} className="${cls}"${style.length ? ` style={{ ${style.join(", ")} }}` : ""} />`;
+  }
+  let prst = n.prst, flipH = n.flipH;
+  if (renamed) { prst = MIRRORED[prst]; flipH = false; }
+  const flip = flipH && n.flipV ? "hv" : flipH ? "h" : n.flipV ? "v" : "";
+  const b = n.box;
+  return `<div data-sm-line id=${q(n.id)}${owner} data-prst="${prst}"${adjAttr(n.av)}${n.rot ? ` data-rot="${n.rot}"` : ""}${flip ? ` data-flip="${flip}"` : ""}${caps}${dash}${linecap} className="${cls}" style={{ position: "absolute", left: ${r1(b.x - origin.x)}, top: ${r1(b.y - origin.y)}, width: ${r1(b.w)}, height: ${r1(b.h)}${style.map((s) => `, ${s}`).join("")} }} />`;
+}