@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/bridgeClient.ts

@@ -6,76 +6,269 @@
 // `iframe.contentWindow.__shotStudio` on load and must never observe a
 // rendered-but-bridgeless stage; if the handle lived in a component it could
 // only appear after the first commit, and the poll would race it.
-import { clearRasterCache } from "@dailies-studio/shot";
-import { markPerf } from "./PerfHud.js";
-import type { Doc3D, Scene3D } from "@dailies-studio/shot/doc";
+import { clearLayerMaterialPool, clearPlaneCache, clearRasterCache, resetRasterPressure } from "@dailies-studio/shot";
+import type { CoverageProbe, ShotPresentedFrame } from "@dailies-studio/shot";
+import { createShotClock, setStagePhase } from "@dailies-studio/shot/doc";
+import type { ShotClock } from "@dailies-studio/shot/doc";
+import {
+  describePieceFailure,
+  docDurationFrames,
+  instanceComponentIdsOf,
+  instanceModuleOf,
+  masterToSceneCached,
+  pieceFailuresAt,
+  pieceLayerLabel,
+  posterFrame,
+  recordStageError,
+  sceneWindows,
+  sliceShotToScene,
+} from "@dailies-studio/shot/doc";
+import type { StageErrorSource, StageHealthSnapshot, StageRendered, StageRuntimeError } from "@dailies-studio/shot/doc";
+import { stageReadiness } from "@dailies-studio/runtime";
+import { PERF_HUD_ENABLED, markPerf } from "./PerfHud.js";
+import { stageDensity } from "./adaptivePresentation.js";
+import { RenderScaleController } from "./renderScaleController.js";
+import { StagePerformanceTelemetry } from "./stagePerformanceTelemetry.js";
+import { createShotStageExporter } from "./tier1Export.js";
+import type { ShotStageExporter } from "./tier1Export.js";
+import type { CameraGate, Doc3D, Scene3D } from "@dailies-studio/shot/doc";
 import type {
+  EditorChrome,
+  MaterialPreviewTarget,
+  NodePreviewBatch,
+  NodePreviewRequest,
   ShadingMode,
+  ShotBoardPin,
   ShotBridgeHandlers,
+  ShotComponentContext,
+  ShotPeerSelection,
+  ShotPreparePace,
+  ShotPreparePlaybackResult,
+  ShotPreparePlaybackYield,
+  ShotPreparedOutcome,
   ShotScreenQuad,
+  ShotSketchGuide,
+  ShotMotionPreview,
+  ShotSketchGuideArrow,
+  ShotSketchGuideRect,
+  ShotStudioComments,
+  ShotStudioPin,
   ShotStageBridge,
   ShotTool,
   ShotView,
+  SplineBasis,
+  SplineEditContext,
   SnapGuide,
   StageInset,
   StageLayout,
   StagePane,
+  StagePieceFailure,
   WorkingView,
+  WorkPlaneTarget,
+} from "../bridgeTypes.js";
+import {
+  MAX_LOOP_FRAMES,
+  MAX_NODE_PREVIEWS,
+  MAX_SKETCH_GUIDE_SHAPES,
+  SHOT_BRIDGE_VERSION,
+  componentContextSubject,
+  isPlaybackResolution,
+  validPreviewProps,
 } from "../bridgeTypes.js";
-import { SHOT_BRIDGE_VERSION } from "../bridgeTypes.js";
 import { clampSplitRatio } from "./panes.js";
 import { clampShading } from "./shading.js";
+import { TOOL_SPECS } from "../tools.js";
 import { INITIAL_WORKING_VIEW } from "./workingView.js";
