@dailies-studio/shot-editor 0.1.0

package/src/stage/overlays/Overlays.tsx

@@ -0,0 +1,1046 @@
+// The stage's overlay layer: one SVG over the canvas.
+//
+// ── WHY THE OVERLAY IS IN THE STAGE AND NOT IN THE CHROME ───────────────
+//
+// The chrome is three-free and receives screen-space numbers as data — that
+// invariant is unchanged and `sourceHygiene.test.ts` still enforces it. What
+// changed is WHERE those numbers are drawn.
+//
+// Drawing them in the stage removes a cross-document synchronisation problem
+// outright. The quads are recomputed inside the render loop; the chrome is
+// another document with its own commit schedule, so pushing them across would
+// paint the outline one frame behind the pixels it outlines — visible on every
+// dolly, as handles that lag the layer. The chrome can still READ the quads
+// (`bridge.selectionQuads(pane)`) for anything that belongs in a panel.
+//
+// It is also where the pointer already is: gestures land on the stage's own
+// DOM, so the thing being dragged and the thing being drawn are one document.
+//
+// ── ONE SVG, TWO PANES ──────────────────────────────────────────────────
+//
+// Each pane is a `<g>` translated to its rect and clipped to it. Translating
+// is what lets every number that crosses this boundary be PANE-LOCAL — the
+// same coordinates `paneAt` hands the pointer lane and the same ones
+// `StageTools` projects into. A single overlay in canvas coordinates would
+// need every quad offset at the draw site, which is a second place for a pane
+// origin to be added or forgotten.
+//
+// Clipping is not decoration. A layer that sits off the left edge of the
+// camera pane projects to a negative x, and an unclipped outline would draw it
+// across the working pane's picture as a stray rectangle.
+//
+// ── THE OUTLINE IS A POLYGON ────────────────────────────────────────────
+//
+// Never an axis-aligned rect. A tilted layer's outline is a trapezoid, and a
+// bounding box would lie about the tilt in every frame — and would put the
+// resize handles somewhere the layer is not.
+import { useEffect, useRef } from "react";
+import { pathToD } from "@dailies-studio/shot/doc";
+import type { PathPoint } from "@dailies-studio/shot/doc";
+import type { NavBall } from "../gizmoMath.js";
+import type { ModalAxis, ModalMode } from "../modalState.js";
+import { HANDLE_SITES, handlePoint } from "../handles.js";
+import type { StageInset } from "../../bridgeTypes.js";
+import type { PaneRect, StagePane } from "../panes.js";
+import type { ScreenQuad } from "../project.js";
+
+/** A smart guide, already converted to CSS px by the caller — the overlay does
+ *  no coordinate maths of its own, so there is one conversion in the lane. */
+export interface ScreenGuide {
+  axis: "x" | "y";
+  at: number;
+}
+
+/** A live marquee, in the coordinates of the pane the drag STARTED in. It
+ *  stays in that pane even when the cursor leaves it, which is what makes a
+ *  marquee that overshoots the divider still mean what the author meant. */
+export interface ScreenMarquee {
+  pane: StagePane;
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+
+export interface OverlayProps {
+  width: number;
+  height: number;
+  panes: { working: PaneRect | null; camera: PaneRect | null };
+  /** The exportable frame, in CSS px from the CAMERA PANE's top-left. */
+  frame: { x: number; y: number; width: number; height: number };
+  /** Selection outlines, pane-local. Empty for a pane that is off screen. */
+  quadsCamera: readonly ScreenQuad[];
+  quadsWorking: readonly ScreenQuad[];
+  /** Parallel to both quad arrays: is this selected layer locked? ONE array for
+   *  both panes, because the selection is one selection and only its projection
+   *  differs. A locked layer keeps its outline and loses its handles. */
+  locked: readonly boolean[];
+  /**
+   * The multi-select's ONE box, per pane, or null.
+   *
+   * When it is drawn it OWNS the handles and every member outline gives them up
+   * — because `grabAt` gives the box first refusal on any press near a handle,
+   * so a member's own would be drawn and never answered. When it is null (one
+   * layer, or a selection that is not coplanar and axis-parallel) the members
+   * keep theirs and nothing else changes.
+   */
+  unionCamera: ScreenQuad | null;
+  unionWorking: ScreenQuad | null;
+  /**
+   * What a click WOULD select, and in which pane, or null.
+   *
+   * Drawn thinner and dimmer than the selection so the two never read as the
+   * same state. It is the affordance Figma and Blender both have and this stage
+   * did not: without it the author learns what a click selects by clicking,
+   * which in a group tree means undoing a selection they did not want.
+   */
+  hover: { pane: StagePane; quad: ScreenQuad } | null;
+  /** "Camera follows this view" is armed, so orbiting writes the document. */
+  followsView: boolean;
+  /** The isolated layer's label, or null when nothing is isolated. Isolation
+   *  REPLACES the working pane's camera with a derived head-on orthographic rig
+   *  (isolation.ts), so orbit, pan and dolly all stop answering — the badge is
+   *  what turns that from "the view froze" into a mode with a way out. */
+  isolation: string | null;
+  marquee: ScreenMarquee | null;
+  guides: readonly ScreenGuide[];
+  /** The pen's path so far, in CAMERA-PANE CSS px, or null when no path is
+   *  being drawn. Converted by the caller, like the guides — the overlay does
+   *  no coordinate maths of its own.
+   *
+   *  `cursor` is where the rubber band ends; `closeHot` is true when a press
+   *  there would CLOSE the loop, which the preview says by filling the first
+   *  anchor rather than by moving anything. */
+  /**
+   * The same guides, PROJECTED, for the working pane.
+   *
+   * A guide is a line in the design plane. In the flat camera pane that is one
+   * screen coordinate, which is what `guides` above carries. Under a free orbit
+   * it is a segment at an arbitrary angle, so it needs two projected endpoints
+   * and cannot be expressed the same way.
+   *
+   * It used to be neither: `snapFor` runs for a move in BOTH panes, so a
+   * working-pane drag snapped onto another layer's edge and nothing was drawn
+   * to say why — the layer simply jumped. Silent behaviour is the whole class
+   * this lane keeps removing.
+   */
+  guidesWorking: readonly { a: readonly [number, number]; b: readonly [number, number] }[];
+  pen: ScreenPen | null;
+  /** A live modal transform's pill, or null. In-pane for the FollowBadge's
+   *  reason: a mode the author is inside belongs over the picture it is
+   *  changing, not in a panel they are not looking at. */
+  modal: ScreenModal | null;
+  /** The working pane's axis indicator: six projected axis ends, and what a
+   *  click on one should do. Null when there is no working pane. */
+  nav: ScreenNav | null;
+  /** The selected toon mesh's key-direction handle, or null when there is no
+   *  single toon mesh selected. Working pane only: it is a 3D direction, and
+   *  the camera pane has no way to show one. */
+  keyLight: ScreenKeyLight | null;
+  /**
+   * How far the chrome's floating panels reach into the stage, per side.
+   *
+   * EVERY piece of overlay furniture lays out inside it — the mode bars, the
+   * modal pill, the nav gizmo — because the panes are the whole window and the
+   * chrome sits on top of them. Before this, two mode bars drew entirely behind
+   * the opaque shell header and the modal pill drew behind the left rail, so
+   * the only thing that said a G / R / S transform was live had never been
+   * visible in the default layout.
+   *
+   * The pane RECTS are untouched: insetting those would move the scissor and
+   * shrink the rendered picture. This is paint only.
+   */
+  inset: StageInset;
+}
+
+/**
+ * The key-light handle: where the selected mesh is on screen, and which way its
+ * fake key points.
+ *
+ * ── IT IS NOT A LIGHT, AND THE DRAWING SHOULD NOT PRETEND ─────────────────
+ *
+ * This lane has no lights and is not getting any (`MeshShading`: "no lights,
+ * ever"). What a toon mesh has is `keyDir`, a direction evaluated in the
+ * shader — and until now the only way to set it was three number fields in the
+ * inspector, which is a poor way to answer a question the author is looking
+ * straight at. So the sun disc is an affordance for a uniform, and it wears the
+ * frustum's yellow: the colour this stage already uses for "scene rig drawn as
+ * furniture", not the accent that means "your selection".
+ */
+export interface ScreenKeyLight {
+  /** The selected layer's quad centre, pane-local CSS px. */
+  at: readonly [number, number];
+  /** The key direction projected into the pane, normalised, or null when it
+   *  points nearly along the view axis and has no readable 2D direction. */
+  dir: readonly [number, number] | null;
+  /** A press on the disc or its arm. The overlay is paint: it hands the whole
+   *  event to the stage, exactly as `ScreenNav.onGrab` does. */
+  onGrab: (event: React.PointerEvent) => void;
+}
+
+export interface ScreenNav {
+  balls: readonly NavBall[];
+  /**
+   * A press ON the widget: a ball, or `null` for its backing disc.
+   *
+   * ── WHY THE OVERLAY HANDS THE WHOLE EVENT OVER ──────────────────────────
+   *
+   * It used to be `onSnap(ball)`, fired straight from `pointerdown` — so the
+   * gizmo could only be CLICKED, and dragging it did nothing. Blender's turns
+   * the view. Deciding between the two needs a travel threshold and a drag
+   * lane, and this file is paint: it owns no gesture vocabulary and registers
+   * no move listeners. The stage runs `dragGesture` exactly as it does for an
+   * orbit on empty space, and snaps only when the travel never crossed.
+   */
+  onGrab: (event: React.PointerEvent, ball: NavBall | null) => void;
+}
+
+/** What the modal pill says, and whose colour it wears: the accent for layer
+ *  transforms, the frustum's yellow for the camera — the same subject-colour
+ *  rule the FollowBadge states. */
+export interface ScreenModal {
+  label: string;
+  camera: boolean;
+  /**
+   * Which transform is live, drawn as a glyph before the label.
+   *
+   * A modal takes POINTER LOCK, so there is no cursor on screen at all while
+   * one runs — the usual place a tool says what it is doing. The pill is the
+   * only surface left, and a word alone is something the author has to read;
+   * a shape is something they see. Same three modes the keymap arms.
+   */
+  mode: ModalMode;
+  /** The axis lock, or null. Tints the glyph with that axis's own colour, so
+   *  "S then X" says which direction is about to move without a second look at
+   *  the label. */
+  axis: ModalAxis;
+}
+
+/**
+ * Where the pill's live numbers are written, OUTSIDE React.
+ *
+ * The readout changes on every pointermove, and `modalBadge` is memoised on the
+ * modal STATE alone precisely so motion costs no render. Routing the numbers
+ * through props would undo that — a full stage commit per mouse move to change
+ * a string. So the pill registers a setter here and `flushModal` calls it.
+ *
+ * A module-level box rather than a ref chain, because exactly one modal can be
+ * live at a time (the pointerdown lane's first branch guarantees it) and the
+ * two ends are in different files.
+ */
+export const modalReadoutSink: { write: ((text: string) => void) | null } = { write: null };
+
+export interface ScreenPen {
+  points: readonly PathPoint[];
+  closed: boolean;
+  cursor: readonly [number, number] | null;
+  closeHot: boolean;
+}
+
+export function Overlays({
+  width,
+  height,
+  panes,
+  frame,
+  quadsCamera,
+  quadsWorking,
+  locked,
+  unionCamera,
+  unionWorking,
+  hover,
+  followsView,
+  isolation,
+  marquee,
+  guides,
+  guidesWorking,
+  pen,
+  modal,
+  nav,
+  keyLight,
+  inset,
+}: OverlayProps) {
+  const { working, camera } = panes;
+  return (
+    <svg
+      className="stage-overlay"
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      // The pointer lane owns the container; the overlay is paint only. Without
+      // this every drag would end the moment the cursor crossed a handle.
+      style={{ position: "absolute", inset: 0, pointerEvents: "none" }}
+    >
+      <defs>
+        {working === null ? null : <PaneClip id="shot-pane-working" rect={working} />}
+        {camera === null ? null : <PaneClip id="shot-pane-camera" rect={camera} />}
+      </defs>
+
+      {working === null ? null : (
+        <g clipPath="url(#shot-pane-working)" transform={`translate(${working.x} ${working.y})`}>
+          {/* NO FRAME BORDER. The exportable frame is a property of the shot
+              camera's projection; drawn in an orbit view it would be a
+              rectangle floating in front of a scene it does not bound. */}
+          {/* UNDER the selection: a layer that is both hovered and selected
+              must read as selected, not as a heavier version of hovered. */}
+          {hover?.pane === "working" ? <HoverQuad quad={hover.quad} /> : null}
+          {quadsWorking.map((q, i) => (
+            // HANDLES HERE TOO, since `runTransformGesture` learned to measure
+            // a resize by unprojecting two rays onto the layer's own plane. The
+            // old note here said this pane had "no zoom, only a distance" and
+            // therefore no resize; the ray form has no zoom term at all, so the
+            // reason is gone and the author can resize what they are looking at.
+            <SelectionQuad
+              key={i}
+              quad={q}
+              handles={locked[i] !== true && unionWorking === null}
+            />
+          ))}
+          {unionWorking === null ? null : <UnionBox quad={unionWorking} />}
+          {/* The snap guides, as the SEGMENTS they are once the plane is seen
+              at an angle. Same colour and weight as the camera pane's, because
+              they are the same guides. */}
+          {guidesWorking.map((g, i) => (
+            <line
+              key={i}
+              x1={g.a[0]}
+              y1={g.a[1]}
+              x2={g.b[0]}
+              y2={g.b[1]}
+              stroke="var(--guide, #f43f5e)"
+              strokeWidth={1}
+            />
+          ))}
+          {marquee?.pane === "working" ? <Marquee rect={marquee} /> : null}
+          {/* The mode bars STACK DOWN FROM the chrome's bottom edge, so they
+              are the first thing under the header rather than behind it. */}
+          {isolation === null ? null : (
+            <IsolationBadge
+              width={working.width}
+              y={inset.top}
+              left={inset.left}
+              label={isolation}
+            />
+          )}
+          {/* Under the isolation bar when both are on. Two bars at the same y
+              would hide one mode behind the other, and isolation is the one
+              that changed the camera. */}
+          {followsView ? (
+            <FollowBadge
+              width={working.width}
+              y={inset.top + (isolation === null ? 0 : BAR_H)}
+              left={inset.left}
+            />
+          ) : null}
+          {keyLight === null ? null : <KeyLightGizmo light={keyLight} />}
+          {modal === null ? null : <ModalBadge modal={modal} rect={working} inset={inset} />}
+          {nav === null ? null : (
+            <NavGizmo nav={nav} width={working.width} top={inset.top} right={inset.right} />
+          )}
+        </g>
+      )}
+
+      {camera === null ? null : (
+        <g clipPath="url(#shot-pane-camera)" transform={`translate(${camera.x} ${camera.y})`}>
+          <FrameBorder rect={frame} width={camera.width} height={camera.height} />
+          {hover?.pane === "camera" ? <HoverQuad quad={hover.quad} /> : null}
+          {quadsCamera.map((q, i) => (
+            // A LOCKED LAYER DRAWS NO HANDLES, matching `grabAt`, which refuses
+            // to answer one. A handle that cannot be grabbed is a handle the
+            // author will try to grab, and then wonder what is broken.
+            //
+            // NOR DOES A MEMBER OF A UNION. The box has them, and `grabAt` gives
+            // the box first refusal on every press near one — so a member's own
+            // handle would be drawn and never answered.
+            <SelectionQuad key={i} quad={q} handles={locked[i] !== true && unionCamera === null} />
+          ))}
+          {unionCamera === null ? null : <UnionBox quad={unionCamera} />}
+          {guides.map((g, i) =>
+            g.axis === "x" ? (
+              <line
+                key={i}
+                x1={g.at}
+                y1={0}
+                x2={g.at}
+                y2={camera.height}
+                stroke="var(--guide, #f43f5e)"
+                strokeWidth={1}
+              />
+            ) : (
+              <line
+                key={i}
+                x1={0}
+                y1={g.at}
+                x2={camera.width}
+                y2={g.at}
+                stroke="var(--guide, #f43f5e)"
+                strokeWidth={1}
+              />
+            ),
+          )}
+          {marquee?.pane === "camera" ? <Marquee rect={marquee} /> : null}
+          {pen === null || pen.points.length === 0 ? null : <PenPreview pen={pen} />}
+          {/* THE BADGE FOLLOWS THE MODE, NOT THE PANE. Camera-only plus
+              isolated is a legitimate state — the author can switch layout
+              while inside a subtree — and it had zero indicators while the dim
+              and the pick scope were both fully in force, so every click
+              outside the card did nothing with nothing to say why. Drawn here
+              only when the working pane is off screen, or the two would both
+              render it. */}
+          {isolation === null || working !== null ? null : (
+            <IsolationBadge
+              width={camera.width}
+              y={inset.top}
+              left={inset.left}
+              label={isolation}
+            />
+          )}
+        </g>
+      )}
+
+      {working === null || camera === null ? null : <Divider x={camera.x} height={height} />}
+    </svg>
+  );
+}
+
+function PaneClip({ id, rect }: { id: string; rect: PaneRect }) {
+  // Authored at the ORIGIN because the group that references it carries the
+  // translate, and a clip path resolves in the referencing element's own user
+  // space. Repeating the pane's x here would offset it twice.
+  return (
+    <clipPath id={id}>
+      <rect x={0} y={0} width={rect.width} height={rect.height} />
+    </clipPath>
+  );
+}
+
+/**
+ * "Camera follows this view", said INSIDE the pane it is true of.
+ *
+ * Blender's decade-old complaint about the equivalent toggle is that it is easy
+ * to forget it is on — and it is easy because the only thing that says so is a
+ * checkbox in a panel nobody is looking at while they orbit. So this is drawn
+ * over the picture, in the gizmo's own yellow so it reads as the same subject,
+ * and it is a full-width bar rather than a dot because the state it announces
+ * is that ORBITING EDITS THE DOCUMENT.
+ *
+ * A bar and not a border: a border here would be one more rectangle in a pane
+ * that already draws a frustum, a selection and a divider.
+ */
+/** Height of a mode bar. Shared so isolation can stack follow under itself
+ *  without either one restating the other's geometry. */
+const BAR_H = 22;
+
+function FollowBadge({ width, y, left }: { width: number; y: number; left: number }) {
+  return (
+    <ModeBar
+      width={width}
+      y={y}
+      left={left}
+      color="var(--frustum, #eab308)"
+      text="CAMERA FOLLOWS THIS VIEW"
+    />
+  );
+}
+
+/**
+ * "You are inside this layer", said INSIDE the pane it is true of.
+ *
+ * Isolation is the largest mode this pane has: `StageTools` swaps a derived
+ * orthographic head-on rig into the working camera's slot, so orbit, pan, dolly
+ * and the nav gizmo all stop answering, and picking is scoped to the subtree.
+ * With no in-pane sign, that reads as the view having frozen on whatever was
+ * double-clicked — and the only thing that said otherwise was a breadcrumb in
+ * the left panel, which `[` and `.` can hide entirely.
+ *
+ * THE WAY OUT IS IN THE BADGE, for the reason the badge exists at all: a mode
+ * the author entered by accident has to be leavable without finding the panel
+ * that documents it.
+ *
+ * The accent, not the frustum's yellow: the subject is a LAYER, which is the
+ * same subject-colour rule ModalBadge follows.
+ */
+function IsolationBadge({
+  width,
+  y,
+  label,
+  left,
+}: {
+  width: number;
+  y: number;
+  label: string;
+  left: number;
+}) {
+  return (
+    <ModeBar
+      width={width}
+      y={y}
+      left={left}
+      color="var(--accent, #3b82f6)"
+      text={`INSIDE ${label.toUpperCase()} — ESC TO LEAVE`}
+    />
+  );
+}
+
+function ModeBar({
+  width,
+  y,
+  color,
+  text,
+  /** How far the chrome's left rail reaches into this pane. THE TEXT IS THE
+   *  ONLY PART THAT MOVES: the tinted band is a full-width mode indicator and
+   *  reads correctly under a panel, but the words did not — they drew at x = 10,
+   *  behind an opaque rail, so the only thing naming isolation or follow mode
+   *  was invisible at every default panel width. */
+  left,
+}: {
+  width: number;
+  y: number;
+  color: string;
+  text: string;
+  left: number;
+}) {
+  return (
+    <g pointerEvents="none">
+      <rect x={0} y={y} width={width} height={BAR_H} fill={color} fillOpacity={0.16} />
+      <rect x={0} y={y} width={width} height={2} fill={color} />
+      <text
+        x={left + 10}
+        y={y + 16}
+        fill={color}
+        fontFamily="var(--font-ui, system-ui)"
+        fontSize={11}
+        fontWeight={600}
+        letterSpacing={0.4}
+      >
+        {text}
+      </text>
+    </g>
+  );
+}
+
+/**
+ * The live modal transform's pill: which transform, which axis, whose
+ * subject. Bottom-left of the working pane — over the picture being changed
+ * (the FollowBadge's argument), and at the bottom so it never collides with
+ * the follow bar at the top. Width from the label's length at the pill's own
+ * monospace-ish tracking; an SVG has no text measurement without layout, and
+ * a few px of slack is invisible on a translucent plate.
+ */
+/**
+ * The three mode glyphs, as SVG path data on a 16x16 box centred at (8, 8).
+ *
+ * Stroked, not filled, so one `stroke` attribute colours the whole thing and
+ * the shapes read at 14px against a translucent plate. They are the shapes the
+ * tools already imply: a four-way arrow for move, an arc with a head for
+ * rotate, and a diagonal with a box at each end for scale.
+ */
+const MODAL_GLYPHS: Record<ModalMode, string> = {
+  move: "M8 2v12M2 8h12M8 2 6 4.5M8 2l2 2.5M8 14l-2-2.5M8 14l2-2.5M2 8l2.5-2M2 8l2.5 2M14 8l-2.5-2M14 8l-2.5 2",
+  rotate: "M3.2 9.6a5 5 0 1 0 1.5-4.4M4.7 2.2v3.2h3.2",
+  scale: "M4 12 12 4M2.5 10.5h3v3h-3zM10.5 2.5h3v3h-3z",
+};
+
+/** Glyph size and the gap to the label, in CSS px. The pill's own width grows
+ *  by exactly this much so nothing that fitted before starts clipping. */
+const GLYPH_PX = 14;
+const GLYPH_GAP_PX = 6;
+
+/** The axis palette, the same tokens the nav gizmo and the move arms wear. */
+const AXIS_COLORS: Record<"x" | "y" | "z", string> = {
+  x: "var(--axis-x, #ef4444)",
+  y: "var(--axis-y, #22c55e)",
+  z: "var(--axis-z, #3b82f6)",
+};
+
+function ModalBadge({ modal, rect, inset }: { modal: ScreenModal; rect: PaneRect; inset: StageInset }) {
+  const color = modal.camera ? "var(--frustum, #eab308)" : "var(--accent, #3b82f6)";
+  // The glyph wears the AXIS's colour when one is locked, and the pill's own
+  // otherwise. The lock is the thing most worth seeing at a glance, and it is
+  // the one piece of modal state that changes mid-gesture.
+  const glyphColor = modal.axis === null ? color : AXIS_COLORS[modal.axis];
+  const shift = GLYPH_PX + GLYPH_GAP_PX;
+  // INSIDE the chrome on both axes. It sat at x = 10 and y = height - 34, which
+  // is behind the 232px left rail and behind the timeline dock — so the only
+  // thing that says a transform is live has never been visible in the default
+  // layout.
+  const x = inset.left + 10;
+  const y = rect.height - inset.bottom - 34;
+  // The live numbers, written straight into the node. See `modalReadoutSink`:
+  // the readout changes per pointermove and the pill is memoised on state, so
+  // the two have to meet outside React or motion costs a stage commit.
+  const readout = useRef<SVGTextElement | null>(null);
+  useEffect(() => {
+    modalReadoutSink.write = (text: string): void => {
+      if (readout.current !== null) readout.current.textContent = text;
+    };
+    return () => {
+      modalReadoutSink.write = null;
+    };
+  }, []);
+  return (
+    <g pointerEvents="none">
+      <rect
+        x={x}
+        y={y}
+        rx={4}
+        // Room for the label AND the numbers. An SVG has no text measurement
+        // without layout, and a few px of slack is invisible on a translucent
+        // plate; a pill too NARROW would clip the figure the author is reading.
+        width={modal.label.length * 7.5 + 96 + shift}
+        height={24}
+        fill="var(--panel, #1c1c20)"
+        fillOpacity={0.88}
+        stroke={color}
+        strokeWidth={1}
+      />
+      {/* Scaled onto the pill from the 16x16 box the paths are authored in, so
+          the shapes stay editable as plain coordinates. */}
+      <g
+        transform={`translate(${x + 10} ${y + 5}) scale(${GLYPH_PX / 16})`}
+        fill="none"
+        stroke={glyphColor}
+        strokeWidth={1.6}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d={MODAL_GLYPHS[modal.mode]} />
+      </g>
+      <text
+        x={x + 10 + shift}
+        y={y + 16}
+        fill={color}
+        fontFamily="var(--font-ui, system-ui)"
+        fontSize={11}
+        fontWeight={600}
+        letterSpacing={0.6}
+      >
+        {modal.label}
+      </text>
+      <text
+        ref={readout}
+        x={x + modal.label.length * 7.5 + 22 + shift}
+        y={y + 16}
+        fill="var(--text, #e7e7ea)"
+        fontFamily="var(--font-mono, ui-monospace, monospace)"
+        fontSize={11}
+        fontWeight={500}
+      />
+    </g>
+  );
+}
+
+/** Arm length and disc radius, CSS px. The arm is long enough to aim with and
+ *  short enough not to cross the layer it belongs to. */
+const KEY_ARM_PX = 48;
+const KEY_DISC_PX = 9;
+
+function KeyLightGizmo({ light }: { light: ScreenKeyLight }) {
+  const color = "var(--frustum, #eab308)";
+  const [cx, cy] = light.at;
+  // The arm points where the KEY COMES FROM, which is the direction the author
+  // is aiming: a sun in the sky, not a ray leaving it. `dir` is already the
+  // design direction projected into the pane, so this is a sign, not a maths.
+  const tip =
+    light.dir === null ? null : ([cx - light.dir[0] * KEY_ARM_PX, cy - light.dir[1] * KEY_ARM_PX] as const);
+  return (
+    <g>
+      {tip === null ? null : (
+        <line x1={cx} y1={cy} x2={tip[0]} y2={tip[1]} stroke={color} strokeWidth={1.5} strokeDasharray="3 3" />
+      )}
+      {/* The grabbable end. When the key points nearly along the view axis
+          there is no readable 2D direction, so the disc sits ON the layer
+          centre — still draggable, which is what pulls it back out of the
+          degenerate pose. */}
+      <g
+        transform={`translate(${tip === null ? cx : tip[0]} ${tip === null ? cy : tip[1]})`}
+        // The one other piece of overlay furniture that takes pointer events.
+        // Paint hands the event over; the stage owns the drag.
+        pointerEvents="auto"
+        style={{ cursor: "grab" }}
+        onPointerDown={light.onGrab}
+      >
+        <circle r={KEY_DISC_PX} fill="var(--panel, #1c1c20)" fillOpacity={0.9} stroke={color} strokeWidth={1.5} />
+        {/* Four short rays, so the disc reads as a key rather than as another
+            handle. Drawn at the diagonals to stay clear of the arm. */}
+        {[45, 135, 225, 315].map((deg) => {
+          const r = (deg * Math.PI) / 180;
+          return (
+            <line
+              key={deg}
+              x1={Math.cos(r) * (KEY_DISC_PX + 2)}
+              y1={Math.sin(r) * (KEY_DISC_PX + 2)}
+              x2={Math.cos(r) * (KEY_DISC_PX + 5)}
+              y2={Math.sin(r) * (KEY_DISC_PX + 5)}
+              stroke={color}
+              strokeWidth={1.5}
+              strokeLinecap="round"
+            />
+          );
+        })}
+      </g>
+    </g>
+  );
+}
+
+/** The nav gizmo's radius and its ball, in CSS px. Small enough to be furniture
+ *  over the corner of a picture, large enough that a ball is a real click
+ *  target at the size a cursor actually is. */
+const NAV_RADIUS = 30;
+const NAV_BALL = 8;
+const NAV_MARGIN = 16;
+
+/**
+ * Which way is which, in the corner of the working pane.
+ *
+ * ── WHY THIS IS SVG AND NOT A SECOND VIEWPORT ───────────────────────────
+ *
+ * The usual build of this widget is a small scene rendered into its own corner
+ * viewport. That is exactly the construction SplitRenderer's header forbids:
+ * a second render into a scissored canvas, whose failure on the WebGPU backend
+ * is a whole-attachment MSAA resolve that wipes the neighbouring pane — silent,
+ * and invisible to CI because the pinned Chromium cannot make a WebGPU device.
+ *
+ * A nav gizmo shows DIRECTIONS, and the directions are three dot products
+ * against the camera basis (`navBalls`). So it costs no GL at all.
+ *
+ * ── THE AXES ARE THE DESIGN AXES ────────────────────────────────────────
+ *
+ * X right, Y DOWN, Z away — the same three the inspector's fields and the
+ * modal's `G` `Y` mean. Labelling them with world axes instead would put the
+ * letter Y on the arm that moves a layer the opposite way from the number the
+ * author is watching.
+ *
+ * Top-right, which is where every 3D tool puts it — but pushed down past the
+ * chrome that floats over this pane's own top edge. `top` is the chrome's own
+ * measurement, sent across the bridge, and it replaced a hardcoded 116 that a
+ * wrapping control strip on a narrow window grew straight past.
+ */
+function NavGizmo({
+  nav,
+  width,
+  top,
+  /** How far the inspector reaches into this pane from the right. Unlike the
+   *  mode bars', this inset is not cosmetic: the gizmo is the only piece of
+   *  overlay furniture that TAKES POINTER EVENTS, so drawing it under an opaque
+   *  panel makes it unclickable rather than merely hidden. */
+  right,
+}: {
+  nav: ScreenNav;
+  width: number;
+  top: number;
+  right: number;
+}) {
+  const gap = NAV_RADIUS + NAV_BALL + NAV_MARGIN;
+  const cx = width - right - gap;
+  const cy = top + gap;
+  // FAR FIRST. A flat drawing has no depth buffer, so paint order is the only
+  // cue for which end of an axis is pointing at the author — and without it a
+  // gizmo seen from behind reads exactly like one seen from the front.
+  const balls = [...nav.balls].sort((a, b) => a.toward - b.toward);
+  return (
+    <g data-testid="nav-gizmo">
+      {/* THE DISC TURNS THE VIEW. Blender's gizmo drags to orbit, and the body
+          is the part with nothing else to do — a press here can only ever have
+          meant "turn me". `grab` is the cursor because that is what it is. */}
+      <circle
+        cx={cx}
+        cy={cy}
+        r={NAV_RADIUS + NAV_BALL}
+        fill="var(--panel, #0c0c0e)"
+        fillOpacity={0.6}
+        pointerEvents="auto"
+        style={{ cursor: "grab" }}
+        onPointerDown={(e) => nav.onGrab(e, null)}
+      />
+      {balls.map((ball) => {
+        const x = cx + ball.x * NAV_RADIUS;
+        const y = cy + ball.y * NAV_RADIUS;
+        const color = `var(--axis-${ball.axis}, ${NAV_FALLBACK[ball.axis]})`;
+        return (
+          <g
+            key={`${ball.axis}${ball.positive ? "+" : "-"}`}
+            // The SVG root is `pointerEvents: none` so drags pass through it;
+            // these groups opt back in. The press is stopped by the STAGE (see
+            // `onGrab`), which needs the event to open its own drag lane —
+            // stopping it here would leave a ball that could be clicked and
+            // never dragged, which is the behaviour this replaced.
+            pointerEvents="auto"
+            style={{ cursor: "pointer" }}
+            onPointerDown={(e) => nav.onGrab(e, ball)}
+          >
+            {/* The spoke, positive ends only: drawing both makes six lines
+                through one point and reads as a star rather than as an axis. */}
+            {ball.positive ? (
+              <line x1={cx} y1={cy} x2={x} y2={y} stroke={color} strokeWidth={2} />
+            ) : null}
+            <circle
+              cx={x}
+              cy={y}
+              r={NAV_BALL}
+              // FILLED positive, HOLLOW negative — the one thing that tells the
+              // author whether they are looking at +Z or at -Z when the two
+              // project to the same place.
+              fill={ball.positive ? color : "var(--panel, #0c0c0e)"}
+              stroke={color}
+              strokeWidth={1.5}
+            />
+            {ball.positive ? (
+              <text
+                x={x}
+                y={y + 3.5}
+                textAnchor="middle"
+                fill="var(--bg, #000)"
+                fontFamily="var(--font-ui, system-ui)"
+                fontSize={10}
+                fontWeight={700}
+              >
+                {ball.axis.toUpperCase()}
+              </text>
+            ) : null}
+          </g>
+        );
+      })}
+    </g>
+  );
+}
+
+const NAV_FALLBACK: Readonly<Record<"x" | "y" | "z", string>> = {
+  x: "#ef4444",
+  y: "#22c55e",
+  z: "#3b82f6",
+};
+
+/** The seam between the panes. It belongs to the CAMERA pane's first column,
+ *  which is what `paneAt` decides, so it is drawn ON that column rather than
+ *  straddling it — a half-pixel straddle would put the drawn edge and the
+ *  hit-tested edge in different places. */
+function Divider({ x, height }: { x: number; height: number }) {
+  return (
+    <rect
+      x={x}
+      y={0}
+      width={1}
+      height={height}
+      fill="var(--stage-divider, #232328)"
+      shapeRendering="crispEdges"
+    />
+  );
+}
+
+/**
+ * The exportable frame.
+ *
+ * Its rect comes from `frameRect`, which is derived from the SAME numbers as
+ * the camera's view offset — so the border sits exactly on the pixels that will
+ * be exported, at every zoom and every playhead, rather than approximately on
+ * them. The dimmed surround is what makes "you are working off-canvas" legible
+ * without a second camera.
+ */
+function FrameBorder({
+  rect,
+  width,
+  height,
+}: {
+  rect: OverlayProps["frame"];
+  width: number;
+  height: number;
+}) {
+  return (
+    <>
+      {/* Even-odd fill: one path, outer rect minus the frame, so the scrim can
+          never disagree with the border about where the frame is. */}
+      <path
+        d={`M0 0H${width}V${height}H0Z M${rect.x} ${rect.y}H${rect.x + rect.width}V${
+          rect.y + rect.height
+        }H${rect.x}Z`}
+        fillRule="evenodd"
+        fill="rgba(0,0,0,0.45)"
+      />
+      <rect
+        x={rect.x}
+        y={rect.y}
+        width={rect.width}
+        height={rect.height}
+        fill="none"
+        stroke="var(--frame-border, #6b7280)"
+        strokeWidth={1}
+        shapeRendering="crispEdges"
+      />
+    </>
+  );
+}
+
+/** What a click would select. One px and half opacity against the selection's
+ *  1.5 px solid, so the two states are told apart at a glance and never
+ *  mistaken for each other on a layer that is both. */
+function HoverQuad({ quad }: { quad: ScreenQuad }) {
+  return (
+    <polygon
+      points={pointsOf(quad)}
+      fill="none"
+      stroke="var(--accent, #3b82f6)"
+      strokeOpacity={0.5}
+      strokeWidth={1}
+    />
+  );
+}
+
+function SelectionQuad({ quad, handles }: { quad: ScreenQuad; handles?: boolean }) {
+  const points = pointsOf(quad);
+  return (
+    <>
+      <polygon points={points} fill="none" stroke="var(--accent, #3b82f6)" strokeWidth={1.5} />
+      {/* THE SAME TABLE `grabAt` HIT-TESTS, imported rather than restated: a
+          drawn handle the hit test does not answer, or an answered one nobody
+          drew, is the exact bug the hover cursor exists to make impossible. */}
+      {handles !== true
+        ? null
+        : HANDLE_SITES.map((site, i) => {
+            const [x, y] = handlePoint(quad, site);
+            return (
+              <rect
+                key={i}
+                x={x - 3.5}
+                y={y - 3.5}
+                width={7}
+                height={7}
+                fill="var(--panel, #1c1c20)"
+                stroke="var(--accent, #3b82f6)"
+                strokeWidth={1.5}
+              />
+            );
+          })}
+    </>
+  );
+}
+
+/**
+ * The one box around a multi-select.
+ *
+ * ── IT LOOKS DIFFERENT FROM A SELECTION OUTLINE ON PURPOSE ──────────────
+ *
+ * A dashed edge and solid handles, against the members' solid edges and (now)
+ * no handles. The two are different objects and offer different gestures: a
+ * member's outline says "this layer is selected", the box says "these grow
+ * together, about the corner opposite the one you grab". Drawing them alike
+ * would leave the author guessing which of nine outlines the handles belong to.
+ *
+ * The handles come off `HANDLE_SITES` like every other handle in the lane, so
+ * the box the hit test answers and the box the author sees are one table.
+ */
+function UnionBox({ quad }: { quad: ScreenQuad }) {
+  return (
+    <>
+      <polygon
+        points={pointsOf(quad)}
+        fill="none"
+        stroke="var(--accent, #3b82f6)"
+        strokeWidth={1}
+        strokeDasharray="4 3"
+      />
+      {HANDLE_SITES.map((site, i) => {
+        const [x, y] = handlePoint(quad, site);
+        return (
+          <rect
+            key={i}
+            x={x - 3.5}
+            y={y - 3.5}
+            width={7}
+            height={7}
+            fill="var(--panel, #1c1c20)"
+            stroke="var(--accent, #3b82f6)"
+            strokeWidth={1.5}
+          />
+        );
+      })}
+    </>
+  );
+}
+
+/**
+ * The path as it is being drawn, through THE SAME PRINTER the committed layer
+ * uses.
+ *
+ * `pathToD` and not a hand-rolled polyline: the preview has to show the curve
+ * the anchors actually describe, and a second printer here would be a second
+ * answer to "what does this path look like" — visibly wrong the moment a
+ * handle is pulled, which is exactly when the author is looking at it.
+ *
+ * The DOTS are an affordance rather than decoration. One anchor draws no
+ * segment, so without them the author cannot tell a pen that registered their
+ * click from one that did not — and the FIRST dot fills when a press there
+ * would close the loop, which is the only signal that the path can be ended
+ * without reaching for Enter. The tether to the cursor is paid for by a hover
+ * listener in StageApp; the earlier note here said it was not worth a
+ * per-move re-render, and drawing curves rather than a polyline changed that.
+ */
+function PenPreview({ pen }: { pen: ScreenPen }) {
+  const { points, cursor } = pen;
+  const last = points[points.length - 1];
+  return (
+    <g pointerEvents="none">
+      {points.length >= 2 ? (
+        <path d={pathToD({ points: [...points], closed: pen.closed })} fill="none" stroke="var(--accent, #3b82f6)" strokeWidth={1.5} />
+      ) : null}
+      {/* The rubber band to the cursor, drawn as the segment it WOULD become:
+          curved when the anchor behind it carries an outgoing handle. */}
+      {last !== undefined && cursor !== null && !pen.closed ? (
+        <path
+          d={pathToD({ points: [last, { p: [cursor[0], cursor[1]] }], closed: false })}
+          fill="none"
+          stroke="var(--accent, #3b82f6)"
+          strokeWidth={1}
+          strokeDasharray="4 3"
+          opacity={0.7}
+        />
+      ) : null}
+      {/* Handles, so a pulled curve is legible as two arms and not just a bend. */}
+      {points.map((p, i) => (
+        <g key={`h${i}`}>
+          {p.out === undefined ? null : (
+            <line x1={p.p[0]} y1={p.p[1]} x2={p.out[0]} y2={p.out[1]} stroke="var(--accent, #3b82f6)" strokeWidth={1} opacity={0.6} />
+          )}
+          {p.in === undefined ? null : (
+            <line x1={p.p[0]} y1={p.p[1]} x2={p.in[0]} y2={p.in[1]} stroke="var(--accent, #3b82f6)" strokeWidth={1} opacity={0.6} />
+          )}
+        </g>
+      ))}
+      {points.map((p, i) => (
+        <circle
+          key={i}
+          cx={p.p[0]}
+          cy={p.p[1]}
+          r={i === 0 && pen.closeHot ? 5 : 3}
+          // A FILLED first anchor is the whole close affordance: the author
+          // needs to know the next click ends the path before they make it.
+          fill={i === 0 && pen.closeHot ? "var(--accent, #3b82f6)" : "var(--panel, #1c1c20)"}
+          stroke="var(--accent, #3b82f6)"
+          strokeWidth={1.5}
+        />
+      ))}
+    </g>
+  );
+}
+
+function Marquee({ rect }: { rect: ScreenMarquee }) {
+  const x = Math.min(rect.x0, rect.x1);
+  const y = Math.min(rect.y0, rect.y1);
+  return (
+    <rect
+      x={x}
+      y={y}
+      width={Math.abs(rect.x1 - rect.x0)}
+      height={Math.abs(rect.y1 - rect.y0)}
+      fill="var(--accent, #3b82f6)"
+      fillOpacity={0.12}
+      stroke="var(--accent, #3b82f6)"
+      strokeWidth={1}
+    />
+  );
+}
+
+function pointsOf(quad: ScreenQuad): string {
+  const out: string[] = [];
+  for (let i = 0; i < 8; i += 2) out.push(`${quad[i]},${quad[i + 1]}`);
+  return out.join(" ");
+}