@dailies-studio/shot-editor 0.1.0

package/src/stage/StageApp.tsx

@@ -0,0 +1,3423 @@
+// The stage's React tree: the working area, `ShotRuntime` inside it, and the
+// overlay on top.
+//
+// ── THE WORKING AREA ────────────────────────────────────────────────────
+//
+// The canvas fills the whole viewport and the CAMERA carries the pan and zoom,
+// through `setViewOffset` (see view.ts). Two consequences worth stating:
+//
+//   1. You can work OFF-CANVAS. The render is wider than the exportable frame,
+//      and the frame's own rectangle is derived from the same numbers as the
+//      offset — so the bright border sits exactly on the pixels that will be
+//      exported rather than approximately on them.
+//
+//   2. Zooming RE-RENDERS instead of magnifying. A CSS `transform: scale()`
+//      would have been fewer lines and would have made every zoomed-in frame
+//      soft, in a tool whose entire job is judging pixels.
+//
+// The layer RASTERS follow the zoom too, so text is cut for the pixels it is
+// actually shown at.
+//
+// ── TWO PANES, ONE CANVAS, ONE SET OF NUMBERS ───────────────────────────
+//
+// `paneRects` divides the canvas and EVERY consumer reads that one answer: the
+// renderer scissors to it, `viewOffsetFor` measures the camera pane rather than
+// the canvas, the overlay translates into it, and `paneAt` routes the pointer
+// by it. A divider the renderer drew to and the pointer tested against
+// separately would be off by a column at some widths, and the symptom is
+// "clicking near the middle selects the wrong thing" rather than anything that
+// looks like a layout bug.
+//
+// COORDINATES CROSS AS PANE-LOCAL. `paneAt` returns the pane and the local
+// point together, and that pair is passed straight through to the feed. There
+// is no second place where a pane origin is subtracted, which is the only way
+// to be sure it is never subtracted twice.
+//
+// THE STAGE TAKES OVER THE PRESENT ONLY WHEN IT HAS TO. In camera mode
+// `ShotRuntime` renders itself exactly as it does in an export, untouched;
+// `SplitRenderer` mounts and `renderControl` flips to "external" only when a
+// second pane is on screen. That is deliberate: the single-pane path is the one
+// the export shares, and the cheapest way to keep it identical is to not
+// reimplement it.
+import { memo, useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
+import { ShotRuntime, hasPostChain, quantizeRasterScale } from "@dailies-studio/shot";
+import {
+  DEFAULT_KEY_DIR,
+  MIN_INVERTIBLE_SCALE,
+  binsAtCached,
+  cameraRigAtCached,
+  componentDefsOfCached,
+  instanceComponentIdsOf,
+  masterToSceneCached,
+  sceneHasMeshCached,
+  transitionAtCached,
+  withDescendants,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D, RenderBin, SnapGuide } from "@dailies-studio/shot/doc";
+import { Vector3 } from "three";
+import type { Plane, Ray } from "three";
+import { Overlays, modalReadoutSink } from "./overlays/Overlays.js";
+import type { OverlayProps, ScreenKeyLight, ScreenMarquee, ScreenModal } from "./overlays/Overlays.js";
+import { FrustumGizmo } from "./FrustumGizmo.js";
+import { GridPlane } from "./GridPlane.js";
+import { MoveGizmo } from "./MoveGizmo.js";
+import { SplitRenderer } from "./SplitRenderer.js";
+import { StageTools } from "./StageTools.js";
+import { createStageFeed } from "./feed.js";
+import type { Grab, StageFeed } from "./feed.js";
+import { PERF_HUD_ENABLED, PerfHud, PerfProbe, createPerfBox } from "./PerfHud.js";
+import { resolveInstanceModules } from "./instanceModules.js";
+import type { InstanceResolution } from "./instanceModules.js";
+import { quadMoved, toScreen } from "./project.js";
+import type { ScreenQuad, WorldQuad } from "./project.js";
+import { quadCentre } from "./handles.js";
+import { paneAt, paneRects } from "./panes.js";
+import type { PaneRect, StagePane } from "./panes.js";
+import { isolationExtent, isolationEye, isolationFrame } from "./isolation.js";
+import {
+  DOLLY_FALLOFF_PX,
+  WORKING_FOV_DEG,
+  defaultWorkingView,
+  dollyBounds,
+  dollyBy,
+  orbitBy,
+  panWorkingBy,
+  workingScreenScale,
+  workingViewForIsolation,
+} from "./workingView.js";
+import type { WorkingView } from "./workingView.js";
+import { axisParam, framingArmDelta, keyDirOnScreen, navBalls, rotateKeyDir, viewForBall } from "./gizmoMath.js";
+import type { GizmoGrab, NavBall, Vec3 } from "./gizmoMath.js";
+import { frustumShape } from "./frustumGeometry.js";
+import { isPanGesture, panBy, wheelToView } from "./interactions/panZoom.js";
+import { designDelta, designPoint, gesturePlane, unionScale } from "./interactions/move.js";
+import type { DesignBox } from "./interactions/move.js";
+import { clampZoom, designToScreen, fitView, frameRect, screenToDesign, viewOffsetFor } from "./view.js";
+import type { FrameSize } from "./view.js";
+import type { StageClient, StageClientState } from "./bridgeClient.js";
+import { isDrawTool, specOf } from "../tools.js";
+import type { DrawTool } from "../tools.js";
+import { resolveKey } from "../state/keymap.js";
+import {
+  PEN_CLOSE_SLOP_PX,
+  PEN_DRAG_THRESHOLD_PX,
+  PEN_EMPTY,
+  penCloses,
+  penData,
+  penReduce,
+} from "./penState.js";
+import type { PenState } from "./penState.js";
+import {
+  TILT_DEG_PER_PX,
+  advanceVirtual,
+  axisRefusal,
+  framingDeltaFor,
+  initialGestureKind,
+  layerGestureFor,
+  modalAxisToggle,
+  modalLabel,
+  modalReadout,
+  modalTarget,
+  typeNumber,
+  typedValue,
+  PRECISION_FACTOR,
+} from "./modalState.js";
+import type { ModalMode, ModalState } from "./modalState.js";
+import type { ShotView, WorkingViewOrigin } from "../bridgeTypes.js";
+
+/**
+ * Below this a press-and-release is a CLICK, not a drag. Without it every click
+ * that moved one pixel would clear the selection instead of setting it — and,
+ * once the draw lane existed, would insert a two-pixel rectangle instead of one
+ * of a usable size.
+ *
+ * ONE threshold for both lanes on purpose: "did the pointer travel" is the same
+ * question, and two numbers would make a gesture a marquee and a click at the
+ * same time.
+ */
+const DRAG_THRESHOLD_PX = 3;
+
+/** What the wheel lane actually reads off a WheelEvent — a plain shape, so the
+ *  rAF coalescer can hand the handler one batch with summed deltas. */
+interface WheelLike {
+  clientX: number;
+  clientY: number;
+  deltaX: number;
+  deltaY: number;
+  deltaMode: number;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  /** Shift turns a vertical wheel into a horizontal one, which is how a mouse
+   *  reaches the pan a trackpad gets from `deltaX`. */
+  shiftKey: boolean;
+}
+
+/** What an unisolated layer fades to. Low enough that the subject is obviously
+ *  the subject, high enough that the surroundings are still context to align
+ *  against — which is the whole reason they are drawn at all rather than
+ *  hidden. */
+const DIM_OPACITY = 0.18;
+
+// TILT_DEG_PER_PX moved to modalState.ts — one definition for the drag lane
+// and the modal lane; imported above.
+
+/**
+ * The design z = 0 plane, which is the plane the camera's framed rectangle sits
+ * in and therefore the one a frustum drag unprojects onto.
+ *
+ * Built through `gesturePlane` from an IDENTITY matrix rather than constructed
+ * here, so the frustum drag and a layer's "move it on the canvas" drag are the
+ * same plane maths from the same file. `gesturePlane` takes anything with an
+ * `elements` array, which is also what keeps this line free of a three import
+ * it would otherwise need for `Matrix4`.
+ */
+const Z0_PLANE = gesturePlane("frame", {
+  elements: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+});
+
+/** Nothing on screen. Hoisted so the prop is referentially stable. */
+const EMPTY_BINS: readonly RenderBin[] = Object.freeze([]);
+
+/** A live modal transform's imperative half — held in a REF, not state:
+ *  mouse motion drives it per pointer event and must not re-render the
+ *  stage. The pure half (what each mode+axis emits) is modalState.ts; the
+ *  pill is the only thing React is told about. Coordinates are PANE-LOCAL
+ *  CSS px, which is what `feed.rayAt` measures against. */
+/**
+ * The four bidirectional resize cursors, in the order `resizeCursorFor` indexes
+ * them: east, south-east, south, south-west. Each is its own opposite, which is
+ * why four names cover eight handles.
+ */
+const RESIZE_CURSORS = ["ew-resize", "nwse-resize", "ns-resize", "nesw-resize"] as const;
+
+/**
+ * A handle's screen direction, as a cursor.
+ *
+ * ── WHY AN ANGLE AND NOT A NAME ─────────────────────────────────────────
+ *
+ * The selection box is a PROJECTED QUAD, not an axis-aligned rectangle. Roll a
+ * layer 45 degrees and its "nw" corner points due north; look at it from the
+ * working pane's orbit and it can point anywhere at all. A cursor chosen from
+ * the handle's NAME would sit at up to 45 degrees to the edge the author is
+ * about to drag, which is worse than no cursor because it is confidently wrong.
+ *
+ * ── AND WHY FOUR BUCKETS RATHER THAN A DRAWN CURSOR ─────────────────────
+ *
+ * CSS has exactly these four bidirectional resize cursors and no way to rotate
+ * one. Snapping to the nearest is correct to within 22.5 degrees, which is what
+ * Figma does and what nobody has ever noticed. A data-URI SVG cursor rotated to
+ * the exact angle is possible and is deliberately NOT built here: it is a
+ * per-frame image encode for an error nobody can see. The rotate ring is where
+ * that cost earns its keep, because CSS has no rotate cursor at all.
+ *
+ * `angle` is measured in the overlay's y-DOWN space (see `Grab.handleAngle`),
+ * so bucket 1 is down-and-right, which reads as the ↖↘ diagonal: `nwse`.
+ */
+/** Ctrl quantises a pointer roll, Blender's own 15 degrees. */
+const ROLL_SNAP_DEG = 15;
+
+/**
+ * The rotate cursor, as a data-URI SVG rotated to the ring's own angle.
+ *
+ * ── THE ONE PLACE A DRAWN CURSOR EARNS ITS KEEP ─────────────────────────
+ *
+ * CSS has four bidirectional resize cursors and NO rotate cursor at all, so
+ * unlike `resizeCursorFor` there is nothing to snap to. Figma and Framer both
+ * draw one, and without it the ring is a band of empty space that silently
+ * behaves differently from the space beside it.
+ *
+ * QUANTISED TO 15 DEGREES and cached, so a sweep round a box mints 24 strings
+ * over its whole life rather than one per pointermove. The eye cannot see the
+ * difference; the allocation is real.
+ */
+const ROTATE_CURSORS = new Map<number, string>();
+export function rotateCursorFor(angle: number): string {
+  if (!Number.isFinite(angle)) return "pointer";
+  const step = Math.round((angle * 180) / Math.PI / ROLL_SNAP_DEG) * ROLL_SNAP_DEG;
+  const cached = ROTATE_CURSORS.get(step);
+  if (cached !== undefined) return cached;
+  // Two black-outlined white arrowheads on an arc, which is the shape every
+  // design tool uses and the only one that reads at 24px.
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">` +
+    `<g transform="rotate(${step} 12 12)" fill="none" stroke="#000" stroke-width="3.2" ` +
+    `stroke-linecap="round" stroke-linejoin="round">` +
+    `<path d="M5 9a7.6 7.6 0 0 1 14 0"/><path d="M19 4v5h-5"/></g>` +
+    `<g transform="rotate(${step} 12 12)" fill="none" stroke="#fff" stroke-width="1.6" ` +
+    `stroke-linecap="round" stroke-linejoin="round">` +
+    `<path d="M5 9a7.6 7.6 0 0 1 14 0"/><path d="M19 4v5h-5"/></g></svg>`;
+  const value = `url("data:image/svg+xml,${encodeURIComponent(svg)}") 12 12, pointer`;
+  ROTATE_CURSORS.set(step, value);
+  return value;
+}
+
+export function resizeCursorFor(angle: number): string {
+  if (!Number.isFinite(angle)) return "pointer";
+  const k = Math.round(angle / (Math.PI / 4));
+  return RESIZE_CURSORS[((k % 4) + 4) % 4]!;
+}
+
+/**
+ * What a press at a point would do, as data.
+ *
+ * `"empty"` is what a marquee, an orbit or a deselecting click all start from,
+ * and the three are told apart by the BUTTON and the MODIFIERS, which this
+ * union deliberately knows nothing about — those belong to the press lane, and
+ * a hover has neither.
+ */
+type StageIntent =
+  | { kind: "arm"; arm: GizmoGrab }
+  | { kind: "grab"; grab: Grab }
+  | { kind: "frustum"; part: "apex" | "body" }
+  | { kind: "empty" };
+
+interface ModalLive {
+  state: ModalState;
+  rect: PaneRect;
+  anchor: readonly [number, number];
+  virtual: readonly [number, number];
+  lastRaw: readonly [number, number];
+  /** The anchor ray and unprojection plane, captured at start — move modes
+   *  only; rotate and scale are screen-space and need neither. */
+  ray: Ray | null;
+  plane: Plane | null;
+  screenScale: number;
+  /** The world DESIGN point a scale grows away from — the selection's median —
+   *  or null for a single layer, which scales in place. Snapshotted at the
+   *  start so the pivot cannot walk while the layers move around it. */
+  pivot: readonly [number, number, number] | null;
+  /**
+   * A one-shot message the pill shows INSTEAD of the numbers, or null.
+   *
+   * For the axis keys the mapping table claims and ignores (`S` then `Z`, any
+   * axis during a camera zoom, `Z` during a camera move). The listener has
+   * already called `preventDefault`, so without this the key is swallowed and
+   * nothing anywhere distinguishes that from a key that never registered.
+   *
+   * Cleared by the next axis press that IS honoured, AND by any real pointer
+   * motion — a refusal describes a KEY, and the author moving the mouse is the
+   * author moving on. Without the second clause the message sat over a
+   * transform that was still changing while the live numbers never came back.
+   */
+  refusal: string | null;
+  /**
+   * The numeric buffer: `G X 200 Enter`.
+   *
+   * A STRING and not a number, because `"1."`, `"-"` and `""` are all real
+   * mid-typing states that no number can represent — and a bare `-` parsed as
+   * `-0` would snap the layer to the origin the moment the author pressed it.
+   * `typedValue` is the one place that decides when it means something.
+   *
+   * Emptying it hands the transform back to the mouse, which is what makes a
+   * mistyped digit recoverable without cancelling the whole gesture.
+   */
+  typed: string;
+  /** CTRL is held: quantise. Shift's partner, tracked here for the same reason
+   *  shift is read per event — it can change mid-gesture. */
+  snap: boolean;
+}
+
+/** Nothing snapping — the overwhelmingly common case, hoisted so "no guides"
+ *  is the same array on every render and cannot break the overlay's memo. */
+const EMPTY_GUIDES: OverlayProps["guides"] = [];
+
+/**
+ * The overlay, with its OWN repaint subscription.
+ *
+ * This is the leaf `feed.onOverlay` re-renders. When the bump lived on
+ * `StageApp` (`bumpOverlay`), a camera dolly with a selection cost two full
+ * stage commits per frame — one for the dolly, one when the quads moved — and
+ * each commit is a GL draw under `frameloop="never"`. Here, a moved quad
+ * repaints one SVG.
+ */
+function OverlaysHost({
+  feed,
+  designGuides,
+  size,
+  keyLightArm,
+  ...rest
+}: {
+  feed: StageFeed;
+  /** The guides as the STORE sends them: one design-frame coordinate on one
+   *  axis, origin at the canvas centre. The camera pane's screen numbers are
+   *  derived by the caller; the working pane's segments are derived here,
+   *  because only this half is re-rendered when the camera moves. */
+  designGuides: readonly SnapGuide[];
+  size: FrameSize;
+  /**
+   * The key-light arm's DIRECTION and its grab handler, or null.
+   *
+   * Its screen ANCHOR is derived here rather than passed, for `guidesWorking`'s
+   * reason: the layer's quad is rewritten by the in-canvas half every frame and
+   * no dependency array can see it move, so it has to be read where the repaint
+   * already happens.
+   */
+  keyLightArm: { layerId: string; dir: readonly [number, number] | null; onGrab: (e: React.PointerEvent) => void } | null;
+} & Omit<
+  OverlayProps,
+  | "quadsCamera"
+  | "quadsWorking"
+  | "locked"
+  | "guidesWorking"
+  | "unionCamera"
+  | "unionWorking"
+  | "keyLight"
+>) {
+  const [, bump] = useReducer((n: number) => n + 1, 0);
+  useEffect(() => {
+    feed.onOverlay = bump;
+    return () => {
+      feed.onOverlay = null;
+    };
+  }, [feed]);
+  return (
+    <MemoOverlays
+      {...rest}
+      quadsCamera={feed.quadsCamera}
+      quadsWorking={feed.quadsWorking}
+      locked={feed.locked}
+      unionCamera={feed.union?.camera ?? null}
+      unionWorking={feed.union?.working ?? null}
+      keyLight={keyLightAnchor(keyLightArm, feed)}
+      guidesWorking={projectGuides(designGuides, feed, rest.panes.working, size)}
+    />
+  );
+}
+
+/**
+ * The key-light handle, anchored on its layer's quad.
+ *
+ * Null when the layer has no quad in the working pane this frame — which is
+ * every frame outside its lifespan, and every frame it is behind the camera.
+ * Drawing a handle for a layer that is not on screen would put a sun in empty
+ * space and let the author drag the shading of something they cannot see.
+ */
+function keyLightAnchor(
+  arm: { layerId: string; dir: readonly [number, number] | null; onGrab: (e: React.PointerEvent) => void } | null,
+  feed: StageFeed,
+): ScreenKeyLight | null {
+  if (arm === null) return null;
+  const index = feed.ids.indexOf(arm.layerId);
+  const quad = index < 0 ? undefined : feed.quadsWorking[index];
+  if (quad === undefined) return null;
+  return { at: quadCentre(quad), dir: arm.dir, onGrab: arm.onGrab };
+}
+
+/**
+ * A design-plane guide line, as a screen SEGMENT in the working pane.
+ *
+ * ── WHY IT IS HERE AND NOT IN A `useMemo` ON `StageApp` ─────────────────
+ *
+ * `feed.workingCamera` is a mutable object the in-canvas half rewrites every
+ * frame, so no dependency array can see it move. `OverlaysHost` re-renders on
+ * `feed.onOverlay`, which fires exactly when a projected quad moved — which is
+ * every frame of the drag these guides exist during. So this is computed where
+ * the repaint already happens, and nowhere else.
+ *
+ * Cheap by construction: guides are empty except mid-snap, and the common case
+ * returns the same frozen array every time so the memo below still bails.
+ *
+ * The endpoints span TWICE the canvas, so the line runs past the artwork the
+ * way the camera pane's full-height rule does rather than stopping at an edge
+ * that would read as part of the geometry.
+ */
+function projectGuides(
+  guides: readonly SnapGuide[],
+  feed: StageFeed,
+  rect: PaneRect | null,
+  size: FrameSize,
+): readonly { a: readonly [number, number]; b: readonly [number, number] }[] {
+  const camera = feed.workingCamera;
+  if (guides.length === 0 || rect === null || camera === null) return EMPTY_SEGMENTS;
+  const out: { a: readonly [number, number]; b: readonly [number, number] }[] = [];
+  for (const g of guides) {
+    // Design (dx, dy) with the origin at the canvas centre, and the one mapping
+    // applied on the way out: world = (x, -y, -z).
+    const span = g.axis === "x" ? size.height : size.width;
+    const from = g.axis === "x" ? [g.at, span] : [-span, -g.at];
+    const to = g.axis === "x" ? [g.at, -span] : [span, -g.at];
+    out.push({
+      a: toScreen(_guideA.set(from[0]!, from[1]!, 0), camera, rect.width, rect.height),
+      b: toScreen(_guideB.set(to[0]!, to[1]!, 0), camera, rect.width, rect.height),
+    });
+  }
+  return out;
+}
+
+const EMPTY_SEGMENTS: readonly { a: readonly [number, number]; b: readonly [number, number] }[] = [];
+const _guideA = new Vector3();
+const _guideB = new Vector3();
+
+/**
+ * The SVG bails unless a prop actually changed. StageApp re-renders on every
+ * seek and every gesture frame, and the overlay's props are stable across a
+ * seek by construction: the quads arrive as FRESH ARRAYS from StageTools
+ * exactly when a quad moved (feed.ts), the frame rect and the guides are
+ * memoized by the caller, and everything else is state. So the memo turns
+ * "the overlay re-renders whenever the stage does" into "the overlay
+ * re-renders when something it draws moved", which is what the quad gate in
+ * StageTools was already promising.
+ */
+const MemoOverlays = memo(Overlays);
+
+export function StageApp({ client }: { client: StageClient }) {
+  const state = useStageState(client);
+  const areaRef = useRef<HTMLDivElement | null>(null);
+  const feed = useMemo(createStageFeed, []);
+  const perfBox = useMemo(createPerfBox, []);
+  const [viewport, setViewport] = useState({ width: 0, height: 0 });
+  const [marquee, setMarquee] = useState<ScreenMarquee | null>(null);
+  /**
+   * The outline a click would select, in STATE because the overlay draws it.
+   *
+   * The one place in the hover lane that costs a render, so it is written only
+   * when the answer actually CHANGES — a pointermove inside one layer keeps the
+   * same quad object and commits nothing. `quadMoved`'s half-pixel gate is the
+   * same rule `StageTools` uses to decide the selection outline moved, so a
+   * stationary pointer over a stationary layer is free.
+   */
+  const [hover, setHover] = useState<{ pane: StagePane; quad: ScreenQuad } | null>(null);
+  /**
+   * The pen's path so far, in DESIGN px from the frame's top-left.
+   *
+   * DESIGN and not screen, even though the preview is drawn in screen space and
+   * has to be converted on every render. A point held in screen coordinates
+   * would stay where it is on the display while the author pans or zooms
+   * between clicks, and land somewhere they never pointed at.
+   *
+   * The GEOMETRY is penState.ts's and none of it is here: this component owns
+   * the pointer plumbing and the conversion, and nothing about where a handle
+   * goes.
+   */
+  const [pen, setPen] = useState<PenState>(PEN_EMPTY);
+  /** The space bar is DOWN, so a left drag pans. See `useKeyRelay`. */
+  const spaceRef = useRef(false);
+  /** …and a pan actually ran during this hold, so the release must not also
+   *  play. A separate bit because key auto-repeat resurrects a shared one. */
+  const spacePanned = useRef(false);
+  /**
+   * Recompute the cursor with no pointer motion, filled in far below.
+   *
+   * Declared up HERE because the key relay is registered above everything
+   * `refreshCursor` needs (`intentAt`, the feed, the panes), and a ref is the
+   * one shape that lets a listener registered once reach a function rebuilt on
+   * every render — the pattern `endModalRef` and `wheelRef` already use.
+   */
+  const refreshCursorRef = useRef<() => void>(() => {});
+  /**
+   * The cursor a live orbit or dolly is holding, or null.
+   *
+   * Navigation was the one gesture family with no feedback at all: a pan closed
+   * the hand and the orbit right beside it said nothing, so "am I turning the
+   * view or dragging a layer" was answered only by watching the picture. It is
+   * a REF and read by `cursorFor` rather than written at the press, because
+   * every move of these drags commits and the per-commit refresh would
+   * overwrite an imperative write immediately.
+   */
+  const navCursorRef = useRef<string | null>(null);
+  /** `B` armed a one-shot box select (Blender's). Consumed by the next press,
+   *  whether or not it marquees — an armed mode the author has to remember is
+   *  worse than one that expires. */
+  const boxSelectRef = useRef(false);
+  /** The live modal transform's PILL state — the ref below is authoritative;
+   *  this exists so the overlay re-renders on start/axis/end and on nothing
+   *  else (mouse motion stays off React entirely). */
+  const [modal, setModal] = useState<ModalState | null>(null);
+  const modalRef = useRef<ModalLive | null>(null);
+  const modalRaf = useRef(0);
+  /** The cursor's last known canvas position and button state, fed by the
+   *  pointer-move prop. The start lane needs an ANCHOR — a modal begins on a
+   *  keydown, which carries no coordinates — and `buttons` gates starting
+   *  while any drag lane may be live (a modal's end would close that drag's
+   *  scrub).
+   *
+   *  `inside` IS LOAD-BEARING, not bookkeeping. Without it the position alone
+   *  answers "where is the cursor", and it lies in two ways that both open a
+   *  modal nobody asked for: it starts at `[0, 0]`, which is INSIDE the working
+   *  pane in every layout that has one, so `G`/`S` armed a camera modal before
+   *  the pointer had ever entered the stage; and the stage is an iframe that
+   *  keeps keyboard focus after the cursor moves onto the chrome, where no
+   *  `pointermove` arrives to correct the stale position. Either way the modal
+   *  opened invisibly, and its guards swallow the wheel, the first click in
+   *  EITHER pane, and every non-modifier key including the space the pan gate
+   *  reads — which is the whole of "I can't move or pan around". */
+  const lastPointer = useRef<{ at: readonly [number, number]; buttons: number; inside: boolean }>({
+    at: [0, 0],
+    buttons: 0,
+    inside: false,
+  });
+  /** The pane the cursor is over, so a crossing writes `activePane` ONCE. */
+  const hoverPane = useRef<StagePane | null>(null);
+
+  const doc = state.doc;
+  const size = doc?.size ?? { width: 1920, height: 1080 };
+  // How far the working pane may dolly, derived from THIS document's fit. Every
+  // navigation writer passes it; the derived-pose writers (fit, isolation seed)
+  // deliberately do not. Memoised on the two numbers because it runs a
+  // `defaultWorkingView` and every wheel event would otherwise repeat it.
+  const dolly = useMemo(() => dollyBounds(size), [size.width, size.height]);
+  // Stable for the stage's lifetime, so the runtime's mount effect can hold it
+  // in a ref and stay a mount-only effect. It bumps a plain counter on the feed
+  // and touches no React state: a layer arriving must not re-commit the stage.
+  const bumpSceneEpoch = useCallback(() => {
+    feed.sceneEpoch += 1;
+  }, [feed]);
+  // Straight across the bridge. Stable identity so the runtime's effect stays
+  // a mount-only one; `client` is the stage's own handle and never changes.
+  const pushMeshStats = useCallback(
+    (layerId: string, triangles: number | null) => {
+      client.handlers()?.onMeshStats(layerId, triangles);
+    },
+    [client],
+  );
+  const view = state.view;
+  const layout = state.layout;
+  const workingView = state.workingView;
+  const follows = state.cameraFollowsView;
+
+  // The area's client origin, maintained by the SAME ResizeObserver that
+  // measures the viewport — never read per event. `localPoint` runs on every
+  // pointermove of every drag, and a `getBoundingClientRect` there is a forced
+  // layout read against a layout the same move's render just invalidated. The
+  // area is `position: fixed; inset: 0` today (origin 0,0 always); the ref
+  // keeps this honest if that ever changes.
+  const areaOrigin = useRef<readonly [number, number]>([0, 0]);
+  useViewportSize(areaRef, setViewport, areaOrigin);
+
+  const panes = useMemo(() => paneRects(layout, viewport), [layout, viewport]);
+
+  // ── A MOVED DIVIDER INVALIDATES "WHICH PANE IS THE POINTER OVER" ─────────
+  //
+  // `onPointerHover` reports a pane crossing ONCE, deduped against
+  // `hoverPane`. But a panel collapse, a window resize or a divider drag moves
+  // the boundary under a STATIONARY cursor, with no pointermove to follow —
+  // and the dedupe then pins the disagreement indefinitely, so Home and the
+  // zoom keys keep addressing a pane the author is no longer pointing at.
+  //
+  // Keyed on `panes` and not on `layout.mode`, because all three of those
+  // change the rects without necessarily changing the mode.
+  useEffect(() => {
+    hoverPane.current = null;
+  }, [panes]);
+
+  // ── THE RESOLVED POSITION, AND ISOLATION ─────────────────────────────────
+  //
+  // UP HERE, above the gesture lanes, because `paneScreenScale` below is read
+  // by `startModal`, `runTransformGesture` and `runGizmoGesture` — all of which
+  // are declared before the render half of this component. The rest of the
+  // frame's derivations (effects, bins, the camera rig) stay where they are.
+  //
+  // Where the playhead lands in the document, resolved ONCE. It rides the SAME
+  // size-1 caches ShotRuntime reads (frameCache.ts), so the stage and the
+  // runtime cannot compute the frame twice — the second caller replays the
+  // first one's answer.
+  const at = useMemo(
+    () => (doc === null ? null : masterToSceneCached(doc, state.frame)),
+    [doc, state.frame],
+  );
+  // Isolation is derived from ONE id and the document the stage already has,
+  // rather than pushed as a set: a set the chrome computed could disagree with
+  // the tree after any edit, and the two would then argue about what is
+  // pickable. Both memos are keyed on the resolved position, so the frame
+  // follows a parent's animation while the author is inside a card.
+  const isolated = useMemo(
+    () =>
+      // NOT IN THIS SCENE MEANS NOT ISOLATED. `withDescendants` answers a set
+      // holding the seed whether or not the seed exists, so an id from another
+      // document — or from another scene, once the playhead has moved on —
+      // produces a "keep" set that no layer matches: every layer dims and
+      // `pickable` filters to empty. A uniformly dead pane with nothing to
+      // click is worse than no isolation, and this one guard is what makes the
+      // dim, the picking and the badge agree by construction.
+      state.isolation === null || at === null || at.scene.layersById[state.isolation] === undefined
+        ? null
+        : withDescendants(at.scene, [state.isolation]),
+    [state.isolation, at],
+  );
+  const isolationView = useMemo(
+    () =>
+      state.isolation === null || at === null || isolated === null || doc === null
+        ? null
+        : isolationFrame(at.scene, state.isolation, isolated, at.sceneFrame, doc.fps),
+    [state.isolation, at, isolated, doc],
+  );
+  /**
+   * The derived head-on rig, or null once the AUTHOR owns the camera.
+   *
+   * Every consumer that means "which camera is drawing this pane" reads this
+   * and not `isolationView`: the ortho rig in `StageTools`, the screen scale
+   * below, and the nav gizmo. `isolationView` itself stays the geometry, which
+   * the seeding effect still needs after the hand-over.
+   */
+  const headOnRig = state.isolationOrbit ? null : isolationView;
+
+  /**
+   * CSS px per design px in a pane, asked of the camera ACTUALLY IN THE SLOT.
+   *
+   * `workingScreenScale` derives it from the orbit rig's distance and lens —
+   * correct, until isolation swaps an orthographic camera in and stops reading
+   * `workingView` at all. Every consumer then measured against a pose that was
+   * drawing no pixels: a 400px card isolated in a 1080x1920 document gives a
+   * true scale near 4.1 against a frozen 0.37, so a depth drag ran an order of
+   * magnitude fast and the snap threshold bit at a distance with no relation to
+   * anything on screen.
+   *
+   * NOT ON THE FEED, tempting as that is. An `OrthographicCamera` carries its
+   * own extents but a `PerspectiveCamera` does not carry its target distance,
+   * so the perspective branch would still have to come back here for
+   * `workingView`. This is the one place that knows both.
+   *
+   * The aspect expression is character-for-character `StageTools`' own, so the
+   * two derivations of the ortho extent cannot drift apart.
+   */
+  const paneScreenScale = (rect: PaneRect): number =>
+    headOnRig === null
+      ? workingScreenScale(workingView, rect.height, WORKING_FOV_DEG)
+      : rect.height /
+        (2 * isolationExtent(headOnRig, rect.height === 0 ? 1 : rect.width / rect.height).halfHeight);
+
+  /**
+   * SEED THE ORBIT RIG WHERE THE HEAD-ON RIG STANDS, once per entry.
+   *
+   * So the author's first orbit continues from what is on screen instead of
+   * from wherever the camera was before they entered the subtree. It runs while
+   * the derived rig is still drawing, so it changes no pixel — it only makes
+   * the hand-over continuous.
+   *
+   * ORIGIN "fit", and that is load-bearing: this is a pose the stage derived
+   * ITSELF, so under follow mode it must not reach `writeFramingFromView` and
+   * rewrite the shot camera of a document the author merely opened a card in.
+   * The bridge is written directly for the same reason the document-open fit
+   * does it — the local `setWorkingView` is the gesture path.
+   */
+  const seededFor = useRef<string | null>(null);
+  useEffect(() => {
+    if (state.isolation === null) {
+      seededFor.current = null;
+      return;
+    }
+    if (state.isolationOrbit || isolationView === null || panes.working === null) return;
+    if (seededFor.current === state.isolation) return;
+    seededFor.current = state.isolation;
+    const rect = panes.working;
+    const { halfHeight } = isolationExtent(isolationView, rect.height === 0 ? 1 : rect.width / rect.height);
+    const seeded = workingViewForIsolation(isolationEye(isolationView).eye, isolationView.target, halfHeight);
+    client.bridge.setWorkingView(seeded);
+    client.handlers()?.onWorkingViewChange(seeded, "fit");
+  }, [client, state.isolation, state.isolationOrbit, isolationView, panes.working]);
+
+  /** What the in-pane badge says. Off `isolationView` and not off `isolation`
+   *  alone, so a stale id — one the scene no longer holds — announces no mode
+   *  the pane is not actually in. */
+  const isolationLabel = useMemo(() => {
+    if (state.isolation === null || at === null || isolationView === null) return null;
+    const label = at.scene.layersById[state.isolation]?.label ?? state.isolation;
+    // ── AND WHETHER IT IS ACTUALLY ON SCREEN ──────────────────────────────
+    //
+    // A layer outside its own lifespan at this frame is dimmed away with
+    // everything else, so the pane is uniformly dark with nothing to click and
+    // the badge said only "INSIDE CARD" — which reads as the mode being broken
+    // rather than as the playhead being somewhere the card is not.
+    //
+    // `isolated` is the subtree, so this is true when NO member is drawing:
+    // a group whose children are all off-lifespan is just as blank.
+    const drawing = (feed.frames ?? []).some((f) => isolated?.has(f.id) === true);
+    return drawing ? label : `${label} — NOT ON SCREEN AT THIS FRAME`;
+    // `feed.frames` is a mutable field, so this cannot be keyed on it. The
+    // playhead is what changes the answer, and `at` carries it.
+  }, [state.isolation, at, isolationView, isolated, feed]);
+  // The camera pane is what the view offset, the fit and the zoom anchor are
+  // all measured against — `view.ts` still knows nothing about panes, it is
+  // simply handed a smaller viewport. Falling back to the whole canvas keeps
+  // those three total while the working pane is the only one on screen.
+  const cameraViewport = panes.camera ?? viewport;
+  // WHENEVER THE WORKING PANE IS ON SCREEN, not only in a split. A working-only
+  // layout has no camera pane at all, so leaving `ShotRuntime` to present would
+  // draw the shot camera across a viewport the author asked to see from
+  // somewhere else. The camera-only layout is the one — and the only one — that
+  // stays on the runtime's own path, which is the path an export shares.
+  const ownsPresent = panes.working !== null;
+
+  const fit = useCallback(
+    (): ShotView => fitView(cameraViewport, size),
+    [cameraViewport, size.width, size.height],
+  );
+  /**
+   * Frame the whole canvas, KEEPING where the author is standing.
+   *
+   * Blender's Frame All moves the target and the distance and never the
+   * angles, and numpad-dot in this editor already worked that way
+   * (`fitWorkingViewToSelection`). Home did not: it went back to the canonical
+   * three-quarter pose, so an author who had lined up an elevation lost it to
+   * a key they pressed to see everything.
+   *
+   * DONE IN THE FITTER and not in `defaultWorkingView`, because that function
+   * is also `INITIAL_WORKING_VIEW` and the document-open fit — both of which
+   * genuinely want the canonical pose. Read at CALL time, so the angles are
+   * whatever they are when Home is pressed rather than whatever they were when
+   * this callback was built.
+   */
+  const fitWorking = useCallback((): WorkingView => {
+    const at = client.getState().workingView;
+    return {
+      ...defaultWorkingView(size, WORKING_FOV_DEG),
+      theta: at.theta,
+      phi: at.phi,
+      // Spread conditionally: `exactOptionalPropertyTypes` is on, so writing
+      // `ortho: undefined` is not the same as omitting it.
+      ...(at.ortho === undefined ? {} : { ortho: at.ortho }),
+    };
+  }, [client, size.width, size.height]);
+  useEffect(() => {
+    client.setFitter(fit);
+    client.setWorkingFitter(fitWorking);
+    return () => {
+      client.setFitter(null);
+      client.setWorkingFitter(null);
+    };
+  }, [client, fit, fitWorking]);
+
+  // The chrome's data seam onto the overlay geometry. Rendering the outline is
+  // the stage's job (see Overlays), but a panel that wants to sit beside the
+  // selection needs the numbers.
+  useEffect(() => {
+    client.setQuadSource((pane) => {
+      const quads = pane === "working" ? feed.quadsWorking : feed.quadsCamera;
+      // Length, not `feed.ids.length`: a pane that is off screen holds no quads
+      // even though the selection is not empty, and answering with a shorter
+      // array zipped against the ids would pair a layer with another's outline.
+      return quads.length === 0 ? null : feed.ids.slice(0, quads.length).map((id, i) => ({ id, pts: quads[i]! }));
+    });
+    return () => client.setQuadSource(null);
+  }, [client, feed]);
+
+  // Fit once, when a document first arrives at a laid-out viewport. Re-fitting
+  // on every doc push would fight the author's own zoom on every autosave.
+  const fittedFor = useRef<string | null>(null);
+  /** The exact view the last auto-fit produced, so a later refit can tell "the
+   *  author has not touched it" from "the author framed something". */
+  const lastFit = useRef<ShotView | null>(null);
+  useEffect(() => {
+    if (doc === null || viewport.width === 0 || fittedFor.current === doc.id) return;
+    fittedFor.current = doc.id;
+    const next = fit();
+    lastFit.current = next;
+    client.bridge.setView(next);
+    client.handlers()?.onViewChange(next);
+    // Both panes get framed by the same event: opening a document into a split
+    // and finding the working pane looking at the previous document's canvas
+    // would be the same bug the camera fit exists to prevent.
+    //
+    // ORIGIN "fit", and that is not decoration. This line is a MIRROR of a view
+    // the stage derived itself; follow mode listens on the same handler an
+    // orbit uses, so without the discriminator opening a shot while follow is
+    // armed silently overwrites its camera and autosaves it.
+    const working = fitWorking();
+    client.bridge.setWorkingView(working);
+    client.handlers()?.onWorkingViewChange(working, "fit");
+  }, [client, doc, fit, fitWorking, viewport.width]);
+
+  /**
+   * THE CAMERA PANE REFITS WHEN IT CHANGES SIZE, but only if the author never
+   * framed anything themselves.
+   *
+   * Entering a split halves the pane's width, and the frame the author was
+   * looking at is then cut off with no key pressed to explain it. Refitting is
+   * what every design tool does; what none of them do is overwrite a zoom the
+   * author chose, which is why this compares against the LAST AUTO-FIT rather
+   * than refitting unconditionally.
+   *
+   * Reference equality is the right test: `setView` only ever passes fresh
+   * objects, so `view === lastFit.current` means nothing has written since.
+   */
+  useEffect(() => {
+    if (doc === null || panes.camera === null || lastFit.current === null) return;
+    if (view !== lastFit.current) return;
+    const next = fit();
+    if (next.zoom === view.zoom && next.panX === view.panX && next.panY === view.panY) return;
+    lastFit.current = next;
+    client.bridge.setView(next);
+    client.handlers()?.onViewChange(next);
+  }, [client, doc, fit, panes.camera, view]);
+
+  const setView = useCallback(
+    (next: ShotView) => {
+      client.bridge.setView(next);
+      client.handlers()?.onViewChange(next);
+    },
+    [client],
+  );
+
+  const setWorkingView = useCallback(
+    (next: WorkingView, origin: WorkingViewOrigin = "gesture") => {
+      const s = client.getState();
+      // ── INSIDE ISOLATION, THE FIRST GESTURE TAKES THE CAMERA ────────────
+      //
+      // The derived orthographic head-on rig is the ENTRY pose, not a cage.
+      // While it owns the slot nothing reads `workingView`, so this used to
+      // swallow the write — which is correct as far as it goes (under follow,
+      // projecting an unseen pose onto the shot camera rewrites and autosaves
+      // the document) but leaves an author who orbits with a pane that does
+      // nothing and says nothing. Blender's local view scopes what you see and
+      // leaves the camera free; so does this now.
+      //
+      // The chrome owns the mode, flips its bit and pushes it back down, so the
+      // ordinary orbit rig takes over from the NEXT commit. This gesture's own
+      // pose still lands, because `workingView` was seeded to the head-on rig's
+      // own pose on entry (see the seeding effect) — so the first orbit
+      // continues from what is on screen rather than jumping to wherever the
+      // camera happened to be before the author entered.
+      //
+      // ORIGIN MATTERS. Only a real navigation gesture takes the camera. A
+      // "fit" is the stage mirroring a pose it derived itself, which must not
+      // silently leave head-on mode.
+      if (s.isolation !== null && !s.isolationOrbit) {
+        if (origin === "fit") return;
+        client.handlers()?.onIsolationOrbitTaken();
+      }
+      client.bridge.setWorkingView(next);
+      client.handlers()?.onWorkingViewChange(next, origin);
+    },
+    [client],
+  );
+
+  const onReady = useCallback(
+    (info: { backend: string }) => {
+      if (doc === null) return;
+      client.handlers()?.onReady({
+        width: doc.size.width,
+        height: doc.size.height,
+        durationFrames: durationOf(doc),
+        backend: info.backend,
+      });
+    },
+    [client, doc],
+  );
+
+  // The project's own modules for every `instance` layer. Resolved HERE
+  // because this file is the only one served through the project's Vite; the
+  // chrome is a prebuilt bundle with no view of the project graph.
+  const instances = useInstanceModules(client, doc);
+
+  useKeyRelay(client, spaceRef, spacePanned, refreshCursorRef);
+
+  /**
+   * The pen's terminators: Enter or a double-click commits, Escape abandons.
+   *
+   * ── WHY THE KEY LISTENER IS IN THE CAPTURE PHASE ────────────────────────
+   *
+   * `useKeyRelay` forwards every keystroke to the chrome, where Escape CLEARS
+   * THE SELECTION. Both are correct and only one of them may happen: an author
+   * abandoning a half-drawn path must not also lose what they had selected. A
+   * capture-phase listener on window runs before the relay's bubble-phase one,
+   * and `stopPropagation` there means the event never reaches it.
+   *
+   * Mounted only while the pen HOLDS POINTS, so with no path in progress
+   * Escape is the chrome's as it always was.
+   */
+  /**
+   * Hand the path to the chrome and clear the pen.
+   *
+   * The anchors AND both handles move to canvas-centre origin together: a
+   * handle is an absolute point in the same space as the anchor it belongs to,
+   * not an offset from it, so converting the anchor alone would leave every
+   * curve pointing at where the old origin used to be.
+   *
+   * Under two anchors `penData` answers null and this sends nothing — one
+   * anchor is a layer with no geometry and no way to select it, and refusing
+   * IS the behaviour (the same posture `onDraw` documents for an empty pen).
+   */
+  const commitPen = useCallback(
+    (next: PenState): void => {
+      const data = penData(next);
+      setPen(PEN_EMPTY);
+      if (data === null) return;
+      client.handlers()?.onPenCommit({
+        closed: data.closed,
+        points: data.points.map((p) => ({
+          p: centreOrigin(p.p, size),
+          ...(p.in === undefined ? {} : { in: centreOrigin(p.in, size) }),
+          ...(p.out === undefined ? {} : { out: centreOrigin(p.out, size) }),
+        })),
+      });
+    },
+    [client, size.width, size.height],
+  );
+
+  /**
+   * The pen in CAMERA-PANE px, for the preview.
+   *
+   * Every anchor and both its handles go through the same projection, for the
+   * reason `commitPen` gives about the origin shift: a handle is a point in the
+   * anchor's space, not an offset from it. `closeHot` is answered by
+   * `penCloses` rather than by a second distance test here, so the highlight
+   * and the click agree by construction.
+   */
+  const penScreen = useMemo(() => {
+    if (pen.points.length === 0) return null;
+    const project = (p: readonly [number, number]): [number, number] =>
+      designToScreen([p[0], p[1]], view, cameraViewport, size);
+    return {
+      closed: pen.closed,
+      cursor: pen.cursor === null ? null : project(pen.cursor),
+      closeHot:
+        pen.cursor !== null &&
+        penCloses(pen, pen.cursor, PEN_CLOSE_SLOP_PX / Math.max(view.zoom, MIN_INVERTIBLE_SCALE)),
+      points: pen.points.map((p) => ({
+        p: project(p.p),
+        ...(p.in === undefined ? {} : { in: project(p.in) }),
+        ...(p.out === undefined ? {} : { out: project(p.out) }),
+      })),
+    };
+  }, [pen, view, cameraViewport, size.width, size.height]);
+
+  useEffect(() => {
+    if (state.tool !== "path") {
+      // Arming another tool abandons the pen. The points are the pen's, and a
+      // path that committed later out of a tool the author had left would
+      // appear from nowhere.
+      if (pen.points.length > 0) setPen(PEN_EMPTY);
+      return;
+    }
+    if (pen.points.length === 0) return;
+    const area = areaRef.current;
+    const commit = (): void => commitPen(pen);
+    const onKey = (ev: KeyboardEvent): void => {
+      // Resolved through the KEYMAP, not by comparing key names here. The
+      // chrome's keymap is the one table that knows Escape means deselect
+      // when no path is open, and `penActive` is what tells it a path is —
+      // so the precedence lives in one readable place instead of being an
+      // accident of which listener happened to be in the capture phase.
+      const action = resolveKey(ev, { editing: false, hasSelection: false, penActive: true });
+      if (action?.kind !== "penCommit" && action?.kind !== "penAbandon") return;
+      ev.preventDefault();
+      ev.stopPropagation();
+      if (action.kind === "penCommit") commit();
+      else setPen(PEN_EMPTY);
+    };
+    window.addEventListener("keydown", onKey, true);
+    area?.addEventListener("dblclick", commit);
+    return () => {
+      window.removeEventListener("keydown", onKey, true);
+      area?.removeEventListener("dblclick", commit);
+    };
+  }, [client, pen, size.width, size.height, state.tool]);
+
+  const localPoint = (e: { clientX: number; clientY: number }): [number, number] => {
+    return [e.clientX - areaOrigin.current[0], e.clientY - areaOrigin.current[1]];
+  };
+
+  // ── THE MODAL TRANSFORM CONTROLLER (G / R / S) ──────────────────────────
+  //
+  // A modal transform is the EXISTING gesture lane re-driven: it opens the
+  // same onGestureStart / onGesture / onGestureEnd (or onFramingGesture*)
+  // scrub a pointer drag opens, so animate mode, snapping, refusals and
+  // one-undo-per-gesture all fall out unchanged. Only the input differs —
+  // mouse MOTION with no button held, terminated by click/Enter (confirm) or
+  // Escape/right-click (cancel). It registers ZERO pointer listeners: motion
+  // rides the pointer-move prop below, termination rides the pointerdown
+  // lane's first branch, and keys ride one capture-phase listener (the pen's
+  // pattern). The mapping tables live in modalState.ts.
+
+  const emitModal = (live: ModalLive): void => {
+    const handlers = client.handlers();
+    if (handlers === undefined || handlers === null) return;
+    const travel = { x: live.virtual[0] - live.anchor[0], y: live.virtual[1] - live.anchor[1] };
+    // ── A TYPED VALUE OUTRANKS THE POINTER ────────────────────────────────
+    //
+    // `G X 200 Enter`. While the buffer holds something, the mouse stops
+    // driving the transform entirely — Blender's own behaviour, and the reason
+    // backspacing it empty hands the gesture back rather than cancelling it.
+    //
+    // A PLANAR MOVE HAS NO SCALAR to replace: `designDelta` answers two
+    // components from two rays, and picking one for the author would guess.
+    // Blender requires an axis for a numeric move too, and the refusal says so
+    // in the pill rather than silently ignoring the digits.
+    const exact = typedValue(live.typed);
+    if (exact !== null && live.state.mode === "move" && live.state.axis === null) {
+      live.refusal = "TYPE AN AXIS FIRST · X Y Z";
+      modalReadoutSink.write?.(live.refusal);
+      return;
+    }
+    // ── A SCALE IS A FACTOR, AND ZERO IS NOT ONE ──────────────────────────
+    //
+    // `size` has no sign and no zero to come back from, so `applyGesture`
+    // refuses a non-positive ratio by name. The modal used to clamp the typed
+    // value to 0.1 before it ever got there, so `S 0 Enter` shrank the layer to
+    // a tenth of itself rather than being refused — the number the author typed
+    // silently replaced by another one. The table returns null; this names it.
+    if (exact !== null && live.state.mode === "scale" && !(exact > 0)) {
+      live.refusal = "A SCALE NEEDS A FACTOR ABOVE ZERO";
+      modalReadoutSink.write?.(live.refusal);
+      return;
+    }
+    let planar: { dx: number; dy: number; dz: number } | null = null;
+    if (live.state.mode === "move" && live.ray !== null && live.plane !== null) {
+      const to = feed.rayAt?.("working", live.virtual[0], live.virtual[1]) ?? null;
+      planar = to === null ? null : designDelta(live.ray, to, live.plane);
+    }
+    // A LIVE BUFFER IS SHOWN AS TYPED, not as the number it parses to, so the
+    // author can see `1.` while they are half way through `1.5`.
+    const echo = live.typed === "" ? null : `${live.typed}_`;
+    if (live.state.target === "camera") {
+      const delta = framingDeltaFor(live.state, travel, planar, DOLLY_FALLOFF_PX, exact);
+      // THE PILL'S NUMBERS COME OFF THE EMITTED DELTA, never re-derived from
+      // the travel: a readout computed a second way is one that can disagree
+      // with the thing moving under it. Written imperatively, because this runs
+      // per pointermove and the pill is memoised on state alone.
+      modalReadoutSink.write?.(live.refusal ?? echo ?? modalReadout(delta));
+      if (delta !== null) handlers.onFramingGesture(delta);
+      return;
+    }
+    // THE PANE'S SCALE IS RE-READ, not the one snapshotted at start. A window
+    // resize or a panel collapse mid-transform moves the divider, and a scale
+    // captured before it describes a pane that no longer exists — so the layer
+    // would suddenly grow at the wrong rate for the rest of the gesture.
+    // `travel` is measured in the virtual cursor's own accumulated px and is
+    // unaffected; only the px-to-design conversion has to stay current.
+    // Always the WORKING pane: modals only start over it (the keymap's
+    // `workingPane` gate), and the camera branch above returned already.
+    const scale = panes.working === null ? live.screenScale : paneScreenScale(panes.working);
+    const delta = layerGestureFor(live.state, travel, planar, scale, live.pivot, exact, live.snap);
+    modalReadoutSink.write?.(live.refusal ?? echo ?? modalReadout(delta));
+    if (delta !== null) handlers.onGesture(delta);
+  };
+
+  const flushModal = (): void => {
+    modalRaf.current = 0;
+    const live = modalRef.current;
+    if (live !== null) emitModal(live);
+  };
+
+  const endModal = (
+    commit: boolean,
+    /**
+     * Hand the cursor back? False ONLY on a live switch (`G` then `R`), which
+     * discards one modal and starts another inside the same keystroke.
+     *
+     * Chrome refuses a `requestPointerLock` that follows an exit too closely,
+     * so the exit-then-request pair a switch used to make left the new modal
+     * UNLOCKED for the rest of the gesture — and an unlocked modal cancels the
+     * moment the pointer leaves the stage, which on a long rotate is most of
+     * the time. Keeping the lock across the seam is the whole fix; every other
+     * caller really is ending the gesture and still releases.
+     */
+    release = true,
+  ): void => {
+    const live = modalRef.current;
+    if (live === null) return;
+    modalRef.current = null;
+    if (modalRaf.current !== 0) {
+      cancelAnimationFrame(modalRaf.current);
+      modalRaf.current = 0;
+    }
+    // Released FIRST, so the cursor is back under the author's control before
+    // anything else runs — and unconditionally for a real end, because a lock
+    // that outlived its modal would freeze the pointer with nothing left to
+    // drive.
+    if (release && document.pointerLockElement === areaRef.current) document.exitPointerLock?.();
+    // The final position lands before the end on a commit — dragGesture's own
+    // rule, so the layer cannot land a frame behind the pointer.
+    if (commit) emitModal(live);
+    const handlers = client.handlers();
+    if (live.state.target === "camera") handlers?.onFramingGestureEnd(commit);
+    else handlers?.onGestureEnd(commit);
+    setModal(null);
+  };
+  // Stable identity for the mount-once effects below; the function itself
+  // only touches refs and the (stable) client, so a stale closure is safe.
+  const endModalRef = useRef(endModal);
+  endModalRef.current = endModal;
+
+  const startModal = (
+    mode: ModalMode,
+    local: readonly [number, number],
+    rect: PaneRect,
+    /** The outgoing modal's `lastRaw` on a LIVE SWITCH (`G` then `R`), so the
+     *  first move after it measures one step and not the whole prior travel.
+     *  Absent on a fresh start, where the press point is both. */
+    lastRaw: readonly [number, number] = local,
+  ): void => {
+    const handlers = client.handlers();
+    if (handlers === undefined || handlers === null) return;
+    const target = modalTarget(state.selection.length > 0);
+    // ── NOTHING ON SCREEN, NOTHING TO TRANSFORM ─────────────────────────
+    //
+    // Hoisted ABOVE the mode branch, because it used to live inside the move
+    // arm only: `G` returned silently when no selected layer had a frame at
+    // this playhead, while `R` and `S` armed happily and transformed a layer
+    // nobody could see. All three want the same answer.
+    const onScreen = feed.frames?.find((f) => state.selection.includes(f.id)) ?? null;
+    if (target === "layers" && onScreen === null) return;
+    let ray: Ray | null = null;
+    let plane: Plane | null = null;
+    if (mode === "move") {
+      // The anchor ray and the plane, captured at start. Layers unproject on
+      // the FRAME plane through the first selected layer — the same plane
+      // the letter G already means in this editor — and the camera on z = 0,
+      // the plane its rectangle sits in. No ray means no camera on screen:
+      // nothing to start, better than a scrub that can never be fed.
+      ray = feed.rayAt?.("working", local[0], local[1]) ?? null;
+      if (ray === null) return;
+      if (target === "layers") {
+        // ANY selected layer that is on screen this frame, not `selection[0]`.
+        // The selection is DOCUMENT-ordered (see the store's `select`), so its
+        // first entry is whichever id sorts lowest — not the one the author
+        // grabbed, and not necessarily one that is alive at this frame. Taking
+        // the first that has a frame means a multi-select whose lowest member
+        // is outside its lifespan still transforms, instead of refusing the
+        // whole gesture with no explanation. Found once, above the branch.
+        plane = gesturePlane("frame", onScreen!.matrixWorld);
+      } else {
+        plane = Z0_PLANE;
+      }
+    }
+    const screenScale = paneScreenScale(rect);
+    // THE MEDIAN OF WHAT IS SELECTED, which is Blender's default pivot, and
+    // null for one layer — a single layer scaling about the median of itself is
+    // the same thing as scaling in place, and null says so without arithmetic.
+    // Off `feed.frames`, whose `matrixWorld` is the pose actually on screen at
+    // this frame, so an animated parent is already accounted for.
+    // ROTATE JOINS SCALE. The rotate ring passes a pivot and `R` did not, so a
+    // multi-selection orbited about its median from the ring and spun in place
+    // from the key. `layerGestureFor` puts it on the ROLL row only; a tilt about
+    // a shared point is not expressible (see there).
+    const pivot = mode === "scale" || mode === "rotate" ? selectionPivot(feed, state.selection) : null;
+    const modalState: ModalState = { mode, target, axis: null };
+    // ARMED ONLY IF THE SCRUB ACTUALLY OPENED. A pointer drag can absorb a
+    // refusal silently — the author releases and tries again — but a modal
+    // stays armed, so one that opened over another lane's scrub would drive
+    // THAT scrub with its own deltas and commit it. `false` here means a
+    // gesture or a wheel flick still holds the history.
+    const opened =
+      target === "camera"
+        ? handlers.onFramingGestureStart()
+        : handlers.onGestureStart(initialGestureKind(modalState), state.selection, screenScale);
+    if (opened === false) return;
+    // ── THE CURSOR IS PINNED FOR THE DURATION ─────────────────────────────
+    //
+    // A modal is driven by motion with no button held, so the pointer is free
+    // to leave the stage — and `onPointerLeave` then cancelled the transform.
+    // On a laptop trackpad that is a large scale or a long move most of the
+    // time. Locking removes the edge entirely; the emit integrates
+    // `movementX/Y` instead of reading an absolute point.
+    //
+    // ALLOWED HERE because a keydown carries transient user activation, which
+    // is what `requestPointerLock` requires. A browser that refuses (or an
+    // iframe without the permission) rejects, and the modal runs exactly as it
+    // did before — the fallback is today's behaviour, not a broken one.
+    //
+    // NOT RE-REQUESTED WHEN IT IS ALREADY HELD, which is the state a live
+    // switch leaves (see `endModal`'s `release`). Asking again would be a
+    // second promise to swallow for no change of state.
+    if (document.pointerLockElement !== areaRef.current) {
+      void areaRef.current?.requestPointerLock?.()?.catch?.(() => {});
+    }
+    modalRef.current = {
+      state: modalState,
+      rect,
+      anchor: local,
+      virtual: local,
+      lastRaw,
+      ray,
+      plane,
+      screenScale,
+      pivot,
+      refusal: null,
+      typed: "",
+      snap: false,
+    };
+    setModal(modalState);
+  };
+
+  const onModalKey = (ev: KeyboardEvent): void => {
+    const live = modalRef.current;
+    if (live !== null) {
+      // A live modal owns EVERYTHING except the modifier keys themselves
+      // (shift is its precision). Swallowing ⌘Z and Delete here is
+      // deliberate: a relayed transaction while the modal's scrub is open is
+      // the one thing the history model cannot absorb. The keymap's own lane
+      // stays honest about what those combos MEAN — the suppression is this
+      // listener's to own, not the table's to hide.
+      if (ev.key === "Shift" || ev.key === "Control" || ev.key === "Alt" || ev.key === "Meta") return;
+      ev.preventDefault();
+      ev.stopPropagation();
+      // AUTO-REPEAT IS SWALLOWED, not acted on. The axis keys TOGGLE, so a
+      // held X flips the constraint on and off at the OS repeat rate and the
+      // one the author ends up with is decided by how long they held the key
+      // — release on an even count and the axis they pressed to constrain is
+      // cleared instead. Nothing in this lane wants a repeat: the terminators
+      // are one-shot and the starters cannot reach here.
+      if (ev.repeat) return;
+      // `hasSelection` IS THE MODAL'S OWN SUBJECT, not a constant. It was
+      // hard-coded true, so `R` re-armed a ROTATE against the camera — which
+      // has no roll, so `emitModal` could never produce a delta, the pill still
+      // read CAMERA MOVE, and a typed `X 100 Enter` fell past the move-only
+      // axis refusal into `framingDeltaFor` and wrote a real 100px camera pan.
+      const action = resolveKey(keyOf(ev), {
+        editing: false,
+        hasSelection: live.state.target !== "camera",
+        transformModal: true,
+      });
+      if (action === null) return;
+      if (action.kind === "modalConfirm") endModal(true);
+      else if (action.kind === "modalCancel") endModal(false);
+      else if (action.kind === "modalStart") {
+        // ANOTHER TRANSFORM LETTER SWITCHES LIVE. Discarded rather than
+        // committed, so `G` then `R` rotates instead of leaving a move behind
+        // — and restarted at the ORIGINAL ANCHOR, so the rotation is measured
+        // from where the author pressed rather than from wherever the pointer
+        // had wandered while they were moving.
+        //
+        // ── BUT `lastRaw` CARRIES OVER ──────────────────────────────────
+        //
+        // The anchor is where the transform is measured FROM; `lastRaw` is
+        // where the POINTER last was. Re-seeding both to the anchor made the
+        // next pointermove read a step of "everything travelled during the
+        // move" and apply it in one jump. Under pointer lock the deltas are
+        // integrated from `movementX/Y` so it never showed; on the unlocked
+        // fallback path (an iframe with no permission, a browser that refused)
+        // it was the whole prior travel at once.
+        const anchor = live.anchor;
+        const rect = live.rect;
+        const lastRaw = live.lastRaw;
+        endModal(false, false);
+        startModal(action.mode, anchor, rect, lastRaw);
+      }
+      else if (action.kind === "modalAxis") {
+        const next = modalAxisToggle(live.state, action.axis);
+        if (next === live.state) {
+          // CLAIMED AND IGNORED. The key was already swallowed by the
+          // `preventDefault` above, so saying nothing here is
+          // indistinguishable from a key that never arrived.
+          live.refusal = axisRefusal(live.state, action.axis);
+          modalReadoutSink.write?.(live.refusal ?? "");
+          return;
+        }
+        live.state = next;
+        live.refusal = null;
+        setModal(next);
+        // Re-project what is already travelled under the new constraint.
+        if (modalRaf.current === 0) modalRaf.current = requestAnimationFrame(flushModal);
+      } else if (action.kind === "modalNumber") {
+        const next = typeNumber(live.typed, action.ch);
+        // A second decimal point is rejected rather than swallowed, so `1.2.3`
+        // cannot exist. Nothing to redraw when the buffer did not change.
+        if (next === null) return;
+        live.typed = next;
+        live.refusal = null;
+        if (modalRaf.current === 0) modalRaf.current = requestAnimationFrame(flushModal);
+      } else if (action.kind === "modalNumberBack") {
+        // Emptying it hands the transform back to the MOUSE rather than
+        // cancelling, which is what makes a mistyped digit recoverable.
+        live.typed = live.typed.slice(0, -1);
+        live.refusal = null;
+        if (modalRaf.current === 0) modalRaf.current = requestAnimationFrame(flushModal);
+      }
+      return;
+    }
+    if (doc === null) return;
+    const at = lastPointer.current;
+    // `inside` before the position is read at all: off the stage there is no
+    // cursor to anchor to and the coordinate below is a leftover (see the ref).
+    // `buttons !== 0` means a drag lane may be live; the pen's emptiness
+    // keeps its own capture listener and this one from fighting over a key.
+    if (!at.inside || at.buttons !== 0 || pen.points.length > 0) return;
+    const hit = paneAt(panes, at.at[0], at.at[1]);
+    if (hit === null || hit.pane !== "working") return;
+    const action = resolveKey(keyOf(ev), {
+      editing: isEditable(ev.target),
+      hasSelection: state.selection.length > 0,
+      workingPane: true,
+    });
+    // `B` ARMS A BOX SELECT for the next press, and it is consumed HERE rather
+    // than in the chrome: the marquee is the stage's own lane, and a bit that
+    // crossed the bridge would be one round trip behind the press it arms.
+    if (action?.kind === "boxSelect") {
+      boxSelectRef.current = true;
+      ev.preventDefault();
+      ev.stopPropagation();
+      return;
+    }
+    if (action?.kind !== "modalStart") return;
+    ev.preventDefault();
+    ev.stopPropagation();
+    startModal(action.mode, hit.local, panes.working as PaneRect);
+  };
+  const onModalKeyRef = useRef(onModalKey);
+  onModalKeyRef.current = onModalKey;
+
+  useEffect(() => {
+    // Registered ONCE, reading the current handler through a ref (the wheel
+    // lane's pattern). Capture phase so a consumed start/terminator never
+    // reaches useKeyRelay's bubble listener — same reason the pen's is.
+    const down = (ev: KeyboardEvent): void => onModalKeyRef.current(ev);
+    // A blur mid-modal (clicked into the chrome, alt-tabbed) cancels: keys
+    // and motion stop arriving, and an abandoned open scrub outlives them.
+    const blur = (): void => endModalRef.current(false);
+    window.addEventListener("keydown", down, true);
+    window.addEventListener("blur", blur);
+    return () => {
+      window.removeEventListener("keydown", down, true);
+      window.removeEventListener("blur", blur);
+      endModalRef.current(false);
+    };
+  }, []);
+
+  // A document switch mid-modal cancels — the store's doc-swap discard is
+  // the backstop, not the plan. The `B` arm goes with it: an armed one-shot is
+  // a mode the author is in, and modes do not survive the document they were
+  // armed over.
+  useEffect(
+    () => () => {
+      endModalRef.current(false);
+      boxSelectRef.current = false;
+    },
+    [doc?.id],
+  );
+
+  /**
+   * The pen's rubber band and close highlight follow the cursor between
+   * presses, and only then.
+   *
+   * Cheap by construction: it returns before touching state unless the pen
+   * actually holds a point, so with any other tool armed this is one comparison
+   * per pointer event. `penReduce`'s `move` with no drag open advances `cursor`
+   * alone, so hover needs no branch of its own in the model.
+   */
+  /** Every pointer event updates the cursor box, not just moves. `buttons` is
+   *  a GATE on starting a modal, and a move-only writer leaves it stale in
+   *  both directions: no `pointermove` is emitted on release, so one stuck at
+   *  1 makes G/R/S silently arm tools forever after; and a press with no
+   *  motion leaves it at 0, which would let a modal open on top of a live
+   *  drag's scrub. */
+  const onPointerTrack = (e: React.PointerEvent<HTMLDivElement>): void => {
+    lastPointer.current = { at: localPoint(e), buttons: e.buttons, inside: true };
+  };
+
+  /**
+   * The cursor left the stage: no modal can be started, and a live one is
+   * cancelled.
+   *
+   * A modal is driven by MOTION over the pane. Off the stage none arrives, so
+   * it can neither be aimed nor confirmed — while its guards go on eating the
+   * wheel, the first press in either pane and the whole keyboard, until the
+   * author guesses Escape. `window`'s blur cancel is not this: blur needs a
+   * CLICK into the chrome, and hovering it is enough to strand one.
+   */
+  /**
+   * The container's cursor, written IMPERATIVELY and exactly once.
+   *
+   * ── WHY NOT REACT ───────────────────────────────────────────────────────
+   *
+   * It changes on every pointermove, and a move already costs a stage commit
+   * and a GL draw when a gesture is live. Routing the cursor through state
+   * would add a full re-render per move to change one string. The last-written
+   * guard makes the common case (the cursor did not change) a string compare.
+   *
+   * ── AND WHY THERE MUST BE ONLY ONE WRITER ───────────────────────────────
+   *
+   * The JSX style object used to carry `cursor: spaceRef.current ? ... `, read
+   * from a REF during render — so it only reached the DOM when something
+   * unrelated happened to commit, which is why the stage appeared to have no
+   * cursor behaviour at all. Leaving that in place alongside this would be
+   * worse than the original bug: React would win on its next commit and the
+   * cursor would be intermittently right, which nobody can debug.
+   */
+  // Seeded EMPTY, mirroring the element's own inline style rather than the
+  // effective value. Seeding it "default" makes the first write to "default" a
+  // no-op, so a stage whose first answer is the default never writes at all and
+  // the ref stops describing the DOM.
+  const cursorRef = useRef("");
+  const setCursor = useCallback((next: string): void => {
+    if (next === cursorRef.current) return;
+    cursorRef.current = next;
+    const el = areaRef.current;
+    if (el !== null) el.style.cursor = next;
+  }, []);
+
+  /**
+   * Arm or disarm the navigation cursor.
+   *
+   * Two writes, and both are needed. The IMPERATIVE one is what puts the shape
+   * on screen at the press, the way the pan lane already does it. The REF is
+   * what makes it survive: an orbit calls `setWorkingView` on every move, every
+   * one of those is a commit, and while a real browser reports a held button
+   * (so `refreshCursor` bails) nothing guarantees that — a synthetic move, or a
+   * commit from anywhere else in the stage, would otherwise re-answer the
+   * cursor from what is UNDER the pointer, which during a navigation drag is
+   * not the subject.
+   */
+  const setNavCursor = useCallback(
+    (next: string | null): void => {
+      navCursorRef.current = next;
+      if (next !== null) {
+        setCursor(next);
+        return;
+      }
+      // Disarming drops to the default BEFORE asking for the real answer,
+      // because `refreshCursor` bails while a button is still reported down —
+      // and at a pointerup the tracked `buttons` is still the drag's. Without
+      // this the closed hand would outlive the gesture until the next move.
+      setCursor("default");
+      refreshCursorRef.current();
+    },
+    [setCursor],
+  );
+
+  /**
+   * The cursor for what is under the pointer, in precedence order.
+   *
+   * The order matters and is not the same as the press lane's: a held space bar
+   * outranks everything because the NEXT press pans whatever it is over, and a
+   * live gesture holds whatever shape it started with because the thing being
+   * dragged has already left the pointer's own position behind.
+   */
+  const cursorFor = useCallback(
+    (pane: StagePane | null, intent: StageIntent | null): string => {
+      // A LIVE NAVIGATION DRAG OUTRANKS EVERYTHING, and it has to be answered
+      // here rather than written imperatively at the press. An orbit or a dolly
+      // calls `setWorkingView` on every move, every one of those is a commit,
+      // and the per-commit effect below re-answers the cursor from what is
+      // UNDER the pointer — which during a navigation drag is not the subject.
+      // An imperative write would therefore survive exactly until the first
+      // move, which is the moment it starts mattering.
+      if (navCursorRef.current !== null) return navCursorRef.current;
+      if (spaceRef.current) return "grab";
+      if (pane === null || intent === null) return "default";
+      switch (intent.kind) {
+        case "grab":
+          if (intent.grab.handleAngle === undefined) return "move";
+          // A UNION HANDLE GETS THE RESIZE CURSOR TOO. What the drag writes
+          // differs (a ratio about a pivot, not one layer's edge), but what the
+          // POINTER does is identical — the corner follows it outward — and a
+          // cursor that said otherwise would be describing the implementation
+          // rather than the gesture.
+          return intent.grab.kind === "roll"
+            ? rotateCursorFor(intent.grab.handleAngle)
+            : intent.grab.kind === "resize" || intent.grab.kind === "scale"
+              ? resizeCursorFor(intent.grab.handleAngle)
+              : "move";
+        case "arm":
+        case "frustum":
+          return "crosshair";
+        case "empty":
+          // The armed TOOL, at last: `ToolSpec.cursor` has carried a column for
+          // all 13 rows, and been tested, with no reader in the stage at all.
+          // Forced back to the default in the working pane, because the draw
+          // tools only act in the camera one (a free orbit has no screen
+          // rectangle that corresponds to a drawn box) and a crosshair over a
+          // pane that will answer with an orbit is a promise the lane breaks.
+          return pane === "working" && isDrawTool(state.tool) ? "default" : specOf(state.tool).cursor;
+      }
+    },
+    [state.tool],
+  );
+
+  const onPointerLeave = (): void => {
+    lastPointer.current = { ...lastPointer.current, inside: false };
+    setCursor("default");
+    setHover(null);
+    // A LIVE MODAL UNDER POINTER LOCK DOES NOT LEAVE. The lock freezes the
+    // cursor, so a `pointerleave` while it holds is the browser's doing and
+    // not the author's — cancelling there would throw away a transform for a
+    // reason they never caused.
+    if (document.pointerLockElement === areaRef.current) return;
+    endModalRef.current(false);
+  };
+
+  const onPointerHover = (e: React.PointerEvent<HTMLDivElement>): void => {
+    const at = localPoint(e);
+    lastPointer.current = { at, buttons: e.buttons, inside: true };
+    const live = modalRef.current;
+    if (live !== null) {
+      // The modal is driven by MOTION with no button held. Raw steps
+      // accumulate into a virtual cursor (shift scales them — precision) and
+      // the emit coalesces to the frame, dragGesture's own pattern.
+      //
+      // UNDER POINTER LOCK the absolute position is frozen and only
+      // `movementX/Y` is real, so the raw point is integrated from the deltas.
+      // That is what lets a transform run past the edge of the window without
+      // the pointer leaving and cancelling it — Blender wraps the cursor for
+      // the same reason.
+      const locked = document.pointerLockElement === areaRef.current;
+      const raw: readonly [number, number] = locked
+        ? [live.lastRaw[0] + e.movementX, live.lastRaw[1] + e.movementY]
+        : [at[0] - live.rect.x, at[1] - live.rect.y];
+      const moved = raw[0] !== live.lastRaw[0] || raw[1] !== live.lastRaw[1];
+      live.virtual = advanceVirtual(live.virtual, live.lastRaw, raw, e.shiftKey);
+      live.lastRaw = raw;
+      // ── A REFUSAL DESCRIBES A KEY, NOT THE TRANSFORM ────────────────────
+      //
+      // It was only ever cleared by another KEY, so "SIZE HAS NO Z" sat in the
+      // pill while the author kept moving the mouse and the size kept changing
+      // — the live numbers never came back and the message described nothing
+      // that was still happening. Any real motion is the author moving on.
+      if (moved) live.refusal = null;
+      // Read PER EVENT, like shift's precision: the author holds and releases
+      // ctrl mid-gesture to nudge onto a round number and off again.
+      live.snap = e.ctrlKey || e.metaKey;
+      if (modalRaf.current === 0) modalRaf.current = requestAnimationFrame(flushModal);
+      return;
+    }
+    const hit = paneAt(panes, at[0], at[1]);
+    // ── THE PANE UNDER THE CURSOR IS THE ACTIVE ONE ───────────────────────
+    //
+    // `activePane` decides what Home fits and what the zoom keys and the
+    // header's zoom buttons address, and until now only a PRESS or a WHEEL
+    // wrote it. In split that leaves it wherever it was: entering split from
+    // camera-only keeps `"camera"` (the store forces the pane to the mode in
+    // the single-pane layouts, so this is split's alone), and Home then fits a
+    // pane the author is not pointing at while the one they are pointing at
+    // does nothing. Hover is the answer the author already believes, and it is
+    // the same rule the modal starters and the shading bar read.
+    //
+    // Once per CROSSING, not once per move: `onActivePane` is a store write
+    // and the chrome re-renders on it.
+    if (hit !== null && hit.pane !== hoverPane.current) {
+      hoverPane.current = hit.pane;
+      client.handlers()?.onActivePane(hit.pane);
+    }
+    // THE CURSOR SAYS WHAT THE PRESS WOULD DO, off the same `intentAt` the
+    // press itself switches on. Not behind the `onActivePane` gate above: that
+    // one fires once per pane CROSSING, and the cursor has to change every time
+    // the pointer crosses a handle.
+    //
+    // No React work: `setCursor` is a string compare and, on a change, one
+    // style write. `intentAt` is three feed calls, the same three the press
+    // makes, and the press lane already runs them per press.
+    if (e.buttons === 0) {
+      const intent = hit === null ? null : intentAt(hit.pane, hit.local[0], hit.local[1]);
+      setCursor(hit === null ? cursorFor(null, null) : cursorFor(hit.pane, intent));
+      // The arm under the pointer lights up. A plain field write, read by
+      // `MoveGizmo` inside the frame loop, so a hover costs no React work at
+      // all — see `feed.hoverArm`.
+      feed.hoverArm = intent?.kind === "arm" ? intent.arm.axis : null;
+      // THE HIGHLIGHT, only over empty space. Over a handle or an already
+      // selected body the press is a transform, not a selection change, so
+      // previewing a selection there would promise something the click will
+      // not do.
+      const over =
+        hit === null || intent === null || intent.kind !== "empty"
+          ? null
+          : hit;
+      const quad = over === null ? null : (feed.hoverQuad?.(over.pane, over.local[0], over.local[1]) ?? null);
+      setHover((prev) => {
+        if (quad === null || over === null) return prev === null ? prev : null;
+        if (prev !== null && prev.pane === over.pane && !quadMoved(prev.quad, quad)) return prev;
+        return { pane: over.pane, quad };
+      });
+    }
+    if (state.tool !== "path" || pen.points.length === 0 || pen.drag !== null) return;
+    if (hit === null || hit.pane !== "camera") return;
+    const design = screenToDesign(hit.local, view, cameraViewport, size);
+    setPen((prev) => penReduce(prev, { kind: "move", at: design, dragThreshold: PEN_DRAG_THRESHOLD_PX }));
+  };
+
+  /**
+   * Double-click: go inside what is under the cursor.
+   *
+   * Reads the pick list fresh rather than trusting the selection the
+   * pointerdown lane just made — a double-click whose first press landed on a
+   * layer and whose second landed a few pixels away, on another, should enter
+   * what the author is pointing at now.
+   */
+  const onDoubleClick = (e: React.MouseEvent<HTMLDivElement>): void => {
+    if (doc === null || isDrawTool(state.tool)) return;
+    const hit = paneAt(panes, ...localPoint(e));
+    if (hit === null) return;
+    const hits = feed.pick?.(hit.pane, hit.local[0], hit.local[1]) ?? [];
+    if (hits.length > 0) client.handlers()?.onEnterLayer(hits, hit.pane);
+  };
+
+  /**
+   * WHAT A PRESS AT THIS POINT WOULD DO. Position only, no buttons, no keys.
+   *
+   * ── WHY THIS IS ONE FUNCTION AND NOT A SEQUENCE OF `return`s ────────────
+   *
+   * It used to be the tail of `onPointerDown`, and it had exactly one caller,
+   * so nothing could ask "what would happen here" without actually making it
+   * happen. That is why the stage had no hover cursor: the answer existed only
+   * as a side effect. Now the press lane switches on it and the hover lane maps
+   * it to a cursor, so the shape under the pointer IS the thing the press does.
+   *
+   * ── THE ORDERING, WHICH IS FORCED ───────────────────────────────────────
+   *
+   * ARMS FIRST. An arm is drawn ON TOP OF the thing it belongs to and overlaps
+   * it, so a gizmo hit ranked below `grabAt` could never be reached: the body
+   * grab would take every press the arm sits over, which is most of the arm at
+   * a shallow orbit. The arms are small screen-space targets nothing else
+   * claims, exactly like the frustum's apex.
+   *
+   * AND THE APEX STILL WORKS UNDERNEATH, because the arms start 30 screen px
+   * out — more than this test's slop plus the apex's own — so a press aimed at
+   * the apex misses all three and falls through to the frustum lane. That
+   * inequality is the whole reason ARM_START_PX has a value rather than a look.
+   *
+   * THEN THE SELECTION. A press on it is a transform, not a selection change: a
+   * handle resizes, the body moves. Pressing an UNselected layer falls through
+   * to the click lane, because dragging something the author had not selected
+   * is the classic way to move the wrong thing.
+   *
+   * THEN THE CAMERA GIZMO, and its rank is the subtlety. The frustum's base
+   * quad is COPLANAR WITH EVERY LAYER — it is the rectangle the layers live in
+   * — so a frustum hit that outranked a layer would make layers unselectable in
+   * this pane, and one that outranked the orbit everywhere inside the frame
+   * would take away the pane's primary gesture. Behind the layers and in front
+   * of empty space is the only ordering in which all three stay reachable. The
+   * APEX is exempt from that veto: it is a small target floating away from the
+   * plane, and nothing else claims it.
+   *
+   * NO SIDE EFFECTS. It is called on every hover, so it may not write state,
+   * open a scrub or notify the chrome.
+   */
+  const intentAt = (pane: StagePane, x: number, y: number): StageIntent => {
+    if (pane === "working") {
+      const arm = feed.gizmoHit?.(x, y) ?? null;
+      if (arm !== null) return { kind: "arm", arm };
+    }
+    const grab = feed.grabAt?.(pane, x, y, state.selection) ?? null;
+    if (grab !== null) return { kind: "grab", grab };
+    if (pane === "working") {
+      const part = feed.frustumHit?.(x, y) ?? null;
+      const overLayer = part === "body" && (feed.pick?.(pane, x, y) ?? []).length > 0;
+      if (part !== null && !overLayer) return { kind: "frustum", part };
+    }
+    return { kind: "empty" };
+  };
+
+  /**
+   * Recompute the cursor from the LAST KNOWN pointer position.
+   *
+   * For everything that changes the answer without moving the pointer: arming a
+   * tool, pressing or releasing the space bar, a layer becoming selected from a
+   * panel. Read through a ref by the listeners that are registered once (the
+   * key relay), which is the same shape `endModalRef` and `wheelRef` use.
+   */
+  const refreshCursor = (): void => {
+    const { at, inside, buttons } = lastPointer.current;
+    // A live modal owns the pointer's meaning, and a DRAG has already left the
+    // pointer's own position behind — a pan's closed hand must survive every
+    // commit the drag itself causes, and this runs on all of them.
+    if (!inside || buttons !== 0 || modalRef.current !== null) return;
+    const hit = paneAt(panes, at[0], at[1]);
+    setCursor(
+      hit === null
+        ? cursorFor(null, null)
+        : cursorFor(hit.pane, intentAt(hit.pane, hit.local[0], hit.local[1])),
+    );
+  };
+  refreshCursorRef.current = refreshCursor;
+
+  // The armed tool changes the cursor with no pointer motion at all, and a
+  // selection arriving from the outliner adds handles under a stationary
+  // pointer. Both are commits, so one effect per commit is the whole cost.
+  useEffect(() => {
+    refreshCursorRef.current();
+  });
+
+  const onPointerDown = (e: React.PointerEvent<HTMLDivElement>): void => {
+    // A press with no motion still moves the gate: without this, holding the
+    // button still still reads `buttons: 0` and a modal could open on top of
+    // the drag's own scrub.
+    onPointerTrack(e);
+    // MIDDLE PRESS: kill the default before anything else looks at it.
+    // Windows and Linux Chrome open AUTOSCROLL on an unprevented middle
+    // mousedown — the anchor puck appears, the cursor changes, and every
+    // subsequent move scrolls instead of reaching this pane. That is both
+    // Blender bindings this stage added, middle-drag orbit and shift+middle
+    // pan, dead on the platform they were reported broken on.
+    // `touchAction: "none"` does not cover it: autoscroll rides the
+    // compatibility MOUSE event, and preventing the pointerdown's default is
+    // what suppresses that.
+    if (e.button === 1) e.preventDefault();
+    // A press terminates a live modal — LEFT confirms, right cancels — and does
+    // NOTHING ELSE. First branch, so a confirm click can never fall through to
+    // pick / marquee / orbit.
+    //
+    // MIDDLE IS IGNORED rather than treated as a confirm. Blender binds it to
+    // auto-constrain, so a Blender user reaches for it MID-TRANSFORM expecting
+    // an axis — and committing the transform instead is worse than doing
+    // nothing, because it is silent and it costs an undo to get back. The
+    // `preventDefault` above still stands: Windows autoscroll must not open
+    // over a live modal either.
+    if (modalRef.current !== null) {
+      if (e.button === 1) return;
+      endModal(e.button !== 2);
+      return;
+    }
+    if (doc === null) return;
+    const canvasStart = localPoint(e);
+    const hit = paneAt(panes, canvasStart[0], canvasStart[1]);
+    // A press in no pane is a press on a gutter the layout left over. Doing
+    // nothing is the only honest answer; picking a pane for it would answer a
+    // click with a camera the author was not pointing at.
+    if (hit === null) return;
+    const { pane, local: start } = hit;
+    const rect = (pane === "camera" ? panes.camera : panes.working) as PaneRect;
+    const el = e.currentTarget;
+    el.setPointerCapture(e.pointerId);
+    client.handlers()?.onActivePane(pane);
+    // ── THE `B` ARM IS SPENT BY *THIS* PRESS, WHATEVER THE PRESS DOES ─────
+    //
+    // It used to be read and cleared down in the empty-space lane, below every
+    // `return` above it — so a press that landed on a layer, a handle, a gizmo
+    // arm or the frustum left the bit SET, and a working-pane drag some time
+    // later marqueed instead of orbiting, with nothing on screen to say why.
+    // Reading it here, where the press is first known to be a press, is what
+    // makes "armed, and spent by the next press" true rather than nearly true.
+    const boxArmed = boxSelectRef.current;
+    boxSelectRef.current = false;
+
+    // ── A RIGHT PRESS OPENS THE MENU, AND DOES NOTHING ELSE ───────────────
+    //
+    // ABOVE the draw and pen lanes on purpose. This is the change the gate
+    // further down reserved for itself: `e.button !== 0` sits BELOW those
+    // lanes, so a right DRAG with the rect tool armed still inserted a layer —
+    // under the browser's own context menu, which is a layer the author did not
+    // ask for and did not see arrive.
+    //
+    // Below the modal terminator above, so a right-click that cancels a
+    // transform cancels it and stops; opening a menu on the way out of a
+    // gesture would be answering a question nobody asked.
+    //
+    // On the PRESS rather than the release, so this opens no gesture of its
+    // own: no move/up pair to register, and sourceHygiene's one-registration
+    // rule for hand-rolled lanes is untouched.
+    if (e.button === 2) {
+      const hits = feed.pick?.(pane, start[0], start[1]) ?? [];
+      client.handlers()?.onContextMenu(hits, pane, { x: e.clientX, y: e.clientY });
+      return;
+    }
+
+    // Deltas are the same in canvas space and in pane space (the two differ by
+    // a constant), so every drag below measures from the CANVAS press point and
+    // only the hit tests use the pane-local one.
+    const dragFrom = (ev: PointerEvent): [number, number] => {
+      const at = localPoint(ev);
+      return [at[0] - canvasStart[0], at[1] - canvasStart[1]];
+    };
+
+    // The pan gate is PANE-DEPENDENT. The camera pane keeps the designer
+    // convention (middle or space = pan). The working pane speaks Blender:
+    // middle-drag ORBITS (the branch below), shift+middle pans, and space
+    // still pans — both muscle memories stay valid at once.
+    // ── BLENDER'S EMULATE-3-BUTTON, so a trackpad can orbit ───────────────
+    //
+    // alt + left stands in for the middle button, which a laptop does not
+    // have — and without it the working pane's orbit was reachable only by
+    // dragging EMPTY SPACE, so an author with a full-bleed background layer
+    // could not turn the view at all.
+    //
+    // Alt is free on a working-pane press: it is read as `aboutCentre` inside a
+    // resize drag and nowhere else. Shift+alt+left therefore pans, which costs
+    // that one combo its additive marquee — named here rather than discovered.
+    //
+    // THE WORKING PANE ONLY, and that gate is the fix. Folding it into the
+    // camera pane's `pans` made alt+left a PAN there, which ate the two
+    // gestures alt already owns on that side: `aboutCentre` on a resize, and
+    // every draw tool that an author holds alt through. The camera pane has a
+    // middle button's worth of pan already (middle, and space), so it needs no
+    // stand-in for a button a laptop lacks.
+    const emulatesMiddle = e.button === 0 && e.altKey && pane === "working";
+    const middle = e.button === 1 || emulatesMiddle;
+    const pans =
+      pane === "camera"
+        ? isPanGesture(e, spaceRef.current)
+        : spaceRef.current || (middle && e.shiftKey);
+    // ctrl/meta + middle DOLLIES, at the wheel's own falloff so a drag and a
+    // notch are the same step. Blender's third mouse binding, and the only one
+    // this pane was missing.
+    if (!pans && pane === "working" && middle && (e.ctrlKey || e.metaKey)) {
+      const fromWorking = workingView;
+      // BRACKETED LIKE EVERY OTHER NAVIGATION LANE. Under follow mode a view
+      // change IS a document write, and an unbracketed one goes through
+      // `store.edit` -> `transaction()` per rAF-flushed move — an undo entry
+      // every frame, with the redo stack cleared each time, and the Escape
+      // restore itself another edit. The travel gate is what keeps a middle
+      // CLICK from opening a scrub it never feeds, which would then block
+      // `edit`/`undo`/`redo` until something else closed it.
+      let dragged = false;
+      const following = follows;
+      // ns-resize, not a zoom cursor: the gesture is a VERTICAL DRAG and that is
+      // what the arrows say. zoom-in/zoom-out are click affordances and would
+      // promise an action a drag does not have.
+      setNavCursor("ns-resize");
+      dragGesture(
+        el,
+        e.pointerId,
+        (ev) => {
+          const dy = dragFrom(ev)[1];
+          if (!dragged && Math.abs(dy) < DRAG_THRESHOLD_PX) return;
+          if (!dragged && following) client.handlers()?.onFramingGestureStart();
+          dragged = true;
+          setWorkingView(dollyBy(fromWorking, -dy, dolly));
+        },
+        (commit) => {
+          setNavCursor(null);
+          if (!dragged) return;
+          if (!commit) setWorkingView(fromWorking);
+          if (following) client.handlers()?.onFramingGestureEnd(commit);
+        },
+      );
+      return;
+    }
+    if (pans) {
+      // A closed hand while the drag runs, and back to whatever the pointer is
+      // over when it ends. This is the one cursor a live gesture is allowed to
+      // change, because a pan is the one gesture whose subject IS the pointer.
+      setCursor("grabbing");
+      const fromView = view;
+      const fromWorking = workingView;
+      // With follow armed, a working-pane pan moves the CAMERA too, so it is
+      // bracketed exactly as an orbit is and the whole hold is one undo entry.
+      const following = follows && pane === "working";
+      if (following) client.handlers()?.onFramingGestureStart();
+      dragGesture(
+        el,
+        e.pointerId,
+        (ev) => {
+          const [dx, dy] = dragFrom(ev);
+          if (pane === "camera") setView(panBy(fromView, dx, dy));
+          // The working pane pans its TARGET at the target's own depth, which
+          // is what keeps the point under the cursor under the cursor. It needs
+          // the pane height because that is what the fov spans, not the canvas.
+          else setWorkingView(panWorkingBy(fromWorking, dx, dy, rect.height, WORKING_FOV_DEG));
+        },
+        (commit) => {
+          // THE VIEW GOES BACK TOO, not only the framing the scrub restores.
+          // Escape means the pan never happened, and a moved view left under a
+          // restored camera is exactly the disagreement follow mode exists to
+          // prevent — the next orbit would cross the gap in one jump.
+          if (!commit) {
+            if (pane === "camera") setView(fromView);
+            else setWorkingView(fromWorking);
+          }
+          if (following) client.handlers()?.onFramingGestureEnd(commit);
+          // The hold PANNED, so releasing space must not also play. Marked on
+          // its OWN bit and not by clearing `spaceRef`: the bar is still down,
+          // and the next auto-repeat keydown would set a shared flag straight
+          // back and play the shot anyway.
+          spacePanned.current = true;
+          refreshCursorRef.current();
+        },
+      );
+      return;
+    }
+
+    // ── MIDDLE-DRAG ORBITS THE WORKING PANE (Blender's muscle memory) ─────
+    //
+    // Before the grab and the frustum lanes on purpose: middle-drag OVER a
+    // layer must orbit, not move it. The same travel gate, follow bracketing
+    // and Escape restore as the empty-space orbit below — a middle CLICK does
+    // nothing and costs nothing.
+    if (pane === "working" && middle) {
+      const fromWorking = workingView;
+      const following = follows;
+      let dragged = false;
+      // A closed hand, from the press, exactly as the pan lane does it. Not
+      // gated on the travel threshold like the gesture start is: an undo entry
+      // for a click would be a real cost and a cursor for one is not, and
+      // waiting would mean the affordance appears after the author has already
+      // committed to the drag.
+      setNavCursor("grabbing");
+      dragGesture(
+        el,
+        e.pointerId,
+        (ev) => {
+          const [dx, dy] = dragFrom(ev);
+          if (!dragged && Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
+          if (!dragged && following) client.handlers()?.onFramingGestureStart();
+          dragged = true;
+          setWorkingView(orbitBy(fromWorking, dx, dy));
+        },
+        (commit) => {
+          setNavCursor(null);
+          if (!dragged) return;
+          if (!commit) setWorkingView(fromWorking);
+          if (following) client.handlers()?.onFramingGestureEnd(commit);
+        },
+      );
+      return;
+    }
+
+    // ── THE INSERT LANES, ABOVE THE GRAB AND THE PICK ─────────────────────
+    //
+    // An armed insert tool outranks everything the canvas already holds. With
+    // the rect tool armed, a drag that happens to start over the selection must
+    // draw a rectangle rather than move the layer under it — that is what
+    // "armed" means, and every design tool behaves this way.
+    //
+    // CAMERA PANE ONLY. A box is drawn on the design plane, and in a free orbit
+    // there is no screen rectangle that corresponds to one: the same drag would
+    // describe a different quadrilateral from every angle. The working pane
+    // keeps its orbit, which is the gesture it has nowhere else to put.
+    if (pane === "camera") {
+      if (isDrawTool(state.tool)) {
+        runDrawGesture(state.tool, start, dragFrom, el, e.pointerId, rect);
+        return;
+      }
+      if (state.tool === "path") {
+        // A press places an anchor; HOLDING AND DRAGGING pulls its bezier
+        // handles. The drag rides `dragGesture` like every other lane in this
+        // file rather than hand-rolling a move/up pair: that helper is the one
+        // place pointercancel and Escape are handled, and a lane without them
+        // leaks its listener when the browser takes the pointer away.
+        //
+        // The two thresholds are SCREEN px (they are about the author's
+        // finger), so they cross into the reducer divided by the zoom.
+        const at = screenToDesign(start, view, cameraViewport, size);
+        const zoom = Math.max(view.zoom, MIN_INVERTIBLE_SCALE);
+        const next = penReduce(pen, { kind: "press", at, closeSlop: PEN_CLOSE_SLOP_PX / zoom });
+        if (next.closed) {
+          commitPen(next);
+          return;
+        }
+        setPen(next);
+        dragGesture(
+          el,
+          e.pointerId,
+          (ev) => {
+            // PANE-LOCAL, which is what `screenToDesign` measures against:
+            // `localPoint` is canvas-local and the two differ by the pane's
+            // origin, so the press point plus the delta is the conversion
+            // (deltas being equal in both spaces is exactly why `dragFrom`
+            // exists).
+            const [dx, dy] = dragFrom(ev);
+            const to = screenToDesign([start[0] + dx, start[1] + dy], view, cameraViewport, size);
+            setPen((prev) => penReduce(prev, { kind: "move", at: to, dragThreshold: PEN_DRAG_THRESHOLD_PX / zoom }));
+          },
+          () => setPen((prev) => penReduce(prev, { kind: "release" })),
+        );
+        return;
+      }
+    }
+
+    // ── ONLY THE PRIMARY BUTTON DRIVES THE LANES BELOW ────────────────────
+    //
+    // Everything from here down assumed a left press. It never checked, so a
+    // right press on a selected layer opened a transform scrub the author had
+    // no idea was running, and a right drag in empty space marqueed. The middle
+    // button's own lanes (orbit, pan, dolly) have all had their say above.
+    //
+    // It sits below the draw and pen lanes, which used to mean a right drag
+    // with the rect tool armed still inserted a layer. That is FIXED: the
+    // context-menu branch above returns on every `button === 2` press, so no
+    // right press reaches this far and the gate now only turns away buttons
+    // three and up. Left where it is because a lane that assumes a left press
+    // should say so, whether or not something upstream already guaranteed it.
+    if (e.button !== 0) return;
+
+    // ── WHAT IS UNDER THE POINTER, ASKED ONCE ─────────────────────────────
+    //
+    // `intentAt` is the arms / grab / frustum / empty-space ordering, and the
+    // hover lane asks it the identical question to choose a cursor. One
+    // function, so the shape the pointer takes and the thing the press does
+    // cannot disagree — which is the whole failure a hover cursor exists to
+    // prevent.
+    const intent = intentAt(pane, start[0], start[1]);
+    if (intent.kind === "arm") {
+      runGizmoGesture(intent.arm, rect, start, canvasStart, el, e.pointerId);
+      return;
+    }
+    if (intent.kind === "grab") {
+      runTransformGesture(intent.grab, pane, rect, start, canvasStart, el, e.pointerId);
+      return;
+    }
+    if (intent.kind === "frustum") {
+      runFramingGesture(intent.part, start, canvasStart, el, e.pointerId);
+      return;
+    }
+
+    // ── EMPTY SPACE: A CLICK UNTIL IT TRAVELS ─────────────────────────────
+    //
+    // What it becomes then depends on the pane.
+    //
+    //   CAMERA: a marquee, which is what a flat design surface means by
+    //     dragging nothing.
+    //
+    //   WORKING: an ORBIT, because that is the only gesture with nowhere else
+    //     to live — pan is already space/middle and dolly is already the wheel,
+    //     and a 3D view whose primary drag was a marquee is a 3D view you
+    //     cannot turn. SHIFT makes it a marquee instead: shift already means
+    //     "extend the selection" in the pick policy, so the one marquee this
+    //     pane offers is the additive one, which is the one still worth having
+    //     once the plain drag is spent.
+    //
+    // THE TRAVEL GATE IS SHARED, and that is the load-bearing part. An orbit
+    // that started on the pointerdown would swallow every click in the working
+    // pane, and clicking a layer there would silently do nothing.
+    // `B` ARMED A ONE-SHOT BOX SELECT, so a Blender user gets the marquee they
+    // reached for without also having to know that shift means it here. Read
+    // and cleared up at `paneAt`, so a press that never reaches this lane still
+    // spends it.
+    const orbits = pane === "working" && !e.shiftKey && !boxArmed;
+    const following = orbits && follows;
+    const fromWorking = workingView;
+    let dragged = false;
+    // The orbit branch only: a marquee draws its own band, and a closed hand
+    // over a rubber band would say the wrong thing about what is moving.
+    if (orbits) setNavCursor("grabbing");
+    dragGesture(
+      el,
+      e.pointerId,
+      (ev) => {
+        const [dx, dy] = dragFrom(ev);
+        if (!dragged && Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
+        // The travel gate is also where a follow scrub OPENS, and for the same
+        // reason it exists at all: a click must not cost an undo entry.
+        if (!dragged && following) client.handlers()?.onFramingGestureStart();
+        dragged = true;
+        if (orbits) {
+          setWorkingView(orbitBy(fromWorking, dx, dy));
+          return;
+        }
+        // CLAMPED TO ITS OWN PANE, at the source. The band stays in the pane
+        // the drag started in (the overlay clips it there), so a marquee
+        // dragged across the divider used to be a clipped VIEW of a larger
+        // invisible rectangle — and `pickRect` selected against the invisible
+        // one. Clamping here makes the drawn band and the selection the same
+        // rectangle by construction rather than by two agreeing clips.
+        const [mx, my] = clampInPane(rect, start[0] + dx, start[1] + dy);
+        setMarquee({ pane, x0: start[0], y0: start[1], x1: mx, y1: my });
+      },
+      (commit, ev) => {
+        setNavCursor(null);
+        // An orbit moved the author, not the selection.
+        if (dragged && orbits) {
+          if (!commit) setWorkingView(fromWorking);
+          if (following) client.handlers()?.onFramingGestureEnd(commit);
+          return;
+        }
+        setMarquee(null);
+        // NO TERMINATING EVENT, NO SELECTION CHANGE. Escape and a cancelled
+        // pointer both end here with `ev: null`, and the final point and the
+        // modifiers are only readable off the event that ended the drag —
+        // answering from the press point would pick something the author had
+        // already dragged away from.
+        if (!commit || ev === null) return;
+        const [dx, dy] = dragFrom(ev);
+        const modifiers = { shift: ev.shiftKey, meta: ev.metaKey || ev.ctrlKey, alt: ev.altKey };
+        if (dragged) {
+          // The SAME clamp the drawn band uses, so the selection is the
+          // rectangle the author actually saw.
+          const [mx, my] = clampInPane(rect, start[0] + dx, start[1] + dy);
+          const hits = feed.pickRect?.(pane, { x0: start[0], y0: start[1], x1: mx, y1: my }) ?? [];
+          // A marquee REPLACES the selection unless shift is held — the same
+          // rule every design tool has, and the reason the pick handler takes
+          // the modifiers rather than deciding for itself.
+          //
+          // `marquee: true` is what tells the chrome this list is a SET rather
+          // than a hit stack. Without it the click policy took `hits[0]` and a
+          // box over five layers selected one.
+          client.handlers()?.onPick(hits, { ...modifiers, meta: false, marquee: true }, pane);
+          return;
+        }
+        client.handlers()?.onPick(feed.pick?.(pane, start[0] + dx, start[1] + dy) ?? [], modifiers, pane);
+      },
+    );
+  };
+
+  /**
+   * Rubber-band a new layer's box, and hand its two corners to the chrome.
+   *
+   * THE PREVIEW IS THE MARQUEE'S OWN RECTANGLE, reused rather than re-drawn:
+   * both are "the box between the press and the cursor", and a second dashed
+   * rect drawn a different way is a second thing to keep in step with the pane
+   * translation and the clip.
+   *
+   * ponytail: a line or an arrow therefore previews as the BOX it spans rather
+   * than as the stroke it will become. Give the overlay a second preview shape
+   * when someone is drawing enough arrows to care.
+   *
+   * The corners cross as DESIGN COORDINATES because only this half can convert
+   * (see `onDraw`), and a sub-threshold drag crosses as two IDENTICAL corners
+   * because only this half knows how far the pointer travelled in screen px.
+   */
+  const runDrawGesture = (
+    tool: DrawTool,
+    start: readonly [number, number],
+    dragFrom: (ev: PointerEvent) => [number, number],
+    el: HTMLDivElement,
+    pointerId: number,
+    rect: PaneRect,
+  ): void => {
+    let dragged = false;
+    dragGesture(
+      el,
+      pointerId,
+      (ev) => {
+        const [dx, dy] = dragFrom(ev);
+        if (!dragged && Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
+        dragged = true;
+        // CLAMPED, exactly as the marquee is and for the same reason. The
+        // marquee lane got this and its sibling here did not: a draw dragged
+        // across the divider previewed clipped (the overlay clips to the pane)
+        // and then INSERTED a layer sized to the full invisible drag, so the
+        // shape the author got was not the shape they saw.
+        const [mx, my] = clampInPane(rect, start[0] + dx, start[1] + dy);
+        setMarquee({ pane: "camera", x0: start[0], y0: start[1], x1: mx, y1: my });
+      },
+      (commit, ev) => {
+        setMarquee(null);
+        // Escape and a cancelled pointer insert NOTHING. Same rule the marquee
+        // lane keeps for the same reason: the final point only exists on the
+        // event that ended the drag, and there is none.
+        if (!commit || ev === null) return;
+        const [dx, dy] = dragFrom(ev);
+        const from = screenToDesign(start, view, cameraViewport, size);
+        const at = clampInPane(rect, start[0] + dx, start[1] + dy);
+        const to = dragged ? screenToDesign(at, view, cameraViewport, size) : from;
+        client.handlers()?.onDraw(tool, [centreOrigin(from, size), centreOrigin(to, size)]);
+      },
+    );
+  };
+
+  /**
+   * Run a move / resize / tilt / depth drag.
+   *
+   * THREE THINGS MAKE THIS ONE UNDO ENTRY AND EXACTLY REVERSIBLE, and none of
+   * them is in this function: `onGestureStart` opens a history scrub, every
+   * delta is measured FROM THE PRESS so the scrub can re-derive from its base,
+   * and Escape ends it with `commit: false`, which restores that base exactly
+   * because the document never left it.
+   *
+   * The delta is computed by unprojecting BOTH rays onto one plane — which
+   * plane is the V-vs-G rule, and it lives in interactions/move.ts.
+   *
+   * IT WORKS UNCHANGED IN THE WORKING PANE. `designDelta` takes two RAYS and a
+   * PLANE and no camera, so which camera cast the rays is not a question it can
+   * ask; a move dragged from an orbit view is the same arithmetic on rays that
+   * happen to come in at an angle. Only the SCREEN-space kinds below are
+   * camera-bound, and `grabAt` never returns one in the working pane.
+   */
+  const runTransformGesture = (
+    grab: Grab,
+    pane: StagePane,
+    rect: PaneRect,
+    start: readonly [number, number],
+    canvasStart: readonly [number, number],
+    el: HTMLDivElement,
+    pointerId: number,
+  ): void => {
+    const handlers = client.handlers();
+    if (handlers === undefined || handlers === null || feed.rayAt === null) return;
+    // ── THE ROTATE RING: AN ANGLE SWEPT, NOT A DISTANCE DRAGGED ──────────
+    //
+    // Its own lane, above the ray work, because it needs neither a ray nor a
+    // plane: a roll is measured on screen, about the projected centre of the
+    // thing being turned. A linear px scale (which is what `R` uses, and what
+    // it should use — it has no drawn handle to follow) would make the box slip
+    // out from under the cursor the moment the author swept past a corner.
+    //
+    // TOTAL FROM THE PRESS, like every other gesture here, so a coalesced move
+    // cannot drift and Escape restores the base exactly.
+    if (grab.kind === "roll") {
+      // BOTH CARRIED ON THE GRAB, from the quad that was actually pressed. They
+      // used to be re-derived from `selection[0]`, which is the lowest id in
+      // document order rather than the one under the cursor.
+      const from = grab.handleAngle;
+      const about = grab.centre;
+      if (from === undefined || about === undefined) return;
+      const [cx, cy] = about;
+      const pivot = selectionPivot(feed, state.selection);
+      handlers.onGestureStart("roll", state.selection, clampZoom(view.zoom));
+      dragGesture(
+        el,
+        pointerId,
+        (ev) => {
+          const at = localPoint(ev);
+          // Unwrapped through `atan2`'s branch cut, so a sweep past due west
+          // does not jump by a full turn.
+          let deg = ((Math.atan2(at[1] - rect.y - cy, at[0] - rect.x - cx) - from) * 180) / Math.PI;
+          deg = ((((deg + 180) % 360) + 360) % 360) - 180;
+          // SHIFT is the same precision the modal lane gives, and CTRL the same
+          // 15 degree quantise Blender uses.
+          if (ev.shiftKey) deg *= PRECISION_FACTOR;
+          if (ev.ctrlKey || ev.metaKey) deg = Math.round(deg / ROLL_SNAP_DEG) * ROLL_SNAP_DEG;
+          // Copied out of the stage's own snapshot: `GestureDelta` is the wire
+          // shape the store re-derives from, and sharing an alias lets one
+          // mutate the other.
+          handlers.onGesture({ kind: "roll", dx: deg, dy: 0, pivot: pivot === null ? null : [...pivot] });
+        },
+        (commit) => handlers.onGestureEnd(commit),
+      );
+      return;
+    }
+    // A RESIZE IS ON THE LAYER'S OWN PLANE, always. The handle is drawn on that
+    // plane and the edge it moves lives in it, so the frame plane would measure
+    // a foreshortened distance on any tilted layer. Select's move joins it (the
+    // V-vs-G rule, interactions/move.ts); G's move is deliberately flat.
+    //
+    // A UNION SCALE joins them for the same reason and with a stronger claim:
+    // its box IS a plane the members all lie in, by `unionQuad`'s own predicate.
+    const plane = gesturePlane(
+      grab.kind === "resize" ||
+        grab.kind === "scale" ||
+        (grab.kind === "move" && state.tool === "select")
+        ? "layer"
+        : "frame",
+      grab.matrixWorld,
+    );
+    // No ray means the pane has no camera on screen, so there is no gesture to
+    // start — better than opening a history scrub that can never be fed.
+    const from = feed.rayAt(pane, start[0], start[1]);
+    if (from === null) return;
+    // ── THE UNION SCALE'S TWO SNAPSHOTS ───────────────────────────────────
+    //
+    // The box and the press point, both frozen at the press and both in DESIGN
+    // px. The box is rebuilt from its members every frame, so reading it live
+    // would move the pivot with the layers the scale is moving; the anchor is
+    // where the ratio is measured from, and re-deriving it per move is how a
+    // gesture stops being a total from the press.
+    //
+    // A press with no honest point on the plane (edge-on) opens no scrub at
+    // all, the same refusal `designDelta` makes mid-drag.
+    const box = grab.kind === "scale" ? designBox(grab.union) : null;
+    const anchor = grab.kind === "scale" ? designPoint(from, plane) : null;
+    if (grab.kind === "scale" && (box === null || anchor === null)) return;
+    // THE PANE'S OWN SCREEN SCALE, which only this half can answer. The chrome
+    // divides its snap threshold by it, and the two panes derive it from
+    // different things entirely: a flat zoom here, an orbit distance there.
+    handlers.onGestureStart(
+      grab.kind,
+      state.selection,
+      pane === "camera" ? clampZoom(view.zoom) : paneScreenScale(rect),
+    );
+
+    dragGesture(
+      el,
+      pointerId,
+      (ev) => {
+        const at = localPoint(ev);
+        const dx = at[0] - canvasStart[0];
+        const dy = at[1] - canvasStart[1];
+        const to = feed.rayAt?.(pane, start[0] + dx, start[1] + dy) ?? null;
+        const delta = to === null ? null : designDelta(from, to, plane);
+        // A null delta is an EDGE-ON layer, which has no answer — skipping the
+        // gesture is the only honest response, and writing NaN is the
+        // alternative.
+        if (delta === null) return;
+        // ── A RESIZE IS THE SAME UNPROJECTION AS A MOVE ───────────────────
+        //
+        // It used to be a screen-px drag divided by `view.zoom`, and that was
+        // wrong in two independent ways at once. `view.zoom` is screen px per
+        // design px AT z = 0 (view.ts), but the camera's distance is
+        // `planeDistance(H, fov, framing.zoom)` (resolve.ts) and nothing
+        // multiplied the two — so every resize was off by the framing's own
+        // zoom even on the canvas plane, and off by the perspective divide at
+        // any depth. Neither error was visible as a jump; the handle just did
+        // not keep up with the cursor, which reads as "resize feels wrong".
+        //
+        // Two rays on the layer's own plane have no zoom term at all, so this
+        // is exact for BOTH panes and for a perspective or an orthographic
+        // camera alike. That is what lets the working pane have handles.
+        if (grab.kind === "resize") {
+          handlers.onGesture({
+            kind: "resize",
+            dx: delta.dx,
+            dy: delta.dy,
+            dz: delta.dz,
+            ...(grab.handle === undefined ? {} : { handle: grab.handle }),
+            keepAspect: ev.shiftKey,
+            aboutCentre: ev.altKey,
+          });
+          return;
+        }
+        // ── A UNION HANDLE IS A RATIO, NOT AN EDGE ────────────────────────
+        //
+        // Same two rays and the same plane as a resize; only the arithmetic on
+        // the far side differs. ALT re-pivots to the box's centre mid-drag,
+        // which is the modifier a single-layer resize spends on `aboutCentre`
+        // and means the same thing here.
+        if (grab.kind === "scale") {
+          if (box === null || anchor === null || grab.handle === undefined) return;
+          const scale = unionScale(box, grab.handle, [anchor[0], anchor[1]], delta, ev.altKey);
+          // A degenerate arm has no ratio — see `unionScale`. Skipping the emit
+          // holds the last good one rather than writing a NaN size.
+          if (scale === null) return;
+          handlers.onGesture({
+            kind: "scale",
+            dx: 0,
+            dy: 0,
+            ratio: scale.ratio,
+            axis: scale.axis,
+            // The design z the whole box lies in, so a member's own depth
+            // offset from the pivot is zero and a uniform scale cannot drift
+            // the selection towards or away from the camera.
+            pivot: [scale.pivot[0], scale.pivot[1], anchor[2]],
+          });
+          return;
+        }
+        handlers.onGesture({ kind: "move", ...delta });
+      },
+      (commit) => handlers.onGestureEnd(commit),
+    );
+  };
+
+  /**
+   * Drag one arm of the move gizmo: a translation along ONE design axis, of
+   * whichever subject the gizmo is hanging on.
+   *
+   * ── IT IS THE SAME SCRUB EVERY OTHER TRANSFORM OPENS ────────────────────
+   *
+   * For layers: `onGestureStart("move", …)` / N× `onGesture` / `onGestureEnd`.
+   * For the camera: the framing trio the frustum's own two grips already use.
+   * Either way every emit is a TOTAL FROM THE PRESS — the two rules that make a
+   * drag one undo entry and exactly reversible (see `dragGesture`). So an arm
+   * drag, a body drag and `G X` all land in the store the same way, and the
+   * store's base/block/refusal fork sees one kind of thing.
+   *
+   * THE SUBJECT COMES OFF THE GRAB, snapshotted at the press, and is never
+   * re-read from the selection mid-drag. A selection arriving from the chrome
+   * while an arm is held would otherwise turn a camera dolly into a layer move
+   * halfway through, inside one history scrub.
+   *
+   * ── WHY IT SOLVES A LINE RATHER THAN A PLANE ────────────────────────────
+   *
+   * `axisParam` is the closest point on the axis line to the pointer ray, so
+   * the grabbed arm stays under the cursor at every orbit. Unprojecting onto a
+   * plane and zeroing the other two components — what the MODAL lane does,
+   * because it has no drawn arm to stay under — drifts as the view turns and
+   * runs away entirely at a grazing angle.
+   *
+   * The axis parameter is already in DESIGN units, and needs no `-y` flip: a
+   * translation of `s` along the arm's world direction is `s` along the design
+   * axis it was built from, because `DESIGN_AXES` carries unit vectors and the
+   * one mapping has no scale in it.
+   *
+   * Null from `axisParam` is a ray PARALLEL to the arm — every point on it is
+   * equally close — and skips the emit rather than writing NaN, the same
+   * refusal `designDelta` makes for an edge-on layer.
+   */
+  const runGizmoGesture = (
+    arm: GizmoGrab,
+    rect: PaneRect,
+    start: readonly [number, number],
+    canvasStart: readonly [number, number],
+    el: HTMLDivElement,
+    pointerId: number,
+  ): void => {
+    const handlers = client.handlers();
+    if (handlers === undefined || handlers === null) return;
+    const from = feed.rayAt?.("working", start[0], start[1]) ?? null;
+    const anchor = from === null ? null : paramAt(arm, from);
+    // No ray, or a press that grazed the arm end-on: there is nothing to
+    // measure against, and opening a scrub that can never be fed is worse than
+    // letting the press fall through to nothing.
+    if (anchor === null) return;
+    const camera = arm.subject === "camera";
+    // The apex's own world z IS the camera's distance to the canvas — the
+    // gizmo hangs on `[x, -y, distance]` (frustumGeometry) — so the dolly's
+    // ratio needs no second lookup and cannot go stale against the pose the
+    // arm was drawn at.
+    const distance = arm.origin[2];
+    if (camera) handlers.onFramingGestureStart();
+    else {
+      handlers.onGestureStart("move", state.selection, paneScreenScale(rect));
+    }
+
+    dragGesture(
+      el,
+      pointerId,
+      (ev) => {
+        const at = localPoint(ev);
+        const to = feed.rayAt?.(
+          "working",
+          start[0] + at[0] - canvasStart[0],
+          start[1] + at[1] - canvasStart[1],
+        );
+        const now = to === null || to === undefined ? null : paramAt(arm, to);
+        if (now === null) return;
+        const d = now - anchor;
+        if (camera) {
+          const delta = framingArmDelta(arm.axis, d, distance);
+          if (delta !== null) handlers.onFramingGesture(delta);
+          return;
+        }
+        handlers.onGesture({
+          kind: "move",
+          dx: arm.axis === "x" ? d : 0,
+          dy: arm.axis === "y" ? d : 0,
+          dz: arm.axis === "z" ? d : 0,
+        });
+      },
+      (commit) => {
+        if (camera) handlers.onFramingGestureEnd(commit);
+        else handlers.onGestureEnd(commit);
+      },
+    );
+  };
+
+  /**
+   * Drag the CAMERA: the body pans its framing, the apex zooms it.
+   *
+   * Working pane only, because the gizmo only exists there — it is the camera
+   * pane's camera drawn as an object, and it cannot appear inside the view it
+   * represents.
+   *
+   * The two halves take their delta from different places on purpose. The BODY
+   * unprojects both rays onto z = 0, the plane its rectangle sits in, so the
+   * grabbed point stays under the cursor whatever angle the author is orbiting
+   * from — the same unprojection a layer move uses, and `designDelta` needs no
+   * camera to do it. The APEX is a screen-space drag: its distance from the
+   * plane IS the zoom (`planeDistance`), the pointer has no depth, and there is
+   * no projection that would make dragging a point along the view axis feel
+   * like anything. Exponential at the wheel's own falloff, so an apex drag and
+   * a wheel notch are the same step.
+   *
+   * What the deltas MEAN — a base write, a refusal, or a block — is the store's
+   * fork, not the stage's. See camera.ts.
+   */
+  const runFramingGesture = (
+    part: "apex" | "body",
+    start: readonly [number, number],
+    canvasStart: readonly [number, number],
+    el: HTMLDivElement,
+    pointerId: number,
+  ): void => {
+    const handlers = client.handlers();
+    if (handlers === undefined || handlers === null) return;
+    const from = part === "body" ? (feed.rayAt?.("working", start[0], start[1]) ?? null) : null;
+    // No ray means no camera on screen for this pane, so there is nothing to
+    // measure against — better than a scrub that can never be fed.
+    if (part === "body" && from === null) return;
+    handlers.onFramingGestureStart();
+
+    dragGesture(
+      el,
+      pointerId,
+      (ev) => {
+        const at = localPoint(ev);
+        const dx = at[0] - canvasStart[0];
+        const dy = at[1] - canvasStart[1];
+        if (part === "apex") {
+          handlers.onFramingGesture({ dx: 0, dy: 0, dzoom: Math.exp(-dy / DOLLY_FALLOFF_PX) });
+          return;
+        }
+        const to = feed.rayAt?.("working", start[0] + dx, start[1] + dy) ?? null;
+        const delta = to === null || from === null ? null : designDelta(from, to, Z0_PLANE);
+        if (delta !== null) handlers.onFramingGesture({ dx: delta.dx, dy: delta.dy, dzoom: 1 });
+      },
+      (commit) => handlers.onFramingGestureEnd(commit),
+    );
+  };
+
+  const onWheel = (e: WheelLike): void => {
+    if (doc === null) return;
+    // A LIVE MODAL OWNS THE VIEW, the way it owns the keyboard. Its anchor ray
+    // and screen scale are captured once at `startModal`; a dolly re-poses the
+    // working camera under them, so the next emit differences a post-dolly ray
+    // against a pre-dolly anchor and commits the camera's motion as the
+    // layer's. Ignoring the wheel keeps the transform anchored to where the
+    // author started it — Blender's own answer is the same, and the author can
+    // confirm or cancel in one keystroke if they wanted to dolly first.
+    if (modalRef.current !== null) return;
+    const at = localPoint(e);
+    const hit = paneAt(panes, at[0], at[1]);
+    if (hit === null) return;
+    client.handlers()?.onActivePane(hit.pane);
+    if (hit.pane === "working") {
+      // `deltaMode` scaled exactly as `wheelToView` scales it — Firefox reports
+      // lines where Chrome reports pixels — so one notch is the same step in
+      // whichever pane it lands in.
+      const rect = panes.working as PaneRect;
+      const scale = e.deltaMode === 1 ? 16 : e.deltaMode === 2 ? rect.height : 1;
+      // ── A TRACKPAD CAN PAN THIS PANE AT LAST ────────────────────────────
+      //
+      // A two-finger sideways scroll reports `deltaX`, and a shifted vertical
+      // one is the same gesture on a mouse wheel. Both used to fall through to
+      // the dolly, so the working pane had NO pan for anyone without a middle
+      // button: the camera pane panned on a plain wheel and this one zoomed,
+      // which is also why the two felt inconsistent.
+      //
+      // ctrl/meta STAYS ON THE DOLLY, deliberately. `panZoom.ts` is explicit
+      // that a trackpad reports a PINCH as ctrl + wheel, so that binding is
+      // what makes two-finger zoom work at all.
+      const pans = !e.ctrlKey && !e.metaKey && (e.deltaX !== 0 || e.shiftKey);
+      if (pans) {
+        // NEGATED, because a wheel delta is the opposite sense from a drag
+        // delta — the same reason `wheelToView` subtracts.
+        const dx = (e.shiftKey ? e.deltaY : e.deltaX) * scale;
+        const dy = (e.shiftKey ? 0 : e.deltaY) * scale;
+        setWorkingView(panWorkingBy(workingView, -dx, -dy, rect.height, WORKING_FOV_DEG), "wheel");
+        return;
+      }
+      // ORIGIN "wheel": under follow this is a document write with no press and
+      // no release to bracket it, so the chrome closes it over silence instead.
+      setWorkingView(dollyBy(workingView, e.deltaY * scale, dolly), "wheel");
+      return;
+    }
+    setView(wheelToView(e, hit.local, view, cameraViewport, size));
+  };
+
+  /**
+   * The wheel is registered BY HAND, non-passive, and it is the only way this
+   * works.
+   *
+   * React attaches `onWheel` as a PASSIVE listener on the root container
+   * (react-dom does this for wheel, touchstart and touchmove), and a passive
+   * listener cannot `preventDefault`. So ctrl/meta + wheel — which is exactly
+   * the gesture a trackpad pinch reports, and the one `wheelToView` reads as
+   * zoom — reached the BROWSER as a page-zoom request at the same time as it
+   * reached us. Both fired: the canvas zoomed and the entire chrome scaled
+   * with it. Preventing the default on a listener we own is the whole fix.
+   *
+   * Every wheel event is prevented, not only the zooming ones: a plain wheel
+   * pans this canvas, and letting it also scroll whatever the browser thinks
+   * is scrollable behind us is the same class of double-handling.
+   *
+   * The handler is read through a ref so the listener registers ONCE. Re-adding
+   * it whenever `view` changed would mean removing and re-adding a listener on
+   * every frame of a zoom gesture.
+   *
+   * EVENTS ARE COALESCED TO THE FRAME, deltas summed. A trackpad fires wheel
+   * far above display rate and each application costs a stage commit and a GL
+   * draw. Summing is exact for every consumer: the pan is linear in the
+   * deltas, and the zoom and the dolly are exponential (`exp(-(a+b)/k) =
+   * exp(-a/k)·exp(-b/k)`), so one flush of a summed delta lands on the same
+   * view as applying each event. The default is still prevented PER EVENT —
+   * only the application defers. A modifier or deltaMode change flushes what
+   * is pending first, so a pinch starting mid-scroll cannot fold into a pan.
+   */
+  const wheelRef = useRef(onWheel);
+  wheelRef.current = onWheel;
+  useEffect(() => {
+    const el = areaRef.current;
+    if (el === null) return;
+    let pending: WheelLike | null = null;
+    let raf = 0;
+    const flush = (): void => {
+      raf = 0;
+      if (pending === null) return;
+      const batch = pending;
+      pending = null;
+      wheelRef.current(batch);
+    };
+    const onWheelNative = (e: WheelEvent): void => {
+      e.preventDefault();
+      // SHIFT joins the flush set: it decides whether a vertical wheel pans or
+      // dollies the working pane, so folding a shifted notch into an unshifted
+      // batch would apply both to whichever the batch ended up claiming.
+      if (
+        pending !== null &&
+        (pending.ctrlKey !== e.ctrlKey ||
+          pending.metaKey !== e.metaKey ||
+          pending.shiftKey !== e.shiftKey ||
+          pending.deltaMode !== e.deltaMode)
+      ) {
+        flush();
+      }
+      if (pending === null) {
+        pending = {
+          clientX: e.clientX,
+          clientY: e.clientY,
+          deltaX: e.deltaX,
+          deltaY: e.deltaY,
+          deltaMode: e.deltaMode,
+          ctrlKey: e.ctrlKey,
+          metaKey: e.metaKey,
+          shiftKey: e.shiftKey,
+        };
+      } else {
+        pending.deltaX += e.deltaX;
+        pending.deltaY += e.deltaY;
+        pending.clientX = e.clientX;
+        pending.clientY = e.clientY;
+      }
+      if (raf === 0) raf = requestAnimationFrame(flush);
+    };
+    el.addEventListener("wheel", onWheelNative, { passive: false });
+    return () => {
+      if (raf !== 0) cancelAnimationFrame(raf);
+      el.removeEventListener("wheel", onWheelNative);
+    };
+  }, []);
+
+  const laidOut = viewport.width > 0 && viewport.height > 0;
+  const offset =
+    laidOut && panes.camera !== null ? viewOffsetFor(view, panes.camera, size) : null;
+
+  // The overlay's derived props, IDENTITY-STABLE across everything that does
+  // not move them — a seek re-renders this component, and fresh objects here
+  // would defeat MemoOverlays entirely. The guides are almost always empty,
+  // and empty must be the SAME empty every render.
+  const overlayFrame = useMemo(
+    () => frameRect(view, cameraViewport, size),
+    [view, cameraViewport, size.width, size.height],
+  );
+  const overlayGuides = useMemo(
+    () =>
+      state.guides.length === 0
+        ? EMPTY_GUIDES
+        : state.guides.map((g) => ({
+            axis: g.axis,
+            // Design FRAME coordinates arrive with the origin at the canvas
+            // centre, the way the schema measures; `designToScreen` wants them
+            // from the frame's top-left. Measured against the CAMERA PANE,
+            // because that is the viewport its projection was computed for.
+            at:
+              g.axis === "x"
+                ? designToScreen([size.width / 2 + g.at, 0], view, cameraViewport, size)[0]
+                : designToScreen([0, size.height / 2 + g.at], view, cameraViewport, size)[1],
+          })),
+    [state.guides, view, cameraViewport, size.width, size.height],
+  );
+  // Where the playhead lands in the document, resolved ONCE. The post stack and
+  // the camera rig both hang off it, and both are read out here rather than
+  // inside the canvas because the playhead and the document live out here —
+  // neither consumer may hold its own copy of either.
+  // Every derivation below rides the SAME size-1 caches ShotRuntime reads
+  // (frameCache.ts), so the stage and the runtime cannot compute the frame
+  // twice — the second caller replays the first one's answer.
+  const effects = at?.scene.effects ?? null;
+  const defs = useMemo(() => (doc === null ? {} : componentDefsOfCached(doc)), [doc]);
+  const hasMesh = at === null ? false : sceneHasMeshCached(at.scene, defs);
+  // The bin partition, from the same resolved position as the post stack. Both
+  // panes draw through it (SplitRenderer), so the editor cannot disagree with
+  // the export about what a model covers. Empty when nothing is on screen AND
+  // for every scene without a live mesh layer — `renderBins` treats empty and
+  // single identically (one plain draw), and gating on `hasMesh` here matches
+  // exactly what ShotScene computes, which is what lets the cache be shared.
+  // The definitions ride into both: a def-blind partition leaves the mesh bin
+  // closed for a scene whose only model is inside a component, and the two
+  // panes would then disagree with the export about what a model covers.
+  const bins = useMemo(
+    () => (at === null || !hasMesh ? EMPTY_BINS : binsAtCached(at.scene, at.sceneFrame, defs)),
+    [at, defs, hasMesh],
+  );
+  // The pill's stable prop — built from the modal STATE alone, so MemoOverlays
+  // re-renders on start/axis/end and never on mouse motion.
+  const modalBadge = useMemo<ScreenModal | null>(
+    () =>
+      modal === null
+        ? null
+        : {
+            label: modalLabel(modal),
+            camera: modal.target === "camera",
+            // The glyph and its axis tint. Both ride the same memo as the label
+            // because both are modal STATE — they change when the author arms a
+            // mode or presses an axis key, never when the pointer moves.
+            mode: modal.mode,
+            axis: modal.axis,
+          },
+    [modal],
+  );
+
+  /**
+   * The corner axis indicator, which is a pure function of the view's two
+   * angles — so it re-derives exactly when the working pane's picture does,
+   * and never on a seek or a selection change.
+   *
+   * A click SNAPS, through the same `presetWorkingView` the numpad keys go
+   * through and with the same origin an orbit uses: with follow armed, snapping
+   * the view is a camera write, which is what follow means.
+   */
+  /**
+   * A press on the nav gizmo: DRAG TO ORBIT, click to snap.
+   *
+   * The identical lane an orbit on empty space runs — same `dragGesture`, same
+   * `DRAG_THRESHOLD_PX`, same follow bracketing, same Escape restore — so the
+   * widget cannot develop its own idea of what turning the view means. It only
+   * SNAPS when the travel never crossed the threshold, which is what makes one
+   * gesture serve both.
+   *
+   * The event is stopped HERE and not in the overlay: the overlay would have to
+   * stop it to keep the container's own lane out, and then there would be no
+   * event left to open a drag with.
+   */
+  const grabNav = useCallback(
+    (e: React.PointerEvent, ball: NavBall | null) => {
+      e.stopPropagation();
+      e.preventDefault();
+      const el = areaRef.current;
+      if (el === null) return;
+      const start = localPoint(e);
+      const from = client.getState().workingView;
+      const following = client.getState().cameraFollowsView;
+      let dragged = false;
+      el.setPointerCapture(e.pointerId);
+      dragGesture(
+        el,
+        e.pointerId,
+        (ev) => {
+          const at = localPoint(ev);
+          const dx = at[0] - start[0];
+          const dy = at[1] - start[1];
+          if (!dragged && Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
+          // The travel gate is where a follow scrub opens, for the reason it
+          // exists at all: a click must not cost an undo entry.
+          if (!dragged && following) client.handlers()?.onFramingGestureStart();
+          dragged = true;
+          setWorkingView(orbitBy(from, dx, dy));
+        },
+        (commit) => {
+          if (!dragged) {
+            // A CLICK. The disc has no axis to snap to, so it does nothing —
+            // which is right: its whole job is the drag.
+            if (commit && ball !== null) setWorkingView(viewForBall(from, ball));
+            return;
+          }
+          if (!commit) setWorkingView(from);
+          if (following) client.handlers()?.onFramingGestureEnd(commit);
+        },
+      );
+    },
+    [client, setWorkingView],
+  );
+  /**
+   * The selected toon mesh, or null. The whole gate for the key-light handle.
+   *
+   * ONE layer, because a key direction is one value and a handle over a
+   * multi-selection would silently write it to whichever member it felt like.
+   * TOON only, because `keyDir` is inert under `unlit` — a handle that moved a
+   * number nothing reads is worse than no handle. And never while the derived
+   * isolation rig is drawing, for the nav gizmo's reason: the arm is projected
+   * through `workingView`'s basis, which nothing is using then.
+   */
+  const keyLightLayer = useMemo(() => {
+    if (panes.working === null || headOnRig !== null || state.selection.length !== 1) return null;
+    const id = state.selection[0]!;
+    const layer = at?.scene.layersById[id];
+    if (layer === undefined || layer.kind !== "mesh") return null;
+    if (layer.mesh.shading?.mode !== "toon") return null;
+    return { id, dir: layer.mesh.shading.keyDir ?? DEFAULT_KEY_DIR };
+  }, [panes.working, headOnRig, state.selection, at]);
+
+  /**
+   * Drag the key. The gesture trio's shape, and the nav gizmo's plumbing.
+   *
+   * Deltas are measured FROM THE PRESS against the direction at the press, so a
+   * coalesced drag lands exactly where an uncoalesced one does and Escape
+   * restores by discarding rather than by replaying.
+   */
+  const grabKeyLight = useCallback(
+    (e: React.PointerEvent) => {
+      // Stopped HERE and not in the overlay, for `grabNav`'s reason: the
+      // overlay would have to stop it to keep the container's lane out, and
+      // then there would be no event left to open a drag with.
+      e.stopPropagation();
+      e.preventDefault();
+      const el = areaRef.current;
+      const light = keyLightLayer;
+      if (el === null || light === null) return;
+      const start = localPoint(e);
+      const from = light.dir;
+      const view = client.getState().workingView;
+      let opened = false;
+      el.setPointerCapture(e.pointerId);
+      dragGesture(
+        el,
+        e.pointerId,
+        (ev) => {
+          const at2 = localPoint(ev);
+          const dx = at2[0] - start[0];
+          const dy = at2[1] - start[1];
+          if (!opened && Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
+          if (!opened) {
+            // The travel gate is where the scrub opens, for the reason it
+            // exists at all: a click must not cost an undo entry. A refusal
+            // here abandons the drag rather than emitting into nothing.
+            if (client.handlers()?.onKeyLightStart(light.id) !== true) return;
+            opened = true;
+          }
+          client.handlers()?.onKeyLight(rotateKeyDir(from, view, dx, dy));
+        },
+        (commit) => {
+          if (!opened) return;
+          client.handlers()?.onKeyLightEnd(commit);
+        },
+      );
+    },
+    [client, keyLightLayer],
+  );
+
+  const keyLightArm = useMemo(
+    () =>
+      keyLightLayer === null
+        ? null
+        : { layerId: keyLightLayer.id, dir: keyDirOnScreen(keyLightLayer.dir, workingView), onGrab: grabKeyLight },
+    [keyLightLayer, workingView, grabKeyLight],
+  );
+
+  const nav = useMemo(
+    // HIDDEN WHILE THE DERIVED RIG DRAWS. The balls are a projection of
+    // `workingView`'s basis, and nothing is using that basis then — so the
+    // widget drew one camera's axes over another camera's picture, offered
+    // `cursor: pointer`, and did nothing when clicked. Once the author has
+    // taken the camera it is correct again and its clicks land.
+    () =>
+      panes.working === null || headOnRig !== null
+        ? null
+        : { balls: navBalls(workingView), onGrab: grabNav },
+    [panes.working, headOnRig, workingView, grabNav],
+  );
+
+  // A transition window mounts its own priority-1 compositor inside
+  // ShotRuntime, so the probe has to count it too — the comment below promises
+  // this expression mirrors EXACTLY when a priority-1 renderer exists, and a
+  // probe that claims priority when one already has it is the bug it guards.
+  const inTransition = doc !== null && transitionAtCached(doc, state.frame) !== null;
+  // The gizmo's pose. `cameraRigAt` is the ONE answer to "where is the camera
+  // at this frame", including the dolly-vs-zoom distinction — deriving it a
+  // second time inside the gizmo would be a second camera model.
+  const rig = useMemo(
+    () => (at === null || doc === null ? null : cameraRigAtCached(at.scene, doc.size.height, at.sceneFrame, doc.fps)),
+    [at, doc],
+  );
+
+  /** Where the camera IS, for the arms to hang on when nothing is selected.
+   *  Off `rig` through the same `frustumShape` the gizmo's own vertices come
+   *  from, so the arms cannot sit anywhere but on the drawn apex. */
+  const cameraApex = useMemo<Vec3 | null>(
+    () => (rig === null ? null : frustumShape(rig, size).apex),
+    [rig, size],
+  );
+
+  return (
+    <div
+      ref={areaRef}
+      data-shot-area
+      // No `onWheel` prop: React would register it passive and the browser
+      // would page-zoom alongside us. It is added by hand above.
+      onPointerDown={onPointerDown}
+      // GO INSIDE whatever is under the cursor. A React prop, like the hover
+      // below and for the same reason: it opens no gesture and holds no state,
+      // so it is not one of the hand-rolled lanes `sourceHygiene.test.ts`
+      // holds to one registration each.
+      //
+      // The pointerdown lane has already run and selected, which is the
+      // intended compound — the author sees what they are about to enter
+      // highlighted before they enter it.
+      onDoubleClick={onDoubleClick}
+      // THE PEN'S HOVER, and nothing else's. A React prop rather than an
+      // `addEventListener`, deliberately: the hand-rolled pointer lanes in this
+      // file are held to one registration each (`sourceHygiene.test.ts`)
+      // because a lane that rolls its own move/up pair has no `pointercancel`
+      // and leaks a history scrub. This listener opens no gesture and holds no
+      // state, so React's own teardown is the whole story.
+      //
+      // Without it the pen's rubber band and its close highlight have no input
+      // at all: `cursor` would only advance while a button was held, so the
+      // author would never see that the next click closes the loop.
+      onPointerMove={onPointerHover}
+      // The cursor box, kept honest on RELEASE too. React props rather than
+      // `addEventListener` for the reason the hover prop states: they open no
+      // gesture and hold no state, so React's own teardown is the whole story
+      // and the hand-rolled-lane rule in sourceHygiene.test.ts is untouched.
+      onPointerUp={onPointerTrack}
+      onPointerCancel={onPointerTrack}
+      onLostPointerCapture={onPointerTrack}
+      // The cursor LEFT. Same posture as the props above — no gesture, no
+      // state of its own — and it is what keeps a modal from being armed by a
+      // keystroke aimed at the chrome, or stranded there once it is.
+      onPointerLeave={onPointerLeave}
+      // ALWAYS. The browser's own menu over a 3D canvas offers "save image"
+      // and "reload" and nothing an author of a shot could want, and every
+      // right press now has a meaning of its own: it opens the stage's menu,
+      // or it cancels a modal. The one-shot suppressor this replaced existed
+      // only for the cancel case; a rule with no exceptions needs no flag.
+      onContextMenu={(e) => {
+        e.preventDefault();
+      }}
+      style={{
+        position: "fixed",
+        inset: 0,
+        overflow: "hidden",
+        background: "var(--stage-backdrop, #0e0e10)",
+        // NO `cursor` HERE. It is written imperatively by `setCursor`, and a
+        // second writer React re-applies on every commit makes the right cursor
+        // intermittent. See `setCursor`.
+        touchAction: "none",
+      }}
+    >
+      {doc === null || !laidOut ? null : (
+        <>
+          <ShotRuntime
+            doc={doc}
+            frame={state.frame}
+            viewport={viewport}
+            viewOffset={offset}
+            // Only while the working pane is on screen. In camera mode the
+            // runtime presents itself exactly as an export does — header.
+            renderControl={ownsPresent ? "external" : "default"}
+            // Quantised to the ladder, never the raw zoom: the raster cache
+            // keys on this value, so a continuous zoom would re-raster the
+            // whole document per wheel event. The ladder's top rung is the
+            // same 4x cap this line used to spell out by hand.
+            rasterScale={quantizeRasterScale(clampZoom(view.zoom))}
+            // A far layer costs what it looks like, not what it was authored
+            // at. The editor only: an export names its own scale and never
+            // reaches the branch, which is what keeps preview === export a
+            // property of the code rather than a rule someone remembers.
+            adaptiveRaster
+            instances={instances.instances}
+            instanceContracts={instances.contracts}
+            {...(isolated === null ? {} : { dim: { keep: isolated, opacity: DIM_OPACITY } })}
+            onLayerGraph={bumpSceneEpoch}
+            onMeshStats={pushMeshStats}
+            onReady={onReady}
+          >
+            <StageTools
+              feed={feed}
+              panes={panes}
+              workingView={workingView}
+              selection={state.selection}
+              layers={at?.scene ?? null}
+              sceneFrame={at?.sceneFrame ?? 0}
+              isolationRoot={isolated === null ? null : state.isolation}
+              isolated={isolated}
+              // The DERIVED rig, so a null here is the author having taken the
+              // camera and `StageTools` falling back to the orbit one with no
+              // branch of its own to keep in step.
+              isolationView={headOnRig}
+            />
+            {/* presenterMounted mirrors exactly the conditions under which a
+                priority-1 renderer exists on this canvas: SplitRenderer when
+                a working pane owns the present, or ShotRuntime's own
+                ScenePresenter (post chain or mesh bin). See PerfProbe for why
+                the probe's priority must not be positive when neither is. */}
+            {PERF_HUD_ENABLED ? (
+              <PerfProbe
+                box={perfBox}
+                presenterMounted={
+                  ownsPresent ||
+                  hasMesh ||
+                  (effects !== null && hasPostChain(effects)) ||
+                  inTransition
+                }
+              />
+            ) : null}
+            {ownsPresent ? (
+              <>
+                {/* The working pane's placement aids. Mounted with the
+                    renderer that draws them and nowhere else: all three are
+                    EDITOR_LAYER objects the shot camera cannot see, so in
+                    camera-only mode they would be scene-graph nodes nothing
+                    ever renders. */}
+                {/* ── BOTH CAMERA AIDS ARE SCOPED OUT WHILE ISOLATED ──────
+                    The grid IS the design z = 0 plane, and a card at z = 400
+                    seen head-on has it running across the pane as a wall at an
+                    unrelated angle. The frustum is the SHOT camera drawn as an
+                    object, and inside a subtree it frames something the pane
+                    cannot show. Worse, with an empty selection `modalTarget`
+                    retargets the move arms at that camera, so a drag would
+                    write `framing` from a view with no relation to it. */}
+                {isolated === null ? (
+              <GridPlane frame={size} target={workingView.target} distance={workingView.distance} />
+            ) : null}
+                <MoveGizmo
+                  feed={feed}
+                  panes={panes}
+                  selection={state.selection}
+                  cameraApex={isolated === null ? cameraApex : null}
+                />
+                {isolated === null ? (
+                  <FrustumGizmo feed={feed} panes={panes} rig={rig} frame={size} />
+                ) : null}
+                <SplitRenderer
+                  feed={feed}
+                  panes={panes}
+                  effects={effects}
+                  bins={bins}
+                  hasMesh={hasMesh}
+                  frame={state.frame}
+                  shading={state.shading}
+                />
+              </>
+            ) : null}
+          </ShotRuntime>
+          <OverlaysHost
+            feed={feed}
+            width={viewport.width}
+            height={viewport.height}
+            panes={panes}
+            frame={overlayFrame}
+            hover={hover}
+            followsView={follows}
+            isolation={isolationLabel}
+            marquee={marquee}
+            pen={penScreen}
+            guides={overlayGuides}
+            designGuides={state.guides}
+            size={size}
+            modal={modalBadge}
+            nav={nav}
+            keyLightArm={keyLightArm}
+            inset={state.inset}
+          />
+          {PERF_HUD_ENABLED ? (
+            <PerfHud box={perfBox} layers={at === null ? 0 : Object.keys(at.scene.layersById).length} />
+          ) : null}
+        </>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The world DESIGN point a multi-selection scales away from: the mean of its
+ * members' origins, at the frame on screen.
+ *
+ * NULL FOR ONE LAYER, and that is not an optimisation. One layer's median is
+ * its own origin, so the offset from it is zero and the position never moves —
+ * which is exactly what `pivot: null` means downstream, said without arithmetic
+ * that could round.
+ *
+ * The MEAN and not the bounding box's centre: `project.ts` and `Overlays` both
+ * state that a screen bounding box lies about tilt, and the same is true in the
+ * world. A mean of origins is a real point that needs no box.
+ *
+ * Off `matrixWorld`, whose 13th to 15th elements are the translation column, so
+ * the one mapping (design y down, z away) is undone on the way out.
+ */
+/**
+ * A pane-local point, held inside its pane.
+ *
+ * ── AT THE SOURCE, IN ONE PLACE ─────────────────────────────────────────
+ *
+ * The overlay CLIPS its bands to the pane, so a drag that crosses the divider
+ * draws a clipped view of a larger invisible rectangle — and the lane behind it
+ * then acts on the invisible one. The marquee selected against it; the draw
+ * tools inserted a layer sized to it. Both are the same bug and now share the
+ * same clamp, so the rectangle drawn and the rectangle acted on are one
+ * rectangle by construction rather than by two clips agreeing.
+ */
+function clampInPane(rect: PaneRect, x: number, y: number): [number, number] {
+  return [Math.max(0, Math.min(rect.width, x)), Math.max(0, Math.min(rect.height, y))];
+}
+
+/**
+ * The union box's world corners, as the DESIGN rectangle the scale measures in.
+ *
+ * `unionQuad` only answers for a box whose edges run along the world axes, so
+ * the two opposite corners carry the whole rectangle and `(x, -y)` is the only
+ * conversion needed. TL is `quad[0]` and BR is `quad[2]`, and world +y is up, so
+ * the flip is what turns the world's TOP corner into design's SMALLEST y.
+ */
+function designBox(union: WorldQuad | undefined): DesignBox | null {
+  if (union === undefined) return null;
+  return { x0: union[0].x, y0: -union[0].y, x1: union[2].x, y1: -union[2].y };
+}
+
+function selectionPivot(feed: StageFeed, selection: readonly string[]): Vec3 | null {
+  if (selection.length < 2) return null;
+  let n = 0;
+  let x = 0;
+  let y = 0;
+  let z = 0;
+  // One frame per id, the FIRST — the same rule `StageTools`' `byId` follows. A
+  // cloner stamps its children N times under one id, and averaging every clone
+  // would put the pivot in the empty space between them.
+  const seen = new Set<string>();
+  for (const frame of feed.frames ?? []) {
+    if (!selection.includes(frame.id) || seen.has(frame.id)) continue;
+    seen.add(frame.id);
+    const e = frame.matrixWorld.elements;
+    x += e[12]!;
+    y += e[13]!;
+    z += e[14]!;
+    n += 1;
+  }
+  // Fewer than two ON SCREEN is the same case as fewer than two selected: a
+  // layer outside its lifespan at this frame has no position to average.
+  return n < 2 ? null : [x / n, -(y / n), -(z / n)];
+}
+
+/** A three `Ray` into the plain numbers `axisParam` takes. The one place the
+ *  gizmo lane crosses from three into the three-free maths module, so nothing
+ *  in gizmoMath.ts has to know what a Ray is. `Raycaster` hands out a
+ *  normalized direction, which is what the unit-direction solve assumes. */
+function paramAt(arm: GizmoGrab, ray: Ray): number | null {
+  return axisParam(
+    arm.origin,
+    arm.direction,
+    [ray.origin.x, ray.origin.y, ray.origin.z],
+    [ray.direction.x, ray.direction.y, ray.direction.z],
+  );
+}
+
+/**
+ * The pointer plumbing every committing drag in this file shares.
+ *
+ * THREE THINGS MAKE A DRAG ONE UNDO ENTRY AND EXACTLY REVERSIBLE, and two of
+ * them are here: the gesture ends exactly once however it ends, and Escape ends
+ * it with `commit: false`. The third is the caller's, and is the reason every
+ * `move` above measures FROM THE PRESS: the scrub re-derives from its base.
+ *
+ * Module scope, so it closes over nothing and EVERY caller in this file gets
+ * the same teardown — which is how one of them ends up leaking a `keydown`
+ * listener that fires against a finished gesture, or registering `pointerup`
+ * alone and leaving a history scrub open forever when the browser cancels the
+ * pointer instead of releasing it.
+ *
+ * `end` is handed the event that ENDED the drag, or null when nothing did
+ * (Escape, `pointercancel`). The marquee lane needs it: the final point and the
+ * modifiers exist only on that event, and a `commit` boolean cannot carry them.
+ */
+function dragGesture(
+  el: HTMLDivElement,
+  pointerId: number,
+  move: (ev: PointerEvent) => void,
+  end: (commit: boolean, ev: PointerEvent | null) => void,
+): void {
+  let live = true;
+  // MOVES ARE COALESCED TO THE FRAME, last event wins. A pointermove costs a
+  // full stage commit and a GL draw (and, for a document-writing gesture, a
+  // fresh Doc3D and a chrome-wide notification), while the display can only
+  // show one result per frame — so applying every event buys nothing and
+  // stalls the thread exactly when the author is watching most closely.
+  // Deltas are measured FROM THE PRESS by every caller, so dropping
+  // intermediate events cannot make a drag drift; the LAST event always
+  // applies, on the frame or at the release below.
+  let pending: PointerEvent | null = null;
+  let raf = 0;
+  const flush = (): void => {
+    raf = 0;
+    if (!live || pending === null) return;
+    const ev = pending;
+    pending = null;
+    move(ev);
+  };
+  const onMove = (ev: PointerEvent): void => {
+    pending = ev;
+    if (raf === 0) raf = requestAnimationFrame(flush);
+  };
+  const finish = (commit: boolean, ev: PointerEvent | null): void => {
+    if (!live) return;
+    live = false;
+    if (raf !== 0) cancelAnimationFrame(raf);
+    // The FINAL position always lands before the end: a move still pending at
+    // release would otherwise drop the last frame of travel and the layer
+    // would land where the pointer was a frame ago. A discard skips it — the
+    // gesture is being thrown away.
+    if (commit && pending !== null) {
+      const last = pending;
+      pending = null;
+      move(last);
+    }
+    pending = null;
+    el.removeEventListener("pointermove", onMove);
+    el.removeEventListener("pointerup", up);
+    el.removeEventListener("pointercancel", cancel);
+    window.removeEventListener("keydown", onKey);
+    try {
+      el.releasePointerCapture(pointerId);
+    } catch {
+      /* already released */
+    }
+    end(commit, ev);
+  };
+  const up = (ev: PointerEvent): void => finish(true, ev);
+  const cancel = (): void => finish(false, null);
+  const onKey = (ev: KeyboardEvent): void => {
+    if (ev.key !== "Escape") return;
+    ev.preventDefault();
+    finish(false, null);
+  };
+  el.addEventListener("pointermove", onMove);
+  el.addEventListener("pointerup", up);
+  el.addEventListener("pointercancel", cancel);
+  window.addEventListener("keydown", onKey);
+}
+
+/**
+ * Design px from the frame's TOP-LEFT (what `screenToDesign` answers) into
+ * design px from the CANVAS CENTRE (what the schema stores).
+ *
+ * One conversion, at the boundary, in the direction the guides already cross in
+ * the other — see the `designToScreen` call the overlay makes for them. Doing
+ * it in the chrome instead would mean the chrome deriving canvas geometry it
+ * only half knows.
+ */
+function centreOrigin(
+  point: readonly [number, number],
+  frame: { width: number; height: number },
+): [number, number] {
+  return [point[0] - frame.width / 2, point[1] - frame.height / 2];
+}
+
+function durationOf(doc: {
+  scenes: readonly string[];
+  scenesById: Record<string, { durationFrames: number }>;
+}): number {
+  let total = 0;
+  for (const id of doc.scenes) total += Math.max(1, Math.trunc(doc.scenesById[id]?.durationFrames ?? 0));
+  return total;
+}
+
+/**
+ * Every instance layer's component and declared contract, re-resolved when the
+ * set of component IDS changes and not on every keystroke.
+ *
+ * KEYED ON THE IDS, not on the document: an inspector edit mints a new `Doc3D`
+ * on every character typed, and re-running the resolver there would re-await a
+ * cached promise per keystroke and hand `ShotRuntime` a fresh object identity
+ * each time — remounting every instanced component, which for a module with
+ * internal state is visible as a flicker and for one behind Suspense is a
+ * re-fetch. The module cache in instanceModules.ts makes the awaits free; the
+ * identity is what has to stay stable.
+ */
+function useInstanceModules(client: StageClient, doc: Doc3D | null): InstanceResolution {
+  const [resolved, setResolved] = useState<InstanceResolution>(EMPTY_INSTANCES);
+  // Joined on a character no registry id can contain (an id is
+  // "<module>#<Export>", and a module path holds no newline), so two different
+  // id sets can never collapse to the same key.
+  const key = doc === null ? "" : instanceComponentIdsOf(doc).join("\n");
+  useEffect(() => {
+    if (doc === null || key === "") {
+      setResolved(EMPTY_INSTANCES);
+      return;
+    }
+    let live = true;
+    void resolveInstanceModules(doc).then((next) => {
+      if (!live) return;
+      setResolved(next);
+      // Reported, never thrown: a module that will not resolve leaves its layer
+      // empty, and the author needs to know WHY rather than losing the editor.
+      for (const message of next.errors) client.handlers()?.onError(message);
+    });
+    return () => {
+      live = false;
+    };
+    // `doc` is deliberately not a dependency — see the header. It is read
+    // through the closure at the moment the id set changes, which is the only
+    // moment its instance layers can differ.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [client, key]);
+  return resolved;
+}
+
+const EMPTY_INSTANCES: InstanceResolution = { instances: {}, contracts: {}, errors: [] };
+
+function useStageState(client: StageClient): StageClientState {
+  const [state, setState] = useState(client.getState);
+  useEffect(() => client.subscribe(() => setState(client.getState())), [client]);
+  return state;
+}
+
+/** The container's CSS size, which is the canvas's size and therefore the unit
+ *  every screen coordinate in this lane is measured in. `origin` receives the
+ *  container's client origin from the same measurement, so the pointer lanes
+ *  can convert client coordinates without a per-event layout read. */
+function useViewportSize(
+  ref: React.RefObject<HTMLDivElement | null>,
+  set: (size: { width: number; height: number }) => void,
+  origin?: React.RefObject<readonly [number, number]>,
+): void {
+  useEffect(() => {
+    const el = ref.current;
+    if (el === null) return;
+    const measure = (): void => {
+      const rect = el.getBoundingClientRect();
+      if (origin !== undefined) origin.current = [rect.left, rect.top];
+      set({ width: Math.round(rect.width), height: Math.round(rect.height) });
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [ref, set, origin]);
+}
+
+/**
+ * Forward the stage's own key events to the chrome, and hold the space bar's
+ * two bits.
+ *
+ * KEYBOARD EVENTS GO TO ONE DOCUMENT. The stage is an iframe, so once the
+ * author has moved the pointer onto the canvas — which is most of the time,
+ * since StagePanel focuses the frame on pointer entry — the chrome's window
+ * listener never sees a keystroke. Without this relay every shortcut would work
+ * only while a panel had focus, which is the version of this bug that reads as
+ * "the shortcuts are flaky".
+ *
+ * ── WHY THE RELAY AND THE SPACE FLAG ARE ONE HOOK ───────────────────────
+ *
+ * They were two, and the split was a silent bug: both registered a `keyup` on
+ * `window`, and DOM listeners fire in registration order, so the flag hook —
+ * called one line earlier — cleared the bit before the relay could read it.
+ * Space therefore NEVER reached the chrome from a focused stage, so it never
+ * played or paused. One hook, one listener pair, and the order is a statement
+ * rather than an accident of which line came first.
+ *
+ * ── AND WHY THE BAR NEEDS TWO BITS, NOT ONE ─────────────────────────────
+ *
+ * `held` gates the pan. `panned` says a pan actually ran, and is what makes the
+ * release swallow the play/pause. One flag carrying both could not survive
+ * KEY AUTO-REPEAT: the pan lane cleared it at the end of the drag, the OS fired
+ * the next repeat keydown milliseconds later and set it straight back, and the
+ * release played the shot anyway. Which happened depended on repeat timing,
+ * which is the definition of flaky.
+ *
+ * A fresh press clears `panned`; a repeat does not, so a hold that panned stays
+ * marked for as long as the author keeps the bar down.
+ *
+ * Refs, not state: both are read at pointerdown and neither changes a pixel, so
+ * state would re-render the whole stage twice per press of the space bar.
+ * `blur` clears them too, because `keyup` never arrives if the author alt-tabs
+ * mid-hold and the stage would be stuck in pan mode.
+ */
+function useKeyRelay(
+  client: StageClient,
+  held: React.RefObject<boolean>,
+  panned: React.RefObject<boolean>,
+  refreshCursor: React.RefObject<() => void>,
+): void {
+  useEffect(() => {
+    const down = (e: KeyboardEvent): void => {
+      if (e.key === " ") {
+        if (!e.repeat) panned.current = false;
+        // The bar changes the cursor to a grab hand with no pointer motion at
+        // all, so the refresh rides the same listener that owns the flag. AFTER
+        // the flag is set, because `cursorFor` reads it — refreshing first
+        // recomputes the answer the bar was pressed to change. Only on the
+        // FIRST press: an auto-repeat re-deriving the same answer at the OS
+        // repeat rate buys nothing.
+        const first = !held.current;
+        held.current = true;
+        if (first) refreshCursor.current();
+        return; // the chrome hears space on KEYUP, and only if no pan ran
+      }
+      if (client.handlers()?.onKey(keyOf(e), isEditable(e.target)) === true) e.preventDefault();
+    };
+    const up = (e: KeyboardEvent): void => {
+      if (e.key !== " ") return;
+      held.current = false;
+      refreshCursor.current();
+      if (!panned.current) client.handlers()?.onKey(keyOf(e), isEditable(e.target));
+      panned.current = false;
+    };
+    const clear = (): void => {
+      held.current = false;
+      panned.current = false;
+      refreshCursor.current();
+    };
+    window.addEventListener("keydown", down);
+    window.addEventListener("keyup", up);
+    window.addEventListener("blur", clear);
+    return () => {
+      window.removeEventListener("keydown", down);
+      window.removeEventListener("keyup", up);
+      window.removeEventListener("blur", clear);
+    };
+  }, [client, held, panned, refreshCursor]);
+}
+
+function keyOf(e: KeyboardEvent) {
+  return {
+    key: e.key,
+    shiftKey: e.shiftKey,
+    altKey: e.altKey,
+    ctrlKey: e.ctrlKey,
+    metaKey: e.metaKey,
+    code: e.code,
+  };
+}
+
+function isEditable(target: EventTarget | null): boolean {
+  if (target === null || typeof (target as HTMLElement).tagName !== "string") return false;
+  const el = target as HTMLElement;
+  return el.isContentEditable || el.tagName === "INPUT" || el.tagName === "TEXTAREA";
+}
+
+