partforge 0.55.1 → 0.57.0

package/docs/AUTHORING-PARTS.md

@@ -1121,6 +1121,111 @@ const wall  = k.shape2d(outer).offset(-2, { corners: "sharp" });  // inset, mite
 
 `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.)
 
+## Editing profiles
+
+Once a profile exists — imported SVG, `pathProfile`, or the result of a boolean — the
+**2-D editing ops** let you reshape it with named operations instead of hand-editing
+control points: round or bevel a corner, nudge/rotate/mirror it, measure it, simplify
+it, or validate it. This is deliberately the same vocabulary an LLM agent calls: pick a
+corner, name a radius, get back a profile — never coordinate math. Every op is
+available two ways — as a `Shape2D` method (`plate.fillet(2)`) and as a free function
+over plain contour data (`filletProfile(outline, 2)`) — both run the same
+`contour-ops.js`/paper.js machinery.
+
+**Polymorphic input contract.** Every op below accepts a point list, a `{start,
+segments}` contour, a `{outer, holes}` region, or a region array, and returns the
+**same shape it was given** — a bare point list stays a point list, upgrading to a
+`{start, segments}` contour only if the op introduces curves (e.g. a fillet, or a
+non-uniform scale on an arc). The exception is the three arc-length queries
+(`profileLength`, `profilePointAt`, `profileTangentAt`): they are single-contour by
+nature, so passing a region throws, naming the accessor to use —
+`profilePointAt: pass a single contour (use region.outer / region.holes[i])`.
+
+**Transforms** — exact on every segment type (line, arc, cubic); mirror and
+non-uniform scale re-normalize winding (outer CCW, holes CW) afterward, so no op can
+hand the kernel an inverted region:
+
+| Function | Notes |
+|---|---|
+| `translateProfile(input, [dx,dy])` | exact on all segment types |
+| `rotateProfile(input, deg, center = [0,0])` | arcs stay arcs |
+| `scaleProfile(input, s \| [sx,sy], center = [0,0])` | non-uniform scale converts `{to,via}` arcs to cubics (an ellipse is not a circular arc) |
+| `mirrorProfile(input, axis)` | `axis: "x" \| "y" \| {point:[x,y], dir:[dx,dy]}` |
+
+**Corners** — fillet inserts a true `{to,via}` arc (a real STEP `CIRCLE` on OCCT);
+chamfer sets back `dist` along each adjacent segment and connects with a straight
+`{to}`. Both throw, precisely, when a radius/distance doesn't fit — naming the corner,
+its coordinates, and the max that would work — rather than silently clamping:
+
+| Function | Notes |
+|---|---|
+| `filletProfile(input, r, opts?)` | `r`: number, or an array matched positionally with `opts.corners.indices` |
+| `chamferProfile(input, dist, opts?)` | symmetric setback, straight connector |
+| `profileCorners(input)` | `[{index, point, interiorAngleDeg, convex, segTypes}]` |
+
+`opts.corners` selects which corners an op touches (default `"all"`):
+
+- `"all"` · `"convex"` · `"concave"`
+- `{indices: [...]}` — positions into `profileCorners(input)`'s own return order; pair
+  with an array `r`/`dist` for per-corner radii (the `roundedProfile` pattern)
+- `{near: [x,y], count?: 1}` — nearest-corner selection; the hook for a human pick or
+  an agent resolving "the top-left corner" from bbox reasoning
+
+```js
+// Fillet only the two corners nearest the profile's top edge, 3mm and 1.5mm:
+const corners = profileCorners(outline);
+const top = corners.filter((c) => c.point[1] > 20).map((c) => c.index);
+const rounded = filletProfile(outline, [3, 1.5], { corners: { indices: top } });
+
+// Fillet every convex corner of a Shape2D by the same amount:
+plate = plate.fillet(p.cornerR, { corners: "convex" });
+```
+
+**Queries, cleanup and validation:**
+
+| Function | Notes |
+|---|---|
+| `profileLength(contour)` | mm; single contour only |
+| `profilePointAt(contour, {t} \| {length})` | `t` ∈ [0,1] normalized arc length; single contour only |
+| `profileTangentAt(contour, {t} \| {length})` | unit vector; single contour only |
+| `profileNearestPoint(input, [x,y])` | `{point, distance, contourIndex, segmentIndex, t}` — accepts regions; the pick-resolution primitive |
+| `profileBounds(input)` | curve-exact `{min, max}` |
+| `profileArea(input)` | outers − holes, curve-exact |
+| `profileContains(input, [x,y])` | curve-aware containment (inside an outer, not inside a hole) |
+| `simplifyProfile(input, tolerance)` | corner-preserving: splits at corners, refits each smooth run within `tolerance` mm, rejoins — corners survive exactly, arcs entering it return as cubics |
+| `validateProfile(input)` | `{ok, issues: [{type, contourIndex, segmentIndex?, point?, message}]}`; never throws — `type` is `self-intersection`, `winding`, `nesting`, or `degenerate` |
+
+Two rules worth internalizing before reaching for any of this:
+
+- **Fillet after booleans if STEP `CIRCLE` fidelity matters.** Booleans run through
+  paper.js, which is cubic-only — an arc entering a boolean returns as a cubic
+  approximation (relative error ~1e-6). `union`/`cut` first, `fillet` last keeps the
+  rounded corners true circular arcs all the way to STEP export.
+- **Run `validateProfile` after mutations.** `fillet`/`chamfer` check only their own
+  corner's local fit — not whether the result self-intersects globally (a large radius
+  on a narrow profile can produce arcs that cross the far side). `validateProfile`
+  never throws, so it's cheap to call after any edit and inspect `issues` before
+  committing to the result.
+
+A practical trap with the broad selectors: `"all"`/`"convex"`/`"concave"` match **every**
+matching corner, including ones you didn't mean to touch. Union a curve-native outline
+with a *tessellated* point-list shape (e.g. `circleProfile`, still a faceted polygon —
+see "Profiles & patterns") and every one of that polygon's facet vertices becomes its
+own small convex corner in the result; a `corners: "convex"` fillet then tries to round
+all of them, including the tiny ones whose neighboring facet is too short to hold any
+useful radius. `profileCorners(input)` reports each corner's `interiorAngleDeg`, which
+cleanly tells a facet artifact (close to 180°, barely bent) from a real corner (well
+away from 180°) — filter on that, or pass a coarser `segs` to the tessellated shape
+before unioning, rather than fighting the selector after the fact.
+
+**`Shape2D` methods.** Existing: `union`, `cut`, `cutAll`, `intersect`, `offset`,
+`area`, `boundingBox`, `toRegions`, `simple`, `regions`, `clone`, `extrude`, `revolve`.
+New, all delegating to the pure functions above over the shape's stored contours:
+`translate([dx,dy])`, `rotate(deg, center?)`, `scale(s | [sx,sy], center?)`,
+`mirror(axis)`, `toContours()` (the stored contour IR, deep-copied — the one readback
+that tessellates nothing, unlike `toRegions()`), `fillet(r, opts?)`, `chamfer(dist,
+opts?)`, `simplify(tolerance)`, `corners()`, `contains([x,y])`.
+
 ## Convex hull
 
 `k.hull([a, b, …])` wraps its inputs (Shape2Ds, curve contours, or point lists) in a
@@ -1929,8 +2034,11 @@ 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, and routes accordingly — Manifold for
-everything else (so sweep-heavy parts, e.g. helical grooves, stay fast). Force it with
+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.
 

package/docs/ERROR-PATTERNS.md

@@ -52,8 +52,8 @@ 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 `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)".
+- **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 the whole part to OCCT. (`Shape2D.fillet`/`.chamfer` are the shared pure-JS implementation and do **not** route; the probe tracks which handle kind an op ran on.)
+- **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)".
 
 ## fillet-chamfer-many-edges-slow
 
