partforge 0.9.0 → 0.11.0

package/bin/cli.js

@@ -150,6 +150,9 @@ function printMeasure(r) {
   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) {

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).
@@ -458,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);
 ```
 
@@ -498,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
@@ -531,13 +586,17 @@ carries:
 - `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.
+  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 }`.
+`{ 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:
@@ -582,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
   },
 }
 ```
@@ -591,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
@@ -604,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
@@ -645,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]);

package/docs/ERROR-PATTERNS.md

@@ -73,6 +73,12 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 - **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.
@@ -91,6 +97,18 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 - **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.9.0",
+  "version": "0.11.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",
@@ -25,7 +25,9 @@
     ".": "./src/index.js",
     "./worker": "./src/framework/worker.js",
     "./geometry": "./src/framework/geometry/polygon.js",
-    "./testing": "./src/testing.js"
+    "./derive": "./src/framework/derive.js",
+    "./testing": "./src/testing.js",
+    "./tokens.css": "./src/framework/tokens.css"
   },
   "bin": {
     "partforge": "./bin/cli.js"

package/src/framework/app.css

@@ -2,22 +2,8 @@
    busy overlay) + the light/dark palettes. Imported by framework/mount.js, so
    every part-app gets it; each part's HTML only carries structural markup.
    See docs/AUTHORING-PARTS.md. */
+@import "./tokens.css"; /* palette + light overrides; also exported standalone as partforge/tokens.css */
 
-:root {
-  color-scheme: dark;
-  --bg: #15181d; --surface: #1f242c; --surface-2: #20262e; --border: #2c333d;
-  --text: #d6dbe2; --text-strong: #e7ebf1; --text-2: #cdd4dd;
-  --muted: #7d8794; --muted-2: #aab2bd; --status: #8b94a0; --hint: #6b7480;
-  --accent: #3f7bf0; --accent-soft: #26314a; --on-accent: #fff; --input-bg: #161a20; --err: #f8746c;
-  --mono: ui-monospace, "SF Mono", SFMono-Regular, "JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace;
-}
-:root[data-theme="light"] {
-  color-scheme: light;
-  --bg: #eef1f5; --surface: #ffffff; --surface-2: #f4f6f9; --border: #d4dae2;
-  --text: #2b333d; --text-strong: #1a2129; --text-2: #3a434e;
-  --muted: #6b7480; --muted-2: #59636f; --status: #6b7480; --hint: #8a93a0;
-  --accent: #1f5bd6; --accent-soft: #e6edfc; --on-accent: #fff; --input-bg: #ffffff; --err: #d8453d;
-}
 * { box-sizing: border-box; }
 html, body { margin: 0; height: 100%; overflow: hidden;
   font: 13px/1.4 -apple-system, system-ui, sans-serif; }

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/framework/tokens.css

@@ -0,0 +1,18 @@
+/* partforge design tokens — the light/dark palette. Imported by app.css (so every
+   part-app gets it via mount) and exported as "partforge/tokens.css" for other
+   consumers (e.g. partforge-cloud's app chrome) to share one source of truth. */
+:root {
+  color-scheme: dark;
+  --bg: #15181d; --surface: #1f242c; --surface-2: #20262e; --border: #2c333d;
+  --text: #d6dbe2; --text-strong: #e7ebf1; --text-2: #cdd4dd;
+  --muted: #7d8794; --muted-2: #aab2bd; --status: #8b94a0; --hint: #6b7480;
+  --accent: #3f7bf0; --accent-soft: #26314a; --on-accent: #fff; --input-bg: #161a20; --err: #f8746c;
+  --mono: ui-monospace, "SF Mono", SFMono-Regular, "JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace;
+}
+:root[data-theme="light"] {
+  color-scheme: light;
+  --bg: #eef1f5; --surface: #ffffff; --surface-2: #f4f6f9; --border: #d4dae2;
+  --text: #2b333d; --text-strong: #1a2129; --text-2: #3a434e;
+  --muted: #6b7480; --muted-2: #59636f; --status: #6b7480; --hint: #8a93a0;
+  --accent: #1f5bd6; --accent-soft: #e6edfc; --on-accent: #fff; --input-bg: #ffffff; --err: #d8453d;
+}

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/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,9 +12,10 @@ 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 = [];
@@ -34,12 +36,24 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
     };
   });
 
+  // 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),
@@ -52,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,
   };
 }

package/src/testing/verify.js

@@ -1,8 +1,10 @@
 import { parseAssertion, evaluateAssertion } from "./assert-dsl.js";
 import { measure as defaultMeasure } from "./measure.js";
+import { pairKey, CONTACT_EPS } from "./gaps.js";
 import { resolveProfile } from "./dfm-profiles.js";
 import { expandCases } from "./cases.js";
 import { subPartReadKeys, relevanceHash, RELEVANT_ALL } from "../framework/param-deps.js";
+import { resolveParams } from "../framework/jobs.js";
 
 // Metric registry: name → how to pull the value out of facts, whether a failure
 // is a hard gate or a warning, and the diagnostics attached to a non-pass check:
@@ -44,6 +46,98 @@ const normalizeExpectation = (spec) =>
     ? { expr: spec.expr, hint: spec.hint }
     : { expr: spec, hint: undefined };
 
+const PAIR_HINTS = {
+  contact: "the pair should touch but doesn't — grow the joining feature or move the mating datum so the faces meet",
+  clearance: "the pair's free-fit gap is out of the declared range — adjust the mating dimensions or the declared clearance",
+  nearMiss: "sub-parts nearly touch here — if they should meet, declare the pair in verify.expect._view.contacts and close the gap; if a free fit is intended, declare it under clearance",
+};
+
+// Pair-wise view checks: `contacts` (must touch), `clearance` (assertion DSL vs
+// the measured pair distance), and warnings for undeclared near misses. These are
+// per-pair, so they live outside the scalar VIEW_METRICS registry but emit the
+// same structured check objects.
+function pairGapChecks(facts, { contacts, clearance }, subPartNames) {
+  const checks = [];
+  const declared = new Set();
+  const names = new Set(facts.subparts.map((s) => s.name));
+  // The part's full sub-part vocabulary (when the caller knows it): a declared
+  // name absent from THIS case's facts but present in the part is an
+  // enabled()-gated sub-part that is off for this case → skip, don't throw.
+  // A name in neither set is a typo → throw. Without the vocabulary (bare
+  // evaluateCase callers) the case's own names are the vocabulary.
+  const known = subPartNames ? new Set(subPartNames) : names;
+  const requirePair = (a, b, what) => {
+    if (a === b) throw new Error(`${what}: a pair must name two different sub-parts, got ["${a}", "${b}"]`);
+    let absent = false;
+    for (const n of [a, b]) {
+      if (names.has(n)) continue;
+      if (!known.has(n)) throw new Error(`${what}: unknown sub-part "${n}" (view has: ${[...names].join(", ")})`);
+      absent = true;
+    }
+    return absent; // true = valid pair, but a sub-part is disabled in this case
+  };
+  const gapFor = (a, b) => facts.gaps?.find((g) => pairKey(g.a, g.b) === pairKey(a, b));
+  const disabledSkip = (base) => ({ ...base, actual: null, status: "skip", pass: null, message: "sub-part disabled in this case" });
+  // No gap table at all = legacy facts → skip. A table that MERELY LACKS the pair
+  // = the sub-part built empty (meshGaps skips empty meshes) → a declared gate
+  // must fail loudly, not skip, or verify.ok would vouch for an unverified pair.
+  const noReading = (base) => (facts.gaps
+    ? { ...base, actual: null, status: "fail", pass: false,
+        message: "no measured distance for the pair",
+        hint: "one sub-part produced no mesh (an empty solid?) — fix the build before trusting this gate" }
+    : { ...base, actual: null, status: "skip", pass: null, message: "unavailable" });
+
+  if (contacts != null && !Array.isArray(contacts)) {
+    throw new Error(`contacts: must be an array of ["a", "b"] pairs, got ${JSON.stringify(contacts)}`);
+  }
+  for (const pair of contacts ?? []) {
+    if (!Array.isArray(pair) || pair.length !== 2) {
+      throw new Error(`contacts: each entry must be an ["a", "b"] pair, got ${JSON.stringify(pair)}`);
+    }
+    const [a, b] = pair;
+    const disabled = requirePair(a, b, "contacts");
+    declared.add(pairKey(a, b));
+    const base = { scope: "view", subpart: `${a}×${b}`, metric: "contact", kind: "gate", expr: "touching" };
+    if (disabled) { checks.push(disabledSkip(base)); continue; }
+    const g = gapFor(a, b);
+    if (!g) { checks.push(noReading(base)); continue; }
+    const overlapping = (facts.overlaps ?? []).some((o) => pairKey(o.a, o.b) === pairKey(a, b));
+    if (overlapping || g.distance <= CONTACT_EPS) {
+      checks.push({ ...base, actual: g.distance, status: "pass", pass: true, message: overlapping ? "in contact (overlapping)" : "in contact" });
+    } else {
+      checks.push({ ...base, actual: g.distance, status: "fail", pass: false,
+        message: `${g.distance.toFixed(3)}mm apart, expected touching`,
+        hint: PAIR_HINTS.contact, pattern: "near-miss-gap", location: g.at });
+    }
+  }
+
+  for (const [key, spec] of Object.entries(clearance ?? {})) {
+    const pair = key.split("×").map((s) => s.trim());
+    if (pair.length !== 2 || !pair[0] || !pair[1]) throw new Error(`clearance: pair key must be "a×b", got "${key}"`);
+    const [a, b] = pair;
+    const disabled = requirePair(a, b, "clearance");
+    declared.add(pairKey(a, b));
+    const { expr, hint: partHint } = normalizeExpectation(spec);
+    const base = { scope: "view", subpart: `${a}×${b}`, metric: "clearance", kind: "gate", expr: String(expr) };
+    if (disabled) { checks.push(disabledSkip(base)); continue; }
+    const g = gapFor(a, b);
+    if (!g) { checks.push(noReading(base)); continue; }
+    const { pass, message } = evaluateAssertion(parseAssertion(expr), g.distance);
+    const out = { ...base, actual: g.distance, status: pass ? "pass" : "fail", pass, message };
+    if (!pass) { out.hint = partHint ?? PAIR_HINTS.clearance; out.pattern = "near-miss-gap"; out.location = g.at; }
+    checks.push(out);
+  }
+
+  for (const g of facts.nearMisses ?? []) {
+    if (declared.has(pairKey(g.a, g.b))) continue;
+    checks.push({ scope: "view", subpart: `${g.a}×${g.b}`, metric: "nearMiss", kind: "warn",
+      expr: "intent undeclared", actual: g.distance, status: "warn", pass: false,
+      message: `${g.distance.toFixed(3)}mm gap`, hint: PAIR_HINTS.nearMiss,
+      pattern: "near-miss-gap", location: g.at });
+  }
+  return checks;
+}
+
 function check(scope, subpart, metric, spec, registry, factsObj) {
   const reg = registry[metric];
   if (!reg) throw new Error(`unknown ${scope} metric "${metric}"${subpart ? ` on sub-part "${subpart}"` : ""}`);
@@ -71,13 +165,17 @@ function check(scope, subpart, metric, spec, registry, factsObj) {
 }
 
 // Pure policy: profile rules + per-part expect → checks for one case's facts.
-export function evaluateCase(facts, { profile, expect }) {
+export function evaluateCase(facts, { profile, expect, subPartNames }) {
   const checks = [];
+  // contacts/clearance are per-pair, not scalar view metrics — peel them off
+  // before the registry loop and hand them to pairGapChecks.
+  const { contacts, clearance, ...viewScalarExp } = expect?._view ?? {};
   const viewExp = {
     ...(profile?.bed ? { bbox: `<=[${profile.bed.join(",")}]` } : {}),
-    ...(expect?._view ?? {}),
+    ...viewScalarExp,
   };
   for (const [metric, expr] of Object.entries(viewExp)) checks.push(check("view", null, metric, expr, VIEW_METRICS, facts));
+  checks.push(...pairGapChecks(facts, { contacts, clearance }, subPartNames));
 
   for (const s of facts.subparts) {
     const merged = {
@@ -93,11 +191,22 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
   view = view ?? Object.keys(part.views)[0];
   const profileSpec = process ?? part.verify?.process;
   const profile = profileSpec ? resolveProfile(profileSpec) : null;
-  const expect = part.verify?.expect ?? {};
-  const expectMentionsMinWall = Object.values(expect).some((o) => o && typeof o === "object" && "minWall" in o);
-  const needMinWall = profile?.minWall != null || expectMentionsMinWall;
+  const expectSpec = part.verify?.expect ?? {};
 
   const cases = expandCases(part);
+  // `expect` can be a pure function of the case's resolved params — (p, d) →
+  // expect object — so topology that legitimately changes with a preset (an
+  // optional drain or bore flipping the genus) can be pinned per case instead
+  // of one static number that some presets must violate.
+  const resolveExpect = (params) => {
+    if (typeof expectSpec !== "function") return expectSpec;
+    const { p, d } = resolveParams(part, params);
+    return expectSpec(p, d) ?? {};
+  };
+  const expanded = cases.map((c) => ({ ...c, expect: resolveExpect(c.params) }));
+  const expectMentionsMinWall = expanded.some(({ expect }) =>
+    Object.values(expect).some((o) => o && typeof o === "object" && "minWall" in o));
+  const needMinWall = profile?.minWall != null || expectMentionsMinWall;
   const readKeys = subPartReadKeys(part, view, part.defaults);
   const signature = (params) =>
     readKeys === RELEVANT_ALL
@@ -111,7 +220,8 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
     return memo.get(key);
   };
 
-  const caseResults = cases.map(({ name, params }) => ({ name, params, checks: evaluateCase(measureCase(params), { profile, expect }) }));
+  const subPartNames = Object.keys(part.parts);
+  const caseResults = expanded.map(({ name, params, expect }) => ({ name, params, checks: evaluateCase(measureCase(params), { profile, expect, subPartNames }) }));
   const all = caseResults.flatMap((c) => c.checks.map((ch) => ({ case: c.name, ...ch })));
   return {
     ok: !all.some((c) => c.status === "fail"),

package/src/testing.js

@@ -4,7 +4,10 @@
 export { createManifoldKernel } from "./framework/geometry/manifold-backend.js";
 export { bootManifoldKernel } from "./testing/manifold.js";
 export { handle, viewSubParts } from "./framework/jobs.js";
+export { resolveDerived } from "./framework/derive.js";
+export { relevantParamKeys, RELEVANT_ALL } from "./framework/param-deps.js";
 export { assemblyOverlaps } from "./framework/assembly.js";
+export { assemblyGaps, meshGaps } from "./testing/gaps.js";
 export { bootOcctKernel } from "./testing/occt.js";
 export { meshVolume, bboxSize } from "./testing/mesh.js";
 export { buildView } from "./testing/build.js";