partforge 0.31.0 → 0.33.0

package/src/framework/mount.js

@@ -15,6 +15,7 @@ import { resolveDerived } from "./derive.js";
 import { detectBackend } from "./geometry/probe.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";
@@ -22,8 +23,8 @@ import { createPickRequestClient } from "./pick-request/index.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 }) {
-  return { ready, dispose, captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames) };
+export function makeHandle({ ready, dispose, viewer, setParams }) {
+  return { ready, dispose, setParams, captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames) };
 }
 
 function createCleanupStack() {
@@ -58,7 +59,10 @@ function createCleanupStack() {
 // Embedding contract (0.12.0):
 //   const runtime = mount(part, { createWorker, elements, onBuild, onPick });
 //   await runtime.ready;   // first successful build of the default view
+//   runtime.setParams({ openAngle: 45 }); // programmatic edit; pose-only changes apply instantly
 //   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.
 // 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.
@@ -126,7 +130,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     const qs = new URLSearchParams(location.search);
     const debug = qs.has("debug");
     let cachingOn = !(debug && qs.has("nocache"));
-    let lastGen = { skipped: 0, rebuilt: 0 }; // Layer-1 counts for the most recent generate
+    let lastGen = { skipped: 0, rebuilt: 0, posed: 0 }; // Layer-0/1 counts for the most recent generate
+    // Sub-parts the pose fast path has repaired since the last build was dispatched.
+    // A SET of names, not a running total: a slider drag re-repairs the same
+    // sub-part on every input event, and "247 posed" for a one-sub-part app would
+    // be nonsense. A build dispatched in the SAME dirty cycle takes the count into
+    // its report — a mixed edit re-poses one sub-part and rebuilds another, and the
+    // overlay should say so. Anything that kicks a build for an unrelated reason
+    // (view switch / forceRegen) clears it first, so it can't be miscredited.
+    const pendingPosed = new Set();
     const dbg = debug
       ? createDebugOverlay({ initialCachingOn: cachingOn, onToggle: (on) => { cachingOn = on; forceRegen(); } })
       : null;
@@ -135,7 +147,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: () => { cutawayChrome.reset(); refreshView(); updateRelevance(); loop.kick(); },
+      onChange: () => { pendingPosed.clear(); cutawayChrome.reset(); refreshView(); updateRelevance(); loop.kick(); },
     });
     cleanup.defer(() => tabsCtl.detach());
     const view = () => tabsCtl.current();
@@ -199,13 +211,21 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       missingParts,
       send: (missing) => {
         const needed = viewSubParts(part, view(), params);
-        lastGen = { skipped: needed.length - missing.length, rebuilt: missing.length }; // for the overlay
+        // for the overlay; this build reports the poses repaired in its own cycle.
+        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());
       },
     });
     cleanup.defer(() => loop.dispose());
 
+    // Pose fast path (Layer 0): a param edit that only re-poses a sub-part is
+    // repaired synchronously in the viewer — no debounce, no worker job.
+    const fastPath = createPoseFastPath(part, viewer, cache, {
+      params, getView: view, getParamsVersion: () => loop.version(),
+    });
+
     // 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;
@@ -272,13 +292,17 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
             for (const m of data.meshes) {
               viewer.setSubGeometry(m.name, m); // disposes any previous mesh for this name
               cache.record(m.name);
+              // Stamp the fast path's pose baseline. Only here, inside the
+              // non-stale branch: the stamp must describe the geometry actually
+              // delivered, which buildDone() true guarantees is at the live params.
+              fastPath.recordDelivered(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, posed: lastGen.posed });
             onBuild?.({ status: "success", ms: data.ms });
             if (!readySettled) { readySettled = true; resolveReady(); }
           }
@@ -319,15 +343,37 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     const updateRelevance = () => panel.applyRelevance(relevantParamKeys(part, view(), params));
     updateRelevance(); // initial view
 