+import { createFontPreviewFaces, fontPreviewDoc, sanitizeFontPreview } from "./fontPreview.js";
+import { motionPreviewDoc, sanitizeMotionPreview } from "./motionPreview.js";
+import type { StageFontPreview } from "./fontPreview.js";
+import type { FontPlatform } from "@dailies-studio/shot";
 
 export interface StageClientState {
   /** A chrome has registered its handlers. Nothing renders before this. */
   connected: boolean;
   doc: Doc3D | null;
-  /** MASTER frame. */
+  /** The saved revision `doc` is (v34 `loadDoc`), or null for an unsaved edit
+   *  or a host that did not say. Stamped on a piece failure first seen while
+   *  this document is on stage; never read by anything that draws. */
+  docRev: string | null;
+  /**
+   * MASTER frame, for the one mode that renders it through React: a Tier-1
+   * export, whose commit stamps the marker the capture requires, written by
+   * the capture loop (`exportHost.seek`). Isolation and a component context
+   * are not that mode: isolation's head-on frame is held still for the
+   * subtree's whole life (`isolationAnchor`), and a component context's
+   * def-local frames ride the clock like the scene's. Everywhere else the
+   * transport publishes into `StageClient.clock` with its presentation token,
+   * and this field holds the frame of the last export commit: read
+   * `clock.get().frame` for the playhead.
+   */
   frame: number;
+  /** The scene under the playhead, or null off the timeline, with no
+   *  document, or under a component context. The coarse half of the playhead:
+   *  it moves at cuts, so the stage re-renders at cuts and not per frame. */
+  sceneId: string | null;
+  /** The chrome's transport is running. SCHEDULING ONLY — see the bridge's
+   *  `setPlaying`. It must never reach a cache key or a sampled value. */
+  playing: boolean;
   selection: readonly string[];
+  /** Other people's selections (bridge v43), sanitized on the way in. */
+  peerSelections: readonly ShotPeerSelection[];
   view: ShotView;
   /** Live only while a gesture is snapping. */
   guides: readonly SnapGuide[];
   tool: ShotTool;
+  /** Editor-only construction plane and spline point-mode subject. */
+  workPlane: WorkPlaneTarget;
+  splineBasis: SplineBasis;
+  splineEdit: SplineEditContext | null;
   /** How many panes are on screen. Pushed by the chrome; never derived here,
    *  so there is one owner of "what is the author looking at". */
   layout: StageLayout;
+  /** THE AUTHOR IS WATCHING: the picture, and nothing drawn over it. Pushed by
+   *  the chrome like the layout, and orthogonal to it: it does not replace
+   *  `layout`, it hides it (see `setVideo` in bridgeTypes and `watching` in
+   *  StageApp). */
+  video: boolean;
+  /** VIEW ONLY (bridge v41): the person may look but not edit, so the stage
+   *  draws no handles and starts no edit gesture. See `setReadOnly` in
+   *  bridgeTypes and `readOnly` in StageApp. */
+  readOnly: boolean;
+  /** THE BOARD IS WATCHING (bridge v30): the same no-furniture picture as
+   *  `video`, plus a derived fit into the chrome's hole. Separate from
+   *  `video` because the two are different author intents that happen to want
+   *  one picture; see `setStoryboardPreview` in bridgeTypes. */
+  storyboardPreview: boolean;
+  /** THE STUDIO'S COMMENT LAYER (bridge v45): every Studio pin, drawn on its
+   *  anchor's frame, and whether the tool is armed. Null when the chrome has
+   *  none. Sanitized on the way in; see `setStudioComments` in bridgeTypes. */
+  studioComments: ShotStudioComments | null;
+  /** THE SKETCH GUIDE (bridge v47): one storyboard sketch as plain shapes in
+   *  design px, or null. Sanitized on the way in; see `setSketchGuide`. */
+  sketchGuide: ShotSketchGuide | null;
+  /** THE FONT PREVIEW (bridge v50), sanitized, with the private family its
+   *  faces landed under (`face`), or null. Only the runtime's picture reads
+   *  it (`fontPreviewDoc` in StageApp); see `setFontPreview`. */
+  fontPreview: StageFontPreview | null;
+  /** THE MOTION PREVIEW (bridge v53), sanitized, or null. Only the runtime's
+   *  picture reads it (`motionPreviewDoc` in StageApp); see `setMotionPreview`. */
+  motionPreview: ShotMotionPreview | null;
+  /** The text layer the inline editor is open on (bridge v38), or null. */
+  textEdit: string | null;
   workingView: WorkingView;
-  /** "Camera follows this view" is armed. The stage brackets its orbit with the
-   *  framing gesture lane while it is, and draws the badge that says so. */
-  cameraFollowsView: boolean;
+  /** PILOTING (bridge v29): the Camera pane's navigation writes the shot
+   *  camera through the framing gesture lane, and the pane wears the badge
+   *  that says so. `pilotText` is the badge's words, composed by the chrome
+   *  (it knows what holds the camera); null means the plain badge. */
+  pilot: boolean;
+  pilotText: string | null;
+  /** What a camera write would do at the playhead (bridge v29), so the gizmo
+   *  can dim a held camera and the pointer lane can say why BEFORE a drag.
+   *  Null when no document is open. */
+  cameraGate: CameraGate | null;
   /** The isolated subtree's root layer id, or null for the whole scene. The
    *  stage derives the members, the camera and the dimming from the document
    *  it already has — see `setIsolation`. */
   isolation: string | null;
+  /** Mesh SURFACE whose material graph owns the working-pane interaction
+   * surface. The layer still renders; only scene-edit gestures are suppressed.
+   * `slot` names which of a model glTF materials the workspace is editing, or
+   * null for the layer-wide binding. */
+  materialPreview: MaterialPreviewTarget | null;
   /** Inside isolation, has the author taken the working camera? False means the
    *  derived orthographic head-on rig draws the pane; true means the ordinary
    *  orbit rig does. Meaningless while `isolation` is null. */
   isolationOrbit: boolean;
+  /**
+   * The master frame the isolated subtree is framed from: where the playhead
+   * stood when the author entered it, or pressed Home inside it. A new object
+   * on each of those and on nothing else, so it is the one key the stage's
+   * frozen head-on frame is derived on. Null while `isolation` is.
+   */
+  isolationAnchor: { frame: number } | null;
+  /** The component context (v14): render ONE definition standalone, def-local
+   *  clock, whole viewport. Null = the ordinary scene render. Mutually
+   *  exclusive with isolation — the chrome owns the mode and clears isolation
+   *  first. `zoom` scales the derived head-on frame; absent is 1. */
+  componentContext: ShotComponentContext | null;
   /** The working pane's shading. Workspace state, mirrored from the chrome. */
   shading: ShadingMode;
-  /** How far the chrome's floating panels reach into the stage, per side. Paint
-   *  only: the overlay lays its furniture inside it and `paneRects` ignores it
-   *  entirely. Zero until the chrome says otherwise. */
+  /** The working pane's grid floor (bridge v22). Workspace state too: how the
+   *  author looks at the scene, never something about the shot. */
+  grid: boolean;
+  /** Rulers and smart guides (bridge v44), workspace state on `grid`'s rule.
+   *  The playback resolution the same push carries (v52) goes to
+   *  `StageClient.renderScale` and not here: it moves nothing drawn paused,
+   *  so it re-renders nothing and ends no preparing pass. */
+  editorChrome: Pick<EditorChrome, "rulers" | "smartGuides">;
+  /** Motion paths for the selection (bridge v44), workspace state too. */
+  motionPaths: boolean;
+  /** How far the chrome's docked panels reach into the stage, per side. It
+   *  places what has to be SEEN — the overlay's furniture, the derived head-on
+   *  framing, the camera pane's fit, and where the split seam falls — and moves
+   *  neither the scissor nor the hit test: `paneRects` takes it for the seam
+   *  alone and still returns rects that partition the whole viewport. See
+   *  `setStageInset`. Zero until the chrome says otherwise. */
   inset: StageInset;
+  /** A Tier-1 export is running: StageApp renders the export framing (design
+   *  viewport, no view offset, dpr 1, no overlays) and the capture loop owns
+   *  `frame`. Chrome `seek`/`loadDoc` pushes are DEFERRED until this clears —
+   *  a mid-capture re-render would let the encoder stamp one frame's
+   *  timestamp on another frame's pixels. Null = normal editing. */
+  exporting: { scene?: string } | null;
+  /** THE FROZEN PICTURE (v51): the frame a preparing pass froze on screen,
+   *  from the freeze until it lifts, or null. While it stands, StageApp keeps
+   *  the overlays it drew for that frame and starts no transform on the
+   *  scene graph under it, which holds another frame. */
+  held: number | null;
+  /** A preparing pass is drawing its own frames under the freeze (v51). Set
+   *  by its first publication and cleared by an author seek, the restore, the
+   *  hand-over and a cancel. StageTools projects nothing while it is set, so
+   *  the furniture keeps the frozen frame's outlines. */
+  passDrawing: boolean;
 }
 
 const INITIAL: StageClientState = {
   connected: false,
   doc: null,
+  docRev: null,
   frame: 0,
+  sceneId: null,
+  playing: false,
   selection: [],
+  peerSelections: [],
   view: { zoom: 1, panX: 0, panY: 0 },
   guides: [],
   tool: "select",
+  workPlane: { kind: "xy" },
+  splineBasis: "bezier",
+  splineEdit: null,
   layout: { mode: "camera", splitRatio: 0.5 },
+  video: false,
+  readOnly: false,
+  storyboardPreview: false,
+  studioComments: null,
+  sketchGuide: null,
+  fontPreview: null,
+  motionPreview: null,
+  textEdit: null,
   workingView: INITIAL_WORKING_VIEW,
-  cameraFollowsView: false,
+  pilot: false,
+  pilotText: null,
+  cameraGate: null,
   isolation: null,
+  materialPreview: null,
   isolationOrbit: false,
+  isolationAnchor: null,
+  componentContext: null,
   shading: "solid",
+  grid: true,
+  editorChrome: { rulers: false, smartGuides: true },
+  motionPaths: true,
   inset: { top: 0, right: 0, bottom: 0, left: 0 },
+  exporting: null,
+  held: null,
+  passDrawing: false,
 };
 
 /** Finite and non-negative on every side. A boundary, like `clampSplitRatio`:
@@ -86,8 +279,168 @@ function clampInset(inset: StageInset): StageInset {
   return { top: one(inset.top), right: one(inset.right), bottom: one(inset.bottom), left: one(inset.left) };
 }
 
+function sanitizeWorkPlane(target: WorkPlaneTarget): WorkPlaneTarget {
+  if (target.kind === "selection") {
+    return target.layerId.length > 0 ? { kind: "selection", layerId: target.layerId } : { kind: "xy" };
+  }
+  return target.kind === "xy" || target.kind === "xz" || target.kind === "yz" || target.kind === "view"
+    ? { kind: target.kind }
+    : { kind: "xy" };
+}
+
+const HEX_COLOR_RE = /^#[0-9a-fA-F]{6}$/;
+
+/** At most this many peer outlines, and ids per peer: past that the outlines
+ *  are noise, and the stage projects every id each frame. */
+export const MAX_PEER_SELECTIONS = 16;
+export const MAX_PEER_IDS = 50;
+
+/** A boundary like `sanitizePins`: each name becomes a `<text>` and each
+ *  colour a `stroke`. A peer with no ids or no plain hex colour is dropped;
+ *  a name is cut to 60 characters. */
+export function sanitizePeerSelections(peers: unknown): ShotPeerSelection[] {
+  if (!Array.isArray(peers)) return [];
+  const out: ShotPeerSelection[] = [];
+  for (const peer of peers as unknown[]) {
+    if (out.length >= MAX_PEER_SELECTIONS) break;
+    if (typeof peer !== "object" || peer === null) continue;
+    const { ids, name, color } = peer as Record<string, unknown>;
+    if (!Array.isArray(ids) || typeof color !== "string" || !HEX_COLOR_RE.test(color)) continue;
+    const kept = (ids as unknown[]).filter((id): id is string => typeof id === "string" && id.length > 0).slice(0, MAX_PEER_IDS);
+    if (kept.length === 0) continue;
+    out.push({ ids: kept, name: typeof name === "string" ? name.slice(0, 60) : "", color });
+  }
+  return out;
+}
+
+/** Pins become positioned SVG with a label: a pin with no thread id or a
+ *  point off the frame is dropped, and a colour that is not plain hex falls
+ *  back to the accent rather than reaching a `fill` attribute. */
+function sanitizePins(pins: unknown): ShotBoardPin[] {
+  if (!Array.isArray(pins)) return [];
+  const unit = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n) && n >= 0 && n <= 1;
+  return pins.flatMap((pin: Partial<ShotBoardPin> | null) => {
+    if (pin === null || typeof pin !== "object") return [];
+    if (typeof pin.threadId !== "string" || pin.threadId.length === 0 || !unit(pin.u) || !unit(pin.v)) return [];
+    return [
+      {
+        threadId: pin.threadId,
+        u: pin.u,
+        v: pin.v,
+        initials: typeof pin.initials === "string" ? pin.initials.slice(0, 2) : "",
+        color: typeof pin.color === "string" && HEX_COLOR_RE.test(pin.color) ? pin.color : "#0099FF",
+        active: pin.active === true,
+        label: typeof pin.label === "string" ? pin.label : "Comment",
+      },
+    ];
+  });
+}
+
+/** Studio pins (bridge v45) on `sanitizePins`'s rule, plus the anchor: a pin
+ *  whose anchor names no Shot, a frame that is not a whole frame at or after
+ *  the Shot's start, or a layer that is not an id or null, is dropped. */
+export function sanitizeStudioComments(comments: ShotStudioComments | null): ShotStudioComments | null {
+  if (comments === null || typeof comments !== "object") return null;
+  const raw: unknown[] = Array.isArray(comments.pins) ? comments.pins : [];
+  const pins = raw.flatMap((pin): ShotStudioPin[] => {
+    if (pin === null || typeof pin !== "object") return [];
+    const { anchor, ...rest } = pin as Partial<ShotStudioPin>;
+    if (anchor === null || typeof anchor !== "object" || anchor.kind !== "studio") return [];
+    const { sceneId, frame, layerId } = anchor;
+    if (typeof sceneId !== "string" || sceneId.length === 0) return [];
+    if (!Number.isSafeInteger(frame) || frame < 0) return [];
+    if (layerId !== null && (typeof layerId !== "string" || layerId.length === 0)) return [];
+    const [board] = sanitizePins([{ ...rest, u: anchor.u, v: anchor.v }]);
+    if (board === undefined) return [];
+    const { u, v, ...face } = board;
+    return [{ ...face, anchor: { kind: "studio", sceneId, frame, layerId, u, v } }];
+  });
+  return { pins, armed: comments.armed === true };
+}
+
+/** A sketch guide (bridge v47) the overlay can draw: finite numbers, sides
+ *  above zero, labels as short plain strings, at most
+ *  `MAX_SKETCH_GUIDE_SHAPES` shapes. A shape that fails is dropped; a guide
+ *  with nothing left is null. */
+export function sanitizeSketchGuide(guide: ShotSketchGuide | null): ShotSketchGuide | null {
+  if (guide === null || typeof guide !== "object") return null;
+  const num = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n);
+  const pair = (p: unknown): p is [number, number] => Array.isArray(p) && p.length === 2 && num(p[0]) && num(p[1]);
+  const label = (l: unknown): { label?: string } => (typeof l === "string" && l.trim() !== "" ? { label: l.trim().slice(0, 80) } : {});
+  const rects = (Array.isArray(guide.rects) ? guide.rects : []).flatMap((r: Partial<ShotSketchGuideRect> | null): ShotSketchGuideRect[] => {
+    if (r === null || typeof r !== "object" || !pair(r.at) || !pair(r.size) || r.size[0] <= 0 || r.size[1] <= 0) return [];
+    return [{ at: [r.at[0], r.at[1]], size: [r.size[0], r.size[1]], ...(num(r.radius) && r.radius > 0 ? { radius: r.radius } : {}), ...label(r.label) }];
+  });
+  const arrows = (Array.isArray(guide.arrows) ? guide.arrows : []).flatMap((a: Partial<ShotSketchGuideArrow> | null): ShotSketchGuideArrow[] => {
+    if (a === null || typeof a !== "object" || !pair(a.from) || !pair(a.to)) return [];
+    return [{ from: [a.from[0], a.from[1]], to: [a.to[0], a.to[1]], ...label(a.label) }];
+  });
+  const kept = rects.slice(0, MAX_SKETCH_GUIDE_SHAPES);
+  const shapes = { rects: kept, arrows: arrows.slice(0, MAX_SKETCH_GUIDE_SHAPES - kept.length) };
+  return shapes.rects.length + shapes.arrows.length === 0 ? null : shapes;
+}
+
+/**
+ * A DERIVED head-on rig is drawing the working pane: an isolated subtree, or an
+ * open component definition.
+ *
+ * The stage's copy of the chrome store's `headOnOwnsPane`. Two copies because
+ * the two sides hold different state shapes, and no more than two: the one
+ * thing a third head-on mode must not have to do is find six spellings of this.
+ *
+ * `componentContext` is validated against the document wherever it is written
+ * (`setComponentContext`, `loadDoc`), so a non-null one always names a
+ * definition that exists and is therefore always drawing.
+ */
+export function headOnOwnsPane(state: StageClientState): boolean {
+  return (state.isolation !== null || state.componentContext !== null) && !state.isolationOrbit;
+}
+
 export interface StageClient {
   readonly bridge: ShotStageBridge;
+  /** The playhead as a STORE (shot's frameStore.ts). `bridge.seek` publishes
+   *  every accepted frame here; `ShotRuntime` subscribes to it and the stage's
+   *  frame loops read it. The one live answer to "what frame is it". */
+  readonly clock: ShotClock;
+  /** Shared by the always-on playback quality policy and, under `?perf=1`,
+   *  the opt-in diagnostics. */
+  readonly performanceTelemetry: StagePerformanceTelemetry;
+  /** The playback render scale (renderScaleController.ts): StageApp hands it
+   *  to the runtime as `presentationScale` and feeds it the GPU timer's
+   *  frames; the client feeds it the frames the transport presented (the
+   *  telemetry's `subscribePresented`), tells it the transport, the
+   *  document's rate, another Project and the Preferences mode, and reports
+   *  what it holds (v52). */
+  readonly renderScale: RenderScaleController;
+  /** One runtime presentation reached the GL canvas. This is the single
+   * stage-local fan-out for telemetry and an armed Tier-1 framebuffer
+   * snapshot; callers must invoke it synchronously from onPresented.
+   * `drawnPlaying` is the `playing` the runtime was rendered with for this
+   * draw: a flag flip reaches the runtime a commit after it is set here.
+   * `drawnForExport` is whether that render was in export framing: only such
+   * a draw may resolve an armed capture (see `present` below). */
+  present(info: ShotPresentedFrame, document: Doc3D | null, drawnPlaying?: boolean, drawnForExport?: boolean): void;
+  /** A presentation of the WHOLE picture for `health()` (v35): StageApp calls
+   *  it from every presentation once the placed components' modules are
+   *  installed, `epoch` being the module epoch they were imported under
+   *  (hosted), paused or playing, with no telemetry, capture or
+   *  preparing-pass work. Ignored while other work above the runtime is
+   *  still outstanding (the capture gate's own question), and never recorded
+   *  for a preparing pass's own frames (v51), which are not the author's.
+   *
+   *  It also closes the READINESS LATCH (v51): a whole presentation of the
+   *  open subject (`drawn.subject`) means this renderer owes it nothing more
+   *  (`onStageBusy`). And one the transport drew in the playing presentation
+   *  (`drawn.playing`) joins `takePlayed()`. Without `drawn`, the subject is
+   *  the open one whenever `document` is the open document, drawn paused. */
+  noteDrawn(info: ShotPresentedFrame, document: Doc3D | null, epoch?: number | null, drawn?: StageDrawn): void;
+  /** The project's modules hot-updated under this stage (Vite's
+   *  `vite:afterUpdate`, locally): the code it runs is now that update's.
+   *  `checked` is each placed component's module (`/src/X.tsx`) the update
+   *  touched, with null when it replaced cleanly and the failure when it did
+   *  not, which leaves the stage running the previous code. `health()` says
+   *  so as a component failure, and its `loadedAt` moves to now. */
+  noteHotUpdate(checked: ReadonlyMap<string, string | null>): void;
   getState(): StageClientState;
   subscribe(listener: () => void): () => void;
   /** The chrome's handlers, or null before connect. The stage calls up through
@@ -98,64 +451,1444 @@ export interface StageClient {
   setQuadSource(source: ((pane: StagePane) => readonly ShotScreenQuad[] | null) | null): void;
   /** How the stage answers `fitView()`. Registered by the viewport. */
   setFitter(fit: (() => ShotView) | null): void;
+  /** How the stage answers `designPointAt()`. Registered by the viewport;
+   *  until then the bridge answers null and a drop lands centred. */
+  setDesignPointer(source: ((clientX: number, clientY: number) => readonly [number, number] | null) | null): void;
+  /** What the last instance-module resolution could not load. Registered by
+   *  StageApp; the Tier-1 export REFUSES rather than shipping the empty layers
+   *  those errors describe. */
+  setInstanceErrors(errors: readonly string[]): void;
+  /** Layers whose component RESOLVED and then threw while rendering — the
+   *  boundary contains the crash and the layer draws nothing, which an export
+   *  cannot tell from a layer meant to be empty. Same refusal, other cause. */
+  setInstanceCrashes(errors: readonly string[]): void;
+  /** A crash above the instance boundaries makes the whole stage unusable.
+   *  Latch it into the export refusal path and reject an armed capture now,
+   *  instead of leaving the controller to wait for its presentation timeout. */
+  setFatalError(message: string): void;
+  /** Known render-input or renderer failures whose fallback pixels are valid
+   *  for an interactive preview but not an exact export. Registered by the
+   *  stage and cleared when every reported source has recovered.
+   *  `compileBlocked` says one of them is a standing renderer compile failure
+   *  that stopped the draw (the runtime's `blocking`, never a list of failed
+   *  pipelines the rest draws around): the stage cannot present, so it owes
+   *  no presentation (v51). */
+  setRenderErrors(errors: readonly string[], compileBlocked?: boolean): void;
+  /** The pieces the runtime isolated (`ShotRuntimeProps.onPieceFailures`),
+   *  whole. Forwarded to the chrome (v34 `onPieceFailures`), and an exact
+   *  capture of any frame a listed piece belongs to REFUSES by name, since
+   *  that frame would be missing it: at arm, at the matching presentation,
+   *  and at once for a capture already armed. */
+  setPieceFailures(failures: readonly StagePieceFailure[]): void;
+  /** The list as last set. */
+  pieceFailures(): readonly StagePieceFailure[];
+  /** An error outside the piece log: an uncaught throw or rejection in this
+   *  document, the export worker's failure. Kept, deduplicated, for
+   *  `health()` (v35) and announced to the chrome (`onStageHealth`). */
+  recordError(source: StageErrorSource, message: string): void;
+  /** How the stage answers `requestNodePreviews`. Registered by the node
+   *  preview component once it mounts; until then the bridge answers null,
+   *  which is the same posture `setQuadSource` takes for selection shapes. */
+  setNodePreviewSource(
+    source: ((request: NodePreviewRequest) => Promise<NodePreviewBatch | null>) | null,
+  ): void;
+  /** How the stage answers `coverage()` (v36): the runtime's check of the
+   *  live Shot, handed over while one is mounted and null once none is. */
+  setCoverageProbe(probe: CoverageProbe | null): void;
   /** …and `fitWorkingView()`. A separate registration rather than one fitter
    *  returning both, because the two are computed from different things: the
    *  camera fit needs the PANE SIZE and the working fit needs the DOCUMENT. */
   setWorkingFitter(fit: (() => WorkingView) | null): void;
+  /** How `hoverLayer` reaches the overlay: an imperative sink registered by
+   *  StageApp, so a chrome hover never routes through `set()` (a stage commit
+   *  is a GL draw under frameloop="never"). */
+  setHoverSink(sink: ((layerId: string | null) => void) | null): void;
+  /** The stage area element, registered by StageApp — the Tier-1 exporter
+   *  finds the GL canvas and the commit marker through it. Stage-internal,
+   *  never on the bridge. */
+  setExportArea(el: HTMLElement | null): void;
+  /** The renderer-owned framebuffer canvas. Kept separate from the area marker
+   * so a component DOM portal cannot redirect capture by adding another canvas.
+   * The optional predicate is the renderer's already-created WebGL context,
+   * which closes the event-delivery gap around a lost context. */
+  setExportCanvas(
+    canvas: HTMLCanvasElement | null,
+    isContextLost?: () => boolean,
+  ): void;
   setDisposer(dispose: () => void): void;
+  /** A press or a wheel on the stage: aborts a dashboard poster capture that
+   *  holds the stage in export framing, and answers true when there was one,
+   *  so the input is swallowed rather than landing on a picture the author
+   *  never framed. */
+  yieldPoster(): boolean;
+  /** `passDrawing`, as a stable synchronous getter for StageTools' frame
+   *  loop, which runs inside a draw and cannot wait for a render (v51). */
+  passDrawing(): boolean;
+  /** Where the frozen picture and its shield mount (v51): StageApp's element
+   *  between the runtime's canvas host and the overlays, OUTSIDE the canvas's
+   *  parent, so `exportRefusal`'s portal scan never counts it. Stage-internal.
+   *  Null (the stage unmounting it) ends a pass and drops a freeze. */
+  registerFreezeHost(el: HTMLElement | null): void;
+  /** Whether a stage interaction is live (v51): a G/R/S modal, a pen or
+   *  spline draft, a marquee or a held pointer, a drag over the stage.
+   *  Registered by StageApp, which owns them. A preparing pass neither starts
+   *  nor goes on while one is (`yielded: "interaction"`); the inline text
+   *  editor and a spline edit are the client's own state and count too. */
+  setInteractionProbe(probe: (() => boolean) | null): void;
+  /** One of those interactions just began: a running preparing pass ends now
+   *  (`yielded: "interaction"`), not at its next hop. */
+  yieldToInteraction(): void;
+  /** The raster rung the stage draws at (the authored zoom, quantised:
+   *  `editorRasterScale`), the last part of
+   *  `preparationKey().base`. Registered by StageApp. */
+  setRasterScale(scale: number): void;
+}
+
+/** What one presentation drew, beside its document (v51 `noteDrawn`). */
+export interface StageDrawn {
+  /** Its subject (`stageSubject` of the render that drew it). */
+  subject: string | null;
+  /** Drawn in the playing presentation: the `playing` it rendered with. */
+  playing: boolean;
+}
+
+/**
+ * WHAT THE STAGE SHOWS (v51), the subject the readiness latch is kept for:
+ * the Project, a component context on it, or a material preview of one of its
+ * meshes. The document's id leads every one, so another Project is another
+ * subject even under the same code context. Null with no document.
+ */
+export function stageSubject(
+  doc: Doc3D | null,
+  context: ShotComponentContext | null,
+  preview: MaterialPreviewTarget | null,
+): string | null {
+  if (doc === null) return null;
+  if (preview !== null) return `${doc.id}\nmaterial:${preview.layerId}:${preview.slot}`;
+  return context === null ? doc.id : `${doc.id}\n${componentContextSubject(context)}`;
 }
 
