partforge 0.7.0 → 0.9.0

package/bin/cli.js

@@ -14,10 +14,31 @@ import { measure } from "../src/testing/measure.js";
 import { verify } from "../src/testing/verify.js";
 import { renderViews } from "../src/testing/render.js";
 import { createPickServer, requestPicks, formatPickResult } from "../src/framework/pick-request/server.js";
+import { matchPattern } from "../src/testing/error-patterns.js";
 
 const die = (msg) => { console.error(msg); process.exit(1); };
 const USAGE = "usage: partforge <measure|render|pick-serve|pick> …";
 
+// Crash contract (issue #27): with --json, a thrown error becomes structured
+// stdout JSON; either way the message is matched against ERROR-PATTERNS.md and
+// the pattern's fix is surfaced. Exit 1 always. NOTE on stdout purity: crash
+// JSON is the only thing on stdout for errors thrown before any report printing
+// (load/boot/measure). But verify() runs after printMeasure and can throw (an
+// unknown metric in verify.expect, or a per-case build crash), so a throw after
+// printing appends the JSON after the human lines — it is not pure. Consumers
+// should prefer --out for robust machine parsing.
+function crash(cmd, e, jsonMode) {
+  const message = e?.message || String(e);
+  const m = matchPattern(message);
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: false, error: { message, ...(m && { pattern: m.id, hint: m.fix }) } }, null, 2));
+  } else {
+    console.error(`${cmd} failed: ${message}`);
+    if (m) console.error(`pattern: ERROR-PATTERNS.md#${m.id} — ${m.fix}`);
+  }
+  process.exit(1);
+}
+
 const parse = (args, options, usage) => {
   try {
     return parseArgs({ args, options, strict: true, allowPositionals: true });
@@ -29,9 +50,9 @@ const parse = (args, options, usage) => {
 async function loadPart(partPath, usage) {
   if (!partPath) die(usage);
   const mod = await import(pathToFileURL(resolve(process.cwd(), partPath)))
-    .catch((e) => die(`cannot load part "${partPath}": ${e.message}`));
+    .catch((e) => { throw new Error(`cannot load part "${partPath}": ${e.message}`); });
   const part = mod.default;
-  if (!part?.parts || !part?.views) die(`"${partPath}" has no default-exported PartDefinition`);
+  if (!part?.parts || !part?.views) throw new Error(`"${partPath}" has no default-exported PartDefinition`);
   return part;
 }
 
@@ -46,27 +67,33 @@ const commands = {
       json: { type: "boolean" },
       out: { type: "string" },
     }, usage);
-    const part = await loadPart(partPath, usage);
-    const kernel = await bootKernel(part);
     try {
+      const part = await loadPart(partPath, usage);
+      const kernel = await bootKernel(part);
       const report = measure(kernel, part, view);
       printMeasure(report);
+      // Write --out right after measure succeeds, then re-write once verify has
+      // attached report.verify. If verify throws (unknown metric, per-case build
+      // crash) the file already holds the measure half (no `verify` key) — matching
+      // the doc's advice to prefer --out for exactly that non-pure-stdout case.
+      const writeOut = () => {
+        mkdirSync(dirname(resolve(flags.out)), { recursive: true });
+        writeFileSync(flags.out, JSON.stringify(report, null, 2));
+      };
+      if (flags.out) writeOut();
       let vok = true;
       if ((part.verify || flags.process) && !flags["no-verify"]) {
         const v = verify(kernel, part, { process: flags.process, view });
         printVerify(v);
         report.verify = v;
         vok = v.ok;
+        if (flags.out) writeOut();
       }
-      if (flags.out) {
-        mkdirSync(dirname(resolve(flags.out)), { recursive: true });
-        writeFileSync(flags.out, JSON.stringify(report, null, 2));
-        console.log(`\nwrote ${flags.out}`);
-      }
+      if (flags.out) console.log(`\nwrote ${flags.out}`);
       if (flags.json) console.log(JSON.stringify(report, null, 2));
       process.exit(report.ok && vok ? 0 : 1);
     } catch (e) {
-      die(`measure failed: ${e.message || e}`);
+      crash("measure", e, !!flags.json);
     }
   },
 
@@ -76,15 +103,15 @@ const commands = {
       views: { type: "string" },
       out: { type: "string" },
     }, usage);
