partforge 0.6.1 → 0.8.0

package/src/framework/mount.js

@@ -1,26 +1,34 @@
 import "./app.css"; // shared chrome styles — every part-app gets them via mount
-import { zipSync } from "fflate";
+import { triggerDownload, downloadParts } from "./download.js";
 import { createViewer } from "./viewer.js";
-import { loadRotating, saveRotating, loadCamera, saveCamera, loadView, saveView } from "./view-state.js";
+import { attachViewerControls } from "./viewer-controls.js";
+import { loadCamera } from "./view-state.js";
 import { buildControls } from "./controls.js";
-import { relevantParamKeys, subPartReadKeys, relevanceHash, RELEVANT_ALL } from "./param-deps.js";
+import { relevantParamKeys } from "./param-deps.js";
+import { createMeshCache } from "./mesh-cache.js";
 import { createGeometryService } from "./geometry-service.js";
 import { viewSubParts } from "./jobs.js";
 import { detectBackend } from "./geometry/probe.js";
 import { createDebugOverlay } from "./debug-overlay.js";
-import { attachPicker, formatSelection } from "./selection/index.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 { createPickRequestClient } from "./pick-request/index.js";
 
-// Mount a full parametric-part app from a PartDefinition: 3-D viewer + control
-// panel + the two geometry workers + the auto-regenerating view/cache loop +
-// STL/STEP export. 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).
+// Mount a full parametric-part app from a PartDefinition. mount is WIRING: the
+// pieces it composes each live (and are tested) in their own module — the viewer,
+// 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 names = Object.keys(part.parts);
   const viewer = createViewer(container, part);
+  attachHoverLabels(viewer, { part }); // always-on hover inspection (no-op on touch-only devices)
+  const ui = createStatusUi();
 
   // ?backend=occt|manifold forces the backend; otherwise it's detected per part.
   let forcedBackend = new URLSearchParams(location.search).get("backend");
