@dailies-studio/shot-editor 0.1.0

package/src/stage/StageTools.tsx

@@ -0,0 +1,581 @@
+// The half of the stage that lives INSIDE the canvas.
+//
+// It renders nothing. Its whole job is to keep `feed` pointing at the live
+// camera and the live layer transforms, so the pointer lane and the overlay —
+// both of which are ordinary DOM outside the canvas — can ask geometry
+// questions without ever touching three themselves.
+//
+// ── PRIORITY 0, AND WHY THE OVERLAY IS NOT PUSHED AT ────────────────────
+//
+// `useFrame(…, 0)` runs in the same pass as the camera and layer writes, so the
+// quads it computes are the ones that are about to be drawn — not last frame's.
+// Under `frameloop="never"` that pass happens once per commit, so this costs
+// nothing while nothing moves, and exactly one recompute per seek, pan or zoom.
+//
+// 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 { useFrame, useThree } from "@react-three/fiber";
+import { OrthographicCamera, PerspectiveCamera, Raycaster, Vector2 } from "three";
+import type { Camera, Object3D } from "three";
+import {
+  SHOT_LAYER_BOX,
+  SHOT_LAYER_KEY,
+  SHOT_LAYER_LOCKED,
+  SHOT_LAYER_ORDER,
+  SHOT_LAYER_PICKABLE,
+} from "@dailies-studio/shot";
+import { memoLast, outermost } from "@dailies-studio/shot/doc";
+import type { LayerLookup } from "@dailies-studio/shot/doc";
+import { nearestHandle, quadCentre, rotateRingAt } from "./handles.js";
+import {
+  pickInRect,
+  pickLayers,
+  pickLayersByDistance,
+  projectQuad,
+  quadMoved,
+  screenQuad,
+  unionQuad,
+} from "./project.js";
+import type { LayerFrame, ScreenQuad } from "./project.js";
+import type { Grab, StageFeed } from "./feed.js";
+import type { PaneRect, StagePane } from "./panes.js";
+import { WORKING_FOV_DEG, workingPose } from "./workingView.js";
+import type { WorkingView } from "./workingView.js";
+import { isolationExtent, isolationEye } from "./isolation.js";
+import type { IsolationFrame } from "./isolation.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
+ *  will — but the mask has to be right BEFORE something depends on it, because
+ *  the failure is a gizmo leaking into the graded image. */
+export const EDITOR_LAYER = 1;
+
+
+/** Does the union box need repainting? Its APPEARANCE is a state change in its
+ *  own right — it comes and goes as a selection is tilted or added to — so a
+ *  null on either side is a change, and two boxes compare corner by corner. */
+function unionMoved(a: StageFeed["union"], b: StageFeed["union"]): boolean {
+  if (a === null || b === null) return a !== b;
+  for (const pane of ["camera", "working"] as const) {
+    const before = a[pane];
+    const after = b[pane];
+    if (before === null || after === null) {
+      if (before !== after) return true;
+      continue;
+    }
+    if (quadMoved(before, after)) return true;
+  }
+  return false;
+}
+
+/** Reused per frame; picking allocates enough already without a raycaster. */
+const RAYCASTER = new Raycaster();
+const NDC = new Vector2();
+
+/**
+ * `collectFrames`, replayed while nothing about the graph's MEMBERSHIP changed.
+ *
+ * This was the single biggest per-frame CPU item on the stage: a full
+ * `Object3D.traverse` of every node in the scene, every frame, whether or not
+ * anything had moved — and during an orbit or a dolly nothing HAS moved, in the
+ * only sense this walk cares about.
+ *
+ * The key is what membership actually depends on, and nothing more:
+ * - `root`, three's scene object, which is stable for the canvas's lifetime but
+ *   belongs in the key because a second canvas would be a different graph;
+ * - `layers`, the document's scene at this frame. Every edit mints a new object
+ *   (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;
+ * - `epoch`, the mount counter, because a model or an instance module resolving
+ *   commits a subtree that no value above predicts.
+ *
+ * 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
+ * frame and a gesture drag all move the matrices the cached frames already
+ * 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[] =>
+    collectFrames(root),
+);
+
+export function StageTools({
+  feed,
+  panes,
+  workingView,
+  selection,
+  layers,
+  sceneFrame,
+  isolationRoot,
+  isolated,
+  isolationView,
+}: {
+  feed: StageFeed;
+  /** The two pane rectangles, in CSS px from the CANVAS top-left. Everything
+   *  this component answers is measured inside ONE of them. */
+  panes: { working: PaneRect | null; camera: PaneRect | null };
+  workingView: WorkingView;
+  selection: readonly string[];
+  /** The scene at the playhead, for the hover lane's parent walk. `layers` and
+   *  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 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;
+}): null {
+  const scene = useThree((s) => s.scene);
+  const camera = useThree((s) => s.camera);
+
+  // The working pane's camera. Owned HERE and not by the renderer that draws
+  // with it: this runs at priority 0, the renderer at priority 1, so the camera
+  // that answers a pick is the same object in the same state as the one the
+  // pixel came from. See the note on `feed.workingCamera`.
+  const workingCamera = useMemo(() => {
+    const cam = new PerspectiveCamera(WORKING_FOV_DEG, 1, 0.1, 10_000);
+    cam.layers.enable(EDITOR_LAYER);
+    return cam;
+  }, []);
+
+  /** The isolation pane's camera. Its own object rather than a mode on the one
+   *  above, because an orthographic projection is a different class — and
+   *  because `feed.workingCamera` is read by picking, projection and the
+   *  renderer, all of which want whichever one is actually in the slot. */
+  const isolationCamera = useMemo(() => {
+    const cam = new OrthographicCamera(-1, 1, 1, -1, 0.1, 10_000);
+    cam.layers.enable(EDITOR_LAYER);
+    return cam;
+  }, []);
+
+  /** The working pane's own ORTHOGRAPHIC rig (numpad-5). Its own object beside
+   *  the perspective one, for `isolationCamera`'s reason: a projection is a
+   *  different class, and every consumer wants whichever is actually in the
+   *  slot rather than one object that changes type underneath them. */
+  const workingOrtho = useMemo(() => {
+    const cam = new OrthographicCamera(-1, 1, 1, -1, 0.1, 10_000);
+    cam.layers.enable(EDITOR_LAYER);
+    return cam;
+  }, []);
+
+  useFrame(() => {
+    const frames = collectFramesCached(scene, layers, sceneFrame, feed.sceneEpoch);
+    feed.frames = frames;
+
+    // ── ONE FRAME PER ID, THE FIRST ─────────────────────────────────────
+    //
+    // A CLONER stamps its children N times and every clone carries the SAME
+    // `SHOT_LAYER_KEY`, so `new Map(frames.map(...))` kept the LAST one. The
+    // outline and the gesture plane then belonged to a different clone than
+    // the one the author clicked, while `selectionCentre` averaged all of them
+    // and put the move gizmo in empty space between them.
+    //
+    // FIRST, and that is a CHOICE rather than a match. `collectFrames` walks
+    // the scene graph in order, so the first is the one `pickLayers` reports
+    // first in the camera pane — where the hits are sorted by paint order and
+    // every clone shares one. The WORKING pane sorts by distance
+    // (`pickLayersByDistance`), so clicking the nearest clone of a cloner still
+    // outlines and resizes the first one.
+    //
+    // ponytail: threading the picked frame's INDEX through the picker,
+    // `hoverQuad`, `grabAt` and the quad loop is the honest fix, and it is
+    // 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
+    // it would be gone the next time anything moved. This filter is the
+    // editor's own and survives.
+    //
+    // 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 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;
+    }
+
+    /** The pane's rect and camera, or null when that pane is not on screen. */
+    const viewOf = (pane: StagePane): { rect: PaneRect; cam: Camera } | null => {
+      if (pane === "camera") return cameraRect === null ? null : { rect: cameraRect, cam: camera };
+      return workingRect === null || feed.workingCamera === null
+        ? null
+        : { rect: workingRect, cam: feed.workingCamera };
+    };
+
+    feed.rayAt = (pane, x, y) => {
+      const view = viewOf(pane);
+      if (view === null) return null;
+      // NDC against the PANE, never the canvas: the renderer's viewport is the
+      // pane rect, so -1..1 spans the pane and dividing by the canvas would put
+      // every ray a fraction of a screen off.
+      NDC.set((x / view.rect.width) * 2 - 1, -((y / view.rect.height) * 2 - 1));
+      RAYCASTER.setFromCamera(NDC, view.cam);
+      // CLONED. `RAYCASTER` is module scope, so the ray it owns is one object:
+      // the move gesture holds the ray from the PRESS and compares it against
+      // the ray under the cursor, and two aliases of one mutable Ray make that
+      // difference identically zero.
+      return RAYCASTER.ray.clone();
+    };
+
+    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);
+    };
+
+    // The outline a click would select, projected in the pane it was asked
+    // about. `outermost` is `packages/shot`'s, the SAME walk `onPick` runs, so
+    // the preview and the click cannot name different layers.
+    feed.hoverQuad = (pane, x, y) => {
+      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);
+    };
+
+    feed.pickRect = (pane, rect) => {
+      const view = viewOf(pane);
+      if (view === null) return [];
+      return pickInRect(pickable, view.cam, view.rect.width, view.rect.height, rect);
+    };
+
+    feed.grabAt = (pane, x, y, selection) => {
+      if (selection.length === 0) return null;
+      // ── THE UNION BOX OUTRANKS EVERY MEMBER'S OWN HANDLES ─────────────
+      //
+      // When a multi-select has one honest box (`unionQuad`), that box is the
+      // only thing drawn with handles and it is therefore the only thing that
+      // may answer a press near one. Testing the members first would answer a
+      // union corner that happens to coincide with a member's corner — the
+      // commonest case there is, since the union's corners ARE member corners —
+      // with a single-layer `resize`, and the author would watch one layer of
+      // eight grow.
+      //
+      // A LOCKED MEMBER IS NOT FILTERED OUT HERE. The box still draws and still
+      // grabs; `applyGesture` skips the locked layer and names it, which is the
+      // honest report. Dropping it from the union instead would silently shrink
+      // the box the author drew a marquee around.
+      const union = feed.union;
+      const unionQ = union === null ? null : pane === "camera" ? union.camera : union.working;
+      if (union !== null && unionQ !== null) {
+        const grabbed = nearestHandle(unionQ, x, y);
+        // ANY member's matrix serves as the gesture plane: `unionQuad` only
+        // answers for a COPLANAR selection, so every member shares the box's
+        // plane and `gesturePlane("layer", …)` gives the same one from any of
+        // them. The first that still has a frame this playhead, for the same
+        // reason `selectionPivot` skips absent ones.
+        const any = feed.ids.map((id) => byId.get(id)).find((f) => f !== undefined);
+        if (grabbed !== null && any !== undefined) {
+          return {
+            kind: "scale",
+            handle: grabbed.handle,
+            matrixWorld: any.matrixWorld,
+            handleAngle: grabbed.angle,
+            centre: quadCentre(unionQ),
+            union: union.world,
+          };
+        }
+      }
+      // ── HANDLES FIRST, IN BOTH PANES ──────────────────────────────────
+      //
+      // Handles sit on top of the layer, so a press inside the box near one is
+      // a resize and not a move.
+      //
+      // IT USED TO BE CAMERA-PANE ONLY, on the grounds that "a resize is a
+      // screen drag divided by the view's zoom, and the working pane has no
+      // zoom, it has a distance". That reason is gone: `runTransformGesture`
+      // now unprojects two rays onto the layer's own plane, which has no zoom
+      // term at all and is correct for a perspective or an orthographic camera
+      // alike. So the working pane draws handles and grabs them, and the author
+      // can finally resize the thing they are looking at in 3D.
+      const quads = pane === "camera" ? feed.quadsCamera : feed.quadsWorking;
+      for (const [i, id] of feed.ids.entries()) {
+        const frame = byId.get(id);
+        // LOCKED LAYERS OFFER NO HANDLE. `pickable` above does not filter
+        // locked — that filtering lives in `project.ts`'s pickers, which is why
+        // the body branch below is already safe and this one was not. A locked
+        // layer that resizes from a handle is the lock silently not working.
+        if (frame === undefined || frame.locked === true) continue;
+        const quad = quads[i];
+        const grabbed = nearestHandle(quad, x, y);
+        if (grabbed !== null && quad !== undefined) {
+          return {
+            kind: "resize",
+            handle: grabbed.handle,
+            matrixWorld: frame.matrixWorld,
+            handleAngle: grabbed.angle,
+            centre: quadCentre(quad),
+          };
+        }
+        // ── THE ROTATE RING, RANKED AFTER THE RESIZE HANDLES ────────────
+        //
+        // CAMERA PANE ONLY. `rollDeg` turns a layer about the design z axis,
+        // which IS the camera pane's view axis — so a screen sweep there is
+        // exactly a roll. Under the working pane's free orbit the view axis is
+        // some other direction entirely, and a ring drawn on screen would
+        // promise a rotation the document model cannot express. The working
+        // pane keeps `R`, whose degrees are unambiguous.
+        if (pane !== "camera" || quad === undefined) continue;
+        const ring = rotateRingAt(quad, x, y);
+        if (ring !== null) {
+          return {
+            kind: "roll",
+            matrixWorld: frame.matrixWorld,
+            handleAngle: ring.angle,
+            // THE CENTRE THE ANGLE WAS MEASURED ABOUT, carried so the drag
+            // sweeps about the quad that was grabbed rather than about
+            // whichever selected id happens to sort lowest.
+            centre: quadCentre(quad),
+          };
+        }
+      }
+      // 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.
+      const hits = feed.pick?.(pane, x, y) ?? [];
+      const hit = hits.find((id) => selection.includes(id));
+      const frame = hit === undefined ? undefined : byId.get(hit);
+      return frame === undefined ? null : { kind: "move", matrixWorld: frame.matrixWorld };
+    };
+
+    // The overlay set follows the SELECTION, and a selected layer that is not
+    // in the scene this frame (its lifetime ended, or the playhead left its
+    // scene) simply has no quad — it must not hold a stale one.
+    const ids: string[] = [];
+    const locked: boolean[] = [];
+    const quadsCamera: ScreenQuad[] = [];
+    const quadsWorking: ScreenQuad[] = [];
+    const selected: LayerFrame[] = [];
+    let changed = selection.length !== feed.ids.length;
+    for (const [i, id] of selection.entries()) {
+      const frame = byId.get(id);
+      if (frame === undefined) {
+        changed = true;
+        continue;
+      }
+      selected.push(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
+      // the change test or a lock toggled from the outliner would leave the
+      // handles drawn until something else happened to move a quad.
+      if (feed.locked[locked.length] !== (frame.locked === true)) changed = true;
+      locked.push(frame.locked === true);
+      if (cameraRect !== null) {
+        const quad = screenQuad(frame, camera, cameraRect.width, cameraRect.height);
+        if (quadMoved(feed.quadsCamera[quadsCamera.length], quad)) changed = true;
+        quadsCamera.push(quad);
+      }
+      if (workingRect !== null && feed.workingCamera !== null) {
+        const quad = screenQuad(frame, feed.workingCamera, workingRect.width, workingRect.height);
+        if (quadMoved(feed.quadsWorking[quadsWorking.length], quad)) changed = true;
+        quadsWorking.push(quad);
+      }
+      ids.push(id);
+    }
+    // ── THE MULTI-SELECT'S ONE BOX ────────────────────────────────────────
+    //
+    // Derived from the SAME frames the outlines came from, in the same pass, so
+    // the box and the members it contains can never be a frame apart. Null the
+    // moment the selection stops being coplanar and axis-parallel (see
+    // `unionQuad`), which is a state the author can reach mid-drag by tilting —
+    // hence in the change test rather than assumed stable.
+    const world = unionQuad(selected);
+    const union =
+      world === null
+        ? null
+        : {
+            world,
+            camera: cameraRect === null ? null : projectQuad(world, camera, cameraRect.width, cameraRect.height),
+            working:
+              workingRect === null || feed.workingCamera === null
+                ? null
+                : projectQuad(world, feed.workingCamera, workingRect.width, workingRect.height),
+          };
+    if (unionMoved(feed.union, union)) changed = true;
+    // 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.
+    if (
+      !changed &&
+      quadsCamera.length === feed.quadsCamera.length &&
+      quadsWorking.length === feed.quadsWorking.length
+    ) {
+      return;
+    }
+    feed.ids = ids;
+    feed.locked = locked;
+    feed.union = union;
+    feed.quadsCamera = quadsCamera;
+    feed.quadsWorking = quadsWorking;
+    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
+    // quad and drew a second GL frame for every camera-move frame.
+    feed.onOverlay?.();
+  }, 0);
+
+  return null;
+}
+
+
+/**
+ * Every layer group in the scene, as the geometry the editor reasons about.
+ *
+ * It reads `userData` rather than the mesh, and that is the whole point: a
+ * paint layer's plane is GROWN by the rasterizer's shadow padding, so measuring
+ * the mesh would draw the outline a blur radius too big and pick the layer from
+ * outside its own edge. The group carries the transform and no scale.
+ */
+export function collectFrames(root: Object3D): LayerFrame[] {
+  const out: LayerFrame[] = [];
+  root.traverse((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.
+      matrixWorld: o.matrixWorld,
+      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,
+    });
+  });
+  return out;
+}