partforge 0.6.1 → 0.7.0

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

@@ -0,0 +1,31 @@
+// The backend-shared kernel front. Each backend builds its primitive mapping and
+// returns finishKernel(kernel), which layers on everything that is NOT
+// backend-specific:
+//   - argument validation (previously copy-pasted into both backends);
+//   - default compound-op compositions — a backend only overrides one when it has
+//     a reason to (Manifold's boredCylinder hashes atomically for its solid cache);
+//   - a KernelCapabilityError stub for toSTEP when the backend can't write B-rep.
+// The per-Solid twin of this layer is addSugar() in solid-sugar.js.
+import { KernelCapabilityError } from "./errors.js";
+
+export function finishKernel(k) {
+  const rawPrism = k.prism;
+  k.prism = (pts, h, opts) => {
+    if ((opts?.scaleTop ?? 1) < 0) throw new Error("prism: scaleTop must be ≥ 0");
+    return rawPrism(pts, h, opts);
+  };
+
+  const rawRevolve = k.revolve;
+  k.revolve = (pts, opts) => {
+    for (const [r] of pts) if (r < 0) throw new Error("revolve: profile radius must be ≥ 0");
+    return rawRevolve(pts, opts);
+  };
+
+  // Compound: bored-through cylinder (tool overshoots 2 mm each end for a clean cut).
+  k.boredCylinder ??= ({ od, h, bore }) =>
+    k.cylinder(od / 2, od / 2, h).cut(k.cylinder(bore / 2, bore / 2, h + 4).translate([0, 0, -2]));
+
+  k.toSTEP ??= () => { throw new KernelCapabilityError("toSTEP requires the OCCT backend"); };
+
+  return k;
+}

package/src/framework/geometry/kernel.js

