partforge 0.159.0 → 0.161.0

package/docs/AUTHORING-PARTS.md

@@ -310,10 +310,38 @@ Rules (all lint-enforced):
   left right`) or any view-cube orientation — an edge or corner named
   vertical, then depth, then side (`top-front-left`, `top-back-right`,
   `front-left`, `bottom-back-right`, …; `top-front-right` is `iso`). One
-  mechanism per animation: an animation-level name (an intro cue at t=0), an
-  animation-level `[[t, angle], …]` list, or per-step names.
+  mechanism per animation: an animation-level angle (an intro cue at t=0), an
+  animation-level `[[t, angle], …]` list, or per-step angles.
   Cues fire during play only — scrubbing never moves the camera — and a user
   orbit disarms the remaining cues for that run.
+- **Any angle in between is an orbit**: wherever a cue takes a name it also
+  takes `{ azimuth, elevation, distance }`, in degrees and in the part's own
+  frame. `azimuth` 0 looks from the front (−Y) and turns toward the right (+X)
+  at 90, the back at 180 and the left at −90; `elevation` is degrees above the
+  horizontal, −90..90. `iso` is `{ azimuth: 45, elevation: 35.26 }` and
+  `front-right` is `{ azimuth: 45, elevation: 0 }`, so "about half as far down
+  as level from iso" is `{ azimuth: 45, elevation: 17 }`. `distance` is
+  optional: a multiple of the distance a named angle frames the part from (1,
+  the default, is the same framing; 1.5 pulls back; 0.6 moves in), 0.1..10, so
+  it keeps meaning the same thing when params change the part's size. The
+  camera always aims at the part's centre — a cue orbits and zooms, it never
+  pans. Lint (`animation-camera-invalid`) names what is wrong with a malformed
+  orbit: a missing or non-numeric angle, an elevation past ±90, a distance out
+  of range, or an unknown key.
+
+  ```js
+  steps: [
+    { label: "Assembled", camera: "iso", duration: 0.8 },
+    { label: "Expand", camera: { azimuth: 45, elevation: 17, distance: 1.3 }, duration: 2.5,
+      tracks: { explode: [[0, 0], [1, 1]] } },
+  ]
+  ```
+
+  A host can turn the view the user has on screen into one of these with
+  `runtime.getCameraCue()` — `{ cue, panned }`, where `cue` is the orbit that
+  reproduces the current angle and distance and `panned` is how far the user's
+  orbit target sits from the part's centre (a fraction of the framing radius;
+  a pan is the one thing a cue cannot carry).
 - **A camera move takes as long as its cue asks**: a per-step `camera` sweeps
   across that step's whole `duration`, and a listed cue sweeps until the next
   cue (or the end). The move that settles the camera BEFORE playback starts —
@@ -3982,7 +4010,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 +4178,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 +4297,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 +4305,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 +4333,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 +4364,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 +4497,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.161.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/animation.js

@@ -69,12 +69,14 @@ export function normalizeAnimation(name, spec) {
   // params move — ignores it and uses the driver's short fixed tween, since it
   // gates playback and a long one would read as a stall.
   let cues;
-  // A lone angle name is only ever an intro, so it has no sweep of its own.
-  if (typeof spec.camera === "string") cues = [{ t: 0, view: spec.camera, sweep: null }];
-  else if (Array.isArray(spec.camera)) {
+  // A lone angle (a name, or an { azimuth, elevation } orbit) is only ever an
+  // intro, so it has no sweep of its own.
+  if (Array.isArray(spec.camera)) {
     cues = spec.camera.map(([t, view], i, all) => ({
       t, view, sweep: ((all[i + 1]?.[0] ?? 1) - t) * totalDuration,
     }));
+  } else if (spec.camera != null) {
+    cues = [{ t: 0, view: spec.camera, sweep: null }];
   } else {
     cues = steps.flatMap((s, i) => (s.camera ? [{ t: stepStarts[i], view: s.camera, sweep: s.duration }] : []));
   }

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

@@ -12,7 +12,7 @@
 // letting the author wonder why nothing plays.
 import { err, note } from "./finding.js";
 import { EASINGS } from "../animation.js";
-import { CANONICAL_VIEWS, CAMERA_CUE_VIEWS } from "../view-angles.js";
+import { CANONICAL_VIEWS, cameraOrbitProblem, isCameraCue } from "../view-angles.js";
 import { inView } from "../sub-part-views.js";
 import { probeSubPartPose } from "../pose-probe-core.js";
 import { resolveDerivedAttributed } from "../derive.js";
@@ -374,9 +374,14 @@ export const ANIMATION_RULES = [
     id: "animation-camera-invalid",
     run: ({ part }) => {
       const out = [];
-      const badName = (v) => typeof v !== "string" || !CAMERA_CUE_VIEWS.includes(v);
-      // The seven canonical names plus the view cube's corners and edges.
-      const angles = `${CANONICAL_VIEWS.join(", ")}, or a view-cube orientation such as top-front-left or top-back-right`;
+      const badCue = (v) => !isCameraCue(v);
+      // The seven canonical names plus the view cube's corners and edges, or a free-form orbit.
+      const angles = `${CANONICAL_VIEWS.join(", ")}, a view-cube orientation such as top-front-left or top-back-right, or an orbit { azimuth, elevation, distance? } in degrees`;
+      // What to say about one bad cue: an orbit-shaped value gets its own
+      // problem named; anything else is an unknown angle.
+      const describe = (v) => (v !== null && typeof v === "object" && !Array.isArray(v)
+        ? `camera orbit ${cameraOrbitProblem(v)}`
+        : `camera ${JSON.stringify(v)} is not a camera angle`);
       for (const { name, a, base } of animEntries(part)) {
         const stepCameras = Array.isArray(a.steps)
           ? a.steps.map((s, i) => [s?.camera, i]).filter(([c]) => c !== undefined && c !== null)
@@ -384,13 +389,13 @@ export const ANIMATION_RULES = [
         if (a.camera != null && stepCameras.length) {
           out.push(err("animation-camera-invalid",
             `animation "${name}" mixes an animation-level \`camera\` with per-step cameras`,
