partforge 0.60.2 → 0.61.0

package/docs/AUTHORING-PARTS.md

@@ -2058,8 +2058,15 @@ branch that skips it) and the part drops back to Manifold automatically. A zero
 — `fillet(0)`, `chamfer({ d: 0 })` — is the **identity** on both backends (see
 KERNEL-CONTRACT.md), so an unguarded `s.fillet(p.r)` needs no `if (p.r > 0)` wrapper to
 get the fast preview back when the slider hits 0. (`shell` is the exception: `t: 0` is
-degenerate, not identity, so a shell call always routes to OCCT.) Within one build the
-part runs on a single backend — there is no per-op mixing.
+degenerate, not identity, so a shell call always routes to OCCT.)
+
+**Preview routing is per sub-part.** Each sub-part is probed and routed independently, and
+a mixed part's regen fans out to both workers in parallel — a filleted body pays for OCCT
+while a plain lid rebuilds at Manifold speed beside it. This makes it worth isolating a
+CAD-op solid in its own sub-part rather than folding it into a bigger build. Two scopes
+still route whole-part (the max over the sub-parts): **exports** (one STL/STEP/3MF job
+builds everything in one worker) and the **CLI** (a single Node process boots exactly one
+kernel). Within one sub-part's build there is no per-op backend mixing.
 
 **Shading intent.** The kernel decides what shades smooth and where edge lines
 draw — spheres, cylinders and fillets are smooth by construction; boolean cut

package/docs/ERROR-PATTERNS.md

@@ -52,7 +52,7 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 ## probe-routed-to-occt
 
 - **Symptom:** A part builds far slower than expected (preview takes seconds instead of milliseconds), and the worker logs show it running on the `occt` worker.
-- **Cause:** The geometry-free probe runs `build` against a recording proxy (dummy query values), and a **Solid** `fillet`/`chamfer`/`shell` call it reaches — including a branch the real build wouldn't take, since queries return dummies — routes the whole part to OCCT. (`Shape2D.fillet`/`.chamfer` are the shared pure-JS implementation and do **not** route; the probe tracks which handle kind an op ran on. A magnitude that is provably `0` — `fillet(0)`, `chamfer({d: 0})` — is the identity and does not route either, so a fillet param dialed to 0 reverts the part to Manifold with no guard; a magnitude the probe can't prove zero — e.g. computed from a dummy query value — routes conservatively.)
+- **Cause:** The geometry-free probe runs `build` against a recording proxy (dummy query values), and a **Solid** `fillet`/`chamfer`/`shell` call it reaches — including a branch the real build wouldn't take, since queries return dummies — routes that sub-part to OCCT (preview routing is per sub-part; exports and the CLI route the whole part to the max over its sub-parts, since those jobs run in one worker/kernel). (`Shape2D.fillet`/`.chamfer` are the shared pure-JS implementation and do **not** route; the probe tracks which handle kind an op ran on. A magnitude that is provably `0` — `fillet(0)`, `chamfer({d: 0})` — is the identity and does not route either, so a fillet param dialed to 0 reverts the part to Manifold with no guard; a magnitude the probe can't prove zero — e.g. computed from a dummy query value — routes conservatively.)
 - **Fix:** Remove the CAD-only call the probe reaches unnecessarily, or force the backend with `meta.backend: "manifold"` (or `"occt"`). If the rounding is on a 2-D profile, `Shape2D.fillet` before extruding keeps the part on Manifold. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Fillet & chamfer (automatic OCCT backend)". (Routing re-runs with live params on every regen — even after a runtime `needs-occt` reroute, which pins OCCT only until the params next change — so a stale backend choice never outlives a parameter edit.)
 
 ## fillet-chamfer-many-edges-slow

package/docs/KERNEL-CONTRACT.md

@@ -57,10 +57,12 @@ have gone unbuilt for three consecutive rebinds.
 
 `KernelCapabilityError` is a *routing signal*, not a failure: partforge's geometry-free
 probe (`probe.js`) runs `build` against a fake kernel, and any use of an `OCCT_ONLY_OPS`
