partforge 0.160.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 —

package/package.json

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

@@ -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 {