slidemind 0.3.20 → 0.4.0

package/src/builders/card-height.mjs

@@ -0,0 +1,294 @@
+// The height lever of text-card-fit.mjs (3): one new height for a card — for
+// every member of its declared set alike, placed by the set's arrangement —
+// with everything on it re-anchored, what sits right under it moved down into
+// its free room, and nothing landed on what lies over it or crossed into a
+// line it did not cross before. `cx` is text-card-fit's view of the slide:
+// { s, byId, slot, changes, at, ink, heightOf, isText, filled, kids, subtree,
+// inTree, move, block, pastOf, alone }.
+import { gluedIds, linePoints, lineTrace, linesWithin, moveLine } from "./repeat-groups.mjs";
+import { segmentHitsRect } from "./line-fit.mjs";
+import { paintOrdered } from "./concept-layout.mjs";
+import { seatFrame, seatOf, seatRect } from "./seat.mjs";
+
+const INSET = 8; // px kept between a text and its card's edge
+const GAP = 4; // px kept from a neighbour
+const ESCAPE_PX = 3; // a descender past the edge is no escape (overlap-check.ts)
+
+const span = (a0, a1, b0, b1) => a0 < b1 && b0 < a1;
+const hit = (a, b, gap = 0) => span(a.x, a.x + a.w, b.x, b.x + b.w) && span(a.y - gap, a.y + a.h + gap, b.y, b.y + b.h);
+const median = (v) => {
+  const s = [...v].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+
+export function cardHeight({ s, byId, slot, changes, at, ink, heightOf, isText, filled, kids, subtree, inTree, move, block, pastOf, alone }) {
+  const boundsOf = (card) => {
+    const h = card.parent ? byId.get(card.parent) : null;
+    return h && filled(h) ? [h.y + INSET, h.y + h.h - INSET] : [0, slot.h];
+  };
+  // What is drawn on a card: children (with their content) and its own lines.
+  // A child hung across an edge (a badge on the corner) follows that edge;
+  // everything inside moves as ONE block, so a row's disc and its text, or a
+  // title and its divider, never come apart. A child a stack push (`pushed`)
+  // just moved past the edge is content, not a badge.
+  const contentOf = (card, pushed) => {
+    const items = kids(card).map((k) => {
+      const y = isText(k) ? at(k).y : k.y;
+      const glyphs = isText(k) ? ink(k) : { top: y, bottom: y + heightOf(k) };
+      return { k, top: y, bottom: y + heightOf(k), inkTop: glyphs.top, inkBottom: glyphs.bottom, imgTop: k.y, imgBottom: k.y + k.h };
+    });
+    const lines = linesWithin(s, card).map((c) => {
+      const ys = linePoints(c).map((p) => p.y);
+      const [top, bottom] = [Math.min(...ys), Math.max(...ys)];
+      return { c, top, bottom, inkTop: top, inkBottom: bottom, imgTop: top, imgBottom: bottom };
+    });
+    const back = (it) => pushed?.get(it.k) ?? 0;
+    const onEdge = (it) => !isText(it.k) && (it.top - back(it) < card.y - 1 || it.bottom - back(it) > card.y + card.h + 1);
+    const inner = [...items.filter((it) => !onEdge(it)), ...lines];
+    if (!inner.length) return null;
+    const top = Math.min(...inner.map((it) => it.top));
+    const bottom = Math.max(...inner.map((it) => it.bottom));
+    // Where the image set it: centred, or nearer the top or the bottom.
+    const gt = Math.min(...inner.map((it) => it.imgTop)) - card.y;
+    const gb = card.y + card.h - Math.max(...inner.map((it) => it.imgBottom));
+    const anchor = Math.abs(gt - gb) <= card.h * 0.15 ? "center" : gt < gb ? "top" : "bottom";
+    // Glyphs measured as glyphs (text-stack.mjs): the least move keeps the insets from the ink.
+    const inkTop = Math.min(...inner.map((it) => it.inkTop));
+    const inkBottom = Math.max(...inner.map((it) => it.inkBottom));
+    return { inner, edges: items.filter(onEdge), top, bottom, inkTop, inkBottom, gapTop: top - card.y, gapBottom: card.y + card.h - bottom, anchor };
+  };
+  // The card at `top`, H tall, with everything on it re-anchored: dy per element.
+  // `least`: the content moves only as far as the insets from its ink make it.
+  const layout = (card, top, H, mode, pushed) => {
+    const c = contentOf(card, pushed);
+    const moves = new Map([[card, top - card.y]]);
+    const cH = c.bottom - c.top;
+    const keep = (v) => Math.min(Math.max(v, INSET), H - cH - INSET);
+    const at0 = mode === "least" ? c.top + Math.min(Math.max(0, top + INSET - c.inkTop), top + H - INSET - c.inkBottom)
+      : c.anchor === "top" ? top + keep(c.gapTop) : c.anchor === "bottom" ? top + H - cH - keep(c.gapBottom) : top + (H - cH) / 2;
+    const dy = at0 - c.top;
+    const lines = [];
+    for (const it of c.inner) {
+      if (it.c) lines.push([it.c, dy]);
+      else {
+        // A child the reader seated in the card itself keeps its seat in the
+        // new height (seat.mjs): a middle-seated text re-centres, a top-seated
+        // one keeps its inset. One seated in its row moves with the block;
+        // the fit's seat lever re-seats it in the row on the next pass.
+        const atRect = (o) => (isText(o) ? { x: o.x, w: o.w, ...at(o) } : o);
+        const whole = () => { const f = seatFrame(s, it.k, card, atRect); return f.y === card.y && f.h === card.h; };
+        const seated = seatOf(it.k)?.y && it.k.seatBand && it.k.seatInset && mode !== "least" && whole()
+          ? seatRect(it.k, { x: card.x, y: top, w: card.w, h: H }, { w: it.k.w, h: it.bottom - it.top }, { spec: s, at: atRect })?.y
+          : null;
+        const d = seated == null ? dy : seated - it.top;
+        for (const o of subtree(it.k)) moves.set(o, d);
+      }
+    }
+    for (const it of c.edges) {
+      const d = it.top < card.y - 1 ? top - card.y : top + H - card.y - card.h;
+      for (const o of subtree(it.k)) moves.set(o, d);
+    }
+    lineMoves.set(card, lines);
+    return moves;
+  };
+  const lineMoves = new Map();
+  let paint = null; // paint order (transcribe.mjs): what is drawn over a card
+  // How far a card may grow down: to what lies under it in its columns (GAP
+  // kept; what it already overlaps does not count), its panel's or the slot's floor.
+  const floorOf = (card) => {
+    let floor = boundsOf(card)[1];
+    for (const o of s.elements) {
+      if (inTree(o, card) || inTree(card, o) || !(o.w > 0 && o.h > 0) || hit(o, card) || !span(o.x, o.x + o.w, card.x, card.x + card.w)) continue;
+      const y = isText(o) ? at(o).y : o.y;
+      if (y >= card.y + card.h - 1) floor = Math.min(floor, y - GAP);
+    }
+    return floor;
+  };
+  const need = (card, pushed) => {
+    const c = contentOf(card, pushed);
+    return c.bottom - c.top + 2 * INSET;
+  };
+  // Tops for the members under one arrangement, or null.
+  const topsFor = (u, H, anchor) => {
+    const m = u.members;
+    if (u.arrangement === "ring") return m.map((c) => c.y + c.h / 2 - H / 2);
+    if (u.arrangement === "column" || u.arrangement === "grid") {
+      // Rows (a column is one member per row) keep their gaps and their centre.
+      const order = [...m].sort((a, b) => a.y - b.y);
+      const rows = [];
+      for (const c of order) {
+        const last = rows.at(-1);
+        if (last && c.y + c.h / 2 - (last[0].y + last[0].h / 2) <= last[0].h / 2) last.push(c);
+        else rows.push([c]);
+      }
+      if (rows.length === 1) return m.map((c) => c.y);
+      const gaps = rows.slice(1).map((r, k) => r[0].y - (rows[k][0].y + rows[k][0].h));
+      const gap = Math.max(GAP, median(gaps));
+      const mid = (rows[0][0].y + rows.at(-1)[0].y + rows.at(-1)[0].h) / 2;
+      const top0 = mid - (rows.length * H + (rows.length - 1) * gap) / 2;
+      const topOf = new Map(rows.flatMap((r, k) => r.map((c) => [c, top0 + k * (H + gap)])));
+      return m.map((c) => topOf.get(c));
+    }
+    return m.map((c) => (anchor === "top" || anchor === "least" ? c.y : anchor === "bottom" ? c.y + c.h - H : c.y + c.h / 2 - H / 2));
+  };
+  // `hubFixed`: a ring keeps its hub (it anchors the ring to the rest of the
+  // slide) and closes in, both sides of the hub by the same amount; otherwise
+  // an out-of-bounds set moves as one — a ring with its hub. `pushed`: the px
+  // a stack was just moved down by (1a), so a landing counts from before it.
+  const tryPlace = (u, H, anchor, hubFixed, pushed) => {
+    const tops = topsFor(u, H, anchor);
+    const plans = u.members.map((c, i) => ({ card: c, moves: layout(c, tops[i], H, anchor, pushed), rect: { x: c.x, y: tops[i], w: c.w, h: H } }));
+    const ring = u.arrangement === "ring" && u.hub;
+    const hubTree = ring && !hubFixed ? subtree(u.hub) : [];
+    const [ceil, floor] = boundsOf(u.members[0]);
+    const range = () => {
+      let lo = Infinity;
+      let hi = -Infinity;
+      for (const p of plans) for (const [o, dy] of p.moves) {
+        const y = (isText(o) ? at(o).y : o.y) + dy;
+        lo = Math.min(lo, y);
+        hi = Math.max(hi, y + (o === p.card ? H : heightOf(o)));
+      }
+      for (const o of hubTree) { lo = Math.min(lo, o.y); hi = Math.max(hi, o.y + heightOf(o)); }
+      return [lo, hi];
+    };
+    const closeIn = (inward) => {
+      const cy = u.hub.y + u.hub.h / 2;
+      for (const p of plans) {
+        const mc = p.rect.y + H / 2;
+        const dy = mc < cy - 1 ? inward : mc > cy + 1 ? -inward : 0;
+        for (const [o, v] of p.moves) p.moves.set(o, v + dy);
+        lineMoves.set(p.card, (lineMoves.get(p.card) ?? []).map(([c, v]) => [c, v + dy]));
+        p.rect.y += dy;
+      }
+    };
+    let [lo, hi] = range();
+    if (ring && hubFixed) {
+      const inward = Math.max(0, ceil - lo, hi - floor);
+      if (inward > 0) closeIn(inward);
+      [lo, hi] = range();
+      if (lo < ceil - 0.5 || hi > floor + 0.5) return null;
+    } else if (ring && hi - lo > floor - ceil) {
+      closeIn((hi - lo - (floor - ceil)) / 2);
+      [lo, hi] = range();
+    }
+    if (hi - lo > floor - ceil + 0.5) return null;
+    const all = lo < ceil ? ceil - lo : hi > floor ? floor - hi : 0;
+    const moved = new Set([...plans.flatMap((p) => [...p.moves.keys()]), ...hubTree]);
+    const rects = [...plans.map((p) => ({ ...p.rect, y: p.rect.y + all })), ...(all ? hubTree.map((o) => ({ x: o.x, y: o.y + all, w: o.w, h: o.h })) : [])];
+    const old = [...u.members, ...hubTree];
+    const hubAt = ring ? { x: u.hub.x, y: u.hub.y + (hubFixed ? 0 : all), w: u.hub.w, h: u.hub.h } : null;
+    const apart = rects.every((r, i) => rects.every((q, j) => j === i || j >= plans.length || i >= plans.length || !hit(q, r)))
+      && (!hubAt || plans.every((p) => !hit({ ...p.rect, y: p.rect.y + all }, hubAt, GAP)));
+    const exempt = (o) => moved.has(o) || o === u.hub || !(o.w > 0 && o.h > 0) || old.some((c) => hit(o, c));
+    const blocking = s.elements.filter((o) => !exempt(o) && rects.some((r) => hit(o, r, GAP)));
+    const room = blocking.length ? makeRoom(blocking, rects, old, moved, floor) : { push: () => {} };
+    // What lies over a card without being its content (a step badge on its
+    // edge) stays where it is: the content re-set inside the card never lands
+    // on it (pm-03: the launch panel's title lifted onto badge "2").
+    const over = s.elements.filter((o) => !moved.has(o) && o.w > 0 && o.h > 0 && old.some((c) => hit(o, c) && !inTree(c, o)));
+    const rectOf = (o) => ({ x: o.x, y: isText(o) ? at(o).y : o.y, w: o.w, h: heightOf(o) });
+    // Lines cross glyphs, not a text box's empty margin.
+    const drawn = (o) => (isText(o) ? { x: o.x, y: ink(o).top, w: o.w, h: ink(o).bottom - ink(o).top } : rectOf(o));
+    const landsOn = plans.some((p) => [...p.moves].some(([o, dy]) => {
+      if (o === p.card) return false;
+      const back = pushed?.get(o) ?? 0;
+      const [r, g] = [rectOf(o), drawn(o)];
+      return over.some((f) => !hit(f, { ...r, y: r.y - back }) && hit(f, { ...r, y: r.y + dy + all }))
+        || crossesLine({ ...g, y: g.y + dy + all }, [{ ...g, y: g.y - back }], [p.card]);
+    }));
+    // Nor does the card grow under more of what is drawn over it (a caption
+    // across its edge); a backdrop it lies on is drawn under it.
+    paint ??= new Map(paintOrdered(s.elements).map((e, i) => [e, i]));
+    const covered = (f, r) => (span(f.x, f.x + f.w, r.x, r.x + r.w) ? Math.max(0, Math.min(f.y + f.h, r.y + r.h) - Math.max(f.y, r.y)) : 0);
+    const growsOver = plans.some((p) => over.some((f) => f !== u.hub && paint.get(f) > paint.get(p.card)
+      && covered(rectOf(f), { ...p.rect, y: p.rect.y + all }) > covered(rectOf(f), p.card) + 0.5));
+    if (!apart || !room || landsOn || growsOver || plans.some((p) => crossesLine({ ...p.rect, y: p.rect.y + all }, old, u.members))) return null;
+    return () => {
+      room.push();
+      for (const p of plans) {
+        const from = p.card.h;
+        for (const [o, dy] of p.moves) if (dy + all) move(o, Math.round((dy + all) * 10) / 10);
+        for (const [c, dy] of lineMoves.get(p.card) ?? []) if (dy + all) moveLine(c, 0, Math.round((dy + all) * 10) / 10);
+        p.card.h = H;
+        changes.push(from === H ? `${p.card.id}: content re-set inside its ${H}px` : `${p.card.id}: height ${Math.round(from)}→${H}px${u.id ? ` (${u.id}: one height for ${u.members.map((c) => c.id).join(", ")})` : ""}`);
+      }
+      if (all) for (const o of hubTree) move(o, all);
+    };
+  };
+  // A slide line (a loop around panels, a connector) a new rect would cross
+  // and the old one did not: growing or pushing a box into it trades a text
+  // spill for a line through a card (pm-03 after-panel into its loop). A
+  // card's own lines move with it and never count.
+  const crossesLine = (rect, was, owners, moving = []) => {
+    const own = new Set([...owners.flatMap((m) => linesWithin(s, m)), ...moving]);
+    // A connector glued to the card or its content follows it (the arrow
+    // leaving the edge that grows): it starts ON the old edge, so the strict
+    // hit test never counted it as crossed before.
+    const tree = new Set(owners.flatMap((m) => subtree(m).map((o) => o.id)));
+    return (s.connectors ?? []).some((c) => {
+      const t = own.has(c) || gluedIds(c).some((id) => tree.has(id)) ? null : lineTrace(c);
+      const hits = (box) => t.some((p, i) => i > 0 && segmentHitsRect(t[i - 1], p, box));
+      return Boolean(t) && hits(rect) && !was.some((o) => hits(o));
+    });
+  };
+  // What sits right under a growing card moves down with it, all of it by one
+  // step, into the free room it has below — never out of the slot or its
+  // panel, never onto anything else (qbr-04: the banner under the panel had
+  // 10px to spare, the panel needed 4 of them).
+  const makeRoom = (blocking, rects, old, moved, floor) => {
+    const oldBottom = Math.max(...old.map((c) => c.y + c.h));
+    const rootOf = (o) => {
+      let r = o;
+      for (let p = r.parent ? byId.get(r.parent) : null; p && !old.some((c) => inTree(c, p)); p = p.parent ? byId.get(p.parent) : null) r = p;
+      return r;
+    };
+    const roots = [...new Set(blocking.map(rootOf))];
+    if (roots.some((r) => r.y < oldBottom - 1 || moved.has(r))) return null;
+    const extent = (r) => ({ x: r.x, y: r.y, w: r.w, h: Math.max(...subtree(r).map((o) => (isText(o) ? at(o).y : o.y) + heightOf(o))) - r.y });
+    const d = Math.ceil(Math.max(...roots.flatMap((r) => rects.filter((q) => span(q.x, q.x + q.w, r.x, r.x + r.w)).map((q) => q.y + q.h + GAP - r.y))));
+    if (!(d > 0) || roots.some((r) => { const e = extent(r); return e.y + e.h + d > floor + 0.5; })) return null;
+    const pushed = new Set(roots.flatMap(subtree));
+    const free = s.elements.every((o) => pushed.has(o) || moved.has(o) || old.includes(o) || !(o.w > 0 && o.h > 0)
+      || roots.every((r) => { const e = extent(r); return hit(o, e) || !hit(o, { ...e, y: e.y + d }, GAP); }));
+    if (!free || roots.some((r) => crossesLine({ ...extent(r), y: extent(r).y + d }, [extent(r)], [r]))) return null;
+    const lines = roots.flatMap((r) => linesWithin(s, r));
+    return {
+      push: () => {
+        for (const o of pushed) move(o, d);
+        for (const c of lines) moveLine(c, 0, d);
+        changes.push(`${roots.map((r) => r.id).join(", ")}: +${d}px down to make room`);
+      },
+    };
+  };
+  // `pushed` (element → px): a stack moved down on the card (1a) asks for the
+  // height its content now needs inside the insets, before any text is past
+  // the edge.
+  const heightUnit = (u, pushed = null) => {
+    const over = pushed ? (c) => contentOf(c, pushed).bottom > c.y + c.h - INSET + 0.5 : (c) => pastOf(c) > ESCAPE_PX;
+    if (alone(u) || u.members.some((c) => !block(c)) || !u.members.some(over)) return false;
+    const H = Math.ceil(Math.max(...u.members.map((c) => c.h), ...u.members.map((c) => need(c, pushed))));
+    const anchors = u.arrangement === "row" ? ["top", "bottom", "center"] : u.arrangement ? ["center"] : ["top", "bottom", "center"];
+    const tries = u.arrangement === "ring" ? [["center", true], ["center", false]] : anchors.map((a) => [a, false]);
+    // A lone card whose content, re-anchored, would land on what lies over it
+    // (pm-03: the after panel's bullets onto the step badge on its edge): the
+    // content moves only as far as the insets make it — in the card's height,
+    // else in the height its free room below gives it, up to the one that
+    // holds its content where it is. A set keeps one inner layout.
+    if (u.members.length === 1) {
+      const c = u.members[0];
+      const grow = Math.min(Math.ceil(contentOf(c, pushed).inkBottom + INSET - c.y), Math.floor(floorOf(c) - c.y));
+      tries.push(["least", false, H], ...(grow > H ? [["least", false, grow]] : []));
+    }
+    for (const [anchor, hubFixed, h = H] of tries) {
+      const commit = tryPlace(u, h, anchor, hubFixed, pushed);
+      if (commit) {
+        commit();
+        return true;
+      }
+    }
+    return false;
+  };
+  return { heightUnit, crossesLine };
+}

package/src/builders/chart-hole.mjs

@@ -0,0 +1,183 @@
+// What a doughnut paints inside its hole — the figure the slide is about, the
+// caption under it, an icon — stands ON the chart, centred in its ring. It is
+// none of the chart's labelling (chart-labels.mjs): a doughnut's native data
+// labels sit on its ring, and OOXML has no element for the hole. x114 GTM 1
+// and cloud 4/5 lost six such figures: the reader listed each among the
+// chart's own (`owns`), the fold took it as a value label, and the chart
+// printed every slice's value on the ring instead ("9%" and "91%", the hole
+// empty). x114 QBR 3's globe sat on the ring's edge once the native legend
+// pushed the ring away from where the image painted it.
+//
+// The reader names what stands in the hole (`chart.hole`). Here that becomes
+// the chart's own content, on declaration only: each member is a child of the
+// chart, no label fold takes it, it leaves any text block that reaches outside
+// the hole, and the members are centred as ONE unit on the ring the image
+// painted — among themselves they keep their painted arrangement. The chart
+// draws its ring there (chart-jsx.mjs pins the plot area when the frame grew
+// to hold folded labelling).
+import { translateElement } from "./concept-geometry.mjs";
+import { fixCopies, translateFigure } from "./repeat-groups.mjs";
+import { readingRows } from "./text-blocks.mjs";
+
+const half = (v) => Math.round(v * 2) / 2;
+// The hole PowerPoint draws when a doughnut names none, and the widest OOXML
+// allows (`c:holeSize`, percent of the ring's diameter).
+const HOLE_DEFAULT = 50;
+const HOLE_MAX = 90;
+
+/** The ids the reader named in a doughnut's hole; none for any other chart. */
+export function holeIds(e) {
+  const c = e?.kind === "chart" ? e.chart : null;
+  if (c?.type !== "doughnut" || !Array.isArray(c.hole)) return [];
+  return [...new Set(c.hole.filter((id) => typeof id === "string" && id && id !== e.id))];
+}
+
+/** Where the image painted the ring: the chart's rect before its frame grew to hold folded labelling. */
+export function ringRect(e) {
+  const from = e.chart?.folded?.frame?.from;
+  return from && [from.x, from.y, from.w, from.h].every(Number.isFinite) ? { x: from.x, y: from.y, w: from.w, h: from.h } : { x: e.x, y: e.y, w: e.w, h: e.h };
+}
+
+/** Each declared hole member's chart, by member id (the first chart that names it). */
+export function holeMembers(elements) {
+  const ids = new Set((elements ?? []).map((e) => e.id));
+  const out = new Map();
+  for (const c of elements ?? []) for (const id of holeIds(c)) if (ids.has(id) && !out.has(id)) out.set(id, c);
+  return out;
+}
+
+/**
+ * Make every declared hole member its chart's own content: the chart is its
+ * parent, it leaves the chart's `owns` (no label fold takes it) and its own
+ * seat (the hole centres it), and a text block that mixes it with texts outside
+ * that hole lets it go — the members of one hole that shared the block keep
+ * one block of their own. Mutates `spec`; idempotent; returns notes.
+ */
+export function claimHoles(spec) {
+  const els = spec.elements ?? [];
+  const holeOf = holeMembers(els);
+  if (!holeOf.size) return [];
+  const byId = new Map(els.map((e) => [e.id, e]));
+  const notes = [];
+  for (const [id, c] of holeOf) {
+    const e = byId.get(id);
+    // A member inside another member (an icon on its disc) rides with it.
+    if (!holeOf.has(e.parent)) e.parent = c.id;
+    if (e.seat) e.seat = null;
+    if (Array.isArray(c.chart.owns) && c.chart.owns.includes(id)) {
+      c.chart.owns = c.chart.owns.filter((x) => x !== id);
+      notes.push(`chart ${c.id}: ${id} stands in the doughnut's hole — drawn on the chart, centred in its ring, not folded into its labels`);
+    }
+  }
+  const blocks = new Map();
+  for (const e of els) if (e.block) blocks.set(e.block, [...(blocks.get(e.block) ?? []), e]);
+  for (const [block, members] of blocks) {
+    const owners = new Set(members.map((m) => holeOf.get(m.id)?.id ?? ""));
+    if (owners.size < 2) continue;
+    for (const owner of owners) {
+      if (!owner) continue;
+      const inHole = members.filter((m) => holeOf.get(m.id)?.id === owner);
+      for (const m of inHole) {
+        if (inHole.length > 1) m.block = `${block}@${owner}`;
+        else delete m.block;
+      }
+      notes.push(`block ${block}: ${inHole.map((m) => m.id).join(", ")} stand${inHole.length === 1 ? "s" : ""} in ${owner}'s hole — written there, apart from the block's texts outside it`);
+    }
+    // What the block read before the hole and what it read after it are two
+    // texts, on either side of the ring (x114 GTM 1: "Below 300 employees" over
+    // the ring, "convert" under it — one text would pull "convert" up under the
+    // header and onto the ring).
+    const runs = [[]];
+    for (const m of readingRows(members).flat()) {
+      if (holeOf.has(m.id)) { if (runs.at(-1).length) runs.push([]); }
+      else runs.at(-1).push(m);
+    }
+    const parts = runs.filter((r) => r.length);
+    if (parts.length < 2) continue;
+    parts.forEach((run, i) => {
+      for (const m of run) {
+        if (run.length > 1) m.block = i ? `${block}~${i + 1}` : block;
+        else delete m.block;
+      }
+    });
+    notes.push(`block ${block}: the hole parts it — ${parts.map((r) => r.map((m) => m.id).join(" + ")).join(" | ")} written as ${parts.length} texts`);
+  }
+  return notes;
+}
+
+// Members of one hole that shared a block are written as ONE text
+// (text-blocks.mjs, which keeps each member's id on its paragraph): the hole
+// names that text from then on.
+function followFolds(els) {
+  const ids = new Set(els.map((e) => e.id));
+  const textOf = new Map();
+  for (const e of els) for (const p of e.paragraphs ?? []) if (p?.id && !textOf.has(p.id)) textOf.set(p.id, e.id);
+  for (const c of els) {
+    if (!holeIds(c).length) continue;
+    const hole = [...new Set(c.chart.hole.map((id) => (ids.has(id) ? id : textOf.get(id) ?? id)))];
+    if (hole.join("\n") !== c.chart.hole.join("\n")) c.chart.hole = hole;
+  }
+}
+
+/**
+ * Centre each doughnut's hole members, as one unit, on the ring the image
+ * painted (`ringRect`); a member's own children move with it. Returns one line
+ * per hole moved.
+ */
+export function centreHoles(spec) {
+  const els = spec.elements ?? [];
+  followFolds(els);
+  const holeOf = holeMembers(els);
+  if (!holeOf.size) return [];
+  const byChart = new Map();
+  for (const [id, c] of holeOf) byChart.set(c, [...(byChart.get(c) ?? []), id]);
+  const byId = new Map(els.map((e) => [e.id, e]));
+  const figures = new Set((spec.sketch?.figures ?? []).map((f) => f.id));
+  const deltas = new Map();
+  const movedCircles = new Set();
+  const kids = (id) => els.filter((o) => o.parent === id);
+  const move = (e, dx, dy) => {
+    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);
+  };
+  const changes = [];
+  for (const [c, ids] of byChart) {
+    // The unit: the members the chart carries directly (a member on another
+    // member moves with its carrier).
+    const unit = ids.map((id) => byId.get(id)).filter((e) => e.parent === c.id && [e.x, e.y, e.w, e.h].every(Number.isFinite));
+    if (!unit.length) continue;
+    const ring = ringRect(c);
+    const x0 = Math.min(...unit.map((e) => e.x));
+    const y0 = Math.min(...unit.map((e) => e.y));
+    const x1 = Math.max(...unit.map((e) => e.x + e.w));
+    const y1 = Math.max(...unit.map((e) => e.y + e.h));
+    const dx = half(ring.x + ring.w / 2 - (x0 + x1) / 2);
+    const dy = half(ring.y + ring.h / 2 - (y0 + y1) / 2);
+    if (!dx && !dy) continue;
+    for (const e of unit) move(e, dx, dy);
+    changes.push(`${c.id}: its hole (${unit.map((e) => e.id).join(", ")}) centred in the ring (${dx >= 0 ? "+" : ""}${dx}, ${dy >= 0 ? "+" : ""}${dy})`);
+  }
+  fixCopies(spec.sketch, deltas);
+  return changes;
+}
+
+/**
+ * The hole that holds what stands in it: the circle around the members' box,
+ * as a percent of the ring's diameter (`c:holeSize`) — never below the hole
+ * PowerPoint draws by default, at most the widest OOXML allows. A ring gauge's
+ * "27%" in a default hole ran onto its ring (x114 GTM 1). null for a doughnut
+ * with nothing in its hole; `fits` false where even the widest hole is too
+ * small.
+ */
+export function holeSizeFor(spec, chart) {
+  const ids = new Set(holeIds(chart));
+  const unit = (spec.elements ?? []).filter((e) => ids.has(e.id) && e.parent === chart.id && [e.x, e.y, e.w, e.h].every(Number.isFinite));
+  const ring = ringRect(chart);
+  const d = Math.min(ring.w, ring.h);
+  if (!unit.length || !(d > 0)) return null;
+  const w = Math.max(...unit.map((e) => e.x + e.w)) - Math.min(...unit.map((e) => e.x));
+  const h = Math.max(...unit.map((e) => e.y + e.h)) - Math.min(...unit.map((e) => e.y));
+  const need = Math.ceil((100 * Math.hypot(w, h)) / d);
+  return { size: Math.min(HOLE_MAX, Math.max(HOLE_DEFAULT, need)), fits: need <= HOLE_MAX };
+}