partforge 0.159.0 → 0.160.0

package/docs/AUTHORING-PARTS.md

@@ -3982,7 +3982,7 @@ runtime a throwing probe only degrades quietly to `{ error }`.
 `verify-bad-expr`, `verify-bad-pair-check`, `verify-unknown-process`,
 `verify-unknown-orientation`,
 `verify-expect-throws` (all errors). Note `_view` also accepts the pair-wise
-`contacts` / `clearance` keys, which are not scalar view metrics; they are
+`contacts` / `clearance` / `held` keys, which are not scalar view metrics; they are
 validated by `verify-bad-pair-check`, matching `verify.js`'s own handling.
 
 **Animations block** — static validation of each view's `animations` block,
@@ -4150,7 +4150,8 @@ carries:
   *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
+  the pair's closest surface points) and `held` (the first floating sub-part's
+  centre of mass). Whole-solid metrics (bbox, volume, …) have
   none.
 
 Subpart facts include `minWall` (number or `null` — null exactly when no reading
@@ -4268,7 +4269,7 @@ A part can declare how it should be checked, co-located with its schema, so
 ```js
 verify: {
   process: "fdm-pla",            // a DFM profile: fdm-pla | fdm-petg | resin, or an
-                                  // inline { bed:[x,y,z], minWall, clearance, overhang } object
+                                  // inline { base, bed:[x,y,z], minWall, overhang, fits, holeUndersize, bridge } object
   orientation: "print",          // optional; ONLY with this is overhang checked — it says the
                                   // part is laid out for its bed (Z up, bed at the lowest Z)
   cases: ["defaults", "M3"],     // optional; default = defaults + every preset
@@ -4276,7 +4277,8 @@ verify: {
     spacer: { holes: 1, bbox: "<=[60,60,60]", volume: "0.4..0.6cm3" },
     _view:  { overlaps: 0,
               contacts:  [["drum", "flange"]],       // these pairs must touch
-              clearance: { "lid×body": ">=0.3" } },  // intended free fits
+              clearance: { "lid×body": ">=0.3" },    // intended free fits
+              held: true },                          // every printed piece reaches the base
   },
 }
 ```
@@ -4303,7 +4305,30 @@ is why this is a warning and never a gate. Two more limits, stated: it is judged
 the DISPLAY pose, so a sub-part whose `assembly` pose stands it differently from how it prints (a lid that prints
 flat beside its base) is measured as displayed, and `exportable: false` sub-parts
 are skipped. Switch it off under an FDM profile with an inline
-`{ base: "fdm-pla", overhang: null }`. **What `expect` gives you:** per-sub-part
+`{ base: "fdm-pla", overhang: null }`.
+
+**What the profile tells you.** Three more fields carry the numbers a mating
+feature needs. Nothing checks them; they are the one place the value is spelled,
+so `derive()` copies it with a comment naming the fit (`// slip fit: fdm-pla 0.25`).
+`fits` are diametral offsets in mm, negative is interference; `holeUndersize` is
+added to a horizontal bore's diameter because a printed arch sags inward; `bridge`
+is the longest flat span the process prints unsupported (none on resin, which
+prints on supports). They are guide defaults, not measurements of your printer:
+an inline `{ base: "fdm-pla", fits: { … } }` replaces the whole table.
+
+| field | fdm-pla | fdm-petg | resin |
+| --- | --- | --- | --- |
+| `fits.press` — a pin that never comes out | -0.10 | -0.10 | -0.05 |
+| `fits.push` — pressed on by hand | 0.05 | 0.05 | 0.05 |
+| `fits.slip` — a lid that lifts off | 0.25 | 0.30 | 0.10 |
+| `fits.moving` — a hinge pin or axle | 0.35 | 0.40 | 0.15 |
+| `fits.printInPlace` — printed already assembled | 0.45 | 0.50 | 0.20 |
+| `holeUndersize` | 0.25 | 0.30 | 0.05 |
+| `bridge` (mm) | 10 | 10 | — |
+
+`fits` are diametral; the `clearance` expectation below reads a pair's minimum surface distance, so a pin in a bore is declared at half the fit (`fits.slip` 0.25 → `clearance: { "pin×body": "0.08..0.18" }`).
+
+**What `expect` gives you:** per-sub-part
 assertions on the facts `measure` already reports — `holes` (through-bores / genus),
 `volume`, `surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`,
 `overhangArea`, `wall` (a range — see below), `bounds` (the axis-aligned corner
@@ -4311,7 +4336,7 @@ positions, written in the same `{ min, max }` shape `measure` reports them — w
 the geometry sits, vs `bbox` which is only its size) and `centerOfMass` (`[x,y,z]`, the volume-weighted
 centroid; `null` for a degenerate/zero-volume sub-part); and `_view` assertions `bbox`,
 `volume`, `overlaps`, `centerOfMass`, `bounds`, plus the pair-wise
-`contacts` / `clearance` below.
+`contacts` / `clearance` and the graph check `held` below.
 
 Passing these checks does **not** prove structural strength, fatigue life, stability,
 manufacturing tolerance stack-up, regulatory compliance, or safe real-world use.
@@ -4444,6 +4469,22 @@ 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.
 
+**Held (the contact graph).** `contacts` asserts a pair you named; it cannot say a
+sub-part touches nothing at all — a lid placed a hair above its box, a bracket
+beside the wall it should bolt to. `held: true` builds a graph over every
+exportable sub-part in the view, joining two whenever they overlap or their gap
+is within the same ~1 µm `contacts` tolerates, and fails naming each sub-part not
+connected to the base — the lowest sub-part by its bounds, or the one you name
+with `held: "body"`. The location is the first floating sub-part's centre of
+mass. A reference ghost (`exportable: false`) is left out entirely: it neither
+counts nor holds, since it is never printed (lint refuses one named as the base).
+A named base that is `enabled()`-off
+in a case skips that case; a name that exists nowhere throws, like a `contacts`
+pair. It is an expectation, never a default, for the overhang reason: a part
+still being shaped should not be nagged. Topological only — a part balanced on a
+point passes — and the same OCCT caveat applies: a sub-part fully inside another
+reads as not touching there. A view with fewer than two printed sub-parts passes with nothing to hold. A pin or axle running in a clearance bore, or a print-in-place piece, touches nothing in the model and reads as floating: `held` is for assemblies whose pieces seat on each other, so leave it off when a piece is captured with running clearance (`fits.moving`, `fits.printInPlace`) and declare that pair's `clearance` instead. A quick lap answers it `unevaluated`.
+
 **Running it:**
 
 ```bash

package/docs/ERROR-PATTERNS.md

@@ -198,6 +198,12 @@ Variant literals under this entry: `extrude: unknown bevel option`, `extrude: be
 - **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)".
 
