partforge 0.59.0 → 0.60.1

package/docs/ERROR-PATTERNS.md

@@ -308,19 +308,19 @@ Variant literals under this entry: `offsetPolygon: delta must be a finite number
 
 ## 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.
+- **Symptom:** *(Fixed for positive round offsets in `0.60.0`; the ID remains
+  permanent.)* An outward `Shape2D.offset` on a region with a hole could leave a
+  residual hole ring after the source counter should have closed.
+- **Cause:** A fully eroded source counter could survive the raw offset as a
+  locally valid negative loop. Positive-winding cleanup then correctly preserved
+  that loop because the defect was introduced before winding classification.
+- **Fix:** The round resolver now computes a conservative largest-inscribed-disk
+  bound from the source hole and removes a residual counter only when the requested
+  dilation has certainly passed its source inradius. Upgrade to
+  `partforge >= 0.60.0`. Sharp and chamfer offsets use different structuring
+  elements and are not covered by this round-specific gate; continue to verify
+  those styles at the production offset and use explicit boolean stages when their
+  closing topology is critical.
 
 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
@@ -328,39 +328,40 @@ 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.
+- **Symptom:** *(Fixed in `0.60.0`; the ID remains permanent.)* An inward
+  `Shape2D.offset` with clustered reflex corners could retain material outside the
+  true eroded shape.
+- **Cause:** The old overlap-side trim could extend offset lines to an intersection
+  outside the finite extent of one or both segments. The deleted Paper.js
+  `resolveSelfRegions` path is not part of the current resolver.
+- **Fix:** Overlap-side trimming now requires the intersection to lie within both
+  segment extents, and the resulting arrangement is resolved by positive winding.
+  Upgrade to `partforge >= 0.60.0`. The regression oracle pins the clustered-reflex
+  9-gon chamfer area at approximately `3.553831 mm²`.
 
 ## 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.
+- **Symptom:** *(Fixed — kept because IDs are permanent. This pattern no longer
+  exists.)* An inward `Shape2D.offset` past the width of a narrow waist used to leave
+  the shape connected (or add a spurious blob where the waist was) under
+  `corners: "round"` or `"chamfer"`, while `"sharp"` split it correctly. The entry's
+  own witness now behaves: a 30×10 dumbbell with a 2-wide waist at `delta` −2 severs
+  into **two** regions under all three joins — 72.346873 round, 74.000000 chamfer,
+  72.000000 sharp — against the three regions and 97.258 the round join used to give.
+- **Cause:** The waist recovery it described (`splitAtDuplicateEdges` in
+  `contour-offset.js`) matched a pair of duplicate, exactly-collinear edges, so it only
+  ever handled rings made entirely of straight lines; a round or chamfer join left an
+  arc or bevel chord at the pinch with no duplicate edge to cut. That function no longer
+  exists anywhere in `src/` — the whole boolean/heuristic cleanup path was replaced by
+  the winding resolver (`geometry/contour-winding.js`), which computes the
+  positive-winding region of the raw outline directly and severs a pinched waist as an
+  ordinary consequence of that, with no per-shape recovery and no join casing.
+- **Fix:** Nothing to work around; the advice this entry used to give ("use
+  `corners: "sharp"` to split") is obsolete and was making callers change corner style
+  for no reason. If a region count still looks wrong after an inward offset, see
+  [shape2d-offset-winding-chain-incomplete](#shape2d-offset-winding-chain-incomplete)
+  and the parked cases in [KERNEL-CONTRACT.md "Offset: known
+  limitations"](KERNEL-CONTRACT.md#offset-known-limitations).
 
 ## shape2d-offset-kissing-ring-passes-validation
 
@@ -382,6 +383,29 @@ growing a shape past the hole's own width.
   after an inward offset, see
   [shape2d-offset-waist-not-severed-round-join](#shape2d-offset-waist-not-severed-round-join).
 
+## shape2d-offset-winding-chain-incomplete
+
+- **Symptom:** `contour-winding: could not chain offset boundary (incomplete intersection
+  set)` thrown from `Shape2D.offset` (or `offsetPolygon`) after a raw offset self-overlaps
+  at a narrow pinch.
+- **Cause:** *(Known corpus fixed in partforge 0.60; ID retained permanently.)* The resolver
+  used to classify every boundary piece from one fixed midpoint probe. At a narrow cell that
+  probe could cross a nearby non-incident edge, read the wrong winding on both sides, and
+  drop a real continuation. Fully eroded round text counters were a separate upstream cause:
+  their raw offset could retain a negative pocket even under a correct Positive fill.
+- **Fix:** Upgrade to partforge ≥ 0.60. The classifier now chooses among deterministic
+  interior samples by local boundary clearance and caps its probe distance accordingly.
+  Positive round offsets also decide counter collapse from the source hole's inradius before
+  generating a raw outline. On the committed 36,090-offset corpus
+  (`node scripts/offset-rates.mjs`), chain failures before the retry ladder are
+  1 round / 2 chamfer / 4 sharp and **zero remain after it**; the full glyph matrix,
+  including `"Scott"` through +3, has no throw or topology divergence.
+
+  The literal error remains intentionally loud if a new pathological arrangement defeats
+  every retry rung. If it appears on ≥0.60, report the profile, delta, and corner style so it
+  can become a deterministic fixture. Reducing `|delta|` or simplifying nearly coincident
+  features is a temporary workaround; changing corner style is not a reliable general fix.
+
 ## 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

@@ -424,8 +424,12 @@ On `offset`: `round`, `sharp`, and `chamfer` all agree across both backends **at
 
 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.
+**Known limitations.** The native offset engine has verified defects on specific input
+shapes — on inward offsets that sever a shape, and on outward offsets of text — under **all
+three corner styles at nearly the same rate**; see [Offset: known
+limitations](#offset-known-limitations) below for the parked cases, their measured values,
+the committed corpus and script that produce every rate quoted there, and the independent
+construction the truths come from.
 
 **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})`
