@dailies-studio/shot-editor 0.1.0

package/src/stage/frustumGeometry.ts

@@ -0,0 +1,172 @@
+// The shot camera drawn as an object: apex, framed rectangle, pyramid edges and
+// an up-marker, as pure arithmetic.
+//
+// ── WHY THE VERTICES ARE NOT COMPUTED IN THE COMPONENT ──────────────────
+//
+// Because they are the only part that can be WRONG in a way nobody notices. A
+// gizmo drawn a few degrees off still looks like a frustum, and the author would
+// read the error as the camera being somewhere it is not. Pulled out here it is
+// asserted against a hand-computed pose in node, with no GL and no three.
+//
+// THREE-FREE, plain arrays, same rule panes.ts and workingView.ts follow.
+//
+// ── THE POSE IS DERIVED FROM THE RIG, NEVER RE-DERIVED FROM THE DOCUMENT ─
+//
+// `cameraRigAt` (packages/shot/src/resolve.ts) already answers "where is the
+// camera and what is its lens at this frame", including the dolly-vs-zoom
+// distinction that pins the distance for a zoom shot. Recomputing any of that
+// here would be a second camera model, and the two would disagree on exactly
+// the shots that are hardest to eyeball.
+//
+// The cross-section follows from the rig alone: half-height is
+// `distance * tan(fov/2)`, which by `planeDistance`'s definition is exactly
+// `frameHeight / (2 * zoom)` for a dolly AND for a zoom shot. So the drawn
+// rectangle is the framed rectangle by construction rather than by agreement.
+//
+// COORDINATES ARE WORLD (three). The one mapping — design (x, y, z) is world
+// (x, -y, -z) — is applied here and nowhere downstream, the same note
+// workingView.ts carries.
+import type { Framing } from "@dailies-studio/shot/doc";
+import type { FrameSize } from "./view.js";
+
+export type Vec3 = [number, number, number];
+
+/** Exactly what `cameraRigAt` returns, structurally. Named here so this file
+ *  states what it needs rather than importing a shape it cannot check. */
+export interface CameraRig {
+  framing: Framing;
+  distance: number;
+  fovDeg: number;
+}
+
+/**
+ * The gizmo's vertices.
+ *
+ * `corners` are TL, TR, BR, BL — the SAME winding `project.ts` uses for a
+ * layer quad, which is what lets them be handed to `rayHitsQuad` unchanged.
+ */
+export interface FrustumShape {
+  /** The camera's own position. */
+  apex: Vec3;
+  /** The framed rectangle at design z = 0. */
+  corners: [Vec3, Vec3, Vec3, Vec3];
+  /** The up-marker above the top edge: left base, apex, right base. */
+  up: [Vec3, Vec3, Vec3];
+}
+
+/** The up-marker, as fractions of the frustum's half-extents. Small enough not
+ *  to read as part of the picture, big enough to be seen at a fit. */
+const UP_BASE_FRACTION = 0.16;
+const UP_HEIGHT_FRACTION = 0.26;
+
+const DEG = Math.PI / 180;
+
+export function frustumShape(rig: CameraRig, frame: FrameSize): FrustumShape {
+  const distance = finite(rig.distance, 1);
+  const halfH = Math.abs(distance * Math.tan((finite(rig.fovDeg, 35) * DEG) / 2));
+  const aspect = frame.height > 0 ? frame.width / frame.height : 1;
+  const halfW = halfH * aspect;
+
+  // The camera's own basis, straight out of the roll. ShotRuntime writes
+  // `camera.rotation.set(0, 0, -rollDeg)`, so this angle is that rotation and
+  // the two cannot disagree about which way a positive roll turns.
+  const a = -finite(rig.framing.rollDeg, 0) * DEG;
+  const cos = Math.cos(a);
+  const sin = Math.sin(a);
+  const right: Vec3 = [cos, sin, 0];
+  const up: Vec3 = [-sin, cos, 0];
+
+  // The framing's pan IS the camera's position on the plane, negated in y by
+  // the one mapping.
+  const cx = finite(rig.framing.x, 0);
+  const cy = -finite(rig.framing.y, 0);
+  const at = (u: number, v: number): Vec3 => [
+    cx + right[0] * u * halfW + up[0] * v * halfH,
+    cy + right[1] * u * halfW + up[1] * v * halfH,
+    0,
+  ];
+
+  const topMid = at(0, 1);
+  const marker = (u: number, v: number): Vec3 => [
+    topMid[0] + right[0] * u * halfW + up[0] * v * halfH,
+    topMid[1] + right[1] * u * halfW + up[1] * v * halfH,
+    0,
+  ];
+
+  return {
+    apex: [cx, cy, distance],
+    corners: [at(-1, 1), at(1, 1), at(1, -1), at(-1, -1)],
+    up: [
+      marker(-UP_BASE_FRACTION, 0),
+      marker(0, UP_HEIGHT_FRACTION),
+      marker(UP_BASE_FRACTION, 0),
+    ],
+  };
+}
+
+/** Every segment as a flat xyz pair list, ready for a `LineSegments` position
+ *  attribute: four pyramid edges, the base rectangle, then the up-marker. */
+export function frustumSegments(shape: FrustumShape): number[] {
+  const { apex, corners, up } = shape;
+  const out: number[] = [];
+  const seg = (a: Vec3, b: Vec3): void => {
+    out.push(a[0], a[1], a[2], b[0], b[1], b[2]);
+  };
+  for (const corner of corners) seg(apex, corner);
+  for (let i = 0; i < 4; i++) seg(corners[i]!, corners[(i + 1) % 4]!);
+  seg(up[0], up[1]);
+  seg(up[1], up[2]);
+  seg(up[2], up[0]);
+  return out;
+}
+
+/** How many floats `frustumSegments` writes. The buffer is allocated once and
+ *  rewritten in place, so the count has to be a constant rather than whatever
+ *  the first call happened to produce. */
+export const FRUSTUM_SEGMENT_FLOATS = 11 * 2 * 3;
+
+/** Did any vertex move enough to be worth re-uploading the buffer? Half a
+ *  design pixel, mirroring `quadMoved`'s gate for the same reason: this runs on
+ *  every committed frame and a still playhead must cost nothing. */
+export function segmentsMoved(a: ArrayLike<number>, b: ArrayLike<number>, epsilon = 0.5): boolean {
+  if (a.length !== b.length) return true;
+  for (let i = 0; i < a.length; i++) if (Math.abs(a[i]! - b[i]!) > epsilon) return true;
+  return false;
+}
+
+/**
+ * Distance from a screen point to the nearest of the quad's four border
+ * segments, in the same px the points arrive in.
+ *
+ * The corners come PROJECTED (x, y pairs, TL TR BR BL) so this stays
+ * camera-free and testable in node. It exists because the base quad is the
+ * FRAMED rectangle — `frameHeight / (2 * zoom)` tall — so a small zoom makes
+ * it dwarf the canvas and cover the whole working pane. A body grab that
+ * claimed the quad's INTERIOR would then take every press in the pane: orbit
+ * becomes unreachable, and an author who thinks they are orbiting slides the
+ * camera by thousands of design px instead — each slide a document write. The
+ * BORDER is the affordance that is actually drawn, so it is the thing a press
+ * can mean.
+ */
+export function borderDistance(
+  x: number,
+  y: number,
+  corners: readonly (readonly [number, number])[],
+): number {
+  let best = Number.POSITIVE_INFINITY;
+  for (let i = 0; i < corners.length; i++) {
+    const [ax, ay] = corners[i]!;
+    const [bx, by] = corners[(i + 1) % corners.length]!;
+    const dx = bx - ax;
+    const dy = by - ay;
+    const lengthSq = dx * dx + dy * dy;
+    // A degenerate edge is its endpoint (an edge-on quad projects to a line).
+    const t = lengthSq === 0 ? 0 : Math.max(0, Math.min(1, ((x - ax) * dx + (y - ay) * dy) / lengthSq));
+    best = Math.min(best, Math.hypot(x - (ax + t * dx), y - (ay + t * dy)));
+  }
+  return best;
+}
+
+function finite(value: number, fallback: number): number {
+  return Number.isFinite(value) ? value : fallback;
+}

package/src/stage/gizmoMath.ts

@@ -0,0 +1,494 @@
+// The arithmetic behind the working pane's three placement aids: the floor
+// grid, the axis-drag gizmo, and the corner navigation ball.
+//
+// THREE-FREE, like workingView.ts and modalState.ts and for the same reason:
+// every rule here is a table row a node test can pin, and the three-side
+// components (GridPlane, MoveGizmo) and the SVG overlay all read the same
+// answers rather than each deriving their own.
+//
+// ── DESIGN AXES, NOT WORLD AXES ─────────────────────────────────────────
+//
+// The author types G then Y and reads "Y: 300" in the inspector, and both of
+// those mean DESIGN y, which is DOWN. So the gizmo's three arms are the design
+// axes, mapped into world by the one mapping workingView.ts states once:
+// `world = (x, -y, -z)`. Labelling the arms with world axes instead would put
+// the letter Y on the arm that moves the layer the opposite way from the field
+// the author is watching.
+import { presetWorkingView, viewBasis } from "./workingView.js";
+import type { WorkingView, WorkingViewPreset } from "./workingView.js";
+import type { ModalState } from "./modalState.js";
+import type { FramingDelta } from "../bridgeTypes.js";
+
+export type Vec3 = readonly [number, number, number];
+export type DesignAxis = "x" | "y" | "z";
+
+/**
+ * The three design axes as UNIT WORLD directions, and the numpad view each one
+ * looks back from.
+ *
+ * The preset is the view whose EYE sits on the positive end of that axis: eye
+ * on world +x is `right`, eye on world -y (which is design +y, down) is
+ * `bottom`, eye on world -z (design +z, away) is `back`. Stated as a table so
+ * the nav ball and the numpad can never disagree about what "look down X"
+ * means — `presetWorkingView` is the only place either of them turns into
+ * angles.
+ */
+export const DESIGN_AXES: readonly {
+  axis: DesignAxis;
+  world: Vec3;
+  /** Looking back along the axis from its POSITIVE end. */
+  preset: WorkingViewPreset;
+  /** …and from its negative end. */
+  presetNegative: WorkingViewPreset;
+}[] = [
+  { axis: "x", world: [1, 0, 0], preset: "right", presetNegative: "left" },
+  { axis: "y", world: [0, -1, 0], preset: "bottom", presetNegative: "top" },
+  { axis: "z", world: [0, 0, -1], preset: "back", presetNegative: "front" },
+];
+
+/** What a press on one of the drag arms turned out to be. Plain arrays and a
+ *  letter, so the pointer lane can carry it without touching three — and so
+ *  the origin is a SNAPSHOT: the gizmo re-anchors every frame, and an axis
+ *  line that moved with the thing being dragged along it would chase its own
+ *  translation.
+ *
+ *  `subject` is `modalTarget`'s own answer, carried rather than re-derived:
+ *  the arms are drawn at ONE anchor, and a drag that decided for itself
+ *  whether that anchor was a layer or the camera could pick the other one
+ *  mid-gesture if the selection changed under it. */
+export interface GizmoGrab {
+  subject: ModalState["target"];
+  axis: DesignAxis;
+  origin: Vec3;
+  direction: Vec3;
+}
+
+/**
+ * A camera arm's travel, as the framing delta it means.
+ *
+ * The camera has THREE authorable degrees of freedom for placement and they do
+ * not map one-to-one onto the axes: a `Framing` is (x, y, zoom, roll) for a
+ * camera that always looks straight down -z (workingView.ts's note), so x and y
+ * are its position on the plane and there is no free z — the distance IS the
+ * zoom, by `planeDistance`.
+ *
+ * So X and Y are the pan, unchanged, and Z is the DOLLY. `planeDistance` is
+ * `k / zoom`, which makes `distance * zoom` constant and the ratio exact:
+ * pushing the camera from `t0` to `t` multiplies its zoom by `t0 / t`. That is
+ * why this can be a factor rather than an approximation, and why a drag along
+ * the Z arm keeps the arm under the cursor where the apex's exponential drag
+ * (which has no depth to solve against) cannot.
+ *
+ * `travel` is measured along the arm's own DESIGN direction, so +z is towards
+ * the canvas and `t = t0 - travel`.
+ *
+ * Null once the camera has been pushed onto or through the canvas: there is no
+ * framing on the far side (`framingFromWorkingView` refuses the same pose for
+ * the same reason), and the ratio would flip sign rather than grow. Refusing
+ * leaves the last good delta standing, and dragging back recovers because every
+ * emit re-derives from the press.
+ */
+export function framingArmDelta(
+  axis: DesignAxis,
+  travel: number,
+  distanceAtPress: number,
+): FramingDelta | null {
+  if (axis !== "z") {
+    return { dx: axis === "x" ? travel : 0, dy: axis === "y" ? travel : 0, dzoom: 1 };
+  }
+  const t0 = distanceAtPress;
+  const t = t0 - travel;
+  if (!Number.isFinite(t0) || t0 <= 0 || !Number.isFinite(t) || t <= 0) return null;
+  // The zoom CLAMP is camera.ts's (MIN/MAX_FRAMING_ZOOM), deliberately not
+  // repeated here: one boundary for the drag, the align, the fit and the agent
+  // op, and a second opinion would let one of them past the others.
+  return { dx: 0, dy: 0, dzoom: t0 / t };
+}
+
+function dot(a: Vec3, b: Vec3): number {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+
+/** One end of one axis, as the nav ball draws it. */
+export interface NavBall {
+  axis: DesignAxis;
+  positive: boolean;
+  /** Screen direction from the gizmo's centre, y DOWN like every other screen
+   *  number in this lane. NOT normalized: its length is the FORESHORTENING,
+   *  which is what pulls an axis pointing at the author in towards the centre
+   *  — the cue that tells them they are looking down it. */
+  x: number;
+  y: number;
+  /** How far towards the viewer this end points, -1..1. Sort ASCENDING and
+   *  draw in that order, so the near balls land on top of the far ones — which
+   *  is the only depth cue a flat SVG has. */
+  toward: number;
+  preset: WorkingViewPreset;
+}
+
+/**
+ * The six axis ends, projected for the corner gizmo.
+ *
+ * ORTHOGRAPHIC on purpose: a navigation gizmo shows DIRECTIONS, and running it
+ * through the working camera's perspective divide would make the arm pointing
+ * at the author swing wildly with the pane's aspect for no information gained.
+ * Directions are exactly what the camera basis gives, so this is three dot
+ * products per end and no matrices.
+ */
+export function navBalls(view: WorkingView): NavBall[] {
+  const { right, up, forward } = viewBasis(view);
+  const out: NavBall[] = [];
+  for (const { axis, world, preset, presetNegative } of DESIGN_AXES) {
+    const x = dot(world, right);
+    // Screen y is down and the basis's up is up, so the sign flips exactly
+    // once, here.
+    const y = -dot(world, up);
+    // `forward` points from the eye AT the target, so a vector coming back at
+    // the viewer has a negative component along it.
+    const toward = -dot(world, forward);
+    out.push({ axis, positive: true, x, y, toward, preset });
+    out.push({ axis, positive: false, x: -x, y: -y, toward: -toward, preset: presetNegative });
+  }
+  return out;
+}
+
+/** The view a nav ball click lands on. Re-exported through this module so the
+ *  overlay never needs workingView.ts's angle vocabulary — it holds a preset
+ *  string and hands it back. */
+export function viewForBall(view: WorkingView, ball: NavBall): WorkingView {
+  return presetWorkingView(view, ball.preset);
+}
+
+/**
+ * How far along an axis line the closest point to a ray sits.
+ *
+ * THIS IS WHAT MAKES A GRABBED ARM STAY UNDER THE CURSOR. The alternative —
+ * unproject onto a plane and zero the other two components, which is what the
+ * modal lane does because it has no arm to stay under — drifts away from the
+ * pointer as the view turns, and at a grazing angle it runs away entirely.
+ *
+ * The standard closest-approach solve for two lines, with both directions
+ * taken as UNIT (the caller passes an axis from `DESIGN_AXES` and a normalized
+ * ray direction), which collapses `a` and `e` to 1.
+ *
+ * Null when the ray is PARALLEL to the axis: the closest point is then every
+ * point, the solve divides by zero, and skipping the emit is the only honest
+ * answer — the same refusal `designDelta` makes for an edge-on plane.
+ */
+const MIN_AXIS_DENOM = 1e-6;
+
+/**
+ * Can this arm, as DRAWN, answer a press?
+ *
+ * ── THE QUANTITY IS THE SEGMENT'S OWN LENGTH ────────────────────────────
+ *
+ * `ARM_START_PX` and `ARM_PX` are world lengths taken at the anchor's depth and
+ * then projected, so what the author can actually hit is those lengths times
+ * the sine of the axis's angle to the view direction. An axis pointing at the
+ * camera collapses: at Numpad7 the design y arm draws about 2.6 px, and under
+ * an orthographic rig the design z arm draws a mathematical POINT on the
+ * anchor. `borderDistance` to a degenerate segment is just the distance to that
+ * point, so every press near the selection centre grabbed it — and then
+ * `axisParam` divided by a zero denominator, answered null, and the press
+ * opened no scrub and did nothing at all.
+ *
+ * The first version of this gate measured the ROOT's offset from the anchor
+ * instead, reasoning that the tip sits three times further out so the root test
+ * implies the length test. That is backwards, and the cost was total: the root
+ * offset is at most `ARM_START_PX = 30` px, the threshold was 28, and at the
+ * SHIPPED DEFAULT view all three arms measured 20 to 27 — so every arm failed
+ * and the gizmo answered nothing anywhere while still being painted.
+ *
+ * ── AND THE APEX CLEARANCE IS A SEPARATE QUESTION ───────────────────────
+ *
+ * Only on the CAMERA, where the anchor IS the frustum's apex and the apex's own
+ * 14 px grab is tested AFTER this one. An arm whose root lands inside that
+ * radius takes every press aimed at the dolly. A layer has no such neighbour,
+ * so it does not pay for it.
+ *
+ * PURE, and here rather than inside `MoveGizmo`'s frame loop, because a gate
+ * that decides whether a whole widget works has to be checkable without a GL
+ * context — see test/stageGeometry.test.ts.
+ */
+export function armGrabbable(
+  root: readonly [number, number],
+  tip: readonly [number, number],
+  anchor: readonly [number, number],
+  subject: "layers" | "camera",
+  minLengthPx: number,
+  apexClearPx: number,
+): boolean {
+  if (Math.hypot(tip[0] - root[0], tip[1] - root[1]) < minLengthPx) return false;
+  if (subject !== "camera") return true;
+  return Math.hypot(root[0] - anchor[0], root[1] - anchor[1]) >= apexClearPx;
+}
+
+export function axisParam(
+  origin: Vec3,
+  axis: Vec3,
+  rayOrigin: Vec3,
+  rayDirection: Vec3,
+): number | null {
+  const r: Vec3 = [origin[0] - rayOrigin[0], origin[1] - rayOrigin[1], origin[2] - rayOrigin[2]];
+  const b = dot(axis, rayDirection);
+  const denom = 1 - b * b;
+  if (!(Math.abs(denom) > MIN_AXIS_DENOM)) return null;
+  const s = (b * dot(rayDirection, r) - dot(axis, r)) / denom;
+  return Number.isFinite(s) ? s : null;
+}
+
+/** The 1 / 2 / 5 decimal ladder rung nearest a target, in LOG space so "nearest"
+ *  means nearest by ratio — 384 wants 500, not 200, and a linear comparison
+ *  says the opposite. */
+const LADDER = [1, 2, 5, 10];
+
+export function niceStep(target: number): number {
+  if (!Number.isFinite(target) || target <= 0) return 1;
+  const decade = Math.pow(10, Math.floor(Math.log10(target)));
+  const scaled = target / decade;
+  let best = LADDER[0]!;
+  for (const rung of LADDER) {
+    if (Math.abs(Math.log(rung / scaled)) < Math.abs(Math.log(best / scaled))) best = rung;
+  }
+  return best * decade;
+}
+
+/**
+ * The floor grid's line segments, flat xyz pairs for a `LineSegments` position
+ * attribute.
+ *
+ * In the XZ plane at a fixed height, which is the plane the canvas STANDS on
+ * rather than the one it lives in — see GridPlane for why a grid through the
+ * design origin is the wrong answer here even though it is Blender's.
+ */
+export function gridPositions(step: number, cells: number, height: number): number[] {
+  const half = step * cells;
+  const out: number[] = [];
+  for (let i = -cells; i <= cells; i++) {
+    const at = i * step;
+    out.push(at, height, -half, at, height, half);
+    out.push(-half, height, at, half, height, at);
+  }
+  return out;
+}
+
+/**
+ * The grid's spacing at a given camera distance.
+ *
+ * A fixed spacing is a grid that only reads right at one zoom. Dollied out it
+ * is a solid grey field of lines nobody can count, and the cells stop meaning a
+ * distance at all; dollied in there is nothing between the lines at all.
+ *
+ * The rule is one line per tenth of what the camera can SEE, which is the same
+ * rule the frame-height version was already applying — `2 * distance *
+ * tan(fov/2)` is the visible height at the target, and at the fit distance that
+ * is roughly the canvas. Then the same `niceStep` ladder, so the spacing is
+ * always a round number an author can count in, and it changes in jumps rather
+ * than sliding continuously under the artwork.
+ *
+ * FLOORED AT THE FRAME'S OWN HEIGHT, which keeps close range exactly as it was:
+ * zooming in past the canvas refines nothing, because a grid finer than the
+ * document's own tenth is measuring in units the document does not use.
+ *
+ * Pure in (frameHeight, distance, fovDeg): no hysteresis, no memory of the last
+ * answer. A quantised function of the current view is the only kind of
+ * adaptation this lane can have.
+ */
+export function gridStep(frameHeight: number, distance: number, fovDeg: number): number {
+  return niceStep(gridSpan(frameHeight, distance, fovDeg) / GRID_CELLS_PER_SPAN);
+}
+
+/**
+ * What the working camera can SEE at the target, floored at the frame's height.
+ *
+ * The one length the whole floor is built from: the spacing divides it, and the
+ * fade is a multiple of it. Two aids derived from one quantity move together
+ * under a dolly, which is what stops the fade landing inside the drawn patch at
+ * some distances and outside it at others.
+ */
+export function gridSpan(frameHeight: number, distance: number, fovDeg: number): number {
+  const visible = 2 * Math.max(0, distance) * Math.tan((Math.max(1, Math.min(179, fovDeg)) * Math.PI) / 360);
+  return Math.max(frameHeight, Number.isFinite(visible) ? visible : 0);
+}
+
+/** Lines across the visible span. A tenth is the coarsest division that still
+ *  reads as a grid rather than as a floor with four lines on it. */
+export const GRID_CELLS_PER_SPAN = 10;
+
+/**
+ * Cells each way from the grid's centre.
+ *
+ * ── WHY THIS IS LARGE AND NOT 24 ────────────────────────────────────────
+ *
+ * A ground plane is not bounded by what the camera can see. Look ALONG it and
+ * it recedes to a horizon, so no multiple of the visible height covers it —
+ * the old 24 cells (about 2.4 spans) ran out in open view at any grazing
+ * angle, and the pane showed the floor simply stopping in a square.
+ *
+ * The cost of the bigger number is one draw call with `(2 * cells + 1) * 4`
+ * vertices and no per-frame work at all, because the buffer is static and the
+ * OBJECT is what follows the author. The number itself is chosen against
+ * `gridFade`: see `gridExtent`.
+ */
+export const GRID_CELLS = 192;
+
+/**
+ * Where the floor fades out, as `[start, end]` distances FROM THE EYE.
+ *
+ * Extent alone does not buy an infinite grid. A patch large enough to reach
+ * past every view is a patch whose far lines converge into an aliased band,
+ * and a band that ends is still an edge. Fading the lines into the pane's own
+ * backdrop is what turns the end into a horizon.
+ *
+ * Measured from the CAMERA, not from the grid's centre: fog is a property of
+ * how far away a thing is, and a fade centred on the target would sit
+ * lopsided in the view the moment the author orbits off-centre.
+ *
+ * In spans, so the fade dollies WITH the spacing — the author always sees
+ * roughly the same number of cells before the floor dissolves, at every zoom.
+ */
+export function gridFade(frameHeight: number, distance: number, fovDeg: number): [number, number] {
+  const span = gridSpan(frameHeight, distance, fovDeg);
+  return [span * GRID_FADE_START_SPANS, span * GRID_FADE_END_SPANS];
+}
+
+const GRID_FADE_START_SPANS = 1.5;
+const GRID_FADE_END_SPANS = 6;
+
+/**
+ * Half the drawn patch's width, which must always outreach the fade.
+ *
+ * The gate `GRID_CELLS` is chosen against: the fade ring is centred on the
+ * EYE and the patch on the target, so the geometry has to cover
+ * `fadeEnd + distance` or the author finds a hard edge inside the region the
+ * fade has not finished dimming. `gizmoMath.test.ts` sweeps the legal dolly
+ * band against exactly that inequality.
+ */
+export function gridExtent(frameHeight: number, distance: number, fovDeg: number): number {
+  return GRID_CELLS * gridStep(frameHeight, distance, fovDeg);
+}
+
+/**
+ * One world axis, as a single segment through the origin.
+ *
+ * `axis` is the WORLD axis index (0 = x, 1 = y, 2 = z). The design axes map to
+ * the world ones by `world = (x, -y, -z)`, and a LINE THROUGH THE ORIGIN is
+ * invariant under that sign flip — so these are the design axes too, as sets,
+ * and the colours match the nav gizmo's letters without a conversion.
+ */
+/** Radians of key rotation per CSS pixel dragged. A half turn in ~314 px, the
+ *  same order as the modal falloffs, so the two feel like one tool. */
+export const KEY_DRAG_RAD_PER_PX = 0.01;
+
+
+/**
+ * Turn a key direction by a screen drag.
+ *
+ * ── AN ARCBALL, NOT TWO EULER ANGLES ──────────────────────────────────────
+ *
+ * The author is dragging a point around a sphere they are looking at, so the
+ * rotation axes have to be the ones on screen: horizontal travel turns the key
+ * about the view's UP, vertical travel about the view's RIGHT. Yaw and pitch in
+ * world coordinates would drift the moment the author orbited, because "up" in
+ * the picture would no longer be up in the maths.
+ *
+ * `dir` and the result are in the DESIGN frame, which is what
+ * `mesh.shading.keyDir` stores; `viewBasis` speaks the world frame, so the
+ * mapping `world = (x, -y, -z)` is applied on the way in and undone on the way
+ * out. It is its own inverse, which is why both directions are the same line.
+ *
+ * PURE, and measured from a base rather than accumulated: the caller passes the
+ * direction at the PRESS and the total travel, so a coalesced drag lands
+ * exactly where an uncoalesced one does. Unit length is restored at the end,
+ * because a rotation of a unit vector is one and a document should not carry
+ * float drift.
+ */
+export function rotateKeyDir(
+  dir: readonly [number, number, number],
+  view: WorkingView,
+  dxPx: number,
+  dyPx: number,
+): [number, number, number] {
+  const { right, up } = viewBasis(view);
+  // Design -> world, the one mapping.
+  let v: [number, number, number] = [dir[0], -dir[1], -dir[2]];
+  v = rotateAbout(v, up, -dxPx * KEY_DRAG_RAD_PER_PX);
+  v = rotateAbout(v, right, -dyPx * KEY_DRAG_RAD_PER_PX);
+  const length = Math.hypot(v[0], v[1], v[2]);
+  // A zero-length key has no direction to turn. Handing back the input is the
+  // only answer that cannot write NaN into the document.
+  if (!Number.isFinite(length) || length < 1e-9) return [dir[0], dir[1], dir[2]];
+  // …and world -> design, which is the same sign flip.
+  return [v[0] / length, -v[1] / length, -v[2] / length];
+}
+
+/** Rodrigues' rotation of `v` about a unit `axis` by `angle` radians. Written
+ *  out rather than built through three's Quaternion so this file stays
+ *  three-free and testable in node. */
+function rotateAbout(
+  v: readonly [number, number, number],
+  axis: readonly [number, number, number],
+  angle: number,
+): [number, number, number] {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const dot = v[0] * axis[0] + v[1] * axis[1] + v[2] * axis[2];
+  const cross: [number, number, number] = [
+    axis[1] * v[2] - axis[2] * v[1],
+    axis[2] * v[0] - axis[0] * v[2],
+    axis[0] * v[1] - axis[1] * v[0],
+  ];
+  return [
+    v[0] * c + cross[0] * s + axis[0] * dot * (1 - c),
+    v[1] * c + cross[1] * s + axis[1] * dot * (1 - c),
+    v[2] * c + cross[2] * s + axis[2] * dot * (1 - c),
+  ];
+}
+
+/**
+ * A key direction projected into the pane, for drawing the arm.
+ *
+ * `null` when the key points nearly along the view axis: there is no readable
+ * 2D direction there, and drawing a near-zero arm would make the handle jitter
+ * around the layer centre. The caller draws the disc alone instead.
+ */
+export function keyDirOnScreen(
+  dir: readonly [number, number, number],
+  view: WorkingView,
+): [number, number] | null {
+  const { right, up } = viewBasis(view);
+  const world: [number, number, number] = [dir[0], -dir[1], -dir[2]];
+  const sx = world[0] * right[0] + world[1] * right[1] + world[2] * right[2];
+  // NEGATED: screen y runs DOWN and the basis's up runs up.
+  const sy = -(world[0] * up[0] + world[1] * up[1] + world[2] * up[2]);
+  const length = Math.hypot(sx, sy);
+  if (!Number.isFinite(length) || length < 1e-3) return null;
+  return [sx / length, sy / length];
+}
+
+export function axisPositions(axis: 0 | 1 | 2, extent: number): number[] {
+  const a = [0, 0, 0];
+  const b = [0, 0, 0];
+  a[axis] = -extent;
+  b[axis] = extent;
+  return [...a, ...b];
+}
+
+/**
+ * Where an axis segment SITS, given the view target and the floor's world y.
+ *
+ * Two rules in one expression. Along its OWN direction each axis follows the
+ * target, which is the identity on the infinite line it stands for, so no pan
+ * reaches an end and nothing appears to slide. Across the other two it takes
+ * the FLOOR, not zero — the world origin here is the canvas centre, half a
+ * frame height up, and axes placed there hang in mid-air above the grid
+ * instead of crossing it. The vertical axis needs no y of its own: it meets
+ * the floor at that same point on the way through.
+ */
+export function axisOrigin(
+  axis: 0 | 1 | 2,
+  target: readonly [number, number, number],
+  floorY: number,
+): [number, number, number] {
+  return [axis === 0 ? target[0] : 0, axis === 1 ? target[1] : floorY, axis === 2 ? target[2] : 0];
+}