slidemind 0.3.20 → 0.4.0

package/src/builders/rule-shift.mjs

@@ -0,0 +1,96 @@
+// A free vertical separator between two columns (live f85c57c3: four one-line
+// titles, "Permissions", "Audit trail", each running 12–30px past its box
+// through the separator beside it) is an ornament of the gutter, not a wall:
+// where a title set at the ramp is wider than the room the concept drew up to
+// it, the separator moves into its gutter, clear of the title's words, so
+// long as the gutter still holds it clear of the next column. The title keeps
+// its one line and its size; the separator keeps its length and its column,
+// its card or panel, and the slot. The separators of a declared set move
+// alike, by one px, or none does.
+import { correspond, gluedIds, linePoints, lineSpans, moveLine, repeatGroups } from "./repeat-groups.mjs";
+
+/**
+ * The gutter right of a free vertical rule: its stroke's left edge `x` and the
+ * px `room` it may move right, or null when it is no free vertical line or
+ * something already spans it. It ends at `right` (the inner edge of the room
+ * the text owns: its card, else the slot), the panel the rule lies on, and
+ * whatever lies right of it along its length — an element or a line segment.
+ */
+function gutter(spec, rule, { right, beside }, gap) {
+  const pts = linePoints(rule);
+  if (rule.from || rule.to || gluedIds(rule).length || pts.length < 2) return null;
+  const xs = pts.map((p) => p.x);
+  const ys = pts.map((p) => p.y);
+  if (Math.max(...xs) - Math.min(...xs) > 1) return null;
+  const half = (Number.isFinite(rule.strokeWidth) ? rule.strokeWidth : 1) / 2;
+  const x = Math.max(...xs) + half;
+  const y0 = Math.min(...ys);
+  const y1 = Math.max(...ys);
+  let limit = right;
+  for (const o of spec.elements ?? []) {
+    if (!beside(o) || !(o.w > 0 && o.h > 0) || o.y >= y1 || o.y + o.h <= y0 || o.x + o.w <= x) continue;
+    // A panel behind the whole rule is its ground: the rule stays on it.
+    if (o.x <= x - 2 * half && o.x + o.w >= x && o.y <= y0 && o.y + o.h >= y1) limit = Math.min(limit, o.x + o.w);
+    else if (o.x < x) return null; // something already spans the rule: it is no gutter
+    else limit = Math.min(limit, o.x);
+  }
+  for (const l of lineSpans(spec, y0, y1)) if (l.line !== rule && l.x >= x) limit = Math.min(limit, l.x);
+  return { x: x - 2 * half, room: limit - gap - x };
+}
+
+// The texts that correspond to `text` across its declared set, member by member.
+function counterparts(spec, text) {
+  const byId = new Map((spec.elements ?? []).map((e) => [e.id, e]));
+  // A virtual member (repeat-groups.mjs) is the loose parts it lists.
+  const inTree = (e, root) => {
+    const roots = root.ids ?? [root.id];
+    for (let p = e, g = 0; p && g < 32; p = p.parent ? byId.get(p.parent) : null, g++) if (roots.includes(p.id)) return true;
+    return false;
+  };
+  for (const g of repeatGroups(spec)) {
+    const i = g.members.findIndex((m) => inTree(text, m));
+    if (i < 0) continue;
+    if (g.members[i] === text) return g.members.map((m) => ({ member: m, t: m }));
+    const kids = correspond(spec.elements, g.members);
+    const k = kids?.[i].indexOf(text) ?? -1;
+    return k < 0 ? [] : g.members.map((m, j) => ({ member: m, t: kids[j][k] }));
+  }
+  return null;
+}
+
+/**
+ * Move the separator beside `text` right: its stroke at `least` or later
+ * (the text's ink plus the gap), as far as `to` (PowerPoint's slack) where
+ * the gutter allows. In a declared set every corresponding separator (the
+ * one at the same place in its member) moves by the same px — the least
+ * room across them, at least what the widest text needs — or none moves.
+ * `fit(t)` → `{ rule, right, to, least, beside, holds }` for a text (null
+ * when it has no rule beside it); a move after which a text that needed it
+ * still does not `holds()` its ink is undone. Returns the px moved, or null.
+ */
+export function shiftSeparator(spec, text, fit, gap = 4) {
+  const lead = fit(text);
+  if (!lead) return null;
+  const set = counterparts(spec, text);
+  let rows = [lead];
+  if (set) {
+    const at = set.find((c) => c.t === text)?.member;
+    const offset = (rule, m) => linePoints(rule).map((p) => [p.x - m.x, p.y - m.y]);
+    const same = (a, b) => a.length === b.length && a.every((p, i) => Math.abs(p[0] - b[i][0]) <= 2 && Math.abs(p[1] - b[i][1]) <= 2);
+    rows = set.map(({ member, t }) => {
+      const f = t === text ? lead : t && fit(t);
+      return f && at && same(offset(f.rule, member), offset(lead.rule, at)) ? f : null;
+    });
+    if (!rows.length || rows.some((r) => !r) || new Set(rows.map((r) => r.rule)).size !== rows.length) return null;
+  }
+  const gutters = rows.map((r) => gutter(spec, r.rule, r, gap));
+  if (gutters.some((g) => !g)) return null;
+  const must = rows.map((r, i) => Math.ceil(r.least - gutters[i].x));
+  const want = Math.max(...rows.map((r, i) => Math.ceil(r.to - gutters[i].x)));
+  const dx = Math.min(want, Math.floor(Math.min(...gutters.map((g) => g.room))));
+  if (Math.max(...must) <= 0 || dx < Math.max(...must)) return null;
+  for (const r of rows) moveLine(r.rule, dx, 0);
+  if (rows.every((r, i) => must[i] <= 0 || r.holds())) return dx;
+  for (const r of rows) moveLine(r.rule, -dx, 0);
+  return null;
+}