+    // The ONLY caller of fastPath.repair(). It must never move into the regen /
+    // 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
+      // 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.
+      const posed = cachingOn ? fastPath.repair() : [];
+      if (posed.length) {
+        for (const name of posed) pendingPosed.add(name);
+        dbg?.update({ posed: pendingPosed.size }); // partial: merges over the last build's numbers
+      }
       refreshView();    // keep showing the now-stale mesh (no flicker); disable export
       updateRelevance();
     }
 
+    // Programmatic param entry point — the animation-system hook. Same change
+    // 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) {
+      Object.assign(params, partial);
+      panel.syncValues(Object.keys(partial));
+      onParamChange();
+    }
+
     // 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() {
+      pendingPosed.clear(); // this rebuild is not the pose edit's — don't credit it
       for (const n of viewSubParts(part, view(), params)) cache.forget(n);
       refreshView();
       loop.kick();
@@ -371,7 +417,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       cleanup.dispose();
     }
 
-    return makeHandle({ ready, dispose, viewer });
+    return makeHandle({ ready, dispose, viewer, setParams });
   } catch (error) {
     try {
       cleanup.dispose();

package/src/framework/pose-fast-path.js

@@ -0,0 +1,49 @@
+// Decision layer of the pose fast path (no DOM, no three.js — viewer/cache are
+// injected). At mesh delivery each subpart is STAMPED with its probe result at
+// the delivered params; on a later edit, a stale subpart whose baseHash is
+// unchanged gets its delivered mesh re-posed in the viewer (delta vs. the
+// delivered pose) and is re-stamped current — no worker job. Everything else
+// falls through to the normal regen loop.
+import { viewSubParts } from "./jobs.js";
+import { probePoses } from "./pose-probe.js";
+import { poseDelta } from "./geometry/pose.js";
+
+export function createPoseFastPath(part, viewer, cache, { params, getView, getParamsVersion }) {
+  const stamps = {}; // name -> probe entry captured when that subpart's mesh was delivered
+
+  // Memoize the probe per (paramsVersion, view) — same discipline as
+  // createMeshCache's readsFor; params is the live in-place-mutated object.
+  let probeKey = null, probeMap = null;
+  const probeFor = () => {
+    const key = `${getParamsVersion()}|${getView()}`;
+    if (probeKey !== key) { probeKey = key; probeMap = probePoses(part, getView(), params); }
+    return probeMap;
+  };
+
+  return {
+    // Stamp a freshly delivered mesh with its probe result at the current params.
+    // (The caller only records on non-stale builds — buildDone() guarantees the
+    // live params are the ones the worker built with.)
+    recordDelivered(name) {
+      stamps[name] = probeFor().get(name);
+    },
+
+    // Re-pose every visible stale subpart whose base geometry is unchanged.
+    // Returns the NAMES repaired (empty = nothing pose-only to do). Names, not a
+    // count: a slider drag repairs the same subpart on every input event, so only
+    // the caller's set union across a drag is a meaningful "how many were posed".
+    repair() {
+      const posed = [];
+      const poses = probeFor();
+      for (const name of viewSubParts(part, getView(), params)) {
+        if (cache.isCurrent(name) || !viewer.hasSubMesh(name)) continue;
+        const now = poses.get(name), was = stamps[name];
+        if (!now?.trusted || !was?.trusted || now.baseHash !== was.baseHash) continue;
+        viewer.setSubPose(name, poseDelta(now.pose, was.pose));
+        cache.record(name); // current again at these params — regen loop sees nothing missing
+        posed.push(name);
+      }
+      return posed;
+    },
+  };
+}

package/src/framework/pose-probe.js

@@ -0,0 +1,139 @@
+// Geometry-free pose probe: run a subpart's build()+place() against a stub kernel
+// whose token solids carry (a) a content-hash chain built with the shared h() and
+// (b) pending rigid pose steps, mirroring the backends' pose-lazy bookkeeping.
+// The fast path compares probe results ACROSS PARAM CHANGES ONLY — probe hashes
+// are never compared to backend hashes, so they only need to be stable and to
+// fold every geometry-affecting argument.
+//
+// Trust model: any query op (boundingBox/volume/…) during a build marks that
+// subpart untrusted — a query result could feed geometry OR pose, and the probe
+// returns dummies, so neither hash stability nor pose values can be believed.
+// A FUNCTION passed as (or nested inside) an op argument is untrusted for the
+// same reason the OCCT backend refuses to hash function selectors (see `selKey`
+// in occt-backend.js): a closure like `(e) => e.inDirection([0,0,p.z])` has the
+// same source text at every value of `p.z`, so hashing it would hold baseHash
+// stable while the real geometry changed — precisely the false-positive the fast
+// path must never make. Untrusted subparts simply take the normal regen path.
+import { h } from "./geometry/solid-hash.js";
+import { addSugar } from "./geometry/solid-sugar.js";
+import { SOLID_OPS, SOLID_OPTIONAL_OPS, SHAPE2D_OPS, OCCT_ONLY_OPS } from "./geometry/kernel.js";
+import { MAX_PROBE_OPS, ProbeRunawayError } from "./geometry/probe.js";
+import { viewSubParts, resolveParams } from "./jobs.js";
+
+const NAN3 = () => [NaN, NaN, NaN];
+
+function makeProbeSession() {
+  const state = { count: 0, queried: false, unhashable: false };
+  const tick = () => { if (++state.count > MAX_PROBE_OPS) throw new ProbeRunawayError(`pose probe exceeded ${MAX_PROBE_OPS} ops`); };
+
+  // Queries return dummies AND poison trust (see module comment).
+  const QUERY_DUMMIES = {
+    boundingBox: () => ({ min: NAN3(), max: NAN3() }), // addSugar derives center/size
+    volume: () => NaN,
+    genus: () => NaN,
+    isEmpty: () => false,
+    area: () => NaN,
+    toRegions: () => [],
+    simple: () => ({ outer: [[NaN, NaN]], holes: [] }),
+    toMesh: () => ({ positions: new Float32Array(9), normals: new Float32Array(0), triangles: 1, edges: new Float32Array(0) }),
+    toSTL: () => new ArrayBuffer(0),
+    toIndexedMesh: () => ({ positions: new Float32Array(9), indices: new Uint32Array(3) }),
+  };
+
+  // Operand tokens fold into a hash key by their own (pose-folded) hash; plain
+  // data canonicalizes via h(). Functions can't be hashed at all (see the module
+  // comment), so they poison trust AND get a per-call unique key — belt and
+  // braces, so the hash can't collide even before the trust check is consulted.
+  //
+  // The walk mirrors h()'s `canon` exactly (array → elements, other object → own
+  // enumerable values), because a function nested inside an options object —
+  // `fillet({ r, edges: (e) => … })`, the normal calling convention — is reached
+  // by canon, not by the top-level argument check.
+  let unhashable = 0;
+  const argKey = (a) => {
+    if (a && a.__poseToken) return a.__folded();
+    if (typeof a === "function") { state.unhashable = true; return `fn#${unhashable++}`; }
+    if (Array.isArray(a)) return a.map(argKey);
+    if (a && typeof a === "object") return Object.fromEntries(Object.keys(a).map((k) => [k, argKey(a[k])]));
+    return a;
+  };
+
+  function token(hash, pose) {
+    const folded = () => (pose.length ? h("posed", hash, pose) : hash);
+    const foldOp = (op) => (...args) => { tick(); return token(h(op, folded(), ...args.map(argKey)), []); };
+    const t = {
+      __poseToken: true,
+      __folded: folded,
+      _hash: hash,
+      _pose: pose,
+      // The rigid vocabulary stays out of the hash: recorded as pending steps,
+      // exactly like the OCCT backend's pose-lazy wrap. All transform sugar
+      // (rotateAbout/along/at/rotateX…) composes onto these via addSugar.
+      translate: (v) => { tick(); return token(hash, [...pose, { t: "translate", v }]); },
+      rotate: (deg, center, axis) => { tick(); return token(hash, [...pose, { t: "rotate", deg, center, axis }]); },
+      clone: () => t, // tokens are immutable — sharing is safe
+      // regions() is a data-returning query in disguise: on a real backend the
+      // scission ARRAY LENGTH is param-dependent data, so a build branching on
+      // `regions().length` could hold baseHash stable while geometry changed.
+      // It therefore poisons trust like any other query; the single token is
+      // still returned so op chains on regions()[0] don't crash mid-probe.
+      regions: () => { tick(); state.queried = true; return [token(h("regions", folded()), [])]; },
+    };
+    for (const [op, dummy] of Object.entries(QUERY_DUMMIES))
+      t[op] = (...a) => { tick(); state.queried = true; return dummy(...a); };
+    // Every other contract op folds pose + args into a fresh hash. Generated from
+    // the kernel-contract lists so new ops can never silently drift out of the probe.
+    for (const op of [...SOLID_OPS, ...SOLID_OPTIONAL_OPS, ...SHAPE2D_OPS, ...OCCT_ONLY_OPS])
+      t[op] ??= foldOp(op);
+    return addSugar(t);
+  }
+
+  // Kernel: catch-all factory — any op makes a fresh token hashed from its args.
+  const kernelQueries = {
+    toSTEP: () => Promise.resolve(new ArrayBuffer(0)),
+    cleanup: () => {}, beginSubPart: () => {}, endSubPart: () => {},
+    cacheStats: () => ({ hits: 0, misses: 0 }), resetCacheStats: () => {},
+  };
+  const ignore = (key) => typeof key !== "string" || key === "then" || key === "toJSON" || key[0] === "_";
+  const kernel = new Proxy({}, {
+    get(_t, key) {
+      if (ignore(key)) return undefined;
+      if (key in kernelQueries) return kernelQueries[key];
+      return (...args) => { tick(); return token(h(key, ...args.map(argKey)), []); };
+    },
+  });
+
+  return { kernel, state };
+}
+
+const finiteVec = (v) => Array.isArray(v) && v.length === 3 && v.every(Number.isFinite);
+const stepsFinite = (steps) => steps.every((st) =>
+  st.t === "translate"
+    ? finiteVec(st.v)
+    : Number.isFinite(st.deg) && finiteVec(st.center) && finiteVec(st.axis));
+
+// Probe every subpart the view shows. Never throws; a failing/queried/weird
+// subpart yields { trusted: false } and the others still probe.
+export function probePoses(part, view, params) {
+  const out = new Map();
+  let resolved;
+  try { resolved = resolveParams(part, params); }
+  catch {
+    for (const name of viewSubParts(part, view, params)) out.set(name, { trusted: false });
+    return out;
+  }
+  const { p, d } = resolved;
+  for (const name of viewSubParts(part, view, params)) {
+    try {
+      const { kernel, state } = makeProbeSession(); // fresh op budget + trust per subpart
+      const sp = part.parts[name];
+      let s = sp.build(kernel, p, d);
+      if (sp.place) s = sp.place(s, { view, purpose: "display", p, d });
+      const ok = s && s.__poseToken && !state.queried && !state.unhashable && stepsFinite(s._pose);
+      out.set(name, ok ? { baseHash: s._hash, pose: s._pose, trusted: true } : { trusted: false });
+    } catch {
+      out.set(name, { trusted: false });
+    }
+  }
+  return out;
+}

package/src/framework/selection/hover.js

@@ -75,9 +75,12 @@ export function attachHoverLabels(
     emptyOverlayGeometry?.dispose();
     emptyOverlayGeometry = null;
     overlay.geometry = geometry;
-    if (overlayParent !== hit.mesh.parent) {
-      hit.mesh.parent.add(overlay);
-      overlayParent = hit.mesh.parent;
+    // Parent to the sub-part mesh, not to the group: the overlay geometry is a
+    // subset of the mesh's own (delivered-frame) vertices, so it must inherit
+    // whatever fast-path pose viewer.setSubPose has written onto that mesh.
+    if (overlayParent !== hit.mesh) {
+      hit.mesh.add(overlay);
+      overlayParent = hit.mesh;
     }
     overlay.visible = true;
   }

package/src/framework/selection/raycast.js

@@ -7,13 +7,25 @@ const raycaster = new THREE.Raycaster();
 const ndc = new THREE.Vector2();
 
 // Invert the mesh's world transform (pivot rotation + per-view recentring) to recover
-// shared-frame CAD coords — the same frame build() models in.
+// shared-frame CAD coords — the same frame build() models in. `worldToLocal` also
+// undoes the mesh's own local matrix, which carries the viewer's fast-path pose
+// (setSubPose), so re-apply that matrix to land in the CURRENT shared frame rather
+// than the frame the delivered mesh was baked in.
 export function worldToSubPartLocal(mesh, world) {
   const v = Array.isArray(world) ? new THREE.Vector3(world[0], world[1], world[2]) : world.clone();
   mesh.worldToLocal(v);
+  v.applyMatrix4(mesh.matrix);
   return [v.x, v.y, v.z];
 }
 
+const _normal = new THREE.Vector3();
+
+// A geometry-frame direction in shared-frame CAD coords (see pointLocal above).
+function normalInSubPartFrame(mesh, normal) {
+  _normal.copy(normal).transformDirection(mesh.matrix);
+  return [_normal.x, _normal.y, _normal.z];
+}
+
 // The feature carried by a mesh triangle, or null (unlabeled / no attribution data).
 export function featureAt(mesh, triIndex) {
   const { featureIds, features } = mesh.geometry.userData;
@@ -38,9 +50,10 @@ export function raycastViewer(viewer, clientX, clientY) {
     triIndex: hit.faceIndex,
     pointWorld: hit.point,
     pointLocal: worldToSubPartLocal(hit.object, hit.point),
-    // face.normal is in the geometry's local frame, which equals the CAD frame here
-    // (the mesh carries no local transform; only its parents rotate/recentre).
-    normalLocal: hit.face ? [hit.face.normal.x, hit.face.normal.y, hit.face.normal.z] : [0, 0, 0],
+    // face.normal is in the geometry's own frame; the mesh's local matrix (identity,
+    // or a rigid fast-path pose) carries it into the shared CAD frame. The pose is
+    // rigid, so rotating the direction by that matrix is exact.
+    normalLocal: hit.face ? normalInSubPartFrame(hit.object, hit.face.normal) : [0, 0, 0],
     feature: featureAt(hit.object, hit.faceIndex),
   };
 }

package/src/framework/viewer.js

@@ -209,6 +209,7 @@ export function createViewer(container, part) {
   const subCache = Object.fromEntries(names.map((n) => [n, null]));
 
   function setSubGeometry(name, payload) {
+    setSubPose(name, null); // fresh worker mesh is baked at current params — clear any fast-path pose
     const prev = subCache[name];
     const next = buildGeometry(payload);
     subCache[name] = next;
@@ -218,17 +219,38 @@ export function createViewer(container, part) {
     if (prev) { prev.userData.edges?.dispose(); prev.dispose(); }
   }
 
+  // Presentational rigid pose for one sub-part (the pose fast path): applied to
+  // the mesh and its edge lines. `null` clears. Column-major mat16 (pose.js /
+  // three.js Matrix4 convention). Never affects exports or geometry — the worker
+  // owns real placement; this only re-poses the delivered mesh.
+  function setSubPose(name, mat16) {
+    for (const obj of [subMesh[name], subLines[name]]) {
+      if (!obj) continue;
+      obj.matrixAutoUpdate = false;
+      if (mat16) obj.matrix.fromArray(mat16);
+      else obj.matrix.identity();
+      obj.matrixWorldNeedsUpdate = true;
+    }
+  }
+
   // Cache queries for the app's regenerate loop (so it never reaches into subCache).
   const hasSubMesh = (name) => !!subCache[name];
   const subTriangles = (name) => subCache[name]?.userData.triangles ?? 0;
 
   // --- show / hide assembly -------------------------------------------------
   const _box = new THREE.Box3();
+  const _posedBox = new THREE.Box3();
 
   // Recentre the assembly on the pivot and frame the camera to the named parts.
+  // Cached bounding boxes are in the delivered mesh's own frame, so any fast-path
+  // pose has to be applied before the union or framing ignores the re-posing.
   function frameTo(visibleNames) {
     _box.makeEmpty();
-    for (const name of visibleNames) if (subCache[name]) _box.union(subCache[name].boundingBox);
+    for (const name of visibleNames) {
+      if (!subCache[name]) continue;
+      _posedBox.copy(subCache[name].boundingBox).applyMatrix4(subMesh[name].matrix);
+      _box.union(_posedBox);
+    }
     if (_box.isEmpty()) return;
     const center = _box.getCenter(new THREE.Vector3());
     partsGroup.position.copy(center).multiplyScalar(-1); // centre assembly on the pivot
@@ -457,6 +479,7 @@ export function createViewer(container, part) {
     showAssembly,
     hideAssembly,
     setSubGeometry,
+    setSubPose,
     hasSubMesh,
     subTriangles,
     frame,

package/src/framework/worker.js

@@ -2,6 +2,12 @@
 // "manifold" (preview + STL) and "occt" (STEP), via the Worker `name` option.
 // Each instance lazily imports only its own backend, so OCCT's ~11 MB WASM loads
 // only in the worker that needs it, and only on first use.
+//
+// runWorker() returns a rebind handle — { setPart(newPart) } — so a host that
+// swaps parts (an embedder, the cloud runner) can keep this worker and its warm
+// kernel instead of tearing it down. The rebind contract (what setPart
+// guarantees about epochs, cache sweeps, and the re-posted ready) is normative
+// in docs/KERNEL-CONTRACT.md.
 import { handle } from "./jobs.js";
 import { lintPart } from "../lint.js";
 
@@ -35,10 +41,19 @@ export function runWorker(part) {
   let manifold = null; // { preview, print }
   let occt = null;
   let booting = null;
+  let current = part; // rebindable via the returned handle's setPart()
+  let epoch = 0;      // bumped per incoming generate and per setPart
+  const queue = [];   // { data, part, epoch } — jobs run against the part current at arrival
+  let pumping = false;
 
   // Manifold is cheap to boot — bring it up eagerly and signal readiness.
   if (backend === "manifold") {
     booting = manifoldKernels().then((m) => { manifold = m; postMessage({ type: "ready" }); });
+    // A failed boot is reported to the host by the first job that awaits `booting`
+    // (the pump's error boundary posts it). This no-op handler only keeps the eager
+    // rejection from surfacing as an unhandled rejection before that job arrives —
+    // `booting` itself still rejects for kernelFor.
+    booting.catch(() => {});
   } else {
     // OCCT boots lazily (its ~11 MB WASM loads on the first job), but the worker can
     // accept jobs as soon as its module graph is up — messages queue in the port.
@@ -48,30 +63,97 @@ export function runWorker(part) {
     postMessage({ type: "ready" });
   }
 
-  self.onmessage = async (e) => {
-    // Lint is geometry-free by construction, so answer it before touching — or
-    // booting — a kernel. handle() in jobs.js takes an already-booted kernel, and
-    // the branches below await that boot, so routing lint through them would drag
-    // in OCCT's ~11 MB WASM to run a check that never calls the kernel at all.
-    if (e.data?.type === "lint") {
-      postMessage({ type: "lint-report", report: lintPart(part, { params: e.data.params }) });
-      return;
-    }
-    let kernel;
+  async function kernelFor(data) {
     if (backend === "manifold") {
       await booting;
       // The sender declares the job's mesh quality; the worker knows nothing about
       // job-type semantics (mount marks STL/3MF exports quality:"print").
-      kernel = e.data.quality === "print" ? manifold.print : manifold.preview;
-    } else {
-      if (!occt) {
-        postMessage({ type: "progress", phase: "loading exact kernel" }); // feedback during cold boot
-        booting = booting ?? occtKernel().then((k) => (occt = k));
-        await booting;
+      return data.quality === "print" ? manifold.print : manifold.preview;
+    }
+    if (!occt) {
+      postMessage({ type: "progress", phase: "loading exact kernel" }); // feedback during cold boot
+      booting = booting ?? occtKernel().then((k) => (occt = k));
+      await booting;
+    }
+    return occt;
+  }
+
+  // Serial pump: exactly one job at a time. Jobs yield between sub-parts
+  // (jobs.js) so newer messages can enqueue — without this queue two handle()
+  // calls could interleave on the same kernel.
+  async function pump() {
+    if (pumping) return;
+    pumping = true;
+    try {
+      while (queue.length) {
+        const job = queue.shift();
+        // Error boundary around the whole body. handle() reports build failures itself,
+        // but kernelFor can reject — a WASM asset that 404s, an OOM during boot — and an
+        // escaping rejection would kill the pump: this job AND everything queued behind
+        // it would be dropped with no reply at all, leaving the host waiting on a message
+        // that never comes until its own timeout fires.
+        try {
+          // A generate superseded while it sat in the queue never builds at all.
+          if (job.epoch !== null && job.epoch !== epoch) continue;
+          const kernel = await kernelFor(job.data);
+          // handle() declares each message's transferables (the big binary buffers).
+          const post = (m, transfer = []) => postMessage(m, transfer);
+          if (job.epoch === null) { await handle(kernel, job.part, job.data, post); continue; }
+          const isStale = () => job.epoch !== epoch;
+          // Post gate. The boundary check cannot catch a generate that goes stale during
+          // its FINAL sub-part — there is no boundary after it — nor a single-sub-part
+          // generate that goes stale once dequeued. Both would otherwise post the OLD
+          // part's meshes after a rebind. Downgrading them to `superseded` keeps the
+          // contract simple: a `meshes` post is current as of the moment it is posted.
+          const gated = (m, transfer = []) =>
+            (m.type === "meshes" && isStale() ? post({ type: "superseded" }) : post(m, transfer));
+          await handle(kernel, job.part, job.data, gated, { isStale });
+        } catch (err) {
+          // Same shape jobs.js posts for a failed build, so hosts need no new branch.
+          postMessage({ type: "error", message: String(err?.message || err) });
+        }
       }
-      kernel = occt;
+    } finally {
+      pumping = false;
     }
-    // handle() declares each message's transferables (the big binary buffers).
-    await handle(kernel, part, e.data, (m, transfer = []) => postMessage(m, transfer));
+  }
+
+  self.onmessage = (e) => {
+    // Lint is geometry-free by construction, so answer it before touching — or
+    // booting — a kernel. handle() in jobs.js takes an already-booted kernel, and
+    // the pump awaits that boot, so routing lint through the queue would drag in
+    // OCCT's ~11 MB WASM to run a check that never calls the kernel at all.
+    if (e.data?.type === "lint") {
+      postMessage({ type: "lint-report", report: lintPart(current, { params: e.data.params }) });
+      return;
+    }
+    // Only generates supersede each other; exports/inspect always run (cancelling
+    // a user's export because an edit landed would be wrong).
+    const supersedes = e.data?.type === "generate";
+    if (supersedes) epoch++;
+    queue.push({ data: e.data, part: current, epoch: supersedes ? epoch : null });
+    void pump();
+  };
+
+  return {
+    // Rebind contract (docs/KERNEL-CONTRACT.md): swap the part, cancel stale
+    // builds, sweep idle cache partitions, and re-post ready so a remounting
+    // host gates its first generate exactly as on a fresh worker.
+    //
+    // Never runs mid-bracket, so the sweep is always safe: setPart runs
+    // synchronously on the worker's own turn, and jobs.js opens and closes each
+    // sub-part's beginSubPart/endSubPart bracket inside a single synchronous
+    // turn (its only awaits are between sub-parts). The serial pump keeps at
+    // most one handle() in flight, so there is no second bracket to land in
+    // either. An in-flight generate sees the bumped epoch at its next sub-part
+    // boundary and stops there.
+    setPart(newPart) {
+      current = newPart;
+      epoch++;
+      manifold?.preview.sweepCache?.();
+      manifold?.print.sweepCache?.();
+      occt?.sweepCache?.();
+      postMessage({ type: "ready" });
+    },
   };
 }