@dailies-studio/shot-editor 0.1.0

package/src/bridgeTypes.ts

@@ -0,0 +1,582 @@
+// The shot chrome <-> stage protocol, and the ONE place both halves agree.
+//
+// ── WHY A BRIDGE AT ALL ───────────────────────────────────────────────────
+//
+// The chrome is a PREBUILT STATIC bundle (so user tooling can never break the
+// editor) and the stage is served through the PROJECT's Vite (so the three
+// stack resolves to the studio's pinned copies). They are two documents, and
+// the only thing that crosses is this interface — installed on
+// `window.__shotStudio` by the stage's `boot()` before first paint, and polled
+// for by the chrome's `connectStage`.
+//
+// SYNCHRONOUS BY DESIGN, and same-origin only. The motion and canvas lanes made
+// the same call for the same reason: a seek that has to await a postMessage
+// round trip cannot be driven from a pointermove without tearing. Hosting this
+// chrome cross-origin would need an async rewrite; that is a known ceiling and
+// not a bug.
+//
+// ── THREE-FREE ────────────────────────────────────────────────────────────
+//
+// Nothing in this file — or anywhere under src/ outside src/stage/ — may import
+// `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";
+// 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.
+import type { InsertTool, ShotTool } from "./tools.js";
+// The pane vocabulary lives with the geometry that defines it. Importing it
+// here rather than restating it is safe for the three-free rule and load
+// bearing for the lane: `panes.ts` and `workingView.ts` are plain arithmetic
+// with no three import precisely so both documents can share these types, and
+// a second declaration of "what a split is" is a second thing to keep in step.
+import type { StageLayout, StagePane } from "./stage/panes.js";
+import type { ShadingMode } from "./stage/shading.js";
+import type { WorkingView } from "./stage/workingView.js";
+
+export type { InsertTool, ShotTool };
+
+export type { FramingDelta, GestureDelta, GestureKind, SnapGuide };
+export type { ShadingMode, StageLayout, StagePane, WorkingView };
+
+/** Bumped when a change to this file would make an old stage and a new chrome
+ *  disagree silently. `connectStage` refuses a mismatch rather than running.
+ *
+ *  2: the split view. A v1 stage has no `setStageLayout`, so a v2 chrome asking
+ *  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.
+ *
+ *  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
+ *  the stage's own fit is one of them, which under follow rewrites the camera
+ *  of every document that is merely OPENED while follow happens to be armed.
+ *  Silent, dirtying and autosaved, which is exactly what this refusal is for.
+ *
+ *  5: `onDraw`. A v4 stage has no draw lane at all, so with the rect tool armed
+ *  a drag would fall through to its marquee: the author draws a rectangle, sees
+ *  a selection band, and gets no layer and no error. Every tool in the dock
+ *  would look armed and half of them would do nothing.
+ *
+ *  6: `closeDoc` + `clearCaches`. Document close now really closes on the
+ *  stage: the doc is dropped (unmounting every plane) and THEN the raster LRU
+ *  — a module singleton in the STAGE's bundle, which the chrome may not
+ *  import — is freed. A v5 stage has neither method and the push would throw;
+ *  worse, it would keep rendering the closed document behind the file picker
+ *  with every raster resident.
+ *
+ *  7: `onPenCommit`. The pen draws BEZIERS now, and a v6 stage can only report
+ *  the polyline `onDraw` carries — so a v6 stage under a v7 chrome would hand
+ *  back a path whose curves had been flattened to corners on the way, silently
+ *  and only for paths the author had actually curved. The handle geometry has
+ *  no representation in the older lane at all, which is what makes this a
+ *  version and not an optional extra.
+ *
+ *  8: `setIsolation` and `onEnterLayer`. A v7 stage has no isolation at all, so a v8 chrome
+ *  entering a subtree would show the whole scene, undimmed, at the scene
+ *  camera — while its outline, its keymap and its inspector all believed the
+ *  author was inside one card. Every pick would land on a layer the chrome
+ *  considers out of scope, so clicking anything would read as a dead canvas.
+ *
+ *  9: `setShadingMode`, and `"roll"` in `GestureKind`. Two silent
+ *  disagreements at once. A v8 stage has no `setShadingMode`, so a v9 chrome's
+ *  ShadingBar would show an armed wireframe button over a pane still rendering
+ *  clay — the armed-control-over-a-dead-pane state the refusal exists for. And
+ *  a v9 stage can emit `{kind: "roll"}` across `onGesture`, which a v8
+ *  chrome's `transformFor` has no arm for — `undefined` reaches `unchanged()`
+ *  and throws inside the stage's own pointer path.
+ *
+ *  10: `setIsolationOrbit` + `onIsolationOrbitTaken`, and `"scale"` in
+ *  `GestureKind`. Two more silent disagreements. A v9 stage keeps isolation's
+ *  DERIVED orthographic rig in the working camera's slot forever, so a v10
+ *  chrome that believed the author had taken the camera would refuse nothing,
+ *  let follow mode write the shot camera from a pose with no pixels, and
+ *  autosave it. And a v10 chrome can emit `{kind: "scale"}` across `onGesture`,
+ *  which a v9 `transformFor` has no arm for — `undefined` reaches `unchanged()`
+ *  and throws inside the stage's own pointer path, exactly as `"roll"` did at
+ *  version 9.
+ *
+ *  11: `onContextMenu`, `onMeshStats`, and the key-light trio
+ *  (`onKeyLightStart`/`onKeyLight`/`onKeyLightEnd`). All five are stage ->
+ *  chrome, and the mismatch bites in both directions.
+ *
+ *  A v11 stage under a v10 chrome calls handlers that are not there. Every one
+ *  of them fires from inside a pointer lane — a right press, a gizmo drag, a
+ *  model finishing its load — so the failure is a throw in the middle of a
+ *  gesture, which is the same shape `"roll"` and `"scale"` had at 9 and 10.
+ *
+ *  A v10 stage under a v11 chrome is the quiet direction and worse for it: the
+ *  chrome would show a right-click menu that never opens, a key-light gizmo
+ *  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;
+
+/** What the stage reports once it has a renderer and a document. */
+export interface ShotStageInfo {
+  /** The design canvas, design px. */
+  width: number;
+  height: number;
+  /** Master-timeline extent. */
+  durationFrames: number;
+  /** "webgpu" or "webgl" — which backend actually came up, for the status
+   *  badge. A WebGPU request that fell back to WebGL2 is normal, not an error,
+   *  but it is worth showing because it changes what the post stack costs. */
+  backend: string;
+}
+
+/** 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.
+ *
+ *  A QUAD AND NOT A RECT. Layers tilt, so a selected layer's outline is a
+ *  trapezoid; an axis-aligned box would lie about the tilt in every frame and
+ *  would put the resize handles somewhere the layer is not. */
+export interface ShotScreenQuad {
+  id: string;
+  pts: readonly [number, number, number, number, number, 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. */
+export interface ShotView {
+  /** Screen px per design px at z = 0. */
+  zoom: number;
+  /** Pan of the working area, design px. */
+  panX: number;
+  panY: number;
+}
+
+/**
+ * WHY the working view moved, which only the stage can know.
+ *
+ * "Camera follows this view" turns a view change into a DOCUMENT EDIT, so the
+ * three cases stop being the same event the moment follow is armed:
+ *
+ *   "gesture" — an orbit or a pan. The stage brackets it with the framing
+ *     gesture lane, so the whole drag is one undo entry.
+ *   "wheel"   — a dolly. It has no press and no release, so nothing brackets
+ *     it; the chrome closes it over silence instead.
+ *   "fit"     — the stage MIRRORING a view it derived itself, on a document
+ *     open or an iframe reload. Nobody moved anything, so follow must not
+ *     write. Discriminating this by value (is it equal to the fit?) would be a
+ *     guess; the caller is the only half that knows.
+ */
+export type WorkingViewOrigin = "gesture" | "wheel" | "fit";
+
+/** What the chrome installs on the stage. Every handler must be total and must
+ *  never throw back across the boundary — the stage calls them from inside its
+ *  own render loop. */
+export interface ShotBridgeHandlers {
+  /** The renderer is up and the stage is showing `doc`. Fires once per
+   *  document load, and again after a Vite reload remints the stage. */
+  onReady(info: ShotStageInfo): void;
+  /** The stage failed in a way the author needs to see. */
+  onError(message: string): void;
+  /**
+   * A pick, in DOCUMENT order front-to-back — the WHOLE ordered hit list, not
+   * just the nearest.
+   *
+   * The chrome owns the policy (plain click takes the front, Cmd-click walks
+   * behind), because "what does a modified click mean" is a chrome question. A
+   * stage that answered it would have to know about modifier state, and then
+   * two places would decide selection.
+   *
+   * `pane` says which view the hits were read in, and it is not decoration:
+   * the camera pane orders them by PAINT ORDER and the working pane by
+   * DISTANCE (see `pickLayersByDistance`), so the meaning of "the front-most
+   * hit" — and therefore what a meta-click walks behind — depends on it.
+   */
+  onPick(hits: readonly string[], modifiers: PickModifiers, pane: StagePane): void;
+  /**
+   * A DOUBLE-CLICK: go inside whatever is under the cursor.
+   *
+   * The same ordered hit list `onPick` sends, and for the same reason — the
+   * chrome owns "which of these did the author mean", and it is the only half
+   * that knows what is already isolated. A stage that answered would need the
+   * isolation stack, and then two places would decide what entering means.
+   */
+  onEnterLayer(hits: readonly string[], pane: StagePane): void;
+  /**
+   * A RIGHT PRESS: the same ordered hit stack `onPick` sends, plus the point to
+   * open a menu at.
+   *
+   * `onPick`'s division exactly — the stage reports what is under the pointer
+   * and the chrome decides what a menu of it should say. A stage that built the
+   * entries would need the selection, the isolation stack and every store verb,
+   * and the chrome already has all three.
+   *
+   * `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.
+   */
+  onContextMenu(hits: readonly string[], pane: StagePane, at: { x: number; y: number }): void;
+  /**
+   * A mesh layer's triangle count, once its model has loaded — or null when the
+   * layer unmounts or its model is swapped.
+   *
+   * PUSHED, not polled. The count is known exactly once, when the GLB is parsed,
+   * and it cannot change until a different asset arrives; a chrome that asked
+   * for it per frame would be asking a question whose answer it already had.
+   *
+   * It crosses the bridge at all because the chrome is three-free by test: the
+   * outliner wants to badge a heavy model and the budget wants to warn about a
+   * heavy scene, and neither half can read a `BufferGeometry`.
+   */
+  onMeshStats(layerId: string, triangles: number | null): 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
+   * or discard once.
+   *
+   * `onKeyLightStart` returns false when the chrome refuses to open one (a
+   * scrub is already held), and the stage abandons the drag rather than
+   * emitting into nothing. `dir` is a direction in the DESIGN frame, already
+   * unit length. `commit: false` restores the base, which is what Escape means.
+   *
+   * There is no light in this lane and this is not one: it writes
+   * `mesh.shading.keyDir`, a shader uniform that fakes a key direction. See
+   * `MeshShading` — "no lights, ever".
+   */
+  onKeyLightStart(layerId: string): boolean;
+  onKeyLight(dir: readonly [number, number, number]): void;
+  onKeyLightEnd(commit: boolean): void;
+  /**
+   * The author just took the working camera INSIDE isolation.
+   *
+   * ── WHY ISOLATION HANDS THE CAMERA OVER AT ALL ──────────────────────────
+   *
+   * Entering a subtree puts a DERIVED orthographic head-on rig in the working
+   * camera's slot (stage/isolation.ts), because that is the only camera that
+   * can frame a rolled or face-down card: the orbit rig resets its up vector to
+   * world +y every frame and clamps its polar angle off both poles. The pose is
+   * 100 percent derived, so there is no parameter an orbit, a pan or a dolly
+   * can move — and the author's first instinct is to orbit, which did nothing
+   * at all and said nothing about why. Blender's local view scopes what you see
+   * and leaves the viewport camera completely free.
+   *
+   * So the derived rig is the ENTRY pose, not a cage. The first navigation
+   * gesture fires this, the chrome flips its bit and pushes it back down, and
+   * from then on the ordinary perspective orbit rig owns the pane. Home and
+   * numpad-dot clear it, which makes head-on the RESET rather than the only
+   * option.
+   *
+   * It is a separate handler rather than a flavour of `onWorkingViewChange`
+   * because it is a MODE change the chrome must persist and re-push, while a
+   * view change is a mirror the chrome is free to throttle.
+   */
+  onIsolationOrbitTaken(): 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;
+  /** The working pane's orbit / pan / dolly changed. `origin` says WHAT moved
+   *  it, and follow mode is the reason it has to: see `WorkingViewOrigin`. */
+  onWorkingViewChange(view: WorkingView, origin?: WorkingViewOrigin): void;
+  /** Which pane the author last pressed, wheeled or dragged in. The chrome
+   *  points its zoom controls and its fit shortcut at it, so it must follow the
+   *  POINTER rather than the selection — an author can orbit the working pane
+   *  with a camera-pane layer selected. */
+  onActivePane(pane: StagePane): void;
+
+  // ── the gesture lane ─────────────────────────────────────────────────────
+  //
+  // Split into three calls rather than one, because the middle one fires on
+  // every pointermove and the outer two are what make the whole drag ONE undo
+  // entry: `start` opens a history scrub, every `onGesture` re-derives from the
+  // scrub's base, and `end` commits or discards it. A single "here is the new
+  // document" call could not express that, and would cost an undo entry per
+  // pixel moved.
+  /** `screenScale` is SCREEN PX PER DESIGN PX in the pane the press landed in,
+   *  which the stage is the only half able to answer: the camera pane's is
+   *  `ShotView.zoom` and the working pane's is a perspective scale derived from
+   *  the orbit distance. The chrome divides its snap threshold by it, so
+   *  omitting it snaps a working-pane drag at the camera pane's zoom. */
+  /**
+   * …and it ANSWERS whether the scrub opened.
+   *
+   * Engine allows one scrub, so a start that arrives while another lane holds
+   * the history has to be refused. A pointer drag can absorb that silently —
+   * the author releases and tries again — but a MODAL transform arms and stays
+   * armed, so one that opened over somebody else's scrub would drive that
+   * scrub with its own deltas and commit it. The stage honours the answer.
+   */
+  onGestureStart(kind: GestureKind, layerIds: readonly string[], screenScale?: number): boolean;
+  /** The delta MEASURED FROM THE PRESS, never since the last move — the scrub
+   *  re-derives from its base, so a coalesced move cannot make a drag drift. */
+  onGesture(delta: GestureDelta): void;
+  /** `false` = Escape or a lost pointer: restore exactly what was there. */
+  onGestureEnd(commit: boolean): void;
+
+  // ── the CAMERA's gesture lane ────────────────────────────────────────────
+  //
+  // A second lane rather than a `subject` on the first, because the two write
+  // different things through different ops and only one of them can be refused
+  // 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`.
+  /** 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;
+  onFramingGestureEnd(commit: boolean): void;
+
+  /**
+   * INSERT A LAYER. The camera pane's draw lane, and the pen's commit.
+   *
+   * ── THE POINTS ARE DESIGN COORDINATES, NOT SCREEN ONES ─────────────────
+   *
+   * The stage is the only half that can convert: the chrome knows the view but
+   * not the pane's pixel size, and `screenToDesign` needs both. So the numbers
+   * that cross are already in the schema's own space — design px from the
+   * CANVAS CENTRE, +y down (types.ts's coordinate contract) — exactly like the
+   * `SnapGuide` positions that cross the other way. The chrome never divides by
+   * a zoom, and there is no second place a pane origin could be subtracted.
+   *
+   * ── A CLICK IS TWO IDENTICAL POINTS ────────────────────────────────────
+   *
+   * "Did the pointer travel far enough to be a drag" is a SCREEN-px question
+   * and therefore the stage's, so a sub-threshold drag arrives here collapsed
+   * to `from === to` and the chrome's one rule is "a zero-size box means the
+   * default box, centred on the point". A `dragged` flag beside the points
+   * would be a second thing that can disagree with them.
+   *
+   * Two points for every draw tool. The PEN no longer rides this lane — it
+   * 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.
+   */
+  onDraw(tool: InsertTool, points: readonly (readonly [number, number])[]): void;
+
+  /**
+   * COMMIT THE PEN'S PATH: anchors, their bezier handles, and whether the loop
+   * closed.
+   *
+   * ONE ARGUMENT, not `(points, closed)`. `closed` lives inside `PathData`
+   * already, and a flag beside the points would be a second thing that can
+   * disagree with them — the same rule `onDraw` states above for `dragged`.
+   *
+   * Coordinates follow `onDraw` exactly: design px from the canvas centre,
+   * +y down, converted by the stage because only it knows the pane's size.
+   * The chrome normalises them into the layer's own viewBox on arrival.
+   *
+   * Fewer than two anchors never reaches here — `penData` returns null and the
+   * stage commits nothing, because one anchor is a layer with no geometry and
+   * no way to select it.
+   */
+  onPenCommit(data: PathData): 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. */
+  onKey(event: KeyEventFields, editing: boolean): boolean;
+}
+
+/** The fields the keymap reads. A plain object rather than a KeyboardEvent
+ *  so it crosses the bridge as data and a test can build one. */
+export interface KeyEventFields {
+  key: string;
+  shiftKey: boolean;
+  altKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  /** `KeyboardEvent.code` — the numpad lane resolves on it. Optional so a
+   *  probe or an older sender without it keeps today's answers. */
+  code?: string;
+}
+
+/**
+ * The chrome's furniture, as an inset into the stage, in CSS px per side.
+ *
+ * Zero on every side is the honest default: a stage that has not been told
+ * anything draws in the corners, which is where it drew before this existed.
+ */
+export interface StageInset {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface PickModifiers {
+  shift: boolean;
+  meta: boolean;
+  alt: boolean;
+  /**
+   * The hits came from a MARQUEE, not from a click.
+   *
+   * ── WHY THE CHROME CANNOT TELL THEM APART WITHOUT THIS ──────────────────
+   *
+   * `onPick`'s list means two different things. For a click it is the ordered
+   * HIT STACK under one point — front-most first, and a plain click takes the
+   * front one while meta walks behind it. For a marquee it is the SET the box
+   * enclosed, and every one of them is selected.
+   *
+   * Without the discriminator the chrome ran the click policy over both, so a
+   * box drawn over five layers took `hits[0]` and selected exactly one. Box
+   * select has never worked.
+   *
+   * It also decides what an EMPTY list means. BOTH DESELECT — a rubber band
+   * that caught nothing is still the author saying "not that", which is what
+   * Figma and Blender both do. Only the ISOLATION half differs: an empty click
+   * leaves the subtree, and an empty marquee does not, because a band drawn
+   * inside a card that caught nothing is not a request to leave the card.
+   */
+  marquee?: boolean;
+}
+
+/** What the stage installs on `window.__shotStudio`. */
+export interface ShotStageBridge {
+  version: number;
+  /** Register the chrome's handlers. The stage renders NOTHING until this is
+   *  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;
+  /** Park the studio clock on an integer MASTER frame and repaint. */
+  seek(frame: number): void;
+  /** Which layers are selected, for the overlays. */
+  setSelection(ids: readonly string[]): 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.
+   *
+   *  The pane defaults to "camera" — the pane that IS the export, and the only
+   *  one that existed at v1 — so a caller that does not know about the split
+   *  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.
+   */
+  setTool(tool: ShotTool): 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;
+  /** 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;
+  /**
+   * How many views are on screen, and how the width is divided.
+   *
+   * WORKSPACE STATE, not document state: it is never written to a Doc3D and
+   * never reaches an export. The stage holds no copy it was not handed, so this
+   * is re-pushed on every attach.
+   */
+  setStageLayout(layout: StageLayout): void;
+  /**
+   * ISOLATE A SUBTREE, or null for the whole scene.
+   *
+   * WORKSPACE STATE, like the layout: never written to a Doc3D, never in an
+   * export. The stage is handed one id and derives everything from the document
+   * it already has — the subtree's members, the head-on camera, and which
+   * layers to dim — so the chrome never sends a set that could disagree with
+   * the tree.
+   *
+   * It takes the WORKING PANE's slot rather than adding a third view. A
+   * scissored pane per mode is the trap SplitRenderer's header is about, and
+   * the two views an author wants while inside a card are "this card, flat" and
+   * "the shot", which is exactly the split that already exists.
+   */
+  setIsolation(layerId: string | null): void;
+  /**
+   * Inside isolation, does the AUTHOR own the working camera?
+   *
+   * False is the entry state and means the derived orthographic head-on rig
+   * draws the pane. True means the ordinary perspective orbit rig does, driven
+   * by `workingView` exactly as it is outside isolation. See
+   * `onIsolationOrbitTaken` for why the mode exists at all.
+   *
+   * Pushed rather than inferred, because the CHROME owns it: it is the half
+   * that clears the mode on Home, on numpad-dot and on leaving the subtree, and
+   * the half whose `writeFramingFromView` must refuse while the derived rig is
+   * in the slot. A stage that decided for itself would be a second opinion on
+   * which camera is drawing.
+   *
+   * `setIsolation` resets it to false on its own, so entering a subtree never
+   * inherits the last one's mode.
+   */
+  setIsolationOrbit(taken: boolean): void;
+  /**
+   * How far the chrome's own furniture reaches INTO the stage, per side, in CSS
+   * px.
+   *
+   * ── 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.
+   *
+   * `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
+   * answer". Four now do, and two of them — the isolation bar and the follow
+   * bar — sat entirely behind the opaque header, while the G/R/S pill, the only
+   * 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.
+   *
+   * Editor state, never a document field.
+   */
+  setStageInset(inset: StageInset): void;
+  /**
+   * The working pane's shading (solid / wireframe / material / rendered).
+   *
+   * WORKSPACE STATE like the layout: never written to a Doc3D, never in an
+   * export, re-pushed on every attach. The camera pane is not addressable
+   * here — it is always the graded render, by construction.
+   */
+  setShadingMode(mode: ShadingMode): 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,
+   *  the same contract `fitView` has — the stage owns the derivation because it
+   *  owns the lens the distance is derived from. */
+  fitWorkingView(): WorkingView;
+  /**
+   * "Camera follows this view" is armed.
+   *
+   * 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.
+   */
+  setCameraFollowsView(on: boolean): 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`. */
+  closeDoc(): void;
+  /** Drop the stage's raster cache. Called on document CLOSE, AFTER
+   *  `closeDoc` — the bitmaps are known dead because the doc-clear that
+   *  precedes this call unmounts every plane, not merely because the chrome
+   *  closed a panel. Not called on scene switch: surviving a switch warm is
+   *  the whole reason the cache is module-level. */
+  clearCaches(): void;
+  /** Tear the stage down (a chrome unmount, or a bridge version mismatch). */
+  dispose(): void;
+}
+
+declare global {
+  interface Window {
+    __shotStudio?: ShotStageBridge;
+  }
+}

package/src/channels.ts

@@ -0,0 +1,40 @@
+// The eight channels the block system writes, each with its label and its
+// resolved-value formatter.
+//
+// This list IS resolve.ts's combinator table, in the order the composition is
+// written there — and it is the chrome's ONE copy. The inspector's Resolved
+// section and the dock's channel rows both read it, so an eighth channel added
+// in resolve.ts without a row here is a value the author has no way to see in
+// either place, which is how a delta model becomes folklore.
+import { formatValue } from "@dailies-studio/ui";
+import type { LayerDelta, LayerState } from "@dailies-studio/shot/doc";
+
+/** The channel names, exactly as `LayerDelta` declares them. */
+export type Channel = keyof Required<LayerDelta>;
+
+export interface ChannelSpec {
+  key: Channel;
+  label: string;
+  /** The channel's value as the author sees it — from `resolveLayerAt`'s
+   *  output, never a second fold. */
+  read(state: LayerState): string;
+}
+
+export const CHANNELS: readonly ChannelSpec[] = [
+  { key: "opacity", label: "Opacity", read: (s) => formatValue(s.opacity, 0.01) },
+  // Position, size, tilt and roll read the layer's own value WITH the delta
+  // folded in, because that is the number on screen.
+  { key: "offset", label: "Position", read: (s) => s.position.map((v) => formatValue(v, 0.1)).join(", ") },
+  { key: "scale", label: "Size", read: (s) => `${formatValue(s.size[0], 0.1)} × ${formatValue(s.size[1], 0.1)}` },
+  { key: "tilt", label: "Tilt", read: (s) => `${formatValue(s.tilt[0], 0.1)}°, ${formatValue(s.tilt[1], 0.1)}°` },
+  { key: "roll", label: "Roll", read: (s) => `${formatValue(s.rollDeg, 0.1)}°` },
+  // Blur, reveal and stagger have no base at all: they exist only as block
+  // output, so the resolved value IS the fold.
+  { key: "blurPx", label: "Blur", read: (s) => `${formatValue(s.blurPx, 0.1)} px` },
+  { key: "reveal", label: "Reveal", read: (s) => `${formatValue(s.reveal * 100, 1)}%` },
+  { key: "textPhase", label: "Stagger", read: (s) => `${formatValue(s.textPhase * 100, 1)}%` },
+];
+
+export const CHANNEL_BY_KEY: ReadonlyMap<Channel, ChannelSpec> = new Map(
+  CHANNELS.map((c) => [c.key, c]),
+);

package/src/main.tsx

@@ -0,0 +1,15 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { createShotEditorStore } from "./state/store.js";
+import { StoreProvider } from "./state/context.js";
+import { App } from "./app/App.js";
+import "./styles.css";
+
+const store = createShotEditorStore();
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <StoreProvider store={store}>
+      <App />
+    </StoreProvider>
+  </StrictMode>,
+);