partforge 0.60.0 → 0.60.2

package/docs/AUTHORING-PARTS.md

@@ -2052,6 +2052,15 @@ OCCT: rounding a profile before extruding keeps you on fast Manifold. Force the
 `meta.backend: "occt" | "manifold"` if you ever need to. Because an OCCT part is built
 entirely on OCCT, its fillets are exact in the STEP **and** present in the printed STL.
 
+The probe re-runs with the **live parameters on every regen**, and routing works in both
+directions: turn a fillet on and the part moves to OCCT; dial it back to 0 (or take the
+branch that skips it) and the part drops back to Manifold automatically. A zero magnitude
+— `fillet(0)`, `chamfer({ d: 0 })` — is the **identity** on both backends (see
+KERNEL-CONTRACT.md), so an unguarded `s.fillet(p.r)` needs no `if (p.r > 0)` wrapper to
+get the fast preview back when the slider hits 0. (`shell` is the exception: `t: 0` is
+degenerate, not identity, so a shell call always routes to OCCT.) Within one build the
+part runs on a single backend — there is no per-op mixing.
+
 **Shading intent.** The kernel decides what shades smooth and where edge lines
 draw — spheres, cylinders and fillets are smooth by construction; boolean cut
 seams always shade hard and draw a line; a loft's facets shade flat when its

package/docs/ERROR-PATTERNS.md

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

package/docs/KERNEL-CONTRACT.md

@@ -33,10 +33,16 @@ carries the conformance semantics and that one the usage guidance;
 **Core class.** A conforming core kernel implements every op in `KERNEL_OPS` and
 every `Solid` op in `SOLID_OPS`, *except* that the B-rep ops (`fillet`, `chamfer`,
 `shell` — the `OCCT_ONLY_OPS` list — and `toSTEP`) may instead throw
-`KernelCapabilityError`. The in-repo Manifold backend is the reference core kernel.
-Kernels built from this repo get the stubs for free: `addSugar()` generates the
-Solid-level stubs from `OCCT_ONLY_OPS`, and `finishKernel()` stubs `toSTEP` (a
-kernel-level op, so it is not in that Solid-op list).
+`KernelCapabilityError`. Exception to the exception: `fillet(0)` / `chamfer({d: 0})`
+(a magnitude that is exactly the number `0`, either calling convention) is the
+**identity** on every class — it returns the solid unchanged and must not throw, so a
+parametric radius dialed to 0 builds on a core kernel with no guard in the part.
+`shell` has no identity form (`t: 0` means zero-thickness walls — degenerate, not
+identity) and always throws on core. The in-repo Manifold backend is the reference
+core kernel. Kernels built from this repo get the stubs for free: `addSugar()`
+generates the Solid-level stubs (including the zero-magnitude identity) from
+`OCCT_ONLY_OPS`, and `finishKernel()` stubs `toSTEP` (a kernel-level op, so it is
+not in that Solid-op list).
 
 **B-rep class.** Core plus native `fillet`/`chamfer`/`shell` and `toSTEP`. The in-repo
 OCCT/replicad backend is the reference.
