partforge 0.100.0 → 0.101.0

package/docs/AUTHORING-PARTS.md

@@ -3405,6 +3405,8 @@ symptom first** — it maps error text → cause → fix. The invariants, one li
   of deliberate clearance, or overshoot the cut. Mesh CSG shrugs; OCCT's boolean
   degenerates, so the part previews instantly and the STEP export runs for minutes
   ([boolean-coincident-faces-hang](ERROR-PATTERNS.md#boolean-coincident-faces-hang)).
+  The exact kernel refuses the common form up front — an `exactly-touching surfaces`
+  build error names the shared radius and this fix menu.
   For the case that causes this most often — a tapped hole — reach for
   `k.tappedBore`, which owns the bore and the thread together and cannot land them
   on the same face.

package/docs/ERROR-PATTERNS.md

@@ -65,6 +65,7 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 
 - **Symptom:** A part previews instantly but a STEP export (or any OCCT-path build) of one sub-part runs for minutes and never finishes, with no error, no warning, and no progress. Cutting each tool on its own is fast; only the combination hangs. Threaded parts are the usual victims.
 - **Cause:** Two cut tools in the same `cutAll` (or a tool and the body) share an *exactly* coincident face — most often a bore whose radius equals a thread's root radius, so the bore wall and the thread root lie on the same cylinder. OCCT's boolean has to classify a surface that is simultaneously on both operands, and the intersection search degenerates. Manifold's mesh CSG does not care, which is why the preview is fine and only the exact kernel suffers. Measured on one real part: bore alone 0.4 s, thread alone 5.4 s, both together did not finish in fifteen minutes; moving the bore 0.05 mm brought the pair to 12.6 s.
+- **Detected:** The exact kernel now refuses the common cylindrical form of this contact up front — several swept faces lying exactly on one cylindrical face fail the boolean immediately with `<op> between exactly-touching surfaces: … (radius <r>)` and the fix menu below, instead of grinding. Scope, honestly: the guard needs the contact to tile the cylinder (a thread does, ~6+ hugging faces per turn; a sub-turn thread can slip under it — that is the old grinding behavior, not a new one), it covers swept-face-on-cylinder contact only (two swept faces mated exactly, or contact with non-cylindrical faces, can still hang), and a hand-sunk thread whose chord-bands happen to hug the wall can be refused even though it would have built — `k.tappedBore` resolves that refusal too, since its internal composition is exempt. The rule below applies everywhere regardless.
 - **Fix:** For a tapped hole — far and away the most common cause — use `k.tappedBore({ d, pitch, turns, depth })`, which returns the bore and its thread as one tool and cannot put them on the same face. Otherwise: give the surfaces a deliberate clearance instead of letting them land on the same number. Derive one from the other with an explicit gap — `const boreD = threadRootD - 2 * boreClearance;` with `boreClearance` around 0.05-0.1 mm — rather than reusing the same expression for both. The gap is far below a printable layer, so the fit is unchanged. The same rule covers a cut that ends exactly flush with a face (overshoot it by a few tenths, as the surrounding examples do with `+ 0.4` / `- 0.2`) and two tools that abut exactly end-to-end.
 
 ## chamfer-rescue-bisection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.100.0",
+  "version": "0.101.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/geometry/kernel-front.js

@@ -118,7 +118,12 @@ export function finishKernel(k) {
     // swapped, an empty solid). A wrong answer with no error is the worst of the
     // three failure modes, and overhanging is what avoids it.
     const threadLength = pitch * turns;
-    return k.union([
+    // _trustedUnion where the backend offers it (OCCT): this composition is the
+    // coincidence guard's own coached FIX, audited by the identity test and the
+    // guard suite, and its flank chord-bands legitimately hug the bore wall
+    // they overlap — the guard must not second-guess it. Manifold has no guard
+    // and no _trustedUnion; plain union is identical there.
+    return (k._trustedUnion ?? k.union)([
       k.cylinder({ d, h: (depth ?? threadLength) + 2 * overshoot }).translate([0, 0, -overshoot]),
       thread,
     ]);

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

@@ -15,6 +15,7 @@
 //     param change (a lid's open angle) therefore re-runs no OCCT op at all.
 //     Ops that need the real B-rep (booleans, fillet/chamfer/shell, exports,
 //     volume, boundingBox) materialize the pending pose through replicad first.
+import { assertNoCoincidentBoolean } from "./occt-coincidence.js";
 import { toEdgeFinder } from "./edge-selector.js";
 import { toFaceFinder } from "./face-selector.js";
 import { addSugar } from "./solid-sugar.js";
@@ -117,6 +118,12 @@ export function createOcctKernel(replicad) {
   // Manifold backend's fillet/chamfer degradation.
   const buildWarnings = [];
   const recordWarning = (msg) => { buildWarnings.push(msg); console.warn(`partforge: ${msg}`); };
+  // The raw OCCT instance, for the coincident-boolean guard (occt-coincidence.js).
+  // Absent (older replicad, or a boot path that skipped setOC) the guard is a no-op —
+  // detection is an upgrade, never a dependency.
+  let occtInstance = null;
+  try { occtInstance = replicad.getOC(); } catch { /* guard disabled */ }
+  const guardBoolean = (opName, solids) => assertNoCoincidentBoolean(occtInstance, opName, solids);
   // 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, recordWarning);
@@ -223,6 +230,7 @@ export function createOcctKernel(replicad) {
         const key = h("cut", hash, t._hash);
         return cached(key, () => {
           const a = mat(), b = t._mat();
+          guardBoolean("cut", [a._s, b._s]);
           return wrap(a._s.clone().cut(b._s.clone()), [...cloneLabels(a._labels), ...cloneLabels(b._labels)], key);
         });
       },
@@ -231,6 +239,10 @@ export function createOcctKernel(replicad) {
         return cached(key, () => {
           const a = mat(), bs = tools.map((t) => t._mat());
           if (bs.length === 0) return wrap(a._s.clone(), cloneLabels(a._labels), key);
+          // All pairs, tools included: the cut below first fuses the tools
+          // together, so tool-to-tool contact hangs exactly like target-to-tool
+          // (the measured case WAS two tools — a bore and its thread).
+          guardBoolean("cutAll", [a._s, ...bs.map((b) => b._s)]);
           const fusedTools = bs
             .slice(1)
             .reduce((acc, b) => acc.fuse(b._s.clone()), bs[0]._s.clone());
@@ -245,6 +257,7 @@ export function createOcctKernel(replicad) {
         const key = h("intersect", hash, t._hash);
         return cached(key, () => {
           const a = mat(), b = t._mat();
+          guardBoolean("intersect", [a._s, b._s]);
           return wrap(a._s.clone().intersect(b._s.clone()), [...cloneLabels(a._labels), ...cloneLabels(b._labels)], key);
         });
       },
@@ -252,6 +265,7 @@ export function createOcctKernel(replicad) {
         const key = h("union", [hash, t._hash]);
         return cached(key, () => {
           const a = mat(), b = t._mat();
+          guardBoolean("union", [a._s, b._s]);
           return wrap(a._s.clone().fuse(b._s.clone()), [...cloneLabels(a._labels), ...cloneLabels(b._labels)], key);
         });
       },
@@ -628,6 +642,24 @@ export function createOcctKernel(replicad) {
     prism, extrude, revolve, loft: loftOp, sweep, helixSweptTube, heightfield,
     sphere: (r) => cached(h("sphere", r), () => wrap(makeSphere(r), [], h("sphere", r))),
     union: (solids) => {
+      const key = h("union", solids.map((s) => s._hash));
+      return cached(key, () => {
+        const ms = solids.map((s) => s._mat());
+        guardBoolean("union", ms.map((m) => m._s));
+        return wrap(
+          ms.map((m) => m._s.clone()).reduce((a, b) => a.fuse(b)),
+          ms.flatMap((m) => cloneLabels(m._labels)),
+          key,
+        );
+      });
+    },
+    // Union WITHOUT the coincidence guard — for kernel-front compositions that
+    // are audited fixes for the guarded failure (k.tappedBore's bore ∪ thread,
+    // whose flank chord-bands deliberately hug the bore wall they overlap;
+    // measured safe at 3.0s where the tangent form never finishes). `_`-prefixed:
+    // not part of the public kernel surface, and part authors never see it.
+    // Same cache key as union — the geometry is identical either way.
+    _trustedUnion: (solids) => {
       const key = h("union", solids.map((s) => s._hash));
       return cached(key, () => {
         const ms = solids.map((s) => s._mat());

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

@@ -0,0 +1,197 @@
+// Refuses the boolean OCCT cannot survive, before it runs.
+//
+// The degenerate case (measured on real feedback, 2026-08-31): a swept face —
+// a thread root from screwSweep is the canonical one — lying exactly ON the
+// other operand's cylindrical face. OCCT 7.6 detects same-domain overlap
+// between two ANALYTIC cylinders instantly (flush stacks, re-cut holes and
+// overlapping coaxial rods all fuse in milliseconds), but a BSpline surface
+// coincident with a cylinder has no same-domain shortcut: the intersection
+// walker grinds for minutes with no error, wedging the serial kernel worker,
+// or — on OCCT 8 — "finishes" with corrupt geometry (a negative-volume fuse).
+// Every kernel-level mitigation was measured and ruled out: SetFuzzyValue
+// hangs at 1e-4/1e-3/1e-2, SetUseOBB hangs, glue completes only under a
+// precondition (no volumetric overlap) that cannot be proven in general, and
+// the WASM build binds no progress indicator so the grind cannot be aborted.
+// The only fix is refusing the contact and coaching the author toward real
+// clearance, real overlap, or k.tappedBore.
+//
+// The predicate is AREA contact, not proximity: a freeform face whose sampled
+// points nearly all sit on the cylinder (within the sweep's own approximation
+// band — the swept "cylinder" deviates from the true radius by ~1e-3·r, which
+// is exactly why OCCT cannot classify it as same-domain). Faces that merely
+// CROSS the radius (thread flanks, the tapered lead-in ramps) put only a
+// fraction of their samples in the band and are left alone — measured at 0.5
+// and 0.75 against the 0.9 threshold, and a construction with the documented
+// 0.05 mm of clearance sits far outside the band entirely.
+//
+// Known misses, accepted: freeform-vs-freeform coincidence (two swept
+// surfaces mated exactly) and exact contact with non-cylindrical analytic
+// faces. This guard exists for the case users actually author — a bore plus a
+// thread — not as a proof that every boolean terminates.
+
+const FREEFORM_SURFACES = [
+  "GeomAbs_BSplineSurface",
+  "GeomAbs_BezierSurface",
+  "GeomAbs_SurfaceOfExtrusion",
+  "GeomAbs_SurfaceOfRevolution",
+  "GeomAbs_OffsetSurface",
+  "GeomAbs_OtherSurface",
+];
+
+// Sampled 4×4 across each candidate face; "on the cylinder" means within
+// max(1e-3, 2e-3·r) — twice the measured sweep-approximation band, still an
+// order of magnitude below the 0.05 mm the authoring guidance calls real
+// clearance — and a face is contact only when ≥90% of its samples qualify.
+//
+// A single hugging face is NOT enough to refuse: a twisted extrusion's flank
+// is subdivided into narrow helical chord-bands, and whichever band straddles
+// the wall sits inside the position tolerance over its whole area (measured:
+// r-span 0.010 across the full thread length) — yet OCCT resolves that
+// transversal contact in seconds. Local geometry cannot separate the two
+// cases robustly: the band's radial drift and the coincident face's chord
+// wobble are both ~r·1e-3, and every tangency proxy measured (surface
+// normals: cancellation noise on helical faces; radial gradients: the
+// crossing smears over a ~0.37 circumferential path, g≈0.03 vs wobble 0.01)
+// lands inside the noise. What separates them decisively is EXTENT: a
+// coincident swept surface tiles the cylinder with hugging faces (~6+ per
+// turn, 20 measured on a 3-turn thread), while a crossing contributes the one
+// band that happens to straddle (1–3 with phase luck). Hence
+// MIN_CONTACT_FACES: refuse only when several distinct freeform faces hug the
+// SAME cylinder. A sub-turn thread can slip under the threshold — that is the
+// old behavior, not a new failure — and a hand-sunk thread whose chord-band
+// count reaches it is refused with coaching toward k.tappedBore, whose own
+// internal union is exempt (it is this module's audited fix, not a suspect).
+const GRID = 4;
+const REL_TOL = 2e-3;
+const MIN_TOL = 1e-3;
+const MIN_ON_FRACTION = 0.9;
+const MIN_CONTACT_FACES = 4;
+
+// Above this many faces on one operand, skip detection (fail open): the guard
+// must never cost more than the boolean it protects. A part-authored solid is
+// tens to hundreds of faces; only a large STEP import approaches this.
+const MAX_FACES = 8000;
+
+const enumName = (enumObj, value) =>
+  Object.keys(enumObj).find((n) => enumObj[n] === value || (enumObj[n]?.value !== undefined && enumObj[n].value === value?.value));
+
+// One pass over a solid's faces: analytic cylinders (radius + axis + bbox) and
+// freeform faces (adaptor kept for lazy sampling + bbox). Caller must dispose().
+function faceProfile(oc, topo) {
+  const cylinders = [];
+  const freeforms = [];
+  let faceCount = 0;
+  const explorer = new oc.TopExp_Explorer_2(topo, oc.TopAbs_ShapeEnum.TopAbs_FACE, oc.TopAbs_ShapeEnum.TopAbs_SHAPE);
+  for (; explorer.More(); explorer.Next()) {
+    faceCount += 1;
+    if (faceCount > MAX_FACES) break;
+    const face = oc.TopoDS.Face_1(explorer.Current());
+    const adaptor = new oc.BRepAdaptor_Surface_2(face, true);
+    const surface = enumName(oc.GeomAbs_SurfaceType, adaptor.GetType());
+    const box = new oc.Bnd_Box_1();
+    oc.BRepBndLib.Add(face, box, false);
+    const mn = box.CornerMin(), mx = box.CornerMax();
+    const bbox = [mn.X(), mn.Y(), mn.Z(), mx.X(), mx.Y(), mx.Z()];
+    box.delete();
+    if (surface === "GeomAbs_Cylinder") {
+      const cyl = adaptor.Cylinder();
+      const axis = cyl.Axis(), dir = axis.Direction(), loc = axis.Location();
+      cylinders.push({
+        r: cyl.Radius(),
+        loc: [loc.X(), loc.Y(), loc.Z()],
+        dir: [dir.X(), dir.Y(), dir.Z()],
+        bbox,
+      });
+      adaptor.delete();
+    } else if (FREEFORM_SURFACES.includes(surface)) {
+      freeforms.push({ adaptor, bbox });
+    } else {
+      adaptor.delete();
+    }
+  }
+  explorer.delete();
+  return {
+    cylinders,
+    freeforms,
+    overflow: faceCount > MAX_FACES,
+    dispose: () => { for (const f of freeforms) f.adaptor.delete(); },
+  };
+}
+
+const boxesOverlap = (a, b, pad) =>
+  a[0] <= b[3] + pad && b[0] <= a[3] + pad &&
+  a[1] <= b[4] + pad && b[1] <= a[4] + pad &&
+  a[2] <= b[5] + pad && b[2] <= a[5] + pad;
+
+// Fraction of a freeform face's interior sample grid lying within tol of the
+// cylinder's surface.
+function onCylinderFraction(freeform, cyl, tol) {
+  const ad = freeform.adaptor;
+  const u0 = ad.FirstUParameter(), u1 = ad.LastUParameter();
+  const v0 = ad.FirstVParameter(), v1 = ad.LastVParameter();
+  let hits = 0;
+  for (let i = 0; i < GRID; i++) {
+    for (let j = 0; j < GRID; j++) {
+      const p = ad.Value(u0 + ((i + 0.5) / GRID) * (u1 - u0), v0 + ((j + 0.5) / GRID) * (v1 - v0));
+      const px = p.X() - cyl.loc[0], py = p.Y() - cyl.loc[1], pz = p.Z() - cyl.loc[2];
+      const t = px * cyl.dir[0] + py * cyl.dir[1] + pz * cyl.dir[2];
+      const radial = Math.hypot(px - t * cyl.dir[0], py - t * cyl.dir[1], pz - t * cyl.dir[2]);
+      if (Math.abs(radial - cyl.r) <= tol) hits += 1;
+    }
+  }
+  return hits / (GRID * GRID);
+}
+
+function contactBetween(profileA, profileB) {
+  for (const [cylSide, freeSide] of [[profileA, profileB], [profileB, profileA]]) {
+    for (const cyl of cylSide.cylinders) {
+      const tol = Math.max(MIN_TOL, REL_TOL * cyl.r);
+      let contacts = 0;
+      for (const freeform of freeSide.freeforms) {
+        if (!boxesOverlap(cyl.bbox, freeform.bbox, tol)) continue;
+        if (onCylinderFraction(freeform, cyl, tol) >= MIN_ON_FRACTION) contacts += 1;
+        if (contacts >= MIN_CONTACT_FACES) return { radius: cyl.r };
+      }
+    }
+  }
+  return null;
+}
+
+// The one entry point. `solids` are replicad Shape3D wrappers (`.wrapped` is
+// the TopoDS shape); every unordered pair is checked, because a cutAll fuses
+// its tools together before cutting — the contact can be tool-to-tool as
+// easily as target-to-tool. Throws the coached error on contact; returns
+// silently otherwise. Any internal failure returns silently too: the guard
+// must never break a boolean that would have succeeded.
+export function assertNoCoincidentBoolean(oc, opName, solids) {
+  if (!oc || solids.length < 2) return;
+  const profiles = [];
+  try {
+    for (const s of solids) profiles.push(faceProfile(oc, s.wrapped));
+    for (let i = 0; i < profiles.length; i++) {
+      for (let j = i + 1; j < profiles.length; j++) {
+        const contact = contactBetween(profiles[i], profiles[j]);
+        if (contact) throw coincidentBooleanError(opName, contact.radius);
+      }
+    }
+  } catch (e) {
+    if (e?.code === "COINCIDENT_BOOLEAN") throw e;
+    // Detection is best-effort; a probe failure must not block the build.
+  } finally {
+    for (const p of profiles) { try { p.dispose(); } catch { /* freed with the shape */ } }
+  }
+}
+
+function coincidentBooleanError(opName, radius) {
+  const r = Number(radius.toFixed(4));
+  const err = new Error(
+    `${opName} between exactly-touching surfaces: a swept or curved face of one operand lies ` +
+    `exactly on a cylindrical face of the other (radius ${r}). The exact kernel cannot process ` +
+    `this contact — it grinds for minutes or returns broken geometry — so the build was refused ` +
+    `before trying. Make the surfaces genuinely overlap or genuinely clear each other (0.05 or ` +
+    `more) instead of exactly touching; for an internal thread, replace the bore + screwSweep ` +
+    `pair with k.tappedBore, which builds the same tap as one safe tool.`,
+  );
+  err.code = "COINCIDENT_BOOLEAN";
+  return err;
+}