+## floating-subpart
+
+- **Symptom:** A `✗ … held` failure from `verify` reporting `<name> not connected to <base>`: a sub-part that looks assembled in the preview touches nothing that reaches the base.
+- **Cause:** The piece is placed by eye rather than against a mating datum — a lid a hair above its box, a bracket beside the wall it should bolt to, a pin whose bore it was never moved into — or it is held only by a reference ghost (`exportable: false`), which is never printed. On OCCT a sub-part fully inside another reads as not touching, since overlap detection is Manifold-only.
+- **Fix:** Seat the part on a mating face by deriving its position from the face it sits on in `derive()`, or add the fastener, boss or tab that holds it, then keep `verify.expect._view.held` so the next edit re-checks it. If the piece is meant to run free in a clearance bore (a hinge pin, a print-in-place link), the clearance is correct and `held` is the wrong check for that assembly — remove `held` and declare the pair 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.159.0",
+  "version": "0.160.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",

package/src/framework/lint/rules-verify.js

@@ -28,12 +28,13 @@ export function resolveExpect(verify, p, d) {
 const isExpectation = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "expr" in v;
 const exprOf = (v) => (isExpectation(v) ? v.expr : v);
 
-// `contacts` (must-touch pairs) and `clearance` (free-fit gaps) live under
-// `verify.expect._view` but are pair-wise checks, not scalar VIEW_METRICS — mirror
-// verify.js's own peel (verify.js:143) so they never hit the scalar-metric /
-// assertion-expression checks below. Validated for real by `verify-bad-pair-check`.
+// `contacts` (must-touch pairs), `clearance` (free-fit gaps) and `held` (the
+// contact graph) live under `verify.expect._view` but are pair-derived checks,
+// not scalar VIEW_METRICS — mirror verify.js's own peel (evaluateCase) so they
+// never hit the scalar-metric / assertion-expression checks below. Validated for
+// real by `verify-bad-pair-check`.
 const peelPairKeys = (metrics) => {
-  const { contacts, clearance, ...rest } = metrics;
+  const { contacts, clearance, held, ...rest } = metrics;
   return rest;
 };
 
@@ -124,6 +125,33 @@ function checkClearance(clearance, names, path) {
   return out;
 }
 
+// Static analogue of held.js: `true`, or the name of the sub-part the graph is
+// rooted at. Anything else throws at runtime, so it is an error here. A ghost
+// (`exportable: false`) is never printed, so it cannot be the base either — the
+// runtime would accept it and report a misleading skip.
+function checkHeld(held, parts, path) {
+  if (held === undefined || held === null || held === true) return [];
+  const names = Object.keys(parts);
+  if (typeof held === "string") {
+    if (names.includes(held)) {
+      if (parts[held]?.exportable !== false) return [];
+      return [err("verify-bad-pair-check",
+        `\`${path}\` names "${held}", which is exportable: false and never printed, so it cannot be the base`,
+        "Root the contact graph at a printed sub-part, or `held: true` for the lowest one.",
+        path)];
+    }
+    const hint = safeSuggest(held, names);
+    return [err("verify-unknown-subpart",
+      `\`${path}\` references "${held}", which is not a sub-part`,
+      `Use \`true\` (the lowest sub-part is the base) or one of the sub-part names (${names.join(", ")})${hint ? ` — did you mean "${hint}"?` : "."}`,
+      path)];
+  }
+  return [err("verify-bad-pair-check",
+    `\`${path}\` must be true or a sub-part name, got ${describe(held)}`,
+    "Set `held: true` to root the contact graph at the lowest sub-part, or `held: \"<name>\"` to root it at that sub-part.",
+    path)];
+}
+
 // `clearance`'s values genuinely are assertion expressions run through the DSL
 // (verify.js:96), unlike `contacts` (pair arrays with nothing to parse). Mirror
 // verify.js's own normalization — a bare value or an `{ expr, hint }` wrapper,
@@ -337,6 +365,7 @@ export const VERIFY_RULES = [
       return [
         ...checkContacts(view.contacts, names, "verify.expect._view.contacts"),
         ...checkClearance(view.clearance, names, "verify.expect._view.clearance"),
+        ...checkHeld(view.held, part?.parts ?? {}, "verify.expect._view.held"),
       ];
     },
   },

