partforge 0.158.1 → 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.158.1",
+  "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/mount-preview.js

@@ -23,6 +23,13 @@
 // it, so a parked preview is a paused one. `handle.animation` is null once
 // disposed.
 //
+// A playing animation also gets a play/pause/replay button in #viewbar,
+// directly before the view style button (preview-play-button.js): Pause while
+// it plays (or tweens to its intro view), Play while paused, Replay once a
+// one-time animation has finished. No button under reduced motion, for a still
+// file, with `animate: false`, or for a host with no #viewbar; the host can
+// still drive `handle.animation` (state / pause / resume / replay) itself.
+//
 // The decoder loads on demand (it carries the
 // GLTFLoader and meshopt), so a bundle that never mounts a preview never ships it.
 // Hence `ready`. Every handle method is safe before it resolves.
@@ -36,6 +43,7 @@ import { createTooltipPresenter } from "./tooltip.js";
 import { isFaceAlignedState } from "./projection.js";
 import { ENVIRONMENTS } from "./materials/environments.js";
 import { createPreviewPlayer } from "./preview-player.js";
+import { attachPreviewPlayButton } from "./preview-play-button.js";
 
 function previewPart({ meshes, view, meta }) {
   return {
@@ -112,6 +120,10 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
       const own = player;
       cleanups.push(() => own.dispose());
       player.start();
+      if (!reducedMotion && toolbar) {
+        const playButton = attachPreviewPlayButton(own, { toolbar, before: viewStyle.element }, { tooltip });
+        cleanups.push(() => playButton.detach());
+      }
     }
   });
   ready.catch(() => {}); // the host awaits it; never an unhandled rejection