@@ -306,6 +306,32 @@ 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.
 
+## 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.
+- **Cause:** The requested radius/distance exceeds what the corner's adjacent edges (or curved neighbor) can hold before the tangent point runs past the segment's own end.
+- **Fix:** Use the reported `max ≈` value, or narrow `opts.corners` to skip that corner. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Editing profiles".
+
+Variant literal for a curve-adjacent corner (note the semicolon form, not parenthesized): `filletProfile: corner <i> at (<x>, <y>): could not fit r=<r> against the curved segment; max ≈ <m>` (`chamferProfile: … could not fit dist=<d> against the curved segment; max ≈ <m>` for chamfer).
+
+## fillet-chamfer-corners-overlap
+
+- **Symptom:** `filletProfile: corners <i> and <j> overlap on segment <k> (reduce r)` (or the same from `chamferProfile`).
+- **Cause:** Two adjacent selected corners each claim more of the edge between them than it has — their combined setbacks exceed the segment's length (or curved arc-length span).
+- **Fix:** Reduce `r`/`dist`, or fillet/chamfer only one of the two corners (drop the other from `opts.corners`). See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Editing profiles".
+
+## profile-query-needs-single-contour
+
+- **Symptom:** `profilePointAt: pass a single contour (use region.outer / region.holes[i])` (same shape from `profileLength`/`profileTangentAt`, with their own name in place of `profilePointAt`).
+- **Cause:** The arc-length queries (`profileLength`, `profilePointAt`, `profileTangentAt`) are single-contour by nature, and a `{outer, holes}` region or region array was passed instead of a specific contour.
+- **Fix:** Pass `region.outer` or `region.holes[i]`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Editing profiles" polymorphic input contract.
+
+## validate-profile-regions-overlap-or-nest
+
+- **Symptom:** `regions overlap or nest — merge with union() or make it a hole` in a `validateProfile(...).issues` entry (`type: "nesting"`) — reported, never thrown.
+- **Cause:** Two regions in the profile occupy overlapping area without one being declared a hole of the other.
+- **Fix:** Union the two regions into one shape, or restructure the overlapping region as a `holes` entry of its container. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Editing profiles" — run `validateProfile` after mutations.
+
 ## curve-fill-resolved-hole-uncontained
 
 - **Symptom:** `curve-fill: resolved hole has no containing outer`

