partforge 0.160.0 → 0.162.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 —
@@ -4347,12 +4375,16 @@ unverified.
 
 **Assertion DSL:** a bare number means equality (`holes: 1`); `">=n"`, `"<=n"`, `">n"`,
 `"<n"`, or a range `"a..b"`; an optional unit suffix `mm`/`cm`/`mm3`/`cm3`; and for
-`bbox`, `centerOfMass` and each side of `bounds`, a componentwise vector `"<=[x,y,z]"` /
-`">=[x,y,z]"` — exactly 3 components, each a plain number in mm or `*` to skip an axis.
-A vector is always one-sided: a bare `[40,40,10]` (meaning "exactly this size") is
-rejected, since a mesh's box shifts with tessellation and no tolerance would be honest
-for every part — pick `<=` for a limit or `>=` for a floor. `bounds` takes an object
-with `min` and/or `max`, each such a vector: `bounds: { min: ">=[0,0,0]", max:
+`bbox`, `centerOfMass` and each side of `bounds`, a componentwise vector — one-sided,
+`"<=[x,y,z]"` / `">=[x,y,z]"`, or two-sided with a range per axis,
+`"[28..32, 18..22, 9..11]"` (the bare comma form `"28..32,18..22,9..11"` is accepted
+too) — exactly 3 components, each a plain number in mm (or a range of them) or `*` to
+skip an axis. A bare `[40,40,10]` (meaning "exactly this size") is rejected, since a
+mesh's box shifts with tessellation and no tolerance would be honest for every part —
+pick `<=` for a limit, `>=` for a floor, or say what tolerance you mean with a range
+per axis (`"[39.5..40.5, 39.5..40.5, 9.8..10.2]"`; a zero-width `40..40` is an exact
+check with the parser's 1e-6 slack, and will fail on a chorded curve). `bounds` takes an
+object with `min` and/or `max`, each such a vector: `bounds: { min: ">=[0,0,0]", max:
 "<=[220,220,250]" }`. The parser is strict — a malformed assertion fails loudly.
 
 **A part whose typeface is a parameter needs band assertions, not points.** Glyph

package/package.json

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

@@ -160,6 +160,8 @@ function checkHeld(held, parts, path) {
 // `verify-bad-expr`, not `verify-bad-pair-check`: a malformed key is a pair-naming
 // problem, but a malformed value is an assertion-DSL problem, same as any other
 // metric's expectation.
+const DSL_HINT = "Use the assertion DSL: a bare value for equality, a comparison like `>=3`, a range like `2..5`, or a componentwise vector like `<=[60,60,60]` or `[28..32,18..22,9..11]` (with `*` to skip an axis).";
+
 function checkClearanceExprs(clearance, path) {
   if (clearance === undefined || clearance === null || typeof clearance !== "object") return [];
   const out = [];
@@ -168,7 +170,7 @@ function checkClearanceExprs(clearance, path) {
     catch (e) {
       out.push(err("verify-bad-expr",
         `the expectation for _view.clearance["${key}"] is not a valid assertion: ${e?.message || String(e)}`,
-        "Use the assertion DSL: a bare value for equality, a comparison like `>=3`, a range like `2..5`, or a componentwise vector like `<=[60,60,60]` (with `*` to skip an axis).",
+        DSL_HINT,
         `${path}[${JSON.stringify(key)}]`));
     }
   }
@@ -218,7 +220,7 @@ function checkProcessSpec(spec, path, valid, seen, depth = 0) {
 // One expectation's well-formedness against its registry entry: it parses, and it has the form the
 // metric reads — a range for `wall`, a componentwise vector for bbox/centerOfMass/the
 // sides of bounds. A bare vector gets the two legal spellings back, in its own numbers.
-const DSL_HINT = "Use the assertion DSL: a bare value for equality, a comparison like `>=3`, a range like `2..5`, or a componentwise vector like `<=[60,60,60]` (with `*` to skip an axis).";
+const VECTOR_OPS = new Set(["vle", "vge", "vrange"]);
 const capitalize = (t) => t.charAt(0).toUpperCase() + t.slice(1);
 
 function checkExpr(target, metric, spec, reg) {
@@ -246,10 +248,24 @@ function checkExpr(target, metric, spec, reg) {
       `Write ${metric} as \`"<min>..<max>"\` with min <= max, in mm.`,
       path)];
   }
