partforge 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.8.0",
+  "version": "0.10.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,12 +18,14 @@
     "bin",
     "skills/partforge/SKILL.md",
     "docs/AUTHORING-PARTS.md",
+    "docs/ERROR-PATTERNS.md",
     "README.md"
   ],
   "exports": {
     ".": "./src/index.js",
     "./worker": "./src/framework/worker.js",
     "./geometry": "./src/framework/geometry/polygon.js",
+    "./derive": "./src/framework/derive.js",
     "./testing": "./src/testing.js"
   },
   "bin": {

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/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/derive.js

@@ -0,0 +1,28 @@
+// Resolve a part's `derive` into the derived-values object `d` that builds receive.
+//
+// Two authoring forms:
+//   derive: (p) => d                      — one function, computed in a single pass.
+//   derive: { name: (p, d) => {...}, … }  — named GROUPS, run in declaration order;
+//     each group gets the params plus the merged outputs of the groups before it.
+// The grouped form exists so the relevance layer (param-deps.js) can attribute each
+// derived value to just its own group's inputs instead of every param derive touches.
+export function resolveDerived(part, p) {
+  const derive = part.derive;
+  if (!derive) return {};
+  if (typeof derive === "function") return derive(p) ?? {};
+  const d = {};
+  // Groups read earlier groups' outputs through this guard: a key nothing has
+  // produced yet is a wiring mistake (group order / typo), and silently reading
+  // undefined would surface as NaN geometry far downstream — throw here instead.
+  // (Builds still receive the plain merged object, unguarded.)
+  const guard = new Proxy(d, {
+    get(t, key) {
+      if (typeof key === "string" && key !== "then" && !(key in t)) {
+        throw new Error(`derive: group read "${key}" before any earlier group produced it`);
+      }
+      return Reflect.get(t, key);
+    },
+  });
+  for (const fn of Object.values(derive)) Object.assign(d, fn(p, guard) ?? {});
+  return d;
+}

package/src/framework/geometry/kernel.js

@@ -3,7 +3,14 @@
 // test/occt-backend.test.js) assert each backend exposes exactly these ops, so the
 // contract can't silently drift from the implementations — the drift class that
 // once broke the probe kernel (see probe.js). The @typedefs document signatures.
-// (2-D polygon helpers live in ./polygon.js.)
+// The prose half of the contract — conventions, value semantics, conformance
+// classes, versioning policy — is docs/KERNEL-CONTRACT.md; change either side and
+// you must update the other. (2-D polygon helpers live in ./polygon.js.)
+
+// The prose half's version: docs/KERNEL-CONTRACT.md's "Contract version" header
+// must match this number (asserted in kernel-contract.test.js). Bump only on a
+// breaking contract change — see the doc's Versioning section.
+export const CONTRACT_VERSION = 1;
 
 // Ops every backend kernel must implement.
 export const KERNEL_OPS = [

package/src/framework/geometry/probe.js

@@ -3,6 +3,7 @@
 // if an OCCT-only op was used, the part needs the OCCT backend. The op list lives
 // in kernel.js — the same list generates the Manifold backend's throwing stubs.
 import { OCCT_ONLY_OPS } from "./kernel.js";
+import { resolveDerived } from "../derive.js";
 
 const OCCT_ONLY = new Set(OCCT_ONLY_OPS);
 
@@ -49,7 +50,11 @@ export function createProbeKernel() {
 export function detectBackend(part, params = {}) {
   if (part.meta?.backend) return part.meta.backend;
   const p = { ...part.defaults, ...params };
-  const d = part.derive ? part.derive(p) : {};
+  let d = {};
+  // A throwing derive must not escape here — this runs on the main thread mid
+  // regen (after the busy spinner goes up). Probe with an empty `d`; the worker
+  // build hits the same throw and posts a proper error for the UI.
+  try { d = resolveDerived(part, p); } catch { /* fall through with d = {} */ }
   const { kernel, used } = createProbeKernel();
   for (const name of Object.keys(part.parts)) {
     try { part.parts[name].build(kernel, p, d); } catch { /* probe miss → capability backstop covers it */ }

package/src/framework/jobs.js

@@ -1,4 +1,5 @@
 import { meshTo3MF } from "./geometry/threemf.js";
+import { resolveDerived } from "./derive.js";
 
 // Names of the sub-parts a view shows: declared in the view and enabled for these
 // params. Order follows Object.keys(part.parts) (definition order).
@@ -23,8 +24,7 @@ export function exportSubParts(part, view, params) {
 // layered over the part defaults, and derive() run once over the result.
 export function resolveParams(part, params) {
   const p = { ...part.defaults, ...params };
-  const d = part.derive ? part.derive(p) : {};
-  return { p, d };
+  return { p, d: resolveDerived(part, p) };
 }
 
 // Build one sub-part and apply its optional place() for the given purpose/view.
@@ -52,13 +52,16 @@ const bufferOf = (data) => (ArrayBuffer.isView(data) ? data.buffer : data);
 
 export async function handle(kernel, part, msg, post) {
   const onProgress = (phase) => post({ type: "progress", phase });
-  const { p, d } = resolveParams(part, msg.params);
   const label = (name) => part.parts[name].label ?? name;
   const exportName = (name) => part.parts[name].export?.name ?? name;
-  // Local shorthand over the shared helper: kernel/part/view/p/d are fixed per job.
-  const posed = (name, purpose, prog) => buildPosed(kernel, part, name, { purpose, view: msg.view, p, d, onProgress: prog });
 
   try {
+    // Inside the try so a throwing derive posts an error the UI can show,
+    // instead of killing the worker turn silently (an endless spinner).
+    const { p, d } = resolveParams(part, msg.params);
+    // Local shorthand over the shared helper: kernel/part/view/p/d are fixed per job.
+    const posed = (name, purpose, prog) => buildPosed(kernel, part, name, { purpose, view: msg.view, p, d, onProgress: prog });
+
     if (msg.type === "generate") {
       const t0 = Date.now();
       const useCache = msg.cache !== false; // ?debug toggle can disable caching (cache:false)

package/src/framework/mount.js

@@ -8,6 +8,7 @@ import { relevantParamKeys } from "./param-deps.js";
 import { createMeshCache } from "./mesh-cache.js";
 import { createGeometryService } from "./geometry-service.js";
 import { viewSubParts } from "./jobs.js";
+import { resolveDerived } from "./derive.js";
 import { detectBackend } from "./geometry/probe.js";
 import { createDebugOverlay } from "./debug-overlay.js";
 import { createRegenLoop } from "./regen-loop.js";
@@ -58,7 +59,12 @@ export function mount(part, { createWorker, container = document.getElementById(
 
   // Current selection context for the pickers: the active view + live params +
   // derived values. Shared by both ?pick modes below.
-  const getContext = () => ({ view: view(), params, derived: part.derive ? part.derive({ ...part.defaults, ...params }) : {} });
+  const getContext = () => {
+    let derived = {};
+    // A throwing derive must not crash the pick flow — proceed without derived context.
+    try { derived = resolveDerived(part, { ...part.defaults, ...params }); } catch { /* derived stays {} */ }
+    return { view: view(), params, derived };
+  };
 
   // ?pick enables click-to-select: a toggle button + a transient toast. Off by
   // default — no button, no listener, no behavior change. Deleting this block and

package/src/framework/param-deps.js

@@ -4,6 +4,7 @@
 // probe kernel). Errs toward RELEVANT_ALL whenever it can't analyze a build.
 import { createProbeKernel } from "./geometry/probe.js";
 import { viewSubParts } from "./jobs.js";
+import { resolveDerived } from "./derive.js";
 
 export const RELEVANT_ALL = Symbol("relevant-all");
 
@@ -19,9 +20,56 @@ function recorder(obj, seen) {
   });
 }
 
+// Run derive with recorders. `allInputs` is every raw param derive reads.
+// For the grouped form (derive as an object of group functions — see derive.js),
+// `depsOf` maps each derived key to the raw params of just its own group,
+// transitively including the groups whose outputs it read. For the single-function
+// form there is no per-key attribution, so depsOf is null and callers fall back to
+// treating every derive input as feeding every derived key.
+function analyzeDerive(part, params) {
+  const allInputs = new Set();
+  if (!part.derive) return { derived: {}, allInputs, depsOf: null };
+  if (typeof part.derive === "function") {
+    const derived = part.derive(recorder(params, allInputs)) ?? {};
+    return { derived, allInputs, depsOf: null };
+  }
+  const derived = {};
+  const depsOf = new Map();
+  for (const fn of Object.values(part.derive)) {
+    const raw = new Set();
+    const fromEarlier = new Set();
+    const written = new Set();
+    // Reads are recorded (and guarded against not-yet-produced keys, matching
+    // resolveDerived); writes pass THROUGH to the real accumulator so a group
+    // that mutates `d` in place analyzes exactly like it runs in production.
+    const dProxy = new Proxy(derived, {
+      get(t, key) {
+        if (typeof key === "string" && key !== "then") {
+          if (!(key in t)) throw new Error(`derive: group read "${key}" before any earlier group produced it`);
+          fromEarlier.add(key);
+        }
+        return Reflect.get(t, key);
+      },
+      set(t, key, v) {
+        if (typeof key === "string") written.add(key);
+        return Reflect.set(t, key, v);
+      },
+    });
+    const out = fn(recorder(params, raw), dProxy) ?? {};
+    const deps = new Set(raw);
+    for (const k of fromEarlier) for (const dep of depsOf.get(k) ?? []) deps.add(dep);
+    for (const r of raw) allInputs.add(r);
+    for (const key of [...Object.keys(out), ...written]) {
+      depsOf.set(key, deps);
+      if (Object.hasOwn(out, key)) derived[key] = out[key];
+    }
+  }
+  return { derived, allInputs, depsOf };
+}
+
 export function relevantParamKeys(part, view, params) {
   // The union of every on-screen sub-part's read set (that's exactly what
-  // subPartReadKeys computes, derive-input folding included)...
+  // subPartReadKeys computes, derive attribution included)...
   const reads = subPartReadKeys(part, view, params);
   if (reads === RELEVANT_ALL) return RELEVANT_ALL; // analysis failed → everything relevant
   try {
@@ -46,8 +94,7 @@ export function relevantParamKeys(part, view, params) {
 // analysis failure (caller then treats every param as relevant — safe, just slower).
 export function subPartReadKeys(part, view, params) {
   try {
-    const deriveInputs = new Set();
-    const derived = part.derive ? (part.derive(recorder(params, deriveInputs)) ?? {}) : {};
+    const { derived, allInputs, depsOf } = analyzeDerive(part, params);
     const { kernel } = createProbeKernel();
     const map = new Map();
     for (const name of viewSubParts(part, view, params)) {
@@ -55,8 +102,20 @@ export function subPartReadKeys(part, view, params) {
       const reads = new Set();
       const dSeen = new Set();
       if (sp.enabled) sp.enabled(recorder(params, reads)); // gate params change presence too
-      sp.build(kernel, recorder(params, reads), recorder(derived, dSeen));
-      if (dSeen.size > 0) for (const k of deriveInputs) reads.add(k);
+      const built = sp.build(kernel, recorder(params, reads), recorder(derived, dSeen));
+      // place() shapes what's on screen too (display pose is baked into the cached
+      // mesh), so its reads count — without this, a param consumed only by place()
+      // would let the mesh cache skip a rebuild and leave the sub-part misplaced.
+      if (sp.place) sp.place(built, { view, purpose: "display", p: recorder(params, reads), d: recorder(derived, dSeen) });
+      if (dSeen.size > 0) {
+        if (depsOf && [...dSeen].every((k) => depsOf.has(k))) {
+          for (const k of dSeen) for (const dep of depsOf.get(k)) reads.add(dep);
+        } else {
+          // single-function derive, or a derived key no group produced: no
+          // attribution possible — fold every derive input in (safe, coarser).
+          for (const dep of allInputs) reads.add(dep);
+        }
+      }
       map.set(name, reads);
     }
     return map;

package/src/parts/planter.js

@@ -109,12 +109,14 @@ export default {
   views: { planter: { label: "Planter" } },
   // Self-verification (see docs/AUTHORING-PARTS.md "Self-verification"): opt into the
   // FDM-PLA process profile (bed-fit gate + min-wall warning) and pin the design intent
-  // — one drainage hole through the base, fits the bed, no interpenetration.
+  // — fits the bed, no interpenetration, and the RIGHT genus per case: verify runs
+  // across every preset, and "Pen cup"/"Vase" turn the drain off, so `expect` is a
+  // function of the case's params rather than one static hole count.
   verify: {
     process: "fdm-pla",
-    expect: {
-      planter: { holes: 1 /* drain=8 at defaults → 1 hole; adjust if running verify with a non-default drain */, bbox: "<=[220,220,250]" },
+    expect: (p) => ({
+      planter: { holes: p.drain > 0 ? 1 : 0, bbox: "<=[220,220,250]" },
       _view: { overlaps: 0 } /* _view = whole-model composite (not a named part) */,
-    },
+    }),
   },
 };

package/src/testing/bvh.js

@@ -2,8 +2,9 @@
 // Triangle BVH over a mesh in either Manifold non-indexed soup form (9 floats per
 // triangle, no `indices`) or OCCT indexed form (`positions` = 3 floats/vertex +
 // `indices` = 3 vertex-indices/triangle). A reusable spatial index: nearest ray hit
-// (raycast) and nearest surface point (closestPoint, added alongside). AABB tree,
-// median split on the widest centroid axis, slab ray–box test with pruning.
+// (raycast), nearest surface point (closestPoint), and exact mesh-to-mesh distance
+// (distanceTo). AABB tree, median split on the widest centroid axis, slab ray–box
+// test with pruning.
 
 const LEAF = 4; // max triangles per leaf
 
@@ -104,6 +105,82 @@ function distSqBox(p, min, max) {
   return s;
 }
 
+// summed extent of a node's AABB — the "which node is larger" heuristic for dual traversal
+const nodeExtent = (n) => (n.max[0] - n.min[0]) + (n.max[1] - n.min[1]) + (n.max[2] - n.min[2]);
+
+// squared distance between two AABBs (0 when they overlap)
+function boxBoxDistSq(a, b) {
+  let s = 0;
+  for (let ax = 0; ax < 3; ax++) {
+    const v = a.min[ax] > b.max[ax] ? a.min[ax] - b.max[ax] : b.min[ax] > a.max[ax] ? b.min[ax] - a.max[ax] : 0;
+    s += v * v;
+  }
+  return s;
+}
+
+// closest points between segments P1→Q1 and P2→Q2 (Ericson 5.1.9), → { a, b, d2 }
+function closestSegSeg(P1, Q1, P2, Q2) {
+  const sub = (p, q) => [p[0] - q[0], p[1] - q[1], p[2] - q[2]];
+  const dot = (p, q) => p[0] * q[0] + p[1] * q[1] + p[2] * q[2];
+  const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+  const d1 = sub(Q1, P1), d2v = sub(Q2, P2), r = sub(P1, P2);
+  const a = dot(d1, d1), e = dot(d2v, d2v), f = dot(d2v, r);
+  const EPS = 1e-12;
+  let s, t;
+  if (a <= EPS && e <= EPS) { s = 0; t = 0; }
+  else if (a <= EPS) { s = 0; t = clamp01(f / e); }
+  else {
+    const c = dot(d1, r);
+    if (e <= EPS) { t = 0; s = clamp01(-c / a); }
+    else {
+      const b = dot(d1, d2v), denom = a * e - b * b;
+      s = denom !== 0 ? clamp01((b * f - c * e) / denom) : 0;
+      t = (b * s + f) / e;
+      if (t < 0) { t = 0; s = clamp01(-c / a); }
+      else if (t > 1) { t = 1; s = clamp01((b - c) / a); }
+    }
+  }
+  const A = [P1[0] + d1[0] * s, P1[1] + d1[1] * s, P1[2] + d1[2] * s];
+  const B = [P2[0] + d2v[0] * t, P2[1] + d2v[1] * t, P2[2] + d2v[2] * t];
+  const pq = sub(A, B);
+  return { a: A, b: B, d2: dot(pq, pq) };
+}
+
+// exact min distance between two triangles → { d2, a, b } (a on t1, b on t2).
+// Non-intersecting triangles realize their minimum at a vertex-face or edge-edge
+// feature pair; a piercing edge (interior×interior crossing) is caught first with
+// rayTri, since feature distances alone would miss it. rayTri's t is in units of
+// the unnormalized edge direction, so 0 < t <= 1 means the segment itself pierces;
+// parallel/grazing edges return Infinity and the coplanar cases fall to the
+// feature distances.
+function triTriDist(t1, t2) {
+  const edges = (t) => [[t.v0, t.v1], [t.v1, t.v2], [t.v2, t.v0]];
+  for (const [p, q] of edges(t1)) {
+    const d = [q[0] - p[0], q[1] - p[1], q[2] - p[2]];
+    const t = rayTri(p, d, t2, 0);
+    if (t <= 1) { const at = [p[0] + d[0] * t, p[1] + d[1] * t, p[2] + d[2] * t]; return { d2: 0, a: at, b: at }; }
+  }
+  for (const [p, q] of edges(t2)) {
+    const d = [q[0] - p[0], q[1] - p[1], q[2] - p[2]];
+    const t = rayTri(p, d, t1, 0);
+    if (t <= 1) { const at = [p[0] + d[0] * t, p[1] + d[1] * t, p[2] + d[2] * t]; return { d2: 0, a: at, b: at }; }
+  }
+  let best = { d2: Infinity, a: null, b: null };
+  for (const v of [t2.v0, t2.v1, t2.v2]) {
+    const r = closestOnTri(v, t1);
+    if (r.d2 < best.d2) best = { d2: r.d2, a: r.point, b: v };
+  }
+  for (const v of [t1.v0, t1.v1, t1.v2]) {
+    const r = closestOnTri(v, t2);
+    if (r.d2 < best.d2) best = { d2: r.d2, a: v, b: r.point };
+  }
+  for (const [p1, q1] of edges(t1)) for (const [p2, q2] of edges(t2)) {
+    const r = closestSegSeg(p1, q1, p2, q2);
+    if (r.d2 < best.d2) best = { d2: r.d2, a: r.a, b: r.b };
+  }
+  return best;
+}
+
 // Möller–Trumbore; returns t>tMin or Infinity
 function rayTri(o, d, tri, tMin) {
   const e1 = [tri.v1[0] - tri.v0[0], tri.v1[1] - tri.v0[1], tri.v1[2] - tri.v0[2]];
@@ -144,7 +221,6 @@ export function buildBVH(mesh) {
     return bestTri === -1 ? null : { t: best, tri: bestTri };
   }
 
-  // No production consumer yet — pre-built + tested as the reusable primitive for the deferred clearance/min-feature gate.
   function closestPoint(p) {
     let best2 = Infinity, bestPt = null, bestTri = -1;
     const stack = [root];
@@ -162,5 +238,36 @@ export function buildBVH(mesh) {
     return { point: bestPt, dist: Math.sqrt(best2), tri: bestTri };
   }
 
-  return { raycast, closestPoint };
+  // Exact minimum surface-to-surface distance to another buildBVH result.
+  // Dual traversal pruned by AABB–AABB distance; exact triangle–triangle
+  // distance at leaf pairs; early-exits at 0 (touching/intersecting).
+  function distanceTo(other) {
+    let best = { d2: Infinity, a: null, b: null };
+    const stack = [[root, other._root]];
+    while (stack.length && best.d2 > 0) {
+      const [na, nb] = stack.pop();
+      if (boxBoxDistSq(na, nb) >= best.d2) continue;
+      const aLeaf = !!na.tris, bLeaf = !!nb.tris;
+      if (aLeaf && bLeaf) {
+        for (const ta of na.tris) for (const tb of nb.tris) {
+          const r = triTriDist(ta, tb);
+          if (r.d2 < best.d2) best = r;
+        }
+      } else if (!aLeaf && (bLeaf || nodeExtent(na) >= nodeExtent(nb))) {
+        // descend the larger node; push the nearer child last so it pops first
+        const dl = boxBoxDistSq(na.left, nb), dr = boxBoxDistSq(na.right, nb);
+        if (dl < dr) stack.push([na.right, nb], [na.left, nb]);
+        else stack.push([na.left, nb], [na.right, nb]);
+      } else {
+        const dl = boxBoxDistSq(na, nb.left), dr = boxBoxDistSq(na, nb.right);
+        if (dl < dr) stack.push([na, nb.right], [na, nb.left]);
+        else stack.push([na, nb.left], [na, nb.right]);
+      }
+    }
+    if (best.a === null) return { distance: Infinity, at: null, pointA: null, pointB: null }; // empty mesh
+    const at = [(best.a[0] + best.b[0]) / 2, (best.a[1] + best.b[1]) / 2, (best.a[2] + best.b[2]) / 2];
+    return { distance: Math.sqrt(best.d2), at, pointA: best.a, pointB: best.b };
+  }
+
+  return { raycast, closestPoint, distanceTo, _root: root };
 }

package/src/testing/error-patterns.js

@@ -0,0 +1,78 @@
+// Shared parser + matcher for docs/ERROR-PATTERNS.md — the symptom-indexed
+// error→pattern library (issue #28). The parser here is the single source of
+// truth: the format lint (test/error-patterns.test.js) and the CLI crash-path
+// matcher (issue #27) both import it. Contract: partforge code that throws must
+// throw strings appearing verbatim, in a backtick literal AT THE START of some
+// entry's Symptom line — only a leading literal participates in matching, so
+// backticks used for prose mid-sentence never mis-attribute an unrelated crash.
+import { readFileSync } from "node:fs";
+
+// Single-pass, fence-aware parse: a heading inside a ``` / ~~~ fence is quoted
+// content, not structure. Each `## <id>` entry records the `# <section>` it sits
+// under; its body runs to the next h1/h2 heading. (Moved verbatim from the lint
+// test, then enriched with symptom/cause/fix extraction.)
+export function parsePatterns(md) {
+  const entries = [];
+  let section = null;
+  let entry = null;
+  let inFence = false;
+  for (const line of md.split("\n")) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      if (entry) entry.body += line + "\n";
+      continue;
+    }
+    if (!inFence) {
+      const h1 = line.match(/^# (.+)$/);
+      const h2 = line.match(/^## (.+)$/);
+      if (h1) { section = h1[1]; entry = null; continue; }
+      if (h2) { entry = { id: h2[1], section, body: "" }; entries.push(entry); continue; }
+    }
+    if (entry) entry.body += line + "\n";
+  }
+  const field = (body, label) => {
+    const i = body.indexOf(`- **${label}:**`);
+    return i < 0 ? null : body.slice(i).split("\n")[0].replace(`- **${label}:**`, "").trim();
+  };
+  return entries.map((e) => {
+    const symptom = field(e.body, "Symptom");
+    // Leading-literal convention: only a backtick literal at the very START of the
+    // Symptom text is a match literal (kept as a ≤1-element array for compatibility
+    // — tests and the matcher read symptomStrings). Mid-line backticks are prose.
+    const leading = symptom?.match(/^`([^`]+)`/);
+    return {
+      ...e,
+      symptom,
+      cause: field(e.body, "Cause"),
+      fix: field(e.body, "Fix"),
+      symptomStrings: leading ? [leading[1]] : [],
+    };
+  });
+}
+
+// Cached read of the live doc, resolved relative to this module so it works from
+// a consuming app's node_modules too. Any read/parse error → null (callers treat
+// that as "no patterns available", never an error).
+let cached;
+export function loadPatterns() {
+  if (cached !== undefined) return cached;
+  try {
+    cached = parsePatterns(readFileSync(new URL("../../docs/ERROR-PATTERNS.md", import.meta.url), "utf8"));
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+
+// Leading symptom literals ≥ 6 chars, longest match wins. Never throws.
+export function matchPattern(message, patterns = loadPatterns()) {
+  if (!patterns || typeof message !== "string") return null;
+  let best = null;
+  let bestLen = 5;
+  for (const p of patterns) {
+    for (const s of p.symptomStrings) {
+      if (s.length > bestLen && message.includes(s)) { best = p; bestLen = s.length; }
+    }
+  }
+  return best ? { id: best.id, fix: best.fix } : null;
+}

package/src/testing/gaps.js

@@ -0,0 +1,48 @@
+import { buildView } from "./build.js";
+import { buildBVH } from "./bvh.js";
+
+// A measured pair distance at or below this (mm) counts as touching — absorbs
+// posing float error while staying far below any real print clearance.
+export const CONTACT_EPS = 1e-3;
+
+// Default near-miss threshold (mm): pairs closer than this without touching are
+// the "did you mean these to touch?" signal.
+export const GAP_THRESHOLD = 0.5;
+
+// Canonical order-insensitive pair identity — the one rule for "the same pair"
+// shared by measure's overlap exclusion and verify's declared-pair matching.
+export const pairKey = (a, b) => [a, b].sort().join("×");
+
+// Minimum surface-to-surface distance for every sub-part pair of pre-built posed
+// meshes ([{ name, mesh }] — buildView output). Distance 0 = touching or
+// interpenetrating surfaces; callers filter. Pairs involving an empty mesh are
+// skipped (the watertight gate owns that failure). Pure mesh math — both backends.
+//   → [{ a, b, distance, at: [x,y,z] }]
+export function meshGaps(built) {
+  const hasTris = (m) => (m.indices ? m.indices.length > 0 : m.positions.length > 0);
+  const bvhs = built
+    .filter(({ mesh }) => hasTris(mesh))
+    .map(({ name, mesh }) => ({ name, bvh: buildBVH(mesh) }));
+  const out = [];
+  for (let i = 0; i < bvhs.length; i++) {
+    for (let j = i + 1; j < bvhs.length; j++) {
+      const { distance, at } = bvhs[i].bvh.distanceTo(bvhs[j].bvh);
+      out.push({ a: bvhs[i].name, b: bvhs[j].name, distance, at });
+    }
+  }
+  return out;
+}
+
+// Near-miss check for an assembled view — the complement of assemblyOverlaps:
+// sub-part pairs that *almost* touch (0 < distance < threshold mm) in the display
+// pose. Same posing path as assemblyOverlaps; no kernel booleans, so it runs on
+// Manifold and OCCT alike.
+//   → [{ a, b, distance, at }] (empty = no near misses)
+export function assemblyGaps(kernel, part, view, params = {}, { threshold = GAP_THRESHOLD } = {}) {
+  if (!(threshold > CONTACT_EPS)) {
+    throw new Error(`assemblyGaps: threshold must exceed CONTACT_EPS (${CONTACT_EPS} mm), got ${threshold}`);
+  }
+  const gaps = meshGaps(buildView(kernel, part, view, params));
+  kernel.cleanup?.(); // free the per-check WASM objects (meshes are JS-owned copies)
+  return gaps.filter((g) => g.distance > CONTACT_EPS && g.distance < threshold);
+}

package/src/testing/measure.js

@@ -1,5 +1,6 @@
 import { buildView } from "./build.js";
 import { assemblyOverlaps } from "../framework/assembly.js";
+import { meshGaps, pairKey, CONTACT_EPS, GAP_THRESHOLD } from "./gaps.js";
 import { bounds, meshArea } from "./mesh.js";
 import { minWall } from "./min-wall.js";
 
@@ -11,15 +12,17 @@ const unionBounds = (list) => list.reduce(
 
 // Headless geometric report for one view of a part (Manifold-only). Reads exact
 // solid facts (volume/genus/emptiness) and mesh facts (bbox/area/triangles), plus
-// the assembly overlap check. All solid facts are read BEFORE assemblyOverlaps,
+// the assembly overlap check plus pair gap distances (near misses are reported,
+// never folded into `ok`). All solid facts are read BEFORE assemblyOverlaps,
 // which frees the shared kernel's objects at its end.
-//   → { part, view, subparts[], aggregate, overlaps[], ok }
+//   → { part, view, subparts[], aggregate, overlaps[], gaps[], nearMisses[], ok }
 export function measure(kernel, part, view = Object.keys(part.views)[0], params = {}, opts = {}) {
   const built = buildView(kernel, part, view, params);
   const subBounds = [];
   const subparts = built.map(({ name, solid, mesh }) => {
     const b = bounds(mesh.positions);
     subBounds.push(b);
+    const mw = opts.minWall ? minWall(mesh) : null;
     return {
       name,
       bbox: size(b),
@@ -28,16 +31,29 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
       triangleCount: mesh.triangles,
       watertight: typeof solid.isEmpty === "function" ? !solid.isEmpty() : null,
       holes: typeof solid.genus === "function" ? solid.genus() : null,
-      minWall: opts.minWall ? (minWall(mesh)?.value ?? null) : null,
+      minWall: mw?.value ?? null,
+      minWallAt: mw?.location ?? null,
     };
   });
 
+  // Pair surface distances from the meshes already built — no kernel dependency,
+  // so this reads on OCCT too. nearMisses = the issue-#29 signal: pairs that
+  // *almost* touch; overlapping pairs are excluded by name (a fully-contained
+  // sub-part has surface distance > 0 but is the overlap gate's business).
+  const gaps = built.length > 1 ? meshGaps(built) : [];
+
   // Rebuilds with the same kernel and cleans up at its end — every solid fact
   // above is already read, so this is safe.
   const canIntersect = built.length > 0 && typeof built[0].solid.intersect === "function";
   const overlaps = canIntersect ? assemblyOverlaps(kernel, part, view, params) : [];
   kernel.cleanup?.();
 
+  const overlapping = new Set(overlaps.map((o) => pairKey(o.a, o.b)));
+  const gapThreshold = opts.gapThreshold ?? GAP_THRESHOLD;
+  const nearMisses = gaps.filter(
+    (g) => g.distance > CONTACT_EPS && g.distance < gapThreshold && !overlapping.has(pairKey(g.a, g.b)),
+  );
+
   const aggregate = {
     bbox: subparts.length ? size(unionBounds(subBounds)) : [0, 0, 0],
     volume: subparts.reduce((a, s) => a + s.volume, 0),
@@ -50,6 +66,8 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
     subparts,
     aggregate,
     overlaps,
+    gaps,
+    nearMisses,
     ok: subparts.every((s) => s.watertight !== false) && overlaps.length === 0,
   };
 }