@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/StageTools.tsx

@@ -15,9 +15,9 @@
 // It bumps React only when a corner moved by more than half a CSS pixel. Below
 // that the SVG rounds to the same path and the render is pure cost, and the
 // camera moves on every frame of a dolly.
-import { useMemo } from "react";
+import { useLayoutEffect, useMemo, useRef } from "react";
 import { useFrame, useThree } from "@react-three/fiber";
-import { OrthographicCamera, PerspectiveCamera, Raycaster, Vector2 } from "three";
+import { Matrix4, OrthographicCamera, PerspectiveCamera, Raycaster, Vector2, Vector3 } from "three";
 import type { Camera, Object3D } from "three";
 import {
   SHOT_LAYER_BOX,
@@ -25,26 +25,50 @@ import {
   SHOT_LAYER_LOCKED,
   SHOT_LAYER_ORDER,
   SHOT_LAYER_PICKABLE,
+  layerStampEpoch,
 } from "@dailies-studio/shot";
-import { memoLast, outermost } from "@dailies-studio/shot/doc";
-import type { LayerLookup } from "@dailies-studio/shot/doc";
+import {
+  cameraClipPlanes,
+  layerAliveAt,
+  maskTargetOf,
+  memoLast,
+  meshPrimitiveOf,
+  motionPathOf,
+  outermost,
+  parentOf,
+  resolveLayerAt,
+  resolveTracksAt,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D, LayerLookup, MotionPath } from "@dailies-studio/shot/doc";
 import { nearestHandle, quadCentre, rotateRingAt } from "./handles.js";
 import {
+  maskHitsLast,
   pickInRect,
   pickLayers,
-  pickLayersByDistance,
   projectQuad,
   quadMoved,
+  rayHitsQuad,
   screenQuad,
+  toScreen,
   unionQuad,
+  worldQuad,
 } from "./project.js";
 import type { LayerFrame, ScreenQuad } from "./project.js";
-import type { Grab, StageFeed } from "./feed.js";
+import { projectPeers } from "./feed.js";
+import type { FailedQuad, MaskQuad, PeerQuad, StageFeed } from "./feed.js";
 import type { PaneRect, StagePane } from "./panes.js";
-import { WORKING_FOV_DEG, workingPose } from "./workingView.js";
+import { WORKING_FOV_DEG, orthoEyePushBack, viewBasis, workingPose } from "./workingView.js";
 import type { WorkingView } from "./workingView.js";
-import { isolationExtent, isolationEye } from "./isolation.js";
-import type { IsolationFrame } from "./isolation.js";
+import type { HeadOnCamera } from "./isolation.js";
+import {
+  projectSplineLayer,
+  splineScreenBounds,
+  splineScreenHit,
+  splineScreenIntersectsRect,
+} from "./splineStage.js";
+import type { ScreenSpline } from "./splineStage.js";
+import { motionPathHandleAt, motionPathKeyAt, motionPathsMoved, projectMotionPath } from "./motionPathStage.js";
+import type { ScreenMotionPath } from "./motionPathStage.js";
 
 /** Editor-only geometry lives on layer bit 1, and only the working camera sees
  *  it. Nothing draws on it yet — the frustum gizmo is the first thing that
@@ -70,9 +94,147 @@ function unionMoved(a: StageFeed["union"], b: StageFeed["union"]): boolean {
   return false;
 }
 
+/**
+ * The frames this pass brought up to date (`fresh`). Cleared at the top of
+ * each pass; one pass at a time, since the stage has one canvas and
+ * `useFrame` is never re-entered.
+ */
+const FRESH = new Set<LayerFrame>();
+
+/**
+ * A frame with its world matrix, and its parents', up to date for this pass.
+ *
+ * The runtime wrote the pass's positions, but three only folds them into
+ * `matrixWorld` when it renders, AFTER the frame loop. Read stale, a box that
+ * grew (auto text on commit) drew its new size around its old centre until
+ * the next commit. So every projection the pass makes takes its frame through
+ * here, and a frame nothing projects is left to the render, which recomposes
+ * every one anyway: bringing them all up front was the whole graph twice per
+ * frame, cloners included. Parents and self only: children (glyph's commit
+ * hook lives in `updateMatrixWorld`) are the renderer's.
+ */
+function fresh(frame: LayerFrame): LayerFrame {
+  if (!FRESH.has(frame)) {
+    FRESH.add(frame);
+    frame.object?.updateWorldMatrix(true, false);
+  }
+  return frame;
+}
+
 /** Reused per frame; picking allocates enough already without a raycaster. */
 const RAYCASTER = new Raycaster();
 const NDC = new Vector2();
+const PANE_AT = new Vector3();
+const IDENTITY = new Matrix4();
+/** How near a key dot a press has to land, in CSS px: the dot is r 4. */
+const PATH_KEY_GRAB_PX = 8;
+
+/**
+ * The matrix a layer's Position is written in: its group's PARENT, which is
+ * the parent layer's group, or a wrapper between (a splineFollow rig).
+ *
+ * A layer with no frame this pass (outside its lifetime, or hidden) still
+ * draws its path, dimmed, so the matrix is found another way: the group if it
+ * is still mounted, then the parent layer's group, then a mounted sibling's
+ * parent, then the scene root.
+ */
+function parentWorldOf(
+  id: string,
+  byId: ReadonlyMap<string, LayerFrame>,
+  root: Object3D,
+  layers: LayerLookup,
+): Matrix4 {
+  const self = byId.get(id);
+  const own = self?.object?.parent;
+  if (self !== undefined && own != null) {
+    fresh(self);
+    return own.matrixWorld;
+  }
+  let mounted: Object3D | null = null;
+  root.traverse((o) => {
+    if (mounted === null && o.userData[SHOT_LAYER_KEY] === id) mounted = o;
+  });
+  const mountedParent = (mounted as Object3D | null)?.parent;
+  if (mountedParent != null) {
+    mountedParent.updateWorldMatrix(true, false);
+    return mountedParent.matrixWorld;
+  }
+  const parentId = parentOf(layers, id);
+  const parentFrame = parentId === null ? undefined : byId.get(parentId);
+  if (parentFrame?.object !== undefined) {
+    fresh(parentFrame);
+    return parentFrame.object.matrixWorld;
+  }
+  for (const [otherId, frame] of byId) {
+    if (otherId !== id && frame.object?.parent != null && parentOf(layers, otherId) === parentId) {
+      fresh(frame);
+      return frame.object.parent.matrixWorld;
+    }
+  }
+  return IDENTITY;
+}
+
+interface ProjectedSplineFrame {
+  frame: LayerFrame;
+  screen: ScreenSpline;
+  renderGeometry: boolean;
+}
+
+function projectedSplines(
+  frames: readonly LayerFrame[],
+  layers: LayerLookup | null,
+  sceneFrame: number,
+  fps: Doc3D["fps"] | null,
+  camera: Camera | null,
+  width: number,
+  height: number,
+): ProjectedSplineFrame[] {
+  if (layers === null || camera === null || width <= 0 || height <= 0) return [];
+  const out: ProjectedSplineFrame[] = [];
+  for (const frame of frames) {
+    // THE STORED LAYER SAYS WHETHER IT IS A SPLINE, before any track is
+    // sampled: neither the kind nor the primitive's kind is trackable, and
+    // every other tracked layer (each cloner clone too) paid a full resolve
+    // per pane per frame only to be skipped.
+    const stored = layers.layersById[frame.id];
+    if (stored?.kind !== "mesh" || meshPrimitiveOf(stored.mesh)?.kind !== "spline") continue;
+    const layer = fps === null ? stored : resolveTracksAt(stored, sceneFrame, fps);
+    if (layer.kind !== "mesh") continue;
+    const primitive = meshPrimitiveOf(layer.mesh);
+    if (primitive?.kind !== "spline") continue;
+    const renderGeometry = primitive.renderGeometry !== false;
+    const screen = projectSplineLayer(primitive, fresh(frame), camera, width, height, [], renderGeometry);
+    if (screen !== null) out.push({ frame, screen, renderGeometry });
+  }
+  return out;
+}
+
+function uniqueIds(rows: readonly { id: string }[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const row of rows) {
+    if (seen.has(row.id)) continue;
+    seen.add(row.id);
+    out.push(row.id);
+  }
+  return out;
+}
+
+function guidesMoved(
+  before: StageFeed["splineGuidesWorking"],
+  after: StageFeed["splineGuidesWorking"],
+): boolean {
+  if (before.length !== after.length) return true;
+  for (let index = 0; index < after.length; index += 1) {
+    const a = before[index];
+    const b = after[index];
+    if (a === undefined || b === undefined || a.id !== b.id || a.selected !== b.selected || a.pts.length !== b.pts.length) {
+      return true;
+    }
+    if (a.pts.some((value, pointIndex) => Math.abs(value - (b.pts[pointIndex] ?? Number.NaN)) > 0.5)) return true;
+  }
+  return false;
+}
 
 /**
  * `collectFrames`, replayed while nothing about the graph's MEMBERSHIP changed.
@@ -89,9 +251,21 @@ const NDC = new Vector2();
  *   (the whole store is immutable), and an edit is what changes a layer's box,
  *   its lock or its pickability — all of which this walk COPIES rather than
  *   referencing;
- * - `sceneFrame`, because a lifetime ends and a layer leaves the tree;
+ * - `stamps`, the runtime's stamp counter, because those copied values are also
+ *   PER-FRAME values: a size track moves the box without touching `layers`;
  * - `epoch`, the mount counter, because a model or an instance module resolving
- *   commits a subtree that no value above predicts.
+ *   commits a subtree that no value above predicts. A lifetime ending is a
+ *   `LayerNode` unmounting, so it rides this one too.
+ *
+ * ── WHY `stamps` AND NOT THE PLAYHEAD ────────────────────────────────────
+ *
+ * The frame used to be the key term standing in for "a copied value moved",
+ * which is correct and maximally pessimistic: the playhead changes on every
+ * played frame, the stamps change only while something is actually resizing or
+ * restacking, so playback of a scene with no size track re-walked the entire
+ * graph 30 times a second to rebuild an identical answer. `LayerNode` now
+ * compares each stamp before writing it and bumps `layerStampEpoch` only on a
+ * real change, which is the same guarantee stated honestly.
  *
  * What is deliberately NOT in the key is motion. `matrixWorld` is stored as a
  * LIVE REFERENCE (see `collectFrames`), so an orbit, a pan, a scrub within one
@@ -99,20 +273,41 @@ const NDC = new Vector2();
  * point at. That is why replaying the walk is exact rather than merely close.
  */
 const collectFramesCached = memoLast(
-  (root: Object3D, _layers: LayerLookup | null, _sceneFrame: number, _epoch: number): LayerFrame[] =>
+  (root: Object3D, _layers: LayerLookup | null, _stamps: number, _epoch: number): LayerFrame[] =>
     collectFrames(root),
 );
 
+/**
+ * The walk's answer by id (the first frame of each, see the pass) and its
+ * pickable part, replayed while the walk's answer and the isolation scope
+ * hold: they change with nothing else, and rebuilding them was a Map and two
+ * arrays the size of the graph on every pass, cloners included.
+ */
+export const indexFrames = memoLast(
+  (
+    frames: readonly LayerFrame[],
+    isolated: ReadonlySet<string> | null,
+  ): { byId: ReadonlyMap<string, LayerFrame>; pickable: readonly LayerFrame[] } => {
+    const byId = new Map<string, LayerFrame>();
+    for (const f of frames) if (!byId.has(f.id)) byId.set(f.id, f);
+    const pickable = frames.filter((f) => f.pickable !== false && (isolated === null || isolated.has(f.id)));
+    return { byId, pickable };
+  },
+);
+
 export function StageTools({
   feed,
   panes,
   workingView,
   selection,
   layers,
-  sceneFrame,
+  sceneFrameAt,
+  fps,
   isolationRoot,
   isolated,
-  isolationView,
+  headOn,
+  motionPaths,
+  passDrawing,
 }: {
   feed: StageFeed;
   /** The two pane rectangles, in CSS px from the CANVAS top-left. Everything
@@ -124,18 +319,31 @@ export function StageTools({
    *  not `scene`, because `scene` in this file is three's own scene graph. Null
    *  before a document has arrived, or between scenes. */
   layers: LayerLookup | null;
-  /** The playhead, in the scene's own frames. Read only as part of the frame
-   *  walk's cache key: a lifetime ending is a layer leaving the graph. */
-  sceneFrame: number;
+  /** The playhead, in the scene's own frames, read at FRAME time from the
+   *  stage's clock (StageApp's `playhead`). Samples the active spline's
+   *  tracked profile/taper; the frame walk keys on `layerStampEpoch` instead. */
+  sceneFrameAt: () => number;
+  /** Track sampling clock for active spline profile/taper values. */
+  fps: Doc3D["fps"] | null;
   /** The isolated layer itself, which is the BOUNDARY the parent walk stops at
    *  — not the same thing as `isolated`, which is its whole subtree. */
   isolationRoot: string | null;
   /** The isolated subtree's ids, or null when nothing is isolated. Picking is
    *  scoped to it — see the filter below. */
   isolated: ReadonlySet<string> | null;
-  /** The head-on frame for that subtree, or null. Drives the working pane's
-   *  camera while isolation is on. */
-  isolationView: IsolationFrame | null;
+  /** The derived head-on camera, or null once the orbit rig owns the pane.
+   *  Already solved against the chrome inset by `StageApp` — this file installs
+   *  it and does not re-derive any part of it. Non-null for BOTH head-on modes:
+   *  an isolated subtree and an open component definition. */
+  headOn: HeadOnCamera | null;
+  /** Draw the selected layers' motion paths (gap 3). StageApp folds the
+   *  `motionPaths` pref with every state that hides them: playing, watching,
+   *  a material preview, an export, and any gesture but a path key drag. */
+  motionPaths: boolean;
+  /** A preparing pass is drawing its own frames under a frozen picture
+   *  (bridge v51 `passDrawing`), read at frame time: the client's stable
+   *  getter, never a prop value a render would have to deliver. */
+  passDrawing: () => boolean;
 }): null {
   const scene = useThree((s) => s.scene);
   const camera = useThree((s) => s.camera);
@@ -170,8 +378,119 @@ export function StageTools({
     return cam;
   }, []);
 
+  /**
+   * Pose the camera as a pull-based operation, not only as a side effect of
+   * `useFrame`. ClockDriver's compile barrier runs before priority-0 frame
+   * subscribers, and SplitRenderer must compile with the same camera that the
+   * subscriber below will hand to the draw.
+   */
+  const prepareWorkingCamera = (): Camera | null => {
+    const workingRect = panes.working;
+    if (workingRect === null) {
+      feed.workingCamera = null;
+      return null;
+    }
+    if (headOn !== null) {
+      // A HEAD-ON FRAME TAKES THE WORKING PANE'S SLOT. Not a third pane: a
+      // scissored pane per mode is the trap SplitRenderer's header is about,
+      // and the two views an author wants while inside a card are "this card,
+      // flat" and "the shot". The split that already exists is that view.
+      isolationCamera.left = -headOn.halfWidth;
+      isolationCamera.right = headOn.halfWidth;
+      isolationCamera.top = headOn.halfHeight;
+      isolationCamera.bottom = -headOn.halfHeight;
+      isolationCamera.near = headOn.near;
+      isolationCamera.far = headOn.far;
+      isolationCamera.position.set(headOn.eye[0], headOn.eye[1], headOn.eye[2]);
+      isolationCamera.up.set(headOn.up[0], headOn.up[1], headOn.up[2]);
+      isolationCamera.lookAt(headOn.target[0], headOn.target[1], headOn.target[2]);
+      isolationCamera.updateProjectionMatrix();
+      isolationCamera.updateMatrixWorld(true);
+      feed.workingCamera = isolationCamera;
+      return isolationCamera;
+    }
+
+    // Perspective and orthographic views share one pose. The orthographic eye
+    // stands back rather than using a negative near plane, so drawing, picking
+    // and the compile frustum all see the same positive slab.
+    const ortho = workingView.ortho === true;
+    const cam = ortho ? workingOrtho : workingCamera;
+    const { position } = workingPose(workingView);
+    const back = ortho ? orthoEyePushBack(workingView.distance) : 0;
+    const dir = ortho
+      ? [
+          (position[0] - workingView.target[0]) / Math.max(workingView.distance, 1),
+          (position[1] - workingView.target[1]) / Math.max(workingView.distance, 1),
+          (position[2] - workingView.target[2]) / Math.max(workingView.distance, 1),
+        ]
+      : [0, 0, 0];
+    cam.position.set(
+      position[0] + dir[0]! * back,
+      position[1] + dir[1]! * back,
+      position[2] + dir[2]! * back,
+    );
+    const upAt = viewBasis(workingView).up;
+    cam.up.set(upAt[0], upAt[1], upAt[2]);
+    cam.lookAt(workingView.target[0], workingView.target[1], workingView.target[2]);
+    const aspect = workingRect.height === 0 ? 1 : workingRect.width / workingRect.height;
+    if (ortho) {
+      const halfHeight = workingView.distance * Math.tan((WORKING_FOV_DEG * Math.PI) / 360);
+      workingOrtho.top = halfHeight;
+      workingOrtho.bottom = -halfHeight;
+      workingOrtho.right = halfHeight * aspect;
+      workingOrtho.left = -halfHeight * aspect;
+      workingOrtho.near = 0.1;
+      workingOrtho.far = back * 2 + workingView.distance;
+    } else {
+      workingCamera.fov = WORKING_FOV_DEG;
+      workingCamera.aspect = aspect;
+      // The Shot's own rule (`cameraClipPlanes`): a fixed 0.1 against an
+      // orbit radius of thousands of px z-fights a model's faces here too.
+      // Always the derived near, whatever the Shot holds: this view is the
+      // editor's own, never an exported picture, so no film's bytes ride on
+      // it, and the clip it costs a Shot of planes is 1/200 of the orbit
+      // radius in front of the eye.
+      const clip = cameraClipPlanes(workingView.distance, true);
+      workingCamera.near = clip.near;
+      workingCamera.far = clip.far;
+    }
+    cam.updateProjectionMatrix();
+    cam.updateMatrixWorld(true);
+    feed.workingCamera = cam;
+    return cam;
+  };
+
+  // The layout effect above poses the camera on every commit, and the frame
+  // subscriber below used to pose it AGAIN on the advance that same commit
+  // triggers: two `updateProjectionMatrix` + `updateMatrixWorld(true)` per
+  // frame for one answer. The flag says "this commit already posed it"; the
+  // subscriber consumes it, so a heartbeat advance with no commit in between
+  // still poses once, and a commit never poses twice.
+  const posedThisCommit = useRef(false);
+  useLayoutEffect(() => {
+    feed.prepareWorkingCamera = prepareWorkingCamera;
+    prepareWorkingCamera();
+    posedThisCommit.current = true;
+    return () => {
+      if (feed.prepareWorkingCamera !== prepareWorkingCamera) return;
+      feed.prepareWorkingCamera = null;
+      feed.workingCamera = null;
+    };
+  });
+
   useFrame(() => {
-    const frames = collectFramesCached(scene, layers, sceneFrame, feed.sceneEpoch);
+    // ── THE FURNITURE HOLDS STILL WHILE A PASS DRAWS (bridge v51) ─────────
+    //
+    // A preparing pass draws other frames under the frozen picture, and
+    // every projection below would follow them: the outlines, the hints, the
+    // motion paths, the closures the pointer lanes pick through. So the feed
+    // keeps the frozen frame's answers until the pass publishes the author's
+    // frame again; that draw projects everything afresh before the lift.
+    if (passDrawing()) return;
+    const frames = collectFramesCached(scene, layers, layerStampEpoch(), feed.sceneEpoch);
+    // Every projection below brings its own frame's matrix up (`fresh`), and
+    // nothing else does: a pass with no selection projects next to nothing.
+    FRESH.clear();
     feed.frames = frames;
 
     // ── ONE FRAME PER ID, THE FIRST ─────────────────────────────────────
@@ -194,8 +513,7 @@ export function StageTools({
     // plumbing for a case that needs a cloner, the working pane, and a click on
     // a clone that is not the first. Named here; do it when someone reports
     // handles on the wrong clone.
-    const byId = new Map<string, LayerFrame>();
-    for (const f of frames) if (!byId.has(f.id)) byId.set(f.id, f);
+    //
     // ISOLATION SCOPES PICKING, and it does it HERE rather than through
     // `SHOT_LAYER_PICKABLE`. The runtime re-stamps that userData on every
     // commit from a dep-less layout effect, so anything the editor wrote onto
@@ -205,123 +523,12 @@ export function StageTools({
     // A press that lands on nothing is what exits: with the surroundings
     // unpickable, clicking outside the subtree already produces an empty hit
     // list, so "click away to leave" needs no second gesture.
-    const pickable = frames.filter(
-      (f) => f.pickable !== false && (isolated === null || isolated.has(f.id)),
-    );
+    const { byId, pickable } = indexFrames(frames, isolated);
     const cameraRect = panes.camera;
     const workingRect = panes.working;
 
-    if (workingRect === null) {
-      feed.workingCamera = null;
-    } else if (isolationView !== null) {
-      // ISOLATION TAKES THE WORKING PANE'S SLOT. Not a third pane: a scissored
-      // pane per mode is the trap SplitRenderer's header is about, and the two
-      // views an author wants while inside a card are "this card, flat" and
-      // "the shot" — which is the split that already exists.
-      //
-      // Orthographic and posed from the subtree's OWN basis, so it can roll and
-      // can look straight down — neither of which the orbit rig can do (its up
-      // is reset to world +y every frame and its polar angle is clamped off
-      // both poles).
-      const aspect = workingRect.height === 0 ? 1 : workingRect.width / workingRect.height;
-      const extent = isolationExtent(isolationView, aspect);
-      const { eye, up, far } = isolationEye(isolationView);
-      isolationCamera.left = -extent.halfWidth;
-      isolationCamera.right = extent.halfWidth;
-      isolationCamera.top = extent.halfHeight;
-      isolationCamera.bottom = -extent.halfHeight;
-      isolationCamera.near = 0.1;
-      isolationCamera.far = far;
-      isolationCamera.position.set(eye[0], eye[1], eye[2]);
-      isolationCamera.up.set(up[0], up[1], up[2]);
-      isolationCamera.lookAt(
-        isolationView.target[0],
-        isolationView.target[1],
-        isolationView.target[2],
-      );
-      isolationCamera.updateProjectionMatrix();
-      isolationCamera.updateMatrixWorld(true);
-      feed.workingCamera = isolationCamera;
-    } else {
-      // ── PERSPECTIVE OR ORTHOGRAPHIC, SAME POSE ────────────────────────
-      //
-      // Numpad-5. The two rigs are POSED identically — same eye, same target,
-      // same up — and differ only in the projection, so the toggle turns the
-      // vanishing point on and off without moving the camera an inch.
-      //
-      // The ortho half-height is `distance * tan(fov/2)`, which is exactly what
-      // the perspective lens frames AT THE TARGET. So `workingScreenScale`
-      // needs no branch: its `2 * distance * tan(fov/2)` is already both
-      // answers.
-      //
-      // The two agree at the target POINT and not everywhere: an ortho
-      // projection has no perspective divide, so a layer's corners — which sit
-      // at different depths once the view is orbited — are foreshortened by one
-      // rig and not the other. The error grows with distance from the target;
-      // on it, it is under one percent of the layer's own span
-      // (stageGeometry.test.ts pins that), which reads as the same picture and
-      // is what makes the toggle a toggle. Far from the target it is a real
-      // difference, and it is the whole reason to have an ortho view at all.
-      const ortho = workingView.ortho === true;
-      const cam = ortho ? workingOrtho : workingCamera;
-      const { position } = workingPose(workingView);
-      // ── THE ORTHO EYE STANDS BACK, IT DOES NOT REACH FORWARD ──────────
-      //
-      // An orthographic projection does not depend on where along the view axis
-      // the eye sits, so the two ways to cover the scene look identical: a
-      // negative near plane, or a positive near plane with the eye pushed back.
-      // They are NOT identical to the pointer. `Raycaster.setFromCamera` starts
-      // an ortho ray AT the near plane, and `rayHitsTriangle` rejects `t < 0` —
-      // so with a negative near plane every layer behind the eye plane drew
-      // perfectly and answered no click, no marquee, no gizmo and no frustum
-      // hit (`pickInRect`'s guard, `MoveGizmo`'s `behind` and `FrustumGizmo`'s
-      // all read view-space z the same way).
-      //
-      // Standing back is the construction `isolationEye` already uses, and it
-      // fixes all four consumers with no branch in any of them.
-      const back = ortho ? Math.max(workingView.distance * 8, 10_000) : 0;
-      const dir = ortho
-        ? [
-            (position[0] - workingView.target[0]) / Math.max(workingView.distance, 1),
-            (position[1] - workingView.target[1]) / Math.max(workingView.distance, 1),
-            (position[2] - workingView.target[2]) / Math.max(workingView.distance, 1),
-          ]
-        : [0, 0, 0];
-      cam.position.set(
-        position[0] + dir[0]! * back,
-        position[1] + dir[1]! * back,
-        position[2] + dir[2]! * back,
-      );
-      // Re-set every frame: `lookAt` reads `up`, and leaving it to whatever a
-      // previous frame or another consumer left there is how an orbit picks up
-      // a roll nobody authored.
-      cam.up.set(0, 1, 0);
-      cam.lookAt(workingView.target[0], workingView.target[1], workingView.target[2]);
-      const aspect = workingRect.height === 0 ? 1 : workingRect.width / workingRect.height;
-      if (ortho) {
-        const halfHeight = workingView.distance * Math.tan((WORKING_FOV_DEG * Math.PI) / 360);
-        workingOrtho.top = halfHeight;
-        workingOrtho.bottom = -halfHeight;
-        workingOrtho.right = halfHeight * aspect;
-        workingOrtho.left = -halfHeight * aspect;
-        // A POSITIVE NEAR PLANE, with the eye already pushed back by `back`
-        // above. The whole slab is in front of the camera, so every hit test in
-        // this lane agrees with what is drawn.
-        workingOrtho.near = 0.1;
-        workingOrtho.far = back * 2 + workingView.distance;
-      } else {
-        workingCamera.fov = WORKING_FOV_DEG;
-        workingCamera.aspect = aspect;
-        // The shot camera's own near/far, for the same reason it can afford
-        // them: every material here draws with `depthTest: false`, so depth
-        // precision buys nothing and a generous far plane costs nothing.
-        workingCamera.near = 0.1;
-        workingCamera.far = Math.max(workingView.distance * 8, 10_000);
-      }
-      cam.updateProjectionMatrix();
-      cam.updateMatrixWorld(true);
-      feed.workingCamera = cam;
-    }
+    if (!posedThisCommit.current) prepareWorkingCamera();
+    posedThisCommit.current = false;
 
     /** The pane's rect and camera, or null when that pane is not on screen. */
     const viewOf = (pane: StagePane): { rect: PaneRect; cam: Camera } | null => {
@@ -330,6 +537,34 @@ export function StageTools({
         ? null
         : { rect: workingRect, cam: feed.workingCamera };
     };
+    const sceneFrame = sceneFrameAt();
+    const cameraSplines = projectedSplines(
+      pickable,
+      layers,
+      sceneFrame,
+      fps,
+      cameraRect === null ? null : camera,
+      cameraRect?.width ?? 0,
+      cameraRect?.height ?? 0,
+    );
+    const workingSplines = projectedSplines(
+      pickable,
+      layers,
+      sceneFrame,
+      fps,
+      workingRect === null ? null : feed.workingCamera,
+      workingRect?.width ?? 0,
+      workingRect?.height ?? 0,
+    );
+    const splineIds = new Set([...cameraSplines, ...workingSplines].map((row) => row.frame.id));
+    const ordinaryPickable = splineIds.size === 0 ? pickable : pickable.filter((frame) => !splineIds.has(frame.id));
+    const splineMap = (rows: readonly ProjectedSplineFrame[]): Map<string, ProjectedSplineFrame> => {
+      const out = new Map<string, ProjectedSplineFrame>();
+      for (const row of rows) if (!out.has(row.frame.id)) out.set(row.frame.id, row);
+      return out;
+    };
+    const cameraSplineById = splineMap(cameraSplines);
+    const workingSplineById = splineMap(workingSplines);
 
     feed.rayAt = (pane, x, y) => {
       const view = viewOf(pane);
@@ -345,14 +580,52 @@ export function StageTools({
       // difference identically zero.
       return RAYCASTER.ray.clone();
     };
+    feed.paneAt = (pane, design) => {
+      const view = viewOf(pane);
+      if (view === null) return null;
+      // Design y runs down and world y up: world = (x, -y, 0).
+      return toScreen(PANE_AT.set(design[0], -design[1], 0), view.cam, view.rect.width, view.rect.height);
+    };
+    feed.worldToPane = (pane, world) => {
+      const view = viewOf(pane);
+      return view === null ? null : toScreen(world, view.cam, view.rect.width, view.rect.height);
+    };
 
+    const isMask = (id: string): boolean => layers?.layersById[id]?.mask !== undefined;
     feed.pick = (pane, x, y) => {
       const ray = feed.rayAt?.(pane, x, y) ?? null;
       if (ray === null) return [];
-      // The two panes sort their hits differently, and that divergence is the
-      // point — see `pickLayersByDistance`. Paint order answers "what is on top"
-      // in the camera pane; in a free orbit it answers nothing.
-      return pane === "working" ? pickLayersByDistance(ray, pickable) : pickLayers(ray, pickable);
+      const splineRows = pane === "working" ? workingSplines : cameraSplines;
+      if (pane === "camera") {
+        const rows = pickLayers(ray, ordinaryPickable).map((id) => ({
+          id,
+          order: byId.get(id)?.order ?? 0,
+        }));
+        for (const row of splineRows) {
+          if (row.frame.locked !== true && splineScreenHit(row.screen, [x, y])) {
+            rows.push({ id: row.frame.id, order: row.frame.order });
+          }
+        }
+        rows.sort((a, b) => b.order - a.order);
+        return maskHitsLast(uniqueIds(rows), isMask);
+      }
+      // In the free working view, interleave spline centreline hits with plane
+      // hits by ray distance. A spline is one-dimensional, so its layer origin
+      // is the stable depth tie-breaker for the sampled screen hit.
+      const rows: Array<{ id: string; t: number; order: number }> = [];
+      for (const frame of ordinaryPickable) {
+        if (frame.locked === true) continue;
+        const t = rayHitsQuad(ray, worldQuad(frame));
+        if (t !== null) rows.push({ id: frame.id, t, order: frame.order });
+      }
+      for (const row of splineRows) {
+        if (row.frame.locked === true || !splineScreenHit(row.screen, [x, y])) continue;
+        const origin = new Vector3().setFromMatrixPosition(row.frame.matrixWorld);
+        const t = Math.max(0, origin.sub(ray.origin).dot(ray.direction));
+        rows.push({ id: row.frame.id, t, order: row.frame.order });
+      }
+      rows.sort((a, b) => a.t - b.t || b.order - a.order);
+      return maskHitsLast(uniqueIds(rows), isMask);
     };
 
     // The outline a click would select, projected in the pane it was asked
@@ -362,14 +635,40 @@ export function StageTools({
       const view = viewOf(pane);
       const hit = feed.pick?.(pane, x, y)[0];
       if (view === null || layers === null || hit === undefined) return null;
-      const frame = byId.get(outermost(layers, hit, isolationRoot));
-      return frame === undefined ? null : screenQuad(frame, view.cam, view.rect.width, view.rect.height);
+      const selectedId = outermost(layers, hit, isolationRoot);
+      const spline = (pane === "working" ? workingSplineById : cameraSplineById).get(selectedId);
+      if (spline !== undefined) return splineScreenBounds(spline.screen, 4);
+      const frame = byId.get(selectedId);
+      return frame === undefined ? null : screenQuad(fresh(frame), view.cam, view.rect.width, view.rect.height);
+    };
+
+    // One layer's outline BY ID — `hoverQuad` minus the pick. The chrome-hover
+    // sink is its caller (see `feed.quadForLayer`); pull-based, so it answers
+    // while the stage is idle.
+    const quadForLayer = (pane: StagePane, layerId: string): ScreenQuad | null => {
+      const view = viewOf(pane);
+      if (view === null) return null;
+      const spline = (pane === "working" ? workingSplineById : cameraSplineById).get(layerId);
+      if (spline !== undefined) return splineScreenBounds(spline.screen, 4);
+      const frame = byId.get(layerId);
+      return frame === undefined ? null : screenQuad(fresh(frame), view.cam, view.rect.width, view.rect.height);
     };
+    feed.quadForLayer = quadForLayer;
 
     feed.pickRect = (pane, rect) => {
       const view = viewOf(pane);
       if (view === null) return [];
-      return pickInRect(pickable, view.cam, view.rect.width, view.rect.height, rect);
+      const rows = pickInRect(ordinaryPickable, view.cam, view.rect.width, view.rect.height, rect).map((id) => ({
+        id,
+        order: byId.get(id)?.order ?? 0,
+      }));
+      for (const row of pane === "working" ? workingSplines : cameraSplines) {
+        if (row.frame.locked !== true && splineScreenIntersectsRect(row.screen, rect, 2)) {
+          rows.push({ id: row.frame.id, order: row.frame.order });
+        }
+      }
+      rows.sort((a, b) => a.order - b.order);
+      return uniqueIds(rows);
     };
 
     feed.grabAt = (pane, x, y, selection) => {
@@ -462,9 +761,10 @@ export function StageTools({
           };
         }
       }
-      // Then the BODY of anything already selected. Pressing an unselected
-      // layer must select it rather than drag it — dragging something the
-      // author had not selected is the classic way to move the wrong thing.
+      // Then the BODY of anything already selected. A press on an unselected
+      // layer answers null here: StageApp's empty-space lane picks it on the
+      // press and asks again once the new selection lands, so one press-drag
+      // selects and moves.
       const hits = feed.pick?.(pane, x, y) ?? [];
       const hit = hits.find((id) => selection.includes(id));
       const frame = hit === undefined ? undefined : byId.get(hit);
@@ -486,7 +786,9 @@ export function StageTools({
         changed = true;
         continue;
       }
-      selected.push(frame);
+      // Brought up here, so its quads, the union and TransformGizmo's centre
+      // (`feed.frames`, read later in this frame loop) see this pass's pose.
+      selected.push(fresh(frame));
       if (feed.ids[i] !== id) changed = true;
       // The lock is a document flag, so it changes only on a commit — but the
       // overlay repaints off `feed.version`, not off React, so it has to be in
@@ -526,6 +828,165 @@ export function StageTools({
                 : projectQuad(world, feed.workingCamera, workingRect.width, workingRect.height),
           };
     if (unionMoved(feed.union, union)) changed = true;
+    const selectedIds = new Set(selection);
+    const splineGuidesWorking = workingSplines
+      .filter((row) => !row.renderGeometry || selectedIds.has(row.frame.id))
+      .map((row) => ({
+        id: row.frame.id,
+        pts: row.screen.line.flatMap((point) => [point[0], point[1]]),
+        selected: selectedIds.has(row.frame.id),
+      }));
+    if (guidesMoved(feed.splineGuidesWorking, splineGuidesWorking)) changed = true;
+    // ── THE CHROME'S HOVER HINT RIDES THE SAME PASS ───────────────────────
+    // The sink seeds these at write time (an idle stage runs no frame); this
+    // keeps them true while the camera moves. Same half-pixel gate as the
+    // selection quads, so a stationary hint costs nothing.
+    const hintCamera = feed.hintId === null ? null : quadForLayer("camera", feed.hintId);
+    const hintWorking = feed.hintId === null ? null : quadForLayer("working", feed.hintId);
+    if (hintQuadMoved(feed.hintCamera, hintCamera) || hintQuadMoved(feed.hintWorking, hintWorking)) {
+      changed = true;
+    }
+    // ── AND SO DOES A BROKEN PIECE'S PLACEHOLDER ──────────────────────────
+    // A layer the runtime isolated keeps its group (its transform and stamps
+    // are still written), so its outline is the hole where it would draw.
+    const failedCamera: FailedQuad[] = [];
+    const failedWorking: FailedQuad[] = [];
+    for (const id of feed.failedIds) {
+      const label = feed.failedLabels.get(id) ?? "Component";
+      const inCamera = quadForLayer("camera", id);
+      if (inCamera !== null) failedCamera.push({ quad: inCamera, label });
+      const inWorking = quadForLayer("working", id);
+      if (inWorking !== null) failedWorking.push({ quad: inWorking, label });
+    }
+    if (failedMoved(feed.failedCamera, failedCamera) || failedMoved(feed.failedWorking, failedWorking)) {
+      changed = true;
+    }
+    // ── AND SO DOES A SELECTED GROUP'S MASK (gap 7) ───────────────────────
+    // The matte that cuts the selection, dashed. Not for a mask that is itself
+    // selected: its own outline already says where it is.
+    const maskCamera: MaskQuad[] = [];
+    const maskWorking: MaskQuad[] = [];
+    if (layers !== null) {
+      const masks = new Set(selection.map((id) => maskTargetOf(layers, id)));
+      for (const id of masks) {
+        if (id === null || selectedIds.has(id)) continue;
+        const round = layers.layersById[id]?.kind === "ellipse";
+        const inCamera = quadForLayer("camera", id);
+        if (inCamera !== null) maskCamera.push({ quad: inCamera, round });
+        const inWorking = quadForLayer("working", id);
+        if (inWorking !== null) maskWorking.push({ quad: inWorking, round });
+      }
+    }
+    if (masksMoved(feed.maskCamera, maskCamera) || masksMoved(feed.maskWorking, maskWorking)) changed = true;
+    // ── AND SO DO OTHER PEOPLE'S SELECTIONS (bridge v43) ──────────────────
+    const peersCamera = projectPeers(feed.peerSel, quadForLayer, "camera", ids);
+    const peersWorking = projectPeers(feed.peerSel, quadForLayer, "working", ids);
+    if (peersMoved(feed.peersCamera, peersCamera) || peersMoved(feed.peersWorking, peersWorking)) changed = true;
+    // ── AND SO DOES THE OPEN STUDIO PIN'S LAYER RING (bridge v45) ─────────
+    const pinLayerCamera = feed.pinLayerId === null ? null : quadForLayer("camera", feed.pinLayerId);
+    if (pinLayerCamera === null ? feed.pinLayerCamera !== null : quadMoved(feed.pinLayerCamera ?? undefined, pinLayerCamera)) {
+      changed = true;
+    }
+    // ── AND SO DOES THE PEN PREVIEW, ON ITS PANE'S CAMERA ALONE ───────────
+    // It projects at render time, so a camera that moves under a still cursor
+    // (a scrubbed camera move, a wheel zoom) must repaint it. Read only while
+    // the pen holds points: otherwise a moving camera costs no repaint. The
+    // pen draws on the frame: the camera pane, or with no camera pane on
+    // screen a definition's one pane, whose camera is the working one.
+    const penCamera = cameraRect !== null ? camera : feed.workingCamera;
+    const cameraPose =
+      feed.penLive && penCamera !== null
+        ? [...penCamera.projectionMatrix.elements, ...penCamera.matrixWorldInverse.elements]
+        : null;
+    if (cameraPose !== null && cameraPose.some((v, i) => v !== feed.cameraPose?.[i])) changed = true;
+    // ── AND SO DO THE MOTION PATHS (gap 3) ─────────────────────────────────
+    // Projected from the STORED layer, so a key edit redraws on its commit
+    // and a scrub between keys moves only the tick and the current dot.
+    const motionCamera: ScreenMotionPath[] = [];
+    const motionWorking: ScreenMotionPath[] = [];
+    const motionParents = new Map<string, { parent: Matrix4; path: MotionPath }>();
+    if (motionPaths && layers !== null && fps !== null) {
+      for (const id of selection) {
+        const stored = layers.layersById[id];
+        // A splineFollow layer's position is the spline's: it has no path of its own.
+        if (stored === undefined || stored.splineFollow !== undefined) continue;
+        if (isolated !== null && !isolated.has(id)) continue;
+        const path = motionPathOf(stored, fps);
+        if (path === null) continue;
+        const parent = parentWorldOf(id, byId, scene, layers);
+        motionParents.set(id, { parent, path });
+        const dim = !layerAliveAt(stored, sceneFrame);
+        const at = (f: number) => resolveLayerAt(stored, f, fps).position;
+        const sample =
+          sceneFrame < path.from || sceneFrame > path.to
+            ? null
+            : {
+                now: at(sceneFrame),
+                before: at(Math.max(path.from, sceneFrame - 0.5)),
+                after: at(Math.min(path.to, sceneFrame + 0.5)),
+              };
+        if (cameraRect !== null) {
+          motionCamera.push(
+            projectMotionPath(id, path, sceneFrame, dim, sample, parent, camera, cameraRect.width, cameraRect.height),
+          );
+        }
+        if (workingRect !== null && feed.workingCamera !== null) {
+          motionWorking.push(
+            projectMotionPath(
+              id,
+              path,
+              sceneFrame,
+              dim,
+              sample,
+              parent,
+              feed.workingCamera,
+              workingRect.width,
+              workingRect.height,
+            ),
+          );
+        }
+      }
+    }
+    if (motionPathsMoved(feed.motionPathsCamera, motionCamera) || motionPathsMoved(feed.motionPathsWorking, motionWorking)) {
+      changed = true;
+    }
+    // The selected dot goes with its key: a deleted key, a deselected layer
+    // or the pref off leaves no handles to show.
+    const picked = feed.selectedPathKey;
+    if (picked !== null && !motionParents.get(picked.layerId)?.path.keys.some((k) => k.id === picked.keyId)) {
+      feed.selectedPathKey = null;
+      changed = true;
+    }
+    feed.pathKeyHit = (pane, x, y) =>
+      motionPathKeyAt(pane === "camera" ? feed.motionPathsCamera : feed.motionPathsWorking, x, y, PATH_KEY_GRAB_PX);
+    feed.pathHandleHit = (pane, x, y) =>
+      motionPathHandleAt(
+        pane === "camera" ? feed.motionPathsCamera : feed.motionPathsWorking,
+        feed.selectedPathKey,
+        x,
+        y,
+        PATH_KEY_GRAB_PX,
+      );
+    feed.pathKeyAnchor = (layerId, keyId) => {
+      const row = motionParents.get(layerId);
+      const index = row?.path.keys.findIndex((k) => k.id === keyId) ?? -1;
+      const key = row?.path.keys[index];
+      if (row === undefined || key === undefined) return null;
+      const parent = row.parent.clone();
+      const world = new Vector3(key.point[0], -key.point[1], -key.point[2]).applyMatrix4(parent);
+      const neighbours = [row.path.keys[index - 1], row.path.keys[index + 1]].flatMap((k) =>
+        k === undefined ? [] : [k.point],
+      );
+      return {
+        world,
+        parent,
+        frame: key.frame,
+        point: key.point,
+        neighbours,
+        ...(key.spatialIn === undefined ? {} : { spatialIn: key.spatialIn }),
+        ...(key.spatialOut === undefined ? {} : { spatialOut: key.spatialOut }),
+      };
+    };
     // A pane appearing or disappearing changes an array's LENGTH without moving
     // any corner, so the emptiness check is what makes a mode switch repaint —
     // otherwise the overlay keeps drawing the pane that just went away.
@@ -541,6 +1002,19 @@ export function StageTools({
     feed.union = union;
     feed.quadsCamera = quadsCamera;
     feed.quadsWorking = quadsWorking;
+    feed.splineGuidesWorking = splineGuidesWorking;
+    feed.hintCamera = hintCamera;
+    feed.hintWorking = hintWorking;
+    feed.failedCamera = failedCamera;
+    feed.failedWorking = failedWorking;
+    feed.maskCamera = maskCamera;
+    feed.maskWorking = maskWorking;
+    feed.peersCamera = peersCamera;
+    feed.peersWorking = peersWorking;
+    feed.pinLayerCamera = pinLayerCamera;
+    feed.cameraPose = cameraPose;
+    feed.motionPathsCamera = motionCamera;
+    feed.motionPathsWorking = motionWorking;
     feed.version += 1;
     // The overlay leaf's own subscription (see feed.onOverlay) — never a
     // StageApp state setter, which re-committed the whole stage per moved
@@ -551,6 +1025,31 @@ export function StageTools({
   return null;
 }
 
+/** `quadMoved` with null on either side: appearing or vanishing IS a move. */
+function hintQuadMoved(prev: ScreenQuad | null, next: ScreenQuad | null): boolean {
+  if (prev === null || next === null) return prev !== next;
+  return quadMoved(prev, next);
+}
+
+/** A list of quads moved: one appeared, one went, or one moved. */
+function peersMoved(prev: readonly PeerQuad[], next: readonly PeerQuad[]): boolean {
+  if (prev.length !== next.length) return true;
+  return next.some((row, index) => {
+    const was = prev[index];
+    return was?.name !== row.name || was.color !== row.color || was.tag !== row.tag || was.ring !== row.ring || quadMoved(was.quad, row.quad);
+  });
+}
+
+function masksMoved(prev: readonly MaskQuad[], next: readonly MaskQuad[]): boolean {
+  if (prev.length !== next.length) return true;
+  return next.some((row, index) => prev[index]?.round !== row.round || quadMoved(prev[index]?.quad, row.quad));
+}
+
+function failedMoved(prev: readonly FailedQuad[], next: readonly FailedQuad[]): boolean {
+  if (prev.length !== next.length) return true;
+  return next.some((row, index) => prev[index]?.label !== row.label || quadMoved(prev[index]?.quad, row.quad));
+}
+
 
 /**
  * Every layer group in the scene, as the geometry the editor reasons about.
@@ -562,16 +1061,17 @@ export function StageTools({
  */
 export function collectFrames(root: Object3D): LayerFrame[] {
   const out: LayerFrame[] = [];
-  root.traverse((o) => {
+  root.traverseVisible((o) => {
     const id: unknown = o.userData[SHOT_LAYER_KEY];
     const box: unknown = o.userData[SHOT_LAYER_BOX];
     if (typeof id !== "string" || !Array.isArray(box)) return;
     out.push({
       id,
       size: [Number(box[0]), Number(box[1])],
-      // Live reference, not a clone: `traverse` runs after the transforms are
-      // written, and the quad is read in the same tick.
+      // Live reference, not a clone. It is only as fresh as the last
+      // `updateWorldMatrix`, which the overlay pass runs on `object` first.
       matrixWorld: o.matrixWorld,
+      object: o,
       order: typeof o.userData[SHOT_LAYER_ORDER] === "number" ? (o.userData[SHOT_LAYER_ORDER] as number) : 0,
       locked: o.userData[SHOT_LAYER_LOCKED] === true,
       pickable: o.userData[SHOT_LAYER_PICKABLE] !== false,