partforge 0.99.0 → 0.100.0

package/docs/AUTHORING-PARTS.md

@@ -1221,6 +1221,36 @@ turn. A 30 mm shank is 20 turns and about half a second on Manifold; hundreds of
 turns is millions of triangles and minutes behind the STEP button. Bound the
 `length` and `pitch` your schema exposes accordingly.
 
+**Internal threads: use `k.tappedBore`, not a bore plus a `screwSweep`.** The
+periodic trick above is what saves an *external* thread from a boolean, and it
+has no internal equivalent — a tapped hole is a bore and a thread, and they have
+to be combined. Assembled by hand the obvious way, they are a trap:
+
+```js
+// ✗  the bore wall and the thread root land on the same cylinder
+const bore = k.cylinder({ d: boreD, h: depth });
+const thread = k.screwSweep({ profile: [[boreD / 2, 0], …], pitch, turns });
+cap.cutAll([bore, thread]);
+// ✓  one tool, no shared face
+cap.cut(k.tappedBore({ d: boreD, pitch, turns, depth }));
+```
+
+Both cut tools touch along an exactly coincident cylinder without overlapping.
+Manifold shrugs; OCCT has to resolve a tangential contact between a cylinder and
+the thread root's swept spline surface, along a helix, and the intersector
+degenerates — on one real 6-turn cap the export did not finish in **fifteen
+minutes**, while `tappedBore` builds the same hole in about fifteen seconds
+([boolean-coincident-faces-hang](ERROR-PATTERNS.md#boolean-coincident-faces-hang)).
+
+`k.tappedBore({ d, pitch, turns, depth?, crest?, lefthand?, rootSink?, overshoot? })`
+returns that hole as **one** solid to cut: `d` is the bore a tap would cut into,
+`crest` the radial thread height (default `0.15 · pitch`), `depth` the plain-bore
+length (default the thread's own). It owns both halves precisely so it can sink
+the thread's root *inside* the bore — which costs nothing, since the bore already
+removes that material, and is why the tangency never arises. `screwSweep` cannot
+do that for you: a thread cut into solid stock with no bore would then cut a
+deeper root and change your part.
+
 The hand-rolled equivalent, for the record: `screwSweep` is
 `k.extrude({ profile, h, twist })` with the axial profile remapped to polar
 (`ψ = −360·z/pitch`) and `twist = 360 · turns` — one full turn of twist per pitch
@@ -3375,6 +3405,9 @@ 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)).
+  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,7 +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.
-- **Fix:** 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.
+- **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/docs/KERNEL-CONTRACT.md

@@ -288,6 +288,7 @@ above. All ops return a `Solid`.
 | `sweep({profile, path, closed?, cornerRadius?, ruled?, smooth?})` | Sweep a fixed CCW profile along a polyline with a rotation-minimizing frame; sharp mitered corners, or `cornerRadius` fillets; capped ends. |
 | `helixSweptTube({pathR, profileR, pitch, turns, z0, lefthand})` | Circle of radius `profileR` swept along a helix (e.g. a rope groove). Circular profile on a frenet frame that rolls with the helix — **not for threads**; use `screwSweep`. |
 | `screwSweep({profile, pitch, turns, lefthand})` | Screw-motion sweep of an axial lathe profile `[[r, z], …]` (r ≥ 0) — threads. The profile travels to `(r·cosθ, r·sinθ, z + pitch·θ/2π)`; `h = pitch · turns`. Axial extent must not exceed `pitch` or consecutive turns interpenetrate (throws). A profile spanning exactly `pitch` is **periodic**: first and last radius must agree, and it yields a complete threaded body needing no boolean. Compound: the polar-remapped, densified section extruded with `twist = 360 · turns`, exactly as composed in `kernel-front.js`; a backend may override only for caching, never for different geometry. Options-only. Parity: **within tolerance, not by construction** — both backends receive the identical densified polygon, but the mesh backend facets the twist at its own resolution while the B-rep backend builds an exact spline (`hull`'s parity class). |
+| `tappedBore({d, pitch, turns, depth?, crest?, lefthand?, rootSink?, overshoot?})` | A tapped (internally threaded) hole as **one cut tool** — the plain bore of diameter `d` fused with its thread. Compound (`kernel-front.js`), so no backend implements it. Exists for robustness, not ergonomics: assembled by hand the bore wall and the thread root land on exactly the same cylinder, and OCCT's boolean cannot resolve that tangential contact along a helix — measured at fifteen minutes without finishing on a 6-turn cap (73–92 s even with OCCT's own `GlueShift`/`GlueFull` mitigation), against ~14 s for this op. Two offsets carry that: `rootSink` (default 0.2) sinks the thread's root INSIDE the bore by extending each flank COLINEARLY — the same swept surface carried further down, so everything at `r ≥ d/2` is identical to the hand-assembled construction and the union with the bore clips the rest (verified on Manifold, which can build the tangent form, to ~1e-5 of tool volume; sinking the root points radially instead would tilt the flanks and fatten the tooth outside the bore by a measured 2%). The extension steals axial root-flat width, so the sink is silently clamped where a full `rootSink` would consume it — the clamped overlap still clears the coincidence band by an order of magnitude. And `overshoot` (default 0.2) overhangs the bore past the thread at both ends, because flush ends are coincident faces one layer down, where the union does not hang but silently returns the bore alone (operands swapped, an empty solid). Both are refused at zero. `depth` defaults to the thread's own length `pitch · turns` and is refused SHORTER than it (the thread would poke out past the bore's far end); `crest` (radial thread height) defaults to `0.15 · pitch`; the tooth is a printable trapezoid, root flat `pitch/4` and crest flat `pitch/8`. This op owns BOTH halves on purpose: `screwSweep` cannot sink its own root, because a thread cut into solid stock with no bore would then cut deeper and change the part. Options-only. Parity: `screwSweep`'s class (within tolerance), which it composes. |
 | `loftSmooth({sections, stations?, samples?, shading?, closed?})` | Spline-interpolated loft of ≥2 sparse control sections — loft-style ring specs `{polygon\|sides+radius\|curve contour\|Shape2D, z, rotate?, scale?, sharp?}`; vertex counts **may differ**. A point section may tag `sharp: [indices]` as true corners (integers in `0…points.length-1`, sorted/deduped silently); a curve/`Shape2D` section takes corners implicitly from its non-smooth joints (single-region, hole-free, `loftSmooth:`-prefixed `k.loft` validation) and rejects an explicit `sharp`. Every section must resolve to the **same corner count `m`** (frozen error otherwise); with `m ≥ 1` corner 0 anchors the seam (replacing vertex 0), with `m = 0` v1's vertex-0 anchor holds verbatim. Compound (`kernel-front.js` + `loft-smooth.js`): each section's outline is a closed centripetal Catmull-Rom split into `m` clamped open arcs at its corners (or one closed periodic CR when `m = 0`); the `samples` budget is apportioned across arcs by mean arc-length fraction (largest-remainder, min 1 span/arc) and each arc resampled by arc length — total ring vertex count is `samples`, identical across sections, exactly v1's invariant now corner-anchored. The cross-station direction is v1 verbatim (shared centroid-spine knots, per-vertex CR, reflection phantoms at the ends, or periodic knots when `closed: true`). What's new is emission: every station — the dense list and the sparse `stations:"controls"` list alike — is fitted back to an **all-cubic Bézier contour**, arc-by-arc, via exact 4-point CR→Bézier inversion, so **both backends receive identical curve rings**. A B-rep kernel lofts the sparse control wires with its native smooth skin (`ruled: false`) — curve-exact around each ring in STEP (the densified-*point*-wire alternative measured 23 s / WASM-abort territory, which curve wires don't hit). A mesh kernel densifies `stations` rings and lofts them through `k.loft`'s curve-mode per-segment sampling, creasing sharp/corner columns via loft's geometric corner policy. `closed: true` (default false; needs ≥3 control sections, frozen error otherwise) makes the cross-station CR periodic (no reflection phantoms, ring 0 not repeated) and is **Manifold-only**, same restriction as `loft` `closed: true`: a B-rep kernel throws `loftSmooth: closed:true loops are only supported on the Manifold backend` in the composition, before building any rings; combining `closed: true` with `stations:"controls"` is rejected as a defensive invariant (reachable only by explicitly passing the internal `stations:"controls"` value; the composition never produces the combination itself). Options-only. Defaults `stations = (n−1)·8+1` open / `n·8` closed (raised to the section count `n` when lower), `samples = max(64, largest section)` (raised to the corner count `m` when lower); clamps 2…1024 / 8…2048 — the defaults cap themselves at the ceilings, only explicit out-of-range values throw. The surface interpolates every control section exactly. Parity: **within tolerance** (`screwSweep`'s class, unchanged from v1 — ~0.4% measured on the propeller reference part, test-gated at 2%). STEP is now curve-exact around each ring (previously faceted at the `samples` LOD); the cross-station skin remains ThruSections' native fit, not the shared CR — exact cross-station B-splines are a v3 candidate. Additive: `sharp`, curve/`Shape2D` sections, and `closed` are new options on top of v1's `{sections, stations?, samples?, shading?}`; `CONTRACT_VERSION` stays 4 — the same non-bump precedent as `import` above, a refinement inside the op's already-stated tolerance class rather than a new one. |
 | `heightfield(nameOrGrid, {w, d, base?, maxZ?, pitch?, invert?, range?, origin?})` | A depth map as a relief solid: a sampled grid top at `z = base + maxZ·f(v)`, skirt walls, and a flat base cap at `z = 0`. `nameOrGrid` is a name declared in the part's `images` field, or an inline `{width, height, data}` grid. Sample count per axis is `max(2, ceil(w/pitch))` and `max(2, ceil(d/pitch))`; if their product exceeds a vertex budget, `pitch` is scaled up uniformly to fit and, if still over, the two counts are shrunk in lockstep — with a `takeBuildWarnings` message rather than an error. `range` is a remap with clamped ends (`range[0]`→0, `range[1]`→1); `invert` applies after, as `1−v`. `origin` positions the footprint in XY only — the base always sits at `z = 0`. The image stretches to `w × d`; aspect is not preserved. **Axis convention:** sample row 0 (a source PNG's first scanline, i.e. its visual top in an image viewer) maps to the footprint's **−Y** edge — Y increases with row, the standard texture-coordinate mapping — so a depth map viewed from +Z looks vertically mirrored relative to the same file opened in a viewer; flip the source pixels before declaring the image if that orientation is unwanted (`invert` remaps height values, not position, and does not affect this). Fed by an underscore-prefixed side-channel (`_registerImage`), not part authors — see [Conformance classes](#conformance-classes). Required on both in-repo backends: Manifold imports the triangles directly, OCCT sews them into a faceted B-rep via `importSTL`, so STEP export carries a triangulated surface rather than an analytic one. Parity: **exact** — both backends receive byte-identical triangle data. Additive: `CONTRACT_VERSION` stays 4, the same precedent as `import` and `loftSmooth`. |
 | `union(solids[])` | Boolean union of one or more solids. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.99.0",
+  "version": "0.100.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

@@ -57,6 +57,73 @@ export function finishKernel(k) {
       twist: (lefthand ? -360 : 360) * turns,
     });
 
