partforge 0.31.0 → 0.33.0

package/README.md

@@ -128,6 +128,20 @@ so **the rail must be a direct child of the positioned `.pf-shell`** unless
 the host also supplies `elements.shell` to point at the real containing block
 (e.g. when a wrapper div sits between them, as is common in a React layout).
 
+`runtime.setParams(partial)` edits parameters programmatically — the entry point
+for animating a part from host code:
+
+```js
+runtime.setParams({ openAngle: 45 });   // merges into the live params, syncs the panel
+```
+
+The partial is merged into the current params and the control panel updates to
+match. Keys the part doesn't define are silently ignored. When every changed
+parameter only moves geometry (a rotation or translation in `place()`), the
+viewer re-poses the meshes it already has — instantly, with no worker rebuild;
+`onBuild` does not fire for those pose-only edits. Anything that changes the
+geometry itself rebuilds as usual.
+
 `onPick` arms click-to-select permanently: `label` is the feature label (falling
 back to the sub-part label/name) for compact UI, `prompt` is the LLM-ready
 sentence, `token` the compact form, `selection` the raw object. When `onPick` is

package/docs/AUTHORING-PARTS.md

@@ -342,7 +342,9 @@ This holds on **both backends** — and on OCCT, `translate`/`rotate` are additi
 re-running any B-rep work. A parameter that only feeds a final placement rotation (a
 lid's open angle, an exploded-view offset) therefore re-drags in ~0 ms even on the
 slow exact kernel — keep such transforms as the last ops in `build` (or in `place`)
-rather than baking them into the geometry earlier.
+rather than baking them into the geometry earlier. In the app, such pose-only edits
+skip the worker entirely — the viewer re-poses the cached mesh — so they stay smooth
+even at animation rates (see `runtime.setParams`).
 
 ---
 
@@ -1217,6 +1219,63 @@ entirely on OCCT, its fillets are exact in the STEP **and** present in the print
 > `partforge measure` reports `watertight`/`holes` as `n/a` for OCCT parts (Manifold-only
 > topology); `render` works on both.
 
+### 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:
+
+- **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
+  multiplied the face count — and because the solid cache keys each op by its input's
+  content hash, an early fillet is a cache **hit** when a downstream parameter changes,
+  while a fillet-last build re-pays the whole op on every slider step of every parameter.
+- **Never point a rim selector at a many-point extruded profile.** `edges: {inPlane}` on
+  a gear-like extrusion selects *every* polygon edge (hundreds); one chamfer call then
+  costs seconds — and if the distance doesn't fit the tooth lands, the failure-rescue
+  bisection re-runs it ~8× (`ERROR-PATTERNS.md#chamfer-rescue-bisection`). Use the loft
+  bevel below instead.
+
+### Beveling profile rims: extrude's bevel option
+
+For an **extruded profile** (gear, star, bracket outline — any `k.extrude` of a polygon),
+a top/bottom rim bevel doesn't need `chamfer` at all — it's built into `extrude`:
+
+```js
+k.extrude({ profile: prof, h: 5, bevel: 0.6 });                 // 45° bevel, both rims
+k.extrude({ profile: prof, h: 5, bevel: { top: 0.6 } });        // one rim only
+```
+
+Same 45° bevel a rim `chamfer` would cut, but it desugars into extrude + loft +
+intersect at the shared kernel front, so the part **stays on the fast Manifold
+backend** (no CAD-only op for the probe to find) and costs one boolean regardless of
+profile point count. Measured on a 24-tooth involute gear: ~0.1 s on Manifold vs
+~40 s for the equivalent OCCT `chamfer` (576-edge rim × the rescue bisection).
+
+Every profile form works: point arrays, arc profiles, `{outer, holes}` regions
+(hole rims flare outward — the opening is larger at the face, as a chamfer would
+cut it), and `Shape2D` (multi-region shapes bevel each region and union). One
+fidelity caveat: curved profiles are **materialized to point rings** first — the
+loft envelope needs matched points — so a beveled extrusion is faceted at the
+sampling LOD even in STEP export. Arc contours sample at a fixed LOD identically
+on both backends; a `Shape2D` materializes at its own backend's LOD. If you need
+arc-exact STEP walls, that's the one case native `chamfer` still buys you (at
+its OCCT cost).
+
+Rules (throws otherwise — `ERROR-PATTERNS.md#extrude-bevel-invalid`): no
+`twist`/`scaleTop`, and `bottom + top < h` — clamp from your height parameter, e.g.
+`bevel: Math.min(p.chamfer, p.thickness / 2 - 0.2)`. A bevel that would pinch a
+narrow feature shut (a gear's tooth land) is deterministically reduced to the
+largest offset the rim can take, with a console warning
+(`ERROR-PATTERNS.md#extrude-bevel-reduced`).
+
+Under the hood it insets the profile with `offsetPolygon(prof, -c, { corners:
+"sharp" })` and intersects with a loft envelope extended past both faces (so the
+envelope's own end caps never coincide with the extrusion's faces — coincident caps
+leave sliver-triangle shading artifacts). The same construction works by hand when
+you need a variant the option doesn't cover. This bevels a **whole rim**; for
+selective edges on a solid that's already OCCT-routed, plain `chamfer` with a tight
+selector is still the right tool.
+
 ---
 
 ## Conventions & gotchas

package/docs/ERROR-PATTERNS.md

@@ -55,6 +55,34 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 - **Cause:** The geometry-free probe runs `build` against a recording proxy (dummy query values), and a `fillet`/`chamfer`/`shell` call it reaches — including a branch the real build wouldn't take, since queries return dummies — routes the whole part to OCCT.
 - **Fix:** Remove the CAD-only call the probe reaches unnecessarily, or force the backend with `meta.backend: "manifold"` (or `"occt"`). See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Fillet & chamfer (automatic OCCT backend)".
 
+## 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.
+- **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
+
+- **Symptom:** `partforge: chamfer` warning saying the distance `over-ran the geometry — reduced to` a smaller one (or `has no valid distance`), with an attempt count and elapsed seconds, alongside slow builds.
+- **Cause:** The requested chamfer distance doesn't fit the geometry (it over-runs an adjacent face or a short edge), so the failure-rescue bisection in `occt-repair.js` re-runs the full chamfer up to 7 more times to find the largest valid distance — multiplying an already-expensive op by ~8× on every build, since the result is only cached per exact input hash.
+- **Fix:** Lower the chamfer parameter to at most the printed valid distance (the rescue then never fires), clamp it in `build` from the geometry that limits it, or — for extruded profile rims — switch to `extrude`'s `bevel` option, which finds its own limit in pure JS. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Beveling profile rims: extrude's bevel option".
+
+Variant literals under this entry: `partforge: chamfer <d> over-ran the geometry — reduced to <d'> (largest valid; <n> attempts, <t>s — see ERROR-PATTERNS.md#chamfer-rescue-bisection)`, `partforge: chamfer <d> has no valid distance for this geometry — feature skipped (<n> attempts, <t>s — see ERROR-PATTERNS.md#chamfer-rescue-bisection)`.
+
+## extrude-bevel-invalid
+
+- **Symptom:** `extrude: bevel must fit the height (bottom + top < h)` or `extrude: bevel cannot combine with twist or scaleTop` thrown from a build.
+- **Cause:** `extrude`'s `bevel` option desugars into offset-loft envelopes, which need an untwisted straight extrusion and room for both bevels inside the height.
+- **Fix:** Clamp the bevel from the height parameter (e.g. `Math.min(c, h / 2 - 0.2)`) and drop `twist`/`scaleTop`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Beveling profile rims: extrude's bevel option".
+
+Variant literals under this entry: `extrude: unknown bevel option`, `extrude: bevel must be a number or { bottom?, top? }`, `extrude: bevel distances must be finite numbers >= 0`.
+
+## extrude-bevel-reduced
+
+- **Symptom:** `partforge: extrude bevel` warning saying the requested distance `exceeds what the profile can take — reduced to` a smaller one (or `has no valid offset for this profile — rim left square`; `hole` in place of `profile` when a hole's flare is the limit).
+- **Cause:** Offsetting the rim by the bevel distance would pinch a narrow feature (a tooth land, a thin bar, a thin web beside a hole) shut, so the bevel deterministically backs off to the largest offset the outline can take — the same geometric limit OCCT's chamfer hits, resolved in pure JS instead of kernel re-runs.
+- **Fix:** Usually nothing — the reduced bevel is the correct maximum for the geometry. To silence it, clamp the bevel parameter below the printed value or widen the narrow feature.
+
 ## boolean-not-watertight
 
 - **Symptom:** `NOT watertight ✗` from `partforge measure` (non-zero exit) after adding a boolean cut or union.

package/docs/KERNEL-CONTRACT.md

@@ -0,0 +1,437 @@
+# The partforge kernel contract
+
+**Contract version: 1** (introduced in partforge 0.9) — 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.
+
+This document is the portable seam of partforge. A part's `build(k, p, d)` is a pure ESM
+function written against the kernel `k` and the `Solid` handles it returns — no framework
+imports, no DOM, no backend types. That means **the kernel interface is the interchange
+format**: any host that implements this contract can run any partforge part, and an LLM
+given this document plus one exemplar part has everything it needs to write correct
+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`
+  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.**
+- **Prose (this doc):** the semantics an implementer or generator cannot read off a
+  signature — coordinate conventions, value semantics, validation rules, error taxonomy,
+  what parts may and may not rely on across backends.
+
+Audience: backend/host implementers, and anyone (human or LLM) generating parts outside
+this repo. For *authoring guidance* — usage tables, worked snippets, control-panel schema
+— read `docs/AUTHORING-PARTS.md`. Where the two overlap (the op tables), this doc
+carries the conformance semantics and that one the usage guidance;
+`test/kernel-contract.test.js` keeps this doc's op coverage in sync with the code.
+
+## Conformance classes
+
+**Core class.** A conforming core kernel implements every op in `KERNEL_OPS` and
+every `Solid` op in `SOLID_OPS`, *except* that the B-rep ops (`fillet`, `chamfer`,
+`shell` — the `OCCT_ONLY_OPS` list — and `toSTEP`) may instead throw
+`KernelCapabilityError`. The in-repo Manifold backend is the reference core kernel.
+Kernels built from this repo get the stubs for free: `addSugar()` generates the
+Solid-level stubs from `OCCT_ONLY_OPS`, and `finishKernel()` stubs `toSTEP` (a
+kernel-level op, so it is not in that Solid-op list).
+
+**B-rep class.** Core plus native `fillet`/`chamfer`/`shell` and `toSTEP`. The in-repo
+OCCT/replicad backend is the reference.
+
+**Optional ops.** `KERNEL_OPTIONAL_OPS` (`beginSubPart`/`endSubPart`/`sweepCache`/
+`cacheStats`/`resetCacheStats`/`cleanup`) and `SOLID_OPTIONAL_OPS` (`genus`/`isEmpty`) may
+be omitted entirely; callers in the framework guard with `?.`/`typeof`. A host that omits
+them loses sub-part caching and mesh-topology gates (`holes`, emptiness), nothing else.
+`sweepCache()` is the cache's rebind hygiene hook: called once when a worker is rebound to
+a part (never inside a `beginSubPart`/`endSubPart` bracket), it drops cache partitions that
+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 routes the whole part to a B-rep-class kernel. A host with only a core kernel must
+surface the error ("this part needs a B-rep backend") rather than swallow it.
+
+## Global semantics
+
+These hold for every op on every backend. A part may assume them; an implementation must
+provide them.
+
+- **Units are millimetres.** Everywhere, including `volume()` (mm³) and mesh output.
+- **Angles are degrees.** Everywhere (`rotate*`, `twist`, `revolve` `degrees`, loft ring
+  `rotate`, `arcDeg` helpers).
+- **Coordinates are right-handed, Z-up.** Primitives build along **+Z from z = 0**
+  (`cylinder`, `prism`, `extrude` extrude upward; `revolve` spins `[[r, z], …]` about the
+  Z axis). The idiom is *build canonical at the origin, then orient/place*
+  (`.along(dir).at(v)`).
+- **2-D contours are `[[x, y], …]` point lists, CCW = material.** Holes in an `extrude`
+  profile are additional contours; winding of holes is normalized by the backend. The
+  symbolic-arc alternative is an **arc profile** `{ start, segments: [{ to, via? }, …] }`
+  (produced by `roundedProfile`), where a segment with `via` is a three-point circular
+  arc; B-rep backends must carry these arcs exactly (real CIRCLE edges in STEP), mesh
+  backends tessellate them. Cubic Bézier segments (`{to, c1, c2}`, built via `pathProfile().cubicTo(…)`)
+  follow the same rule: exact spline B-rep on OCCT (→ STEP), adaptively faceted at
+  the mesh `segs` LOD on Manifold. Measure-parity (volume/bbox) holds within
+  tolerance as facets converge; this is not a parity waiver.
+- **Ops never mutate — but they MAY consume.** Every op returns a new `Solid` and never
+  mutates one in place. Whether the *inputs stay valid* is backend-dependent: the mesh
+  backend leaves them usable, but the B-rep backend's engine (replicad) deletes the
+  operand of a transform or boolean. The portable rule is therefore: **never reuse a
+  `Solid` after passing it to a transform or boolean — `.clone()` first if you need it
+  again** (failure signature: ERROR-PATTERNS.md `replicad-consumed-operand`). `clone()`
+  must return an independent handle on every backend; a backend MAY additionally provide
+  full value semantics, but a portable part must not rely on it.
+- **Purity and determinism: identical arguments must produce identical geometry.** No
+  randomness, clocks, or hidden global state in an implementation. partforge's solid
+  cache memoizes by a content hash of `(op, args)`; a nondeterministic op silently
+  poisons the cache.
+- **Validation** (a conforming implementation enforces all of these; in-repo the kernel
+  front checks the `prism`/`extrude`/`revolve` rules, `addSugar` the `scale` rule, and
+  the B-rep backend the `shell` rule): `prism`/`extrude` `scaleTop ≥ 0`; `revolve`
+  profile radii `≥ 0`; `scale` `factor > 0`; `shell` requires `open` (a fully
+  closed hollow is not supported).
+- **Error taxonomy:** invalid arguments throw plain `Error` with a message naming the op
+  (`"prism: scaleTop must be ≥ 0"`); a whole op a backend class lacks throws
+  `KernelCapabilityError` (from `geometry/errors.js`) — the routing signal. A
+  backend-divergent *option* (`loft`/`sweep` `closed: true` on a B-rep kernel) throws a
+  plain `Error` naming the limitation, not `KernelCapabilityError`: option misuse is not
+  reroutable, and a host must fail loudly rather than silently ignore the option. Beyond
+  those, nothing else is thrown for well-formed input — a fillet the engine cannot
+  compute falls under the repair policy below, not a part-visible error class.
+
+## Calling convention
+
+**Detection rule (normative):** a call is **options form** when the op receives
+**exactly one argument and it is a plain object** — not an `Array`, not a `Solid`.
+Any other arity or first argument is legacy positional form. "Plain object" means
+`Object.getPrototypeOf(x) === Object.prototype || null`, which excludes arrays,
+`Solid` handles (backend handles carry methods/prototypes), and typed arrays. This
+one rule disambiguates every op with no key-sniffing — the load-bearing case:
+`extrude({outer, holes}, h)` is positional (two arguments); `extrude({profile, h})`
+is options (one plain object).
+
+Options form is canonical — the form this document, `AUTHORING-PARTS.md`, and every
+in-repo part teach and use. Legacy positional forms remain accepted (silently — no
+runtime warning) until contract v2 removes them; a conforming implementation must
+accept both, and this repo's `finishKernel()`/`addSugar()` provide the normalization
+for free.
+
+### Kernel factory ops (options-canonical; legacy positional accepted)
+
+| Op | Canonical options form | Legacy positional (until v2) |
+|---|---|---|
+| `cylinder` | `{r\|d, h, center?}` straight · `{r1, r2, h, center?}` or `{d1, d2, h, center?}` cone | `(rBottom, rTop, h, {center?})` |
+| `sphere` | `{r\|d}` — `sphere(5)` stays valid, undeprecated | `(r)` |
+| `box` | `{size:[x,y,z], center?}` (centered X/Y, base z=0; `center:true` also centers Z) · `{min, max}` | `(min, max)` |
+| `prism` | `{points, h, twist?, scaleTop?}` | `(points2D, h, {twist?,scaleTop?})` |
+| `extrude` | `{profile, h, twist?, scaleTop?, bevel?}` — `profile` = points array, `{outer, holes}`, or arc profile; `bevel` has no positional form | `(profile, h, {twist?,scaleTop?})` |
+| `revolve` | `{profile, degrees?}` | `(points2D, {degrees?})` |
+| `loft` | `{rings, ruled?, closed?}` | `(rings, {ruled?,closed?})` |
+| `sweep` | `{profile, path, closed?, cornerRadius?, ruled?, smooth?}` | `(profile2D, path3D, opts?)` |
+
+`boredCylinder` and `helixSweptTube` were always options-only (no positional
+legacy form exists); they get the same unknown-key / required-key validation as
+the ops above.
+`union(solids[])` and `toSTEP(named[])` take a single array — unchanged.
+
+### Solid ops
+
+| Op | Canonical form(s) | Notes |
+|---|---|---|
+| `fillet` | `fillet(3)` · `fillet({r, edges?})` | options form replaces `fillet(3, selector)` |
+| `chamfer` | `chamfer(1)` · `chamfer({d, edges?})` | ditto |
+| `shell` | `shell({t, open})` | replaces `(thickness, openFaces)`; `open` was already required |
+| everything else | unchanged | `translate/at/along/rotate*/rotateAbout/mirror/scale/cut/cutAll/intersect/union/clone/label` + queries |
+
+### Cylinder key rules
+
+- Straight: exactly one of `r` / `d`. Cone: `r1`+`r2` or `d1`+`d2` (no mixing
+  radius and diameter across ends; no mixing straight and cone keys).
+- `h` required everywhere.
+- Diameter keys are sugar: normalized to radii before the backend sees them.
+
+### `box({size})` placement
+
+`{size:[x,y,z]}` is centered in X and Y with its base at `z = 0` — the same
+canonical placement `cylinder` already has (build canonical at the origin, then
+orient/place). `{center:true}` additionally centers Z. `{min, max}` remains for
+explicit corners and is unaffected.
+
+Scalar shorthands are permanent, not legacy: `sphere(5)`, `fillet(3)`, and
+`chamfer(1)` stay valid and undeprecated — they take a single number with no
+transposition risk, so there is no options-form pressure to replace them (only
+`fillet`/`chamfer`'s two-argument selector call is superseded, by
+`fillet({r, edges})` / `chamfer({d, edges})`).
+
+## Kernel ops (make solids)
+
+Signatures are normative in `kernel.js`'s `@typedef GeometryKernel`; this table fixes
+the behavior. Signatures are shown in the canonical options form — the legacy
+positional equivalents live in the [Calling convention](#calling-convention) table
+above. All ops return a `Solid`.
+
+| Op | Contract |
+|---|---|
+| `cylinder({r\|d, h, center?})` · `cylinder({r1, r2, h, center?})` \| `{d1, d2, h}` | Cylinder along +Z from z = 0 (straight: exactly one of `r`/`d`); the cone form (`r1`/`r2` or `d1`/`d2` ends) gives a frustum. `center: true` centers on z = 0. |
+| `boredCylinder({od, h, bore})` | Compound: cylinder of diameter `od` with a through-bore `bore`. Semantically identical to the composition in `kernel-front.js`; a backend may override only for caching, never for different geometry. |
+| `sphere({r\|d})` | Sphere centered at the origin; bare `sphere(r)` stays valid. |
+| `box({size, center?})` · `box({min, max})` | Axis-aligned box: `{size:[x,y,z]}` centered in X/Y with base at z = 0 (`center: true` also centers Z), or explicit `[x,y,z]` `{min, max}` corners. |
+| `prism({points, h, twist?, scaleTop?})` | Extrude one CCW contour (point list or arc profile) from z = 0. `twist` = total degrees over the height; `scaleTop` = uniform top scale (1 straight, 0 → apex). |
+| `extrude({profile, h, twist?, scaleTop?, bevel?})` | Same, for a polygon-with-holes region — `profile` is `{outer, holes?}` (bare contour = outer only) — in one op, no per-hole boolean. `profile` may also be a `Shape2D` (see below). `bevel` (number = both rims, `{bottom?, top?}` = per rim) cuts a 45° rim bevel; it desugars at the shared front into extrude + loft + intersect/cut, so it is backend-identical by construction and is **not** a CAD-only op (no OCCT routing). Every profile form works — point array, arc profile, `{outer, holes}` (hole rims flare outward), or `Shape2D` (multi-region bevels each and unions) — but curved profiles are **materialized to point rings** first, so a beveled extrusion is faceted at the sampling LOD even in STEP (arc contours at a fixed pure-JS LOD, backend-identical; a `Shape2D` at its backend's own LOD — `hull`'s parity class). No `twist`/`scaleTop`, and `bottom + top < h` or it throws; a bevel a rim's narrow features cannot take is deterministically reduced with a console warning (`ERROR-PATTERNS.md#extrude-bevel-reduced`). |
+| `revolve({profile, degrees?})` | Revolve a lathe profile `[[r, z], …]` (r ≥ 0) about Z; `degrees` < 360 gives a capped partial revolve. Default 360. |
+| `loft({rings, ruled?, closed?})` | Stack polygon cross-sections (per-ring `z`/`rotate`/`scale`, equal vertex counts) with ruled walls and capped ends. Must self-correct a fully inverted result (CW rings / descending z) to an outward 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). |
+| `union(solids[])` | Boolean union of one or more solids. |
+| `text2d(string, {size, font?, align?, valign?, lineHeight?, tracking?, kerning?})` | Outline-font text → `Shape2D`. `size` = cap height (mm). `font` = declared name / inline bytes / default. Build-time; curve-exact on OCCT, faceted on Manifold. |
+| `hull(inputs[])` | Convex hull of all inputs (each a `Shape2D`, a curve contour, or an `[[x,y],…]` point list) → a convex `Shape2D`. Backend-agnostic: a pure-JS monotone-chain hull over the inputs' sampled points (curved inputs tessellated at a fixed LOD), lifted via `shape2d` (see the parity note below). Throws on an empty input array or a degenerate (collinear/point-count < 3) hull. |
+| `hullChain(inputs[])` | Swept hull over an ordered sequence of ≥2 inputs (same input forms as `hull`): the union of `hull([inᵢ, inᵢ₊₁])` for each consecutive pair — e.g. a tapered link connecting a row of circles. Throws with fewer than 2 inputs. |
+| `toSTEP(named[])` | `[{name, solid}]` → `Promise<ArrayBuffer>` of a STEP assembly. B-rep class only. |
+
+`hull`/`hullChain` parity: point-list and curve-contour inputs hull bit-identically
+across backends (pure-JS sampling, no backend materialization involved). A `Shape2D`
+input samples via its own backend materialization (`.toRegions()`), so a hull that
+includes a `Shape2D` input agrees only within the tessellation tolerance of that
+backend's curve faceting — the same class of parity as the 2-D boolean ops above, not
+a waiver of `CONTRACT_VERSION` (still 1; this op is additive).
+
+**Backend-divergent options** (a portable part must treat these as declared here):
+`loft` `closed: true` (capless loop) and `sweep` `closed: true` are supported **only by
+mesh backends** (Manifold); B-rep kernels throw a plain `Error` naming the limitation
+(see the error taxonomy). `loft` `ruled: false` (smooth C2 walls) and `sweep`
+`smooth: true` (native swept B-rep) are honored only by B-rep kernels; mesh kernels
+render the ruled form. `sweep` `closed: true` loops must be planar. Where both backends build the same
+shape they do it **by construction, not by tolerance**: sweep elbows loft the identical
+station list (`sweep.js`) on both backends.
+
+## Solid ops (combine / transform / query / output)
+
+Normative signatures: `kernel.js`'s `@typedef Solid`.
+
+| Op | Contract |
+|---|---|
+| `cut(tool)` / `cutAll(tools[])` / `intersect(other)` / `union(other)` | Boolean subtract (single / batched), intersection, and union. |
+| `translate(v)` · `rotate(deg, center, axis)` · `mirror("XY"\|"XZ"\|"YZ")` · `scale(factor, center?)` | Transforms — but only two are **rigid** (pose): `translate`/`rotate` move a solid without altering it (position + orientation, shape and handedness preserved). `mirror` **reflects** — it returns the opposite-handed (chiral) solid, which no rotation can reproduce; `scale` **resizes**. So `mirror`/`scale` change the solid *itself*, not just where it sits — think of them as build operations, and never as the difference between a display pose and an export pose (see AUTHORING-PARTS.md `place`). `translate`/`rotate` are the primitives; the placement sugar below is composed *purely from them* (`solid-sugar.js`), so it is geometry-identical on every backend and a host gets it for free via `addSugar()`. |
+| `rotateX(deg)` / `rotateY(deg)` / `rotateZ(deg)` · `rotateAbout({axis, deg, through?})` · `along(dir)` · `at(v)` | The readable placement vocabulary parts actually use. `along` maps the canonical +Z build axis to `"±X"\|"±Y"\|"±Z"`. |
+| `clone()` | Independent handle (see value semantics). |
+| `label(name)` | Name this solid's surface for feature attribution; must survive transforms and booleans; equal names merge into one feature. Affects mesh metadata only, never geometry. |
+| `boundingBox()` | `{min, max, center, size}`; `center`/`size` are derived by `addSugar` from the backend's `{min, max}`. |
+| `volume()` | Solid volume in mm³. |
+| `genus()` / `isEmpty()` | Optional (`SOLID_OPTIONAL_OPS`): mesh-topology queries — through-hole count / no-geometry test. The mesh backend provides them; OCCT has no cheap equivalent. |
+| `toMesh({quality?})` | Render mesh: `{positions, normals, indices?, triangles, edges?, featureIds?, features?}`. `indices` optional (a backend may emit soup or indexed); `normals` may be empty (`length 0`) to delegate creasing to the viewer; `edges` (feature-line segments) and the feature fields 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()` | `{positions, indices}` indexed mesh (3MF path). |
+| `fillet(r)` · `fillet({r, edges?})` / `chamfer(d)` · `chamfer({d, edges?})` / `shell({t, open})` | B-rep class (core throws `KernelCapabilityError`). Scalar `fillet(3)`/`chamfer(1)` acts on all edges; the options form adds an `edges` selector. `shell` hollows inward, keeping outer dimensions; `open` (face selector) is required. |
+
+`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
+depend on triangle counts, segment counts, or normals being present.
+
+**Selectors** (`fillet`/`chamfer` `edges` selector, `shell` `open` face selector) are
+declarative objects, criteria AND-combined:
+
+```js
+{ dir: "X"|"Y"|"Z",           // edges along / faces normal-to this axis — edge
+                              //   selectors ALSO accept an [x,y,z] vector; face
+                              //   selectors (shell open) accept ONLY the strings
+  inPlane: "XY"|"XZ"|"YZ", at: number,   // in the given plane at offset `at`
+  near: [x,y,z] }                        // containing this point
+```
+
+`undefined` selects all edges/faces. A raw replicad finder function is also accepted
+in-repo (AUTHORING-PARTS.md offers it for parts that are content to stay OCCT-bound),
+but it is
+inherently backend-specific: portable parts **MUST** use the object form, and a host
+**MAY** reject function selectors.
+
+**B-rep repair policy** (`occt-repair.js`): a failing fillet or shell is skipped **as a
+whole** — attempted once, and on failure the shape reverts to its pre-op state (OCCT
+fillet failures are not monotonic in the radius, so per-edge retry would converge on
+garbage). A failing chamfer instead binary-searches the largest valid distance. A
+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.
+
+## Shape2D (2-D booleans)
+
+`k.shape2d(profile)` (`KERNEL_OPS`) lifts a point list, `{outer,
+holes?}` region, or arc/curve contour into a `Shape2D` — an opaque 2-D boolean
+value. Idempotent: `shape2d(x)` returns `x`
+unchanged if `x` is already a `Shape2D`. `_`-prefixed keys are backend internals.
+Normative signatures: `kernel.js`'s `@typedef
+Shape2D`; the full public surface is `SHAPE2D_OPS`. **Both backends implement it**:
+Manifold wraps a `CrossSection` (each method returns a fresh content-hash-cached
+value, same caching/dispose discipline as `Solid`); OCCT wraps a replicad `Drawing`
+(curve-preserving, so a curved boolean survives to exact STEP — content-hashed so
+downstream `Solid` ops can key on it, but itself uncached; OCCT's `Solid` ops go
+through the same solid cache as Manifold's, with rigid transforms kept pose-lazy so
+re-posing a cached solid re-runs no B-rep work). The `kernel-front.js` `KernelCapabilityError` stub for `shape2d` is
+now a dead / future-backend safety net only (both current backends define the op),
+not an OCCT limitation.
+
+| Op | Contract |
+|---|---|
+| `union(other)` / `cut(other)` / `cutAll(others[])` / `intersect(other)` | 2-D boolean ops; `other` may be a `Shape2D` or a raw profile (lifted via `shape2d` first). |
+| `offset(delta, {corners?, segs?})` | Grows (`delta>0`) or insets (`delta<0`) by `delta` mm; `corners` = `round` (default) / `chamfer` / `sharp`. Curve-preserving on OCCT, faceted at mesh LOD on Manifold. Throws if the offset collapses the shape. |
+| `area()` | Net area (Σ\|outers\| − Σ\|holes\|), mm². |
+| `boundingBox()` | `{min, max}` — axis-aligned 2-D bounds (no `center`/`size`, unlike `Solid.boundingBox`). |
+| `toRegions()` | Materialize into `{outer, holes}[]` region arrays (`assembleRegions`); a boolean result may be several disjoint regions. |
+| `simple()` | `toRegions()` unwrapped — throws unless the result is exactly one region. |
+| `regions()` | Scission: each disjoint region as its own live `Shape2D[]` (each further boolean-able), vs `toRegions()` which returns raw `{outer, holes}` data. |
+| `extrude({h, twist?, scaleTop?})` | Sugar for `k.extrude({profile: this, …})` → `Solid`. |
+| `revolve({degrees?})` | Sugar for `k.revolve({profile: this, …})` → `Solid`. |
+| `clone()` | Independent handle. |
+
+On `offset`: `round`, `sharp`, and `chamfer` all agree across both backends **for convex corners with interior angle ≥ 90°** (the common case: rectangles, hexagons, rounded-rects, pentagons, …). `chamfer` is a true 45° bevel — a straight chord across the corner — matching OCCT to float precision there (a 10×10 square offset +1 gives 142.0 on both; a pentagon 298.920 on both). Manifold has no native bevel join, so it renders `chamfer` as a Round join forced to a single chord per corner (`circularSegments=4`). **At acute (<90° interior) convex corners** — triangles, star points, V-notches — Clipper2 emits 2 chords rather than 1, so Manifold's chamfer bulges ~0.4% beyond OCCT's single-chord bevel (e.g. an equilateral triangle: Manifold 235.46 vs OCCT 234.50). `round` and `sharp` are exact across backends at every angle; prefer them, or accept the small acute-corner difference on `chamfer`.
+
+2-D boolean ops are a **parity-relevant operation**: on OCCT they carry exact circular arcs and Bézier curves; on Manifold they facet curves to mesh LOD. Measure-parity (area, bounding box) holds within the tessellation tolerance as LOD converges — this is not a parity waiver.
+
+A `Shape2D` may be passed directly as the `profile` to `extrude` — Manifold
+extrudes its `CrossSection` directly (no re-tessellation) and OCCT extrudes its
+`Drawing` directly, including any holes it already carries.
+
+## The 2-D helper library
+
+`partforge/geometry` ships pure-JS helpers of two kinds. The **contour builders**
+(`piePolygon`, `hexPolygon`, `regularPolygon`, `roundedRectPolygon`, `ellipsePolygon`,
+`slotPolygon`, `starPolygon`, `ringSectorPolygon`, `circleProfile`, `cornerArc`,
+`filletPolygon`, `roundedProfile`) are pure functions from numbers to plain CCW point
+lists or arc profiles — *data already in this contract's input format*, with no kernel
+dependency at all. The **solid patterns** (`linearPattern`, `circularPattern`) take a
+`Solid` and call only ops from the tables above (`clone`/`translate`/`rotate`/
+`boundingBox`). The **profile transform** (`offsetPolygon`) takes a point list or
+`{outer, holes}` region and grows or shrinks it by a delta in mm — printer-clearance
+offsetting with round/chamfer/sharp corner styles — validating its input and result and
+throwing rather than ever returning degenerate (self-intersecting or collapsed)
+geometry. All three kinds are therefore portable by construction: a host implements
+the kernel and the helpers come along unmodified. (`test/kernel-contract.test.js`
+asserts every `polygon.js` export is named here.)
+
+- `pathProfile` — fluent builder for a curve-native path contour (`lineTo` /
+  `arcTo` / `cubicTo` / `close`); cubic segments become exact B-rep on OCCT and
+  facet at mesh LOD on Manifold.
+
+## Worker rebind
+
+The op tables above are the portable seam for *geometry*; this section is the matching
+seam for *worker lifetime*. A host that shows one part after another (an embedder, the
+cloud runner) can keep a single worker across the swap and reuse its booted WASM kernel
+and warm solid cache instead of paying the boot cost again.
+
+`runWorker(part)` (`src/framework/worker.js`) returns a rebind handle —
+`{ setPart(newPart) }` — and that handle is the whole interface. The framework defines
+**no rebind *message***: a host that talks to its worker over its own re-init protocol
+maps that protocol onto `setPart` itself.
+
+`setPart(newPart)` does four things, synchronously, on the worker's own turn:
+
+- **Swaps the part** for jobs that arrive *after* the call. Jobs already queued keep the
+  part that was current when their message arrived — a job always runs against the part
+  it was sent for, never against a part that replaced it mid-flight.
+- **Bumps the generate epoch**, which is what makes earlier builds stale (below).
+- **Sweeps each booted kernel's solid cache** — one `sweepCache()` per booted kernel,
+  never inside a `beginSubPart`/`endSubPart` bracket. See the Optional ops paragraph
+  under [Conformance classes](#conformance-classes) for what the sweep evicts; a host
+  whose kernel omits the op simply keeps every partition.
+- **Re-posts `{type:"ready"}`**, so a remounting host gates its first generate on
+  readiness exactly as it would on a freshly spawned worker.
+
+**Epoch guard.** Generates supersede each other; exports (`export-stl`/`export-step`/
+`export-3mf`), `inspect`, and `lint` are **never** epoch-guarded — cancelling a user's
+export because an edit landed would be wrong. A generate that is stale by the time the
+job pump reaches it is skipped and never builds at all. A generate already running
+re-checks staleness at each sub-part boundary and, if it has been superseded, stops
+there and posts `{type:"superseded"}` **instead of** `{type:"meshes"}` — a build that
+ended without producing meshes, and not an error. A generate with no boundary left to
+stop at — one that goes stale during its *final* sub-part, or a single-sub-part generate
+that goes stale once the pump has dequeued it — runs to completion, and the worker then
+discards its result the same way, posting `{type:"superseded"}` in place of the meshes it
+built. So **a `meshes` post is current as of the moment it is posted**: it is never a
+previous part's geometry surfacing after a rebind, and a host may take it as the build
+outcome for the part it currently has mounted.
+
+**Host-side rule for `superseded`.** partforge's own `mount()` does not handle a
+`superseded` message, and does not need to: in its single-mount flow the regen loop
+serializes generates, so no generate is ever in flight when the next one is sent and the
+message is unreachable. An **embedding host that rebinds via `setPart` must** do one of
+two things:
+
+- detach the old message listener before rebinding — the partforge-cloud pattern. A
+  rebound worker's next mount sends its first generate *after* `setPart`, so that
+  generate can never be stale, and any `superseded` from the previous mount lands on a
+  listener that is already gone; or
+- handle `superseded` explicitly as "this build ended without meshes" — clear the busy
+  state, keep the current geometry, and wait for the next result. A host that instead
+  lets it fall through a `meshes`-only handler leaves a spinner up forever.
+
+**Only `meshes` is epoch-gated**, so the second option is the weaker one. A stale build's
+other posts — `progress`, `error`, `needs-occt` — are not gated and still reach a listener
+that survived the rebind: a stale `error` would mark a perfectly good new part failed, and
+a stale `needs-occt` would stickily flip the host's backend for a part that never asked for
+it. Handling `superseded` fixes the stuck spinner but not that crosstalk, which is why
+detaching the listener is the recommended pattern.
+
+**Cancellation granularity is the sub-part.** The guard is checked only between
+sub-parts (one macrotask yield each), so a single long WASM op — a big boolean, an OCCT
+fillet — runs to completion no matter how stale it is. That is by design: WASM kernel
+calls are not interruptible, and a build that abandons a sub-part mid-bracket would
+strand pinned cache entries. Hosts should size responsiveness expectations against the
+slowest single sub-part, not the whole build. Cancellation is therefore about *work
+avoided*, never about correctness of what is posted: work already under way may finish,
+but its output is still gated behind the epoch before it leaves the worker.
+
+## Versioning
+
+The contract version is the number at the top of this document, mirrored by
+`CONTRACT_VERSION` in `kernel.js` (the parity test asserts the two match). The op lists
+in `kernel.js` define the current surface; only breaking changes bump the version:
+
+- **Additive** (new kernel/Solid op, new optional field on an options object, new
+  optional mesh-output field): contract version unchanged, minor npm release. Old parts
+  run everywhere; new parts need hosts that implement the new op.
+- **Breaking** (changed signature or semantics, removed op, new *required* argument,
+  tightened validation that rejects previously valid input): contract version bump,
+  **major npm release**, and a migration note added here. Removal without a major bump
+  is forbidden.
+- The naming vocabulary is frozen deliberately: where a name was arbitrary it matches
+  the OpenSCAD/Manifold/CadQuery consensus (`union`, `translate`, `rotate`, `mirror`;
+  `cut` per CadQuery/replicad rather than OpenSCAD's `difference`), so LLM priors
+  transfer. Renames are breaking changes with no offsetting benefit — don't.
+
+## Why not an existing CAD language
+
+Considered and rejected as the part format (2026-07; revisit if the landscape shifts):
+
+- **CadQuery** — largest corpus after OpenSCAD, but its workplane-stack + string-selector
+  model is B-rep-native and cannot be implemented on the mesh backend; Python besides.
+- **KCL (Zoo)** — designed for LLM generation, but young, sketch-plane-shaped, and tied
+  to one vendor's engine; adopting it costs the dual-backend seam.
+- **replicad** — already the OCCT backend; part of partforge's value is papering over
+  its consuming-transform semantics. Matching downward would re-expose them.
+- **OpenSCAD** — closest semantic cousin (Manifold is its modern engine) and the largest
+  LLM prior; unadoptable as syntax (own language, no fillets/STEP), so we align
+  *vocabulary* instead.
+
+The recurring constraint: every op here is implementable on **both** a mesh-CSG kernel
+and a B-rep kernel (see `docs/geometry-backend-strategy.md` for why that dual-backend
+property is worth protecting — OCCT booleans are ~75–1400× slower). Generation *safety*
+comes not from a restricted DSL but from the verify loop (`measure`/`verify` gates:
+`bbox`, `volume`, `holes`, `watertight`, overlaps — plus `minWall` *warnings*, which
+report but never fail) — a generator gets machine-checkable
+pass/fail feedback per part, which a syntax could never provide.
+
+## Conformance checklist for a new backend or host
+
+1. Implement `KERNEL_OPS` + `SOLID_OPS` (stub `OCCT_ONLY_OPS`/`toSTEP` with
+   `KernelCapabilityError` if core class); route through `finishKernel()`/`addSugar()`
+   if building in-repo to inherit validation, sugar, and stubs.
+2. Pass `test/kernel-contract.test.js` (op-list parity) — add an equivalent for an
+   out-of-repo host.
+3. Honor the global semantics above (units, Z-up, CCW, value semantics, determinism).
+4. Run **every part in `src/parts/`** through `npx partforge measure` unmodified — the
+   directory, not this prose, is the acceptance suite (today that includes
+   `faceted-vase.js`, the `loft` exerciser, and — B-rep class — `filleted-box.js`).
+   Caveat: a part with no `verify` block (`filleted-box.js` today) exercises only the
+   default measure gates, so B-rep implementers should also render it and export STEP
+   rather than trust the exit code alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.31.0",
+  "version": "0.33.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",
@@ -19,6 +19,7 @@
     "skills/partforge/SKILL.md",
     "docs/AUTHORING-PARTS.md",
     "docs/ERROR-PATTERNS.md",
+    "docs/KERNEL-CONTRACT.md",
     "README.md"
   ],
   "exports": {