partforge 0.8.0 → 0.10.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,12 @@ 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"}`);
+  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"}`);
 }
 
 function printVerify(v) {
@@ -130,6 +162,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

@@ -44,7 +44,7 @@ export default {
   meta: { title, units, background? },     // title string; units e.g. "mm"; background = 0xRRGGBB scene colour
   parameters,                              // the control-panel schema (array of sections — see below)
   defaults,                                // flat { paramKey: value } — seeds params + control values
-  derive?,                                 // (p) => d   optional dependent values computed once per build
+  derive?,                                 // (p) => d, or { group: (p, d) => {…}, … } — dependent values computed once per build
   parts: {                                 // named sub-parts; each builds ONE solid
     <name>: {
       label?,                              // display name (tabs/progress); defaults to the key
@@ -71,6 +71,14 @@ export default {
   `"display"` or `"export"`; `ctx.view` is the active view. Default is identity, so simple
   parts omit it. **Display placement must not depend on `view`** — display meshes are built
   once per sub-part and cached across views (the viewer re-centres per view).
+  **Any difference between the display and export pose must be a rigid motion** —
+  `translate`/`rotate`/`rotateAbout`/`along`/`at` only. Never put a `mirror` or a
+  non-identity `scale` on one purpose but not the other: the exported (printed) part is the
+  same physical object you show in the assembly, and a reflection or resize there makes the
+  two silently disagree — you print the mirror image of what the viewer showed
+  ([place-not-rigid](ERROR-PATTERNS.md#place-not-rigid)). If a part genuinely needs a
+  reflected or resized form (e.g. a block that seats flipped), bake that into `build` so
+  both purposes share one canonical solid, then pose it rigidly.
 - `enabled(p)` gates a conditional sub-part (e.g. only present when a feature is on).
 - A view's sub-parts are derived, never hard-coded: those whose `views` include the view
   and whose `enabled(p)` is true.
@@ -81,8 +89,10 @@ export default {
 
 `build` receives a backend-agnostic `kernel` (`k`). It returns and combines `Solid`
 handles. The same code runs on **Manifold** (fast meshes — preview + STL + 3MF) and
-**OCCT/replicad** (exact B-rep — STEP). Contract lives in
-`src/framework/geometry/kernel.js`.
+**OCCT/replicad** (exact B-rep — STEP). Op lists live in
+`src/framework/geometry/kernel.js`; the normative semantics (conventions, value
+semantics, conformance classes, versioning) are in `docs/KERNEL-CONTRACT.md` — the
+tables below are the authoring-side view of that contract.
 
 **Kernel — make solids:**
 
@@ -204,9 +214,16 @@ anything `rotateX/Y/Z`/`rotateAbout` can't express, but prefer the vocabulary ab
 
 ### Naming features (`.label()`)
 
-Give build-step solids human-readable names — the viewer's hover tooltip, the
-highlight, and pick selections all use them, so you, the app user, and an agent
-share the same vocabulary ("Make the Drainage hole 10 mm").
+Label your part's features, and label them **thoroughly** — this is how a user points
+at what they want changed. The viewer's hover tooltip, highlight, and pick selection
+all show a feature's label, so you, the app user, and an agent editing on their behalf
+share one vocabulary: "make the Drainage hole 10 mm", "raise the Motor upright". A
+feature with no name can't be referred to — it reads as the whole part, so the request
+has nowhere to land.
+
+Treat comprehensive labeling as the default, not a finishing touch. Name every feature
+a user could reasonably want to change: the base body, and each functional feature —
+grooves, mounts, bores, pockets, distinct structural members.
 
 ```js
 const body = k.prism(d.outerPts, p.height, { scaleTop: p.taper }).label("Faceted wall");
@@ -214,18 +231,26 @@ let s = body.cut(cavity.label("Cavity"));
 if (p.drain > 0) s = s.cut(k.cylinder(d.drainR, d.drainR, p.floor + 4).at([0, 0, -2]).label("Drainage hole"));
 ```
 
+- **Aim for functional groups.** Label at the granularity a user would name a thing
+  ("Rope groove", "Tensioner pockets", "Bearing seat"), grouping repeated or related
+  faces under one name. Fine enough to reference any feature; coarse enough that
+  near-identical surfaces don't fragment into dozens of near-duplicates.
 - A label names the solid's **surface** wherever it survives into the final part —
   a cutting tool's label lands on the faces it leaves behind (the hole's wall).
 - Label **after** shaping compound tools (e.g. after an `intersect` clip) and
   either before or after transforms — labels ride through `at`/`rotate`/etc.
-- The **same label on several solids merges into one feature** — label a pattern
-  of four holes `"Mounting holes"` and they hover/highlight as one.
+- **Same label merges; distinct siblings need distinct names.** The same label on
+  several solids merges into one feature — label a ring of four bolt holes
+  `"Mounting holes"` and they hover/highlight as one. Conversely, when two similar
+  features are things a user would tell apart, name them apart — two uprights as
+  `"Drum upright"` and `"Motor upright"`, not both `"Upright"`.
 - Unlabeled geometry falls back to the sub-part's `label`. Faces created by
   `fillet`/`chamfer`/`shell` are new surfaces, so they use the fallback too.
 - Works on both backends. On OCCT each label keeps a geometry snapshot for
-  mesh-time classification — label a handful of features, not hundreds.
-- Names should describe intent ("Drainage hole", not "cylinder2"); keep them
-  unique per sub-part unless you want the merge behavior.
+  mesh-time classification, so label meaningful features (functional groups — a
+  handful to a couple dozen per part), not hundreds of individual faces.
+- Names should describe intent ("Drainage hole", not "cylinder2"); make them
+  unique per sub-part unless you specifically want the merge behavior.
 
 ### Caching & determinism
 
@@ -324,6 +349,33 @@ coherently:
   thicknesses — so a single input feeds everything downstream. In the demo, `derive`
   turns the nominal `bore` into `boreR` (with a fixed print clearance) and `h` into the
   cut-tool height `cutH`; `build(k, p, d)` reads those.
+- **Grouped `derive` (recommended once it grows):** `derive` may instead be an object of
+  named group functions, run in declaration order; each group receives `(p, d)` where `d`
+  holds the merged outputs of the groups **before** it:
+
+  ```js
+  derive: {
+    core:  (p) => ({ boreR: p.bore / 2 + 0.15 }),
+    stand: (p, d) => ({ postH: d.boreR * 4 + p.base_t }),   // may read earlier groups
+  }
+  ```
+
+  Builds see the same merged `d` either way. The point is the **control panel's
+  relevance dimming** (and the rebuild cache): with a single function, a sub-part that
+  reads *any* derived value is assumed to depend on *every* param `derive` touches, so
+  e.g. stand-only controls stay lit in a drum-only view. With groups, each derived key
+  is attributed to just its own group's inputs (plus, transitively, those of the groups
+  it read), so unrelated controls dim correctly. Group along your sub-part seams:
+  values only one sub-part family reads belong in their own group.
+
+  Grouped-form rules: a group reading a key **no earlier group produced** throws
+  immediately (misordered groups / typos would otherwise surface as silent NaN
+  geometry) — this includes optional-chaining reads like `d.maybe?.x`, so probe for a
+  conditionally-produced key with `"maybe" in d`, not `?.`. Prefer returning values
+  over mutating `d` in place — mutation works and is tracked, but returned keys read
+  clearer. Outside the part definition (helpers, tests), merge groups with
+  `resolveDerived(part, p)` from **`partforge/derive`** — a lean, DOM-free entry safe
+  to import from part modules; don't hand-roll the merge.
 - **Reuse a param `key`** across sub-parts/features so one slider moves all of them.
 - **`enabled(p)`** gates a whole sub-part on a toggle param (the part appears/disappears
   with the control).
@@ -431,9 +483,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
 
@@ -457,11 +510,11 @@ Tests run under **Node 24** (`nvm use` first; the default shell Node is too old)
 `npx vitest run`. Build geometry directly off your part with a Manifold kernel:
 
 ```js
-import { bootManifoldKernel } from "partforge/testing";
+import { bootManifoldKernel, resolveDerived } from "partforge/testing";
 import part from "../src/parts/<part>.js";
 
 const k = await bootManifoldKernel();
-const solid = part.parts.<name>.build(k, part.defaults, part.derive?.(part.defaults) ?? {});
+const solid = part.parts.<name>.build(k, part.defaults, resolveDerived(part, part.defaults));
 expect(solid.toMesh().triangles).toBeGreaterThan(0);
 ```
 
@@ -497,7 +550,10 @@ check it without opening the app:
 
 `measure` prints a report: per sub-part and per view it reports bounding box,
 volume, surface area, triangle count, whether the solid is watertight, and the
-number of through-holes (genus), plus an assembly overlap check. It exits non-zero
+number of through-holes (genus), plus an assembly overlap check, and a
+**near-miss** check — sub-part pairs whose surfaces come closer than 0.5 mm
+without touching (`near-misses:` in the output; reported for judgment, never an
+exit-code gate by itself). It exits non-zero
 if any sub-part isn't watertight or any parts interpenetrate — so it doubles as a
 CI/agent gate. Add `--json` to also dump the report as JSON on stdout, or
 `--out report.json` to write it to a file (nothing is written otherwise). (Manifold output is
@@ -518,6 +574,58 @@ 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)
+  and the pair checks `contact` / `clearance` / `nearMiss` (the midpoint between
+  the pair's closest surface points). 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 }`. Pair-distance facts are `gaps` (every sub-part
+pair: `{ a, b, distance, at }`, distance 0 = touching or overlapping) and
+`nearMisses` (the pairs with an unintended-looking gap under 0.5 mm).
+
+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)
@@ -533,7 +641,9 @@ verify: {
   cases: ["defaults", "M3"],     // optional; default = defaults + every preset
   expect: {                      // design intent, by sub-part name (+ "_view")
     spacer: { holes: 1, bbox: "<=[60,60,60]", volume: "0.4..0.6cm3" },
-    _view:  { overlaps: 0 },
+    _view:  { overlaps: 0,
+              contacts:  [["drum", "flange"]],       // these pairs must touch
+              clearance: { "lid×body": ">=0.3" } },  // intended free fits
   },
 }
 ```
@@ -542,7 +652,7 @@ verify: {
 and a **min-wall** warning. **What `expect` gives you:** per-sub-part assertions on the
 facts `measure` already reports — `holes` (through-bores / genus), `volume`,
 `surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`; and `_view` assertions
-`bbox`, `volume`, `overlaps`.
+`bbox`, `volume`, `overlaps`, plus the pair-wise `contacts` / `clearance` below.
 
 **Assertion DSL:** a bare number means equality (`holes: 1`); `">=n"`, `"<=n"`, `">n"`,
 `"<n"`, or a range `"a..b"`; an optional unit suffix `mm`/`cm`/`mm3`/`cm3`; and for
@@ -555,6 +665,53 @@ The parser is strict — a malformed assertion fails loudly.
 `holes`/`watertight` are Manifold-only, so those assertions **skip** on OCCT parts
 rather than fail.
 
+**Per-case expectations.** Checks run across defaults **and every preset**, so a
+static `expect` breaks the moment a preset legitimately changes an asserted fact —
+a "cup" preset that turns the drainage hole off flips the genus from 1 to 0.
+For that, declare `expect` as a **pure function of the case's resolved params**,
+`(p, d) => ({ … })` (same `p`/`d` your `build` sees, `d` from `derive`):
+
+```js
+verify: {
+  process: "fdm-pla",
+  expect: (p) => ({
+    planter: { holes: p.drain > 0 ? 1 : 0, bbox: "<=[220,220,250]" },
+    _view: { overlaps: 0 },
+  }),
+}
+```
+
+`src/parts/planter.js` is the worked example — its "Pen cup" and "Vase" presets
+disable the drain, so the hole count is pinned per case. Keep the function pure
+(no clock/randomness), like every other part function.
+
+**Contacts & clearance (near-miss gaps).** Volume, bbox, and render checks all miss
+sub-parts that *almost* touch — a flange floating 0.3 mm off its drum body passes
+every one of them. `measure` therefore reports `nearMisses` (pairs with a
+surface-to-surface gap under 0.5 mm), and `_view` accepts two pair-wise gates:
+
+- `contacts: [["drum", "flange"]]` — each listed pair must touch. The gate fails
+  with the measured gap and the closest-point location when the surfaces don't
+  meet. Interpenetration counts as contact — the separate `overlaps` gate owns
+  *excessive* interpenetration. A pair naming an `enabled()`-gated sub-part
+  **skips** in cases where that sub-part is off; a name that exists nowhere in
+  the part still throws.
+- `clearance: { "lid×body": ">=0.3" }` — an intended free fit. Keys are `"a×b"`
+  (order doesn't matter); values take the same assertion DSL as any metric (and
+  the `{ expr, hint }` form), evaluated against the pair's minimum surface
+  distance in mm.
+
+Any pair *not* declared either way that sits closer than 0.5 mm becomes a
+**warning** — the "did you mean these to touch?" signal. Declare the pair to
+silence it. Distances are measured mesh-to-mesh (exact triangle distance, so it
+works on both backends with no kernel booleans); contact tolerates ~1 µm, so a
+tessellation-limited curved contact (e.g. equal-radius cylinder-in-bore built with
+different facet counts) may read a few hundredths of a millimetre — prefer a tight
+`clearance` bound like `"<=0.05"` over `contacts` for those. One OCCT caveat: with
+no overlap detection there (`Solid.intersect` is Manifold-only), a sub-part
+*fully contained* inside another reads as its surface-to-surface distance, so it
+can surface as a near miss — check containment cases on Manifold.
+
 **Running it:**
 
 ```bash
@@ -596,7 +753,9 @@ whole part to OCCT — no declaration needed:
 - `{ dir: "X"｜"Y"｜"Z" }` — edges running along an axis (e.g. `{dir:"Z"}` = the vertical edges)
 - `{ inPlane: "XY"｜"XZ"｜"YZ", at }` — edges lying in a plane (e.g. base edges: `{inPlane:"XY", at:0}`)
 - `{ near: [x,y,z] }` — edges passing through a point
-- a raw `(edgeFinder) => edgeFinder` replicad finder, for anything fancier
+- a raw `(edgeFinder) => edgeFinder` replicad finder, for anything fancier — **OCCT-only
+  escape hatch**: fine for a part that's happy to stay in this repo, but non-portable
+  (parts meant to travel must use the object forms — see `KERNEL-CONTRACT.md`)
 
 ```js
 let s = k.box([0,0,0],[40,30,16]);
@@ -622,20 +781,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,168 @@
+# 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".
+
+## place-not-rigid
+
+- **Symptom:** The exported/printed part is a mirror image of — or a different size than — the same part shown in the assembly/display view. Nothing throws: the preview looks right and only the STL/STEP is wrong, or vice-versa.
+- **Cause:** A `place` whose `purpose: "display"` and `"export"` branches differ by a non-rigid transform — `mirror` (flips handedness) or a non-identity `scale` (changes size) — so display and export are no longer the same solid, only its reflection/resize.
+- **Fix:** Keep the display-vs-export `place` difference a rigid motion (`translate`/`rotate`/`rotateAbout`/`along`/`at`) only. If the part genuinely needs a reflected or resized form, bake that into `build` so both purposes share one canonical solid and pose it rigidly. 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)".
+
+## near-miss-gap
+
+- **Symptom:** A `⚠ … nearMiss` warning or `✗ … contact` failure from `verify` reporting sub-parts `N mm apart, expected touching`, or a `near-misses:` line in `measure` output for parts that look joined in the preview.
+- **Cause:** Two sub-parts that should meet don't quite — a boss shorter than the gap it must bridge, a mis-placed mating datum in `derive()`, or a union that silently missed. Renders and volume/bbox checks cannot see sub-mm joint gaps; this check exists precisely for them.
+- **Fix:** If the pair should touch, grow the joining feature or fix the datum math so the faces meet, then declare the pair in `verify.expect._view.contacts`; if a free fit is intended, declare it under `clearance`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Self-verification (the `verify` block)".
+
+## expect-static-across-presets
+
+- **Symptom:** A `verify` exact gate (`holes`, `volume`, …) fails on SOME presets only — e.g. `✗ planter holes 1  (0 != 1)` on two cases while defaults pass — and the preview looks right for every preset.
+- **Cause:** `verify` runs `expect` across defaults + every preset, and a preset legitimately changes the asserted fact (an optional feature like a drain/bore toggles the genus), while the expectation is one static value.
+- **Fix:** Declare `expect` as a pure function of the case's resolved params — `expect: (p, d) => ({ body: { holes: p.drain > 0 ? 1 : 0 } })` — or restrict `verify.cases`. 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.