partforge 0.56.0 → 0.58.0

package/docs/AUTHORING-PARTS.md

@@ -1195,7 +1195,7 @@ plate = plate.fillet(p.cornerR, { corners: "convex" });
 | `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:
+Three 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
@@ -1206,6 +1206,13 @@ Two rules worth internalizing before reaching for any of this:
   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.
+- **Guard vanishing features with `isEmpty()`.** A boolean chain can legitimately
+  produce an *empty* shape (an `intersect` of shapes a parameter drove apart, a `cut`
+  that removed everything). The empty shape is a fine 2-D value — further booleans,
+  transforms and `offset` all work — but `extrude`/`revolve` throw on it, identically
+  on both backends. If a parameter can drive a feature to nothing, write the guard
+  explicitly: `if (!pocket.isEmpty()) body = body.cut(pocket.extrude({ h }))`.
+  (Symptom-keyed: `ERROR-PATTERNS.md#extrude-empty-shape2d`.)
 
 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
@@ -1224,7 +1231,8 @@ 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])`.
+opts?)`, `simplify(tolerance)`, `corners()`, `contains([x,y])`, `isEmpty()` (no
+regions left — see the vanishing-features rule above).
 
 ## Convex hull
 

package/docs/ERROR-PATTERNS.md

@@ -332,6 +332,12 @@ Variant literal for a curve-adjacent corner (note the semicolon form, not parent
 - **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.
 
+## extrude-empty-shape2d
+
+- **Symptom:** `extrude: the profile Shape2D is empty — nothing to build (a cut/intersect may have removed everything; guard with .isEmpty())` (or the `revolve:` twin), often only at certain parameter values.
+- **Cause:** A 2-D boolean chain legitimately produced an empty shape — an `intersect` of disjoint shapes, or a `cut` that removed everything — and the part handed it to `extrude`/`revolve`. Both backends reject this identically; a silently empty solid would just move the mystery downstream (missing geometry, failing `verify` volume gates).
+- **Fix:** If the emptiness is a surprise, check the boolean operands' placement (`boundingBox()` on each side). If it's a legitimate vanishing feature (a parameter can drive it to nothing), guard the materialization: `if (!pocket.isEmpty()) body = body.cut(pocket.extrude({ h }))`. See [KERNEL-CONTRACT.md](KERNEL-CONTRACT.md) § "Empty shapes".
+
 ## curve-fill-resolved-hole-uncontained
 
 - **Symptom:** `curve-fill: resolved hole has no containing outer`

package/docs/KERNEL-CONTRACT.md

@@ -374,7 +374,7 @@ 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). 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. |
+| `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). |
 | `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. |
@@ -386,10 +386,24 @@ cross-backend note below.
 | `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`. |
+| `isEmpty()` | `true` when the shape has no regions at all — a `cut`/`intersect` legitimately removed everything. Pure JS on the stored IR, backend-identical. See "Empty shapes" below. |
+| `extrude({h, twist?, scaleTop?})` | Sugar for `k.extrude({profile: this, …})` → `Solid`. Throws on an empty shape (see "Empty shapes"). |
+| `revolve({degrees?})` | Sugar for `k.revolve({profile: this, …})` → `Solid`. Throws on an empty shape (see "Empty shapes"). |
 | `clone()` | Independent copy. Every op returns a NEW `Shape2D`; no operand is ever mutated. |
 
