@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/overlays/Overlays.tsx

@@ -40,9 +40,15 @@ 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 { ShotBoardPin, ShotSketchGuide, StageInset } from "../../bridgeTypes.js";
+import { clearOf } from "../panes.js";
 import type { PaneRect, StagePane } from "../panes.js";
+import type { FailedQuad, MaskQuad, PathHandleRef, PathKeyRef, PeerQuad } from "../feed.js";
+import { PATH_HANDLE_MIN_PX } from "../motionPathStage.js";
+import type { ScreenMotionPath, ScreenPathKey } from "../motionPathStage.js";
 import type { ScreenQuad } from "../project.js";
+import type { ScreenSpline } from "../splineStage.js";
+import type { Viewport } from "../view.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. */
@@ -63,6 +69,20 @@ export interface ScreenMarquee {
 }
 
 export interface OverlayProps {
+  /**
+   * THE AUTHOR IS WATCHING: draw the frame, and nothing else in it.
+   *
+   * Most of the furniture is already gone by the time it reaches here: the
+   * selection quads because the stage empties the selection it projects, the
+   * marquee and the pen because those lanes never run, the modal badge because
+   * the draft is abandoned, the isolation badge because the chrome leaves
+   * isolation on the way in. This prop is for the two that ARE still live:
+   * the chrome's row-hover outline (`hintCamera`, pushed by a panel that is
+   * still on screen and still hovering) and the snap guides. It is also the
+   * honest way to say the rule once, instead of leaving it as an emergent
+   * property of six other things being empty.
+   */
+  watching: boolean;
   width: number;
   height: number;
   panes: { working: PaneRect | null; camera: PaneRect | null };
@@ -95,22 +115,79 @@ export interface OverlayProps {
    * 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;
+  /**
+   * The CHROME's hover hint — the layer a timeline row under the cursor names,
+   * projected per pane by the stage (bridge `hoverLayer`, v22). Distinct from
+   * `hover` (the stage's own pointer preview) and drawn identically: pointing
+   * at either representation of a layer lights the other.
+   */
+  hintCamera: ScreenQuad | null;
+  hintWorking: ScreenQuad | null;
+  /**
+   * A BROKEN PIECE'S PLACEHOLDER: the outlines of the layers the runtime
+   * isolated because they threw, per pane, and one line naming what failed
+   * (every isolated piece, layer or not), or null when nothing did. Drawn in
+   * the danger colour, dashed, over a faint wash, so a hole in the picture
+   * reads as a failure and never as a layer meant to be empty. Editor paint
+   * only: the export draws none of it, and refuses the frame instead.
+   */
+  failedCamera: readonly FailedQuad[];
+  failedWorking: readonly FailedQuad[];
+  /** A selected Mask group's mask, dashed (gap 7). See `feed.maskCamera`. */
+  maskCamera: readonly MaskQuad[];
+  maskWorking: readonly MaskQuad[];
+  /**
+   * OTHER PEOPLE'S SELECTIONS (bridge v43, Paper page 21): an outline in each
+   * person's colour, their name tagged above one layer. Under our own
+   * selection, and ringing it when we both hold the same layer.
+   */
+  peersCamera: readonly PeerQuad[];
+  peersWorking: readonly PeerQuad[];
+  failure: string | null;
+  /**
+   * THE STUDIO'S COMMENT PINS (bridge v45) on the frame at the playhead, with
+   * what a pin click calls, or null. Furniture, after everything the author
+   * is editing through.
+   */
+  comments: CommentOverlay | null;
+  /**
+   * THE SKETCH GUIDE (bridge v47) in camera-pane CSS px, or null: one
+   * storyboard sketch as dashed outlines with label chips, laid into the
+   * exportable frame by `sketchGuideScreen`, so it moves with the frame.
+   * Furniture, under the selection.
+   */
+  sketchGuide: ScreenSketchGuide | null;
+  /** The open Studio pin's layer in the camera pane (S5), ringed dashed.
+   *  Drawn only while `comments` is up. */
+  pinLayer?: ScreenQuad | null;
+  /** The empty Shot's one line of help ("Press R for a rectangle..."), centred
+   *  in the frame, or null once the Shot has a layer or a gesture is live.
+   *  Furniture, so it never reaches an export or a still. */
+  emptyHint: string | null;
+  /**
+   * PILOTING the shot camera from the Camera pane, or null.
+   *
+   * The badge is drawn INSIDE the pane whose navigation is writing the
+   * document, with its EJECT on it: a mode the author armed has to be
+   * leavable from the picture it is changing (the isolation badge's rule).
+   * `text` is composed by the chrome, which knows what holds the camera.
+   */
+  pilot: { text: string; onEject: () => void } | null;
+  /**
+   * The component driving the render camera, by name, or null while the
+   * document's rig does. Said INSIDE the 3D pane, where the camera object
+   * follows a camera nothing in the document describes: without it, the
+   * gizmo's grips going dead and the inspector's fields moving nothing read
+   * as two unrelated breakages.
+   */
+  driver: string | null;
+  /** A subtree is isolated (and still in the scene). Isolation REPLACES the
+   *  working pane's camera with a derived head-on orthographic rig
+   *  (isolation.ts), so the pane wears a ring that says it is in a mode. The
+   *  NAME of the subtree and the way out are the chrome's breadcrumb. */
+  isolating: boolean;
   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.
    *
@@ -125,11 +202,33 @@ export interface OverlayProps {
    * this lane keeps removing.
    */
   guidesWorking: readonly { a: readonly [number, number]; b: readonly [number, number] }[];
+  splineGuides: readonly { id: string; pts: readonly number[]; selected: boolean }[];
+  /** The selected layers' motion paths per pane (gap 3), and the key dot the
+   *  pointer is over or dragging. */
+  motionPathsCamera: readonly ScreenMotionPath[];
+  motionPathsWorking: readonly ScreenMotionPath[];
+  pathKeyHover: PathKeyRef | null;
+  /** The dot whose Bezier handles show (schema v40), and the handle the
+   *  pointer is over or dragging. Both null in a read-only viewer. */
+  pathKeySelected: PathKeyRef | null;
+  pathHandleHover: PathHandleRef | null;
+  /** The pen's path so far, in the CSS px of its pane (`ScreenPen.pane`), 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. */
   pen: ScreenPen | null;
+  /** A 3D spline draft or point-edit overlay, in working-pane CSS px. */
+  spline: ScreenSpline | 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 constraint axis through the pivot, while a gizmo arm is held. Working
+   *  pane only, because that is the only pane the gizmo is drawn in. */
+  axisGuide: ScreenAxisGuide | 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;
@@ -138,17 +237,26 @@ export interface OverlayProps {
    *  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.
+   * How far the chrome's docked 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.
+   * modal pill, the nav gizmo — because the panes TILE the whole window and the
+   * chrome's opaque cells sit on top of them. In a split they tile it between
+   * the two of them, which is why no piece of furniture may read a raw edge
+   * (below). 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.
+   *
+   * NO FURNITURE SUBTRACTS THESE EDGES ITSELF. The inset describes the WINDOW's
+   * clear band, not each pane's, so it is only ever read through `clearOf`
+   * below — see its header for the two pieces that hand-rolled the subtraction
+   * and both landed a whole panel's width away from where they meant to be.
    *
-   * The pane RECTS are untouched: insetting those would move the scissor and
-   * shrink the rendered picture. This is paint only.
+   * The pane RECTS still partition the whole viewport: the scissor draws
+   * full-bleed under the docked chrome, so nothing here shrinks the rendered
+   * picture or moves the hit test. (`paneRects` does take the inset now, but
+   * for one thing only — where the split SEAM falls.)
    */
   inset: StageInset;
 }
@@ -214,6 +322,17 @@ export interface ScreenModal {
    *  "S then X" says which direction is about to move without a second look at
    *  the label. */
   axis: ModalAxis;
+  /**
+   * Which pane the pill belongs in.
+   *
+   * A MODAL is working-pane-only and always says `"working"`, but this badge is
+   * now also every POINTER drag's readout (StageApp's `DRAG_BADGES`), and a
+   * body drag or a resize happens in whichever pane the author pressed. Pinning
+   * it to the working pane would have put the numbers for a camera-pane resize
+   * in a pane the author is not looking at — or, in the camera-only layout,
+   * nowhere at all.
+   */
+  pane: StagePane;
 }
 
 /**
@@ -230,14 +349,82 @@ export interface ScreenModal {
  */
 export const modalReadoutSink: { write: ((text: string) => void) | null } = { write: null };
 
+/**
+ * The constraint axis, drawn through the pivot while a gesture is locked to it.
+ *
+ * ── WHY BLENDER DRAWS THIS AND WHY IT MATTERS HERE ──────────────────────
+ *
+ * A locked transform's only cue was the tinted glyph in the pill, at the far
+ * corner of the pane. The line puts the constraint AT THE POINT OF ACTION: it
+ * says which way the motion runs, where it runs off screen, and — once the
+ * layer has moved — how far off the axis the cursor has wandered while the
+ * layer stayed on it (which is exactly what an axis lock is for).
+ *
+ * A screen segment and not a world one: a perspective projection maps the 3D
+ * axis to a 2D line, so this IS the axis, without near-plane clipping. The
+ * pane's own clip path trims it.
+ */
+export interface ScreenAxisGuide {
+  a: readonly [number, number];
+  b: readonly [number, number];
+  axis: "x" | "y" | "z";
+  /** The pane it is drawn in. The gizmo's guide is the working pane's; a
+   *  motion path key drag (gap 3) draws in whichever pane it started in. */
+  pane?: StagePane;
+}
+
 export interface ScreenPen {
+  /** The pane the pen draws on, the frame pane: the camera pane over a Shot,
+   *  a definition's one pane inside it. `ScreenModal.pane`'s rule. */
+  pane: StagePane;
   points: readonly PathPoint[];
   closed: boolean;
   cursor: readonly [number, number] | null;
   closeHot: boolean;
 }
 
+/** The sketch guide laid into the camera pane: CSS px from its top-left. */
+export interface ScreenSketchGuide {
+  rects: readonly { x: number; y: number; width: number; height: number; radius: number; label?: string }[];
+  arrows: readonly { x1: number; y1: number; x2: number; y2: number; label?: string }[];
+}
+
+/**
+ * A guide's design px (origin at the canvas centre, +y down) laid into the
+ * exportable frame's rect, the one conversion the guide takes: a sketch is a
+ * picture of the frame, so it scales and moves with the frame and never with
+ * a layer.
+ */
+export function sketchGuideScreen(
+  guide: ShotSketchGuide,
+  frame: OverlayProps["frame"],
+  size: { width: number; height: number },
+): ScreenSketchGuide {
+  const kx = frame.width / size.width;
+  const ky = frame.height / size.height;
+  const x = (dx: number): number => frame.x + (dx + size.width / 2) * kx;
+  const y = (dy: number): number => frame.y + (dy + size.height / 2) * ky;
+  return {
+    rects: guide.rects.map((r) => ({
+      x: x(r.at[0] - r.size[0] / 2),
+      y: y(r.at[1] - r.size[1] / 2),
+      width: r.size[0] * kx,
+      height: r.size[1] * ky,
+      radius: (r.radius ?? 0) * Math.min(kx, ky),
+      ...(r.label === undefined ? {} : { label: r.label }),
+    })),
+    arrows: guide.arrows.map((a) => ({
+      x1: x(a.from[0]),
+      y1: y(a.from[1]),
+      x2: x(a.to[0]),
+      y2: y(a.to[1]),
+      ...(a.label === undefined ? {} : { label: a.label }),
+    })),
+  };
+}
+
 export function Overlays({
+  watching,
   width,
   height,
   panes,
@@ -248,21 +435,51 @@ export function Overlays({
   unionCamera,
   unionWorking,
   hover,
-  followsView,
-  isolation,
+  hintCamera,
+  hintWorking,
+  failedCamera,
+  failedWorking,
+  maskCamera,
+  maskWorking,
+  peersCamera,
+  peersWorking,
+  failure,
+  comments,
+  sketchGuide,
+  pinLayer,
+  emptyHint,
+  pilot,
+  driver,
+  isolating,
   marquee,
   guides,
   guidesWorking,
+  splineGuides,
+  motionPathsCamera,
+  motionPathsWorking,
+  pathKeyHover,
+  pathKeySelected,
+  pathHandleHover,
   pen,
+  spline,
   modal,
+  axisGuide,
   nav,
   keyLight,
   inset,
 }: OverlayProps) {
   const { working, camera } = panes;
+  // ONE reading of the inset per pane, and every piece of furniture below lays
+  // out inside it. See `clearOf`: the two sites that did this arithmetic
+  // themselves both charged their pane for a panel on the other side of the
+  // seam.
+  const viewport: Viewport = { width, height };
+  const clearWorking = working === null ? null : clearOf(working, inset, viewport);
+  const clearCamera = camera === null ? null : clearOf(camera, inset, viewport);
   return (
     <svg
       className="stage-overlay"
+      data-dailies-stage-furniture=""
       width={width}
       height={height}
       viewBox={`0 0 ${width} ${height}`}
@@ -275,7 +492,7 @@ export function Overlays({
         {camera === null ? null : <PaneClip id="shot-pane-camera" rect={camera} />}
       </defs>
 
-      {working === null ? null : (
+      {working === null || clearWorking === 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
@@ -283,6 +500,36 @@ export function Overlays({
           {/* 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}
+          {/* The chrome's row-hover, same treatment: which layer is this. */}
+          {hintWorking === null ? null : <HoverQuad quad={hintWorking} />}
+          {peersWorking.map((row, i) => (
+            <PeerOutline key={`peer-${i}`} {...row} />
+          ))}
+          {/* Under the selection, like the hover: a broken layer that is
+              selected must still read as selected. */}
+          {failedWorking.map((row, i) => (
+            <FailedPlaceholder key={`failed-${i}`} {...row} />
+          ))}
+          {/* UNDER everything the author is judging — it is a reference line,
+              not a mark. Dashed and half-lit for the same reason: at full
+              weight a line clean across the pane reads as geometry. */}
+          {axisGuide === null || (axisGuide.pane ?? "working") !== "working" ? null : (
+            <AxisGuideLine guide={axisGuide} />
+          )}
+          {splineGuides.map((guide) => (
+            <polyline
+              key={`spline-guide-${guide.id}`}
+              points={flatPolyline(guide.pts)}
+              fill="none"
+              stroke="var(--accent)"
+              strokeWidth={guide.selected ? 1.5 : 1}
+              strokeDasharray={guide.selected ? undefined : "4 4"}
+              opacity={guide.selected ? 1 : 0.72}
+            />
+          ))}
+          {maskWorking.map((row, i) => (
+            <MaskOutline key={`mask-${i}`} {...row} />
+          ))}
           {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
@@ -296,6 +543,16 @@ export function Overlays({
             />
           ))}
           {unionWorking === null ? null : <UnionBox quad={unionWorking} />}
+          {motionPathsWorking.map((path) => (
+            <MotionPathMark
+              key={`path-${path.layerId}`}
+              path={path}
+              hover={pathKeyHover}
+              selected={pathKeySelected}
+              handleHover={pathHandleHover}
+            />
+          ))}
+          {spline === null ? null : <SplinePreview spline={spline} />}
           {/* 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. */}
@@ -306,43 +563,107 @@ export function Overlays({
               y1={g.a[1]}
               x2={g.b[0]}
               y2={g.b[1]}
-              stroke="var(--guide, #f43f5e)"
+              stroke="var(--guide, #f5a524)"
               strokeWidth={1}
             />
           ))}
           {marquee?.pane === "working" ? <Marquee rect={marquee} /> : null}
+          {pen?.pane === "working" ? <PenPreview pen={pen} /> : null}
+          {isolating ? <IsolationRing clear={clearWorking} /> : 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
+          {driver === null ? null : (
+            <ModeBar
               width={working.width}
-              y={inset.top}
-              left={inset.left}
-              label={isolation}
+              y={clearWorking.y}
+              left={clearWorking.x}
+              color="var(--frustum, #eab308)"
+              text={`CAMERA DRIVEN BY ${driver.toUpperCase()}`}
             />
           )}
-          {/* 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
+          {keyLight === null ? null : <KeyLightGizmo light={keyLight} />}
+          {modal?.pane === "working" ? <ModalBadge modal={modal} clear={clearWorking} /> : null}
+          {nav === null ? null : <NavGizmo nav={nav} clear={clearWorking} />}
+          {/* The failure bar in the one pane there is, when there is no
+              camera pane to carry it. */}
+          {failure === null || camera !== null ? null : (
+            <ModeBar
               width={working.width}
-              y={inset.top + (isolation === null ? 0 : BAR_H)}
-              left={inset.left}
+              y={clearWorking.y + clearWorking.height - BAR_H}
+              left={clearWorking.x}
+              color="var(--danger, #ff5c69)"
+              text={failure}
             />
-          ) : 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 : (
+      {camera === null || clearCamera === null ? null : (
         <g clipPath="url(#shot-pane-camera)" transform={`translate(${camera.x} ${camera.y})`}>
+          {/* THE FRAME BORDER SURVIVES VIDEO, and nothing else does. It is not
+              furniture: it is the edge of the picture being watched, and
+              without it a letterboxed shot has no visible boundary at all. */}
           <FrameBorder rect={frame} width={camera.width} height={camera.height} />
+          {/* A BROKEN PIECE SURVIVES VIDEO TOO: watching a picture with a hole
+              in it is exactly when the author must be told it has one. At the
+              bottom of the clear band, where no mode bar stacks. */}
+          {failedCamera.map((row, i) => (
+            <FailedPlaceholder key={`failed-${i}`} {...row} />
+          ))}
+          {failure === null ? null : (
+            <ModeBar
+              width={camera.width}
+              y={clearCamera.y + clearCamera.height - BAR_H}
+              left={clearCamera.x}
+              color="var(--danger, #ff5c69)"
+              text={failure}
+            />
+          )}
+          {watching ? null : (
+            <>
+          {/* PILOTING is this pane's mode: its middle-drag, shift-drag and
+              wheel are writing the shot camera. Top of the clear band. */}
+          {pilot === null ? null : (
+            <PilotBadge
+              width={camera.width}
+              y={clearCamera.y}
+              left={clearCamera.x}
+              right={clearCamera.x + clearCamera.width}
+              text={pilot.text}
+              onEject={pilot.onEject}
+            />
+          )}
+          {emptyHint === null ? null : (
+            <text
+              data-testid="empty-hint"
+              x={frame.x + frame.width / 2}
+              y={frame.y + frame.height / 2}
+              textAnchor="middle"
+              dominantBaseline="middle"
+              fill="var(--ink-3, #9c9c9c)"
+              // A ground under the words, painted first: the frame is
+              // the Shot's background, which can be any colour.
+              stroke="var(--surface-app, #080808)"
+              strokeWidth={3}
+              paintOrder="stroke"
+              fontFamily="var(--font-sans, system-ui)"
+              fontSize={13}
+            >
+              {emptyHint}
+            </text>
+          )}
+          {/* THE SKETCH GUIDE (bridge v47), first: a reference to animate
+              toward, under everything the author is editing. */}
+          {sketchGuide === null ? null : <SketchGuideOverlay guide={sketchGuide} />}
           {hover?.pane === "camera" ? <HoverQuad quad={hover.quad} /> : null}
+          {/* The chrome's row-hover, same treatment: which layer is this. */}
+          {hintCamera === null ? null : <HoverQuad quad={hintCamera} />}
+          {peersCamera.map((row, i) => (
+            <PeerOutline key={`peer-${i}`} {...row} />
+          ))}
+          {maskCamera.map((row, i) => (
+            <MaskOutline key={`mask-${i}`} {...row} />
+          ))}
           {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
@@ -354,6 +675,16 @@ export function Overlays({
             <SelectionQuad key={i} quad={q} handles={locked[i] !== true && unionCamera === null} />
           ))}
           {unionCamera === null ? null : <UnionBox quad={unionCamera} />}
+          {axisGuide?.pane !== "camera" ? null : <AxisGuideLine guide={axisGuide} />}
+          {motionPathsCamera.map((path) => (
+            <MotionPathMark
+              key={`path-${path.layerId}`}
+              path={path}
+              hover={pathKeyHover}
+              selected={pathKeySelected}
+              handleHover={pathHandleHover}
+            />
+          ))}
           {guides.map((g, i) =>
             g.axis === "x" ? (
               <line
@@ -362,7 +693,7 @@ export function Overlays({
                 y1={0}
                 x2={g.at}
                 y2={camera.height}
-                stroke="var(--guide, #f43f5e)"
+                stroke="var(--guide, #f5a524)"
                 strokeWidth={1}
               />
             ) : (
@@ -372,13 +703,16 @@ export function Overlays({
                 y1={g.at}
                 x2={camera.width}
                 y2={g.at}
-                stroke="var(--guide, #f43f5e)"
+                stroke="var(--guide, #f5a524)"
                 strokeWidth={1}
               />
             ),
           )}
           {marquee?.pane === "camera" ? <Marquee rect={marquee} /> : null}
-          {pen === null || pen.points.length === 0 ? null : <PenPreview pen={pen} />}
+          {pen?.pane === "camera" ? <PenPreview pen={pen} /> : null}
+          {/* THE COMMENT PINS (bridge v45), over what the author is editing
+              through and never under it. */}
+          {comments === null ? null : <CommentPinsOverlay comments={comments} pinLayer={pinLayer ?? null} frame={frame} />}
           {/* 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
@@ -386,13 +720,12 @@ export function Overlays({
               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}
-            />
+          {isolating && working === null ? <IsolationRing clear={clearCamera} /> : null}
+          {/* A drag that STARTED HERE reads its numbers here. Modals never do
+              — the keymap arms them over the working pane alone — so in
+              practice this is the resize / body-move / roll readout. */}
+          {modal?.pane === "camera" ? <ModalBadge modal={modal} clear={clearCamera} /> : null}
+            </>
           )}
         </g>
       )}
@@ -426,57 +759,115 @@ function PaneClip({ id, rect }: { id: string; rect: PaneRect }) {
  * 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. */
+/** Height of a mode bar. Shared so the bars that stack can do so without
+ *  restating each 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"
-    />
-  );
-}
+/** How wide the EJECT plate on the pilot badge is, and its inset from the
+ *  clear band's right edge. */
+const EJECT_W = 58;
+const EJECT_GAP = 8;
 
 /**
- * "You are inside this layer", said INSIDE the pane it is true of.
+ * "You are piloting the shot camera", said in the pane whose navigation is
+ * writing it, with the way out on the badge.
  *
- * 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.
+ * Unreal's pilot banner: the piloted thing named top-left and an eject beside
+ * it, because a mode that turns every drag into a document write is the one
+ * an author must never have to hunt for the exit of. The text is the chrome's
+ * (it knows whether a move or a component holds the camera); the plate is the
+ * one piece of this bar that takes pointer events, on the nav gizmo's pattern
+ * (`pointerEvents="auto"` opting back in under a `none` root).
  */
-function IsolationBadge({
+function PilotBadge({
   width,
   y,
-  label,
   left,
+  right,
+  text,
+  onEject,
 }: {
   width: number;
   y: number;
-  label: string;
   left: number;
+  right: number;
+  text: string;
+  onEject: () => void;
 }) {
+  const x = Math.max(left, right - EJECT_GAP - EJECT_W);
   return (
-    <ModeBar
-      width={width}
-      y={y}
-      left={left}
-      color="var(--accent, #3b82f6)"
-      text={`INSIDE ${label.toUpperCase()} — ESC TO LEAVE`}
+    <g data-testid="pilot-badge">
+      <ModeBar width={width} y={y} left={left} color="var(--frustum, #eab308)" text={text} />
+      <g
+        pointerEvents="auto"
+        style={{ cursor: "pointer" }}
+        data-testid="pilot-eject"
+        onPointerDown={(e) => {
+          // The press is CONSUMED here: the stage's own lane would otherwise
+          // read it as a camera-pane press and start a marquee under the badge.
+          e.stopPropagation();
+          e.preventDefault();
+          onEject();
+        }}
+      >
+        <rect
+          x={x}
+          y={y + 3}
+          width={EJECT_W}
+          height={BAR_H - 6}
+          rx={3}
+          fill="var(--frustum, #eab308)"
+          fillOpacity={0.28}
+        />
+        <text
+          x={x + EJECT_W / 2}
+          y={y + 15}
+          textAnchor="middle"
+          fill="var(--frustum, #eab308)"
+          fontFamily="var(--font-sans, system-ui)"
+          fontSize={10}
+          fontWeight={700}
+          letterSpacing={0.6}
+        >
+          EJECT
+        </text>
+      </g>
+    </g>
+  );
+}
+
+/**
+ * "You are inside a layer", said INSIDE the pane it is true of, as a ring.
+ *
+ * Isolation is the largest mode this pane has: `StageTools` swaps a derived
+ * orthographic head-on rig into the working camera's slot, and picking is
+ * scoped to the subtree. With no in-pane sign, that reads as the view having
+ * frozen. The sign was once a tinted bar of capitals across the top of the
+ * picture ("INSIDE CARD. ESC TO LEAVE"), which the author read as cheap and
+ * which covered the top of the very subject they had entered to edit.
+ *
+ * The ring says only "a mode is on". WHICH layer, the trail back up and the
+ * way out are the breadcrumb in the stage header (`IsolationTrail`), where
+ * every other piece of navigation lives. It traces the clear band, so it sits
+ * inside the docked chrome rather than under it.
+ *
+ * The accent, not the frustum's yellow: the subject is a LAYER, which is the
+ * same subject-colour rule ModalBadge follows.
+ */
+function IsolationRing({ clear }: { clear: PaneRect }) {
+  return (
+    <rect
+      data-testid="isolation-ring"
+      x={clear.x + 1}
+      y={clear.y + 1}
+      width={Math.max(0, clear.width - 2)}
+      height={Math.max(0, clear.height - 2)}
+      rx={6}
+      fill="none"
+      stroke="var(--accent, #0099ff)"
+      strokeOpacity={0.55}
+      strokeWidth={2}
+      pointerEvents="none"
     />
   );
 }
@@ -486,11 +877,11 @@ function ModeBar({
   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. */
+  /** The left edge of this pane's clear band, pane-local (`clearOf`). 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;
@@ -507,7 +898,7 @@ function ModeBar({
         x={left + 10}
         y={y + 16}
         fill={color}
-        fontFamily="var(--font-ui, system-ui)"
+        fontFamily="var(--font-sans, system-ui)"
         fontSize={11}
         fontWeight={600}
         letterSpacing={0.4}
@@ -545,26 +936,33 @@ const MODAL_GLYPHS: Record<ModalMode, string> = {
 const GLYPH_PX = 14;
 const GLYPH_GAP_PX = 6;
 
-/** The axis palette, the same tokens the nav gizmo and the move arms wear. */
+/** The axis palette, the same tokens the nav gizmo and the move arms wear. ONE
+ *  map for both overlay sites: the nav ball kept its own copy of the three hexes
+ *  and drew from those instead, so re-pointing an --axis-* token moved the modal
+ *  badge's glyph and left the ball behind. */
 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)";
+function ModalBadge({ modal, clear }: { modal: ScreenModal; clear: PaneRect }) {
+  const color = modal.camera ? "var(--frustum, #eab308)" : "var(--accent, #0099ff)";
   // 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;
+  // INSIDE THIS PANE'S CLEAR BAND, 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 had never
+  // been visible in the default layout. It then sat at `inset.left + 10`, which
+  // is right for the working pane (whose origin IS the window's) and wrong for
+  // a camera pane in a split, where pane-local x is measured from the seam: a
+  // camera-pane resize put its numbers a rail's width in from an edge no rail
+  // touches. `clear` is the answer for whichever pane this is. See `clearOf`.
+  const x = clear.x + 10;
+  const y = clear.y + clear.height - 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.
@@ -578,7 +976,7 @@ function ModalBadge({ modal, rect, inset }: { modal: ScreenModal; rect: PaneRect
     };
   }, []);
   return (
-    <g pointerEvents="none">
+    <g data-testid="modal-badge" pointerEvents="none">
       <rect
         x={x}
         y={y}
@@ -588,7 +986,7 @@ function ModalBadge({ modal, rect, inset }: { modal: ScreenModal; rect: PaneRect
         // 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)"
+        fill="var(--surface-panel, #111111)"
         fillOpacity={0.88}
         stroke={color}
         strokeWidth={1}
@@ -609,7 +1007,7 @@ function ModalBadge({ modal, rect, inset }: { modal: ScreenModal; rect: PaneRect
         x={x + 10 + shift}
         y={y + 16}
         fill={color}
-        fontFamily="var(--font-ui, system-ui)"
+        fontFamily="var(--font-sans, system-ui)"
         fontSize={11}
         fontWeight={600}
         letterSpacing={0.6}
@@ -620,7 +1018,7 @@ function ModalBadge({ modal, rect, inset }: { modal: ScreenModal; rect: PaneRect
         ref={readout}
         x={x + modal.label.length * 7.5 + 22 + shift}
         y={y + 16}
-        fill="var(--text, #e7e7ea)"
+        fill="var(--ink-1, #f5f5f5)"
         fontFamily="var(--font-mono, ui-monospace, monospace)"
         fontSize={11}
         fontWeight={500}
@@ -659,7 +1057,7 @@ function KeyLightGizmo({ light }: { light: ScreenKeyLight }) {
         style={{ cursor: "grab" }}
         onPointerDown={light.onGrab}
       >
-        <circle r={KEY_DISC_PX} fill="var(--panel, #1c1c20)" fillOpacity={0.9} stroke={color} strokeWidth={1.5} />
+        <circle r={KEY_DISC_PX} fill="var(--surface-panel, #111111)" 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) => {
@@ -710,29 +1108,23 @@ const NAV_MARGIN = 16;
  * 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
+ * Top-right of the part of this pane the chrome is not covering, which is where
+ * every 3D tool puts it. Staying clear of the panels is not cosmetic here: 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. That reach used to be a hardcoded 116 for the top edge, which a
  * wrapping control strip on a narrow window grew straight past.
+ *
+ * IT ASKS FOR A CLEAR RECT AND SUBTRACTS NOTHING. It used to compute
+ * `width - inset.right - gap` from the pane's own width, and in a split that is
+ * a double count: the inspector sits on the far side of the SEAM and covers no
+ * part of the working pane, so the gizmo was shoved an inspector's width left,
+ * into the middle of the picture it is meant to sit beside. See `clearOf`.
  */
-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;
-}) {
+function NavGizmo({ nav, clear }: { nav: ScreenNav; clear: PaneRect }) {
   const gap = NAV_RADIUS + NAV_BALL + NAV_MARGIN;
-  const cx = width - right - gap;
-  const cy = top + gap;
+  const cx = clear.x + clear.width - gap;
+  const cy = clear.y + 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.
@@ -746,7 +1138,7 @@ function NavGizmo({
         cx={cx}
         cy={cy}
         r={NAV_RADIUS + NAV_BALL}
-        fill="var(--panel, #0c0c0e)"
+        fill="var(--surface-panel, #111111)"
         fillOpacity={0.6}
         pointerEvents="auto"
         style={{ cursor: "grab" }}
@@ -755,7 +1147,7 @@ function NavGizmo({
       {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]})`;
+        const color = AXIS_COLORS[ball.axis];
         return (
           <g
             key={`${ball.axis}${ball.positive ? "+" : "-"}`}
@@ -780,7 +1172,7 @@ function NavGizmo({
               // 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)"}
+              fill={ball.positive ? color : "var(--surface-panel, #111111)"}
               stroke={color}
               strokeWidth={1.5}
             />
@@ -789,8 +1181,8 @@ function NavGizmo({
                 x={x}
                 y={y + 3.5}
                 textAnchor="middle"
-                fill="var(--bg, #000)"
-                fontFamily="var(--font-ui, system-ui)"
+                fill="var(--surface-app, #080808)"
+                fontFamily="var(--font-sans, system-ui)"
                 fontSize={10}
                 fontWeight={700}
               >
@@ -804,12 +1196,6 @@ function NavGizmo({
   );
 }
 
-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
@@ -821,7 +1207,7 @@ function Divider({ x, height }: { x: number; height: number }) {
       y={0}
       width={1}
       height={height}
-      fill="var(--stage-divider, #232328)"
+      fill="var(--stage-divider, #2a2a2a)"
       shapeRendering="crispEdges"
     />
   );
@@ -857,12 +1243,13 @@ function FrameBorder({
         fill="rgba(0,0,0,0.45)"
       />
       <rect
+        data-testid="stage-frame-border"
         x={rect.x}
         y={rect.y}
         width={rect.width}
         height={rect.height}
         fill="none"
-        stroke="var(--frame-border, #6b7280)"
+        stroke="var(--frame-border, rgba(255, 255, 255, 0.22))"
         strokeWidth={1}
         shapeRendering="crispEdges"
       />
@@ -878,18 +1265,290 @@ function HoverQuad({ quad }: { quad: ScreenQuad }) {
     <polygon
       points={pointsOf(quad)}
       fill="none"
-      stroke="var(--accent, #3b82f6)"
+      stroke="var(--accent, #0099ff)"
       strokeOpacity={0.5}
       strokeWidth={1}
     />
   );
 }
 
+/** Paper page 21: a peer's tag is 19 px tall, 6 px each side, sitting on the
+ *  outline's top-left corner, which it squares. */
+const PEER_TAG_H = 19;
+const PEER_RING = 3;
+
+/** A peer's outline in their colour, and when it carries the tag, their name
+ *  on that colour above it. A layer we hold too gets the outline as a ring
+ *  `PEER_RING` px outside our own, so both read. */
+function PeerOutline({ quad, name, color, tag, ring }: PeerQuad) {
+  const shape = ring ? ringQuad(quad, PEER_RING) : quad;
+  const x = Math.min(shape[0], shape[2], shape[4], shape[6]);
+  const y = Math.min(shape[1], shape[3], shape[5], shape[7]);
+  const label = peerLabel(name);
+  const width = label.length * PLACEHOLDER_CHAR_PX + 12;
+  return (
+    <g data-testid="stage-peer-selection" data-peer={name}>
+      <polygon points={pointsOf(shape)} fill="none" stroke={color} strokeWidth={1.5} />
+      {tag ? (
+        <>
+          <rect x={x - 0.75} y={y - PEER_TAG_H} width={width} height={PEER_TAG_H} rx={4} fill={color} />
+          {/* The corner on the outline is square. */}
+          <rect x={x - 0.75} y={y - 8} width={8} height={8} fill={color} />
+          <text
+            x={x + 5.25}
+            y={y - 5}
+            fill="#0B0B0B"
+            fontFamily="var(--font-sans, Inter, system-ui)"
+            fontSize={11}
+            fontWeight={600}
+          >
+            {label}
+          </text>
+        </>
+      ) : null}
+    </g>
+  );
+}
+
+/** A name fits a tag of at most ~200 px. */
+const PEER_NAME_MAX = 28;
+export function peerLabel(name: string): string {
+  return name.length <= PEER_NAME_MAX ? name : `${name.slice(0, PEER_NAME_MAX - 1).trimEnd()}…`;
+}
+
+/** The quad grown by `by` px on every side: each corner pushed away from the
+ *  centre along both axes. Exact for an upright box, close for a turned one. */
+export function ringQuad(quad: ScreenQuad, by: number): ScreenQuad {
+  const cx = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
+  const cy = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+  const out: number[] = [...quad];
+  for (let i = 0; i < 8; i += 2) {
+    out[i] = quad[i]! + Math.sign(quad[i]! - cx) * by;
+    out[i + 1] = quad[i + 1]! + Math.sign(quad[i + 1]! - cy) * by;
+  }
+  return out as unknown as ScreenQuad;
+}
+
+/** Where an isolated layer would draw: a dashed danger outline over a faint
+ *  danger wash, and a short label in its top-left corner. Dashed so it never
+ *  reads as a selection, washed so the hole reads as a place and not only an
+ *  edge, labelled so an empty box is never mistaken for an empty layer. The
+ *  reason is the inspector's. The layer stays selectable, movable and
+ *  deletable: picking reads the layer's frame, which the runtime still writes,
+ *  never what it drew. */
+function FailedPlaceholder({ quad, label }: FailedQuad) {
+  const x = Math.min(quad[0], quad[2], quad[4], quad[6]);
+  const y = Math.min(quad[1], quad[3], quad[5], quad[7]);
+  const width = Math.max(quad[0], quad[2], quad[4], quad[6]) - x;
+  return (
+    <g data-testid="stage-failed-piece">
+      <polygon
+        points={pointsOf(quad)}
+        fill="var(--danger, #ff5c69)"
+        fillOpacity={0.1}
+        stroke="var(--danger, #ff5c69)"
+        strokeWidth={1.5}
+        strokeDasharray="6 4"
+      />
+      <text
+        x={x + 6}
+        y={y + 16}
+        fill="var(--danger, #ff5c69)"
+        fontFamily="var(--font-sans, system-ui)"
+        fontSize={11}
+        fontWeight={600}
+      >
+        {placeholderLine(label, width - 12)}
+      </text>
+    </g>
+  );
+}
+
+/** About one 11 px semibold sans character. An estimate: SVG text has no
+ *  ellipsis, and measuring would need a layout pass per frame. */
+const PLACEHOLDER_CHAR_PX = 6.6;
+const DID_NOT_LOAD = " did not load";
+
+/** "<name> did not load", cut to `room` px. The name gives way first, so the
+ *  line keeps saying what happened for as long as it fits. */
+export function placeholderLine(label: string, room: number): string {
+  const chars = Math.floor(room / PLACEHOLDER_CHAR_PX);
+  const line = `${label}${DID_NOT_LOAD}`;
+  if (line.length <= chars) return line;
+  const nameRoom = chars - DID_NOT_LOAD.length - 1;
+  if (nameRoom >= 1) return `${label.slice(0, nameRoom).trimEnd()}…${DID_NOT_LOAD}`;
+  return chars >= 2 ? `${line.slice(0, chars - 1).trimEnd()}…` : "";
+}
+
+/** A selected Mask group's mask (Paper page 25, "Mask outline (dashed)"): the
+ *  selection's accent at its 1.5 px, dashed so it reads as the matte's edge
+ *  and never as a second selection. */
+function MaskOutline({ quad, round }: MaskQuad) {
+  return round ? (
+    <path
+      data-testid="stage-mask-outline"
+      d={inscribedEllipse(quad)}
+      fill="none"
+      stroke="var(--accent, #0099ff)"
+      strokeWidth={1.5}
+      strokeDasharray="4 3"
+    />
+  ) : (
+    <polygon
+      data-testid="stage-mask-outline"
+      points={pointsOf(quad)}
+      fill="none"
+      stroke="var(--accent, #0099ff)"
+      strokeWidth={1.5}
+      strokeDasharray="4 3"
+    />
+  );
+}
+
+/** The ellipse inscribed in a quad, as four cubics through its edge midpoints.
+ *  Each control point sits `KAPPA` of the way from a midpoint to the corner it
+ *  turns about, the circle's cubic, and an affine map keeps it exact for any
+ *  parallelogram. A perspective quad gets a close approximation. */
+const KAPPA = 0.5523;
+export function inscribedEllipse(quad: ScreenQuad): string {
+  const pt = (i: number): [number, number] => [quad[(i % 4) * 2]!, quad[(i % 4) * 2 + 1]!];
+  const mid = (i: number): [number, number] => {
+    const [ax, ay] = pt(i);
+    const [bx, by] = pt(i + 1);
+    return [(ax + bx) / 2, (ay + by) / 2];
+  };
+  const toward = (m: [number, number], c: [number, number]): string =>
+    `${m[0] + KAPPA * (c[0] - m[0])} ${m[1] + KAPPA * (c[1] - m[1])}`;
+  let d = `M ${mid(0)[0]} ${mid(0)[1]}`;
+  for (let i = 0; i < 4; i++) {
+    // From the midpoint of edge i, about corner i + 1, to the midpoint of edge i + 1.
+    const corner = pt(i + 1);
+    const to = mid(i + 1);
+    d += ` C ${toward(mid(i), corner)} ${toward(to, corner)} ${to[0]} ${to[1]}`;
+  }
+  return `${d} Z`;
+}
+
+/** Half the current-frame tick's length, CSS px. */
+const PATH_TICK_HALF = 6;
+
+function AxisGuideLine({ guide }: { guide: ScreenAxisGuide }) {
+  return (
+    <line
+      x1={guide.a[0]}
+      y1={guide.a[1]}
+      x2={guide.b[0]}
+      y2={guide.b[1]}
+      stroke={AXIS_COLORS[guide.axis]}
+      strokeWidth={1}
+      strokeDasharray="6 5"
+      opacity={0.7}
+    />
+  );
+}
+
+/**
+ * One layer's motion path (gap 3): a 1px accent line through hollow key dots,
+ * the key under the playhead filled, a hold's step dashed, and a short tick
+ * across the line where the layer is now. A path outside the layer's lifetime
+ * draws dimmed, since the layer itself is not on screen.
+ */
+function MotionPathMark({
+  path,
+  hover,
+  selected,
+  handleHover,
+}: {
+  path: ScreenMotionPath;
+  hover: PathKeyRef | null;
+  selected: PathKeyRef | null;
+  handleHover: PathHandleRef | null;
+}) {
+  const picked = selected !== null && selected.layerId === path.layerId ? selected.keyId : null;
+  const pickedKey = picked === null ? undefined : path.keys.find((k) => k.id === picked);
+  return (
+    <g data-testid="motion-path" data-layer={path.layerId} opacity={path.dim ? 0.4 : 1}>
+      {path.runs.map((run, i) => (
+        <polyline
+          key={i}
+          points={flatPolyline(run.pts)}
+          fill="none"
+          stroke="var(--accent, #0099ff)"
+          strokeWidth={1}
+          strokeDasharray={run.jump ? "4 4" : undefined}
+        />
+      ))}
+      {path.tick === null ? null : (
+        <line
+          x1={path.tick.x - path.tick.nx * PATH_TICK_HALF}
+          y1={path.tick.y - path.tick.ny * PATH_TICK_HALF}
+          x2={path.tick.x + path.tick.nx * PATH_TICK_HALF}
+          y2={path.tick.y + path.tick.ny * PATH_TICK_HALF}
+          stroke="var(--ink-1, #f5f5f5)"
+          strokeWidth={1.5}
+        />
+      )}
+      {/* Off the bezier arm a dot has no handles, so nothing draws. */}
+      {pickedKey === undefined || (pickedKey.in === undefined && pickedKey.out === undefined) ? null : (
+        <PathKeyHandles
+          dot={pickedKey}
+          hot={handleHover !== null && handleHover.layerId === path.layerId && handleHover.keyId === pickedKey.id ? handleHover.part : null}
+        />
+      )}
+      {path.keys.map((key) => {
+        const hot =
+          (hover !== null && hover.layerId === path.layerId && hover.keyId === key.id) || key.id === picked;
+        return (
+          <circle
+            key={key.id}
+            data-testid="motion-path-key"
+            data-current={key.current ? "" : undefined}
+            cx={key.x}
+            cy={key.y}
+            r={key.current ? 4.5 : hot ? 5 : 4}
+            fill={key.current ? "var(--accent, #0099ff)" : "var(--surface-panel, #111111)"}
+            stroke={key.current || hot ? "var(--ink-1, #f5f5f5)" : "var(--accent, #0099ff)"}
+            strokeWidth={hot ? 2 : 1.5}
+          />
+        );
+      })}
+    </g>
+  );
+}
+
+/** The selected dot's Bezier handles (schema v40), in the spline editor's
+ *  look. A tip on its dot (a corner) is not drawn: the dot is what a press
+ *  there grabs, and `motionPathHandleAt` skips it by the same distance. */
+function PathKeyHandles({ dot, hot }: { dot: ScreenPathKey; hot: "in" | "out" | null }) {
+  return (
+    <g data-testid="motion-path-handles">
+      {(["in", "out"] as const).map((part) => {
+        const tip = dot[part];
+        if (tip === undefined || Math.hypot(tip.x - dot.x, tip.y - dot.y) < PATH_HANDLE_MIN_PX) return null;
+        return (
+          <g key={part} data-testid={`motion-path-handle-${part}`}>
+            <line
+              x1={dot.x}
+              y1={dot.y}
+              x2={tip.x}
+              y2={tip.y}
+              stroke="var(--accent, #0099ff)"
+              strokeWidth={1}
+              opacity={0.64}
+            />
+            <SplineHandle at={[tip.x, tip.y]} selected={hot === part} />
+          </g>
+        );
+      })}
+    </g>
+  );
+}
+
 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} />
+      <polygon points={points} fill="none" stroke="var(--accent, #0099ff)" 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. */}
@@ -904,8 +1563,8 @@ function SelectionQuad({ quad, handles }: { quad: ScreenQuad; handles?: boolean
                 y={y - 3.5}
                 width={7}
                 height={7}
-                fill="var(--panel, #1c1c20)"
-                stroke="var(--accent, #3b82f6)"
+                fill="var(--surface-panel, #111111)"
+                stroke="var(--accent, #0099ff)"
                 strokeWidth={1.5}
               />
             );
@@ -934,7 +1593,7 @@ function UnionBox({ quad }: { quad: ScreenQuad }) {
       <polygon
         points={pointsOf(quad)}
         fill="none"
-        stroke="var(--accent, #3b82f6)"
+        stroke="var(--accent, #0099ff)"
         strokeWidth={1}
         strokeDasharray="4 3"
       />
@@ -947,8 +1606,8 @@ function UnionBox({ quad }: { quad: ScreenQuad }) {
             y={y - 3.5}
             width={7}
             height={7}
-            fill="var(--panel, #1c1c20)"
-            stroke="var(--accent, #3b82f6)"
+            fill="var(--surface-panel, #111111)"
+            stroke="var(--accent, #0099ff)"
             strokeWidth={1.5}
           />
         );
@@ -957,6 +1616,206 @@ function UnionBox({ quad }: { quad: ScreenQuad }) {
   );
 }
 
+/** The comment pins on the frame, with what a pin click calls. */
+export interface CommentOverlay {
+  pins: readonly ShotBoardPin[];
+  onPin: (threadId: string) => void;
+}
+
+/** A pin's outline (S5): a 28px teardrop, radii 14/14/14/3, the square
+ *  corner bottom-left, sitting ON the point it marks. */
+const PIN_PATH = "M0 -14 A14 14 0 0 1 14 -28 A14 14 0 0 1 28 -14 A14 14 0 0 1 14 0 H3 A3 3 0 0 1 0 -3 Z";
+
+/** S5's ring around the open Studio pin's layer: dashed, 4px out. */
+const PIN_LAYER_OFFSET = 4;
+
+/** `quad` grown by `d` px on every side: each edge pushed out along its
+ *  normal, corners where the pushed edges meet. Right for a rotated or
+ *  skewed layer, which an axis box is not. */
+export function outsetQuad(quad: ScreenQuad, d: number): ScreenQuad {
+  const pts = [0, 1, 2, 3].map((i) => [quad[i * 2]!, quad[i * 2 + 1]!] as const);
+  let area = 0;
+  for (let i = 0; i < 4; i++) {
+    const [x0, y0] = pts[i]!;
+    const [x1, y1] = pts[(i + 1) % 4]!;
+    area += x0 * y1 - x1 * y0;
+  }
+  const side = area >= 0 ? 1 : -1;
+  const normal = (a: readonly [number, number], b: readonly [number, number]): [number, number] => {
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+    const len = Math.hypot(dx, dy) || 1;
+    return [(dy / len) * side, (-dx / len) * side];
+  };
+  const out: number[] = [];
+  for (let i = 0; i < 4; i++) {
+    const prev = pts[(i + 3) % 4]!;
+    const here = pts[i]!;
+    const next = pts[(i + 1) % 4]!;
+    const n1 = normal(prev, here);
+    const n2 = normal(here, next);
+    const k = d / Math.max(0.2, 1 + n1[0] * n2[0] + n1[1] * n2[1]);
+    out.push(here[0] + (n1[0] + n2[0]) * k, here[1] + (n1[1] + n2[1]) * k);
+  }
+  return out as unknown as ScreenQuad;
+}
+
+/** The label chip's text size and the room it takes, CSS px (Paper SB6:
+ *  10/14 mono on the accent, padding 1 / 5). */
+const GUIDE_CHIP_FONT = 10;
+const GUIDE_CHIP_H = 16;
+const GUIDE_CHIP_PAD = 5;
+/** A monospace glyph's advance at that size, to size a chip without
+ *  measuring text. */
+const GUIDE_CHIP_ADVANCE = 6.1;
+
+/** A label chip's width for `label`: mono advance plus padding. */
+export function guideChipWidth(label: string): number {
+  return Math.ceil(label.length * GUIDE_CHIP_ADVANCE) + GUIDE_CHIP_PAD * 2;
+}
+
+function GuideChip({ x, y, label }: { x: number; y: number; label: string }) {
+  return (
+    <g transform={`translate(${x} ${y})`}>
+      <rect width={guideChipWidth(label)} height={GUIDE_CHIP_H} rx={3} fill="var(--accent, #0099ff)" />
+      <text
+        x={GUIDE_CHIP_PAD}
+        y={GUIDE_CHIP_H / 2}
+        dominantBaseline="central"
+        fill="var(--on-accent, #ffffff)"
+        fontFamily="var(--font-numeric, ui-monospace, monospace)"
+        fontSize={GUIDE_CHIP_FONT}
+      >
+        {label}
+      </text>
+    </g>
+  );
+}
+
+/**
+ * THE SKETCH GUIDE (bridge v47): each sketch item as a 1px dashed accent
+ * outline with its own corner, its label chip on the outline's top edge, and
+ * each arrow as a dashed line with a head. Paint only.
+ */
+function SketchGuideOverlay({ guide }: { guide: ScreenSketchGuide }) {
+  return (
+    <g data-testid="sketch-guide" pointerEvents="none">
+      {guide.rects.map((r, i) => (
+        <g key={`r-${i}`}>
+          <rect
+            x={r.x}
+            y={r.y}
+            width={r.width}
+            height={r.height}
+            rx={r.radius}
+            fill="none"
+            stroke="var(--accent, #0099ff)"
+            strokeWidth={1}
+            strokeDasharray="6 4"
+          />
+          {r.label === undefined ? null : <GuideChip x={r.x} y={r.y - GUIDE_CHIP_H - 2} label={r.label} />}
+        </g>
+      ))}
+      {guide.arrows.map((a, i) => {
+        const len = Math.hypot(a.x2 - a.x1, a.y2 - a.y1) || 1;
+        const ux = (a.x2 - a.x1) / len;
+        const uy = (a.y2 - a.y1) / len;
+        const head = `${a.x2},${a.y2} ${a.x2 - ux * 8 - uy * 4},${a.y2 - uy * 8 + ux * 4} ${a.x2 - ux * 8 + uy * 4},${a.y2 - uy * 8 - ux * 4}`;
+        return (
+          <g key={`a-${i}`}>
+            <line x1={a.x1} y1={a.y1} x2={a.x2} y2={a.y2} stroke="var(--accent, #0099ff)" strokeWidth={1} strokeDasharray="6 4" />
+            <polygon points={head} fill="var(--accent, #0099ff)" />
+            {a.label === undefined ? null : (
+              <GuideChip x={(a.x1 + a.x2) / 2 - guideChipWidth(a.label) / 2} y={(a.y1 + a.y2) / 2 - GUIDE_CHIP_H - 4} label={a.label} />
+            )}
+          </g>
+        );
+      })}
+    </g>
+  );
+}
+
+/** One comment pin (bridge v42). The one thing on the frame's comment layer
+ *  that takes the pointer: the press is consumed, like the pilot badge's
+ *  eject, so it opens the thread and never reaches a pick under it. */
+function CommentPin({ pin, x, y, onPin }: { pin: ShotBoardPin; x: number; y: number; onPin: (threadId: string) => void }) {
+  return (
+    <g
+      data-testid="comment-pin"
+      data-thread={pin.threadId}
+      role="button"
+      aria-label={pin.label}
+      transform={`translate(${x} ${y})`}
+      pointerEvents="auto"
+      style={{ cursor: "pointer" }}
+      onPointerDown={(e) => {
+        e.stopPropagation();
+        e.preventDefault();
+        onPin(pin.threadId);
+      }}
+    >
+      <title>{pin.label}</title>
+      {pin.active ? (
+        <path d={PIN_PATH} fill="none" stroke="var(--accent, #0099ff)" strokeOpacity={0.35} strokeWidth={12} />
+      ) : null}
+      {/* S5: the accent on a 2px white border, so a pin never reads white
+          on a white picture. */}
+      <path d={PIN_PATH} fill="var(--accent, #0099ff)" stroke="#ffffff" strokeWidth={2} />
+      <text
+        x={14}
+        y={-9.5}
+        textAnchor="middle"
+        fill="var(--on-accent, #ffffff)"
+        fontFamily="var(--font-sans, system-ui)"
+        fontSize={12}
+        fontWeight={600}
+      >
+        {pin.initials}
+      </text>
+    </g>
+  );
+}
+
+/**
+ * The Studio's comment layer over the camera frame (bridge v45): the open
+ * pin's layer ringed dashed, and each pin at its `u, v` of the frame rect.
+ * ALL PAINT but the pins: the root takes no pointer events and only a pin
+ * opts back in, so every other click still lands on the layer under it.
+ */
+function CommentPinsOverlay({
+  comments,
+  pinLayer,
+  frame,
+}: {
+  comments: CommentOverlay;
+  pinLayer: ScreenQuad | null;
+  frame: OverlayProps["frame"];
+}) {
+  return (
+    <g data-testid="comment-pins" pointerEvents="none">
+      {pinLayer === null ? null : (
+        <polygon
+          data-testid="studio-pin-layer"
+          points={pointsOf(outsetQuad(pinLayer, PIN_LAYER_OFFSET))}
+          fill="none"
+          stroke="var(--accent, #0099ff)"
+          strokeWidth={1.5}
+          strokeDasharray="4 3"
+        />
+      )}
+      {comments.pins.map((pin) => (
+        <CommentPin
+          key={pin.threadId}
+          pin={pin}
+          x={frame.x + pin.u * frame.width}
+          y={frame.y + pin.v * frame.height}
+          onPin={comments.onPin}
+        />
+      ))}
+    </g>
+  );
+}
+
 /**
  * The path as it is being drawn, through THE SAME PRINTER the committed layer
  * uses.
@@ -980,7 +1839,7 @@ function PenPreview({ pen }: { pen: ScreenPen }) {
   return (
     <g pointerEvents="none">
       {points.length >= 2 ? (
-        <path d={pathToD({ points: [...points], closed: pen.closed })} fill="none" stroke="var(--accent, #3b82f6)" strokeWidth={1.5} />
+        <path d={pathToD({ points: [...points], closed: pen.closed })} fill="none" stroke="var(--accent, #0099ff)" 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. */}
@@ -988,7 +1847,7 @@ function PenPreview({ pen }: { pen: ScreenPen }) {
         <path
           d={pathToD({ points: [last, { p: [cursor[0], cursor[1]] }], closed: false })}
           fill="none"
-          stroke="var(--accent, #3b82f6)"
+          stroke="var(--accent, #0099ff)"
           strokeWidth={1}
           strokeDasharray="4 3"
           opacity={0.7}
@@ -998,10 +1857,10 @@ function PenPreview({ pen }: { pen: ScreenPen }) {
       {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} />
+            <line x1={p.p[0]} y1={p.p[1]} x2={p.out[0]} y2={p.out[1]} stroke="var(--accent, #0099ff)" 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} />
+            <line x1={p.p[0]} y1={p.p[1]} x2={p.in[0]} y2={p.in[1]} stroke="var(--accent, #0099ff)" strokeWidth={1} opacity={0.6} />
           )}
         </g>
       ))}
@@ -1013,8 +1872,8 @@ function PenPreview({ pen }: { pen: ScreenPen }) {
           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)"
+          fill={i === 0 && pen.closeHot ? "var(--accent, #0099ff)" : "var(--surface-panel, #111111)"}
+          stroke="var(--accent, #0099ff)"
           strokeWidth={1.5}
         />
       ))}
@@ -1022,6 +1881,100 @@ function PenPreview({ pen }: { pen: ScreenPen }) {
   );
 }
 
+function SplinePreview({ spline }: { spline: ScreenSpline }) {
+  const last = spline.points[spline.points.length - 1];
+  return (
+    <g pointerEvents="none">
+      {spline.line.length >= 2 ? (
+        <polyline
+          points={spline.line.map((point) => `${point[0]},${point[1]}`).join(" ")}
+          fill="none"
+          stroke="var(--accent, #0099ff)"
+          strokeWidth={1.5}
+          strokeLinejoin="round"
+        />
+      ) : null}
+      {!spline.editing && last !== undefined && spline.cursor !== null && !spline.closed ? (
+        <line
+          x1={last.p[0]}
+          y1={last.p[1]}
+          x2={spline.cursor[0]}
+          y2={spline.cursor[1]}
+          stroke="var(--accent, #0099ff)"
+          strokeWidth={1}
+          strokeDasharray="4 4"
+          opacity={0.72}
+        />
+      ) : null}
+      {spline.points.map((point) => (
+        <g key={`arms-${point.id}`}>
+          {point.in === undefined ? null : (
+            <line
+              x1={point.p[0]}
+              y1={point.p[1]}
+              x2={point.in[0]}
+              y2={point.in[1]}
+              stroke="var(--accent, #0099ff)"
+              strokeWidth={1}
+              opacity={0.64}
+            />
+          )}
+          {point.out === undefined ? null : (
+            <line
+              x1={point.p[0]}
+              y1={point.p[1]}
+              x2={point.out[0]}
+              y2={point.out[1]}
+              stroke="var(--accent, #0099ff)"
+              strokeWidth={1}
+              opacity={0.64}
+            />
+          )}
+          {point.in === undefined ? null : <SplineHandle at={point.in} selected={point.selected} />}
+          {point.out === undefined ? null : <SplineHandle at={point.out} selected={point.selected} />}
+        </g>
+      ))}
+      {spline.points.map((point, index) => (
+        <circle
+          key={point.id}
+          cx={point.p[0]}
+          cy={point.p[1]}
+          r={!spline.editing && index === 0 && spline.closeHot ? 5 : point.selected ? 4 : 3.5}
+          fill={
+            (!spline.editing && index === 0 && spline.closeHot) || point.selected
+              ? "var(--accent, #0099ff)"
+              : "var(--surface-panel, #111111)"
+          }
+          stroke="var(--accent, #0099ff)"
+          strokeWidth={1.5}
+        />
+      ))}
+    </g>
+  );
+}
+
+function flatPolyline(points: readonly number[]): string {
+  const out: string[] = [];
+  for (let index = 0; index + 1 < points.length; index += 2) {
+    out.push(`${points[index]},${points[index + 1]}`);
+  }
+  return out.join(" ");
+}
+
+function SplineHandle({ at, selected }: { at: readonly [number, number]; selected: boolean }) {
+  return (
+    <rect
+      x={at[0] - 3}
+      y={at[1] - 3}
+      width={6}
+      height={6}
+      fill={selected ? "var(--accent, #0099ff)" : "var(--surface-panel, #111111)"}
+      stroke="var(--accent, #0099ff)"
+      strokeWidth={1.25}
+    />
+  );
+}
+
 function Marquee({ rect }: { rect: ScreenMarquee }) {
   const x = Math.min(rect.x0, rect.x1);
   const y = Math.min(rect.y0, rect.y1);
@@ -1031,9 +1984,9 @@ function Marquee({ rect }: { rect: ScreenMarquee }) {
       y={y}
       width={Math.abs(rect.x1 - rect.x0)}
       height={Math.abs(rect.y1 - rect.y0)}
-      fill="var(--accent, #3b82f6)"
+      fill="var(--accent, #0099ff)"
       fillOpacity={0.12}
-      stroke="var(--accent, #3b82f6)"
+      stroke="var(--accent, #0099ff)"
       strokeWidth={1}
     />
   );