@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/bridgeTypes.ts

@@ -21,7 +21,34 @@
 // `three`. The stage PROJECTS; the chrome receives screen-space numbers as
 // plain data. test/sourceHygiene.test.ts is the gate, and the temptation it
 // exists to catch is importing `Vector3` "just for the projection maths".
-import type { Doc3D, FramingDelta, GestureDelta, GestureKind, PathData, SnapGuide } from "@dailies-studio/shot/doc";
+import type {
+  CameraGate,
+  CoverageRequest,
+  Doc3D,
+  ExportFormat,
+  FramingDelta,
+  GestureDelta,
+  GestureKind,
+  MeshMaterialSlotInfo,
+  MotionPresetRequest,
+  PathData,
+  PieceFailure,
+  SnapGuide,
+  SplinePoint3D,
+  StageCoverage,
+  StageHealthSnapshot,
+} from "@dailies-studio/shot/doc";
+// Tier-1 export speaks the shared wire protocol's capability shape verbatim —
+// no duplication needed here: both documents resolve the SAME package, so this
+// is one definition, not a copy (the motion editor duplicates because it sits
+// across a package boundary; this file does not).
+import type { Mp4Encoding, Tier1Capability } from "@dailies-studio/shot/tier1";
+// Engine `Value` only — the wire shape of an instance prop. Type-only and
+// three-free, the same import the instance inspector makes.
+import type { Value } from "@dailies-studio/engine";
+// A component's contract types an `instance.props.<key>` key (Count up), and
+// the stage has no registry of its own to read one from.
+import type { Contract } from "@dailies-studio/contract";
 // ONE definition of the tool union, in the table that also answers what each
 // tool's key, surface, cursor and draw behaviour are. Re-exported here so the
 // stage can take the protocol from one import.
@@ -47,9 +74,10 @@ export type { ShadingMode, StageLayout, StagePane, WorkingView };
  *  for a working pane would get a silently unchanged camera pane — exactly the
  *  half-working state the refusal exists for.
  *
- *  3: the camera lane. A v2 stage has no `setCameraFollowsView`, so a v3 chrome
- *  turning follow on would throw inside the push and, worse, would show its
- *  armed button over a pane that is not following anything.
+ *  3: the camera lane. A v2 stage had no `setCameraFollowsView` (v29's
+ *  `setPilot` now), so a v3 chrome turning follow on would throw inside the
+ *  push and, worse, would show its armed button over a pane that is not
+ *  following anything.
  *
  *  4: `onWorkingViewChange` carries a WorkingViewOrigin. A v3 stage sends none,
  *  so every one of its view changes reads as "the author moved the view" — and
@@ -114,8 +142,715 @@ export type { ShadingMode, StageLayout, StagePane, WorkingView };
  *  that never appears on a toon mesh, and an outliner whose triangle budget
  *  reports an empty scene however heavy the models are. Nothing throws and
  *  nothing is wrong on screen; the author simply believes three features are
