partforge 0.40.0 → 0.44.0

package/src/framework/mount.js

@@ -11,26 +11,39 @@ import { buildControls } from "./controls.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 { viewSubParts } from "./part-model.js";
 import { resolveDerived } from "./derive.js";
-import { detectBackend } from "./geometry/probe.js";
+import { detectBackend } from "./backend-select.js";
 import { createDebugOverlay } from "./debug-overlay.js";
 import { createRegenLoop } from "./regen-loop.js";
 import { createPoseFastPath } from "./pose-fast-path.js";
 import { createStatusUi } from "./status-ui.js";
 import { createViewTabs } from "./view-tabs.js";
 import { attachPickToggle, attachHoverLabels, attachPicker, formatSelection } from "./selection/index.js";
-import { createPickRequestClient } from "./pick-request/index.js";
+import { createPickRequestClient, resolvePickServerUrl, PICK_SERVER_DEFAULT_URL } from "./pick-request/index.js";
 import { exportablePartNames, partLabel } from "./export-select.js";
-import { createExportController } from "./export-controller.js";
+import { createExportController, backendForFormat } from "./export-controller.js";
+import { attachAnimationControls } from "./animation-controls.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation }) {
   return {
     ready, dispose, setParams,
+    // Part-declared animation playback (spec 2026-08-02): null when the part
+    // declares no animations. { play(name?), pause(), seek(t), stop(), state() }.
+    animation: animation ?? null,
     captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
     captureCurrent: (opts) => viewer.captureCurrent(opts),
+    // Park/unpark the viewer: stops the render loop and frees the drawing
+    // buffer and the cached capture target. For an embedder that hides the
+    // canvas without unmounting it — `visibility: hidden`, an off-screen tab —
+    // where nothing collapses the container and the loop would otherwise run
+    // forever. See the setActive comment in viewer.js for what it costs.
+    setActive: (active) => viewer.setActive(active),
+    // Subscribe to WebGL context loss (returns an unsubscribe), so a host can
+    // say "the 3D view ran out of memory" instead of showing a dead canvas.
+    onContextLost: (listener) => viewer.onContextLost(listener),
     listExportableParts,
     exportParts,
     // Narrow-layout pane selection, for a host that draws its own tab bar
@@ -69,7 +82,7 @@ function createCleanupStack() {
 // mesh-validity cache, and the geometry workers. The app supplies `createWorker(name)`
 // so Vite can bundle the worker (see geometry-service.js).
 //
-// Embedding contract (0.39.0):
+// Embedding contract (0.44.0):
 //   const runtime = mount(part, { createWorker, elements, onBuild, onPick, onDownload });
 //   await runtime.ready;   // first successful build of the default view
 //   runtime.setParams({ openAngle: 45 }); // programmatic edit; pose-only changes apply instantly
@@ -86,6 +99,25 @@ function createCleanupStack() {
 //   runtime.setHostPane("rail");  // narrow layout only: show just the controls
 //                                 // rail ('stage' | 'rail'), suppressing the
 //                                 // built-in tab bar. null hands selection back.
+//   runtime.setActive(false);     // park the viewer: stop the render loop and release
+//                                 // both large GPU allocations (the drawing buffer and
+//                                 // the cached capture target). For a host that hides the
+//                                 // canvas WITHOUT unmounting it (`visibility: hidden`, an
+//                                 // inactive tab) — nothing else can detect that, and the
+//                                 // loop would otherwise render a hidden pane forever.
+//                                 // Captures still work while parked (they re-allocate).
+//                                 // setActive(true) restores it. Safe after dispose().
+//   runtime.animation?.play("open");  // part-declared animation playback: null when the
+//                                 // part declares no animations, else
+//                                 // { play(name?), pause(), seek(t), stop(), state() }.
+//                                 // play() with an unknown name warns and does nothing;
+//                                 // any user/host param edit pauses playback. A part's
+//                                 // `autoplay: true` animation self-starts on first show
+//                                 // and each view switch until the user touches the
+//                                 // transport — no runtime call needed for that part.
+//   const off = runtime.onContextLost(() => …);  // WebGL context loss, i.e. the GPU or the
+//                                 // OS gave up — surface it rather than showing a dead
+//                                 // canvas. Returns an unsubscribe.
 //   runtime.dispose();     // full teardown
 // onBuild fires per completed build, so it does NOT fire for a pose-only edit —
 // those are repaired in the viewer and produce no build at all.
@@ -119,7 +151,6 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       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"),
       cutaway: elements.chrome?.cutaway ?? byId("cutaway"),
@@ -183,7 +214,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // 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 tabsCtl = createViewTabs(els.tabs, part, {
-      onChange: () => { pendingPosed.clear(); cutawayChrome.reset(); refreshView(); updateRelevance(); loop.kick(); },
+      onChange: () => { pendingPosed.clear(); cutawayChrome.reset(); refreshView(); updateRelevance(); loop.kick(); animCtl?.autoplayKick(); },
     });
     cleanup.defer(() => tabsCtl.detach());
     const view = () => tabsCtl.current();
@@ -220,10 +251,17 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       cleanup.defer(() => pickToggle.detach());
     } else if (qs.has("pickserver")) {
       // Agent-driven mode: arm the picker only when the local pick-server asks for a
-      // 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";
-      pickClient = createPickRequestClient({ serverUrl, viewer, part, getContext });
+      // click. `?pickserver&picktoken=<token>` or `?pickserver=http://host:port&picktoken=…`.
+      // The URL is attacker-suppliable (anyone can hand the user a link), so a
+      // non-loopback target is refused rather than honoured — otherwise every click,
+      // with its live parameter values, would stream to a remote host.
+      const serverUrl = resolvePickServerUrl(qs.get("pickserver"), {
+        onReject: (raw) => console.warn(
+          `partforge: ignoring non-loopback ?pickserver=${raw} — using ${PICK_SERVER_DEFAULT_URL}`,
+        ),
+      });
+      const token = qs.get("picktoken") || "";
+      pickClient = createPickRequestClient({ serverUrl, token, viewer, part, getContext });
       cleanup.defer(() => pickClient.detach());
     }
 