+  // Compound default: a tapped (internally threaded) hole, as ONE cut tool.
+  //
+  // The tool is a plain bore fused with a helical thread, and the whole reason
+  // this op exists is the ONE line that makes that fuse cheap: the thread's root
+  // is sunk INSIDE the bore rather than sitting on it. Hand-assembled, a tapped
+  // hole is written the obvious way — bore of diameter d, thread whose root
+  // radius is also d/2 — and those two tools then touch along an exactly
+  // coincident cylinder without overlapping. Mesh CSG does not care. OCCT does:
+  // it has to resolve a tangential contact between a cylinder and the swept
+  // B-spline surface of the thread root, along a helix, and the intersector
+  // degenerates. Measured on a real 6-turn M6-ish cap: the tangent form did not
+  // finish in fifteen minutes (with OCCT's own glue mitigation, 73-92 s); the
+  // sunk-root form is 8.4 s.
+  //
+  // Sinking is FREE, not a tolerance compromise: everything inside the bore is
+  // already removed by the bore, so the union is the same point set either way.
+  // That is exactly why this has to be an op that owns BOTH halves — screwSweep
+  // alone cannot sink its own root, because a thread cut into solid stock with
+  // no bore would then cut a deeper root and change the part.
+  k.tappedBore ??= ({ d, pitch, turns, depth, crest, lefthand = false, rootSink = 0.2, overshoot = 0.2 }) => {
+    const rootR = d / 2;
+    const majorR = rootR + (crest ?? 0.15 * pitch);
+    // A printable trapezoidal tooth: flat at root and crest so neither knife-edges
+    // at FDM resolution. Same shape a hand-rolled coarse thread converges on.
+    const rootFlat = pitch / 4;
+    const crestFlat = pitch / 8;
+    const rise = (pitch - rootFlat - crestFlat) / 2;
+    // Sink the root by extending the flanks COLINEARLY into the bore, not by
+    // moving the root points straight inward. A radially-moved root changes the
+    // flank slope, which fattens the tooth OUTSIDE the bore — measured at 2% of
+    // tool volume, and it lands exactly where a mating printed thread needs its
+    // clearance. A colinear extension is the same swept surface carried further
+    // down, so everything at r >= rootR is byte-identical to the hand-assembled
+    // tangent construction and the union with the bore clips the rest — the
+    // identity test in test/tapped-bore.test.js holds this to mesh precision.
+    // The extension steals axial root-flat width (e per side), so the sink is
+    // clamped where a full rootSink would consume it; the clamped overlap still
+    // clears the coincidence band by an order of magnitude.
+    const slope = rise / (majorR - rootR); // axial travel per unit of radial travel, along a flank
+    const sink = Math.min(rootSink, rootR, (0.45 * rootFlat) / slope);
+    const innerR = rootR - sink;
+    const e = slope * sink;
+    // Shifted down by e so the thread still spans [0, pitch*turns] — the bore's
+    // overshoot math below must not depend on the flank geometry.
+    const thread = k.screwSweep({
+      profile: [
+        [innerR, 0],
+        [innerR, rootFlat - 2 * e],
+        [majorR, rootFlat + rise - e],
+        [majorR, rootFlat + rise + crestFlat - e],
+        [innerR, pitch],
+      ],
+      pitch, turns, lefthand,
+    });
+    // The bore overhangs the thread at BOTH ends, for the same reason the sink
+    // exists: flush is a coincident face. Built with both starting at z = 0 the
+    // bore's end cap is coplanar with the thread's first turn, and this union
+    // does not hang — it silently returns the bore alone (or, with the operands
+    // 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([
+      k.cylinder({ d, h: (depth ?? threadLength) + 2 * overshoot }).translate([0, 0, -overshoot]),
+      thread,
+    ]);
+  };
+
   // Compound default: spline-smoothed loft. The shared Catmull-Rom densifier
   // (loft-smooth.js) now emits all-cubic curve rings on BOTH paths — every ring
   // is contour IR ({start, segments:[{to,c1,c2}…]}), fitted exactly from the CR