@@ -1,15 +1,48 @@
-// The GeometryKernel contract (documentation). Backends implement the @typedef
-// below. (2-D polygon helpers live in ./polygon.js.)
+// The GeometryKernel contract. The op lists below are DATA, not just docs: the
+// parity tests (test/kernel-contract.test.js and the OCCT twin in
+// test/occt-backend.test.js) assert each backend exposes exactly these ops, so the
+// contract can't silently drift from the implementations — the drift class that
+// once broke the probe kernel (see probe.js). The @typedefs document signatures.
+// (2-D polygon helpers live in ./polygon.js.)
+
+// Ops every backend kernel must implement.
+export const KERNEL_OPS = [
+  "cylinder", "boredCylinder", "sphere", "box", "prism", "revolve",
+  "helixSweptTube", "union", "toSTEP",
+];
+
+// Backend-optional kernel ops: the Manifold cache brackets + WASM lifetime hooks.
+// jobs.js calls all of these via `?.`, so a backend may simply omit them.
+export const KERNEL_OPTIONAL_OPS = [
+  "beginSubPart", "endSubPart", "cacheStats", "resetCacheStats", "cleanup",
+];
+
+// Ops every Solid must implement (including the sugar addSugar() attaches).
+export const SOLID_OPS = [
+  "cut", "cutAll", "intersect", "clone", "label", "boundingBox", "volume",
+  "translate", "rotate", "rotateX", "rotateY", "rotateZ", "rotateAbout", "along", "at",
+  "mirror", "scale", "toMesh", "toSTL", "toIndexedMesh",
+  "fillet", "chamfer", "shell",
+];
+
+// Backend-optional Solid queries: Manifold mesh-topology numbers (measure.js
+// guards with `typeof`); OCCT has no cheap equivalent.
+export const SOLID_OPTIONAL_OPS = ["genus", "isEmpty"];
+
+// Solid ops only OCCT implements natively. Single source of truth: probe.js routes
+// a part to OCCT when its build uses one of these, and the Manifold backend
+// generates its KernelCapabilityError stubs from the same list — adding an op here
+// wires up both automatically.
+export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
 
 /**
- * @typedef {Object} Solid  An opaque handle to a backend solid.
- * @property {string} _hash   content hash (Manifold backend only; drives the worker solid cache)
+ * @typedef {Object} Solid  An opaque handle to a backend solid. `_`-prefixed keys are backend internals.
  * @property {(tool: Solid) => Solid} cut
  * @property {(tools: Solid[]) => Solid} cutAll      batch subtract (backend-optimized)
- * @property {(other: Solid) => Solid} intersect     boolean intersection (Manifold)
+ * @property {(other: Solid) => Solid} intersect     boolean intersection (both backends)
  * @property {() => Solid} clone   independent copy (replicad consumes solids on transform)
+ * @property {(name: string) => Solid} label   name this solid's surface for hover/pick feature attribution (survives transforms + booleans; same name on several solids merges into one feature)
  * @property {() => {min:number[],max:number[],center:number[],size:number[]}} boundingBox   axis-aligned bounds (query)
- * @property {(thickness:number, openFaces:object) => Solid} shell   hollow inward (OCCT only); openFaces selector required
  * @property {(v: number[]) => Solid} translate
  * @property {(deg: number, center: number[], axis: number[]) => Solid} rotate   internal primitive — prefer rotateX/Y/Z / rotateAbout
  * @property {(deg: number) => Solid} rotateX   rotate about world X through the origin
@@ -20,10 +53,16 @@
  * @property {(v:number[]) => Solid} at   place an origin-built solid at point v (alias of translate)
  * @property {(plane: "XY"|"XZ"|"YZ") => Solid} mirror
  * @property {(factor:number, center?:number[]) => Solid} scale   uniform scale about center (default origin)
- * @property {() => number} volume                   solid volume in mm³ (Manifold; used by collision tests)
- * @property {(opts?: {quality?: "preview"|"print"}) => {positions:Float32Array, normals:Float32Array, indices:Uint32Array, triangles:number}} toMesh
+ * @property {() => number} volume                   solid volume in mm³ (both backends; used by collision/overlap tests)
+ * @property {(opts?: {quality?: "preview"|"print"}) => {positions:Float32Array, normals:Float32Array, indices?:Uint32Array, triangles:number, edges?:Float32Array}} toMesh
+ *           `edges` = feature-edge line segments (Manifold); quality is advisory — the Manifold kernel bakes it at creation
  * @property {(opts?: {quality?: "preview"|"print"}) => Promise<ArrayBuffer>} toSTL
- * @property {() => {positions:Float32Array, indices:Uint32Array}} toIndexedMesh   indexed mesh, for 3MF (Manifold)
+ * @property {() => {positions:Float32Array, indices:Uint32Array}} toIndexedMesh   indexed mesh, for 3MF
+ * @property {(radius:number, selector?:object) => Solid} fillet    round edges (OCCT only; Manifold throws KernelCapabilityError)
+ * @property {(distance:number, selector?:object) => Solid} chamfer  bevel edges (OCCT only; Manifold throws KernelCapabilityError)
+ * @property {(thickness:number, openFaces:object) => Solid} shell   hollow inward (OCCT only); openFaces selector required
+ * @property {() => number} [genus]     through-hole count (Manifold only)
+ * @property {() => boolean} [isEmpty]  no geometry at all (Manifold only)
  *
  * @typedef {Object} GeometryKernel
  * @property {(rBottom:number, rTop:number, h:number, opts?:{center?:boolean}) => Solid} cylinder
@@ -34,6 +73,10 @@
  * @property {(points2D:number[][], opts?:{degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube
  * @property {(solids:Solid[]) => Solid} union
- * @property {(named:{name:string,solid:Solid}[]) => Promise<ArrayBuffer>} toSTEP   OCCT only
+ * @property {(named:{name:string,solid:Solid}[]) => Promise<ArrayBuffer>} toSTEP   OCCT only (Manifold throws KernelCapabilityError)
+ * @property {(name:string) => void} [beginSubPart]   open a per-sub-part solid-cache round (Manifold only)
+ * @property {() => void} [endSubPart]                close the cache round (always pair with beginSubPart)
+ * @property {() => {hits:number,misses:number}} [cacheStats]
+ * @property {() => void} [resetCacheStats]
  * @property {() => void} [cleanup]   free per-job WASM objects (Manifold backend); call after each job
  */

package/src/framework/geometry/manifold-backend.js

@@ -1,8 +1,8 @@
 import { helixTube } from "./helix-tube.js";
-import { KernelCapabilityError } from "./errors.js";
 import { h } from "./solid-hash.js";
 import { createSolidCache } from "./solid-cache.js";
 import { addSugar } from "./solid-sugar.js";
+import { finishKernel } from "./kernel-front.js";
 
 const PLANE_NORMAL = { XY: [0, 0, 1], XZ: [0, 1, 0], YZ: [1, 0, 0] };
 // 'preview' = interactive view (fast); 'print' = STL export (high-res, used only
@@ -38,6 +38,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   const unionRaw = (ms) => ms.reduce((a, b) => T(a.add(b))); // track each reduce step
 
   const cache = createSolidCache();
