@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/types.ts

@@ -15,21 +15,477 @@
 // So: one document, flat fields, and roughly 1700 lines of board machinery
 // simply not written. Autosave debounce, the sha256 rev and the generation
 // fence all still apply — they were never board-shaped, only board-keyed.
-import { DOCK_HEIGHT, RAIL_WIDTH } from "./panelSize.js";
-import type { Doc3D } from "@dailies-studio/shot/doc";
-import type { AgentCredentialsInfo, AgentTranscriptItem } from "@dailies-studio/agent-client";
+import {
+  CODE_PREVIEW_FRAMES,
+  defDurationFrames,
+  docDurationFrames,
+  sceneToMaster,
+} from "@dailies-studio/shot/doc";
+import {
+  CODE_LIVE_WIDTH,
+  DOCK_HEIGHT,
+  DOCK_PPF,
+  INSPECTOR_WIDTH,
+  MATERIAL_COLUMN,
+  RAIL_WIDTH,
+} from "./panelSize.js";
+import type {
+  Doc3D,
+  MaterialGraphSocketType,
+  MeshMaterialSlotInfo,
+} from "@dailies-studio/shot/doc";
+import type { Ease } from "@dailies-studio/engine";
+import type {
+  AgentCredentialsInfo,
+  AgentTranscriptItem,
+} from "@dailies-studio/agent-client";
 import type { Contract } from "@dailies-studio/contract";
-import type { ComponentRow, RenderJob, ShotListing } from "../api.js";
-import type { ShadingMode, ShotStageInfo, ShotView, StageLayout, StagePane, WorkingView } from "../bridgeTypes.js";
+import type {
+  CodeDiagnostic,
+  ComponentDefaultsMeta,
+  ComponentFileHome,
+  ComponentListingUpdate,
+  ComponentRow,
+  LibraryItem,
+  LibraryItemDetail,
+  LibraryItemKind,
+  ProjectAssetUsage,
+  ProjectFile,
+  RenderJob,
+  ShotVersion,
+  ShotVersionList,
+  WorkspaceComponent,
+  WorkspaceComponentVersion,
+  WorkspaceComponentVersionInfo,
+  WorkspaceFontList,
+} from "../api.js";
+import type { GoogleFontEntry } from "../fonts/googleFonts.js";
+import type { FontApplyProgress } from "./fonts.js";
+import type { Value } from "@dailies-studio/engine";
+import type {
+  PlaybackResolution,
+  ShadingMode,
+  ShotComponentBackground,
+  ShotStageInfo,
+  StagePerformanceReport,
+  StagePieceFailure,
+  ShotView,
+  SplineBasis,
+  SplineEditContext,
+  StageInset,
+  StageLayout,
+  StagePane,
+  WorkingView,
+  WorkPlaneTarget,
+} from "../bridgeTypes.js";
 import { INITIAL_WORKING_VIEW } from "../stage/workingView.js";
 import type { DrawPoint } from "./insert.js";
 import type { ShotTool } from "../tools.js";
+import type { SyncStatus } from "./sync.js";
 
 export type SaveState = "idle" | "saving" | "saved" | "error";
 