package/src/builders/seat.mjs

@@ -0,0 +1,354 @@
+// Where a child sits in its carrier is a RELATION the reader declares (`seat`,
+// concept-spec-schema.ts), built here from the carrier's rect and the child's
+// own size — never the offset the painting happened to draw. The painting is a
+// sketch: a glyph lands a few px off its disc's middle, a text beside a disc
+// a little above the card's axis, an accent tab three px short of the card's
+// edge (x100b QBR 5/6; 23% of the children of round carriers in 300 reader
+// specs sit >2px off, 47% of rings off their hub). The same construction
+// serves every pass: the normaliser (painted sizes), the template build
+// (repeat-groups.mjs) and the settle (measured text heights, text-card-fit.mjs
+// / card-height.mjs), so a seated child stays seated when its carrier moves,
+// grows or is rebuilt from a template.
+//   seat.x: left | center | right | span — against that edge at the drawn
+//           inset, centred, or edge to edge (a text spans the inner width).
+//   seat.y: top | middle | bottom | span.
+//   around: the round element a ring, arc or loop stroke circles — it takes
+//           that hub's centre (the hub anchors the slide; the ring follows).
+// A seat the reader did not declare changes nothing: the child keeps the
+// painting's offset, as before. No tolerance decides anything here.
+import { translateElement } from "./concept-geometry.mjs";
+import { paintOrdered } from "./concept-layout.mjs";
+import { fixCopies, linePoints, linesWithin, translateFigure } from "./repeat-groups.mjs";
+
+export const SEAT_X = Object.freeze(["left", "center", "right", "span"]);
+export const SEAT_Y = Object.freeze(["top", "middle", "bottom", "span"]);
+const INSET = 8; // px a spanning text keeps from its carrier's edge (text-card-fit.mjs)
+const half = (v) => Math.round(v * 2) / 2;
+const isText = (e) => (e.kind === "text" || e.kind === "number") && e.text != null && !(e.fill && e.fill !== "none");
+
+/** The reader's seat, validated per axis; null when none was declared. */
+export function seatOf(e) {
+  const s = e?.seat;
+  if (!s || typeof s !== "object") return null;
+  const x = SEAT_X.includes(s.x) ? s.x : null;
+  const y = SEAT_Y.includes(s.y) ? s.y : null;
+  return x || y ? { x, y } : null;
+}
+
+/** The drawn insets of `e` in its frame `f` ({x,y,w,h}), kept for the edge anchors. */
+const insetsOf = (e, f) => ({ left: e.x - f.x, top: e.y - f.y, right: f.x + f.w - e.x - e.w, bottom: f.y + f.h - e.y - e.h });
+
+// ---- The frame a seat refers to -------------------------------------------
+// A parent that stacks content — rows of an icon and its text between
+// dividers, a header over them, columns beside each other — seats a child in
+// the child's own ROW and COLUMN, not in the whole parent: `middle` is the
+// middle of the band between what lies above the row (a divider, the header)
+// and what lies below it (x101: four metric rows all seated "middle" in one
+// card collapsed onto the card's centre, and their dividers ran through the
+// text). The structure is read ONCE from the painting (`seatBand`: the
+// siblings sharing the child's rows and columns, what lies beyond them, the
+// dividers between) and the band is measured from where those are NOW, so a
+// row follows a grown neighbour and a divider the levers moved.
+const axisLine = (c, u) => {
+  const pts = linePoints(c);
+  if (pts.length < 2) return null;
+  const vs = pts.map((p) => p[u]);
+  const v = u === "y" ? "x" : "y";
+  if (Math.max(...vs) - Math.min(...vs) > 2) return null;
+  return { at: (Math.min(...vs) + Math.max(...vs)) / 2, lo: Math.min(...pts.map((p) => p[v])), hi: Math.max(...pts.map((p) => p[v])) };
+};
+const lineRef = (spec, c) => c.id ?? `#${(spec.connectors ?? []).indexOf(c)}`;
+const lineByRef = (spec, ref) => (ref == null ? null : (spec.connectors ?? []).find((c, i) => c.id === ref || `#${i}` === ref) ?? null);
+
+// One axis of the band: `u` is the axis the band runs along (y for rows).
+// A LINE is the siblings sharing e's rows (an icon and its text); the band's
+// bounds are what lies beyond the line: the nearest other sibling or divider.
+function bandOf(spec, e, p, sibs, lines, u) {
+  const v = u === "y" ? "x" : "y";
+  const [size, cross] = u === "y" ? ["h", "w"] : ["w", "h"];
+  const overlap = (a, b) => a[u] < b[u] + b[size] && b[u] < a[u] + a[size];
+  const lineOf = (seed, pool) => {
+    const line = [seed];
+    for (let grew = true; grew;) {
+      grew = false;
+      for (const o of pool) if (!line.includes(o) && line.some((g) => overlap(g, o))) { line.push(o); grew = true; }
+    }
+    return line;
+  };
+  const extent = (items) => [Math.min(...items.map((g) => g[u])), Math.max(...items.map((g) => g[u] + g[size]))];
+  const spansOf = (items) => {
+    const c0 = Math.min(...items.map((g) => g[v]));
+    const c1 = Math.max(...items.map((g) => g[v] + g[cross]));
+    return (o) => o[v] < c1 && c0 < o[v] + o[cross];
+  };
+  const seps = lines.map((c) => ({ c, l: axisLine(c, u) })).filter((x) => x.l);
+  // Several children all seated "middle" in one band are NOT joined into a
+  // stack here: a stack is the reader's declaration (`stacks`, stack.mjs). A
+  // child's line is the siblings sharing its rows (an icon and its text).
+  const block = [lineOf(e, sibs)];
+  const members = block.flat();
+  const [lo, hi] = extent(members);
+  const spans = spansOf(members);
+  const ends = block.map(extent);
+  return {
+    group: block[block.findIndex((l) => l.includes(e))].map((g) => g.id),
+    block: block.map((l) => l.map((g) => g.id)),
+    gaps: ends.slice(1).map(([a], i) => a - ends[i][1]),
+    before: sibs.filter((o) => !members.includes(o) && o[u] + o[size] <= lo + 0.5 && spans(o)).map((o) => o.id),
+    after: sibs.filter((o) => !members.includes(o) && o[u] >= hi - 0.5 && spans(o)).map((o) => o.id),
+    sepBefore: seps.filter((x) => x.l.at <= lo + 0.5 && spans({ [v]: x.l.lo, [cross]: x.l.hi - x.l.lo })).sort((a, b) => b.l.at - a.l.at)[0]?.c ?? null,
+    sepAfter: seps.filter((x) => x.l.at >= hi - 0.5 && spans({ [v]: x.l.lo, [cross]: x.l.hi - x.l.lo })).sort((a, b) => a.l.at - b.l.at)[0]?.c ?? null,
+  };
+}
+
+/**
+ * Where a centred child sits along `u`: its block (seatBand) centred in the
+ * band `[lo, lo+len)`, lines stacked at their drawn gaps on their CURRENT
+ * sizes (`at(o)` → a text's measured rect), the child centred in its line.
+ * null without a recorded block.
+ */
+export function blockStart(spec, e, u, lo, len, at = (o) => o) {
+  const band = e.seatBand?.[u];
+  if (!band?.block) return null;
+  const size = u === "y" ? "h" : "w";
+  const byId = new Map((spec.elements ?? []).map((o) => [o.id, o]));
+  const sizeOf = (id) => { const o = byId.get(id); return o ? (at(o)[size] ?? o[size]) : 0; };
+  const lineSizes = band.block.map((ids) => Math.max(0, ...ids.map(sizeOf)));
+  const gaps = band.gaps ?? [];
+  const total = lineSizes.reduce((a, b) => a + b, 0) + gaps.reduce((a, b) => a + b, 0);
+  let start = lo + (len - total) / 2;
+  for (const [i, ids] of band.block.entries()) {
+    if (ids.includes(e.id)) return half(start + (lineSizes[i] - sizeOf(e.id)) / 2);
+    start += lineSizes[i] + (gaps[i] ?? 0);
+  }
+  return null;
+}
+
+/** The painting's structure around `e` in `p`, recorded once (`seatBand`). */
+export function recordBand(spec, e, p) {
+  const els = spec.elements ?? [];
+  const sibs = els.filter((o) => o.parent === p.id && o !== e && o.w > 0 && o.h > 0 && o.kind !== "rule");
+  const lines = linesWithin(spec, p);
+  const strip = (b) => ({ group: b.group, block: b.block, gaps: b.gaps, before: b.before, after: b.after, sepBefore: b.sepBefore ? lineRef(spec, b.sepBefore) : null, sepAfter: b.sepAfter ? lineRef(spec, b.sepAfter) : null });
+  return { y: strip(bandOf(spec, e, p, sibs, lines, "y")), x: strip(bandOf(spec, e, p, sibs, lines, "x")) };
+}
+
+/**
+ * The frame `e`'s seat refers to, measured now: the parent's box cut to the
+ * child's row and column by the nearest sibling or divider on each side.
+ * `at(o)` → the current rect of an element (a text's measured one).
+ */
+export function seatFrame(spec, e, p, at = (o) => o) {
+  const byId = new Map((spec.elements ?? []).map((o) => [o.id, o]));
+  const rect = (o) => ({ x: o.x, y: o.y, w: o.w, h: o.h, ...at(o) });
+  const f = { x: p.x, y: p.y, w: p.w, h: p.h };
+  const b = e.seatBand;
+  if (!b) return f;
+  for (const [u, size] of [["y", "h"], ["x", "w"]]) {
+    const band = b[u];
+    if (!band) continue;
+    let lo = f[u];
+    let hi = f[u] + f[size];
+    for (const id of band.before ?? []) { const o = byId.get(id); if (o) lo = Math.max(lo, rect(o)[u] + rect(o)[size]); }
+    for (const id of band.after ?? []) { const o = byId.get(id); if (o) hi = Math.min(hi, rect(o)[u]); }
+    const la = axisLine(lineByRef(spec, band.sepBefore) ?? { }, u);
+    const lb = axisLine(lineByRef(spec, band.sepAfter) ?? { }, u);
+    if (la) lo = Math.max(lo, la.at);
+    if (lb) hi = Math.min(hi, lb.at);
+    if (hi - lo > 1) { f[u] = lo; f[size] = hi - lo; }
+  }
+  return f;
+}
+
+/**
+ * The top a y-seat gives a child `h` tall in a carrier band [top, top+H).
+ * `top` (and a text's `span`) keep the drawn inset; null for no y-seat.
+ */
+export function seatTop(e, top, H, h, insets = e.seatInset ?? null) {
+  const y = seatOf(e)?.y;
+  if (!y) return null;
+  if (y === "middle" || (y === "span" && isText(e))) return half(top + (H - h) / 2);
+  if (y === "span") return half(top);
+  if (y === "bottom") return half(top + H - (insets?.bottom ?? 0) - h);
+  return half(top + (insets?.top ?? 0));
+}
+
+/** The left an x-seat gives a child `w` wide in a carrier band [left, left+W). */
+export function seatLeft(e, left, W, w, insets = e.seatInset ?? null) {
+  const x = seatOf(e)?.x;
+  if (!x) return null;
+  if (x === "center") return half(left + (W - w) / 2);
+  if (x === "right") return half(left + W - (insets?.right ?? 0) - w);
+  if (x === "span") return half(left + (isText(e) ? INSET : 0));
+  return half(left + (insets?.left ?? 0));
+}
+
+/**
+ * The rect a seat gives `e` (of `size`) in its frame; spans resize, every
+ * other seat only moves. With `ctx` ({ spec, at }) a centred child sits by
+ * its block (blockStart); without, alone in the frame.
+ */
+export function seatRect(e, frame, size = { w: e.w, h: e.h }, ctx = null) {
+  const s = seatOf(e);
+  if (!s) return null;
+  const insets = e.seatInset ?? insetsOf(e, frame);
+  const w = s.x === "span" ? frame.w - (isText(e) ? 2 * INSET : 0) : size.w;
+  const h = s.y === "span" && !isText(e) ? frame.h : size.h;
+  const at = ctx?.at ?? ((o) => o);
+  const atSized = (o) => (o === e ? { ...at(o), w, h } : at(o));
+  const bx = ctx && s.x === "center" ? blockStart(ctx.spec, e, "x", frame.x, frame.w, atSized) : null;
+  const by = ctx && (s.y === "middle" || (s.y === "span" && isText(e))) ? blockStart(ctx.spec, e, "y", frame.y, frame.h, atSized) : null;
+  return {
+    x: bx ?? seatLeft(e, frame.x, frame.w, w, insets) ?? e.x,
+    y: by ?? seatTop(e, frame.y, frame.h, h, insets) ?? e.y,
+    w: half(w),
+    h: s.y === "span" && !isText(e) ? half(h) : e.h,
+  };
+}
+
+// Scale a drawn element's own geometry along one axis (a span): its points,
+// outline, spline knots, path commands, an arc's centre and radius.
+function scaleAxis(e, axis, from, to) {
+  if (!(from.size > 0) || !(to.size > 0)) return;
+  const k = to.size / from.size;
+  const map = (v) => to.at + (v - from.at) * k;
+  for (const p of [...(e.points ?? []), ...(e.outline ?? [])]) p[axis] = map(p[axis]);
+  const g = e.geometry;
+  if (g?.type === "spline") for (const p of g.points ?? []) p[axis] = map(p[axis]);
+  else if (g?.type === "path") for (const c of g.commands ?? []) for (const kx of axis === "x" ? ["x", "x1", "x2"] : ["y", "y1", "y2"]) if (Number.isFinite(c[kx])) c[kx] = map(c[kx]);
+  else if (g) { g[`c${axis}`] = map(g[`c${axis}`]); g[`r${axis}`] *= k; }
+  if (e.textFrame) { e.textFrame[axis] = map(e.textFrame[axis]); e.textFrame[axis === "x" ? "w" : "h"] *= k; }
+}
+
+// A sketched figure spans only when no circle shapes it: an arc on a circle
+// cannot stretch along one axis. Such a figure moves to the edge instead. A
+// copy takes its source's shape, so it only moves (its source spans).
+const figureOf = (sketch, id) => (sketch?.figures ?? []).find((x) => x.id === id);
+const figureScalable = (f) => f && !f.copyOf && !(f.mirror && f.mirror.axis === "line")
+  && ![...(f.outline ?? []), ...(f.holes ?? []).flat()].some((p) => p?.next === "arc");
+function scaleFigure(f, axis, from, to) {
+  const k = to.size / from.size;
+  const map = (v) => to.at + (v - from.at) * k;
+  for (const p of [...(f.outline ?? []), ...(f.holes ?? []).flat()]) p[axis] = map(p[axis]);
+  const m = f.mirror;
+  if (m && ((m.axis === "horizontal" && axis === "y") || (m.axis === "vertical" && axis === "x"))) m.at = map(m.at);
+}
+
+/**
+ * Seat every child the reader seated: parents before children, so a seat in
+ * a seated carrier lands in the carrier's new place. `sizeOf(e)` gives a
+ * text's MEASURED size where a render exists (the painting's height is a
+ * plan); `only` restricts the pass to those ids. The first pass records the
+ * drawn insets (`seatInset`) for the edge anchors. Returns one line per move.
+ */
+export function applySeats(spec, { sizeOf = null, only = null, beforeFold = false } = {}) {
+  const els = spec.elements ?? [];
+  const byId = new Map(els.map((e) => [e.id, e]));
+  // Before the folds (`beforeFold`), the lines of one text block (`block`,
+  // foldTextBlocks) wait: they are seated as the ONE element they fold into,
+  // and seating each line alone would stack a title and its body on the same
+  // centre. A block the fold refused (lines side by side) is seated line by
+  // line afterwards like any other child.
+  const blockSize = new Map();
+  for (const e of els) if (e.block) blockSize.set(e.block, (blockSize.get(e.block) ?? 0) + 1);
+  const inBlock = (e) => beforeFold && e.block && blockSize.get(e.block) > 1 && !e.paragraphs;
+  const figures = new Set((spec.sketch?.figures ?? []).map((f) => f.id));
+  const deltas = new Map();
+  const movedCircles = new Set();
+  const changes = [];
+  const kids = (id) => els.filter((o) => o.parent === id);
+  const move = (e, dx, dy) => {
+    if (!dx && !dy) return;
+    translateElement(e, dx, dy);
+    if (figures.has(e.id)) translateFigure(spec.sketch, e.id, dx, dy, deltas, movedCircles);
+    for (const k of kids(e.id)) move(k, dx, dy);
+  };
+  // The painting's structure first, before anything moves in this pass.
+  for (const e of els) {
+    const p = e.parent ? byId.get(e.parent) : null;
+    if (p && seatOf(e) && !inBlock(e) && !e.seatBand && p.w > 0 && p.h > 0) e.seatBand = recordBand(spec, e, p);
+  }
+  for (const e of paintOrdered(els)) {
+    const p = e.parent ? byId.get(e.parent) : null;
+    const s = seatOf(e);
+    if (!p || !s || inBlock(e) || (only && !only.has(e.id)) || !(p.w > 0 && p.h > 0) || !(e.w >= 0 && e.h >= 0)) continue;
+    const frame = seatFrame(spec, e, p);
+    e.seatInset ??= insetsOf(e, frame);
+    const to = seatRect(e, frame, sizeOf?.(e) ?? { w: e.w, h: e.h }, { spec });
+    const spanW = s.x === "span" && to.w !== e.w;
+    const spanH = s.y === "span" && !isText(e) && to.h !== e.h;
+    const scaled = { dx: 0, dy: 0 };
+    if (spanW || spanH) {
+      const f = figures.has(e.id) ? figureOf(spec.sketch, e.id) : null;
+      const stretch = !f || figureScalable(f);
+      for (const [axis, on, size] of [["x", spanW, "w"], ["y", spanH, "h"]]) {
+        if (!on) continue;
+        const from = { at: e[axis], size: e[size] };
+        const dest = { at: to[axis], size: stretch || f?.copyOf ? to[size] : e[size] };
+        if (stretch) {
+          if (f) scaleFigure(f, axis, from, dest);
+          else scaleAxis(e, axis, from, dest);
+          scaled[`d${axis}`] = dest.at - from.at;
+          e[axis] = dest.at;
+        } else if (f && !f.copyOf) changes.push(`${e.id}: a figure on a circle cannot stretch to span ${p.id}; moved to its edge`);
+        e[size] = dest.size;
+      }
+    }
+    const dx = half(to.x - e.x);
+    const dy = half(to.y - e.y);
+    if (!dx && !dy && !spanW && !spanH) continue;
+    move(e, dx, dy);
+    // A scaled source moved its own origin too: its copies offset from that.
+    if (figures.has(e.id) && (scaled.dx || scaled.dy)) {
+      const d = deltas.get(e.id) ?? { dx: 0, dy: 0 };
+      deltas.set(e.id, { dx: d.dx + scaled.dx, dy: d.dy + scaled.dy });
+    }
+    changes.push(`${e.id}: seated ${[s.x, s.y].filter(Boolean).join("/")} in ${p.id}${dx || dy ? ` (${dx >= 0 ? "+" : ""}${dx}, ${dy >= 0 ? "+" : ""}${dy})` : ""}`);
+  }
+  fixCopies(spec.sketch, deltas);
+  return changes;
+}
+
+const roundish = (e) => e.kind === "disc" || ["circle", "ring", "ellipse"].includes(e.shape) || (e.geometry && ["arc", "sector"].includes(e.geometry.type));
+
+/**
+ * A ring, arc or loop stroke that circles a hub (`around`) takes the hub's
+ * centre; the hub stays, it anchors the ring to the rest of the slide. Strokes
+ * sharing that arc's `loop` follow it. Returns one line per ring recentred.
+ */
+export function applyAround(spec) {
+  const els = spec.elements ?? [];
+  const byId = new Map(els.map((e) => [e.id, e]));
+  const changes = [];
+  const centre = (e) => (e.geometry && ["arc", "sector"].includes(e.geometry.type) ? { x: e.geometry.cx, y: e.geometry.cy } : { x: e.x + e.w / 2, y: e.y + e.h / 2 });
+  const loopHub = new Map();
+  // A ring circles its hub, so it encloses the hub's centre: a stroked ring or
+  // circle whose box does not hold it is a satellite the reader misnamed
+  // (x101 cloud 4 named four quadrant sectors "around" their hub: sectors and
+  // arcs carry their own centre and are judged by it). It stays as drawn.
+  const encloses = (e, hub) => (e.geometry && ["arc", "sector"].includes(e.geometry.type))
+    || (hub.x + hub.w / 2 > e.x && hub.x + hub.w / 2 < e.x + e.w && hub.y + hub.h / 2 > e.y && hub.y + hub.h / 2 < e.y + e.h);
+  for (const e of els) {
+    const hub = e.around ? byId.get(e.around) : null;
+    if (!hub || hub === e || !roundish(e) || !(hub.w > 0 && hub.h > 0)) continue;
+    if (!encloses(e, hub)) { changes.push(`${e.id}: named around ${hub.id} but does not enclose it; kept as drawn`); continue; }
+    const c = centre(e);
+    const dx = hub.x + hub.w / 2 - c.x;
+    const dy = hub.y + hub.h / 2 - c.y;
+    if (Number.isInteger(e.loop)) loopHub.set(e.loop, hub);
+    if (!dx && !dy) continue;
+    translateElement(e, dx, dy);
+    changes.push(`${e.id}: centred on ${hub.id}, the hub it circles (${dx >= 0 ? "+" : ""}${Math.round(dx * 10) / 10}, ${dy >= 0 ? "+" : ""}${Math.round(dy * 10) / 10})`);
+  }
+  for (const e of els) {
+    const hub = Number.isInteger(e.loop) ? loopHub.get(e.loop) : null;
+    if (!hub || e.around || !roundish(e)) continue;
+    const c = centre(e);
+    const dx = hub.x + hub.w / 2 - c.x;
+    const dy = hub.y + hub.h / 2 - c.y;
+    if (!dx && !dy) continue;
+    translateElement(e, dx, dy);
+    changes.push(`${e.id}: centred on ${hub.id} with its loop`);
+  }
+  return changes;
+}