@@ -262,9 +300,18 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       params, getView: view, getParamsVersion: () => loop.version(),
     });
 
+    // paramsVersion of the most recent animation-frame apply. It is what lets
+    // the meshes handler tell "stale because playback moved on" (show it — that
+    // IS best-effort playback) from "stale because the user edited" (discard).
+    let lastAnimApplyVersion = -1;
+
     // 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;
+    // First-show autoplay latch: separate from `readySettled`, which the error
+    // branch also settles — a part whose first build fails but whose retry
+    // succeeds still deserves its autoplay.
+    let autoplayKicked = false;
     let resolveReady, rejectReady;
     const ready = new Promise((res, rej) => { resolveReady = res; rejectReady = rej; });
     ready.catch(() => {});
@@ -326,7 +373,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
           ui.setStatus(`${data.phase}…`);
           break;
         case "meshes": {
-          if (loop.buildDone()) { // stale results (params changed mid-build) are discarded
+          const fresh = loop.buildDone();
+          if (fresh) { // 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);
@@ -343,6 +391,26 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
             dbg?.update({ ms: data.ms, hits: data.cache?.hits ?? 0, misses: data.cache?.misses ?? 0, skipped: lastGen.skipped, rebuilt: lastGen.rebuilt, posed: lastGen.posed });
             onBuild?.({ status: "success", ms: data.ms });
             if (!readySettled) { readySettled = true; resolveReady(); }
+            // First-show autoplay: latched separately from `ready`, which the
+            // error branch also settles — a part whose first build fails but
+            // whose retry succeeds still deserves its autoplay.
+            if (!autoplayKicked) { autoplayKicked = true; animCtl?.autoplayKick(); }
+          } else if (lastAnimApplyVersion === loop.version()) {
+            // Stale ONLY because animation frames kept bumping the version:
+            // show the delivered meshes anyway — that IS best-effort playback —
+            // but record NOTHING. Cache and fast-path stamps must describe
+            // geometry built at the live params, and this delivery wasn't; the
+            // fast-path stamp is dropped too, so a later pose-only repair can
+            // never re-pose this newer geometry off an older delivery's stamp.
+            // A user edit mid-play pauses playback and bumps the version WITHOUT
+            // touching lastAnimApplyVersion, so a genuinely user-stale result
+            // fails this test and is discarded exactly as before.
+            for (const m of data.meshes) {
+              viewer.setSubGeometry(m.name, m);
+              fastPath.forget(m.name);
+            }
+            ui.hideBusy();
+            refreshView();
           }
           loop.kick(); // stale → rebuild; fresh → the view may still need parts (tab switched mid-build)
           break;
@@ -385,7 +453,11 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     });
     cleanup.defer(() => exportCtl.dispose("viewer disposed"));
 
