partforge 0.61.0 → 0.62.1

package/README.md

@@ -42,9 +42,10 @@ preset, or be hidden, so the interface stays simple while the part stays deeply
 Two geometry backends run in Web Workers, and partforge routes each part to whichever it
 needs:
 
-- **[Manifold](https://github.com/elalish/manifold)** — fast preview meshes and STL / 3MF.
-- **[Replicad](https://replicad.xyz)** (OpenCASCADE-in-WebAssembly) — exact B-rep for STEP
-  export and native fillet / chamfer.
+- **[Manifold](https://github.com/elalish/manifold)** — fast preview meshes and STL / 3MF,
+  including mesh-native fillet and chamfer for straight and circular edges.
+- **[Replicad](https://replicad.xyz)** (OpenCASCADE-in-WebAssembly) — exact B-rep for STEP,
+  shell, and automatic fallback for blend geometry Manifold cannot handle.
 
 The viewer is [three.js](https://threejs.org).
 

package/bin/cli.js

@@ -4,6 +4,7 @@
 // parsed strictly per command with util.parseArgs, so a typo'd flag or a missing
 // option value fails loudly instead of being silently ignored.
 import { parseArgs } from "node:util";
+import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { resolve, dirname } from "node:path";
 import { writeFileSync, mkdirSync } from "node:fs";
@@ -35,6 +36,18 @@ const USAGE = "usage: partforge <lint|measure|render|pick-serve|pick> …";
 // Without --json there is no purity contract: human lines print as each stage
 // completes, so a later crash's message lands after them, not instead of them.
 function crash(cmd, e, jsonMode) {
+  // The mesh backend signals an edge class it can't blend (helical edge, varying
+  // dihedral, …) with NEEDS_OCCT. The two WASM kernels must never boot in one
+  // process, so the fallback is a re-exec of this exact command with the backend
+  // pinned to OCCT via the environment. One retry only — PARTFORGE_BACKEND set
+  // means we ARE the retry.
+  if (e?.code === "NEEDS_OCCT" && !process.env.PARTFORGE_BACKEND) {
+    console.error(`${cmd}: ${e.message} — retrying on the OCCT backend`);
+    const r = spawnSync(process.execPath, process.argv.slice(1), {
+      stdio: "inherit", env: { ...process.env, PARTFORGE_BACKEND: "occt" },
+    });
+    process.exit(r.status ?? 1);
+  }
   const message = e?.message || String(e);
   const m = matchPattern(message);
   if (jsonMode) {
@@ -63,7 +76,15 @@ async function loadPart(partPath, usage) {
   return part;
 }
 
-const bootKernel = (part) => (detectBackend(part) === "occt" ? bootOcctKernel() : bootManifoldKernel());
+// Pass the part's declared fonts through, mirroring the worker path (jobs.js) —
+// otherwise a part using a named font builds in the browser but dies headlessly
+// with `text2d: unknown font …`.
+const bootKernel = (part) => {
+  const backend = process.env.PARTFORGE_BACKEND || detectBackend(part); // env: crash()'s NEEDS_OCCT retry
+  return backend === "occt"
+    ? bootOcctKernel({ fonts: part.fonts })
+    : bootManifoldKernel({ fonts: part.fonts });
+};
 
 const commands = {
   async lint(args) {

package/docs/AUTHORING-PARTS.md

@@ -15,7 +15,7 @@ Two worked examples to read alongside this guide: **`src/parts/demo.js`** (a
 parametric spacer — the smallest complete part) and **`src/parts/planter.js`** (a
 faceted planter — facets, taper, twist, even walls, an optional feature, a `derive`,
 and a `verify` block). **`src/parts/filleted-box.js`** is the worked example for the
-OCCT-only fillet/chamfer/shell ops.
+portable Solid fillet/chamfer API and the OCCT-only shell op.
 
 ---
 
@@ -310,7 +310,7 @@ and the detection rule.
 | `k.loft({ rings, ruled?, closed?, shading? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls. `shading?: "smooth" \| "faceted"` overrides facet/smooth shading inference (default: <32-side rings shade as flat facets, drawing no same-surface lines at all — not even their own cap rims — though cut seams against other solids still draw; ≥32 sides shade smooth) |
 | `k.sweep({ profile, path, cornerRadius?, closed?, ruled?, smooth? })` | sweep a fixed 2-D profile along a 3-D polyline path — sharp mitered corners (or `cornerRadius` fillets), capped ends (both backends). `closed:true` capless loops and `smooth:true` (OCCT-native swept B-rep, STEP-exact / preview-faceted) are backend-specific, like loft's `closed`/`ruled:false`. `closed:true` loops must be **planar** — RMF frame-transport holonomy can seam-twist a non-planar closed loop where the last station rejoins the first, so only planar closed loops are supported/tested |
 | `k.sphere({ r\|d })` | sphere centred at the origin; bare `k.sphere(r)` also stays valid |
-| `k.roundedBox({ size, center?, round })` | box with rounded edges — `round` = number (all edges) or `{ side?, top?, bottom? }` (vertical edges / rims); stays on Manifold (no OCCT routing, unlike `fillet`); `side` must be 0 or ≥ the rim radii (between clamps with a warning); with `side > 0`, `top + bottom` must be strictly `< h` |
+| `k.roundedBox({ size, center?, round })` | box with rounded edges — `round` = number (all edges) or `{ side?, top?, bottom? }` (vertical edges / rims); built as one hand-meshed ring stack (no booleans at all, cheaper than `fillet`'s cutters); `side` must be 0 or ≥ the rim radii (between clamps with a warning); with `side > 0`, `top + bottom` must be strictly `< h` |
 | `k.roundedCylinder({ r\|d, h, center?, round })` | cylinder with rounded rims — `round` = number (both) or `{ top?, bottom? }`; `round: r` with `top+bottom = h` gives a sphere (capsule when `h > 2r`); one lathe revolve, curve-exact in STEP |
 | `k.torus({ rMajor, rMinor })` | torus centered at the origin (tube centerline in z=0); `0 < rMinor < rMajor` |
 | `k.revolve({ profile, degrees? })` | revolve a lathe profile `[[r,z],…]` (r ≥ 0) around the Z axis (full or partial) |
@@ -2013,12 +2013,16 @@ the requirement that exposed the failure.
 
 ---
 
-## Fillet & chamfer (automatic OCCT backend)
+## Fillet, chamfer & shell
 
 Two backends build your part: **Manifold** (fast meshes — preview, STL, 3MF) and
-**OCCT/replicad** (exact B-rep — STEP). Most parts run on Manifold. But Manifold has no
-fillet, so if your `build` calls a **CAD-only op** the framework automatically routes the
-whole part to OCCT — no declaration needed:
+**OCCT/replicad** (exact B-rep — STEP). Most parts run on Manifold — and since
+contract v3 that **includes fillet and chamfer**: the mesh backend blends straight
+edges and circular-arc edges (bore rims, cylinder rims, the arcs where fillets meet a
+face) natively, at exact radius to within tessellation. Only `shell` still routes a
+sub-part to OCCT up front; a fillet/chamfer on an edge class the mesh backend can't
+blend (helical edges, varying dihedral) reroutes that sub-part to OCCT automatically
+at runtime — no declaration needed either way:
 
 | Op | Meaning |
 |---|---|
@@ -2032,8 +2036,9 @@ whole part to OCCT — no declaration needed:
 - `{ inPlane: "XY"｜"XZ"｜"YZ", at }` — edges lying in a plane (e.g. base edges: `{inPlane:"XY", at:0}`)
 - `{ near: [x,y,z] }` — edges passing through a point
 - a raw `(edgeFinder) => edgeFinder` replicad finder, for anything fancier — **OCCT-only
-  escape hatch**: fine for a part that's happy to stay in this repo, but non-portable
-  (parts meant to travel must use the object forms — see `KERNEL-CONTRACT.md`)
+  escape hatch**: it forces the sub-part onto OCCT (the mesh backend reroutes on
+  sight of it) and is non-portable — parts meant to travel must use the object forms
+  (see `KERNEL-CONTRACT.md`)
 
 ```js
 let s = k.box({ min: [0, 0, 0], max: [40, 30, 16] });
@@ -2044,29 +2049,38 @@ s = s.chamfer({ d: 1, edges: { inPlane: "XY", at: 0 } }); // bevel the base
 See `src/parts/filleted-box.js` for the worked example.
 
 **Automatic backend selection.** Before building, the framework runs a geometry-free *probe*
-of your `build` to see whether it uses a CAD-only op **on a Solid**, and routes accordingly —
-Manifold for everything else (so sweep-heavy parts, e.g. helical grooves, stay fast). The
-probe tracks which handle kind each op ran on, so `Shape2D.fillet`/`.chamfer` (the shared,
-backend-identical 2-D implementations — see "Editing profiles") do *not* route a part to
-OCCT: rounding a profile before extruding keeps you on fast Manifold. Force the backend with
-`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.)
+of your `build`; a `shell` call **on a Solid** routes that sub-part to OCCT up front, and
+everything else — fillet and chamfer included — stays on fast Manifold. The probe tracks
+which handle kind each op ran on, so `Shape2D.fillet`/`.chamfer` (the shared,
+backend-identical 2-D implementations — see "Editing profiles") never look like Solid
+ops. Force the backend with `meta.backend: "occt" | "manifold"` if you ever need to.
+STEP export always builds on OCCT, so a filleted part gets exact B-rep blends in its
+STEP even though it previews (and STL/3MF-exports) from the mesh blend — the two agree
+to within tessellation on the supported edge classes, with one visible exception:
+orthogonal box-style corners where three filleted edges meet get a true sphere-octant
+cap, but other blend junctions are mitred on the mesh where OCCT builds a vertex
+blend.
+
+If the mesh backend hits an edge class it can't blend, it signals `NEEDS_OCCT` and the
+framework reroutes **just that sub-part** to OCCT for those exact parameters —
+dialing the parameter away re-tries 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.
+(`shell` is the exception: `t: 0` is degenerate, not identity, so a shell call always
+routes to OCCT.)
+
+**Clamp your radii.** The mesh fillet does **not** validate feasibility — an oversized
+radius self-intersects its cutters and yields a wrong shape rather than a skipped
+feature (OCCT skips instead). Clamp magnitudes against local geometry the way
+`filleted-box.js` does: `Math.min(p.fillet, halfWidth - 0.5, p.h - 0.5)`.
 
 **Preview routing is per sub-part.** Each sub-part is probed and routed independently, and
-a mixed part's regen fans out to both workers in parallel — a filleted body pays for OCCT
-while a plain lid rebuilds at Manifold speed beside it. This makes it worth isolating a
-CAD-op solid in its own sub-part rather than folding it into a bigger build. Two scopes
+a mixed part's regen fans out to both workers in parallel — a shelled body pays for OCCT
+while a plain lid rebuilds at Manifold speed beside it. Two scopes
 still route whole-part (the max over the sub-parts): **exports** (one STL/STEP/3MF job
 builds everything in one worker) and the **CLI** (a single Node process boots exactly one
-kernel). Within one sub-part's build there is no per-op backend mixing.
+kernel; on a mesh-side `NEEDS_OCCT` it re-runs itself once with the backend pinned to
+OCCT). Within one sub-part's build there is no per-op backend mixing.
 
 **Shading intent.** The kernel decides what shades smooth and where edge lines
 draw — spheres, cylinders and fillets are smooth by construction; boolean cut
@@ -2075,16 +2089,15 @@ rings have fewer than 32 sides (`shading: "smooth"|"faceted"` on `k.loft`
 overrides the inference either way). If your part previews smooth but would
 print faceted — or the reverse — set the hint rather than changing facet counts.
 
-> Trade-off: OCCT is much slower on heavy swept geometry (helical grooves), so don't reach for
-> `fillet`/`chamfer` on a sweep-heavy part — design those edges in, or keep the part on Manifold.
+> `partforge measure` reports `watertight`/`holes` as `n/a` for OCCT-run parts
+> (Manifold-only topology); `render` works on both. Filleted parts now measure on
+> Manifold with full topology.
 
-> `partforge measure` reports `watertight`/`holes` as `n/a` for OCCT parts (Manifold-only
-> topology); `render` works on both.
+### Cost on the OCCT path: fillet/chamfer scale with edge count — and order matters
 
-### Cost: fillet/chamfer scale with edge count — and order matters
-
-OCCT fillet/chamfer cost is **per selected edge**, on top of the OCCT boolean tax the
-routing already imposes on the rest of the part. Two habits keep it tolerable:
+These costs apply when a sub-part **does** run on OCCT (a shell, an unsupported edge
+class, a pinned backend, or STEP export). OCCT fillet/chamfer cost is **per selected
+edge**, on top of the OCCT boolean tax. Two habits keep it tolerable:
 
 - **Fillet/chamfer as early as possible, on the simplest solid.** A fillet on a bare
   primitive is ~15× cheaper than the same fillet after a dozen boolean cuts have

package/docs/ERROR-PATTERNS.md

@@ -52,13 +52,13 @@ 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 that sub-part to OCCT (preview routing is per sub-part; exports and the CLI route the whole part to the max over its sub-parts, since those jobs run in one worker/kernel). (`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.)
+- **Cause:** The geometry-free probe runs `build` against a recording proxy (dummy query values), and a **Solid** `shell` call it reaches — including a branch the real build would not take, since queries return dummies — routes that sub-part to OCCT. Fillet and chamfer are not probe-routed: they start on Manifold and reroute only if the mesh backend reports an unsupported edge class. Preview routing is per sub-part; exports and the CLI route the whole part to the max over its sub-parts because those jobs run in one worker/kernel.
+- **Fix:** Remove or guard the unnecessary `shell` call, or force the backend with `meta.backend: "manifold"` (or `"occt"`). See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Fillet, chamfer & shell". Routing re-runs with live params on every regen; a runtime `needs-occt` fallback is latched only for the current parameters, so a stale backend choice never outlives a parameter edit.
 
 ## fillet-chamfer-many-edges-slow
 
-- **Symptom:** A part that fillets or chamfers the rim of an extruded profile (a gear, a star, any many-point polygon) takes many seconds — even tens of seconds — per build, with no error anywhere.
-- **Cause:** OCCT fillet/chamfer cost scales with the number of selected edges, and an `inPlane` rim selector on a many-point extruded profile selects every polygon edge (hundreds for a gear), so one op call costs seconds — and re-runs on every parameter change.
+- **Symptom:** A part on the OCCT path (unsupported-edge fallback, forced backend, CLI fallback, or STEP export) fillets or chamfers the rim of an extruded profile and takes many seconds — even tens of seconds — per build, with no error anywhere.
+- **Cause:** OCCT fillet/chamfer cost scales with the number of selected edges, and an `inPlane` rim selector on a many-point extruded profile selects every polygon edge (hundreds for a gear), so one op call costs seconds — and re-runs on every parameter change while that path is active.
 - **Fix:** Use `extrude`'s `bevel` option instead of `chamfer` — same geometry, stays on the fast Manifold backend. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Beveling profile rims: extrude's bevel option".
 
 ## chamfer-rescue-bisection
@@ -539,6 +539,18 @@ exposure is a `build()` that queries a twisted solid's box itself, which is the
 normal idiom for placing something relative to a solid and now silently disagrees
 between the Manifold preview and the OCCT STEP export.
 
+## mesh-fillet-unsupported-edge
+
+- **Symptom:** `fillet: ` or `chamfer: ` followed by an edge-class reason — e.g. `edge curve is not circular`, `flank angle varies along the arc`, `selector matched no sharp edges`, `~180° knife edge` — thrown as a `KernelCapabilityError`, or a preview sub-part silently rebuilding on the slow OCCT worker.
+- **Cause:** The mesh backend's native fillet/chamfer (`mesh-fillet.js`) covers straight and circular-arc sharp-edge chains; the selected edges fall outside that (helical edge, varying dihedral, non-circular curve, or nothing sharp matched), so the op signals `NEEDS_OCCT` and the framework reroutes that sub-part (the CLI re-execs once with `PARTFORGE_BACKEND=occt`).
+- **Fix:** Usually nothing — the reroute is the designed degrade and the OCCT result is correct, just slower. To stay on Manifold, restructure so the blend lands on a supported edge class (design the rounding into the profile, or fillet before the boolean that curves the edge). See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Fillet, chamfer & shell".
+
+## mesh-fillet-oversized-radius
+
+- **Symptom:** A Manifold-built fillet/chamfer produces a mangled or over-cut shape (no error), where the same part on OCCT would skip the feature with a `fillet(…) failed` warning.
+- **Cause:** The mesh fillet does not validate radius feasibility — a magnitude larger than the local geometry self-intersects its cutter solids and the booleans happily apply them.
+- **Fix:** Clamp the magnitude against local dimensions in the part (`Math.min(p.fillet, halfWidth - 0.5, …)` — see `src/parts/filleted-box.js`), which is required practice on the mesh class per [KERNEL-CONTRACT.md](KERNEL-CONTRACT.md) § "Mesh degrade policy".
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/docs/KERNEL-CONTRACT.md

@@ -1,6 +1,6 @@
 # The partforge kernel contract
 
-**Contract version: 2** (introduced in partforge 0.59) — mirrored by `CONTRACT_VERSION`
+**Contract version: 3** (introduced in partforge 0.62) — 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.
 
@@ -14,7 +14,7 @@ geometry. There is deliberately no separate file format or DSL.
 The contract has two halves:
 
 - **Machine-checked:** the op lists in `src/framework/geometry/kernel.js`
-  (`KERNEL_OPS`, `SOLID_OPS`, `OCCT_ONLY_OPS`, `*_OPTIONAL_OPS`) and their `@typedef`
+  (`KERNEL_OPS`, `SOLID_OPS`, `OCCT_ONLY_OPS`, `ROUTED_CAD_OPS`, `*_OPTIONAL_OPS`) and their `@typedef`
   signatures. `test/kernel-contract.test.js` and the OCCT twin in
   `test/occt-backend.test.js` assert each backend exposes exactly these ops, so the list
   cannot silently drift from the implementations. **Those lists are normative.**
@@ -38,11 +38,35 @@ every `Solid` op in `SOLID_OPS`, *except* that the B-rep ops (`fillet`, `chamfer
 **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).
+identity) and always throws on core. Kernels built from this repo get the stubs for
+free: `addSugar()` generates the Solid-level stubs (including the zero-magnitude
+identity) for whichever `OCCT_ONLY_OPS` a backend leaves undefined, and
+`finishKernel()` stubs `toSTEP` (a kernel-level op, so it is not in that Solid-op
+list).
+
+**The in-repo Manifold backend is the reference core kernel, and since contract v3 it
+implements `fillet` and `chamfer` natively** (`mesh-fillet.js` — tangent-tool CSG).
+Its coverage and tolerance band are part of the contract:
+
+- **Edge classes:** straight sharp edges with planar flanks, and circular-arc sharp
+  edges whose flanks are surfaces of revolution about the arc axis (bore rims,
+  cylinder rims, the arcs where blends meet a face) — full circles included. Convex
+  edges subtract a cutter; concave edges union a filler. Any other edge class
+  (helical edges, varying dihedral, non-circular curves, function selectors) throws
+  `KernelCapabilityError` so the host can reroute that build to a B-rep kernel.
+- **Tolerance band, not identity:** the blend surface is the exact rolling-ball
+  (fillet) or setback-chord (chamfer) surface to within tessellation, plus
+  micron-scale robustness allowances (tool overshoot past tangency and seam-grazing
+  guards, all ≤ ~1e-3 mm). Volumes agree with the B-rep result to ~0.1% on covered
+  edge classes. **Corners:** where exactly three selected straight convex chains meet
+  at a mutually orthogonal vertex (a box corner), the fillet caps it with the
+  rolling-ball sphere octant; every other junction of blended chains is a **mitre**
+  (the blend surfaces intersect), where the B-rep class builds a kernel-specific
+  vertex blend instead — parity at such corners is approximate, like `roundedBox`'s
+  documented corner carve-out.
+- **New surfaces:** like the B-rep op, a mesh blend produces new surfaces — feature
+  labels upstream of the call do not survive through it (attribution uses the
+  fallback path), and the result shades with the default SMOOTH policy.
 
 **B-rep class.** Core plus native `fillet`/`chamfer`/`shell` and `toSTEP`. The in-repo
 OCCT/replicad backend is the reference.
@@ -56,13 +80,18 @@ a part (never inside a `beginSubPart`/`endSubPart` bracket), it drops cache part
 have gone unbuilt for three consecutive rebinds.
 
 `KernelCapabilityError` is a *routing signal*, not a failure: partforge's geometry-free
-probe (`probe.js`) runs `build` against a fake kernel, and any use of an `OCCT_ONLY_OPS`
-op **on a Solid handle** routes the build to a B-rep-class kernel (the probe tracks
-handle kinds, so the same names on a `Shape2D` — shared pure JS, backend-identical — do
-not route). Routing granularity is a host choice: the in-repo framework routes preview
-builds per sub-part (each sub-part builds wholly on one kernel) and exports/CLI whole-
-part; a single-kernel host routes everything whole-part. A host with only a core kernel
-must surface the error ("this part needs a B-rep backend") rather than swallow it.
+probe (`probe.js`) runs `build` against a fake kernel, and any use of a
+`ROUTED_CAD_OPS` op (`shell`, since v3) **on a Solid handle** routes the build to a
+B-rep-class kernel up front (the probe tracks handle kinds, so the same names on a
+`Shape2D` — shared pure JS, backend-identical — do not route). `fillet`/`chamfer` are
+**not probe-routed anymore**: the core kernel attempts them, and throws
+`KernelCapabilityError` only for an edge class it cannot blend — which the in-repo
+framework's runtime reroute latch (`backend-select.js`) converts into a per-sub-part
+OCCT fallback, and the CLI into a re-exec on the OCCT kernel. Routing granularity is a
+host choice: the in-repo framework routes preview builds per sub-part (each sub-part
+builds wholly on one kernel) and exports/CLI whole-part; a single-kernel host routes
+everything whole-part. A host with only a core kernel must surface the error ("this
+part needs a B-rep backend") rather than swallow it.
 
 ## Global semantics
 
@@ -274,7 +303,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`), *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. |
+| `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. |
 
 `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
@@ -337,6 +366,15 @@ garbage). A failing chamfer instead binary-searches the largest valid distance.
 conforming B-rep kernel must degrade this way — a fillet request must never brick the
 build, and authors should expect all-or-nothing filleting per call, not per edge.
 
+**Mesh degrade policy** (`mesh-fillet.js`): the mesh class degrades by *rerouting*, not
+skipping — an unsupported edge class or an empty selection throws
+`KernelCapabilityError` and the framework retries the build on the B-rep kernel, which
+then applies its own repair policy. One asymmetry is deliberate: the mesh class does
+**not** validate radius feasibility (an oversized radius yields self-intersecting tools
+and a wrong shape rather than a skipped feature), so parts should clamp magnitudes
+against local geometry the way `filleted-box.js` does — good practice on both classes,
+mandatory on this one.
+
 ## Shape2D (2-D booleans)
 
 `k.shape2d(profile)` (`KERNEL_OPS`) lifts a point list, `{outer,
@@ -642,6 +680,18 @@ 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.
 
+**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
+the remaining probe-routing set, and unsupported edge classes reroute at runtime via
+`KernelCapabilityError`. Semantics change for existing parts: a part using fillet or
+chamfer now previews (and STL/3MF-exports) from the mesh kernel's tolerance-band
+blend instead of paying for the OCCT worker; STEP export still uses OCCT's exact
+blends. Behavioral deltas to re-measure when migrating: vertex junctions between
+blended chains are mitred rather than corner-blended, radius feasibility is not
+validated on the mesh class (clamp in the part), and a fillet/chamfer that previously
+*failed and was skipped* by OCCT's repair policy may now build (mesh) or reroute.
+
 **v1 → v2** (partforge 0.59): `Shape2D.offset` moved off the two per-backend 2-D
 engines (Clipper2 via `CrossSection` on Manifold, replicad's `Drawing.offset` on
 OCCT) onto the single native contour-offset engine described above. Semantics

package/package.json

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

@@ -26,11 +26,9 @@ export function detectBackends(part, params = {}) {
     if (forced) { backends[name] = forced; continue; }
     const { kernel, cadCalls } = createProbeKernel();
     try { part.parts[name].build(kernel, p, d); } catch { /* probe miss → capability backstop covers it */ }
-    // cadCalls holds only Solid-handle fillet/chamfer/shell — `Shape2D.fillet`/
-    // `.chamfer` are the shared pure-JS implementation (backend-identical) and must
-    // not drag a sub-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 sub-part back onto Manifold with no `if (r > 0)` guard in the build.
+    // cadCalls currently holds only Solid.shell calls. Solid fillet/chamfer start
+    // on Manifold and use the runtime capability backstop below only when the mesh
+    // backend cannot blend the selected edge class; Shape2D variants are shared JS.
     backends[name] = cadCalls.some(({ op, args }) => !isZeroMagnitudeCadOp(op, args))
       ? "occt"
       : "manifold";
@@ -51,7 +49,7 @@ export function detectBackend(part, params = {}) {
 // (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
+// or turning the unsupported feature off never reverts to Manifold. Instead the
 // reroute is latched per (sub-part, params snapshot): the exact combination that
 // failed skips the doomed Manifold retry, and ANY param change re-consults the
 // probe. A part the probe chronically under-detects costs one cheap failed

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

@@ -38,15 +38,20 @@ export function creasedNormals(g, { policies = null, featureLabels = null } = {}
   for (let r = 0; r < roid.length; r++)
     for (let t = ri[r] / 3; t < ri[r + 1] / 3; t++) triOID[t] = roid[r];
 
-  // per-triangle face normals
+  // per-triangle face normals, plus each triangle's minimum height (2·area /
+  // longest edge) — the "thinness" the feature-edge pass gates on below
   const fn = new Float32Array(nTri * 3);
+  const thin = new Float32Array(nTri);
   for (let t = 0; t < nTri; t++) {
     const a = tris[t * 3] * np, b = tris[t * 3 + 1] * np, c = tris[t * 3 + 2] * np;
     const ux = vp[b] - vp[a], uy = vp[b + 1] - vp[a + 1], uz = vp[b + 2] - vp[a + 2];
     const vx = vp[c] - vp[a], vy = vp[c + 1] - vp[a + 1], vz = vp[c + 2] - vp[a + 2];
+    const wx = vp[c] - vp[b], wy = vp[c + 1] - vp[b + 1], wz = vp[c + 2] - vp[b + 2];
     const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
     const L = Math.hypot(nx, ny, nz) || 1;
     fn[t * 3] = nx / L; fn[t * 3 + 1] = ny / L; fn[t * 3 + 2] = nz / L;
+    const longest = Math.max(ux * ux + uy * uy + uz * uz, vx * vx + vy * vy + vz * vz, wx * wx + wy * wy + wz * wz);
+    thin[t] = longest > 0 ? L / Math.sqrt(longest) : 0; // |cross| / maxEdge = min height
   }
 
   // canonical vertex → incident triangles
@@ -94,6 +99,13 @@ export function creasedNormals(g, { policies = null, featureLabels = null } = {}
       const prev = seenEdge.get(key);
       if (prev === undefined) { seenEdge.set(key, t); continue; }
       seenEdge.delete(key);
+      // Sub-visible slivers never emit feature lines: a CSG junction between two
+      // independently tessellated tangent surfaces (e.g. a corner sphere meeting
+      // its edge-fillet cylinders) can leave micron-wide wall strips whose FACES
+      // are invisible but whose long boundary edges would otherwise draw at full
+      // line weight. A triangle thinner than MIN_EDGE cannot be seen, so its
+      // edges are noise by definition — same threshold the segment filter uses.
+      if (thin[prev] < MIN_EDGE || thin[t] < MIN_EDGE) continue;
       const dot = fn[prev * 3] * fn[t * 3] + fn[prev * 3 + 1] * fn[t * 3 + 1] + fn[prev * 3 + 2] * fn[t * 3 + 2];
       // A multi-hole cap triangulation can contain an opposite-wound bridge:
       // its two normals disagree by 180 degrees even though both triangles lie

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 = 2;
+export const CONTRACT_VERSION = 3;
 
 // Ops every backend kernel must implement.
 export const KERNEL_OPS = [
@@ -57,12 +57,19 @@ export const SHAPE2D_OPS = [
   "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.
+// Solid ops a core (mesh) kernel MAY lack. solid-sugar generates KernelCapability-
+// Error stubs for whichever of these a backend leaves undefined. The in-repo
+// Manifold backend now implements fillet and chamfer natively (mesh-fillet.js —
+// straight and circular-arc edge chains), so only `shell` is stubbed there.
 export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
 
+// The subset the geometry-free probe still routes to a B-rep kernel up front.
+// fillet/chamfer are NOT probe-routed anymore: the mesh backend attempts them
+// and throws KernelCapabilityError (code NEEDS_OCCT) only for edge classes it
+// cannot blend, which the framework's runtime reroute latch converts into a
+// per-sub-part OCCT fallback (backend-select.js).
+export const ROUTED_CAD_OPS = ["shell"];
+
 /**
  * @typedef {Object} Solid  An opaque handle to a backend solid. `_`-prefixed keys are backend internals.
  * @property {(tool: Solid) => Solid} cut
@@ -87,8 +94,8 @@ export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
  *           `normals`/`edges` are authoritative shading intent from both backends — see docs/KERNEL-CONTRACT.md "Shading intent"; 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
- * @property {(r:number|{r:number,edges?:object}) => Solid} fillet    round edges (OCCT only); fillet(3) or fillet({r,edges}); legacy (r,selector) accepted for now (see file header)
- * @property {(d:number|{d:number,edges?:object}) => Solid} chamfer  bevel edges (OCCT only); chamfer(1) or chamfer({d,edges}); legacy (d,selector) accepted for now (see file header)
+ * @property {(r:number|{r:number,edges?:object}) => Solid} fillet    round edges; mesh-native for straight/circular chains with automatic OCCT fallback; fillet(3) or fillet({r,edges}); legacy (r,selector) accepted for now (see file header)
+ * @property {(d:number|{d:number,edges?:object}) => Solid} chamfer  bevel edges; mesh-native for straight/circular chains with automatic OCCT fallback; chamfer(1) or chamfer({d,edges}); legacy (d,selector) accepted for now (see file header)
  * @property {(o:{t:number,open:object}) => Solid} shell   hollow inward (OCCT only); legacy (thickness,openFaces) accepted for now (see file header)
  * @property {() => number} [genus]     through-hole count (Manifold only)
  * @property {() => boolean} [isEmpty]  no geometry at all (Manifold only)

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

@@ -12,6 +12,8 @@ import { finishKernel } from "./kernel-front.js";
 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 { KernelCapabilityError } from "./errors.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
@@ -102,10 +104,45 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     return { positions, indices };
   }
 
+  // Mesh fillet/chamfer (mesh-fillet.js): the tool solids are built through the
+  // kernel's own cached loft/revolve/boolean ops, so the whole op memoizes at
+  // this boundary — and the result is simplify()ed to drop the zero-area sliver
+  // triangles booleans legitimately leave behind (they are invisible but their
+  // degenerate normals poison the crease pass into drawing phantom edge lines).
+  // Unsupported edge classes (helical edges, varying dihedral, …) surface as
+  // KernelCapabilityError so the framework reroutes that sub-part to OCCT.
+  // simplify() will not collapse triangles across run (originalID) boundaries,
+  // and the boolean's sliver triangles sit exactly on them — so the result is
+  // re-originaled first. That folds every surface into one fresh original,
+  // which is also the documented B-rep semantic: fillet/chamfer produce new
+  // surfaces, so feature-label attribution downstream of the op uses the
+  // fallback path (AUTHORING-PARTS.md), and the blend shades SMOOTH.
+  const SIMPLIFY_EPS = 1e-4; // 0.1 µm — must exceed the boolean's sliver widths (~2e-5)
+  const meshCadOp = (op, run) => {
+    try {
+      return T(T(run()._m.asOriginal()).simplify(SIMPLIFY_EPS));
+    } catch (e) {
+      if (e instanceof UnsupportedEdgeError) throw new KernelCapabilityError(`${op}: ${e.message}`);
+      throw e;
+    }
+  };
+
   const wrap = (m, hash) => addSugar({
     _m: m,
     _hash: hash,
     cut: (t) => cached(h("cut", hash, t._hash), () => T(m.subtract(t._m))),
+    fillet: (r, selector) => {
+      if (typeof selector === "function") throw new KernelCapabilityError("fillet: function selectors need the OCCT backend");
+      if (r === 0) return wrap(m, hash); // contract: zero magnitude is the identity
+      return cached(h("fillet", hash, r, selector ?? null, segs), () =>
+        meshCadOp("fillet", () => meshFillet(kernel, wrap(m, hash), { r, edges: selector, segs })));
+    },
+    chamfer: (d, selector) => {
+      if (typeof selector === "function") throw new KernelCapabilityError("chamfer: function selectors need the OCCT backend");
+      if (d === 0) return wrap(m, hash);
+      return cached(h("chamfer", hash, d, selector ?? null, segs), () =>
+        meshCadOp("chamfer", () => meshChamfer(kernel, wrap(m, hash), { d, edges: selector, segs })));
+    },
     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))),