@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/FrustumGizmo.tsx

@@ -14,7 +14,22 @@
 //      it and layer picking cannot return it.
 //
 // It also touches no document. Everything it draws is a pure function of the
-// resolved rig, which is a pure function of (document, frame).
+// resolved rig (or of the camera a component drove), which is a pure function
+// of (document, frame).
+//
+// ── TWO BUFFERS: THE BODY AND THE REACH ─────────────────────────────────
+//
+// The BODY is the camera as an object: a short lens pyramid in front of the eye,
+// a box behind it, the up-marker on the lens. Its size is fixed against the
+// SCENE (frustumGeometry's `cameraDisplayLength`), clamped in screen px, so it
+// reads as one more object in the world rather than a thing that grows as the
+// author backs away. It is drawn for the rig and for a driven camera alike.
+//
+// The REACH is the document's model: the four long edges from the eye to the
+// framed rectangle at the design plane, and that rectangle. It is what is in
+// shot, from any angle, and the rig case alone has it (a driven camera has no
+// plane to land on). Dimmer than the body, so the body reads as the camera and
+// the reach as its sightline.
 //
 // ── WHY THE MATERIAL REFUSES THE OVERRIDE ───────────────────────────────
 //
@@ -25,47 +40,42 @@
 //
 // ── AND WHY THE COLOUR IS READ FROM CSS ─────────────────────────────────
 //
-// It is a MATERIAL colour, not a GL clear colour, and it is resolved once at
-// mount inside the stage document — which imports shotTokens.css. So `--frustum`
-// stays the single definition both documents share, and the overlay could draw
-// the same yellow tomorrow without a second literal. (SplitRenderer's clay is
-// hard-coded for the opposite reason: a clear colour is written before any
-// style has resolved.)
-import { useEffect, useMemo } from "react";
-import { useFrame } from "@react-three/fiber";
-import {
-  BufferAttribute,
-  BufferGeometry,
-  LineSegments,
-  Vector3,
-} from "three";
+// It is a MATERIAL colour, not a GL clear colour, and it is resolved inside the
+// stage document, which imports shotTokens.css, whenever appearance changes.
+// So `--frustum` stays the single definition both documents share, and the
+// overlay could draw the same yellow tomorrow without a second literal.
+import { useEffect, useMemo, useRef } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { Box3, BufferAttribute, BufferGeometry, LineSegments, Vector3 } from "three";
+import type { Quaternion } from "three";
 import { LineBasicNodeMaterial } from "three/webgpu";
 import { EDITOR_LAYER } from "./StageTools.js";
 import { tokenColor } from "./tokenColor.js";
+import type { StageTheme } from "./stageTheme.js";
 import {
-  FRUSTUM_SEGMENT_FLOATS,
+  BODY_GRAB_PX,
+  CAMERA_BODY_SEGMENT_FLOATS,
+  FRAME_SEGMENT_FLOATS,
   borderDistance,
-  frustumSegments,
+  cameraBodySegments,
+  cameraBodyShape,
+  cameraDisplayLength,
+  frameSegments,
   frustumShape,
+  isDriven,
+  rigPose,
   segmentsMoved,
+  waypointCrossSize,
+  waypointSegmentFloats,
+  waypointSegments,
 } from "./frustumGeometry.js";
-import type { CameraRig } from "./frustumGeometry.js";
-import { toScreen } from "./project.js";
+import type { CameraPose, CameraRig } from "./frustumGeometry.js";
+import { toScreen, worldPerPixel } from "./project.js";
+import { sceneExtent } from "./sceneExtent.js";
 import type { StageFeed } from "./feed.js";
 import type { PaneRect } from "./panes.js";
 import type { FrameSize } from "./view.js";
 
-/** How close a press has to land to the apex to grab it, in CSS px. Larger
- *  than the layer handles' 10: the apex is a single point with no box around
- *  it, and it is the only way to reach the zoom. */
-export const APEX_GRAB_PX = 14;
-
-/** How close a press has to land to the base rectangle's DRAWN border to grab
- *  the body. The interior is deliberately not a grab target — see
- *  `borderDistance` for why an interior claim takes the whole pane away — so
- *  the border is a line, and it gets the same slop the apex point does. */
-const BODY_GRAB_PX = 14;
-
 /** Over everything. Every material in this lane draws with `depthTest: false`,
  *  so paint order is `renderOrder` alone (ShotRuntime's header) — a gizmo that
  *  shared the layers' range would be hidden by whichever layer sorted after it. */
