slidemind 0.3.19 → 0.4.0

package/src/builders/figure-sketch.mjs

@@ -0,0 +1,375 @@
+// A drawn figure as a STRUCTURAL SKETCH, compiled to exact geometry.
+//
+// The concept image is a sketch; tracing it copies its wobble. A figure is
+// instead described by what it is: a closed outline of a few points where the
+// outline changes character (corners, arc ends, extremes and inflections of a
+// smooth curve), each edge typed — a straight line, an arc on a named circle,
+// or a smooth curve — plus relations (a mirrored half, a copy of another
+// figure). Errors in those few numbers move or resize a feature; they cannot
+// put a dent into an edge, and a repeated or mirrored figure cannot drift.
+//
+// The same module compiles the sketch in the slide page (`<Figure>`, shipped
+// by the add-in as a browser script — so preview = export) and expands the
+// reader's sketch in the transcriber. It must stay self-contained: no imports,
+// only top-level `export function` / `export const` declarations.
+//
+// Figure props (slot px, absolute in the content container):
+//   circles  { id: [cx, cy, r] }
+//   outline  [{ x, y, smooth?, tangent?: "h"|"v", to?: "line"|"arc"|"curve", on?: circleId, dir?: "cw"|"ccw" }]
+//            — `to` is the edge from this point to the next (default line); arcs lie on `on`,
+//            running clockwise (cw) or counter-clockwise (ccw) on screen around its centre.
+//   mirror   { axis: "vertical"|"horizontal", at } | { axis: "line", through: [x, y], angle }
+//            (0° = vertical); `outline` is then the half from the axis back to the axis.
+//   holes    [outline, …]
+
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1]];
+const add = (a, b) => [a[0] + b[0], a[1] + b[1]];
+const mul = (a, s) => [a[0] * s, a[1] * s];
+const len = (a) => Math.hypot(a[0], a[1]);
+const nrm = (a) => { const l = len(a) || 1; return [a[0] / l, a[1] / l]; };
+const circleOf = (circles, id) => {
+  const c = id != null && circles ? circles[id] : null;
+  return Array.isArray(c) && c.length >= 3 && c.every(Number.isFinite) && c[2] > 0 ? { cx: c[0], cy: c[1], r: c[2] } : null;
+};
+
+function reflector(mirror) {
+  let px = 0, py = 0, ux = 0, uy = 1;
+  if (mirror.axis === "vertical") px = Number(mirror.at);
+  else if (mirror.axis === "horizontal") { py = Number(mirror.at); ux = 1; uy = 0; }
+  else {
+    const through = Array.isArray(mirror.through) ? mirror.through : [mirror.through?.x, mirror.through?.y];
+    const a = (Number(mirror.angle ?? 0) * Math.PI) / 180;
+    px = Number(through[0]); py = Number(through[1]); ux = Math.sin(a); uy = Math.cos(a);
+  }
+  const foot = (p) => { const t = (p[0] - px) * ux + (p[1] - py) * uy; return [px + t * ux, py + t * uy]; };
+  return { foot, reflect: (p) => { const f = foot(p); return [2 * f[0] - p[0], 2 * f[1] - p[1]]; } };
+}
+
+/**
+ * The full outline of a mirrored half: its first and last points sit on the
+ * axis; the other half is reflected and traversed back. A reflection AND a
+ * reversed traversal leave each arc's turning direction as it was.
+ */
+export function mirrorOutline(half, mirror, circles) {
+  const { foot, reflect } = reflector(mirror);
+  const m = half.length - 1;
+  if (m < 1) return { outline: half, circles };
+  const out = { ...circles };
+  const pts = half.map((p, i) => {
+    if (i !== 0 && i !== m) return { ...p };
+    const [x, y] = foot([p.x, p.y]);
+    return { ...p, x, y };
+  });
+  const mirroredCircle = (id) => {
+    const c = circleOf(out, id);
+    if (!c) return id;
+    const [cx, cy] = reflect([c.cx, c.cy]);
+    if (Math.hypot(cx - c.cx, cy - c.cy) < 0.5) return id;
+    const nid = `${id}~m`;
+    out[nid] ??= [cx, cy, c.r];
+    return nid;
+  };
+  const edge = (p) => ({ to: p.to, on: p.to === "arc" ? mirroredCircle(p.on) : undefined, dir: p.dir });
+  const full = pts.slice(0, m);
+  full.push({ ...pts[m], ...edge(pts[m - 1]) });
+  for (let k = m - 1; k >= 1; k--) {
+    const [x, y] = reflect([pts[k].x, pts[k].y]);
+    full.push({ ...pts[k], x, y, ...edge(pts[k - 1]) });
+  }
+  return { outline: full, circles: out };
+}
+
+function gauss(A, b) {
+  const n = b.length, m = A.map((r, i) => [...r, b[i]]);
+  for (let c = 0; c < n; c++) {
+    let p = c;
+    for (let r = c + 1; r < n; r++) if (Math.abs(m[r][c]) > Math.abs(m[p][c])) p = r;
+    [m[c], m[p]] = [m[p], m[c]];
+    const d = m[c][c] || 1e-12;
+    for (let r = 0; r < n; r++) if (r !== c) { const f = m[r][c] / d; for (let k = c; k <= n; k++) m[r][k] -= f * m[c][k]; }
+  }
+  return m.map((r, i) => r[n] / (r[i] || 1e-12));
+}
+
+// A C2 spline through a few designer points (chord-length parameters), ends
+// clamped to a unit tangent where one is known, natural otherwise.
+function splineOpen(Q, t0, t1) {
+  const k = Q.length - 1, h = [];
+  for (let i = 0; i < k; i++) h.push(Math.max(1e-6, len(sub(Q[i + 1], Q[i]))));
+  const M = [0, 1].map((ax) => {
+    const y = Q.map((q) => q[ax]), n = k + 1;
+    const A = Array.from({ length: n }, () => new Array(n).fill(0)), b = new Array(n).fill(0);
+    for (let i = 1; i < k; i++) { A[i][i - 1] = h[i - 1]; A[i][i] = 2 * (h[i - 1] + h[i]); A[i][i + 1] = h[i]; b[i] = 6 * ((y[i + 1] - y[i]) / h[i] - (y[i] - y[i - 1]) / h[i - 1]); }
+    if (t0) { A[0][0] = 2 * h[0]; A[0][1] = h[0]; b[0] = 6 * ((y[1] - y[0]) / h[0] - t0[ax]); } else A[0][0] = 1;
+    if (t1) { A[k][k - 1] = h[k - 1]; A[k][k] = 2 * h[k - 1]; b[k] = 6 * (t1[ax] - (y[k] - y[k - 1]) / h[k - 1]); } else A[k][k] = 1;
+    return gauss(A, b);
+  });
+  return cubicsFrom(Q, h, M, false);
+}
+function splineClosed(Q) {
+  const k = Q.length, h = [];
+  for (let i = 0; i < k; i++) h.push(Math.max(1e-6, len(sub(Q[(i + 1) % k], Q[i]))));
+  const M = [0, 1].map((ax) => {
+    const y = Q.map((q) => q[ax]), A = Array.from({ length: k }, () => new Array(k).fill(0)), b = new Array(k).fill(0);
+    for (let i = 0; i < k; i++) { const p = (i - 1 + k) % k, nx = (i + 1) % k; A[i][p] += h[p]; A[i][i] += 2 * (h[p] + h[i]); A[i][nx] += h[i]; b[i] = 6 * ((y[nx] - y[i]) / h[i] - (y[i] - y[p]) / h[p]); }
+    return gauss(A, b);
+  });
+  return cubicsFrom(Q, h, M, true);
+}
+function cubicsFrom(Q, h, M, closed) {
+  const n = closed ? Q.length : Q.length - 1, segs = [];
+  for (let i = 0; i < n; i++) {
+    const j = (i + 1) % Q.length;
+    const d0 = [0, 1].map((ax) => (Q[j][ax] - Q[i][ax]) / h[i] - (h[i] * (2 * M[ax][i] + M[ax][j])) / 6);
+    const d1 = [0, 1].map((ax) => (Q[j][ax] - Q[i][ax]) / h[i] + (h[i] * (M[ax][i] + 2 * M[ax][j])) / 6);
+    segs.push({ t: "C", p0: Q[i], c1: add(Q[i], mul(d0, h[i] / 3)), c2: sub(Q[j], mul(d1, h[i] / 3)), p1: Q[j] });
+  }
+  return segs;
+}
+
+function circleCircle(a, b, near) {
+  const d = Math.hypot(b.cx - a.cx, b.cy - a.cy);
+  if (d < 1e-6 || d > a.r + b.r || d < Math.abs(a.r - b.r)) return null;
+  const t = (a.r ** 2 - b.r ** 2 + d * d) / (2 * d), hh = Math.sqrt(Math.max(0, a.r ** 2 - t * t));
+  const mx = a.cx + (t * (b.cx - a.cx)) / d, my = a.cy + (t * (b.cy - a.cy)) / d;
+  const c1 = [mx + (hh * (b.cy - a.cy)) / d, my - (hh * (b.cx - a.cx)) / d], c2 = [mx - (hh * (b.cy - a.cy)) / d, my + (hh * (b.cx - a.cx)) / d];
+  return len(sub(c1, near)) <= len(sub(c2, near)) ? c1 : c2;
+}
+
+// Screen coordinates (y down): a positive angle turns clockwise.
+function arcSweep(c, a, b, dir) {
+  let da = Math.atan2(b[1] - c.cy, b[0] - c.cx) - Math.atan2(a[1] - c.cy, a[0] - c.cx);
+  while (da <= -Math.PI) da += 2 * Math.PI;
+  while (da > Math.PI) da -= 2 * Math.PI;
+  if (dir === "cw" && da < 0) da += 2 * Math.PI;
+  else if (dir === "ccw" && da > 0) da -= 2 * Math.PI;
+  return da;
+}
+
+/**
+ * Whether an outline has points enough to enclose anything: 3, or 2 joined by
+ * an arc (a lens, a disc from two half circles). A mirrored half runs from the
+ * axis to the axis; its 2 points enclose only when their edge is an arc.
+ */
+export function enoughPoints(outline, mirrored = false) {
+  const n = outline?.length ?? 0;
+  if (n >= 3) return true;
+  return n === 2 && outline.some((p, i) => p?.to === "arc" && (!mirrored || i === 0));
+}
+
+/** One closed outline -> segments (L / A / C). */
+export function compileOutline(outline, circles) {
+  const issues = [];
+  const pts = (outline ?? []).filter((p) => Number.isFinite(p?.x) && Number.isFinite(p?.y));
+  const n = pts.length;
+  if (!enoughPoints(pts)) return { segs: [], issues: ["an outline needs 3 points, or 2 joined by an arc"] };
+  const P = pts.map((p) => [p.x, p.y]);
+  const kind = (i) => { const t = pts[i].to; return t === "arc" || t === "curve" ? t : "line"; };
+  const arcCircle = (i) => { if (kind(i) !== "arc") return null; const c = circleOf(circles, pts[i].on); if (!c) issues.push(`point ${i}: arc on unknown circle "${pts[i].on}"`); return c; };
+  // 1. every arc end lies on its circle; a corner between two circles is their intersection
+  for (let i = 0; i < n; i++) {
+    const cin = arcCircle((i - 1 + n) % n), cout = arcCircle(i);
+    if (cin && cout && (cin.cx !== cout.cx || cin.cy !== cout.cy || cin.r !== cout.r)) { const x = circleCircle(cin, cout, P[i]); if (x) { P[i] = x; continue; } }
+    const c = cin ?? cout;
+    if (c) { const v = nrm(sub(P[i], [c.cx, c.cy])); P[i] = [c.cx + v[0] * c.r, c.cy + v[1] * c.r]; }
+  }
+  const tangentAt = (i, atEnd) => {
+    const a = P[i], b = P[(i + 1) % n], c = kind(i) === "arc" ? circleOf(circles, pts[i].on) : null;
+    if (c) { const q = atEnd ? b : a, r = sub(q, [c.cx, c.cy]); return nrm(arcSweep(c, a, b, pts[i].dir) > 0 ? [-r[1], r[0]] : [r[1], -r[0]]); }
+    return nrm(sub(b, a));
+  };
+  const hint = (i, chord) => (pts[i].tangent === "h" ? [Math.sign(chord[0]) || 1, 0] : pts[i].tangent === "v" ? [0, Math.sign(chord[1]) || 1] : null);
+  const breaks = (i) => !pts[i].smooth || !!pts[i].tangent;
+  const segs = new Array(n).fill(null);
+  // 2. smooth curves: one spline per run of curve edges between breaks
+  if (pts.every((_, i) => kind(i) === "curve") && !pts.some((_, i) => breaks(i))) {
+    splineClosed(P).forEach((s, i) => (segs[i] = s));
+  } else {
+    for (let s = 0; s < n; s++) {
+      if (kind(s) !== "curve" || (kind((s - 1 + n) % n) === "curve" && !breaks(s))) continue;
+      const idx = [s];
+      let j = s;
+      do { j = (j + 1) % n; idx.push(j); } while (kind(j) === "curve" && !breaks(j) && idx.length <= n);
+      const Q = idx.map((i) => P[i]), first = idx[0], last = idx[idx.length - 1];
+      let t0 = hint(first, sub(Q[1], Q[0])), t1 = hint(last, sub(Q[Q.length - 1], Q[Q.length - 2]));
+      if (!t0 && pts[first].smooth && kind((first - 1 + n) % n) !== "curve") t0 = tangentAt((first - 1 + n) % n, true);
+      if (!t1 && pts[last].smooth && kind(last) !== "curve") t1 = tangentAt(last, false);
+      const cs = Q.length === 2 && !t0 && !t1 ? [{ t: "L", p0: Q[0], p1: Q[1] }] : splineOpen(Q, t0, t1);
+      idx.slice(0, -1).forEach((i, k) => (segs[i] = cs[k]));
+    }
+  }
+  // 3. lines and arcs
+  for (let i = 0; i < n; i++) {
+    if (segs[i]) continue;
+    const a = P[i], b = P[(i + 1) % n], c = kind(i) === "arc" ? circleOf(circles, pts[i].on) : null;
+    segs[i] = c ? { t: "A", c: [c.cx, c.cy], r: c.r, a0: Math.atan2(a[1] - c.cy, a[0] - c.cx), da: arcSweep(c, a, b, pts[i].dir), p0: a, p1: b } : { t: "L", p0: a, p1: b };
+  }
+  return { segs, issues };
+}
+
+export function flattenSegs(segs) {
+  const out = [];
+  for (const s of segs) {
+    if (s.t === "L") out.push(s.p0);
+    else if (s.t === "A") { const k = Math.max(2, Math.ceil(Math.abs(s.da) / 0.05)); for (let i = 0; i < k; i++) { const a = s.a0 + (s.da * i) / k; out.push([s.c[0] + s.r * Math.cos(a), s.c[1] + s.r * Math.sin(a)]); } }
+    else for (let i = 0; i < 16; i++) { const t = i / 16, u = 1 - t; out.push([0, 1].map((ax) => u * u * u * s.p0[ax] + 3 * u * u * t * s.c1[ax] + 3 * u * t * t * s.c2[ax] + t * t * t * s.p1[ax])); }
+  }
+  return out;
+}
+
+/** Crossings between non-adjacent edges of a closed polyline. */
+export function selfIntersections(poly) {
+  const n = poly.length;
+  const o = (p, q, r) => Math.sign((q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0]));
+  let hits = 0;
+  for (let i = 0; i < n; i++) for (let j = i + 2; j < n; j++) {
+    if (i === 0 && j === n - 1) continue;
+    const a = poly[i], b = poly[(i + 1) % n], c = poly[j], d = poly[(j + 1) % n];
+    if (o(a, b, c) * o(a, b, d) < 0 && o(c, d, a) * o(c, d, b) < 0) hits++;
+  }
+  return hits;
+}
+
+const fmt = (v) => String(Math.round(v * 100) / 100);
+export function segsToPath(segs) {
+  if (!segs.length) return "";
+  let d = `M ${fmt(segs[0].p0[0])} ${fmt(segs[0].p0[1])}`;
+  for (const s of segs) {
+    if (s.t === "L") d += ` L ${fmt(s.p1[0])} ${fmt(s.p1[1])}`;
+    else if (s.t === "A") d += ` A ${fmt(s.r)} ${fmt(s.r)} 0 ${Math.abs(s.da) > Math.PI ? 1 : 0} ${s.da > 0 ? 1 : 0} ${fmt(s.p1[0])} ${fmt(s.p1[1])}`;
+    else d += ` C ${fmt(s.c1[0])} ${fmt(s.c1[1])} ${fmt(s.c2[0])} ${fmt(s.c2[1])} ${fmt(s.p1[0])} ${fmt(s.p1[1])}`;
+  }
+  return `${d} Z`;
+}
+
+/**
+ * Figure props -> the path to draw (slot px), its box, and what is wrong with
+ * it. A figure that cannot be drawn exactly still draws its points as a
+ * polygon, and names why.
+ */
+export function compileFigure(props) {
+  let circles = props?.circles ?? {};
+  let outline = props?.outline ?? [];
+  if (props?.mirror) ({ outline, circles } = mirrorOutline(outline, props.mirror, circles));
+  const main = compileOutline(outline, circles);
+  const holes = (props?.holes ?? []).map((h) => compileOutline(h, circles));
+  const issues = [...main.issues, ...holes.flatMap((h) => h.issues)];
+  let segs = main.segs;
+  if (!segs.length && outline.length >= 2) segs = outline.map((p, i) => ({ t: "L", p0: [p.x, p.y], p1: [outline[(i + 1) % outline.length].x, outline[(i + 1) % outline.length].y] }));
+  const flat = flattenSegs(segs);
+  const crossings = flat.length ? selfIntersections(flat) : 0;
+  if (crossings) issues.push(`the outline crosses itself (${crossings}×)`);
+  const all = [flat, ...holes.map((h) => flattenSegs(h.segs))].flat();
+  const xs = all.map((p) => p[0]), ys = all.map((p) => p[1]);
+  const bbox = all.length ? { x: Math.min(...xs), y: Math.min(...ys), w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys) } : { x: 0, y: 0, w: 0, h: 0 };
+  const d = [segs, ...holes.map((h) => h.segs)].filter((s) => s.length).map(segsToPath).join(" ");
+  return { d, bbox, issues };
+}
+
+// ---- the reader's sketch -> per-figure props (transcriber side) ----------
+
+const round1 = (v) => Math.round(v * 2) / 2;
+
+function rotatePoint(p, pivot, deg, dx, dy) {
+  const t = (deg * Math.PI) / 180, co = Math.cos(t), si = Math.sin(t);
+  const x = p[0] - pivot[0], y = p[1] - pivot[1];
+  return [pivot[0] + x * co - y * si + dx, pivot[1] + x * si + y * co + dy];
+}
+
+/**
+ * The reader's sketch (slot px: `{ circles: [{ id, cx, cy, r }], figures: [{ id,
+ * outline: [{ x, y, kind, tangent, next, circle, dir }], mirror, copyOf, holes }] }`)
+ * as literal Figure props per figure id. A copy is written out as its own
+ * outline (a rotated/shifted source), so every figure's props stand alone.
+ * Returns `{ figures: Map<id, props>, issues: string[] }`.
+ */
+export function expandSketch(sketch) {
+  const circlesAll = {};
+  for (const c of sketch?.circles ?? []) {
+    if (c && typeof c.id === "string" && [c.cx, c.cy, c.r].every(Number.isFinite) && c.r > 0) circlesAll[c.id] = [c.cx, c.cy, c.r];
+  }
+  const readPoint = (p) => {
+    const out = { x: round1(p.x), y: round1(p.y) };
+    if (p.kind === "smooth") out.smooth = true;
+    if (p.tangent === "h" || p.tangent === "v") out.tangent = p.tangent;
+    if (p.next === "arc" || p.next === "curve") out.to = p.next;
+    if (p.next === "arc") { out.on = p.circle; if (p.dir === "cw" || p.dir === "ccw") out.dir = p.dir; }
+    return out;
+  };
+  const byId = new Map((sketch?.figures ?? []).filter((f) => f && typeof f.id === "string").map((f) => [f.id, f]));
+  const out = new Map();
+  const issues = [];
+  const usedCircles = (outlines, pool) => {
+    const ids = new Set(outlines.flat().filter((p) => p.to === "arc").map((p) => p.on));
+    return Object.fromEntries([...ids].filter((id) => pool[id]).map((id) => [id, pool[id].map(round1)]));
+  };
+  const build = (id, stack) => {
+    if (out.has(id)) return out.get(id);
+    const f = byId.get(id);
+    if (!f) return null;
+    if (f.copyOf) {
+      if (stack.includes(f.copyOf.id)) { issues.push(`${id}: copyOf forms a cycle`); return null; }
+      const src = build(f.copyOf.id, [...stack, id]);
+      if (!src) { issues.push(`${id}: copy of unknown figure ${f.copyOf.id}`); return null; }
+      // Mirror first, then rotate the whole: a copy has no relation of its own.
+      const full = src.mirror ? mirrorOutline(src.outline, src.mirror, src.circles) : { outline: src.outline, circles: src.circles };
+      const piv = circlesAll[f.copyOf.about]
+        ? circlesAll[f.copyOf.about].slice(0, 2)
+        : (() => { const xs = full.outline.map((p) => p.x), ys = full.outline.map((p) => p.y); return [(Math.min(...xs) + Math.max(...xs)) / 2, (Math.min(...ys) + Math.max(...ys)) / 2]; })();
+      const rot = Number(f.copyOf.rotate) || 0, dx = Number(f.copyOf.dx) || 0, dy = Number(f.copyOf.dy) || 0;
+      const circles = Object.fromEntries(Object.entries(full.circles).map(([cid, c]) => { const [x, y] = rotatePoint([c[0], c[1]], piv, rot, dx, dy); return [cid, [round1(x), round1(y), round1(c[2])]]; }));
+      const outline = full.outline.map((p) => { const [x, y] = rotatePoint([p.x, p.y], piv, rot, dx, dy); return { ...p, x: round1(x), y: round1(y) }; });
+      const holes = (src.holes ?? []).map((h) => h.map((p) => { const [x, y] = rotatePoint([p.x, p.y], piv, rot, dx, dy); return { ...p, x: round1(x), y: round1(y) }; }));
+      const props = { circles: usedCircles([outline, ...holes], circles), outline, ...(holes.length ? { holes } : {}), copyOf: f.copyOf.id };
+      out.set(id, props);
+      return props;
+    }
+    const outline = (f.outline ?? []).filter((p) => Number.isFinite(p?.x) && Number.isFinite(p?.y)).map(readPoint);
+    if (!enoughPoints(outline, !!f.mirror)) { issues.push(`${id}: too few points to draw`); return null; }
+    const holes = (f.holes ?? []).map((h) => (h ?? []).filter((p) => Number.isFinite(p?.x) && Number.isFinite(p?.y)).map(readPoint)).filter((h) => enoughPoints(h));
+    const mirror = f.mirror?.axis === "vertical" || f.mirror?.axis === "horizontal"
+      ? { axis: f.mirror.axis, at: round1(Number(f.mirror.at)) }
+      : f.mirror?.axis === "line" && f.mirror.through
+        ? { axis: "line", through: [round1(Number(f.mirror.through.x ?? f.mirror.through[0])), round1(Number(f.mirror.through.y ?? f.mirror.through[1]))], angle: Math.round(Number(f.mirror.angle) * 10) / 10 }
+        : null;
+    const props = { circles: usedCircles([outline, ...holes], circlesAll), outline, ...(mirror ? { mirror } : {}), ...(holes.length ? { holes } : {}) };
+    const compiled = compileFigure(props);
+    if (compiled.issues.length) issues.push(...compiled.issues.map((m) => `${id}: ${m}`));
+    out.set(id, props);
+    return props;
+  };
+  for (const id of byId.keys()) build(id, []);
+  return { figures: out, issues };
+}
+
+const lit = (v) => JSON.stringify(v).replace(/"([A-Za-z_][A-Za-z0-9_]*)":/g, "$1: ");
+/** Figure props as JSX attributes (object literals only — the preservation reader reads them). */
+export function figureJsxAttrs(props) {
+  const attrs = [`circles={${lit(props.circles ?? {})}}`, `outline={${lit(props.outline)}}`];
+  if (props.mirror) attrs.push(`mirror={${lit(props.mirror)}}`);
+  if (props.holes?.length) attrs.push(`holes={${lit(props.holes)}}`);
+  return attrs.join(" ");
+}
+
+/**
+ * A figure that reaches outside the content slot (the export refuses one) is
+ * shifted in — and shrunk uniformly only when it is larger than the slot —
+ * never distorted. Returns `{ props, moved }`.
+ */
+export function fitFigureToSlot(props, slot) {
+  const { bbox } = compileFigure(props);
+  if (!(bbox.w > 0 && bbox.h > 0)) return { props, moved: false };
+  const inside = bbox.x >= -1 && bbox.y >= -1 && bbox.x + bbox.w <= slot.w + 1 && bbox.y + bbox.h <= slot.h + 1;
+  if (inside) return { props, moved: false };
+  const k = Math.min(1, slot.w / bbox.w, slot.h / bbox.h);
+  const tx = Math.max(0, Math.min(slot.w - bbox.w * k, bbox.x)), ty = Math.max(0, Math.min(slot.h - bbox.h * k, bbox.y));
+  const T = (x, y) => [Math.round((tx + (x - bbox.x) * k) * 2) / 2, Math.round((ty + (y - bbox.y) * k) * 2) / 2];
+  const point = (p) => { const [x, y] = T(p.x, p.y); return { ...p, x, y }; };
+  const circles = Object.fromEntries(Object.entries(props.circles ?? {}).map(([id, c]) => { const [x, y] = T(c[0], c[1]); return [id, [x, y, Math.round(c[2] * k * 2) / 2]]; }));
+  let mirror = props.mirror ?? null;
+  if (mirror?.axis === "vertical") mirror = { ...mirror, at: T(mirror.at, 0)[0] };
+  else if (mirror?.axis === "horizontal") mirror = { ...mirror, at: T(0, mirror.at)[1] };
+  else if (mirror?.axis === "line") mirror = { ...mirror, through: T(mirror.through[0], mirror.through[1]) };
+  const out = { ...props, circles, outline: props.outline.map(point), ...(mirror ? { mirror } : {}), ...(props.holes?.length ? { holes: props.holes.map((h) => h.map(point)) } : {}) };
+  return { props: out, moved: true };
+}