-export function createStageClient(): StageClient {
+/**
+ * How long the preparing pass waits for one frame's presentation before it
+ * moves on. A cold frame can take over a second (a lit material's program is
+ * 100 to 300 ms on its own, and gemini's first cut measured 1.5 s); the
+ * deadline only has to stop one frame that never lands from holding Play.
+ */
+export const PREPARE_FRAME_DEADLINE_MS = 5_000;
+
+/** The longest an `"idle"` pace waits for the browser's idle time between two
+ *  frames (`requestIdleCallback`'s timeout). */
+export const IDLE_HOP_TIMEOUT_MS = 100;
+
+/** How long a frozen picture still stands once the author scrubs under it: a
+ *  scrub shows the frames it passes, a video frame still decoding or a Shot
+ *  still loading included, so it never waits out the 5 s backstop. */
+export const SCRUB_LIFT_MS = 150;
+
+/**
+ * Lay `bitmap` over `canvas`, in `host`, with a SHIELD over every overlay.
+ *
+ * The host is StageApp's, after the runtime's canvas host and before the
+ * overlays (`registerFreezeHost`): the copy covers the canvas and sits under
+ * the overlays, and `exportRefusal`'s portal scan, which counts the canvas's
+ * siblings, never sees it. The shield is transparent and stacks over the
+ * overlays. A press or a wheel on it is swallowed and calls `onPress`: the
+ * scene graph under it holds another frame, so a pick there would act on a
+ * picture the author is not looking at. A right press opens no browser menu,
+ * a move, a click and a double click stop there, so the hover and the
+ * double-click lanes stay still. It sets no cursor, so the area's shows
+ * through. Removing both is the caller's.
+ */
+function mountFreeze(
+  host: HTMLElement,
+  canvas: HTMLCanvasElement,
+  bitmap: ImageBitmap,
+  onPress: () => void,
+): { remove(): void } {
+  const frozen = document.createElement("canvas");
+  frozen.width = bitmap.width;
+  frozen.height = bitmap.height;
+  frozen.getContext("2d")?.drawImage(bitmap, 0, 0);
+  frozen.dataset["preparing"] = "frozen";
+  const box = canvas.getBoundingClientRect();
+  const origin = host.getBoundingClientRect();
+  Object.assign(frozen.style, {
+    position: "absolute",
+    left: `${box.left - origin.left}px`,
+    top: `${box.top - origin.top}px`,
+    width: `${box.width}px`,
+    height: `${box.height}px`,
+    pointerEvents: "none",
+  });
+  const shield = document.createElement("div");
+  shield.dataset["preparing"] = "shield";
+  Object.assign(shield.style, {
+    position: "absolute",
+    left: "0",
+    top: "0",
+    width: "100%",
+    height: "100%",
+    zIndex: "1",
+    pointerEvents: "auto",
+  });
+  const press = (event: Event): void => {
+    event.preventDefault();
+    event.stopPropagation();
+    onPress();
+  };
+  const stop = (event: Event): void => event.stopPropagation();
+  shield.addEventListener("pointerdown", press);
+  shield.addEventListener("wheel", press, { passive: false });
+  shield.addEventListener("contextmenu", (event) => event.preventDefault());
+  for (const type of ["pointermove", "click", "dblclick"]) shield.addEventListener(type, stop);
+  host.append(frozen, shield);
+  return {
+    remove() {
+      frozen.remove();
+      shield.remove();
+    },
+  };
+}
+
+/** The changes a preparing pass ends on (v51 `yielded: "push"`): a stage push
+ *  that changes the picture or the overlays drawn over it. */
+const PASS_ENDS_ON_PUSH: ReadonlySet<keyof StageClientState> = new Set<keyof StageClientState>([
+  "fontPreview",
+  "motionPreview",
+  "grid",
+  "editorChrome",
+  "motionPaths",
+  "peerSelections",
+  "studioComments",
+  "sketchGuide",
+  "readOnly",
+  "textEdit",
+  "isolation",
+  "materialPreview",
+  "componentContext",
+  "layout",
+  "video",
+  "view",
+  "inset",
+]);
+
+export function createStageClient(
+  opts: {
+    /** Test seam: the Tier-1 exporter factory. The real one spawns a module
+     *  Worker and reads a live GL canvas, neither of which exists in jsdom —
+     *  a fake here is what lets the deferral rules be pinned. */
+    createExporter?: typeof createShotStageExporter;
+    /** Test seam for deterministic request-to-present timing. */
+    performanceTelemetry?: StagePerformanceTelemetry;
+    /** Test seam for the close/export ordering of the three runtime caches. */
+    clearCaches?: () => void;
+    /** Test seam: where the font preview's faces load (v50). jsdom has no
+     *  CSS Font Loading API. */
+    fontPlatform?: () => FontPlatform | null;
+  } = {},
+): StageClient {
   let state: StageClientState = INITIAL;
+  const clock = createShotClock(0);
+  /** The last frame the transport accepted: the coalescing reference and
+   *  what a mode that renders the frame through React starts from. */
+  let lastFrame = 0;
+  /** The preparing pass in flight (`preparePlayback`), or null. `end` stops
+   *  it and gives the stage back (a reason, or null for a cancel); `pace` is
+   *  the chrome's, asked again here; `startFrame` is the author's frame it
+   *  gives back; `ended` settles once that frame has been published again. */
+  let preparing: {
+    end(reason: ShotPreparePlaybackYield | null): void;
+    pace(): ShotPreparePace;
+    startFrame: number;
+    ended: Promise<void>;
+  } | null = null;
+  /** Coverage checks running (v36): a pass under an `"idle"` pace would draw
+   *  other frames under them, so none starts meanwhile. */
+  let checking = 0;
+  /** The frozen picture over the canvas (v51), or null. It belongs to the
+   *  client and not to one pass: a pass that starts while it still stands
+   *  adopts it. */
+  let freeze: { remove(): void } | null = null;
+  /** The element it mounts in (`registerFreezeHost`). */
+  let freezeHost: HTMLElement | null = null;
+  /** The freeze's pending lift, or null: on the first complete presentation
+   *  of the frame the clock is on, from the publication `after` on (prepare
+   *  tokens count down), paused, or in either presentation once the
+   *  transport runs (`either`). `deadline` is the 5 s backstop, which an
+   *  author's scrub has shortened once `scrubbed` (`SCRUB_LIFT_MS`). */
+  let lift: { after: number; either: boolean; scrubbed: boolean; deadline: ReturnType<typeof setTimeout> } | null = null;
+  /** StageApp's answer to "is a stage interaction live" (v51). */
+  let interactionProbe: (() => boolean) | null = null;
+  const interactionLive = (): boolean =>
+    state.textEdit !== null || state.splineEdit !== null || interactionProbe?.() === true;
+  /** The transport is running: the chrome's `setPlaying`, which `playing`
+   *  is not while a pass holds the playing presentation. */
+  let transport = false;
+  /** What the transport drew whole in the playing presentation since it
+   *  started (`takePlayed`), as frames per document object: a loop draws the
+   *  same frames again, and a Set keeps them once. */
+  let played = new Map<Doc3D, Set<number>>();
+  /** What `preparationKey()` reads: the GPU epoch (a new renderer, the end of
+   *  export framing, a cache clear, a close: `gpuStateReplaced`), the raster
+   *  rung, and the module epoch and hot updates the placed code components
+   *  were imported under. */
+  let gpuEpoch = 0;
+  let rasterScale = 1;
+  let moduleEpoch: number | null = null;
+  let hotUpdates = 0;
+  /** The one MessageChannel a `"play"` pace hops through, made on first
+   *  use, and the steps waiting on it in order. */
+  let hopChannel: MessageChannel | null = null;
+  const hops: (() => void)[] = [];
+  /**
+   * The next frame, in a task of its own. Never `setTimeout(step, 0)`: a
+   * nested timer clamps to 4 ms. `"play"` hops through the message channel;
+   * `"idle"` waits for the browser's idle time, at most `IDLE_HOP_TIMEOUT_MS`
+   * (a browser without `requestIdleCallback` hops as `"play"` does).
+   */
+  const hop = (pace: ShotPreparePace, run: () => void): void => {
+    if (pace === "idle" && typeof requestIdleCallback === "function") {
+      requestIdleCallback(() => run(), { timeout: IDLE_HOP_TIMEOUT_MS });
+      return;
+    }
+    if (hopChannel === null) {
+      hopChannel = new MessageChannel();
+      hopChannel.port1.onmessage = () => hops.shift()?.();
+    }
+    hops.push(run);
+    hopChannel.port2.postMessage(null);
+  };
+  /** The runtime's coverage check of the live Shot, registered while one is
+   *  mounted (`ShotRuntimeProps.onCoverageProbe`). */
+  let coverageProbe: CoverageProbe | null = null;
+  /** The dashboard poster in flight (`capturePoster`), or null. It is
+   *  decoration: whatever the author starts on the stage aborts it, and
+   *  `settled` is the moment the stage has left its export framing. */
+  let poster: { abort: AbortController; settled: Promise<void> } | null = null;
+  /** The document whose poster capture FAILED (not yielded). It answers null
+   *  until the document changes, so the chrome may ask again freely: a
+   *  retry costs a comparison, never another minute in export framing. */
+  let posterFailedFor: Doc3D | null = null;
+  /** Abort the poster when it holds the stage in export framing, resolving
+   *  once the stage is back in the author's; null when there is none. */
+  const yieldPoster = (): Promise<void> | null => {
+    if (poster === null || state.exporting === null) return null;
+    poster.abort.abort();
+    return poster.settled;
+  };
+  /** Publications the preparing pass is waiting to see presented, by token. */
+  const presentWaiters = new Map<number, (drawnPlaying: boolean) => void>();
+  /** The preparing pass's own tokens: NEGATIVE, so they can never be one the
+   *  telemetry minted (it counts up from 1). */
+  let prepareTokens = 0;
+  const prepareToken = (): number => {
+    prepareTokens -= 1;
+    return prepareTokens;
+  };
+  const performanceTelemetry =
+    opts.performanceTelemetry ?? new StagePerformanceTelemetry({ rich: PERF_HUD_ENABLED });
+  const renderScale = new RenderScaleController();
+  /** The scene under a master frame, for `StageClientState.sceneId`. */
+  const sceneIdAt = (doc: Doc3D | null, frame: number): string | null =>
+    doc === null || state.componentContext !== null ? null : (masterToSceneCached(doc, frame)?.sceneId ?? null);
   const listeners = new Set<() => void>();
   let handlers: ShotBridgeHandlers | null = null;
   let quadSource: ((pane: StagePane) => readonly ShotScreenQuad[] | null) | null = null;
   let fitter: (() => ShotView) | null = null;
+  let designPointer: ((clientX: number, clientY: number) => readonly [number, number] | null) | null = null;
+  let nodePreviewSource:
+    | ((request: NodePreviewRequest) => Promise<NodePreviewBatch | null>)
+    | null = null;
   let workingFitter: (() => WorkingView) | null = null;
+  /** The chrome-hover lane's imperative sink, registered by StageApp. Null
+   *  before the stage mounts — a hover over a not-yet-connected stage is
+   *  nothing to draw on. */
+  let hoverSink: ((layerId: string | null) => void) | null = null;
   let dispose: (() => void) | null = null;
+  let exportArea: HTMLElement | null = null;
+  let exportCanvas: HTMLCanvasElement | null = null;
+  let exportContextLost = false;
+  let exportContextIsLost: (() => boolean) | null = null;
+  let removeExportCanvasListeners: (() => void) | null = null;
+  let exporter: ShotStageExporter | null = null;
+  /** Created on first use: the real one spawns a Worker to probe. */
+  const exporterOf = (): ShotStageExporter =>
+    (exporter ??= (opts.createExporter ?? createShotStageExporter)(exportHost, {
+      onWorkerError: (message) => recordError("export-worker", message),
+    }));
+  let pendingCapture: {
+    frame: number;
+    width: number;
+    height: number;
+    snapshotting: boolean;
+    snapshot: (canvas: HTMLCanvasElement) => Promise<ImageBitmap>;
+    resolve: (bitmap: ImageBitmap) => void;
+    reject: (error: unknown) => void;
+  } | null = null;
+  /** What the last instance-module resolution could not load; the Tier-1
+   *  export refuses while it is non-empty. */
+  let instanceErrors: string[] = [];
+  /** Contained render crashes, by the same rule. */
+  let instanceCrashes: string[] = [];
+  /** Placed components' modules whose last hot update failed, by module
+   *  path (`/src/X.tsx`): the stage still runs their previous code. */
+  const hotErrors = new Map<string, string>();
+  /** When the stage last took a hot update of the project's code (wall ms),
+   *  or null: `health().loadedAt` is the later of this and its load. */
+  let codeAt: number | null = null;
+  /** The hot-update failures of modules the document on stage places. */
+  const placedHotErrors = (): string[] => {
+    if (hotErrors.size === 0 || state.doc === null) return [];
+    const placed = new Set(instanceComponentIdsOf(state.doc).map((id) => `/${instanceModuleOf(id)}`));
+    return [...hotErrors].filter(([module]) => placed.has(module)).map(([, message]) => message);
+  };
+  /** Last-resort StageRootBoundary failure. The boundary cannot recover without
+   *  reloading the stage realm, so this remains terminal for this client. */
+  let fatalError: string | null = null;
+  /** Recoverable failures outside instance resolution. A preview may show a
+   *  fallback for these, but an accepted export must not silently bake it. */
+  let renderErrors: string[] = [];
+  /** The pieces the runtime isolated, as last reported. Scoped per FRAME at
+   *  the gate (`piecesAt`): a Shot warming ahead of its cut in the editor is
+   *  not in the frame being captured. */
+  let pieceFailures: readonly StagePieceFailure[] = [];
+  // ── HEALTH (v35) ─────────────────────────────────────────────────────
+  //
+  // What `health()` answers: everything above, the errors outside the piece
+  // log, and what was last PRESENTED (a complete picture, readiness clear),
+  // with the saved revision and module epoch it was drawn from. The chrome
+  // hears `onStageHealth` when any of it changes, never per frame: a
+  // presentation announces itself only when its document, revision or epoch
+  // differs from the last one's.
+  let stageErrors: StageRuntimeError[] = [];
+  let rendered: { -readonly [K in keyof StageRendered]: StageRendered[K] } | null = null;
+  /** The document object `rendered` was drawn from. */
+  let presentedDoc: Doc3D | null = null;
+  /** Each pushed document's saved revision, by object: a presentation may
+   *  still draw the document a newer push replaced. */
+  const revOfDoc = new WeakMap<Doc3D, string | null>();
+  /** Editor telemetry only, never read by anything that draws. */
+  const wallNow = (): number => Date.now();
+  /** What `health()` says was last presented: announced only when the
+   *  document, its revision or the module epoch moved, never per frame. */
+  function notePresented(info: ShotPresentedFrame, document: Doc3D | null, epoch: number | null): void {
+    if (document === null) return;
+    const rev = revOfDoc.get(document) ?? null;
+    const same = rendered !== null && presentedDoc === document && rendered.rev === rev && rendered.epoch === epoch;
+    presentedDoc = document;
+    if (same) {
+      rendered!.frame = info.frame;
+      rendered!.at = wallNow();
+      return;
+    }
+    rendered = { rev, docId: document.id, frame: info.frame, epoch, at: wallNow() };
+    notifyHealth();
+  }
+  function recordError(source: StageErrorSource, message: string): void {
+    stageErrors = recordStageError(stageErrors, source, message, state.docRev, wallNow());
+    notifyHealth();
+  }
+  function notifyHealth(): void {
+    try {
+      handlers?.onStageHealth?.();
+    } catch {
+      // A handler must never throw back into the stage (bridgeTypes).
+    }
+  }
+  /** The GPU state behind prepared frames was replaced (v51): a new
+   *  renderer, the end of export framing, a cache clear, a close. The
+   *  preparation base moves, and the chrome hears it (`onStageHealth`), so a
+   *  scheduler that had nothing left to prepare looks again. */
+  function gpuStateReplaced(): void {
+    gpuEpoch += 1;
+    notifyHealth();
+  }
+  /** Chrome pushes that landed mid-export, applied when it ends. `frame` also
+   *  remembers the pre-export playhead so a cancelled export puts the author
+   *  back where they were. */
+  const deferred: {
+    doc: Doc3D | null;
+    /** `doc`'s revision, from the same push. */
+    rev: string | null;
+    frame: number | null;
+    componentContext: ShotComponentContext | null;
+    closed: boolean;
+    clearCaches: boolean;
+    /** The latest isolation push, boxed so "isolate nothing" (null) is not
+     *  mistaken for "nothing was pushed". `orbit` is the camera mode the
+     *  chrome re-asserts right after it (`setIsolationOrbit`). */
+    isolation: { layerId: string | null; orbit: boolean } | null;
+  } = {
+    doc: null,
+    rev: null,
+    frame: null,
+    componentContext: null,
+    closed: false,
+    clearCaches: false,
+    isolation: null,
+  };
 
   function set(patch: Partial<StageClientState>): void {
-    let changed = false;
-    for (const key of Object.keys(patch) as (keyof StageClientState)[]) {
-      if (!Object.is(state[key], patch[key])) {
-        changed = true;
-        break;
+    const keys = Object.keys(patch) as (keyof StageClientState)[];
+    if (keys.every((key) => Object.is(state[key], patch[key]))) return;
+    const was = state;
+    state = { ...state, ...patch };
+    // THE SUBJECT, and the latch with it (v51): a new one is owed its first
+    // whole presentation on this renderer. An edit of the open Project is
+    // not a new subject: the latch is kept per subject, never per document
+    // object, or every keystroke would hold Play again.
+    if (state.doc !== was.doc || state.componentContext !== was.componentContext || state.materialPreview !== was.materialPreview) {
+      const next = stageSubject(state.doc, state.componentContext, state.materialPreview);
+      if (next !== subject) {
+        subject = next;
+        latch = null;
+        queueBusy();
+        // A FROZEN PICTURE OF ONE SUBJECT never stands for another, nor do
+        // the overlays held with it: the new subject's own progressive draw is
+        // the honest picture, and its first whole one, which the lift waits
+        // for, is exactly what a load withholds. In this patch, not a second.
+        if (freeze !== null) {
+          cancelLift();
+          freeze.remove();
+          freeze = null;
+          state = { ...state, held: null, passDrawing: false };
+        }
       }
     }
-    if (!changed) return;
-    state = { ...state, ...patch };
+    // THE PHASE THE RUNTIME READS (`stagePhase`), in this task: the hand-over
+    // clears `passDrawing` and publishes the start frame in one, and that
+    // draw is the transport's first picture, never a pass's.
+    setStagePhase(state.passDrawing ? "pass" : state.playing ? "transport" : "paused");
     for (const l of listeners) l();
+    // A PASS GIVES WAY (v51) to a stage interaction starting, and to a push
+    // that changes the picture or what is drawn over it. By value, because
+    // the chrome re-pushes some of these unchanged with every document push.
+    const pass = preparing;
+    if (pass === null) return;
+    const moved = (key: keyof StageClientState): boolean => JSON.stringify(was[key]) !== JSON.stringify(state[key]);
+    if (state.splineEdit !== null && moved("splineEdit")) pass.end("interaction");
+    else if (keys.some((key) => PASS_ENDS_ON_PUSH.has(key) && moved(key))) pass.end("push");
   }
 
+  /** The font preview's faces (v50): loaded outside every readiness claim and
+   *  every error report, and handed to the state once they land. */
+  const previewFaces = createFontPreviewFaces((face) => {
+    if (state.fontPreview !== null) set({ fontPreview: { ...state.fontPreview, face } });
+  }, opts.fontPlatform);
+  /** Whether the font preview changes what the runtime draws: one naming no
+   *  text layer of the open document changes nothing, so the coverage check
+   *  and the poster refuse nothing for it. */
+  const previewingFont = (): boolean =>
+    state.doc !== null && state.fontPreview !== null && fontPreviewDoc(state.doc, state.fontPreview) !== state.doc;
+  /** The same question for the motion preview (v53): a preset that lands no
+   *  key on the open document changes nothing. */
+  const previewingMotion = (): boolean =>
+    state.doc !== null && state.motionPreview !== null && motionPreviewDoc(state.doc, state.motionPreview) !== state.doc;
+
+  function validComponentContext(
+    ctx: ShotComponentContext | null,
+    doc: Doc3D | null,
+  ): ShotComponentContext | null {
+    if (ctx === null) return null;
+    const zoom = typeof ctx.zoom === "number" && ctx.zoom > 0 && Number.isFinite(ctx.zoom)
+      ? ctx.zoom
+      : 1;
+    // v45's preview fields, each omitted unless valid so a context without
+    // them stays the v44 object.
+    const look = {
+      ...(ctx.background === "dark" || ctx.background === "light" || ctx.background === "brand"
+        ? { background: ctx.background }
+        : {}),
+      ...(Number.isSafeInteger(ctx.loopFrames) && ctx.loopFrames! > 0 && ctx.loopFrames! <= MAX_LOOP_FRAMES
+        ? { loopFrames: ctx.loopFrames! }
+        : {}),
+    };
+    if ("code" in ctx) {
+      if (ctx.code.length === 0) return null;
+      // Rebuilt, not passed through, so junk fields a future chrome sends
+      // cannot ride into stage state; `props` survives only in validated form
+      // (v27) — a malformed key is dropped rather than blanking the preview.
+      const props = validPreviewProps(ctx.props);
+      return { code: ctx.code, zoom, ...(props === undefined ? {} : { props }), ...look };
+    }
+    if (doc?.components?.[ctx.def] === undefined) return null;
+    // Tried values (v46), validated like the code arm's. The Edit tab's bit
+    // (v48) only ever crosses as `true`.
+    const tried = validPreviewProps(ctx.props);
+    return {
+      def: ctx.def,
+      zoom,
+      ...(tried === undefined ? {} : { props: tried }),
+      ...look,
+      ...(ctx.edit === true ? { edit: true as const } : {}),
+    };
+  }
+
+  /** The listed pieces that belong to the picture at `frame`, in the frame
+   *  space the capture uses: a one-Shot export's frames are its slice's. */
+  function piecesAt(frame: number): StagePieceFailure[] {
+    if (pieceFailures.length === 0) return [];
+    const doc = state.doc;
+    if (doc === null) return [...pieceFailures];
+    const scope = state.exporting?.scene;
+    const drawn = scope === undefined ? doc : (sliceShotToScene(doc, scope) ?? doc);
+    return pieceFailuresAt(pieceFailures, drawn, frame);
+  }
+
+  /** The renderer's context is lost: its loss event fired, or the renderer
+   *  says so now. A renderer that cannot answer counts as lost: an exact
+   *  export cannot turn that uncertainty into accepted pixels. */
+  function contextLost(): boolean {
+    if (exportContextLost) return true;
+    if (exportContextIsLost === null) return false;
+    try {
+      return exportContextIsLost();
+    } catch {
+      return true;
+    }
+  }
+
+  /** `frame` is the capture's own; without one (a begin) the frame-scoped
+   *  refusals wait for the frame. */
+  function exportRefusal(frame?: number): Error | null {
+    if (fatalError !== null) {
+      return new Error(`export refused because the stage crashed: ${fatalError}`);
+    }
+    if (frame !== undefined) {
+      const broken = piecesAt(frame);
+      if (broken.length > 0) {
+        const first = broken[0]!;
+        return new Error(
+          `export refused: ${broken.length} piece(s) of frame ${frame} failed to render, so the frame ` +
+            `would be missing them: ${describePieceFailure(first, pieceLayerLabel(state.doc, first))}`,
+        );
+      }
+    }
+    if (contextLost()) {
+      return new Error(
+        "export refused because the ShotRuntime WebGL context is lost; " +
+          "reload the stage before exporting",
+      );
+    }
+    if (renderErrors.length > 0) {
+      return new Error(
+        `export refused: ${renderErrors.length} known render failure(s) would make ` +
+          `the accepted export incomplete or wrong: ${renderErrors[0]!}`,
+      );
+    }
+    const moduleErrors = [...instanceErrors, ...placedHotErrors()];
+    if (moduleErrors.length > 0) {
+      return new Error(
+        `export refused: ${moduleErrors.length} component module(s) failed to load, ` +
+          `so their layers would render empty or stale: ${moduleErrors[0]!}`,
+      );
+    }
+    if (instanceCrashes.length > 0) {
+      return new Error(
+        `export refused: ${instanceCrashes.length} component(s) crashed while rendering, ` +
+          `so their layers would render empty: ${instanceCrashes[0]!}`,
+      );
+    }
+    const canvasParent = exportCanvas?.parentElement ?? null;
+    const portal =
+      canvasParent === null
+        ? null
+        : [...canvasParent.children].find((child) => child !== exportCanvas) ?? null;
+    if (portal !== null) {
+      return new Error(
+        "export refused: component DOM output is mounted beside the ShotRuntime canvas, " +
+          "but browser export captures only the renderer framebuffer; use the Studio server render",
+      );
+    }
+    return null;
+  }
+
+  /** A refusal that arrives while a capture is armed cancels it at once, for
+   *  the frame that capture is for. */
+  function refuseArmedCapture(): void {
+    if (state.exporting === null) return;
+    const refusal = exportRefusal(pendingCapture?.frame);
+    if (refusal !== null) cancelPendingCapture(refusal);
+  }
+
+  function clearStageCaches(): void {
+    // The GPU state prepared frames stood on goes with the caches (v51).
+    gpuStateReplaced();
+    if (opts.clearCaches !== undefined) {
+      opts.clearCaches();
+      return;
+    }
+    clearRasterCache();
+    clearPlaneCache();
+    clearLayerMaterialPool();
+  }
+
+  function cancelPendingCapture(error: Error): void {
+    const pending = pendingCapture;
+    if (pending === null) return;
+    pendingCapture = null;
+    pending.reject(error);
+  }
+
+  function registerExportCanvas(
+    canvas: HTMLCanvasElement | null,
+    isContextLost?: () => boolean,
+  ): void {
+    removeExportCanvasListeners?.();
+    removeExportCanvasListeners = null;
+    exportCanvas = canvas;
+    exportContextLost = false;
+    exportContextIsLost = isContextLost ?? null;
+    if (canvas === null) return;
+    // A NEW RENDERER (v51): it owes the subject its first whole presentation,
+    // and nothing an older one prepared is resident on it.
+    latch = null;
+    gpuStateReplaced();
+    queueBusy();
+
+    const lost = (event: Event): void => {
+      // WebGL restores only when the loss event is cancelled, so preview may
+      // recover. Exact export stays terminal until a fresh renderer canvas
+      // mounts: ClockDriver's program watch belongs to the old context and a
+      // restored event alone does not prove those programs were recompiled.
+      event.preventDefault();
+      exportContextLost = true;
+      cancelPendingCapture(
+        new Error(
+          "export refused because the ShotRuntime WebGL context was lost during capture",
+        ),
+      );
+      // A lost context presents nothing, so nothing may wait on it (v51):
+      // not the hold, and not a pass, whose every frame would wait out its
+      // deadline. The chrome reads the loss from `health()` as the pass ends.
+      preparing?.end(null);
+      queueBusy();
+    };
+    // On a WebGPU-backed canvas this event simply never fires; the listener is
+    // the WebGL path's loss signal and is harmless to leave armed.
+    canvas.addEventListener("webglcontextlost", lost);
+    removeExportCanvasListeners = () => {
+      canvas.removeEventListener("webglcontextlost", lost);
+    };
+  }
+
+  /**
+   * THE CAPTURE GATE'S QUESTION: is any real work outstanding.
+   *
+   * `shot:draw` and `shot:repaint` are internal handoff claims that open and
+   * close inside a single presentation, so waiting on them is waiting on
+   * yourself. `shot:instances` is a real load (StageApp holds it across
+   * `resolveInstanceModules`), but the capture gate needs no claim for it:
+   * StageApp checks the resolved map's identity directly before it calls
+   * `present`, which is the stricter test. A paused video seek (`shot:seek`)
+   * holds every capture, because photographing a stale frame is the bug that
+   * claim exists to prevent.
+   */
+  const HANDOFF = new Set(["shot:draw", "shot:repaint", "shot:instances"]);
+  const externallyPending = (): boolean => stageReadiness.waitingOn().some((label) => !HANDOFF.has(label));
+
+  /**
+   * THE PLAYBACK HOLD'S QUESTION (v51): does this renderer still owe the open
+   * subject its first whole presentation.
+   *
+   * Not "is any load open", which the hold used to ask of the registry: then
+   * a preparing pass's own loads greyed Play, and the button lit on renderer
+   * creation, before any picture. A whole presentation (`noteDrawn`'s full
+   * path) of the subject closes the latch once, and loads arriving after it
+   * hold nothing. A paused video seek therefore holds the subject's FIRST
+   * whole presentation and never a later one, and Pause never re-arms it. A
+   * new subject, a new renderer or a new stage document owes one again.
+   *
+   * Released, so nothing waits for ever, while the stage cannot present at
+   * all: a crash, a lost context, a standing renderer compile failure. A
+   * standing fallback (a texture, an html, a font or a glyph failure) is not
+   * that: the stage still presents, so the latch closes.
+   */
+  let subject: string | null = null;
+  let latch: string | null = null;
+  let compileBlocked = false;
+  const presentationOwed = (): boolean =>
+    state.doc !== null && latch !== subject && fatalError === null && !compileBlocked && !contextLost();
+
+  /** What the chrome was last TOLD. Null before `connect`: a value computed
+   *  while nobody was listening was never sent, and must not suppress the
+   *  first real push. */
+  let sentBusy: boolean | null = null;
+  let busyQueued = false;
+  const publishBusy = (): void => {
+    if (handlers === null) return;
+    const busy = presentationOwed();
+    if (busy === sentBusy) return;
+    sentBusy = busy;
+    handlers.onStageBusy(busy);
+  };
+  /** COALESCED TO A MICROTASK and then deduped by value: one commit can move
+   *  the subject, the renderer and the errors together, and the chrome only
+   *  needs to know where that run landed. Never from inside a presentation:
+   *  the chrome's store write would put React between two draws. */
+  const queueBusy = (): void => {
+    if (busyQueued) return;
+    busyQueued = true;
+    queueMicrotask(() => {
+      busyQueued = false;
+      publishBusy();
+    });
+  };
+
+  /**
+   * ONE SECOND OF PRESENTATION, forwarded to the chrome.
+   *
+   * On a microtask for `publishBusy`'s reason: the window closes inside the
+   * runtime's `onPresented` call stack, and a chrome store write from there
+   * would put React rendering between a draw and the next one.
+   */
+  const unsubscribeWindow = performanceTelemetry.subscribeWindow((window) => {
+    const perSecond = 1000 / window.durationMs;
+    const report = {
+      presentedFps: window.presentedFrames * perSecond,
+      expectedFps: window.expectedFrames * perSecond,
+      droppedPublications: window.droppedPublications,
+      // The GPU's own time and the scale in force (v52): what the fps chip
+      // says while the picture renders below the display's density.
+      gpuMs: window.gpuP95Ms,
+      renderScale: renderScale.inForce(),
+    };
+    queueMicrotask(() => handlers?.onPerformance(report));
+  });
+  /** THE PLAYBACK RENDER SCALE'S DEADLINES (renderScaleController.ts): every
+   *  frame of the transport that reached the canvas, with its document frame,
+   *  timed by the clock read its request took in `publishFrame`, before it
+   *  was drawn. Inside the runtime's `onPresented` call stack, and a push
+   *  only. */
+  const unsubscribePresented = performanceTelemetry.subscribePresented((at, frame) => renderScale.presented(at, frame));
+
+  /**
+   * The transport's seek: publish `frame` to the clock and answer the token
+   * its presentation will echo, or null when nothing was published (an export
+   * owns the clock, or the frame is already the one on screen). `seek` and the
+   * preparing pass share it, so a prepared frame is drawn exactly as a played
+   * one is.
+   *
+   * The token is the telemetry's, which it mints only while the transport
+   * runs or the perf HUD is on. `tokenFor` supplies one otherwise, for a
+   * caller that has to know when THIS publication is presented.
+   */
+  const publishFrame = (frame: number, tokenFor?: () => number): number | null => {
+    // Mid-export the capture loop owns the clock — remember the ask and
+    // land on it when the export ends.
+    if (state.exporting !== null) {
+      deferred.frame = Math.round(frame);
+      return null;
+    }
+    // Integer frames over a rational fps is the engine's invariant, and this
+    // is the boundary a float could sneak through: a chrome that computed a
+    // frame from a pixel position would otherwise hand the studio clock a
+    // fractional one and break byte-identity against the export.
+    // THE PREVIEW LOOP (v45): inside a component context with a loop length,
+    // every frame wraps into it, so a transport that runs past the loop
+    // shows the loop again instead of a held last frame.
+    const loop = state.componentContext?.loopFrames;
+    const rounded = loop === undefined ? Math.round(frame) : ((Math.round(frame) % loop) + loop) % loop;
+    // REQUESTED here, PUBLISHED only if it actually changes the stage: a
+    // transport tick that resolves to the frame already on screen is a
+    // coalesced request, not a dropped one, and counting it as loss would
+    // degrade quality on any document slower than the display.
+    const request = performanceTelemetry.request(rounded);
+    if (lastFrame === rounded) {
+      performanceTelemetry.coalesceRequest(request);
+      return null;
+    }
+    lastFrame = rounded;
+    const token = performanceTelemetry.publish(request) ?? tokenFor?.() ?? null;
+    // ── THE FRAME IS A STORE WRITE, NOT A STATE WRITE ───────────────────
+    //
+    // The stage committed its whole tree per seek: react-dom's half of a
+    // played frame, measured at 1.6 to 3 ms, for a tree whose structure
+    // changes at cuts. Only the scene under the playhead is state now; the
+    // frame and its token go to the clock, which `ShotRuntime`'s driver
+    // subscribes to and the stage's frame loops read. A component context's
+    // def-local frames too, so a played definition commits no stage render
+    // per frame: the runtime's component mount reads them off the clock. The
+    // one mode that renders the frame through React, an export, never gets
+    // here: its capture loop writes the frame (`exportHost.seek`).
+    const sceneId = sceneIdAt(state.doc, rounded);
+    if (sceneId !== state.sceneId) set({ sceneId });
+    clock.set(rounded, token);
+    return token;
+  };
+
+  /**
+   * A preparing pass's publication: `frame` with the pass's own `token`,
+   * minted before it so a draw inside the publication finds its waiter.
+   * Never coalesced, so a frame already on screen is drawn again under the
+   * new token, and never a telemetry token: a negative one tells a pass's
+   * presentation from the transport's (`takePlayed`). A pass never runs in
+   * a component context, and an export ends it.
+   */
+  const publishPrepared = (frame: number, token: number): void => {
+    const rounded = Math.round(frame);
+    if (state.exporting !== null) {
+      deferred.frame = rounded;
+      return;
+    }
+    lastFrame = rounded;
+    const sceneId = sceneIdAt(state.doc, rounded);
+    if (sceneId !== state.sceneId) set({ sceneId });
+    clock.set(rounded, token);
+  };
+
+  const cancelLift = (): void => {
+    if (lift === null) return;
+    clearTimeout(lift.deadline);
+    lift = null;
+  };
+  /** The frozen picture comes down, now, and the furniture follows the
+   *  scene graph again. */
+  const dropFreeze = (): void => {
+    cancelLift();
+    freeze?.remove();
+    freeze = null;
+    if (state.held !== null || state.passDrawing) set({ held: null, passDrawing: false });
+  };
+  /** A press or a wheel on the shield (`mountFreeze`). It ends the pass
+   *  drawing under it (`yielded: "press"`), or, once that pass has given the
+   *  stage back, takes the frozen picture down at once, so a press between
+   *  the restore and the lift is never one that does nothing. Swallowed
+   *  either way: until the restore is drawn the scene graph may still hold
+   *  the pass's frame. */
+  const shieldPress = (): void => {
+    if (preparing !== null) preparing.end("press");
+    else dropFreeze();
+  };
+  /** A standing freeze waits for the author's frame from publication `after`
+   *  on (see `lift`), and comes down at the 5 s backstop at the latest. */
+  const armLift = (after: number): void => {
+    if (freeze === null) return;
+    cancelLift();
+    lift = { after, either: transport, scrubbed: false, deadline: setTimeout(dropFreeze, PREPARE_FRAME_DEADLINE_MS) };
+  };
+
   const bridge: ShotStageBridge = {
     version: SHOT_BRIDGE_VERSION,
     connect(next) {
       handlers = next;
-      set({ connected: true });
+      // THE HANDSHAKE, and unconditional: the chrome starts at `stageBusy:
+      // false`, so a presentation owed before it was listening, on a cold
+      // open, would otherwise never be reported at all.
+      sentBusy = null;
+      queueBusy();
+      // THE FONT PREVIEW IS CLEARED ON EVERY ATTACH (v50), its faces with it:
+      // it belongs to an open picker, and a chrome that has just attached has
+      // none open and re-pushes nothing for it.
+      previewFaces.show(null);
+      set({ connected: true, fontPreview: null, motionPreview: null });
+    },
+    health(): StageHealthSnapshot {
+      return {
+        crashed: fatalError,
+        contextLost: contextLost(),
+        pieces: pieceFailures,
+        renderErrors: [...renderErrors],
+        componentErrors: [...instanceErrors, ...instanceCrashes, ...placedHotErrors()],
+        errors: stageErrors,
+        rendered: rendered === null ? null : { ...rendered },
+        loadedAt: Math.max(performance.timeOrigin, codeAt ?? 0),
+      };
+    },
+    async coverage(request) {
+      // THE AUTHOR'S FRAME, AS THE SHOT DRAWS IT. A poster holding export
+      // framing steps aside first, as it does for any capture. A preparing
+      // pass under an `"idle"` pace draws other frames under a frozen
+      // picture: it ends (`yielded: "coverage"`), and hands the author's frame
+      // back, before the check reads the stage, and none starts while one
+      // runs (`checking`). A queued Play's pass is the author's and is never
+      // ended by a read: the check refuses while it runs, as it refuses a
+      // playing stage.
+      //
+      // It moves no `preparationKey()` (v51): the check draws into targets
+      // of its own and frees only those, so what prepared frames stand on is
+      // untouched. An agent's every write is checked, and a base that moved
+      // with each would throw every prepared frame away after it.
+      const yielding = yieldPoster();
+      if (yielding !== null) await yielding;
+      checking += 1;
+      try {
+        const pass = preparing;
+        if (pass !== null && pass.pace() === "idle") {
+          pass.end("coverage");
+          await pass.ended;
+        }
+        // What the check refuses, by what the stage shows: its picture must
+        // be the Shot's, still, at one frame.
+        const refusal =
+          state.doc === null
+            ? "no Project is on the stage"
+            : state.exporting !== null
+              ? "the stage is exporting"
+              : preparing !== null
+                ? "the stage is preparing to play, so its frame moves; the check measures a paused stage"
+                : state.playing
+                  ? "the stage is playing, so its frame moves; the check measures a paused stage"
+                  : state.componentContext !== null
+                    ? "the stage shows a component on its own, not a Shot"
+                    : state.isolation !== null
+                      ? "the stage is isolating a layer, which fades the rest of the Shot"
+                      : state.materialPreview !== null
+                        ? "the stage is previewing a material, which hides the rest of the Shot"
+                        : previewingFont()
+                          ? "the stage is previewing a font on some text layers, so its picture is not the Shot's"
+                          : previewingMotion()
+                            ? "the stage is previewing a motion preset on some layers, so its picture is not the Shot's"
+                            : coverageProbe === null
+                            ? "no Shot is under the playhead"
+                            : null;
+        if (refusal !== null) throw new Error(`the stage did not check which layers draw: ${refusal}`);
+        return await coverageProbe!({ ...(request ?? {}), frame: lastFrame });
+      } finally {
+        checking -= 1;
+      }
     },
-    loadDoc(doc) {
+    loadDoc(doc, rev = null) {
+      revOfDoc.set(doc, rev);
+      // THE SAME DOCUMENT, NOW A SAVED REVISION (v35): the chrome's own save
+      // landed, or a re-push of what is on stage. Nothing to re-render; the
+      // revision is all that moved, and a picture already drawn from this
+      // object IS that revision.
+      if (doc === state.doc && doc === (deferred.doc ?? state.doc)) {
+        if (rev !== state.docRev) {
+          set({ docRev: rev });
+          if (rendered !== null && presentedDoc === doc && rendered.rev !== rev) {
+            rendered.rev = rev;
+            notifyHealth();
+          }
+        }
+        return;
+      }
+      // Mid-export: DEFERRED, never interleaved. A doc swap re-renders every
+      // plane, and the capture loop would encode frame N's timestamp over
+      // whatever the new document draws. The export finishes on the document
+      // it started with; the push lands the moment it ends.
+      if (state.exporting !== null) {
+        // An edit, not an echo of the document the stage already has.
+        if (doc !== (deferred.doc ?? state.doc)) yieldPoster();
+        deferred.doc = doc;
+        deferred.rev = rev;
+        deferred.closed = false;
+        return;
+      }
+      // The authored cadence is what every window is judged against, so it has
+      // to land before the first bucket closes. During export this waits with
+      // the document because the active capture still uses the old cadence.
+      // It is the render scale's budget too.
+      performanceTelemetry.setFrameRate(doc.fps);
+      renderScale.setFrameRate(doc.fps);
       // A DIFFERENT document opening, not an edit echo: the span from here to
       // the next presented frame is the author's "how long until I see it".
       // markPerf no-ops without ?perf=1. Set BEFORE the state write, because
       // the commit this write triggers is the frame that settles it.
-      if (state.doc?.id !== doc.id) markPerf("open→frame");
-      set({ doc });
+      if (state.doc?.id !== doc.id) {
+        markPerf("open→frame");
+        // A pass's frames and what the transport played were the other
+        // Project's (v51). An edit of this one keeps both.
+        preparing?.end(null);
+        played = new Map();
+        // So was the raster cache's pressure: left standing, it would cut
+        // this Project's first rasters at a cheaper rung, then cut them again
+        // a rung at a time as the relief came in. And so was the render scale
+        // the last Project's GPU time settled on.
+        resetRasterPressure();
+        renderScale.reset();
+      }
+      // A doc swap can remove the definition the context renders; a context
+      // pointing at nothing would leave the whole viewport blank with no way
+      // out from the stage side. A CODE subject survives the swap: it is built
+      // from a registry id, so no document can take it away.
+      const ctx =
+        state.componentContext !== null &&
+        !("code" in state.componentContext) &&
+        doc.components?.[state.componentContext.def] === undefined
+          ? null
+          : state.componentContext;
+      const materialPreview = materialPreviewStillReal(doc, state.materialPreview?.layerId ?? null)
+        ? state.materialPreview
+        : null;
+      // Every outstanding token belonged to the OLD document. Holding them
+      // would let a stale publication match a presentation of the new one.
+      performanceTelemetry.resetPublications();
+      performanceTelemetry.setDebugDocument(doc);
+      set({
+        doc,
+        docRev: rev,
+        componentContext: ctx,
+        splineEdit: null,
+        materialPreview,
+        sceneId: ctx === null ? (masterToSceneCached(doc, lastFrame)?.sceneId ?? null) : null,
+      });
     },
     seek(frame) {
-      // Integer frames over a rational fps is the engine's invariant, and this
-      // is the boundary a float could sneak through: a chrome that computed a
-      // frame from a pixel position would otherwise hand the studio clock a
-      // fractional one and break byte-identity against the export.
-      set({ frame: Math.round(frame) });
+      // A scrub is the author's: a poster holding the stage steps aside, and
+      // the frame lands when its framing ends. A re-push of the frame the
+      // stage will return to anyway is not one.
+      if (state.exporting !== null && Math.round(frame) !== deferred.frame) yieldPoster();
+      // Nor is a re-push of the frame a running pass gives back (v51): the
+      // chrome restates the playhead after every document push, an ambient
+      // one included, and a queued Play's pass runs on across those.
+      if (preparing !== null && Math.round(frame) === preparing.startFrame) return;
+      // A seek ends a preparing pass's picture (v51): the pass gives the
+      // stage back first, and a freeze still standing lifts on the frame this
+      // lands on. A SCRUB NEVER LEAVES THE PICTURE FROZEN: a frame that moves
+      // under a freeze waiting for its lift shortens its backstop, once.
+      preparing?.end(null);
+      if (state.passDrawing) set({ passDrawing: false });
+      if (lift !== null && !lift.scrubbed && Math.round(frame) !== lastFrame) {
+        clearTimeout(lift.deadline);
+        lift = { ...lift, scrubbed: true, deadline: setTimeout(dropFreeze, SCRUB_LIFT_MS) };
+      }
+      publishFrame(frame);
+    },
+    preparePlayback(request) {
+      const { frames, onProgress, signal, pace, deadlineMs } = request;
+      preparing?.end(null);
+      const answer = (result: ShotPreparePlaybackResult): Promise<ShotPreparePlaybackResult> => Promise.resolve(result);
+      // UNDER EXPORT FRAMING a queued Play steps a poster aside and runs once
+      // it has. Anything else holding the framing (an export, a still, a
+      // capture), or a poster under an `"idle"` pace, is the chrome's to
+      // wait out.
+      if (state.exporting !== null) {
+        const yielding = pace() === "play" ? yieldPoster() : null;
+        return yielding === null
+          ? answer({ completed: false, presented: 0, yielded: "export" })
+          : yielding.then(() => bridge.preparePlayback(request));
+      }
+      const canvas = exportCanvas;
+      const host = freezeHost;
+      if (state.doc === null) return answer({ completed: false, presented: 0, refused: "no Project is on the stage" });
+      if (state.componentContext !== null) {
+        return answer({ completed: false, presented: 0, refused: "the stage shows a component on its own" });
+      }
+      if (canvas === null || host === null) {
+        return answer({ completed: false, presented: 0, refused: "the stage has no picture to freeze" });
+      }
+      // What the stage is doing comes first: a live interaction (its pointer,
+      // plane and picks read the scene graph a pass re-poses), a hidden page
+      // (it presents nothing), a coverage check measuring the author's frame
+      // (only an `"idle"` pace gives way to it), and a font preview, whose
+      // frames are not the Project's.
+      const early: ShotPreparePlaybackYield | null = interactionLive()
+        ? "interaction"
+        : typeof document !== "undefined" && document.visibilityState === "hidden"
+          ? "hidden"
+          : checking > 0 && pace() === "idle"
+            ? "coverage"
+            : previewingFont() || previewingMotion()
+              ? "push"
+              : null;
+      if (early !== null) return answer({ completed: false, presented: 0, yielded: early });
+      if (signal?.aborted === true) return answer({ completed: false, presented: 0 });
+      return new Promise((resolve) => {
+        const startFrame = lastFrame;
+        const wasPlaying = state.playing;
+        let presented = 0;
+        let settled = false;
+        /** Tears down what the pass is waiting on now: one publication's
+         *  presentation and its deadline. */
+        let abandon: (() => void) | null = null;
+        let ended: () => void = () => {};
+        // The chrome aborts with `"input"` for author input under an idle
+        // pace; any other abort is a cancel.
+        const onAbort = (): void => restore(false, signal?.reason === "input" ? "input" : null);
+        const onResize = (): void => restore(false, "resize");
+        const onHidden = (): void => {
+          if (document.visibilityState === "hidden") restore(false, "hidden");
+        };
+        const stop = (): void => {
+          settled = true;
+          abandon?.();
+          abandon = null;
+          signal?.removeEventListener("abort", onAbort);
+          window.removeEventListener("resize", onResize);
+          document.removeEventListener("visibilitychange", onHidden);
+          if (preparing === self) preparing = null;
+          // After the author's frame is published, in this task.
+          queueMicrotask(ended);
+        };
+        /**
+         * BACK TO THE AUTHOR'S STAGE: an `"idle"` pace at the end of the
+         * list, a cancel, a yield, an export. The stage gets its own playing
+         * flag back and the start frame under a fresh token, the furniture
+         * follows the scene graph again, and a freeze lifts on the first
+         * complete presentation of the frame the clock is on (`lift`): the
+         * start frame, or the newer one a later seek lands on.
+         *
+         * PAUSED, NOT JUST PRESENTED. `playing` reaches the runtime a commit
+         * after it is set here, so the restored frame's first draw is usually
+         * still the playing one, and a playing draw does not wait on a video
+         * seek: it showed the nearest picture the decoder held, and lifted
+         * there the author saw a softer frame for about 150 ms, then the real
+         * one. Mid-export the frame lands in `deferred.frame`, which the
+         * export's end restores.
+         */
+        const restore = (completed: boolean, why: ShotPreparePlaybackYield | null): void => {
+          if (settled) return;
+          stop();
+          set({ playing: wasPlaying, passDrawing: false });
+          const token = prepareToken();
+          armLift(token);
+          publishPrepared(startFrame, token);
+          resolve({ completed, presented, ...(why === null ? {} : { yielded: why }) });
+        };
+        /** Could not run at all: nothing of `frames` was drawn. */
+        const refuse = (reason: string): void => {
+          if (settled) return;
+          stop();
+          resolve({ completed: false, presented: 0, refused: reason });
+        };
+        const self = {
+          end: (why: ShotPreparePlaybackYield | null): void => restore(false, why),
+          pace,
+          startFrame,
+          ended: new Promise<void>((done) => {
+            ended = done;
+          }),
+        };
+        preparing = self;
+        signal?.addEventListener("abort", onAbort, { once: true });
+        window.addEventListener("resize", onResize);
+        document.addEventListener("visibilitychange", onHidden);
+        /** Wait for publication `token` to be presented IN THE PLAYING
+         *  PRESENTATION, or for `ms` to pass. A frame drawn paused prepared a
+         *  mount playback never uses (the warm-up's playing roles), and
+         *  `playing` reaches the runtime a commit after `begin` sets it, so
+         *  the pass's first frame is usually drawn paused first; that commit
+         *  draws it again, echoing the token.
+         *  At the deadline an external claim still open (a font, a texture,
+         *  a video seek) makes it `"timeout-pending"`. */
+        const waitFor = (token: number, ms: number, done: (outcome: ShotPreparedOutcome) => void): void => {
+          const settle = (outcome: ShotPreparedOutcome): void => {
+            abandon?.();
+            abandon = null;
+            done(outcome);
+          };
+          const timer = setTimeout(() => settle(externallyPending() ? "timeout-pending" : "timeout"), ms);
+          presentWaiters.set(token, (drawnPlaying) => {
+            if (drawnPlaying) settle("presented");
+          });
+          abandon = () => {
+            clearTimeout(timer);
+            presentWaiters.delete(token);
+          };
+        };
+        /** One frame: published under a fresh token (so a frame already on
+         *  screen is drawn again, in the playing presentation), waited for,
+         *  reported, then the next one after a hop. At the end of the list
+         *  the pace decides: hand over, or restore. */
+        const step = (index: number): void => {
+          if (settled) return;
+          if (interactionLive()) {
+            restore(false, "interaction");
+            return;
+          }
+          if (index >= frames.length) {
+            if (pace() === "play") handOver();
+            else restore(true, null);
+            return;
+          }
+          const token = prepareToken();
+          const asked = deadlineMs?.(index);
+          const ms =
+            typeof asked === "number" && asked > 0 ? Math.min(asked, PREPARE_FRAME_DEADLINE_MS) : PREPARE_FRAME_DEADLINE_MS;
+          waitFor(token, ms, (outcome) => {
+            if (outcome === "presented") presented += 1;
+            // NOT FROM INSIDE THE PRESENTATION: `present` runs in the
+            // runtime's `onPresented` call stack, where neither the chrome's
+            // store write nor the next publication may run. Reported even if
+            // the pass ended meanwhile: drawn is drawn.
+            queueMicrotask(() => {
+              onProgress?.(index + 1, frames.length, outcome);
+              if (!settled) hop(pace(), () => step(index + 1));
+            });
+          });
+          publishPrepared(frames[index]!, token);
+        };
+        /**
+         * THE HAND-OVER, at the end of a queued Play's list: the start frame
+         * is presented again in the playing presentation, under a fresh token,
+         * and the freeze lifts INSIDE that presentation, so the picture the
+         * author sees is the one the transport starts on and never another
+         * Shot's. The furniture follows the scene graph from this draw on, so
+         * the lift shows outlines projected from it. At the 5 s backstop it
+         * restores instead: no presentation of the start frame means no
+         * hand-over, and the freeze waits for one by the lift's rules, which
+         * the chrome's start of the transport opens to either presentation.
+         */
+        const handOver = (): void => {
+          set({ passDrawing: false });
+          const token = prepareToken();
+          waitFor(token, PREPARE_FRAME_DEADLINE_MS, (outcome) => {
+            if (outcome !== "presented") {
+              restore(true, null);
+              return;
+            }
+            stop();
+            dropFreeze();
+            resolve({ completed: true, presented, handedOver: true });
+          });
+          publishPrepared(startFrame, token);
+        };
+        /** THE PLAYING PRESENTATION, which is what playback draws with: the
+         *  warm-up's playing roles. The canvas density is the paused one
+         *  (`useStageDensity` holds it while `playing`), so the pass resizes
+         *  nothing. From the first publication on the furniture holds the
+         *  frozen frame. */
+        const begin = (): void => {
+          if (settled) return;
+          if (interactionLive()) {
+            restore(false, "interaction");
+            return;
+          }
+          set({ playing: true, passDrawing: true });
+          step(0);
+        };
+        // ── EVERY PASS DRAWS UNDER A FROZEN PICTURE ────────────────────────
+        //
+        // Nothing it draws may be seen: not the other frames, not the playing
+        // presentation's own picture of this one (a video's nearest decoded
+        // frame). A freeze an earlier pass left standing OF THIS FRAME is
+        // adopted, its lift called off. Otherwise the frame on screen is
+        // presented again and copied INSIDE that presentation
+        // (the playback framebuffer is unpreserved, so a copy taken later is
+        // blank), then laid over the canvas with the shield above every
+        // overlay. A freeze of an older frame (a seek landed before its lift)
+        // stands, lift and all, until the new copy replaces it.
+        if (freeze !== null && state.held === startFrame) {
+          cancelLift();
+          begin();
+          return;
+        }
+        const token = prepareToken();
+        const timer = setTimeout(() => refuse("freeze timed out"), PREPARE_FRAME_DEADLINE_MS);
+        abandon = () => {
+          clearTimeout(timer);
+          presentWaiters.delete(token);
+        };
+        presentWaiters.set(token, () => {
+          abandon?.();
+          abandon = null;
+          let copy: Promise<ImageBitmap>;
+          try {
+            copy = createImageBitmap(canvas);
+          } catch {
+            refuse("the stage could not copy its picture");
+            return;
+          }
+          void copy.then(
+            (bitmap) => {
+              if (settled) {
+                bitmap.close();
+                return;
+              }
+              if (interactionLive()) {
+                bitmap.close();
+                restore(false, "interaction");
+                return;
+              }
+              const older = freeze;
+              freeze = mountFreeze(host, canvas, bitmap, shieldPress);
+              bitmap.close();
+              older?.remove();
+              cancelLift();
+              set({ held: startFrame });
+              begin();
+            },
+            () => refuse("the stage could not copy its picture"),
+          );
+        });
+        publishPrepared(startFrame, token);
+      });
+    },
+    preparationKey() {
+      const canvas = exportCanvas;
+      // The density the stage draws at, paused and playing (`stageDensity`,
+      // StageApp's canvas `dpr`). A change while the transport runs or a
+      // pass draws reads here at once, while the canvas waits for the Pause
+      // edge: the base moves, so nothing drawn at the old density is credited
+      // under the new one.
+      const ratio = stageDensity();
+      return {
+        base: `${performance.timeOrigin}:${gpuEpoch}:${canvas?.clientWidth ?? 0}x${canvas?.clientHeight ?? 0}@${ratio}:${rasterScale}`,
+        modules: `${moduleEpoch ?? ""}:${hotUpdates}`,
+      };
+    },
+    takePlayed() {
+      const out: { frame: number; document: Doc3D }[] = [];
+      for (const [document, frames] of played) for (const frame of frames) out.push({ frame, document });
+      played = new Map();
+      return out;
+    },
+    setPlaying(playing) {
+      // NOT deferred mid-export, unlike `seek` and `loadDoc`. Those two would
+      // change what the capture loop draws; this changes only what the stage
+      // does between draws, and an export cannot be running while the transport
+      // is (`setPlaying` refuses on the chrome side). Writing it through keeps
+      // the flag honest if the two ever overlap.
+      const next = playing === true;
+      // The transport never overlaps a preparing pass (v51): one the chrome
+      // did not hand over gives the stage back first.
+      preparing?.end(null);
+      // A poster is not an export: the chrome takes no lock for it, so Play
+      // can arrive mid-capture. Aborting it cancels the armed capture at once,
+      // so no captured frame can be drawn under the playing flag.
+      if (next) yieldPoster();
+      // Opens or closes the sampling windows, and releases the rung on pause.
+      // The render scale takes the transport's frames alone as samples and
+      // deadlines: a preparing pass sets `playing` and never this.
+      performanceTelemetry.setPlaying(next);
+      renderScale.setPlaying(next);
+      // RETRACTED ON STOP, and null rather than zero: no frames are expected of
+      // a stopped stage, so the last window's rate is stale the moment playback
+      // ends and 0 fps would read as a stall. Queued so it lands after any
+      // window report already in flight, and outside the chrome's own set.
+      if (!next) queueMicrotask(() => handlers?.onPerformance(null));
+      // What the transport draws is counted from its start (`takePlayed`). A
+      // freeze still standing may lift in either presentation from here, but
+      // never at once: the canvas may still hold another Shot's picture.
+      if (next && !transport) played = new Map();
+      transport = next;
+      if (next && lift !== null) lift.either = true;
+      if (state.playing === next) return;
+      set({ playing: next });
     },
     setSelection(ids) {
       set({ selection: [...ids] });
     },
+    setPeerSelections(peers) {
+      const next = sanitizePeerSelections(peers);
+      // Identity-stable when both are empty: no peers is the common case.
+      if (next.length === 0 && state.peerSelections.length === 0) return;
+      set({ peerSelections: next });
+    },
     selectionQuads(pane = "camera") {
+      // Under a frozen picture the feed holds that frame's quads (StageTools
+      // projects nothing while a pass draws), so this answers for it.
       return quadSource === null ? null : quadSource(pane);
     },
     setTool(tool) {
-      set({ tool });
+      // An unknown id (the retired "move", or any stale caller) arms Select.
+      set({ tool: Object.hasOwn(TOOL_SPECS, tool) ? tool : "select" });
+    },
+    setWorkPlane(target) {
+      set({ workPlane: sanitizeWorkPlane(target) });
+    },
+    setSplineBasis(splineBasis) {
+      set({ splineBasis: splineBasis === "catmull-rom" ? "catmull-rom" : "bezier" });
+    },
+    setSplineEditContext(splineEdit) {
+      set({
+        splineEdit:
+          splineEdit === null
+            ? null
+            : { layerId: splineEdit.layerId, selectedPointIds: [...splineEdit.selectedPointIds] },
+      });
     },
     setSnapGuides(guides) {
       // Identity-stable when both are empty, so the common case (no gesture
@@ -163,6 +1896,11 @@ export function createStageClient(): StageClient {
       if (guides.length === 0 && state.guides.length === 0) return;
       set({ guides: [...guides] });
     },
+    hoverLayer(layerId) {
+      // NOT a `set()`: the whole point of the verb is that a chrome hover
+      // costs one SVG leaf repaint, never a stage commit. See bridgeTypes v22.
+      hoverSink?.(layerId);
+    },
     setView(view) {
       set({ view });
     },
@@ -172,6 +1910,9 @@ export function createStageClient(): StageClient {
       set({ view });
       return view;
     },
+    designPointAt(clientX, clientY) {
+      return designPointer?.(clientX, clientY) ?? null;
+    },
     setStageLayout(layout) {
       // Gaining a working pane is the compile-storm moment (SplitRenderer +
       // clay mount); the span to the next presented frame measures it.
@@ -181,7 +1922,75 @@ export function createStageClient(): StageClient {
       // anywhere — the stage does not get to assume its caller was careful.
       set({ layout: { mode: layout.mode, splitRatio: clampSplitRatio(layout.splitRatio) } });
     },
+    setVideo(video) {
+      // Gaining or losing the working pane is the compile-storm moment on this
+      // side too: Video is drawn as the camera-only panes, so turning it OFF
+      // over a split or a 3D-view layout mounts the same renderer the layout
+      // push does. Marked with the same span for the same reason.
+      if (!video && state.layout.mode !== "camera" && state.video) {
+        markPerf("split→frame");
+      }
+      set({ video });
+    },
+    setReadOnly(on) {
+      set({ readOnly: on === true });
+    },
+    setStoryboardPreview(on) {
+      // No `split→frame` mark, unlike `setVideo` above: the board covers the
+      // window, so gaining or losing the working pane behind it costs the
+      // author nothing they are looking at.
+      set({ storyboardPreview: on });
+    },
+    setStudioComments(comments) {
+      const next = sanitizeStudioComments(comments);
+      // Identity-stable when both are empty: no Studio comments is the common
+      // case, and the chrome re-pushes on every attach.
+      if (next === null && state.studioComments === null) return;
+      set({ studioComments: next });
+    },
+    setSketchGuide(guide) {
+      const next = sanitizeSketchGuide(guide);
+      // Identity-stable when both are off: the chrome re-pushes on attach.
+      if (next === null && state.sketchGuide === null) return;
+      set({ sketchGuide: next });
+    },
+    setFontPreview(preview) {
+      // NOT deferred mid-export: export framing draws the real document
+      // whatever this holds (StageApp), and the preview shows again when the
+      // export ends.
+      const next = sanitizeFontPreview(preview);
+      // Identity-stable when both are off: no preview is the common case.
+      if (next === null && state.fontPreview === null) return;
+      // A hover is the author's: a poster holding export framing steps aside,
+      // and the preview shows once it has.
+      if (next !== null) yieldPoster();
+      const face = previewFaces.show(next);
+      set({ fontPreview: next === null ? null : { ...next, face } });
+    },
+    setMotionPreview(preview) {
+      // NOT deferred mid-export, the font preview's rule: export framing draws
+      // the real document whatever this holds (StageApp).
+      const next = sanitizeMotionPreview(preview);
+      if (next === null && state.motionPreview === null) return;
+      if (next !== null) yieldPoster();
+      set({ motionPreview: next });
+    },
+    editText(layerId) {
+      set({ textEdit: typeof layerId === "string" ? layerId : null });
+    },
     setIsolation(isolation) {
+      // DEFERRED MID-EXPORT, like every other chrome push. The chrome sends
+      // this after every document push, and it once wrote `frame`: landing it
+      // during a capture moved the export framing off the armed frame, so that
+      // frame never presented and the export timed out 20 s later. The anchor
+      // below reads `lastFrame`, which the capture loop owns, so it still waits.
+      if (state.exporting !== null) {
+        // Rides every document push unchanged: only a real change is the
+        // author's, and steps a poster aside.
+        if (isolation !== (deferred.isolation?.layerId ?? state.isolation)) yieldPoster();
+        deferred.isolation = { layerId: isolation, orbit: false };
+        return;
+      }
       // Validated against the DOCUMENT here, not trusted: the chrome's id can
       // be one edit behind the stage's doc, and an isolation naming a layer
       // that no longer exists would leave the pane pointed at nothing with no
@@ -192,10 +2001,71 @@ export function createStageClient(): StageClient {
       // perspective pose derived from somewhere else entirely, and the head-on
       // entry view — the whole point of isolation — would only appear the first
       // time.
-      set({ isolation: isolation !== null && scene !== null ? isolation : null, isolationOrbit: false });
+      const next = isolation !== null && scene !== null ? isolation : null;
+      set({
+        isolation: next,
+        isolationOrbit: false,
+        // A NEW ANCHOR ONLY FOR A NEW SUBTREE. This push rides every document
+        // push unchanged, and re-anchoring on each one re-fitted the camera on
+        // every edit: a drag that grew the subtree zoomed the pane out from
+        // under the pointer that was dragging.
+        ...(next === state.isolation ? {} : { isolationAnchor: next === null ? null : { frame: lastFrame } }),
+      });
+    },
+    setMaterialPreview(target) {
+      // Clamped AT THE BOUNDARY, the way `clampInset` is: a slot arrives as a
+      // number from another document and a negative or fractional one would
+      // otherwise reach the runtime as a key that matches nothing.
+      const layerId = target === null ? null : target.layerId;
+      const known = state.doc !== null && materialPreviewStillReal(state.doc, layerId);
+      if (!known || target === null) {
+        set({ materialPreview: null });
+        return;
+      }
+      const slot =
+        typeof target.slot === "number" && Number.isSafeInteger(target.slot) && target.slot >= 0
+          ? target.slot
+          : null;
+      set({ materialPreview: { layerId: target.layerId, slot } });
     },
     setIsolationOrbit(taken) {
-      set({ isolationOrbit: taken === true });
+      // Riding a deferred isolation push, the orbit belongs to that push: it
+      // is applied with it in `end()`, not to the isolation still on screen.
+      if (state.exporting !== null && deferred.isolation !== null) {
+        deferred.isolation.orbit = taken === true;
+        return;
+      }
+      // FALSE IS HOME, and Home inside a subtree re-derives its frame from
+      // where the playhead stands now: the frame is held still across edits,
+      // so this is how the author re-fits after moving things out of it.
+      set(
+        taken === true || state.isolation === null
+          ? { isolationOrbit: taken === true }
+          : { isolationOrbit: false, isolationAnchor: { frame: lastFrame } },
+      );
+    },
+    setComponentContext(ctx) {
+      // THE ZOOM IS CLAMPED AT THE BOUNDARY, exactly as `setMaterialPreview`
+      // clamps its slot and `clampInset` its sides: it divides the subject's
+      // half-extents, so a zero, a negative or a NaN is an orthographic frustum
+      // that projects the whole subject to nothing — with no error anywhere.
+      // The chrome owns the RANGE; this owns only "a number the camera can use".
+      const targetDoc = state.exporting !== null
+        ? deferred.closed
+          ? null
+          : deferred.doc ?? state.doc
+        : state.doc;
+      const next = validComponentContext(ctx, targetDoc);
+      if (state.exporting !== null) {
+        // A poster never starts inside a context, so a context arriving is
+        // the author entering one: the poster steps aside.
+        if (next !== null) yieldPoster();
+        // Export framing always renders scenes. Remember a chrome context push
+        // for the single restore commit instead of interleaving it with capture.
+        deferred.componentContext = next;
+        return;
+      }
+      set({ componentContext: next });
     },
     setStageInset(inset) {
       const next = clampInset(inset);
@@ -217,55 +2087,652 @@ export function createStageClient(): StageClient {
       set({ workingView });
       return workingView;
     },
+    setGridVisible(visible) {
+      set({ grid: visible === true });
+    },
+    setEditorChrome(chrome) {
+      // Clamped at the boundary like the shading: a mode this stage does not
+      // know is the default.
+      renderScale.setMode(isPlaybackResolution(chrome.playbackResolution) ? chrome.playbackResolution : "auto");
+      const next = { rulers: chrome.rulers === true, smartGuides: chrome.smartGuides !== false };
+      if (next.rulers === state.editorChrome.rulers && next.smartGuides === state.editorChrome.smartGuides) return;
+      set({ editorChrome: next });
+    },
+    setMotionPaths(on) {
+      if ((on === true) !== state.motionPaths) set({ motionPaths: on === true });
+    },
     setShadingMode(mode) {
       // Clamped at the boundary like the split ratio: an unknown mode from a
       // careless caller means the default clay, not a pane that draws nothing.
       set({ shading: clampShading(mode) });
     },
-    setCameraFollowsView(on) {
-      set({ cameraFollowsView: on === true });
+    setPilot(on, text) {
+      set({ pilot: on === true, pilotText: typeof text === "string" ? text : null });
+    },
+    setCameraGate(gate) {
+      set({ cameraGate: gate ?? null });
     },
     closeDoc() {
-      set({ doc: null, selection: [] });
+      // Mid-export: deferred like loadDoc. Unmounting every plane under the
+      // capture loop is the one thing worse than re-rendering under it.
+      if (state.exporting !== null) {
+        yieldPoster();
+        deferred.closed = true;
+        deferred.doc = null;
+        deferred.componentContext = null;
+        return;
+      }
+      // A pass draws the document that is leaving, and nothing prepared for
+      // it stands for anything now (v51).
+      preparing?.end(null);
+      gpuStateReplaced();
+      // The context names a definition in the doc that just left; a context
+      // over no document would render nothing with no way out.
+      performanceTelemetry.setDebugDocument(null);
+      // A font preview belongs to the document's open picker, and leaves with it.
+      previewFaces.show(null);
+      set({
+        doc: null,
+        docRev: null,
+        selection: [],
+        componentContext: null,
+        splineEdit: null,
+        materialPreview: null,
+        fontPreview: null,
+        motionPreview: null,
+      });
     },
     clearCaches() {
-      // Called right after closeDoc. The chrome's two calls run synchronously
-      // before the stage's doc-null commit can land, so the clear disposes
-      // textures some planes still bind — safe, because no GL draw happens
-      // between synchronous JS and that commit (draws ride commits), and the
-      // unmount commit runs cleanups, never a draw of the old doc.
-      clearRasterCache();
+      // `closeShot` pairs this with `closeDoc`. During export that close is
+      // deferred, so its cache clear must be deferred with it. Disposing live
+      // raster or plane resources inside the capture loop can invalidate the
+      // frame in flight and force replacement allocations on later frames.
+      if (state.exporting !== null) {
+        deferred.clearCaches = true;
+        return;
+      }
+      clearStageCaches();
+    },
+    exportCapability() {
+      return exporterOf().capability();
+    },
+    exportMovie(request) {
+      // An export the author asked for waits only for a poster to step aside.
+      // Otherwise it enters export framing in this task, before any await,
+      // which the dialog's same-task document check relies on.
+      const yielding = yieldPoster();
+      return yielding === null
+        ? exporterOf().exportMovie(request)
+        : yielding.then(() => exporterOf().exportMovie(request));
+    },
+    requestNodePreviews(request) {
+      // Never during an export, for `capturePoster`'s reason and one more: the
+      // preview component is not even mounted in export framing, so this is a
+      // belt on top of a structural guarantee rather than the only guard.
+      // Never without a preview target either — a thumbnail needs the source
+      // material channels of the surface being edited, and there is no such
+      // surface when the workspace is closed.
+      if (state.exporting !== null || state.materialPreview === null || nodePreviewSource === null) {
+        return Promise.resolve(null);
+      }
+      // Clamped rather than refused. A request one node too long is a scroll
+      // position, and a size outside the band is a device-pixel-ratio the
+      // chrome could not have known about.
+      const size = Math.max(32, Math.min(256, Math.round(request.size)));
+      const nodeIds = [...new Set(request.nodeIds)].slice(0, MAX_NODE_PREVIEWS);
+      if (nodeIds.length === 0) return Promise.resolve(null);
+      return nodePreviewSource({ ...request, size, nodeIds });
+    },
+    async capturePoster(maxWidth) {
+      // THE EXPORT'S OWN CAPTURE, never a read of the live canvas: the playback
+      // framebuffer is unpreserved, and a late read can be valid-sized black.
+      // The exporter flips into export framing, arms the in-draw snapshot at
+      // the poster frame (the one the local CLI renders, `posterFrame`), and
+      // restores the author's stage on every path.
+      //
+      // Only on an idle stage showing the film. A poster is decoration: it
+      // never interrupts playback, an export, Play's preparing pass, a
+      // component or material being edited, or a font being previewed (export
+      // framing would replace that view with the film). And it never holds
+      // the stage against the author: anything they start on it (Play, an
+      // export or capture, a scrub, an edit, a press, a font preview) aborts it
+      // (`yieldPoster`), and the chrome takes no lock for it. Null means no
+      // new upload, so an existing poster remains and a project that never
+      // had one keeps the gradient.
+      const doc = state.doc;
+      if (
+        doc === null ||
+        doc === posterFailedFor ||
+        poster !== null ||
+        state.exporting !== null ||
+        state.playing ||
+        preparing !== null ||
+        state.componentContext !== null ||
+        state.materialPreview !== null ||
+        previewingFont() ||
+        previewingMotion()
+      ) {
+        return null;
+      }
+      const width = Math.min(Math.max(1, Math.floor(maxWidth)), doc.size.width);
+      const abort = new AbortController();
+      const capture = exporterOf().captureStill({
+        frame: posterFrame(docDurationFrames(doc)),
+        width,
+        height: Math.max(1, Math.round((doc.size.height * width) / doc.size.width)),
+        type: "image/jpeg",
+        quality: 0.85,
+        signal: abort.signal,
+      });
+      const entry = { abort, settled: capture.then(() => undefined, () => undefined) };
+      poster = entry;
+      try {
+        return await capture;
+      } catch {
+        // Yielded is not failed: the chrome asks again once the stage is idle.
+        if (!abort.signal.aborted) posterFailedFor = doc;
+        return null;
+      } finally {
+        if (poster === entry) poster = null;
+      }
+    },
+    captureFrame({ format, ...still }) {
+      const yielding = yieldPoster();
+      return yielding === null
+        ? exporterOf().captureStill({ ...still, type: `image/${format}` })
+        : yielding.then(() => exporterOf().captureStill({ ...still, type: `image/${format}` }));
     },
     dispose() {
+      preparing?.end(null);
+      dropFreeze();
+      hopChannel?.port1.close();
+      hopChannel = null;
+      hops.length = 0;
+      previewFaces.show(null);
+      cancelPendingCapture(new Error("the stage was disposed during capture"));
+      registerExportCanvas(null);
+      unsubscribeWindow();
+      unsubscribePresented();
       dispose?.();
       dispose = null;
       handlers = null;
+      // A reminted client handshakes again in `connect`; a stale "they already
+      // know it is true" would swallow that push.
+      sentBusy = null;
+    },
+  };
+
+  /** The exporter's window onto this client: state for the numbers, the
+   *  registered area element for the canvas and the commit marker, and the
+   *  shared readiness latch for "the draw landed". `begin`/`end` are the only
+   *  writers of `exporting`, so the deferral in `loadDoc`/`seek` and this
+   *  block cannot disagree about when the capture loop owns the clock. */
+  const exportHost: Parameters<typeof createShotStageExporter>[0] = {
+    composition() {
+      const doc = state.doc;
+      return doc === null
+        ? null
+        : { width: doc.size.width, height: doc.size.height, fps: doc.fps };
+    },
+    scopeFrames(sceneId) {
+      const doc = state.doc;
+      if (doc === null) return null;
+      if (sceneId === undefined) return docDurationFrames(doc);
+      const slice = sliceShotToScene(doc, sceneId);
+      // sliceShotToScene falls back to the whole document for an unknown id
+      // (a component rendering nothing is worse than one rendering the shot);
+      // an EXPORT of the wrong scope is the opposite trade, so refuse.
+      if (slice === null || doc.scenesById[sceneId] === undefined) return null;
+      return docDurationFrames(slice);
+    },
+    sceneStartFrames(sceneId) {
+      const doc = state.doc;
+      // A one-scene export starts on its only scene; the whole timeline's
+      // master frames ARE its export frames.
+      if (doc === null || sceneId !== undefined) return [0];
+      return sceneWindows(doc).map((window) => window.start);
+    },
+    begin(sceneId) {
+      if (state.exporting !== null) throw new Error("an export is already running");
+      // A preparing pass ends FIRST, synchronously (`yielded: "export"`): it
+      // restores the stage's playing flag and the author's frame while
+      // nothing is exporting, so the frame recorded below is the author's and
+      // not the pass's current one. A frozen picture comes down with it:
+      // export framing redraws the canvas, and nothing may stand over it.
+      preparing?.end("export");
+      dropFreeze();
+      // REFUSAL OVER CORRUPTION. A component whose module failed to load or
+      // crashed draws nothing, and export cannot tell that apart from a layer
+      // meant to be empty. The author has already seen the stage error; this is
+      // the exporter declining to bake it into every frame.
+      const refusal = exportRefusal();
+      if (refusal !== null) throw refusal;
+      deferred.frame = lastFrame;
+      deferred.doc = null;
+      deferred.componentContext = state.componentContext;
+      deferred.closed = false;
+      deferred.clearCaches = false;
+      deferred.isolation = null;
+      // An export always renders SCENES: a component context left set would
+      // put the runtime's def mount and the export framing on the canvas at
+      // once. Cleared rather than refused — the chrome's dialog is master-side
+      // and the author asked for the shot.
+      set({
+        exporting: sceneId === undefined ? {} : { scene: sceneId },
+        // Outside every valid timeline. The first capture arms BEFORE seek(0),
+        // so frame 0 cannot be coalesced with begin's framing commit and miss
+        // the only in-draw snapshot opportunity.
+        frame: -1,
+        // Belt and braces. The chrome already refuses to start an export while
+        // the transport runs and refuses to start the transport mid-export, so
+        // this should always be false already — but `playing` defers work a
+        // capture must not have deferred, and the cost of asserting it here is
+        // one boolean against a whole class of wrong exported frame.
+        playing: false,
+        componentContext: null,
+      });
+    },
+    seek(frame) {
+      // Through React: the commit stamps `data-export-frame`, which the
+      // capture requires in the same task as the draw. The clock follows so
+      // the stage's frame loops agree.
+      set({ frame });
+      clock.set(frame);
+    },
+    end() {
+      cancelPendingCapture(new Error("the export ended before its frame was captured"));
+      // Deferred chrome pushes land HERE, with the export flag and the frame
+      // in one commit — the stage never paints an in-between state.
+      const restoredFrame = deferred.frame ?? lastFrame;
+      lastFrame = restoredFrame;
+      const patch: Partial<StageClientState> = {
+        exporting: null,
+        frame: restoredFrame,
+      };
+      const clearCaches = deferred.clearCaches;
+      try {
+        const restoredDoc = deferred.closed ? null : deferred.doc ?? state.doc;
+        patch.componentContext = validComponentContext(deferred.componentContext, restoredDoc);
+        if (deferred.closed) {
+          performanceTelemetry.setDebugDocument(null);
+          patch.doc = null;
+          patch.docRev = null;
+          patch.selection = [];
+          patch.splineEdit = null;
+          patch.materialPreview = null;
+          previewFaces.show(null);
+          patch.fontPreview = null;
+          patch.motionPreview = null;
+        } else if (deferred.doc !== null) {
+          // Another Project, as `loadDoc` resets for one.
+          if (deferred.doc.id !== state.doc?.id) {
+            resetRasterPressure();
+            renderScale.reset();
+          }
+          performanceTelemetry.setFrameRate(deferred.doc.fps);
+          renderScale.setFrameRate(deferred.doc.fps);
+          performanceTelemetry.resetPublications();
+          performanceTelemetry.setDebugDocument(deferred.doc);
+          patch.doc = deferred.doc;
+          patch.docRev = deferred.rev;
+          patch.splineEdit = null;
+          patch.materialPreview = materialPreviewStillReal(
+            deferred.doc,
+            state.materialPreview?.layerId ?? null,
+          )
+            ? state.materialPreview
+            : null;
+        }
+        // The isolation push the export held back, validated against the
+        // document that is about to be current, as `setIsolation` does.
+        if (deferred.isolation !== null) {
+          const layerId = deferred.isolation.layerId;
+          patch.isolation =
+            layerId !== null && restoredDoc !== null && sceneWithLayer(restoredDoc, layerId) !== null
+              ? layerId
+              : null;
+          // What the live pair would have left: `setIsolation` resets the
+          // orbit and `setIsolationOrbit` sets it, whatever is isolated. A
+          // component context reads it too (`headOnOwnsPane`).
+          patch.isolationOrbit = deferred.isolation.orbit;
+          if (patch.isolation !== state.isolation) {
+            patch.isolationAnchor = patch.isolation === null ? null : { frame: restoredFrame };
+          }
+        }
+        patch.sceneId = sceneIdAt(restoredDoc, restoredFrame);
+      } finally {
+        // WHATEVER FAILED ABOVE, THE STAGE LEAVES EXPORT FRAMING. Stuck in it,
+        // every chrome push stays deferred for the session and every later
+        // export refuses with "an export is already running".
+        deferred.doc = null;
+        deferred.frame = null;
+        deferred.componentContext = null;
+        deferred.closed = false;
+        deferred.clearCaches = false;
+        deferred.isolation = null;
+        set(patch);
+        clock.set(restoredFrame);
+        // Export framing dropped the resident scenes and remounted the placed
+        // components: what prepared frames stood on is gone (v51). Said once
+        // the stage is the author's again, a throw above included.
+        gpuStateReplaced();
+      }
+      // With exporting cleared and the deferred document patch published, no
+      // capture draw can race this release. The following React commit either
+      // unmounts the old document or mounts the replacement from empty caches.
+      if (clearCaches) clearStageCaches();
+    },
+    canvas() {
+      return exportCanvas;
+    },
+    frameCommitted(frame) {
+      return exportArea?.getAttribute("data-export-frame") === String(frame);
+    },
+    waitingOn() {
+      return stageReadiness.describe();
+    },
+    armCapture(frame, size, snapshot) {
+      if (state.exporting === null) {
+        return Promise.reject(new Error("an exact framebuffer capture requires export framing"));
+      }
+      const refusal = exportRefusal(frame);
+      if (refusal !== null) return Promise.reject(refusal);
+      if (pendingCapture !== null) {
+        return Promise.reject(new Error("another export frame capture is already armed"));
+      }
+      return new Promise<ImageBitmap>((resolve, reject) => {
+        pendingCapture = {
+          frame,
+          width: size.width,
+          height: size.height,
+          snapshotting: false,
+          snapshot,
+          resolve,
+          reject,
+        };
+      });
+    },
+    cancelCapture(error) {
+      cancelPendingCapture(error);
     },
   };
 
   return {
     bridge,
+    clock,
+    performanceTelemetry,
+    renderScale,
+    noteDrawn(info, document, epoch = null, drawn) {
+      if (document === null) return;
+      moduleEpoch = epoch;
+      // A FRAME THE TRANSPORT DREW (`takePlayed`), in the playing
+      // presentation: never a pass's (its tokens are negative), and none
+      // while a component or a font preview stands in for the Project's
+      // picture, which the chrome's keys do not describe.
+      const token = info.presentationToken;
+      const transported =
+        transport &&
+        drawn?.playing === true &&
+        !(token !== undefined && token < 0) &&
+        state.componentContext === null &&
+        state.fontPreview === null &&
+        state.motionPreview === null;
+      // A PASS'S OWN FRAME is not the author's picture, so it is never what
+      // `health()` says was drawn: an agent's check reads that as the
+      // playhead's Shot drawn at that revision. The freeze, the restore and
+      // the hand-over draw the author's frame with `passDrawing` clear, and
+      // count; a late draw of a prepared frame is off the clock's frame.
+      const passFrame = token !== undefined && token < 0 && (state.passDrawing || info.frame !== clock.get().frame);
+      // Playing, the next frame of the picture already recorded moves only
+      // the frame: no readiness query and no clock read per played frame,
+      // once the latch is closed and while nothing counts what was played.
+      if (
+        state.playing &&
+        !transported &&
+        latch === subject &&
+        rendered !== null &&
+        presentedDoc === document &&
+        rendered.epoch === epoch &&
+        rendered.rev === (revOfDoc.get(document) ?? null)
+      ) {
+        if (!passFrame) rendered.frame = info.frame;
+        return;
+      }
+      if (externallyPending()) return;
+      // A MOTION PREVIEW'S FRAME is not the Project's picture either (v53): the
+      // chrome is seeking through a preset's frames on a stamped copy, so
+      // `health()` reads pending until it clears and the playhead is drawn.
+      if (!passFrame && !previewingMotion()) notePresented(info, document, epoch);
+      if (transported) played.set(document, (played.get(document) ?? new Set<number>()).add(info.frame));
+      // THE LATCH (v51): this renderer presented the open subject whole.
+      const drew = drawn === undefined ? (document === state.doc ? subject : null) : drawn.subject;
+      if (latch !== subject && drew === subject) {
+        latch = subject;
+        queueBusy();
+      }
+    },
+    noteHotUpdate(checked) {
+      for (const [module, error] of checked) {
+        if (error === null) hotErrors.delete(module);
+        else hotErrors.set(module, error);
+      }
+      hotUpdates += 1;
+      codeAt = wallNow();
+      if (hotErrors.size > 0) refuseArmedCapture();
+      notifyHealth();
+    },
+    present(info, document, drawnPlaying = false, drawnForExport = false) {
+      // The preparing pass, first: it waits on exactly this publication.
+      const waiter = info.presentationToken === undefined ? undefined : presentWaiters.get(info.presentationToken);
+      waiter?.(drawnPlaying);
+      // Then a frozen picture waiting for the author's frame (v51): the frame
+      // the clock is on now, so a seek moves the lift to the newer frame;
+      // drawn from the restore's publication on, not a late draw of a
+      // prepared one; complete; and paused, or in either presentation once
+      // the transport runs (see `restore` in `preparePlayback`).
+      const waiting = lift;
+      if (waiting !== null) {
+        const token = info.presentationToken;
+        const current = info.frame === clock.get().frame && !(token !== undefined && token < 0 && token > waiting.after);
+        if (current && (!drawnPlaying || waiting.either) && !externallyPending()) dropFreeze();
+      }
+      const pending = pendingCapture;
+      // The DOCUMENT drawn, too. The r3f root commits after the DOM one, so a
+      // draw from the previous document can land at the armed frame with the
+      // new frame marker already stamped: the still stage reuses one stage
+      // for every Shot of a Project, and most thumbnails are frame 0. Export
+      // framing defers `loadDoc`, so `state.doc` is the armed document.
+      //
+      // And the FRAMING drawn. Until the r3f root commits the export render,
+      // the editor's tree is still mounted, and a frame it started behind a
+      // compile can land at the armed frame with every live check above and
+      // below already true. Its picture is the presentation lane's: raster
+      // rungs, analytic shapes, the GPU Canvas2D store. So only a draw from
+      // an export-framing render resolves a capture.
+      if (
+        pending === null ||
+        state.exporting === null ||
+        !drawnForExport ||
+        info.frame !== pending.frame ||
+        document !== state.doc
+      ) {
+        performanceTelemetry.present(info, document);
+        return;
+      }
+      if (pending.snapshotting) {
+        // The framebuffer has already been synchronously handed to the
+        // snapshot implementation. Keep the capture record live until that
+        // asynchronous snapshot settles so a context loss, fatal stage error,
+        // or known render failure can still cancel the final export frame.
+        performanceTelemetry.present(info, document);
+        return;
+      }
+      const refusal = exportRefusal(pending.frame);
+      if (refusal !== null) {
+        pendingCapture = null;
+        pending.reject(refusal);
+        performanceTelemetry.present(info, document);
+        return;
+      }
+      // ClockDriver already proved its local scope clear before publishing.
+      // The module-global scope can also contain cooperative work owned above
+      // ShotRuntime, so it is a second exact gate. The three labels
+      // `externallyPending` excludes are internal handoff claims: draw/repaint
+      // belong to the presentation now executing, while instance-map identity
+      // is checked directly by StageApp before it calls `present` and releases
+      // in the parent layout effect after this child draw.
+      if (externallyPending()) {
+        performanceTelemetry.present(info, document);
+        return;
+      }
+      const canvas = exportCanvas;
+      if (
+        canvas === null ||
+        canvas.width !== pending.width ||
+        canvas.height !== pending.height ||
+        exportArea?.getAttribute("data-export-frame") !== String(pending.frame)
+      ) {
+        // ResizeObserver and the r3f commit can land separately. Keep the arm
+        // until a later matching presentation proves both framing and pixels.
+        performanceTelemetry.present(info, document);
+        return;
+      }
+      pending.snapshotting = true;
+      try {
+        // Invocation, not only resolution, stays in ShotRuntime's onPresented
+        // call stack. createImageBitmap snapshots the unpreserved default
+        // framebuffer before Chromium can present and retire it.
+        void pending.snapshot(canvas).then(
+          (bitmap) => {
+            if (pendingCapture !== pending) {
+              // Cancellation rejects the controller immediately, but the
+              // browser may still finish a createImageBitmap already in
+              // flight. It must not escape or remain live after refusal.
+              bitmap.close();
+              return;
+            }
+            pendingCapture = null;
+            pending.resolve(bitmap);
+          },
+          (error) => {
+            if (pendingCapture !== pending) return;
+            pendingCapture = null;
+            pending.reject(error);
+          },
+        );
+      } catch (error) {
+        if (pendingCapture === pending) {
+          pendingCapture = null;
+          pending.reject(error);
+        }
+      }
+      // Snapshot INVOCATION comes first. Rich telemetry can fingerprint,
+      // allocate a sample row, and notify diagnostic listeners; none of that
+      // belongs between the GL draw and an unpreserved framebuffer read.
+      performanceTelemetry.present(info, document);
+    },
     getState: () => state,
     subscribe(listener) {
       listeners.add(listener);
       return () => listeners.delete(listener);
     },
     handlers: () => handlers,
+    setInstanceErrors(errors) {
+      instanceErrors = [...errors];
+      refuseArmedCapture();
+      notifyHealth();
+    },
+    setInstanceCrashes(errors) {
+      instanceCrashes = [...errors];
+      refuseArmedCapture();
+      notifyHealth();
+    },
+    setFatalError(message) {
+      fatalError = message.trim() === "" ? "unknown stage error" : message;
+      refuseArmedCapture();
+      notifyHealth();
+      queueBusy();
+    },
+    setRenderErrors(errors, blocked = false) {
+      renderErrors = [...errors];
+      compileBlocked = blocked;
+      refuseArmedCapture();
+      notifyHealth();
+      queueBusy();
+    },
+    setPieceFailures(failures) {
+      pieceFailures = [...failures];
+      // Before the chrome hears it: its handler can start other work.
+      refuseArmedCapture();
+      handlers?.onPieceFailures(pieceFailures);
+      notifyHealth();
+    },
+    pieceFailures: () => pieceFailures,
+    recordError,
+    setHoverSink(sink) {
+      hoverSink = sink;
+    },
     setQuadSource(source) {
       quadSource = source;
     },
+    setNodePreviewSource(source) {
+      nodePreviewSource = source;
+    },
+    setCoverageProbe(probe) {
+      coverageProbe = probe;
+    },
     setFitter(fit) {
       fitter = fit;
     },
+    setDesignPointer(source) {
+      designPointer = source;
+    },
     setWorkingFitter(fit) {
       workingFitter = fit;
     },
+    setExportArea(el) {
+      exportArea = el;
+    },
+    setExportCanvas(canvas, isContextLost) {
+      if (isContextLost === undefined) registerExportCanvas(canvas);
+      else registerExportCanvas(canvas, isContextLost);
+    },
     setDisposer(fn) {
       dispose = fn;
     },
+    yieldPoster() {
+      return yieldPoster() !== null;
+    },
+    passDrawing: () => state.passDrawing,
+    registerFreezeHost(el) {
+      if (el === freezeHost) return;
+      // The frozen picture lived in the old host and went with it.
+      if (freezeHost !== null) {
+        preparing?.end(null);
+        dropFreeze();
+      }
+      freezeHost = el;
+    },
+    setInteractionProbe(probe) {
+      interactionProbe = probe;
+    },
+    yieldToInteraction() {
+      preparing?.end("interaction");
+    },
+    setRasterScale(scale) {
+      rasterScale = scale;
+    },
   };
 }
 
+/** One fatal-stage path shared by the root boundary and its integration test.
+ * The export refusal must be installed before chrome reporting, because the
+ * handler can synchronously start other work in response to the error. */
+export function reportFatalStage(client: StageClient, message: string): void {
+  client.setFatalError(message);
+  client.handlers()?.onError(`stage crashed: ${message}`);
+}
+
 /** The scene holding a layer, or null. Exported for the isolation guard and for
  *  the stage's own scoping — "is this id still real" is the question both ask,
  *  and a second implementation of it is how the two drift. */
@@ -276,3 +2743,17 @@ export function sceneWithLayer(doc: Doc3D, layerId: string | null): Scene3D | nu
   }
   return null;
 }
+
+/** Material preview also supports a mesh inside an opened component
+ * definition. Layer ids are document-global, so a linear container walk is a
+ * complete lookup and avoids teaching the stage bridge about chrome context. */
+function materialPreviewStillReal(doc: Doc3D, layerId: string | null): layerId is string {
+  if (layerId === null) return false;
+  for (const scene of Object.values(doc.scenesById)) {
+    if (scene.layersById[layerId]?.kind === "mesh") return true;
+  }
+  for (const def of Object.values(doc.components ?? {})) {
+    if (def.layersById[layerId]?.kind === "mesh") return true;
+  }
+  return false;
+}