+  const featureLabels = new Map(); // originalID -> label string (grows per label(); tiny)
   // Boundary ops route through cache.lookup; on a miss `make` runs the WASM op,
   // tracks the result, and returns the triple the cache needs to pin/dispose it.
   const cached = (hash, computeM) => cache.lookup(hash, () => {
@@ -49,7 +50,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   // transient mesh handle.
   function meshOut(m, asStl) {
     const g = m.getMesh();
-    const r = asStl ? stlFromMesh(g) : creasedNormals(g, Math.cos((SHARP_ANGLE * Math.PI) / 180));
+    const r = asStl ? stlFromMesh(g) : creasedNormals(g, Math.cos((SHARP_ANGLE * Math.PI) / 180), featureLabels);
     g.delete?.();
     return r;
   }
@@ -79,14 +80,23 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
       () => T(m.subtract(unionRaw(tools.map((t) => t._m))))),
     intersect: (t) => cached(h("intersect", hash, t._hash), () => T(m.intersect(t._m))),
     clone: () => wrap(m, hash),
+    // Name this solid's surface for hover/pick feature attribution. asOriginal()
+    // stamps a fresh originalID that survives transforms and booleans, so every
+    // surviving triangle of this surface can be traced back to the label. The
+    // registry entry lives exactly as long as the cache pins the solid — eviction
+    // disposes both, so the registry can't grow unboundedly across regenerates.
+    label: (name) => {
+      const lh = h("label", hash, name);
+      return cache.lookup(lh, () => {
+        const o = T(m.asOriginal());
+        const id = o.originalID();
+        featureLabels.set(id, name);
+        return { value: wrap(o, lh), pin: o, dispose: () => { featureLabels.delete(id); o.delete?.(); } };
+      });
+    },
     boundingBox: () => {
-      const b = m.boundingBox();           // { min: Vec3, max: Vec3 }
-      const min = [...b.min], max = [...b.max];
-      return {
-        min, max,
-        center: [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2],
-        size: [max[0] - min[0], max[1] - min[1], max[2] - min[2]],
-      };
+      const b = m.boundingBox();           // { min: Vec3, max: Vec3 } — addSugar derives center/size
+      return { min: [...b.min], max: [...b.max] };
     },
     volume: () => m.volume(),
     genus: () => m.genus(),
@@ -101,8 +111,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
       return wrap(T(b.translate(center)), h("rotate", hash, deg, center, axis));
     },
     mirror: (plane) => wrap(T(m.mirror(PLANE_NORMAL[plane])), h("mirror", hash, plane)),
-    scale: (factor, center = [0, 0, 0]) => {
-      if (!(factor > 0)) throw new Error("scale: factor must be > 0");
+    scale: (factor, center) => { // factor validated (and center defaulted) by addSugar
       const a = T(m.translate([-center[0], -center[1], -center[2]]));
       const b = T(a.scale([factor, factor, factor]));
       return wrap(T(b.translate(center)), h("scale", hash, factor, center));
@@ -110,12 +119,9 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     toMesh: () => meshOut(m, false),
     toSTL: () => Promise.resolve(meshOut(m, true)),
     toIndexedMesh: () => indexedMeshOut(m),
-    fillet: () => { throw new KernelCapabilityError("fillet requires the OCCT backend"); },
-    chamfer: () => { throw new KernelCapabilityError("chamfer requires the OCCT backend"); },
-    shell: () => { throw new KernelCapabilityError("shell requires the OCCT backend"); },
   });
 
-  return {
+  return finishKernel({
     cylinder: (rb, rt, h2, { center = false } = {}) =>
       wrap(T(Manifold.cylinder(h2, rb, rt, segs, center)), h("cylinder", rb, rt, h2, center, segs)),
     // Compound op: hashed ATOMICALLY from its own args, so it is a single cache
@@ -134,7 +140,6 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     },
     prism: (pts, height, { twist = 0, scaleTop = 1 } = {}) =>
       cached(h("prism", pts, height, twist, scaleTop, segs), () => {
-        if (scaleTop < 0) throw new Error("prism: scaleTop must be ≥ 0");
         const cs = T(CrossSection.ofPolygons([pts]));
         if (twist === 0 && scaleTop === 1) return T(cs.extrude(height));
         const nDiv = Math.max(1, Math.ceil(Math.abs(twist) / 5));
@@ -144,12 +149,8 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
       }),
     helixSweptTube: (o) => cached(h("helixSweptTube", o, tube), () => T(helixTube(wasm, { ...o, ...tube }))),
     revolve: (pts, { degrees = 360 } = {}) =>
-      cached(h("revolve", pts, degrees, segs), () => {
-        for (const [r] of pts) if (r < 0) throw new Error("revolve: profile radius must be ≥ 0");
-        return T(Manifold.revolve([pts], segs, degrees));
-      }),
+      cached(h("revolve", pts, degrees, segs), () => T(Manifold.revolve([pts], segs, degrees))),
     union: (solids) => cached(h("union", solids.map((s) => s._hash)), () => unionRaw(solids.map((s) => s._m))),
-    toSTEP: () => { throw new Error("STEP export not supported by the Manifold backend"); },
     beginSubPart: (name) => cache.begin(name),
     endSubPart: () => cache.end(),
     cacheStats: () => cache.stats(),
@@ -157,7 +158,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // Free every WASM object created since the last cleanup EXCEPT solids the cache
     // still pins (they must survive for the next build to resume from them).
     cleanup: () => { for (const o of tracked) if (!cache.isPinned(o)) o.delete?.(); tracked.length = 0; },
-  };
+  });
 }
 
 // Build a non-indexed mesh with normals that are smooth within a single original
