@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/gizmoMath.ts

@@ -14,6 +14,7 @@
 // `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 { borderDistance } from "./frustumGeometry.js";
 import { presetWorkingView, viewBasis } from "./workingView.js";
 import type { WorkingView, WorkingViewPreset } from "./workingView.js";
 import type { ModalState } from "./modalState.js";
@@ -46,20 +47,53 @@ export const DESIGN_AXES: readonly {
   { 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
+/**
+ * Every handle the transform gizmo can be grabbed by, as ONE name.
+ *
+ * A single string rather than a `{kind, axis}` pair because every consumer
+ * wants it whole: the hover field compares it, the draw pass keys the active
+ * one off it, and the hit table is an ordered list of them. `screen` carries no
+ * axis at all — it is the view-plane disc — which is exactly the shape a pair
+ * would have had to fake with a null.
+ */
+export type GizmoHandleId =
+  | `axis:${DesignAxis}`
+  | `plane:${DesignAxis}`
+  | `arc:${DesignAxis}`
+  | "screen";
+
+/** The design axis a handle names, or null for the view-plane disc. A `plane:`
+ *  or `arc:` handle names its own NORMAL, so `plane:z` is the pad the author
+ *  drags in x and y and `arc:z` is the ring they turn IN that plane. */
+export function gizmoAxisOf(handle: GizmoHandleId): DesignAxis | null {
+  if (handle === "screen") return null;
+  return handle.slice(handle.indexOf(":") + 1) as DesignAxis;
+}
+
+/** What a press on one of the gizmo's handles turned out to be. Plain arrays
+ *  and a name, 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
+ *  the handles 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;
+  handle: GizmoHandleId;
   origin: Vec3;
+  /**
+   * ONE world vector, meaning what the handle needs it to mean: an `axis:`
+   * arm's own direction, or the NORMAL of the plane a `plane:` pad and the
+   * `screen` disc unproject onto.
+   *
+   * Two fields would be one field always null — an arm solves a LINE
+   * (`axisParam`, so the grabbed arm stays under the cursor) and a pad solves a
+   * PLANE (`designDelta`), and neither solve has any use for the other's
+   * vector.
+   */
   direction: Vec3;
 }
 
@@ -105,6 +139,21 @@ export function framingArmDelta(
   return { dx: 0, dy: 0, dzoom: t0 / t };
 }
 
+/**
+ * The camera's roll arc, as the framing delta a swept angle means.
+ *
+ * An arc measures an ANGLE where an arm measures travel, so it is its own
+ * function rather than a fourth axis of `framingArmDelta`. The sign is the
+ * layer arc's own: the drawn camera turns WITH the pointer around its ring, the
+ * way a layer does around its `arc:z` — the modal negates for the camera because
+ * it measures the picture in the camera pane, where a clockwise roll of the
+ * camera turns the picture the other way; this arc is drawn around the camera
+ * object, so no negation.
+ */
+export function framingArcDelta(angleDeg: number): FramingDelta {
+  return { dx: 0, dy: 0, dzoom: 1, droll: Number.isFinite(angleDeg) ? angleDeg : 0 };
+}
+
 function dot(a: Vec3, b: Vec3): number {
   return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 }
@@ -159,6 +208,61 @@ export function viewForBall(view: WorkingView, ball: NavBall): WorkingView {
   return presetWorkingView(view, ball.preset);
 }
 
+/** Below this a middle-press has no direction to read: the author has not
+ *  committed to a way yet, and picking an axis for them would be a guess. In
+ *  screen px of accumulated travel. */
+export const MIN_AUTO_CONSTRAIN_PX = 8;
+
+/**
+ * Below this an axis is too FORESHORTENED to be what a screen drag meant.
+ *
+ * An axis pointing near the camera projects to almost nothing, so its screen
+ * direction is noise — every drag is "close to" it because it barely has a
+ * direction at all. `navBalls` keeps the foreshortening in the vector's length
+ * for exactly this reason (it is the nav gizmo's own depth cue), so the test is
+ * a length test.
+ */
+const MIN_AXIS_PROJECTION = 0.2;
+
+/**
+ * The design axis a screen drag was heading along, or null.
+ *
+ * Blender's middle-mouse AUTO-CONSTRAIN: the author drags a little way, taps
+ * the middle button, and the transform locks to whichever axis they were
+ * already going along. This is that choice, and it is `navBalls`' projection
+ * re-read — the same three dot products the corner gizmo draws itself from, so
+ * the axis the widget shows pointing that way IS the axis this picks.
+ *
+ * Null when the travel is too short to have a direction, or when the best axis
+ * is too foreshortened to have one either. Refusing beats locking to an axis
+ * the author did not mean, which costs an undo to get out of.
+ */
+export function autoConstrainAxis(
+  view: WorkingView,
+  dx: number,
+  dy: number,
+): DesignAxis | null {
+  const length = Math.hypot(dx, dy);
+  if (!(length >= MIN_AUTO_CONSTRAIN_PX)) return null;
+  let best: DesignAxis | null = null;
+  let bestScore = 0;
+  for (const ball of navBalls(view)) {
+    // The POSITIVE end alone: an axis and its opposite are one line, and a drag
+    // "along x" is along x whichever way it points.
+    if (!ball.positive) continue;
+    const axisLength = Math.hypot(ball.x, ball.y);
+    if (axisLength < MIN_AXIS_PROJECTION) continue;
+    // |cos| between the drag and the axis, so either direction along the axis
+    // scores the same.
+    const score = Math.abs((ball.x * dx + ball.y * dy) / (axisLength * length));
+    if (score > bestScore) {
+      bestScore = score;
+      best = ball.axis;
+    }
+  }
+  return best;
+}
+
 /**
  * How far along an axis line the closest point to a ray sits.
  *
@@ -199,12 +303,11 @@ const MIN_AXIS_DENOM = 1e-6;
  * 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.
+ * There used to be a second question here, an apex clearance for the camera's
+ * arms: the frustum's apex had its own 14 px grab tested AFTER the arms, and
+ * an arm rooted inside that radius took every press aimed at the dolly. The
+ * apex grab is gone (the Z arm IS the dolly, and the camera body's grab is
+ * tested after the arms too), so the length rule is the whole gate again.
  *
  * 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
@@ -213,14 +316,403 @@ const MIN_AXIS_DENOM = 1e-6;
 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;
+  return Math.hypot(tip[0] - root[0], tip[1] - root[1]) >= minLengthPx;
+}
+
+/**
+ * The gizmo's shape, in CSS px, HELD CONSTANT as the author dollies.
+ *
+ * World-space sizes would be a gizmo that fills the pane up close and vanishes
+ * far out — and, because every hit test below is in screen px, one whose grab
+ * target changed size with the zoom.
+ *
+ * ── THE PROPORTIONS ARE DREI'S ──────────────────────────────────────────
+ *
+ * `arrowHead`, `padAt` and `pad` are `@react-three/drei` 10.7.7's PivotControls
+ * numbers, restated here as fractions of `arm` and rounded to whole pixels:
+ * `AxisArrow.js`'s `coneLength = 0.2`, `PlaneSlider.js`'s `pos1 * 1.7 = 1.7/7`
+ * and `length = 0.225`. MIT, same vendoring the player's `view.tsx` did with
+ * that release, and for the same reason — the shapes are tuned and the tuning
+ * is the part worth having. NONE OF DREI'S CODE IS USED: its shafts and arcs
+ * are `Line2`/`LineMaterial` (a GLSL `ShaderMaterial`), which is dead on the
+ * WebGPU backend and silently so; its hit-testing is r3f events, which this
+ * stage does not run; and its hover is React state under a `frameloop="never"`
+ * canvas, which cannot repaint. See docs and the plan for the full account.
+ */
+export const GIZMO_PX = {
+  /** An arm's tip, measured from the anchor. */
+  arm: 90,
+  /**
+   * Where an arm STARTS.
+   *
+   * It has to clear the anchor by more than BOTH slops added together. On the
+   * camera the anchor is the eye, the centre of the camera body's own grab box
+   * (`BODY_GRAB_PX`, frustumGeometry.ts), which the pointer lane tests AFTER
+   * the arms: the arms win where they overlap it, and a start inside the box's
+   * slop would leave no press near the eye that reached the body at all.
+   *
+   * 30 > 14 + 14. It also keeps the three roots from piling into one ambiguous
+   * blob, which is why the layer gizmo wants it too.
+   */
+  armStart: 30,
+  /** Shaft radius. Thin enough to read as a line, thick enough to be a solid. */
+  shaft: 1.5,
+  /** Arrowhead length — drei's 0.2 of the arm. */
+  arrowHead: 18,
+  /** Arrowhead radius. */
+  arrowWidth: 5,
+  /** A plane pad's centre, on both of its two axes — drei's 1.7/7 of the arm. */
+  padAt: 22,
+  /** A plane pad's side — drei's 0.225 of the arm. */
+  pad: 20,
+  /**
+   * A rotate arc's radius — drei's 0.65 of the arm.
+   *
+   * INSIDE the arrowheads on purpose. A quarter arc between two axes crosses
+   * both of the arms that bound it, and the hit table ranks arms above arcs, so
+   * the two crossings belong to the arms and the 80% of the arc between them is
+   * the author's. That is drei's own layout and Blender's; a ring at the arm's
+   * full length would cross the cones instead, where the arm is widest.
+   */
+  arc: 58,
+  /**
+   * How close a press has to land to an ARC.
+   *
+   * Tighter than an arm's 14. An arc is a curve crossing three other handles'
+   * neighbourhoods, and every px of slop is a px it takes from one of them —
+   * whereas an arm is a straight run through empty space.
+   */
+  arcGrab: 9,
+  /** The view-plane disc's radius. Inside `padAt` less half a pad, so the disc
+   *  and the three pads do not overlap and the hit order never has to arbitrate
+   *  between them. */
+  screen: 11,
+  /** How close a press has to land to an ARM, in CSS px. The frustum's own 14 —
+   *  a line is a line, and the author's finger is the same size in both. */
+  grab: 14,
+} as const;
+
+/**
+ * How long an arm's DRAWN segment must be, on screen, to answer a press.
+ *
+ * `armStart` and `arm` 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. A press within `grab` of that point would grab it, `axisParam` would
+ * divide by a zero denominator and answer null, and the press would open no
+ * scrub and do nothing at all — under a line that looked grabbable.
+ */
+export const MIN_ARM_SCREEN_PX = GIZMO_PX.grab * 2;
+
+/**
+ * The two design axes a plane pad SPANS, given the one it is normal to.
+ *
+ * By filter rather than by cross product, so the pair is stable and stated in
+ * the table's own order — which is what lets the drawn pad and its hit quad be
+ * built from the same two vectors, in the same order, and therefore be the same
+ * square. A cross product would answer a correct plane with an arbitrary
+ * in-plane rotation, and the mismatch would be invisible until an author
+ * pressed the corner of a pad and got the arm underneath it.
+ */
+export function padAxes(axis: DesignAxis): readonly [Vec3, Vec3] {
+  const rest = DESIGN_AXES.filter((a) => a.axis !== axis);
+  return [rest[0]!.world, rest[1]!.world];
+}
+
+/** A point `distance` along a unit direction from an anchor. */
+export function alongAxis(from: Vec3, direction: Vec3, distance: number): Vec3 {
+  return [
+    from[0] + direction[0] * distance,
+    from[1] + direction[1] * distance,
+    from[2] + direction[2] * distance,
+  ];
+}
+
+/**
+ * A plane pad's four world corners, wound consistently.
+ *
+ * `at` is the centre's offset along BOTH of its axes and `half` is half its
+ * side, both already in world units. Wound so `pointInQuad`'s sign test sees a
+ * convex quad however the projection flips it.
+ *
+ * ONE function for the drawing and the hit test. They had drifted apart at the
+ * first attempt: the mesh took its rotation from `setFromUnitVectors`, which
+ * lands the square at whatever in-plane angle the shortest rotation happens to
+ * give, while the hit quad was built from `padAxes`. Same plane, different
+ * square — a handle whose corners answer no press.
+ */
+export function padCorners(centre: Vec3, axis: DesignAxis, at: number, half: number): Vec3[] {
+  const [u, v] = padAxes(axis);
+  return PAD_SIGNS.map(([su, sv]) => [
+    centre[0] + u[0] * (at + su * half) + v[0] * (at + sv * half),
+    centre[1] + u[1] * (at + su * half) + v[1] * (at + sv * half),
+    centre[2] + u[2] * (at + su * half) + v[2] * (at + sv * half),
+  ]);
+}
+
+/** A plane pad's world centre. */
+export function padCentre(centre: Vec3, axis: DesignAxis, at: number): Vec3 {
+  const [u, v] = padAxes(axis);
+  return [
+    centre[0] + (u[0] + v[0]) * at,
+    centre[1] + (u[1] + v[1]) * at,
+    centre[2] + (u[2] + v[2]) * at,
+  ];
+}
+
+/** The four corners as signed half-widths on the pad's two axes, wound. */
+const PAD_SIGNS: readonly (readonly [number, number])[] = [
+  [-1, -1],
+  [1, -1],
+  [1, 1],
+  [-1, 1],
+];
+
+/**
+ * The shoelace area of a projected polygon, unsigned.
+ *
+ * `armGrabbable`'s claim in the units a quad has: a pad seen EDGE-ON projects
+ * to a sliver no press can land inside, and its plane is grazing enough that
+ * `designDelta` would answer a wild number if one did.
+ */
+export function screenArea(corners: readonly (readonly [number, number])[]): number {
+  let sum = 0;
+  for (let i = 0; i < corners.length; i++) {
+    const [ax, ay] = corners[i]!;
+    const [bx, by] = corners[(i + 1) % corners.length]!;
+    sum += ax * by - bx * ay;
+  }
+  return Math.abs(sum) / 2;
+}
+
+/**
+ * The smallest projected pad, in square screen px, that can answer a press.
+ *
+ * A tenth of the pad drawn face-on (20 x 20 = 400) — well past the sliver and
+ * well short of anything a working pad reaches.
+ */
+export const MIN_PAD_SCREEN_AREA = 40;
+
+type Pt = readonly [number, number];
+
+/**
+ * One thing on screen a press can land on, already projected.
+ *
+ * Screen geometry and not world, because that is where the question is asked:
+ * "is the cursor on this handle" is a question about pixels, and asking it in
+ * world units makes a grab target that shrinks as the author dollies out.
+ */
+export interface GizmoTarget {
+  handle: GizmoHandleId;
+  origin: Vec3;
+  direction: Vec3;
+  shape:
+    /** An arm (two points) or an arc (many). `borderDistance` walks a CLOSED
+     *  polygon, so a two-point path is that one segment measured twice — the
+     *  point-to-segment distance — and an open arc is measured with one extra
+     *  chord from its last point back to its first, which lies well outside
+     *  the slop and therefore never wins. */
+    | { type: "path"; points: readonly Pt[]; slop: number }
+    | { type: "quad"; corners: readonly Pt[] }
+    | { type: "disc"; at: Pt; radius: number };
+}
+
+/**
+ * The FIRST target that contains a point, in the order it was handed.
+ *
+ * ── AN ORDER, NOT A NEAREST-WINS ────────────────────────────────────────
+ *
+ * With three arms and nothing else, "closest segment within 14px" was a
+ * complete answer. It stops being one the moment handles overlap: a plane pad
+ * SITS ON the two arms that bound it, and a nearest-wins test would give the
+ * pad's interior to whichever arm's centreline happened to be nearer, which is
+ * a handle that is drawn and never grabbed.
+ *
+ * So priority is declared — smallest and innermost first, which is the only
+ * order in which every handle stays reachable (the disc is inside the pads, the
+ * pads are inside the arms' span) — and each target carries its own exact
+ * shape rather than a distance. Ordering is the ARRAY's, so the one place it
+ * lives is where the targets are built, and it is checkable here without a GL
+ * context.
+ *
+ * The apex and the frustum's border are deliberately NOT in this list: they
+ * belong to `feed.frustumHit`, which `intentAt` ranks below `feed.grabAt` with
+ * a layer veto on the body. Folding them in here would rank them above both.
+ */
+export function gizmoHitAt(
+  targets: readonly GizmoTarget[],
+  x: number,
+  y: number,
+): GizmoTarget | null {
+  for (const target of targets) {
+    const shape = target.shape;
+    if (shape.type === "path") {
+      if (borderDistance(x, y, shape.points) <= shape.slop) return target;
+      continue;
+    }
+    if (shape.type === "quad") {
+      if (pointInQuad(x, y, shape.corners)) return target;
+      continue;
+    }
+    if (Math.hypot(shape.at[0] - x, shape.at[1] - y) <= shape.radius) return target;
+  }
+  return null;
+}
+
+/**
+ * Is a point inside a projected convex polygon?
+ *
+ * The cross product of each edge with the point-to-vertex vector keeps one sign
+ * all the way round a convex polygon, and flips somewhere on a point outside
+ * it. Winding-agnostic (either sign is accepted, as long as it is consistent),
+ * because a plane pad seen from behind projects the other way round and it is
+ * still the same pad.
+ *
+ * A zero cross means the point is ON that edge, which counts as inside — the
+ * alternative is a one-pixel dead line down the middle of a handle.
+ */
+export function pointInQuad(x: number, y: number, corners: readonly Pt[]): boolean {
+  if (corners.length < 3) return false;
+  let sign = 0;
+  for (let i = 0; i < corners.length; i++) {
+    const [ax, ay] = corners[i]!;
+    const [bx, by] = corners[(i + 1) % corners.length]!;
+    const cross = (bx - ax) * (y - ay) - (by - ay) * (x - ax);
+    if (cross === 0) continue;
+    const next = cross > 0 ? 1 : -1;
+    if (sign === 0) sign = next;
+    else if (sign !== next) return false;
+  }
+  return true;
+}
+
+/**
+ * A rotate arc's world points: a QUARTER turn in the plane normal to `axis`,
+ * running from that plane's first design axis round to its second.
+ *
+ * A quarter and not a full ring, which is drei's PivotControls layout and
+ * Blender's: three full rings at one radius make a sphere of lines over exactly
+ * the geometry the author is judging, and each one crosses the other two twice.
+ * A quarter arc per axis says the same thing — "turn about this" — inside one
+ * octant, and leaves the rest of the view clear.
+ *
+ * `segments` points, so an arc of 24 is 24 chords; the projected polyline IS
+ * the hit shape (`gizmoHitAt`), so the drawing and the grab are the same curve
+ * by construction rather than by two matching formulas.
+ */
+/** Chords per quarter arc. Enough that the polyline reads as a curve at the
+ *  radius it is drawn at, and that the hit test's own chords never sit further
+ *  than a fraction of `arcGrab` inside the true circle. */
+export const ARC_SEGMENTS = 24;
+
+export function arcPoints(
+  centre: Vec3,
+  axis: DesignAxis,
+  radius: number,
+  segments: number,
+): Vec3[] {
+  const [u, v] = padAxes(axis);
+  const out: Vec3[] = [];
+  for (let i = 0; i <= segments; i++) {
+    const t = (i / segments) * (Math.PI / 2);
+    const cos = Math.cos(t) * radius;
+    const sin = Math.sin(t) * radius;
+    out.push([
+      centre[0] + u[0] * cos + v[0] * sin,
+      centre[1] + u[1] * cos + v[1] * sin,
+      centre[2] + u[2] * cos + v[2] * sin,
+    ]);
+  }
+  return out;
+}
+
+/**
+ * Where a point sits round a rotate arc, in radians, measured IN THE ARC'S OWN
+ * PLANE.
+ *
+ * ── WHY NOT A SCREEN-SPACE `atan2` ──────────────────────────────────────
+ *
+ * The camera-pane roll ring can use one, because that ring is drawn in screen
+ * space and the rotation it drives is about the view axis. A working-pane arc
+ * is a circle in the WORLD seen at an angle, so it projects to an ellipse: a
+ * screen angle runs fast across the ellipse's narrow axis and slow across its
+ * wide one, and the grabbed point slides out from under the cursor exactly
+ * where the author can see it doing so.
+ *
+ * Two dot products against the plane's own basis instead — the same solve
+ * `@react-three/drei` 10.7.7's `AxisRotator.calculateAngle` performs (MIT), and
+ * for the same reason.
+ */
+export function ringAngle(centre: Vec3, axis: DesignAxis, point: Vec3): number {
+  const [u, v] = padAxes(axis);
+  const dx = point[0] - centre[0];
+  const dy = point[1] - centre[1];
+  const dz = point[2] - centre[2];
+  return Math.atan2(
+    dx * v[0] + dy * v[1] + dz * v[2],
+    dx * u[0] + dy * u[1] + dz * u[2],
+  );
+}
+
+/**
+ * The representative of `delta` (an angle that has been wrapped into a single
+ * turn) nearest `total`.
+ *
+ * ── WHAT THIS IS FOR, AND WHY IT IS NOT A DRIFT ─────────────────────────
+ *
+ * `ringAngle`'s difference lives in (-PI, PI], so a sweep past half a turn
+ * comes back as a rotation the other way and a sweep past a full turn comes
+ * back as zero — the author drags round and the layer springs back. Blender
+ * counts turns; so does this.
+ *
+ * The count is path-dependent, which is the ONLY path-dependent quantity a
+ * gesture in this editor carries, and it has to be: "how many times round" is
+ * not recoverable from the pointer's current position. What is emitted is still
+ * a TOTAL from the press, so the store's re-derive-from-base, one-undo-entry
+ * and exact-Escape properties all hold unchanged — see `advanceVirtual`, whose
+ * accumulation is path-dependent for the same reason and with the same result.
+ */
+export function unwrapTurns(total: number, delta: number): number {
+  const turn = Math.PI * 2;
+  if (!Number.isFinite(total) || !Number.isFinite(delta)) return delta;
+  return delta + Math.round((total - delta) / turn) * turn;
+}
+
+/**
+ * The constraint axis, as the long screen segment Blender draws through the
+ * pivot while a transform is locked to it.
+ *
+ * ── WHY IT IS DONE IN SCREEN SPACE ──────────────────────────────────────
+ *
+ * A perspective projection maps a 3D line to a 2D line, so the image of the
+ * whole axis IS the screen line through the projected anchor with the projected
+ * direction. Extending two world points to ±infinity and projecting those
+ * instead means clipping them against the camera's near plane first, since a
+ * point behind the eye projects to a mirrored ghost — real work, for the same
+ * segment.
+ *
+ * `towards` is any second point on the axis, ahead of it on screen; only the
+ * direction is used. Null when the two project to the same pixel, which is an
+ * axis pointing at the camera — the arm is already refusing presses in that
+ * pose (`armGrabbable`), and a guide line with no direction would be a random
+ * one.
+ */
+export function axisGuide(
+  at: Pt,
+  towards: Pt,
+  reach: number,
+): { a: [number, number]; b: [number, number] } | null {
+  const dx = towards[0] - at[0];
+  const dy = towards[1] - at[1];
+  const length = Math.hypot(dx, dy);
+  if (!(length > 1e-6) || !Number.isFinite(reach)) return null;
+  const ux = (dx / length) * reach;
+  const uy = (dy / length) * reach;
+  return { a: [at[0] - ux, at[1] - uy], b: [at[0] + ux, at[1] + uy] };
 }
 
 export function axisParam(