package/docs/KERNEL-CONTRACT.md

@@ -51,8 +51,10 @@ 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.
+op **on a Solid handle** routes the whole part 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). A host with only a core kernel must surface the error ("this part needs a
+B-rep backend") rather than swallow it.
 
 ## Global semantics
 
@@ -328,44 +330,79 @@ 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.
+holes?}` region, region array, or arc/curve contour into a `Shape2D` — a 2-D
+sketch value carrying booleans, transforms, corner ops and queries. Idempotent:
+`shape2d(x)` returns `x` unchanged if `x` is already a `Shape2D`. `_`-prefixed
+keys are internals. Normative signatures: `kernel.js`'s `@typedef Shape2D`; the
+full public surface is `SHAPE2D_OPS`. The `kernel-front.js`
+`KernelCapabilityError` stub for `shape2d` is a dead / future-backend safety net
+only (both current backends define the op), not an OCCT limitation.
+
+**Contour storage.** A `Shape2D` stores a **curve-native contour IR** — a region
+list `[{outer, holes[]}]` whose contours are `{start, segments}` with line, arc
+(`{to, via}`) and cubic (`{to, c1, c2}`) segments. It is *not* a backend handle:
+no `CrossSection` and no replicad `Drawing` exists until the shape is handed to a
+kernel op. Curves therefore survive every op, on both backends — a rounded corner
+is still a circle after a union, and reaches STEP as a real `CIRCLE` entity.
+
+**One shared implementation.** `geometry/shape2d.js` implements the whole surface
+against that IR, and both backends instantiate it. Booleans run through **paper.js**
+(pure JS, curve-exact), as do the transforms, corner ops and queries — so
+`union`/`cut`/`intersect`/`cutAll`, `translate`/`rotate`/`scale`/`mirror`,
+`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).
+
+**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
+preview / 480 print, OCCT 64): `toRegions()`, `simple()` (its unwrapped form), and
+`regions()` — scission currently round-trips through `toRegions()`, so each returned
+`Shape2D` is a faceted copy, not a curve-native slice of the original. `extrude` and
+`revolve` materialize the shape into the backend's own form instead (Manifold: a
+`CrossSection`, memoized in the solid cache by content hash + LOD, so extruding the
+same shape twice tessellates once; OCCT: a fresh `Drawing` per call, drawn from the
+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.
 
 | 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. |