-op **on a Solid handle** routes the whole part to a B-rep-class kernel (the probe tracks
+op **on a Solid handle** routes the build to a B-rep-class kernel (the probe tracks
 handle kinds, so the same names on a `Shape2D` — shared pure JS, backend-identical — do
-not route). A host with only a core kernel must surface the error ("this part needs a
-B-rep backend") rather than swallow it.
+not route). Routing granularity is a host choice: the in-repo framework routes preview
+builds per sub-part (each sub-part builds wholly on one kernel) and exports/CLI whole-
+part; a single-kernel host routes everything whole-part. A host with only a core kernel
+must surface the error ("this part needs a B-rep backend") rather than swallow it.
 
 ## Global semantics
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.60.2",
+  "version": "0.61.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",

package/src/app-mixed-smoke.js

@@ -0,0 +1,9 @@
+import part from "./parts/mixed-smoke.js";
+import { mount } from "./framework/index.js";
+
+// Dev/CI-only app for the mixed-backend smoke fixture — see parts/mixed-smoke.js.
+// Handle stashed for scripts/check-app.mjs, same as the other smoke apps.
+window.__pfRuntime = mount(part, {
+  createWorker: (name) =>
+    new Worker(new URL("./mixed-smoke-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/framework/backend-select.js

@@ -6,47 +6,82 @@ import { createProbeKernel } from "./geometry/probe.js";
 import { isZeroMagnitudeCadOp } from "./geometry/op-options.js";
 import { resolveDerived } from "./derive.js";
 
-export function detectBackend(part, params = {}) {
-  if (part.meta?.backend) return part.meta.backend;
+/**
+ * Per-sub-part routing: probe each sub-part's build independently and map it to
+ * its own backend, so a mixed part previews its plain sub-parts on fast Manifold
+ * while only the CAD-op ones pay for OCCT. Sub-parts build independently by
+ * construction (buildPosed builds one at a time), which is what makes splitting
+ * them across the two workers sound.
+ */
+export function detectBackends(part, params = {}) {
+  const forced = part.meta?.backend;
   const p = { ...part.defaults, ...params };
   let d = {};
   // A throwing derive must not escape here — this runs on the main thread mid
   // regen (after the busy spinner goes up). Probe with an empty `d`; the worker
   // build hits the same throw and posts a proper error for the UI.
   try { d = resolveDerived(part, p); } catch { /* fall through with d = {} */ }
-  const { kernel, cadCalls } = createProbeKernel();
+  const backends = {};
   for (const name of Object.keys(part.parts)) {
+    if (forced) { backends[name] = forced; continue; }
+    const { kernel, cadCalls } = createProbeKernel();
     try { part.parts[name].build(kernel, p, d); } catch { /* probe miss → capability backstop covers it */ }
+    // cadCalls holds only Solid-handle fillet/chamfer/shell — `Shape2D.fillet`/
+    // `.chamfer` are the shared pure-JS implementation (backend-identical) and must
+    // not drag a sub-part onto OCCT. A provably zero magnitude is the identity (see
+    // KERNEL-CONTRACT.md) and doesn't route either, so a fillet param dialed to 0
+    // drops the sub-part back onto Manifold with no `if (r > 0)` guard in the build.
+    backends[name] = cadCalls.some(({ op, args }) => !isZeroMagnitudeCadOp(op, args))
+      ? "occt"
+      : "manifold";
   }
-  // cadCalls holds only Solid-handle fillet/chamfer/shell — `Shape2D.fillet`/
-  // `.chamfer` are the shared pure-JS implementation (backend-identical) and must
-  // not drag a part onto OCCT. A provably zero magnitude is the identity (see
-  // KERNEL-CONTRACT.md) and doesn't route either, so a fillet param dialed to 0
-  // drops the part back onto Manifold with no `if (r > 0)` guard in the build.
-  for (const { op, args } of cadCalls) {
-    if (!isZeroMagnitudeCadOp(op, args)) return "occt";
-  }
-  return "manifold";
+  return backends;
+}
+
+// Whole-part detection: the max over detectBackends. This is the routing for
+// anything that must build every sub-part in ONE worker — exports (a single
+// STL/STEP/3MF job) and the single-process CLI, which can't mix kernels at all.
+export function detectBackend(part, params = {}) {
+  return Object.values(detectBackends(part, params)).includes("occt") ? "occt" : "manifold";
 }
 
-// The mount-time backend chooser. detectBackend() re-runs per regen with live
+// The mount-time backend chooser. detectBackends() re-runs per regen with live
 // params, so backend choice already follows the parameters in both directions —
 // this wrapper exists for the runtime backstop: when the probe under-detects
 // (a CAD-only call it can't reach — e.g. gated on a real geometry query the
 // probe answers with dummies) the Manifold build throws NEEDS_OCCT and the
 // worker asks for a reroute. That must not pin OCCT for the rest of the session,
 // or turning the OCCT-only feature off never reverts to Manifold. Instead the
-// reroute is latched per params snapshot: the exact params that failed skip the
-// doomed Manifold retry, and ANY param change re-consults the probe. A part the
-// probe chronically under-detects costs one cheap failed Manifold dispatch per
-// param change — the price of automatic reversion.
+// reroute is latched per (sub-part, params snapshot): the exact combination that
+// failed skips the doomed Manifold retry, and ANY param change re-consults the
+// probe. A part the probe chronically under-detects costs one cheap failed
+// Manifold dispatch per param change — the price of automatic reversion.
 export function createBackendPolicy(part, { forced = null } = {}) {
-  let latchedParams = null; // JSON snapshot of the params proven at runtime to need OCCT
+  let latchedParams = null;  // JSON snapshot of the params proven at runtime to need OCCT
+  let latchedNames = null;   // the sub-parts that proved it (null = all of them)
+  const latched = (params, name) =>
+    latchedParams !== null && latchedParams === JSON.stringify(params) &&
+    (latchedNames === null || latchedNames.has(name));
   return {
-    backendFor: (params) => forced
-      ?? (latchedParams !== null && latchedParams === JSON.stringify(params)
-        ? "occt"
-        : detectBackend(part, params)),
-    noteNeedsOcct: (params) => { latchedParams = JSON.stringify(params); },
+    // name → backend for a preview generate; mount groups sub-parts by this.
+    backendsFor(params) {
+      const backends = detectBackends(part, params);
+      for (const name of Object.keys(backends)) {
+        if (forced) backends[name] = forced;
+        else if (latched(params, name)) backends[name] = "occt";
+      }
+      return backends;
+    },
+    // Whole-part max, for jobs that need one worker (exports).
+    backendFor(params) {
+      if (forced) return forced;
+      return Object.values(this.backendsFor(params)).includes("occt") ? "occt" : "manifold";
+    },
+    // `subparts` names the failed job's sub-parts; omitted (an export job, which
+    // doesn't carry them) it latches the whole part for these params.
+    noteNeedsOcct(params, subparts) {
+      latchedParams = JSON.stringify(params);
+      latchedNames = subparts ? new Set(subparts) : null;
+    },
   };
 }

package/src/framework/jobs.js

@@ -244,7 +244,9 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       post({ type: "report", ...report }, match?.map((m) => m.delta.data.buffer) ?? []);
     }
   } catch (err) {
-    if (err?.code === "NEEDS_OCCT") post({ type: "needs-occt", jobId: msg.jobId });
+    // `subparts` (generate jobs only) tells the reroute policy which sub-parts the
+    // failed job covered, so only those latch to OCCT — not the whole part.
+    if (err?.code === "NEEDS_OCCT") post({ type: "needs-occt", jobId: msg.jobId, subparts: msg.subparts });
     else post({ type: "error", message: String(err?.message || err), jobId: msg.jobId });
   } finally {
     kernel.cleanup?.();

package/src/framework/mount.js

@@ -402,6 +402,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
 
     // 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.
+    // Routing is per SUB-part: the missing set splits by backend and each group goes
+    // to its own worker in parallel, so a mixed part previews its plain sub-parts at
+    // Manifold speed while only the filleted ones wait on OCCT. The return value is
+    // the job count — the loop holds the cycle open until every group has replied.
     const loop = createRegenLoop({
       missingParts,
       send: (missing) => {
@@ -410,7 +414,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         lastGen = { skipped: needed.length - missing.length, rebuilt: missing.length, posed: pendingPosed.size };
         pendingPosed.clear(); // consumed — never counted against a second build
         ui.showBusy("generating");
-        service.send({ type: "generate", subparts: missing, view: view(), params, cache: cachingOn }, backendFor());
+        const backends = backendPolicy.backendsFor(params);
+        let jobs = 0;
+        for (const backend of ["manifold", "occt"]) {
+          const subparts = missing.filter((n) => (backends[n] ?? "manifold") === backend);
+          if (subparts.length === 0) continue;
+          service.send({ type: "generate", subparts, view: view(), params, cache: cachingOn }, backend);
+          jobs++;
+        }
+        return jobs;
       },
     });
     cleanup.defer(() => loop.dispose());
@@ -509,7 +521,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
               // delivered, which buildDone() true guarantees is at the live params.
               fastPath.recordDelivered(m.name);
             }
-            ui.hideBusy();
+            // A split dispatch answers in two meshes replies; the busy spinner
+            // stays up until the view has everything (the other worker's job may
+            // still be running — often OCCT, the slow one).
+            if (missingParts().length === 0) ui.hideBusy();
             refreshView();
             if (data.ms && missingParts().length === 0) {
               const tris = viewSubParts(part, view(), params).reduce((s, n) => s + viewer.subTriangles(n), 0);
@@ -517,11 +532,16 @@ 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(); }
+            // ready/autoplay wait for the WHOLE view: a split dispatch delivers in
+            // two replies, and a host acting on `ready` (screenshotting, measuring)
+            // must never see half an assembly.
+            if (missingParts().length === 0) {
+              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 —
@@ -553,10 +573,12 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
           ui.setStatus(`${data.filename} downloaded`);
           break;
         case "needs-occt":
-          // Probe missed for the current params — rebuild on OCCT. The latch is
-          // per params snapshot, so changing params re-consults the probe and the
-          // part can drop back to Manifold when the OCCT-only feature goes away.
-          backendPolicy.noteNeedsOcct(params);
+          // Probe missed for the current params — rebuild the failed job's
+          // sub-parts on OCCT (an export reply has no subparts and latches the
+          // whole part). The latch is per params snapshot, so changing params
+          // re-consults the probe and sub-parts drop back to Manifold when the
+          // OCCT-only feature goes away.
+          backendPolicy.noteNeedsOcct(params, data.subparts);
           loop.buildDone();
           loop.kick();
           break;

package/src/framework/regen-loop.js

@@ -4,8 +4,10 @@
 //
 // 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();
+// - at most one dispatch CYCLE is in flight; kicks while generating are absorbed
+//   and the caller re-kicks after the cycle's last buildDone(). `send` may fan a
+//   dispatch out to several workers (per-sub-part backend routing) and reports
+//   how many jobs it posted; each worker reply is one 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()
@@ -14,19 +16,19 @@
 //   fast-apply path kicks explicitly).
 export function createRegenLoop({ missingParts, send, debounceMs = 180 }) {
   let kernelReady = false;
-  let generating = false;
+  let pending = 0;       // worker replies still owed for the in-flight dispatch cycle
   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 (disposed || !kernelReady || generating) return; // re-kicked when the current build finishes
+    if (disposed || !kernelReady || pending > 0) return; // re-kicked when the current cycle finishes
     const missing = missingParts();
     if (missing.length === 0) return;
-    generating = true;
     genVersion = paramsVersion;
-    send(missing);
+    // A send with no return value is the single-job case (one worker, one reply).
+    pending = send(missing) ?? 1;
   }
 
   return {
@@ -42,10 +44,12 @@ export function createRegenLoop({ missingParts, send, debounceMs = 180 }) {
       clearTimeout(timer);
       if (debounce) 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.
+    // One job of the cycle finished (meshes / needs-occt / error). Returns whether
+    // its result is still current; the caller applies the meshes only on true, then
+    // kicks (a no-op until the cycle's last reply). Guarded decrement: a reply
+    // outside any cycle (an export-triggered needs-occt) must not pre-close the next.
     buildDone() {
-      generating = false;
+      if (pending > 0) pending--;
       return genVersion === paramsVersion;
     },
     version: () => paramsVersion,

package/src/mixed-smoke-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/mixed-smoke.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/src/parts/mixed-smoke.js

@@ -0,0 +1,36 @@
+// CI fixture for per-sub-part backend routing (the mixed-backend twin of
+// text-smoke.js): one filleted sub-part that routes to OCCT next to a plain one
+// that stays on Manifold, so the smoke check exercises a split generate — two
+// workers answering one regen cycle — in a real browser. Dial "Edge fillet" to 0
+// and the whole part drops back to Manifold (zero magnitude is the identity).
+export default {
+  meta: { title: "Mixed smoke", units: "mm" },
+  parameters: [
+    {
+      id: "body",
+      title: "Body",
+      advanced: [
+        { key: "w", label: "Width", unit: "mm", min: 10, max: 60, step: 1 },
+        { key: "r", label: "Edge fillet", unit: "mm", min: 0, max: 5, step: 0.5 },
+      ],
+    },
+  ],
+  defaults: { w: 30, r: 2 },
+  parts: {
+    body: {
+      label: "Body",
+      views: ["assembly"],
+      export: { name: "body" },
+      // Unguarded on purpose: fillet(0) is the identity, so r drives the routing.
+      build: (k, p) => k.box({ min: [0, 0, 0], max: [p.w, p.w, 10] }).fillet({ r: p.r, edges: { dir: "Z" } }),
+    },
+    lid: {
+      label: "Lid",
+      views: ["assembly"],
+      export: { name: "lid" },
+      build: (k, p) => k.box({ min: [0, 0, 0], max: [p.w, p.w, 2] }),
+      place: (s) => s.at([0, 0, 12]),
+    },
+  },
+  views: { assembly: { label: "Assembly" } },
+};