@litfamily/litopencode 1.0.31 → 1.0.33

package/skills/lit-schematic/scripts/doctor.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Reports what lit-schematic can do on this machine. Drawing and QA need only Node; PNG and
+// PDF export need Chrome or Chromium; Korean labels render in Pretendard when it is found; a
+// cutaway's motion loop needs ffmpeg (MP4, GIF) and img2webp (WebP), and is the only part that does.
+// It never installs anything and always exits 0 unless --strict is given and export is blocked.
+//
+//   node doctor.mjs [--out <dir>] [--json] [--strict]
+
+import { accessSync, constants, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { findPretendard } from "./lib/fonts.mjs";
+import { findTool } from "./motion.mjs";
+import { findChrome } from "./render.mjs";
+
+export function diagnose({ out = process.cwd(), env = process.env } = {}) {
+  const major = Number(process.versions.node.split(".")[0]);
+  const chrome = findChrome(env);
+  const font = findPretendard();
+  let writable = false;
+  try {
+    accessSync(existsSync(out) ? out : resolve(out, ".."), constants.W_OK);
+    writable = true;
+  } catch {
+    writable = false;
+  }
+  const checks = [
+    { id: "node", ok: major >= 20, detail: `Node ${process.versions.node}`, needed: "drawing, QA" },
+    { id: "renderer", ok: Boolean(chrome), detail: chrome ?? "no Chrome or Chromium found (set CHROME_PATH)", needed: "PNG, PDF, close-up sheets" },
+    { id: "font.korean", ok: Boolean(font), detail: font ? `${font.file} (${font.source})` : "Pretendard not found; Hangul falls back to the system font", needed: "Korean labels" },
+    { id: "output", ok: writable, detail: resolve(out), needed: "writing files" },
+    { id: "motion.ffmpeg", ok: Boolean(findTool("ffmpeg", env)), detail: findTool("ffmpeg", env) ?? "ffmpeg not found", needed: "motion loop (MP4, GIF)" },
+    { id: "motion.webp", ok: Boolean(findTool("img2webp", env)), detail: findTool("img2webp", env) ?? "img2webp not found", needed: "motion loop (WebP)" },
+  ];
+  const status = !checks[0].ok || !writable ? "BLOCKED" : chrome ? "PASS" : "DEGRADED";
+  return {
+    status,
+    checks,
+    setup: [
+      ...(chrome ? [] : ["Install Google Chrome (or Chromium), or point CHROME_PATH at an existing binary. lit-schematic never installs it for you."]),
+      ...(findTool("ffmpeg", env) && findTool("img2webp", env) ? [] : ["Only for motion loops: install ffmpeg and the WebP tools (img2webp) with your package manager. lit-schematic never installs them."]),
+    ],
+  };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const args = process.argv.slice(2);
+  const i = args.indexOf("--out");
+  const result = diagnose({ out: i >= 0 ? args[i + 1] : process.cwd() });
+  if (args.includes("--json")) console.log(JSON.stringify(result, null, 2));
+  else {
+    for (const c of result.checks) console.log(`${c.ok ? "ok  " : "MISS"} ${c.id.padEnd(12)} ${c.detail}  [${c.needed}]`);
+    for (const line of result.setup) console.log(`setup: ${line}`);
+    console.log(`DOCTOR ${result.status}`);
+  }
+  process.exitCode = args.includes("--strict") && result.status !== "PASS" ? 1 : 0;
+}

package/skills/lit-schematic/scripts/lib/figure.mjs

@@ -0,0 +1,81 @@
+// Journal figure pages: an exact column width in millimetres, panels with (a), (b) labels at
+// their top left, a key of stream colours, and the same mm user space as every other kit
+// drawing so the QA gate reads sizes at print scale.
+
+import { createCanvas } from "./sheet.mjs";
+import { el, esc, n, pathOf, ptToMm, svgDocument } from "./svg.mjs";
+import { JOURNAL, STREAM, fontFor } from "./theme.mjs";
+
+export const WIDTHS = JOURNAL.width;
+
+export function createFigure({ width = "double", height, title, desc = "", lang = "en", mode = "journal", labelStyle = "paren", textPt = JOURNAL.textPt } = {}) {
+  const w = typeof width === "number" ? width : WIDTHS[width];
+  if (!w) throw new Error(`createFigure: width must be a number of mm or one of ${Object.keys(WIDTHS).join(", ")}`);
+  if (!height) throw new Error("createFigure: height in mm is required");
+  if (height > JOURNAL.maxHeight) throw new Error(`createFigure: ${height} mm is taller than a journal page allows (${JOURNAL.maxHeight} mm)`);
+  const panels = [];
+  const layers = [];
+  const text = ptToMm(textPt);
+  const panelText = ptToMm(JOURNAL.panelPt);
+
+  function panel(label, [x, y, pw, ph]) {
+    const box = [x, y, x + pw, y + ph];
+    const inner = label === null ? box : [x, y + panelText + 1.6, x + pw, y + ph];
+    const entry = { label, box, inner, body: [] };
+    panels.push(entry);
+    return {
+      box,
+      inner,
+      label,
+      canvas: (options = {}) => {
+        const c = createCanvas({ box: options.box ?? inner, style: "journal", ...options });
+        entry.body.push(() => c.render());
+        entry.canvas = c;
+        return c;
+      },
+      iso: (view, { box: target = inner, labelColumn = null, calloutSize = text } = {}) => {
+        const fitted = view.fit(target, { labelColumn, size: calloutSize });
+        entry.view = view;
+        entry.body.push(() => view.render() + view.renderCallouts({ box: target, size: calloutSize }));
+        return fitted;
+      },
+      text: (tx, ty, content, { size = text, anchor = "start", bold = false, color = "#000000", kind = "note" } = {}) => {
+        entry.body.push(() => el("text", { x: tx, y: ty, "font-family": fontFor(content), "font-size": size, "text-anchor": anchor, "font-weight": bold ? "bold" : undefined, fill: color, "data-label": kind }, esc(content)));
+      },
+      raw: (svg) => entry.body.push(() => svg),
+    };
+  }
+
+  // A key of stream roles: a short line swatch and its name, one row each.
+  function key(roles, [x, y], { columns = 1, colWidth = 34, rowHeight = text + 1.6 } = {}) {
+    const rows = roles.map((role, i) => {
+      const spec = STREAM[role];
+      if (!spec) throw new Error(`key: unknown stream role ${role}`);
+      const cx = x + (i % columns) * colWidth;
+      const cy = y + Math.floor(i / columns) * rowHeight;
+      return el("g", { "data-legend-item": `role:${role}` },
+        el("path", { d: pathOf([[cx, cy - text * 0.3], [cx + 7, cy - text * 0.3]]), stroke: spec.color, "stroke-width": ptToMm(JOURNAL.linePt * 1.4), "stroke-dasharray": spec.dash ?? undefined, fill: "none", "data-legend-line": role }),
+        el("text", { x: cx + 9, y: cy, "font-family": fontFor(spec.label), "font-size": text, fill: "#000000", "data-label": "legend" }, esc(spec.label)));
+    });
+    layers.push(el("g", { "data-key": "streams" }, rows));
+  }
+
+  function render() {
+    const body = [el("rect", { x: 0, y: 0, width: w, height, fill: "#ffffff" })];
+    panels.forEach((p) => {
+      if (p.label === null) {
+        body.push(el("g", { "data-figure-body": "1" }, p.body.map((f) => f())));
+        return;
+      }
+      const [x0, y0] = p.box;
+      const shown = labelStyle === "paren" ? `(${p.label})` : labelStyle === "bold" ? p.label : p.label.toUpperCase();
+      body.push(el("g", { "data-panel": p.label, "data-panel-box": p.box.map(n).join(" ") },
+        el("text", { x: x0 + 0.2, y: y0 + panelText * 0.8, "font-family": fontFor(shown), "font-size": panelText, "font-weight": "bold", fill: "#000000", "data-label": "panel-label" }, esc(shown)),
+        p.body.map((f) => f())));
+    });
+    body.push(...layers);
+    return svgDocument({ width: w, height, title, desc, mode, lang, body: body.join(""), extra: { "data-min-text-pt": JOURNAL.minTextPt } });
+  }
+
+  return { width: w, height, text, panel, key, render, warnings: () => panels.flatMap((p) => [...(p.canvas?.warnings ?? []), ...(p.view?.warnings ?? [])]) };
+}

package/skills/lit-schematic/scripts/lib/fonts.mjs

@@ -0,0 +1,25 @@
+// Locates fonts for rendering. Pretendard ships with the sibling lit-diagram-drawer skill
+// (unmodified official file under the OFL); lit-schematic reads it from there instead of carrying
+// a second copy. Both skills install side by side under one skills directory.
+
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SKILL_ROOT = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+
+export function findPretendard() {
+  const sibling = join(SKILL_ROOT, "..", "lit-diagram-drawer", "assets", "fonts", "PretendardVariable.woff2");
+  if (existsSync(sibling)) return { file: sibling, source: "skill" };
+  const dirs = [join(homedir(), "Library", "Fonts"), "/Library/Fonts", join(homedir(), ".local", "share", "fonts"), "/usr/share/fonts", "C:\\Windows\\Fonts"];
+  for (const dir of dirs) {
+    try {
+      const hit = readdirSync(dir).find((name) => /^Pretendard.*\.(?:otf|ttf|woff2)$/iu.test(name));
+      if (hit) return { file: join(dir, hit), source: "system" };
+    } catch {
+      // directory absent on this platform
+    }
+  }
+  return null;
+}

package/skills/lit-schematic/scripts/lib/geom.mjs

@@ -0,0 +1,113 @@
+// Plane geometry shared by the router, the label placer and the QA gate.
+// Boxes are [x0, y0, x1, y1] with x0 <= x1 and y0 <= y1; points are [x, y].
+
+export const EPS = 1e-6;
+
+export const boxOf = (points) => {
+  const xs = points.map((p) => p[0]);
+  const ys = points.map((p) => p[1]);
+  return [Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys)];
+};
+export const grow = ([x0, y0, x1, y1], by) => [x0 - by, y0 - by, x1 + by, y1 + by];
+export const union = (a, b) => [Math.min(a[0], b[0]), Math.min(a[1], b[1]), Math.max(a[2], b[2]), Math.max(a[3], b[3])];
+export const area = ([x0, y0, x1, y1]) => Math.max(0, x1 - x0) * Math.max(0, y1 - y0);
+export const boxesOverlap = (a, b, by = 0) => a[0] < b[2] - by && a[2] > b[0] + by && a[1] < b[3] - by && a[3] > b[1] + by;
+export const overlapArea = (a, b) => area([Math.max(a[0], b[0]), Math.max(a[1], b[1]), Math.min(a[2], b[2]), Math.min(a[3], b[3])]);
+export const contains = (outer, inner, by = 0) =>
+  inner[0] >= outer[0] - by && inner[1] >= outer[1] - by && inner[2] <= outer[2] + by && inner[3] <= outer[3] + by;
+export const pointIn = ([x, y], [x0, y0, x1, y1], by = 0) => x > x0 + by && x < x1 - by && y > y0 + by && y < y1 - by;
+export const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+
+export function pointSegmentDistance(p, a, b) {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const span = dx * dx + dy * dy;
+  const t = span > 0 ? Math.max(0, Math.min(1, ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / span)) : 0;
+  return Math.hypot(p[0] - a[0] - t * dx, p[1] - a[1] - t * dy);
+}
+
+// Proper intersection point of two segments, or null. Touching at endpoints counts only when
+// `touch` is true; collinear overlaps are reported separately by `collinearOverlap`.
+export function segmentIntersection(a, b, c, d, touch = false) {
+  const r = [b[0] - a[0], b[1] - a[1]];
+  const s = [d[0] - c[0], d[1] - c[1]];
+  const denom = r[0] * s[1] - r[1] * s[0];
+  if (Math.abs(denom) < EPS) return null;
+  const t = ((c[0] - a[0]) * s[1] - (c[1] - a[1]) * s[0]) / denom;
+  const u = ((c[0] - a[0]) * r[1] - (c[1] - a[1]) * r[0]) / denom;
+  const lo = touch ? -EPS : 1e-4;
+  const hi = touch ? 1 + EPS : 1 - 1e-4;
+  if (t < lo || t > hi || u < lo || u > hi) return null;
+  return { point: [a[0] + t * r[0], a[1] + t * r[1]], t, u };
+}
+
+export function collinearOverlap(a, b, c, d, tolerance = 0.05) {
+  const r = [b[0] - a[0], b[1] - a[1]];
+  const length = Math.hypot(r[0], r[1]);
+  if (length < EPS) return 0;
+  const cross = (p) => Math.abs((p[0] - a[0]) * r[1] - (p[1] - a[1]) * r[0]) / length;
+  if (cross(c) > tolerance || cross(d) > tolerance) return 0;
+  const along = (p) => ((p[0] - a[0]) * r[0] + (p[1] - a[1]) * r[1]) / length;
+  const lo = Math.max(0, Math.min(along(c), along(d)));
+  const hi = Math.min(length, Math.max(along(c), along(d)));
+  return Math.max(0, hi - lo);
+}
+
+// Length of a segment that lies strictly inside a box (Liang–Barsky clip).
+export function insideLength(a, b, [x0, y0, x1, y1]) {
+  let t0 = 0;
+  let t1 = 1;
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  for (const [p, q] of [[-dx, a[0] - x0], [dx, x1 - a[0]], [-dy, a[1] - y0], [dy, y1 - a[1]]]) {
+    if (Math.abs(p) < EPS) {
+      if (q <= 0) return 0;
+    } else {
+      const t = q / p;
+      if (p < 0) t0 = Math.max(t0, t);
+      else t1 = Math.min(t1, t);
+    }
+  }
+  return t1 > t0 ? (t1 - t0) * Math.hypot(dx, dy) : 0;
+}
+
+export const segmentsOf = (points) => points.slice(1).map((point, index) => [points[index], point]);
+
+export function pathLength(points) {
+  return segmentsOf(points).reduce((sum, [a, b]) => sum + dist(a, b), 0);
+}
+
+export function pointAlong(points, at) {
+  let left = at;
+  for (const [a, b] of segmentsOf(points)) {
+    const length = dist(a, b);
+    if (left <= length) {
+      const t = length ? left / length : 0;
+      return { point: [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t], direction: length ? [(b[0] - a[0]) / length, (b[1] - a[1]) / length] : [1, 0] };
+    }
+    left -= length;
+  }
+  const [a, b] = segmentsOf(points).at(-1);
+  const length = dist(a, b) || 1;
+  return { point: b, direction: [(b[0] - a[0]) / length, (b[1] - a[1]) / length] };
+}
+
+// Removes repeated points and merges collinear runs, keeping the polyline's corners only.
+export function simplify(points) {
+  const out = [];
+  for (const point of points) {
+    const last = out.at(-1);
+    if (last && dist(last, point) < EPS) continue;
+    if (out.length >= 2) {
+      const prev = out.at(-2);
+      const cross = (last[0] - prev[0]) * (point[1] - last[1]) - (last[1] - prev[1]) * (point[0] - last[0]);
+      const dot = (last[0] - prev[0]) * (point[0] - last[0]) + (last[1] - prev[1]) * (point[1] - last[1]);
+      if (Math.abs(cross) < EPS && dot > 0) {
+        out[out.length - 1] = point;
+        continue;
+      }
+    }
+    out.push(point);
+  }
+  return out;
+}