+| `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. |
+| `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. |
+| `toContours()` | The stored contour IR — `{outer, holes}[]` of `{start, segments}` contours, **curve-native and lossless** (no tessellation). Returns a deep copy, safe to mutate. |
 | `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. |
+| `regions()` | Scission: each disjoint region as its own live `Shape2D[]` (each further boolean-able), vs `toRegions()` which returns raw `{outer, holes}` data. Goes through `toRegions()`, so the pieces are tessellated at the backend's LOD — curves do not survive scission. |
+| `translate([dx,dy])` / `rotate(deg, center?)` / `scale(f\|[sx,sy], center?)` / `mirror(axis)` | Rigid/similarity transforms on the contours (curve-preserving). `center` defaults to the origin; `axis` is `"x"`, `"y"`, or `{point, dir}`. `scale`'s factor is uniform when a bare number, per-axis when `[sx,sy]`. |
+| `fillet(r, {corners?})` / `chamfer(d, {corners?})` | Round (true arcs) or bevel (straight chords) selected corners. `corners` = `"all"` (default) / `"convex"` / `"concave"` / `{indices}` / `{near, count?}`; `r`/`d` may be an array paired positionally with `{indices}`. Throws when no corner matches. |
+| `simplify(tolerance)` | Corner-preserving decimation/refit within `tolerance` mm — dense point rings become fewer segments (and refit arcs/cubics) without moving corners. |
+| `corners()` | The corner list — `{index, point, interiorAngleDeg, convex, segTypes}[]`. This positional order is what `fillet`/`chamfer`'s `{indices}` selects into. |
+| `contains([x,y])` | Point-in-shape test (inside an outer, not inside a hole). |
 | `extrude({h, twist?, scaleTop?})` | Sugar for `k.extrude({profile: this, …})` → `Solid`. |
 | `revolve({degrees?})` | Sugar for `k.revolve({profile: this, …})` → `Solid`. |
-| `clone()` | Independent handle. |
+| `clone()` | Independent copy. Every op returns a NEW `Shape2D`; no operand is ever mutated. |
 
 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.
+`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.
 
-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.
+**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})`
+exports a filleted profile as `CIRCLE` B-rep entities on OCCT — the corner op does not
+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.)
 
 ## The 2-D helper library
 
-`partforge/geometry` ships pure-JS helpers of two kinds. The **contour builders**
+`partforge/geometry` ships pure-JS helpers of several 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
@@ -376,14 +413,54 @@ dependency at all. The **solid patterns** (`linearPattern`, `circularPattern`) t
 `{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.)
+geometry. All 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.
 
