partforge 0.81.0 → 0.83.0

package/bin/cli.js

@@ -438,6 +438,34 @@ function printMeasure(r) {
   console.log(`  near-misses: ${r.nearMisses.length
     ? r.nearMisses.map((g) => `${g.a}×${g.b} (${g.distance.toFixed(2)}mm at [${g.at.map((n) => n.toFixed(1)).join(", ")}])`).join(", ")
     : "none"}`);
+  if (r.probes) {
+    // Solid-fact probes get the sub-part line treatment (in mm³ — probes are
+    // localization instruments, a slab's volume in cm³ rounds to noise), one
+    // level deep too so the common paired shape ({ mine, ref }) reads as lines
+    // rather than a JSON wall; anything else prints as JSON; a failed probe
+    // prints its error where the reader is.
+    const isFacts = (v) => v && typeof v === "object" && "empty" in v && "volume" in v;
+    const factsLine = (v) => (v.empty
+      ? `empty (no material in the probed region)`
+      : `bbox ${v.bbox.map((n) => n.toFixed(2)).join("×")}  ` +
+        `bounds [${v.bounds.min.map((n) => n.toFixed(2)).join(", ")}]…[${v.bounds.max.map((n) => n.toFixed(2)).join(", ")}]  ` +
+        `vol ${v.volume.toFixed(2)}mm³`);
+    console.log(`  probes:`);
+    for (const [name, v] of Object.entries(r.probes)) {
+      if (v && typeof v === "object" && typeof v.error === "string") {
+        console.log(`    ${name}  ERROR: ${v.error}`);
+      } else if (isFacts(v)) {
+        console.log(`    ${name}  ${factsLine(v)}`);
+      } else if (v && typeof v === "object" && !Array.isArray(v) && Object.values(v).some(isFacts)) {
+        console.log(`    ${name}:`);
+        for (const [key, sub] of Object.entries(v)) {
+          console.log(`      ${key}  ${isFacts(sub) ? factsLine(sub) : JSON.stringify(sub)}`);
+        }
+      } else {
+        console.log(`    ${name}  ${JSON.stringify(v)}`);
+      }
+    }
+  }
 }
 
 function printVerify(v) {

package/docs/AUTHORING-PARTS.md

@@ -88,6 +88,8 @@ export default {
     },
   },
   views: { <name>: { label, default?, animations? } },  // view tabs; a view may own animations (below)
