partforge 0.62.1 → 0.63.0

package/docs/AUTHORING-PARTS.md

@@ -2093,6 +2093,29 @@ print faceted — or the reverse — set the hint rather than changing facet cou
 > (Manifold-only topology); `render` works on both. Filleted parts now measure on
 > Manifold with full topology.
 
+### `roundAll(r)` — round everything at once
+
+`s.roundAll(2)` (or `s.roundAll({ r: 2 })`) rounds **every** edge of the solid
+— convex and concave — with radius ≈ 2 mm in one pass, on both backends, with
+no OCCT routing. Faces stay in place (within backend tolerance). It is the
+blunt, global counterpart to `fillet`/`chamfer`: there is no edge selection,
+and features smaller than the ball are **consumed** — walls thinner than `2r`
+melt away, holes narrower than `2r` seal shut. That makes it ideal for
+"soften this whole organic part" and wrong for parts where a specific edge
+must stay sharp (use `fillet` with a selector for that).
+
+Rules of thumb:
+
+- Keep `r` under half your thinnest wall unless you *want* melting.
+- Preview and STL/3MF export always work (mesh morphology). STEP export gets
+  true B-rep arc surfaces while `r` is below the smallest feature size; at
+  consuming radii OCCT cannot represent the melt and **skips the op whole**
+  with a `roundall-skipped` warning — the STEP then has the un-rounded shape.
+- Relying on consumption? Add a `verify` volume assertion so a regression in
+  the radius (or a backend skip) fails loudly.
+- A small ridge remaining where a thin rib was consumed is correct morphology
+  (the rib's dilation fillet survives the opening), not a bug.
+
 ### Cost on the OCCT path: fillet/chamfer scale with edge count — and order matters
 
 These costs apply when a sub-part **does** run on OCCT (a shell, an unsupported edge

package/docs/ERROR-PATTERNS.md

@@ -101,6 +101,12 @@ Variant literals under this entry: `extrude: unknown bevel option`, `extrude: be
 - **Cause:** OCCT's native fillet cannot build the rim round-over at a degenerate boundary (e.g. a rim radius exactly equal to `round.side` on a stadium profile, `2·side == min(w, d)`) and would otherwise return invalid-but-nonempty geometry; the monotonicity/validity gate in `occt-repair.js`'s `safeOp` catches it and skips the feature rather than exporting invalid STEP.
 - **Fix:** shrink the affected rim radius slightly below `round.side` (or below the degenerate boundary), or accept the sharp rim at that exact radius.
 
+## roundall-skipped
+
+- **Symptom:** console warning `partforge: roundall-skipped: offset step … produced no valid solid — r=… is likely at/above the smallest feature size; returning the un-rounded solid`, and the OCCT build (STEP export, CLI measure with the OCCT backend) shows sharp edges where `roundAll` was expected.
+- **Cause:** the B-rep backend implements `roundAll` as a triple OCCT offset, which cannot change topology: a radius at or above the smallest local feature (thin wall < 2r, hole < 2r) has no valid B-rep offset result, so the op skips whole rather than emit garbage (KERNEL-CONTRACT.md, `roundAll` row). The mesh backend meanwhile performs true consumption — so preview and STEP legitimately differ in this regime.
+- **Fix:** reduce `r` below half the smallest wall/hole radius if STEP fidelity matters; or accept the divergence (preview/STL are correct) and gate the part with a `verify` volume assertion so the behavior is intentional.
+
 ## boolean-not-watertight
 
 - **Symptom:** `NOT watertight ✗` from `partforge measure` (non-zero exit) after adding a boolean cut or union.

package/docs/KERNEL-CONTRACT.md

@@ -1,6 +1,6 @@
 # The partforge kernel contract
 
-**Contract version: 3** (introduced in partforge 0.62) — mirrored by `CONTRACT_VERSION`
+**Contract version: 4** (introduced in partforge 0.63) — mirrored by `CONTRACT_VERSION`
 in `src/framework/geometry/kernel.js` and asserted by `test/kernel-contract.test.js`;
 see [Versioning](#versioning) for what may change under which version bump.
 
@@ -68,6 +68,20 @@ Its coverage and tolerance band are part of the contract:
   labels upstream of the call do not survive through it (attribution uses the
   fallback path), and the result shades with the default SMOOTH policy.
 
+`roundAll` is required on **every** class (it is in `SOLID_OPS`, not
+`OCCT_ONLY_OPS`) and is **parity-tolerant with a regime split**: while `r` is
+strictly below the solid's smallest feature size (min wall, min hole
+diameter / 2), both classes produce the morphological result and volumes agree
+within the mesh-tolerance band. That band is stated at the **export (print)
+tier**, where the mesh class's tessellation is fine enough to compare against
+B-rep arcs (box and L-bracket cases: ≤ 0.05%); the preview tier is coarser by
+design and runs ~0.2% below the B-rep volume, which is tessellation, not a
+parity failure. At consuming radii, only the core (mesh) class
+performs true consumption; a B-rep class MUST either produce a valid solid or
+skip the entire op (returning the input unchanged, warning `roundall-skipped`)
+— emitting an invalid or semantically wrong solid is non-conforming. Authors
+relying on consumption should gate it with a `verify` volume assertion.
+
 **B-rep class.** Core plus native `fillet`/`chamfer`/`shell` and `toSTEP`. The in-repo
 OCCT/replicad backend is the reference.
 
@@ -304,6 +318,7 @@ Normative signatures: `kernel.js`'s `@typedef Solid`.
 | `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})` | `fillet`/`chamfer`: implemented on BOTH in-repo classes since v3 — exactly on B-rep, tolerance-band on the mesh class for straight and circular-arc edge chains (see [Conformance classes](#conformance-classes)); an edge class the mesh kernel cannot blend throws `KernelCapabilityError` and reroutes. Zero magnitude — `fillet(0)` / `chamfer({d: 0})` — 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` remains B-rep-only (core throws), hollows inward keeping outer dimensions; `open` (face selector) is required. |