@@ -166,7 +167,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
 // only over incident triangles of the SAME original surface that also meet within
 // `sharpCos` — so cut seams stay crisp at any angle (even near-tangent), and a
 // surface's own sharp edges (e.g. a face meeting a side) stay crisp too.
-function creasedNormals(g, sharpCos) {
+function creasedNormals(g, sharpCos, featureLabels) {
   const np = g.numProp, vp = g.vertProperties, tris = g.triVerts;
   const nTri = (tris.length / 3) | 0, nVert = (vp.length / np) | 0;
 
@@ -245,7 +246,27 @@ function creasedNormals(g, sharpCos) {
       }
     }
 
-  return { positions, normals, triangles: nTri, edges: Float32Array.from(edges) }; // mesh non-indexed
+  // Per-triangle feature attribution: map each triangle's original-surface id
+  // through the label registry. Same label string → same feature entry, so a
+  // pattern of solids labeled alike reads as one feature.
+  let featureIds = null, features = null;
+  if (featureLabels?.size) {
+    const indexOf = new Map(); // label string -> 1-based feature index
+    features = [];
+    featureIds = new Uint16Array(nTri);
+    for (let t = 0; t < nTri; t++) {
+      const label = featureLabels.get(triOID[t]);
+      if (label === undefined) continue;
+      let fi = indexOf.get(label);
+      if (fi === undefined) { features.push(label); fi = features.length; indexOf.set(label, fi); }
+      featureIds[t] = fi;
+    }
+    if (features.length === 0) { featureIds = features = null; } // labels exist in the kernel, none in THIS mesh
+  }
+
+  const out = { positions, normals, triangles: nTri, edges: Float32Array.from(edges) }; // mesh non-indexed
+  if (featureIds) { out.featureIds = featureIds; out.features = features; }
+  return out;
 }
 
 function stlFromMesh(g) {

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

@@ -4,116 +4,68 @@
 import { toEdgeFinder } from "./edge-selector.js";
 import { toFaceFinder } from "./face-selector.js";
 import { addSugar } from "./solid-sugar.js";
+import { finishKernel } from "./kernel-front.js";
+import { createOcctRepair } from "./occt-repair.js";
+import { classifyFaceGroups } from "./feature-attribution.js";
 const MESH = { preview: { tolerance: 0.1, angularTolerance: 0.5 }, print: { tolerance: 0.01, angularTolerance: 0.1 } };
 
 export function createOcctKernel(replicad) {
   const { makeCylinder, makeBox, makeCircle, makeHelix, assembleWire, genericSweep,
           makeCompound, loft, draw, exportSTEP, measureVolume, makeSphere } = replicad;
 
-  // Is a shape a closed solid? A broken chamfer (one that over-ran and consumed a face)
-  // meshes to an OPEN surface; a valid one is closed. OCCT meshes each face separately,
-  // so weld vertices by position, then a closed solid has every edge shared by exactly
-  // two triangles. (A coarse mesh is enough — this is a topology check.)
-  const isClosedSolid = (shape) => {
-    const m = shape.mesh({ tolerance: 0.3, angularTolerance: 1.0 });
-    const P = m.vertices, T = m.triangles;
-    const id = new Map();
-    const vid = (i) => {
-      const key = Math.round(P[i * 3] * 32) + "," + Math.round(P[i * 3 + 1] * 32) + "," + Math.round(P[i * 3 + 2] * 32);
-      let d = id.get(key); if (d === undefined) { d = id.size; id.set(key, d); } return d;
-    };
-    const edges = new Map();
-    for (let t = 0; t < T.length / 3; t++) {
-      const a = vid(T[t * 3]), b = vid(T[t * 3 + 1]), c = vid(T[t * 3 + 2]);
-      for (const [x, y] of [[a, b], [b, c], [c, a]]) { const e = x < y ? x * 1e7 + y : y * 1e7 + x; edges.set(e, (edges.get(e) || 0) + 1); }
-    }
-    for (const n of edges.values()) if (n !== 2) return false;
-    return true;
-  };
-
-  // The true maximum chamfer for an edge depends on local angles and adjacent features,
-  // which is hard to predict analytically (and OCCT exposes no max-radius query). So
-  // VALIDATE the result instead of guessing: try the requested distance, and if it makes
-  // a closed solid, use it (valid large chamfers — e.g. on a pill — go through). If not,
-  // binary-search the largest distance that does. Discarded attempts are freed so OCCT's
-  // WASM heap doesn't grow across regenerates.
-  const validChamfer = (shape, finderFn, distance) => {
-    if (!(distance > 0)) return shape.clone();
-    const tryAt = (d) => {
-      const probe = shape.clone();
-      let res;
-      try { res = probe.chamfer(d, finderFn); } catch { return null; } // probe consumed by the op
-      if (measureVolume(res) > 0 && isClosedSolid(res)) return res;
-      res.delete?.();
-      return null;
-    };
-    let best = tryAt(distance);
-    if (best) return best;                                   // requested distance is valid
-    let lo = 0, hi = distance, bestD = 0;
-    for (let i = 0; i < 6; i++) {
-      const mid = (lo + hi) / 2;
-      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; }
-    return shape.clone();                                    // nothing valid — skip the chamfer
-  };
+  // Fillet/chamfer/shell failure recovery (skip-on-failure, chamfer binary search) —
+  // see occt-repair.js for the policies and why they differ per op.
+  const { validChamfer, safeOp } = createOcctRepair(measureVolume);
 
-  // Native fillet/chamfer can throw or yield an empty solid for out-of-range radii
-  // or awkward edge interactions — and OCCT's failures aren't monotonic in the
-  // radius (e.g. a radius that equals an adjacent fillet's can fail while larger
-  // ones succeed). Rather than letting the whole part vanish, attempt the op on a
-  // clone and fall back to the original shape (feature skipped) on a throw or empty
-  // result, with a console warning so it's discoverable.
-  const safeOp = (shape, op, label) => {
-    const backup = shape.clone();
-    try {
-      const result = op(shape);
-      if (measureVolume(result) > 0) { backup.delete?.(); return result; }
-      result.delete?.();
-      console.warn(`partforge: ${label} produced an empty solid — feature skipped (radius out of range?)`);
-    } catch (e) {
-      console.warn(`partforge: ${label} failed (${e?.message || e}) — feature skipped`);
-    }
-    return backup;
-  };
+  // Feature labels: each entry snapshots the labeled solid's geometry at the moment
+  // the label applies; transforms move the snapshots along, booleans merge the two
+  // sides' lists. At toMesh() time result faces are classified against the snapshots.
+  const cloneLabels = (ls) => ls.map((l) => ({ label: l.label, snapshot: l.snapshot.clone() }));
+  const mapLabels = (ls, f) => ls.map((l) => ({ label: l.label, snapshot: f(l.snapshot.clone()) }));
 
-  const wrap = (shape) => addSugar({
+  const wrap = (shape, labels = []) => addSugar({
     _s: shape,
-    cut: (t) => wrap(shape.cut(t._s)),
-    cutAll: (tools) => wrap(shape.cut(makeCompound(tools.map((t) => t._s)))),
-    clone: () => wrap(shape.clone()),
+    _labels: labels,
+    label: (name) => wrap(shape, [...labels, { label: name, snapshot: shape.clone() }]),
+    cut: (t) => wrap(shape.cut(t._s), [...cloneLabels(labels), ...cloneLabels(t._labels ?? [])]),
+    cutAll: (tools) => wrap(
+      shape.cut(makeCompound(tools.map((t) => t._s))),
+      [...cloneLabels(labels), ...tools.flatMap((t) => cloneLabels(t._labels ?? []))]
+    ),
+    intersect: (t) => wrap(shape.intersect(t._s), [...cloneLabels(labels), ...cloneLabels(t._labels ?? [])]),
+    clone: () => wrap(shape.clone(), cloneLabels(labels)),
     boundingBox: () => {
-      const bb = shape.boundingBox;        // replicad BoundingBox: .bounds [[min],[max]], .center
-      const [min, max] = bb.bounds;
-      return {
-        min: [...min], max: [...max], center: [...bb.center],
-        size: [max[0] - min[0], max[1] - min[1], max[2] - min[2]],
-      };
-    },
-    translate: (v) => wrap(shape.translate(v)),
-    rotate: (deg, center, axis) => wrap(shape.rotate(deg, center, axis)),
-    mirror: (plane) => wrap(shape.mirror(plane)),
-    scale: (factor, center = [0, 0, 0]) => {
-      if (!(factor > 0)) throw new Error("scale: factor must be > 0");
-      return wrap(shape.scale(factor, center));
+      const [min, max] = shape.boundingBox.bounds; // addSugar derives center/size
+      return { min: [...min], max: [...max] };
     },
+    translate: (v) => wrap(shape.translate(v), mapLabels(labels, (s) => s.translate(v))),
+    rotate: (deg, center, axis) => wrap(shape.rotate(deg, center, axis), mapLabels(labels, (s) => s.rotate(deg, center, axis))),
+    mirror: (plane) => wrap(shape.mirror(plane), mapLabels(labels, (s) => s.mirror(plane))),
+    scale: (factor, center) => wrap(shape.scale(factor, center), mapLabels(labels, (s) => s.scale(factor, center))), // validated/defaulted by addSugar
     toMesh: ({ quality = "preview" } = {}) => {
       const m = shape.mesh(MESH[quality]);
-      return {
+      const out = {
         positions: Float32Array.from(m.vertices),
         normals: new Float32Array(0), // let the main thread crease (matches prior look)
         indices: Uint32Array.from(m.triangles),
         triangles: m.triangles.length / 3,
       };
+      if (labels.length) {
+        const soups = labels.map((l) => {
+          const lm = l.snapshot.clone().mesh(MESH.preview); // clone: mesh() must not disturb the kept snapshot
+          return { label: l.label, vertices: lm.vertices, triangles: lm.triangles };
+        });
+        Object.assign(out, classifyFaceGroups(m, soups));
+      }
+      return out;
     },
     toSTL: ({ quality = "print" } = {}) => shape.blobSTL(MESH[quality]).arrayBuffer(),
-    fillet: (radius, selector) => wrap(safeOp(shape, (sh) => sh.fillet(radius, toEdgeFinder(selector)), `fillet(${radius})`)),
-    chamfer: (distance, selector) => wrap(validChamfer(shape, toEdgeFinder(selector), distance)),
+    fillet: (radius, selector) => wrap(safeOp(shape, (sh) => sh.fillet(radius, toEdgeFinder(selector)), `fillet(${radius})`), cloneLabels(labels)),
+    chamfer: (distance, selector) => wrap(validChamfer(shape, toEdgeFinder(selector), distance), cloneLabels(labels)),
     shell: (thickness, openFaces) => {
       if (openFaces == null) throw new Error("shell: openFaces is required (a fully closed hollow is not supported)");
       // replicad shells inward with a positive thickness in this version, keeping outer dimensions.
-      return wrap(safeOp(shape, (sh) => sh.shell(thickness, toFaceFinder(openFaces)), `shell(${thickness})`));
+      return wrap(safeOp(shape, (sh) => sh.shell(thickness, toFaceFinder(openFaces)), `shell(${thickness})`), cloneLabels(labels));
     },
     volume: () => measureVolume(shape),
     toIndexedMesh: () => {
@@ -131,9 +83,8 @@ export function createOcctKernel(replicad) {
     return wrap(loft([w1, w2]));
   };
 
-  // extrude a 2-D polygon from z=0
+  // extrude a 2-D polygon from z=0 (arguments validated by the kernel front)
   const prism = (pts, h, { twist = 0, scaleTop = 1 } = {}) => {
-    if (scaleTop < 0) throw new Error("prism: scaleTop must be ≥ 0");
     let pen = draw(pts[0]);
     for (let i = 1; i < pts.length; i++) pen = pen.lineTo(pts[i]);
     const sketch = pen.close().sketchOnPlane("XY");
@@ -146,7 +97,6 @@ export function createOcctKernel(replicad) {
 
   // revolve a lathe profile [[r,z],…] around the Z axis (degrees defaults to 360)
   const revolve = (pts, { degrees = 360 } = {}) => {
-    for (const [r] of pts) if (r < 0) throw new Error("revolve: profile radius must be ≥ 0");
     let pen = draw(pts[0]);
     for (let i = 1; i < pts.length; i++) pen = pen.lineTo(pts[i]);
     const sketch = pen.close().sketchOnPlane("XZ");
@@ -162,13 +112,14 @@ export function createOcctKernel(replicad) {
     return wrap(genericSweep(profile, spine, { frenet: true }));
   };
 
-  return {
-    cylinder,
-    boredCylinder: ({ od, h, bore }) =>
-      cylinder(od / 2, od / 2, h).cut(cylinder(bore / 2, bore / 2, h + 4).translate([0, 0, -2])),
+  return finishKernel({
+    cylinder, // boredCylinder: the kernel front's default composition is exactly right here
     box: (min, max) => wrap(makeBox(min, max)), prism, revolve, helixSweptTube,
     sphere: (r) => wrap(makeSphere(r)),
-    union: (solids) => wrap(solids.map((s) => s._s).reduce((a, b) => a.fuse(b))),
+    union: (solids) => wrap(
+      solids.map((s) => s._s).reduce((a, b) => a.fuse(b)),
+      solids.flatMap((s) => cloneLabels(s._labels ?? []))
+    ),
     toSTEP: (named) => exportSTEP(named.map(({ name, solid }) => ({ name, shape: solid._s }))).arrayBuffer(),
-  };
+  });
 }

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

@@ -0,0 +1,83 @@
+// Failure recovery for native OCCT features (fillet/chamfer/shell), extracted from
+// occt-backend.js so the backend reads as a clean contract mapping and the pure
+// mesh-topology logic is unit-testable without booting OCCT.
+//
+// Two deliberately different rescue policies:
+//   - chamfer → validChamfer: try the requested distance, and if it breaks the
+//     solid, binary-search the largest distance that doesn't. An over-large chamfer
+//     fails by over-running its faces, which is (near enough) monotonic in the
+//     distance — so bisection is sound.
+//   - fillet (and shell) → safeOp: attempt once, skip the feature on failure.
+//     OCCT fillet failures are NOT monotonic in the radius (a radius equal to an
+//     adjacent fillet's can fail while larger ones succeed), so a binary search
+//     would converge on garbage; skipping keeps the part alive and warns.
+
+// Is a shape a closed solid? A broken chamfer (one that over-ran and consumed a face)
+// meshes to an OPEN surface; a valid one is closed. OCCT meshes each face separately,
+// so weld vertices by position, then a closed solid has every edge shared by exactly
+// two triangles. (A coarse mesh is enough — this is a topology check.)
+export const isClosedSolid = (shape) => {
+  const m = shape.mesh({ tolerance: 0.3, angularTolerance: 1.0 });
+  const P = m.vertices, T = m.triangles;
+  const id = new Map();
+  const vid = (i) => {
+    const key = Math.round(P[i * 3] * 32) + "," + Math.round(P[i * 3 + 1] * 32) + "," + Math.round(P[i * 3 + 2] * 32);
+    let d = id.get(key); if (d === undefined) { d = id.size; id.set(key, d); } return d;
+  };
+  const edges = new Map();
+  for (let t = 0; t < T.length / 3; t++) {
+    const a = vid(T[t * 3]), b = vid(T[t * 3 + 1]), c = vid(T[t * 3 + 2]);
+    for (const [x, y] of [[a, b], [b, c], [c, a]]) { const e = x < y ? x * 1e7 + y : y * 1e7 + x; edges.set(e, (edges.get(e) || 0) + 1); }
+  }
+  for (const n of edges.values()) if (n !== 2) return false;
+  return true;
+};
+
+export function createOcctRepair(measureVolume) {
+  // The true maximum chamfer for an edge depends on local angles and adjacent features,
+  // which is hard to predict analytically (and OCCT exposes no max-radius query). So
+  // VALIDATE the result instead of guessing: try the requested distance, and if it makes
+  // a closed solid, use it (valid large chamfers — e.g. on a pill — go through). If not,
+  // binary-search the largest distance that does. Discarded attempts are freed so OCCT's
+  // WASM heap doesn't grow across regenerates.
+  const validChamfer = (shape, finderFn, distance) => {
+    if (!(distance > 0)) return shape.clone();
+    const tryAt = (d) => {
+      const probe = shape.clone();
+      let res;
+      try { res = probe.chamfer(d, finderFn); } catch { return null; } // probe consumed by the op
+      if (measureVolume(res) > 0 && isClosedSolid(res)) return res;
+      res.delete?.();
+      return null;
+    };
+    let best = tryAt(distance);
+    if (best) return best;                                   // requested distance is valid
+    let lo = 0, hi = distance, bestD = 0;
+    for (let i = 0; i < 6; i++) {
+      const mid = (lo + hi) / 2;
+      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; }
+    return shape.clone();                                    // nothing valid — skip the chamfer
+  };
+
+  // Native fillet/shell can throw or yield an empty solid for out-of-range radii
+  // or awkward edge interactions. Rather than letting the whole part vanish, attempt
+  // the op on a clone and fall back to the original shape (feature skipped) on a
+  // throw or empty result, with a console warning so it's discoverable.
+  const safeOp = (shape, op, label) => {
+    const backup = shape.clone();
+    try {
+      const result = op(shape);
+      if (measureVolume(result) > 0) { backup.delete?.(); return result; }
+      result.delete?.();
+      console.warn(`partforge: ${label} produced an empty solid — feature skipped (radius out of range?)`);
+    } catch (e) {
+      console.warn(`partforge: ${label} failed (${e?.message || e}) — feature skipped`);
+    }
+    return backup;
+  };
+
+  return { validChamfer, safeOp };
+}

package/src/framework/geometry/probe.js

@@ -1,41 +1,48 @@
 // Geometry-free backend detection. A probe kernel records every op a part's
 // build() invokes (returning chainable no-op proxies, dummy values for queries);
-// if an OCCT-only op was used, the part needs the OCCT backend.
-export const OCCT_ONLY = new Set(["fillet", "chamfer", "shell"]);
+// if an OCCT-only op was used, the part needs the OCCT backend. The op list lives
+// in kernel.js — the same list generates the Manifold backend's throwing stubs.
+import { OCCT_ONLY_OPS } from "./kernel.js";
+
+const OCCT_ONLY = new Set(OCCT_ONLY_OPS);
 
 export function createProbeKernel() {
   const used = new Set();
   const note = (name) => used.add(name);
-  const proxy = {
-    cut() { note("cut"); return proxy; },
-    cutAll() { note("cutAll"); return proxy; },
-    intersect() { note("intersect"); return proxy; },
-    clone() { note("clone"); return proxy; },
-    boundingBox() { note("boundingBox"); return { min: [0, 0, 0], max: [1, 1, 1], center: [0.5, 0.5, 0.5], size: [1, 1, 1] }; },
-    translate() { note("translate"); return proxy; },
-    rotate() { note("rotate"); return proxy; },
-    mirror() { note("mirror"); return proxy; },
-    scale() { note("scale"); return proxy; },
-    fillet() { note("fillet"); return proxy; },
-    chamfer() { note("chamfer"); return proxy; },
-    shell() { note("shell"); return proxy; },
-    volume() { note("volume"); return 1; },
-    toMesh() { note("toMesh"); return { positions: new Float32Array(9), normals: new Float32Array(9), triangles: 1, edges: new Float32Array(0) }; },
-    toSTL() { note("toSTL"); return new ArrayBuffer(0); },
-    toIndexedMesh() { note("toIndexedMesh"); return { positions: new Float32Array(9), indices: new Uint32Array(3) }; },
+
+  // Catch-all proxies: any method records its name and returns the chainable solid
+  // proxy, EXCEPT the queries below, which return realistic dummy values the build may
+  // read. Using a Proxy (rather than a hand-listed allowlist) means new kernel/solid
+  // methods never have to be mirrored here — the probe can't drift out of sync with the
+  // real backends. (That drift previously broke the panel's relevance dimming/hiding when
+  // the build-step vocabulary was added but not taught to the probe.)
+  const solidQueries = {
+    boundingBox: () => ({ min: [0, 0, 0], max: [1, 1, 1], center: [0.5, 0.5, 0.5], size: [1, 1, 1] }),
+    volume: () => 1,
+    toMesh: () => ({ positions: new Float32Array(9), normals: new Float32Array(9), triangles: 1, edges: new Float32Array(0) }),
+    toSTL: () => new ArrayBuffer(0),
+    toIndexedMesh: () => ({ positions: new Float32Array(9), indices: new Uint32Array(3) }),
   };
-  const kernel = {
-    cylinder() { note("cylinder"); return proxy; },
-    boredCylinder() { note("boredCylinder"); return proxy; },
-    sphere() { note("sphere"); return proxy; },
-    box() { note("box"); return proxy; },
-    prism() { note("prism"); return proxy; },
-    revolve() { note("revolve"); return proxy; },
-    helixSweptTube() { note("helixSweptTube"); return proxy; },
-    union() { note("union"); return proxy; },
-    toSTEP() { note("toSTEP"); return Promise.resolve(new ArrayBuffer(0)); },
-    cleanup() {},
+  const kernelQueries = {
+    toSTEP: () => Promise.resolve(new ArrayBuffer(0)),
+    cleanup: () => {},
   };
+
+  // `ignore` keeps the proxy from masquerading as a thenable/internal handle: symbols,
+  // `then` (so it's never await-unwrapped), and `_`-prefixed internals resolve to
+  // undefined rather than a chainable op.
+  const ignore = (key) => typeof key !== "string" || key === "then" || key[0] === "_";
+
+  const opProxy = (queries) => new Proxy({}, {
+    get(_t, key) {
+      if (ignore(key)) return undefined;
+      if (key in queries) return queries[key];
+      return (..._args) => { note(key); return proxy; };
+    },
+  });
+
+  const proxy = opProxy(solidQueries);   // a solid handle: every op chains back to itself
+  const kernel = opProxy(kernelQueries); // factory ops (cylinder/box/prism/…) return a solid
   return { kernel, used };
 }