@@ -435,44 +439,53 @@ 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 native offset engine preserves line, arc, and cubic contour IR through its normal cleanup
+path. Tangled raw offsets are split at crossings, classified under the Positive winding rule,
+and chained back into regions by `geometry/contour-winding.js`. Positive round dilation also
+uses the source hole's inradius to prove when a counter has fully closed, and positive
+dilation drops output components that contain no source material. These are source-domain
+topology proofs, not output-area heuristics.
+
+The reported text case is covered as correctness in
+`test/offset-oracle-manifold.test.js`: the 6-glyph × 7-delta round matrix, including
+`"Scott"` at +0.8/+1.5/+2/+3, matches Clipper2 region and hole counts exactly and stays
+within the corpus area tolerance. `"Scott"` retains native arcs and cubics at every tested
+delta.
+
+**Measured failure surface.** The committed instrument is
+`node scripts/offset-rates.mjs`, over 600 deterministic seeded shapes plus six glyph cases,
+20 deltas, and three corner styles (36,090 attempts). In partforge 0.60 it reports:
+
+- before the retry ladder: round 1/12,030 (0.008%), chamfer 2/12,030 (0.017%), sharp
+  4/12,030 (0.033%);
+- after the retry ladder: zero chain-incomplete failures for all three styles;
+- seven oracle-checked rescues, with median area error 0.0972%, worst 1.663%
+  (2.2373 mm²), zero region-count losses, and zero complete arc losses.
+
+The ladder remains a numerical escape hatch: it perturbs delta by 1e-9, coarsens crossing
+clustering, then tries polyline outlines. A future case that reaches a coarse clustering or
+polyline rung can still lose fine topology or native arcs, so the order remains
+fidelity-first and every newly found rescue must be checked against the independent
+Minkowski oracle.
+
+The currently parked limitations are narrower:
+
+- **Round erosion with several holes reaching the eroded outer can keep too much material.**
+  The characterized 30×20 plate with three rectangular holes at −2 returns about 324.75
+  instead of the 258.18 oracle truth under round corners; chamfer and sharp are exact.
+- **Fully eroded holes under sharp and chamfer can leave a remnant.** The source-inradius
+  gate is intentionally limited to round joins, whose structuring element is a Euclidean
+  disk. A 1×1 hole at +2 closes correctly under round, while the sharp/chamfer variants
+  remain parked rather than applying the wrong geometric criterion.
+- **Erosion can emit sub-0.001 mm² rings.** Five exact seeded cases are pinned in
+  `test/offset-fuzz.test.js`. They are not automatically deleted: unlike positive
+  dilation, erosion has no source-membership invariant that distinguishes a false island
+  from a genuine surviving crumb.
+
+The fuzz oracle sweep covers 150 seeded shapes × 6 deltas × 3 styles and currently reports
+no region-count, hole-count, or area disagreements outside those explicit
+characterizations. Do not widen tolerances or add an area-based sliver filter when a new
+case appears; add its deterministic fixture and establish the source-domain truth first.
 ## The 2-D helper library
 
 `partforge/geometry` ships pure-JS helpers of several kinds. The **contour builders**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.59.0",
+  "version": "0.60.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",
@@ -81,7 +81,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json",
-    "check": "node scripts/check-app.mjs"
+    "check": "node scripts/check-app.mjs",
+    "offset-rates": "node scripts/offset-rates.mjs"
   },
   "dependencies": {
     "dompurify": "^3.4.11",