-    const panel = buildControls(els.controls, part.parameters, params, onParamChange);
+    let animCtl = null; // assigned below; panel edits must pause active playback
+    const panel = buildControls(els.controls, part.parameters, params, () => {
+      animCtl?.notifyUserEdit();
+      onParamChange();
+    });
     cleanup.defer(() => panel.dispose());
     const updateRelevance = () => panel.applyRelevance(relevantParamKeys(part, view(), params));
     updateRelevance(); // initial view
@@ -394,8 +466,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // forceRegen path: forceRegen() forgets cache stamps WITHOUT bumping the params
     // version, so a repair there would re-stamp everything current off the memoized
     // probe and the forced rebuild would silently no-op.
-    function onParamChange() {
-      loop.markDirty(); // bump the version first: refreshView below must see the parts as stale
+    function onParamChange({ debounce = true } = {}) {
+      loop.markDirty({ debounce }); // bump the version first: refreshView below must see the parts as stale
       // Pose-only edits: re-posed + re-stamped current, no job. Skipped entirely
       // when caching is off — ?debug&nocache is there to measure true uncached
       // rebuilds, which the fast path would otherwise hide.
@@ -412,11 +484,33 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // path as a slider edit: pose-only changes repair synchronously (no worker
     // job, no debounce); geometry changes fall through to the regen loop.
     function setParams(partial) {
+      animCtl?.notifyUserEdit();
       Object.assign(params, partial);
       panel.syncValues(Object.keys(partial));
       onParamChange();
     }
 
+    // Animation-frame param entry point: same change path as setParams, minus
+    // the regen debounce. The explicit kick after repair is what makes playback
+    // best-effort — a pose-only frame finds nothing missing (repair re-stamped
+    // it) and sends no job; a geometry frame dispatches immediately when the
+    // worker is idle and is otherwise absorbed until buildDone re-kicks.
+    function applyAnimationValues(values) {
+      Object.assign(params, values);
+      panel.syncValues(Object.keys(values));
+      onParamChange({ debounce: false });
+      lastAnimApplyVersion = loop.version(); // this version came from playback, not a user edit
+      loop.kick();
+    }
+
+    // Animation transport + driver (no-op null when the part declares none).
+    animCtl = attachAnimationControls(viewer, part, {
+      container: els.viewer,
+      applyValues: applyAnimationValues,
+      getParamValues: (keys) => Object.fromEntries(keys.map((k) => [k, params[k]])),
+    });
+    if (animCtl) cleanup.defer(() => animCtl.detach());
+
     // 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() {
@@ -437,7 +531,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
 
     const onStepClick = () => {
       ui.showBusy("exporting STEP");
-      service.send({ type: "export-step", view: view(), params }, "occt"); // STEP is always OCCT
+      service.send({ type: "export-step", view: view(), params }, backendForFormat("step", backendFor));
     };
     if (els.exports.step) {
       els.exports.step.addEventListener("click", onStepClick);
@@ -453,7 +547,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       cleanup.defer(() => els.exports.threeMf.removeEventListener("click", on3mfClick));
     }
 
-    // Optional host-page viewer chrome (pause / reframe / theme) + camera persistence.
+    // Optional host-page viewer chrome (reframe / theme) + camera persistence.
     const chrome = attachViewerControls(viewer, els.chrome, { tooltip });
     cleanup.defer(() => chrome.detach());
 
@@ -470,6 +564,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       listExportableParts: () =>
         exportablePartNames(part, params).map((name) => ({ name, label: partLabel(part, name) })),
       exportParts: (opts) => exportCtl.exportParts(opts),
+      animation: animCtl?.runtime ?? null,
     });
   } catch (error) {
     try {

package/src/{testing → framework/oracle}/build.js

@@ -1,4 +1,4 @@
-import { viewSubParts, resolveParams, buildPosed } from "../framework/jobs.js";
+import { viewSubParts, resolveParams, buildPosed } from "../part-model.js";
 
 // Build every sub-part of a view in its display (assembly) pose with the given
 // Manifold kernel, returning live solids + copied-out meshes. Mirrors the