partforge 0.31.0 → 0.32.0

package/README.md

@@ -128,6 +128,20 @@ so **the rail must be a direct child of the positioned `.pf-shell`** unless
 the host also supplies `elements.shell` to point at the real containing block
 (e.g. when a wrapper div sits between them, as is common in a React layout).
 
+`runtime.setParams(partial)` edits parameters programmatically — the entry point
+for animating a part from host code:
+
+```js
+runtime.setParams({ openAngle: 45 });   // merges into the live params, syncs the panel
+```
+
+The partial is merged into the current params and the control panel updates to
+match. Keys the part doesn't define are silently ignored. When every changed
+parameter only moves geometry (a rotation or translation in `place()`), the
+viewer re-poses the meshes it already has — instantly, with no worker rebuild;
+`onBuild` does not fire for those pose-only edits. Anything that changes the
+geometry itself rebuilds as usual.
+
 `onPick` arms click-to-select permanently: `label` is the feature label (falling
 back to the sub-part label/name) for compact UI, `prompt` is the LLM-ready
 sentence, `token` the compact form, `selection` the raw object. When `onPick` is

package/docs/AUTHORING-PARTS.md

@@ -342,7 +342,9 @@ This holds on **both backends** — and on OCCT, `translate`/`rotate` are additi
 re-running any B-rep work. A parameter that only feeds a final placement rotation (a
 lid's open angle, an exploded-view offset) therefore re-drags in ~0 ms even on the
 slow exact kernel — keep such transforms as the last ops in `build` (or in `place`)
-rather than baking them into the geometry earlier.
+rather than baking them into the geometry earlier. In the app, such pose-only edits
+skip the worker entirely — the viewer re-poses the cached mesh — so they stay smooth
+even at animation rates (see `runtime.setParams`).
 
 ---
 
@@ -1217,6 +1219,63 @@ entirely on OCCT, its fillets are exact in the STEP **and** present in the print
 > `partforge measure` reports `watertight`/`holes` as `n/a` for OCCT parts (Manifold-only
 > topology); `render` works on both.
 
+### Cost: fillet/chamfer scale with edge count — and order matters
+
+OCCT fillet/chamfer cost is **per selected edge**, on top of the OCCT boolean tax the
+routing already imposes on the rest of the part. Two habits keep it tolerable:
+
+- **Fillet/chamfer as early as possible, on the simplest solid.** A fillet on a bare
+  primitive is ~15× cheaper than the same fillet after a dozen boolean cuts have
+  multiplied the face count — and because the solid cache keys each op by its input's
+  content hash, an early fillet is a cache **hit** when a downstream parameter changes,
+  while a fillet-last build re-pays the whole op on every slider step of every parameter.
+- **Never point a rim selector at a many-point extruded profile.** `edges: {inPlane}` on
+  a gear-like extrusion selects *every* polygon edge (hundreds); one chamfer call then
+  costs seconds — and if the distance doesn't fit the tooth lands, the failure-rescue
+  bisection re-runs it ~8× (`ERROR-PATTERNS.md#chamfer-rescue-bisection`). Use the loft
+  bevel below instead.
+
+### Beveling profile rims: extrude's bevel option
+
+For an **extruded profile** (gear, star, bracket outline — any `k.extrude` of a polygon),
+a top/bottom rim bevel doesn't need `chamfer` at all — it's built into `extrude`:
+
+```js
+k.extrude({ profile: prof, h: 5, bevel: 0.6 });                 // 45° bevel, both rims
+k.extrude({ profile: prof, h: 5, bevel: { top: 0.6 } });        // one rim only
+```
+
+Same 45° bevel a rim `chamfer` would cut, but it desugars into extrude + loft +
+intersect at the shared kernel front, so the part **stays on the fast Manifold
+backend** (no CAD-only op for the probe to find) and costs one boolean regardless of
+profile point count. Measured on a 24-tooth involute gear: ~0.1 s on Manifold vs
+~40 s for the equivalent OCCT `chamfer` (576-edge rim × the rescue bisection).
+
+Every profile form works: point arrays, arc profiles, `{outer, holes}` regions
+(hole rims flare outward — the opening is larger at the face, as a chamfer would
+cut it), and `Shape2D` (multi-region shapes bevel each region and union). One
+fidelity caveat: curved profiles are **materialized to point rings** first — the
+loft envelope needs matched points — so a beveled extrusion is faceted at the
+sampling LOD even in STEP export. Arc contours sample at a fixed LOD identically
+on both backends; a `Shape2D` materializes at its own backend's LOD. If you need
+arc-exact STEP walls, that's the one case native `chamfer` still buys you (at
+its OCCT cost).
+
+Rules (throws otherwise — `ERROR-PATTERNS.md#extrude-bevel-invalid`): no
+`twist`/`scaleTop`, and `bottom + top < h` — clamp from your height parameter, e.g.
+`bevel: Math.min(p.chamfer, p.thickness / 2 - 0.2)`. A bevel that would pinch a
+narrow feature shut (a gear's tooth land) is deterministically reduced to the
+largest offset the rim can take, with a console warning
+(`ERROR-PATTERNS.md#extrude-bevel-reduced`).
+
+Under the hood it insets the profile with `offsetPolygon(prof, -c, { corners:
+"sharp" })` and intersects with a loft envelope extended past both faces (so the
+envelope's own end caps never coincide with the extrusion's faces — coincident caps
+leave sliver-triangle shading artifacts). The same construction works by hand when
+you need a variant the option doesn't cover. This bevels a **whole rim**; for
+selective edges on a solid that's already OCCT-routed, plain `chamfer` with a tight
+selector is still the right tool.
+
 ---
 
 ## Conventions & gotchas

package/docs/ERROR-PATTERNS.md

@@ -55,6 +55,34 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 - **Cause:** The geometry-free probe runs `build` against a recording proxy (dummy query values), and a `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.
 - **Fix:** Remove the CAD-only call the probe reaches unnecessarily, or force the backend with `meta.backend: "manifold"` (or `"occt"`). See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Fillet & chamfer (automatic OCCT backend)".
 
+## fillet-chamfer-many-edges-slow
+
+- **Symptom:** A part that fillets or chamfers the rim of an extruded profile (a gear, a star, any many-point polygon) takes many seconds — even tens of seconds — per build, with no error anywhere.
+- **Cause:** OCCT fillet/chamfer cost scales with the number of selected edges, and an `inPlane` rim selector on a many-point extruded profile selects every polygon edge (hundreds for a gear), so one op call costs seconds — and re-runs on every parameter change.
+- **Fix:** Use `extrude`'s `bevel` option instead of `chamfer` — same geometry, stays on the fast Manifold backend. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Beveling profile rims: extrude's bevel option".
+
+## chamfer-rescue-bisection
+
+- **Symptom:** `partforge: chamfer` warning saying the distance `over-ran the geometry — reduced to` a smaller one (or `has no valid distance`), with an attempt count and elapsed seconds, alongside slow builds.
+- **Cause:** The requested chamfer distance doesn't fit the geometry (it over-runs an adjacent face or a short edge), so the failure-rescue bisection in `occt-repair.js` re-runs the full chamfer up to 7 more times to find the largest valid distance — multiplying an already-expensive op by ~8× on every build, since the result is only cached per exact input hash.
+- **Fix:** Lower the chamfer parameter to at most the printed valid distance (the rescue then never fires), clamp it in `build` from the geometry that limits it, or — for extruded profile rims — switch to `extrude`'s `bevel` option, which finds its own limit in pure JS. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Beveling profile rims: extrude's bevel option".
+
+Variant literals under this entry: `partforge: chamfer <d> over-ran the geometry — reduced to <d'> (largest valid; <n> attempts, <t>s — see ERROR-PATTERNS.md#chamfer-rescue-bisection)`, `partforge: chamfer <d> has no valid distance for this geometry — feature skipped (<n> attempts, <t>s — see ERROR-PATTERNS.md#chamfer-rescue-bisection)`.
+
+## extrude-bevel-invalid
+
+- **Symptom:** `extrude: bevel must fit the height (bottom + top < h)` or `extrude: bevel cannot combine with twist or scaleTop` thrown from a build.
+- **Cause:** `extrude`'s `bevel` option desugars into offset-loft envelopes, which need an untwisted straight extrusion and room for both bevels inside the height.
+- **Fix:** Clamp the bevel from the height parameter (e.g. `Math.min(c, h / 2 - 0.2)`) and drop `twist`/`scaleTop`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Beveling profile rims: extrude's bevel option".
+
+Variant literals under this entry: `extrude: unknown bevel option`, `extrude: bevel must be a number or { bottom?, top? }`, `extrude: bevel distances must be finite numbers >= 0`.
+
+## extrude-bevel-reduced
+
+- **Symptom:** `partforge: extrude bevel` warning saying the requested distance `exceeds what the profile can take — reduced to` a smaller one (or `has no valid offset for this profile — rim left square`; `hole` in place of `profile` when a hole's flare is the limit).
+- **Cause:** Offsetting the rim by the bevel distance would pinch a narrow feature (a tooth land, a thin bar, a thin web beside a hole) shut, so the bevel deterministically backs off to the largest offset the outline can take — the same geometric limit OCCT's chamfer hits, resolved in pure JS instead of kernel re-runs.
+- **Fix:** Usually nothing — the reduced bevel is the correct maximum for the geometry. To silence it, clamp the bevel parameter below the printed value or widen the narrow feature.
+
 ## boolean-not-watertight
 
 - **Symptom:** `NOT watertight ✗` from `partforge measure` (non-zero exit) after adding a boolean cut or union.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.31.0",
+  "version": "0.32.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/framework/controls.js

@@ -218,6 +218,7 @@ export function buildControls(root, parameters, params, onDirty) {
   const info = createInfoPopover();
   const controls = []; // { key, el } per control element
   const sections = []; // { el, keys:Set } per rendered section
+  const syncFns = []; // { key, sync } for every widget that can re-read params
   for (const sec of parameters) {
     if (!sectionRenders(sec)) continue;
     const section = el("div", "section");
@@ -225,7 +226,11 @@ export function buildControls(root, parameters, params, onDirty) {
     attachInfo(title, sec.description, info);
     section.append(title);
     const keys = new Set();
-    const register = (key, node) => { controls.push({ key, el: node }); keys.add(key); };
+    const register = (key, node, sync) => {
+      controls.push({ key, el: node });
+      keys.add(key);
+      if (sync) syncFns.push({ key, sync });
+    };
     if (sec.features) buildFeatureSection(section, sec, params, onDirty, register, info);
     else buildPresetSection(section, sec, params, onDirty, register, info);
     root.append(section);
@@ -233,6 +238,12 @@ export function buildControls(root, parameters, params, onDirty) {
   }
   return {
     applyRelevance: (relevant) => applyRelevance(relevant, controls, sections),
+    // Re-read params into the widgets — all of them, or just `keys`. The
+    // programmatic twin of a user edit (setParams); never fires onDirty.
+    syncValues: (keys) => {
+      const only = keys && new Set(keys);
+      for (const { key, sync } of syncFns) if (!only || only.has(key)) sync();
+    },
     dispose: () => { info.dispose(); root.replaceChildren(); },
   };
 }
@@ -263,7 +274,7 @@ function buildPresetSection(section, sec, params, onDirty, register, info) {
     attachInfo(lbl, t.description, info);
     row.append(box, lbl);
     box.addEventListener("change", () => { params[t.key] = box.checked ? (t.on ?? 1) : 0; onDirty?.(); });
-    register(t.key, row);
+    register(t.key, row, () => { box.checked = params[t.key] > 0; });
     section.append(row);
   }
 
@@ -274,8 +285,11 @@ function buildPresetSection(section, sec, params, onDirty, register, info) {
     for (const def of advanced) {
       const s = makeParameterControl(def, params, () => { if (preset) preset.value = "Custom"; onDirty?.(); }, info);
       adv.append(s.wrap);
-      syncs[def.key] = s.sync;
-      register(def.key, s.wrap);
+      syncs[def.key] = s.sync; // raw: preset APPLICATION must not mark itself Custom
+      // A programmatic edit diverges from the preset exactly as a user edit does,
+      // so the picker falls back to Custom — leaving a stale preset name selected
+      // would also make it unre-appliable (no change event for the current option).
+      register(def.key, s.wrap, () => { s.sync(); if (preset) preset.value = "Custom"; });
     }
     section.append(toggle, adv);
   }
@@ -306,7 +320,12 @@ function buildFeatureSection(section, sec, params, onDirty, register, info) {
     const featLabel = el("span", "", feat.label);
     attachInfo(featLabel, feat.description, info);
     checkRow.append(box, featLabel);
-    register(feat.key, checkRow);
+    // `group` is created just below — the sync only ever runs after this
+    // function returns, so the closure is safely bound by then.
+    register(feat.key, checkRow, () => {
+      box.checked = params[feat.key] > 0;
+      group.classList.toggle("hidden", !box.checked);
+    });
 
     const group = el("div", "feat-group");
     const syncs = [];
@@ -314,7 +333,7 @@ function buildFeatureSection(section, sec, params, onDirty, register, info) {
       const s = makeParameterControl(def, params, onDirty, info);
       group.append(s.wrap);
       syncs.push(s.sync);
-      register(def.key, s.wrap);
+      register(def.key, s.wrap, s.sync);
     }
     group.classList.toggle("hidden", !box.checked);
 

package/src/framework/debug-overlay.js

@@ -43,13 +43,21 @@ export function createDebugOverlay({ initialCachingOn = true, onToggle } = {}) {
 
   cb.addEventListener("change", () => onToggle?.(cb.checked));
 
+  // What's currently on screen. update() MERGES over it, so a caller reporting one
+  // figure doesn't blank the others: a pose-only edit ran no build and no L2 ops,
+  // and would otherwise wipe the last build's timing back to "—" on its way to
+  // showing a posed count.
+  const shown = { ms: null, hits: 0, misses: 0, skipped: 0, rebuilt: 0, posed: 0 };
+
   return {
-    update({ ms, hits = 0, misses = 0, skipped = 0, rebuilt = 0 } = {}) {
+    update(counts = {}) {
+      Object.assign(shown, counts);
+      const { ms, hits, misses, skipped, rebuilt, posed } = shown;
       const l2 = cb.checked ? `${hits} hit / ${misses} miss` : "off";
       readout.textContent =
         `build: ${ms != null ? Math.round(ms) + " ms" : "—"}\n` +
         `L2 ops: ${l2}\n` +
-        `L1 parts: ${skipped} skipped / ${rebuilt} rebuilt`;
+        `L1 parts: ${skipped} skipped / ${rebuilt} rebuilt / ${posed} posed`;
     },
     detach: () => box.remove(),
   };

package/src/framework/geometry/kernel-front.js

@@ -25,6 +25,7 @@ const opentype = typeof opentypeNamespace.parse === "function"
 import { KernelCapabilityError } from "./errors.js";
 import { isPlainOptions, KERNEL_OP_SPECS } from "./op-options.js";
 import { textGlyphs } from "./text2d.js";
+import { beveledExtrude } from "./rim-bevel.js";
 import { DEFAULT_FONT_BYTES } from "./fonts/default-font.js";
 import { convexHull, hullPoints } from "./hull.js";
 
@@ -45,6 +46,16 @@ export function finishKernel(k) {
     };
   }
 
+  // extrude({ bevel }) desugars here — before the spec-wrapped op ever sees it —
+  // into extrude + loft + intersect (rim-bevel.js), so both backends share one
+  // implementation and the probe records no CAD-only op. beveledExtrude calls
+  // back into the wrapped k.extrude/k.loft, so caching and validation apply.
+  const specExtrude = k.extrude;
+  k.extrude = (...a) =>
+    a.length === 1 && isPlainOptions(a[0]) && a[0].bevel !== undefined
+      ? beveledExtrude(k, a[0])
+      : specExtrude(...a);
+
   k.toSTEP ??= () => { throw new KernelCapabilityError("toSTEP requires the OCCT backend"); };
   k.shape2d ??= () => { throw new KernelCapabilityError("shape2d requires the Manifold backend"); };
 

package/src/framework/geometry/kernel.js

@@ -99,7 +99,7 @@ export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
  * @property {(o:{r?:number,d?:number}) => Solid} sphere   sphere centred at the origin; {r|d}; bare sphere(r) stays valid
  * @property {(o:{size?:number[],center?:boolean,min?:number[],max?:number[]}) => Solid} box   {size} = centered X/Y, base z=0 ({center:true} centers Z too) or {min,max}; legacy (min,max) accepted until v2
  * @property {(o:{points:number[][],h:number,twist?:number,scaleTop?:number}) => Solid} prism   extrude polygon from z=0; legacy (points,h,opts) accepted until v2
- * @property {(o:{profile:number[][]|{outer:number[][],holes?:number[][][]},h:number,twist?:number,scaleTop?:number}) => Solid} extrude   polygon-with-holes region from z=0; legacy (profile,h,opts) accepted until v2
+ * @property {(o:{profile:number[][]|{outer:number[][],holes?:number[][][]},h:number,twist?:number,scaleTop?:number,bevel?:number|{bottom?:number,top?:number}}) => Solid} extrude   polygon-with-holes region from z=0; bevel = 45° rim bevel (any profile form incl. Shape2D, materialized to point rings; no twist/scaleTop); legacy (profile,h,opts) accepted until v2
  * @property {(o:{rings:{polygon?:number[][],sides?:number,radius?:number,z:number,rotate?:number,scale?:number|number[]}[],ruled?:boolean,closed?:boolean}) => Solid} loft   stack polygon cross-sections; legacy (rings,opts) accepted until v2
  * @property {(o:{profile:number[][],path:number[][],closed?:boolean,cornerRadius?:number,ruled?:boolean,smooth?:boolean}) => Solid} sweep   sweep a 2-D profile along a 3-D polyline; legacy (profile,path,opts) accepted until v2
  * @property {(o:{profile:number[][],degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z; legacy (points,opts) accepted until v2

package/src/framework/geometry/occt-repair.js

@@ -42,7 +42,9 @@ export function createOcctRepair(measureVolume) {
   // WASM heap doesn't grow across regenerates.
   const validChamfer = (shape, finderFn, distance) => {
     if (!(distance > 0)) return shape.clone();
+    let attempts = 0;
     const tryAt = (d) => {
+      attempts++;
       const probe = shape.clone();
       let res;
       try { res = probe.chamfer(d, finderFn); } catch { return null; } // probe consumed by the op
@@ -50,6 +52,7 @@ export function createOcctRepair(measureVolume) {
       res.delete?.();
       return null;
     };
+    const t0 = performance.now();
     let best = tryAt(distance);
     if (best) return best;                                   // requested distance is valid
     let lo = 0, hi = distance, bestD = 0;
@@ -58,7 +61,12 @@ export function createOcctRepair(measureVolume) {
       const res = tryAt(mid);
       if (res) { best?.delete?.(); best = res; bestD = mid; lo = mid; } else hi = mid;
     }
-    if (best) { console.info(`partforge: chamfer ${distance} reduced to ${bestD.toFixed(2)} (largest valid for this geometry)`); return best; }
+    // The rescue re-ran the chamfer per attempt — on a many-edge selection that
+    // multiplies an already-expensive op by ~8x, so make the cost loud enough to
+    // act on (lower the distance, or bevel profile rims with a loft instead).
+    const cost = `${attempts} attempts, ${((performance.now() - t0) / 1000).toFixed(1)}s — see ERROR-PATTERNS.md#chamfer-rescue-bisection`;
+    if (best) { console.warn(`partforge: chamfer ${distance} over-ran the geometry — reduced to ${bestD.toFixed(2)} (largest valid; ${cost})`); return best; }
+    console.warn(`partforge: chamfer ${distance} has no valid distance for this geometry — feature skipped (${cost})`);
     return shape.clone();                                    // nothing valid — skip the chamfer
   };
 

package/src/framework/geometry/op-options.js

@@ -103,7 +103,10 @@ export function prismArgs(o) {
 }
 
 export function extrudeArgs(o) {
-  checkKeys("extrude", o, ["profile", "h", "twist", "scaleTop"]);
+  // `bevel` is accepted here so the validating probe (lint) doesn't flag it, but
+  // it never reaches the positional backend op — kernel-front.js desugars a
+  // bevel call into extrude + loft + intersect before this normalizer runs.
+  checkKeys("extrude", o, ["profile", "h", "twist", "scaleTop", "bevel"]);
   return [req("extrude", o, "profile"), req("extrude", o, "h"), ...tail(o, ["twist", "scaleTop"])];
 }
 

package/src/framework/geometry/pose.js

@@ -3,11 +3,16 @@
 // the underlying B-rep shape; composePose folds them (in application order) into
 // one column-major mat4, and transformPositions re-poses a cached tessellation's
 // vertices with it. Pure JS — unit-testable without booting a kernel.
+//
+// The same math backs the viewer's pose fast path: when a param change only
+// moves a sub-part, `poseDelta` (via `invertRigid`) gives the matrix carrying an
+// already-delivered mesh from the pose it was built at to the new one, so the
+// viewer re-poses instead of rebuilding.
 
 const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
 
 // column-major 4x4 product: (A·B)[c][r] = Σk A[k][r]·B[c][k]
-function mul(A, B) {
+function mulMat4(A, B) {
   const o = new Array(16);
   for (let c = 0; c < 4; c++)
     for (let r = 0; r < 4; r++)
@@ -28,13 +33,13 @@ function rotationAbout(deg, center, axis) {
     x * z * C + y * s, y * z * C - x * s, c + z * z * C, 0,
     0, 0, 0, 1,
   ];
-  return mul(translation(center), mul(R, translation([-center[0], -center[1], -center[2]])));
+  return mulMat4(translation(center), mulMat4(R, translation([-center[0], -center[1], -center[2]])));
 }
 
 const stepMatrix = (s) => (s.t === "translate" ? translation(s.v) : rotationAbout(s.deg, s.center, s.axis));
 
 // Fold steps so the EARLIEST step applies first: p' = Mn · … · M1 · p.
-export const composePose = (steps) => steps.reduce((m, s) => mul(stepMatrix(s), m), IDENTITY);
+export const composePose = (steps) => steps.reduce((m, s) => mulMat4(stepMatrix(s), m), IDENTITY);
 
 // Apply a mat4 to an interleaved xyz Float32Array in place.
 export function transformPositions(positions, m) {
@@ -45,3 +50,30 @@ export function transformPositions(positions, m) {
     positions[i + 2] = m[2] * x + m[6] * y + m[10] * z + m[14];
   }
 }
+
+// Invert a rigid mat4 (rotation + translation only): Rᵀ, t' = −Rᵀ·t. Valid only
+// for matrices produced by composePose — transposing the 3x3 block inverts a
+// rotation, so any scale or shear in it yields garbage rather than an inverse.
+export function invertRigid(m) {
+  const r0 = m[0], r1 = m[1], r2 = m[2],
+        r4 = m[4], r5 = m[5], r6 = m[6],
+        r8 = m[8], r9 = m[9], r10 = m[10],
+        tx = m[12], ty = m[13], tz = m[14];
+  return [
+    r0, r4, r8, 0,
+    r1, r5, r9, 0,
+    r2, r6, r10, 0,
+    -(r0 * tx + r1 * ty + r2 * tz),
+    -(r4 * tx + r5 * ty + r6 * tz),
+    -(r8 * tx + r9 * ty + r10 * tz),
+    1,
+  ];
+}
+
+// The matrix that carries a mesh delivered at `oldSteps` to the pose `newSteps`:
+// compose(new) · compose(old)⁻¹. Both step lists come from the pose probe.
+export const poseDelta = (newSteps, oldSteps) => {
+  const target = composePose(newSteps);
+  const inv = invertRigid(composePose(oldSteps));
+  return mulMat4(target, inv);
+};

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,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,