package/skills/lit-schematic/scripts/lib/interactive.mjs

@@ -0,0 +1,292 @@
+// One self-contained HTML page for an isometric cutaway: preset views, an exploded view, layer
+// toggles and callouts that light their part on hover or keyboard focus. Nothing is fetched:
+// the drawings, styles and script are inline, so the file works offline and from email.
+//
+// Input is the static art the kit already drew, one SVG per preset view, each carrying the
+// markers the kit writes: data-group on assemblies, data-part/data-hull on parts, data-leader,
+// data-leader-dot, data-for-leader and data-target on callouts. Explode vectors are screen
+// offsets per view (view.screenVector of the world move), so the page needs no geometry.
+//
+// State can be set from the URL hash for checks and screenshots:
+//   #view=<id>&explode=1&hide=<group>,<group>&select=<callout id>
+
+import { esc } from "./svg.mjs";
+
+const CSS = `
+:root{--paper:#ffffff;--ink:#1d1d20;--muted:#5d5d64;--line:#d9d9de;--accent:#0072b2;--accent-soft:rgba(0,114,178,.14);--focus:#0072b2;color-scheme:light}
+*{box-sizing:border-box}
+body{margin:0;background:var(--paper);color:var(--ink);font:15px/1.45 Arial,Helvetica,"Apple SD Gothic Neo","Noto Sans KR",Pretendard,sans-serif}
+main{max-width:1180px;margin:0 auto;padding:20px 16px 28px}
+h1{font-size:22px;margin:0 0 4px}
+.lede{margin:0 0 14px;color:var(--muted);max-width:72ch}
+.bar{display:flex;flex-wrap:wrap;gap:10px 18px;align-items:center;margin:0 0 10px;padding:10px 0;border-top:1px solid var(--line);border-bottom:1px solid var(--line)}
+.group{display:flex;flex-wrap:wrap;gap:6px;align-items:center;border:0;margin:0;padding:0}
+.group>span,.group legend{font-size:12px;letter-spacing:.04em;text-transform:uppercase;color:var(--muted);margin-right:4px;padding:0;float:left}
+button{font:inherit;font-size:14px;padding:6px 12px;border:1px solid var(--line);border-radius:6px;background:#fff;color:var(--ink);cursor:pointer}
+button[aria-pressed="true"]{background:var(--ink);border-color:var(--ink);color:#fff}
+label.toggle{display:inline-flex;gap:6px;align-items:center;font-size:14px;padding:4px 8px;border:1px solid var(--line);border-radius:6px;cursor:pointer}
+button:focus-visible,label.toggle:focus-within,[data-for-leader]:focus-visible{outline:2px solid var(--focus);outline-offset:3px}
+.stage{position:relative}
+.stage svg{display:block;width:100%;height:auto;max-height:max(360px, calc(100vh - 200px))}
+.stage .view[hidden]{display:none}
+[data-for-leader]{cursor:pointer}
+[data-for-leader].on{font-weight:bold;fill:var(--accent)}
+path[data-leader].on{stroke:var(--accent);stroke-width:.32}
+circle[data-leader-dot].on{fill:var(--accent)}
+.hl{fill:var(--accent-soft);stroke:var(--accent);stroke-width:.45;pointer-events:none}
+.stage.exploded [data-leader],.stage.exploded [data-leader-dot]{opacity:.55}
+.hint{margin:10px 0 0;font-size:13px;color:var(--muted)}
+.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}
+@media (max-width:640px){h1{font-size:19px}button{padding:6px 9px}}
+`;
+
+// The page script: plain DOM, one animation loop that stops when nothing moves.
+const SCRIPT = `
+(() => {
+  const data = JSON.parse(document.getElementById("lit-data").textContent);
+  const stage = document.querySelector(".stage");
+  const live = document.getElementById("live");
+  const still = matchMedia("(prefers-reduced-motion: reduce)");
+  const state = { view: data.views[0].id, explode: 0, hidden: new Set(), select: null };
+  const progress = Object.fromEntries(data.order.map((g) => [g, 0]));
+  const target = Object.fromEntries(data.order.map((g) => [g, 0]));
+  const starts = {};
+  let frame = 0;
+
+  const svgOf = (id) => stage.querySelector('.view[data-view="' + id + '"] svg');
+  const active = () => svgOf(state.view);
+  const viewData = (id) => data.views.find((v) => v.id === id);
+  const say = (text) => { live.textContent = text; };
+
+  // Original leader ends, so an exploded part keeps its dot.
+  for (const view of data.views) {
+    const svg = svgOf(view.id);
+    for (const path of svg.querySelectorAll("path[data-leader]")) path.dataset.d0 = path.getAttribute("d");
+    for (const dot of svg.querySelectorAll("circle[data-leader-dot]")) { dot.dataset.cx0 = dot.getAttribute("cx"); dot.dataset.cy0 = dot.getAttribute("cy"); }
+    for (const label of svg.querySelectorAll("[data-for-leader]")) {
+      label.setAttribute("tabindex", "0");
+      label.setAttribute("role", "button");
+      label.setAttribute("aria-pressed", "false");
+    }
+  }
+
+  const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+  const offsetOf = (node, view) => {
+    let dx = 0, dy = 0;
+    for (let n = node; n && n.tagName !== "svg"; n = n.parentNode) {
+      const g = n.getAttribute && n.getAttribute("data-group");
+      const v = g && viewData(view).explode[g];
+      if (v) { dx += v[0] * progress[g]; dy += v[1] * progress[g]; }
+    }
+    return [dx, dy];
+  };
+
+  function place(view) {
+    const svg = svgOf(view);
+    const vd = viewData(view);
+    for (const node of svg.querySelectorAll("[data-group]")) {
+      const g = node.getAttribute("data-group");
+      const v = vd.explode[g];
+      const p = progress[g] || 0;
+      if (v && p > 0) node.setAttribute("transform", "translate(" + (v[0] * p).toFixed(3) + " " + (v[1] * p).toFixed(3) + ")");
+      else node.removeAttribute("transform");
+      // visibility, not display: an assembly nested in a hidden one (a bundle inside its shell) stays.
+      node.style.visibility = state.hidden.has(g) ? "hidden" : "visible";
+    }
+    for (const path of svg.querySelectorAll("path[data-leader]")) {
+      const id = path.getAttribute("data-leader");
+      const part = svg.querySelector('[data-part="' + CSS.escape(path.getAttribute("data-target") || "") + '"]');
+      const [dx, dy] = part ? offsetOf(part, view) : [0, 0];
+      const pts = path.dataset.d0.match(/-?[\\d.]+/g).map(Number);
+      pts[pts.length - 2] += dx; pts[pts.length - 1] += dy;
+      path.setAttribute("d", "M" + pts[0] + " " + pts[1] + pts.slice(2).reduce((s, v, i) => s + (i % 2 ? " " + v : "L" + v), ""));
+      const dot = svg.querySelector('circle[data-leader-dot="' + id + '"]');
+      dot.setAttribute("cx", (Number(dot.dataset.cx0) + dx).toFixed(3));
+      dot.setAttribute("cy", (Number(dot.dataset.cy0) + dy).toFixed(3));
+      const hiddenPart = part && part.closest("[data-group]") && [...state.hidden].some((g) => part.closest('[data-group="' + g + '"]'));
+      for (const el of [path, dot, svg.querySelector('[data-for-leader="' + id + '"]')]) el.style.display = hiddenPart ? "none" : "";
+    }
+    highlight(view);
+  }
+
+  function highlight(view) {
+    const svg = svgOf(view);
+    svg.querySelectorAll(".hl").forEach((n) => n.remove());
+    svg.querySelectorAll(".on").forEach((n) => n.classList.remove("on"));
+    svg.querySelectorAll("[data-for-leader]").forEach((n) => n.setAttribute("aria-pressed", "false"));
+    if (!state.select) return;
+    const label = svg.querySelector('[data-for-leader="' + state.select + '"]');
+    if (!label) return;
+    const path = svg.querySelector('path[data-leader="' + state.select + '"]');
+    const part = svg.querySelector('[data-part="' + CSS.escape(path.getAttribute("data-target") || "") + '"]');
+    [label, path, svg.querySelector('circle[data-leader-dot="' + state.select + '"]')].forEach((n) => n.classList.add("on"));
+    label.setAttribute("aria-pressed", "true");
+    if (part && part.dataset.hull) {
+      const [dx, dy] = offsetOf(part, view);
+      const poly = document.createElementNS("http://www.w3.org/2000/svg", "polygon");
+      poly.setAttribute("class", "hl");
+      poly.setAttribute("points", part.dataset.hull.split(" ").map((p) => p.split(",").map(Number)).map(([x, y]) => (x + dx).toFixed(2) + "," + (y + dy).toFixed(2)).join(" "));
+      svg.querySelector("[data-callouts]").before(poly);
+    }
+  }
+
+  function tick(now) {
+    let moving = false;
+    for (const g of data.order) {
+      const s = starts[g];
+      if (!s) continue;
+      const t = Math.min(1, Math.max(0, (now - s.at) / data.duration));
+      progress[g] = s.from + (target[g] - s.from) * ease(t);
+      if (t < 1) moving = true; else delete starts[g];
+    }
+    place(state.view);
+    frame = moving ? requestAnimationFrame(tick) : 0;
+  }
+
+  function setExplode(on, announce = true) {
+    state.explode = on ? 1 : 0;
+    stage.classList.toggle("exploded", !!on);
+    document.getElementById("explode").setAttribute("aria-pressed", String(!!on));
+    // Outside parts leave first and come home last.
+    const order = on ? data.order : [...data.order].reverse();
+    const now = performance.now();
+    order.forEach((g, i) => {
+      target[g] = on ? 1 : 0;
+      if (still.matches) { progress[g] = target[g]; delete starts[g]; }
+      else starts[g] = { from: progress[g], at: now + i * data.stagger };
+    });
+    if (still.matches) place(state.view);
+    else if (!frame) frame = requestAnimationFrame(tick);
+    if (announce) say(on ? data.text.exploded : data.text.assembled);
+  }
+
+  function setView(id, announce = true) {
+    state.view = id;
+    for (const node of stage.querySelectorAll(".view")) node.hidden = node.dataset.view !== id;
+    for (const b of document.querySelectorAll("[data-view-button]")) b.setAttribute("aria-pressed", String(b.dataset.viewButton === id));
+    place(id);
+    if (announce) say(viewData(id).label);
+  }
+
+  function select(id, announce = true) {
+    state.select = state.select === id ? null : id;
+    highlight(state.view);
+    if (announce && state.select) say(active().querySelector('[data-for-leader="' + state.select + '"]').textContent);
+  }
+
+  document.querySelectorAll("[data-view-button]").forEach((b) => b.addEventListener("click", () => setView(b.dataset.viewButton)));
+  document.getElementById("explode").addEventListener("click", () => setExplode(!state.explode));
+  document.querySelectorAll("[data-layer]").forEach((box) => box.addEventListener("change", () => {
+    if (box.checked) state.hidden.delete(box.dataset.layer); else state.hidden.add(box.dataset.layer);
+    place(state.view);
+    say((box.checked ? data.text.shown : data.text.hidden) + " " + box.dataset.label);
+  }));
+  stage.addEventListener("click", (e) => {
+    const label = e.target.closest("[data-for-leader]");
+    if (label) { select(label.getAttribute("data-for-leader")); return; }
+    const part = e.target.closest("[data-part]");
+    const id = part && partCallout(part);
+    if (id) select(id);
+  });
+  stage.addEventListener("keydown", (e) => {
+    const label = e.target.closest && e.target.closest("[data-for-leader]");
+    if (label && (e.key === "Enter" || e.key === " ")) { e.preventDefault(); select(label.getAttribute("data-for-leader")); }
+  });
+  stage.addEventListener("focusin", (e) => {
+    const label = e.target.closest && e.target.closest("[data-for-leader]");
+    if (label && state.select !== label.getAttribute("data-for-leader")) select(label.getAttribute("data-for-leader"));
+  });
+  // Hover previews a part's callout without changing the selection the keyboard made.
+  let hoverFrom = null;
+  stage.addEventListener("pointermove", (e) => {
+    const label = e.target.closest("[data-for-leader]");
+    const part = !label && e.target.closest("[data-part]");
+    const id = label ? label.getAttribute("data-for-leader") : part ? partCallout(part) : null;
+    if (id && id !== state.select) { if (hoverFrom === null) hoverFrom = state.select; state.select = id; highlight(state.view); }
+    if (!id && hoverFrom !== null) { state.select = hoverFrom; hoverFrom = null; highlight(state.view); }
+  });
+  stage.addEventListener("pointerleave", () => { if (hoverFrom !== null) { state.select = hoverFrom; hoverFrom = null; highlight(state.view); } });
+  document.addEventListener("keydown", (e) => {
+    // A held key repeats; a toggle should flip once per press.
+    if (e.repeat || e.altKey || e.ctrlKey || e.metaKey) return;
+    if (e.target.closest && e.target.closest("input,button")) { if (e.key !== "Escape") return; }
+    if (e.key === "Escape") { state.select = null; highlight(state.view); }
+    if (e.key === "e" || e.key === "E") setExplode(!state.explode);
+    const n = Number(e.key);
+    if (n >= 1 && n <= data.views.length) setView(data.views[n - 1].id);
+  });
+  function partCallout(part) {
+    for (let n = part; n && n.tagName !== "svg"; n = n.parentNode) {
+      const name = n.getAttribute && n.getAttribute("data-part");
+      if (!name) continue;
+      const path = active().querySelector('path[data-leader][data-target="' + CSS.escape(name) + '"]');
+      if (path) return path.getAttribute("data-leader");
+    }
+    return null;
+  }
+
+  // Initial state, optionally from the hash.
+  const hash = new URLSearchParams(location.hash.slice(1));
+  for (const g of (hash.get("hide") || "").split(",").filter(Boolean)) {
+    state.hidden.add(g);
+    const box = document.querySelector('[data-layer="' + g + '"]');
+    if (box) box.checked = false;
+  }
+  setView(viewData(hash.get("view")) ? hash.get("view") : state.view, false);
+  if (hash.get("explode") === "1") { for (const g of data.order) { progress[g] = 1; target[g] = 1; } state.explode = 1; stage.classList.add("exploded"); document.getElementById("explode").setAttribute("aria-pressed", "true"); }
+  if (hash.get("select")) state.select = hash.get("select");
+  place(state.view);
+  document.documentElement.dataset.ready = "1";
+})();
+`;
+
+export function renderInteractive({
+  title, description = "", lang = "en", views, layers = [], order = null,
+  duration = 700, stagger = 90, hint = null,
+  text = {},
+} = {}) {
+  if (!title) throw new Error("renderInteractive: title is required");
+  if (!views?.length) throw new Error("renderInteractive: give at least one view { id, label, svg, explode }");
+  const groups = order ?? [...new Set(views.flatMap((v) => Object.keys(v.explode ?? {})))];
+  const words = {
+    views: "View", layers: "Layers", explode: "Exploded view", exploded: "Exploded view", assembled: "Assembled",
+    shown: "Showing", hidden: "Hiding",
+    hint: "Hover or Tab to a label to light its part. E explodes, 1 to " + views.length + " switch views, Esc clears.",
+    ...text,
+  };
+  const data = {
+    views: views.map((v) => ({ id: v.id, label: v.label, explode: v.explode ?? {} })),
+    order: groups, duration, stagger,
+    text: { exploded: words.exploded, assembled: words.assembled, shown: words.shown, hidden: words.hidden },
+  };
+  const stripProlog = (svg) => svg.replace(/^\s*<\?xml[^>]*>\s*/u, "");
+  const viewButtons = views.map((v, i) => `<button type="button" data-view-button="${esc(v.id)}" aria-pressed="${i === 0}" aria-keyshortcuts="${i + 1}">${esc(v.label)}</button>`).join("");
+  const layerBoxes = layers.map((l) => `<label class="toggle"><input type="checkbox" checked data-layer="${esc(l.group)}" data-label="${esc(l.label)}">${esc(l.label)}</label>`).join("");
+  const stages = views.map((v, i) => `<div class="view" data-view="${esc(v.id)}"${i ? " hidden" : ""}>${stripProlog(v.svg)}</div>`).join("");
+  return `<!doctype html>
+<html lang="${esc(lang)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<main>
+<h1>${esc(title)}</h1>
+${description ? `<p class="lede">${esc(description)}</p>` : ""}
+<div class="bar">
+<div class="group" role="group" aria-label="${esc(words.views)}"><span aria-hidden="true">${esc(words.views)}</span>${viewButtons}</div>
+<button type="button" id="explode" aria-pressed="false" aria-keyshortcuts="E">${esc(words.explode)}</button>
+${layers.length ? `<fieldset class="group"><legend>${esc(words.layers)}</legend>${layerBoxes}</fieldset>` : ""}
+</div>
+<div class="stage">${stages}</div>
+<p class="hint">${esc(hint ?? words.hint)}</p>
+<p id="live" class="sr" aria-live="polite"></p>
+</main>
+<script type="application/json" id="lit-data">${JSON.stringify(data).replace(/</gu, "\\u003c")}</script>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+}