-            "One camera mechanism per animation: either the animation-level name/cue-list, or per-step names — not both.",
+            "One camera mechanism per animation: either the animation-level angle/cue-list, or per-step angles — not both.",
             `${base}.camera`));
         }
         for (const [cam, i] of stepCameras) {
-          if (badName(cam)) {
+          if (badCue(cam)) {
             out.push(err("animation-camera-invalid",
-              `animation "${name}" step ${i} camera "${cam}" is not a camera angle`,
+              `animation "${name}" step ${i} ${describe(cam)}`,
               `Camera cues use ${angles}.`,
               `${base}.steps[${i}].camera`));
           }
@@ -398,17 +403,10 @@ export const ANIMATION_RULES = [
         // An explicit `camera: null` is "no camera", which is how
         // normalizeAnimation reads it — not a malformed value to report.
         if (a.camera == null) continue;
-        if (typeof a.camera === "string") {
-          if (badName(a.camera)) {
-            out.push(err("animation-camera-invalid",
-              `animation "${name}" camera "${a.camera}" is not a camera angle`,
-              `Camera cues use ${angles}.`,
-              `${base}.camera`));
-          }
-        } else if (Array.isArray(a.camera)) {
+        if (Array.isArray(a.camera)) {
           const cues = a.camera;
           const wellFormed = cues.length > 0 && cues.every((c) =>
-            Array.isArray(c) && c.length === 2 && Number.isFinite(c[0]) && c[0] >= 0 && c[0] <= 1 && !badName(c[1]));
+            Array.isArray(c) && c.length === 2 && Number.isFinite(c[0]) && c[0] >= 0 && c[0] <= 1 && !badCue(c[1]));
           const sorted = cues.every((c, i) => i === 0 || (Array.isArray(c) && Array.isArray(cues[i - 1]) && c[0] > cues[i - 1][0]));
           if (!wellFormed || !sorted) {
             out.push(err("animation-camera-invalid",
@@ -416,10 +414,17 @@ export const ANIMATION_RULES = [
               `Cues are \`[[t, angle], …]\` with t strictly ascending in 0..1 and angles from: ${angles}.`,
               `${base}.camera`));
           }
+        } else if (typeof a.camera === "string" || typeof a.camera === "object") {
+          if (badCue(a.camera)) {
+            out.push(err("animation-camera-invalid",
+              `animation "${name}" ${describe(a.camera)}`,
+              `Camera cues use ${angles}.`,
+              `${base}.camera`));
+          }
         } else {
           out.push(err("animation-camera-invalid",
-            `animation "${name}" \`camera\` is neither an angle name nor a cue list`,
-            "Use a canonical angle string, or `[[t, angle], …]` cues.",
+            `animation "${name}" \`camera\` is neither an angle nor a cue list`,
+            "Use an angle name, an { azimuth, elevation, distance? } orbit, or `[[t, angle], …]` cues.",
             `${base}.camera`));
         }
       }

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

@@ -121,6 +121,10 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // Read at teardown time, so it is the LIVE pose — unlike the camera the
     // viewer persists for a page reload, which only records the end of a drag
     // and so misses a view-cube click, Reframe, or an animation cue.
+    // The user's current view as an animation camera cue — `{ cue, panned }`,
+    // or null with nothing on screen — so a host can turn "the way I'm looking
+    // now" into a `camera` value an author (or an agent) writes into a part.
+    getCameraCue: () => viewer.getCameraCue?.() ?? null,
     getViewerState: () => ({
       camera: viewer.getCameraState(),
       projection: viewer.getProjection?.() ?? "perspective",

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/style-camera.js

@@ -117,7 +117,19 @@ export function fitPoseToPoints(view, points, { fov, aspect = 1, fill }) {
 
 // `points` (flat world xyz, optional) lets a "fit" style frame the geometry
 // itself (fitPoseToPoints); without them it fits the box's eight corners.
-export function stylePose(style, view, box, { aspect = 1, points } = {}) {
+export function stylePose(style, view, box, opts = {}) {
+  const out = framedPose(style, view, box, opts);
+  // An orbit cue's `distance` multiplies whatever framing the style chose — the
+  // canonical distance already carries it (cameraPoseForView), a fit does not.
+  const k = typeof view === "object" && view !== null ? view.distance ?? 1 : 1;
+  if (k === 1 || out.fitted === false) return strip(out);
+  const { position, target } = out.pose;
+  out.pose = { ...out.pose, position: [0, 1, 2].map((i) => target[i] + (position[i] - target[i]) * k) };
+  return strip(out);
+}
+const strip = ({ pose, fov, sceneBounds }) => ({ pose, fov, sceneBounds });
+
+function framedPose(style, view, box, { aspect = 1, points } = {}) {
   const fov = style.camera.fov;
   const min = box?.min ?? [0, 0, 0], max = box?.max ?? [0, 0, 0];
   const center = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];
@@ -130,7 +142,7 @@ export function stylePose(style, view, box, { aspect = 1, points } = {}) {
 
   if (style.camera.framing === "canonical" || diag === 0) {
     const radius = Math.max(size[0], size[1], size[2]) / 2 || DEFAULT_RADIUS;
-    return { pose: cameraPoseForView(view, { center, radius }), fov, sceneBounds };
+    return { pose: cameraPoseForView(view, { center, radius }), fov, sceneBounds, fitted: false };
   }
 
   const fitted = points?.length >= 3 && fitPoseToPoints(view, points, { fov, aspect, fill: style.camera.fill });

package/src/framework/view-angles.js

@@ -93,16 +93,123 @@ const norm = (v) => {
   return [v[0] / l, v[1] / l, v[2] / l];
 };
 
+// A free-form camera cue: `{ azimuth, elevation, distance? }`, for the angles no
+// name reaches ("halfway between iso and level"). Degrees, in the MODEL frame
+// the face names already use: azimuth 0 looks from the front (model -Y) and
+// turns toward the right (model +X) at 90, back at 180, left at -90 (or 270);
+// elevation is above the horizontal, 90 straight down from the top. So iso is
+// { azimuth: 45, elevation: 35.26 } and front-right is { azimuth: 45,
+// elevation: 0 }. `distance` multiplies the framing distance a named angle
+// would use (1, the default, frames the part exactly as a name does; 2 is
+// twice as far out), so a cue keeps meaning the same thing as the part's
+// params change its size. The camera always aims at the part's centre: a cue
+// orbits, it never pans.
+export const CAMERA_ORBIT_KEYS = ["azimuth", "elevation", "distance"];
+export const CAMERA_ORBIT_DISTANCE = { min: 0.1, max: 10 };
+
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
+  && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+
+// Why `v` is not a valid orbit cue, as a short phrase; null when it is.
+export function cameraOrbitProblem(v) {
+  if (!isPlainObject(v)) return "is not an { azimuth, elevation } object";
+  const extra = Object.keys(v).filter((k) => !CAMERA_ORBIT_KEYS.includes(k));
+  if (extra.length) return `has unknown key${extra.length > 1 ? "s" : ""} ${extra.map((k) => `\`${k}\``).join(", ")}`;
+  if (!Number.isFinite(v.azimuth)) return "needs a finite numeric `azimuth` (degrees)";
+  if (!Number.isFinite(v.elevation)) return "needs a finite numeric `elevation` (degrees)";
+  if (v.elevation < -90 || v.elevation > 90) return "has an `elevation` outside -90..90";
+  if (v.distance !== undefined) {
+    const { min, max } = CAMERA_ORBIT_DISTANCE;
+    if (!Number.isFinite(v.distance) || v.distance < min || v.distance > max) {
+      return `has a \`distance\` outside ${min}..${max} (a multiple of the default framing distance)`;
+    }
+  }
+  return null;
+}
+
+// Every value a camera cue may be: an angle name from CAMERA_CUE_VIEWS, or an orbit.
+export function isCameraCue(v) {
+  if (typeof v === "string") return CAMERA_CUE_VIEWS.includes(v);
+  return cameraOrbitProblem(v) === null;
+}
+
+// A filename- and log-safe label for a cue: the name itself, or e.g.
+// "az30-el20" / "az30-el20-d1.5" for an orbit.
+export function cameraCueLabel(cue) {
+  if (typeof cue === "string") return cue;
+  const n = (x) => String(Math.round(x * 100) / 100).replace("-", "m");
+  return `az${n(cue.azimuth)}-el${n(cue.elevation)}${cue.distance !== undefined && cue.distance !== 1 ? `-d${n(cue.distance)}` : ""}`;
+}
+
+const RAD = Math.PI / 180;
+
+// World (Y-up) direction and up for an orbit. Model (x, y, z) -> world (x, z, -y)
+// as everywhere else in this file, so model (sin az·cos el, -cos az·cos el, sin el)
+// lands at world (sin az·cos el, sin el, cos az·cos el).
+function orbitAngle({ azimuth, elevation }) {
+  const az = azimuth * RAD, el = elevation * RAD;
+  const h = Math.cos(el);
+  const dir = [Math.sin(az) * h, Math.sin(el), Math.cos(az) * h];
+  // Straight down (or up) a +Y up is degenerate; use the screen-up a camera
+  // approaching that pole from this azimuth would have, which at azimuth 0 is
+  // exactly the `up` the top/bottom names use.
+  let up = [0, 1, 0];
+  if (Math.abs(h) < 1e-9) {
+    const s = elevation > 0 ? -1 : 1;
+    up = [s * Math.sin(az), 0, s * Math.cos(az)];
+  }
+  return { dir, up };
+}
+
+const framingDistance = (radius) => radius * 2.6 + 6; // matches viewer.frameTo's framing distance
+
 export function cameraPoseForView(view, { center, radius }) {
   // DIRS first so the seven canonical names keep their exact existing poses;
-  // ORIENTATIONS covers the other nineteen the cube can reach.
-  const a = DIRS[view] ?? ORIENTATIONS[view];
-  if (!a) throw new Error(`unknown canonical view "${view}"`);
+  // ORIENTATIONS covers the other nineteen the cube can reach; an object is an orbit.
+  let a, scale = 1;
+  if (typeof view === "string") {
+    a = DIRS[view] ?? ORIENTATIONS[view];
+    if (!a) throw new Error(`unknown canonical view "${view}"`);
+  } else {
+    const problem = cameraOrbitProblem(view);
+    if (problem) throw new Error(`camera cue ${problem}`);
+    a = orbitAngle(view);
+    scale = view.distance ?? 1;
+  }
   const d = norm(a.dir);
-  const dist = radius * 2.6 + 6; // matches viewer.frameTo's framing distance
+  const dist = framingDistance(radius) * scale;
   return {
     position: [center[0] + d[0] * dist, center[1] + d[1] * dist, center[2] + d[2] * dist],
     up: a.up,
     target: [...center],
   };
 }
+
+// The inverse of an orbit cue: the cue that reproduces a live camera's angle and
+// distance, so a host (or the agent behind it) can say "keep the view the user
+// has now". `position`/`target` are the viewer's world (Y-up) camera state, and
+// `radius` the same framing radius cameraPoseForView takes for this scene.
+// Rounded to 0.1° and 0.01× — finer than the eye can tell — so the result reads
+// like something an author would write. A pan is not representable (cues always
+// aim at the centre), so it is reported rather than silently dropped. Null for a
+// camera sitting on its target.
+export function cameraCueForPose({ position, target }, { center, radius }) {
+  const off = [position[0] - target[0], position[1] - target[1], position[2] - target[2]];
+  const len = Math.hypot(off[0], off[1], off[2]);
+  if (!(len > 1e-9)) return null;
+  const [x, y, z] = [off[0] / len, off[1] / len, off[2] / len];
+  const round = (v, step) => Math.round(v / step) * step;
+  const fix = (v, places) => Number(v.toFixed(places)) || 0; // || 0 folds -0
+  const elevation = fix(round(Math.asin(Math.max(-1, Math.min(1, y))) / RAD, 0.1), 1);
+  // Azimuth is meaningless at a pole; 0 matches the top/bottom names' roll.
+  const azimuth = Math.abs(elevation) >= 90 ? 0 : fix(round(Math.atan2(x, z) / RAD, 0.1), 1);
+  const { min, max } = CAMERA_ORBIT_DISTANCE;
+  const distance = fix(Math.min(max, Math.max(min, round(len / framingDistance(radius), 0.01))), 2);
+  const panned = Math.hypot(target[0] - center[0], target[1] - center[1], target[2] - center[2]);
+  return {
+    cue: distance === 1 ? { azimuth, elevation } : { azimuth, elevation, distance },
+    // How far the user's orbit target sits from the part centre the cue aims at,
+    // as a fraction of the framing radius. 0 when they never panned.
+    panned: radius > 0 ? fix(panned / radius, 2) : 0,
+  };
+}

package/src/framework/viewer.js

@@ -25,7 +25,7 @@ import { orthoFrustum, perspectiveDistance, isFaceAligned, FACE_ALIGN_COS } from
 import { depthRangeFor } from "./depth-range.js";
 import { addViewerLights, captureLightPoses, createCaptureLights, createHemisphereLight } from "./viewer-lighting.js";
 import { makeCaptureCamera, recenteredView, captureDepthRange } from "./capture-frame.js";
-import { CANONICAL_VIEWS, cameraPoseForView } from "./view-angles.js";
+import { CANONICAL_VIEWS, cameraPoseForView, cameraCueForPose } from "./view-angles.js";
 
 import { srgbEncodeInPlace, RENDER_STYLES, getRenderStyle, CAD_LIGHT_THEME, CAD_DARK_THEME } from "./renderStyles.js";
 import { stylePose, modelToWorld } from "./style-camera.js";
@@ -1361,6 +1361,21 @@ export function createViewer(container, part) {
       { duration, onComplete: finish },
     );
   }
+  // The user's current view as an animation camera cue (view-angles.js
+  // cameraCueForPose): `{ cue: { azimuth, elevation, distance? }, panned }`,
+  // measured against the same bounds and radius tweenCameraTo frames a cue
+  // with, so playing the returned cue lands where the user is looking now
+  // (bar any pan, which `panned` reports). getCameraState supplies the pose,
+  // so an orthographic view reads at its perspective-equivalent distance.
+  // Null with nothing on screen.
+  function getCameraCue() {
+    const box = getVisibleWorldBounds();
+    if (!box || box.isEmpty()) return null;
+    const center = box.getCenter(new THREE.Vector3()).toArray();
+    const size = box.getSize(new THREE.Vector3());
+    const { pos, target } = getCameraState();
+    return cameraCueForPose({ position: pos, target }, { center, radius: Math.max(size.x, size.y, size.z) || 12 });
+  }
   // Cancelling has to put damping back: the tween's own completion path is the
   // only other place that does, and it never runs for a cancelled tween.
   const cancelCameraTween = () => { camTween.cancel(); restoreDamping(); };
@@ -3100,6 +3115,7 @@ export function createViewer(container, part) {
     onFrame,
     onAssemblyChange: (cb) => { assemblyListeners.add(cb); return () => assemblyListeners.delete(cb); },
     tweenCameraTo,
+    getCameraCue,
     holdGround,
     cancelCameraTween,
     orbitBy,

package/src/testing/render.js

@@ -1,7 +1,7 @@
 import { writeFileSync, mkdirSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { safeName } from "../framework/safe-name.js";
-import { ORIENTATIONS } from "../framework/view-angles.js";
+import { ORIENTATIONS, cameraOrbitProblem, cameraPoseForView, cameraCueLabel } from "../framework/view-angles.js";
 import { buildView } from "../framework/oracle/build.js";
 import { renderStyled } from "../framework/softrender/index.js";
 import { getRenderStyle } from "../framework/renderStyles.js";
@@ -28,7 +28,16 @@ export const RENDER_VIEWS = Object.keys(RENDER_ANGLES);
 // The view cube's other orientations (animation camera cues may name them, and
 // a still defaults to its cue's angle), mapped from the viewer's Y-up world
 // back into model space: world (x, y, z) -> model (x, -z, y).
+// An { azimuth, elevation, distance? } orbit cue resolves too, through the
+// viewer's own cameraPoseForView so the two cannot disagree about an angle.
 export function renderAngle(name) {
+  if (typeof name === "object" && name !== null) {
+    if (cameraOrbitProblem(name)) return null;
+    const pose = cameraPoseForView(name, { center: [0, 0, 0], radius: 1 });
+    const toModelDir = ([x, y, z]) => [x, -z, y];
+    return { dir: toModelDir(pose.position), up: toModelDir(pose.up) };
+  }
+  if (typeof name !== "string") return null;
   if (Object.hasOwn(RENDER_ANGLES, name)) return RENDER_ANGLES[name];
   const o = Object.hasOwn(ORIENTATIONS, name) ? ORIENTATIONS[name] : null;
   if (!o) return null;
@@ -60,7 +69,7 @@ export async function renderViewImages(kernel, part, view = Object.keys(part.vie
   // An explicit size is the caller's choice and is honoured as given.
   if (!size) size = resolved.camera.aspect ? [640, Math.round(640 / resolved.camera.aspect)] : [800, 600];
   for (const angle of views) {
-    if (!renderAngle(angle)) throw new Error(`unknown angle "${angle}" (use: ${RENDER_VIEWS.join(", ")}, or a view-cube orientation such as top-front-left)`);
+    if (!renderAngle(angle)) throw new Error(`unknown angle ${JSON.stringify(angle)} (use: ${RENDER_VIEWS.join(", ")}, a view-cube orientation such as top-front-left, or an { azimuth, elevation, distance? } orbit)`);
   }
   // Own-key lookups only — a part named "constructor" must not inherit a value
   // off Object.prototype and vanish from the render.
@@ -76,7 +85,9 @@ export async function renderViewImages(kernel, part, view = Object.keys(part.vie
     const img = renderStyled(subparts, { view: angle, style, size, supersample, edges });
     const png = new PNG({ width: img.width, height: img.height });
     png.data.set(img.rgba);
-    return { angle, png: PNG.sync.write(png) };
+    // `angle` is always a string: an orbit cue comes back as its label (az30-el20),
+    // which is also what names its file.
+    return { angle: cameraCueLabel(angle), png: PNG.sync.write(png) };
   });
 }
 

package/types/index.d.ts

@@ -5,7 +5,7 @@
 // their geometry helpers from "partforge/geometry".
 
 import type { BackendName } from "./kernel.js";
-import type { CanonicalView, ParamValue, PartDefinition } from "./part.js";
+import type { CameraOrbit, CanonicalView, ParamValue, PartDefinition } from "./part.js";
 
 export * from "./kernel.js";
 export * from "./part.js";
@@ -669,6 +669,15 @@ export interface PartRuntime {
    * view-cube click, Reframe, or an animation cue).
    */
   getViewerState(): ViewerState;
+  /**
+   * The user's current view as an animation camera cue, for "keep the view I
+   * have now": write `cue` as a `camera` value and playing it lands on this
+   * angle and distance. Cues always aim at the part's centre, so a pan cannot
+   * be carried — `panned` says how far the user's orbit target sits from that
+   * centre, as a fraction of the framing radius (0 when they never panned).
+   * Null with nothing on screen. Safe after `dispose()`.
+   */
+  getCameraCue(): { cue: CameraOrbit; panned: number } | null;
   /**
    * True while the `preview` GLB is on screen: from the moment it decodes until a
    * build delivers the whole view (a build error leaves it on). Picking, hover

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. */
@@ -660,11 +676,27 @@ export type ViewCubeOrientation =
   | "bottom-front-left" | "bottom-front-right" | "bottom-back-left" | "bottom-back-right";
 
 /**
- * A camera cue angle: one of the canonical seven or a view-cube orientation.
- * `partforge lint` rejects anything else (`animation-camera-invalid`). Cues fire
- * during play only; scrubbing never moves the camera.
+ * A free-form camera angle, for the ones no name reaches. Degrees, in the
+ * part's own frame: `azimuth` 0 looks from the front (-Y) and turns toward the
+ * right (+X) at 90, back at 180, left at -90; `elevation` is above the
+ * horizontal, -90..90. `iso` is `{ azimuth: 45, elevation: 35.26 }` and
+ * `front-right` is `{ azimuth: 45, elevation: 0 }`. `distance` multiplies the
+ * framing distance a named angle uses (default 1; 0.1..10). The camera always
+ * aims at the part's centre.
+ */
+export interface CameraOrbit {
+  azimuth: number;
+  elevation: number;
+  distance?: number;
+}
+
+/**
+ * A camera cue: one of the canonical seven, a view-cube orientation, or a
+ * free-form `CameraOrbit`. `partforge lint` rejects anything else
+ * (`animation-camera-invalid`). Cues fire during play only; scrubbing never
+ * moves the camera.
  */
-export type CameraCue = CanonicalView | ViewCubeOrientation;
+export type CameraCue = CanonicalView | ViewCubeOrientation | CameraOrbit;
 
 /** One step of a multi-step animation. Steps play in order; prev/next navigate them. */
 export interface AnimationStep {