-    const part = await loadPart(partPath, usage);
-    const kernel = await bootKernel(part);
     try {
+      const part = await loadPart(partPath, usage);
+      const kernel = await bootKernel(part);
       const views = flags.views ? flags.views.split(",") : undefined;
       const files = await renderViews(kernel, part, view, { views, out: flags.out || "render" });
       for (const f of files) console.log(`wrote ${f}`);
       process.exit(0);
     } catch (e) {
-      die(`render failed: ${e.message || e}`);
+      crash("render", e, false);
     }
   },
 
@@ -120,7 +147,9 @@ function printMeasure(r) {
   }
   const a = r.aggregate;
   console.log(`  ── view  bbox ${a.bbox.map((n) => n.toFixed(1)).join("×")}  vol ${(a.volume / 1000).toFixed(2)}cm³  tris ${a.triangleCount}`);
-  console.log(`  overlaps: ${r.overlaps.length ? r.overlaps.map((o) => `${o.a}×${o.b} (${o.volume.toFixed(1)}mm³)`).join(", ") : "none"}`);
+  console.log(`  overlaps: ${r.overlaps.length
+    ? r.overlaps.map((o) => `${o.a}×${o.b} (${o.volume.toFixed(1)}mm³ at [${o.location.map((n) => n.toFixed(1)).join(", ")}])`).join(", ")
+    : "none"}`);
 }
 
 function printVerify(v) {
@@ -130,6 +159,10 @@ function printVerify(v) {
     for (const ch of c.checks) {
       const icon = ch.status === "pass" ? "✓" : ch.status === "fail" ? "✗" : ch.status === "warn" ? "⚠" : "·";
       console.log(`    ${icon} ${ch.subpart ?? "_view"} ${ch.metric} ${ch.expr}  (${ch.message})`);
+      if (ch.status === "fail" || ch.status === "warn") {
+        if (ch.location) console.log(`        at [${ch.location.map((n) => n.toFixed(1)).join(", ")}]`);
+        if (ch.hint) console.log(`        hint: ${ch.hint}${ch.pattern ? ` (ERROR-PATTERNS.md#${ch.pattern})` : ""}`);
+      }
     }
   }
   const f = v.failures.length, w = v.warnings.length;

package/docs/AUTHORING-PARTS.md

@@ -90,13 +90,55 @@ handles. The same code runs on **Manifold** (fast meshes — preview + STL + 3MF
 |---|---|
 | `k.cylinder(rBottom, rTop, h, { center? })` | cylinder/cone along +Z (frustum if radii differ) |
 | `k.box(min, max)` | axis-aligned box from `[x,y,z]` min/max |
-| `k.prism(points2D, h, { twist?, scaleTop? })` | extrude a 2-D polygon from z=0; optional `twist` (degrees over the height) and `scaleTop` (uniform top taper: 1 straight, <1 taper in, 0 → point/cone) |
+| `k.prism(points2D, 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? })` | 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 |
+| `k.sweep(profile2D, path3D, { 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)` | sphere centred at the origin |
 | `k.revolve(points2D, { degrees })` | revolve a lathe profile `[[r,z],…]` (r ≥ 0) around the Z axis (full or partial) |
 | `k.helixSweptTube({ pathR, profileR, pitch, turns, z0, lefthand })` | circle swept along a helix (e.g. a rope groove) |
 | `k.union(solids[])` | boolean union |
 
-2-D polygon helpers for `prism`: `import { piePolygon, hexPolygon } from "partforge/geometry"`.
+**`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 `profile2D` and a plain `[[x,y,z],…]` point list as its
+`path3D`; 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
+k.extrude({ outer: roundedRectPolygon(40, 30, 4), holes: [circleProfile(6)] }, 10);
+
+// a tapered, twisting faceted vase wall (see src/parts/faceted-vase.js)
+const rings = [];
+for (let i = 0; i <= 24; i++) { const t = i / 24;
+  rings.push({ sides: 6, radius: 30 - 8 * t, z: 120 * t, rotate: 90 * t }); }
+k.loft(rings);                          // ruled walls, capped ends
+
+// a cable/hose: sweep a circle along a 3-D polyline, with rounded bends
+k.sweep(circleProfile(3), [[0, 0, 0], [0, 0, 20], [15, 0, 20]], { cornerRadius: 5 });
+
+// round every corner of any CCW outline, then extrude/loft/prism it
+k.prism(filletPolygon(bracketOutline, 3), 4);       // tessellated corners (faceted in STEP)
+k.prism(roundedProfile(bracketOutline, 3), 4);      // true CIRCLE corners in STEP export
+```
+
+2-D polygon helpers for `prism`/`extrude`/`loft`: `import { piePolygon, hexPolygon,
+regularPolygon, roundedRectPolygon, starPolygon, circleProfile, filletPolygon,
+roundedProfile } from "partforge/geometry"`. `filletPolygon(points, r, { segs? })` rounds
+every corner of a CCW polygon (per-corner radius clamped so neighbouring arcs never overlap)
+and returns points usable by `prism`/`extrude`/`loft` on both backends — but it **bakes each
+corner into line facets**, so STEP corners are faceted. `roundedProfile(points, r | r[])`
+rounds corners the same way but keeps them **mathematically true** — it carries the arc
+symbolically so STEP export gets real circular edges. Use it for `prism`/`extrude` (not yet
+`loft` — arc rings are rejected there in v1). A scalar `r` rounds every corner; a per-corner
+`r[]` (length = points) rounds selectively (a `0`, a zero-length edge, or a straight/180°
+corner stays sharp).
 **Import geometry helpers from `partforge/geometry`, never from `partforge`** — the main
 entry pulls in the DOM viewer/controls, and your build functions run in a Web Worker
 (importing the main entry there throws `document is not defined`).
@@ -195,7 +237,12 @@ module-level mutable state. An impure build will silently return stale geometry.
 Cache granularity follows the operations you call. Booleans and heavy primitives are
 cached; cheap transforms are recomputed. To make a multi-step shape into a single
 cache node, use (or add) a **compound op** like `k.boredCylinder({ od, h, bore })` —
-it hashes from its own arguments and never exposes its internals to the cache.
+it hashes from its own arguments and never exposes its internals to the cache. The heavy
+primitives `loft`, `sweep`, `extrude`, `prism`, and `revolve` are cached this way too:
+their hash folds every shape-affecting argument (each `loft` ring's points/`z`/`rotate`/`scale`,
+`sweep`'s profile points/path points/`cornerRadius`/`closed`, `extrude`'s holes, an arc
+profile's segment specs from `roundedProfile`, and the tessellation from `twist`), so
+changing any of them is a fresh cache node while an identical rebuild is a hit.
 
 ---
 
@@ -384,9 +431,10 @@ stylesheet). `mount` looks up these element IDs:
 Copy `demo.html` and change the title, the panel heading, and the `<script src>`. Two workers are spawned from your one worker entry
 (`name` = `"manifold"` for preview/STL/3MF, `"occt"` for STEP — handled for you).
 
-> Production deploy builds `index.html` only. Extra `*.html` files are **dev-only**
-> (Vite serves any root HTML in `npm run dev`). To also ship one, add it to
-> `build.rollupOptions.input` in `vite.config.js`.
+> Production deploy compiles only the pages listed in `build.rollupOptions.input`
+> (currently the landing gallery + the demo part pages). Other root `*.html` files are
+> **dev-only** (Vite serves any root HTML in `npm run dev`) unless added there. To also
+> ship one, add it to `build.rollupOptions.input` in `vite.config.js`.
 
 ### Developing against a local (linked) partforge
 
@@ -471,6 +519,54 @@ The `measure` function is also exported for vitest (boot a Manifold kernel as in
       expect(r.subparts[0].holes).toBe(1);   // e.g. expects one bore
     });
 
+### The diagnostics contract (for agents)
+
+`partforge measure <part> --json` / `--out <file>` emits the machine-readable
+report. Every `fail`/`warn` check in `verify.failures` / `verify.warnings`
+carries:
+
+- `hint` — one self-contained corrective sentence (always present),
+- `pattern` — a stable [ERROR-PATTERNS.md](ERROR-PATTERNS.md) entry ID when one
+  applies (follow it with `ERROR-PATTERNS.md#<id>`),
+- `location` — `[x, y, z]` in mm where the metric has one: `minWall` (thinnest
+  sample point) and `overlaps` (the center of the first offending intersection's
+  *bounding box* — a nearby indicator, not an exact point: when a pair overlaps in
+  more than one place the bbox center can fall in the empty space between regions).
+  Whole-solid metrics (bbox, volume, …) have none.
+
+Subpart facts include `minWall` (number or `null` — null exactly when no reading
+exists, e.g. the OCCT backend or min-wall measurement turned off, matching
+`minWallAt`'s null) and `minWallAt` (`[x,y,z]` or `null`); overlap entries are
+`{ a, b, volume, location }`.
+
+A **thrown** error (bad part module, kernel failure) with `--json` prints pure
+JSON to stdout and exits 1:
+
+```json
+{ "ok": false, "error": { "message": "…", "pattern": "<id>", "hint": "…" } }
+```
+
+`pattern`/`hint` appear when the message matches an ERROR-PATTERNS.md symptom
+string. Exit codes: 0 pass, 1 gate failure or crash — unchanged. Caveat: a throw
+*after* measure output has printed (e.g. an unknown metric in `verify.expect`, or
+a per-case build crash) appends this JSON after the human lines, so stdout is no
+longer pure JSON; prefer `--out` (or parse the trailing JSON object — the crash
+JSON is pretty-printed across multiple lines) for robust machine parsing. With
+`--out` the measure report is written to the file as soon as `measure` succeeds,
+so even if a later `verify` throw crashes the run the file is there — it just
+lacks the `verify` key.
+
+**Part-authored hints.** Any `verify.expect` metric accepts `{ expr, hint }` in
+place of a bare expression — use it to name the governing parameter:
+
+```js
+verify: {
+  expect: {
+    body: { minWall: { expr: ">=1.2", hint: "increase `wallThickness` or reduce `twist`" } },
+  },
+}
+```
+
 ---
 
 ## Self-verification (the `verify` block)
@@ -575,20 +671,23 @@ entirely on OCCT, its fillets are exact in the STEP **and** present in the print
 
 ## Conventions & gotchas
 
-- **replicad (OCCT) transforms consume their input.** `s.translate/.rotate/.mirror/.cut`
-  delete the operand and return a new solid; never reuse a solid after transforming it.
-  The framework rebuilds each sub-part fresh per job and applies `place` once, which
-  avoids this — follow the same pattern in your own code.
-- **Part modules are DOM-free and side-effect-free** — they import into both the main
-  thread (schema → controls) and the worker (build → kernel).
+When something fails confusingly, **grep [ERROR-PATTERNS.md](ERROR-PATTERNS.md) for the
+symptom first** — it maps error text → cause → fix. The invariants, one line each:
+
+- **replicad (OCCT) transforms consume their input** — never reuse a transformed solid;
+  `.clone()` first ([replicad-consumed-operand](ERROR-PATTERNS.md#replicad-consumed-operand)).
+- **Part modules are DOM-free and side-effect-free** — they load in both the main thread
+  and the worker ([worker-imports-main-entry](ERROR-PATTERNS.md#worker-imports-main-entry)).
+- **`build` is a pure function of `(k, p, d)`** — impurity silently defeats the geometry
+  cache ([impure-build-stale-preview](ERROR-PATTERNS.md#impure-build-stale-preview)).
 - **Units are millimetres** throughout.
-- **Preview vs print quality.** Manifold bakes segment counts in at primitive creation,
-  so the export path uses a separate high-res "print" kernel — your `build` is quality-
-  agnostic; just build the geometry.
-- **Display placement is view-independent** (so meshes cache across views); only
-  `place(..., { purpose: "export" })` may depend on `view`.
-- Keep geometry backend-agnostic (kernel calls only) so it works in both backends; only
-  STEP requires OCCT.
+- **Preview vs print quality:** Manifold bakes segment counts in at primitive creation,
+  so builds are quality-agnostic; the export path uses a separate high-res "print" kernel.
+- **Display placement is view-independent**; only `place(..., { purpose: "export" })` may
+  depend on `view` ([view-dependent-display-place](ERROR-PATTERNS.md#view-dependent-display-place)).
+- **Keep geometry backend-agnostic** (kernel calls only); only STEP requires OCCT
+  ([probe-routed-to-occt](ERROR-PATTERNS.md#probe-routed-to-occt),
+  [occt-holes-watertight-na](ERROR-PATTERNS.md#occt-holes-watertight-na)).
 
 ---
 

package/docs/ERROR-PATTERNS.md

@@ -0,0 +1,150 @@
+# Error patterns — symptom-indexed lookup
+
+When a build, test, `measure`, or `verify` run fails confusingly: **grep this file
+for the symptom first** — the literal error text, or a phrase describing the
+misbehavior — before debugging from scratch.
+
+**How to add a pattern** (`##` headings are reserved for pattern entries — the lint
+test parses every one; keep prose like this as plain paragraphs):
+
+- One pattern per `## <id>` heading. The heading is a **stable kebab-case ID**:
+  permanent once committed — never renamed, never reused. External consumers
+  (issue #27 diagnostics, HARDWARE.md, skills) cite `ERROR-PATTERNS.md#<id>`.
+- **Namespaces:** core framework patterns are bare slugs. Subsystem patterns take
+  a reserved prefix — `hardware-*` is reserved for the parts library (issue #30).
+  One `#`-level section per namespace.
+- Entry shape — exactly these three list lines, then optional note paragraphs:
+  - **Symptom:** the literal string an agent would see, verbatim in backticks,
+    when one exists; otherwise the observable misbehavior. This is the grep target.
+  - **Cause:** one sentence.
+  - **Fix:** the concrete change, linking the governing rule
+    ([AUTHORING-PARTS.md](AUTHORING-PARTS.md) section) rather than restating it.
+- No tables inside entries.
+- Code that throws should throw greppable strings: an error message thrown by
+  partforge should appear verbatim, in a backtick literal **at the start** of its
+  pattern's Symptom line. Only that leading literal is what the crash matcher
+  matches on — backticks used for prose later in the line never participate, so a
+  reworded Symptom must lead with the thrown string, not bury it mid-sentence.
+- `test/error-patterns.test.js` lints this file's structure.
+
+# Core framework
+
+## worker-imports-main-entry
+
+- **Symptom:** `ReferenceError: document is not defined` thrown from a worker build.
+- **Cause:** The part (or a helper it imports) imports `partforge` instead of `partforge/geometry`, and the main entry pulls in the DOM viewer/controls.
+- **Fix:** Import geometry helpers only from `partforge/geometry` in anything a worker loads. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API".
+
+## impure-build-stale-preview
+
+- **Symptom:** Preview geometry doesn't change after editing the part's `build` (or changes once, then sticks), with no error anywhere.
+- **Cause:** The preview kernel memoizes geometry by content hash, and an impure `build` (`Math.random`, clock, module-level mutable state) silently defeats it.
+- **Fix:** Make `build` a pure function of `(k, p, d)`; move randomness/state into `derive` inputs or delete it. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Caching & determinism".
+
+## replicad-consumed-operand
+
+- **Symptom:** On the OCCT backend a solid is unexpectedly empty, or the build crashes, right after the same solid was transformed or used in a boolean — often only in STEP export, with the Manifold preview fine.
+- **Cause:** replicad transforms and booleans (`translate`/`rotate`/`mirror`/`cut`/…) consume their operand — the input solid is deleted and a new one returned.
+- **Fix:** Never reuse a solid after transforming it; take a `.clone()` first when you need the original again. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API" (the `s.clone()` row).
+
+The framework itself rebuilds each sub-part fresh per job and applies `place` once, which avoids the problem — follow the same pattern in your own code.
+
+## 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)".
+
+## boolean-not-watertight
+
+- **Symptom:** `NOT watertight ✗` from `partforge measure` (non-zero exit) after adding a boolean cut or union.
+- **Cause:** A coplanar-face or grazing-cut degeneracy — the tool surface exactly touches the body surface, leaving zero-thickness geometry.
+- **Fix:** Overcut: extend the tool past the faces it pierces (e.g. the demo's cut tool is `h + 4` starting at `z = -2`) and avoid exactly-flush faces in unions. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Verifying a part headlessly (render + measure)".
+
+## dual-kernel-same-process
+
+- **Symptom:** A test file crashes or hangs (WASM abort) when it boots both geometry kernels.
+- **Cause:** OCCT and Manifold WASM must not boot in the same process.
+- **Fix:** Keep OCCT-booting tests in their own files (vitest isolates per file) and boot via `bootOcctKernel()` in a `beforeAll`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Testing a part".
+
+## view-dependent-display-place
+
+- **Symptom:** A sub-part renders correctly in one view but appears misplaced (usually in its other-view pose) after switching views.
+- **Cause:** A `place` that depends on `ctx.view` for `purpose: "display"` — display meshes are built once per sub-part and cached across views.
+- **Fix:** Make display placement view-independent; only `place(..., { purpose: "export" })` may branch on `view`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "The `PartDefinition` contract".
+
+## wrong-node-version
+
+- **Symptom:** Confusing failures during `npm install`, tests, or CLI runs — WASM load errors, syntax errors in dependencies, or kernels that never boot — on a machine that built fine before.
+- **Cause:** The shell's default Node is older than the required Node 24 (`.nvmrc` pins it).
+- **Fix:** Run `nvm use` before `npm install`, tests, or any `npx partforge` command. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Quickstart".
+
+## worker-url-not-inline
+
+- **Symptom:** The app loads but geometry never builds — the worker 404s or is missing from the production bundle (works in `npm run dev`, breaks in `npm run build`).
+- **Cause:** The `new Worker(new URL(...))` call was moved out of the app entry file (into a helper or variable), so Vite's static analysis can't see and bundle the worker.
+- **Fix:** Keep `new Worker(new URL("./<part>-worker.js", import.meta.url), ...)` inline in `src/app-<part>.js`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Wiring a part into a runnable app".
+
+## minwall-sliver-triangles
+
+- **Symptom:** `⚠` minWall warnings from `verify` on a faceted part whose walls are clearly thicker than the profile minimum.
+- **Cause:** The ray-shot wall-thickness measurement can catch sliver triangles at facet seams, reading a near-zero "wall" that isn't a designed wall.
+- **Fix:** Check where the reported thin spot is: at a facet seam or chamfer transition it's a sliver artifact (minWall is a warning, never a gate — safe to note and move on); along a real wall, thicken the wall. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Self-verification (the `verify` block)".
+
+## param-key-missing-from-defaults
+
+- **Symptom:** The affected control's number box renders empty/blank (internally `numStr(undefined)` produces the string `NaN`, which a number input sanitizes to empty), or its range slider sits at a browser-default position and edits don't drive the geometry — no error is thrown — and if the key is `hidden`, no control is rendered for it at all.
+- **Cause:** A `key` used in the `parameters` schema (slider, feature, or preset override) doesn't exist in `defaults` — every key must, including `hidden` ones.
+- **Fix:** Add the key to `defaults` with a sensible starting value. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Parameters: the control-panel schema".
+
+## dimmed-control-vestigial-param
+
+- **Symptom:** A control renders dimmed (but still editable) and changing it does nothing on screen.
+- **Cause:** No sub-part visible in the active view reads that parameter — the relevance-aware panel dims controls with no on-screen effect.
+- **Fix:** This is a signal, not a bug: either the parameter is vestigial (delete it), the control is in the wrong section/view scope, or you're in a view that legitimately doesn't use it. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "The relevance-aware panel".
+
+## linked-checkout-wasm-403
+
+- **Symptom:** In a consuming app using an `npm link`ed partforge checkout, the kernel never boots and the dev-server network tab shows `403` on the Manifold/OCCT `.wasm` files.
+- **Cause:** The linked checkout lives outside the app's project root, so Vite's dev server refuses to serve its files.
+- **Fix:** Allow-list it: `server: { fs: { allow: ["./", "../partforge"] } }` in the app's `vite.config.js`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Developing against a local (linked) partforge".
+
+## ring-sector-full-circle
+
+- **Symptom:** `ringSectorPolygon: arcDeg must be < 360 (use a cut for a full ring)`
+- **Cause:** A full annulus can't be a single simple polygon — it's a contour-with-hole.
+- **Fix:** Cut an inner cylinder from an outer one (or `k.extrude({ outer, holes })`); use `ringSectorPolygon` only for partial arcs. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Profiles & patterns".
+
+## occt-closed-loop-unsupported
+
+- **Symptom:** `loft: closed:true loops are only supported on the Manifold backend` (or the same message from `sweep:`) — typically during STEP export of a part that previews fine.
+- **Cause:** Capless closed loops are a Manifold-only capability; the OCCT backend rejects them, and STEP export always runs on OCCT.
+- **Fix:** Keep the part on Manifold (no STEP) or model the loop as a capped solid both backends support. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API".
+
+## smooth-geometry-faceted-preview
+
+- **Symptom:** A `ruled:false` loft or `smooth:true` sweep looks faceted/straight-walled in the viewer even though the options are set.
+- **Cause:** Smooth blending is OCCT-native; the Manifold preview always tessellates ruled straight walls — only STEP export carries the smooth surface.
+- **Fix:** Nothing is wrong — verify smoothness in the exported STEP, not the preview. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API".
+
+## scale-moved-the-part
+
+- **Symptom:** After `s.scale(f)` a part is resized but also relocated — features drift away from where they were built.
+- **Cause:** `scale(factor, center?)` defaults its center to the origin, so scaling an off-origin solid about the origin also translates it.
+- **Fix:** Pass the center you mean, e.g. `s.scale(f, s.boundingBox().center)` to resize in place. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API".
+
+## occt-holes-watertight-na
+
+- **Symptom:** `watertight n/a` in `partforge measure` output, and `holes`/`watertight` assertions in a `verify` block don't run, on a part with fillets/chamfers.
+- **Cause:** `holes` and `watertight` are Manifold-only topology facts, and this part auto-routed to OCCT — the assertions skip rather than fail.
+- **Fix:** Expected behavior: assert on backend-independent facts (`bbox`, `volume`, `overlaps`) for OCCT parts, or split topology assertions into a Manifold-buildable configuration. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Self-verification (the `verify` block)".
+
+## html-page-missing-in-prod
+
+- **Symptom:** A part's page 404s in the production deploy while working fine under `npm run dev`.
+- **Cause:** Only pages listed in `build.rollupOptions.input` are compiled by the production build; other root `*.html` pages are dev-only conveniences Vite serves without building.
+- **Fix:** Add the page to `build.rollupOptions.input` in `vite.config.js` if it should ship. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Wiring a part into a runnable app".
+
+# Hardware library
+
+Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.7.0",
+  "version": "0.9.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",
@@ -18,6 +18,7 @@
     "bin",
     "skills/partforge/SKILL.md",
     "docs/AUTHORING-PARTS.md",
+    "docs/ERROR-PATTERNS.md",
     "README.md"
   ],
   "exports": {

package/skills/partforge/SKILL.md

@@ -56,3 +56,8 @@ Picks come back **in request order**, each echoing its prompt, so you can map th
 
 - This only *reads* a click — it never edits files. You make the edits yourself after.
 - The server is localhost-only and holds one request at a time.
+
+## Related: debugging failures
+
+If anything fails while you're editing a part, grep `docs/ERROR-PATTERNS.md` for the
+symptom first — its preamble states the full grep-first rule.

package/src/app-faceted-vase.js

@@ -0,0 +1,10 @@
+import vasePart from "./parts/faceted-vase.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only example app for the faceted vase part. Identical wiring to app-planter.js —
+// only the imported definition and the worker entry differ per part. `npm run dev`,
+// then open /faceted-vase.html.
+mount(vasePart, {
+  createWorker: (name) =>
+    new Worker(new URL("./faceted-vase-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/faceted-vase-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/faceted-vase.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/src/framework/assembly.js

@@ -6,7 +6,7 @@ import { viewSubParts, resolveParams, buildPosed } from "./jobs.js";
 // Parts meant to fit together (e.g. a block seated in a pocket void) read ~0 and
 // don't trip it. Manifold-only (needs Solid.intersect + Solid.volume); meant for
 // part tests so an author/LLM editing a part sees collisions fail.
-//   → [{ a, b, volume }] for each offending pair (empty = no collisions)
+//   → [{ a, b, volume, location }] for each offending pair (empty = no collisions)
 export function assemblyOverlaps(kernel, part, view, params = {}, { tolerance = 1 } = {}) {
   const { p, d } = resolveParams(part, params);
   const posed = viewSubParts(part, view, p).map((name) => ({
@@ -17,8 +17,14 @@ export function assemblyOverlaps(kernel, part, view, params = {}, { tolerance =
   const overlaps = [];
   for (let i = 0; i < posed.length; i++) {
     for (let j = i + 1; j < posed.length; j++) {
-      const volume = posed[i].solid.intersect(posed[j].solid).volume();
-      if (volume > tolerance) overlaps.push({ a: posed[i].name, b: posed[j].name, volume });
+      const inter = posed[i].solid.intersect(posed[j].solid);
+      const volume = inter.volume();
+      if (volume > tolerance) {
+        // location = the intersection's bounding-box center — a nearby indicator, not
+        // an exact contact point: for a disjoint (multi-region) intersection it is the
+        // midpoint of those regions and can land in the empty space between them.
+        overlaps.push({ a: posed[i].name, b: posed[j].name, volume, location: inter.boundingBox().center });
+      }
     }
   }
   kernel.cleanup?.(); // free the per-check WASM objects

package/src/framework/geometry/helix-tube.js

@@ -1,8 +1,10 @@
 // Builds a watertight triangle mesh of a circular profile swept along a helix in
 // its frenet frame, then imports it as a Manifold solid. The profile stays
 // perpendicular to the helix tangent (unlike twist-extrude), so it matches an
-// exact frenet sweep. Winding is consistent-outward; getting it wrong makes
-// Manifold.ofMesh throw or import an inverted solid.
+// exact frenet sweep. Winding is consistent-outward; the ring stitching + caps +
+// ofMesh import are the shared ring-mesh helpers in mesh-build.js (also used by loft).
+import { sideQuads, fanCap, manifoldFromMesh } from "./mesh-build.js";
+
 const norm = (v) => { const m = Math.hypot(...v); return [v[0] / m, v[1] / m, v[2] / m]; };
 const cross = (a, b) => [a[1]*b[2]-a[2]*b[1], a[2]*b[0]-a[0]*b[2], a[0]*b[1]-a[1]*b[0]];
 
@@ -28,23 +30,11 @@ export function helixTube(wasm, opts) {
              ctr[2] + profileR * (Math.cos(a) * N[2] + Math.sin(a) * B[2]));
     }
   }
-  // side faces (outward winding)
-  for (let i = 0; i < n - 1; i++) for (let j = 0; j < ringSegs; j++) {
-    const a = i*ringSegs + j, b = i*ringSegs + (j+1)%ringSegs;
-    const cc = (i+1)*ringSegs + j, dd = (i+1)*ringSegs + (j+1)%ringSegs;
-    Tr.push(a, dd, cc, a, b, dd);
-  }
-  // end caps
-  const c0 = V.length / 3;
-  V.push(pathR * Math.cos(0), pathR * Math.sin(0), z0);
-  for (let j = 0; j < ringSegs; j++) Tr.push(c0, (j+1)%ringSegs, j);
-  const base = (n - 1) * ringSegs, cz = V.length / 3;
-  V.push(pathR * Math.cos(sign * phiMax), pathR * Math.sin(sign * phiMax), z0 + c * phiMax);
-  for (let j = 0; j < ringSegs; j++) Tr.push(cz, base + j, base + (j+1)%ringSegs);
+  sideQuads(Tr, n, ringSegs, false); // side walls between the n stations
+  // end caps fanned from each end's path-center (outward: bottom flipped, top not)
+  fanCap(V, Tr, 0, ringSegs, [pathR, 0, z0], true);
+  fanCap(V, Tr, (n - 1) * ringSegs, ringSegs,
+         [pathR * Math.cos(sign * phiMax), pathR * Math.sin(sign * phiMax), z0 + c * phiMax], false);
 
-  const mesh = new wasm.Mesh({ numProp: 3, vertProperties: Float32Array.from(V), triVerts: Uint32Array.from(Tr) });
-  mesh.merge();
-  const out = wasm.Manifold.ofMesh(mesh);
-  mesh.delete?.(); // input mesh is consumed by ofMesh; free it (caller tracks `out`)
-  return out;
+  return manifoldFromMesh(wasm, V, Tr);
 }

package/src/framework/geometry/kernel-front.js

@@ -15,6 +15,12 @@ export function finishKernel(k) {
     return rawPrism(pts, h, opts);
   };
 
+  const rawExtrude = k.extrude;
+  k.extrude = (profile, h, opts) => {
+    if ((opts?.scaleTop ?? 1) < 0) throw new Error("extrude: scaleTop must be ≥ 0");
+    return rawExtrude(profile, h, opts);
+  };
+
   const rawRevolve = k.revolve;
   k.revolve = (pts, opts) => {
     for (const [r] of pts) if (r < 0) throw new Error("revolve: profile radius must be ≥ 0");

package/src/framework/geometry/kernel.js

@@ -7,8 +7,8 @@
 
 // Ops every backend kernel must implement.
 export const KERNEL_OPS = [
-  "cylinder", "boredCylinder", "sphere", "box", "prism", "revolve",
-  "helixSweptTube", "union", "toSTEP",
+  "cylinder", "boredCylinder", "sphere", "box", "prism", "extrude", "revolve",
+  "loft", "sweep", "helixSweptTube", "union", "toSTEP",
 ];
 
 // Backend-optional kernel ops: the Manifold cache brackets + WASM lifetime hooks.
@@ -70,6 +70,9 @@ export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
  * @property {(r:number) => Solid} sphere   sphere centred at the origin
  * @property {(min:number[], max:number[]) => Solid} box
  * @property {(points2D:number[][], h:number, opts?:{twist?:number,scaleTop?:number}) => Solid} prism   extrude polygon from z=0 (optional twist° + uniform top taper)
+ * @property {(profile:number[][]|{outer:number[][],holes?:number[][][]}, h:number, opts?:{twist?:number,scaleTop?:number}) => Solid} extrude   extrude a polygon-with-holes region from z=0 in one op (bare array = outer only)
+ * @property {(rings:{polygon?:number[][],sides?:number,radius?:number,z:number,rotate?:number,scale?:number|number[]}[], opts?:{ruled?:boolean,closed?:boolean}) => Solid} loft   stack polygon cross-sections (per-ring z/rotate/scale), ruled walls, capped ends
+ * @property {(profile2D:number[][], path3D:number[][], opts?:{closed?:boolean,cornerRadius?:number,ruled?:boolean,smooth?:boolean}) => Solid} sweep   sweep a fixed 2-D profile along a 3-D polyline path (sharp mitered corners or cornerRadius fillets; capped ends; closed:true loops and smooth:true native B-rep are backend-specific)
  * @property {(points2D:number[][], opts?:{degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube
  * @property {(solids:Solid[]) => Solid} union