@@ -73,112 +83,522 @@ const FRUSTUM_RENDER_ORDER = 1_000_000;
 
 const FRUSTUM_FALLBACK = "#eab308";
 
+/** How far the reach sits below the body: the sightline reads as belonging to
+ *  the camera without competing with it. */
+const REACH_OPACITY = 0.55;
+
+/** How far a hovered gizmo blends towards the theme's contrast ink — the move
+ *  arms' own tint, so the two widgets in this pane light up by the same amount
+ *  and neither reads as the more active one. */
+const HOVER_TINT = 0.45;
+
+/** How many committed frames a driven scene's bounds are trusted for before
+ *  the walk runs again. A flythrough moves objects, but the ground and the
+ *  architecture bound the world; a change between refreshes is a sub-pixel
+ *  pop in the body's size, not a wrong drawing. */
+const EXTENT_REFRESH_FRAMES = 60;
+
+/** The lens rectangle stays in front of the design plane: this far along the
+ *  rig's own distance at most. */
+const REACH_CAP_FRACTION = 0.9;
+
 /** Scratch for the border test's behind-camera check. */
 const _view = new Vector3();
 
+/**
+ * AFTER EVERY CAMERA WRITER. `ShotCamera` puts the render camera on the rig at
+ * priority 0, and an instance component that drives the camera itself writes
+ * below that (fiber sorts a phase's priorities DESCENDING, so lower runs
+ * later). The gizmo reads the camera after all of them, so it draws the
+ * camera the pane is about to render with and not the one the rig proposed.
+ */
+const AFTER_CAMERA_WRITERS = -1000;
+
+/** Scratch for reading the render camera's basis. */
+const _eye = new Vector3();
+const _right = new Vector3();
+const _up = new Vector3();
+const _forward = new Vector3();
+const _pose: CameraPose = { eye: [0, 0, 0], right: [1, 0, 0], up: [0, 1, 0], forward: [0, 0, -1], fovDeg: 35 };
+/** Scratch for the bounds walk, and its centre. */
+const _bounds = new Box3();
+const _centre = new Vector3();
+
+/** The render camera's pose, or null when it is not a perspective camera. */
+function readPose(camera: object): CameraPose | null {
+  const cam = camera as {
+    isPerspectiveCamera?: boolean;
+    fov: number;
+    position: Vector3;
+    quaternion: Quaternion;
+  };
+  if (cam.isPerspectiveCamera !== true) return null;
+  _eye.copy(cam.position);
+  _right.set(1, 0, 0).applyQuaternion(cam.quaternion);
+  _up.set(0, 1, 0).applyQuaternion(cam.quaternion);
+  _forward.set(0, 0, -1).applyQuaternion(cam.quaternion);
+  _pose.eye = [_eye.x, _eye.y, _eye.z];
+  _pose.right = [_right.x, _right.y, _right.z];
+  _pose.up = [_up.x, _up.y, _up.z];
+  _pose.forward = [_forward.x, _forward.y, _forward.z];
+  _pose.fovDeg = cam.fov;
+  return _pose;
+}
+
+/** How close a press has to land to a waypoint's centre to grab it, in CSS px.
+ *  A point with no box around it gets the body's own slop. */
+export const WAYPOINT_GRAB_PX = 14;
+
+/** The eyes of the path move under the playhead, if there is one. */
+export interface WaypointMarks {
+  shotId: string;
+  eyes: readonly [number, number, number][];
+}
+
 export interface FrustumGizmoProps {
+  /** Resolved editor theme. It rebuilds only the token-backed GL material. */
+  theme: StageTheme;
   feed: StageFeed;
   panes: { working: PaneRect | null; camera: PaneRect | null };
-  /** The camera as resolved at the playhead. Null when no scene is on screen. */
-  rig: CameraRig | null;
+  /** The camera rig at the clock's frame, read at FRAME time (StageApp's
+   *  `playhead`), or null when nothing is on screen. */
+  rigAt: () => CameraRig | null;
   frame: FrameSize;
+  /**
+   * The waypoints to draw and to make grabbable, or null.
+   *
+   * Null whenever the playhead is not inside a PATH move — the same rule the
+   * frustum follows about which camera it draws. Computed by the host because
+   * it holds the document; this component only ever draws what it is handed.
+   */
+  waypointsAt: () => WaypointMarks | null;
+  /**
+   * The component that has CLAIMED the render camera (the runtime's
+   * `useClaimStageCamera`), read at frame time, or null. A claim beats the
+   * float comparison `offTheRig` makes, and it brings the component's own
+   * extent for the body's size.
+   */
+  driverAt: () => { name: string; extent?: number } | null;
+  /**
+   * Who drives the camera, pushed ON CHANGE: the claim's name, "a component"
+   * for an unclaimed writer the float comparison caught, or null for the rig.
+   * The stage relays it to the chrome (`onCameraDriver`).
+   */
+  onDriver: (name: string | null) => void;
+}
+
+/** One line buffer: allocated once, rewritten in place. `rest` is its opacity
+ *  when nothing holds the camera; a held camera draws at a fraction of it. */
+interface Lines {
+  lines: LineSegments;
+  geometry: BufferGeometry;
+  material: LineBasicNodeMaterial;
+  tint: number;
+  rest: number;
+  opacity: number;
+}
+
+/** How far a HELD camera fades: the fork would refuse a drag on it (a finished
+ *  move with Animate off, a path), and the dimming says so before the press. */
+const HELD_OPACITY = 0.4;
+
+function newLines(floats: number, opacity: number): Lines {
+  const geometry = new BufferGeometry();
+  geometry.setAttribute("position", new BufferAttribute(new Float32Array(floats), 3));
+  const material = new LineBasicNodeMaterial();
+  material.color.copy(tokenColor("--frustum", FRUSTUM_FALLBACK));
+  material.depthTest = false;
+  material.depthWrite = false;
+  material.toneMapped = false;
+  // See the header: the working pane renders under a clay override.
+  material.allowOverride = false;
+  // Always transparent, so the held fade is one `opacity` write and not a
+  // material recompile the first time the playhead crosses into a move.
+  material.transparent = true;
+  material.opacity = opacity;
+  const lines = new LineSegments(geometry, material);
+  lines.layers.set(EDITOR_LAYER);
+  lines.renderOrder = FRUSTUM_RENDER_ORDER;
+  // The vertices are WORLD positions rewritten in place, so the object stays
+  // at the origin and the bounding sphere the culler would test is never the
+  // one the buffer holds. Culling it against a stale sphere makes the gizmo
+  // vanish at some orbits and not others.
+  lines.frustumCulled = false;
+  lines.matrixAutoUpdate = false;
+  return { lines, geometry, material, tint: 0, rest: opacity, opacity };
+}
+
+function fadeTo(target: Lines, held: boolean): void {
+  const want = held ? target.rest * HELD_OPACITY : target.rest;
+  if (target.opacity === want) return;
+  target.opacity = want;
+  target.material.opacity = want;
+}
+
+/** Rewrite a buffer only when a vertex moved by more than `epsilon`: this runs
+ *  on every committed frame, and a parked playhead must not re-upload. */
+function write(target: Lines, next: number[], epsilon: number): void {
+  const attribute = target.geometry.getAttribute("position") as BufferAttribute;
+  const buffer = attribute.array as Float32Array;
+  if (segmentsMoved(buffer, next, epsilon)) {
+    buffer.set(next);
+    attribute.needsUpdate = true;
+  }
+}
+
+function tintTo(target: Lines, want: number, hot: ReturnType<typeof tokenColor>): void {
+  if (target.tint === want) return;
+  target.tint = want;
+  target.material.color.copy(tokenColor("--frustum", FRUSTUM_FALLBACK)).lerp(hot, want);
+}
+
+function newPoints(n: number): Vector3[] {
+  return Array.from({ length: n }, () => new Vector3());
 }
 