- *  broken and one number is true. */
-export const SHOT_BRIDGE_VERSION = 11;
+ *  broken and one number is true.
+ *
+ *  12: `exportCapability` and `exportMovie` — Tier-1 in-browser export, and
+ *  the bridge's first Promise-returning members (same-origin, so the promise
+ *  and the finished Blob cross as plain references). A v11 stage under a v12
+ *  chrome throws "exportMovie is not a function" the moment the dialog's
+ *  browser path runs; the gate turns that into the rebuild message at
+ *  connect.
+ *
+ *  13: `capturePoster` — the dashboard's card thumbnail, read off the live GL
+ *  canvas. A v12 stage under a v13 chrome would simply never produce a
+ *  poster, which is the quietest possible failure (a gradient placeholder
+ *  forever, and nothing in the console); the version gate turns it into the
+ *  rebuild message instead.
+ *
+ *  14: `setComponentContext` — the component context (unify P2). A v13 stage
+ *  has no verb, so a v14 chrome entering a definition would throw inside the
+ *  push; and the quiet direction is worse: the chrome's outline, dock and
+ *  inspector would all address the definition while the stage kept rendering
+ *  the SCENE at master time — every def-local seek the dock issues would
+ *  scrub the scene instead, and a pick would land on layers the chrome
+ *  considers out of scope. `seek` also changes MEANING under a context
+ *  (def-local frames), which no optional-feature fallback can express.
+ *
+ *  15: 3D spline authoring. Work-plane state, spline drafts, point-edit
+ *  gestures and projected non-quad selection shapes all cross the bridge. A
+ *  v14 stage would leave Shift+P armed over an orbiting pane and a v14 chrome
+ *  would ignore the point edits a v15 stage emits, so neither direction has a
+ *  truthful optional fallback.
+ *
+ *  16: material-workspace preview ownership and shader compile diagnostics.
+ *  The stage must stop scene picking/transforms while the graph owns the
+ *  pointer, and the chrome must distinguish a last-good preview from a graph
+ *  the GPU rejected. A v15 half would silently violate one of those claims.
+ *
+ *  17: material SLOTS and node PREVIEWS. `setMaterialPreview` addresses a
+ *  submesh slot rather than a whole layer, `onMaterialCompile` reports per
+ *  slot, `onMeshMaterialSlots` pushes the parsed glTF material list, and
+ *  `requestNodePreviews` answers with thumbnails. Neither half degrades
+ *  honestly: a v16 stage under a v17 chrome would leave the slot rail empty
+ *  forever and throw on a preview request, and a v17 stage under a v16 chrome
+ *  would call a slot handler that is not there from inside the model-load
+ *  effect.
+ *
+ *  18: `onFitRequest` — the stage asking the chrome to hand the camera back.
+ *  In the material workspace every drag orbits, and an orbited camera stays the
+ *  author's forever by design, so a double-click on the object is the gesture
+ *  that re-derives the head-on frame. It is stage -> chrome and fires from
+ *  inside a pointer lane, so a v18 stage under a v17 chrome throws mid-gesture
+ *  exactly as the version-11 handlers did.
+ *
+ *  19: `GestureDelta.suppressGuides` — the stage telling the chrome that CTRL
+ *  is held, so the smart guides step aside for a delta that is already on a
+ *  round number. Both halves fail silently without the bump, in opposite
+ *  directions and both invisibly: a v19 stage under a v18 chrome quantises the
+ *  emit and then has the guides pull it back off, so holding ctrl looks like it
+ *  does nothing at all; a v18 stage under a v19 chrome never sets the flag, so
+ *  the guides stay on and the same thing happens. There is no wrong PIXEL to
+ *  see either way — only a modifier that appears not to work — which is exactly
+ *  the class of mismatch a version gate exists to turn into a refusal.
+ *
+ *  20: `setPlaying` — the chrome telling the stage the transport is running, so
+ *  the stage can defer work that the next seek is about to redo anyway. A v19
+ *  stage under a v20 chrome simply never learns it is playing and behaves
+ *  exactly as it did at v19, which is why this bump is about honesty rather
+ *  than corruption: the mismatch costs performance, never pixels.
+ *
+ *  21: `ShotComponentContext.zoom` — the Studio's zoom over the definition's
+ *  head-on render. An additive optional field, and bumped anyway on version
+ *  19's rule: a v20 stage ignores it, so the chrome's zoom control moves a
+ *  number nothing on screen answers to. There is no wrong PIXEL to see, only a
+ *  control that appears not to work, which is exactly the class of mismatch
+ *  this gate exists to turn into a refusal rather than a support question.
+ *
+ *  22: `hoverLayer` and `setGridVisible`, one release. `hoverLayer` is the
+ *  chrome telling the stage which layer a timeline row under the cursor names,
+ *  so the stage lights that layer's outline without a click (and without
+ *  changing the selection) — imperative on the stage side (a feed write and
+ *  one SVG leaf repaint, zero GL draws — the reason it is NOT a state push).
+ *  `setGridVisible` toggles the working pane's grid floor, workspace state on
+ *  `setShadingMode`'s pattern. A v21 stage under a v22 chrome would throw on
+ *  either missing verb — hover on the first row crossing, grid on the first
+ *  toggle — which is version 18's mid-gesture failure class and exactly what
+ *  the gate refuses up front.
+ *
+ *  23: `ShotComponentContext` becomes a union, so the context can name a CODE
+ *  component ("<module>#<Export>") and not only an authored definition. A v22
+ *  stage handed a code context reads `ctx.def` as undefined, fails its own
+ *  "is this definition in the document" check and stores null: the chrome
+ *  enters the code studio, the stage keeps rendering the shot behind the hole,
+ *  and the author sees a panel over the wrong picture. A wrong PIXEL, which is
+ *  version 18's class and the reason this is a bump rather than an additive
+ *  field.
+ *
+ *  24: `onWaypointGesture`, the camera lane's second verb. A path move's
+ *  waypoints became grabbable in the working pane, and the drag rides the
+ *  EXISTING `onFramingGestureStart`/`End` bracket — one scrub, one undo entry —
+ *  but it writes a WAYPOINT rather than the framing, so it needs a message of
+ *  its own. A v23 chrome under a v24 stage would throw on the first waypoint
+ *  drag: version 22's missing-verb class, refused up front instead.
+ *
+ *  25: `onStageBusy`, the readiness lane. The chrome holds playback while the
+ *  stage is still loading (renderer init, fonts, textures, models), because
+ *  play against a scene that has not landed runs the clock over a blank
+ *  picture. A v24 stage under a v25 chrome never calls the handler, so the
+ *  chrome would read "ready" forever and the hold would silently not exist —
+ *  no wrong pixel, but a guard that is present in the source and absent in the
+ *  product, which is the worst of both. Refused up front instead.
+ *
+ *  26: `onPerformance`, the presentation readout. The stage already measures
+ *  what it PRESENTS, once a second, because the adaptive quality policy is
+ *  driven by it; the chrome had no way to read it, so the only number it could
+ *  have shown was its own seek cadence, and the stage coalesces requests and
+ *  drops publications precisely when the two diverge. A number that reads 60
+ *  while the picture runs at 18 is worse than no number. A v25 stage under a
+ *  v26 chrome never calls the handler, so the badge would simply never appear:
+ *  silent in the direction that looks like it works, which is version 25's
+ *  class exactly. Refused up front instead.
+ *
+ *  27: `ShotCodeContext.props`, the defaults rail's live preview. The code
+ *  studio's component face scrubs a contract default and the stage must show
+ *  it before the commit lands in source, so the override rides the context —
+ *  additive and optional, but bumped on v21's rule: a v26 stage's
+ *  `validComponentContext` REBUILDS the code arm as `{ code, zoom }` and
+ *  silently strips the field, so the rail's scrub would move a control
+ *  nothing on screen answers to. Refused up front instead.
+ *
+ *  28: `setVideo`, the watch-only frame. Video stopped being a pane layout and
+ *  became a flag over the picture, and the stage is where the flag does its
+ *  work: it empties the selection it draws furniture for, refuses every grab
+ *  and draw gesture, drops the hover raycast, and abandons a live modal, pen
+ *  or spline draft. A v27 stage under a v28 chrome never receives the message,
+ *  so it would keep drawing handles over a finished picture and keep taking
+ *  transform drags on it. An author "watching" would be editing by accident,
+ *  and nothing anywhere would say so. Silent in the direction that looks like
+ *  it works, which is version 25's class exactly. Refused up front instead.
+ *
+ *  29: the camera lane, made legible. `setPilot` replaces
+ *  `setCameraFollowsView`: piloting drives the shot camera from the CAMERA
+ *  pane's own navigation (orbit, pan, wheel) through the framing gesture lane,
+ *  where follow projected 3D-view orbits onto a camera that cannot tilt and
+ *  left the two panes disagreeing mid-drag. `setCameraGate` tells the stage
+ *  what a camera write would do at the playhead, so the gizmo dims and the
+ *  press refuses BEFORE the drag instead of after it. `onFramingGesture` grew
+ *  an origin (a wheel has no release, so the chrome brackets it with silence)
+ *  and answers whether it wrote, so the badge can flash a refusal.
+ *  `onLeavePilot` is the badge's own EJECT, and `onCameraDriver` names the
+ *  component driving the render camera. A v28 stage under a v29 chrome throws
+ *  on the attach push (`setPilot`), and the quiet direction is worse: a v29
+ *  stage under a v28 chrome would keep the pane's wheel and drags on the
+ *  viewport while the badge said the camera was being piloted. Version 25's
+ *  class exactly. Refused up front instead.
+ *
+ *  30: `setStoryboardPreview`, the board's hole. The Storyboard used to be
+ *  chrome over an unchanged stage; it now leaves a `.stage-window` in its
+ *  bottom strip, and `measureInset` hands that rect down as the whole visible
+ *  stage. A v29 stage under a v30 chrome never receives the flag, so it would
+ *  keep the layout the author left behind it and draw selection handles,
+ *  gizmos and the grid into a 300px monitor. Worse, the picture there would be
+ *  whatever the stage was last framed at rather than the shot: the derived fit
+ *  rides this bit too. Silent in the direction that looks like it works, which
+ *  is version 28's class exactly. Refused up front instead.
+ *
+ *  31: `preparePlayback`, the preparing pass before Play. A v30 stage under a
+ *  v31 chrome has no such method, and a chrome that called it would throw on
+ *  every Play. Refused up front instead.
+ *
+ *  32: `captureFrame`, the storyboard's "Frame from Shot" drawn by the stage
+ *  itself, because the hosted editor has no server renderer to ask, and the
+ *  GIF export kind (`ShotExportMovieRequest.format`, `Tier1Capability.gif`).
+ *  A v31 stage has no `captureFrame`, so a v32 chrome would throw on every
+ *  capture; and it ignores `format`, so a GIF export would come back an MP4.
+ *  Refused up front instead.
+ *
+ *  33: `capturePoster` YIELDS and REMEMBERS. The chrome takes no lock for a
+ *  poster, so the stage now aborts one for anything the author starts on it
+ *  (Play, an export or `captureFrame`, a scrub, an edit, a press), and answers
+ *  null at once for a document whose capture failed. The chrome relies on
+ *  both: it asks again on every null. A v32 stage under it would re-run a
+ *  failing capture, up to a minute in export framing, on every ask, and an
+ *  export started mid-poster would refuse "already running". Refused up
+ *  front instead.
+ *
+ *  34: `onPieceFailures`, one broken piece isolated. The stage now draws the
+ *  rest of a Shot when a layer, a background, a post stack or a transition
+ *  throws, and sends the chrome the whole list of what it isolated (and
+ *  `loadDoc` carries the document's revision, stamped on each failure). A v33
+ *  chrome under a v34 stage has no such handler, so the one message that says
+ *  a piece is missing would throw from inside the stage's apply pass; a v33
+ *  stage under a v34 chrome never sends it, so a broken layer would read as a
+ *  healthy stage. Silent in the direction that looks like it works, version
+ *  25's class. Refused up front instead.
+ *
+ *  35: `health()` and `onStageHealth`, the stage reporting on itself to an
+ *  agent that cannot see it. `health()` answers what the stage holds (the
+ *  crash, a lost context, the isolated pieces, the render fallbacks, the
+ *  component failures, the uncaught errors of its document and its export
+ *  worker, and what it last PRESENTED: the saved revision, the module epoch,
+ *  the frame), and `onStageHealth` says it changed, never per frame. `loadDoc`
+ *  of the document already on stage now only records its revision, which is
+ *  how the chrome's own save marks the picture as that revision. A v34 stage
+ *  under a v35 chrome has no `health()`, so every MCP write would wait out
+ *  its check and answer "pending" over a stage that drew it; a v35 stage
+ *  under a v34 chrome calls a handler that is not there from inside its
+ *  presentation. Refused up front instead.
+ *
+ *  36: `coverage()`, which mesh-like layers put a pixel in the frame. A
+ *  write whose every piece drew can still show nothing of a model: a
+ *  gradient background drawn over it, a layer that paints over it, a camera
+ *  that does not see it. The stage now draws its frame offscreen, whole and
+ *  without each mesh, device or placed component layer, and says which of
+ *  them changed no pixel (shot stageCoverage.ts). A v35 stage under a v36
+ *  chrome has no `coverage()`, so every health report would say the layers
+ *  were not checked and an agent would learn to ignore it; a v36 stage under
+ *  a v35 chrome is never asked, which reads as a stage whose layers all
+ *  draw. Silent in the direction that looks like it works, version 25's
+ *  class. Refused up front instead.
+ *
+ *  37: `setBoardFrame`, the storyboard's Frame view framing the live stage:
+ *  a tag, a numbered dot on each pinned beat's layer, and an onion skin of
+ *  the previous still. Unlike `setStoryboardPreview` it keeps the stage
+ *  editable, so it fits the shot into the hole without hiding furniture or
+ *  refusing a click, and it parks every view gesture so the fit is the only
+ *  framing on screen. A v36 stage under a v37 chrome throws "setBoardFrame
+ *  is not a function" the moment the Frame view opens; a v37 stage under a
+ *  v36 chrome is never framed, so the board's window would show the
+ *  author's pan and zoom instead of the shot. Refused up front instead.
+ *
+ *  38: `editText` and `onTextEdit`, the stage's inline text editor. A Text
+ *  click inserts a layer and opens it for typing; a double-click on a text
+ *  layer opens it again. A v37 stage under a v38 chrome throws "editText is
+ *  not a function" on the first Text click; a v38 stage under a v37 chrome
+ *  calls a handler that is not there when the editor closes, and the words
+ *  are lost. Refused up front instead. Also `designPointAt`, the query a
+ *  drop on the frame converts its point through: a v37 stage under a v38
+ *  chrome throws "designPointAt is not a function" on the first drop. And
+ *  `onInstanceNaturalSize`, what a box-ignoring instance module draws: a v38
+ *  stage under a v37 chrome calls a handler that is not there on the first
+ *  placed component.
+ *
+ *  39: `exportMovie` takes a master `window`, the work area. A v38 stage
+ *  under a v39 chrome ignores the field and exports the whole film into a
+ *  file named for the work area, with audio cut to the window: silent in the
+ *  direction that looks like it works. Refused up front instead.
+ *
+ *  40: `onTextAutoSize`, an auto-width text box's measured size (`TextBox`).
+ *  A v40 stage under a v39 chrome calls a handler that is not there on the
+ *  first auto text box; a v39 stage under a v40 chrome never measures, so the
+ *  box keeps its click estimate. Refused up front instead.
+ *
+ *  41: `setReadOnly`, a viewer's stage. A v40 stage under a v41 chrome throws
+ *  "setReadOnly is not a function" on attach; a v41 stage under a v40 chrome
+ *  is never told, which is the editable stage it always was. Refused up front
+ *  instead.
+ *
+ *  42: Storyboard comments. `ShotBoardFrame` gains `pins` and `comment`, and
+ *  the handlers gain `onCommentAt` and `onCommentPin`. A v41 stage under a
+ *  v42 chrome draws no pins and never reports a comment click; a v42 stage
+ *  under a v41 chrome calls handlers that are not there. Refused up front
+ *  instead.
+ *
+ *  43: `setPeerSelections`, other people's selections (live collaboration,
+ *  R7). A v42 stage under a v43 chrome throws "setPeerSelections is not a
+ *  function" on the first peer; a v43 stage under a v42 chrome is never
+ *  told, so it draws no peer outlines. Refused up front instead.
+ *
+ *  44: Rulers, guides and the motion path key drag. The stage gains
+ *  `setEditorChrome` and `setMotionPaths`; the handlers gain the guide
+ *  gestures (`onGuideGestureStart`, `onGuideGesture`, `onGuideGestureEnd`,
+ *  `onGuideSet`, `onGuideRemove`) and the path key drag
+ *  (`onPathKeyGestureStart`, `onPathKeyGesture`, `onPathKeyGestureEnd`,
+ *  plus `onPathKeyDoubleClick` and `onContextMenu`'s optional `pathKey`), whose
+ *  `part` already names the Bezier handles so schema v40 needs no second
+ *  bump. A v43 stage under a v44 chrome throws "setEditorChrome is not a
+ *  function" on attach; a v44 stage under a v43 chrome calls guide handlers
+ *  that are not there on the first ruler drag. Refused up front instead.
+ *
+ *  45: The Components workspace's preview and Studio comments. Both arms of
+ *  `ShotComponentContext` gain `background` (dark, light or brand, drawn as
+ *  the working pane's clear colour) and `loopFrames` (the stage wraps every
+ *  seek inside the context to that length). The stage gains
+ *  `setStudioComments`, pins anchored to a Shot and a frame with no still,
+ *  and the handlers gain `onStudioCommentAt`. A v44 stage under a v45 chrome
+ *  throws "setStudioComments is not a function" on attach and ignores the
+ *  background and the loop; a v45 stage under a v44 chrome calls a handler
+ *  that is not there on the first Studio comment. Refused up front instead.
+ *  The board no longer frames the stage, so v45 also drops `setBoardFrame`
+ *  (v37) and `onCommentAt` (v42); the pins `ShotBoardPin` describes are the
+ *  Studio's now.
+ *
+ *  46: The Components props panel tries values without saving them.
+ *  `ShotDefContext` gains `props` (exposed key -> Value), drawn the way a
+ *  placement's overrides are. A v45 stage under a v46 chrome ignores them, so
+ *  the panel would show a tried value the preview never draws. Refused up
+ *  front instead.
+ *
+ *  47: The Studio's sketch guide. The stage gains `setSketchGuide`, one
+ *  storyboard sketch as plain shapes in design px, drawn as dashed outlines
+ *  over the camera frame. A v46 stage under a v47 chrome throws
+ *  "setSketchGuide is not a function" on attach. Refused up front instead.
+ *
+ *  48: A definition is authored only on the Components Edit tab.
+ *  `ShotDefContext` gains `edit`, and only then does the definition's one
+ *  pane take the authoring lanes (the draw tools, the pen, drops and the
+ *  Select grammar). The Preview tab shows the same definition and orbits.
+ *  A v47 stage under a v48 chrome would author on Preview too, so a drag
+ *  there moved the master definition. Refused up front instead.
+ *
+ *  49: `exportMovie` takes a `quantizer`, the quality's CRF as a fixed H.264
+ *  QP, and its result says how the encoder ran (`encoding`). A bitrate encode
+ *  can open soft (KAN-23), so the stage encodes at the QP wherever a hardware
+ *  encoder honours one. A v48 stage under a v49 chrome ignores the field and
+ *  silently ships the bitrate encode, and the dialog never learns which
+ *  encoder ran: silent in the direction that looks like it works, version
+ *  25's class. Refused up front instead.
+ *
+ *  50: The font picker's stage preview. The stage gains `setFontPreview`, a
+ *  font shown on some text layers without a document write. A v49 stage
+ *  under a v50 chrome throws "setFontPreview is not a function" on the first
+ *  hover in the picker. Refused up front instead.
+ *
+ *  51: Honest readiness, the queued Play, and background preparation that
+ *  runs. `onStageBusy` now says the stage owes the open subject its first
+ *  whole presentation, not that a load is open. `preparePlayback` loses
+ *  `background` and takes a `pace`, reports each frame's outcome, ends with
+ *  a reason (`yielded`, `refused`) and hands over on the start frame
+ *  (`handedOver`). The stage gains `preparationKey()` and `takePlayed()`. A
+ *  v50 stage under a v51 chrome would report busy for ordinary loads,
+ *  resolve before the start frame is presented, and ignore `pace`; a v51
+ *  stage under a v50 chrome would call `pace()` on a request that has none.
+ *  Refused up front instead.
+ *
+ *  52: The playback render scale's report and its preference. A played frame
+ *  may render below the display's density while the GPU cannot keep up (the
+ *  stage's renderScaleController.ts decides, on stage-local inputs), so
+ *  `StagePerformanceReport` gains `gpuMs` (the second's GPU p95, null without
+ *  a timer) and `renderScale` (the share of the display's density its last
+ *  frame rendered at), and `EditorChrome` gains `playbackResolution` (the
+ *  Preferences row: `auto`, `full` or `fast`). A v51 stage under a v52 chrome
+ *  sends neither field, and the fps chip reads both; a v52 stage under a v51
+ *  chrome is never told a mode, so it runs Auto, and the chip never says the
+ *  picture renders below the display's density: silent in the direction that
+ *  looks like it works, version 25's class. Refused up front instead.
+ *
+ *  53: The motion preset picker's stage preview. The stage gains
+ *  `setMotionPreview`, a preset's keys shown on some layers without a
+ *  document write, while the chrome seeks the stage through the preset's
+ *  frames. A v52 stage under a v53 chrome throws "setMotionPreview is not a
+ *  function" on the first hover in the Motion section. Refused up front
+ *  instead.
+ */
+export const SHOT_BRIDGE_VERSION = 53;
+
+/**
+ * A motion preset the Motion section shows on some layers before it is
+ * applied (bridge v53). Never written to a Doc3D. The stage stamps it on its
+ * own copy with the same `stampMotionPreset` a commit runs, so the preview is
+ * exactly the keys an apply writes.
+ */
+export interface ShotMotionPreview {
+  /** The container that holds the layers: the Shot's scene id, or the open
+   *  definition's id. */
+  containerId: string;
+  layerIds: readonly string[];
+  /** The stamp, `at` included (the chrome's playhead, container-local). */
+  request: MotionPresetRequest;
+  /** The registry's contracts for the placed components among `layerIds`,
+   *  by component id: what types a Count up's `instance.props.progress`. */
+  contracts?: Readonly<Record<string, Contract>>;
+}
+
+/** One file of a previewed face: a font url the stage loads itself, and the
+ *  characters it covers (a CSS `unicode-range`; absent, the whole file). */
+export interface ShotFontPreviewFace {
+  url: string;
+  unicodeRange?: string;
+}
+
+/** A font the font picker shows on some text layers before it is applied
+ *  (bridge v50). Never written to a Doc3D. */
+export interface ShotFontPreview {
+  /** The container that holds the layers: the Shot's scene id, or the open
+   *  definition's id. */
+  containerId: string;
+  /** The text layers that show the font. Other layers, and other kinds, are
+   *  left as they are. */
+  layerIds: readonly string[];
+  /** The family's display name, kept in the stack after the preview face. */
+  family: string;
+  /** The generic family drawn while the faces load, and where they have no
+   *  glyph (`sans-serif`, `serif`, `monospace`, `cursive`). */
+  fallback: string;
+  /** The style the faces are, which the layers draw in for the preview. */
+  style: "normal" | "italic";
+  /** The faces' `font-weight` descriptor range: a variable file's `wght`
+   *  axis, or `[1, 1000]` for one static file. Each layer keeps its own
+   *  weight, and the browser never synthesises bold over the range. */
+  weightRange: readonly [number, number];
+  /** The faces, the family's default subset first. The stage fetches every
+   *  one as soon as the preview arrives (a face joins the stage's font set
+   *  only once it has loaded), so list the files the layers' text needs
+   *  (`subsetsForText`), not each of the family's subsets. The same files,
+   *  style and weight range sent again keep the faces already loaded. */
+  faces: readonly ShotFontPreviewFace[];
+}
+
+/** The component preview's backdrop (bridge v45). `brand` is the Project's
+ *  first brand colour, and dark when it has none. */
+export type ShotComponentBackground = "dark" | "light" | "brand";
+
+/** The colour `brand` resolves to: the first colour row of the PROJECT's
+ *  branding, or null when it has none (the caller then draws dark). One rule
+ *  for both documents, so the stage and the board's card stage cannot pick
+ *  different rows. */
+export function brandBackdrop(doc: Pick<Doc3D, "resources"> | null): string | null {
+  for (const item of doc?.resources?.branding ?? []) {
+    if (item.type === "color" && /^#[0-9a-fA-F]{6}$/.test(item.value)) return item.value;
+  }
+  return null;
+}
+
+/** The most frames a preview loop may hold: ten minutes at 60 fps. A bound,
+ *  so a junk number cannot make the wrap a no-op that reads as a loop. */
+export const MAX_LOOP_FRAMES = 36_000;
+
+/** A Studio comment's place (bridge v45): a Shot, a Shot-local frame, the
+ *  topmost layer under the click, and the point as 0..1 of the frame rect.
+ *  No still: a Studio comment is left on the moving picture at a timecode. */
+export interface ShotStudioAnchor {
+  kind: "studio";
+  sceneId: string;
+  /** Shot-local, frames from the Shot's start. */
+  frame: number;
+  layerId: string | null;
+  u: number;
+  v: number;
+}
+
+/** One Studio comment pin (bridge v45). The stage draws it while stopped on
+ *  its anchor's Shot and frame, so the chrome sends every pin once rather
+ *  than re-pushing per frame. */
+export interface ShotStudioPin {
+  threadId: string;
+  anchor: ShotStudioAnchor;
+  /** As `ShotBoardPin`. */
+  initials: string;
+  color: string;
+  active: boolean;
+  label: string;
+}
+
+/** What the Studio's comment layer lays over the camera pane (bridge v45).
+ *  See `setStudioComments`. */
+export interface ShotStudioComments {
+  pins: readonly ShotStudioPin[];
+  /** The comment tool is armed: a primary click on the camera frame is
+   *  `onStudioCommentAt` instead of a pick. */
+  armed: boolean;
+}
+
+/** One outline of the Studio's sketch guide (bridge v47): a sketch item's
+ *  box in design px, `at` its centre (origin at the canvas centre, +y down,
+ *  the layer units), with its corner radius and its label chip. */
+export interface ShotSketchGuideRect {
+  at: readonly [number, number];
+  size: readonly [number, number];
+  /** Corner radius, design px; absent is square. */
+  radius?: number;
+  label?: string;
+}
+
+/** A sketch arrow (bridge v47): a motion note, drawn from `from` to `to`. */
+export interface ShotSketchGuideArrow {
+  from: readonly [number, number];
+  to: readonly [number, number];
+  label?: string;
+}
+
+/** THE SKETCH GUIDE (bridge v47): what "Guide: Sketch N" draws over the
+ *  camera frame. Plain shapes, so the stage needs no storyboard code. */
+export interface ShotSketchGuide {
+  rects: readonly ShotSketchGuideRect[];
+  arrows: readonly ShotSketchGuideArrow[];
+}
+
+/** The most shapes a guide carries: a sketch's own item limit, with room
+ *  for nothing more. A bound, so a junk message cannot flood the overlay. */
+export const MAX_SKETCH_GUIDE_SHAPES = 32;
+
+/** One other person's selection (bridge v43): outlined in their colour with
+ *  their name, under this tab's own selection, and never clickable. */
+export interface ShotPeerSelection {
+  ids: readonly string[];
+  name: string;
+  /** `#rrggbb`. */
+  color: string;
+}
+
+/** One comment pin as the stage draws it on the camera pane's frame
+ *  (bridge v42; the Studio's pins from v45). */
+export interface ShotBoardPin {
+  threadId: string;
+  /** Where on the picture, 0..1 across and down the frame rect. */
+  u: number;
+  v: number;
+  /** Up to two letters, the thread author's initials. */
+  initials: string;
+  /** The author's colour, a hex string: the stage has no chrome tokens. */
+  color: string;
+  /** The open thread's pin, drawn with a ring. */
+  active: boolean;
+  /** The pin's accessible name. */
+  label: string;
+}
+
+/**
+ * One piece the stage isolated: which kind (a layer, a placed code component,
+ * a layer inside a component definition, a Shot's background, its post stack,
+ * a transition), where (the Shot, the layer, the field when known), what it
+ * threw, and the frame and document revision it was first seen at. The
+ * runtime's own record (`PieceFailure`, pieceFailures.ts), verbatim.
+ */
+export type StagePieceFailure = PieceFailure;
+
+/** What the stage's shader compiler most recently established for one graph.
+ * It is live runtime state, never persisted with the material definition.
+ *
+ * `slot` is the glTF material index the report is about, or null for the
+ * layer-wide binding. A model with a Glass slot over a Studio base compiles two
+ * materials and can fail at exactly one of them, so a diagnostic that named
+ * only the layer would put a red badge on a graph that is fine. */
+export type MaterialCompileDiagnostic =
+  | { status: "compiling"; materialId: string; layerId: string; slot: number | null }
+  | { status: "ready"; materialId: string; layerId: string; slot: number | null }
+  | { status: "error"; materialId: string; layerId: string; slot: number | null; message: string };
+
+/**
+ * WHICH SURFACE the material workspace is editing.
+ *
+ * `slot: null` is the layer-wide binding — the whole model, and the only
+ * possibility for a primitive. A number is a glTF material index, stable
+ * because an asset id is a content hash (see `materialSlots.ts`).
+ */
+export interface MaterialPreviewTarget {
+  layerId: string;
+  slot: number | null;
+}
+
+/** The chrome's ask for a batch of node thumbnails. */
+export interface NodePreviewRequest {
+  materialId: string;
+  layerId: string;
+  slot: number | null;
+  /** The VIEWPORT-VISIBLE nodes only, chosen by the chrome. The stage clamps
+   *  to `MAX_NODE_PREVIEWS` rather than refusing, because a request that is one
+   *  node too long is a scroll position, not a bug. */
+  nodeIds: readonly string[];
+  /** Thumbnail edge in device px, clamped to [32, 256]. */
+  size: number;
+}
+
+export type NodePreviewResult =
+  | { nodeId: string; bitmap: ImageBitmap; message?: undefined }
+  | { nodeId: string; bitmap: null; message: string };
+
+export interface NodePreviewBatch {
+  materialId: string;
+  /** The graph the stage actually drew. The chrome drops a batch whose
+   *  signature is no longer current rather than painting a stale thumbnail
+   *  over a graph the author has since edited. */
+  semanticSignature: string;
+  size: number;
+  results: readonly NodePreviewResult[];
+}
+
+/** One atlas readback is one GPU stall, so the batch is bounded. 64 cells at
+ *  96px is a 768x768 target, which is cheaper than the graph it describes. */
+export const MAX_NODE_PREVIEWS = 64;
+
+/**
+ * The stage's component context: render ONE component standalone.
+ *
+ * The subject mounts on its own canvas (drawn as a plate over the working
+ * pane's clay backdrop, no scene, no post stack, no scene camera), and while a
+ * context is set the frames the chrome pushes through `seek` are SUBJECT-LOCAL
+ * (0 = the subject's own start).
+ *
+ * TWO SUBJECTS, ONE CONTEXT (v23). A shot places two things that are both
+ * called "component": an authored definition in `doc.components`, and a code
+ * component from the author's repo placed as an `instance` layer. Only the
+ * first could ever be opened, because only the first had something for the
+ * stage to render. The `code` arm gives the second one a subject too, and it
+ * does so WITHOUT a second render path: the stage builds a synthetic
+ * definition holding one instance of that component at contract defaults
+ * (`codePreviewDef`), so both arms land in the same mount.
+ *
+ * The zoom is on both arms; everything else differs, which is why this is a
+ * union and not one interface with optional halves.
+ */
+export type ShotComponentContext = ShotDefContext | ShotCodeContext;
+
+/** A definition the loaded document holds. */
+export interface ShotDefContext {
+  /** A `cmp_` id in the loaded document. */
+  def: string;
+  /**
+   * The chrome's zoom over the head-on render: 1 fits the whole canvas, 2
+   * shows it twice as large. Absent = 1.
+   *
+   * IT CROSSES AS A NUMBER AND NOT AS A CAMERA, because the frame is derived
+   * on the stage side (`componentFrame(size)`) and only the stage knows the
+   * pane it has to fit into. The zoom scales that frame's half-extents before
+   * the fit, so the "honest visible rect" promise the derived rig makes holds
+   * at every magnification instead of only at 1.
+   */
+  zoom?: number;
+  /** The preview's backdrop (v45), the working pane's clear colour. Absent =
+   *  the working pane's own token, as before v45. */
+  background?: ShotComponentBackground;
+  /** The preview loop's length in frames (v45): every seek inside the
+   *  context wraps to `frame % loopFrames`. Absent = no wrap. */
+  loopFrames?: number;
+  /** TRIED values from the Components props panel (v46), exposed key ->
+   *  Value, drawn exactly as a placement's overrides are. Editor-only and
+   *  never persisted: "Apply to all instances" is what writes the definition.
+   *  Absent or empty = the definition's own values. */
+  props?: Readonly<Record<string, Value>>;
+  /** True on the Components Edit tab (v48): the definition is being authored,
+   *  so its one pane is the frame the draw tools, the pen, drops and the
+   *  Select grammar map through. Absent on the Preview tab, which only views
+   *  the definition: a drag there orbits and nothing on it writes the master. */
+  edit?: true;
+}
+
+/**
+ * A code component from the author's repo, by REGISTRY ID.
+ *
+ * The id is all that crosses. The stage rebuilds the subject from it with the
+ * same pure function the chrome would, so the two sides cannot hold different
+ * subjects for one id, and a document is not involved at all: a code component
+ * can be opened from any context, including one where nothing places it.
+ */
+export interface ShotCodeContext {
+  /** "<module>#<Export>", the registry id and `ComponentRow.id`. */
+  code: string;
+  /** As `ShotDefContext.zoom`. */
+  zoom?: number;
+  /** As `ShotDefContext.background` (v45). */
+  background?: ShotComponentBackground;
+  /** As `ShotDefContext.loopFrames` (v45). */
+  loopFrames?: number;
+  /**
+   * Live default OVERRIDES from the defaults rail, contract KEY -> engine
+   * Value (curve/gradient as their encoded strings, `instance.props`' own
+   * form — `buildProps` decodes). Absent or empty = every prop at its
+   * declared default, exactly the v23 behaviour.
+   *
+   * EDITOR-ONLY, NEVER PERSISTED: the stage merges these over the synthetic
+   * preview instance's props for THIS render; committing a value goes through
+   * the defaults-persist API and lands in source, at which point the chrome
+   * drops the override. The def identity stays stable — only the props map
+   * changes — so nothing remounts under a scrub.
+   */
+  props?: Readonly<Record<string, Value>>;
+}
+
+/** `ShotCodeContext.props` values a stage may accept from a chrome: finite
+ *  numbers, strings, booleans, and finite numeric tuples of 2..4 — the wire
+ *  shapes of every animatable contract kind. Anything else is DROPPED, not
+ *  refused: one malformed key must not blank an otherwise valid preview.
+ *  Returns undefined when nothing survives, so the caller can omit the field
+ *  entirely and keep the v23 object shape.
+ *
+ *  KNOWN CEILING: a string on a curve/gradient KEY is decoded by `buildProps`
+ *  inside the render, and an undecodable one throws there — the same refusal
+ *  a corrupt document value has always produced. This validator cannot see
+ *  contract kinds, so it cannot close that; the shipped rail closes it by
+ *  construction (it validates + encodes composite values before they reach
+ *  the bridge), and any other chrome owes the same care. */
+export function validPreviewProps(raw: unknown): Record<string, Value> | undefined {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined;
+  const out: Record<string, Value> = {};
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof value === "string" || typeof value === "boolean") {
+      out[key] = value;
+      continue;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      out[key] = value;
+      continue;
+    }
+    if (
+      Array.isArray(value) &&
+      value.length >= 2 &&
+      value.length <= 4 &&
+      value.every((n) => typeof n === "number" && Number.isFinite(n))
+    ) {
+      out[key] = value as Value;
+    }
+  }
+  return Object.keys(out).length === 0 ? undefined : out;
+}
+
+/** The subject a context names, for callers that only need to tell one context
+ *  from another: the fake bridge's log line, and the stage's own re-push
+ *  equality check. */
+export function componentContextSubject(ctx: ShotComponentContext): string {
+  return "code" in ctx ? ctx.code : ctx.def;
+}
 
 /** What the stage reports once it has a renderer and a document. */
 export interface ShotStageInfo {
@@ -130,6 +865,37 @@ export interface ShotStageInfo {
   backend: string;
 }
 
+/** One second of presentation, as the stage measured it.
+ *
+ * `expectedFrames` is what the document's rate asked for over the same window,
+ * so a reader can say "28 of 30" rather than only "28" — the pair is what makes
+ * the number judgeable. */
+export interface StagePerformanceReport {
+  presentedFps: number;
+  expectedFps: number;
+  droppedPublications: number;
+  /** The GPU's own time per frame over the same second, its p95 in ms (v52),
+   *  off three's timestamp queries: render passes only, so an upload or a
+   *  compile is not in it (the stage's gpuTimer.ts). Null when the renderer
+   *  has no timer or no frame's time landed in the window. */
+  gpuMs: number | null;
+  /** The share of the display's density the window's last frame rendered at
+   *  (v52): 1, or a step below it while the playback render scale holds one
+   *  (the stage's renderScaleController.ts). The canvas itself never resizes. */
+  renderScale: number;
+}
+
+/** The Preferences row "Playback resolution" (v52). `auto` lets the stage
+ *  render a played frame below the display's density while the GPU cannot
+ *  keep up, `full` never does, and `fast` starts at 0.7 of it and never goes
+ *  above. Paused frames, stills and exports are always at full density. */
+export const PLAYBACK_RESOLUTIONS = ["auto", "full", "fast"] as const;
+export type PlaybackResolution = (typeof PLAYBACK_RESOLUTIONS)[number];
+
+export function isPlaybackResolution(value: unknown): value is PlaybackResolution {
+  return (PLAYBACK_RESOLUTIONS as readonly unknown[]).includes(value);
+}
+
 /** A screen-space quad for one layer: TL, TR, BR, BL as x,y pairs, in CSS
  *  pixels relative to the stage viewport's top-left.
  *
@@ -141,6 +907,82 @@ export interface ShotScreenQuad {
   pts: readonly [number, number, number, number, number, number, number, number];
 }
 
+/** Editor-only construction plane. `selection` means the named layer's local
+ *  XY plane, and falls back visibly to world XY when the layer disappears. */
+export type WorkPlaneTarget =
+  | { kind: "xy" | "xz" | "yz" | "view" }
+  | { kind: "selection"; layerId: string };
+
+/** A work plane resolved into design coordinates (+Y down, +Z away). */
+export interface ResolvedWorkPlane {
+  target: WorkPlaneTarget;
+  origin: readonly [number, number, number];
+  xAxis: readonly [number, number, number];
+  yAxis: readonly [number, number, number];
+  normal: readonly [number, number, number];
+  fallback: boolean;
+}
+
+/** The stage's world-space draft. The chrome recentres it into one spline
+ *  layer at commit, assigning stable point ids in the process. */
+export interface SplineCreateDraft {
+  basis: SplineBasis;
+  closed: boolean;
+  points: readonly SplinePoint3D[];
+}
+
+/** The interpolation new spline drafts use. Workspace state, never document data. */
+export type SplineBasis = "bezier" | "catmull-rom";
+
+export type SplinePointPart = "anchor" | "in" | "out";
+
+/** Which part of a motion path key a drag holds (v44): the key's own dot, or
+ *  one of its spatial Bezier handles (schema v40). The chrome refuses `"in"`
+ *  and `"out"` off a bezier path, and on the side no segment uses. */
+export type PathKeyPart = "key" | "in" | "out";
+
+/** A path key drag's offset from where it started, in the layer's stored
+ *  position units: parent space, +y DOWN, +z away, the numbers the
+ *  inspector's Position row shows. The stage measures
+ *  the whole drag, never a step, so a dropped event loses nothing. */
+export interface PathKeyDelta {
+  dx: number;
+  dy: number;
+  dz: number;
+  /** A handle drag only (Alt): move this handle alone. Without it the chrome
+   *  turns the opposite handle to stay in line, keeping its length. Read per
+   *  move, so the pair can break mid-drag. */
+  breakPair?: boolean;
+}
+
+/** The per-viewer preferences the stage acts on: its furniture (v44) and the
+ *  playback resolution (v52). */
+export interface EditorChrome {
+  /** Rulers along the camera pane's top and left edges. */
+  rulers: boolean;
+  /** Smart guides: a dragged guide snaps to the frame's edges and centre. */
+  smartGuides: boolean;
+  /** What a played frame may render at (v52, `PlaybackResolution`). It moves
+   *  no furniture and ends no preparing pass, which draws at full density. */
+  playbackResolution: PlaybackResolution;
+}
+
+/** How a guide drag ended (v44). `"remove"` is a guide dragged back onto its
+ *  ruler; a guide created from the ruler and dropped there is never added. */
+export type GuideGestureOutcome = "commit" | "remove" | "cancel";
+
+export interface SplineEditContext {
+  layerId: string;
+  selectedPointIds: readonly string[];
+}
+
+export interface SplinePointPatch {
+  layerId: string;
+  pointId: string;
+  part: SplinePointPart;
+  value: readonly [number, number, number];
+}
+
 /** The stage's view of the working area: how much of the frame is on screen and
  *  where. Owned by the stage (it is a camera `setViewOffset`), mirrored to the
  *  chrome so the zoom readout and "fit" have something to read and write. */
@@ -178,6 +1020,71 @@ export interface ShotBridgeHandlers {
   onReady(info: ShotStageInfo): void;
   /** The stage failed in a way the author needs to see. */
   onError(message: string): void;
+  /**
+   * The stage still OWES THE OPEN SUBJECT its first whole presentation, or no
+   * longer does (v51).
+   *
+   * The subject is what the stage shows: the Project (`doc.id`), a component
+   * context, or a material preview's layer and slot. A whole presentation is
+   * a clock echo of the current subject, drawn with no external readiness
+   * claim open and every placed component's module installed. Once this
+   * renderer has drawn one, the subject is latched and loads no longer make
+   * the stage busy: a font, a texture, a model or a paused video seek arriving
+   * later holds nothing. A new subject, a new renderer (a new export canvas)
+   * or a new stage document owes one again.
+   *
+   * A PAUSED VIDEO SEEK holds the subject's FIRST whole presentation only. It
+   * never holds again after that, and the latch never re-arms on Pause.
+   *
+   * False with no document, and false while the stage cannot present at all
+   * (a fatal error, a lost context, a renderer compile failure), so nothing
+   * waits on it for ever. A standing fallback (a texture, html, font or glyph
+   * failure) does not release the hold: the stage still presents, so the
+   * latch closes anyway.
+   *
+   * Sent on connect and then on every CHANGE of the value, coalesced to a
+   * microtask and deduped stage-side.
+   *
+   * THIS IS NOT THE EXPORT GATE'S QUESTION. A capture waits on every external
+   * claim at every frame it takes, a paused video seek included. See
+   * `bridgeClient.ts`.
+   */
+  onStageBusy(pending: boolean): void;
+  /**
+   * The pieces the stage isolated (v34), WHOLE, on every change: a layer, a
+   * background, a post stack or a transition that threw while the rest of the
+   * Shot kept drawing. Empty once every piece renders again. Sent from inside
+   * the stage's apply pass, so it must not throw.
+   *
+   * The same list refuses an exact export or still of any frame a listed piece
+   * belongs to, by name (the stage's own gate, `bridgeClient.ts`).
+   */
+  onPieceFailures(failures: readonly StagePieceFailure[]): void;
+  /**
+   * What `health()` answers changed (v35): a presentation of another
+   * document, revision or module epoch, a piece, a render fallback, a
+   * component failure, the crash, or an uncaught error. Also sent when
+   * `preparationKey().base` moves (v51), so a chrome with nothing left to
+   * prepare looks again. No payload: the chrome reads `health()` when it
+   * wants the answer, which is when an agent asks. Never per frame. Sent from
+   * inside the stage's presentation, so it must not throw.
+   */
+  onStageHealth(): void;
+  /**
+   * What the stage PRESENTED over the last second, or null once it stops.
+   *
+   * Sent once per closed telemetry window, and windows roll only during
+   * playback, so this is 1Hz while playing and silent otherwise. Null on pause
+   * is a retraction rather than a zero: no frames are expected of a stopped
+   * stage, and 0 fps would read as a stall.
+   *
+   * It has to come from the stage. The chrome knows what it ASKED for, and the
+   * stage coalesces requests and drops publications exactly when the ask and
+   * the picture come apart, which is the only time the number is interesting.
+   */
+  onPerformance(report: StagePerformanceReport | null): void;
+  /** The real stage is the material specimen; report what its compiler did. */
+  onMaterialCompile(diagnostic: MaterialCompileDiagnostic): void;
   /**
    * A pick, in DOCUMENT order front-to-back — the WHOLE ordered hit list, not
    * just the nearest.
@@ -202,6 +1109,10 @@ export interface ShotBridgeHandlers {
    * isolation stack, and then two places would decide what entering means.
    */
   onEnterLayer(hits: readonly string[], pane: StagePane): void;
+  /** The inline text editor closed with this content (v38). One edit, by id:
+   *  a click outside can move the selection before the editor's blur lands.
+   *  Empty (or blank) content removes the layer. */
+  onTextEdit(layerId: string, content: string): void;
   /**
    * A RIGHT PRESS: the same ordered hit stack `onPick` sends, plus the point to
    * open a menu at.
@@ -214,8 +1125,16 @@ export interface ShotBridgeHandlers {
    * `at` is in CLIENT coordinates and needs no translation: the stage iframe is
    * `position: fixed; inset: 0`, so a point in the stage's document is the same
    * point in the chrome's.
+   *
+   * `pathKey` (v44) is the motion path key dot under the press, when there is
+   * one: the menu is then that key's (seek, curved path, delete).
    */
-  onContextMenu(hits: readonly string[], pane: StagePane, at: { x: number; y: number }): void;
+  onContextMenu(
+    hits: readonly string[],
+    pane: StagePane,
+    at: { x: number; y: number },
+    pathKey?: { layerId: string; keyId: string },
+  ): void;
   /**
    * A mesh layer's triangle count, once its model has loaded — or null when the
    * layer unmounts or its model is swapped.
@@ -229,6 +1148,37 @@ export interface ShotBridgeHandlers {
    * heavy scene, and neither half can read a `BufferGeometry`.
    */
   onMeshStats(layerId: string, triangles: number | null): void;
+  /**
+   * The glTF materials a model actually ships, pushed once when it parses.
+   *
+   * The same "known exactly once, at parse" argument `onMeshStats` makes: a
+   * material's index, name, colour and map set live in the FILE, not in the
+   * document, so no amount of reading `Doc3D` tells the chrome that slot 3 is
+   * called "Screen" and carries a base-colour map. Without it the slot rail
+   * could only offer bare indices.
+   *
+   * `null` on unmount or a model swap, so a stale list never outlives the
+   * model it described.
+   */
+  onMeshMaterialSlots(layerId: string, slots: readonly MeshMaterialSlotInfo[] | null): void;
+  /**
+   * What an instance module that never read its box draws at scale 1, design
+   * px (v38): pushed once after its first commit while the layer has no
+   * `instance.naturalSize`. The chrome stores it only for a component it just
+   * placed, and sets the box to it in the same history entry (F41).
+   */
+  onInstanceNaturalSize(layerId: string, size: readonly [number, number]): void;
+  /** An auto-width text box's measured size, design px (v40, `autoTextSize`):
+   *  pushed when the stored `transform.size` is off. The chrome writes it in
+   *  the current history entry, keeping the box's aligned edge. */
+  onTextAutoSize(layerId: string, size: readonly [number, number]): void;
+  /** A comment pin was clicked (v42): from v45, a Studio pin on the camera
+   *  pane. */
+  onCommentPin(threadId: string): void;
+  /** A click on the camera frame with the Studio comment tool armed (v45):
+   *  the Shot and Shot-local frame on screen, the point, and the topmost
+   *  layer under it. */
+  onStudioCommentAt(anchor: ShotStudioAnchor): void;
   /**
    * The key-light gizmo's drag, as the same three-call shape every other
    * gesture uses: open a scrub, re-derive from its base on every emit, commit
@@ -271,6 +1221,23 @@ export interface ShotBridgeHandlers {
    * view change is a mirror the chrome is free to throttle.
    */
   onIsolationOrbitTaken(): void;
+  /**
+   * GIVE THE CAMERA BACK: re-derive the head-on rig for whatever this pane is
+   * looking at. The exact inverse of `onIsolationOrbitTaken`.
+   *
+   * The hand-over above is one-way by design, and Home is the key that undoes
+   * it — but the material workspace covers the panel that key belongs to, and
+   * in that mode EVERY drag orbits, so the first accidental nudge left the
+   * object crooked with no visible way back. A double-click on the object is
+   * the gesture, and it starts on the stage because the chrome cannot receive
+   * it: the workspace body is `pointer-events: none` so its drags reach the
+   * stage, which also means nothing there is clickable.
+   *
+   * It carries no argument on purpose. WHAT to re-derive is the chrome's
+   * question — it owns the isolation and the component context that decide it —
+   * and this is only the news that the author asked.
+   */
+  onFitRequest(): void;
   /** The stage's own pan/zoom changed. Camera pane only: the working pane's
    *  view is a `WorkingView`, and the two are not the same shape. */
   onViewChange(view: ShotView): void;
@@ -319,18 +1286,46 @@ export interface ShotBridgeHandlers {
   // for being under a shot. One scrub is open at a time either way (engine's
   // history throws on a second), which the pointer already guarantees.
   //
-  // It brackets TWO gestures: a drag on the frustum gizmo, which sends deltas;
-  // and — while "camera follows this view" is armed — a working-pane orbit or
-  // pan, which sends none at all. The view change IS the payload there, and it
-  // already crosses as `onWorkingViewChange`.
+  // It brackets the camera gizmo's drags in the working pane and, while
+  // PILOTING (v29), the Camera pane's own navigation: an orbit, a pan and a
+  // wheel there are framing deltas like any other.
   /** Answers whether the scrub opened, for `onGestureStart`'s reason. */
   onFramingGestureStart(): boolean;
-  /** Measured FROM THE PRESS, same rule as `onGesture`. `dzoom` is a factor. */
-  onFramingGesture(delta: FramingDelta): void;
+  /**
+   * Measured FROM THE PRESS, same rule as `onGesture`. `dzoom` is a factor.
+   *
+   * `origin: "wheel"` (v29) is a notch with no press and no release around
+   * it: the chrome opens the scrub itself and closes it over silence, the way
+   * follow's wheel used to be bracketed. ANSWERS whether the document took
+   * the write — false is the fork's refusal (a held camera, a path) — so the
+   * pilot badge can flash rather than the pane silently not moving.
+   */
+  onFramingGesture(delta: FramingDelta, origin?: "wheel"): boolean;
   onFramingGestureEnd(commit: boolean): void;
+  /** The pilot badge's own EJECT (v29): hands off the camera, which stays
+   *  where it is. The chrome owns the mode, so this is only the news. */
+  onLeavePilot(): void;
+  /** Which component drives the render camera this frame, by name, or null
+   *  when the document's rig does (v29). Pushed on change, never per frame. */
+  onCameraDriver(name: string | null): void;
+  /**
+   * A PATH MOVE'S WAYPOINT, dragged in the working pane.
+   *
+   * The same bracket as the three above — the scrub is already open and the
+   * camera lane is already the one that owns it — but a different write: this
+   * moves one pose in a list rather than the framing the camera resolves to.
+   * `writeFraming` REFUSES a drag over a path for exactly that reason (there is
+   * no single end for a gesture to land on), and this is the answer to the
+   * refusal: name the pose.
+   *
+   * `dx`/`dy` are design px MEASURED FROM THE PRESS, `onGesture`'s rule, so a
+   * coalesced move cannot make the drag drift.
+   */
+  onWaypointGesture(shotId: string, index: number, delta: { dx: number; dy: number }): void;
 
   /**
-   * INSERT A LAYER. The camera pane's draw lane, and the pen's commit.
+   * INSERT A LAYER. The frame pane's draw lane (the camera pane over a Shot,
+   * an open definition's one pane inside it), and the pen's commit.
    *
    * ── THE POINTS ARE DESIGN COORDINATES, NOT SCREEN ONES ─────────────────
    *
@@ -353,8 +1348,16 @@ export interface ShotBridgeHandlers {
    * carries handles now and crosses as `onPenCommit` below — but `onDraw`
    * still accepts `"path"`, because `layerFromDraw` remains the way an
    * agent-free caller mints a polyline path.
+   *
+   * `under` is the pick under a TEXT tool CLICK (no drag), front first. A
+   * click on a text layer edits it rather than stacking a new one, the
+   * Figma and Paper rule; the chrome decides, since it owns the layer kinds.
    */
-  onDraw(tool: InsertTool, points: readonly (readonly [number, number])[]): void;
+  onDraw(
+    tool: InsertTool,
+    points: readonly (readonly [number, number])[],
+    under?: readonly string[],
+  ): void;
 
   /**
    * COMMIT THE PEN'S PATH: anchors, their bezier handles, and whether the loop
@@ -374,6 +1377,60 @@ export interface ShotBridgeHandlers {
    */
   onPenCommit(data: PathData): void;
 
+  /** Commit a working-pane 3D spline draft as one layer and one undo entry. */
+  onSplineCreateCommit(draft: SplineCreateDraft): void;
+  /** Point-mode selection remains chrome-owned, just like layer selection. */
+  onSplinePointPick(layerId: string, pointId: string, additive: boolean): void;
+  /** A point/handle drag, bracketed into one document history entry. */
+  onSplinePointGestureStart(layerId: string, pointId: string, part: SplinePointPart): boolean;
+  onSplinePointGesture(patch: SplinePointPatch): void;
+  onSplinePointGestureEnd(commit: boolean): void;
+  /**
+   * A ruler guide drag, bracketed into one history entry (v44).
+   *
+   * `guideId` null CREATES a guide on `axis`, pulled out of a ruler; an id
+   * moves that guide. Returns false when the chrome refuses (a viewer, an
+   * unknown id), and the stage then draws nothing. `at` is the guide's
+   * position in the inspector's units: centre origin, y UP, which is what the
+   * ruler under it reads.
+   */
+  onGuideGestureStart(guideId: string | null, axis: "x" | "y"): boolean;
+  onGuideGesture(at: number): void;
+  onGuideGestureEnd(outcome: GuideGestureOutcome): void;
+  /** Set one guide's position from the numeric entry: one history entry. */
+  onGuideSet(guideId: string, at: number): void;
+  /** Delete one guide (a selected guide and Delete). */
+  onGuideRemove(guideId: string): void;
+  /**
+   * A motion path key drag, bracketed into one history entry (v44).
+   *
+   * `keyId` is a key on the layer's `transform.position` track. Each
+   * `onPathKeyGesture` carries the WHOLE offset since the start, in position
+   * units, and the chrome writes start + offset. `part` is `"key"` for the
+   * dot, or a Bezier handle (`"in"`, `"out"`) on a bezier path: the chrome
+   * then writes the handle's offset, mirroring the other one unless the delta
+   * says `breakPair`.
+   */
+  onPathKeyGestureStart(layerId: string, keyId: string, part: PathKeyPart): boolean;
+  onPathKeyGesture(delta: PathKeyDelta): void;
+  onPathKeyGestureEnd(commit: boolean): void;
+  /** A double-click on a motion path key dot (v44). The chrome toggles the
+   *  key between corner and smooth on a bezier path, and seeks to it on any
+   *  other. */
+  onPathKeyDoubleClick(layerId: string, keyId: string): void;
+  /** Insert an anchor after a segment's leading point. */
+  onSplineSegmentInsert(
+    layerId: string,
+    afterPointId: string,
+    point: SplinePoint3D,
+    /** Local progress in the authored span, used for a shape-preserving Bezier split. */
+    spanProgress?: number,
+  ): void;
+  /** Delete selected anchors in point mode, subject to the valid-curve floor. */
+  onSplinePointDelete(layerId: string, pointIds: readonly string[]): void;
+  /** Enter confirms point mode and Escape leaves it when no drag is live. */
+  onSplinePointModeEnd(layerId: string): void;
+
   /** A key the STAGE received. Returns true when the chrome consumed it, so the
    *  stage knows whether to preventDefault. Keyboard events go to ONE document,
    *  and once the canvas has focus that document is the stage. */
@@ -440,12 +1497,36 @@ export interface ShotStageBridge {
    *  called: there is nothing worth painting before a chrome exists, and the
    *  document arrives immediately after. */
   connect(handlers: ShotBridgeHandlers): void;
-  /** Replace the document. Cheap when the reference is unchanged. */
-  loadDoc(doc: Doc3D): void;
+  /** Replace the document. Cheap when the reference is unchanged. `rev` is
+   *  the saved revision it is (v34), or null for an edit not yet saved: it is
+   *  stamped on a piece failure first seen while this document is on stage. */
+  loadDoc(doc: Doc3D, rev?: string | null): void;
   /** Park the studio clock on an integer MASTER frame and repaint. */
   seek(frame: number): void;
+  /**
+   * The transport is running, or has stopped.
+   *
+   * SCHEDULING ONLY. The stage may use this to decide WHEN work happens — a
+   * repaint left for the next seek, a resolution held down until the transport
+   * stops — and may never let it reach a cache key or a sampled value. Every
+   * frame that is rested on, captured or exported is drawn by the same code
+   * whether or not it was played through, and two machines playing one document
+   * still ask for the same pixels.
+   *
+   * A stage that ignores this call is CORRECT, only slower, which is what makes
+   * the v20 gate a soft one.
+   *
+   * `true` also lets a freeze a preparing pass left standing lift on the first
+   * complete presentation of the current frame in EITHER presentation (v51),
+   * not only a paused one. Never at once: the canvas may still hold another
+   * Shot's picture.
+   */
+  setPlaying(playing: boolean): void;
   /** Which layers are selected, for the overlays. */
   setSelection(ids: readonly string[]): void;
+  /** Other people's selections, drawn as outlines in their colours (v43).
+   *  Ids the drawn shot does not hold draw nothing. An empty list clears. */
+  setPeerSelections(peers: readonly ShotPeerSelection[]): void;
   /** Screen quads for the current selection at the current frame, or null when
    *  nothing is selected. The chrome polls this from its own render rather than
    *  being pushed at, so an overlay re-render is never scheduled by the stage.
@@ -455,21 +1536,46 @@ export interface ShotStageBridge {
    *  keeps getting the answer it always got. */
   selectionQuads(pane?: StagePane): readonly ShotScreenQuad[] | null;
   /**
-   * Which tool is armed, because it decides the PLANE a move unprojects onto:
-   * "select" slides a tilted layer along its own surface, "move" slides it flat
-   * with z untouched. See stage/interactions/move.ts — that distinction is the
-   * whole difference between the two, and it only exists once layers can tilt.
+   * Which tool is armed, because it decides what a press does (pick, draw, pen)
+   * and the cursor. The plane a move unprojects onto is not a tool: a plain
+   * drag slides along the layer's own plane and an Alt-drag keeps it flat (see
+   * stage/interactions/move.ts).
    */
   setTool(tool: ShotTool): void;
+  /** Editor-only construction plane, re-pushed on attach and scene change. */
+  setWorkPlane(target: WorkPlaneTarget): void;
+  /** Interpolation for the next spline draft. A draft freezes it on its first anchor. */
+  setSplineBasis(basis: SplineBasis): void;
+  /** Enter/leave spline point mode and mirror the selected anchors. */
+  setSplineEditContext(context: SplineEditContext | null): void;
   /** Smart-guide lines the chrome's snapping landed on, in DESIGN frame
    *  coordinates. Pushed rather than polled because they change only while a
    *  gesture is running and must vanish the instant it ends. */
   setSnapGuides(guides: readonly SnapGuide[]): void;
+  /**
+   * The layer a CHROME surface is pointing at (a timeline row under the
+   * cursor), or null when it left. The stage lights that layer's outline
+   * through the same hover path its own pointer uses — pointing at the row
+   * answers "which one is this" without a click and without touching the
+   * selection.
+   *
+   * Imperative on the stage side by design: under `frameloop="never"` every
+   * state push is a React commit and therefore a GL draw, and a hover must
+   * cost one SVG leaf repaint and zero draws (v22).
+   */
+  hoverLayer(layerId: string | null): void;
   /** Drive the working-area view. */
   setView(view: ShotView): void;
   /** Fit the design frame to the CAMERA PANE with a margin. Returns the view it
    *  landed on so the chrome's readout stays in step. */
   fitView(): ShotView;
+  /** A point of the STAGE DOCUMENT (its client px, what a `drop` event on it
+   *  reports) as design px from the canvas centre, the coordinates `onDraw`
+   *  hands over, or null when it is not over the frame pane (the camera pane
+   *  over a Shot, an open definition's one pane inside it, where the point is
+   *  from the definition's canvas centre). A drop onto the frame places at
+   *  the point the author let go (v38). */
+  designPointAt(clientX: number, clientY: number): readonly [number, number] | null;
   /**
    * How many views are on screen, and how the width is divided.
    *
@@ -478,6 +1584,115 @@ export interface ShotStageBridge {
    * is re-pushed on every attach.
    */
   setStageLayout(layout: StageLayout): void;
+  /**
+   * THE AUTHOR IS WATCHING: draw the picture and nothing else.
+   *
+   * Video is the export's frame with every piece of authoring furniture taken
+   * off it: no selection handles, no union box, no hover outline, no marquee,
+   * no draw or transform gestures, no pen or spline draft. What stays is the
+   * frame border, navigation (wheel, space-drag) and the plain click, which is
+   * how an author picks the layer they want to work on and lands back in Edit.
+   *
+   * A FLAG AND NOT A LAYOUT, deliberately. The stage forces the camera-only
+   * panes while this is on and hands the author's real layout back untouched
+   * when it goes off, so `setStageLayout` keeps saying which EDITOR is waiting
+   * underneath and this says whether anything is drawn on top of it.
+   *
+   * WORKSPACE STATE, like the layout: never written to a Doc3D, never in an
+   * export, and re-pushed on every attach.
+   */
+  setVideo(on: boolean): void;
+  /**
+   * The Project is VIEW ONLY for this person (v41): their role lets them look
+   * but not edit. The stage keeps what looking needs (hover, click-select, the
+   * marquee, the outlines, navigation) and drops what editing needs: no
+   * handles, no drag gestures, no draw tools, no double-click text edit, no
+   * camera framing drag, no key light drag. The chrome refuses every write as
+   * well, so this only spares a viewer gestures that would be refused anyway.
+   *
+   * WORKSPACE STATE, like `setVideo`: never written to a Doc3D, re-pushed on
+   * every attach.
+   */
+  setReadOnly(on: boolean): void;
+  /**
+   * THE BOARD IS WATCHING, through a hole the size of a postcard.
+   *
+   * The same picture `setVideo` asks for (the camera pane, no furniture,
+   * `watching` in StageApp answers for both), and a SECOND flag rather than a
+   * second caller of the first: `setVideo` is the author choosing Video, it
+   * writes the focus layout, empties the selection through the chrome's own
+   * `setVideo` verb and collapses the inspector the board needs, and it is
+   * refused outright while a component definition is open. None of that is
+   * true of a board that simply wants to see the frame it is planning.
+   *
+   * It also carries the FRAMING, which `setVideo` does not: while this is on
+   * the camera pane's view is derived from `fit()` every render instead of
+   * read from `state.view`, so the shot lands whole inside the hole and
+   * nothing has to be put back when the board closes.
+   *
+   * WORKSPACE STATE, like the layout: never written to a Doc3D and never in
+   * an export. Only the component stage (ComponentStage) sends it, on its own
+   * bridge: the shot stage starts with it off and the chrome never turns it on.
+   */
+  setStoryboardPreview(on: boolean): void;
+  /**
+   * THE STUDIO'S COMMENT LAYER (bridge v45), or null for none.
+   *
+   * Pins draw over the camera pane's frame while stopped on their anchor's
+   * Shot and frame; a click on one calls `onCommentPin`. Armed, a primary
+   * press on the frame calls `onStudioCommentAt` instead of picking. Not
+   * drawn inside a component context or in the material workspace.
+   *
+   * WORKSPACE STATE: never written to a Doc3D, re-pushed on every attach.
+   */
+  setStudioComments(comments: ShotStudioComments | null): void;
+  /**
+   * THE SKETCH GUIDE (bridge v47), or null for none: one storyboard sketch
+   * drawn as dashed outlines and labels in the camera frame, so it follows
+   * the camera pane's view. Not drawn while watching, inside a component
+   * context or in the material workspace.
+   *
+   * WORKSPACE STATE: never written to a Doc3D, re-pushed on every attach.
+   */
+  setSketchGuide(guide: ShotSketchGuide | null): void;
+  /**
+   * THE FONT PREVIEW (bridge v50), or null for none: the font picker's
+   * hovered or arrowed-to family drawn on the given text layers. Only the
+   * picture changes: picking, overlays, auto-width measuring, stills,
+   * coverage, health and every export keep the real document, and a face
+   * that fails to load reports nothing and holds no readiness claim. While a
+   * preview changes a text layer of the open document, `coverage()` refuses
+   * (its picture is not the Shot's) and `capturePoster` answers null; a
+   * preview arriving mid-poster aborts the poster. An export or a capture
+   * draws the real document and the preview shows again when it ends. Until
+   * the faces land the layers draw `family`, then `fallback`.
+   *
+   * WORKSPACE STATE: never written to a Doc3D, cleared on every attach and
+   * when the document closes.
+   */
+  setFontPreview(preview: ShotFontPreview | null): void;
+  /**
+   * THE MOTION PREVIEW (bridge v53), or null for none: the Motion section's
+   * active preset stamped on the given layers. Only the picture changes, as
+   * with the font preview: picking, overlays, health and every export keep
+   * the real document, and a presentation drawn under it is never reported
+   * as the Project's (`health()` reads pending until it clears). The chrome
+   * moves through the preset's frames with ordinary seeks and seeks back to
+   * the playhead when it clears. While it changes the open document,
+   * `coverage()` refuses, `capturePoster` answers null and a preparing pass
+   * gives way.
+   *
+   * WORKSPACE STATE: never written to a Doc3D, cleared on every attach and
+   * when the document closes.
+   */
+  setMotionPreview(preview: ShotMotionPreview | null): void;
+  /**
+   * OPEN THE INLINE TEXT EDITOR on one text layer, or null to close it
+   * without committing (v38). The stage draws the editor over the layer, with
+   * the content selected, and answers `onTextEdit` on Escape or a click
+   * outside. Workspace state: never written to a Doc3D.
+   */
+  editText(layerId: string | null): void;
   /**
    * ISOLATE A SUBTREE, or null for the whole scene.
    *
@@ -493,6 +1708,26 @@ export interface ShotStageBridge {
    * "the shot", which is exactly the split that already exists.
    */
   setIsolation(layerId: string | null): void;
+  /** Give the working pane to the material workspace. The target remains
+   * rendered and navigable, but scene picking, transforms and draw tools stop.
+   *
+   * v17 addresses a SLOT rather than a layer, because a model's submeshes each
+   * carry their own graph and the workspace edits exactly one of them. */
+  setMaterialPreview(target: MaterialPreviewTarget | null): void;
+  /**
+   * ENTER OR LEAVE THE COMPONENT CONTEXT (v14): render one definition
+   * standalone, or null for the ordinary scene render.
+   *
+   * WORKSPACE STATE like isolation: never written to a Doc3D, never in an
+   * export, re-pushed on every attach. The stage is handed the def id and
+   * derives everything from the document it already has. While a context is
+   * set, `seek` frames are DEF-LOCAL; `setIsolation` and the camera/split
+   * machinery are inert (the context owns the whole viewport). The chrome
+   * clears isolation before setting a context — the two are mutually
+   * exclusive views, and the stage refuses nothing here because the chrome
+   * owns the mode.
+   */
+  setComponentContext(ctx: ShotComponentContext | null): void;
   /**
    * Inside isolation, does the AUTHOR own the working camera?
    *
@@ -509,6 +1744,10 @@ export interface ShotStageBridge {
    *
    * `setIsolation` resets it to false on its own, so entering a subtree never
    * inherits the last one's mode.
+   *
+   * `false` while isolated is also Home: the stage re-fits the held isolation
+   * frame from the current playhead. That frame otherwise stays still across
+   * edits and playback.
    */
   setIsolationOrbit(taken: boolean): void;
   /**
@@ -517,11 +1756,12 @@ export interface ShotStageBridge {
    *
    * ── WHY THE STAGE CANNOT MEASURE THIS ITSELF ────────────────────────────
    *
-   * A pane is the WHOLE WINDOW (`paneRects`), because the stage iframe is
-   * pinned `position: fixed; inset: 0` and the chrome's panels float ON TOP of
-   * it. So "the top-right corner of the working pane" is behind the shell
-   * header, and there is no measurement the stage's document can take to
-   * discover that — the panels are in the other document.
+   * A pane runs to the WINDOW'S OWN EDGES — `paneRects` insets nothing for the
+   * chrome, and in a split the two panes divide the window between them —
+   * because the stage iframe is pinned `position: fixed; inset: 0` and the
+   * chrome's panels are docked ON TOP of it. So the top of the working pane is
+   * behind the shell header, and there is no measurement the stage's document
+   * can take to discover that — the panels are in the other document.
    *
    * `Overlays` carried a hardcoded 116 for the top edge and a note saying the
    * real fix was this message, "worth it when a second overlay needs the same
@@ -530,9 +1770,23 @@ export interface ShotStageBridge {
    * thing that says a modal transform is live, has never been visible in the
    * default layout at all.
    *
-   * PAINT ONLY. `paneRects` must not change: insetting the pane rects would
-   * move the scissor and the hit test together and shrink the rendered picture
-   * to fit the chrome. This positions overlay FURNITURE and nothing else.
+   * ── WHAT IT MOVES, AND WHAT IT MUST NEVER MOVE ──────────────────────────
+   *
+   * It moves the things that have to be SEEN: the overlay's furniture, the
+   * derived head-on framing, the camera pane's zoom-to-fit, and where the split
+   * SEAM falls (the ratio is the working pane's share of the width, and the
+   * width it divides has to be the width the author can see — dividing the
+   * whole window put the seam at 683 on a 1366 laptop whose visible canvas ran
+   * 212..1066, handing the working pane 471 visible px against 383 with a fifth
+   * of it behind the rail).
+   *
+   * It moves NEITHER THE SCISSOR NOR THE HIT TEST. `paneRects` takes the inset
+   * for the seam alone; the rects it returns still partition the WHOLE
+   * viewport, so the stage keeps drawing full-bleed under the docked chrome
+   * and `paneAt` keeps answering for every pixel of it. Insetting those rects
+   * instead would shrink the rendered picture to fit the chrome and leave dead
+   * gutters where the panels sit. Which pixels are visible is a separate
+   * question, asked separately, by `insetRect`.
    *
    * Editor state, never a document field.
    */
@@ -545,6 +1799,27 @@ export interface ShotStageBridge {
    * here — it is always the graded render, by construction.
    */
   setShadingMode(mode: ShadingMode): void;
+  /**
+   * The working pane's grid floor, on or off (v22).
+   *
+   * WORKSPACE STATE by `setShadingMode`'s rule: never written to a Doc3D,
+   * never in an export (the grid is an EDITOR_LAYER object the shot camera
+   * cannot see), re-pushed on every attach. The spline work-plane aid is NOT
+   * gated by this — a drawing aid for an open gesture is not furniture.
+   */
+  setGridVisible(visible: boolean): void;
+  /**
+   * The rulers and smart guides, on or off (v44), and the playback
+   * resolution (v52).
+   *
+   * WORKSPACE STATE by `setGridVisible`'s rule: a per-viewer preference,
+   * never written to a Doc3D, never in an export, re-pushed on every attach.
+   * The guides themselves are document data and arrive with `loadDoc`.
+   */
+  setEditorChrome(chrome: EditorChrome): void;
+  /** Motion paths for the selected layers, on or off (v44). Workspace state
+   *  by `setGridVisible`'s rule, re-pushed on every attach. */
+  setMotionPaths(on: boolean): void;
   /** Drive the working pane's orbit camera. */
   setWorkingView(view: WorkingView): void;
   /** Frame the whole canvas in the working pane. Returns the view it landed on,
@@ -552,15 +1827,28 @@ export interface ShotStageBridge {
    *  owns the lens the distance is derived from. */
   fitWorkingView(): WorkingView;
   /**
-   * "Camera follows this view" is armed.
+   * PILOTING is armed, or not (v29).
    *
-   * The stage needs it for two things it is the only half able to do: bracket
-   * an orbit with the framing gesture lane, so one drag is one undo entry; and
-   * draw the affordance INSIDE the working pane. Blender's long-running
-   * complaint about its equivalent is that it is easy to forget it is on, and a
-   * checkbox in a panel the author is not looking at is exactly how.
+   * The stage needs it for two things it is the only half able to do: route
+   * the Camera pane's navigation (middle-drag orbit, shift-drag pan, wheel
+   * zoom) down the framing gesture lane instead of the viewport, so one drag
+   * is one undo entry; and draw the affordance INSIDE the pane. Blender's
+   * long-running complaint about its "Lock Camera to View" is that it is easy
+   * to forget it is on, and a checkbox in a panel the author is not looking at
+   * is exactly how.
+   *
+   * `text` is the badge's words when something holds the camera (a finished
+   * move with Animate off, a path, a component driving it), composed by the
+   * chrome because the chrome knows why; null draws the plain badge.
+   */
+  setPilot(on: boolean, text: string | null): void;
+  /**
+   * What a camera write would do at the playhead (v29), or null with no
+   * document. The gizmo dims when it is not `free`, the pointer lane refuses
+   * the press with the gate's own sentence, and the hover names the move —
+   * all BEFORE a drag, where the error strip used to speak after one.
    */
-  setCameraFollowsView(on: boolean): void;
+  setCameraGate(gate: CameraGate | null): void;
   /** Drop the document: the stage renders nothing and every layer plane
    *  unmounts, releasing its raster pins and texture bindings. The close
    *  half of `loadDoc`. */
@@ -571,10 +1859,297 @@ export interface ShotStageBridge {
    *  closed a panel. Not called on scene switch: surviving a switch warm is
    *  the whole reason the cache is module-level. */
   clearCaches(): void;
+  /**
+   * Tier-1 export: what THIS browser can encode at the document's dimensions.
+   * Empirical (a VideoEncoder/AudioEncoder probe inside the encode worker),
+   * never UA sniffing. Cached per dimensions on the stage side.
+   */
+  exportCapability(): Promise<Tier1Capability>;
+  /**
+   * Render the shot in place and encode an MP4, or a GIF (v32), in THIS
+   * browser.
+   *
+   * The stage flips into export framing — design viewport, no view offset,
+   * dpr 1, raster scale 1, overlays unmounted: the same numbers a Tier-2
+   * render pins — drives every frame through the same draw latch the still
+   * lane uses, and restores the author's framing and playhead when done.
+   * While it runs, chrome `seek`/`loadDoc` pushes are DEFERRED (applied on
+   * completion), never interleaved: a mid-capture re-render would let the
+   * encoder stamp one frame's timestamp on another frame's pixels.
+   *
+   * One at a time — a second call rejects while one runs. Cancel via
+   * `signal`; cancellation restores the stage and resolves nothing.
+   */
+  exportMovie(request: ShotExportMovieRequest): Promise<ShotExportMovieResult>;
+  /**
+   * The Project's poster frame (`posterFrame`, the frame the local CLI
+   * renders) as a JPEG at most `maxWidth` wide: the dashboard's card
+   * thumbnail.
+   *
+   * Captured the way an export frame is: export framing, then the in-draw
+   * snapshot from the matching presentation, then the author's stage back.
+   * The playback framebuffer is unpreserved, so the live canvas is never read.
+   *
+   * Null (never a throw) when there is nothing to capture or the stage is
+   * busy: no document, an export in flight, playback or its preparing pass
+   * running, a component or material being edited, or a capture that refused.
+   * Null uploads nothing: an existing poster remains, and a card that never
+   * had one keeps its deterministic gradient, so this is never worth an error.
+   *
+   * The chrome takes no lock for it, so the poster YIELDS: anything the author
+   * starts on the stage mid-capture (Play, an export or `captureFrame`, a
+   * scrub, an edit, a component, a press, a font preview) aborts it, runs
+   * once the stage has left its export framing, and the poster answers null.
+   * A document whose
+   * capture failed answers null at once until it changes, so the chrome may
+   * ask again whenever it likes.
+   */
+  capturePoster(maxWidth: number): Promise<Blob | null>;
+  /**
+   * One exact still of the whole timeline (v32): the storyboard's "Frame
+   * from Shot". Captured the way `capturePoster` is (export framing, the
+   * in-draw snapshot at `frame`, the author's stage back), then scaled to the
+   * asked size and encoded.
+   *
+   * Rejects with the reason, unlike the poster: the author asked for this
+   * picture, and a silent nothing would read as a dead menu row. The chrome
+   * holds its export lock around the call, which pauses the transport.
+   */
+  captureFrame(request: ShotCaptureFrameRequest): Promise<Blob>;
+  /**
+   * THUMBNAILS for a batch of nodes in the open material graph.
+   *
+   * The same request/response shape `capturePoster` established, and for the
+   * same reason: the chrome is three-free by test, so it cannot render a node's
+   * value itself. The stage compiles one unlit preview material per requested
+   * node, draws them into ONE atlas render target and reads it back once —
+   * one GPU stall per batch rather than per thumbnail.
+   *
+   * Null (never a throw) when there is nothing to draw: no stage, an export in
+   * flight, no material preview target set, or a newer request superseded this
+   * one. A missing thumbnail is a blank card, which is worth no error.
+   *
+   * EDITOR ONLY. The component that answers this is mounted only while the
+   * stage is not exporting, and the CLI's render page never mounts it at all,
+   * so no export can be reached from here.
+   */
+  requestNodePreviews(request: NodePreviewRequest): Promise<NodePreviewBatch | null>;
+  /**
+   * DRAW EACH OF `frames` ONCE, so playback does not pay a first-use cost on
+   * any of them (`playbackPreparation.ts` says what that cost is and which
+   * frames carry it). One pass serves a queued Play and the background alike:
+   * `pace()` says which it is, and is asked again at every hop and at the end
+   * of the list, so a Play pressed during a background pass upgrades it.
+   *
+   * EVERY PASS DRAWS UNDER A FROZEN PICTURE. The frame on screen is presented
+   * again, copied inside that presentation and laid over the canvas with a
+   * shield above every overlay; a freeze an earlier pass left standing is
+   * adopted instead. A press or a wheel on the shield ends the pass
+   * (`"press"`). The stage then switches to its PLAYING presentation (the
+   * warm-up's playing roles), because that is what playback will draw with,
+   * and publishes each frame with a fresh token, the frame already on screen
+   * included. It waits for that frame's playing presentation with a deadline,
+   * so one frame that never lands cannot hold Play for ever, and reports the
+   * frame's outcome to `onProgress`.
+   *
+   * At the end of the list under a `"play"` pace it HANDS OVER: the start
+   * frame is presented again in the playing presentation, the freeze lifts
+   * inside that presentation, and it resolves `handedOver` with the stage
+   * left playing, for the chrome to start the transport at once (a start
+   * frame that is not presented within 5 s restores instead). Under an
+   * `"idle"` pace, and on a cancel, a yield or an export, it restores the
+   * stage's own playing flag and the start frame, and the freeze lifts on the
+   * first complete presentation of the current frame (a later seek moves the
+   * lift to the newer frame, and a scrub lifts it within 150 ms). A
+   * press on the shield after the restore takes the freeze down at once.
+   *
+   * Refused (`refused`, none of `frames` drawn) with no document, no canvas
+   * or a component context, and when the freeze itself times out. Under
+   * export framing a `"play"` pace waits for a poster to step aside and an
+   * `"idle"` pace yields (`"export"`). A stage interaction live at the start,
+   * or begun during the pass, yields (`"interaction"`); the other early ends
+   * are the rest of `ShotPreparePlaybackYield`. Never rejects: preparation is
+   * an optimisation, and a stage that cannot do it is only slower.
+   *
+   * One at a time: a second call cancels the first.
+   */
+  preparePlayback(request: ShotPreparePlaybackRequest): Promise<ShotPreparePlaybackResult>;
+  /**
+   * What the GPU state behind prepared frames stands on (v51), for the
+   * chrome's preparation keys. Synchronous and cheap. When `base` moves the
+   * chrome drops every key; `modules` joins only the keys of Shots that place
+   * code components.
+   */
+  preparationKey(): ShotPreparationKey;
+  /**
+   * The `(frame, document)` pairs of every whole presentation the TRANSPORT
+   * drew in the playing presentation since it started, then cleared (v51),
+   * so the chrome can credit what playback drew as prepared at Pause.
+   *
+   * Never a preparing pass's frames, and none while a component context or a
+   * font preview shows. Reset when the transport starts and on `loadDoc` of
+   * another document id.
+   */
+  takePlayed(): ReadonlyArray<{ frame: number; document: Doc3D }>;
+  /**
+   * What the stage knows about itself (v35), for an agent that cannot see it:
+   * the crash, a lost context, the isolated pieces, the render fallbacks, the
+   * component failures, the uncaught errors of this document and its export
+   * worker, and what it last presented (a complete picture, readiness clear)
+   * with the saved revision and module epoch it drew. Synchronous and cheap:
+   * a copy of what the stage already keeps for its export gate.
+   */
+  health(): StageHealthSnapshot;
+  /**
+   * Which mesh-like layers put a pixel in the frame on stage (v36): for the
+   * Shot under the playhead, at the frame last drawn, each mesh, device and
+   * placed component layer the document says shows there (in the Shot or in
+   * a placed component definition, at most `cap`, the rest listed as
+   * skipped) is drawn away once and the frame compared with itself drawn
+   * whole, offscreen, through the Shot's camera in export framing, its bins,
+   * its post chain and its colour boundary. Nothing is presented, and the
+   * author's picture, playhead and every flag it flips are as they were
+   * after, a throw included. Works in a hidden tab.
+   *
+   * Rejects with the reason it could not check: no Shot under the playhead,
+   * a component shown alone, an isolated layer or a material preview (the
+   * picture is not the Shot's then), an export, Play or its preparing pass,
+   * a playhead that moved. A preparing pass under an `"idle"` pace is ended
+   * first and resolves `yielded: "coverage"`.
+   */
+  coverage(request?: CoverageRequest): Promise<StageCoverage>;
   /** Tear the stage down (a chrome unmount, or a bridge version mismatch). */
   dispose(): void;
 }
 
+/** Who is waiting on a preparing pass (v51), asked at every hop. `"play"`: a
+ *  queued Play. `"idle"`: nobody, the author sits paused. */
+export type ShotPreparePace = "play" | "idle";
+
+/** How one frame of a preparing pass ended (v51). `"presented"`: its own
+ *  publication was presented in the playing presentation. `"timeout"`: its
+ *  deadline passed with no external readiness claim pending.
+ *  `"timeout-pending"`: its deadline passed while an external claim (a font,
+ *  a texture, an html layer, a video seek) was still pending. */
+export type ShotPreparedOutcome = "presented" | "timeout" | "timeout-pending";
+
+/** Why a preparing pass ended before its list did (v51). */
+export type ShotPreparePlaybackYield =
+  | "press" // a press or wheel on the shield (cancels a queued Play)
+  | "input" // author input while pace() was "idle": the request's signal aborted with the reason "input"
+  | "interaction" // a live stage interaction started (or was live at the start)
+  | "push" // a stage push that changes the picture or the overlays
+  | "resize" // a window resize
+  | "hidden" // the document became hidden
+  | "coverage" // a coverage() check needed the author's frame
+  | "export"; // export framing (an export, a poster, a still, a capture)
+
+/** The chrome's request for the preparing pass (`preparePlayback`). */
+export interface ShotPreparePlaybackRequest {
+  /** MASTER frames, in the order to draw them. */
+  frames: readonly number[];
+  /** After each frame: presented, or its deadline passed (with or without an
+   *  external claim pending at the deadline). */
+  onProgress?: ((framesDone: number, totalFrames: number, outcome: ShotPreparedOutcome) => void) | undefined;
+  /** Aborting it cancels the pass, and the stage restores. Aborted with the
+   *  reason `"input"` (author input under an `"idle"` pace), the pass
+   *  resolves `yielded: "input"`. */
+  signal?: AbortSignal | undefined;
+  /** Asked at every hop and at the end of the list. `"play"`: a queued Play
+   *  is waiting (hop through a MessageChannel; hand over at the end).
+   *  `"idle"`: nothing is waiting (hop through requestIdleCallback with a
+   *  100 ms timeout; restore at the end). */
+  pace: () => ShotPreparePace;
+  /** How long `frames[index]` may take to present, in ms, asked as it is
+   *  published: the chrome's second-timeout rule asks for 500 after a
+   *  timeout in the same Shot. Absent, or not a positive number, it is
+   *  `PREPARE_FRAME_DEADLINE_MS` (5 s), which is also the ceiling. */
+  deadlineMs?: ((index: number) => number) | undefined;
+}
+
+export interface ShotPreparePlaybackResult {
+  /** Every frame was presented or timed out. */
+  completed: boolean;
+  /** Frames whose own publication was presented in the playing presentation. */
+  presented: number;
+  /** Ended early, for this reason. */
+  yielded?: ShotPreparePlaybackYield;
+  /** Could not run at all, and why: no document, no canvas, a component
+   *  context, or a freeze that timed out. None of `frames` was drawn. */
+  refused?: string;
+  /** Ended in the playing presentation on the start frame with the freeze
+   *  lifted: start the transport now. */
+  handedOver?: true;
+}
+
+/** What the GPU state behind prepared frames stands on (v51
+ *  `preparationKey()`). */
+export interface ShotPreparationKey {
+  /** Moves when the GPU state prepared frames stand for is replaced:
+   *  `performance.timeOrigin : gpuEpoch : canvas CSS size @ resolved pixel
+   *  ratio : raster rung`. The GPU epoch moves on a new renderer, at the END
+   *  of export framing (an export, a poster, a still, `captureFrame`), on
+   *  `clearCaches` and on `closeDoc`, and each move is announced through
+   *  `onStageHealth`. A coverage check moves nothing: it draws into targets
+   *  of its own. */
+  base: string;
+  /** The placed code components' module epoch : hot-update count. */
+  modules: string;
+}
+
+/** The chrome's request for one exact still (`captureFrame`, v32). */
+export interface ShotCaptureFrameRequest {
+  /** A MASTER frame of the whole timeline. */
+  frame: number;
+  /** The delivered size, in px. The frame is drawn at the design size, as an
+   *  export frame is, and scaled to this. */
+  width: number;
+  height: number;
+  format: "png" | "jpeg" | "webp";
+  signal?: AbortSignal | undefined;
+}
+
+/** The chrome's request for a Tier-1 (in-browser) movie export. */
+export interface ShotExportMovieRequest {
+  /** Absent = mp4. A GIF (v32) takes no audio, bitrate or quantizer, and
+   *  matches the server GIF's palette, timing and loop rules (tier1/gifSink.ts). */
+  format?: ExportFormat | undefined;
+  /** Scene id to export; absent or "" = the whole timeline (the same
+   *  WHOLE_TIMELINE convention the render route takes). */
+  sceneId?: string | undefined;
+  /** Master frames of the whole timeline to export, the work area (v39).
+   *  Refused with a `sceneId`. Absent = the whole scope. */
+  window?: { start: number; frames: number } | undefined;
+  /** Target video bitrate, bits/s — derived by the chrome from the shared
+   *  quality table (bitsPerPixel × w × h × fps) so the browser and server
+   *  paths honour the same quality choice. Absent = the encoder default. */
+  videoBitrate?: number | undefined;
+  /** The H.264 QP for every P frame, a whole number 0..51 (v49): the quality's
+   *  CRF from the same table. The stage encodes at it where a hardware encoder
+   *  honours a fixed QP, and at `videoBitrate` everywhere else. Absent =
+   *  `videoBitrate` only. */
+  quantizer?: number | undefined;
+  /** The document's audio, already mixed OFFLINE by the chrome (planar f32,
+   *  48 kHz stereo). Absent = export silent. The chrome owns the mix because
+   *  audio was never part of the stage: the preview's clips play from the
+   *  chrome document, and the stage neither draws nor samples them. */
+  audio?: { sampleRate: number; channels: Float32Array[] } | undefined;
+  onProgress?: ((framesDone: number, totalFrames: number) => void) | undefined;
+  signal?: AbortSignal | undefined;
+}
+
+export interface ShotExportMovieResult {
+  blob: Blob;
+  extension: string;
+  /** Set when the document HAS audio but this browser could not encode it —
+   *  the export shipped silent and the dialog says why (the motion lane's
+   *  exact affordance). */
+  audioSkippedReason?: string;
+  /** How the MP4's encoder ran (v49): a fixed QP or a bitrate, on a hardware
+   *  or a software encoder. Absent for a GIF. */
+  encoding?: Mp4Encoding;
+}
+
 declare global {
   interface Window {
     __shotStudio?: ShotStageBridge;