partforge 0.58.1 → 0.59.0

package/docs/AUTHORING-PARTS.md

@@ -294,8 +294,10 @@ transposition mistake (swap two same-typed numbers, get a valid *wrong* solid).
 Single-argument chaining ops (`translate`, `rotate*`, `cut`, `mirror`, `scale`, …)
 already take one argument and are unaffected. Legacy positional calls (e.g.
 `k.cylinder(rBottom, rTop, h)`) still work — they're accepted silently until a
-future contract v2 — but are not shown here; see `docs/KERNEL-CONTRACT.md`
-"Calling convention" for the full canonical/legacy table and the detection rule.
+future breaking contract version removes them (contract v2, partforge 0.59, did
+not — it only changed `offset` semantics) — but are not shown here; see
+`docs/KERNEL-CONTRACT.md` "Calling convention" for the full canonical/legacy table
+and the detection rule.
 
 **Kernel — make solids:**
 
@@ -1119,7 +1121,7 @@ const wall  = k.shape2d(outer).offset(-2, { corners: "sharp" });  // inset, mite
 
 (This achieves the same geometry as building the profiles separately and using `k.extrude({ profile: { outer, holes }, h })`, but the Shape2D path is more idiomatic for complex 2-D operations.)
 
-`Shape2D.offset(delta, {corners})` grows (`delta>0`) or insets (`delta<0`) a shape with round/chamfer/sharp corners — curve-preserving on OCCT, faceted at mesh LOD on Manifold; it throws if the offset collapses the shape. (For `derive()`/main-thread clearance math on plain point lists, use the pure `offsetPolygon` helper instead.)
+`Shape2D.offset(delta, { corners: "round" | "chamfer" | "sharp" })` grows (`delta>0`) or insets (`delta<0`) a shape. It runs backend-independently on the shared contour engine — lines and arcs offset exactly (arcs stay arcs), so results are backend-identical by construction, like every other `Shape2D` op; it throws if the offset collapses the shape. A region with holes offsets material-wise: the outer grows/shrinks by `delta`, holes by `-delta`, so a positive `delta` always adds material. (For `derive()`/main-thread clearance math on plain point lists, use the pure `offsetPolygon` helper instead.)
 
 ## Editing profiles
 

package/docs/ERROR-PATTERNS.md