+  probes?,                                 // { name: (k, p, d) => Solid | plain JSON } — measurements reported by
+                                           // measure/inspect, never rendered or exported (see "Probes" below)
 };
 ```
 
@@ -313,7 +315,7 @@ and the detection rule.
 | `k.box({ size, center? })` · `k.box({ min, max })` | `{size:[x,y,z]}` = centered X/Y, base at z=0 (`center:true` also centers Z); `{min,max}` = explicit `[x,y,z]` corners |
 | `k.prism({ points, h, twist?, scaleTop? })` | extrude a 2-D polygon (or an **arc profile** from `roundedProfile`) from z=0; optional `twist` (degrees over the height) and `scaleTop` (uniform top taper: 1 straight, <1 taper in, 0 → point/cone) |
 | `k.extrude({ profile, h, twist?, scaleTop? })` | extrude a **polygon-with-holes** region from z=0 in one op — `profile` is `{ outer, holes? }` where each contour is a points array **or an arc profile** (`roundedProfile`, for true STEP fillets), or a bare points array / arc profile for outer-only; same `twist`/`scaleTop` as `prism` (both backends) |
-| `k.loft({ rings, ruled?, closed?, shading? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls. `shading?: "smooth" \| "faceted"` overrides facet/smooth shading inference (default: <32-side rings shade as flat facets, drawing no same-surface lines at all — not even their own cap rims — though cut seams against other solids still draw; ≥32 sides shade smooth) |
+| `k.loft({ rings, ruled?, closed?, shading? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). A ring's `polygon` may be a point list, `sides`+`radius`, a curve contour, or a single-region hole-free `Shape2D` (multi-region / holed shapes throw). Identical all-line rings are bit-identical on both backends (unchanged legacy). Identical curve-structure rings loft curve-natively on OCCT (STEP keeps true arcs) and facet at fixed LOD on Manifold; structurally different rings auto-resample to a common vertex count with a deterministic seam and share the same faceted STEP at sampling LOD on both backends. `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls. `shading?: "smooth" \| "faceted"` overrides facet/smooth shading inference (point-ring default: <32-side rings shade as flat facets, drawing no same-surface lines at all — not even their own cap rims — though cut seams against other solids still draw; ≥32 sides shade smooth. Curve/resample rings shade by tessellation provenance — smooth only along smooth contour spans, with dividing lines at sharp corners and silhouette-kink rings; see the shading-intent note) |
 | `k.sweep({ profile, path, cornerRadius?, closed?, ruled?, smooth? })` | sweep a fixed 2-D profile along a 3-D polyline path — sharp mitered corners (or `cornerRadius` fillets), capped ends (both backends). `closed:true` capless loops and `smooth:true` (OCCT-native swept B-rep, STEP-exact / preview-faceted) are backend-specific, like loft's `closed`/`ruled:false`. `closed:true` loops must be **planar** — RMF frame-transport holonomy can seam-twist a non-planar closed loop where the last station rejoins the first, so only planar closed loops are supported/tested |
 | `k.sphere({ r\|d })` | sphere centred at the origin; bare `k.sphere(r)` also stays valid |
 | `k.roundedBox({ size, center?, round })` | box with rounded edges — `round` = number (all edges) or `{ side?, top?, bottom? }` (vertical edges / rims); built as one hand-meshed ring stack (no booleans at all, cheaper than `fillet`'s cutters); `side` must be 0 or ≥ the rim radii (between clamps with a warning); with `side > 0`, `top + bottom` must be strictly `< h` |
@@ -324,16 +326,32 @@ and the detection rule.
 | `k.screwSweep({ profile, pitch, turns, lefthand? })` | screw-motion sweep of an **axial** lathe profile `[[r, z], …]` (same convention as `k.revolve`) — threads, worms, helical ridges. `h = pitch · turns`. The profile's axial extent must not exceed `pitch`; a profile spanning exactly `pitch` must be **periodic** (first radius == last radius) and yields a complete threaded body with no boolean (both backends) |
 | `k.union(solids[])` | boolean union |
 
-**`loft` rings** — each ring is `{ polygon:[[x,y],…] | sides+radius, z, rotate?, scale? }`
-(all rings must share the same vertex count; `rotate` is degrees about Z, `scale` is a
-number or `[sx,sy]`). Author rings CCW and ordered by ascending `z` (the `regularPolygon`
-/ `polygon.js` helpers are already CCW); loft self-corrects a fully-inverted result so
-CW-wound or descending-z rings still export a valid outward solid. (Arc profiles from
-`roundedProfile` are **not** accepted as loft rings yet — a ring must be a point array;
-use `prism`/`extrude` for true-arc STEP export.) **`sweep`** takes the same CCW
-`polygon.js` outline as its `profile` and a plain `[[x,y,z],…]` point list as its
-`path`; the profile stays perpendicular to the path (a rotation-minimizing frame), with
-sharp mitered corners by default or `cornerRadius` fillets. Worked snippets:
+**`loft` rings** — each ring is `{ polygon:[[x,y],…] | sides+radius | {start,segments} | Shape2D, z, rotate?, scale? }`
+(`rotate` is degrees about Z, `scale` is a number or `[sx,sy]`). A ring's `polygon` may be:
+- a point list `[[x,y],…]` — plain polygon
+- `{sides, radius}` — shorthand for a regular polygon
+- a curve contour `{start:[x,y], segments:[...]}` — from `roundedProfile` (true CIRCLE/CUBIC edges in STEP)
+- a single-region hole-free `Shape2D` — from a 2-D boolean, fillet, or other shape operation
+
+Rings with **identical all-line segment structure** (the same straight-sided shape at different z/scale/rotate) are
+bit-identical on both backends — unchanged legacy behavior, parity by construction. When such a ring set mixes a
+point-list ring with a Shape2D/contour-sourced one, start-vertex correspondence is not author-controlled (a Shape2D's
+contour starts wherever its outline begins) — use per-ring `rotate`, or keep every ring the same form, to control twist
+phase. Rings with **identical curve structure**
+(containing arcs/Béziers, the same shape at different z/scale/rotate) loft curve-natively on OCCT (STEP keeps exact arc
+edges), while a Manifold preview facets at fixed LOD. **Structurally different rings** (e.g. a square morphing to a circle,
+or unequal-N point lists) auto-resample to a common vertex count in shared pure-JS code, with seam = the outermost +X-ray
+crossing from each ring's centroid; use per-ring `rotate` to tune the twist phase. Every backend then lofts the identical
+resampled point rings — parity by construction on both — and STEP is faceted at the sampling LOD.
+
+Author rings CCW and ordered by ascending `z` (the `regularPolygon` / `polygon.js` helpers are already CCW);
+loft self-corrects a fully-inverted result so CW-wound or descending-z rings still export a valid outward solid.
+Multi-region or holed `Shape2D` throws — loft each region as its own solid and union the lofts, or cut holes from
+the lofted solid after it closes.
+
+**`sweep`** takes the same CCW `polygon.js` outline as its `profile` and a plain `[[x,y,z],…]` point list as its
+`path`; the profile stays perpendicular to the path (a rotation-minimizing frame), with sharp mitered corners by
+default or `cornerRadius` fillets. Worked snippets:
 
 ```js
 // a square tube (extrude a region with a hole) — one op, no boolean cut
@@ -1520,6 +1538,76 @@ keeps only the seams:
   `meshTriangles`, `parseStl`, `parse3MF`); those exports are part of its contract.
 
 
+## Probes: measuring geometry into the report
+
+A `probes` block turns the measure report into an instrument panel. Each probe is
+a pure `(k, p, d)` function with **build's exact contract** — same kernel handle,
+same resolved params and derived values — but its result lands in the **report**
+instead of the scene:
+
+```js
+probes: {
+  // A Solid anywhere in the return value is measured into a fact object:
+  // { empty, bbox, bounds, centerOfMass, volume, surfaceArea, triangleCount,
+  //   watertight, holes }
+  slabX12: (k, p, d) => buildBody(k, p, d)
+    .intersect(k.box({ min: [12, -25, -4], max: [13, 25, 4] })),
+
+  // The paired form — the localizing workhorse when a rebuild drifts from its
+  // imported reference: the same thin slab through both solids, side by side.
+  slabPair: (k, p, d) => ({
+    mine: buildBody(k, p, d).intersect(k.box({ min: [12, -25, -4], max: [13, 25, 4] })),
+    ref:  k.import("scan").intersect(k.box({ min: [12, -25, -4], max: [13, 25, 4] })),
+  }),
+
+  // Plain JSON passes through verbatim — compute any number the solid queries
+  // can reach (volume/boundingBox booleans, arc fits, whatever).
+  xor: (k, p, d) => {
+    const mine = buildBody(k, p, d), ref = k.import("scan");
+    return mine.volume() + ref.volume() - 2 * mine.intersect(ref).volume();
+  },
+}
+```
+
+**Where they show up.** `npx partforge measure` prints a `probes:` section and
+includes `probes: { name: value }` in `--json`; the worker's `inspect` job carries
+the same key, so any host reporting measure output (e.g. an agent's check loop)
+sees probe values on every edit with no extra wiring. Probes are **part-level,
+not per-view**: every measured view reports them, so they never disappear because
+the "wrong" tab was measured.
+
+**What they replace.** Before probes, getting a cross-section's numbers out of
+the pipeline meant authoring throwaway `exportable: false` sub-parts and fishing
+their facts out of the sub-part list — polluting views, the control panel's
+mental model, and the overlap check. Probes are invisible to the viewer, the
+exporter, the assembly checks, and `verify` gates; they exist only in the report.
+
+**Failure is contained.** A probe that throws reports `{ error: "…" }` in its
+own slot — it never crashes the measurement and never flips the report's `ok`.
+An empty boolean result (a slab that misses the part) reports
+`{ empty: true, volume: 0 }` rather than degenerate infinite bounds — "no
+material here" is a first-class answer for a localizing probe. Lint covers
+probes with the same pass as builds: a throwing probe is `probe-throws`, a
+malformed block is `invalid-probes`, and unknown ops / bad options / impurity
+are caught exactly as in `build`.
+
+**Driving geometry from a live measurement.** Probes get numbers *out*. To feed
+a measurement *into* geometry, remember that `build` already holds a real
+kernel: `k.import("scan").boundingBox()` (and `.volume()`, and booleans between
+solids) work live inside any build, so a sub-part can size itself off another
+solid directly — no probe needed. Keep it pure: the measurement is deterministic
+for a given import + params, which is exactly what the geometry cache assumes.
+To set parameter **defaults** from a reference (the "rebuild this STL" flow),
+declare a probe that reads the value, run `measure`, and bake the reported
+number into `defaults` — the probe then keeps watching it on every regen, so a
+swapped import shows up as a probe delta instead of silently stale defaults.
+
+**Cost.** Probes run on every `measure`/`inspect` (including quick checks — the
+agent loop is exactly who reads them), so keep them proportionate: a handful of
+thin-slab booleans is cheap; a dense sweep of whole-part XORs is not. `verify`'s
+per-case re-measures skip probes entirely (no gate reads them). The reference
+part for probes is [`src/parts/import-demo.js`](../src/parts/import-demo.js).
+
 ## Wiring a part into a runnable app
 
 Three tiny glue files per part (copy from the demo). The worker statically imports
@@ -1953,8 +2041,9 @@ previously didn't; that's the fix working as intended, not a regression.
 ### Rule catalog
 
 **Definition shape** — `missing-meta-title`, `missing-defaults`, `no-buildable-parts`,
-`missing-views`, `part-view-unknown` (all errors); `view-unused`,
-`default-view-ambiguous` (warnings).
+`missing-views`, `part-view-unknown`, `invalid-probes` (all errors); `view-unused`,
+`default-view-ambiguous` (warnings). `invalid-probes` fires when a declared
+`probes` block isn't an object of functions (see "Probes" above).
 
 **Parameter schema** — `features-requires-sliders`, `features-requires-on`,
 `control-key-not-in-defaults`, `control-default-not-primitive`,
@@ -2033,10 +2122,12 @@ internals (`hidden: true`). Grouping controls organizes them but does not
 reduce the count — the check recurses into groups — so a group alone doesn't
 bring a section back under budget.
 
-**Kernel API**, found by executing `build()` against a geometry-free probe —
+**Kernel API**, found by executing `build()` — and every declared probe, which
+shares build's `(k, p, d)` contract — against a geometry-free probe —
 `unknown-kernel-op`, `unknown-solid-op`, `invalid-op-options`, `build-throws`,
-`derive-throws`, `manifold-backend-uses-occt-op`, `build-runaway` (errors);
-`nondeterministic-build` (warning, from diffing two probe runs).
+`probe-throws`, `derive-throws`, `manifold-backend-uses-occt-op`,
+`build-runaway` (errors); `nondeterministic-build` (warning, from diffing two
+probe runs).
 
 **Verify block** — `verify-unknown-metric`, `verify-unknown-subpart`,
 `verify-bad-expr`, `verify-bad-pair-check`, `verify-unknown-process`,
@@ -2455,10 +2546,15 @@ OCCT). Within one sub-part's build there is no per-op backend mixing.
 
 **Shading intent.** The kernel decides what shades smooth and where edge lines
 draw — spheres, cylinders and fillets are smooth by construction; boolean cut
-seams always shade hard and draw a line; a loft's facets shade flat when its
-rings have fewer than 32 sides (`shading: "smooth"|"faceted"` on `k.loft`
-overrides the inference either way). If your part previews smooth but would
-print faceted — or the reverse — set the hint rather than changing facet counts.
+seams always shade hard and draw a line; a point-ring loft's facets shade flat
+when its rings have fewer than 32 sides. A curve or resample loft shades by
+**tessellation provenance**: only wall sections that came from a smoothly
+tessellated contour span (an arc/Bézier run) shade smooth, sharp contour
+corners and silhouette-kink rings (an abrupt direction change up the stack,
+like a belly break) flat-shade and draw a dividing line, and a morph's snapped
+corners do the same. `shading: "smooth"|"faceted"` on `k.loft` overrides all of
+this either way. If your part previews smooth but would print faceted — or the
+reverse — set the hint rather than changing facet counts.
 
 > `partforge measure` reports `watertight`/`holes` as `n/a` for OCCT-run parts
 > (Manifold-only topology); `render` works on both. Filleted parts now measure on

package/docs/ERROR-PATTERNS.md

@@ -478,10 +478,25 @@ Variant literal for a curve-adjacent corner: `filletProfile: corner <i> at (<x>,
 - **Symptom:** an intentionally faceted loft (low-side-count rings) previews
   smooth-shaded, but exports/prints show flat facets.
 - **Cause:** the loft's shading policy resolved to smooth — a `shading:
-  "smooth"` hint, `ruled: false`, or rings with 32+ sides.
+  "smooth"` hint, `ruled: false`, rings with 32+ sides, or (for curve/resample
+  rings) the smooth-shaded section came from a smoothly tessellated contour
+  span — arcs/Béziers shade smooth per SECTOR, while sharp corners and
+  silhouette-kink rings flat-shade with a dividing line.
 - **Fix:** pass `shading: "faceted"` to `k.loft` (or drop the smooth-implying
   option) per [AUTHORING-PARTS.md](AUTHORING-PARTS.md) shading-intent note.
 
+## loft-ring-multi-region-shape2d
+
+- **Symptom:** `loft: ring 0 is a Shape2D with 2 regions — a loft ring must be a single closed outline (union the regions into one, or loft each separately)`
+- **Cause:** the Shape2D handed to a loft ring holds several disjoint outlines (usually the result of a union that never overlapped).
+- **Fix:** loft each region as its own solid and union the lofts, or rebuild the profile so the outlines actually merge into one. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API" (`loft` rings).
+
+## loft-ring-has-holes
+
+- **Symptom:** `loft: ring 0 has holes — loft rings must be hole-free outlines (cut the holes from the lofted solid instead)`
+- **Cause:** the ring Shape2D has an inner contour (a `.cut()` inside the outline). Lofting hole tunnels needs its own correspondence and is not supported.
+- **Fix:** loft the outer outline, then `.cut()` a second loft (or an extrusion) of the hole profile from the solid. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API" (`loft` rings).
+
 ## duplicate-preset-name-throws
 
 - **Symptom:** `duplicate preset name across sections:` thrown from verify/measure, naming the repeated preset (e.g. `duplicate preset name across sections: "Compact"`).

package/docs/KERNEL-CONTRACT.md

@@ -284,7 +284,7 @@ above. All ops return a `Solid`.
 | `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. |
+| `loft({rings, ruled?, closed?})` | Stack cross-sections along Z with ruled walls and capped ends (per-ring `z`/`rotate`/`scale`). A ring's `polygon` may be a point list, `sides`+`radius`, a curve contour, or a single-region hole-free `Shape2D` (multi-region / holed shapes throw). Rings with **identical all-line segment structure** (one straight-sided shape reused at different z/scale/rotate) loft **bit-identically** on both backends — parity by construction, unchanged legacy behavior. Rings with **identical curve structure** (containing arcs or Béziers, the same shape at different z/scale/rotate) loft curve-natively on a B-rep kernel — STEP keeps exact arc edges — while a mesh kernel facets the same sections at a fixed LOD (`hull`'s parity class). **Structurally different rings** (a rounded square morphing to a circle, unequal-N point lists) are arc-length-resampled once, in shared pure-JS code, to a common vertex count with a deterministic seam (the outermost +X-ray crossing from each ring's centroid; per-ring `rotate` tunes the phase) and snapped corners — every backend then lofts the **identical** resampled point rings, so the result is parity **by construction** and STEP is faceted at the sampling LOD. 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). Circular profile on a frenet frame that rolls with the helix — **not for threads**; use `screwSweep`. |
 | `screwSweep({profile, pitch, turns, lefthand})` | Screw-motion sweep of an axial lathe profile `[[r, z], …]` (r ≥ 0) — threads. The profile travels to `(r·cosθ, r·sinθ, z + pitch·θ/2π)`; `h = pitch · turns`. Axial extent must not exceed `pitch` or consecutive turns interpenetrate (throws). A profile spanning exactly `pitch` is **periodic**: first and last radius must agree, and it yields a complete threaded body needing no boolean. Compound: the polar-remapped, densified section extruded with `twist = 360 · turns`, exactly as composed in `kernel-front.js`; a backend may override only for caching, never for different geometry. Options-only. Parity: **within tolerance, not by construction** — both backends receive the identical densified polygon, but the mesh backend facets the twist at its own resolution while the B-rep backend builds an exact spline (`hull`'s parity class). |
@@ -309,7 +309,10 @@ mesh backends** (Manifold); B-rep kernels throw a plain `Error` naming the limit
 `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.
+station list (`sweep.js`), and structurally-different loft rings loft the identical resampled ring list
+(`loft-rings.js`) on both backends. Structurally-identical all-line rings remain bit-identical on both backends
+(unchanged legacy behavior). Structurally-identical curve rings are the exception by design: the B-rep kernel keeps the
+exact curves (STEP-exact) while a mesh kernel facets them — `hull`'s parity class.
 
 ### Rounded primitives
 
@@ -386,11 +389,20 @@ are present:
   filtered out; Manifold ships policy-gated sharp/seam segments.
 
 `loft` accepts `shading?: "smooth" | "faceted"` to override facet-vs-smooth
-inference: by default, rings with fewer than 32 sides shade as intentional flat
-facets with no same-surface edge lines, while rings with 32+ sides (and
-`ruled: false` lofts) shade smooth. `shading: "smooth"` forces smooth shading;
-`shading: "faceted"` forces facets; any other non-nullish value throws.
-Thresholds live in `src/framework/geometry/shading-policy.js`.
+inference. Point-list (poly-exact) lofts infer as before: rings with fewer than
+32 sides shade as intentional flat facets with no same-surface edge lines, while
+rings with 32+ sides (and `ruled: false` lofts) shade smooth. Curve and resample
+lofts shade by **tessellation provenance** instead of a single whole-solid
+policy: the walls partition into shading sectors split at sharp contour joints
+(and at snapped corners in a resample morph), and into band groups split at
+silhouette-kink rings (wall direction bending more than the 5° tangent bar —
+the same bar at which a B-rep loft's real ring edges draw lines). Sector and
+band-group boundaries flat-shade and draw dividing lines regardless of bend
+angle; only sectors whose facets come from smoothly tessellated curve spans
+shade smooth inside. `shading: "smooth"` forces whole-solid smooth shading;
+`shading: "faceted"` forces facets — either hint bypasses sectoring entirely;
+any other non-nullish value throws. Thresholds live in
+`src/framework/geometry/shading-policy.js`.
 
 Known limitation: the OCCT backend ignores `shading` — a loft forced to OCCT
 via `meta.backend` draws its facet corner edges as B-rep feature lines. The
@@ -401,7 +413,11 @@ collapses it to a single shading surface that inherits the majority policy of
 its registered constituent surfaces, weighted by triangle count. A constituent
 with no registered policy of its own (e.g. a plain boolean tool) still votes,
 as SMOOTH — the policy it actually renders with — and an exact tie resolves to
-the no-lines (faceted) policy.
+the no-lines (faceted) policy. Two exceptions preserve their surface partition
+through labeling instead of collapsing: fillet/chamfer blend bands (base +
+blend re-stamp as two surfaces), and provenance-sectored lofts (every sector
+and band-group run re-stamps 1:1) — in both cases all the resulting surfaces
+carry the one label, so hover/pick still reads a single feature.
 
 **Selectors** (`fillet`/`chamfer` `edges` selector, `shell` `open` face selector) are
 declarative objects, criteria AND-combined:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.81.0",
+  "version": "0.83.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-lofted-bottle.js

@@ -0,0 +1,22 @@
+// 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 loftedBottlePart from "./parts/lofted-bottle.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only example app for the lofted-bottle part (the Shape2D-loft reference part).
+// Identical wiring to app.js — the only thing that differs per part is which definition
+// you import and which worker entry you point at. `npm run dev`, then open
+// /lofted-bottle.html.
+// Dev-only: the handle is stashed on window so scripts/check-app.mjs can drive
+// the embedding contract (runtime.captureCurrent) the way an embedder would.
+window.__pfRuntime = mount(loftedBottlePart, {
+  createWorker: (name) =>
+    new Worker(new URL("./lofted-bottle-worker.js", import.meta.url), { type: "module", name }),
+  onAnnotationSend: (payload) => {
+    window.__pfLastAnnotation = payload;
+    console.log("annotation payload", payload);
+  },
+});

package/src/framework/geometry/kernel.js

@@ -142,7 +142,7 @@ export const ROUTED_CAD_OPS = ["shell"];
  * @property {(o:{size?:number[],center?:boolean,min?:number[],max?:number[]}) => Solid} box   {size} = centered X/Y, base z=0 ({center:true} centers Z too) or {min,max}; legacy (min,max) accepted for now (see file header)
  * @property {(o:{points:number[][],h:number,twist?:number,scaleTop?:number}) => Solid} prism   extrude polygon from z=0; legacy (points,h,opts) accepted for now (see file header)
  * @property {(o:{profile:number[][]|{outer:number[][],holes?:number[][][]},h:number,twist?:number,scaleTop?:number,bevel?:number|{bottom?:number,top?:number}}) => Solid} extrude   polygon-with-holes region from z=0; bevel = 45° rim bevel (any profile form incl. Shape2D, materialized to point rings; no twist/scaleTop); legacy (profile,h,opts) accepted for now (see file header)
- * @property {(o:{rings:{polygon?:number[][],sides?:number,radius?:number,z:number,rotate?:number,scale?:number|number[]}[],ruled?:boolean,closed?:boolean,shading?:"smooth"|"faceted"}) => Solid} loft   stack polygon cross-sections; shading overrides facet-vs-smooth shading inference; legacy (rings,opts) accepted for now (see file header)
+ * @property {(o:{rings:{polygon?:number[][]|{start:number[],segments:object[]}|Shape2D,sides?:number,radius?:number,z:number,rotate?:number,scale?:number|number[]}[],ruled?:boolean,closed?:boolean,shading?:"smooth"|"faceted"}) => Solid} loft   stack polygon cross-sections; polygon accepts point lists, curve contours, or hole-free Shape2D; shading overrides facet-vs-smooth shading inference; legacy (rings,opts) accepted for now (see file header)
  * @property {(o:{profile:number[][],path:number[][],closed?:boolean,cornerRadius?:number,ruled?:boolean,smooth?:boolean}) => Solid} sweep   sweep a 2-D profile along a 3-D polyline; legacy (profile,path,opts) accepted for now (see file header)
  * @property {(o:{profile:number[][],degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z; legacy (points,opts) accepted for now (see file header)
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube