@dailies-studio/shot-editor 0.1.0

package/src/stage/workingView.ts

@@ -0,0 +1,636 @@
+// The working pane's free-orbit camera, as pure spherical arithmetic.
+//
+// ── COORDINATE CONVENTION, STATED ONCE ──────────────────────────────────
+//
+// The DOCUMENT is design px with +y DOWN and +z AWAY. three is +y UP and -z
+// away. The one mapping is `world = (x, -y, -z)`, and each lane performs it in
+// exactly one place: ShotRuntime for the camera and the layers, move.ts for a
+// gesture delta (see packages/shot docs).
+//
+// EVERYTHING HERE IS ALREADY WORLD (three) COORDINATES. `target` is a world
+// point, `workingPose().position` is a world point, and nothing in this file
+// negates anything. A second negation is the exact failure this note exists to
+// prevent: it looks right on a centred canvas and inverts the orbit everywhere
+// else, which reads as "orbit is inverted sometimes".
+//
+// One unit is one design px, because the mapping has no scale in it.
+//
+// ── WHY THIS IS NOT A SECOND DOCUMENT CAMERA ────────────────────────────
+//
+// view.ts's header says the shot has ONE camera, and that still holds: this one
+// is EDITOR STATE. It is never written to the document, never sampled, and
+// never reaches an export. It decides where the author is standing while they
+// look at the shot; the shot itself is unchanged by where they stand.
+//
+// ── ANGLES ARE DEGREES ──────────────────────────────────────────────────
+//
+// Hence every constant being named `*_DEG`. `phi` is the polar angle FROM WORLD
+// +Y, which is three's own `Spherical` convention, so `phi = 90, theta = 0`
+// puts the eye at +z looking back down the shot camera's own axis. Keeping the
+// convention identical to three's is what lets `workingPose` be checked against
+// `Vector3.setFromSphericalCoords` rather than against a diagram.
+//
+// THREE-FREE: plain arrays and numbers, so the chrome can render a readout of
+// the view and these functions are testable in node.
+import { DEFAULT_FOV_DEG, planeDistance } from "@dailies-studio/shot/doc";
+import { FIT_MARGIN } from "./view.js";
+import type { FrameSize } from "./view.js";
+
+/**
+ * The working camera's lens, FIXED.
+ *
+ * Deliberately not `scene.fovDeg`: a zoom shot animates the shot camera's lens
+ * every frame, and a working pane that followed it would breathe under the
+ * author's hands while they orbit — the one thing an authoring view must not
+ * do. It borrows the schema's own default only so this lane has no second
+ * magic number, not because the two are coupled.
+ *
+ * Everything that needs the working camera's lens reads THIS: the camera the
+ * stage writes, and `defaultWorkingView`'s derived distance. A second opinion
+ * would make "fit" frame something other than what is drawn.
+ */
+export const WORKING_FOV_DEG = DEFAULT_FOV_DEG;
+
+export interface WorkingView {
+  /** Azimuth in degrees, wrapped to [-180, 180). 0 is the shot camera's axis. */
+  theta: number;
+  /** Polar angle from world +y, in degrees. Clamped off both poles. */
+  phi: number;
+  /** Eye-to-target distance, in world units (= design px). */
+  distance: number;
+  /** The world point the eye orbits and looks at. */
+  target: [number, number, number];
+  /**
+   * ORTHOGRAPHIC instead of perspective. Numpad-5, and the reason ours used to
+   * answer null: the pane had only a perspective lens.
+   *
+   * It is what makes an elevation readable — parallel edges stay parallel, so
+   * two layers the same size measure the same on screen wherever they sit in
+   * depth, which is exactly what you want while lining a card up against
+   * another one behind it.
+   *
+   * ── AND WHY NOTHING ELSE IN THIS FILE BRANCHES ON IT ──────────────────
+   *
+   * The ortho half-height the renderer uses is `distance * tan(fov/2)`, which
+   * is exactly the half-height the perspective lens frames AT THE TARGET. So
+   * the picture is identical at the moment of the toggle, and
+   * `workingScreenScale`'s `2 * distance * tan(fov/2)` is already right for
+   * both. Orbit, pan and dolly are unchanged too: they move the same five
+   * numbers.
+   *
+   * `framingFromWorkingView` is the ONE exception and it is load-bearing — see
+   * its own note.
+   *
+   * Optional so every existing literal in this repo, and every persisted
+   * workspace pref, keeps meaning perspective with no migration.
+   */
+  ortho?: boolean;
+}
+
+export const ORBIT_DEG_PER_PX = 0.3;
+
+/**
+ * How far one numpad orbit step turns the view, in DEGREES.
+ *
+ * Blender's own 15. It lives HERE beside `ORBIT_DEG_PER_PX` rather than in the
+ * keymap, because the keymap deciding how far a turn is would be a second
+ * opinion on the same question — and a degrees-based step means it does not
+ * change when the drag sensitivity does.
+ */
+export const ORBIT_STEP_DEG = 15;
+
+
+/** Off the poles, both ends. At phi 0 or 180 the eye is straight above or below
+ *  the target, `lookAt`'s up vector is parallel to the view direction, and the
+ *  camera's roll is undefined — which shows up as the view snapping to an
+ *  arbitrary rotation exactly at the top of a drag. */
+export const MIN_PHI_DEG = 5;
+export const MAX_PHI_DEG = 175;
+
+/** A degenerate distance is not a far-away camera, it is a camera AT the target:
+ *  `lookAt` gets a zero-length direction and writes a NaN quaternion, and every
+ *  projected quad after that is NaN. The floor is one design px because a
+ *  sub-pixel camera distance means nothing in a design-px world. */
+const MIN_DISTANCE = 1;
+const MAX_DISTANCE = 1e7;
+
+/** Wheel px for one e-fold of distance. THE SAME 320 `wheelToView` uses for
+ *  zoom, so one notch is the same ratio whichever pane it lands in. Exported so
+ *  the chrome's zoom BUTTONS can express their step as a ratio through
+ *  `dollyBy` rather than reaching past the clamps to write `distance`. */
+export const DOLLY_FALLOFF_PX = 320;
+
+/**
+ * How far a NAVIGATION gesture may dolly, as a ratio of the fit distance.
+ *
+ * `MIN_DISTANCE`/`MAX_DISTANCE` above are SANITISATION — they exist so `lookAt`
+ * never sees a zero-length direction and so a distance stays a finite float.
+ * They are deliberately vacuous as travel limits: 1e7 is ~2400x the fit
+ * distance of a 1080-tall document, which is a wheel spin into empty space with
+ * the canvas long since a dot, and 1 puts the eye a single design px from the
+ * target. Neither scales with the document, so a 4K board and a square sticker
+ * get the same nonsense band.
+ *
+ * These two do scale, because they are expressed against `defaultWorkingView`'s
+ * derived fit. For a 1920x1080 document (fit ~4159) the band is ~[42, 41590]:
+ * at the near wall the smallest legal layer, 1 design px, still spans a
+ * readable fraction of the pane, and at the far wall the whole canvas reads
+ * about 42 px tall. Past either end there is nothing to look at.
+ */
+export const DOLLY_MIN_FIT_RATIO = 1 / 100;
+export const DOLLY_MAX_FIT_RATIO = 10;
+
+/** The travel limits for one document, from `dollyBounds`. */
+export interface DollyBounds {
+  min: number;
+  max: number;
+}
+
+/**
+ * The navigation band for a document, derived from the same fit
+ * `defaultWorkingView` computes so the two cannot disagree.
+ *
+ * Only NAVIGATION is bounded. `defaultWorkingView`, `workingViewForFraming` and
+ * `workingViewForIsolation` answer "show me exactly this" and stay unbounded on
+ * purpose: fitting a selection the author deliberately made tiny should frame
+ * it, not refuse. The next dolly then walks back into band from wherever the
+ * fit landed, which is the behaviour a wall should have.
+ *
+ * PURE in (frame, fov), and three-free, so the chrome's zoom buttons can ask
+ * for the same numbers the stage's wheel uses.
+ */
+export function dollyBounds(frame: FrameSize, fovDeg: number = WORKING_FOV_DEG): DollyBounds {
+  const fit = defaultWorkingView(frame, fovDeg).distance;
+  return { min: fit * DOLLY_MIN_FIT_RATIO, max: fit * DOLLY_MAX_FIT_RATIO };
+}
+
+/** The default three-quarter look. Off-axis on both angles so the canvas reads
+ *  as a plane in space at a glance; a straight-on default would be
+ *  indistinguishable from the camera pane and the split would look broken. */
+const DEFAULT_THETA_DEG = 35;
+const DEFAULT_PHI_DEG = 65;
+
+const DEG = Math.PI / 180;
+
+function clampPhi(phi: number): number {
+  if (!Number.isFinite(phi)) return 90;
+  return Math.max(MIN_PHI_DEG, Math.min(MAX_PHI_DEG, phi));
+}
+
+function clampDistance(distance: number): number {
+  if (!Number.isFinite(distance)) return MIN_DISTANCE;
+  return Math.max(MIN_DISTANCE, Math.min(MAX_DISTANCE, distance));
+}
+
+/** Azimuth into [-180, 180). Wrapped rather than clamped: a full turn is a real
+ *  gesture, and an unwrapped theta grows without bound over a session until it
+ *  loses float precision in `Math.sin`. */
+function wrapDeg(deg: number): number {
+  if (!Number.isFinite(deg)) return 0;
+  return ((((deg + 180) % 360) + 360) % 360) - 180;
+}
+
+/**
+ * The eye position for a view.
+ *
+ * This IS `Vector3.setFromSphericalCoords(r, phi, theta)` offset by the target,
+ * written out so the file stays three-free — and so it can be diffed against
+ * three when someone doubts the convention. The camera's orientation is not
+ * returned because it is not free: the working camera always looks at `target`.
+ */
+export function workingPose(view: WorkingView): { position: [number, number, number] } {
+  const phi = clampPhi(view.phi) * DEG;
+  const theta = wrapDeg(view.theta) * DEG;
+  const r = clampDistance(view.distance);
+  const sinPhi = Math.sin(phi);
+  return {
+    position: [
+      view.target[0] + r * sinPhi * Math.sin(theta),
+      view.target[1] + r * Math.cos(phi),
+      view.target[2] + r * sinPhi * Math.cos(theta),
+    ],
+  };
+}
+
+/**
+ * A drag orbits the eye around the target.
+ *
+ * BOTH SIGNS ARE NEGATIVE, which is `OrbitControls`' convention and therefore
+ * the one already in the author's hands: dragging right walks the eye left, so
+ * the thing under the cursor appears to follow the cursor. Dragging down walks
+ * the eye up and over, so the canvas tips towards the author.
+ *
+ * Measured from the PRESS by the caller, never accumulated — the same rule
+ * `panBy` states, for the same reason.
+ */
+export function orbitBy(view: WorkingView, dxPx: number, dyPx: number): WorkingView {
+  return {
+    ...view,
+    theta: wrapDeg(view.theta - dxPx * ORBIT_DEG_PER_PX),
+    phi: clampPhi(clampPhi(view.phi) - dyPx * ORBIT_DEG_PER_PX),
+  };
+}
+
+/**
+ * The same orbit, asked for in DEGREES.
+ *
+ * The numpad's step is an angle, not a distance, so routing it through
+ * `orbitBy` would make it change whenever the drag sensitivity did. Both share
+ * one implementation, so the two can never differ about which way is which.
+ *
+ * The SIGNS ARE FLIPPED against `orbitBy` because the two are asked opposite
+ * questions: a drag says "the eye moves this way against the cursor" and a
+ * numpad says "turn the view this way". Numpad4 turning the view LEFT is what
+ * the key means and what Blender does.
+ */
+export function orbitByDegrees(view: WorkingView, dxDeg: number, dyDeg: number): WorkingView {
+  return orbitBy(view, -dxDeg / ORBIT_DEG_PER_PX, -dyDeg / ORBIT_DEG_PER_PX);
+}
+
+/**
+ * SCREEN PX PER DESIGN PX at the target's depth — the working pane's answer to
+ * `ShotView.zoom`, which is the same quantity for the flat camera pane.
+ *
+ * Exported because two lanes need the identical number and a second derivation
+ * would put them a lens apart: the pan below turns a drag into world units with
+ * its reciprocal, and the chrome's snapping divides a SCREEN threshold by it —
+ * a working-pane drag measured against the camera pane's zoom snaps at a
+ * distance that has nothing to do with what the author can see.
+ *
+ * `viewportHeight` is the PANE's height, not the canvas's, because the pane is
+ * what the fov spans.
+ *
+ * Infinity for a degenerate lens, which is the answer that stays useful in both
+ * directions: the pan's `1 / scale` is then zero (a lens with no extent moves
+ * nothing) and the snap threshold divided by it is zero (nothing to snap to).
+ */
+export function workingScreenScale(
+  view: WorkingView,
+  viewportHeight: number,
+  fovDeg: number = WORKING_FOV_DEG,
+): number {
+  const height = Number.isFinite(viewportHeight) && viewportHeight > 0 ? viewportHeight : 1;
+  const fov = Number.isFinite(fovDeg) ? fovDeg : 0;
+  const visible = 2 * clampDistance(view.distance) * Math.tan((fov * DEG) / 2);
+  return visible > 0 ? height / visible : Number.POSITIVE_INFINITY;
+}
+
+/**
+ * The camera basis straight out of the two angles, all three UNIT LENGTH.
+ *
+ * three's `lookAt` builds z = normalize(eye - target), x = normalize(up × z),
+ * y = z × x with world +y as up; substitute the spherical eye and those
+ * collapse to exactly these closed forms. No matrix and no cross product means
+ * nothing here can drift out of step with the renderer's own basis.
+ *
+ * `forward` points FROM the eye AT the target — the direction the author is
+ * looking, which is `-z` of that basis. Stated as its own name because every
+ * consumer wants the looking direction and none of them wants to remember the
+ * sign.
+ *
+ * Three lanes read it: the pan below turns a screen drag into a world one, the
+ * nav gizmo projects the design axes onto (right, up), and the same gizmo sorts
+ * its balls by `forward`. A second derivation in any of them would put the
+ * drawn axes a rotation away from the one the pan moves along.
+ */
+export function viewBasis(view: WorkingView): {
+  right: [number, number, number];
+  up: [number, number, number];
+  forward: [number, number, number];
+} {
+  const theta = wrapDeg(view.theta) * DEG;
+  const phi = clampPhi(view.phi) * DEG;
+  const sinPhi = Math.sin(phi);
+  return {
+    right: [Math.cos(theta), 0, -Math.sin(theta)],
+    up: [-Math.cos(phi) * Math.sin(theta), sinPhi, -Math.cos(phi) * Math.cos(theta)],
+    // `workingPose` puts the eye at +r along (sinφ sinθ, cosφ, sinφ cosθ) from
+    // the target, so looking AT the target is that same direction negated.
+    forward: [-sinPhi * Math.sin(theta), -Math.cos(phi), -sinPhi * Math.cos(theta)],
+  };
+}
+
+/**
+ * A drag slides the target across the screen, keeping the eye's angles.
+ *
+ * The scale is the visible height AT THE TARGET'S DEPTH divided by the
+ * viewport's — `planeDistance` run backwards. Panning at the target's depth is
+ * what makes the point under the cursor keep up with the cursor; using any
+ * other depth makes the canvas either lag or outrun the pointer, at a rate that
+ * changes with the dolly.
+ */
+export function panWorkingBy(
+  view: WorkingView,
+  dxPx: number,
+  dyPx: number,
+  viewportHeight: number,
+  fovDeg: number,
+): WorkingView {
+  const perPx = 1 / workingScreenScale(view, viewportHeight, fovDeg);
+  const { right, up } = viewBasis(view);
+  return {
+    ...view,
+    target: [
+      view.target[0] + (dyPx * up[0] - dxPx * right[0]) * perPx,
+      view.target[1] + dyPx * up[1] * perPx,
+      view.target[2] + (dyPx * up[2] - dxPx * right[2]) * perPx,
+    ],
+  };
+}
+
+/**
+ * The wheel dollies the eye in and out.
+ *
+ * EXPONENTIAL, mirroring `wheelToView`: distance is the reciprocal of zoom, so
+ * where zoom multiplies by `exp(-dy / 320)` this multiplies by `exp(+dy / 320)`
+ * and a notch is the same visual step in either pane. Linear steps would crawl
+ * when far out and jump when close in.
+ *
+ * `wheelDeltaY` is already `deltaMode`-scaled by the caller, exactly as
+ * `wheelToView` scales it — Firefox reports lines where Chrome reports px.
+ *
+ * `bounds` is the document's navigation band (`dollyBounds`). It is optional
+ * because the sanitisation clamp has to hold with or without a document, and
+ * because an absent argument leaves this function byte-identical to the version
+ * every existing caller was written against.
+ *
+ * THE WHEEL COALESCER SUMS DELTAS, so the clamp has to compose. It does: for a
+ * monotone map into a saturating interval, clamping each step and clamping the
+ * composed step land on the same value for a same-sign burst, which is every
+ * real wheel spin. A burst that reverses inside one frame loses only the travel
+ * a wall would have eaten anyway.
+ */
+export function dollyBy(view: WorkingView, wheelDeltaY: number, bounds?: DollyBounds): WorkingView {
+  const dy = Number.isFinite(wheelDeltaY) ? wheelDeltaY : 0;
+  const dollied = clampDistance(clampDistance(view.distance) * Math.exp(dy / DOLLY_FALLOFF_PX));
+  const distance = bounds === undefined ? dollied : Math.max(bounds.min, Math.min(bounds.max, dollied));
+  return { ...view, distance };
+}
+
+/**
+ * The view an author gets before they touch anything: an off-axis three-quarter
+ * look with the WHOLE canvas in shot.
+ *
+ * THE DISTANCE IS DERIVED, NOT AUTHORED, for the same reason `planeDistance` is
+ * (resolve.ts): there is then no number for anyone to get wrong. The shot
+ * camera's own distance frames the canvas HEIGHT exactly. Seen from an angle
+ * the canvas is turned, so the extent that has to fit is its DIAGONAL — which
+ * is the identical relationship with `hypot(w, h)` substituted for the height,
+ * and it is rotation-invariant, so no orbit angle can push a corner off-pane.
+ * Then the same `FIT_MARGIN` the 2D fit uses, so "fit" means one thing here.
+ *
+ * PURE in (frame, fov): a document opens at the same view on every machine, and
+ * a fresh load and a reset button cannot disagree.
+ */
+export function defaultWorkingView(frame: FrameSize, fovDeg: number): WorkingView {
+  const diagonal = Math.hypot(frame.width, frame.height);
+  return {
+    theta: DEFAULT_THETA_DEG,
+    phi: DEFAULT_PHI_DEG,
+    distance: clampDistance(planeDistance(diagonal, fovDeg, 1) / (1 - FIT_MARGIN * 2)),
+    target: [0, 0, 0],
+  };
+}
+
+/**
+ * The orbit pose that stands where isolation's DERIVED head-on rig stands.
+ *
+ * ── WHY THE HAND-OVER NEEDS A CONVERSION AT ALL ─────────────────────────
+ *
+ * Isolation draws with an orthographic camera posed from the subtree's own
+ * basis (isolation.ts), and the author's first navigation gesture hands the
+ * pane back to this file's spherical rig. Without seeding, that gesture would
+ * continue from wherever the orbit camera happened to be BEFORE the author
+ * entered the subtree, and the picture would jump the width of the scene.
+ *
+ * This is `workingPose` run backwards, so the two cannot disagree: substitute
+ * the returned angles and the eye comes back where it started.
+ *
+ * ── THE NAMED CEILING ───────────────────────────────────────────────────
+ *
+ * ponytail: the orbit rig resets `up` to world +y every frame and clamps its
+ * polar angle off both poles, so a subtree that is ROLLED or lying FACE DOWN
+ * has no exact representation here and seeds to the nearest pose that does. The
+ * picture turns once, at the moment the author takes the camera, by the amount
+ * the rig cannot express. Head-on stays exact because the reset goes back to
+ * the derived rig rather than trying to represent it. Upgrade path is a
+ * free-roll working camera, which is a bigger change than the jump is worth.
+ *
+ * `halfHeight` is the ortho rig's own half-extent, and the distance is derived
+ * so the perspective lens frames the same height — the ortho camera's distance
+ * is arbitrary (it is chosen for the clip planes) and carrying it across would
+ * frame something else entirely.
+ */
+export function workingViewForIsolation(
+  eye: readonly [number, number, number],
+  target: readonly [number, number, number],
+  halfHeight: number,
+  fovDeg: number = WORKING_FOV_DEG,
+): WorkingView {
+  const dx = eye[0] - target[0];
+  const dy = eye[1] - target[1];
+  const dz = eye[2] - target[2];
+  const r = Math.hypot(dx, dy, dz);
+  // A degenerate separation means the derived rig is not looking anywhere yet,
+  // which the clamps below turn into a usable pose rather than a NaN one.
+  const unitY = r > 0 ? dy / r : 0;
+  const tan = Math.tan((Number.isFinite(fovDeg) ? fovDeg : WORKING_FOV_DEG) * DEG * 0.5);
+  return {
+    theta: wrapDeg((Math.atan2(dx, dz) * 180) / Math.PI),
+    phi: clampPhi((Math.acos(Math.max(-1, Math.min(1, unitY))) * 180) / Math.PI),
+    distance: clampDistance(tan > 0 ? halfHeight / tan : MIN_DISTANCE),
+    target: [target[0], target[1], target[2]],
+    // ORTHOGRAPHIC, because the rig this inverts IS one (isolation.ts's
+    // `isolationEye` builds an `OrthographicCamera`). Rebuilding the view
+    // without the flag silently dropped the pane back to perspective at the
+    // exact moment the author took the camera over, so the picture changed on
+    // the first orbit with nothing having asked for it.
+    ortho: true,
+  };
+}
+
+/** The Blender-numpad axis views. Plain strings so the keymap can carry one
+ *  without importing this module. */
+export type WorkingViewPreset = "front" | "back" | "right" | "left" | "top" | "bottom";
+
+/**
+ * Snap the view to an axis, KEEPING the distance and the target.
+ *
+ * Angles only: the numpad answers "which side am I looking from", never "how
+ * far away am I" — Blender's convention, and the one that makes the keys safe
+ * to lean on mid-layout. Front is theta 0 (the shot camera's own axis, per
+ * this file's convention) and back wraps to -180 via `wrapDeg`.
+ *
+ * TOP AND BOTTOM LAND ON THE POLE CLAMPS, not on 0/180: straight down the
+ * pole the camera's roll is undefined (see MIN_PHI_DEG), so "top" is the
+ * closest pose that still has a stable up — 5 degrees off vertical, keeping
+ * the author's theta so the horizon stays where they left it.
+ */
+export function presetWorkingView(view: WorkingView, preset: WorkingViewPreset): WorkingView {
+  switch (preset) {
+    case "front":
+      return { ...view, theta: 0, phi: 90 };
+    case "back":
+      return { ...view, theta: wrapDeg(180), phi: 90 };
+    case "right":
+      return { ...view, theta: 90, phi: 90 };
+    case "left":
+      return { ...view, theta: -90, phi: 90 };
+    case "top":
+      return { ...view, phi: MIN_PHI_DEG };
+    case "bottom":
+      return { ...view, phi: MAX_PHI_DEG };
+  }
+}
+
+/**
+ * The view held before any document has arrived, in BOTH documents.
+ *
+ * 1080p is a stand-in and the fitter replaces it the moment a document lands.
+ * It exists so the initial state is a real, finite pose rather than a camera
+ * sitting AT its own target — which is what `{distance: 0, target: [0,0,0]}`
+ * would be, and which makes `lookAt` write a NaN quaternion and blank the pane
+ * with no error. The chrome's `INITIAL_STATE` and the stage's own initial state
+ * take it from here so a reconnect cannot start them on different views.
+ */
+export const INITIAL_WORKING_VIEW: WorkingView = defaultWorkingView(
+  { width: 1920, height: 1080 },
+  WORKING_FOV_DEG,
+);
+
+/**
+ * The working view, projected onto the FRAMING model — "align the camera to
+ * this view", and the half of the round trip that can fail.
+ *
+ * ── WHY THIS CAN REFUSE, AND WHY REFUSING IS THE FEATURE ────────────────
+ *
+ * A `Framing` is four numbers (x, y, zoom, roll) describing a camera that looks
+ * straight down -z from the +z side. A free orbit is five, and most of them
+ * describe a pose no framing can name. Writing "the closest framing" for a pose
+ * the author is looking at from behind the canvas would hand them a camera
+ * pointing at something else and call it aligned; naming the reason costs one
+ * message and is the only answer they can act on.
+ *
+ * ── WHAT IS PRESERVED, AND WHAT IS NOT ──────────────────────────────────
+ *
+ * The CENTRE is where the author is looking: the view axis meets z = 0 there,
+ * and that point is the framing's pan by definition of the model.
+ *
+ * The ZOOM matches the FRAMED AREA, not the camera's distance. The shot camera
+ * frames `height / zoom` design px; the working camera frames
+ * `2 * t * tan(fov/2)` at the point it is looking at. Equating those is what
+ * makes the picture the same size; equating the two DISTANCES instead would be
+ * off by the ratio of the lenses, and the working lens is deliberately not the
+ * scene's (see WORKING_FOV_DEG).
+ *
+ * ROLL is not read. The working camera's up is world +y at every pose — it
+ * cannot be rolled — so the framing that matches what the author sees has no
+ * roll, and inventing one from the foreshortening of world-up would rotate the
+ * shot by an amount the author never asked for. The caller keeps whatever roll
+ * the framing already had.
+ */
+export type ViewFramingResult =
+  | { ok: true; x: number; y: number; zoom: number }
+  | { ok: false; refusal: string };
+
+/**
+ * Below this the view axis is parallel enough to the canvas that the hit point
+ * runs away to infinity — a grazing pose has no framing, not a huge one.
+ *
+ * It is used for the AXIS test alone now. It used to also guard the
+ * eye-to-target separation, and that arm was unreachable: `clampDistance`
+ * floors every distance at `MIN_DISTANCE = 1` for every input including NaN,
+ * so the separation can never be smaller than 1. A refusal nobody can trigger
+ * is a refusal nobody can trust, so it is gone rather than left to imply a
+ * case that does not exist.
+ */
+const MIN_AXIS_Z = 1e-4;
+
+export function framingFromWorkingView(
+  view: WorkingView,
+  frame: FrameSize,
+  fovDeg: number = WORKING_FOV_DEG,
+): ViewFramingResult {
+  const eye = workingPose(view).position;
+  const target = view.target;
+  const dir: [number, number, number] = [target[0] - eye[0], target[1] - eye[1], target[2] - eye[2]];
+  const length = Math.hypot(dir[0], dir[1], dir[2]);
+  // A FINITE BACKSTOP, not a separation test. `clampDistance` floors the
+  // distance at `MIN_DISTANCE = 1` for every input including NaN, so a camera
+  // sitting on its own target is unreachable — the refusal that claimed to
+  // catch it was dead code. What CAN still arrive here is a non-finite target,
+  // which no clamp on the distance touches.
+  if (!Number.isFinite(length)) {
+    return {
+      ok: false,
+      refusal:
+        "The working camera is not looking anywhere a framing could describe — press Home to " +
+        "put it back, then align.",
+    };
+  }
+
+  if (eye[2] <= 0) {
+    return {
+      ok: false,
+      refusal:
+        "The working camera is behind the canvas, and the shot camera always looks at it from the " +
+        "front — orbit back round to the front of the layers, then align.",
+    };
+  }
+  // Towards the plane means -z: the eye is in front of it, so the axis has to
+  // point back at it. Away from it, or along it, has no crossing to frame.
+  const axisZ = dir[2] / length;
+  if (axisZ > -MIN_AXIS_Z) {
+    return {
+      ok: false,
+      refusal:
+        "The working camera is looking along the canvas rather than at it, so there is no " +
+        "rectangle for the shot camera to frame — orbit until the canvas faces you, then align.",
+    };
+  }
+
+  // Where the view axis meets design z = 0, and how far away that is.
+  const t = -eye[2] / axisZ;
+  const hit: [number, number] = [eye[0] + (dir[0] / length) * t, eye[1] + (dir[1] / length) * t];
+  // ── ORTHOGRAPHIC FRAMES A CONSTANT HEIGHT ────────────────────────────────
+  //
+  // A perspective camera's framed height grows with the distance to the plane,
+  // which is why `t` appears below. An ortho camera's does not: it is the
+  // rig's own half-extent, `distance * tan(fov/2)`, wherever the plane happens
+  // to be. Substituting `distance` for `t` is not an approximation — it IS the
+  // ortho answer, and the two agree exactly when the plane is at the target.
+  //
+  // LOAD-BEARING, and not optional: this function is a DOCUMENT WRITER (align
+  // camera to view, and every gesture under follow mode). Leaving `t` here
+  // would write a framing that gets more wrong the further the target sits
+  // from z = 0, silently, and autosave it.
+  const span = view.ortho === true ? clampDistance(view.distance) : t;
+  const zoom = frame.height / (2 * span * Math.tan((fovDeg * DEG) / 2));
+  if (!Number.isFinite(zoom) || zoom <= 0) {
+    return { ok: false, refusal: "The working camera is too close to the canvas to express as a framing — dolly back, then align." };
+  }
+  // The one mapping, undone: world y is design -y.
+  return { ok: true, x: hit[0], y: -hit[1], zoom };
+}
+
+/**
+ * The other half of the round trip: the working view that sees exactly what a
+ * framing sees.
+ *
+ * Head on, at the distance whose framed height matches. It exists so "align,
+ * then look at what you aligned to" is a checkable identity rather than a
+ * claim, and so the fitter has one place to derive a distance from a lens.
+ */
+export function workingViewForFraming(
+  framing: { x: number; y: number; zoom: number },
+  frame: FrameSize,
+  fovDeg: number = WORKING_FOV_DEG,
+): WorkingView {
+  const zoom = framing.zoom > 0 ? framing.zoom : 1;
+  return {
+    theta: 0,
+    phi: 90,
+    distance: clampDistance(frame.height / (2 * zoom * Math.tan((fovDeg * DEG) / 2))),
+    target: [framing.x, -framing.y, 0],
+  };
+}