slidemind 0.3.20 → 0.4.0

package/src/builders/concept-lines.mjs

@@ -0,0 +1,509 @@
+// Line topology: every stroke the reader saw, as ONE Line (docs: the line
+// plan's model). A connector the reader declared, an open path, a rule and a
+// stroked ring all go through the same intake, `toLines(spec)`; a separate
+// arrowhead triangle or end dot at a stroke end is that end's cap.
+//
+// Glue has exactly two sources (I2): the reader declared the end (a
+// connector's from/to, or a stroke end whose `strokeEnds` says its ink
+// touches an element), or — where the reader said nothing about that end —
+// the ink touches the node's outline (LINE_TOL). Nothing is glued for being
+// "near enough": a free end stays where the ink ends.
+//
+// Every open stroke — path or rule, straight or diagonal, headed or not —
+// leaves here as a native line (spec.connectors). Rings stay closed outlines
+// and glyph marks stay drawn forms.
+import { isGlyphStroke, sideOf, strokeTraces, traceMidpoint } from './line-fit.mjs';
+import { illustrationOwner } from './concept-relationships.mjs';
+import { cleanText, textIsPrinted } from './concept-text.mjs';
+
+/**
+ * Every tolerance the intake uses, in one table. Generic: never tuned per
+ * slide or per design.
+ */
+export const LINE_TOL = Object.freeze({
+  // I2: an end touches a node when its distance to the node's outline is at
+  // most max(contactPx, half the stroke width) — the ink's own edge — plus,
+  // only where a head is drawn or declared at THAT end, the head's length
+  // capped at headReachMaxPx (its tip, not the shaft, meets the node). It is
+  // never a proximity reach that grows with the stroke.
+  contactPx: 3,
+  headReachMaxPx: 12,
+  // A head triangle or end dot is an end's cap when its centre lies within
+  // capReach · its radius of the end (never less than capFloorPx).
+  capReach: 1.5,
+  capFloorPx: 5,
+  // A filled triangle larger than this is a shape (a roof), not a head…
+  headMaxPx: 30,
+  // …and a disc larger than this is a node (a timeline stop), not an end dot.
+  dotMaxPx: 12,
+  // Arrowhead length in stroke widths, DrawingML's sm / med / lg.
+  capLen: Object.freeze({ sm: 2, md: 3, lg: 5 }),
+  // The width the tolerances assume when the reader gave none. The Line
+  // itself carries no width then (null): the design's default weight draws it.
+  defaultWidthPx: 2,
+});
+
+const NODE_KINDS = new Set(['card', 'panel', 'disc', 'badge', 'shape']);
+const ROUND = new Set(['circle', 'ellipse', 'ring']);
+const SIZES = new Set(['sm', 'md', 'lg']);
+// Caps with a length along the stroke (an oval dot sits centred on the end).
+const HEAD_CAPS = new Set(['triangle', 'arrow', 'stealth', 'diamond']);
+// The path a reader connector's route names.
+const CONNECTOR_KIND = { straight: 'straight', elbow: 'orthogonal', curved: 'curve', arc: 'arc', polyline: 'polyline' };
+const dist = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+// The reader's no-text stand-ins (":null") are wordless too: the intake runs before
+// normalizeForLayout cleans text, and a placeholder disc must not become a glue target.
+const wordless = e => cleanText(e.text, { printed: textIsPrinted(e) }) == null;
+const noCap = () => ({ type: 'none', size: null, sizePx: 0, colorHex: null, from: null });
+const dashOf = d => (d === 'dashed' ? 'dash' : d === 'dotted' ? 'sysDot' : 'solid');
+const isRound = n => n.kind === 'disc' || ROUND.has(n.shape);
+const holds = (n, r) => r.x >= n.x - 1 && r.y >= n.y - 1 && r.x + r.w <= n.x + n.w + 1 && r.y + r.h <= n.y + n.h + 1;
+const centroid = pts => ({ x: pts.reduce((s, q) => s + q.x, 0) / pts.length, y: pts.reduce((s, q) => s + q.y, 0) / pts.length });
+const finite = p => Number.isFinite(p?.x) && Number.isFinite(p?.y);
+
+// The DrawingML size bucket a cap of `px` shows on a stroke of width `w`.
+const sizeBucket = (px, w) => {
+  const k = px / Math.max(0.5, w);
+  return k <= 2.5 ? 'sm' : k <= 4 ? 'md' : 'lg';
+};
+
+function segmentDistance(p, a, b) {
+  const dx = b.x - a.x, dy = b.y - a.y, l = dx * dx + dy * dy;
+  const t = l ? Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / l)) : 0;
+  return Math.hypot(p.x - a.x - t * dx, p.y - a.y - t * dy);
+}
+
+/**
+ * Distance from `p` to a node's outline (inside or out): its outline polygon
+ * when the reader gave one (an irregular panel), an ellipse for a round node,
+ * its rect otherwise.
+ */
+export function outlineDistance(p, n) {
+  const poly = (n.outline ?? []).filter(finite);
+  if (poly.length >= 3) return Math.min(...poly.map((a, i) => segmentDistance(p, a, poly[(i + 1) % poly.length])));
+  if (isRound(n)) {
+    const rx = n.w / 2, ry = n.h / 2, dx = p.x - n.x - rx, dy = p.y - n.y - ry;
+    const rho = Math.hypot(dx / rx, dy / ry);
+    return rho < 1e-9 ? Math.min(rx, ry) : Math.hypot(dx, dy) * Math.abs(1 - 1 / rho);
+  }
+  const ox = Math.max(n.x - p.x, 0, p.x - n.x - n.w), oy = Math.max(n.y - p.y, 0, p.y - n.y - n.h);
+  if (ox || oy) return Math.hypot(ox, oy);
+  return Math.min(p.x - n.x, n.x + n.w - p.x, p.y - n.y, n.y + n.h - p.y);
+}
+
+// ---- Path kind: what the stroke's points ARE, never what its glue suggests.
+
+function pathKindOf(e, pts) {
+  const g = e.geometry;
+  if (g?.type === 'arc') return Math.abs(g.sweep) >= 360 ? 'ring' : 'arc';
+  if (g?.type === 'spline' || (g?.type === 'path' && (g.commands ?? []).some(c => c?.op === 'C' || c?.op === 'Q'))) return 'curve';
+  if (pts.length === 2) return 'straight';
+  const axis = pts.slice(1).every((p, i) => Math.abs(p.x - pts[i].x) <= 1 || Math.abs(p.y - pts[i].y) <= 1);
+  return axis ? 'orthogonal' : 'polyline';
+}
+
+function ringTrace(g) {
+  const at = a => ({ x: g.cx + g.rx * Math.cos((a * Math.PI) / 180), y: g.cy + g.ry * Math.sin((a * Math.PI) / 180) });
+  return Array.from({ length: 37 }, (_, i) => at(g.start + i * 10));
+}
+
+/**
+ * A rule's trace: its two points, in the reader's order, when it gave them (a
+ * diagonal arrow or an axis stays diagonal); else the centre line of its thin
+ * rect, along the long side.
+ */
+export function ruleTrace(e) {
+  const pts = (e.points ?? []).filter(finite);
+  if (pts.length >= 2) return [pts[0], pts.at(-1)];
+  return 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 }];
+}
+
+function sameTrace(a, b) {
+  if (!b || a.length < 3 || a.length !== b.length) return false;
+  if (Math.min(dist(a[0], b[0]) + dist(a.at(-1), b.at(-1)), dist(a[0], b.at(-1)) + dist(a.at(-1), b[0])) > 2) return false;
+  const remaining = [...b];
+  for (const p of a) {
+    const i = remaining.findIndex(q => dist(p, q) <= 1);
+    if (i < 0) return false;
+    remaining.splice(i, 1);
+  }
+  return true;
+}
+
+// The reader's own coordinate inventory of a stroke, for duplicate detection
+// against its connectors (Bezier controls included: order does not matter).
+function inventory(e) {
+  const g = e.geometry;
+  if (g?.type === 'spline') return g.closed ? null : g.points;
+  if (g?.type === 'arc') {
+    if (Math.abs(g.sweep) >= 360) return null;
+    const at = a => ({ x: g.cx + g.rx * Math.cos(a * Math.PI / 180), y: g.cy + g.ry * Math.sin(a * Math.PI / 180) });
+    return [at(g.start), at(g.start + g.sweep / 2), at(g.start + g.sweep)];
+  }
+  if (g?.type === 'path') {
+    const cmds = g.commands ?? [];
+    if (cmds.filter(c => c.op === 'M').length !== 1 || cmds.some(c => c.op === 'Z')) return null;
+    const pts = [];
+    for (const c of cmds) {
+      if (c.op === 'C' || c.op === 'Q') pts.push({ x: c.x1, y: c.y1 });
+      if (c.op === 'C') pts.push({ x: c.x2, y: c.y2 });
+      pts.push({ x: c.x, y: c.y });
+    }
+    return pts.length >= 2 && pts.every(p => Number.isFinite(p.x) && Number.isFinite(p.y)) ? pts : null;
+  }
+  return e.points?.length >= 2 ? e.points : null;
+}
+
+// A Line restored from the connector `applyLines` wrote for it: the topology
+// as decided then, with whatever has been written on the connector since.
+function restored(c) {
+  return {
+    ...c.line,
+    stroke: { ...c.line.stroke, widthPx: c.strokeWidth ?? c.line.stroke.widthPx, colorHex: c.colorHex ?? c.line.stroke.colorHex },
+    path: { ...c.line.path, points: c.points ?? c.line.path.points },
+  };
+}
+
+/**
+ * The cap the reader declared at one end, where no separate head or dot was
+ * drawn there: its `strokeEnds` end when it gave one (cap type and length),
+ * else a triangle when it said the end is headed, at its sm/md/lg bucket.
+ */
+function declaredCap(se, headed, bucket, w) {
+  const size = SIZES.has(bucket) ? bucket : null;
+  if (se) {
+    if (!se.cap || se.cap === 'none') return noCap();
+    const px = Number.isFinite(se.capSize) && se.capSize > 0 ? se.capSize : 0;
+    return { type: se.cap, size: size ?? (px ? sizeBucket(px, w) : null), sizePx: px || (size ? LINE_TOL.capLen[size] * w : 0), colorHex: null, from: null };
+  }
+  if (!headed) return noCap();
+  return { type: 'triangle', size, sizePx: size ? LINE_TOL.capLen[size] * w : 0, colorHex: null, from: null };
+}
+
+// The node ids the reader named as a stroke end anywhere on the slide.
+function declaredEndpoints(elements, connectors) {
+  const ids = new Set();
+  for (const c of connectors) for (const id of [c.from, c.to]) if (id) ids.add(id);
+  for (const x of [...elements, ...connectors]) for (const k of ['start', 'end']) if (x.strokeEnds?.[k]?.element) ids.add(x.strokeEnds[k].element);
+  return ids;
+}
+
+// The reader often traces an arrowhead's arm into the stroke: the ink runs to
+// the tip, then a few px back along one side of the head. That stub is the
+// head, not the stroke — left in, the head sits on it and points back down
+// (x74N1 cloud 8: a rising trend line ended in a 7px hook with a down-pointing
+// head). The stroke ends at the tip.
+function dropHeadArms(line) {
+  for (const i of [0, 1]) {
+    const pts = line.path.points;
+    if (pts.length < 3 || !HEAD_CAPS.has(line.ends[i].cap.type)) continue;
+    const [arm, tip, prev] = i ? [pts.at(-1), pts.at(-2), pts.at(-3)] : [pts[0], pts[1], pts[2]];
+    const back = (tip.x - prev.x) * (arm.x - tip.x) + (tip.y - prev.y) * (arm.y - tip.y) < 0;
+    if (!back || dist(arm, tip) > LINE_TOL.headReachMaxPx) continue;
+    line.path = { ...line.path, points: i ? pts.slice(0, -1) : pts.slice(1) };
+    if (line.path.points.length === 2 && (line.path.kind === 'polyline' || line.path.kind === 'orthogonal')) line.path.kind = 'straight';
+    const end = line.ends[i];
+    if (!end.at || dist(end.at, arm) <= 1) end.at = tip;
+  }
+  return line;
+}
+
+/**
+ * Read every Line of a spec. Returns `{ lines, duplicates, converted }`:
+ * `duplicates` are strokes that redraw a reader connector (`{ id, of }`),
+ * `converted` the element ids `applyLines` replaces by a connector (open
+ * strokes and the head triangles they claimed).
+ */
+export function readLines(spec) {
+  const elements = spec.elements ?? [];
+  const connectors = spec.connectors ?? [];
+  const byId = new Map(elements.map(e => [e.id, e]));
+  const kids = new Map();
+  for (const e of elements) if (e.parent) kids.set(e.parent, [...(kids.get(e.parent) ?? []), e]);
+  const valid = connectors.filter(c => !c.line && byId.has(c.from) && byId.has(c.to) && c.from !== c.to);
+  const heads = elements.filter(e => e.kind === 'path' && wordless(e) && e.fill && e.fill !== 'none' && !e.geometry && e.points?.length === 3 && Math.max(e.w ?? 0, e.h ?? 0) <= LINE_TOL.headMaxPx);
+  const dots = elements.filter(e => (e.kind === 'disc' || (e.kind === 'shape' && ROUND.has(e.shape))) && wordless(e) && e.w > 0 && e.h > 0 && Math.max(e.w, e.h) <= LINE_TOL.dotMaxPx && !kids.has(e.id));
+  const claimed = new Set();
+  // Caps a previous pass already decided stay claimed (idempotence).
+  for (const c of connectors) for (const end of c.line?.ends ?? []) if (end.cap?.from) claimed.add(end.cap.from);
+
+  // Pass 1: the lines drawn as elements.
+  const drawn = [];
+  const duplicates = [];
+  const converted = new Set();
+  for (const e of elements) {
+    if (illustrationOwner(elements, e) || !wordless(e)) continue;
+    let traces = [], source = null;
+    if (e.kind === 'rule' && (e.w > 0 || e.h > 0 || e.points?.length >= 2)) { traces = [ruleTrace(e)]; source = 'rule'; }
+    else if (e.kind === 'path' && e.geometry?.type === 'arc' && Math.abs(e.geometry.sweep) >= 360 && (!e.fill || e.fill === 'none') && e.stroke) { traces = [ringTrace(e.geometry)]; source = 'ring'; }
+    else { traces = strokeTraces(e); source = 'path'; }
+    if (!traces.length) continue;
+    const mark = source === 'path' && isGlyphStroke(e, traces);
+    if (source === 'path' && !mark) {
+      const pts = inventory(e);
+      const of = pts && valid.find(c => sameTrace(pts, c.points));
+      if (of) { duplicates.push({ id: e.id, of }); continue; }
+    }
+    if (source !== 'ring' && !mark) converted.add(e.id);
+    const widthPx = Number.isFinite(e.stroke?.width) && e.stroke.width > 0 ? e.stroke.width : null;
+    traces.forEach((t, k) => {
+      const outer = [k === 0, k === traces.length - 1];
+      drawn.push({
+        e, source, mark, outer,
+        // The reader's own word on each outer end (contact, cap), when it gave one.
+        se: [outer[0] ? e.strokeEnds?.start : null, outer[1] ? e.strokeEnds?.end : null],
+        bucket: [outer[0] ? e.ends?.start : null, outer[1] ? e.ends?.end : null],
+        line: {
+          id: traces.length > 1 ? `${e.id}-${k + 1}` : e.id,
+          role: mark ? 'mark' : source === 'rule' ? 'divider' : source === 'ring' ? 'frame' : 'relation',
+          source: { kind: source, id: e.id },
+          ...(e.loop != null ? { loop: e.loop } : {}),
+          ends: [t[0], t.at(-1)].map(at => ({ node: null, at, cap: noCap(), contact: 'none', side: null })),
+          path: { kind: source === 'rule' ? pathKindOf({}, t) : pathKindOf(e, t), points: t, corners: 'sharp' },
+          stroke: { widthPx, colorHex: e.stroke?.colorHex ?? e.colorHex ?? (source === 'rule' ? e.fillHex : null) ?? null, token: e.stroke?.colorToken ?? e.colorToken ?? null, dash: dashOf(e.stroke?.dash ?? e.dash) },
+          read: { color: e.color ?? (source === 'rule' ? 'muted' : null) },
+          notes: [],
+        },
+      });
+    });
+  }
+
+  // Caps: each separate head triangle or end dot goes to the NEAREST stroke
+  // end within its reach, whichever stroke that is (heads before dots) — a
+  // rule listed first never takes a path's head. An end left without one
+  // carries the cap the reader declared there.
+  const capEnds = drawn.filter(d => !d.mark && d.source !== 'ring').flatMap(d => d.line.ends.map((end, i) => ({ d, end, i })).filter(x => x.d.outer[x.i]));
+  const reachOf = el => {
+    const c = el.points ? centroid(el.points) : { x: el.x + el.w / 2, y: el.y + el.h / 2 };
+    const r = el.points ? Math.max(...el.points.map(q => dist(q, c))) : Math.max(el.w, el.h) / 2;
+    return { c, reach: Math.max(LINE_TOL.capFloorPx, r * LINE_TOL.capReach) };
+  };
+  const pairs = [];
+  for (const [rank, list] of [[0, heads], [1, dots]]) {
+    for (const el of list) {
+      if (claimed.has(el.id)) continue;
+      const { c, reach } = reachOf(el);
+      for (const ce of capEnds) {
+        const d = dist(ce.end.at, c);
+        if (d <= reach) pairs.push({ rank, d, el, ce });
+      }
+    }
+  }
+  pairs.sort((p, q) => p.rank - q.rank || p.d - q.d);
+  const capped = new Set();
+  for (const { el, ce } of pairs) {
+    if (claimed.has(el.id) || capped.has(ce.end)) continue;
+    claimed.add(el.id);
+    capped.add(ce.end);
+    const w = ce.d.line.stroke.widthPx ?? LINE_TOL.defaultWidthPx;
+    const isHead = heads.includes(el);
+    const span = k => (isHead ? Math.max(...el.points.map(q => q[k])) - Math.min(...el.points.map(q => q[k])) : el[k === 'x' ? 'w' : 'h']);
+    const sizePx = Math.max(span('x'), span('y'));
+    const declared = SIZES.has(ce.d.bucket[ce.i]) ? ce.d.bucket[ce.i] : null;
+    ce.end.cap = { type: isHead ? 'triangle' : 'oval', size: declared ?? sizeBucket(sizePx, w), sizePx, colorHex: el.colorHex ?? el.fillHex ?? null, from: el.id };
+    // A head that leaves with its stroke leaves the elements too.
+    if (isHead) converted.add(el.id);
+  }
+  for (const { d, end, i } of capEnds) {
+    if (!capped.has(end)) end.cap = declaredCap(d.se[i], Boolean(d.bucket[i]) && d.bucket[i] !== 'none', d.bucket[i], d.line.stroke.widthPx ?? LINE_TOL.defaultWidthPx);
+  }
+  for (const d of drawn) if (!d.mark && d.source !== 'ring') dropHeadArms(d.line);
+
+  // Pass 2: glue. Where the reader said what an end touches, that decides;
+  // elsewhere only ink contact with a glue target does. A glue target is a
+  // node a line can meaningfully join: one carrying words (its own or a
+  // descendant's), or one the reader named as a stroke end somewhere on the
+  // slide. A wordless disc, badge or panel is decoration unless declared.
+  const gone = new Set([...converted, ...duplicates.map(d => d.id)]);
+  const endpoints = declaredEndpoints(elements, connectors);
+  const worded = n => !wordless(n) || (kids.get(n.id) ?? []).some(worded);
+  const nodes = elements.filter(n => NODE_KINDS.has(n.kind) && n.w > 0 && n.h > 0 && !claimed.has(n.id) && (endpoints.has(n.id) || worded(n)));
+  for (const { e, line, mark, source, se } of drawn) {
+    if (mark || source === 'ring') continue;
+    // A stroke drawn inside a node glues by ink only to nodes inside that same
+    // container — never to it or out of it (a refresh mark in a disc beside a hub).
+    const box = nodes.filter(n => n.id !== e.id && holds(n, e)).sort((p, q) => p.w * p.h - q.w * q.h)[0];
+    const reachable = box ? nodes.filter(n => n !== box && holds(box, n)) : nodes;
+    const w = line.stroke.widthPx ?? LINE_TOL.defaultWidthPx;
+    const hits = line.ends.map((end, i) => {
+      if (se[i]) {
+        const id = se[i].element;
+        const n = id && id !== e.id && !gone.has(id) ? byId.get(id) : null;
+        // A stroke lying wholly inside the element it names divides that
+        // element; it does not join it (a row rule ending on its panel's edge
+        // was routed to the panel's side site, a loop across the rows).
+        return se[i].contact === 'touches' && n && !holds(n, e) ? { n, contact: 'declared' } : null;
+      }
+      const head = HEAD_CAPS.has(end.cap.type) ? Math.min(end.cap.sizePx || LINE_TOL.capLen.md * w, LINE_TOL.headReachMaxPx) : 0;
+      const tol = Math.max(LINE_TOL.contactPx, w / 2) + head;
+      const touching = reachable
+        .filter(n => n.id !== e.id)
+        .map(n => ({ n, d: outlineDistance(end.at, n) }))
+        .filter(h => h.d <= tol)
+        .sort((p, q) => p.d - q.d || p.n.w * p.n.h - q.n.w * q.n.h);
+      return touching[0] ? { n: touching[0].n, contact: 'ink' } : null;
+    });
+    // Both ends on one node is a mark on it, not a relation between things.
+    if (hits[0] && hits[0].n === hits[1]?.n) continue;
+    hits.forEach((h, i) => {
+      if (!h) return;
+      Object.assign(line.ends[i], { node: h.n.id, contact: h.contact, side: sideOf(line.ends[i].at, h.n) });
+    });
+    // A rule that carries a head or joins a node relates things; a bare one divides.
+    if (source === 'rule' && line.ends.some(x => x.node || HEAD_CAPS.has(x.cap.type))) line.role = 'relation';
+  }
+
+  // The reader's connectors: glue as declared — unless its `strokeEnds` says
+  // the ink stops short of that element (gap) or joins nothing (free). An end
+  // naming a stroke that is itself a line (or a removed duplicate) is a point
+  // where it touched it.
+  const declared = connectors.map((c, i) => {
+    if (c.line) return restored(c);
+    const pts = (c.points ?? []).filter(finite);
+    const widthPx = Number.isFinite(c.strokeWidth) && c.strokeWidth > 0 ? c.strokeWidth : null;
+    const w = widthPx ?? LINE_TOL.defaultWidthPx;
+    const arrow = c.arrow ?? 'end';
+    const end = (k, id, side, point, at, headed) => {
+      const se = c.strokeEnds?.[k];
+      const p = point ?? pts.at(at) ?? null;
+      const glued = Boolean(id && byId.has(id) && !gone.has(id) && (!se || se.contact === 'touches' || !p));
+      return {
+        node: glued ? id : null,
+        at: p,
+        cap: declaredCap(se, headed, c.head, w),
+        contact: glued ? 'declared' : 'none',
+        side: glued ? side ?? null : null,
+      };
+    };
+    const ends = [
+      end('start', c.from, c.fromSide, c.fromPoint, 0, arrow === 'start' || arrow === 'both'),
+      end('end', c.to, c.toSide, c.toPoint, -1, arrow === 'end' || arrow === 'both'),
+    ];
+    return dropHeadArms({
+      id: c.id ?? `connector-${i + 1}`,
+      role: 'relation',
+      source: { kind: 'connector', id: c.id ?? null, index: i },
+      ...(c.loop != null ? { loop: c.loop } : {}),
+      ends,
+      path: { kind: CONNECTOR_KIND[c.route] ?? (pts.length === 2 ? 'straight' : 'polyline'), points: pts, corners: c.corner === 'curve' || c.corner === 'rounded' ? 'rounded' : 'sharp' },
+      stroke: { widthPx, colorHex: c.colorHex ?? null, token: null, dash: dashOf(c.style) },
+      read: { color: c.color ?? null },
+      notes: [],
+    });
+  });
+  return { lines: [...declared, ...drawn.map(d => d.line)], duplicates, converted: [...converted] };
+}
+
+/** Every Line of a spec (see `readLines`). */
+export function toLines(spec) {
+  return readLines(spec).lines;
+}
+
+// The connector's arrow/head words for a Line's caps.
+function arrowOf([s, t]) {
+  const arrowed = [s, t].map(end => HEAD_CAPS.has(end.cap.type));
+  return {
+    arrow: arrowed[0] && arrowed[1] ? 'both' : arrowed[0] ? 'start' : arrowed[1] ? 'end' : 'none',
+    head: (arrowed[1] ? t.cap.size : null) ?? (arrowed[0] ? s.cap.size : null),
+  };
+}
+
+// A Line end in the reader's own `strokeEnds` vocabulary.
+const strokeEndOf = end => ({ element: end.node, contact: end.node ? 'touches' : 'free', cap: end.cap.type, capSize: end.cap.sizePx || null });
+
+/**
+ * The connector a stroke Line is written as: glued ends name their node, free
+ * ends are points, its caps are its `strokeEnds`, and the Line itself rides
+ * along (`line`) so the topology is decided once.
+ */
+function toConnector(line, slot) {
+  const [s, t] = line.ends;
+  const glued = Boolean(s.node && t.node);
+  const kind = line.path.kind;
+  const route = kind === 'straight' ? 'straight' : !glued ? 'arc' : kind === 'arc' || kind === 'curve' ? 'curved' : 'elbow';
+  const inSlot = p => ({ x: Math.max(0, Math.min(slot.w, p.x)), y: Math.max(0, Math.min(slot.h, p.y)) });
+  return {
+    id: line.id,
+    from: s.node, to: t.node,
+    ...(s.node ? { fromSide: s.side } : { fromPoint: inSlot(s.at) }),
+    ...(t.node ? { toSide: t.side } : { toPoint: inSlot(t.at) }),
+    route, ...arrowOf(line.ends),
+    ...(route === 'arc' ? { via: traceMidpoint(line.path.points) } : {}),
+    style: line.stroke.dash === 'solid' ? 'solid' : 'dashed',
+    color: line.read.color ?? 'accent', colorHex: line.stroke.colorHex,
+    strokeWidth: line.stroke.widthPx,
+    strokeEnds: { start: strokeEndOf(s), end: strokeEndOf(t) },
+    ...(line.loop != null ? { loop: line.loop } : {}),
+    points: line.path.points,
+    line,
+  };
+}
+
+/**
+ * Write a spec's stroke Lines into it: each open stroke (path or rule)
+ * becomes a connector (glued where the reader declared it or the ink touches
+ * a glue target, a point end otherwise), the head triangles it claimed go
+ * with it, and a stroke that redraws a reader connector is removed. A reader
+ * connector whose `strokeEnds` frees an end gets that end as a point, and its
+ * arrow/head follow its caps. Rings and glyph marks stay drawn elements.
+ * Idempotent. Returns the notes.
+ */
+export function applyLines(spec) {
+  const { lines, duplicates, converted } = readLines(spec);
+  const elements = spec.elements ?? [];
+  const byId = new Map(elements.map(e => [e.id, e]));
+  const connectors = spec.connectors ?? [];
+  const removed = new Set(converted);
+  const notes = [];
+  for (const d of duplicates) {
+    removed.add(d.id);
+    notes.push(`${d.id}: removed duplicate stroke of native connector ${d.of.from} -> ${d.of.to}`);
+  }
+  const slot = spec.slot;
+  const joined = new Map();
+  for (const line of lines) {
+    if (line.source.kind !== 'connector' || !connectors[line.source.index] || connectors[line.source.index].line) continue;
+    const c = connectors[line.source.index];
+    line.ends.forEach((end, i) => {
+      const [key, pointKey, sideKey] = i ? ['to', 'toPoint', 'toSide'] : ['from', 'fromPoint', 'fromSide'];
+      const se = c.strokeEnds?.[i ? 'end' : 'start'];
+      if (end.node && !end.at && se && se.contact !== 'touches') notes.push(`${c.id ?? `${c.from} -> ${c.to}`}: the reader saw that end's ink not touch ${c[key]} but gave no point for it; it stays glued`);
+      if (!c[key] || end.node || !end.at || !byId.has(c[key]) || removed.has(c[key])) return;
+      notes.push(`${c.id ?? `${c.from} -> ${c.to}`}: the reader saw the ink stop short of ${c[key]}; that end is free`);
+      c[key] = null;
+      c[pointKey] = { x: Math.max(0, Math.min(slot.w, end.at.x)), y: Math.max(0, Math.min(slot.h, end.at.y)) };
+      delete c[sideKey];
+    });
+    if (c.strokeEnds) Object.assign(c, arrowOf(line.ends));
+  }
+  for (const line of lines) {
+    // Only strokes still drawn as elements: a line restored from its
+    // connector is already written.
+    if ((line.source.kind !== 'path' && line.source.kind !== 'rule') || line.role === 'mark' || !removed.has(line.source.id)) continue;
+    connectors.push(toConnector(line, slot));
+    const [s, t] = line.ends;
+    if (s.node && t.node) joined.set(line.source.id, [...(joined.get(line.source.id) ?? []), `${s.node} -> ${t.node}`]);
+  }
+  for (const [id, pairs] of joined) notes.push(`${id}: joined stroke into native connector ${pairs.join(', ')}`);
+  // A connector the reader attached to a stroke that is now a line keeps its
+  // own end where it touched it — a free end, not a dangling id.
+  for (const c of connectors) {
+    for (const [key, pointKey, at] of [['from', 'fromPoint', 0], ['to', 'toPoint', -1]]) {
+      if (!c[key] || !removed.has(c[key]) || !(c.points?.length >= 2)) continue;
+      c[pointKey] = c.points.at(at);
+      c[key] = null;
+    }
+  }
+  if (removed.size) {
+    spec.elements = elements.filter(e => !removed.has(e.id));
+    // Preserve labels/children, even when they were attached to a stroke.
+    for (const e of spec.elements) if (removed.has(e.parent)) e.parent = byId.get(e.parent)?.parent ?? null;
+  }
+  spec.connectors = connectors;
+  // An arrow is a line with a head: dividers, rules and rails are lines the
+  // image draws, not arrows it counts (x74N1 QBR 5: arrows=9 from nine rules).
+  if (spec.counts) { spec.counts.elements = spec.elements.length; spec.counts.arrows = connectors.filter(c => (c.arrow ?? 'end') !== 'none').length; }
+  return notes;
+}