partforge 0.146.2 → 0.146.3

package/docs/ERROR-PATTERNS.md

@@ -78,7 +78,13 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 
 - **Symptom:** `produced an impossible result` — the full message reads `boolean result invalid: <op> produced an impossible result — …`, thrown from `union`, `cut`, `cutAll` or `intersect`, naming one of: `a negative volume`, `a union smaller than its largest operand`, `a cut larger than its body`, `a cut that emptied its body although the tools cover at most <x> mm³ of its <y> mm³`, `an intersection larger than its smallest operand`.
 - **Cause:** The kernel's boolean returned geometry that violates the one property no boolean may (a union contains its inputs, a cut only removes, an intersection lies inside each input, a solid has non-negative volume) without reporting an error. On the exact kernel this follows a tangent or self-touching contact the coincidence guard could not recognise up front ([boolean-coincident-faces-hang](#boolean-coincident-faces-hang) covers the form it does refuse); on the mesh kernel it should never happen and would be a kernel bug worth reporting. The gate carries 1% slack on the largest operand, so volume-integration noise cannot trip it.
-- **Fix:** The same menu as the coincidence guard's — genuine overlap or genuine clearance (0.05 mm or more) instead of exact contact, cut tools overcut past the faces they pierce, threads in the periodic `screwSweep` form or via `k.tappedBore`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Gotchas". A refusal is a throw, not a warning, on purpose: the alternative is the silently wrong part these rules exist to stop, and a live preview keeps its last good mesh on screen across a failed rebuild.
+- **Fix:** The same menu as the coincidence guard's — genuine overlap or genuine clearance (0.05 mm or more) instead of exact contact, cut tools overcut past the faces they pierce, threads in the periodic `screwSweep` form or via `k.tappedBore`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Gotchas". A refusal is a throw, not a warning, on purpose: the alternative is the silently wrong part these rules exist to stop, and a live preview keeps its last good mesh on screen across a failed rebuild. A result of exactly `0 mm³` on the mesh kernel almost always means an operand was already broken, not the boolean. Since 0.146.3 that case is reported as [boolean-invalid-operand](#boolean-invalid-operand) instead.
+
+## boolean-invalid-operand
+
+- **Symptom:** `<op>: operand <n> is not a valid solid (Manifold status <status>)`, thrown from `union`, `cut`, `cutAll` or `intersect` on the mesh kernel; or `prism: the profile encloses no area` / `extrude: the profile encloses no area`, thrown from the op that built the broken operand.
+- **Cause:** An earlier op built nothing: a primitive with a zero dimension (`cylinder({r: 0})`), or a cross-section with no area (points that are collinear, repeated, or cancel each other out). Manifold marks such a solid as an error rather than throwing, and any boolean it reaches then comes back empty. Before 0.146.3 the boolean result gate reported that as [boolean-impossible-result](#boolean-impossible-result), and a `prism` whose single outline was wound clockwise produced it too. A prism now accepts either winding, like `extrude` and the OCCT backend.
+- **Fix:** Give the operand real size. Check the op that built it and the parameter values that size it. A dimension driven to zero, or two profile points that coincide, is the usual culprit. If a parameter can legitimately reach zero, skip the feature in `build` when it does. Do not add overlap or clearance: the boolean was never the problem.
 
 ## chamfer-rescue-bisection
 

package/docs/KERNEL-CONTRACT.md

@@ -288,7 +288,7 @@ above. All ops return a `Solid`.
 | `torus({ rMajor, rMinor })` | Torus centered at the origin, tube centerline in the z = 0 plane; requires 0 < rMinor < rMajor. Curve-exact on B-rep backends. Options-only. |
 | `roundedBox({ size, center?, round })` | Box with selectively rounded edges; `round`: number = every edge, or `{ side?, top?, bottom? }` (vertical edges / top rim / bottom rim). Corner semantics and the `0 < side < rim` clamp-with-warning rule are normative in the design spec and summarized under [Rounded primitives](#rounded-primitives). Options-only. |
 | `box({size, center?})` · `box({min, max})` | Axis-aligned box: `{size:[x,y,z]}` centered in X/Y with base at z = 0 (`center: true` also centers Z), or explicit `[x,y,z]` `{min, max}` corners. |
-| `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). |
+| `prism({points, h, twist?, scaleTop?})` | Extrude one contour (point list or arc profile; either winding, CCW by convention) 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 in `[r, z]` (r ≥ 0) about Z; `degrees` < 360 gives a capped partial revolve. Default 360. `profile` may be a point list, a `Shape2D`, or — lifted to a `Shape2D` by the kernel front before the op runs — a `{start, segments}` path contour or an `{outer, holes}` region. A mesh backend spends its circle count in proportion to the sweep. |
 | `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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.146.2",
+  "version": "0.146.3",
   "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/geometry/manifold-backend.js

@@ -25,6 +25,21 @@ import { checkBooleanResult } from "./boolean-gate.js";
 import { KernelCapabilityError } from "./errors.js";
 import { heightfieldMesh, hashGridData } from "./heightfield.js";
 
+// A boolean whose operand was already broken. See `judged` below.
+const invalidOperand = (op, index, status) => new Error(
+  `${op}: operand ${index} is not a valid solid (Manifold status ${status}) — an earlier op ` +
+  "built nothing, so this boolean has nothing to work with. The usual causes are a primitive " +
+  "with a zero dimension (a radius, height or size driven to 0) and a profile that encloses no " +
+  "area (collinear, repeated, or self-cancelling points). Check the op that built this operand " +
+  "and the parameter values that size it. " +
+  "See ERROR-PATTERNS.md#boolean-invalid-operand.");
+
+// A point-list profile whose cross-section came out empty. Thrown at the op,
+// before the empty solid can reach a boolean and be misreported there.
+const emptyProfile = (op) => new Error(
+  `${op}: the profile encloses no area — nothing to build (its points may be collinear, ` +
+  "repeated, or cancel each other out). See ERROR-PATTERNS.md#boolean-invalid-operand.");
+
 const PLANE_NORMAL = { XY: [0, 0, 1], XZ: [0, 1, 0], YZ: [1, 0, 0] };
 // 'preview' = interactive view (fast); 'print' = STL export (high-res, used only
 // by the export path — Manifold meshing is cheap, so we tessellate generously).
@@ -89,6 +104,14 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   };
   const BOX_SLACK = 1e-3; // mm — an enclosure test, not a measurement
   const judged = (op, operandMs, resultM) => {
+    // An operand that is already in an error state (Manifold's status, e.g.
+    // InvalidConstruction from extruding an empty cross-section) makes the
+    // boolean return an empty error-state result. Judged by volume, that reads
+    // as "a union smaller than its largest operand" or "a cut that emptied
+    // its body", and the coaching sends the author hunting for tangent contacts
+    // that are not there. It is the operand's failure, so say that instead.
+    const bad = operandMs.findIndex((mm) => mm.status() !== "NoError");
+    if (bad >= 0) throw invalidOperand(op, bad, operandMs[bad].status());
     const box = (mm) => mm.boundingBox();
     const err = checkBooleanResult(op, operandMs.map(volumeOf), volumeOf(resultM), {
       overlap: (i, j) => {
@@ -760,7 +783,13 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     },
     prism: (pts, height, { twist = 0, scaleTop = 1 } = {}) =>
       cached(h("prism", pts, height, twist, scaleTop, segs), () => {
-        const cs = T(CrossSection.ofPolygons([tessellateContour(pts, segsAt)]));
+        // Even/odd like `extrude` below and like the OCCT prism, so the outline's
+        // winding does not matter. Under Manifold's default Positive rule a
+        // CLOCKWISE outline filled nothing: the extrude came back
+        // InvalidConstruction and the next boolean reported an "impossible
+        // result" (118 production builds in two weeks, every one a 0 mm³ result).
+        const cs = T(CrossSection.ofPolygons([tessellateContour(pts, segsAt)], "EvenOdd"));
+        if (cs.isEmpty()) throw emptyProfile("prism");
         if (twist === 0 && scaleTop === 1) return T(cs.extrude(height));
         const nDiv = Math.max(1, Math.ceil(Math.abs(twist) / 5));
         // Manifold's extrude scaleTop is a Vec2 — a scalar is NOT broadcast (it scales
@@ -856,6 +885,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
           const { outer, holes } = tessellateProfile(profile, segsAt);
           return T(CrossSection.ofPolygons([outer, ...holes], "EvenOdd"));
         })();
+        if (cs.isEmpty()) throw emptyProfile("extrude");
         if (twist === 0 && scaleTop === 1) return T(cs.extrude(height));
         const nDiv = Math.max(1, Math.ceil(Math.abs(twist) / 5));
         return T(cs.extrude(height, nDiv, twist, [scaleTop, scaleTop]));