@@ -306,6 +306,82 @@ Variant literals under this entry: `offsetPolygon: delta must be a finite number
   inset. Realistic clearances (fractions of a mm) and wall insets up to the
   narrowest feature never trip this.
 
+## shape2d-offset-partial-reflection-residual
+
+- **Symptom:** A pocket that should close doesn't — an outward `Shape2D.offset` on a
+  region with a hole leaves a leftover hole ring behind (`.holes.length` stays > 0,
+  `.area()` under-reports) even though the hole's narrowest span is smaller than
+  `delta` and the pocket should have closed completely.
+- **Cause:** A raw offset ring can be locally valid — correctly wound (CW for a
+  hole), no self-intersections — while still lying inside the region it should have
+  been swept away by. That's a *global* defect only a whole-shape containment check
+  can see, and `offset`'s validator (`contour-offset.js`'s `validateRawOffset`)
+  only checks local validity. Known limitation — see
+  [KERNEL-CONTRACT.md "Offset: known limitations"](KERNEL-CONTRACT.md#offset-known-limitations).
+- **Fix:** No general fix yet. Verify `.holes.length` after an offset meant to
+  close a pocket rather than assuming it did; work around by offsetting in stages
+  or padding the pocket before offsetting.
+
+Searchable phrasings of the same misbehavior: hole doesn't disappear after offset;
+pocket not closed by offset; residual hole ring; `.holes.length` still 1 after
+growing a shape past the hole's own width.
+
+## shape2d-offset-reflex-cluster-too-much-material
+
+- **Symptom:** An inward `Shape2D.offset` (`corners: "chamfer"` or `"sharp"`) on a
+  shape with several reflex/concave corners close together leaves several times too
+  much material — `.area()` comes back far larger than the eroded shape should be,
+  often split across more regions than expected. No error is thrown.
+- **Cause:** When the offset's raw rings self-intersect, `offset` hands them to
+  paper.js (`paper-bridge.js`'s `resolveSelfRegions`) to untangle. Clustered reflex
+  corners produce several overlapping self-intersection loops at once, and paper.js
+  resolves that tangle into the wrong set of sub-regions — keeping loops that should
+  have cancelled. Verified: a 9-gon with clustered reflex corners at `delta` −2.79
+  chamfer resolves to ~7.71 where the true eroded area is ~2.76. Known limitation —
+  see [KERNEL-CONTRACT.md "Offset: known limitations"](KERNEL-CONTRACT.md#offset-known-limitations).
+- **Fix:** No general fix yet. Check `.area()` against the expected eroded area
+  rather than trusting a large inward offset over a spiky outline; work around by
+  using `corners: "round"` (which does not produce the same chord tangle), by
+  simplifying the outline before offsetting, or by offsetting in smaller stages.
+
+## shape2d-offset-waist-not-severed-round-join
+
+- **Symptom:** An inward `Shape2D.offset` past the width of a narrow waist does not
+  split the shape in two — the result stays connected (or comes back with a spurious
+  extra blob where the waist was) and `.area()` over-reports — but the *same* offset
+  with `corners: "sharp"` splits correctly. Verified: a 30×10 dumbbell with a 2-wide
+  waist at `delta` −2 gives 72.000 in two regions under `sharp` and 97.258 in three
+  regions under `round` (74.000 vs 96.000 under `chamfer`).
+- **Cause:** The recovery that severs a waist pinched shut by an offset
+  (`splitAtDuplicateEdges` in `contour-offset.js`) works by finding the pair of
+  duplicate, exactly-collinear edges the two sides of the pinch land on — so it only
+  handles rings made entirely of straight lines. A round or chamfer join inserts an
+  arc or a bevel chord at the waist, so there is no duplicate straight edge left to
+  cut and the pinched ring survives as one over-solid blob.
+- **Fix:** Use `corners: "sharp"` for an inward offset that is meant to split a
+  shape; or offset the pieces separately and union them. Check the result's region
+  count (`.toRegions().length`) rather than assuming the split happened.
+
+## shape2d-offset-kissing-ring-passes-validation
+
+- **Symptom:** *(Fixed in partforge 0.59 — kept because IDs are permanent.)* Two
+  rings produced by the same `Shape2D.offset` call — two eroding holes that grew into
+  each other, or a hole that eroded out through its own outer — used to come back
+  still separate and overlapping, and extruded to *solid* material inside the pocket
+  or a tab of material hanging off the outline.
+- **Cause:** The offset validator's ring-crossing test only looked for transversal
+  crossings, so two rings that interfere along a shared collinear edge (which is what
+  a sharp join produces) registered as fine; and its hole-containment test sampled a
+  single point of the hole ring, which stays inside even when most of the ring has
+  escaped. The cleanup stage then self-united everything under one even-odd compound,
+  where a doubly-covered region cancels back to solid instead of merging.
+- **Fix:** Upgrade to partforge ≥ 0.59, where `ringsCross` also tests collinear
+  overlap, hole containment tests the whole ring, and cleanup unites the outers and
+  *subtracts* the united hole rings. Nearby holes now merge into one hole and a
+  near-edge hole is clipped by its eroded outer. If a ring count still looks wrong
+  after an inward offset, see
+  [shape2d-offset-waist-not-severed-round-join](#shape2d-offset-waist-not-severed-round-join).
+
 ## fillet-chamfer-radius-does-not-fit
 
 - **Symptom:** `filletProfile: corner <i> at (<x>, <y>): r=<r> does not fit; max ≈ <m>` (or `chamferProfile: … dist=<d> does not fit; max ≈ <m>`) thrown from `Shape2D.fillet`/`.chamfer` or the free `filletProfile`/`chamferProfile` functions.

package/docs/KERNEL-CONTRACT.md

@@ -1,6 +1,6 @@
 # The partforge kernel contract
 
-**Contract version: 1** (introduced in partforge 0.9) — mirrored by `CONTRACT_VERSION`
+**Contract version: 2** (introduced in partforge 0.59) — 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.
 
@@ -116,13 +116,15 @@ 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.
+runtime warning) until a future breaking contract version removes them; a conforming
+implementation must accept both, and this repo's `finishKernel()`/`addSugar()`
+provide the normalization for free. (Contract v2, partforge 0.59, did **not** remove
+them — that bump was for `offset` semantics, see [Versioning](#versioning); legacy
+positional removal is still pending a version of its own.)
 
 ### Kernel factory ops (options-canonical; legacy positional accepted)
 
-| Op | Canonical options form | Legacy positional (until v2) |
+| Op | Canonical options form | Legacy positional (pending removal) |
 |---|---|---|
 | `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)` |
@@ -352,6 +354,8 @@ against that IR, and both backends instantiate it. Booleans run through **paper.
 `fillet`/`chamfer`/`simplify`, and `area`/`boundingBox`/`corners`/`contains` are
 **backend-identical**, not merely parity-tolerant. `area()` and `boundingBox()` are
 curve-exact (they integrate the real curves; they do not measure a tessellation).
+`offset` runs on this same shared engine (`geometry/contour-offset.js`) — see below —
+so it is backend-identical too, like everything else in this list.
 
 **Lazy materialization.** Backend geometry is built only where it is unavoidable.
 Three readbacks tessellate to point rings at the backend's own LOD (Manifold 116
@@ -365,16 +369,28 @@ contours — arcs and cubics become true B-rep edges). A `Shape2D` may be passed
 directly as the `profile` to `extrude`/`revolve`, holes included. `toContours()` is
 the one readback that tessellates nothing.
 
-**Offset is the carve-out.** `offset` is the one op that cannot run on the contour
-IR, so it routes into the backend's own 2-D engine (Clipper2 via `CrossSection` on
-Manifold, replicad's `Drawing.offset` on OCCT) and its result is lifted back into the
-IR. Manifold's returns line contours at mesh LOD; OCCT's stays curve-native. See the
-cross-backend note below.
+**Offset runs on the contour IR too.** `Shape2D.offset(delta, { corners })` runs
+backend-independently on the contour IR — no backend `CrossSection` or `Drawing` is
+ever involved. Lines and arcs offset exactly (arcs stay arcs); cubics are
+approximated to ≤ 1e-3 mm deviation. `corners: "round"` inserts exact arc joins,
+`"chamfer"` a true 45°-bisecting bevel chord at every corner angle, `"sharp"` miters
+with limit 2 (falling back to the bevel chord past the limit). Self-intersecting raw
+results are resolved through the shared planar boolean engine (paper.js), which may
+return arcs as cubic approximations — identical to boolean-op output. `segs` is
+accepted and ignored (there is no backend LOD to tune). Both backends produce
+identical offset geometry by construction, like every other Shape2D op.
+
+A region with holes offsets **material-wise**: the outer boundary moves by `delta`,
+each hole by `-delta`, so a positive `delta` always adds material (the outer grows,
+holes shrink) and a negative one always removes it (the outer shrinks, holes grow) —
+never the reverse for either. This one shared implementation is what guarantees it;
+a route that offsets a single fused `outer.cut(hole)` drawing with one call gets it
+backwards for the holes (see the migration note below).
 
 | 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). Curve-exact and backend-identical (paper.js). |
-| `offset(delta, {corners?, segs?})` | Grows (`delta>0`) or insets (`delta<0`) by `delta` mm; `corners` = `round` (default) / `chamfer` / `sharp`. The one backend-specific op: curve-preserving on OCCT, faceted at mesh LOD on Manifold. Throws if the offset collapses the shape. Empty in → empty out (short-circuits before the backend). |
+| `offset(delta, {corners?, segs?})` | Grows (`delta>0`) or insets (`delta<0`) by `delta` mm; `corners` = `round` (default) / `chamfer` / `sharp`. Runs backend-independently on the contour IR — lines/arcs offset exactly, cubics approximate to ≤ 1e-3 mm; `chamfer` is a true 45°-bisecting bevel at every corner angle, `sharp` miters with limit 2. Backend-identical by construction, like every other Shape2D op. Holes offset material-wise (`-delta` where the outer gets `delta`). `segs` is accepted and ignored. Empty in → empty out (short-circuits before the engine). Throws if the offset collapses the shape. |
 | `area()` | Net area (Σ\|outers\| − Σ\|holes\|), mm². Curve-exact. |
 | `boundingBox()` | `{min, max}` — axis-aligned 2-D bounds, curve-exact (no `center`/`size`, unlike `Solid.boundingBox`). |
 | `toRegions()` | Materialize into `{outer, holes}[]` point-ring region arrays (`assembleRegions`), tessellating curves at the backend's LOD; a boolean result may be several disjoint regions. |
@@ -404,9 +420,12 @@ pinned, Manifold silently built an empty solid where OCCT threw — behavior no
 could rely on portably, so defining it follows the reference backend and is not a
 contract break.)
 
-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`.
+On `offset`: `round`, `sharp`, and `chamfer` all agree across both backends **at every corner angle, convex or reflex** — a 10×10 square offset +1 gives 142.0 on both, a pentagon 298.920 on both, and an equilateral triangle's chamfer agrees to float precision on both, with no acute-corner carve-out. This follows from `offset` being one native implementation rather than a call into either backend's own 2-D engine — there is no Clipper2-vs-OCCT split left to diverge.
 