+| `roundAll(r)` · `roundAll({r})` | Morphological close-then-open with a ball of radius `r`: rounds EVERY edge (convex and concave) at radius ≈ `r`; faces stay in place (within the class's tolerance band — the B-rep offset chain can drift ~0.1 mm); features smaller than the ball are consumed (walls < 2r melt, holes < 2r seal). Implemented natively on BOTH classes — never routes, never throws `KernelCapabilityError`. Parity-tolerant only while `r` is below the smallest feature size; at consuming radii the mesh class performs true consumption and a B-rep class MAY skip the whole op unchanged with a `roundall-skipped` warning (skip is the only permitted degrade). `roundAll(0)` is the identity on every class. |
 
 `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
@@ -680,6 +695,13 @@ in `kernel.js` define the current surface; only breaking changes bump the versio
   `cut` per CadQuery/replicad rather than OpenSCAD's `difference`), so LLM priors
   transfer. Renames are breaking changes with no offsetting benefit — don't.
 
+**v3 → v4** (partforge 0.63): `Solid.roundAll` is added to `SOLID_OPS` (portable
+morphological rounding — rounds every edge with a ball of radius `r`;
+parity-tolerant, regime-split semantics, see
+[Conformance classes](#conformance-classes)). Additive for parts — nothing
+existing calls it — but breaking for backend implementers: a core kernel must
+now implement it (no stub, unlike the `OCCT_ONLY_OPS` ops).
+
 **v2 → v3** (partforge 0.62): `Solid.fillet` and `Solid.chamfer` are implemented
 natively on the mesh (core reference) kernel for straight and circular-arc edge
 chains, and are **no longer probe-routed to OCCT** — `ROUTED_CAD_OPS` (`shell`) is

package/package.json

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

@@ -16,7 +16,7 @@
 // The prose half's version: docs/KERNEL-CONTRACT.md's "Contract version" header
 // must match this number (asserted in kernel-contract.test.js). Bump only on a
 // breaking contract change — see the doc's Versioning section.
-export const CONTRACT_VERSION = 3;
+export const CONTRACT_VERSION = 4;
 
 // Ops every backend kernel must implement.
 export const KERNEL_OPS = [
@@ -38,7 +38,7 @@ export const SOLID_OPS = [
   "cut", "cutAll", "intersect", "union", "clone", "label", "boundingBox", "volume",
   "translate", "rotate", "rotateX", "rotateY", "rotateZ", "rotateAbout", "along", "at",
   "mirror", "scale", "toMesh", "toSTL", "toIndexedMesh",
-  "fillet", "chamfer", "shell",
+  "fillet", "chamfer", "shell", "roundAll",
 ];
 
 // Backend-optional Solid queries: Manifold mesh-topology numbers (measure.js

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

@@ -13,6 +13,7 @@ import { meshToStl } from "./mesh-stl.js";
 import { creasedNormals } from "./creased-normals.js";
 import { loftShadingPolicy, SMOOTH } from "./shading-policy.js";
 import { meshFillet, meshChamfer, UnsupportedEdgeError } from "./mesh-fillet.js";
+import { meshRoundAll } from "./mesh-roundall.js";
 import { KernelCapabilityError } from "./errors.js";
 
 const PLANE_NORMAL = { XY: [0, 0, 1], XZ: [0, 1, 0], YZ: [1, 0, 0] };
@@ -143,6 +144,14 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
       return cached(h("chamfer", hash, d, selector ?? null, segs), () =>
         meshCadOp("chamfer", () => meshChamfer(kernel, wrap(m, hash), { d, edges: selector, segs })));
     },
+    roundAll: (r) => {
+      if (r === 0) return wrap(m, hash); // contract: zero magnitude is the identity
+      // `quality` in the key is redundant but harmless — the cache lives on a
+      // per-quality kernel, so it can never collide across tiers (the OCCT twin
+      // key omits it for the same reason); it just spells out that the ball
+      // tessellation, and so the result, is tier-dependent.
+      return cached(h("roundAll", hash, r, quality), () => T(meshRoundAll(wasm, m, r, quality)));
+    },
     cutAll: (tools) => cached(h("cutAll", hash, tools.map((t) => t._hash)),
       () => T(m.subtract(unionRaw(tools.map((t) => t._m))))),
     intersect: (t) => cached(h("intersect", hash, t._hash), () => T(m.intersect(t._m))),

package/src/framework/geometry/mesh-roundall.js

@@ -0,0 +1,83 @@
+// Morphological whole-solid rounding on the mesh backend: close-then-open with
+// a ball — dilate(+r), erode(2r), dilate(+r) via Manifold's native Minkowski
+// sum/difference. Rounds EVERY edge (convex and concave) at radius ≈ r and
+// consumes features smaller than the ball (walls < 2r melt, holes < 2r seal) —
+// that is the op's contract, not a defect (docs/roundall-design.md).
+//
+// simplify() between steps is mandatory, not an optimization: the naive
+// Minkowski (hull-of-triangle-pairs) emits sliver-degenerate meshes whose
+// complexity compounds through the chain — the design spike measured 106s and
+// 761k broken-topology triangles without it vs 2.4s and 340 clean triangles
+// with it, on the same torture case. asOriginal() first, because simplify()
+// will not collapse triangles across run (originalID) boundaries and the
+// Minkowski output is stitched from many.
+//
+// This op must NEVER throw KernelCapabilityError / NEEDS_OCCT: the mesh
+// backend is roundAll's reference implementation — rerouting to OCCT would
+// trade a correct result for a skip (occt-roundall.js can only skip where
+// morphology exceeds what B-rep offsets support).
+//
+// INVARIANT — both balls share ONE segment count. Minkowski support functions
+// add, so the chain displaces a face with normal n by 2·h_r(n) − h_2r(n), where
+// h is the ball's support. Manifold spheres built with equal `segs` are similar
+// (the 2r ball is the r ball scaled by two), so h_2r = 2·h_r and the term is
+// exactly zero in EVERY direction — the input's planar faces return to their
+// original planes. Give the two balls different segment counts and the term is
+// only zero where a vertex happens to line up: axis-aligned boxes still look
+// right while off-axis faces drift (measured 0.07mm at preview, r=2). The count
+// is sized from the erosion ball (2r), the larger of the two, so the coarser of
+// the two facetings still meets the tier's sagitta tolerance.
+
+// Sphere tessellation from the facet sagitta r·(1 − cos(π/segs)): pick the
+// fewest segments that keep it under the quality tier's tolerance.
+const SAGITTA_TOL = { preview: 0.05, print: 0.01 }; // mm
+export function roundAllSegs(r, quality) {
+  const tol = SAGITTA_TOL[quality] ?? SAGITTA_TOL.preview;
+  if (!(r > tol)) return 12;
+  return Math.min(64, Math.max(12, Math.ceil(Math.PI / Math.acos(1 - tol / r))));
+}
+
+export function meshRoundAll(wasm, m, r, quality) {
+  if (!Number.isFinite(r) || r <= 0) throw new Error("roundAll: r must be a finite number > 0 (r = 0 is handled as the identity by the caller)");
+  const segs = roundAllSegs(2 * r, quality); // ONE count for BOTH balls — see the invariant above
+  // Simplify tolerance: max(r/100, 0.01) mm, but never enough to collapse the
+  // rim ring of a rounded edge into the next ring up. That ring sits
+  // r·(1 − cos(2π/segs)) above the face plane, and it is what holds a planar
+  // face at its exact position; collapsing it shaves the face inward (print
+  // tier, r = 2: segs 45 puts the ring 0.0195 mm up, and a flat 0.02 tolerance
+  // pulled every face of a box in by 0.034 mm). Half that spacing keeps margin.
+  const tol = Math.min(Math.max(r / 100, 0.01), 0.5 * r * (1 - Math.cos((2 * Math.PI) / segs)));
+  const step = (input, sphere, op) => {
+    const raw = op === "sum" ? input.minkowskiSum(sphere) : input.minkowskiDifference(sphere);
+    let orig;
+    try {
+      orig = raw.asOriginal();
+    } finally {
+      raw.delete?.();
+    }
+    try {
+      return orig.simplify(tol);
+    } finally {
+      orig.delete?.();
+    }
+  };
+  const sphR = wasm.Manifold.sphere(r, segs);
+  const sph2R = wasm.Manifold.sphere(2 * r, segs);
+  try {
+    const a = step(m, sphR, "sum");          // dilate: rounds convex, seals holes < 2r
+    let b;
+    try {
+      b = step(a, sph2R, "diff");        // erode 2r: melts walls < 2r
+    } finally {
+      a.delete?.();
+    }
+    try {
+      return step(b, sphR, "sum");          // dilate back: final radius ≈ r everywhere
+    } finally {
+      b.delete?.();
+    }
+  } finally {
+    sphR.delete?.();
+    sph2R.delete?.();
+  }
+}

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

@@ -21,6 +21,7 @@ import { addSugar } from "./solid-sugar.js";
 import { makeShape2dFactory } from "./shape2d.js";
 import { finishKernel } from "./kernel-front.js";
 import { createOcctRepair } from "./occt-repair.js";
+import { occtRoundAll } from "./occt-roundall.js";
 import { classifyFaceGroups } from "./feature-attribution.js";
 import { resolveRings } from "./loft.js";
 import { resolveSweepStations } from "./sweep.js";
@@ -223,6 +224,14 @@ export function createOcctKernel(replicad) {
           return wrap(validChamfer(a._s, toEdgeFinder(selector), distance), cloneLabels(a._labels), key);
         });
       },
+      roundAll: (r) => {
+        const key = h("roundAll", hash, r);
+        return cached(key, () => {
+          const a = mat();
+          if (r === 0) return wrap(a._s.clone(), cloneLabels(a._labels), key);
+          return wrap(occtRoundAll(replicad, a._s, r), cloneLabels(a._labels), key);
+        });
+      },
       shell: (thickness, openFaces) => {
         if (openFaces == null) throw new Error("shell: openFaces is required (a fully closed hollow is not supported)");
         const key = h("shell", hash, thickness, selKey(openFaces));

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

@@ -0,0 +1,94 @@
+// B-rep side of roundAll: dilate(+r), erode(-2r), dilate(+r) via raw OCCT
+// BRepOffsetAPI_MakeOffsetShape (replicad has no solid-offset wrapper). Each
+// step runs a variant cascade — the design spike showed no single parameter
+// combo survives all shapes: plain solids dilate with Arc/Intersection=false,
+// the chained erosion only succeeds with Arc/Intersection=true, and concave
+// post-boolean solids only dilate with the Intersection join (morphologically
+// fine: the FINAL Arc dilation supplies the convex rounding).
+//
+// A candidate is accepted only if IsDone, non-null, closed (mesh check),
+// finite positive volume, AND volume-monotonic (dilation must not shrink,
+// erosion must not grow). The monotonic gate is load-bearing: OCCT offsets
+// return BRepCheck-valid garbage — the spike saw an erosion "succeed" at 0.4%
+// of the input volume, and a sealed hole come back as an 11% crater. A gated
+// failure skips the WHOLE op (warn + clone), mirroring safeOp's fillet policy
+// and for the same reason: OCCT offset failures are not monotonic in r, so
+// searching for a "largest working radius" would converge on garbage.
+// Feature-consuming radii (r at/above the smallest feature) are the expected
+// skip trigger — true consumption is mesh-class-only (docs/roundall-design.md).
+//
+// Every WASM object made here is freed, same convention as occt-repair.js, so
+// OCCT's heap doesn't grow across regenerates: up to twelve offset builders and
+// progress ranges, every rejected candidate, and each superseded intermediate.
+// The one thing never freed is the caller's `shape` — it belongs to the caller,
+// and the skip path hands back a clone of it.
+import { isClosedSolid } from "./occt-repair.js";
+
+const VARIANTS = [
+  { join: "arc", inter: false },
+  { join: "arc", inter: true },
+  { join: "int", inter: false },
+  { join: "int", inter: true },
+];
+
+export function occtRoundAll(replicad, shape, r) {
+  if (!Number.isFinite(r) || r <= 0) throw new Error("roundAll: r must be a finite number > 0 (r = 0 is handled as the identity by the caller)");
+  const oc = replicad.getOC();
+  const tryOffset = (topo, offset, v) => {
+    const progress = new oc.Message_ProgressRange_1();
+    const mk = new oc.BRepOffsetAPI_MakeOffsetShape();
+    try {
+      mk.PerformByJoin(topo, offset, 1e-6,
+        oc.BRepOffset_Mode.BRepOffset_Skin, v.inter, false,
+        v.join === "arc" ? oc.GeomAbs_JoinType.GeomAbs_Arc : oc.GeomAbs_JoinType.GeomAbs_Intersection,
+        false, progress);
+      if (!mk.IsDone()) return null;
+      const s = mk.Shape();
+      // Wrap BEFORE the finally frees the builder — replicad's own idiom for this
+      // very algorithm (its `offset()` does `cast(offsetBuilder.Shape()); offsetBuilder.delete()`).
+      // The wrapper carries its own TopoDS_Shape handle, so the result outlives `mk`.
+      return s.IsNull() ? null : new replicad.Solid(s);
+    } catch {
+      return null;
+    } finally {
+      mk.delete?.();
+      progress.delete?.();
+    }
+  };
+  let vol;
+  try {
+    vol = replicad.measureVolume(shape);
+  } catch (e) {
+    // Can't gate what can't be measured — skip rather than run the cascade blind.
+    console.warn(`partforge: roundall-skipped: the input solid's volume could not be measured (${e?.message || e}); returning the un-rounded solid`);
+    return shape.clone(); // if the clone throws too, the caller's shape is unusable — let it propagate
+  }
+  let cur = shape;
+  for (const off of [r, -2 * r, r]) {
+    let next = null;
+    for (const v of VARIANTS) {
+      const cand = tryOffset(cur.wrapped, off, v);
+      if (!cand) continue;
+      let cvol;
+      try { cvol = replicad.measureVolume(cand); } catch { cand.delete?.(); continue; }
+      if (!Number.isFinite(cvol) || cvol <= 0) { cand.delete?.(); continue; }
+      if (off > 0 && cvol < vol * 0.999) { cand.delete?.(); continue; } // dilation shrank: garbage
+      if (off < 0 && cvol > vol * 1.001) { cand.delete?.(); continue; } // erosion grew: garbage
+      // isClosedSolid meshes the candidate, and meshing OCCT offset garbage can
+      // throw — that is just another rejected candidate, not an escape hatch out
+      // of "roundAll never throws for geometry".
+      try { if (!isClosedSolid(cand)) { cand.delete?.(); continue; } }
+      catch { cand.delete?.(); continue; }
+      next = cand;
+      vol = cvol;
+      break;
+    }
+    if (cur !== shape) cur.delete?.(); // superseded intermediate; never the caller's shape
+    if (!next) {
+      console.warn(`partforge: roundall-skipped: offset step ${off} produced no valid solid — r=${r} is likely at/above the smallest feature size; returning the un-rounded solid`);
+      return shape.clone();
+    }
+    cur = next;
+  }
+  return cur;
+}

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

@@ -289,6 +289,8 @@ export const SOLID_OP_SPECS = {
     return [req("chamfer", o, "d"), ...(o.edges !== undefined ? [o.edges] : [])]; } },
   shell:   { toArgs: (o) => { checkKeys("shell", o, ["t", "open"]);
     return [req("shell", o, "t"), req("shell", o, "open")]; } },
+  roundAll: { toArgs: (o) => { checkKeys("roundAll", o, ["r"]);
+    return [req("roundAll", o, "r")]; } },
 };
 
 // A zero-magnitude fillet/chamfer is the identity on every conformance class

package/types/kernel.d.ts

@@ -269,6 +269,12 @@ export interface Solid {
    * Closed (no open face) hollows are not supported.
    */
   shell(o: { t: number; open: FaceSelector }): Solid;
+  /**
+   * Morphological close-then-open with a ball of radius `r`: rounds EVERY edge
+   * (convex and concave). Implemented natively on both backends — never routes,
+   * never throws `KernelCapabilityError`. `roundAll(0)` is the identity.
+   */
+  roundAll(r: number | { r: number }): Solid;
   /** Through-hole count (Manifold only). */
   genus?(): number;
   /** No geometry at all (Manifold only). */