partforge 0.146.1 → 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.1",
+  "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/kernel-front.js

@@ -21,6 +21,7 @@ import { KernelCapabilityError } from "./errors.js";
 import { isPlainOptions, KERNEL_OP_SPECS } from "./op-options.js";
 import { isPathContour, contourToPoints } from "./profile.js";
 import { textGlyphs } from "./text2d.js";
+import { unionMany } from "./union-many.js";
 import { placeRegions } from "./vector2d.js";
 import { beveledExtrude } from "./rim-bevel.js";
 import { DEFAULT_FONT_BYTES } from "./fonts/default-font.js";
@@ -279,7 +280,7 @@ export function finishKernel(k) {
     if (regions.length === 0) throw new Error("text2d: string produced no glyph geometry (empty or all-whitespace?)");
     // Glyph regions are machine-resolved by curve-fill — trusted, so a text
     // part does not pay profile validation per glyph per rebuild.
-    return regions.map((r) => k.shape2d.trusted(r)).reduce((a, b) => a.union(b));
+    return unionMany(regions.map((r) => k.shape2d.trusted(r)), k.shape2d.trusted);
   };
 
   // 2-D vector art as a Shape2D. Backend-agnostic for the same reason text2d is:
@@ -300,7 +301,7 @@ export function finishKernel(k) {
     if (!doc) throw new Error(`vector2d: unknown vector "${name}" — declare it in the part's \`vectors\` field`);
     // vector documents carry their own validation (VECTOR-FORMAT.md); trusted lift
     const lift = (regions, measureAgainst = regions) =>
-      placeRegions(regions, doc.units, opts, { measureAgainst, name }).map((r) => k.shape2d.trusted(r)).reduce((a, b) => a.union(b));
+      unionMany(placeRegions(regions, doc.units, opts, { measureAgainst, name }).map((r) => k.shape2d.trusted(r)), k.shape2d.trusted);
     if (opts.shape != null) {
       const entry = doc.shapes.get(opts.shape);
       if (!entry) {

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]));

package/src/framework/geometry/union-many.js

@@ -0,0 +1,75 @@
+// Union of many Shape2Ds — the text2d / vector2d reduction — without the
+// quadratic left fold those ops used to run.
+//
+// `shapes.reduce((a, b) => a.union(b))` hands paper.js the WHOLE accumulated
+// result on every step, so n glyphs cost about n²/2 glyph conversions plus n
+// planar booleans over an ever-growing compound path. Measured on a 4-line,
+// 290-glyph paragraph (feedback #169, a bathroom sign): 14 s for text2d alone,
+// over a minute for the forge. Two independent savings, applied in order:
+//
+//   1. Shapes whose bounding boxes do not touch cannot share a point, so their
+//      union is just their regions side by side — no boolean at all. Text is
+//      almost entirely this case: letters sit apart, and only a kerned pair, a
+//      script face or negative tracking makes neighbours overlap. Shapes are
+//      grouped into clusters whose boxes overlap (transitively); the clusters
+//      are mutually disjoint, so concatenating them IS the union.
+//   2. Inside a cluster that does need booleans, the union is balanced
+//      (pairs, then pairs of pairs), so each shape is converted O(log n)
+//      times instead of O(n).
+//
+// Bounds are paper's exact curve bounds (Shape2D.boundingBox), padded by EPS so
+// shapes that merely touch along an edge still meet a boolean — touching
+// glyphs must fuse, not sit as two regions sharing an edge.
+//
+// Deterministic: clusters are emitted in the order of their first member, and
+// members keep input order, so the same inputs give the same regions (and so
+// the same Shape2D hash — build purity rests on it).
+const EPS = 1e-6;
+
+// `fromContours` builds a Shape2D from a list of already-resolved regions (the
+// kernel's k.shape2d.trusted) — passed in so this module needs no kernel.
+export function unionMany(shapes, fromContours) {
+  if (shapes.length === 0) throw new Error("unionMany: no shapes");
+  if (shapes.length === 1) return shapes[0];
+
+  const boxes = shapes.map((s) => s.boundingBox());
+  const n = shapes.length;
+  const parent = Array.from({ length: n }, (_, i) => i);
+  const find = (i) => { while (parent[i] !== i) { parent[i] = parent[parent[i]]; i = parent[i]; } return i; };
+  const join = (a, b) => { const ra = find(a), rb = find(b); if (ra !== rb) parent[Math.max(ra, rb)] = Math.min(ra, rb); };
+
+  // Sweep in x: `active` holds every box whose x-range can still reach the
+  // current one. Worst case (a vertical column of shapes) is O(n²) box checks —
+  // cheap arithmetic, nothing like the booleans it saves.
+  const order = [...boxes.keys()].sort((a, b) => boxes[a].min[0] - boxes[b].min[0] || a - b);
+  let active = [];
+  for (const i of order) {
+    const bi = boxes[i];
+    active = active.filter((j) => boxes[j].max[0] + EPS >= bi.min[0]);
+    for (const j of active) {
+      const bj = boxes[j];
+      if (bj.min[1] - EPS <= bi.max[1] && bi.min[1] - EPS <= bj.max[1]) join(i, j);
+    }
+    active.push(i);
+  }
+
+  const clusters = new Map();                       // root → member indices, input order
+  for (let i = 0; i < n; i++) {
+    const r = find(i);
+    if (!clusters.has(r)) clusters.set(r, []);
+    clusters.get(r).push(i);
+  }
+
+  const merged = [...clusters.values()].map((members) => balancedUnion(members.map((i) => shapes[i])));
+  if (merged.length === 1) return merged[0];
+  return fromContours(merged.flatMap((s) => s.toContours()));
+}
+
+function balancedUnion(xs) {
+  while (xs.length > 1) {
+    const next = [];
+    for (let i = 0; i < xs.length; i += 2) next.push(i + 1 < xs.length ? xs[i].union(xs[i + 1]) : xs[i]);
+    xs = next;
+  }
+  return xs[0];
+}