+### 2-D editing ops
+
+The **2-D editing ops** are the free-function twins of the `Shape2D` transforms,
+corner ops and queries documented above — the same `contour-ops.js`/paper.js
+machinery, callable directly on a point list, a `{start, segments}` contour, a
+`{outer, holes}` region, or a region array, with no `shape2d()` lift required.
+Every op returns the same shape of input it was given (a bare point list stays a
+point list, upgrading to a contour only if the op introduces curves — e.g. a
+non-uniform scale on an arc). The arc-length queries are the one exception:
+being single-contour by nature, they throw on a region. The full set: `translateProfile`,
+`rotateProfile`, `scaleProfile`, `mirrorProfile`, `filletProfile`, `chamferProfile`,
+`profileCorners`, `profileLength`, `profilePointAt`, `profileTangentAt`,
+`profileNearestPoint`, `profileBounds`, `profileArea`, `profileContains`,
+`simplifyProfile`, `validateProfile`.
+
+| Group | Function | Notes |
+|---|---|---|
+| Transforms | `translateProfile(input, [dx,dy])` | exact on all segment types |
+| | `rotateProfile(input, deg, center?)` | arcs stay arcs |
+| | `scaleProfile(input, s \| [sx,sy], center?)` | non-uniform scale converts `{to,via}` arcs to cubics |
+| | `mirrorProfile(input, axis)` | `axis: "x" \| "y" \| {point, dir}` |
+| Corners | `filletProfile(input, r, opts?)` | `r` may be an array paired with `{indices}` |
+| | `chamferProfile(input, dist, opts?)` | symmetric setback, straight connector |
+| | `profileCorners(input)` | `[{index, point, interiorAngleDeg, convex, segTypes}]` |
+| Queries | `profileLength(contour)` | mm; single contour only |
+| | `profilePointAt(contour, {t} \| {length})` | single contour only |
+| | `profileTangentAt(contour, {t} \| {length})` | unit vector; single contour only |
+| | `profileNearestPoint(input, [x,y])` | `{point, distance, contourIndex, segmentIndex, t}`; accepts regions |
+| | `profileBounds(input)` | curve-exact `{min, max}` |
+| | `profileArea(input)` | outers − holes, curve-exact |
+| | `profileContains(input, [x,y])` | curve-aware containment |
+| Cleanup | `simplifyProfile(input, tolerance)` | corner-preserving decimation/refit |
+| Validation | `validateProfile(input)` | `{ok, issues}`; never throws |
+
+`filletProfile`/`chamferProfile`'s `opts.corners` selector and `profileCorners`'s
+positional order match `Shape2D.fillet`/`Shape2D.chamfer`/`Shape2D.corners`
+exactly — `CornerSelector` above applies unchanged. Mirror and negative-scale
+inputs re-normalize winding (outer CCW, holes CW) before returning, so no op can
+hand the kernel inverted regions.
+
 ## Worker rebind
 
 The op tables above are the portable seam for *geometry*; this section is the matching

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.55.1",
+  "version": "0.57.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/app-gasket.js