-export function FrustumGizmo({ feed, panes, rig, frame }: FrustumGizmoProps) {
-  const gizmo = useMemo(() => {
+export function FrustumGizmo({
+  theme,
+  feed,
+  panes,
+  rigAt,
+  frame,
+  waypointsAt,
+  driverAt,
+  onDriver,
+}: FrustumGizmoProps) {
+  /** The last driver name pushed, so the relay fires on change only. */
+  const pushedDriver = useRef<string | null>(null);
+  // The camera the camera pane renders with. On the rig it is where `rigAt`
+  // says; a component that drives it moves it off the rig, and then THIS is
+  // the camera the picture came from.
+  const renderCamera = useThree((s) => s.camera);
+  const scene = useThree((s) => s.scene);
+  const hotColor = useMemo(
+    () => tokenColor("--gizmo-hot", theme === "light" ? "#1c1c1c" : "#ffffff"),
+    [theme],
+  );
+  const body = useMemo(() => newLines(CAMERA_BODY_SEGMENT_FLOATS, 1), [theme]);
+  const reach = useMemo(() => newLines(FRAME_SEGMENT_FLOATS, REACH_OPACITY), [theme]);
+  // The hit-test geometry, kept as three vectors so the screen test allocates
+  // nothing: the twelve body points (lens rectangle, then the box) and the
+  // framed rectangle's four corners.
+  const hit = useMemo(() => ({ body: newPoints(12), quad: newPoints(4) }), []);
+
+  // ── THE WAYPOINT MARKS ────────────────────────────────────────────────────
+  //
+  // A SECOND object rather than more segments in the body's buffer, and the
+  // reason is the count: the body has 23 segments always, so its buffer is
+  // allocated once and rewritten in place. A path has two to a dozen
+  // waypoints, and folding them in would mean reallocating the body's buffer
+  // whenever an author inserted a pose. Separate objects, one allocation each.
+  const marks = useMemo(() => {
     const geometry = new BufferGeometry();
-    geometry.setAttribute(
-      "position",
-      new BufferAttribute(new Float32Array(FRUSTUM_SEGMENT_FLOATS), 3),
-    );
     const material = new LineBasicNodeMaterial();
     material.color.copy(tokenColor("--frustum", FRUSTUM_FALLBACK));
     material.depthTest = false;
     material.depthWrite = false;
     material.toneMapped = false;
-    // See the header: the working pane renders under a clay override.
     material.allowOverride = false;
-
     const lines = new LineSegments(geometry, material);
     lines.layers.set(EDITOR_LAYER);
     lines.renderOrder = FRUSTUM_RENDER_ORDER;
-    // The vertices are WORLD positions rewritten in place, so the object stays
-    // at the origin and the bounding sphere the culler would test is never the
-    // one the buffer holds. Culling it against a stale sphere makes the gizmo
-    // vanish at some orbits and not others.
     lines.frustumCulled = false;
     lines.matrixAutoUpdate = false;
-    return { lines, geometry, material, apex: new Vector3(), quad: newQuad() };
-  }, []);
+    lines.visible = false;
+    return { lines, geometry, material, eyes: [] as Vector3[], sizes: [] as number[], count: -1, tint: 0 };
+  }, [theme]);
 
   useEffect(
     () => () => {
-      gizmo.geometry.dispose();
-      gizmo.material.dispose();
+      body.geometry.dispose();
+      body.material.dispose();
+      reach.geometry.dispose();
+      reach.material.dispose();
+      marks.geometry.dispose();
+      marks.material.dispose();
     },
-    [gizmo],
+    [body, reach, marks],
   );
 
+  /**
+   * The extent of a DRIVEN camera's world: the largest axis of the live
+   * content's bounds, re-walked when the graph's membership changes
+   * (`feed.sceneEpoch`) or every `EXTENT_REFRESH_FRAMES`, whichever comes
+   * first. NaN when the walk found nothing, and the caller falls back to the
+   * frame.
+   *
+   * ponytail: a full traverse per refresh. A component that streams thousands
+   * of separate meshes pays it every 60 frames; a declared extent from the
+   * component (the camera claim) is the upgrade and skips the walk entirely.
+   */
+  const extentCache = useRef({ epoch: -1, frames: 0, value: Number.NaN });
+  const drivenExtent = (): number => {
+    const cache = extentCache.current;
+    if (cache.epoch !== feed.sceneEpoch || cache.frames >= EXTENT_REFRESH_FRAMES) {
+      cache.epoch = feed.sceneEpoch;
+      cache.frames = 0;
+      cache.value = sceneExtent(scene, _bounds);
+    }
+    cache.frames += 1;
+    return cache.value;
+  };
+  const rigExtent = Math.max(frame.width, frame.height);
+
   useFrame(() => {
+    const list = waypointsAt()?.eyes ?? [];
+    if (list.length === 0) {
+      marks.lines.visible = false;
+      feed.waypointHit = null;
+      return;
+    }
+    marks.lines.visible = true;
+    const want = feed.hoverWaypoint === null ? 0 : HOVER_TINT;
+    if (marks.tint !== want) {
+      marks.tint = want;
+      marks.material.color.copy(tokenColor("--frustum", FRUSTUM_FALLBACK)).lerp(hotColor, want);
+    }
+    // REALLOCATE ONLY WHEN THE COUNT CHANGES, which is when a waypoint is
+    // inserted or removed. A drag moves vertices inside a buffer that is
+    // already the right size.
+    if (marks.count !== list.length) {
+      marks.count = list.length;
+      // ── DISPOSE, THEN REBUILD ──────────────────────────────────────────────
+      //
+      // `setAttribute` alone ORPHANS the outgoing attribute's GPU buffer: three
+      // frees an attribute only from the geometry's own dispose listener, which
+      // walks the attributes still ATTACHED at that moment. Replacing one in
+      // place leaves the old buffer alive with nothing pointing at it, and
+      // nothing draws wrong — the only symptom is `renderer.info.memory
+      // .attributes` climbing every time the playhead crosses between two path
+      // moves with different waypoint counts.
+      marks.geometry.dispose();
+      marks.geometry = new BufferGeometry();
+      marks.geometry.setAttribute(
+        "position",
+        new BufferAttribute(new Float32Array(waypointSegmentFloats(list.length)), 3),
+      );
+      marks.lines.geometry = marks.geometry;
+      marks.eyes = list.map(() => new Vector3());
+      marks.sizes = list.map(() => 0);
+    }
+    // The hit-test points follow every frame regardless of the redraw gate,
+    // the same rule the body follows and for the same reason — and each cross
+    // is sized against its OWN screen depth, so a path that runs towards the
+    // author does not end in a mark too small to grab.
+    const camera = feed.workingCamera;
     const working = panes.working;
+    let epsilon = 0.5;
+    for (let i = 0; i < list.length; i++) {
+      const eye = marks.eyes[i]!.set(list[i]![0], list[i]![1], list[i]![2]);
+      const wpp = camera === null || working === null ? 0 : worldPerPixel(camera, eye, working.height);
+      marks.sizes[i] = waypointCrossSize(rigExtent, wpp);
+      if (i === 0 && wpp > 0) epsilon = 0.5 * wpp;
+    }
+    const next = waypointSegments(list, marks.sizes);
+    const attribute = marks.geometry.getAttribute("position") as BufferAttribute;
+    const buffer = attribute.array as Float32Array;
+    if (segmentsMoved(buffer, next, epsilon)) {
+      buffer.set(next);
+      attribute.needsUpdate = true;
+    }
+
+    feed.waypointHit = (x, y) => {
+      if (camera === null || working === null) return null;
+      // NEAREST WINS, and it has to: a path that doubles back puts two eyes
+      // within a grab radius of each other, and answering with whichever came
+      // first in the list would move the one behind the pointer.
+      let best: number | null = null;
+      let bestDistance = WAYPOINT_GRAB_PX;
+      for (let i = 0; i < marks.eyes.length; i++) {
+        const eye = marks.eyes[i]!;
+        // A waypoint BEHIND the working camera projects to garbage, so it is
+        // not on screen to be grabbed.
+        _view.copy(eye).applyMatrix4(camera.matrixWorldInverse);
+        if (_view.z >= 0) continue;
+        const [px, py] = toScreen(eye, camera, working.width, working.height);
+        const distance = Math.hypot(px - x, py - y);
+        if (distance <= bestDistance) {
+          best = i;
+          bestDistance = distance;
+        }
+      }
+      return best;
+    };
+  }, 0);
+
+  useEffect(
+    () => () => {
+      feed.waypointHit = null;
+      feed.hoverWaypoint = null;
+    },
+    [feed],
+  );
+
+  useFrame(() => {
+    const working = panes.working;
+    const rig = rigAt();
     if (rig === null) {
-      gizmo.lines.visible = false;
+      body.lines.visible = false;
+      reach.lines.visible = false;
       feed.frustumHit = null;
+      feed.cameraDriven = false;
+      feed.cameraWorld = null;
+      if (pushedDriver.current !== null) {
+        pushedDriver.current = null;
+        onDriver(null);
+      }
       return;
     }
-    gizmo.lines.visible = true;
+    const camera = feed.workingCamera;
 
-    const shape = frustumShape(rig, frame);
-    const next = frustumSegments(shape);
-    const attribute = gizmo.geometry.getAttribute("position") as BufferAttribute;
-    const buffer = attribute.array as Float32Array;
-    // The 0.5px gate `quadMoved` uses, for the same reason: this runs on every
-    // committed frame, and a parked playhead must not re-upload a buffer.
-    if (segmentsMoved(buffer, next)) {
-      buffer.set(next);
-      attribute.needsUpdate = true;
+    // ── IT LIGHTS UP UNDER THE CURSOR, LIKE THE MOVE ARMS ─────────────────
+    //
+    // Off a plain field the pointer lane wrote (`feed.hoverFrustum`), read
+    // here in the frame loop: one uniform write per change and zero React
+    // renders, the same trade `feed.hoverArm` makes. Both grips pan, so both
+    // buffers light together: one tint is the honest one.
+    const want = feed.hoverFrustum === null ? 0 : HOVER_TINT;
+    tintTo(body, want, hotColor);
+    tintTo(reach, want, hotColor);
+
+    // ── WHOSE CAMERA ───────────────────────────────────────────────────────
+    //
+    // The rig's, unless a component drives the render camera: one that has
+    // CLAIMED it (by name, with its world's extent), or one the float
+    // comparison catches writing it off the rig this frame (a flythrough
+    // writes eye, target and lens itself). Then the body follows the camera
+    // the pane renders with, sized against the component's own world, and
+    // nothing is grabbable: dragging the rig would move nothing the picture
+    // shows.
+    const live = readPose(renderCamera);
+    const driver = driverAt();
+    const driven = isDriven(driver, rig, live);
+    feed.cameraDriven = driven;
+    const driverName = driver?.name ?? (driven ? "a component" : null);
+    if (driverName !== pushedDriver.current) {
+      pushedDriver.current = driverName;
+      onDriver(driverName);
+    }
+    const pose = driven && live !== null ? live : rigPose(rig);
+    // A HELD camera fades: the fork would refuse a drag on it, and the fade is
+    // the cue that says so before the press (the cursor and the pill say why).
+    const held = !driven && feed.cameraGate !== null && feed.cameraGate.kind !== "free";
+    fadeTo(body, held);
+    fadeTo(reach, held);
+
+    // The component's world: its declared extent, or the one the bounds walk
+    // measures; the walk runs either way for the CENTRE, which Home fits to.
+    let extent = rigExtent;
+    if (driven) {
+      const walked = drivenExtent();
+      const declared = driver?.extent;
+      const chosen = declared !== undefined && declared > 0 ? declared : walked;
+      extent = Number.isFinite(chosen) && chosen > 0 ? chosen : rigExtent;
+      if (!_bounds.isEmpty()) {
+        _bounds.getCenter(_centre);
+        feed.cameraWorld = { centre: [_centre.x, _centre.y, _centre.z], extent };
+      } else {
+        feed.cameraWorld = { centre: [pose.eye[0], pose.eye[1], pose.eye[2]], extent };
+      }
+    } else {
+      feed.cameraWorld = null;
     }
+    _eye.set(pose.eye[0], pose.eye[1], pose.eye[2]);
+    const wpp = camera === null || working === null ? 0 : worldPerPixel(camera, _eye, working.height);
+    const length = cameraDisplayLength(
+      extent,
+      wpp,
+      working === null ? 0 : working.height,
+      driven ? Number.POSITIVE_INFINITY : REACH_CAP_FRACTION * rig.distance,
+    );
+    // Half a SCREEN pixel at the eye, both cases: the old half design px gate
+    // was a whole city block for a metre-scale component.
+    const epsilon = wpp > 0 ? 0.5 * wpp : 0.5;
 
-    // The hit-test geometry follows every frame regardless of that gate: half a
+    const shape = cameraBodyShape(pose, length, frame);
+    write(body, cameraBodySegments(shape), epsilon);
+    body.lines.visible = true;
+    // The hit-test geometry follows every frame regardless of the gate: half a
     // pixel of drift is invisible in the drawing and is still the difference
-    // between grabbing the apex and missing it.
-    gizmo.apex.set(shape.apex[0], shape.apex[1], shape.apex[2]);
-    for (let i = 0; i < 4; i++) {
-      gizmo.quad[i]!.set(shape.corners[i]![0], shape.corners[i]![1], shape.corners[i]![2]);
+    // between grabbing the body and missing it.
+    for (let i = 0; i < 4; i++) hit.body[i]!.set(shape.near[i]![0], shape.near[i]![1], shape.near[i]![2]);
+    for (let i = 0; i < 8; i++) hit.body[4 + i]!.set(shape.box[i]![0], shape.box[i]![1], shape.box[i]![2]);
+
+    if (driven) {
+      reach.lines.visible = false;
+      feed.frustumHit = null;
+      return;
     }
+    const far = frustumShape(rig, frame);
+    write(reach, frameSegments(far), epsilon);
+    reach.lines.visible = true;
+    for (let i = 0; i < 4; i++) hit.quad[i]!.set(far.corners[i]![0], far.corners[i]![1], far.corners[i]![2]);
 
     feed.frustumHit = (x, y) => {
-      const camera = feed.workingCamera;
       if (camera === null || working === null) return null;
-      // THE APEX FIRST, and in SCREEN px: it is a point, so a world-space
-      // radius would be a grab target that shrinks as the author dollies out
-      // until it cannot be hit at all.
-      const [ax, ay] = toScreen(gizmo.apex, camera, working.width, working.height);
-      if (Math.hypot(ax - x, ay - y) <= APEX_GRAB_PX) return "apex";
-      // THE BODY BY ITS BORDER, in SCREEN px like the apex and for the same
-      // reason. A corner behind the working camera projects to garbage, so a
-      // quad that is not wholly in front answers null — its border is not on
-      // screen to be grabbed, and the press falls through to the orbit.
+      // THE BODY FIRST, by the screen box its twelve points project to,
+      // inflated by the slop. A small object drawn over the layers wins over
+      // them (the pointer lane keeps its layer veto for the reach alone). A
+      // point behind the working camera projects to garbage, so a body that is
+      // not wholly in front is not on screen to be grabbed.
+      let minX = Number.POSITIVE_INFINITY;
+      let minY = Number.POSITIVE_INFINITY;
+      let maxX = Number.NEGATIVE_INFINITY;
+      let maxY = Number.NEGATIVE_INFINITY;
+      let inFront = true;
+      for (const point of hit.body) {
+        _view.copy(point).applyMatrix4(camera.matrixWorldInverse);
+        if (_view.z >= 0) {
+          inFront = false;
+          break;
+        }
+        const [sx, sy] = toScreen(point, camera, working.width, working.height);
+        if (sx < minX) minX = sx;
+        if (sx > maxX) maxX = sx;
+        if (sy < minY) minY = sy;
+        if (sy > maxY) maxY = sy;
+      }
+      if (
+        inFront &&
+        x >= minX - BODY_GRAB_PX &&
+        x <= maxX + BODY_GRAB_PX &&
+        y >= minY - BODY_GRAB_PX &&
+        y <= maxY + BODY_GRAB_PX
+      ) {
+        return "body";
+      }
+      // THE FRAMED RECTANGLE BY ITS BORDER, in SCREEN px like the body and for
+      // the same reason. Its interior is deliberately not a target — see
+      // `borderDistance` for why an interior claim takes the whole pane away.
       const corners: [number, number][] = [];
-      for (const corner of gizmo.quad) {
+      for (const corner of hit.quad) {
         _view.copy(corner).applyMatrix4(camera.matrixWorldInverse);
         if (_view.z >= 0) return null;
         corners.push(toScreen(corner, camera, working.width, working.height));
       }
-      return borderDistance(x, y, corners) <= BODY_GRAB_PX ? "body" : null;
+      return borderDistance(x, y, corners) <= BODY_GRAB_PX ? "frame" : null;
     };
-  }, 0);
+  }, AFTER_CAMERA_WRITERS);
 
   useEffect(
     () => () => {
       feed.frustumHit = null;
+      feed.hoverFrustum = null;
+      feed.cameraDriven = false;
+      feed.cameraWorld = null;
+      if (pushedDriver.current !== null) {
+        pushedDriver.current = null;
+        onDriver(null);
+      }
     },
-    [feed],
+    [feed, onDriver],
   );
 
-  return <primitive object={gizmo.lines} />;
-}
-
-function newQuad(): [Vector3, Vector3, Vector3, Vector3] {
-  return [new Vector3(), new Vector3(), new Vector3(), new Vector3()];
+  return (
+    <>
+      <primitive object={body.lines} />
+      <primitive object={reach.lines} />
+      <primitive object={marks.lines} />
+    </>
+  );
 }