-  if (form === "vector" && parsed.op !== "vle" && parsed.op !== "vge") {
+  if (form === "vector" && parsed.op !== "vle" && parsed.op !== "vge" && parsed.op !== "vrange") {
     return [err("verify-bad-expr",
       `the expectation for ${target}.${metric} must be a componentwise vector, got ${describe(expr)} — ${metric} is an [x,y,z] reading`,
-      `Write ${metric} as \`"<=[x,y,z]"\` or \`">=[x,y,z]"\` (componentwise; * skips an axis).`,
+      `Write ${metric} as \`"<=[x,y,z]"\`, \`">=[x,y,z]"\` or \`"[a..b,c..d,e..f]"\` (componentwise; * skips an axis).`,
+      path)];
+  }
+  // A vector on a scalar metric (`volume: "<=[1,2,3]"`) is not a parse error, and
+  // the evaluator would index a number and pass it vacuously — so it is caught here.
+  if (form !== "vector" && VECTOR_OPS.has(parsed.op)) {
+    return [err("verify-bad-expr",
+      `the expectation for ${target}.${metric} must be a single value, got ${describe(expr)} — ${metric} is one number, not an [x,y,z] reading`,
+      DSL_HINT,
+      path)];
+  }
+  if (parsed.op === "vrange" && parsed.vec.some((c) => c !== null && c[0] > c[1])) {
+    return [err("verify-bad-expr",
+      `the expectation for ${target}.${metric} must be a range vector with min <= max on every axis, got "${expr}"`,
+      `Write each axis of ${metric} as \`<min>..<max>\` with min <= max, in mm (or \`*\` to skip it).`,
       path)];
   }
   return [];

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/assert-dsl.js

@@ -25,7 +25,8 @@ const reVec = /^(>=|<=)\s*\[\s*(.+?)\s*\]$/;
 // own numbers, which is a one-step fix. Returns that hint, or null when `expr` is
 // not a bare vector. An exact vector is deliberately not offered: a mesh's box is
 // tessellation-dependent (a curved face chords inside its true extent), so no
-// tolerance would be honest for every part.
+// tolerance would be honest for every part — a writer who wants both sides
+// declares the tolerance themselves with the per-axis range form below.
 const reBareVec = /^(?:==?)?\s*\[(.*)\]$/;
 const VEC_TAIL = "(componentwise; * skips an axis)";
 
@@ -36,6 +37,10 @@ export function bareVectorHint(expr) {
     const m = expr.trim().match(reBareVec);
     if (!m) return null;
     comps = m[1].split(",").map((t) => t.trim());
+    // A component with `..` in it is a range-vector attempt (below), not a bare
+    // vector: its own parse error names the right fix, and the two-spelling hint
+    // here would send the writer back to a one-sided form.
+    if (comps.some((c) => c.includes(".."))) return null;
   } else return null;
   comps = comps.map((c) => c.replace(/\s*mm$/, ""));
   const ok = comps.length === 3 && comps.every((c) => c === "*" || (c !== "" && Number.isFinite(Number(c))));
@@ -46,6 +51,33 @@ export function bareVectorHint(expr) {
 
 const show = (expr) => (typeof expr === "string" ? `"${expr}"` : JSON.stringify(expr));
 
+// The two-sided vector form: a RANGE per axis, `"[28..32, 18..22, 9..11]"`, with `*`
+// skipping an axis. The brackets are optional because the bare comma form
+// (`"28..32,18..22,9..11"`) is what a model produces when it reaches for this —
+// three trials wrote it before the form existed and were told "unrecognized form".
+// Components are plain numbers in mm, like the one-sided vectors: a unit suffix
+// is refused rather than scaled. Returns null when `s` is not a range-vector
+// attempt at all (no `..` inside a bracket pair or comma list), so the other
+// forms get their turn; a malformed attempt throws its own error.
+const reRangeComp = new RegExp(`^(${NUM})\\s*\\.\\.\\s*(${NUM})$`);
+const RANGE_VEC_SHAPE = "exactly 3 components, each a range a..b in mm or *";
+
+function rangeVector(s) {
+  const bracketed = s.match(/^\[(.*)\]$/);
+  const inner = bracketed ? bracketed[1] : s;
+  if (!inner.includes("..") || !inner.includes(",")) return null;
+  if (!bracketed && /[\[\]]/.test(s)) return null; // one bracket of a pair — not this form
+  const parts = inner.split(",").map((t) => t.trim());
+  if (parts.length !== 3) throw new Error(`assertion: a range vector takes ${RANGE_VEC_SHAPE}: "${s}"`);
+  const vec = parts.map((t) => {
+    if (t === "*") return null;
+    const m = t.match(reRangeComp);
+    if (!m) throw new Error(`assertion: a range vector takes ${RANGE_VEC_SHAPE}: "${s}"`);
+    return [toBase(m[1], undefined), toBase(m[2], undefined)];
+  });
+  return { op: "vrange", vec };
+}
+
 export function parseAssertion(expr) {
   if (typeof expr === "number" || typeof expr === "boolean") return { op: "eq", value: expr };
   const bare = bareVectorHint(expr);
@@ -53,6 +85,8 @@ export function parseAssertion(expr) {
   if (typeof expr !== "string") throw new Error(`assertion: unsupported value ${JSON.stringify(expr)}`);
   const s = expr.trim();
 
+  const vr = rangeVector(s);
+  if (vr) return vr;
   const vec = s.match(reVec);
   if (vec) {
     const parts = vec[2].split(",").map((t) => t.trim());
@@ -76,6 +110,7 @@ export function parseAssertion(expr) {
 const EPS = 1e-6;
 const approxEq = (a, b) => Math.abs(a - b) <= EPS + EPS * Math.abs(b);
 const fmtVec = (v) => "[" + v.map((x) => (x === null ? "*" : x)).join(",") + "]";
+const fmtRangeVec = (v) => "[" + v.map((c) => (c === null ? "*" : `${c[0]}..${c[1]}`)).join(",") + "]";
 
 export function evaluateAssertion(parsed, actual) {
   switch (parsed.op) {
@@ -102,6 +137,15 @@ export function evaluateAssertion(parsed, actual) {
       }
       return { pass, message: `${fmtVec(actual)} ${ge ? ">=" : "<="} ${fmtVec(parsed.vec)}` };
     }
+    case "vrange": {
+      let pass = true;
+      for (let i = 0; i < 3; i++) {
+        const band = parsed.vec[i];
+        if (band === null) continue;
+        if (actual[i] < band[0] - EPS || actual[i] > band[1] + EPS) pass = false;
+      }
+      return { pass, message: `${fmtVec(actual)} ${pass ? "in" : "out of"} ${fmtRangeVec(parsed.vec)}` };
+    }
     default: throw new Error(`assertion: unknown op "${parsed.op}"`);
   }
 }

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/verify-metrics.js

@@ -130,7 +130,7 @@ export const SUBPART_METRICS = {
     hint: "the rebuild's symmetric difference vs its reference import is too large — compare the ghost overlay, then adjust the governing dimensions toward the measured reference" },
   refVolumeDeltaPct: { kind: "gate", extract: (s) => s.deviation?.volumeDeltaPct ?? null,
     hint: "rebuild volume differs from the reference import by more than the allowed percentage — a feature is missing, doubled, or mis-scaled vs the reference" },
-  refBboxDelta: { kind: "gate", extract: (s) => s.deviation?.bboxDelta ?? null,
+  refBboxDelta: { kind: "gate", form: "vector", extract: (s) => s.deviation?.bboxDelta ?? null,
     hint: "the rebuild's bounding-box corners drift from the reference import — check overall dimensions and that the rebuild is aligned to the reference's coordinates" },
   // Sheet parts (sheetPart(), partforge/geometry): each process's own checks. verify
   // volunteers them on every sheet sub-part; an author may declare them like any other.

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

@@ -676,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 type CameraCue = CanonicalView | ViewCubeOrientation;
+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 | CameraOrbit;
 
 /** One step of a multi-step animation. Steps play in order; prev/next navigate them. */
 export interface AnimationStep {