@@ -36,121 +44,61 @@ export function mount(part, { createWorker, container = document.getElementById(
     ? createDebugOverlay({ initialCachingOn: cachingOn, onToggle: (on) => { cachingOn = on; forceRegen(); } })
     : null;
 
-  const statusEl = document.getElementById("status");
   const dlBtn = document.getElementById("download");
   const dlStepBtn = document.getElementById("download-step");
   const dl3mfBtn = document.getElementById("download-3mf");
-  const busyEl = document.getElementById("busy");
-  const phaseEl = document.getElementById("phase");
-  const partSeg = document.getElementById("part");
-  let kernelReady = false;
 
-  const exportBtns = [dlBtn, dlStepBtn, dl3mfBtn].filter(Boolean);
-  const setExportEnabled = (on) => exportBtns.forEach((b) => { b.disabled = !on; });
-
-  const setStatus = (msg, isErr = false) => { statusEl.textContent = msg; statusEl.classList.toggle("err", isErr); };
-  const showBusy = (phase) => { phaseEl.textContent = `${phase}…`; busyEl.classList.add("show"); };
-  const hideBusy = () => busyEl.classList.remove("show");
-
-  // --- per-sub-part mesh cache + auto-regenerating view composition ----------
-  // The view-tab buttons are generated from `part.views` (the single source of truth):
-  // each entry becomes a <button data-part=view>label</button> inside #part, with the
-  // first view marked active by default. (A saved view, below, overrides the default.)
-  if (partSeg && part.views) {
-    partSeg.innerHTML = Object.entries(part.views)
-      .map(([key, v], i) => `<button data-part="${key}"${i === 0 ? ' class="on"' : ""}>${v?.label ?? key}</button>`)
-      .join("");
-  }
-  // The initial view is whichever tab is marked active (else the first tab).
+  // 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, {
+    onChange: () => { refreshView(); updateRelevance(); loop.kick(); },
+  });
+  const view = () => tabs.current();
   const params = { ...part.defaults };
-  const defaultView = partSeg.querySelector("button.on")?.dataset.part ?? partSeg.querySelector("button")?.dataset.part;
-  const savedView = loadView();
-  const savedBtn = savedView ? [...partSeg.querySelectorAll("button[data-part]")].find((b) => b.dataset.part === savedView) : null;
-  let view = savedBtn ? savedView : defaultView;
-  if (savedBtn) for (const b of partSeg.children) b.classList.toggle("on", b === savedBtn);
+
+  // Current selection context for the pickers: the active view + live params +
+  // derived values. Shared by both ?pick modes below.
+  const getContext = () => ({ view: view(), params, derived: part.derive ? part.derive({ ...part.defaults, ...params }) : {} });
 
   // ?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")) {
-    const btn = document.createElement("button");
-    btn.id = "pf-pick";
-    btn.textContent = "Pick";
-    btn.title = "Click a surface to copy a selection token";
-    Object.assign(btn.style, {
-      position: "fixed", left: "12px", bottom: "12px", zIndex: 9999,
-      font: "12px system-ui, sans-serif", padding: "6px 10px", cursor: "pointer",
-    });
-    document.body.appendChild(btn);
-
-    const toast = document.createElement("div");
-    Object.assign(toast.style, {
-      position: "fixed", left: "12px", bottom: "48px", zIndex: 9999, maxWidth: "60ch",
-      font: "12px ui-monospace, monospace", padding: "6px 10px", borderRadius: "4px",
-      background: "rgba(20,24,29,0.92)", color: "#d8e0ea", display: "none",
-      whiteSpace: "pre-wrap", wordBreak: "break-word",
-    });
-    document.body.appendChild(toast);
-
-    const picker = attachPicker(viewer, {
-      part,
-      getContext: () => ({ view, params, derived: part.derive ? part.derive({ ...part.defaults, ...params }) : {} }),
-      onPick: (selection) => {
-        const token = formatSelection(selection, { style: "token" });
-        navigator.clipboard?.writeText(token);
-        toast.textContent = `copied: ${token}`;
-        toast.style.display = "block";
-        setTimeout(() => { toast.style.display = "none"; }, 4000);
-      },
-    });
-
-    btn.addEventListener("click", () => {
-      const isActive = btn.classList.toggle("on");
-      picker.setActive(isActive);
-      btn.style.outline = isActive ? "2px solid #ffcc33" : "";
-    });
+    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`.
     const serverUrl = typeof qs.get("pickserver") === "string" && qs.get("pickserver")
       ? qs.get("pickserver") : "http://127.0.0.1:4518";
-    createPickRequestClient({
-      serverUrl,
-      viewer,
-      part,
-      getContext: () => ({ view, params, derived: part.derive ? part.derive({ ...part.defaults, ...params }) : {} }),
-    });
+    createPickRequestClient({ serverUrl, viewer, part, getContext });
   }
 
   let framedView = null; // the view the camera was last framed to (null until first show)
   let cameraRestored = false; // saved camera applied once, on the first frame after load
-  let generating = false;
-  let paramsVersion = 0; // bumped on every settings edit
-  let genVersion = -1;   // the params version the in-flight generate is building
-  let genTimer = null;   // debounce timer for auto-regenerate
-  const cacheHash = {}; // n -> relevance hash each sub-part's cached mesh was built at
 
-  // Memoize the per-sub-part read-key map per (paramsVersion, view): subPartReadKeys
-  // runs probe builds, so we compute it once per change, not per sub-part.
-  let _readsKey = null, _readsMap = null;
-  const readsFor = () => {
-    const key = `${paramsVersion}|${view}`;
-    if (_readsKey !== key) { _readsKey = key; _readsMap = subPartReadKeys(part, view, params); }
-    return _readsMap;
-  };
-  // The relevance hash for one sub-part at the current params (RELEVANT_ALL → hash
-  // over ALL params, so any edit invalidates it — the safe fallback).
-  const hashFor = (n) => {
-    if (!cachingOn) return `v${paramsVersion}`; // caching off: any edit invalidates every sub-part (Layer 1 off)
-    const reads = readsFor();
-    const keys = reads === RELEVANT_ALL ? Object.keys(params) : [...(reads.get(n) ?? Object.keys(params))];
-    return relevanceHash(keys, params);
-  };
-
-  // A cached sub-part is current only if its relevance hash is unchanged.
-  const isCurrent = (n) => !!viewer._subCache[n] && cacheHash[n] === hashFor(n);
-  const missingParts = () => viewSubParts(part, view, params).filter((n) => !isCurrent(n));
+  // Per-sub-part cache-validity tracker (Layer 1): view/version/caching change over
+  // time, so they're passed as getters; params is a stable in-place-mutated object.
+  const cache = createMeshCache(part, viewer, {
+    params,
+    getView: view,
+    getParamsVersion: () => loop.version(),
+    isCaching: () => cachingOn,
+  });
+  const isCurrent = cache.isCurrent;
+  const missingParts = () => viewSubParts(part, view(), params).filter((n) => !isCurrent(n));
+
+  // The regenerate state machine (ready gating / debounce / stale-redo) lives in
+  // regen-loop.js; this send callback is the one place a build job is dispatched.
+  const loop = createRegenLoop({
+    missingParts,
+    send: (missing) => {
+      const needed = viewSubParts(part, view(), params);
+      lastGen = { skipped: needed.length - missing.length, rebuilt: missing.length }; // for the overlay
+      ui.showBusy("generating");
+      service.send({ type: "generate", subparts: missing, view: view(), params, cache: cachingOn }, backendFor());
+    },
+  });
 
   // 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
@@ -158,10 +106,10 @@ export function mount(part, { createWorker, container = document.getElementById(
   // Show the assembly, framing the camera only the first time we show a given view
   // (initial load / tab switch) — never on a regenerate, so zoom/orbit are kept.
   function showView(needed) {
-    const frame = view !== framedView;
+    const frame = view() !== framedView;
     viewer.showAssembly(needed, { frame });
     if (frame) {
-      framedView = view;
+      framedView = view();
       if (!cameraRestored) {
         const cam = loadCamera();
         if (cam) viewer.setCameraState(cam);
@@ -171,87 +119,71 @@ export function mount(part, { createWorker, container = document.getElementById(
   }
 
   function refreshView() {
-    const needed = viewSubParts(part, view, params);
+    const needed = viewSubParts(part, view(), params);
     if (needed.every(isCurrent)) {
       showView(needed);
-      setExportEnabled(true);
-      const tris = needed.reduce((s, n) => s + viewer._subCache[n].userData.triangles, 0);
-      setStatus(`${tris.toLocaleString()} triangles`);
-    } else if (needed.every((n) => viewer._subCache[n])) {
+      ui.setExportEnabled(true);
+      const tris = needed.reduce((s, n) => s + viewer.subTriangles(n), 0);
+      ui.setStatus(`${tris.toLocaleString()} triangles`);
+    } else if (needed.every((n) => viewer.hasSubMesh(n))) {
       showView(needed); // stale but present — keep it visible during regenerate
-      setExportEnabled(false);
+      ui.setExportEnabled(false);
     } else {
       viewer.hideAssembly();
-      setExportEnabled(false);
+      ui.setExportEnabled(false);
     }
   }
 
-  showBusy("booting kernel"); // visible from first paint until the kernel is ready
+  ui.showBusy("booting kernel"); // visible from first paint until the kernel is ready
 
-  // --- download helpers ------------------------------------------------------
-  function triggerDownload(arrayBuffer, filename, mime) {
-    const url = URL.createObjectURL(new Blob([arrayBuffer], { type: mime }));
-    const a = document.createElement("a");
-    a.href = url;
-    a.download = filename;
-    a.click();
-    URL.revokeObjectURL(url);
-  }
-
-  function onDownloadParts({ parts, ext, mime }) {
-    if (parts.length === 1) return triggerDownload(parts[0].data, `${parts[0].name}.${ext}`, mime);
-    const entries = {};
-    for (const p of parts) entries[`${p.name}.${ext}`] = new Uint8Array(p.data);
-    triggerDownload(zipSync(entries, { level: 0 }), `${part.meta?.title ?? "parts"}.zip`.toLowerCase().replace(/\s+/g, "-"), "application/zip");
-  }
+  // Bundle filename for a multi-part export (single parts download under their own name).
+  const zipName = `${part.meta?.title ?? "parts"}.zip`.toLowerCase().replace(/\s+/g, "-");
 
   // --- shared message handler ------------------------------------------------
   function onWorkerMessage({ data }) {
     switch (data.type) {
       case "ready":
-        kernelReady = true;
-        maybeGenerate(); // auto-build the default view (keeps the busy spinner up)
+        loop.ready(); // auto-build the default view (keeps the busy spinner up)
         break;
       case "progress":
-        showBusy(data.phase);
-        setStatus(`${data.phase}…`);
+        ui.showBusy(data.phase);
+        ui.setStatus(`${data.phase}…`);
         break;
       case "meshes": {
-        generating = false;
-        if (genVersion !== paramsVersion) { maybeGenerate(); break; } // changed mid-build → redo
-        for (const m of data.meshes) {
-          if (viewer._subCache[m.name]) { viewer._subCache[m.name].userData.edges?.dispose(); viewer._subCache[m.name].dispose(); }
-          viewer.setSubGeometry(m.name, m);
-          cacheHash[m.name] = hashFor(m.name);
-        }
-        hideBusy();
-        refreshView();
-        if (data.ms && missingParts().length === 0) {
-          setStatus(`${statusEl.textContent} · ${(data.ms / 1000).toFixed(1)} s`);
+        if (loop.buildDone()) { // stale results (params changed mid-build) are discarded
+          for (const m of data.meshes) {
+            viewer.setSubGeometry(m.name, m); // disposes any previous mesh for this name
+            cache.record(m.name);
+          }
+          ui.hideBusy();
+          refreshView();
+          if (data.ms && missingParts().length === 0) {
+            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 });
         }
-        dbg?.update({ ms: data.ms, hits: data.cache?.hits ?? 0, misses: data.cache?.misses ?? 0, skipped: lastGen.skipped, rebuilt: lastGen.rebuilt });
-        maybeGenerate(); // active view may still need parts (tab switched during build)
+        loop.kick(); // stale → rebuild; fresh → the view may still need parts (tab switched mid-build)
         break;
       }
       case "download-parts":
-        hideBusy();
-        onDownloadParts(data);
-        setStatus(`${data.parts.length} part(s) downloaded`);
+        ui.hideBusy();
+        downloadParts(data, zipName);
+        ui.setStatus(`${data.parts.length} part(s) downloaded`);
         break;
       case "download":
-        hideBusy();
+        ui.hideBusy();
         triggerDownload(data.data, data.filename, data.mime);
-        setStatus(`${data.filename} downloaded`);
+        ui.setStatus(`${data.filename} downloaded`);
         break;
       case "needs-occt":
         forcedBackend = "occt"; // probe missed; this part needs OCCT — stick to it
-        generating = false;
-        maybeGenerate();
+        loop.buildDone();
+        loop.kick();
         break;
       case "error":
-        generating = false;
-        hideBusy();
-        setStatus(`failed: ${data.message}`, true);
+        loop.buildDone();
+        ui.hideBusy();
+        ui.setStatus(`failed: ${data.message}`, true);
         refreshView();
         break;
     }
@@ -260,107 +192,38 @@ export function mount(part, { createWorker, container = document.getElementById(
   const service = createGeometryService({ createWorker, onMessage: onWorkerMessage });
 
   const panel = buildControls(controls, part.parameters, params, onParamChange);
-  const updateRelevance = () => panel.applyRelevance(relevantParamKeys(part, view, params));
+  const updateRelevance = () => panel.applyRelevance(relevantParamKeys(part, view(), params));
   updateRelevance(); // initial view
 
   function onParamChange() {
-    paramsVersion++; // every edit invalidates the caches (by version)
-    refreshView();   // keep showing the now-stale mesh (no flicker); disable export
+    loop.markDirty(); // bump the version first: refreshView below must see the parts as stale
+    refreshView();    // keep showing the now-stale mesh (no flicker); disable export
     updateRelevance();
-    scheduleGenerate();
-  }
-
-  // Debounce auto-regeneration so dragging a slider doesn't queue a build per pixel.
-  function scheduleGenerate() {
-    clearTimeout(genTimer);
-    genTimer = setTimeout(maybeGenerate, 180);
-  }
-
-  // Build whatever the active view is missing — automatic, no Generate button.
-  function maybeGenerate() {
-    if (!kernelReady || generating) return; // retried when the current build finishes
-    const needed = viewSubParts(part, view, params);
-    const missing = needed.filter((n) => !isCurrent(n));
-    if (missing.length === 0) return;
-    generating = true;
-    genVersion = paramsVersion;
-    lastGen = { skipped: needed.length - missing.length, rebuilt: missing.length }; // for the overlay
-    showBusy("generating");
-    service.generate({ type: "generate", subparts: missing, view, params, cache: cachingOn }, backendFor());
   }
 
   // Re-run the active view under the current caching setting, so toggling the
   // ?debug switch updates the readout for the same design without a param change.
   function forceRegen() {
-    for (const n of viewSubParts(part, view, params)) delete cacheHash[n];
+    for (const n of viewSubParts(part, view(), params)) cache.forget(n);
     refreshView();
-    maybeGenerate();
+    loop.kick();
   }
 
-  partSeg.addEventListener("click", (e) => {
-    const btn = e.target.closest("button[data-part]");
-    if (!btn) return;
-    view = btn.dataset.part;
-    saveView(view);
-    for (const b of partSeg.children) b.classList.toggle("on", b === btn);
-    refreshView();  // instant if the view's parts are cached + current
-    updateRelevance();
-    maybeGenerate(); // else auto-build the missing pieces
-  });
-
   dlBtn.addEventListener("click", () => {
-    showBusy("exporting STL");
-    service.exportStl({ type: "export-stl", view, params }, backendFor());
+    ui.showBusy("exporting STL");
+    service.send({ type: "export-stl", view: view(), params, quality: "print" }, backendFor());
   });
 
   dlStepBtn.addEventListener("click", () => {
-    showBusy("exporting STEP");
-    service.exportStep({ type: "export-step", view, params });
+    ui.showBusy("exporting STEP");
+    service.send({ type: "export-step", view: view(), params }, "occt"); // STEP is always OCCT
   });
 
   dl3mfBtn?.addEventListener("click", () => {
-    showBusy("exporting 3MF");
-    service.export3mf({ type: "export-3mf", view, params }, backendFor());
+    ui.showBusy("exporting 3MF");
+    service.send({ type: "export-3mf", view: view(), params, quality: "print" }, backendFor());
   });
 
-  // --- viewer controls (optional host-page buttons: #pause / #reframe / #theme) --
-  const pauseBtn = document.getElementById("pause");
-  const reframeBtn = document.getElementById("reframe");
-  const themeBtn = document.getElementById("theme");
-
-  // Theme: toggle the page chrome (CSS vars keyed off <html data-theme>) and the
-  // scene together; remember the choice across reloads.
-  let theme = localStorage.getItem("theme") || "dark";
-  function applyTheme(mode) {
-    theme = mode;
-    document.documentElement.dataset.theme = mode;
-    viewer.setTheme(mode);
-    themeBtn?.classList.toggle("on", mode === "light");
-    localStorage.setItem("theme", mode);
-  }
-  applyTheme(theme);
-  themeBtn?.addEventListener("click", () => applyTheme(theme === "light" ? "dark" : "light"));
-
-  // Pause/resume the idle auto-rotation.
-  let rotating = loadRotating();
-  viewer.setAutoRotate(rotating);
-  if (pauseBtn) {
-    pauseBtn.textContent = rotating ? "⏸" : "▶";
-    pauseBtn.title = rotating ? "Pause rotation" : "Resume rotation";
-  }
-  pauseBtn?.addEventListener("click", () => {
-    rotating = !rotating;
-    viewer.setAutoRotate(rotating);
-    pauseBtn.textContent = rotating ? "⏸" : "▶";
-    pauseBtn.title = rotating ? "Pause rotation" : "Resume rotation";
-    saveRotating(rotating);
-  });
-
-  // Re-fit the camera to the current view.
-  reframeBtn?.addEventListener("click", () => viewer.frame());
-
-  // 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()));
+  // Optional host-page viewer chrome (#pause / #reframe / #theme) + camera persistence.
+  attachViewerControls(viewer);
 }

package/src/framework/param-deps.js

@@ -20,32 +20,23 @@ function recorder(obj, seen) {
 }
 
 export function relevantParamKeys(part, view, params) {
+  // The union of every on-screen sub-part's read set (that's exactly what
+  // subPartReadKeys computes, derive-input folding included)...
+  const reads = subPartReadKeys(part, view, params);
+  if (reads === RELEVANT_ALL) return RELEVANT_ALL; // analysis failed → everything relevant
   try {
     const relevant = new Set();
-
-    // derive: record which raw params feed it; produce real derived values once.
-    const deriveInputs = new Set();
-    const derived = part.derive ? (part.derive(recorder(params, deriveInputs)) ?? {}) : {};
-
-    // gate params: a param read by a view sub-part's enabled() changes what's on screen.
+    for (const keys of reads.values()) for (const k of keys) relevant.add(k);
+    // ...plus the gate params of EVERY in-view sub-part, on or off: toggling one
+    // changes what's on screen, so its enabled() inputs are relevant even when the
+    // sub-part is currently hidden (on-screen ones are already in `reads`).
     for (const name of Object.keys(part.parts)) {
       const sp = part.parts[name];
       if (sp.views.includes(view) && sp.enabled) sp.enabled(recorder(params, relevant));
     }
-
-    // direct build reads across the on-screen (enabled) sub-parts.
-    const { kernel } = createProbeKernel();
-    let anyDerivedRead = false;
-    for (const name of viewSubParts(part, view, params)) {
-      const dSeen = new Set();
-      part.parts[name].build(kernel, recorder(params, relevant), recorder(derived, dSeen));
-      if (dSeen.size > 0) anyDerivedRead = true;
-    }
-    if (anyDerivedRead) for (const k of deriveInputs) relevant.add(k);
-
     return relevant;
   } catch {
-    return RELEVANT_ALL; // couldn't analyze — treat everything as relevant
+    return RELEVANT_ALL;
   }
 }
 

package/src/framework/pick-request/server.js

@@ -58,6 +58,16 @@ export function createPickServer({ port = 4518, timeoutMs = 120000 } = {}) {
       }
       batch = createBatch(body.prompts);
       pending = { res, timer: setTimeout(() => { timeout(batch); finish(); }, timeoutMs) };
+      // A dropped client (Ctrl-C'd CLI) must free the slot immediately, not wedge
+      // every new request behind 409-busy until timeoutMs. Drop `pending` first so
+      // finish() never writes to the dead socket. (This also fires after a normal
+      // finish(), where `pending` is already null — the guard makes it a no-op.)
+      res.on("close", () => {
+        if (pending?.res !== res) return;
+        clearTimeout(pending.timer);
+        pending = null;
+        if (batch) { cancel(batch); finish(); }
+      });
       sse("prompt", view(batch));
       return; // held open until finish()
     }

package/src/framework/regen-loop.js

@@ -0,0 +1,45 @@
+// The auto-regenerate state machine (no DOM, no workers — pure orchestration).
+// mount.js wires it to the geometry service: `missingParts` reports what the
+// active view still needs, `send` dispatches one build job for those parts.
+//
+// Invariants (pinned by test/framework/regen-loop.test.js):
+// - nothing is sent until ready() (the worker announced its kernel);
+// - at most one build is in flight; kicks while generating are absorbed and the
+//   caller re-kicks after buildDone();
+// - markDirty() bumps the params version and debounces a kick, so dragging a
+//   slider queues one build per pause, not one per pixel;
+// - a build that a mid-flight edit outdated is reported stale by buildDone()
+//   (return false → the caller discards the meshes and kicks a rebuild).
+export function createRegenLoop({ missingParts, send, debounceMs = 180 }) {
+  let kernelReady = false;
+  let generating = 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
+    const missing = missingParts();
+    if (missing.length === 0) return;
+    generating = true;
+    genVersion = paramsVersion;
+    send(missing);
+  }
+
+  return {
+    kick,
+    ready() { kernelReady = true; kick(); },
+    markDirty() {
+      paramsVersion++;
+      clearTimeout(timer);
+      timer = setTimeout(kick, debounceMs);
+    },
+    // The build finished (meshes / needs-occt / error). Returns whether its result
+    // is still current; the caller applies the meshes only on true, then kicks.
+    buildDone() {
+      generating = false;
+      return genVersion === paramsVersion;
+    },
+    version: () => paramsVersion,
+  };
+}

package/src/framework/selection/format.js

@@ -9,17 +9,13 @@ const fmtParams = (p) => Object.entries(p).map(([k, v]) => `${k}:${v}`).join(","
 
 function tokenStyle(s) {
   const head = `@${s.subPart}`;
-  const feat = s.feature
-    ? ` · ${s.feature.kind === "cylinder"
-        ? `cyl-face r=${s.feature.radius} axis=${s.feature.axis}`
-        : `${s.feature.kind}-face`}`
-    : "";
+  const feat = s.feature ? ` · ${s.feature.label}` : "";
   return `${head}${feat} · pt(${s.point.join(",")}) n(${fmtNormal(s.normal)}) · {${fmtParams(s.params)}}`;
 }
 
 function promptStyle(s) {
   const params = Object.entries(s.params).map(([k, v]) => `${k}: ${v}`).join(", ");
-  const feat = s.feature ? ` a ${s.feature.kind} face,` : "";
+  const feat = s.feature ? ` **${s.feature.label}**,` : "";
   return `On sub-part **${s.subPart}**, the user pointed at${feat} local point (${s.point.join(", ")}), `
     + `normal ${fmtNormal(s.normal)}, with params {${params}}.`;
 }