partforge 0.10.0 → 0.12.0

package/README.md

@@ -88,6 +88,40 @@ Test your parts headlessly with `partforge/testing`
 (or `node scripts/check-app.mjs <entry>.html`) — it loads the app and verifies the kernel
 boots with no errors. Needs Playwright: `npm i -D playwright && npx playwright install chromium`.
 
+### Embedding (0.12.0+)
+
+`mount()` returns a runtime handle and accepts element references, so an
+embedding app (React, iframe, multiple mounts) can size, await, and tear down
+the viewer without global IDs:
+
+```js
+const runtime = mount(part, {
+  createWorker,
+  elements: {
+    viewer, controls,                       // canvas host + param-panel host
+    status: { status, busy, phase },        // status chrome
+    tabs,                                   // view-tab segmented control
+    exports: { stl, step, threeMf },        // export buttons
+    chrome: { pause, reframe, theme },      // viewer buttons
+  },
+  onBuild: ({ status, ms, error }) => {},   // per accepted build: "success" | "error"
+  onPick: ({ selection, label, prompt, token }) => {}, // programmatic click-to-select
+});
+await runtime.ready;   // first successful build (rejects on a first-build error)
+runtime.dispose();     // stops loops, workers, observers, listeners; frees GPU resources
+```
+
+Every `elements` entry defaults to the legacy global ID (`#app`, `#controls`,
+`#status`/`#busy`/`#phase`, `#part`, `#download`/`#download-step`/`#download-3mf`,
+`#pause`/`#reframe`/`#theme`), so a classic host page needs no changes. The viewer
+sizes from its container via ResizeObserver — no window coupling.
+
+`onPick` arms click-to-select permanently: `label` is the feature label (falling
+back to the sub-part label/name) for compact UI, `prompt` is the LLM-ready
+sentence, `token` the compact form, `selection` the raw object. When `onPick` is
+set, the `?pick` / `?pickserver` URL modes are ignored (one click listener ever
+live); hover labels stay always-on.
+
 ## Authoring guide
 
 **[docs/AUTHORING-PARTS.md](docs/AUTHORING-PARTS.md)** is the full guide — the part

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,8 @@
     "./worker": "./src/framework/worker.js",
     "./geometry": "./src/framework/geometry/polygon.js",
     "./derive": "./src/framework/derive.js",
-    "./testing": "./src/testing.js"
+    "./testing": "./src/testing.js",
+    "./tokens.css": "./src/framework/tokens.css"
   },
   "bin": {
     "partforge": "./bin/cli.js"

package/src/framework/app.css

@@ -2,22 +2,8 @@
    busy overlay) + the light/dark palettes. Imported by framework/mount.js, so
    every part-app gets it; each part's HTML only carries structural markup.
    See docs/AUTHORING-PARTS.md. */
+@import "./tokens.css"; /* palette + light overrides; also exported standalone as partforge/tokens.css */
 
-:root {
-  color-scheme: dark;
-  --bg: #15181d; --surface: #1f242c; --surface-2: #20262e; --border: #2c333d;
-  --text: #d6dbe2; --text-strong: #e7ebf1; --text-2: #cdd4dd;
-  --muted: #7d8794; --muted-2: #aab2bd; --status: #8b94a0; --hint: #6b7480;
-  --accent: #3f7bf0; --accent-soft: #26314a; --on-accent: #fff; --input-bg: #161a20; --err: #f8746c;
-  --mono: ui-monospace, "SF Mono", SFMono-Regular, "JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace;
-}
-:root[data-theme="light"] {
-  color-scheme: light;
-  --bg: #eef1f5; --surface: #ffffff; --surface-2: #f4f6f9; --border: #d4dae2;
-  --text: #2b333d; --text-strong: #1a2129; --text-2: #3a434e;
-  --muted: #6b7480; --muted-2: #59636f; --status: #6b7480; --hint: #8a93a0;
-  --accent: #1f5bd6; --accent-soft: #e6edfc; --on-accent: #fff; --input-bg: #ffffff; --err: #d8453d;
-}
 * { box-sizing: border-box; }
 html, body { margin: 0; height: 100%; overflow: hidden;
   font: 13px/1.4 -apple-system, system-ui, sans-serif; }

package/src/framework/controls.js

@@ -47,35 +47,51 @@ export function clampToRange(raw, min, max) {
   return Math.min(max, Math.max(min, v));
 }
 