+**Empty shapes.** An empty `Shape2D` is a legal 2-D value, and every 2-D op is total
+on it: booleans treat it as the identity/absorbing element, transforms and `offset`
+return it unchanged, `area()` is 0, `toRegions()` is `[]`. What it cannot do is become
+3-D: `extrude` and `revolve` (either calling form, on both backends) throw
+`"<op>: the profile Shape2D is empty — nothing to build (a cut/intersect may have
+removed everything; guard with .isEmpty())"`. The check runs in the shared op-spec
+layer before any backend materialization, so the two backends agree by construction.
+A part whose parameters can drive a feature to nothing guards explicitly:
+`if (!pocket.isEmpty()) body = body.cut(pocket.extrude({ h }))`. (Before this was
+pinned, Manifold silently built an empty solid where OCCT threw — behavior no part
+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`.
 
 `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.56.0",
+  "version": "0.58.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/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/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);

package/src/framework/geometry/kernel.js

@@ -51,6 +51,7 @@ export const SHAPE2D_OPS = [
   "union", "cut", "cutAll", "intersect", "offset", "area", "boundingBox", "toRegions", "simple", "regions", "clone",
   "extrude", "revolve",
   "translate", "rotate", "scale", "mirror", "toContours", "fillet", "chamfer", "simplify", "corners", "contains",
+  "isEmpty",
 ];
 
 // Solid ops only OCCT implements natively. Single source of truth: probe.js routes
@@ -94,7 +95,8 @@ export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
  * @property {(other: Shape2D|number[][]) => Shape2D} cut
  * @property {(others: (Shape2D|number[][])[]) => Shape2D} cutAll   batch subtract
  * @property {(other: Shape2D|number[][]) => Shape2D} intersect
- * @property {(delta:number, opts?:{corners?:"round"|"chamfer"|"sharp",segs?:number}) => Shape2D} offset   grow (+) / shrink (−) by delta; the one backend-specific op (Clipper2 vs OCCT) — throws when the shape collapses
+ * @property {(delta:number, opts?:{corners?:"round"|"chamfer"|"sharp",segs?:number}) => Shape2D} offset   grow (+) / shrink (−) by delta; the one backend-specific op (Clipper2 vs OCCT) — throws when the shape collapses; empty in → empty out
+ * @property {() => boolean} isEmpty   true when the shape has no regions (a cut/intersect removed everything); guard before extrude/revolve, which throw on an empty profile
  * @property {() => number} area   net area (outers minus holes), mm² — curve-exact, not tessellated
  * @property {() => {min:number[],max:number[]}} boundingBox   axis-aligned 2-D bounds (curve-exact)
  * @property {() => {outer:number[][],holes:number[][][]}[]} toRegions   materialize into point-ring region arrays (tessellated at the backend's LOD)

package/src/framework/geometry/op-options.js

@@ -220,6 +220,16 @@ const checkScaleTop = (op) => (_profile, _h, opts) => {
   if ((opts?.scaleTop ?? 1) < 0) throw new Error(`${op}: scaleTop must be ≥ 0`);
 };
 
+// An empty Shape2D (a cut/intersect can legitimately remove everything) is a
+// valid 2-D value, but 3-D materialization must reject it identically on both
+// backends — Manifold would silently build an empty solid, OCCT would throw a
+// backend-specific error. `?.` because the probe's fake handle has no _regions.
+const checkNonEmptyProfile = (op, profile) => {
+  if (profile && profile._shape2d && profile._regions?.length === 0)
+    throw new Error(`${op}: the profile Shape2D is empty — nothing to build ` +
+      "(a cut/intersect may have removed everything; guard with .isEmpty())");
+};
+
 // Ops that were always options-only have no positional form to normalize —
 // toArgs validates keys/required and passes the object through unchanged, so a
 // typo'd key fails loudly instead of destructuring to undefined → NaN geometry.
@@ -236,8 +246,12 @@ export const KERNEL_OP_SPECS = {
   sphere:   { toArgs: sphereArgs },
   box:      { toArgs: boxArgs },
   prism:    { toArgs: prismArgs, check: checkScaleTop("prism") },
-  extrude:  { toArgs: extrudeArgs, check: checkScaleTop("extrude") },
+  extrude:  { toArgs: extrudeArgs, check: (profile, h, opts) => {
+    checkNonEmptyProfile("extrude", profile);
+    checkScaleTop("extrude")(profile, h, opts);
+  } },
   revolve:  { toArgs: revolveArgs, check: (pts) => {
+    checkNonEmptyProfile("revolve", pts);
     if (pts && pts._shape2d) {
       // The B-rep backend's Drawing bounding box is tolerance-padded (1e-6 on
       // every side, measured), so a lathe profile touching the revolve axis at

package/src/framework/geometry/shape2d.js

@@ -66,8 +66,12 @@ export function makeShape2dFactory({ segs, offsetRegions, extrude, revolve }) {
       // rings are explicitly closed. Both backends' readbacks close explicitly today, so this
       // is a no-op in practice; it's here so the storage invariant (every stored ring
       // explicitly closed — see closeContourGap's own comment) holds unconditionally.
-      offset:    (delta, opts = {}) => make(offsetRegions(regions, delta, opts)
+      // Empty in → empty out without calling the hook: the 2-D ops stay total on the
+      // empty shape on both backends (the OCCT hook would otherwise choke on a null
+      // Drawing); only 3-D materialization (extrude/revolve) rejects it.
+      offset:    (delta, opts = {}) => regions.length === 0 ? make([]) : make(offsetRegions(regions, delta, opts)
         .map((rg) => ({ outer: closeContourGap(rg.outer), holes: rg.holes.map(closeContourGap) }))),
+      isEmpty:   () => regions.length === 0,
       area:      () => profileArea(regions),
       boundingBox: () => profileBounds(regions),
       toRegions: () => assembleRegions(regions.flatMap((rg) =>

package/src/framework/mount.js

@@ -453,8 +453,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       if (needed.every(isCurrent)) {
         showView(needed);
         ui.setExportEnabled(true);
-        const tris = needed.reduce((s, n) => s + viewer.subTriangles(n), 0);
-        ui.setStatus(`${tris.toLocaleString()} triangles`);
+        // The line used to read "N triangles" here; that debug readout now goes
+        // to the console (see the `meshes` case). Clearing keeps a stale
+        // "phase…" from outliving the build it described.
+        ui.setStatus("");
       } else if (needed.every((n) => viewer.hasSubMesh(n))) {
         showView(needed); // stale but present — keep it visible during regenerate
         ui.setExportEnabled(false);
@@ -498,7 +500,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
             ui.hideBusy();
             refreshView();
             if (data.ms && missingParts().length === 0) {
-              ui.setStatus(`${ui.statusText()} · ${(data.ms / 1000).toFixed(1)} s`);
+              const tris = viewSubParts(part, view(), params).reduce((s, n) => s + viewer.subTriangles(n), 0);
+              console.debug(`partforge: built ${tris.toLocaleString()} triangles in ${(data.ms / 1000).toFixed(1)} s`);
             }
             dbg?.update({ ms: data.ms, hits: data.cache?.hits ?? 0, misses: data.cache?.misses ?? 0, skipped: lastGen.skipped, rebuilt: lastGen.rebuilt, posed: lastGen.posed });
             onBuild?.({ status: "success", ms: data.ms });
@@ -545,8 +548,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         case "error":
           loop.buildDone();
           ui.hideBusy();
-          ui.setStatus(`failed: ${data.message}`, true);
+          // refreshView FIRST: its all-current branch clears the status line,
+          // so writing the failure after it keeps the message on screen.
           refreshView();
+          ui.setStatus(`failed: ${data.message}`, true);
           onBuild?.({ status: "error", error: data.message });
           if (!readySettled) { readySettled = true; rejectReady(new Error(data.message)); }
           break;

package/src/framework/status-ui.js

@@ -10,6 +10,5 @@ export function createStatusUi({ status, busy, phase, exports = [] }) {
     showBusy(p) { phase.textContent = `${p}…`; busy.classList.add("show"); },
     hideBusy() { busy.classList.remove("show"); },
     setExportEnabled(on) { exportBtns.forEach((b) => { b.disabled = !on; }); },
-    statusText: () => status.textContent,
   };
 }

package/types/kernel.d.ts

@@ -199,9 +199,11 @@ export interface Shape2D {
   corners(): Corner2D[];
   /** Is `[x, y]` inside the shape (inside an outer, not inside a hole)? */
   contains(p: Point2): boolean;
-  /** Sugar for `k.extrude({ profile: this, ... })`. */
+  /** No regions left (a cut/intersect removed everything)? Guard before `extrude`/`revolve`, which throw on an empty shape. */
+  isEmpty(): boolean;
+  /** Sugar for `k.extrude({ profile: this, ... })`. Throws if the shape is empty — guard with `isEmpty()`. */
   extrude(opts: { h: number; twist?: number; scaleTop?: number }): Solid;
-  /** Sugar for `k.revolve({ profile: this, ... })`. */
+  /** Sugar for `k.revolve({ profile: this, ... })`. Throws if the shape is empty — guard with `isEmpty()`. */
   revolve(opts?: { degrees?: number }): Solid;
 }