partforge 0.28.0 → 0.32.0

package/src/framework/geometry/rim-bevel.js

@@ -0,0 +1,132 @@
+// Rim bevel for extruded profiles — extrude({ profile, h, bevel }). Composed
+// entirely from existing kernel ops (extrude + loft + intersect/cut) at the
+// backend-shared front, so both backends get identical semantics for free and
+// the probe sees no CAD-only op: a beveled extrusion stays on the fast Manifold
+// backend instead of routing the whole part to OCCT. (OCCT's native chamfer is
+// per-edge; on a many-point profile rim — a gear — one call costs seconds. The
+// loft envelope costs one boolean regardless of point count.)
+//
+// Accepted profiles: point array, arc/curve contour, { outer, holes } region,
+// or a Shape2D (multi-region Shape2Ds bevel each region and union). Curved
+// profiles are MATERIALIZED to point rings first — the loft envelope needs
+// rings in 1:1 point correspondence — so a beveled extrusion is faceted at the
+// sampling LOD even in STEP export (the same fidelity class as loft rings).
+// Arc contours sample at a fixed pure-JS LOD (backend-identical, like hull);
+// a Shape2D materializes via its own backend's toRegions (hull's Shape2D
+// parity class). The body is built from the SAME materialized rings as the
+// envelope — mixing a curve-exact body with a faceted envelope would leave
+// sliver artifacts where the smooth wall crosses the faceted one.
+//
+// Geometry: a 45° bevel, exactly what chamfer({d, edges:{inPlane}}) would cut.
+// The outer rim insets toward the material; a hole's rim flares the other way
+// (the opening is larger at the face). Outer bevels come from intersecting a
+// loft envelope extended 1 mm past both faces (so its end caps never coincide
+// with the extrusion's faces — coincident caps leave sliver-triangle shading
+// artifacts). Hole bevels are separate per-rim flare cutters that meet the
+// hole wall only along a ring (a curve, not a face), keeping the booleans away
+// from coincident-face degeneracies on the B-rep backend.
+import { offsetPolygon } from "./polygon.js";
+import { tessellateProfile } from "./profile.js";
+import { ringArea } from "./shape2d-regions.js";
+
+// Fixed pure-JS sampling LOD for arc/curve contours — hull.js precedent: not a
+// backend's own segment count, so both backends materialize bit-identically.
+const BEVEL_SEGS = 64;
+
+// Normalize `bevel` (number = both rims, {bottom, top} = per rim) and validate
+// against the height. Exported for direct unit testing.
+export function resolveBevel(bevel, h) {
+  let bottom, top;
+  if (typeof bevel === "number") { bottom = bevel; top = bevel; }
+  else if (bevel !== null && typeof bevel === "object") {
+    for (const key of Object.keys(bevel)) if (key !== "bottom" && key !== "top")
+      throw new Error(`extrude: unknown bevel option ${JSON.stringify(key)} (valid: bottom, top)`);
+    bottom = bevel.bottom ?? 0; top = bevel.top ?? 0;
+  } else throw new Error("extrude: bevel must be a number or { bottom?, top? }");
+  if (!(Number.isFinite(bottom) && bottom >= 0) || !(Number.isFinite(top) && top >= 0))
+    throw new Error("extrude: bevel distances must be finite numbers >= 0");
+  if (bottom + top >= h)
+    throw new Error("extrude: bevel must fit the height (bottom + top < h)");
+  return { bottom, top };
+}
+
+// offsetPolygon needs CCW input; toRegions/hand-written holes may wind either
+// way. Tessellated arc contours close back onto their start point — drop that
+// duplicate, or the offset ring's point count never matches and fit() gives up.
+const ccw = (r) => {
+  const [x0, y0] = r[0], [xn, yn] = r[r.length - 1];
+  const ring = Math.abs(x0 - xn) < 1e-9 && Math.abs(y0 - yn) < 1e-9 ? r.slice(0, -1) : r;
+  return ringArea(ring) >= 0 ? ring : [...ring].reverse();
+};
+
+// The largest offset (inset for the outer rim, outset for a hole rim — the sign
+// of `delta`) the ring can take, starting from the requested distance. Narrow
+// features cap the bevel (the same geometric limit OCCT's chamfer hits — see
+// ERROR-PATTERNS.md#chamfer-rescue-bisection), but each attempt here is pure JS
+// on the 2-D outline, not a kernel op, so backing off is effectively free. The
+// loop is deterministic, preserving build purity. `corners: "sharp"` keeps the
+// offset 1:1 with the input points — loft stitching requires every ring to
+// share the profile's exact point count (a mismatch is treated as a failed try).
+const fit = (ring, delta, what) => {
+  const requested = Math.abs(delta), sign = Math.sign(delta);
+  let c = requested;
+  for (;;) {
+    try {
+      const off = offsetPolygon(ring, sign * c, { corners: "sharp" });
+      if (off.length === ring.length) {
+        if (c < requested)
+          console.warn(`partforge: extrude bevel ${requested} exceeds what the ${what} can take — reduced to ${c.toFixed(2)}`);
+        return { ring: off, c };
+      }
+    } catch { /* offset collapsed or self-intersected — try smaller */ }
+    c *= 0.85;
+    if (c < 0.05) {
+      console.warn(`partforge: extrude bevel ${requested} has no valid offset for this ${what} — rim left square`);
+      return null;
+    }
+  }
+};
+
+const outerRings = (outer, h, b, t) => {
+  const rings = [];
+  if (b) rings.push({ polygon: b.ring, z: -1 }, { polygon: b.ring, z: 0 }, { polygon: outer, z: b.c });
+  else rings.push({ polygon: outer, z: -1 });
+  if (t) rings.push({ polygon: outer, z: h - t.c }, { polygon: t.ring, z: h }, { polygon: t.ring, z: h + 1 });
+  else rings.push({ polygon: outer, z: h + 1 });
+  return rings;
+};
+
+const bevelRegion = (k, region, h, bottom, top) => {
+  const outer = ccw(region.outer);
+  const holes = (region.holes ?? []).map(ccw);
+  let s = k.extrude({ profile: holes.length ? { outer, holes } : outer, h });
+  const b = bottom > 0 ? fit(outer, -bottom, "profile") : null;
+  const t = top > 0 ? fit(outer, -top, "profile") : null;
+  if (b || t) s = s.intersect(k.loft({ rings: outerRings(outer, h, b, t) }));
+  const cutters = [];
+  for (const hole of holes) {
+    const hb = bottom > 0 ? fit(hole, bottom, "hole") : null;
+    if (hb) cutters.push(k.loft({ rings: [
+      { polygon: hb.ring, z: -1 }, { polygon: hb.ring, z: 0 }, { polygon: hole, z: hb.c },
+    ] }));
+    const ht = top > 0 ? fit(hole, top, "hole") : null;
+    if (ht) cutters.push(k.loft({ rings: [
+      { polygon: hole, z: h - ht.c }, { polygon: ht.ring, z: h }, { polygon: ht.ring, z: h + 1 },
+    ] }));
+  }
+  return cutters.length ? s.cutAll(cutters) : s;
+};
+
+export function beveledExtrude(k, { profile, h, twist, scaleTop, bevel }) {
+  if (twist !== undefined || scaleTop !== undefined)
+    throw new Error("extrude: bevel cannot combine with twist or scaleTop");
+  const { bottom, top } = resolveBevel(bevel, h);
+  // bevel: 0 must hash identically to the plain call — hand the original
+  // profile straight through (curve-exact on OCCT, no materialization).
+  if (bottom === 0 && top === 0) return k.extrude({ profile, h });
+  const regions = profile != null && typeof profile.toRegions === "function"
+    ? profile.toRegions()
+    : [tessellateProfile(profile, BEVEL_SEGS)];
+  if (regions.length === 0) throw new Error("extrude: bevel profile produced no regions");
+  return regions.map((r) => bevelRegion(k, r, h, bottom, top)).reduce((a, x) => a.union(x));
+}

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,11 +59,14 @@ 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.
-export function mount(part, { createWorker, elements = {}, onBuild, onPick,
+export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload,
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
   const byId = (id) => document.getElementById(id);
@@ -126,7 +130,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick,
     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,
     // 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,
       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,
             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(); }
           }
@@ -287,12 +311,12 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick,
         }
         case "download-parts":
           ui.hideBusy();
-          downloadParts(data, zipName);
+          downloadParts(data, zipName, onDownload);
           ui.setStatus(`${data.parts.length} part(s) downloaded`);
           break;
         case "download":
           ui.hideBusy();
-          triggerDownload(data.data, data.filename, data.mime);
+          triggerDownload(data.data, data.filename, data.mime, onDownload);
           ui.setStatus(`${data.filename} downloaded`);
           break;
         case "needs-occt":
@@ -319,15 +343,37 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick,
     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,
       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,