-// --- info glyph + shared popover ------------------------------------------
-// One popover element, reused across glyphs (only one open at a time). Global
-// dismiss listeners are registered once at module load.
-let popover = null;
-function ensurePopover() {
-  if (!popover || !popover.isConnected) {
-    popover = document.createElement("div");
-    popover.className = "popover";
-    popover.hidden = true;
-    document.body.append(popover);
-  }
-  return popover;
-}
-function closePopover() {
-  if (popover && !popover.hidden) {
-    popover.hidden = true;
-    if (popover._owner) { popover._owner.setAttribute("aria-expanded", "false"); popover._owner = null; }
+// --- info glyph + per-panel popover -----------------------------------------
+// One popover element per panel, shared by all its glyphs (only one open at a
+// time). Document-level dismiss listeners are registered per panel and removed
+// by panel.dispose().
+function createInfoPopover() {
+  const pop = el("div", "popover");
+  pop.hidden = true;
+  document.body.append(pop);
+  let owner = null; // the glyph whose description is showing
+
+  function close() {
+    if (pop.hidden) return;
+    pop.hidden = true;
+    if (owner) { owner.setAttribute("aria-expanded", "false"); owner = null; }
   }
-}
-if (typeof document !== "undefined") {
-  document.addEventListener("click", (e) => {
-    if (popover && !popover.hidden && !popover.contains(e.target) && !e.target.closest?.(".info")) closePopover();
-  });
-  document.addEventListener("keydown", (e) => { if (e.key === "Escape") closePopover(); });
+  const onDocClick = (e) => {
+    if (!pop.hidden && !pop.contains(e.target) && !e.target.closest?.(".info")) close();
+  };
+  const onDocKeydown = (e) => { if (e.key === "Escape") close(); };
+  document.addEventListener("click", onDocClick);
+  document.addEventListener("keydown", onDocKeydown);
+
+  return {
+    toggle(glyph, description) {
+      if (owner === glyph) { close(); return; } // toggle off
+      close();
+      pop.innerHTML = renderMarkdown(description);
+      pop.hidden = false;
+      owner = glyph;
+      glyph.setAttribute("aria-expanded", "true");
+      const r = glyph.getBoundingClientRect();
+      pop.style.top = `${r.bottom + 6}px`;
+      pop.style.left = `${Math.max(8, r.left - 8)}px`;
+    },
+    dispose() {
+      document.removeEventListener("click", onDocClick);
+      document.removeEventListener("keydown", onDocKeydown);
+      pop.remove();
+    },
+  };
 }
 
-// Append a focusable ⓘ glyph to `container` that toggles the shared popover with
-// `description` (Markdown). No-op when description is empty.
-function attachInfo(container, description) {
+// Append a focusable ⓘ glyph to `container` that toggles the panel's shared
+// popover with `description` (Markdown). No-op when description is empty.
+function attachInfo(container, description, info) {
   if (typeof description !== "string" || !description.trim()) return;
   const glyph = document.createElement("button");
   glyph.type = "button";
@@ -83,19 +99,7 @@ function attachInfo(container, description) {
   glyph.textContent = "ⓘ";
   glyph.setAttribute("aria-label", "More info");
   glyph.setAttribute("aria-expanded", "false");
-  glyph.addEventListener("click", (e) => {
-    e.stopPropagation();
-    const pop = ensurePopover();
-    if (pop._owner === glyph) { closePopover(); return; } // toggle off
-    closePopover();
-    pop.innerHTML = renderMarkdown(description);
-    pop.hidden = false;
-    pop._owner = glyph;
-    glyph.setAttribute("aria-expanded", "true");
-    const r = glyph.getBoundingClientRect();
-    pop.style.top = `${r.bottom + 6}px`;
-    pop.style.left = `${Math.max(8, r.left - 8)}px`;
-  });
+  glyph.addEventListener("click", (e) => { e.stopPropagation(); info.toggle(glyph, description); });
   container.append(glyph);
 }
 
@@ -111,12 +115,12 @@ function el(tag, className, text) {
 //   "number"           — number box only (no slider)
 // The box accepts exact values (finer than `step`); typed values clamp to
 // [min, max] on commit (blur/Enter). Returns { wrap, sync }.
-function makeSlider(def, params, onChange) {
+function makeSlider(def, params, onChange, info) {
   const numeric = def.control === "number";
   const wrap = el("div", "slider");
   const row = el("div", "row");
   const label = el("label", "", def.label);
-  attachInfo(label, def.description);
+  attachInfo(label, def.description, info);
   row.append(label);
 
   // editable value box (+ optional unit suffix)
@@ -181,25 +185,29 @@ function advancedBlock() {
 }
 
 export function buildControls(root, parameters, params, onDirty) {
+  const info = createInfoPopover();
   const controls = []; // { key, el } per control element
   const sections = []; // { el, keys:Set } per rendered section
   for (const sec of parameters) {
     if (!sectionRenders(sec)) continue;
     const section = el("div", "section");
     const title = el("div", "sec-title", sec.title);
-    attachInfo(title, sec.description);
+    attachInfo(title, sec.description, info);
     section.append(title);
     const keys = new Set();
     const register = (key, node) => { controls.push({ key, el: node }); keys.add(key); };
-    if (sec.features) buildFeatureSection(section, sec, params, onDirty, register);
-    else buildPresetSection(section, sec, params, onDirty, register);
+    if (sec.features) buildFeatureSection(section, sec, params, onDirty, register, info);
+    else buildPresetSection(section, sec, params, onDirty, register, info);
     root.append(section);
     sections.push({ el: section, keys });
   }
-  return { applyRelevance: (relevant) => applyRelevance(relevant, controls, sections) };
+  return {
+    applyRelevance: (relevant) => applyRelevance(relevant, controls, sections),
+    dispose: () => { info.dispose(); root.replaceChildren(); },
+  };
 }
 
-function buildPresetSection(section, sec, params, onDirty, register) {
+function buildPresetSection(section, sec, params, onDirty, register, info) {
   // preset picker, below the title, full width (omitted when the section has no presets)
   let preset = null;
   const presetNames = sec.presets ? Object.keys(sec.presets) : [];
@@ -222,7 +230,7 @@ function buildPresetSection(section, sec, params, onDirty, register) {
     box.type = "checkbox";
     box.checked = params[t.key] > 0;
     const lbl = el("span", "", t.label);
-    attachInfo(lbl, t.description);
+    attachInfo(lbl, t.description, info);
     row.append(box, lbl);
     box.addEventListener("change", () => { params[t.key] = box.checked ? (t.on ?? 1) : 0; onDirty?.(); });
     register(t.key, row);
@@ -234,7 +242,7 @@ function buildPresetSection(section, sec, params, onDirty, register) {
   if (advanced.length) {
     const { adv, toggle } = advancedBlock();
     for (const def of advanced) {
-      const s = makeSlider(def, params, () => { if (preset) preset.value = "Custom"; onDirty?.(); });
+      const s = makeSlider(def, params, () => { if (preset) preset.value = "Custom"; onDirty?.(); }, info);
       adv.append(s.wrap);
       syncs[def.key] = s.sync;
       register(def.key, s.wrap);
@@ -254,7 +262,7 @@ function buildPresetSection(section, sec, params, onDirty, register) {
   }
 }
 
-function buildFeatureSection(section, sec, params, onDirty, register) {
+function buildFeatureSection(section, sec, params, onDirty, register, info) {
   // Everything lives under Advanced: each feature is a checkbox followed by its
   // own controls, which appear directly below it when the box is checked.
   const { adv, toggle } = advancedBlock();
@@ -266,14 +274,14 @@ function buildFeatureSection(section, sec, params, onDirty, register) {
     box.type = "checkbox";
     box.checked = params[feat.key] > 0;
     const featLabel = el("span", "", feat.label);
-    attachInfo(featLabel, feat.description);
+    attachInfo(featLabel, feat.description, info);
     checkRow.append(box, featLabel);
     register(feat.key, checkRow);
 
     const group = el("div", "feat-group");
     const syncs = [];
     for (const def of feat.sliders.filter((d) => !d.hidden)) {
-      const s = makeSlider(def, params, onDirty);
+      const s = makeSlider(def, params, onDirty, info);
       group.append(s.wrap);
       syncs.push(s.sync);
       register(def.key, s.wrap);

package/src/framework/debug-overlay.js

@@ -36,5 +36,6 @@ export function createDebugOverlay({ initialCachingOn = true, onToggle } = {}) {
         `L2 ops: ${l2}\n` +
         `L1 parts: ${skipped} skipped / ${rebuilt} rebuilt`;
     },
+    detach: () => box.remove(),
   };
 }

package/src/framework/geometry-service.js

@@ -12,5 +12,8 @@ export function createGeometryService({ createWorker, onMessage }) {
   // Post a job to the chosen backend's worker. The message's own `type` says what to
   // do (generate / export-stl / export-3mf / export-step); `backend` picks the worker
   // — manifold for preview/STL/3MF, occt for STEP (the caller passes "occt" for that).
-  return { send: (msg, backend = "manifold") => workers[backend].postMessage(msg) };
+  return {
+    send: (msg, backend = "manifold") => workers[backend].postMessage(msg),
+    terminate: () => { workers.manifold.terminate(); workers.occt.terminate(); },
+  };
 }

package/src/framework/mount.js

@@ -14,7 +14,7 @@ import { createDebugOverlay } from "./debug-overlay.js";
 import { createRegenLoop } from "./regen-loop.js";
 import { createStatusUi } from "./status-ui.js";
 import { createViewTabs } from "./view-tabs.js";
-import { attachPickToggle, attachHoverLabels } from "./selection/index.js";
+import { attachPickToggle, attachHoverLabels, attachPicker, formatSelection } from "./selection/index.js";
 import { createPickRequestClient } from "./pick-request/index.js";
 
 // Mount a full parametric-part app from a PartDefinition. mount is WIRING: the
@@ -22,14 +22,43 @@ import { createPickRequestClient } from "./pick-request/index.js";
 // the schema-driven control panel, the regenerate state machine (regen-loop.js),
 // the view tabs (view-tabs.js), the status chrome (status-ui.js), the per-sub-part
 // mesh-validity cache, and the geometry workers. The app supplies `createWorker(name)`
-// so Vite can bundle the worker (see geometry-service.js). DOM element ids match the
-// host page: #app (viewer), #controls, #status, #download, #download-step, #busy,
-// #phase, #part (the view-tab segmented control).
-export function mount(part, { createWorker, container = document.getElementById("app"),
-                              controls = document.getElementById("controls") } = {}) {
-  const viewer = createViewer(container, part);
-  attachHoverLabels(viewer, { part }); // always-on hover inspection (no-op on touch-only devices)
-  const ui = createStatusUi();
+// so Vite can bundle the worker (see geometry-service.js).
+//
+// Embedding contract (0.12.0):
+//   const runtime = mount(part, { createWorker, elements, onBuild, onPick });
+//   await runtime.ready;   // first successful build of the default view
+//   runtime.dispose();     // full teardown
+// Every `elements` entry defaults to the legacy global-ID lookup (below), resolved
+// exactly once here — submodules take element refs and never query the document.
+// `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
+export function mount(part, { createWorker, elements = {}, onBuild, onPick,
+                              container: legacyContainer, controls: legacyControls } = {}) {
+  // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
+  const byId = (id) => document.getElementById(id);
+  const els = {
+    viewer: elements.viewer ?? legacyContainer ?? byId("app"),
+    controls: elements.controls ?? legacyControls ?? byId("controls"),
+    status: {
+      status: elements.status?.status ?? byId("status"),
+      busy: elements.status?.busy ?? byId("busy"),
+      phase: elements.status?.phase ?? byId("phase"),
+    },
+    tabs: elements.tabs ?? byId("part"),
+    exports: {
+      stl: elements.exports?.stl ?? byId("download"),
+      step: elements.exports?.step ?? byId("download-step"),
+      threeMf: elements.exports?.threeMf ?? byId("download-3mf"),
+    },
+    chrome: {
+      pause: elements.chrome?.pause ?? byId("pause"),
+      reframe: elements.chrome?.reframe ?? byId("reframe"),
+      theme: elements.chrome?.theme ?? byId("theme"),
+    },
+  };
+
+  const viewer = createViewer(els.viewer, part);
+  const hover = attachHoverLabels(viewer, { part }); // always-on hover inspection (no-op on touch-only devices)
+  const ui = createStatusUi({ ...els.status, exports: [els.exports.stl, els.exports.step, els.exports.threeMf] });
 
   // ?backend=occt|manifold forces the backend; otherwise it's detected per part.
   let forcedBackend = new URLSearchParams(location.search).get("backend");
@@ -45,20 +74,16 @@ export function mount(part, { createWorker, container = document.getElementById(
     ? createDebugOverlay({ initialCachingOn: cachingOn, onToggle: (on) => { cachingOn = on; forceRegen(); } })
     : null;
 
-  const dlBtn = document.getElementById("download");
-  const dlStepBtn = document.getElementById("download-step");
-  const dl3mfBtn = document.getElementById("download-3mf");
-
   // View tabs (generated from part.views) + live params. A tab switch shows the
   // cached assembly instantly if it's current, else auto-builds what's missing.
-  const tabs = createViewTabs(document.getElementById("part"), part, {
+  const tabsCtl = createViewTabs(els.tabs, part, {
     onChange: () => { refreshView(); updateRelevance(); loop.kick(); },
   });
-  const view = () => tabs.current();
+  const view = () => tabsCtl.current();
   const params = { ...part.defaults };
 
   // Current selection context for the pickers: the active view + live params +
-  // derived values. Shared by both ?pick modes below.
+  // derived values. Shared by every pick mode below.
   const getContext = () => {
     let derived = {};
     // A throwing derive must not crash the pick flow — proceed without derived context.
@@ -66,18 +91,30 @@ export function mount(part, { createWorker, container = document.getElementById(
     return { view: view(), params, derived };
   };
 
-  // ?pick enables click-to-select: a toggle button + a transient toast. Off by
-  // default — no button, no listener, no behavior change. Deleting this block and
-  // the selection/ dir reverts the app exactly.
-  if (qs.has("pick")) {
-    attachPickToggle(viewer, { part, getContext });
+  // Click-to-select. Precedence (one click listener is ever live): the programmatic
+  // onPick option, else the ?pick clipboard toggle, else the ?pickserver client.
+  let picker = null;      // { setActive, detach } — armed permanently for onPick
+  let pickToggle = null;  // { detach }
+  let pickClient = null;  // { detach }
+  if (onPick) {
+    picker = attachPicker(viewer, {
+      part, getContext,
+      onPick: (selection) => onPick({
+        selection,
+        label: selection.feature?.label ?? part.parts[selection.subPart]?.label ?? selection.subPart,
+        prompt: formatSelection(selection, { style: "prompt" }),
+        token: formatSelection(selection, { style: "token" }),
+      }),
+    });
+    picker.setActive(true);
+  } else if (qs.has("pick")) {
+    pickToggle = attachPickToggle(viewer, { part, getContext });
   } else if (qs.has("pickserver")) {
     // Agent-driven mode: arm the picker only when the local pick-server asks for a
-    // click. Mutually exclusive with the clipboard ?pick toggle (else-if), so only one
-    // click listener is ever live. `?pickserver` or `?pickserver=http://host:port`.
+    // click. `?pickserver` or `?pickserver=http://host:port`.
     const serverUrl = typeof qs.get("pickserver") === "string" && qs.get("pickserver")
       ? qs.get("pickserver") : "http://127.0.0.1:4518";
-    createPickRequestClient({ serverUrl, viewer, part, getContext });
+    pickClient = createPickRequestClient({ serverUrl, viewer, part, getContext });
   }
 
   let framedView = null; // the view the camera was last framed to (null until first show)
@@ -106,6 +143,13 @@ export function mount(part, { createWorker, container = document.getElementById(
     },
   });
 
+  // First-build readiness: resolves on the first accepted meshes result, rejects on
+  // a first-build error. Guarded against unhandled rejection when never awaited.
+  let readySettled = false;
+  let resolveReady, rejectReady;
+  const ready = new Promise((res, rej) => { resolveReady = res; rejectReady = rej; });
+  ready.catch(() => {});
+
   // Reflect the active view. If every needed part is current, show it and enable
   // export. If stale (a regenerate is in flight), keep the old mesh visible so the
   // view doesn't flicker. If nothing's built yet, show nothing.
@@ -167,6 +211,8 @@ export function mount(part, { createWorker, container = document.getElementById(
             ui.setStatus(`${ui.statusText()} · ${(data.ms / 1000).toFixed(1)} s`);
           }
           dbg?.update({ ms: data.ms, hits: data.cache?.hits ?? 0, misses: data.cache?.misses ?? 0, skipped: lastGen.skipped, rebuilt: lastGen.rebuilt });
+          onBuild?.({ status: "success", ms: data.ms });
+          if (!readySettled) { readySettled = true; resolveReady(); }
         }
         loop.kick(); // stale → rebuild; fresh → the view may still need parts (tab switched mid-build)
         break;
@@ -191,13 +237,15 @@ export function mount(part, { createWorker, container = document.getElementById(
         ui.hideBusy();
         ui.setStatus(`failed: ${data.message}`, true);
         refreshView();
+        onBuild?.({ status: "error", error: data.message });
+        if (!readySettled) { readySettled = true; rejectReady(new Error(data.message)); }
         break;
     }
   }
 
   const service = createGeometryService({ createWorker, onMessage: onWorkerMessage });
 
-  const panel = buildControls(controls, part.parameters, params, onParamChange);
+  const panel = buildControls(els.controls, part.parameters, params, onParamChange);
   const updateRelevance = () => panel.applyRelevance(relevantParamKeys(part, view(), params));
   updateRelevance(); // initial view
 
@@ -215,21 +263,52 @@ export function mount(part, { createWorker, container = document.getElementById(
     loop.kick();
   }
 
-  dlBtn.addEventListener("click", () => {
+  const onStlClick = () => {
     ui.showBusy("exporting STL");
     service.send({ type: "export-stl", view: view(), params, quality: "print" }, backendFor());
-  });
+  };
+  els.exports.stl?.addEventListener("click", onStlClick);
 
-  dlStepBtn.addEventListener("click", () => {
+  const onStepClick = () => {
     ui.showBusy("exporting STEP");
     service.send({ type: "export-step", view: view(), params }, "occt"); // STEP is always OCCT
-  });
+  };
+  els.exports.step?.addEventListener("click", onStepClick);
 
-  dl3mfBtn?.addEventListener("click", () => {
+  const on3mfClick = () => {
     ui.showBusy("exporting 3MF");
     service.send({ type: "export-3mf", view: view(), params, quality: "print" }, backendFor());
-  });
+  };
+  els.exports.threeMf?.addEventListener("click", on3mfClick);
+
+  // Optional host-page viewer chrome (pause / reframe / theme) + camera persistence.
+  const chrome = attachViewerControls(viewer, els.chrome);
+
+  // Full teardown of everything this mount created. Idempotent. A disposed runtime
+  // can never surface a late build result (workers are terminated, the loop is
+  // terminal), which is what makes cross-mount swap races safe for embedders.
+  let disposed = false;
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    if (!readySettled) { readySettled = true; rejectReady(new Error("disposed before first build")); }
+    picker?.detach();
+    pickToggle?.detach();
+    pickClient?.detach();
+    hover.detach();
+    loop.dispose();
+    service.terminate();
+    els.exports.stl?.removeEventListener("click", onStlClick);
+    els.exports.step?.removeEventListener("click", onStepClick);
+    els.exports.threeMf?.removeEventListener("click", on3mfClick);
+    chrome.detach();
+    tabsCtl.detach();
+    panel.dispose();
+    dbg?.detach();
+    ui.hideBusy();
+    ui.setStatus("");
+    viewer.dispose();
+  }
 
-  // Optional host-page viewer chrome (#pause / #reframe / #theme) + camera persistence.
-  attachViewerControls(viewer);
+  return { ready, dispose };
 }

package/src/framework/regen-loop.js

@@ -13,12 +13,13 @@
 export function createRegenLoop({ missingParts, send, debounceMs = 180 }) {
   let kernelReady = false;
   let generating = false;
+  let disposed = false;
   let paramsVersion = 0; // bumped on every settings edit
   let genVersion = -1;   // the params version the in-flight build is building
   let timer = null;
 
   function kick() {
-    if (!kernelReady || generating) return; // re-kicked when the current build finishes
+    if (disposed || !kernelReady || generating) return; // re-kicked when the current build finishes
     const missing = missingParts();
     if (missing.length === 0) return;
     generating = true;
@@ -28,7 +29,7 @@ export function createRegenLoop({ missingParts, send, debounceMs = 180 }) {
 
   return {
     kick,
-    ready() { kernelReady = true; kick(); },
+    ready() { if (disposed) return; kernelReady = true; kick(); },
     markDirty() {
       paramsVersion++;
       clearTimeout(timer);
@@ -41,5 +42,7 @@ export function createRegenLoop({ missingParts, send, debounceMs = 180 }) {
       return genVersion === paramsVersion;
     },
     version: () => paramsVersion,
+    // Terminal: cancel the pending debounce and refuse all future sends.
+    dispose() { disposed = true; clearTimeout(timer); },
   };
 }

package/src/framework/selection/pick-toggle.js

@@ -31,4 +31,13 @@ export function attachPickToggle(viewer, { part, getContext }) {
   });
 
   btn.addEventListener("click", () => picker.setActive(btn.classList.toggle("on")));
+
+  return {
+    detach: () => {
+      picker.detach();
+      clearTimeout(hideTimer);
+      btn.remove();
+      toast.remove();
+    },
+  };
 }

package/src/framework/status-ui.js

@@ -1,18 +1,15 @@
 // The status line, busy overlay, and export-button enabling — mount's host-page
-// chrome, as one small adapter. #status/#busy/#phase are required page elements;
-// export buttons are looked up by id and any that are absent are simply skipped.
-export function createStatusUi(doc = document) {
-  const statusEl = doc.getElementById("status");
-  const busyEl = doc.getElementById("busy");
-  const phaseEl = doc.getElementById("phase");
-  const exportBtns = ["download", "download-step", "download-3mf"]
-    .map((id) => doc.getElementById(id)).filter(Boolean);
+// chrome, as one small adapter. Element refs in (mount resolves defaults); no
+// document queries here. status/busy/phase are required; export buttons are an
+// array and any falsy entries are simply skipped.
+export function createStatusUi({ status, busy, phase, exports = [] }) {
+  const exportBtns = exports.filter(Boolean);
 
   return {
-    setStatus(msg, isErr = false) { statusEl.textContent = msg; statusEl.classList.toggle("err", isErr); },
-    showBusy(phase) { phaseEl.textContent = `${phase}…`; busyEl.classList.add("show"); },
-    hideBusy() { busyEl.classList.remove("show"); },
+    setStatus(msg, isErr = false) { status.textContent = msg; status.classList.toggle("err", isErr); },
+    showBusy(p) { phase.textContent = `${p}…`; busy.classList.add("show"); },
+    hideBusy() { busy.classList.remove("show"); },
     setExportEnabled(on) { exportBtns.forEach((b) => { b.disabled = !on; }); },
-    statusText: () => statusEl.textContent,
+    statusText: () => status.textContent,
   };
 }

package/src/framework/tokens.css

@@ -0,0 +1,18 @@
+/* partforge design tokens — the light/dark palette. Imported by app.css (so every
+   part-app gets it via mount) and exported as "partforge/tokens.css" for other
+   consumers (e.g. partforge-cloud's app chrome) to share one source of truth. */
+:root {
+  color-scheme: dark;
+  --bg: #15181d; --surface: #1f242c; --surface-2: #20262e; --border: #2c333d;
+  --text: #d6dbe2; --text-strong: #e7ebf1; --text-2: #cdd4dd;
+  --muted: #7d8794; --muted-2: #aab2bd; --status: #8b94a0; --hint: #6b7480;
+  --accent: #3f7bf0; --accent-soft: #26314a; --on-accent: #fff; --input-bg: #161a20; --err: #f8746c;
+  --mono: ui-monospace, "SF Mono", SFMono-Regular, "JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace;
+}
+:root[data-theme="light"] {
+  color-scheme: light;
+  --bg: #eef1f5; --surface: #ffffff; --surface-2: #f4f6f9; --border: #d4dae2;
+  --text: #2b333d; --text-strong: #1a2129; --text-2: #3a434e;
+  --muted: #6b7480; --muted-2: #59636f; --status: #6b7480; --hint: #8a93a0;
+  --accent: #1f5bd6; --accent-soft: #e6edfc; --on-accent: #fff; --input-bg: #ffffff; --err: #d8453d;
+}

package/src/framework/view-tabs.js

@@ -5,7 +5,8 @@ import { loadView, saveView } from "./view-state.js";
 // the #part div empty); a part without `views` keeps whatever buttons the page
 // hand-wrote. The active view persists across reloads via view-state.
 export function createViewTabs(el, part, { onChange }) {
-  if (el && part.views) {
+  const generated = !!(el && part.views);
+  if (generated) {
     el.innerHTML = Object.entries(part.views)
       .map(([key, v], i) => `<button data-part="${key}"${i === 0 ? ' class="on"' : ""}>${v?.label ?? key}</button>`)
       .join("");
@@ -20,14 +21,21 @@ export function createViewTabs(el, part, { onChange }) {
   let view = savedBtn ? saved : defaultView;
   if (savedBtn) setActive(savedBtn);
 
-  el.addEventListener("click", (e) => {
+  const onClick = (e) => {
     const btn = e.target.closest("button[data-part]");
     if (!btn) return;
     view = btn.dataset.part;
     saveView(view);
     setActive(btn);
     onChange(view);
-  });
+  };
+  el.addEventListener("click", onClick);
 
-  return { current: () => view };
+  return {
+    current: () => view,
+    detach: () => {
+      el.removeEventListener("click", onClick);
+      if (generated) el.innerHTML = ""; // we generated these buttons; hand-written markup stays
+    },
+  };
 }

package/src/framework/viewer-controls.js

@@ -1,14 +1,10 @@
 import { loadRotating, saveRotating, saveCamera, loadTheme, saveTheme } from "./view-state.js";
 
-// Wire the optional viewer-chrome buttons on the host page (#pause / #reframe /
-// #theme) to the viewer, plus persist the camera pose. Each button is optional —
-// omit it from the page and its behavior is simply absent. Self-contained: touches
-// only the viewer and the DOM, none of the part/params/regenerate state.
-export function attachViewerControls(viewer) {
-  const pauseBtn = document.getElementById("pause");
-  const reframeBtn = document.getElementById("reframe");
-  const themeBtn = document.getElementById("theme");
-
+// Wire the optional viewer-chrome buttons (pause / reframe / theme) to the viewer,
+// plus persist the camera pose. Element refs in (mount resolves defaults); each
+// button is optional — pass nothing and its behavior is simply absent. Returns
+// { detach } removing every listener this attached.
+export function attachViewerControls(viewer, { pause: pauseBtn, reframe: reframeBtn, theme: themeBtn } = {}) {
   // Theme: toggle the page chrome (CSS vars keyed off <html data-theme>) and the
   // scene together; remember the choice across reloads.
   let theme = loadTheme();
@@ -20,7 +16,8 @@ export function attachViewerControls(viewer) {
     saveTheme(mode);
   }
   applyTheme(theme);
-  themeBtn?.addEventListener("click", () => applyTheme(theme === "light" ? "dark" : "light"));
+  const onThemeClick = () => applyTheme(theme === "light" ? "dark" : "light");
+  themeBtn?.addEventListener("click", onThemeClick);
 
   // Pause/resume the idle auto-rotation.
   let rotating = loadRotating();
@@ -31,18 +28,32 @@ export function attachViewerControls(viewer) {
     pauseBtn.title = rotating ? "Pause rotation" : "Resume rotation";
   };
   syncPause();
-  pauseBtn?.addEventListener("click", () => {
+  const onPauseClick = () => {
     rotating = !rotating;
     viewer.setAutoRotate(rotating);
     syncPause();
     saveRotating(rotating);
-  });
+  };
+  pauseBtn?.addEventListener("click", onPauseClick);
 
   // Re-fit the camera to the current view.
-  reframeBtn?.addEventListener("click", () => viewer.frame());
+  const onReframeClick = () => viewer.frame();
+  reframeBtn?.addEventListener("click", onReframeClick);
 
   // Persist the camera when the user finishes an orbit/zoom, and right before a
   // reload (captures the latest pose, including auto-rotation drift).
   viewer.onCameraEnd(() => saveCamera(viewer.getCameraState()));
-  window.addEventListener("pagehide", () => saveCamera(viewer.getCameraState()));
+  const onPageHide = () => saveCamera(viewer.getCameraState());
+  window.addEventListener("pagehide", onPageHide);
+
+  return {
+    detach: () => {
+      themeBtn?.removeEventListener("click", onThemeClick);
+      pauseBtn?.removeEventListener("click", onPauseClick);
+      reframeBtn?.removeEventListener("click", onReframeClick);
+      window.removeEventListener("pagehide", onPageHide);
+      // the onCameraEnd listener lives on the OrbitControls object, which
+      // viewer.dispose() destroys — nothing to remove here
+    },
+  };
 }

package/src/framework/viewer.js

@@ -87,7 +87,7 @@ export function createViewer(container, part) {
   // CAD-style feature edge lines (anti-aliased "fat" lines), one per sub-part.
   const EDGE_ANGLE = 35; // deg — OCCT fallback threshold (Manifold supplies seam-aware edges)
   const lineMaterial = new LineMaterial({ color: 0x1c232d, linewidth: 1.0 }); // ~10% lighter, 1 px
-  lineMaterial.resolution.set(innerWidth, innerHeight);
+  lineMaterial.resolution.set(1, 1); // real size set by resize() below
   const subLines = Object.fromEntries(
     names.map((n) => [n, new LineSegments2(new LineSegmentsGeometry(), lineMaterial)])
   );
@@ -204,14 +204,16 @@ export function createViewer(container, part) {
   }
 
   // --- resize ---------------------------------------------------------------
+  // Size from the host container (not the window) so embedders control the pane.
   function resize() {
-    const w = innerWidth, h = innerHeight;
+    const w = container.clientWidth || 300, h = container.clientHeight || 150;
     renderer.setSize(w, h);
     camera.aspect = w / h;
     camera.updateProjectionMatrix();
     lineMaterial.resolution.set(w, h); // fat lines need the viewport size for px width
   }
-  addEventListener("resize", resize);
+  const ro = new ResizeObserver(resize);
+  ro.observe(container);
   resize();
 
   // --- render loop ----------------------------------------------------------
@@ -235,6 +237,7 @@ export function createViewer(container, part) {
   function onCameraEnd(cb) { controls.addEventListener("end", cb); }
 
   // Transient marker at a world-space point — visual confirmation of a pick.
+  const flashTimers = new Set();
   function flashPoint(world) {
     const dot = new THREE.Mesh(
       new THREE.SphereGeometry(1.2, 16, 12),
@@ -243,8 +246,38 @@ export function createViewer(container, part) {
     dot.renderOrder = 999;
     dot.position.set(world[0], world[1], world[2]);
     scene.add(dot);
-    setTimeout(() => { scene.remove(dot); dot.geometry.dispose(); dot.material.dispose(); }, 1200);
+    const t = setTimeout(() => {
+      flashTimers.delete(t);
+      scene.remove(dot); dot.geometry.dispose(); dot.material.dispose();
+    }, 1200);
+    flashTimers.add(t);
   }
 
-  return { showAssembly, hideAssembly, setSubGeometry, hasSubMesh, subTriangles, frame, setAutoRotate, setTheme, getCameraState, setCameraState, onCameraEnd, camera, domElement: renderer.domElement, _subMeshes: subMesh, flashPoint };
+  // Full teardown: render loop, observers, controls, timers, GPU resources, DOM.
+  // Idempotent. Cached sub-part geometries and their edge lines are freed; the
+  // shared and per-part cloned materials tolerate double-dispose.
+  let disposed = false;
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    ro.disconnect();
+    renderer.setAnimationLoop(null);
+    controls.dispose();
+    for (const t of flashTimers) clearTimeout(t);
+    flashTimers.clear();
+    for (const n of names) {
+      const g = subCache[n];
+      if (g) { g.userData.edges?.dispose(); g.dispose(); subCache[n] = null; }
+      subMesh[n].material?.dispose();
+      subMesh[n].geometry?.dispose(); // the initial empty BufferGeometry, if never replaced
+    }
+    material.dispose();
+    lineMaterial.dispose();
+    grid.geometry.dispose();
+    grid.material.dispose();
+    renderer.dispose();
+    renderer.domElement.remove();
+  }
+
+  return { showAssembly, hideAssembly, setSubGeometry, hasSubMesh, subTriangles, frame, setAutoRotate, setTheme, getCameraState, setCameraState, onCameraEnd, camera, domElement: renderer.domElement, _subMeshes: subMesh, flashPoint, dispose };
 }