@@ -151,7 +163,7 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
     getView: () => live?.view ?? null,
     // null before ready, for a still file, with animate: false, and once disposed.
     get animation() {
-      return player ? { state: player.state, pause: player.pause, resume: player.resume } : null;
+      return player ? { state: player.state, pause: player.pause, resume: player.resume, replay: player.replay } : null;
     },
     getViewerState,
     setViewerState(next) {

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/src/framework/preview-play-button.js

@@ -0,0 +1,76 @@
+// The preview's play/pause/replay button (mount-preview.js): lets a visitor stop
+// a cached preview's baked autoplay animation while they read the page. A plain
+// `#viewbar button`, inserted directly before the view style button (#view-style,
+// after its divider), so it inherits the toolbar's sizing and hover styles.
+//
+// Three states, read off the player's onChange notifications (never polled):
+//   - Pause  while playing or during the intro camera tween;
+//   - Play   while paused — resumes from the pose it froze at;
+//   - Replay once a one-time animation has finished at its end pose — plays it
+//            again from the start, camera cues included. A looping animation
+//            never gets here.
+// The label (aria-label, and the tooltip, which reads it each time it shows)
+// names what a click does and so carries the state; there is deliberately no
+// aria-pressed (WAI-ARIA: a toggle whose label changes must not also report a
+// pressed state). A label change hides a tooltip that is showing, so it never
+// reads the old action; it comes back with the new text on the next hover.
+//
+// Made only for a player that plays: mount-preview never creates it under
+// reduced motion (the player never starts), for a still file, with
+// animate: false, or for a host with no #viewbar. Nothing is remembered: a
+// remount starts fresh.
+import { attachButtonTooltips } from "./tooltip.js";
+
+const svg = (body) => `<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+// lucide "pause", "play" and "rotate-ccw".
+const STATES = {
+  pause: { label: "Pause animation", icon: svg(`<rect x="14" y="4" width="4" height="16" rx="1"/><rect x="6" y="4" width="4" height="16" rx="1"/>`) },
+  play: { label: "Play animation", icon: svg(`<polygon points="6 3 20 12 6 21 6 3"/>`) },
+  replay: { label: "Replay animation", icon: svg(`<path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/>`) },
+};
+
+// What a click does for a given player status.
+const actionFor = (status) => (status === "paused" ? "play" : status === "done" ? "replay" : "pause");
+
+export function attachPreviewPlayButton(player, { toolbar, before = null }, { tooltip = null } = {}) {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.id = "pf-preview-play";
+  button.className = "pf-preview-play-button";
+  let action = null;
+  let tooltipBinding = null;
+
+  function render(status) {
+    const next = actionFor(status);
+    if (next === action) return;
+    action = next;
+    const { label, icon } = STATES[next];
+    button.innerHTML = icon;
+    button.setAttribute("aria-label", label);
+    if (!tooltip) button.title = label;
+    tooltipBinding?.hide(); // a showing tooltip still names the old action
+  }
+  render(player.state().status);
+
+  const anchor = before && before.parentElement === toolbar ? before : [...toolbar.children].find((c) => c.id === "theme") ?? null;
+  toolbar.insertBefore(button, anchor);
+  tooltipBinding = tooltip ? attachButtonTooltips(tooltip, [{ element: button }]) : null;
+
+  const onClick = () => {
+    if (action === "pause") player.pause();
+    else if (action === "play") player.resume();
+    else player.replay();
+  };
+  button.addEventListener("click", onClick);
+  const off = player.onChange((s) => render(s.status));
+
+  return {
+    element: button,
+    detach() {
+      off();
+      button.removeEventListener("click", onClick);
+      tooltipBinding?.detach();
+      button.remove();
+    },
+  };
+}

package/src/framework/preview-player.js

@@ -18,6 +18,14 @@
 //    opacity, no ground hold, no cue — so the visitor sees exactly what the
 //    file draws without a player (the opening pose, every sub-part opaque; an
 //    opacity fade-in must not leave a sub-part hidden for good).
+//
+// A host can pause, resume and — once a one-time animation has finished —
+// replay it (the preview's play/pause button, preview-play-button.js). Pause
+// stops any camera move where it is (viewer.cancelCameraTween, as the live
+// driver does): a cancelled tween never fires its onComplete, and createPlayback
+// re-honors an abandoned intro or sweep on the next play(). An orbit while
+// paused stays paused. onChange(cb) reports every status change, so a control
+// never polls.
 import { createPlayback } from "./animation.js";
 import { invertRigid, mulMat4 } from "./geometry/pose.js";
 
@@ -99,6 +107,21 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
   const restInverse = Object.fromEntries(Object.keys(tracks).map((name) => [name, invertRigid(rest[name])]));
 
   let offFrame = null, offOrbit = null, started = false, disposed = false;
+  const listeners = new Set();
+  let lastStatus = playback.state().status;
+
+  function snapshotState() {
+    const { status, t } = playback.state();
+    return { status, t };
+  }
+  function notify() {
+    const now = snapshotState();
+    if (now.status === lastStatus) return;
+    lastStatus = now.status;
+    for (const cb of [...listeners]) {
+      try { cb(now); } catch (error) { console.warn("partforge: preview animation listener failed", error); }
+    }
+  }
 
   function apply(t) {
     const seconds = t * duration;
@@ -111,7 +134,7 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
     if (snap.status !== "intro" || !snap.cue) return;
     viewer.tweenCameraTo(snap.cue.view, {
       duration: INTRO_TWEEN_SECONDS,
-      onComplete: () => { if (!disposed) playback.introDone(); },
+      onComplete: () => { if (!disposed) { playback.introDone(); notify(); } },
     });
   }
 
@@ -120,11 +143,12 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
     if (!snap) return; // not playing: intro, paused, or done — the last poses stand
     apply(snap.t);
     if (snap.cue) viewer.tweenCameraTo(snap.cue.view, { duration: snap.cue.sweep ?? INTRO_TWEEN_SECONDS });
+    notify();
   }
 
   function onOrbit() {
     playback.disarmCues();
-    if (playback.state().status === "intro") playback.introDone();
+    if (playback.state().status === "intro") { playback.introDone(); notify(); }
   }
 
   return {
@@ -137,25 +161,44 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
       offFrame = viewer.onFrame(onFrame);
       offOrbit = viewer.onCameraStart(onOrbit);
       honorIntro(playback.play());
+      notify();
     },
     pause() {
-      if (!disposed) playback.pause();
+      if (disposed || !offFrame) return;
+      const { status } = playback.state();
+      if (status !== "playing" && status !== "intro") return;
+      viewer.cancelCameraTween(); // an intro tween or a cue's sweep stops where it is
+      playback.pause();
+      notify();
     },
     resume() {
       if (disposed || playback.state().status !== "paused") return;
       honorIntro(playback.play());
+      notify();
+    },
+    // From `done` only (a one-time animation resting at its end pose): play it
+    // again exactly as on arrival — t = 0 pose and opacity first, then the
+    // re-armed intro cue (createPlayback's play() from done resets t and cues).
+    replay() {
+      if (disposed || playback.state().status !== "done") return;
+      apply(0);
+      honorIntro(playback.play());
+      notify();
+    },
+    onChange(cb) {
+      if (disposed) return () => {};
+      listeners.add(cb);
+      return () => listeners.delete(cb);
     },
     dispose() {
       if (disposed) return;
       disposed = true;
+      listeners.clear();
       if (!offFrame) return; // never played (not started, or reduced motion): nothing to undo
       offFrame(); offOrbit();
       offFrame = offOrbit = null;
       viewer.holdGround(false);
     },
-    state() {
-      const { status, t } = playback.state();
-      return { status, t };
-    },
+    state: snapshotState,
   };
 }

package/types/index.d.ts

@@ -809,6 +809,8 @@ export interface PreviewRuntime {
     state(): { status: "idle" | "intro" | "playing" | "paused" | "done"; t: number };
     pause(): void;
     resume(): void;
+    /** Play a finished one-time animation again from the start (its camera cues included); a no-op unless `state().status` is `"done"`. */
+    replay(): void;
   } | null;
   renderMode: {
     get(): RenderMode;

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. */