package/src/framework/geometry/kernel.js

@@ -27,6 +27,8 @@ export const KERNEL_OPS = [
   "loftSmooth",
   // Additive in 0.92 (same precedent): both backends implement it.
   "heightfield",
+  // Additive (same precedent): a compound default, so neither backend implements it.
+  "tappedBore",
 ];
 
 // Backend-optional kernel ops: the sub-part cache brackets + WASM lifetime hooks.
@@ -151,6 +153,7 @@ export const ROUTED_CAD_OPS = ["shell"];
  * @property {(o:{profile:number[][],degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z; legacy (points,opts) accepted for now (see file header)
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube
  * @property {(o:{profile:number[][],pitch:number,turns:number,lefthand?:boolean}) => Solid} screwSweep   screw-motion sweep of an axial [[r,z]] profile — threads; options-only
+ * @property {(o:{d:number,pitch:number,turns:number,depth?:number,crest?:number,lefthand?:boolean,rootSink?:number,overshoot?:number}) => Solid} tappedBore   compound: a tapped hole as ONE cut tool — bore plus thread, root sunk inside the bore so the two never share a face
  * @property {(o:{sections:object[],stations?:number,samples?:number,shading?:string,closed?:boolean}) => Solid} loftSmooth   Catmull-Rom-densified loft of sparse control sections; options-only
  * @property {(nameOrGrid: string|{width:number,height:number,data:Uint16Array}, opts: {w:number,d:number,base?:number,maxZ?:number,pitch?:number,invert?:boolean,range?:number[],origin?:"center"|"corner"}) => Solid} heightfield   depth-map relief solid; nameOrGrid is a name declared in the part's `images` field or an inline grid
  * @property {(solids:Solid[]) => Solid} union

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

@@ -272,6 +272,30 @@ export const KERNEL_OP_SPECS = {
   boredCylinder:  { toArgs: passThrough("boredCylinder", ["od", "h", "bore"], ["od", "h", "bore"]) },
   helixSweptTube: { toArgs: passThrough("helixSweptTube",
     ["pathR", "profileR", "pitch", "turns", "z0", "lefthand"], ["pathR", "profileR", "pitch", "turns"]) },
+  tappedBore: {
+    toArgs: passThrough("tappedBore",
+      ["d", "pitch", "turns", "depth", "crest", "lefthand", "rootSink", "overshoot"], ["d", "pitch", "turns"]),
+    check: (o) => {
+      if (!(o.d > 0)) throw new Error("tappedBore: d must be > 0");
+      if (!(o.pitch > 0)) throw new Error("tappedBore: pitch must be > 0");
+      if (!(o.turns > 0)) throw new Error("tappedBore: turns must be > 0");
+      if (o.depth != null && !(o.depth > 0)) throw new Error("tappedBore: depth must be > 0");
+      if (o.crest != null && !(o.crest > 0)) throw new Error("tappedBore: crest must be > 0");
+      // The sink is what keeps the bore and the thread root off the same
+      // cylinder; at zero they are tangent again and OCCT degenerates, which is
+      // the entire failure this op exists to prevent.
+      if (o.rootSink != null && !(o.rootSink > 0)) throw new Error("tappedBore: rootSink must be > 0");
+      if (o.rootSink != null && o.rootSink >= o.d / 2)
+        throw new Error("tappedBore: rootSink must be smaller than the bore radius");
+      if (o.overshoot != null && !(o.overshoot > 0)) throw new Error("tappedBore: overshoot must be > 0");
+      // The thread is always pitch*turns long; a shorter bore would leave it
+      // poking out past the bore's far end — a tap deeper than its own hole,
+      // and the overhang guarantee above quietly broken at that end.
+      if (o.depth != null && o.depth < o.pitch * o.turns)
+        throw new Error(
+          `tappedBore: depth (${o.depth}) must cover the thread (pitch*turns = ${o.pitch * o.turns}) — lower turns to Math.floor(depth / pitch), or raise depth`);
+    },
+  },
   screwSweep: {
     toArgs: passThrough("screwSweep", ["profile", "pitch", "turns", "lefthand"], ["profile", "pitch", "turns"]),
     check: (o) => {

package/types/kernel.d.ts

@@ -381,6 +381,32 @@ export interface ScrewSweepOptions {
   lefthand?: boolean;
 }
 
+/** `k.tappedBore` — a tapped (internally threaded) hole as ONE cut tool: the
+ *  plain bore and its thread, fused, with the thread's root sunk inside the bore
+ *  so the two never share a face. Hand-assembling the pair puts the bore wall and
+ *  the thread root on exactly the same cylinder, which OCCT's boolean cannot
+ *  resolve — measured at fifteen minutes without finishing, against ~10 s here. */
+export interface TappedBoreOptions {
+  /** Bore (minor/root) diameter, mm — the hole a tap would cut into. */
+  d: number;
+  /** Axial rise per turn, mm. */
+  pitch: number;
+  /** Number of thread turns; the thread is `pitch * turns` long. */
+  turns: number;
+  /** Plain-bore length, mm. Defaults to the thread's own length. */
+  depth?: number;
+  /** Radial thread height (major radius minus root), mm. Defaults to `0.15 * pitch`. */
+  crest?: number;
+  lefthand?: boolean;
+  /** How far the thread's root sits INSIDE the bore, mm (default 0.2). Free
+   *  rather than a compromise: the bore already removes that material, so the
+   *  union is unchanged — it only stops the two tools being tangent. */
+  rootSink?: number;
+  /** How far the bore overhangs the thread at each end, mm (default 0.2).
+   *  Flush ends are coincident faces, the same failure one layer down. */
+  overshoot?: number;
+}
+
 /** One `k.loftSmooth` control section. Point arrays may tag true corners with
  *  `sharp`; curve contours and Shape2D outlines carry corners implicitly. */
 export interface LoftSmoothSection {
@@ -536,6 +562,8 @@ export interface GeometryKernel {
   helixSweptTube(o: HelixSweptTubeOptions): Solid;
   /** Sweep an axial lathe profile by screw motion — threads. */
   screwSweep(o: ScrewSweepOptions): Solid;
+  /** A tapped hole as one cut tool — bore plus thread, never tangent. */
+  tappedBore(o: TappedBoreOptions): Solid;
   /** Spline-interpolated loft of sparse control sections. */
   loftSmooth(o: LoftSmoothOptions): Solid;
   /** Rim round-overs via one lathe revolve; curve-exact in STEP. */