-`offset` is therefore **parity-relevant**: on OCCT the result carries exact arcs, on Manifold it is faceted at mesh LOD, and measure-parity holds within the tessellation tolerance as LOD converges (not a parity waiver). The three tessellating readbacks — `toRegions()`, `simple()`, `regions()` — are LOD-dependent for the same reason: they hand back point rings sampled at the backend's own segment count, so the two backends' output differs in vertex count and by the chord error, converging as LOD rises. Those four ops are the whole LOD-dependent surface; everything else is backend-identical.
+The three tessellating readbacks — `toRegions()`, `simple()`, `regions()` — remain LOD-dependent: they hand back point rings sampled at the backend's own segment count, so the two backends' output differs in vertex count and by chord error, converging as LOD rises. Those three ops are the whole LOD-dependent surface; everything else, including `offset`, is backend-identical.
+
+**Known limitations.** The native offset engine has verified defects on specific
+input shapes; see [Offset: known limitations](#offset-known-limitations) below.
 
 **Fillet after a boolean reaches STEP as real arcs.** Because booleans preserve curves
 and `fillet` inserts true arc segments, `shape2d(a).union(b).fillet(2).extrude({h})`
@@ -414,6 +433,46 @@ exports a filleted profile as `CIRCLE` B-rep entities on OCCT — the corner op
 have to run before the boolean, and no facet fan is baked in along the way. (Manifold
 facets at mesh LOD, as always, since its meshes have no curve representation.)
 
+### Offset: known limitations
+
+The native offset engine (`geometry/contour-offset.js`) is correct on the honest-agreement
+corpus (`test/contour-offset.test.js`, `test/offset-oracle-manifold.test.js`,
+`test/offset-oracle-occt.test.js`), but two cases are verified defects, pinned as
+characterization tests in the "known divergences (parked)" block of
+`test/offset-oracle-manifold.test.js` rather than silently tolerated:
+
+- **A pocket that should fully close doesn't.** An outward offset large enough that a
+  hole's max inscribed circle is smaller than `delta` should erase the hole entirely; the
+  engine instead leaves a residual ring. Verified: a 30×20 plate with a 5-wide-arm L-shaped
+  pocket, offset +3, should reach 0 holes / area 928.274 — actual leaves a residual hole at
+  ~921.21. Root cause: a raw offset ring can be locally valid (correctly wound, no
+  self-intersections) while still lying inside the region it should have been swept away
+  by — only a *global* containment check catches this, and none currently runs.
+- **Clustered reflex corners degrade accuracy.** A chamfer offset over several reflex
+  corners sitting close together can resolve to several times too much surviving area.
+  Verified: a 9-gon with clustered reflex corners, chamfer offset delta −2.79; true area
+  2.76 (a thin sliver), native resolves ~7.71. Root cause: `resolveSelfRegions`
+  (`paper-bridge.js`) doesn't fully untangle the self-intersections this corner geometry
+  produces.
+
+Neither is silent in the sense of going unnoticed by tests — each has a pinned
+characterization test that fails loudly if the defect gets worse, and is meant to be
+deleted and promoted to the main corpus the day it's fixed. They matter to a part author
+today: don't rely on `offset` to fully close a pocket, or to hold tight tolerance through a
+reflex-corner cluster — verify the result (`holes`/`area`) rather than assuming it.
+
+Two further cases were on this list and are now **fixed**, asserted as correctness in the
+same block: two eroding holes that grow into each other merge into one hole (40×20 plate,
+two 6×8 holes 3 mm apart, delta −2 sharp → area 348), and a hole that erodes through its
+outer boundary is clipped by it (40×20 plate, 10×10 hole 2 mm from the edge, delta −2 sharp
+→ area 408, hole absorbed into the outline). Both used to produce topologically invalid
+output — overlapping rings, or a hole ring outside its own outer — which even-odd fill then
+turned back into *solid* material on extrude (360 and 436 respectively). The fix was two
+missing checks in the fast-path validator (ring-crossing now also detects collinear overlap;
+hole containment now tests the whole hole ring, not one point of it) plus a cleanup stage
+that unites the outer rings and *subtracts* the united hole rings instead of self-uniting
+everything under one even-odd compound.
+
 ## The 2-D helper library
 
 `partforge/geometry` ships pure-JS helpers of several kinds. The **contour builders**
@@ -562,6 +621,48 @@ 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.
 
+**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
+changed, not just implementation: `offset` is now backend-identical by construction
+at every corner angle (the old acute-corner `chamfer` divergence and the LOD-faceted
+Manifold result are both gone), and `segs` is now accepted-but-ignored rather than
+tuning Manifold's tessellation. Holes offset material-wise (`-delta` where the outer
+gets `delta`) on both backends — the deleted OCCT production route got this backwards
+by fusing `outer.cut(hole)` into one `Drawing` and offsetting it with a single call,
+so holes grew under a positive `delta` instead of shrinking; no test caught it because
+there was no holed-offset test before this contract version. Parts that relied on the
+old holed-offset direction (if any existed) need the sign of their workaround removed.
+
+**`sharp` and `chamfer` change shape on acute corners — check these when migrating.** This
+is a real geometric change, not a precision polish, and it is the one thing v1 parts should
+be re-measured for. Once a convex corner gets tighter than 90° the two old backends did not
+agree with each other, and neither agreed with this repo's own `offsetPolygon`; v1's claim
+that "`round` and `sharp` are exact across backends at every angle" was simply false.
+Measured on an 11-point star (alternating radii 10 and 4) at `delta` +2:
+
+| corners | native (v2) | Clipper2 (v1 Manifold) | OCCT (v1 B-rep) | `offsetPolygon` |
+| --- | --- | --- | --- | --- |
+| `round` | 295.933 | 295.933 | 295.933 | 295.933 |
+| `sharp` | 282.158 | 300.671 | 326.534 | 282.158 |
+| `chamfer` | 278.389 | 288.138 | 278.389 | 278.389 |
+
+The spread is **miter-limit policy**, not accuracy: OCCT miters unbounded, so an acute spike
+shoots arbitrarily far past the corner; Clipper2 squares the corner off past its own limit
+rather than bevelling it. Native applies miter limit 2 and falls back to a plain bevel — the
+same rule `offsetPolygon` (`geometry/polygon.js`) has always used, so `offset` and
+`offsetPolygon` now agree to the digit where previously *neither* backend matched the pure-JS
+helper sitting next to it. `chamfer` additionally lands exactly on OCCT's `bevel` join; only
+Clipper2 differed there, because it had no bevel join and approximated one with two chords.
+
+Practical rule: divergence from v1 is confined to `sharp` and `chamfer` on **outward**
+offsets of shapes with sub-90° convex corners (star points, V-notches, triangles, spiky text
+serifs), and native is always the *smaller*, never the over-solid, result — a clearance
+offset that fit in v1 still fits. `round` is unchanged at every angle, inward offsets are
+unchanged, and shapes whose corners are all ≥90° (rectangles, hexagons, rounded-rects, slots)
+are unchanged. A random-polygon sweep put the >1%-divergent share at 1.6% overall, every one
+of them `sharp` or `chamfer` at positive delta.
+
 ## Why not an existing CAD language
 
 Considered and rejected as the part format (2026-07; revisit if the landscape shifts):

package/package.json

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