@@ -266,7 +272,7 @@ Normative signatures: `kernel.js`'s `@typedef Solid`.
 | `toMesh({quality?})` | Render mesh: `{positions, normals, indices?, triangles, edges?, featureIds?, features?}`. `indices` optional (a backend may emit soup or indexed); `normals` and `edges` are authoritative shading intent from both backends — see [Shading intent](#shading-intent-tomesh-normals-and-edges) below; `featureIds`/`features` are optional metadata. |
 | `toSTL({quality?})` | `Promise<ArrayBuffer>`, binary STL, outward CCW winding. Stored facet normals may be zero — slicers recompute them (the mesh backend happens to write them). |
 | `toIndexedMesh({quality?})` | `{positions, indices}` indexed mesh (3MF path); defaults to `"print"` like `toSTL`. Coincident vertices need NOT be welded — the 3MF writer welds, because that format reads topology from the indices rather than re-stitching soup by position the way an STL consumer does. |
-| `fillet(r)` · `fillet({r, edges?})` / `chamfer(d)` · `chamfer({d, edges?})` / `shell({t, open})` | B-rep class (core throws `KernelCapabilityError`). Scalar `fillet(3)`/`chamfer(1)` acts on all edges; the options form adds an `edges` selector. `shell` hollows inward, keeping outer dimensions; `open` (face selector) is required. |
+| `fillet(r)` · `fillet({r, edges?})` / `chamfer(d)` · `chamfer({d, edges?})` / `shell({t, open})` | B-rep class (core throws `KernelCapabilityError`), *except* a zero magnitude — `fillet(0)` / `chamfer({d: 0})` — which is the identity on every class (returns the solid unchanged, never throws; `shell` excluded, `t: 0` is degenerate). Scalar `fillet(3)`/`chamfer(1)` acts on all edges; the options form adds an `edges` selector. `shell` hollows inward, keeping outer dimensions; `open` (face selector) is required. |
 
 `quality` (`"preview"` | `"print"`) is **advisory**: it trades tessellation density for
 speed and a backend may bake it at kernel creation (Manifold does). A part must never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.60.0",
+  "version": "0.60.2",
   "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/backend-select.js

@@ -2,12 +2,10 @@
 // This is framework-level policy, not geometry-kernel plumbing: it knows the full
 // PartDefinition shape (meta.backend, defaults, parts[name].build), unlike
 // everything in geometry/, which is part-agnostic.
-import { OCCT_ONLY_OPS } from "./geometry/kernel.js";
 import { createProbeKernel } from "./geometry/probe.js";
+import { isZeroMagnitudeCadOp } from "./geometry/op-options.js";
 import { resolveDerived } from "./derive.js";
 
-const OCCT_ONLY = new Set(OCCT_ONLY_OPS);
-
 export function detectBackend(part, params = {}) {
   if (part.meta?.backend) return part.meta.backend;
   const p = { ...part.defaults, ...params };
@@ -16,13 +14,39 @@ export function detectBackend(part, params = {}) {
   // regen (after the busy spinner goes up). Probe with an empty `d`; the worker
   // build hits the same throw and posts a proper error for the UI.
   try { d = resolveDerived(part, p); } catch { /* fall through with d = {} */ }
-  const { kernel, solidUsed } = createProbeKernel();
+  const { kernel, cadCalls } = createProbeKernel();
   for (const name of Object.keys(part.parts)) {
     try { part.parts[name].build(kernel, p, d); } catch { /* probe miss → capability backstop covers it */ }
   }
-  // solidUsed, not used: `Shape2D.fillet`/`.chamfer` are the shared pure-JS
-  // implementation (backend-identical) and must not drag a part onto OCCT — only
-  // the same names called on a Solid are CAD-only.
-  for (const op of solidUsed) if (OCCT_ONLY.has(op)) return "occt";
+  // cadCalls holds only Solid-handle fillet/chamfer/shell — `Shape2D.fillet`/
+  // `.chamfer` are the shared pure-JS implementation (backend-identical) and must
+  // not drag a part onto OCCT. A provably zero magnitude is the identity (see
+  // KERNEL-CONTRACT.md) and doesn't route either, so a fillet param dialed to 0
+  // drops the part back onto Manifold with no `if (r > 0)` guard in the build.
+  for (const { op, args } of cadCalls) {
+    if (!isZeroMagnitudeCadOp(op, args)) return "occt";
+  }
   return "manifold";
 }
+
+// The mount-time backend chooser. detectBackend() re-runs per regen with live
+// params, so backend choice already follows the parameters in both directions —
+// this wrapper exists for the runtime backstop: when the probe under-detects
+// (a CAD-only call it can't reach — e.g. gated on a real geometry query the
+// probe answers with dummies) the Manifold build throws NEEDS_OCCT and the
+// worker asks for a reroute. That must not pin OCCT for the rest of the session,
+// or turning the OCCT-only feature off never reverts to Manifold. Instead the
+// reroute is latched per params snapshot: the exact params that failed skip the
+// doomed Manifold retry, and ANY param change re-consults the probe. A part the
+// probe chronically under-detects costs one cheap failed Manifold dispatch per
+// param change — the price of automatic reversion.
+export function createBackendPolicy(part, { forced = null } = {}) {
+  let latchedParams = null; // JSON snapshot of the params proven at runtime to need OCCT
+  return {
+    backendFor: (params) => forced
+      ?? (latchedParams !== null && latchedParams === JSON.stringify(params)
+        ? "occt"
+        : detectBackend(part, params)),
+    noteNeedsOcct: (params) => { latchedParams = JSON.stringify(params); },
+  };
+}

package/src/framework/geometry/contour-offset.js

@@ -824,6 +824,35 @@ function sourceBackedPositiveRegions(source, out, delta) {
   return result;
 }
 
+// Crossing clustering can snap both ends of a tiny curve run onto the same pool vertex.
+// The run then survives as a closed loop attached at one point (or as a whole one-segment
+// contour). It encloses only geometry inside the resolver's own 2*CLUSTER_TOL cluster-
+// diameter uncertainty, but a downstream cap triangulator may bridge that loop across the
+// face and expose the bridge as a bogus feature edge. Positive dilation may discard these
+// sub-resolution counter loops: they are collapsed negative boundaries, never new material.
+// Keep erosion unchanged; its tiny surviving islands have no equivalent source-domain proof.
+function dropSubresolutionPositiveLoops(out, delta) {
+  if (delta <= 0) return out;
+  const radius = 2 * CLUSTER_TOL;
+  const clean = (contour) => {
+    const segments = [];
+    let from = contour.start;
+    for (const seg of contour.segments) {
+      const controls = [seg.via, seg.c1, seg.c2].filter(Boolean);
+      const clusteredLoop = dist(from, seg.to) <= 1e-12
+        && controls.every((p) => dist(from, p) <= radius);
+      if (!clusteredLoop) segments.push(seg);
+      from = seg.to;
+    }
+    return segments.length ? { start: contour.start, segments } : null;
+  };
+
+  return out.flatMap((rg) => {
+    const outer = clean(rg.outer);
+    return outer ? [{ outer, holes: rg.holes.map(clean).filter(Boolean) }] : [];
+  });
+}
+
 // Region-in / region-out offset: the engine behind Shape2D.offset on BOTH backends.
 // Fast path: raw per-ring offsets that validate cleanly are returned as-is (lines/arcs
 // exact). Cleanup path: anything dirty or invalid goes through resolveOffsetWinding
@@ -850,6 +879,7 @@ export function offsetRegions(regions, delta, { corners = "round" } = {}) {
     if (out === null) throw err;            // pinned message, unchanged, when nothing works
   }
   out = sourceBackedPositiveRegions(regions, out, delta);
+  out = dropSubresolutionPositiveLoops(out, delta);
   if (out.length === 0) throw new Error("Shape2D.offset: offset collapses the shape (reduce |delta|)");
   return out;
 }

package/src/framework/geometry/creased-normals.js

@@ -95,10 +95,14 @@ export function creasedNormals(g, { policies = null, featureLabels = null } = {}
       if (prev === undefined) { seenEdge.set(key, t); continue; }
       seenEdge.delete(key);
       const dot = fn[prev * 3] * fn[t * 3] + fn[prev * 3 + 1] * fn[t * 3 + 1] + fn[prev * 3 + 2] * fn[t * 3 + 2];
-      // policy-gated same-surface lines; seam rule unchanged
-      const hard = triOID[prev] === triOID[t]
+      // A multi-hole cap triangulation can contain an opposite-wound bridge:
+      // its two normals disagree by 180 degrees even though both triangles lie
+      // in the same plane. Gate on the unoriented supporting-plane angle first
+      // so that triangulation seam never becomes a feature line.
+      const bends = Math.abs(dot) < COPLANAR_COS;
+      const hard = bends && (triOID[prev] === triOID[t]
         ? polFor(triOID[t]).sameSurfaceLines && dot < cosFor(triOID[t])
-        : dot < COPLANAR_COS;
+        : true);
       if (hard) {
         const ai = i * np, bj = j * np;
         const dx = vp[ai] - vp[bj], dy = vp[ai + 1] - vp[bj + 1], dz = vp[ai + 2] - vp[bj + 2];

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

@@ -208,6 +208,9 @@ export function createOcctKernel(replicad) {
         const key = h("fillet", hash, radius, selKey(selector));
         return cached(key, () => {
           const a = mat();
+          // radius 0 is the identity per the contract — skip the kernel call so it
+          // can't trip the repair path's "feature skipped" warning.
+          if (radius === 0) return wrap(a._s.clone(), cloneLabels(a._labels), key);
           return wrap(safeOp(a._s.clone(), (sh) => sh.fillet(radius, toEdgeFinder(selector)), `fillet(${radius})`), cloneLabels(a._labels), key);
         });
       },
@@ -216,6 +219,7 @@ export function createOcctKernel(replicad) {
         // validChamfer probes on internal clones and never consumes its input.
         return cached(key, () => {
           const a = mat();
+          if (distance === 0) return wrap(a._s.clone(), cloneLabels(a._labels), key); // identity, same as fillet(0)
           return wrap(validChamfer(a._s, toEdgeFinder(selector), distance), cloneLabels(a._labels), key);
         });
       },

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

@@ -280,8 +280,8 @@ export const KERNEL_OP_SPECS = {
 };
 
 // Solid ops under the options convention; addSugar() wraps these when the
-// backend provides them natively (OCCT). The Manifold KernelCapabilityError
-// stubs ignore arguments, so options-form calls still throw the routing error.
+// backend provides them natively (OCCT). The Manifold stubs check only for the
+// zero-magnitude identity case below, then throw the routing error unnormalized.
 export const SOLID_OP_SPECS = {
   fillet:  { toArgs: (o) => { checkKeys("fillet", o, ["r", "edges"]);
     return [req("fillet", o, "r"), ...(o.edges !== undefined ? [o.edges] : [])]; } },
@@ -290,3 +290,17 @@ export const SOLID_OP_SPECS = {
   shell:   { toArgs: (o) => { checkKeys("shell", o, ["t", "open"]);
     return [req("shell", o, "t"), req("shell", o, "open")]; } },
 };
+
+// A zero-magnitude fillet/chamfer is the identity on every conformance class
+// (KERNEL-CONTRACT.md), so it neither routes a part to OCCT nor throws the
+// Manifold capability error. True only when the magnitude is PROVABLY the number
+// 0 in either calling convention — anything unprovable stays conservative
+// (routes/throws). shell is excluded: t = 0 means zero-thickness walls, which is
+// degenerate, not identity.
+export function isZeroMagnitudeCadOp(op, args) {
+  const key = op === "fillet" ? "r" : op === "chamfer" ? "d" : null;
+  if (!key) return false;
+  const a0 = args[0];
+  const v = typeof a0 === "number" ? a0 : isPlainOptions(a0) ? a0[key] : undefined;
+  return v === 0;
+}

package/src/framework/geometry/probe.js

@@ -15,7 +15,7 @@
 // lists, which test/kernel-contract.test.js pins to both backend implementations.
 import {
   KERNEL_OPS, KERNEL_OPTIONAL_OPS,
-  SOLID_OPS, SOLID_OPTIONAL_OPS, SHAPE2D_OPS,
+  SOLID_OPS, SOLID_OPTIONAL_OPS, SHAPE2D_OPS, OCCT_ONLY_OPS,
 } from "./kernel.js";
 import { KERNEL_OP_SPECS, SOLID_OP_SPECS, isPlainOptions } from "./op-options.js";
 
@@ -92,15 +92,22 @@ function makeProbe(onCall) {
   return { kernel, proxy, shape2d };
 }
 
+const CAD_OPS = new Set(OCCT_ONLY_OPS);
+
 export function createProbeKernel() {
   const used = new Set();       // every op name, any handle kind
   const solidUsed = new Set();  // ops recorded on kernel/Solid handles only — the
                                 // routing set: Shape2D.fillet must not look like Solid.fillet
-  const { kernel } = makeProbe((scope, key) => {
+  const cadCalls = [];          // Solid-handle fillet/chamfer/shell calls WITH args —
+                                // routing needs the magnitude (fillet(0) is identity, stays on Manifold)
+  const { kernel } = makeProbe((scope, key, args) => {
     used.add(key);
-    if (scope !== "shape2d") solidUsed.add(key);
+    if (scope !== "shape2d") {
+      solidUsed.add(key);
+      if (CAD_OPS.has(key)) cadCalls.push({ op: key, args });
+    }
   });
-  return { kernel, used, solidUsed };
+  return { kernel, used, solidUsed, cadCalls };
 }
 
 export function createValidatingProbe({ maxOps = MAX_PROBE_OPS } = {}) {

package/src/framework/geometry/solid-sugar.js

@@ -12,7 +12,7 @@
 //     the needs-occt reroute works without hand-written per-backend stubs.
 import { KernelCapabilityError } from "./errors.js";
 import { OCCT_ONLY_OPS } from "./kernel.js";
-import { isPlainOptions, SOLID_OP_SPECS } from "./op-options.js";
+import { isPlainOptions, isZeroMagnitudeCadOp, SOLID_OP_SPECS } from "./op-options.js";
 
 const ORIGIN = [0, 0, 0];
 const AXIS = { X: [1, 0, 0], Y: [0, 1, 0], Z: [0, 0, 1] };
@@ -59,14 +59,21 @@ export function addSugar(s) {
 
   // Options-object calling convention for the multi-param B-rep ops. Wrap only
   // when the backend provides the op natively (OCCT); the Manifold stubs below
-  // ignore their arguments, so options-form calls still throw the routing error.
+  // read their arguments just enough to spot the zero-magnitude identity case,
+  // and throw the routing error for everything else.
   for (const [op, { toArgs }] of Object.entries(SOLID_OP_SPECS)) {
     const raw = s[op];
     if (raw) s[op] = (...a) => raw(...(a.length === 1 && isPlainOptions(a[0]) ? toArgs(a[0]) : a));
   }
 
   for (const op of OCCT_ONLY_OPS) {
-    s[op] ??= () => { throw new KernelCapabilityError(`${op} requires the OCCT backend`); };
+    // Zero magnitude is the identity per the contract — return a fresh handle
+    // (same idiom as along("+Z")) so an unguarded `.fillet(p.r)` at r = 0 builds
+    // on the core kernel instead of throwing the routing error.
+    s[op] ??= (...a) => {
+      if (isZeroMagnitudeCadOp(op, a)) return s.translate(ORIGIN);
+      throw new KernelCapabilityError(`${op} requires the OCCT backend`);
+    };
   }
 
   return Object.assign(s, SUGAR);

package/src/framework/mount.js

@@ -13,7 +13,7 @@ import { createMeshCache } from "./mesh-cache.js";
 import { createGeometryService } from "./geometry-service.js";
 import { viewSubParts } from "./part-model.js";
 import { resolveDerived } from "./derive.js";
-import { detectBackend } from "./backend-select.js";
+import { createBackendPolicy } from "./backend-select.js";
 import { createDebugOverlay } from "./debug-overlay.js";
 import { createRegenLoop } from "./regen-loop.js";
 import { createPoseFastPath } from "./pose-fast-path.js";
@@ -253,10 +253,14 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     cleanup.defer(() => ui.setStatus(""));
     cleanup.defer(() => ui.hideBusy());
 
-    // ?backend=occt|manifold forces the backend; otherwise it's detected per part.
+    // ?backend=occt|manifold forces the backend; otherwise it's re-detected per
+    // regen with the live params (so a fillet dialed to 0 reverts to Manifold),
+    // with a params-keyed latch for runtime needs-occt reroutes — see
+    // createBackendPolicy for why the latch must not outlive a param change.
     let forcedBackend = new URLSearchParams(location.search).get("backend");
     if (forcedBackend !== "occt" && forcedBackend !== "manifold") forcedBackend = null;
-    const backendFor = () => forcedBackend ?? detectBackend(part, params);
+    const backendPolicy = createBackendPolicy(part, { forced: forcedBackend });
+    const backendFor = () => backendPolicy.backendFor(params);
 
     // ?debug shows the cache debug overlay; ?debug&nocache starts with caching off.
     const qs = new URLSearchParams(location.search);
@@ -549,7 +553,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
           ui.setStatus(`${data.filename} downloaded`);
           break;
         case "needs-occt":
-          forcedBackend = "occt"; // probe missed; this part needs OCCT — stick to it
+          // Probe missed for the current params — rebuild on OCCT. The latch is
+          // per params snapshot, so changing params re-consults the probe and the
+          // part can drop back to Manifold when the OCCT-only feature goes away.
+          backendPolicy.noteNeedsOcct(params);
           loop.buildDone();
           loop.kick();
           break;