package/src/framework/oracle/dfm-profiles.js

@@ -5,10 +5,34 @@
 // (a warn, armed only by the part — see overhangAngleFor; resin prints on
 // supports, so it carries none); `clearance` mm is carried for a future gap check
 // (not enforced yet).
+//
+// `fits`, `holeUndersize` and `bridge` are the numbers an author (or the cloud
+// agent) copies into derive() for a mating feature; nothing in this repo reads
+// them yet. They are guide defaults from the FDM design guides, not measurements:
+// a calibrated printer overrides them through an inline `{ base, fits: {...} }`
+// profile, which REPLACES the fits table whole. `fits` are diametral offsets in
+// mm (negative = interference): press (a pin that never comes out), push (a cap
+// pressed on by hand), slip (a lid that lifts off), moving (a hinge pin or axle),
+// printInPlace (parts printed already assembled). `holeUndersize` is added to a
+// horizontal bore's diameter, since the top of a printed arch sags inward.
+// `bridge` is the longest flat span the process prints unsupported; resin prints
+// on supports, so it carries none.
 export const PROFILES = {
-  "fdm-pla": { bed: [220, 220, 250], minWall: 1.2, clearance: 0.2, overhang: 45 },
-  "fdm-petg": { bed: [220, 220, 250], minWall: 1.5, clearance: 0.3, overhang: 45 },
-  "resin": { bed: [120, 68, 160], minWall: 0.6, clearance: 0.1 },
+  "fdm-pla": {
+    bed: [220, 220, 250], minWall: 1.2, clearance: 0.2, overhang: 45,
+    fits: { press: -0.1, push: 0.05, slip: 0.25, moving: 0.35, printInPlace: 0.45 },
+    holeUndersize: 0.25, bridge: 10,
+  },
+  "fdm-petg": {
+    bed: [220, 220, 250], minWall: 1.5, clearance: 0.3, overhang: 45,
+    fits: { press: -0.1, push: 0.05, slip: 0.3, moving: 0.4, printInPlace: 0.5 },
+    holeUndersize: 0.3, bridge: 10,
+  },
+  "resin": {
+    bed: [120, 68, 160], minWall: 0.6, clearance: 0.1,
+    fits: { press: -0.05, push: 0.05, slip: 0.1, moving: 0.15, printInPlace: 0.2 },
+    holeUndersize: 0.05,
+  },
 };
 
 export function resolveProfile(spec) {

package/src/framework/oracle/held.js

@@ -0,0 +1,79 @@
+// `_view.held`: every exportable sub-part in the view must be connected, through
+// contact or overlap, to a base. A pair-derived check like `contacts` — it reads
+// the gap table and overlap list measure already computed and never touches a
+// mesh — so it lives beside pairGapChecks, outside the scalar VIEW_METRICS
+// registry, and emits the same structured check object.
+//
+// Topological only: a part balanced on a point passes. Load path and strength
+// are not this check's business (AUTHORING-PARTS.md, "Self-verification").
+import { CONTACT_EPS } from "./gaps.js";
+
+export const HELD_HINT = "sub-part touches nothing — seat it on a mating face or add the fastener that holds it";
+
+// `held` is `true` (base = the lowest sub-part by bounds.min z) or a sub-part
+// name. `subPartNames` is the part's whole vocabulary (so a base that is
+// enabled()-off in this case skips rather than throws); `exportableNames` bounds
+// the graph to printed sub-parts — a reference ghost neither counts nor holds.
+export function heldCheck(facts, held, { subPartNames, exportableNames } = {}) {
+  if (held === undefined || held === null) return null;
+  if (held !== true && typeof held !== "string") {
+    throw new Error(`held: must be true or a sub-part name, got ${JSON.stringify(held)}`);
+  }
+  const base = {
+    scope: "view", subpart: null, metric: "held", kind: "gate",
+    expr: held === true ? "connected" : `connected to ${held}`,
+  };
+  const inView = facts.subparts.map((s) => s.name);
+  const known = subPartNames ? new Set(subPartNames) : new Set(inView);
+  if (typeof held === "string" && !known.has(held)) {
+    throw new Error(`held: unknown sub-part "${held}" (view has: ${inView.join(", ")})`);
+  }
+  const printed = exportableNames ? new Set(exportableNames) : null;
+  const nodes = inView.filter((n) => !printed || printed.has(n));
+  if (typeof held === "string" && !nodes.includes(held)) {
+    return { ...base, actual: null, status: "skip", pass: null, message: "sub-part disabled in this case" };
+  }
+  if (nodes.length < 2) {
+    return { ...base, actual: 0, status: "pass", pass: true, message: `${nodes.length} sub-part, nothing to hold` };
+  }
+  // Same rule as pairGapChecks' noReading: a deliberately skipped pass (quick lap)
+  // is unevaluated; a legacy result with no table stays an untagged skip.
+  if (!facts.gaps) {
+    return facts.measuredGaps === false
+      ? { ...base, actual: null, status: "skip", pass: null, unevaluated: true,
+          message: "not measured (quick check)", hint: "re-run this check without `quick` to measure pair distances" }
+      : { ...base, actual: null, status: "skip", pass: null, message: "unavailable" };
+  }
+  const adj = new Map(nodes.map((n) => [n, new Set()]));
+  const join = (a, b) => {
+    if (!adj.has(a) || !adj.has(b)) return;
+    adj.get(a).add(b);
+    adj.get(b).add(a);
+  };
+  for (const o of facts.overlaps ?? []) join(o.a, o.b);
+  for (const g of facts.gaps) if (g.distance <= CONTACT_EPS) join(g.a, g.b);
+  const rowOf = (n) => facts.subparts.find((s) => s.name === n);
+  const zOf = (n) => rowOf(n)?.bounds?.min?.[2];
+  const root = held === true
+    ? nodes.reduce((best, n) => (zOf(n) != null && (zOf(best) == null || zOf(n) < zOf(best)) ? n : best), nodes[0])
+    : held;
+  const seen = new Set([root]);
+  const queue = [root];
+  while (queue.length) {
+    const n = queue.shift();
+    for (const m of adj.get(n)) if (!seen.has(m)) { seen.add(m); queue.push(m); }
+  }
+  const floating = nodes.filter((n) => !seen.has(n));
+  if (floating.length === 0) {
+    return { ...base, actual: 0, status: "pass", pass: true, message: `${nodes.length} sub-parts connected to ${root}` };
+  }
+  const first = rowOf(floating[0]);
+  const location = first?.centerOfMass
+    ?? (first?.bounds ? first.bounds.min.map((v, i) => (v + first.bounds.max[i]) / 2) : null);
+  return {
+    ...base, actual: floating.length, status: "fail", pass: false,
+    message: `${floating.join(", ")} not connected to ${root}`,
+    hint: HELD_HINT, pattern: "floating-subpart",
+    ...(location ? { location } : {}),
+  };
+}

package/src/framework/oracle/verify.js

@@ -1,6 +1,7 @@
 import { parseAssertion, evaluateAssertion } from "./assert-dsl.js";
 import { measure as defaultMeasure } from "./measure.js";
 import { pairKey, CONTACT_EPS } from "./gaps.js";
+import { heldCheck } from "./held.js";
 import { resolveProfile, overhangAngleFor } from "./dfm-profiles.js";
 import { expandExpectations, partGatesMinWall } from "./gates.js";
 import { relevanceHash } from "../param-deps.js";
@@ -270,11 +271,11 @@ function sheetRowChecks(s, declaredExp) {
 // `overhang` is the angle the part opted into (dfm-profiles.js overhangAngleFor),
 // or null/undefined: only then does the profile's overhang rule apply, as a
 // 1 mm² warning floor — a chamfer sitting exactly on the angle sheds slivers.
-export function evaluateCase(facts, { profile, expect, subPartNames, overhang = null }) {
+export function evaluateCase(facts, { profile, expect, subPartNames, exportableNames, overhang = null }) {
   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 ?? {};
+  // contacts/clearance/held are pair-derived, not scalar view metrics — peel
+  // them off before the registry loop. held.js explains the exportable bound.
+  const { contacts, clearance, held, ...viewScalarExp } = expect?._view ?? {};
   // No sheet part in the view: every line below runs exactly as it did before sheet
   // parts existed (test/verify-golden.test.js). With one, the bed moves from the view
   // to each printed sub-part — see the sheet-parts block above.
@@ -285,6 +286,8 @@ export function evaluateCase(facts, { profile, expect, subPartNames, overhang =
   };
   for (const [metric, expr] of Object.entries(viewExp)) checks.push(...checksFor("view", null, metric, expr, VIEW_METRICS, facts));
   checks.push(...pairGapChecks(facts, { contacts, clearance }, subPartNames));
+  const heldResult = heldCheck(facts, held, { subPartNames, exportableNames });
+  if (heldResult) checks.push(heldResult);
 
   // Same rule as gapsSkipped above, one metric over: a min-wall gate with no reading
   // is a warn ("min wall unavailable"), which does not move `ok` — right when the
@@ -437,6 +440,9 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
   };
 
   const subPartNames = Object.keys(part.parts);
+  // A reference ghost (`exportable: false`) is never printed, so it neither counts
+  // as held nor holds anything — the same exclusion measure applies to overhang.
+  const exportableNames = subPartNames.filter((n) => part.parts[n]?.exportable !== false);
   // An unmeasured case gets ONE check standing for the whole case rather than a
   // silent absence: "this preset was not checked" has to be visible in the same
   // list every other verdict lives in, or a reader counting passes sees a shorter
@@ -449,7 +455,7 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
   }];
   const caseResults = expanded.map(({ name, params, expect }) => {
     const facts = measureCase(params);
-    return { name, params, checks: facts ? evaluateCase(facts, { profile, expect, subPartNames, overhang: overhangAngle }) : notMeasured(name) };
+    return { name, params, checks: facts ? evaluateCase(facts, { profile, expect, subPartNames, exportableNames, overhang: overhangAngle }) : notMeasured(name) };
   });
   // VACUOUS VERIFY. A part that declares nothing — no profile, an empty or absent
   // `expect` — used to come back `ok: true` with zero checks, and every reader

package/types/part.d.ts

@@ -491,6 +491,17 @@ export interface DfmProfile {
   overhang?: number | null;
   /** Carried for a future gap check; not enforced yet. */
   clearance?: number;
+  /**
+   * Diametral fit offsets in mm, negative = interference: `press` (never comes
+   * out), `push` (pressed on by hand), `slip` (lifts off), `moving` (a pin or
+   * axle), `printInPlace` (printed assembled). Guide defaults; an inline profile
+   * replaces the whole table.
+   */
+  fits?: { press: number; push: number; slip: number; moving: number; printInPlace: number };
+  /** Added to a horizontal bore's diameter — a printed arch sags inward. */
+  holeUndersize?: number;
+  /** Longest flat span printed unsupported, mm. Absent on a process that prints on supports. */
+  bridge?: number;
   /** Inherit from a named profile and override the rest. */
   base?: DfmProfileName | DfmProfile;
 }
@@ -600,6 +611,11 @@ export interface ViewExpectations {
   contacts?: Array<[string, string]>;
   /** Intended free fits, keyed `"a×b"` (order-insensitive). */
   clearance?: Record<string, Expectation>;
+  /**
+   * Every exportable sub-part must be connected, through contact or overlap, to
+   * the base: the lowest sub-part (`true`) or the named one. Topological only.
+   */
+  held?: true | string;
 }
 
 /** `verify.expect`: sub-part names plus the reserved `_view` key. */