+/** The dialog a delete under live sync shows (`syncDeleted`). */
+export interface SyncDeleted {
+  /** The Project's store name and title when it was trashed. */
+  name: string;
+  title: string;
+  /** Who trashed it, by name; null when it was this user or is unknown. */
+  by: string | null;
+  color: string | null;
+  /** The Trash handle; null when the session did not say (no Restore). */
+  trashId: string | null;
+  /** `describePending` of what waits. */
+  lines: string[];
+  count: number;
+  /** A Restore or Save as copy is under way. */
+  busy: boolean;
+  error: string | null;
+}
+
+/** The Components workspace's two tabs: the component alone on the stage, or
+ *  the studio that edits it (Component Studio or Code Studio). */
+export type ComponentsTab = "preview" | "edit";
+
+/** The shot board's tools (its footer): Select V, Text T, Box R, Arrow A,
+ *  Image I and Component C. Image and Component open their pickers. */
+export type SketchTool = "select" | "text" | "box" | "arrow" | "image" | "component";
+
+/** Which component the Components workspace shows: a Studio-made definition
+ *  of this document, or a code component by registry id. */
+/** One use whose changes have no prop in a newer version: where it is, and
+ *  the keys. The changes stay on the use, kept aside, not applied. */
+export interface ComponentUpdateRemoved {
+  where: string;
+  keys: string[];
+}
+
+/** An Update waiting for a yes, with the props it drops that uses changed. */
+export interface ComponentUpdatePending {
+  defId: string;
+  version: number;
+  /** True for a Community copy: the server writes it, so the yes is always
+   *  asked and says how to take it back. */
+  community: boolean;
+  /** One entry per use that loses a changed prop. Null when the Community
+   *  listing's definition could not be read first: its list then comes after
+   *  the update, in `ComponentUpdateApplied`. */
+  removed: ComponentUpdateRemoved[] | null;
+}
+
+/** A Community update the server wrote into this document, held so the
+ *  author sees what it kept aside and can put the document back. */
+export interface ComponentUpdateApplied {
+  defId: string;
+  version: number;
+  removed: ComponentUpdateRemoved[];
+  /** The document the server wrote against, and the one it wrote. Revert
+   *  update puts `before` back only while the open document is `after`. */
+  before: Doc3D;
+  after: Doc3D;
+}
+
+export type ComponentsSelection = { kind: "studio"; def: string } | { kind: "code"; module: string };
+
+/** The Shot a door into Components left (C7): the entered Shot, the playhead,
+ *  the selection, and the use the door opened (`layerUseKey`). `shotFrame` is
+ *  the frame inside that Shot, for the crumb. */
+export type ComponentsOrigin = {
+  sel: ComponentsSelection;
+  useKey: string;
+  enteredScene: string | null;
+  sceneId: string | null;
+  frame: number;
+  shotFrame: number;
+  selection: readonly string[];
+};
+
+/** The Components workspace's preview look (bridge v45). Null fields keep the
+ *  stage's own ground and the component's own length. */
+/** One build check of a code component. */
+export interface ComponentBuild {
+  status: "building" | "built" | "failed";
+  /** Why it failed. */
+  message?: string;
+  /** The workspace version the passing build recorded. */
+  version?: number;
+}
+
+export interface ComponentPreviewLook {
+  background: ShotComponentBackground | null;
+  loopFrames: number | null;
+}
+
+/** The Insert drawer's sections, top to bottom, and its jump chips. */
+export const INSERT_SECTIONS = ["Basics", "Icons", "Shaders", "Backgrounds"] as const;
+export type InsertSection = (typeof INSERT_SECTIONS)[number];
+
+/**
+ * What the open source buffer is doing, when it is doing something other than
+ * sitting there.
+ *
+ * DIRTY IS NOT IN HERE. It is `content !== savedContent`, a comparison that
+ * cannot be stale, and a status value that also claimed to know would be a
+ * second answer to the same question — the one that ends up disagreeing after
+ * an undo lands the buffer back on the saved text.
+ *
+ * `"conflict"` is STICKY: the file changed on disk under the buffer (a 409, or
+ * an agent's edit arriving over SSE) and stays that way until the author picks
+ * reload or overwrite, because silently choosing either one loses work.
+ */
+export type CodeStatus = "idle" | "saving" | "conflict" | "error";
+
+/**
+ * The source file behind the open code component.
+ *
+ * SAVES EXPLICITLY (Ctrl+S), never on keystroke: every save re-runs contract
+ * extraction and reloads the stage, so autosaving half-typed code would thrash
+ * both and show the author a stream of broken renders they did not ask for.
+ */
+export interface CodeFileState {
+  /** Posix path relative to the project root, which is `ComponentRow.rel`. */
+  rel: string;
+  /** Live editor text, LF-normalised (CodeMirror is LF-only internally). */
+  content: string;
+  /** Text at last load or save, LF. Dirty is `content !== savedContent`. */
+  savedContent: string;
+  /** Server hash at last load or save, sent as `baseHash` so a save can 409. */
+  savedHash: string | null;
+  /** Restored on save, so a CRLF file round-trips as CRLF. */
+  lineEnding: "lf" | "crlf";
+  status: CodeStatus;
+  /** What went wrong, when `status` is "error" or "conflict". */
+  error: string | null;
+  /** The HTTP status behind `error`. 404 means the file was deleted on disk. */
+  errorStatus: number | null;
+  diagnostics: readonly CodeDiagnostic[];
+  /**
+   * This file is a BUILD PRODUCT the studio itself emits, so the server will
+   * refuse every write to it with a 403 and no force.
+   *
+   * Carried on the buffer so the editor can say so BEFORE the author types a
+   * page of changes into a file that cannot accept them. Read from the file's
+   * own bytes on the way in (`SourceFile.generated`), not guessed from the
+   * path: the marker rule catches an emit that moved, and the directory rule
+   * alone would miss it. `docName` is the owning Project's store name when
+   * the server resolved it, so the strip can open it.
+   */
+  generated: { docName: string | null } | null;
+}
+
+/** The viewport/editor state borrowed while one mesh's material graph is open.
+ * None of it is document data: leaving the graph hands the author back the
+ * exact stage, camera and tool posture they were using before they went in. */
+export interface MaterialWorkspaceRestore {
+  selection: readonly string[];
+  stageLayout: StageLayout;
+  workingView: WorkingView;
+  activePane: StagePane;
+  shadingMode: ShadingMode;
+  previousShading: ShadingMode;
+  tool: ShotTool;
+  pilot: boolean;
+  isolation: string | null;
+  isolationOrbit: boolean;
+  splineEdit: SplineEditContext | null;
+  animateMode: boolean;
+}
+
+/** A persistent material-authoring context over the live stage. The target is
+ * addressed by its container because component definitions and shots can both
+ * contain mesh ids, while the graph itself is resolved through the layer's
+ * current material binding on every document update (undo may replace it). */
+export interface MaterialWorkspaceState {
+  containerId: string;
+  layerId: string;
+  /**
+   * WHICH SURFACE of the target the graph is editing (schema v17).
+   *
+   * A glTF material index, or null for the layer-wide binding — which is the
+   * only possibility on a primitive, and the default on a model until the
+   * author picks a slot. Editor state: the DOCUMENT records the binding, and
+   * this records which one is on the canvas.
+   */
+  slot: number | null;
+  restore: MaterialWorkspaceRestore;
+}
+
+/** What the graph canvas has selected. Nodes and edges together because one
+ *  rubber band picks up both, and Delete acts on whatever it caught. */
+export interface MaterialGraphSelection {
+  nodeIds: readonly string[];
+  edgeIds: readonly string[];
+}
+
+/**
+ * The socket a palette was opened FROM, when the author dragged a wire into
+ * empty space rather than pressing Tab.
+ *
+ * `side` says which end of the wire is in hand: `"source"` means the author is
+ * holding an OUTPUT and wants something to feed, `"target"` means they are
+ * holding an input and want something to feed it. The type rides along so the
+ * palette can put the kinds that would actually connect at the top, rather than
+ * letting the author find out by dropping one and being refused.
+ */
+export interface MaterialPaletteSource {
+  nodeId: string;
+  socket: string;
+  side: "source" | "target";
+  type: MaterialGraphSocketType;
+}
+
+/**
+ * "Open the node palette here". A MAILBOX, like `stageMenu` and `appMenu`, with
+ * the same fresh-identity rule: pressing Tab twice at the same point must
+ * re-open the palette rather than be swallowed by value equality.
+ *
+ * `at` is a point in GRAPH coordinates, or null when the palette should place
+ * what it adds wherever the canvas considers the middle — the keyboard route,
+ * which has no pointer to ask.
+ */
+export interface MaterialPaletteRequest {
+  at: { x: number; y: number } | null;
+  from?: MaterialPaletteSource;
+}
+
+/** Stage-originated shader status. Kept separate from the document because a
+ * compiler result says what this browser rendered, never what the author saved. */
+export type MaterialCompileState =
+  | { status: "idle" }
+  | {
+      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;
+    };
+
+/**
+ * ONE KEYFRAME, AS A CURVE GESTURE ADDRESSES IT.
+ *
+ * ── AND WHY THIS ONE IS BY ID WHEN `selectedKeyframe` IS BY POSITION ──────
+ *
+ * `selectedKeyframe`'s comment argues that a PERSISTED subject must be a
+ * position: a key can be replaced by a drag landing on its frame, and an id
+ * kept across that would address something that is gone.
+ *
+ * A curve gesture is the opposite case. It runs inside ONE scrub, every capture
+ * re-derives from the same base document, and the whole point of the drag is
+ * that the frame is CHANGING. A position captured at the press would be right
+ * for one pointer event and wrong after it; the id is stable for exactly as
+ * long as the gesture is, and `captureCurveOps` resolves it against the base —
+ * never against the live document.
+ */
+export interface CurveKeyRef {
+  containerId: string;
+  /** Null = the SHOT itself, the address every keyframe verb already takes. */
+  layerId: string | null;
+  path: string;
+  /** The keyframe's own `kf_…` id. */
+  keyframeId: string;
+  /** Which component of a VECTOR track the value edit writes. Absent on a
+   *  scalar track; a vector's keyframe frames are shared across components
+   *  because they are one track. */
+  component?: number;
+}
+
+/** A curve gesture's edits, applied in order inside one scrub capture. A batch
+ *  and not one call each because a keyframe drag MOVES and SETS THE VALUE
+ *  atomically, and two captures would be two undo entries and one visible
+ *  intermediate document. */
+export type CurveOp =
+  | {
+      kind: "move";
+      /** `keys[0]` ANCHORS: every key moves by one delta, and a snapped move
+       *  snaps the first one's landing and applies what it got back to the rest,
+       *  so the shape of a multi-key selection survives the pull. */
+      keys: readonly CurveKeyRef[];
+      deltaFrames: number;
+      /** Pull the anchor onto a nearby edge — THE ROWS' snap, same targets and
+       *  same threshold. Off (absent) is the raw rounded delta. */
+      snap?: boolean;
+    }
+  | { kind: "setValue"; key: CurveKeyRef; value: number }
+  | { kind: "setEase"; keys: readonly CurveKeyRef[]; ease: Ease };
+
+/**
+ * ONE KEYFRAME'S ADDRESS, as the store holds it and every keyframe verb takes
+ * it: which container, which layer (null = the shot itself), which path, which
+ * frame. See `selectedKeyframes` for why it is a position and not an id.
+ */
+export interface KeyframeSel {
+  containerId: string;
+  layerId: string | null;
+  path: string;
+  frame: number;
+}
+
+/** Do these two addresses name the same keyframe? All four fields, because
+ *  that is the whole address — a path match in the wrong container is a
+ *  different key on a different layer. */
+export function sameKeyframeSel(a: KeyframeSel, b: KeyframeSel): boolean {
+  return (
+    a.containerId === b.containerId &&
+    a.layerId === b.layerId &&
+    a.path === b.path &&
+    a.frame === b.frame
+  );
+}
+
+/** The same identity as a Map key. A PIPE, `curveRowId`'s reason: every part is
+ *  an id slug or a dotted path and none of them can contain one. */
+export function keyframeSelKey(a: KeyframeSel): string {
+  return `${a.containerId}|${a.layerId ?? ""}|${a.path}|${a.frame}`;
+}
+
+/**
+ * The selection's PRIMARY keyframe, or null.
+ *
+ * Every consumer that describes ONE keyframe — the inspector's heading, the
+ * curve pane's subject ladder, "which track am I looking at" — reads this
+ * rather than indexing the array, so widening the field stayed a rename at
+ * each of those sites instead of a decision at each of them.
+ */
+export function primaryKeyframe(s: {
+  selectedKeyframes: readonly KeyframeSel[];
+}): KeyframeSel | null {
+  return s.selectedKeyframes[0] ?? null;
+}
+
+/**
+ * EVERY SPEED THE SHUTTLE HAS, in ladder order.
+ *
+ * A closed list rather than a number, so "what does a third press of J do" has
+ * one answer and no caller can invent 3.5x. `1` is the resting rate and the one
+ * every start returns to; the negatives run the picture backwards.
+ *
+ * SIX AND NOT MORE. Each rung is a doubling, which is the only spacing where a
+ * press feels like a step rather than a nudge, and 4x at 30fps is already 120
+ * distinct frames a second — past that the display, not the ladder, is the
+ * limit.
+ */
+export const SHUTTLE_RATES = [-4, -2, -1, 1, 2, 4] as const;
+
+export type PlayRate = (typeof SHUTTLE_RATES)[number];
+
+/**
+ * A window of MASTER frames, half open: `start` plays, `end` does not.
+ *
+ * The shape `sceneWindows` already uses, deliberately — the playback clock
+ * wraps `[start, end)` for an entered shot and for a work area with the same
+ * arithmetic, and a closed range here would need one of the two to subtract a
+ * frame that the other does not.
+ */
+export interface WorkArea {
+  start: number;
+  end: number;
+}
+
+/**
+ * One ask for the dock to show some layers' rows (`dockReveal`).
+ *
+ * THREE SEPARATE ANSWERS, because the two askers want different amounts. The
+ * board's "Fine-tune in Studio" selects keys, and a key on a closed row is a
+ * selection nobody can see, so it opens the layer's own lanes. A pick on the stage or in Layers only wants the row in view: opening
+ * its lanes would grow the dock under the author on every click.
+ */
+export interface DockReveal {
+  layerIds: readonly string[];
+  /** Open each layer's own channel lanes (the shot context's disclosure). */
+  lanes: boolean;
+  /** Open the row's shot group and scroll the first layer's row into view. */
+  scroll: boolean;
+  /** Flash the first layer's row once (`is-revealed`). */
+  flash: boolean;
+  /** Audio clip ids to show (gap 8). Sound mode scrolls to the first clip's
+   *  track row and flashes it; the other modes have no clip rows to show. */
+  audioIds?: readonly string[];
+}
+
+/** The Preferences page fields `setEditorPref` writes. The grid, the badges
+ *  and the playhead rule keep their older setters. */
+export type EditorPrefField =
+  | "motionPaths"
+  | "rulers"
+  | "smartGuides"
+  | "blockLabels"
+  | "fieldLabels"
+  | "toolbarPosition"
+  | "playbackResolution";
+
 export interface ShotEditorState {
-  /** Everything in `.studio/shots/`, for the switcher. */
-  shots: readonly ShotListing[];
   /** The open document's store name, or null at the empty state. */
   name: string | null;
   doc: Doc3D | null;
@@ -40,47 +496,203 @@ export interface ShotEditorState {
   /** MASTER frame. Integer, always. */
   frame: number;
   playing: boolean;
+  /**
+   * HOW FAST, AND WHICH WAY, the transport runs. Only read while `playing`.
+   *
+   * A WORKSPACE PREF and never the document: it is the author holding a key to
+   * find a moment, in the same family as `previewVolume` and for the same
+   * reason — an export that came out at 4x because somebody shuttled would be
+   * the worst kind of silent corruption. `setPlaying(true)` puts it back to 1,
+   * so a shuttle is never a mode the author has to remember to leave.
+   *
+   * THE PICTURE ONLY. See `transportAudible`: sound is silent at every rate but
+   * 1, because reverse needs reversed buffers and 2x needs a time stretcher,
+   * and either one is a second clock that can disagree with the picture's.
+   */
+  playRate: PlayRate;
+  /**
+   * WHETHER THE PROJECT TRANSPORT LOOPS its window (the work area, or the whole
+   * film). Off, playback stops on the window's last frame. The dock's Loop
+   * button, in the Project context only: a shot or a definition always loops,
+   * because those are the views an author watches a beat in over and over
+   * (`playbackLoops` is the effective answer). A workspace pref like
+   * `playRate`, carried across a document switch by `workspacePrefs`.
+   */
+  loopPlayback: boolean;
+  /**
+   * A QUEUED PLAY, or null: Play is on and the transport has not started.
+   *
+   * `"armed"` waits for the stage to be ready (`stageReady`), `"preparing"`
+   * runs a Play pass that has drawn `done` of `total` frames (each frame
+   * playback would pay a first-use cost on, see `playbackPreparation.ts`), and
+   * `"starting"` waits for the stage to hand over on the start frame. The
+   * transport then starts by itself, in one write that clears this and sets
+   * `playing` and `playOrigin`.
+   *
+   * `playing` stays the transport's truth and is false while this is set.
+   * Every toggle reads `playOn`, so a second press cancels a queued Play. The
+   * same pass run while the author sits paused (the background pass) sets no
+   * intent: it is no start, and nothing on screen shows it.
+   */
+  playIntent: { phase: "armed" | "preparing" | "starting"; done: number; total: number } | null;
+  /**
+   * WHERE AND WHEN THE TRANSPORT STARTED, or null while it is stopped: the
+   * frame (`defFrame` inside a definition) and the `performance.now()` of the
+   * start. Written in the same write that turns `playing` true, and cleared
+   * on every stop. The picture clock and the audio session both anchor on
+   * it, so picture and sound start from one instant.
+   */
+  playOrigin: { frame: number; at: number } | null;
+  /**
+   * THE WORK AREA: the window playback loops inside, or null for the whole
+   * document.
+   *
+   * MASTER frames, half open — `[start, end)`, the shape `sceneWindows` uses,
+   * so "the last frame" needs no off-by-one anywhere.
+   *
+   * SESSION STATE AND DELIBERATELY NOT A DOCUMENT FIELD. It is a monitoring
+   * preference, like the preview volume: a document field would cost a schema
+   * bump and a migration for something that is not part of the film, and the
+   * render side already owns an internal frame range a CLI flag can reach
+   * without touching the document at all.
+   *
+   * IT IS ALSO NOT A WORKSPACE PREF, which is the one place it parts company
+   * with `playRate`: these are frames of THIS document, and carrying them to
+   * the next one would loop the transport over a window that means nothing
+   * there. `workspacePrefs` leaves it out on purpose, so a document switch
+   * clears it.
+   *
+   * It applies only in the scene context. A shot already loops inside its own
+   * window and a component definition runs its own clock, so both of those
+   * have an answer already and a second window would be two answers.
+   */
+  workArea: WorkArea | null;
 
-  /** Which scene the micro timeline and the inspector are looking at. This is
-   *  the SINGLE bit that decides macro vs micro, and it is the same bit the URL
-   *  mirrors — one two-level model, not two. */
+  /**
+   * Which shot the inspector and the isolation scope are looking at: the one
+   * the PLAYHEAD is in, or the one a row/strip click has pinned.
+   *
+   * DERIVED, NOT A MODE BIT. `sceneAt` ends `?? doc.scenes[0] ?? null`, so it is
+   * non-null for any open document, and `seek`, `onHistoryChange` and
+   * `loadInto` all rewrite it. It used to be described here as "the single
+   * bit that decides macro vs micro" — that was true of the two-level dock this
+   * lane deleted, and stayed on the field for a release after the thing it
+   * described was gone. The macro/micro bit is `enteredScene`, below.
+   */
   sceneId: string | null;
+  /**
+   * The shot the author has ENTERED, or null for the scene context.
+   *
+   * THE ONE CONTEXT BIT, and the reason it is a field of its own rather than a
+   * reading of `sceneId`: `sceneId` follows the playhead, so "no shot entered"
+   * has no spelling in it at all.
+   *
+   *   null           → SCENE context. Arrange shots, aim the camera, grade.
+   *   set            → SHOT context. The elements of that shot and their
+   *                    property lanes.
+   *   `editingDef`   → COMPONENT context, nested inside the shot context.
+   *
+   * Written ONLY by `enterScene`/`leaveScene` (and the document-swap clear),
+   * never derived. While it is set the master playhead is clamped inside that
+   * shot's window by `clampToEntered`, which is what keeps every one of the
+   * ~83 existing `sceneId` readers correct with no edit: `sceneAt` can only
+   * ever answer with the entered shot.
+   */
+  enteredScene: string | null;
   /** Layer ids, in document order, deduped. */
   selection: readonly string[];
 
   /** Which tool is armed. Decides what a canvas press does, and which plane a
    *  move unprojects onto. */
   tool: ShotTool;
+  /** Per-shot construction planes. Editor state only and reset on project load. */
+  workPlanes: Readonly<Record<string, WorkPlaneTarget>>;
+  /** Interpolation used by the next Shift+P draft. A workspace preference. */
+  splineBasis: SplineBasis;
+  /** The spline whose anchors are being edited, or null for layer mode. */
+  splineEdit: SplineEditContext | null;
 
   /**
-   * TWO MODE BITS, and collapsing them would be a data-corrupting surprise.
+   * ⇧A, Animate: edits write keyframes at the playhead.
    *
-   * `inspectorMode` is a VIEW choice, set by clicking the inspector's tabs.
-   * `animateMode` is a BEHAVIOUR choice, set ONLY by ⇧A: with it on, a canvas
-   * drag authors a BLOCK ending at the playhead instead of writing the base.
+   * With it on, every author edit (a drag, a typed value, a nudge) still lands
+   * as a value, and the store then keys each static field it moved: the old
+   * value at the layer's start and the new one at the playhead, in the same
+   * undo step (`noteChange`, store.ts). A field a track already writes is
+   * keyed at the playhead whether this is on or not. An agent apply never
+   * records.
    *
-   * One bit would mean that clicking "Animate" to LOOK at the blocks silently
-   * arms block authoring on the next drag.
+   * A BEHAVIOUR bit: nothing but ⇧A and its toolbar button may write this, so
+   * looking at a panel never arms recording on the next drag.
    */
-  inspectorMode: "design" | "animate";
   animateMode: boolean;
 
   /**
-   * The block the dock has focused, or null.
+   * The camera move the dock has focused, or null.
    *
-   * Addressed by (scene, layer, block) even though a block id is unique across
-   * the document. The layer is what tells a row which lane it is in without a
-   * lookup; the SCENE is what stopped being derivable when the dock became one
-   * master strip. `state.sceneId` follows the playhead, so a block clicked in
-   * scene 3 while the playhead sits in scene 1 would have sent Delete and Split
-   * at scene 1 — where the id does not exist, so both would have silently done
-   * nothing.
+   * Addressed by (scene, shot) even though a shot id is unique across the
+   * document: the SCENE is what stopped being derivable when the dock became
+   * one master strip. `state.sceneId` follows the playhead, so a move clicked
+   * in scene 3 while the playhead sits in scene 1 would have sent Delete at
+   * scene 1, where the id does not exist, and it would silently do nothing.
+   */
+  selectedMove: { sceneId: string; shotId: string } | null;
+  /**
+   * The track keyframes the dock has focused. Empty when none is.
+   *
+   * ── ADDRESSED BY POSITION, NOT BY ID ────────────────────────────────────
+   *
+   * A `kf_…` id exists and is unique, and this deliberately does not use it. The
+   * three edits an author makes to a keyframe are "move it", "ease it" and
+   * "delete it", and every one of them is `(track, frame)` — `setKeyframeAt`
+   * REPLACES by frame, and a drag onto an occupied frame replaces the key that
+   * was there. Keying selection on an id would leave it pointing at a keyframe
+   * a drag had just replaced, which is a stale subject with no symptom until
+   * Delete removes the wrong thing.
+   *
+   * The container is carried for `selectedMove`'s reason, one level up: a
+   * definition's interior tracks live under a `cd_…` id and a shot's under a
+   * `sc_…` one, and `state.sceneId` follows the playhead, so a diamond clicked
+   * in another shot would have sent Delete somewhere it does not exist.
+   *
+   * `layerId: null` means the SHOT ITSELF is the subject — its background and
+   * its post stack (P5). Null rather than a second field, because every verb
+   * that acts on a keyframe already carries the whole address and a parallel
+   * `sceneKeyframe` would double each of them.
+   *
+   * ── A LIST, WITH `[0]` AS THE PRIMARY ─────────────────────────────────
+   *
+   * Box-select in the graph, dragging four keys at once, applying one ease to
+   * a run and copy/paste are all the same missing capability, and this single
+   * field was the whole of what was missing: `CurveGraph` and `TimelineModel`
+   * were already written for a set (`selectedAddrs`, `selectKeyframes(refs,
+   * mode)`, `move.refs[]`) and only this store answered with one.
+   *
+   * ORDERED, and `[0]` is the PRIMARY — what the inspector describes, what the
+   * curve pane focuses, what a "which track" question resolves against. The
+   * most recently added entry becomes primary, which is what makes shift-click
+   * feel like extending a selection rather than shuffling it.
+   *
+   * Still POSITIONS, for the reason above: ids stay a gesture-scope concept,
+   * resolved against a drag's own base.
+   */
+  selectedKeyframes: readonly KeyframeSel[];
+  /**
+   * ROWS or GRAPH: which face the dock's track area shows.
+   *
+   * The AE / Rive posture, and a MODE rather than a second panel because the two
+   * answer the same question at different resolutions — "when does this happen"
+   * and "how does it move" — and a graph beside the rows would take the height
+   * the rows need to be readable at all.
+   *
+   * In the store rather than in the dock because the keymap toggles it and the
+   * dock's own `open`/`openShots` sets do not have that problem.
    */
-  selectedBlock: { sceneId: string; layerId: string; blockId: string } | null;
+  dockMode: "rows" | "graph" | "sound";
   /**
    * The marker the strip has selected, or null.
    *
-   * A BARE ID, unlike `selectedBlock`: a marker belongs to the document rather
+   * A BARE ID, unlike `selectedMove`: a marker belongs to the document rather
    * than to a scene (`MarkerRef.frame` is a master frame), so there is nothing
    * to address it relative to and nothing that can go stale under a retime.
    *
@@ -89,6 +701,25 @@ export interface ShotEditorState {
    * Delete" can never remove a marker the author stopped looking at.
    */
   selectedMarker: string | null;
+  /**
+   * The audio clips the Sound dock has selected (gap 8): clip ids in either
+   * home. The next subject after the marker for Delete, ⌘D, ⌘B and Q / W.
+   *
+   * It KEEPS the layer selection, because the inspector keeps showing the
+   * layer and a clip has no inspector of its own. Any other focus (a camera move, a
+   * key, a marker, a layer pick) clears it.
+   */
+  selectedAudio: readonly string[];
+  /**
+   * Per-tab SOLO: the track ids this tab hears alone. Monitoring, never the
+   * document: not saved, not synced, never in an export. Empty is the full mix.
+   */
+  soloTracks: readonly string[];
+  /** Snap drags to the beat grid when the document has a tempo. Per tab. */
+  snapBeats: boolean;
+  /** A note the dock shows in its head, such as "3 clips split". Not an
+   *  error; the dock drops it after a moment. */
+  dockNotice: { text: string } | null;
   /**
    * The box a drawn IMAGE layer is waiting to land in, or null.
    *
@@ -111,13 +742,279 @@ export interface ShotEditorState {
    * inside the iframe is a different document's event and never reaches the
    * chrome window's outside-click listener.
    */
-  stageMenu: { at: { x: number; y: number }; hits: readonly string[]; pane: StagePane } | null;
+  stageMenu: {
+    at: { x: number; y: number };
+    hits: readonly string[];
+    pane: StagePane;
+    /** Set when the press landed on a motion path dot (gap 3): the menu is
+     *  that key's, not the layer's. */
+    pathKey?: { layerId: string; keyId: string };
+  } | null;
+  /**
+   * ⌘K asked for the app menu. A MAILBOX, like `stageMenu` above, and for the
+   * same reason and with the same identity rule: fresh object per press, so a
+   * second ⌘K re-opens rather than being swallowed by value equality.
+   *
+   * It carries NOTHING — the menu opens under its own trigger, whose rect only
+   * the header knows. The object exists so that an effect has an identity to key
+   * on; a boolean would need a second verb to put it back.
+   *
+   * Never persisted, never a document edit, and never cleared by the store: the
+   * menu owns its own dismissal (Escape, an outside press, a row firing), none
+   * of which the store can see.
+   */
+  appMenu: Record<string, never> | null;
+  /** "Focus the column's search", asked by `/`. A MAILBOX on `appMenu`'s
+   *  model: the store cannot reach the input, so it parks a fresh identity and
+   *  the panel's effect moves the caret. Never cleared, never persisted. */
+  searchFocus: Record<string, never> | null;
   /**
-   * The mesh layers a material pick would be applied to, or null when the
-   * picker is closed. Editor state: nothing exists in the document until a
-   * card is chosen.
+   * A request that Code Studio take ONE STEP BACK, the way its own Escape and
+   * back chevron do: leaving asks first when a buffer is dirty. A fresh object per press, on
+   * `appMenu`'s model, because the key can arrive where the panel cannot hear
+   * it (the stage iframe forwards its keys straight to `handleKey`), and the
+   * store cannot open the confirm that leaving needs.
    */
-  materialPicker: { layerIds: readonly string[] } | null;
+  codeBackRequest: Record<string, never> | null;
+  /** The node editor over one real mesh, or null for the ordinary shot shell. */
+  materialWorkspace: MaterialWorkspaceState | null;
+  /** Fraction of the viewport occupied by the graph pane. Workspace-only. */
+  materialColumnWidth: number;
+  /** A code component's live preview width in px, clamped to `CODE_LIVE_WIDTH`. */
+  codeLiveWidth: number;
+  /**
+   * What the graph canvas has selected.
+   *
+   * Its own field rather than a second use of `selection`, which holds LAYER
+   * ids: the two are live at the same time (the workspace keeps the mesh
+   * selected on the stage while the author works on its nodes), and one field
+   * serving both would make Delete in the graph reach for the mesh.
+   *
+   * Revalidated on every document write beside `isolation`: undo, an agent
+   * write or a delete can take a node away, and a selection pointing at nothing
+   * makes the next Delete a silent no-op.
+   */
+  materialGraphSelection: MaterialGraphSelection;
+  /**
+   * WHICH SCOPE the canvas is showing: the trail of function ids the author has
+   * entered, innermost last. Empty is the main graph.
+   *
+   * A TRAIL and not one id, because the crumb bar has to name every level to
+   * get back out of a function entered from inside another one. Editor state:
+   * the document records which nodes belong to which function (`node.scope`),
+   * and this records which of those the author is looking at.
+   */
+  materialGraphPath: readonly string[];
+  /** The node palette's mailbox, or null. Fresh identity per request — see
+   *  `MaterialPaletteRequest`. */
+  materialPalette: MaterialPaletteRequest | null;
+  /** Do graph drags land on the grid? A workspace preference, never document
+   *  data: node positions are layout and an author's snapping habit is not. */
+  materialSnapToGrid: boolean;
+  /** "Frame the graph" asked for. A MAILBOX for `appMenu`'s reason: only the
+   *  canvas knows its own viewport, so the store parks an identity and the
+   *  canvas's effect does the fit. */
+  materialFrameRequest: Record<string, never> | null;
+  /** Latest compile status for the graph currently mounted on the stage. */
+  materialCompile: MaterialCompileState;
+  // ── the storyboard ───────────────────────────────────────────────────────
+  /**
+   * The fourth mode: the Project's planning board. A FLAG over the shell,
+   * not a place that remembers what it replaced: it clears nothing on
+   * entry and restores nothing on exit. Mirrored as `?storyboard=1`.
+   */
+  storyboardOpen: boolean;
+  /**
+   * THE SHOT BOARD: the planned shot ("part_…") whose sketches the board
+   * shows, or null for the whole board. The workspace stays `storyboard`.
+   * Closing the board KEEPS it, so the switch's Storyboard segment comes back
+   * to the view the author left; a write that removes the part clears it.
+   * Mirrored as `?plan=<partId>`. Session state, never saved.
+   */
+  storyboardPlan: string | null;
+  /** The sketch the shot board shows ("skt_…"), one of the plan's, or null
+   *  while the plan has none yet. Mirrored as `?sketch=<id>`. */
+  storyboardSketch: string | null;
+  /** The items selected on the open sketch ("ski_…"), revalidated on every
+   *  write like `storyboardSelection`. */
+  sketchSelection: readonly string[];
+  /** The shot board's armed tool. A view pref, never saved. */
+  sketchTool: SketchTool;
+  /** Play on the shot board: the sketch live in one stage. A preview, so
+   *  nothing is saved, and it stops when the shot board closes. */
+  sketchPlaying: boolean;
+  /** "Guide: Sketch N" in the Studio: the sketch the stage draws as dashed
+   *  outlines, or null. A view, never saved, and it goes with its sketch. */
+  sketchGuide: { partId: string; sketchId: string } | null;
+  /**
+   * Where leaving a mode (the Components workspace or the material nodes)
+   * goes back to. `"storyboard"` when the mode was entered over the board, so
+   * a trip from the board comes back to the board; `"stage"` otherwise.
+   * Written on the first entry only, so switching subjects inside a mode keeps
+   * it. Entering a Shot resets it.
+   */
+  returnTarget: "stage" | "storyboard";
+  /**
+   * The Components workspace is up with NO component open: its empty state,
+   * or the top bar's door before a pick. Once a subject opens, `editingDef`
+   * or `codeComponent` holds the workspace and this goes false.
+   */
+  componentsOpen: boolean;
+  /** Which tab of the Components workspace shows. Every edit door lands on
+   *  `"edit"`; the top bar's door keeps what the author last picked. */
+  componentsTab: ComponentsTab;
+  /** The component the Components workspace last showed. Written by every
+   *  door, kept on leave, so the top bar reopens it. Cleared on a document
+   *  swap: a definition id names one document's component. */
+  componentsSelection: ComponentsSelection | null;
+  /** Where a Shot door into Components came from (C7), or null. Back to Shot
+   *  and Esc restore it. Leaving Components any other way clears it. */
+  componentsOrigin: ComponentsOrigin | null;
+  /** The preview's ground and loop (bridge v45), pushed with the component
+   *  context. */
+  componentPreview: ComponentPreviewLook;
+  /** The workspace component store's rows (`GET /api/workspace-components`),
+   *  or null before the first read. The `cpt_` id of a component of this
+   *  Project is looked up here by its home. */
+  workspaceComponents: WorkspaceComponent[] | null;
+  /** Which Project each code file belongs to, from the same read (`homes`):
+   *  the module paths every live Project lists as made for it or uses. Null
+   *  before the first read, and Your library's "made for no Project" waits on
+   *  it. Kept across a Project switch, like the rows. */
+  componentHomes: ComponentFileHome[] | null;
+  /** The font apply in flight for the Font field (`applyFont` and the verbs
+   *  that share its lane): its download and upload progress, and its failure
+   *  with Retry (`retryFontApply`). Null when none runs or the last one
+   *  landed; cleared by a newer apply and by a Project switch. */
+  fontApply: FontApplyProgress | null;
+  /** The workspace font list (`GET /api/fonts`, `loadWorkspaceFonts`), or
+   *  null before the first read that succeeded. */
+  workspaceFonts: WorkspaceFontList | null;
+  /** The Google catalog once loaded (`loadFontCatalog`), for the font
+   *  helpers that take it (`state/fonts.ts`); null before. */
+  fontCatalog: readonly GoogleFontEntry[] | null;
+  /** The versions read per workspace component, newest first. */
+  componentVersions: Readonly<Record<string, WorkspaceComponentVersionInfo[]>>;
+  /** The last build check per code component (registry id). A failing one
+   *  keeps its last good build on screen and refuses an export. */
+  componentBuilds: Readonly<Record<string, ComponentBuild>>;
+  /** The Share dialog for the component Components shows (lane P draws it). */
+  shareComponentOpen: boolean;
+  /** The History view of the component Components shows, or null when it is
+   *  closed. `viewing` is the version read for the read-only view. */
+  componentHistory: { viewing: WorkspaceComponentVersion | null } | null;
+  /** Every use (C4): the centre lists the uses of `subject` in place of the
+   *  preview, and the right panel shows THIS USE for `use` (a key from
+   *  `cardUseKey`/`layerUseKey` in workspace.ts). It names its subject, so a
+   *  switch to another component shows that one's preview again without a
+   *  reset at every door (`usesViewOf`). Null when closed. */
+  componentUses: { subject: ComponentsSelection; use: string | null } | null;
+  /** The latest version of each Community listing this document's copies
+   *  came from, by listing id. Read by `refreshListingUpdates`. */
+  componentListingUpdates: Readonly<Record<string, ComponentListingUpdate>>;
+  /** An Update held for a yes: applying it drops props this document's uses
+   *  changed, so the author sees them first. Null when none is pending. */
+  componentUpdate: ComponentUpdatePending | null;
+  /** The Community update just written, until Done, Revert update or a doc
+   *  swap. Null when none. */
+  componentUpdated: ComponentUpdateApplied | null;
+  /**
+   * The library browser: the whole shipped catalog, full screen, where an
+   * author picks what this Project wants.
+   *
+   * A DIALOG AND NOT A FIFTH MODE, which is the one decision in this field
+   * worth writing down. `Dialog` portals to `document.body` at `--z-dialog`
+   * 1100, above the whole shell (whose top tier is the overlay, 10), and it
+   * brings its own focus trap and its own Escape. So this flag costs no
+   * workspace in `workspaceOf`, no shell class, no cell slots, no keymap lane
+   * and no `edgesOf` key.
+   *
+   * It also has to be a dialog to be usable. A fifth mode would join the
+   * modes' one-at-a-time rule (`workspaceOf`: opening one closes the
+   * others), so it could not share the screen with the board, which is
+   * exactly where an author chooses what to build with. This opens over
+   * anything, including the board.
+   */
+  libraryBrowserOpen: boolean;
+  /**
+   * The Insert drawer over the left column: closed (null), or open and asked
+   * to show `section`. A FRESH OBJECT per open, so asking again for the
+   * section already open scrolls back to it. Closed by any change of
+   * workspace (opening a mode), and never open for a viewer.
+   */
+  insertDrawer: { section: InsertSection } | null;
+  /** The author has met the drawer (closed it, or added anything). Remembered
+   *  in `editorPrefs`; while false, an empty Project opens the drawer once. */
+  insertDrawerSeen: boolean;
+  /** A layer the drawer placed WITHOUT selecting it ("Use as background"):
+   *  its outline row flashes and says where it went. The next selection
+   *  clears it. */
+  justPlaced: string | null;
+  /**
+   * The planned shot currently being renamed, or null. Its name field shows in
+   * the Plan panel's head and on the shot board's bar (`PartName`).
+   *
+   * ONE SPELLING FOR EVERY SURFACE, so a rename started with F2 and one started
+   * from a double-click on the name are the same rename.
+   */
+  storyboardRenaming: string | null;
+  /**
+   * What the board has selected: reference ids ("ref_…"), still ids
+   * ("stl_…"), part ids ("part_…"), and the derived gap and cut ids. Its own field
+   * for `materialGraphSelection`'s reason, and revalidated on every document
+   * write beside it: a delete, an undo or an agent write can take a card away.
+   */
+  storyboardSelection: readonly string[];
+  /**
+   * The `animateMode` the board parked on open, or null while it is closed.
+   * The board is planning, so an armed key-on-change bit would turn every
+   * placement into keys. Close restores it, as Material does.
+   */
+  storyboardRestoreAnimate: boolean | null;
+  /**
+   * Whether a reference's "More" fold (every control of a component card) is
+   * open. A component card's "All controls" sets it, so the fold the
+   * inspector shows is the one the card asked for. A view pref.
+   */
+  referenceMoreOpen: boolean;
+  /**
+   * Whether the board's Project assets panel is open in the right column
+   * (`boardRightPanel` "assets"), from the board's + menu. Where "Keep in
+   * Assets" lands and a file is uploaded, removed or dragged onto a card.
+   * False whenever the board is closed. Session state, never saved.
+   */
+  boardAssetsOpen: boolean;
+  /**
+   * The category the library browser opens on, or null to keep its own. A
+   * mailbox: `setLibraryBrowserOpen(true, category)` parks it and the browser
+   * applies it once on open.
+   */
+  libraryBrowserCategory: "all" | LibraryItemKind | null;
+  /**
+   * The planned shots "Build planned shots" handed to the agent (S1). A card
+   * reads Building while its part is here and it is not marked built. All
+   * leave when the agent run that followed ends. Session state, never saved;
+   * a document switch drops it.
+   */
+  boardBuilding: { part: string }[];
+  /** True once an agent run started after the last "Build planned shots",
+   *  so the run's end clears `boardBuilding`. */
+  boardBuildingRan: boolean;
+  /** Files dropped or pasted on the board, waiting for the drop dialog's
+   *  scope (S2). Null while the dialog is closed. */
+  boardDrop: { files: File[] } | null;
+  /**
+   * The last "Add motion" request: the planned shot and the Shot it asked the
+   * agent to change. The review card warns when a proposal redraws any other
+   * Shot, and copies this part's prompt. Transient: a document switch drops it.
+   */
+  motionRequest: { partId: string; sceneId: string | null } | null;
+  /** Text the agent composer adopts on its next render. A fresh identity per
+   *  ask, consumed once by the mounted composer. */
+  agentPrefill: { text: string } | null;
+  /** Layers the timeline dock shows on its next render. A fresh identity per
+   *  ask, consumed once by the mounted dock, `agentPrefill`'s shape. */
+  dockReveal: DockReveal | null;
   /**
    * Triangle counts by mesh layer id, pushed up from the stage as models load.
    *
@@ -127,6 +1024,16 @@ export interface ShotEditorState {
    * layer whose model has not arrived yet reports nothing at all.
    */
   meshTriangles: Readonly<Record<string, number>>;
+  /**
+   * The glTF materials each loaded model ships, pushed up from the stage as
+   * models parse.
+   *
+   * The same push-not-poll argument the triangle count makes: a material index,
+   * name and map set live in the FILE, so no amount of reading the document
+   * tells the slot rail that slot 3 is called "Screen". Absent for a layer
+   * whose model has not loaded, and for every primitive.
+   */
+  meshMaterialSlots: Readonly<Record<string, readonly MeshMaterialSlotInfo[]>>;
   /**
    * The subtree being edited in isolation, or null for the whole scene.
    *
@@ -161,6 +1068,26 @@ export interface ShotEditorState {
   /** The shading the working pane was in before the current one, so ⇧Z can
    *  toggle wireframe and come BACK rather than stranding the author in it. */
   previousShading: ShadingMode;
+  /**
+   * The shading to put back on leaving the open definition, or null if there is
+   * nothing to put back.
+   *
+   * ── WHY A DEFINITION OPENS IN MATERIAL ──────────────────────────────────
+   *
+   * Clay is a MODELLING aid: it strips colour and texture so silhouette and
+   * proportion read. A component definition is made of exactly what clay
+   * strips — painted layers, stacked, drawn with `depthTest` off — so the
+   * default solid shading rendered an opened definition as ONE featureless grey
+   * rectangle. It looked like the editor had hung.
+   *
+   * The same argument the material picker already makes on close: a look you
+   * cannot see is a choice you cannot make.
+   *
+   * SEPARATE FROM `previousShading`, which belongs to ⇧Z's wireframe toggle.
+   * One field serving both would make leaving a definition and pressing ⇧Z
+   * fight over the same slot.
+   */
+  shadingBeforeDef: ShadingMode | null;
   /**
    * The component definition the OUTLINE is scoped to, or null for the scene.
    *
@@ -175,6 +1102,136 @@ export interface ShotEditorState {
    * every write beside `isolation` — a definition can be deleted too.
    */
   editingDef: string | null;
+  /**
+   * The DEF-LOCAL playhead while a definition is open (unify P2). A SECOND
+   * field beside `frame` on purpose: `frame` is master time and every
+   * playhead-paired verb (addShotAtPlayhead, Animate's keys, audio preview, the
+   * scene render) reads it — repurposing it def-locally would silently corrupt
+   * all of them. While `editingDef` is null this is inert. Clamped against
+   * `defDurationFrames` at the same seam `editingDef` is validated.
+   */
+  defFrame: number;
+  /**
+   * The chrome's zoom over the Studio's head-on render. 1 = the whole canvas
+   * fitted, 2 = twice as large.
+   *
+   * EDITOR STATE, pushed to the stage with the component context: the stage
+   * frames the definition from `def.size`, so the zoom is a scale on that
+   * frame's half-extents rather than anything the document records.
+   *
+   * NOT a workspace pref, and deliberately not: it is scoped to ONE definition's
+   * canvas, so carrying it to the next definition would open a component the
+   * author has never seen at a magnification they chose for another one. It
+   * resets to 1 on every entry, with the rest of the cleared-on-leave set.
+   */
+  studioZoom: number;
+  /**
+   * THE OTHER COMPONENT FAMILY'S OPEN SUBJECT: a registry id
+   * ("<module>#<Export>") whose source the code studio is showing, or null.
+   *
+   * A SECOND FIELD BESIDE `editingDef` rather than a widened one, for the
+   * reason `defFrame` is a second field beside `frame`: the two subjects are
+   * different KINDS. A definition is a document object with an interior, an
+   * exposed surface and named actions, and every one of those is a panel that
+   * reads `editingDef`. A code component is a .tsx file the author owns; it has
+   * a source buffer and a contract, and nothing else in this chrome. One field
+   * answering both would have every reader ask "which sort is it" first.
+   *
+   * MUTUALLY EXCLUSIVE with `editingDef`: both mean "the stage is rendering one
+   * component standalone", and the stage holds one context. Each entry clears
+   * the other, and `pushComponentContext` is where the two meet.
+   */
+  codeComponent: string | null;
+  /**
+   * The defaults rail's LIVE overrides, contract key -> engine Value.
+   *
+   * A scrub writes here and pushes the component context; nothing lands in any
+   * document. A committed key is HELD here until the fresh contract arrives
+   * (`loadContract` clears it), so the preview never flashes the old default
+   * between the write landing in source and the re-extraction being adopted.
+   */
+  codePreviewProps: Readonly<Record<string, Value>>;
+  /**
+   * FOLLOW MODE: the project file Code Studio is following an MCP agent in,
+   * or null. While the agent keeps writing it, its buffer is read-only and
+   * reloads on each write (`adoptSourceChange`), and the preview takes the
+   * props and frame of each `preview_component` the agent asks for. "Take
+   * over" (`takeOverCodeFile`) ends it.
+   */
+  codeFollow: string | null;
+  /** A file the author asked to follow that the registry does not list yet:
+   *  it opens in follow mode as soon as it does (`refreshLibrary`). */
+  codeFollowPending: string | null;
+  /**
+   * The Components props panel's TRIED values, prop key -> engine Value, for
+   * the open subject (a code component's contract keys, or a definition's
+   * exposed keys).
+   *
+   * While `componentApplyAll` is off, every props-panel edit lands here and
+   * nowhere else: the preview draws it (pushed on the component context) and
+   * no document, file or instance changes. Turning `componentApplyAll` on
+   * saves these to the component and clears them. Dropped whenever the
+   * subject changes (the `set` seam), so a tried value never follows the
+   * author to another component.
+   */
+  componentPlay: Readonly<Record<string, Value>>;
+  /**
+   * The props panel's "Apply to all instances" checkbox. Off (the default) =
+   * try values in the preview only (`componentPlay`). On = every edit saves to
+   * the component itself, which every instance without its own value follows.
+   * Resets to off with the subject.
+   */
+  componentApplyAll: boolean;
+  /** The key under an active scrub gesture, or null. Its override survives a
+   *  contract landing mid-drag (another key's commit must not yank this one). */
+  codeScrubKey: string | null;
+  /** Keys whose defaults commit is IN FLIGHT. The held-override release in
+   *  `loadContract` keeps these too: a contract landing for key A's commit
+   *  must not yank key B's still-travelling one — that would flash B's old
+   *  default on stage for the exact window the hold exists to cover. */
+  codePendingDefaults: readonly string[];
+  /** Each default the author changed while this component is open, as it was
+   *  before the first change: what the props head's Reset puts back. Kept by
+   *  the store, so it survives the panel remounting, and dropped with the
+   *  defaults history (another component, or leaving Code Studio). */
+  codeDefaultsBaseline: Readonly<Record<string, Value>>;
+  /** The last defaults-commit refusal or failure, shown at the top of the
+   *  rail. Cleared by the next gesture. */
+  codeDefaultsError: string | null;
+  /** Per-component defaults metadata (target file, writability, per-key
+   *  editability), cached beside `contracts` and evicted at the same seams. */
+  contractDefaults: Readonly<Record<string, ComponentDefaultsMeta>>;
+  /**
+   * Every open buffer, keyed by project-relative posix path.
+   *
+   * A MAP AND NOT ONE FILE, because the subject and the buffer stopped being
+   * the same question. A component is one export in one module, but the work of
+   * changing it reaches the helper beside it, the types it imports and the
+   * config that includes it — and an editor that can only hold the file it
+   * previewed makes the author leave to read any of them.
+   *
+   * Keyed by rel rather than an array of tabs: rel IS the identity (`/api/files`
+   * takes one, the diagnostics route takes one, `CodeEditor`'s state cache keys
+   * on one), and a list would need a lookup on every one of those.
+   */
+  codeFiles: Readonly<Record<string, CodeFileState>>;
+  /** Which buffer the editor is showing, or null when none is open. Always a
+   *  key of `codeFiles` or null — nothing may point at a buffer that is not
+   *  there, and `closeCodeFile` picks the neighbour rather than leaving this
+   *  dangling. */
+  codeActive: string | null;
+  /** Tab order, oldest first. SEPARATE from `codeFiles` because an object's key
+   *  order is a language detail and a tab strip's order is a promise to the
+   *  author: tabs must not reshuffle when a buffer is replaced. */
+  codeOrder: readonly string[];
+  /** Every editable file in the project, flat, as `GET /api/files` answers.
+   *  The tree's shape is drawn from these paths, never stored. */
+  projectFiles: readonly ProjectFile[];
+  projectFilesLoaded: boolean;
+  /** The server's walk hit its cap, so this listing is INCOMPLETE. Said in the
+   *  tree, because a file browser that quietly omits files is worse than none. */
+  projectFilesTruncated: boolean;
+  projectFilesError: string | null;
   /** The export dialog is open. A store bit rather than local state, because
    *  the keymap opens it (⌘E) and the header's button toggles it, and two
    *  places holding "is it open" is one place for them to disagree. */
@@ -187,11 +1244,46 @@ export interface ShotEditorState {
    * away from the modal without cancelling anything.
    */
   renderJob: RenderJob | null;
+  /**
+   * A render of THIS document is running, either way it was started.
+   *
+   * ONE lock both export paths write, because both mean the same thing to the
+   * chrome: the transport is held, Space and the Play menu refuse, and the
+   * progress on screen comes from here. It is NOT the stage's own
+   * `exporting` (bridgeClient) — that one is the Tier-1 deferral flag and says
+   * nothing about a server render.
+   *
+   * `where` is what the chrome does about it. A BROWSER export renders through
+   * the visible stage by design, so the stage is veiled and says so; a SERVER
+   * render leaves the stage alone and only pauses playback, because the machine
+   * is busy but the canvas is still the author's.
+   */
+  exportLock: {
+    where: "browser" | "server";
+    done: number;
+    total: number;
+    /** What a server render is doing before its first frame (F98), such as
+     *  the one-time browser download. */
+    note?: string;
+  } | null;
   // ── the agent drawer ─────────────────────────────────────────────────────
   //
   // Held in the STORE and not in the panel, for the reason the render job is:
   // closing the drawer must not cancel a running turn or lose its transcript.
   agentOpen: boolean;
+  /** The right column's Comments tab is the one picked (plan C5). The agent
+   *  wins the column while it is open; the tab comes back when it closes. */
+  commentsOpen: boolean;
+  /** The Studio's Brief tab is the one picked (S4): the planned shot the
+   *  Shot under the playhead was built from. Off the board only; the agent and
+   *  Comments win the column while open, as over the inspector. */
+  briefOpen: boolean;
+  /** The comment tool (C): off the board, a click on the camera pane drafts
+   *  a Studio thread (bridge v45, S5). Null when not armed. */
+  boardTool: "comment" | null;
+  /** The open Project takes comments from this caller
+   *  (`LoadedShot.can.comment`). A missing `can` (an older server) is true. */
+  canComment: boolean;
   agentItems: readonly AgentTranscriptItem[];
   agentRunning: boolean;
   agentError: string | null;
@@ -213,18 +1305,97 @@ export interface ShotEditorState {
   railCollapsed: boolean;
   inspectorCollapsed: boolean;
   /**
-   * What entering the working view auto-collapsed, per panel: the collapse
-   * value to restore on leaving, or null when there is nothing pending —
-   * either the mode is not on, or the author toggled that panel themselves
-   * inside it and took ownership (the collapse verbs null the slot).
+   * What the focus mode auto-collapsed, per panel: the collapse value to
+   * restore on leaving it, or null when there is nothing pending. Either the
+   * mode is off, or the author toggled that panel themselves inside it and
+   * took ownership (the collapse verbs null the slot).
+   *
+   * The DOCK has no slot, and that is the current rule rather than an
+   * oversight: no view collapses the timeline any more. See `focusHides`.
    */
   focusRestoreInspector: boolean | null;
-  focusRestoreDock: boolean | null;
+  focusRestoreRail: boolean | null;
+  /**
+   * Whether the focus mode is engaged, or null for off.
+   *
+   * There is exactly ONE now, and it belongs to one place: Video at the SCENE
+   * level, where the subject is the finished cut rather than anything to edit,
+   * so both side rails go and the picture gets the full width. Inside a shot
+   * NEITHER view hides a panel: the author is building there and the panels
+   * are what they build with. See `applyFocus` in store.ts.
+   *
+   * ── WHY THIS IS STORED AND NOT DERIVED ──────────────────────────────────
+   *
+   * It is the "before" of every transition, and the input it would be derived
+   * from cannot supply one: `video` is the same flag everywhere and survives
+   * a trip into a shot, so it means "rails away" at the scene level and
+   * "nothing engaged" one level down, and a CONTEXT change with the flag
+   * unchanged is a real transition in both directions. The restore slots cannot supply it either:
+   * they are null both when the mode was never entered and when the author
+   * took ownership inside it, so a mode with its slots surrendered would look
+   * unengaged and re-collapse the panels the author had just re-opened, on
+   * the next edit, because `syncContextStage` runs on every one of them.
+   *
+   * Stored, the answer is a comparison: same key, nothing happens.
+   */
+  focusHides: "video" | null;
+  /**
+   * THE AUTHOR IS WATCHING, not working.
+   *
+   * Video is the export's picture with the authoring taken off it: no handles,
+   * no hover, no drawing, no drags. The transport runs in Edit and Video alike.
+   * It is a FLAG OVER THE PICTURE and never a pane layout, which is the whole
+   * correction this field carries. It was `sceneVideo` and applied at the scene
+   * level alone, because a shot's Video was spelled as camera mode
+   * (`stageLayout.mode`) instead. That could not survive contact with the
+   * facts: the rect, ellipse, line, text, image and pen tools draw in the
+   * CAMERA pane and nowhere else, so "Video is the camera pane" made drawing
+   * impossible in the view that could not play and possible in the one that
+   * could.
+   *
+   * So `stageLayout.mode` is EDIT'S LAYOUT now (the 3D viewport, the split, the
+   * frame, on keys ⇧1 / ⇧2 / ⇧3) and this is orthogonal to it. Entering Video
+   * never writes the layout; leaving shows it again. Above a shot it ALSO
+   * puts both side rails away, which is the one focus mode left in the product
+   * (`focusKeyFor`).
+   *
+   * THE WAY OUT IS ANY EDIT. Every selection verb, the document seam, both
+   * scrub lanes, the tool arm and the four "go somewhere to work" doors call
+   * `enterEdit()`, so the first touch of anything lands the author in Edit,
+   * paused, on the frame they were looking at. See the seam list in store.ts.
+   *
+   * A WORKSPACE VALUE: it survives a document switch, like `stageLayout` and
+   * the slots that ride with it, and it is deliberately NOT persisted to
+   * storage: a reload opens on the work, not on the screening room.
+   */
+  video: boolean;
   /** Dragged sizes, in PIXELS — see state/panelSize.ts for why not `vh`. */
   railWidth: number;
   dockHeight: number;
+  /** The RIGHT rail's width. It was a CSS literal with no writer at all until
+   *  the UX overhaul, which is why the panel had been worked around (labels
+   *  shortened to fit) rather than widened. State now, for the reason
+   *  `railWidth` is state, and it reaches CSS the same way: `--inspector-w`,
+   *  written imperatively from App.tsx. */
+  inspectorWidth: number;
+  /**
+   * How far the chrome reaches in over the stage on each side, measured.
+   *
+   * The stage iframe is pinned `inset: 0` and the panels are docked over it, so
+   * only the shell can know this — it measures the boxes and pushes the four
+   * numbers down the bridge for the overlay's furniture and the derived
+   * framing (see `setStageInset`).
+   *
+   * IT IS STATE AND NOT A CLOSURE because the CHROME needs it too. The split
+   * divider divides the part the author can see, not the window, so the
+   * handle's own arithmetic reads the same four numbers the stage does. A
+   * second measurement in App.tsx would be a second answer to a question with
+   * one true answer, and the two would disagree exactly while a panel moves.
+   */
+  stageInset: StageInset;
   /** Pixels per frame in the dock. The unit @dailies-studio/timeline's geometry
-   *  and `useAnchoredZoom` both speak, so there is no second zoom scale. */
+   *  and `useAnchoredZoom` both speak, so there is no second zoom scale. Its
+   *  bounds and its default are `DOCK_PPF` in state/panelSize.ts. */
   dockPpf: number;
 
   /**
@@ -259,17 +1430,26 @@ export interface ShotEditorState {
    *  shortcut point at it, so it follows the POINTER and not the selection. */
   activePane: StagePane;
   /**
-   * "Camera follows this view": orbiting the working pane writes the shot
-   * camera's framing continuously.
+   * PILOTING: the Camera pane's navigation (middle-drag orbit, shift-drag
+   * pan, wheel zoom, R roll) writes the shot camera through the framing
+   * gesture lane instead of moving the pane's viewport.
    *
-   * A WORKSPACE PREF like the other two, and deliberately NOT called a lock.
-   * The word says "nothing can move" when what is true is the opposite — the
-   * camera is being moved by everything you do. It is armed only by its own
-   * control, never as a side effect of entering a mode, for the reason
-   * `animateMode` is: a bit that silently makes drags write the document must
-   * be turned on on purpose.
+   * It replaced "camera follows this view", which projected every 3D-view
+   * orbit onto a camera that cannot tilt and left the two panes disagreeing
+   * mid-drag. Session-only and deliberately NOT called a lock: nothing is
+   * locked, the camera is being moved by everything you do. It is armed only
+   * by its own control or its key, never as a side effect of entering a mode,
+   * for the reason `animateMode` is: a bit that silently makes drags write the
+   * document must be turned on on purpose.
+   */
+  pilot: boolean;
+  /**
+   * The component that drives the render camera, by name, or null while the
+   * document's rig does. Reported by the stage (bridge v29 `onCameraDriver`):
+   * the inspector's Camera fields and the camera verbs describe a rig the
+   * picture ignores while this is set, and they say so.
    */
-  cameraFollowsView: boolean;
+  cameraDriver: string | null;
   /**
    * The WORKING pane's shading (solid / wireframe / material / rendered).
    *
@@ -279,8 +1459,124 @@ export interface ShotEditorState {
    * sentence with no footnotes.
    */
   shadingMode: ShadingMode;
+  /** The working pane's grid floor: how the author looks at the scene, never
+   *  something about the shot. Remembered across reloads in `editorPrefs`. */
+  showGrid: boolean;
+  /**
+   * The two DIAGNOSTIC chips in the canvas bar, shown or hidden.
+   *
+   * Per-viewer prefs on `showGrid`'s rule: how the author is looking at the
+   * chrome, never anything about the shot, and remembered across reloads in
+   * `editorPrefs`. They exist because both chips are for the person
+   * BUILDING the film and neither belongs in a recording of it.
+   *
+   * ONLY these two. The save-state and codegen chips are not on this switch and
+   * must not join it: they are the chrome telling the author something is wrong
+   * or unsaved, and a warning with an off switch is a warning that will be off
+   * on the day it matters.
+   */
+  showFpsBadge: boolean;
+  showBackendBadge: boolean;
+  /**
+   * A single plain pick of a layer moves a paused playhead onto it (gap 4),
+   * when the playhead is outside the layer's lifespan. A per-viewer
+   * pref on `showGrid`'s rule, kept in `editorPrefs`, and the View menu's
+   * "Move playhead to selection" row.
+   */
+  selectMovesPlayhead: boolean;
+  /**
+   * THE REST OF THE PREFERENCES PAGE (gap 5, Paper page 24), each a per-viewer
+   * pref on `showGrid`'s rule: kept in `editorPrefs`, synced to the account
+   * when hosted, never in the document, and carried across a document switch.
+   *
+   * `motionPaths`: the selected layer's motion path on the stage.
+   * `rulers`: the camera pane's rulers (and the guides they create).
+   * `smartGuides`: snapping to the frame and the other layers while dragging.
+   *   User guides snap either way; Ctrl drops both for one drag.
+   * `blockLabels`: camera move bar names, when they fit or never.
+   * `fieldLabels`: inspector fields show a glyph in the pill, or the name above.
+   * `toolbarPosition`: the tool footer under the canvas, or above it.
+   */
+  motionPaths: boolean;
+  rulers: boolean;
+  smartGuides: boolean;
+  blockLabels: "fit" | "off";
+  fieldLabels: "compact" | "named";
+  toolbarPosition: "bottom" | "top";
+  /**
+   * What a played frame may render at (bridge v52, `PlaybackResolution`):
+   * Auto lowers it below the display's density only while the GPU cannot keep
+   * up, Full never does, Fast starts at 0.7 of it. Pushed to the stage with
+   * the rulers (`setEditorChrome`). Kept in `editorPrefs` on this browser
+   * only, not on the account: it is a fact about this machine's GPU, which
+   * another device does not share.
+   */
+  playbackResolution: PlaybackResolution;
+  /** The Preferences dialog is open. A store bit for `exportOpen`'s reason:
+   *  ⌘, , the app menu row and the agent's `prefs.open` all open it. */
+  prefsOpen: boolean;
   /** What the stage reported on ready, or null before it did. */
   stageInfo: ShotStageInfo | null;
+  /**
+   * What the stage PRESENTED over the last second, or null when it is not
+   * playing.
+   *
+   * Written once a second during playback and retracted on stop. Like
+   * `sceneId`'s per-cut write it is hot-only while `playing` (store `set`), so
+   * the fps chip reads it hot and no other panel wakes for it. Null is the
+   * resting state and means "no measurement", not "zero frames": the chrome's
+   * own seek cadence is not an answer here, because the stage coalesces
+   * requests and drops publications exactly when the two disagree.
+   */
+  stagePerf: StagePerformanceReport | null;
+  /**
+   * The pieces of the Shot the stage could not draw and isolated (bridge v34
+   * `onPieceFailures`): a layer, a background, a post stack or a transition
+   * that threw while the rest kept drawing. Whole on every change, empty once
+   * everything renders again, and empty with no stage attached. The stage
+   * badge shows it, and the stage refuses an export of any frame it touches.
+   */
+  stagePieceFailures: readonly StagePieceFailure[];
+  /** The stage's render fallbacks (`health().renderErrors`): an html layer
+   *  that failed to decode, a font or glyph engine failure, a missing
+   *  texture. Mirrored on each health change for the same badge. */
+  stageRenderErrors: readonly string[];
+  /**
+   * The stage still OWES THE OPEN SUBJECT its first whole presentation
+   * (bridge v51 `onStageBusy`): the Project, a component context or a
+   * material preview, not yet drawn whole by this renderer. Once it has been,
+   * later loads (a font, a texture, a model) hold nothing.
+   *
+   * FALSE WHEN NO STAGE IS ATTACHED, and that is the contract rather than an
+   * accident: a bare store, a unit test and SSR are all "ready". False too
+   * while the stage cannot present at all (a crash, a lost context, a
+   * renderer compile failure), so a queued Play never waits on it for ever.
+   * `onReady` is not this signal: it fires when the RENDERER is up, before
+   * anything is drawn. Read through `stageReady`.
+   */
+  stageBusy: boolean;
+  /**
+   * A STAGE IS ON ITS WAY: a connect attempt has begun and none has reported
+   * in yet.
+   *
+   * `stageBusy` cannot answer this. It is FALSE when no stage is attached, by
+   * the contract above, so Play used to start for the whole iframe boot: the
+   * stage document, a renderer adapter request and the first commit, with
+   * nothing on the canvas but the stage's own boot ground. Now a press there
+   * is queued (`playIntent` armed) until the stage reports in and draws.
+   *
+   * Read together with `stageInfo === null`, which is what "has not reported
+   * in" means: `onReady` is the single writer of that field, and it fires when
+   * the renderer is up on the document the chrome pushed.
+   *
+   * Written by `StagePanel` alone: true from its first commit (hosted, through
+   * the code host's boot too), and again for the document a reload remints;
+   * false when the attempt fails or the panel unmounts, which also cancels a
+   * queued Play, so a bridge version mismatch or a poll timeout hands the
+   * button back instead of leaving it waiting. A bare store, a unit test and
+   * SSR never mount `StagePanel`, which is what keeps them ready.
+   */
+  stageExpected: boolean;
   /** A stage connect or runtime failure, for the overlay strip. */
   stageError: string | null;
 
@@ -298,10 +1594,70 @@ export interface ShotEditorState {
   /** Lazily fetched contracts by component id — the inspector's row source. */
   contracts: Readonly<Record<string, Contract>>;
 
+  // ── the shipped library, for the board's Library lane ────────────────────
+  /** Every `GET /api/library/catalog` row: built-ins, installed shared
+   *  components and the SHIPPED items. The rail lists the non-builtins; a
+   *  `library` card looks its row up here for the thumb and the docs. */
+  libraryCatalog: readonly LibraryItem[];
+  /** `libraryLoaded`'s rule, for the same reason: a failed fetch also ends
+   *  with an empty list, and "no items" must never look like "not read". */
+  libraryCatalogLoaded: boolean;
+  libraryCatalogError: string | null;
+  /** The items the registry REFUSED to read: a lying `library.json`, files that
+   *  drifted from `library-manifest.json`, a manifest entry with no directory.
+   *  They are omitted from `libraryCatalog`, so without these rows an item this
+   *  build broke is indistinguishable from one it never shipped. Each error
+   *  names its own fix. */
+  libraryCatalogProblems: readonly { id: string; error: string }[];
+  /** Lazily fetched item details by id (`loadLibraryItem`), the inspector's
+   *  Docs source. */
+  libraryItems: Readonly<Record<string, LibraryItemDetail>>;
+
+  /** Server-authoritative media usage for the open Project. Null while it has
+   * not been read, or when the current server predates the scoped asset API. */
+  assetUsage: ProjectAssetUsage | null;
+
   saveState: SaveState;
   /** Unsaved edits exist. Separate from `saveState` because a save that is
    *  in flight while a new edit lands is BOTH "saving" and dirty. */
   dirty: boolean;
+  /** Live sync only (null without it): an edit exists that is only in this
+   *  tab's memory, not yet in IndexedDB. Under sync THAT is what a closed tab
+   *  loses, so the close guard reads it instead of `dirty`. */
+  syncUnstored: boolean | null;
+  /** Live sync only (null without it): where this device's changes stand,
+   *  for the save chip, its popover and the quota banner. A `hold` makes the
+   *  Project read only until it clears (`readOnlyReason` says why). */
+  syncStatus: SyncStatus | null;
+  /** The open Project moved on the server under unsaved edits: another tab or
+   *  an agent wrote it ("changed"), or it is gone ("deleted"). Autosave stops
+   *  while it is set, so the same 409 is not sent on every edit, and the
+   *  shell's banner offers the one way on (`reloadLatest`). */
+  saveConflict: "changed" | "deleted" | null;
+  /** Live sync (R10): the open Project was renamed under the session. The
+   *  header's short note, "Renamed to X by Maya"; it clears itself. `by` is
+   *  the person's name, null when it was this user or nobody is known. */
+  syncRenamed: { to: string; by: string | null; color: string | null } | null;
+  /** Live sync (R10): the open Project went to the Trash under changes of
+   *  this tab that never reached the server. The dialog offers `restoreDeleted`
+   *  or `saveDeletedAsCopy`; the editor is read only meanwhile. */
+  syncDeleted: SyncDeleted | null;
+  /** The open Project is view only: the server said this caller may not edit
+   *  it (`LoadedShot.can.edit === false`, a hosted Viewer), or refused a save
+   *  as forbidden. Every document and server write is refused with
+   *  `VIEW_ONLY` (`viewOnly` in store.ts) and nothing autosaves. */
+  readOnly: boolean;
+  /** The Version history panel is open in the right column. */
+  versionsOpen: boolean;
+  /** The panel's name field is up and focused (Cmd+S, "Save version"). */
+  versionNameAsk: boolean;
+  /** The open Project's version rows, or null before the first read. */
+  versionList: ShotVersionList | null;
+  /** A version on screen in place of the live document. The chrome shows
+   *  `doc` read-only (`readOnly` is true while it is up); the history keeps
+   *  the live document, and `roleReadOnly` keeps what the server's role
+   *  said, so leaving the preview puts both back. */
+  versionPreview: { version: ShotVersion; roleReadOnly: boolean } | null;
   /** The last API failure, in words the author can act on. */
   error: string | null;
   /** Codegen refused to overwrite a hand-edited generated file. Sticky until
@@ -318,33 +1674,131 @@ export const INITIAL_VIEW: ShotView = { zoom: 1, panX: 0, panY: 0 };
 /** Camera only, because that is the pane that IS the export: an editor that
  *  opened onto a working pane would open onto a view of the shot that is not
  *  the shot. */
-export const INITIAL_STAGE_LAYOUT: StageLayout = { mode: "camera", splitRatio: 0.5 };
+export const INITIAL_STAGE_LAYOUT: StageLayout = {
+  mode: "camera",
+  splitRatio: 0.5,
+};
 
 export const INITIAL_STATE: ShotEditorState = {
-  shots: [],
   name: null,
   doc: null,
   rev: null,
   frame: 0,
   playing: false,
+  playRate: 1,
+  loopPlayback: true,
+  playIntent: null,
+  playOrigin: null,
+  workArea: null,
   sceneId: null,
+  enteredScene: null,
   selection: [],
   isolation: null,
   isolationOrbit: false,
   previousShading: "solid",
+  shadingBeforeDef: null,
   editingDef: null,
+  defFrame: 0,
+  studioZoom: 1,
+  codeComponent: null,
+  codePreviewProps: {},
+  codeFollow: null,
+  codeFollowPending: null,
+  componentPlay: {},
+  componentApplyAll: false,
+  codeScrubKey: null,
+  codePendingDefaults: [],
+  codeDefaultsBaseline: {},
+  codeDefaultsError: null,
+  contractDefaults: {},
+  codeFiles: {},
+  codeActive: null,
+  codeOrder: [],
+  projectFiles: [],
+  projectFilesLoaded: false,
+  projectFilesTruncated: false,
+  projectFilesError: null,
   tool: "select",
-  inspectorMode: "design",
+  workPlanes: {},
+  splineBasis: "bezier",
+  splineEdit: null,
   animateMode: false,
-  selectedBlock: null,
+  selectedMove: null,
+  selectedKeyframes: [],
+  dockMode: "rows",
   selectedMarker: null,
+  selectedAudio: [],
+  soloTracks: [],
+  snapBeats: true,
+  dockNotice: null,
   imagePick: null,
   stageMenu: null,
-  materialPicker: null,
+  appMenu: null,
+  searchFocus: null,
+  codeBackRequest: null,
+  materialWorkspace: null,
+  materialColumnWidth: MATERIAL_COLUMN.default,
+  codeLiveWidth: CODE_LIVE_WIDTH.default,
+  materialGraphSelection: { nodeIds: [], edgeIds: [] },
+  materialGraphPath: [],
+  materialPalette: null,
+  materialSnapToGrid: true,
+  materialFrameRequest: null,
+  materialCompile: { status: "idle" },
+  storyboardOpen: false,
+  storyboardPlan: null,
+  storyboardSketch: null,
+  sketchSelection: [],
+  sketchTool: "select",
+  sketchPlaying: false,
+  sketchGuide: null,
+  returnTarget: "stage",
+  componentsOpen: false,
+  componentsTab: "preview",
+  componentsSelection: null,
+  componentsOrigin: null,
+  // Dark, the desk, from the start: the Backdrop control lights what the
+  // stage draws. Null sent nothing and left the working pane's own grey.
+  componentPreview: { background: "dark", loopFrames: null },
+  workspaceComponents: null,
+  componentHomes: null,
+  fontApply: null,
+  workspaceFonts: null,
+  fontCatalog: null,
+  componentVersions: {},
+  componentBuilds: {},
+  shareComponentOpen: false,
+  componentHistory: null,
+  componentUses: null,
+  componentListingUpdates: {},
+  componentUpdate: null,
+  componentUpdated: null,
+  libraryBrowserOpen: false,
+  insertDrawer: null,
+  insertDrawerSeen: false,
+  justPlaced: null,
+  storyboardRenaming: null,
+  storyboardSelection: [],
+  storyboardRestoreAnimate: null,
+  referenceMoreOpen: false,
+  boardAssetsOpen: false,
+  libraryBrowserCategory: null,
+  boardBuilding: [],
+  boardBuildingRan: false,
+  boardDrop: null,
+  motionRequest: null,
+  agentPrefill: null,
+  dockReveal: null,
   meshTriangles: {},
+  meshMaterialSlots: {},
   exportOpen: false,
   renderJob: null,
+  exportLock: null,
   agentOpen: false,
+  commentsOpen: false,
+  briefOpen: false,
+  boardTool: null,
+  canComment: true,
   agentItems: [],
   agentRunning: false,
   agentError: null,
@@ -357,28 +1811,217 @@ export const INITIAL_STATE: ShotEditorState = {
   railCollapsed: false,
   inspectorCollapsed: false,
   focusRestoreInspector: null,
-  focusRestoreDock: null,
+  focusRestoreRail: null,
+  focusHides: null,
+  video: false,
   railWidth: RAIL_WIDTH.default,
   dockHeight: DOCK_HEIGHT.default,
-  dockPpf: 6,
+  inspectorWidth: INSPECTOR_WIDTH.default,
+  stageInset: { top: 0, right: 0, bottom: 0, left: 0 },
+  dockPpf: DOCK_PPF.default,
   previewMuted: false,
   previewVolume: 1,
   view: INITIAL_VIEW,
   stageLayout: INITIAL_STAGE_LAYOUT,
   workingView: INITIAL_WORKING_VIEW,
   activePane: "camera",
-  cameraFollowsView: false,
+  pilot: false,
+  cameraDriver: null,
   shadingMode: "solid",
+  showGrid: true,
+  showFpsBadge: true,
+  showBackendBadge: true,
+  selectMovesPlayhead: true,
+  motionPaths: true,
+  rulers: false,
+  smartGuides: true,
+  blockLabels: "fit",
+  fieldLabels: "compact",
+  toolbarPosition: "bottom",
+  playbackResolution: "auto",
+  prefsOpen: false,
   stageInfo: null,
+  stagePerf: null,
+  stagePieceFailures: [],
+  stageRenderErrors: [],
+  stageBusy: false,
+  stageExpected: false,
   stageError: null,
   library: [],
   libraryLoaded: false,
   libraryError: null,
   contracts: {},
+  libraryCatalog: [],
+  libraryCatalogLoaded: false,
+  libraryCatalogError: null,
+  libraryCatalogProblems: [],
+  libraryItems: {},
+  assetUsage: null,
   saveState: "idle",
   dirty: false,
+  syncUnstored: null,
+  syncStatus: null,
+  saveConflict: null,
+  syncRenamed: null,
+  syncDeleted: null,
+  readOnly: false,
+  versionsOpen: false,
+  versionNameAsk: false,
+  versionList: null,
+  versionPreview: null,
   error: null,
   emitWarning: null,
   canUndo: false,
   canRedo: false,
 };
+
+/**
+ * How long the SUBJECT-LOCAL clock runs, or null when no component is open.
+ *
+ * THE ONE ANSWER FOR THREE FORKS. The component context swaps the whole
+ * playback triple (the total, the seek verb and the starting frame), and that
+ * fork is asked in three places: the header's playback loop reads the total,
+ * the same loop picks `seekDef` over `seek`, and `seekDefTo` clamps against it.
+ * Three copies of "is a component open, and if so how long is it" is three
+ * chances to answer differently, and the symptom of disagreeing is a transport
+ * that wraps at a frame the scrubber cannot reach.
+ *
+ * A CODE COMPONENT HAS NO DURATION of its own — it has a `useStudioClock()` and
+ * whatever it does with it — so it gets the preview's fixed ruler. A definition
+ * has an authored one, or a derived extent.
+ */
+export function defClockFrames(s: ShotEditorState): number | null {
+  // The preview's loop length (bridge v45) wraps the stage, so the chrome's
+  // transport wraps at the same frame.
+  const loop = s.componentPreview.loopFrames;
+  if (s.codeComponent !== null) return loop ?? CODE_PREVIEW_FRAMES;
+  const def =
+    s.editingDef === null ? undefined : s.doc?.components?.[s.editingDef];
+  return def === undefined ? null : (loop ?? defDurationFrames(def));
+}
+
+/**
+ * THE WINDOW THE TRANSPORT LOOPS INSIDE, in whichever clock is driving.
+ *
+ * One function because the two halves of the answer have to agree: a start from
+ * one reading and a length from another is a loop that wraps to a frame outside
+ * itself, and `seek`'s clamp then pins the playhead there and playback looks
+ * frozen. Three subjects, innermost first:
+ *
+ *   A COMPONENT CONTEXT owns the clock outright. Its own duration, based at 0,
+ *   and `frame` does not move at all while it is open — so neither the entered
+ *   shot nor the work area has any say.
+ *
+ *   AN ENTERED SHOT is a window of master time, so it is the loop.
+ *
+ *   A WORK AREA is the scene context's own window, and only there: the two
+ *   above already answer, and a second window over one of them would be two
+ *   answers to one question. CLAMPED to the document on every read rather than
+ *   repaired on write — a trim, an undo or a deleted shot can shorten the film
+ *   under a work area nobody touched, and a stale end would loop past the last
+ *   frame the document has.
+ *
+ * It allocates one two-field object per call, and the two selectors below make
+ * that two allocations per store notification — which during playback is twice
+ * a frame. Deliberate, and within the rule this file keeps: what the rule
+ * forbids is the O(scenes) walk `sceneWindows` materialises per call, which is
+ * why the entered-shot arm reaches for `sceneToMaster` (a prefix sum with an
+ * early return) instead. Two fixed-size literals are not that.
+ *
+ * EXPORTED so the window rule can be asked directly, without a fake rAF queue
+ * to reach it — the same reason `playbackTargetFrame` is.
+ */
+export function playbackWindow(s: ShotEditorState): {
+  start: number;
+  frames: number;
+} {
+  const def = defClockFrames(s);
+  if (def !== null) return { start: 0, frames: def };
+  const doc = s.doc;
+  if (doc === null) return { start: 0, frames: 0 };
+  const total = docDurationFrames(doc);
+  if (s.enteredScene !== null) {
+    const entered = doc.scenesById[s.enteredScene];
+    // A STALE ENTERED SHOT FALLS BACK TO THE WHOLE FILM AND NOT TO THE WORK
+    // AREA. The shot was deleted out from under the author, which is a state
+    // the chrome repairs on its next context sync; borrowing a bracket they
+    // drew in the scene context for those few frames would be the transport
+    // inventing a window nobody asked for at the one moment it is confused.
+    return entered === undefined
+      ? { start: 0, frames: total }
+      : {
+          start: sceneToMaster(doc, s.enteredScene, 0) ?? 0,
+          frames: Math.max(0, Math.trunc(entered.durationFrames)),
+        };
+  }
+  const area = s.workArea;
+  if (area === null) return { start: 0, frames: total };
+  const end = Math.min(total, Math.trunc(area.end));
+  const start = Math.max(0, Math.trunc(area.start));
+  // A BRACKET THE FILM NO LONGER REACHES IS NO WINDOW AT ALL — fall back to the
+  // whole film rather than squeezing it onto the last frame. A one-frame loop
+  // at the end of a document the author just trimmed reads as a frozen
+  // transport, which is the failure this whole file keeps designing against,
+  // and the honest answer to "your bracket is off the end" is the film. A
+  // bracket that still OVERLAPS keeps its overlap: only the end was clamped.
+  return start < end ? { start, frames: end - start } : { start: 0, frames: total };
+}
+
+/** Whether the transport wraps at the end of `playbackWindow`. A definition
+ *  and an entered shot always do; the Project context follows the Loop pref. */
+export function playbackLoops(s: ShotEditorState): boolean {
+  if (defClockFrames(s) !== null) return true;
+  return s.enteredScene !== null || s.loopPlayback;
+}
+
+/**
+ * IS THE SOUND THE MASTER SOUNDTRACK, PLAYED STRAIGHT? The one answer behind
+ * `TransportSnapshot.audible`.
+ *
+ * TWO REASONS IT IS FALSE, and they are the same reason twice: a second clock
+ * the picture's clock cannot agree with.
+ *
+ *   A COMPONENT CONTEXT drives a definition-local clock and never moves
+ *   `frame`, so the document's soundtrack has nothing to anchor to — it would
+ *   start from a static master frame and play on over a definition looping on
+ *   its own. `defClockFrames` is the same predicate the transport forks on.
+ *
+ *   ANY RATE BUT 1 is silent, and that is a refusal rather than a gap. Reverse
+ *   needs reversed buffers; 2x and 4x with the pitch kept need a time
+ *   stretcher. Both are a second scheduler running on its own arithmetic
+ *   beside the picture's, and the moment the two round differently the author
+ *   is hearing one frame while watching another. This lane refuses that the
+ *   way it refuses every other plausible-but-wrong artifact.
+ *
+ * A pure function of the state, so the bridge that pushes the snapshot has no
+ * second opinion to form — see `audio/index.tsx`.
+ */
+export function transportAudible(s: ShotEditorState): boolean {
+  return defClockFrames(s) === null && s.playRate === 1;
+}
+
+/** The buffer the editor is showing, or null. One reader for `codeActive` so
+ *  nothing has to remember that it indexes `codeFiles`. */
+export function activeCodeFile(s: ShotEditorState): CodeFileState | null {
+  return s.codeActive === null ? null : (s.codeFiles[s.codeActive] ?? null);
+}
+
+/** The file the SUBJECT lives in, or null. What lets the URL leave `file=` off
+ *  in the ordinary case where the author is looking at the component's own
+ *  source: `code=` already says which file that is. */
+export function codeSubjectRel(s: ShotEditorState): string | null {
+  if (s.codeComponent === null) return null;
+  return s.library.find((r) => r.id === s.codeComponent)?.rel ?? null;
+}
+
+/** Is ANY open buffer unsaved? What the leave-confirm asks, and it must ask
+ *  across the whole tab set: the buffer on screen being clean says nothing
+ *  about the three behind it, and closing the studio drops them all. */
+export function anyCodeFileDirty(s: Pick<ShotEditorState, "codeFiles">): boolean {
+  return Object.values(s.codeFiles).some((f) => f.content !== f.savedContent);
+}
+
+/** Are the code buffers live? Only Code Studio's subject holds them. */
+export function buffersOpen(s: ShotEditorState): boolean {
+  return s.codeComponent !== null;
+}