@@ -0,0 +1,14 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
+import part from "./parts/gasket.js";
+import { mount } from "./framework/index.js";
+
+// Dev example app for the gasket demo (src/parts/gasket.js). The
+// `new Worker(new URL(...))` call must stay inline here so Vite bundles the worker.
+mount(part, {
+  createWorker: (name) =>
+    new Worker(new URL("./gasket-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/framework/animation-controls.js

@@ -249,11 +249,19 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   scrubWrap.addEventListener("pointerleave", onWrapPointerLeave);
   scrubWrap.addEventListener("pointercancel", onWrapPointerLeave);
 
+  // Late-bound hook into the placement section below (a plain call would hit
+  // the TDZ on its `let placementRaf` — setup invokes syncStructure before the
+  // placement block runs). Wired to schedulePlacement once that block exists,
+  // so a view switch that shows/hides the bar re-publishes --pf-anim-clear
+  // even where ResizeObserver is absent.
+  let onStructureChanged = null;
+
   // Per-view + per-animation chrome: which chooser shows, the picker's options,
   // title, ⓘ description, pager labels, scrubber ticks. A view with no
   // animations hides the whole bar rather than showing an empty transport.
   function syncStructure() {
     bar.style.display = current ? "" : "none";
+    onStructureChanged?.();
     hideChapterBubble();
     if (!current) return;
     const paged = animations.length > 1;
@@ -536,10 +544,20 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     bar.style.maxWidth = "";
     bar.style.overflow = "";
     bar.classList.remove("pf-squeezed");
-    const vb = viewbarEl?.getBoundingClientRect();
+    const stageRect = container.getBoundingClientRect();
     const barRect = bar.getBoundingClientRect();
+    // Publish the bar's vertical claim on the stage as --pf-anim-clear: the
+    // distance from the stage's bottom edge to the bar's top, 0px when the bar
+    // is hidden (a view with no animations). Hosts that float their own chrome
+    // at the stage's bottom-centre (partforge-cloud's status/forging stack)
+    // read it to sit above the bar instead of under it; with no bar mounted
+    // the property is never set and a var() fallback of 0px applies.
+    const clear = bar.style.display === "none"
+      ? 0
+      : Math.max(0, Math.round(stageRect.bottom - barRect.top));
+    container.style.setProperty("--pf-anim-clear", `${clear}px`);
+    const vb = viewbarEl?.getBoundingClientRect();
     if (!vb || barRect.top >= vb.bottom || barRect.bottom <= vb.top) return;
-    const stageRect = container.getBoundingClientRect();
     const plan = planAnimBarPlacement({
       stageWidth: stageRect.width,
       barWidth: barRect.width,
@@ -581,6 +599,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     placementObserver.observe(bar);
     if (viewbarEl) placementObserver.observe(viewbarEl);
   }
+  onStructureChanged = schedulePlacement; // see the hook's declaration above
   schedulePlacement();
 
   const runtime = {
@@ -662,6 +681,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
       scrubWrap.removeEventListener("pointercancel", onWrapPointerLeave);
       hideChapterBubble(); // also clears hoverInside
       chapterBubble.remove(); // a stage child, so the bar taking itself out misses it
+      container.style.removeProperty("--pf-anim-clear"); // no bar, no claim
       bar.remove();
     },
     __viewer: viewer, // test hook only

package/src/framework/backend-select.js

@@ -16,10 +16,13 @@ export function detectBackend(part, params = {}) {
   // regen (after the busy spinner goes up). Probe with an empty `d`; the worker
   // build hits the same throw and posts a proper error for the UI.
   try { d = resolveDerived(part, p); } catch { /* fall through with d = {} */ }
-  const { kernel, used } = createProbeKernel();
+  const { kernel, solidUsed } = createProbeKernel();
   for (const name of Object.keys(part.parts)) {
     try { part.parts[name].build(kernel, p, d); } catch { /* probe miss → capability backstop covers it */ }
   }
-  for (const op of used) if (OCCT_ONLY.has(op)) return "occt";
+  // solidUsed, not used: `Shape2D.fillet`/`.chamfer` are the shared pure-JS
+  // implementation (backend-identical) and must not drag a part onto OCCT — only
+  // the same names called on a Solid are CAD-only.
+  for (const op of solidUsed) if (OCCT_ONLY.has(op)) return "occt";
   return "manifold";
 }

package/src/framework/chrome.css

@@ -234,7 +234,13 @@
    #viewbar's, so a host that re-anchors this bar still inherits its chrome.
    animation-controls.js may inline-override left/transform/max-width (and
    overflow while width-capped) to hold a 10px gap to #viewbar, and clears
-   the overrides whenever centered placement fits. */
+   the overrides whenever centered placement fits.
+
+   animation-controls.js also publishes --pf-anim-clear on the STAGE element:
+   the px distance from the stage's bottom edge to the visible bar's top (0px
+   while the active view has no animations; unset when no view declares any).
+   A host floating its own chrome at the stage's bottom-centre should anchor it
+   at calc(var(--pf-anim-clear, 0px) + <gap>) to stack above the bar. */
 .pf-anim-bar {
   position: absolute; left: 50%; bottom: 14px; transform: translateX(-50%);
   z-index: 15; max-width: calc(100% - 24px);