@dailies-studio/shot-editor 0.1.0

package/src/state/store.ts

@@ -0,0 +1,4094 @@
+// The shot chrome's one store. Engine-owned history, one document, one stage.
+//
+// ── THE THREE RULES THIS FILE EXISTS TO KEEP ─────────────────────────────
+//
+// 1. EVERY DOCUMENT EDIT IS A `transaction()`. Undo/redo is engine's
+//    `createHistory<Doc3D>`, not a hand-rolled stack, so a gesture that wants
+//    "one undo entry for a whole drag" uses `scrub()` and gets it by
+//    construction rather than by remembering to coalesce.
+//
+// 2. THE STAGE IS PUSHED AT, NEVER POLLED. `loadDoc` on every history change,
+//    `seek` on every frame change, `setSelection` on every selection write. The
+//    stage holds no copy of anything it was not handed.
+//
+// 3. A SAVE ALWAYS CLAIMS ITS BASELINE. `baseRev` is the rev the open document
+//    was read at; a mismatch comes back 409 and the author is told to reload,
+//    never silently merged. `null` claims a create.
+import { createHistory } from "@dailies-studio/engine";
+import type { History } from "@dailies-studio/engine";
+import {
+  ASSET_ID_PREFIX,
+  LAYER_ID_PREFIX,
+  MAX_AUDIO_GAIN,
+  addAudioClip,
+  addLayer,
+  addMarker,
+  addPresetBlock,
+  addShot,
+  alignLayers,
+  addComponentInstance,
+  clonerLayers,
+  createComponent,
+  deleteComponent,
+  homeOf,
+  patchHome,
+  renameComponent,
+  animateGesture,
+  applyFramingDelta,
+  applyGesture,
+  applyInstanceRebinds,
+  applyToTransform,
+  instanceContractRefFor,
+  instancePropPlan,
+  cameraAt,
+  createShotDoc,
+  framingForLayers,
+  docDurationFramesCached,
+  duplicateLayers,
+  freshId,
+  groupLayers,
+  masterToSceneCached,
+  moveLayer,
+  canHoldChildren,
+  outermost as outermostIn,
+  parentBaseTransform,
+  parentOf,
+  rigidOf,
+  toLocal,
+  withDescendants,
+  relativesOf,
+  sceneToMaster,
+  MAX_FRAMING_ZOOM,
+  MIN_BLOCK_FRAMES,
+  MIN_FRAMING_ZOOM,
+  removeLayers,
+  renameLayer,
+  reorderLayer,
+  restackLayer,
+  moveBlock,
+  moveShot,
+  removeAudioClip,
+  removeBlock,
+  removeMarker,
+  removeShot,
+  reorderScene,
+  setBlockEase,
+  setBlockParams,
+  setBlockPreset,
+  setLayerFlags,
+  setSceneTransition,
+  sizeChangesPixels,
+  splitBlock,
+  splitScene,
+  trimBlock,
+  trimScene,
+  trimShot,
+  snapMove,
+  ungroupLayer,
+  worldBaseTransform,
+  updateAudioClip,
+  updateMarker,
+  usedIdsOf,
+  createScene,
+  writeFraming,
+} from "@dailies-studio/shot/doc";
+import type {
+  AlignMode,
+  AnimBlock,
+  BlockSlot,
+  Doc3D,
+  Framing,
+  FramingDelta,
+  GestureDelta,
+  GestureKind,
+  InstanceContractRef,
+  InstanceLayer3D,
+  MarkerRef,
+  MoveShot,
+  Scene3D,
+  SceneTransition,
+  Shot,
+  ShotAssetKind,
+  SnapGuide,
+} from "@dailies-studio/shot/doc";
+import { patchProposalIn } from "@dailies-studio/agent-client";
+import type {
+  AgentCredentialsInfo,
+  AgentProposalPatch,
+  AgentTranscriptItem,
+} from "@dailies-studio/agent-client";
+import type { RenderJob } from "../api.js";
+import type { Ease, Value } from "@dailies-studio/engine";
+import type { Scrub } from "@dailies-studio/engine";
+import * as api from "../api.js";
+import { ApiError } from "../api.js";
+import { isOwnEcho } from "./clientId.js";
+import { DOCK_HEIGHT, RAIL_WIDTH, clampSize, dockCeiling } from "./panelSize.js";
+import { INITIAL_STATE, INITIAL_VIEW } from "./types.js";
+import type { ShotEditorState } from "./types.js";
+import { deviceLayer, htmlLayer, instanceLayer, layerFromDraw, meshLayer, penLayer } from "./insert.js";
+import { TRIANGLE_CAP_REFUSAL, TRIANGLE_HARD_CAP, sumTriangles } from "./triangles.js";
+import type { DrawPoint, InsertContext, NewLayer3D } from "./insert.js";
+import { isEditable, resolveKey } from "./keymap.js";
+import type { KeyEventLike } from "./keymap.js";
+import { FIT_MARGIN, clampZoom } from "../stage/view.js";
+import { clampSplitRatio } from "../stage/panes.js";
+import { nextShading } from "../stage/shading.js";
+import {
+  DOLLY_FALLOFF_PX,
+  WORKING_FOV_DEG,
+  dollyBounds,
+  dollyBy,
+  framingFromWorkingView,
+  orbitByDegrees,
+  presetWorkingView,
+  workingViewForFraming,
+} from "../stage/workingView.js";
+import { CAMERA_ROW_ID, writeAudioDrag, writeLifespan } from "../panels/timeline/model.js";
+import type { AudioDrag, LifespanDrag } from "../panels/timeline/model.js";
+import { wavDurationSeconds } from "@dailies-studio/timeline";
+import type { InsertTool, ShotTool } from "../tools.js";
+import type {
+  PickModifiers,
+  ShadingMode,
+  ShotBridgeHandlers,
+  ShotScreenQuad,
+  ShotStageBridge,
+  ShotStageInfo,
+  ShotView,
+  StageLayout,
+  StagePane,
+  WorkingView,
+  WorkingViewOrigin,
+} from "../bridgeTypes.js";
+
+/** How close a moving edge has to come to a target before it is pulled onto it,
+ *  in SCREEN px. Divided by the zoom at use, so the pull feels the same size on
+ *  screen at every zoom — snapping that got stronger as you zoomed out is the
+ *  classic version of this bug. */
+const SNAP_THRESHOLD_PX = 6;
+
+/** A stand-in target for a relayed key that landed in a field on the STAGE. The
+ *  stage cannot send a DOM node across the bridge, so it sends the verdict and
+ *  this reconstitutes something `isEditable` agrees with. */
+const EDITING_TARGET = { tagName: "INPUT", isContentEditable: false } as unknown as EventTarget;
+
+/** Autosave debounce. Long enough that a drag is one save, short enough that
+ *  closing the tab a beat after an edit does not lose it. */
+const AUTOSAVE_MS = 400;
+
+/**
+ * Every "what is selected" bit, cleared. Loading a document must set ALL of
+ * them, and `set` merges, so a swap that only cleared `selection` left the
+ * others pointing into the document that just went away.
+ *
+ * That is not a near miss: ids in this lane are deterministic slugs minted
+ * against one document's used ids, so the FIRST marker of every shot is
+ * `mk_marker` and a stale `selectedMarker` resolves against its successor. The
+ * inspector then opens on a marker the author never clicked and Delete removes
+ * it, because `deleteSelection` consults the marker before the layers.
+ */
+const CLEARED_SELECTION = {
+  selection: [] as readonly string[],
+  selectedBlock: null,
+  selectedMarker: null,
+  imagePick: null,
+  // Isolation is a layer id too, and the same deterministic-slug argument
+  // applies to it exactly: `l3_card` exists in most shots, so an isolation
+  // carried across a document swap would silently enter a DIFFERENT card and
+  // scope every pick to it.
+  isolation: null,
+  editingDef: null,
+} satisfies Partial<ShotEditorState>;
+
+/**
+ * How long the wheel has to go quiet before a follow-mode dolly counts as
+ * finished.
+ *
+ * A wheel is the one authoring gesture with no end: a trackpad flick is thirty
+ * to eighty events and no release. Follow mode makes each of them a document
+ * write, so without a bracket one flick is thirty undo entries — while the pan
+ * and the orbit on the same pane are one each. Silence is the only end signal a
+ * wheel has.
+ *
+ * Long enough to bridge the gaps inside one flick, short enough that the scrub
+ * it holds open is closed before the author's hand reaches a panel — and every
+ * other lane that takes the history closes it first anyway, so the window is a
+ * latency question and never a correctness one.
+ */
+const WHEEL_IDLE_MS = 180;
+
+/** How far behind the chrome's `workingView` mirror may trail the stage's live
+ *  value while follow is off. Nothing renders from it — it feeds persistence
+ *  and the keyboard zoom's read — so 10 Hz is indistinguishable from live. */
+const WORKING_VIEW_MIRROR_MS = 100;
+
+/**
+ * One press of the zoom buttons, expressed as the wheel travel that produces
+ * the camera pane's own 1.25x step.
+ *
+ * Routed through `dollyBy` rather than written onto `distance` so the working
+ * pane's clamps stay the only place a distance is bounded — and so "zoom in"
+ * means the same RATIO in both panes, which is the only sense in which the two
+ * can be the same control.
+ */
+const WORKING_ZOOM_STEP_PX = DOLLY_FALLOFF_PX * Math.log(1.25);
+
+/**
+ * A new camera move's length: ONE SECOND of the document's own fps.
+ *
+ * Derived rather than a frame count, because a move is a CINEMATIC duration. A
+ * fixed 30 would be a third of a second on a 90fps document and two seconds on
+ * a 15fps one, which is the same number meaning two different things.
+ */
+const NEW_SHOT_SECONDS = 1;
+
+/**
+ * Said by every lane that wants the history while a POINTER holds it. Engine
+ * allows one scrub, so the alternative is an exception thrown at the author
+ * from inside somebody else's event handler.
+ *
+ * WORDED FOR EVERY CALLER, not just the camera. `undo` is the one that has to
+ * be covered and is the easiest to miss: it bypasses `edit` entirely, and
+ * `commit()` clears the redo stack, so an undo taken mid-drag does not merely
+ * land inside the drag's entry — it destroys that entry on BOTH stacks.
+ */
+const HISTORY_BUSY =
+  "A drag is still running, so this would land inside its own undo entry — " +
+  "finish the drag, then try again.";
+
+export interface ShotEditorStore {
+  getState(): ShotEditorState;
+  subscribe(listener: () => void): () => void;
+
+  /** Handed to `connectStage`; the stage calls these. */
+  readonly stageHandlers: ShotBridgeHandlers;
+  attachStage(bridge: ShotStageBridge | null): void;
+  /** The live bridge, for the overlay layer's per-frame quad read. Null until
+   *  the stage connects. */
+  stage(): ShotStageBridge | null;
+  selectionQuads(): readonly ShotScreenQuad[] | null;
+
+  refreshShots(): Promise<void>;
+  openShot(name: string): Promise<void>;
+  createShot(name: string): Promise<void>;
+  closeShot(): void;
+  /** Adopt a write that landed from somewhere else (another tab, an agent). */
+  adoptExternalChange(payload: { name?: string; origin?: string; clientId?: string }): void;
+
+  /**
+   * The ONE document-edit seam. `fn` must be pure and must return the SAME
+   * reference when nothing changed — that is what makes a no-op edit cost no
+   * history entry and no save.
+   *
+   * ── IT ANSWERS WHETHER IT RAN ─────────────────────────────────────────
+   *
+   * False means the edit was REFUSED, and the refusal is already in `error`.
+   * Every caller that follows an edit with its own `set({ error })` was wiping
+   * that message: a mid-drag arrow nudge hit `historyBusy`, which wrote
+   * HISTORY_BUSY, and then the caller's own "nothing to nudge" (or its `null`)
+   * overwrote it — so the key did nothing and said nothing, which is the exact
+   * silence this lane keeps removing. Ten call sites shared the bug and share
+   * this fix.
+   */
+  edit(fn: (doc: Doc3D) => Doc3D): boolean;
+  undo(): void;
+  redo(): void;
+  /** Force the pending autosave now (a doc switch, a close, a blur). */
+  flush(): Promise<void>;
+
+  seek(frame: number): void;
+  setPlaying(playing: boolean): void;
+  /** Advance one frame; the transport's rAF loop calls this. */
+  step(delta: number): void;
+
+  select(ids: readonly string[]): void;
+  /**
+   * Bring the playhead into a scene, so what the author is about to click is on
+   * screen. A no-op when it already is.
+   *
+   * The dock shows every scene at once and the STAGE shows exactly one: the one
+   * at the playhead. So a row press in another scene has to navigate, or the
+   * author selects a layer that draws no handles, opens an inspector on
+   * something invisible, and `select` — which orders ids within the current
+   * scene — quietly resolves the selection to nothing.
+   *
+   * SELECTING navigates; CREATING does not. "Show me this" moving the playhead
+   * is the request; "+ shot", which puts a new thing AT the playhead, would be
+   * silently changing where its own write lands, so that one refuses by name
+   * instead.
+   */
+  focusScene(sceneId: string): void;
+  setScene(sceneId: string | null): void;
+  setTool(tool: ShotTool): void;
+  setInspectorMode(mode: "design" | "animate"): void;
+  setAnimateMode(on: boolean): void;
+
+  /** THE ONLY KEY BINDING SITE. Returns true when the event was consumed, so
+   *  the caller knows whether to preventDefault. */
+  handleKey(event: KeyEventLike & { target?: EventTarget | null }): boolean;
+
+  /** Layer-tree edits, each one transaction. The sidebar and the keymap drive
+   *  the same functions, so "what does delete do" has one answer. */
+  deleteSelection(): void;
+  duplicateSelection(): void;
+  /** Align or distribute the selection on the design plane. */
+  alignSelection(mode: AlignMode): void;
+  groupSelection(): void;
+  ungroupSelection(): void;
+  toggleFlag(flag: "hidden" | "locked"): void;
+  renameLayer(id: string, label: string): void;
+  reorderLayer(id: string, toIndex: number): void;
+  /** Reparent and/or reorder, keeping the layer where it is on screen. The
+   *  outline's drop target; `parent: null` is the scene root. */
+  moveLayerTo(id: string, to: { parent?: string | null; index?: number }): void;
+  // ── components ────────────────────────────────────────────────────────────
+  /** Turn the selection into a reusable definition and leave one instance. */
+  createComponentFromSelection(name?: string): void;
+  /** Another placement of a definition, at its own size. */
+  placeComponent(defId: string): void;
+  /** Refuses while instances exist, naming where they are. */
+  deleteComponent(defId: string): void;
+  renameComponent(defId: string, name: string): void;
+  /** One exposed field on one instance. `null` clears it back to the
+   *  definition's own value. */
+  setComponentOverride(layerId: string, key: string, value: Value | null): void;
+  /** Scope the OUTLINE to a definition's interior, or null for the scene. */
+  editComponent(defId: string | null): void;
+
+  /** Edit this subtree alone: the working pane frames it head-on, everything
+   *  outside it dims and stops being pickable. */
+  enterIsolation(id: string): void;
+  /** Up ONE level, to the isolated layer's parent — or out to the scene when
+   *  it had none. Entering walks down, so leaving walks back up. */
+  exitIsolation(): void;
+  /** All the way out to the scene, however deep. The breadcrumb's first crumb;
+   *  Escape is the one-level version. */
+  exitIsolationAll(): void;
+  restack(id: string, to: "front" | "back" | "forward" | "backward"): void;
+  nudge(dx: number, dy: number): void;
+  selectAll(): void;
+
+  // ── the insertion lane ───────────────────────────────────────────────────
+  //
+  // The draw tools arrive through `stageHandlers.onDraw` (the stage owns the
+  // pointer); these are the paths a MENU drives, plus the second half of the
+  // image tool, which has to wait on a file.
+  /**
+   * Finish a drawn media layer with the file the author picked, or drop the
+   * pending box when they cancelled (`null`).
+   *
+   * An IMAGE OR A VIDEO, decided by the kind the server sniffed — the Frame
+   * tool draws one box and the file fills it. Rejects with a message the caller
+   * shows. Asset and layer land in ONE undo entry — see `insertAssetLayer`.
+   */
+  completeImageDraw(file: File | null): Promise<void>;
+  /** Upload a .glb and insert a mesh layer naming it, at the playhead. */
+  addMeshLayer(file: File): Promise<void>;
+  /** Insert a device slab of a preset from the registry, at the playhead. */
+  addDeviceLayer(preset: string): void;
+  /** Insert an html snippet layer at the playhead. No drag tool: a snippet is
+   *  authored in the inspector, and a rubber band would only pick its box. */
+  addHtmlLayer(): void;
+  /**
+   * Wrap the selection in a cloner.
+   *
+   * There is deliberately no "insert an empty cloner": `validateShotDoc`
+   * refuses a cloner with no children, so the empty one would be a document the
+   * author could not save. A no-op with nothing selected is the honest answer,
+   * and the menu disables the row rather than offering it.
+   */
+  addClonerLayer(): void;
+
+  // ── the component registry (instance layers) ─────────────────────────────
+  /** Fetch `GET /api/components` into `library`. Never throws: a failed fetch
+   *  sets `libraryError` and leaves `libraryLoaded` false, because "the lookup
+   *  failed" and "there are no components" must never look the same. */
+  refreshLibrary(): Promise<void>;
+  /** Fetch and cache ONE component's contract. Idempotent and deduped. */
+  loadContract(componentId: string): Promise<void>;
+  /** Mount a contracted component as a layer at the playhead. The registry row
+   *  supplies the binding (hash + import-or-snapshot); a row whose host is not
+   *  "three" is refused here as well as at the save gate, so the menu can never
+   *  produce a document the server would reject. */
+  addInstanceLayer(componentId: string): Promise<void>;
+  /** Set ONE contract-keyed prop on an instance layer. */
+  setInstanceProp(layerId: string, key: string, value: Value): void;
+  /** Clear one stored prop, so it falls back to the contract's default. Also
+   *  how a quarantined override is finally discarded — by the AUTHOR, explicitly,
+   *  which is the only way one ever goes away. */
+  clearInstanceProp(layerId: string, key: string): void;
+  setInstanceClockOffset(layerId: string, frames: number): void;
+  /**
+   * Re-bind an instance to its component's CURRENT contract.
+   *
+   * Records the live hash, re-decides import-vs-snapshot, and moves every value
+   * the rename/orphan planner classifies as a `rebind` onto its new key.
+   * Orphans are LEFT WHERE THEY ARE — the quarantine — because dropping them is
+   * the documented silent-data-loss failure this whole lane is written against.
+   * Never automatic: it is a statement that the current contract is the one
+   * this instance means, and only the author can make it.
+   */
+  rebindInstance(layerId: string): Promise<string | null>;
+
+  // ── the timeline dock ────────────────────────────────────────────────────
+  setDockCollapsed(collapsed: boolean): void;
+  setRailCollapsed(collapsed: boolean): void;
+  setInspectorCollapsed(collapsed: boolean): void;
+  /** Both clamp; both take the RAW dragged value, so the handle never has to
+   *  know the bounds. */
+  setRailWidth(width: number): void;
+  setDockHeight(height: number): void;
+  /** Hide every panel, or bring them all back. See the implementation. */
+  togglePanels(): void;
+  setDockPpf(ppf: number): void;
+
+  // ---- the audio lane --------------------------------------------------------
+  /**
+   * Upload a file, measure the STORED wav, and register asset + clip in ONE
+   * undo entry. Rejects with a message the lane shows; never leaves half of it
+   * on the document.
+   */
+  importAudio(file: File, atFrame?: number): Promise<void>;
+  /** One capture of the live `beginBlockDrag` scrub. See `writeAudioDrag`. */
+  dragAudio(clipId: string, mode: AudioDrag, delta: number): void;
+  /** Linear 0..2, also one capture of the live scrub. */
+  dragAudioGain(clipId: string, gain: number): void;
+  toggleAudioMute(clipId: string): void;
+  removeAudio(clipId: string): void;
+  /** PREVIEW monitoring, never the mix. */
+  setPreviewMuted(muted: boolean): void;
+  setPreviewVolume(volume: number): void;
+
+  // ---- the marker lane -------------------------------------------------------
+  selectMarker(markerId: string | null): void;
+  /**
+   * `M`, and the lane's `+`. ONE transaction, and the new mark becomes the
+   * inspector's subject.
+   *
+   * A second press at the same frame SELECTS the mark already there rather than
+   * stacking an invisible duplicate on it. Premiere does the same, and the
+   * alternative is a document with two marks the author can only tell apart by
+   * deleting one.
+   */
+  addMarkerAtPlayhead(): void;
+  /** One capture of the live `beginBlockDrag` scrub, so a marker drag is one
+   *  undo entry like every other gesture on the strip. */
+  dragMarker(markerId: string, frame: number): void;
+  /** The inspector's fields. One transaction each. */
+  setMarker(markerId: string, patch: Partial<Omit<MarkerRef, "id">>): void;
+  removeMarker(markerId: string): void;
+
+  selectBlock(at: { sceneId: string; layerId: string; blockId: string } | null): void;
+  /**
+   * The dock's "fit the whole document across the lane", registered by the dock
+   * because only the dock knows how many pixels wide its lane is.
+   *
+   * The same shape `fitView` uses against the stage bridge: the store owns the
+   * verb so the keymap has one place to reach, and the surface that owns the
+   * measurement owns the arithmetic. Null on unmount.
+   */
+  attachDockFit(fit: ((sceneId?: string) => void) | null): void;
+  /** No argument fits the whole document; a scene id frames THAT SHOT across
+   *  the lane (the strip's double-click). */
+  fitDock(sceneId?: string): void;
+
+  // ── export ───────────────────────────────────────────────────────────────
+  setExportOpen(open: boolean): void;
+  /** Mirror one render job off the SSE bus (or off the POST that started it). */
+  setRenderJob(job: RenderJob | null): void;
+
+  // ── the agent drawer ─────────────────────────────────────────────────────
+  setAgentOpen(open: boolean): void;
+  setAgentModel(model: string | null): void;
+  setAgentCredentials(info: AgentCredentialsInfo | null, error?: string): void;
+  setAgentRunning(running: boolean): void;
+  setAgentError(error: string | null): void;
+  setAgentSession(sessionId: string): void;
+  setAgentCost(costUsd: number | null): void;
+  appendAgentItem(item: AgentTranscriptItem): void;
+  patchAgentProposal(id: string, patch: AgentProposalPatch): void;
+  clearAgentTranscript(): void;
+  /** One scrub for a whole trim or move, exactly like a canvas gesture. Shared
+   *  by the block bars, the lifespan bars and the scene strip's trim: only one
+   *  of them can have the pointer, so one lane is all they need. */
+  beginBlockDrag(): void;
+  dragBlock(
+    sceneId: string,
+    layerId: string,
+    blockId: string,
+    edge: "body" | "in" | "out",
+    toFrame: number,
+  ): void;
+  /** A lifespan bar's body, its two edges, or a slip. `delta` is measured from
+   *  the scrub's BASE, not from the last move. */
+  dragLifespan(sceneId: string, layerId: string, mode: LifespanDrag, delta: number): void;
+  endBlockDrag(commit: boolean): void;
+  trimScene(sceneId: string, durationFrames: number): void;
+  reorderScene(sceneId: string, toIndex: number): void;
+  /** The blend this shot plays INTO the next one; null clears it. Stored on the
+   *  outgoing shot, so it travels with the content it was authored against. */
+  setSceneTransition(sceneId: string, next: SceneTransition | null): void;
+  /** Append a scene to the master timeline and seek into it. The scene strip is
+   *  the only place scenes are created, reordered and trimmed. */
+  addScene(): void;
+  /** ⌘B. Splits the focused BLOCK when there is one, else the current SCENE. */
+  splitAtPlayhead(): void;
+
+  // ── blocks ───────────────────────────────────────────────────────────────
+  /** Add an In / Out / During preset block to every selected layer. */
+  addBlock(slot: BlockSlot, preset: string, durationFrames?: number): void;
+  setBlockParams(layerId: string, blockId: string, params: Record<string, Value>): void;
+  setBlockEase(layerId: string, blockId: string, ease: AnimBlock["ease"]): void;
+  setBlockTiming(layerId: string, blockId: string, frame: number, durationFrames: number): void;
+  /** Swap a block's preset IN PLACE, keeping its window and its ease. */
+  setBlockPreset(layerId: string, blockId: string, preset: string): void;
+  removeBlock(layerId: string, blockId: string): void;
+  /** Clear one In/Out preset from the whole selection — the palette's toggle-off. */
+  removeBlocksByPreset(slot: BlockSlot, preset: string): void;
+  setView(view: ShotView): void;
+  fitView(): void;
+  /** Zoom the ACTIVE pane one step: the camera view's zoom, or a working-view
+   *  dolly. ONE verb for the header buttons and for ⌘+/⌘−, so the two cannot
+   *  route to different panes. */
+  zoomActivePane(direction: 1 | -1): void;
+  /** Fit the ACTIVE pane — what ⇧Z does, shared with the header readout. */
+  fitActivePane(): void;
+  /** How many panes the stage shows. Clamps the ratio and keeps `activePane`
+   *  pointing at a pane that actually exists. */
+  setStageLayout(layout: StageLayout): void;
+  setWorkingView(view: WorkingView): void;
+  fitWorkingView(): void;
+  /** Frame the SELECTION in the working view, keeping the author's angles —
+   *  numpad-dot. Falls back to `fitWorkingView` (frame all) on an empty or
+   *  extentless selection, so the key never reads dead. It derives from editor
+   *  state and writes no document of its own; the write it CAN cause is
+   *  follow mode's, through `setWorkingView`, on the documented rule that
+   *  follow is follow whatever moved the view. */
+  fitWorkingViewToSelection(): void;
+  setActivePane(pane: StagePane): void;
+
+  // ── the camera, authored from the working pane ───────────────────────────
+  //
+  // All three go through ONE document op (camera.ts's `writeFraming`) and
+  // therefore through one three-way fork: base write, refusal, or a move
+  // ending at the playhead. What differs is only which framing they ask for.
+  /** Arm "camera follows this view". Never called a lock — see types.ts. */
+  setCameraFollowsView(on: boolean): void;
+  /** The working pane's shading. Workspace state; the camera pane is always
+   *  the graded render and is not addressable here. */
+  setShadingMode(mode: ShadingMode): void;
+
+  // ── mesh materials ───────────────────────────────────────────────────────
+  /** Open the material picker for these mesh layers. Editor state: nothing
+   *  reaches the document until a card is chosen. */
+  openMaterialPicker(layerIds: readonly string[]): void;
+  closeMaterialPicker(): void;
+  /** Paint a catalog TSL generator over every named mesh layer's albedo, in
+   *  ONE undo entry. */
+  applyMeshMaterial(layerIds: readonly string[], generatorId: string): void;
+  /** Back to the model's own materials. */
+  removeMeshMaterial(layerIds: readonly string[]): void;
+  /** Point the shot camera where the working pane is looking, or refuse when
+   *  that pose is not expressible as a framing. */
+  alignCameraToWorkingView(): void;
+  /** Frame the selection, with the same margin the stage's own fit uses. */
+  fitCameraToSelection(): void;
+  /** Type a framing field. THE SAME SEAM A DRAG USES, so the inspector and the
+   *  frustum cannot disagree about when a base write is invisible. */
+  setSceneCamera(patch: Partial<Framing>): void;
+
+  // ── one camera move ──────────────────────────────────────────────────────
+  //
+  // These three write a SHOT and never `scene.camera`, so they are outside the
+  // three-way fork above by construction: a shot's `from` and `to` are visible
+  // at its own frames whatever the playhead is doing, which is exactly why the
+  // panel that edits them can be plain fields.
+  setShotFraming(shotId: string, end: "from" | "to", patch: Partial<Framing>): void;
+  /** The TWO-POSE kinds only. A path is authored by an agent, through
+   *  `waypoints`, and converting a move into one from a segmented control
+   *  would need a waypoint editor this chrome does not have. */
+  setShotKind(shotId: string, kind: MoveShot["kind"]): void;
+  setShotEase(shotId: string, ease: Ease): void;
+  /** ⇧C, and the dock's "+ shot". A move that is STILL at both ends until the
+   *  author drags the frustum or types a field. `sceneId` is which camera row
+   *  asked; omitted (the key) means the scene the playhead is in. */
+  addShotAtPlayhead(sceneId?: string): void;
+  dismissError(): void;
+  /** Surface a refusal from a panel. Null clears. Panels do not own the error
+   *  strip, so this is the one way in. */
+  reportError(message: string | null): void;
+}
+
+export function createShotEditorStore(): ShotEditorStore {
+  let state: ShotEditorState = INITIAL_STATE;
+  const listeners = new Set<() => void>();
+  let docHistory: History<Doc3D> | null = null;
+  let bridge: ShotStageBridge | null = null;
+  /** The dock's own fit, registered while it is mounted. */
+  let dockFit: ((sceneId?: string) => void) | null = null;
+  let saveTimer: ReturnType<typeof setTimeout> | null = null;
+  /** The stage's working view, mirrored at a trailing 10 Hz while follow is
+   *  off — see onWorkingViewChange. */
+  let pendingWorkingView: WorkingView | null = null;
+  let workingViewMirror: ReturnType<typeof setTimeout> | null = null;
+  type SnapBox = Parameters<typeof snapMove>[0][number];
+  /** The live drag, or null. Holds the history scrub that makes it one entry,
+   *  and the screen scale of the PANE it started in — see `snapFor`. */
+  let gesture: {
+    kind: GestureKind;
+    layerIds: string[];
+    scrub: Scrub<Doc3D>;
+    screenScale: number | null;
+    /** snapFor's box lists, built once per gesture instead of per pointermove:
+     *  they derive from the scrub BASE and the selection, both fixed for the
+     *  whole drag. Keyed on the scene because a playing timeline can cross a
+     *  scene boundary mid-drag, which must rebuild rather than snap against
+     *  the previous scene's layers. */
+    snap: { forScene: string; moving: SnapBox[]; others: SnapBox[] } | null;
+  } | null = null;
+  /**
+   * The live CAMERA drag, or null. A separate lane from `gesture` because the
+   * two write different things through different ops, and only this one can be
+   * refused for sitting under a shot.
+   *
+   * Never both: engine's history allows one scrub at a time and throws on a
+   * second, which a pointer already guarantees — but the guards below say so
+   * rather than relying on it, because a lost pointerup must not turn the next
+   * press into an exception thrown across the bridge.
+   */
+  let framing: Scrub<Doc3D> | null = null;
+  /**
+   * The live KEY-LIGHT drag, or null. A third lane for the same reason the
+   * second one exists: it writes a different thing (one mesh layer's shading)
+   * through a different path, and the three guard each other rather than
+   * relying on a pointer to be the only way in.
+   */
+  let keyLight: { layerId: string; scrub: Scrub<Doc3D> } | null = null;
+  /**
+   * The idle timer that closes a follow-mode WHEEL dolly's framing scrub.
+   *
+   * Non-null means this store — not a pointer — opened `framing`, and is the
+   * only thing allowed to close it. Every other lane that wants the history
+   * flushes it first (`closeWheelFraming`), because engine allows exactly one
+   * scrub and a wheel's is open during a window nothing else can see.
+   */
+  let wheelFraming: ReturnType<typeof setTimeout> | null = null;
+  let savePromise: Promise<void> = Promise.resolve();
+  /**
+   * THE GENERATION FENCE. Every async load carries the generation it started
+   * in; a response from an older one is DISCARDED rather than applied. Without
+   * it, opening B while A is still loading resolves A last and shows A under
+   * B's name — which reads as data loss and is impossible to reproduce.
+   */
+  let generation = 0;
+
+  function set(patch: Partial<ShotEditorState>): void {
+    let changed = false;
+    for (const key of Object.keys(patch) as (keyof ShotEditorState)[]) {
+      if (!Object.is(state[key], patch[key])) {
+        changed = true;
+        break;
+      }
+    }
+    if (!changed) return;
+    state = { ...state, ...patch };
+    for (const l of listeners) l();
+  }
+
+  function pushDocToStage(doc: Doc3D): void {
+    bridge?.loadDoc(doc);
+    // ISOLATION RIDES EVERY DOCUMENT PUSH, not only the ones that changed it.
+    //
+    // The stage validates the id against ITS OWN document (bridgeClient's
+    // `sceneWithLayer`), so the push is the only thing that can clear an
+    // isolation the new document does not contain. Without it, opening a second
+    // shot while inside a card left the stage holding the first document's id:
+    // `withDescendants` then answers a set of one id that no layer matches, so
+    // the dim keeps NOTHING, every layer fades, and `pickable` filters down to
+    // empty. The author gets a uniformly dimmed pane where no click does
+    // anything, and the chrome shows no isolation at all to explain it.
+    //
+    // AFTER `loadDoc`, because the validation reads the document this pushed.
+    // `bridgeClient.set` no-ops on `Object.is` equality, so re-pushing an
+    // unchanged id costs nothing and this can be unconditional.
+    bridge?.setIsolation(state.isolation);
+    // AND THE CAMERA MODE BEHIND IT, because `setIsolation` resets the stage's
+    // copy to head-on on its own. Without this, a Vite reload — or any document
+    // push — would drop an author who had taken the camera straight back to the
+    // derived rig, which reads as the view snapping for no reason.
+    if (state.isolationOrbit) bridge?.setIsolationOrbit(true);
+  }
+
+  /**
+   * The workspace bits the stage cannot know, re-pushed on every attach.
+   *
+   * DOCUMENT-INDEPENDENT, so unlike the doc/frame/selection re-push this one is
+   * NOT gated on a document being open: a fresh stage that connected before any
+   * document exists still has to come up in the layout the author left, or the
+   * split silently collapses on every Vite reload.
+   */
+  function pushWorkspaceToStage(): void {
+    bridge?.setStageLayout(state.stageLayout);
+    bridge?.setWorkingView(state.workingView);
+    bridge?.setCameraFollowsView(state.cameraFollowsView);
+    bridge?.setShadingMode(state.shadingMode);
+    // THE ARMED TOOL IS WORKSPACE STATE TOO, and it was the one piece pushed
+    // only from `setTool`. A Vite reload of the stage therefore came back with
+    // the select tool while the dock still lit the rect (or the pen), and the
+    // author's next drag did something they had not asked for.
+    bridge?.setTool(state.tool);
+    // NO ISOLATION HERE. It used to ride the workspace push, but isolation
+    // names a LAYER, so it is document-scoped and belongs with the document —
+    // see `pushDocToStage`. Every path that reaches this function with a
+    // document open pushes that document first, so a Vite reload still comes
+    // back inside the subtree the author was in.
+  }
+
+  /** Clamp a master frame into the open document. A frame past the end is not
+   *  an error (a scene got trimmed), it is a frame that has to come back. */
+  function clampFrame(doc: Doc3D | null, frame: number): number {
+    if (doc === null) return 0;
+    const last = Math.max(0, docDurationFramesCached(doc) - 1);
+    return Math.max(0, Math.min(last, Math.round(frame)));
+  }
+
+  /**
+   * The container a LAYER-TREE edit writes to.
+   *
+   * A component definition while one is open in the outline, the current shot
+   * otherwise. Every op in `layerOps` takes a container id rather than a scene
+   * id (see home.ts), so routing the eight tree verbs through this one function
+   * is the whole of what makes a definition's interior editable — with the same
+   * drag, the same rename, the same flags and the same undo.
+   *
+   * The PLAYHEAD's scene is deliberately not this: inserting at the playhead,
+   * placing a block and splitting are scene-scoped whatever the outline is
+   * showing.
+   */
+  function layerContainer(): string | null {
+    return state.editingDef ?? state.sceneId;
+  }
+
+  /** The scene the playhead is in, which is what the inspector and the micro
+   *  timeline follow unless the author has pinned another one. */
+  function sceneAt(doc: Doc3D | null, frame: number): string | null {
+    if (doc === null) return null;
+    return masterToSceneCached(doc, frame)?.scene.id ?? doc.scenes[0] ?? null;
+  }
+
+  function onHistoryChange(doc: Doc3D): void {
+    const frame = clampFrame(doc, state.frame);
+    const sceneId = sceneAt(doc, frame);
+    // THE ONE INVALIDATION POINT for isolation. Every document write lands
+    // here — undo, redo, a delete, an agent edit — so validating the id once
+    // in this function covers all of them, and there is no second place that
+    // could forget. A subtree whose root is gone leaves the author inside a
+    // pane framing nothing, with the surroundings unpickable and no way out.
+    //
+    // BOTH SCOPES, and the second one was missing. `isolationStillReal` asks
+    // whether the layer is anywhere in the document, which is right for a
+    // delete; it says nothing about whether it is in the scene now ON SCREEN.
+    // A `reorderScene`, `trimScene`, `splitScene` or an undo can move the
+    // playhead into a different scene, and the crumb then claimed an isolation
+    // the stage refuses to scope to — with `selectAll` scoped to it selecting
+    // nothing. `seek` and `setScene` already run this; the history seam is the
+    // third door into the same state and had only half the guard.
+    const alive = isolationStillReal(doc, state.isolation) ? state.isolation : null;
+    // Against the COMMITTED doc, not `state.doc`: this runs before the `set`
+    // below, so the store's copy is still the previous document.
+    const isolation = alive === null ? null : isolationForScene(sceneId, doc);
+    // The same guard for the outline's subject, and for the same reason: a
+    // definition can be deleted, undone away or removed by an agent, and an
+    // outline scoped to one that is gone shows an empty tree with no way back.
+    const editingDef =
+      state.editingDef !== null && doc.components?.[state.editingDef] !== undefined
+        ? state.editingDef
+        : null;
+    set({
+      doc,
+      frame,
+      sceneId,
+      isolation,
+      // An isolation that went stale takes its camera mode with it, or the next
+      // subtree would open in a perspective pose derived from a layer that no
+      // longer exists.
+      ...(isolation === null ? { isolationOrbit: false } : {}),
+      editingDef,
+      dirty: true,
+      canUndo: docHistory?.canUndo ?? false,
+      canRedo: docHistory?.canRedo ?? false,
+    });
+    // `pushDocToStage` carries the isolation, so there is no second push here.
+    pushDocToStage(doc);
+    bridge?.seek(frame);
+    scheduleSave();
+  }
+
+  /** Is an isolated layer still in the document? Its ANCESTORS matter too:
+   *  deleting a group takes its children with it, and a child id that survives
+   *  in nothing is exactly the stale case. `layersById` is the whole answer —
+   *  `removeLayers` drops the subtree, so a live entry means a live layer. */
+  function isolationStillReal(doc: Doc3D, id: string | null): boolean {
+    if (id === null) return false;
+    return Object.values(doc.scenesById).some((s) => s.layersById[id] !== undefined);
+  }
+
+  /**
+   * The isolation, dropped when the SCENE ON SCREEN does not hold it.
+   *
+   * DOCUMENT scope is right for `isolationStillReal` above and SCENE scope is
+   * right here, and the two are not in tension: an edit made while the playhead
+   * sits in another scene must not drop a valid isolation, but the playhead
+   * ARRIVING in another scene means the subtree the author is inside is not on
+   * screen any more. The stage already refuses to scope to it (StageApp's
+   * `isolated` memo), so leaving the chrome's copy set would put a breadcrumb
+   * and an outline scope over a pane showing the whole scene — two truths, and
+   * the author's next click would disagree with what the panel says.
+   *
+   * Scrubbing back does NOT restore it. That is the honest half: an isolation
+   * the author cannot see is not one they are in.
+   */
+  function isolationForScene(sceneId: string | null, doc: Doc3D | null = state.doc): string | null {
+    const id = state.isolation;
+    if (id === null || sceneId === null) return id;
+    return doc?.scenesById[sceneId]?.layersById[id] === undefined ? null : id;
+  }
+
+  /**
+   * Re-read the mirrored undo/redo flags.
+   *
+   * `scrub.commit()` records the undo entry WITHOUT a document notification —
+   * the captures already notified, and the commit changes no document, only the
+   * stacks. So the flags a capture mirrored say "nothing to undo", and the undo
+   * button stays disabled after a drag until some later edit happens to refresh
+   * it. Both other chromes call this at exactly the same place, with the same
+   * reason written down.
+   */
+  function syncHistoryFlags(): void {
+    set({ canUndo: docHistory?.canUndo ?? false, canRedo: docHistory?.canRedo ?? false });
+  }
+
+  /**
+   * A pointer already holds the history. Say so and refuse.
+   *
+   * THE SEAM, not a fourteenth per-keymap-arm guard. `writeCamera` has carried
+   * this shape since the camera lane landed; promoting it to `edit`, `undo` and
+   * `redo` is what makes every OTHER caller safe at once, because all of them
+   * route through one of those three.
+   *
+   * Reachable from the stage's own key relay: a keystroke during a drag is
+   * ordinary (⌘Z, Delete, an arrow step), and without this it threw out of the
+   * stage's keydown handler, across the bridge, mid-gesture.
+   */
+  function historyBusy(): boolean {
+    if (gesture === null && framing === null) return false;
+    set({ error: HISTORY_BUSY });
+    return true;
+  }
+
+  /**
+   * Say what an edit refused, WITHOUT overwriting a refusal to run it at all.
+   *
+   * Nine actions follow `store.edit` with their own `set({ error: refusal })`,
+   * and every one of them was wiping `HISTORY_BUSY`: a refused edit never runs
+   * its body, so `refusal` is still the `null` it was initialised to, and the
+   * `set` replaced the message the guard had just written. The keystroke did
+   * nothing and said nothing.
+   *
+   * `ran` comes straight from `edit`'s return, so the two facts cannot drift.
+   */
+  function sayRefusal(ran: boolean, refusal: string | null): void {
+    if (ran) set({ error: refusal });
+  }
+
+  /**
+   * Is there no working pane to aim a view key at? If so, SAY SO.
+   *
+   * Six keys — the numpad presets, ⇧C's fit, the orbit steps and numpad-5's
+   * ortho — all return `true` from `handleKey` (so the browser's own binding is
+   * suppressed) and then did nothing at all in the camera-only layout. That
+   * layout is the INITIAL state, so a fresh session's numpad was dead and
+   * silent, which is the worst version: the author cannot tell a key that is
+   * not bound from one that is refusing.
+   *
+   * They are guarded rather than allowed because with follow armed
+   * `setWorkingView` WRITES the shot camera, and camera-only layout has neither
+   * of follow's indicators on screen — so the key would rewrite and autosave
+   * the camera with nothing to say it had.
+   */
+  function noWorkingPane(): boolean {
+    if (state.stageLayout.mode !== "camera") return false;
+    set({
+      error:
+        `that key aims the working view, and this layout shows the camera only. ` +
+        `Press 1 for the working view or 2 for the split.`,
+    });
+    return true;
+  }
+
+  function scheduleSave(): void {
+    if (saveTimer !== null) clearTimeout(saveTimer);
+    saveTimer = setTimeout(() => {
+      saveTimer = null;
+      void runSave();
+    }, AUTOSAVE_MS);
+  }
+
+  function runSave(): Promise<void> {
+    const name = state.name;
+    const doc = state.doc;
+    if (name === null || doc === null) return Promise.resolve();
+    const gen = generation;
+    set({ saveState: "saving" });
+    // Serialised behind the previous save: two overlapping PUTs would race on
+    // `rev` and the second would 409 against a baseline the first just moved.
+    savePromise = savePromise.then(async () => {
+      if (gen !== generation) return;
+      try {
+        const result = await api.saveShot(name, doc, state.rev);
+        if (gen !== generation) return;
+        set({
+          rev: result.rev,
+          saveState: "saved",
+          // Only clean if nothing landed WHILE the save was in flight.
+          dirty: state.doc !== doc,
+          error: null,
+          emitWarning: result.warning ?? null,
+        });
+        if (state.doc !== doc) scheduleSave();
+      } catch (e) {
+        if (gen !== generation) return;
+        const message = e instanceof Error ? e.message : String(e);
+        set({
+          saveState: "error",
+          error:
+            e instanceof ApiError && e.conflict
+              ? `${message} (your edits are still here — copy anything you need before reloading)`
+              : message,
+        });
+      }
+    });
+    return savePromise;
+  }
+
+  /**
+   * Pull a move onto the frame's and the other layers' edges and centres.
+   *
+   * MOVES ONLY. A resize snapping its handle sounds appealing and is a
+   * different computation (the moving edge is one edge, not the box), and a
+   * tilt has nothing to snap to; doing them badly here would be worse than not
+   * doing them.
+   *
+   * `zoom` IS THE PANE'S OWN, not the camera pane's. `grabAt` returns a move in
+   * the working pane too, and that pane has no zoom — it has an orbit distance,
+   * and its screen scale is the perspective quantity the stage sends at gesture
+   * start. Dividing a SCREEN threshold by a number belonging to a pane that may
+   * not even be on screen is how a working-only drag ends up snapping from 60
+   * design px away, or not at all.
+   *
+   * Named ceiling: the guides come back in DESIGN frame coordinates and the
+   * overlay can only draw them in the camera pane, because an axis-aligned
+   * design line is not an axis-aligned screen line under a free orbit. A
+   * working-only layout therefore snaps at the right distance and draws no
+   * guide; showing them there needs projected segments, not a second threshold.
+   */
+  function snapFor(
+    base: Doc3D,
+    sceneId: string,
+    layerIds: readonly string[],
+    delta: GestureDelta,
+    zoom: number,
+  ): { delta: GestureDelta; guides: SnapGuide[] } {
+    if (delta.kind !== "move") return { delta, guides: [] };
+    const scene = base.scenesById[sceneId];
+    if (scene === undefined) return { delta, guides: [] };
+    // The box lists derive from the scrub BASE and the selection, both fixed
+    // for the whole drag — so they are built once per gesture and cached on
+    // it, not rebuilt per pointermove. `worldBaseTransform` walks the layer's
+    // ancestor chain, and running that for every layer in the scene on every
+    // move was the single biggest per-move cost in this lane.
+    let boxes = gesture?.snap ?? null;
+    if (boxes === null || boxes.forScene !== sceneId) {
+      const selected = new Set(layerIds);
+      const moving: SnapBox[] = [];
+      const others: SnapBox[] = [];
+      for (const layer of Object.values(scene.layersById)) {
+        // WORLD positions, not stored ones. A nested layer's
+        // `transform.position` is local to its parent, so snapping a root
+        // layer's edge against a grouped layer's stored x compares two
+        // different frames and lands the guide nowhere near the thing it
+        // claims to align to. The gesture delta is world-space too (the stage
+        // unprojected a pointer onto a plane), so the whole comparison happens
+        // in one frame.
+        const world = worldBaseTransform(scene, layer.id).position;
+        const box = {
+          position: [world[0], -world[1], -world[2]] as [number, number, number],
+          size: layer.transform.size,
+        };
+        if (selected.has(layer.id)) moving.push(box);
+        else others.push(box);
+      }
+      boxes = { forScene: sceneId, moving, others };
+      if (gesture !== null) gesture.snap = boxes;
+    }
+    const snapped = snapMove(boxes.moving, boxes.others, base.size, delta, SNAP_THRESHOLD_PX / Math.max(zoom, 1e-6));
+    return {
+      delta: { ...delta, dx: snapped.dx, dy: snapped.dy },
+      guides: snapped.guides,
+    };
+  }
+
+  /**
+   * THE ONE SEAM EVERY CAMERA AUTHOR GOES THROUGH.
+   *
+   * `writeFraming` owns the three-way fork (base write / refusal / a move
+   * ending at the playhead) so that a frustum drag, an orbit under follow, an
+   * align and a fit cannot disagree about what animate mode means or about when
+   * a write is invisible. All this adds is where the entry lands: inside the
+   * CAMERA's open scrub for a drag, or its own transaction for a button.
+   *
+   * ── WHICH LANE OWNS THE HISTORY ─────────────────────────────────────────
+   *
+   * Engine allows one scrub at a time, and the two lanes here share one
+   * `History`. So "no camera scrub open" does NOT mean "free to open a
+   * transaction": a layer drag or a timeline block drag holds `gesture` across
+   * a whole pointer hold, and `transaction()` throws while any scrub is live.
+   * ⌥C during a drag, or a wheel dolly under follow during one, used to throw
+   * that out of the stage's own event handler.
+   *
+   * Folding the write into the OTHER lane's scrub is not the fix either:
+   * `capture` always re-derives from ITS base, so a camera write would wipe the
+   * transform in progress until the next pointermove re-captured it. A lane
+   * already open wins, and the camera says so — the same rule
+   * `onFramingGestureStart` states, and the same refusal-over-corruption answer
+   * every other fork in this file gives.
+   */
+  function writeCamera(next: (current: Framing) => Framing): void {
+    const sceneId = state.sceneId;
+    const doc = state.doc;
+    if (sceneId === null || doc === null) return;
+    if (framing === null && gesture !== null) {
+      set({ error: HISTORY_BUSY });
+      return;
+    }
+    const sceneFrame = masterToSceneCached(doc, state.frame)?.sceneFrame ?? 0;
+    let refusal: string | null = null;
+    const apply = (base: Doc3D): Doc3D => {
+      const out = writeFraming(base, sceneId, sceneFrame, base.fps, state.animateMode, next);
+      refusal = out.refusal;
+      return out.doc;
+    };
+    if (framing === null) store.edit(apply);
+    else framing.capture(apply);
+    // Shown, never swallowed: a camera drag that silently did nothing is the
+    // two-truths failure this whole lane refuses by name to avoid.
+    set({ error: refusal });
+  }
+
+  /** Project a working-pane pose onto the framing model and write it. Shared by
+   *  the align button and by follow mode, which differ only in what triggers
+   *  them and whether a scrub happens to be open. */
+  function writeFramingFromView(view: WorkingView): void {
+    const doc = state.doc;
+    if (doc === null) return;
+    // THE DERIVED RIG REPLACED THE POSE THIS PROJECTS. On entering a subtree
+    // the working pane draws an orthographic head-on rig (isolation.ts), so
+    // `state.workingView` is a pose with no reader and no pixels — projecting
+    // it onto the shot camera writes a framing from a viewpoint nobody is
+    // looking at, dirties the document and autosaves it. Refused for BOTH
+    // callers here rather than in each: follow mode, which would do it silently
+    // per gesture, and ⌥C, which is an author asking for it and gets told why.
+    //
+    // RE-KEYED, NOT DELETED, when isolation learned to hand the camera over:
+    // once `isolationOrbit` is true the orbit rig is genuinely drawing the pane
+    // and a framing write is legal again, so the refusal turns off with the
+    // derived rig rather than with the mode.
+    if (state.isolation !== null && !state.isolationOrbit) {
+      set({
+        error:
+          "The working pane is showing this subtree head-on rather than a viewpoint the shot " +
+          "camera could take — orbit the pane to take the camera, or leave isolation (Esc), " +
+          "then align.",
+      });
+      return;
+    }
+    const projected = framingFromWorkingView(view, doc.size, WORKING_FOV_DEG);
+    if (!projected.ok) {
+      set({ error: projected.refusal });
+      return;
+    }
+    // ROLL AND FOCUS ARE KEPT. The working camera cannot express either, so
+    // taking them from the view would zero an authored roll and pull focus to
+    // the canvas every time the author aligned.
+    writeCamera((current) => ({
+      ...current,
+      x: projected.x,
+      y: projected.y,
+      zoom: projected.zoom,
+    }));
+  }
+
+  /**
+   * Give the wheel the bracket it cannot give itself: the first notch opens the
+   * framing scrub, and `WHEEL_IDLE_MS` of silence commits it.
+   *
+   * Only when nothing else holds the history. A wheel turned mid-drag folds
+   * into that drag's scrub instead, which is one undo entry either way and does
+   * not leave this store closing a scrub it never opened.
+   */
+  function armWheelFraming(): void {
+    if (wheelFraming !== null) {
+      clearTimeout(wheelFraming);
+    } else {
+      if (gesture !== null || framing !== null) return;
+      stageHandlers.onFramingGestureStart();
+      if (framing === null) return; // no document open: nothing was started
+    }
+    wheelFraming = setTimeout(closeWheelFraming, WHEEL_IDLE_MS);
+  }
+
+  /** Close a wheel's scrub NOW. Called by the idle timer, and by every other
+   *  lane before it takes the history — engine allows exactly one scrub, and a
+   *  wheel's is the only one open while no pointer is down. */
+  function closeWheelFraming(): void {
+    if (wheelFraming === null) return;
+    clearTimeout(wheelFraming);
+    wheelFraming = null;
+    stageHandlers.onFramingGestureEnd(true);
+  }
+
+  // ── the insertion lane ────────────────────────────────────────────────────
+  //
+  // Two shapes, and the split is the ASSET. Without one the layer is built from
+  // the open document and inserted; with one, the asset registration and the
+  // insert have to be the same transaction — an undo that removed the layer and
+  // left an orphan asset behind, or removed the asset and left a layer pointing
+  // at nothing, is a document `validateShotDoc` refuses to save, produced BY
+  // THE UNDO BUTTON. Same reasoning `importAudio` carries.
+
+  /**
+   * Where the playhead is and how long its scene is: the two numbers every
+   * insert needs to land in TIME. Null when nothing can be inserted.
+   *
+   * BOTH come from the SAME `masterToScene` call, and neither from
+   * `state.sceneId`. The pin and the playhead can diverge (see `focusScene`),
+   * and a scene taken from one with a frame taken from the other writes a
+   * lifetime measured on a foreign clock into a scene the stage is not showing
+   * — the layer appears nowhere, and `onHistoryChange` snapping the pin back to
+   * the playhead's scene then makes the follow-up `select` filter it out too.
+   * The playhead is what the stage renders and what every other create in this
+   * chrome lands on, so it is the one source.
+   *
+   * `state.sceneId` is the fallback for a playhead that is in no scene at all
+   * (a zero-length tail), where landing in the pinned scene beats refusing.
+   */
+  function insertContext(): {
+    sceneId: string;
+    scene: Scene3D;
+    ctx: InsertContext;
+    parent?: string;
+  } | null {
+    const doc = state.doc;
+    if (doc === null) return null;
+    const at = masterToSceneCached(doc, state.frame);
+    const sceneId = at?.sceneId ?? state.sceneId;
+    const scene = sceneId === null ? undefined : doc.scenesById[sceneId];
+    if (sceneId === null || scene === undefined) return null;
+    // ── WHAT IS DRAWN INSIDE A CARD BELONGS TO THE CARD ──────────────────
+    //
+    // Everything outside the isolated subtree is dimmed and unpickable, so an
+    // insert that landed beside it appeared to go nowhere: it drew at the
+    // scene root, dimmed, un-clickable, with the outline showing nothing new.
+    //
+    // ONLY WHEN THE ISOLATED LAYER CAN HOLD CHILDREN. `enterIsolation`
+    // validates that the layer exists and nothing else, so a plain rect can be
+    // the subject — and handing one to `addLayer` as a parent throws out of
+    // `withChildren`. Falling back to a root insert is the honest answer: the
+    // author gets the layer, in the scene, where the outline can find it.
+    const isolated = state.isolation === null ? undefined : scene.layersById[state.isolation];
+    const parent = isolated !== undefined && canHoldChildren(isolated) ? isolated.id : undefined;
+    return {
+      sceneId,
+      scene,
+      ctx: {
+        sceneFrame: at?.sceneId === sceneId ? at.sceneFrame : 0,
+        durationFrames: scene.durationFrames,
+      },
+      ...(parent === undefined ? {} : { parent }),
+    };
+  }
+
+  /**
+   * Insert a built layer, and select it.
+   *
+   * The id is MINTED HERE rather than read back out of the new document:
+   * `addLayer` derives it from the same `usedIdsOf`, and knowing it up front is
+   * what lets the insert select what it just made without diffing two layer
+   * maps to find out which one is new.
+   */
+  function insertLayer(layer: NewLayer3D): void {
+    const at = insertContext();
+    const doc = state.doc;
+    if (at === null || doc === null) return;
+    const id = freshId(usedIdsOf(doc), LAYER_ID_PREFIX, layer.kind);
+    store.edit((base) => addLayerAt(base, at, { ...layer, id }));
+    select([id]);
+  }
+
+  /**
+   * `addLayer`, with the isolation parent and the rebase applied.
+   *
+   * ONE FUNCTION, because there are TWO insert paths and only one of them had
+   * this: `insertAssetLayer` calls the same `insertContext()` and used to
+   * discard its `parent`, so inside a subtree a drawn rect became a child while
+   * an imported image or `.glb` landed at the scene root — dimmed, unpickable,
+   * and invisible in an outline scoped to the card.
+   */
+  function addLayerAt(
+    base: Doc3D,
+    at: { sceneId: string; parent?: string },
+    layer: NewLayer3D & { id: string },
+  ): Doc3D {
+    return addLayer(base, {
+      sceneId: at.sceneId,
+      layer: { ...layer, transform: rebasedForParent(base, at.sceneId, at.parent, layer.transform) },
+      ...(at.parent === undefined ? {} : { parent: at.parent }),
+    });
+  }
+
+  /**
+   * A transform authored in SCENE coordinates, expressed in a parent's frame.
+   *
+   * Every builder in the insert lane works in design coordinates: the draw
+   * tools hand back a box in the scene's own space, and so does the device
+   * preset. But `transform.position` is local to the layer's PARENT, so
+   * spreading `parent` without this puts the drawn rectangle at the group's own
+   * offset and roll — visibly somewhere the author did not draw it, and further
+   * off the deeper or the more rotated the group is.
+   *
+   * Identity at the root, which is why every existing insert is byte-identical.
+   */
+  function rebasedForParent(
+    doc: Doc3D,
+    sceneId: string,
+    parent: string | undefined,
+    transform: NewLayer3D["transform"],
+  ): NewLayer3D["transform"] {
+    const scene = doc.scenesById[sceneId];
+    if (parent === undefined || scene === undefined) return transform;
+    // `toLocal` answers position / tilt / roll only: size and opacity are
+    // untouched by nesting, so the caller's own survive the spread.
+    return { ...transform, ...toLocal(parentBaseTransform(scene, parent), rigidOf(transform)) };
+  }
+
+  /** …and the same thing for a layer that names an uploaded asset, in ONE
+   *  transaction. The asset is deduped by PATH: the store is content-addressed,
+   *  so a re-import of identical bytes must not mint a second `ShotAsset` the
+   *  exporter would then fetch twice. */
+  function insertAssetLayer(
+    uploaded: api.UploadedAsset,
+    filename: string,
+    kind: ShotAssetKind,
+    build: (assetId: string, ctx: InsertContext) => NewLayer3D | null,
+  ): void {
+    const at = insertContext();
+    if (at === null) return;
+    let created: string | null = null;
+    store.edit((base) => {
+      const used = usedIdsOf(base);
+      const existing = Object.values(base.assets).find((a) => a.path === uploaded.path);
+      const asset = existing ?? {
+        id: freshId(used, ASSET_ID_PREFIX, slug(filename.replace(/\.[^.]*$/, ""))),
+        path: uploaded.path,
+        hash: uploaded.hash,
+        kind,
+      };
+      const layer = build(asset.id, at.ctx);
+      if (layer === null) return base;
+      used.add(asset.id);
+      created = freshId(used, LAYER_ID_PREFIX, layer.kind);
+      const withAsset =
+        existing === undefined ? { ...base, assets: { ...base.assets, [asset.id]: asset } } : base;
+      // Through the SAME seam `insertLayer` uses, so an imported image and a
+      // drawn rect land in the same place inside a subtree.
+      return addLayerAt(withAsset, at, { ...layer, id: created });
+    });
+    if (created !== null) select([created]);
+  }
+
+  /** One instance block edited in place, as one transaction. Layer-addressed
+   *  rather than selection-addressed: an instance's props belong to ONE
+   *  component's contract, so fanning a prop write across a mixed selection
+   *  would write keys the other layers' components never had. */
+  function patchInstance(
+    layerId: string,
+    next: (inst: InstanceLayer3D["instance"]) => InstanceLayer3D["instance"],
+  ): void {
+    const sceneId = state.sceneId;
+    if (sceneId === null) return;
+    store.edit((doc) => {
+      const scene = doc.scenesById[sceneId];
+      const layer = scene?.layersById[layerId];
+      if (scene === undefined || layer === undefined || layer.kind !== "instance") return doc;
+      const instance = next(layer.instance);
+      if (instance === layer.instance) return doc;
+      return {
+        ...doc,
+        scenesById: {
+          ...doc.scenesById,
+          [sceneId]: {
+            ...scene,
+            layersById: { ...scene.layersById, [layerId]: { ...layer, instance } },
+          },
+        },
+      };
+    });
+  }
+
+  /**
+   * The contract binding recorded on an instance layer, from a registry detail.
+   *
+   * `instanceContractRefFor` owns the import-vs-snapshot decision, and it is
+   * the SAME function the 2D lane's embeds go through — a chrome-side
+   * re-derivation of that rule is what emitted unresolvable imports for
+   * builtins in that lane.
+   */
+  function bindingFor(detail: api.ComponentDetail): {
+    contractHash: string;
+    contract: InstanceContractRef;
+  } {
+    return {
+      contractHash: detail.contract.contractHash,
+      contract: instanceContractRefFor({
+        availability: detail.contractAvailability ?? "inferred",
+        contract: detail.contract,
+      }),
+    };
+  }
+
+  /**
+   * Upload a file, refuse it if it is none of the kinds the caller takes, and
+   * report WHICH one it turned out to be.
+   *
+   * A LIST rather than one kind, because the Frame picker takes either media
+   * kind and the caller has to fork on the answer. The kind is the SERVER's:
+   * it comes off the stored filename's extension, which is the same answer the
+   * save gate and the exporter will get, and a browser-side MIME guess that
+   * disagreed would mint a layer kind the document cannot back.
+   *
+   * THE GENERATION FENCE, for the reason every async load in this file carries
+   * one: the author can switch documents while an upload is in flight, and a
+   * layer written into whichever shot happens to be open when it lands is a
+   * layer in the wrong film. The bytes are still in the store, so re-importing
+   * is the whole recovery.
+   */
+  async function uploadOfKind<K extends ShotAssetKind>(
+    file: File,
+    kinds: readonly K[],
+    gen: number,
+  ): Promise<{ uploaded: api.UploadedAsset; kind: K }> {
+    const uploaded = await api.uploadAsset(file);
+    if (gen !== generation) throw new Error(`${file.name} was imported into a scene that has closed`);
+    const kind = uploaded.kind;
+    // The wire's `kind` is a plain string — the server's extension map knows
+    // kinds this union does not (hdri) — so the membership test IS the
+    // narrowing, and the cast below is exactly what it proved.
+    if (kind === undefined || !(kinds as readonly string[]).includes(kind)) {
+      throw new Error(
+        `${file.name} is not ${kindsPhrase(kinds)} ` +
+          `(the store saw it as ${uploaded.kind ?? "an unknown kind"})`,
+      );
+    }
+    return { uploaded, kind: kind as K };
+  }
+
+  /** A draw gesture that needs no asset. Null from the builder — a pen with
+   *  nothing in it — inserts nothing rather than a layer the author would have
+   *  to find and delete. */
+  function insertDrawn(tool: InsertTool, points: readonly DrawPoint[]): void {
+    const at = insertContext();
+    if (at === null) return;
+    const layer = layerFromDraw(tool, points, at.ctx);
+    if (layer !== null) insertLayer(layer);
+    // BACK TO SELECT, whether or not anything landed. The armed tool is a mode,
+    // and leaving the author in it after a gesture that produced nothing is how
+    // the next click draws a second thing they did not ask for.
+    store.setTool("select");
+  }
+
+  /**
+   * The container a click on this layer should select: its outermost ancestor,
+   * stopping at the ISOLATION boundary.
+   *
+   * The boundary is what makes entering a subtree mean anything. Without it,
+   * clicking a child inside an isolated card would walk all the way back up to
+   * the card the author had just entered, and going in would change nothing.
+   */
+  function outermost(id: string): string {
+    const sceneId = state.sceneId;
+    const scene = sceneId === null ? undefined : state.doc?.scenesById[sceneId];
+    return scene === undefined ? id : outermostIn(scene, id, state.isolation);
+  }
+
+  const stageHandlers: ShotBridgeHandlers = {
+    onReady(info: ShotStageInfo) {
+      set({ stageInfo: info, stageError: null });
+      // The stage just (re)mounted — a Vite reload remints it — so re-push
+      // everything it cannot know. Order matters: doc, then frame, then
+      // selection, because the later two address into the former.
+      if (state.doc !== null) {
+        pushDocToStage(state.doc);
+        bridge?.seek(state.frame);
+        bridge?.setSelection(state.selection);
+      }
+      pushWorkspaceToStage();
+    },
+    onError(message: string) {
+      set({ stageError: message });
+    },
+    onPick(hits: readonly string[], modifiers: PickModifiers, pane: StagePane) {
+      // A pick IS an activation, so it lands here as well as through
+      // `onActivePane`. Both routes exist because a wheel or an orbit activates
+      // a pane without changing the selection, and a marquee changes the
+      // selection from a pointerdown that already reported its pane.
+      set({ activePane: pane });
+      // THE CHROME OWNS THE POLICY (see bridgeTypes). Plain click takes the
+      // front-most hit; shift extends; meta walks BEHIND the current selection,
+      // which is the whole reason the stage sends the ordered list.
+      if (hits.length === 0) {
+        if (modifiers.shift) return;
+        // ── CLICKING AWAY LEAVES THE SUBTREE ────────────────────────────
+        //
+        // Isolation scopes picking to the subtree, so everything outside it
+        // already answers an empty hit list — which means "click outside to
+        // leave" needs no second gesture, only this branch. `StageTools` has
+        // claimed for a while that it already worked; now it does.
+        //
+        // NOT FOR AN EMPTY MARQUEE. A rubber band drawn inside a card that
+        // caught nothing is not a request to leave the card, and routing both
+        // through this handler is why the flag exists.
+        if (state.isolation !== null && modifiers.marquee !== true) {
+          store.exitIsolation();
+          // `exitIsolation` selects the boundary layer so the author can see
+          // where they came out of; an explicit click on nothing means nothing
+          // selected, so the clear has to follow it.
+          select([]);
+          return;
+        }
+        select([]);
+        return;
+      }
+      // ── A MARQUEE IS A SET, NOT A HIT STACK ─────────────────────────────
+      //
+      // Every enclosed layer is selected, resolved through the same
+      // `outermost` walk a click uses so box-selecting across a group's
+      // children selects the group — which is what Figma does and what the
+      // outline expects. `select` dedupes and document-orders, so the
+      // many-to-one collapse comes out right for free.
+      //
+      // SHIFT APPENDS rather than toggling: reusing the click path's toggle
+      // would DESELECT anything the box happened to re-touch, which is the
+      // opposite of what dragging a bigger box means.
+      if (modifiers.marquee === true) {
+        const inBox = hits.map(outermost);
+        select(modifiers.shift ? [...state.selection, ...inBox] : inBox);
+        return;
+      }
+      // A CLICK SELECTS THE OUTERMOST CONTAINER, not the leaf under the
+      // cursor. That is what makes a group a thing rather than a label: click a
+      // card, get the card; go inside it (Enter, or double-click) and the same
+      // click gets the child. Meta-click still walks the raw hit list, which is
+      // the escape hatch for reaching a leaf without entering anything.
+      const front = outermost(hits[0]!);
+      if (modifiers.meta) {
+        const at = hits.indexOf(state.selection[0] ?? "");
+        select([hits[(at + 1) % hits.length]!]);
+        return;
+      }
+      if (modifiers.shift) {
+        select(
+          state.selection.includes(front)
+            ? state.selection.filter((id) => id !== front)
+            : [...state.selection, front],
+        );
+        return;
+      }
+      select([front]);
+    },
+    onEnterLayer(hits: readonly string[], pane: StagePane) {
+      set({ activePane: pane });
+      // The same layer a single click would have selected — its outermost
+      // container, stopping at the boundary the author is already inside. So
+      // click-then-double-click walks INTO the thing that was highlighted,
+      // rather than jumping to whichever leaf happened to be under the pixel.
+      const first = hits[0];
+      if (first === undefined) return;
+      store.enterIsolation(outermost(first));
+    },
+    onIsolationOrbitTaken() {
+      // The author navigated the working pane while the derived head-on rig
+      // was drawing it. From here the ordinary orbit rig owns the pane, so the
+      // framing refusal turns off and the nav gizmo becomes meaningful again.
+      // Pushed straight back down: the stage reads the bit to pick a camera.
+      if (state.isolation === null || state.isolationOrbit) return;
+      set({ isolationOrbit: true });
+      bridge?.setIsolationOrbit(true);
+    },
+    onViewChange(view: ShotView) {
+      set({ view });
+    },
+    onWorkingViewChange(workingView: WorkingView, origin: WorkingViewOrigin = "gesture") {
+      // THE MIRROR IS TRAILING-THROTTLED while follow is off. This fires per
+      // pointermove of every orbit/pan/dolly, no chrome component subscribes
+      // to `workingView` live (it exists for persistence and for the keyboard
+      // zoom's read), and every `set` is a full listener sweep — a few hundred
+      // selector evaluations with the inspector open, buying zero renders.
+      // Under follow the write-through below still runs per event, because the
+      // camera write is the payload there, not the mirror.
+      if (origin === "fit" || !state.cameraFollowsView) {
+        pendingWorkingView = workingView;
+        workingViewMirror ??= setTimeout(() => {
+          workingViewMirror = null;
+          if (pendingWorkingView !== null) set({ workingView: pendingWorkingView });
+          pendingWorkingView = null;
+        }, WORKING_VIEW_MIRROR_MS);
+        if (origin === "fit") return;
+      } else {
+        set({ workingView });
+      }
+      // A FIT is the stage mirroring a view it derived ITSELF — on a document
+      // open, or on an iframe reload. Nobody moved anything, so following it
+      // would rewrite the camera of every shot merely opened while follow
+      // happens to be armed (it is a workspace pref and crosses a switch),
+      // dirty it, and autosave it with no author input.
+      if (!state.cameraFollowsView) return;
+      // FOLLOW MODE. The view change IS the payload — there is no delta to send
+      // — so the write happens here, inside whatever scrub brackets the
+      // gesture. An orbit or a pan is bracketed by the stage's pointer lane; a
+      // wheel has no release, so it gets one from silence instead.
+      if (origin === "wheel") armWheelFraming();
+      writeFramingFromView(workingView);
+    },
+    onActivePane(activePane: StagePane) {
+      // …and CLOSE the stage menu. This is the seam every stage press and
+      // wheel already crosses, and it has to be the one: the iframe is a
+      // different document, so a pointerdown inside it never reaches the
+      // chrome window's own outside-click listener. For a right press the
+      // order is this handler then `onContextMenu`, and React batches both, so
+      // the effect sees the newly opened menu rather than the cleared one.
+      if (state.stageMenu !== null) set({ activePane, stageMenu: null });
+      else set({ activePane });
+    },
+    onDraw(tool, points) {
+      if (state.doc === null || state.sceneId === null) return;
+      if (tool === "image") {
+        // THE BOX WAITS FOR THE FILE. A file dialog only opens from a click on
+        // a real `<input>`, which this is not, so the geometry parks in state
+        // and the toolbar's hidden input finishes the job. Copied out because
+        // the array belongs to the stage's own gesture, which is over.
+        set({ imagePick: points.map((p): DrawPoint => [p[0], p[1]]) });
+        // …and the tool is spent either way: the pick can be cancelled, and an
+        // author left holding the image tool would draw a second box trying to
+        // work out why nothing appeared.
+        store.setTool("select");
+        return;
+      }
+      insertDrawn(tool, points);
+    },
+
+    /** The pen's commit. Same shape as `insertDrawn` — build, insert if the
+     *  builder answered, and disarm either way — but through `penLayer`,
+     *  because a path with handles is not something `layerFromDraw`'s bare
+     *  points can describe. */
+    onPenCommit(data) {
+      const at = insertContext();
+      if (at === null) return;
+      const layer = penLayer(data, at.ctx);
+      if (layer !== null) insertLayer(layer);
+      store.setTool("select");
+    },
+
+    onKey(event, editing) {
+      // Straight into the SAME resolver the chrome's own listener uses, so a
+      // shortcut cannot mean one thing with the canvas focused and another with
+      // a panel focused.
+      return store.handleKey({ ...event, target: editing ? EDITING_TARGET : null });
+    },
+
+    // ── the gesture lane ────────────────────────────────────────────────────
+    //
+    // ONE DRAG IS ONE UNDO ENTRY, and that is `scrub()` doing the work rather
+    // than this code coalescing. Every `onGesture` re-derives from the scrub's
+    // BASE — the document as it was at press — so a coalesced pointermove, a
+    // snap that bites and un-bites, or a refusal partway through cannot make
+    // the drag drift. Escape is `discard()`, which restores the base exactly
+    // because it never left.
+    onGestureStart(kind, layerIds, screenScale) {
+      if (docHistory === null || state.doc === null) return false;
+      closeWheelFraming();
+      // ONE SCRUB AT A TIME, stated rather than relied on — the same guard
+      // `onFramingGestureStart` carries, and for the same reason: a lost
+      // pointerup must not turn the next press into an exception thrown across
+      // the bridge from inside the stage's own pointer handler.
+      //
+      // THE ANSWER IS RETURNED, which the modal lane needs. A pointer drag can
+      // afford to fail silently — the author releases and tries again — but a
+      // MODAL arms and stays armed, so one that opened over somebody else's
+      // scrub would drive that scrub with its own deltas and commit it.
+      if (gesture !== null || framing !== null) return false;
+      gesture = {
+        kind,
+        layerIds: [...layerIds],
+        scrub: docHistory.scrub(),
+        screenScale: screenScale ?? null,
+        snap: null,
+      };
+      set({ error: null });
+      return true;
+    },
+    onGesture(delta) {
+      const active = gesture;
+      if (active === null || state.sceneId === null || state.doc === null) return;
+      const sceneId = state.sceneId;
+      const sceneFrame = masterToSceneCached(state.doc, state.frame)?.sceneFrame ?? 0;
+      let refusals: string[] = [];
+      let guides: SnapGuide[] = [];
+      active.scrub.capture((base) => {
+        // ── THE ONE FORK ANIMATE MODE OWNS ────────────────────────────────
+        //
+        // ON: the drag authors a BLOCK ending at the playhead. OFF: it writes
+        // the layer's own values. Both are legitimate and both are one undo
+        // entry; what must never happen is the author not knowing which they
+        // got, which is why the mode is a deliberate ⇧A and never a side effect
+        // of looking at a panel.
+        //
+        // Snapping is deliberately NOT applied in animate mode: the author is
+        // authoring a MOTION, and pulling its end onto another layer's edge
+        // would quantise the animation to whatever happened to be nearby.
+        if (state.animateMode) {
+          const out = animateGesture(base, sceneId, active.layerIds, delta, sceneFrame, base.fps);
+          refusals = out.refusals;
+          guides = [];
+          return out.doc;
+        }
+        const snapped = snapFor(
+          base,
+          sceneId,
+          active.layerIds,
+          delta,
+          // The pane's own screen scale when the stage sent one. The camera
+          // pane's zoom is the fallback, which is what a caller with no pane —
+          // a test, or the timeline dock — is asking for anyway.
+          active.screenScale ?? state.view.zoom,
+        );
+        guides = snapped.guides;
+        const out = applyGesture(base, sceneId, active.layerIds, snapped.delta, sceneFrame, base.fps);
+        refusals = out.refusals;
+        return out.doc;
+      });
+      bridge?.setSnapGuides(guides);
+      // ── A BOX THAT IS BOOKKEEPING, NOT PICTURE ────────────────────────
+      //
+      // A group's or a cloner's `size` bounds children that carry their own, so
+      // the SIZE half of a resize is a document write that draws nothing. The
+      // position half is not: `resizeTransform` shifts the box's centre by half
+      // of what the edge moved, and for a container that translates the whole
+      // subtree. So this is a word and not a refusal, and it says which half.
+      //
+      // RESIZE ONLY. A `scale` about a pivot is mostly the translation — the
+      // author asked to move the arrangement apart, which is exactly what a
+      // container does — and calling that a no-op would be the lie.
+      //
+      // `sizeChangesPixels` and NOT `layerDraws`: a `component` draws nothing
+      // and is not pickable, but its box feeds `instanceScale`, so resizing an
+      // instance really does resize the picture.
+      const layers = state.doc.scenesById[sceneId]?.layersById ?? {};
+      const inert =
+        delta.kind === "resize"
+          ? active.layerIds
+              .map((id) => layers[id])
+              .find((l) => l !== undefined && !sizeChangesPixels(l))
+          : undefined;
+      set({
+        // The layer-level refusals come first: one of them is a layer that did
+        // not move at all, which outranks one that moved without showing it.
+        error:
+          refusals[0] ??
+          (inert === undefined
+            ? null
+            : `"${inert.label}" is a ${inert.kind}, so its box only bounds its children. ` +
+              `Dragging the handle moves it, but growing the box draws nothing.`),
+      });
+    },
+    onGestureEnd(commit) {
+      const active = gesture;
+      gesture = null;
+      if (active === null) return;
+      bridge?.setSnapGuides([]);
+      if (commit) active.scrub.commit();
+      else active.scrub.discard();
+      syncHistoryFlags();
+    },
+
+    onFramingGestureStart() {
+      if (docHistory === null || state.doc === null) return false;
+      closeWheelFraming();
+      // One scrub at a time. A lane already open wins rather than throwing
+      // across the bridge from inside the stage's own pointer handler.
+      if (gesture !== null || framing !== null) return false;
+      framing = docHistory.scrub();
+      set({ error: null });
+      return true;
+    },
+    onFramingGesture(delta: FramingDelta) {
+      if (framing === null) return;
+      writeCamera((current) => applyFramingDelta(current, delta));
+    },
+    onFramingGestureEnd(commit) {
+      const active = framing;
+      framing = null;
+      if (active === null) return;
+      // `commit(): false` is Escape, and it restores the pre-drag framing
+      // EXACTLY because every capture re-derived from the base — the document
+      // never left it.
+      if (commit) active.commit();
+      else active.discard();
+      syncHistoryFlags();
+    },
+
+    // ── THE KEY-LIGHT ARM ─────────────────────────────────────────────────
+    //
+    // The same three-call shape as the two lanes above, for the same reasons: a
+    // scrub opened at the travel gate, every emit re-derived from its base, one
+    // undo entry per drag, and Escape restoring exactly because the document
+    // never left that base.
+    //
+    // It is not a light. `mesh.shading.keyDir` is a shader uniform naming a
+    // fake key direction; this lane has no lights and is not getting any.
+    onKeyLightStart(layerId: string) {
+      if (docHistory === null || state.doc === null) return false;
+      closeWheelFraming();
+      if (gesture !== null || framing !== null || keyLight !== null) return false;
+      keyLight = { layerId, scrub: docHistory.scrub() };
+      set({ error: null });
+      return true;
+    },
+    onKeyLight(dir) {
+      const active = keyLight;
+      if (active === null || state.sceneId === null) return;
+      const sceneId = state.sceneId;
+      // Non-finite components would reach `keyU.normalize()` as a NaN vector
+      // and blank the model, so they are dropped rather than written. The
+      // gizmo cannot produce them, which is exactly why the guard is here and
+      // not there: this is the boundary, and a boundary checks.
+      if (!dir.every((n) => Number.isFinite(n))) return;
+      active.scrub.capture((base) => {
+        const scene = base.scenesById[sceneId];
+        const layer = scene?.layersById[active.layerId];
+        if (scene === undefined || layer === undefined || layer.kind !== "mesh") return base;
+        const prior = layer.mesh.shading;
+        return {
+          ...base,
+          scenesById: {
+            ...base.scenesById,
+            [sceneId]: {
+              ...scene,
+              layersById: {
+                ...scene.layersById,
+                [active.layerId]: {
+                  ...layer,
+                  mesh: {
+                    ...layer.mesh,
+                    // The prior toon fields are carried, not replaced: dragging
+                    // the arm must not silently reset the band count or the rim
+                    // the author already set.
+                    shading: {
+                      ...(prior?.mode === "toon" ? prior : {}),
+                      mode: "toon",
+                      keyDir: [dir[0], dir[1], dir[2]],
+                    },
+                  },
+                },
+              },
+            },
+          },
+        };
+      });
+    },
+    onKeyLightEnd(commit) {
+      const active = keyLight;
+      keyLight = null;
+      if (active === null) return;
+      if (commit) active.scrub.commit();
+      else active.scrub.discard();
+      syncHistoryFlags();
+    },
+
+    onContextMenu(hits, pane, at) {
+      set({ activePane: pane });
+      // EMPTY SPACE OPENS NOTHING, and deselects nothing. There is no paste
+      // verb and no scene-level entry in this menu, so a menu there would be a
+      // list of things that cannot act — and a right-click is a question about
+      // something, not an edit.
+      const first = hits[0];
+      if (first === undefined) return;
+      // The plain-click policy, deliberately reused rather than restated: the
+      // outermost container, unless it is already part of the selection, in
+      // which case the whole selection stands and the menu acts on all of it.
+      const front = outermost(first);
+      if (!state.selection.includes(front)) select([front]);
+      // A FRESH OBJECT EVERY TIME. `StageMenu` opens from this field's
+      // identity, so a second right-click at the same point on the same layer
+      // has to look different or the menu would open once and never again.
+      set({ stageMenu: { at: { x: at.x, y: at.y }, hits: [...hits], pane } });
+    },
+    onMeshStats(layerId, triangles) {
+      const current = state.meshTriangles;
+      if (triangles === null) {
+        if (!(layerId in current)) return;
+        const next = { ...current };
+        delete next[layerId];
+        set({ meshTriangles: next });
+        return;
+      }
+      if (current[layerId] === triangles) return;
+      set({ meshTriangles: { ...current, [layerId]: triangles } });
+    },
+  };
+
+  function select(ids: readonly string[]): void {
+    // Deduped and in DOCUMENT order, so every consumer — the inspector's
+    // fan-out, the layers panel, a multi-edit transaction — sees one canonical
+    // ordering and none of them has to sort.
+    //
+    // ── WHICH HOME THE IDS ARE ORDERED AGAINST, AND WHY BOTH ─────────────
+    //
+    // Through `homeOf` and the CONTAINER, never `scenesById[sceneId]` alone:
+    // inside a component definition (`editingDef`) the clicked ids live in
+    // the definition's own `layersById`, and ordering against the scene's map
+    // filtered every one of them out — clicking a row inside a definition
+    // selected nothing, silently.
+    //
+    // But the container alone is the SAME BUG POINTING THE OTHER WAY. Half
+    // this chrome is scene-scoped whatever the outline shows (`layerContainer`
+    // and `insertContext` both say so): `placeComponent` puts an instance in
+    // the SCENE and selects it, an insert draws into the scene, and every
+    // stage pick reports scene ids because the stage is never told about
+    // `editingDef` at all. With a definition open, ordering those against the
+    // definition dropped every one and cleared the selection instead.
+    //
+    // So: order against the container, then take anything left over from the
+    // scene — and LEAVE THE DEFINITION when that happens. An id that lives in
+    // the scene means the caller addressed the scene, and the container-scoped
+    // verbs (`toggleFlag`, `renameLayer`, `groupSelection`) must address the
+    // home the selection actually lives in or they no-op against the wrong
+    // one. Ids in neither are still dropped: that is how a stale id from a
+    // deleted layer stops here rather than in a panel.
+    const container = layerContainer();
+    const doc = state.doc;
+    const home = doc !== null && container !== null ? homeOf(doc, container) : null;
+    const sceneHome =
+      doc !== null && state.sceneId !== null && container !== state.sceneId
+        ? homeOf(doc, state.sceneId)
+        : null;
+    const wanted = new Set(ids);
+    const orderById = new Map<string, number>();
+    for (const l of Object.values(home?.layersById ?? {})) {
+      if (wanted.has(l.id)) orderById.set(l.id, l.order);
+    }
+    let leftDefinition = false;
+    if (orderById.size < wanted.size && sceneHome !== null) {
+      for (const l of Object.values(sceneHome.layersById)) {
+        if (!wanted.has(l.id) || orderById.has(l.id)) continue;
+        orderById.set(l.id, l.order);
+        leftDefinition = true;
+      }
+    }
+    const ordered =
+      home === null && sceneHome === null
+        ? [...wanted]
+        : [...orderById.entries()].sort((a, b) => a[1] - b[1]).map(([id]) => id);
+    // Above the early return, like the two focus clears below: the ids can be
+    // unchanged (re-selecting what was already selected) while the container
+    // still has to follow them out of the definition.
+    if (leftDefinition) set({ editingDef: null });
+    // A FOCUS THE NEW SELECTION DOES NOT OWN GOES FIRST, above the early return.
+    // The camera row focuses a shot WITHOUT touching the layer selection
+    // (BlockRow skips `select` for CAMERA_ROW_ID, and ⇧C focuses a shot outright),
+    // so "click the layer I already had selected" is the ordinary way back — and
+    // it is exactly the call whose ids are unchanged. Leaving the focus behind
+    // strands the inspector on a subject the author navigated away from, and
+    // `deleteSelection` consults the same field first, so Delete would remove the
+    // shot rather than the layer just clicked.
+    //
+    // The `includes` is load-bearing, not caution: LifespanRow's `pick()` fires on
+    // every pointerdown of a lifespan drag, so an unconditional clear would drop
+    // the author's focused block the instant they touched its own layer's bar.
+    if (state.selectedBlock !== null && !ordered.includes(state.selectedBlock.layerId)) {
+      set({ selectedBlock: null });
+    }
+    // A MARKER IS ALWAYS DROPPED, unconditionally, and above the early return
+    // with it. There is no "the marker belongs to this layer" test to make —
+    // markers are document-level — so the rule is simply that clicking a layer
+    // makes the layer the subject, which is what stops Delete from removing a
+    // beat the author had stopped looking at.
+    if (state.selectedMarker !== null) set({ selectedMarker: null });
+    if (sameIds(ordered, state.selection)) return;
+    // A block belongs to a layer, so changing the layer selection drops the
+    // focused block rather than leaving the dock pointing at a row the author
+    // has navigated away from.
+    set({ selection: ordered, selectedBlock: null });
+    bridge?.setSelection(ordered);
+  }
+
+  /**
+   * Put the open document's NAME in the URL, and nothing else.
+   *
+   * That is the only thing boot reads back, so it is the only thing worth
+   * writing: a reload lands on the document the author was in, at frame 0.
+   * The playhead is deliberately not mirrored — `seek` calls no `replaceState`
+   * at all, and per-frame history writes (~30/s) trip Safari's rate limit
+   * (SecurityError past ~100 calls/30s).
+   */
+  function mirrorUrl(): void {
+    if (typeof window === "undefined") return;
+    const url = new URL(window.location.href);
+    if (state.name === null) url.searchParams.delete("shot");
+    else url.searchParams.set("shot", state.name);
+    window.history.replaceState(null, "", url);
+  }
+
+  async function loadInto(name: string, gen: number): Promise<void> {
+    const loaded = await api.loadShot(name);
+    if (gen !== generation) return;
+    // ── AN OPEN GESTURE DIES WITH THE HISTORY IT WAS TAKEN AGAINST ───────
+    //
+    // `closeShot` has always discarded these; a RELOAD needs it just as much
+    // and had no such line. The document id does not change when the same
+    // shot is re-read (an external write adopted through
+    // `adoptExternalChange`), so nothing downstream notices the swap either:
+    // the stage's own mid-gesture guards key on `doc.id`. Left open, the next
+    // capture runs against the DEAD history — whose `onHistoryChange` is
+    // still subscribed — and republishes the pre-reload document over the one
+    // just loaded, then autosaves it with the fresh rev. A pointer drag makes
+    // that window milliseconds wide; a modal transform holds it open for as
+    // long as the author leaves the key pressed.
+    gesture?.scrub.discard();
+    gesture = null;
+    framing?.discard();
+    framing = null;
+    if (wheelFraming !== null) {
+      clearTimeout(wheelFraming);
+      wheelFraming = null;
+    }
+    docHistory = createHistory<Doc3D>(loaded.doc);
+    docHistory.subscribe(onHistoryChange);
+    const frame = 0;
+    set({
+      name: loaded.name,
+      doc: loaded.doc,
+      rev: loaded.rev,
+      frame,
+      sceneId: sceneAt(loaded.doc, frame),
+      ...CLEARED_SELECTION,
+      playing: false,
+      dirty: false,
+      saveState: "idle",
+      error: null,
+      emitWarning: null,
+      canUndo: false,
+      canRedo: false,
+    });
+    mirrorUrl();
+    pushDocToStage(loaded.doc);
+    bridge?.seek(frame);
+    bridge?.setSelection([]);
+  }
+
+  const store: ShotEditorStore = {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    stageHandlers,
+
+    attachStage(next) {
+      bridge = next;
+      if (next === null) {
+        set({ stageInfo: null });
+        return;
+      }
+      if (state.doc !== null) {
+        // Through `pushDocToStage`, not `next.loadDoc`: the isolation rides the
+        // document push now, and a second entry point that pushed the document
+        // without it is exactly how the stage ends up scoped to a layer the
+        // document it is holding does not contain.
+        pushDocToStage(state.doc);
+        next.seek(state.frame);
+        next.setSelection(state.selection);
+      }
+      pushWorkspaceToStage();
+    },
+    stage: () => bridge,
+    selectionQuads: () => bridge?.selectionQuads() ?? null,
+
+    async refreshShots() {
+      try {
+        const { shots } = await api.listShots();
+        set({ shots });
+      } catch (e) {
+        set({ error: e instanceof Error ? e.message : String(e) });
+      }
+    },
+
+    async openShot(name) {
+      if (name === state.name) return;
+      // REFUSE rather than replace: `loadInto` swaps `state.doc`, so opening
+      // over a document whose last save failed destroys edits that exist
+      // nowhere else. `flush` has already put the reason in `state.error`.
+      try {
+        await store.flush();
+      } catch {
+        return;
+      }
+      const gen = ++generation;
+      try {
+        await loadInto(name, gen);
+      } catch (e) {
+        if (gen !== generation) return;
+        set({ error: e instanceof Error ? e.message : String(e) });
+      }
+    },
+
+    async createShot(name) {
+      // Same refusal as `openShot`: creating swaps the open document out.
+      try {
+        await store.flush();
+      } catch {
+        return;
+      }
+      const gen = ++generation;
+      // PascalCase for the component name; the store name stays as typed.
+      const componentName = pascalCase(name);
+      const doc = createShotDoc({ id: `sht_${slug(name)}`, name: componentName });
+      try {
+        // `null` is the CREATE claim: a name already in use comes back 409
+        // rather than overwriting whatever is there.
+        const result = await api.saveShot(name, doc, null);
+        if (gen !== generation) return;
+        docHistory = createHistory<Doc3D>(doc);
+        docHistory.subscribe(onHistoryChange);
+        set({
+          name,
+          doc,
+          rev: result.rev,
+          frame: 0,
+          sceneId: doc.scenes[0] ?? null,
+          ...CLEARED_SELECTION,
+          dirty: false,
+          saveState: "saved",
+          error: null,
+          emitWarning: result.warning ?? null,
+          canUndo: false,
+          canRedo: false,
+        });
+        mirrorUrl();
+        pushDocToStage(doc);
+        // THE SAME TWO PUSHES `loadInto` ENDS WITH, and for the same reason:
+        // the stage keeps whatever frame and selection the last document left
+        // it parked at, so a new shot opened from a scrubbed one drew a blank
+        // pane at a master frame the fresh document does not reach.
+        bridge?.seek(0);
+        bridge?.setSelection([]);
+        void store.refreshShots();
+      } catch (e) {
+        if (gen !== generation) return;
+        set({ error: e instanceof Error ? e.message : String(e) });
+      }
+    },
+
+    closeShot() {
+      // An open scrub outlives the document it was taken against; discarding it
+      // is the only thing that keeps history consistent across a close.
+      if (wheelFraming !== null) {
+        clearTimeout(wheelFraming);
+        wheelFraming = null;
+      }
+      gesture?.scrub.discard();
+      gesture = null;
+      framing?.discard();
+      framing = null;
+      generation++;
+      docHistory = null;
+      // Close for REAL on the stage: drop the doc first (unmounting every
+      // plane — without this the stage keeps rendering the closed document
+      // behind the file picker), then free the raster cache. Bridge verbs and
+      // not calls, because the cache is a singleton in the stage's bundle.
+      bridge?.closeDoc();
+      bridge?.clearCaches();
+      set({ ...INITIAL_STATE, shots: state.shots, ...workspacePrefs(state) });
+      mirrorUrl();
+    },
+
+    adoptExternalChange(payload) {
+      // Our own echo, or a different document: nothing to do.
+      if (isOwnEcho(payload)) return;
+      if (payload.name !== undefined && payload.name !== state.name) {
+        void store.refreshShots();
+        return;
+      }
+      if (state.name === null) return;
+      // Someone else wrote OUR document. Adopting silently would throw away
+      // local edits, so a dirty chrome is told instead of overwritten.
+      if (state.dirty) {
+        set({
+          error:
+            `this scene changed somewhere else while you had unsaved edits — ` +
+            `your version is still open; save it under another name or reload to take theirs`,
+        });
+        return;
+      }
+      const gen = ++generation;
+      void loadInto(state.name, gen).catch(() => {
+        /* a deleted document surfaces on the next list refresh */
+      });
+    },
+
+    edit(fn) {
+      if (docHistory === null) return false;
+      // A wheel dolly's scrub is closed by silence, so a panel edit can land
+      // inside that window with no pointer down anywhere. Committing the flick
+      // first is what keeps `transaction()` from throwing at the author.
+      closeWheelFraming();
+      if (historyBusy()) return false;
+      docHistory.transaction(fn);
+      return true;
+    },
+    undo() {
+      closeWheelFraming();
+      if (historyBusy()) return;
+      docHistory?.undo();
+    },
+    redo() {
+      closeWheelFraming();
+      if (historyBusy()) return;
+      docHistory?.redo();
+    },
+    /**
+     * Get what is in memory onto disk, or THROW.
+     *
+     * Every caller uses this as "the disk now has my edits" immediately before
+     * it overwrites or DROPS the in-memory document (a checkpoint restore, a
+     * document switch, an agent apply). A flush that reports a success it did
+     * not achieve turns each of those into silent data loss.
+     *
+     * The debounce check alone is not that guarantee. `runSave`'s catch sets
+     * `saveState: "error"` and does NOT reschedule, so a failed autosave (a 409
+     * from a second surface writing the same shot is the ordinary way in)
+     * leaves `dirty` true with no timer armed: this used to see `saveTimer ===
+     * null`, await an already-settled promise, and return as if it had written.
+     *
+     * NO RETRY, deliberately. The failure that gets here is a 409 against a
+     * baseline someone else moved, and re-sending the same rev produces the
+     * same 409 — a second blind PUT over a version this chrome has not seen is
+     * the corruption, not the cure. Refusing keeps the document open, in
+     * memory, with the reason already on screen.
+     */
+    async flush() {
+      if (saveTimer !== null) {
+        clearTimeout(saveTimer);
+        saveTimer = null;
+        await runSave();
+      }
+      await savePromise;
+      if (state.saveState === "error") {
+        throw new Error(
+          `${state.error ?? "the last save failed"}. This scene is not on disk, so nothing that ` +
+            `replaces or closes it may run yet`,
+        );
+      }
+    },
+
+    seek(frame) {
+      const next = clampFrame(state.doc, frame);
+      if (next === state.frame) return;
+      const sceneId = sceneAt(state.doc, next);
+      // ONE `set`, not two. A seek fires per frame during playback and every
+      // `set` is a full listener sweep, so the isolation scope is folded into
+      // the same patch rather than routed through `setScene`.
+      const isolation = isolationForScene(sceneId);
+      const wasIsolated = state.isolation;
+      set({ frame: next, sceneId, isolation, ...(isolation === null ? { isolationOrbit: false } : {}) });
+      bridge?.seek(next);
+      if (isolation !== wasIsolated) bridge?.setIsolation(isolation);
+      // No mirrorUrl: the URL carries only the document name, which a seek
+      // never changes.
+    },
+    setPlaying(playing) {
+      set({ playing });
+    },
+    step(delta) {
+      if (state.doc === null) return;
+      const total = docDurationFramesCached(state.doc);
+      if (total <= 0) return;
+      // Wraps, because a preview loop is what an author wants from the space
+      // bar; stopping at the end would need a second key to get back.
+      const next = ((state.frame + delta) % total + total) % total;
+      store.seek(next);
+    },
+
+    select,
+    focusScene(sceneId) {
+      if (state.doc === null || sceneId === state.sceneId) return;
+      const at = sceneToMaster(state.doc, sceneId, 0);
+      if (at !== null) store.seek(at);
+      // PINNED HERE, and not left to `seek`'s side effect. `seek` early-returns
+      // when the target frame is the one the playhead is already on, and that is
+      // precisely the state this repairs: FilePanel pins a scene without moving
+      // the playhead, so the pin and the playhead have already diverged and the
+      // seek back is a no-op. Every caller follows this with `select`, which
+      // orders within `state.sceneId` — an unrepaired pin makes that selection
+      // resolve to empty and silently clear whatever was selected before.
+      //
+      // After the seek rather than before, so this wins unconditionally: a
+      // zero-length scene would otherwise have `sceneAt` hand the pin to its
+      // neighbour.
+      store.setScene(sceneId);
+    },
+    setTool(tool) {
+      set({ tool });
+      bridge?.setTool(tool);
+    },
+    setInspectorMode(inspectorMode) {
+      // A VIEW choice only. It must never arm `animateMode` — see types.ts.
+      set({ inspectorMode });
+    },
+    setAnimateMode(animateMode) {
+      // …and turning animate ON follows the inspector to the Animate tab,
+      // because the author is about to author blocks and wants to see them. The
+      // dependency runs one way only.
+      set({ animateMode, inspectorMode: animateMode ? "animate" : state.inspectorMode });
+    },
+
+    handleKey(event) {
+      const action = resolveKey(event, {
+        editing: isEditable(event.target ?? null),
+        hasSelection: state.selection.length > 0,
+        isolation: state.isolation !== null,
+      });
+      if (action === null) return false;
+      switch (action.kind) {
+        case "tool":
+          store.setTool(action.tool);
+          return true;
+        case "undo":
+          store.undo();
+          return true;
+        case "redo":
+          store.redo();
+          return true;
+        case "save":
+          // `flush` throws when it could not write; the failure is already in
+          // `state.error` and on screen, and nothing here destroys anything.
+          void store.flush().catch(() => {});
+          return true;
+        case "playToggle":
+          store.setPlaying(!state.playing);
+          return true;
+        case "step":
+          store.setPlaying(false);
+          store.step(action.delta);
+          return true;
+        case "nudge":
+          store.nudge(action.dx, action.dy);
+          return true;
+        // The three view verbs address the ACTIVE PANE. One set of keys for two
+        // panes is what the pane bit is for; a second set would be four
+        // shortcuts for one idea, and the author would still have to know which
+        // pane they were in.
+        case "fit":
+          store.fitActivePane();
+          return true;
+        case "fitTimeline":
+          store.fitDock();
+          return true;
+        case "zoom":
+          store.zoomActivePane(action.direction);
+          return true;
+        case "zoomReset":
+          // "100%" has no meaning for an orbit camera — there is no pixel that
+          // is one design pixel — so the reset the author actually wants there
+          // is the fit.
+          if (state.activePane === "working") store.fitWorkingView();
+          else store.setView({ ...state.view, zoom: 1 });
+          return true;
+        case "stageLayout": {
+          // `toggle` is numpad-0's alone: press it once to go to the camera,
+          // press it again to come back. The 1 / 2 / 3 row deliberately does
+          // NOT toggle — pressing 2 twice must leave you in the split, because
+          // those keys name a layout rather than a place to visit.
+          //
+          // Back to the SPLIT and not to the working pane: the split is what
+          // numpad-0 was almost certainly pressed from, and it is the only
+          // mode from which both the camera and the author's own view are
+          // visible.
+          const mode =
+            action.toggle === true && state.stageLayout.mode === action.mode ? "split" : action.mode;
+          store.setStageLayout({ ...state.stageLayout, mode });
+          return true;
+        }
+        case "shadingCycle":
+          // Only with a working pane on screen: cycling an invisible pane's
+          // mode is a state change the author cannot see happen.
+          if (state.stageLayout.mode !== "camera") {
+            store.setShadingMode(nextShading(state.shadingMode));
+          }
+          return true;
+        case "alignCameraToView":
+          store.alignCameraToWorkingView();
+          return true;
+        // NO `addShot` ARM. ⇧C was that key and is Blender's fit-all now, so
+        // the action had no producer left. `store.addShotAtPlayhead` stays —
+        // the timeline's `+ shot` button is its caller.
+        case "addMarker":
+          store.addMarkerAtPlayhead();
+          return true;
+        case "togglePanel":
+          if (action.panel === "rail") store.setRailCollapsed(!state.railCollapsed);
+          else if (action.panel === "inspector") {
+            store.setInspectorCollapsed(!state.inspectorCollapsed);
+          } else store.togglePanels();
+          return true;
+        case "animateToggle":
+          store.setAnimateMode(!state.animateMode);
+          return true;
+        case "openExport":
+          // Only with a document open: an export dialog over nothing would
+          // offer to render a shot that does not exist.
+          if (state.name !== null) store.setExportOpen(true);
+          return true;
+        case "deleteSelection":
+          store.deleteSelection();
+          return true;
+        case "duplicate":
+          store.duplicateSelection();
+          return true;
+        case "selectAll":
+          store.selectAll();
+          return true;
+        case "deselect":
+          select([]);
+          return true;
+        case "group":
+          store.groupSelection();
+          return true;
+        case "ungroup":
+          store.ungroupSelection();
+          return true;
+        case "toggleLock":
+          store.toggleFlag("locked");
+          return true;
+        case "toggleHidden":
+          store.toggleFlag("hidden");
+          return true;
+        case "splitAtPlayhead":
+          store.splitAtPlayhead();
+          return true;
+        case "enterIsolation": {
+          const first = state.selection[0];
+          if (first !== undefined) store.enterIsolation(first);
+          return true;
+        }
+        case "exitIsolation":
+          store.exitIsolation();
+          return true;
+        // BOTH GUARDED ON A VISIBLE WORKING PANE, for the reason `shadingCycle`
+        // is — and here it is not merely invisible but WRITING: with follow
+        // armed, `setWorkingView` writes the shot camera, and in camera-only
+        // layout both of follow's indicators are off screen (CameraViewBar
+        // returns null, the in-pane badge has no pane), so a numpad key would
+        // rewrite and autosave the camera with nothing on screen to say so.
+        case "workingViewPreset":
+          if (noWorkingPane()) return true;
+          store.setWorkingView(presetWorkingView(state.workingView, action.preset));
+          return true;
+        case "fitSelection":
+          if (noWorkingPane()) return true;
+          store.fitWorkingViewToSelection();
+          return true;
+        // The next three are guarded on a VISIBLE working pane, exactly as
+        // `workingViewPreset` above is and for the same reason: with follow
+        // armed `setWorkingView` writes the shot camera, and in camera-only
+        // layout both of follow's indicators are off screen — so a numpad key
+        // would rewrite and autosave the camera with nothing on screen to say
+        // so.
+        case "orbitStep":
+          if (noWorkingPane()) return true;
+          store.setWorkingView(orbitByDegrees(state.workingView, action.dx, action.dy));
+          return true;
+        case "toggleWorkingOrtho":
+          if (noWorkingPane()) return true;
+          store.setWorkingView({ ...state.workingView, ortho: state.workingView.ortho !== true });
+          return true;
+        case "setHidden": {
+          // EXPLICIT, unlike `toggleFlag`, which reads `selection[0]`'s own
+          // flag — so hiding five layers one at a time left no key that could
+          // bring them back, the selection having gone with them.
+          const sceneId = layerContainer();
+          const home = state.doc === null || sceneId === null ? null : homeOf(state.doc, sceneId);
+          if (sceneId === null || home === null) return true;
+          // ── THE SCOPE ON SCREEN, not the whole container ────────────────
+          //
+          // Inside isolation the author can only see one subtree, so "hide
+          // everything else" and "reveal everything" both mean everything IN
+          // THAT SUBTREE. Reaching outside it writes `hidden` onto layers the
+          // pane never showed, which the author discovers on leaving.
+          // DESCENDANTS ONLY, not `relativesOf`: the isolation root's own
+          // ancestors are above the boundary and off screen with everything
+          // else outside it.
+          const scoped =
+            state.isolation === null
+              ? Object.keys(home.layersById)
+              : [...withDescendants(home, [state.isolation])];
+          // ── AND WHAT ⇧H MUST LEAVE ALONE ────────────────────────────────
+          //
+          // `hidden` CASCADES, so "everything minus the selection" hid the
+          // selection's own ancestors and the cascade blanked the selection
+          // itself — and inside isolation the root is an ancestor by
+          // definition, so the whole pane went. `relativesOf` is the fix and
+          // lives in packages/shot beside the walk it shares.
+          const keep = relativesOf(home, state.selection);
+          const ids =
+            action.scope === "reveal"
+              ? scoped
+              : action.scope === "others"
+                ? scoped.filter((id) => !keep.has(id))
+                : [...new Set(state.selection)];
+          if (ids.length === 0) return true;
+          store.edit((doc) => setLayerFlags(doc, sceneId, ids, { hidden: action.scope !== "reveal" }));
+          return true;
+        }
+        case "clearTransform": {
+          // Back to the layer's own zero on ONE channel — Blender's ⌥G / ⌥R /
+          // ⌥S. The fastest way out of a transform that went wrong several
+          // edits ago, which undo cannot reach once anything else has happened.
+          const sceneId = layerContainer();
+          if (sceneId === null || state.selection.length === 0) return true;
+          const ids = state.selection;
+          store.edit((doc) => {
+            const home = homeOf(doc, sceneId);
+            if (home === null) return doc;
+            const layersById = { ...home.layersById };
+            let changed = false;
+            for (const id of ids) {
+              const layer = layersById[id];
+              if (layer === undefined || layer.locked === true) continue;
+              const t = layer.transform;
+              // SIZE IS NOT CLEARED TO ZERO. A layer with no extent has no
+              // handles left to grab and no way back, which is the same reason
+              // `clampSize` exists — so ⌥S resets the two tilt-free axes to the
+              // layer's own square rather than to nothing.
+              const next =
+                action.channel === "offset"
+                  ? { ...t, position: [0, 0, 0] as [number, number, number] }
+                  : action.channel === "rotation"
+                    ? { ...t, tilt: [0, 0] as [number, number], rollDeg: 0 }
+                    : t;
+              if (next === t) continue;
+              layersById[id] = { ...layer, transform: next };
+              changed = true;
+            }
+            return changed ? patchHome(doc, sceneId, { ...home, layersById }) : doc;
+          });
+          // ⌥S has no honest answer yet: `size` is authored geometry rather
+          // than a transform channel, so "clear" would mean picking a size the
+          // author never chose. Named rather than silently doing nothing.
+          if (action.channel === "scale") {
+            set({
+              error:
+                "A layer's size is its own geometry rather than a transform, so there is no scale " +
+                "to clear — set W and H in the inspector, or undo the resize.",
+            });
+          }
+          return true;
+        }
+        case "wireframeToggle":
+          // Blender's ⇧Z: into wireframe, and back to whatever was there.
+          if (state.stageLayout.mode !== "camera") {
+            store.setShadingMode(
+              state.shadingMode === "wireframe" ? (state.previousShading ?? "solid") : "wireframe",
+            );
+          }
+          return true;
+        case "boxSelect":
+          // STAGE-LOCAL. The letter has one owner (this table), and the stage
+          // reads the armed bit in its own marquee lane — no bridge message and
+          // no store verb, so there is nothing for this arm to do.
+          return false;
+        case "toggleIsolation":
+          // Blender's local view, in or out. `selection[0]` is the subject
+          // going in, which is the same rule ⌘Enter uses.
+          if (state.isolation !== null) store.exitIsolation();
+          else if (state.selection[0] !== undefined) store.enterIsolation(state.selection[0]);
+          return true;
+        case "penCommit":
+        case "penAbandon":
+        case "modalStart":
+        case "modalAxis":
+        case "modalNumber":
+        case "modalNumberBack":
+        case "modalConfirm":
+        case "modalCancel":
+          // UNREACHABLE FROM HERE, and listed rather than defaulted so it stays
+          // that way. The pen and the modal transforms live in the stage, which
+          // resolves these with `penActive` / `workingPane` / `transformModal`
+          // in its own capture-phase listener and consumes them there; this
+          // call site never sets those bits, so the resolver cannot answer
+          // them. If either lane ever moves into the chrome, this arm is a
+          // compile error waiting to be filled in rather than a key that
+          // silently does nothing.
+          return false;
+      }
+    },
+
+    deleteSelection() {
+      // ── THE SUBJECT ORDER: marker, then block, then layers ──────────────
+      //
+      // Most specific first, and each of the three is cleared by selecting one
+      // of the others (see `select`, `selectBlock`, `selectMarker`) — so the
+      // order below never has to arbitrate between two things the author
+      // believes are both selected.
+      //
+      // The MARKER is above the `sceneId` guard on purpose: a marker is timed on
+      // master frames and belongs to no scene, so gating it on one would make
+      // Delete silently do nothing on a document whose playhead is outside every
+      // scene.
+      const marker = state.selectedMarker;
+      if (marker !== null) {
+        store.removeMarker(marker);
+        return;
+      }
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      // A FOCUSED BLOCK is the subject when there is one: the author is looking
+      // at the dock, and deleting the whole layer because a block was selected
+      // would be the worst possible reading of the same key.
+      const focused = state.selectedBlock;
+      if (focused !== null) {
+        set({ selectedBlock: null });
+        // THE BLOCK'S OWN SCENE, which is why it is carried on the selection.
+        // `sceneId` is where the playhead is, and on one master strip those are
+        // routinely different — deleting against the wrong one is a silent
+        // no-op, the worst possible reading of a Delete key.
+        store.edit((doc) =>
+          focused.layerId === CAMERA_ROW_ID
+            ? removeShot(doc, focused.sceneId, focused.blockId)
+            : removeBlock(doc, focused.sceneId, focused.layerId, focused.blockId),
+        );
+        return;
+      }
+      const ids = state.selection;
+      if (ids.length === 0) return;
+      select([]);
+      store.edit((doc) => removeLayers(doc, sceneId, ids));
+    },
+    duplicateSelection() {
+      const ids = state.selection;
+      if (ids.length === 0 || state.sceneId === null) return;
+      const sceneId = layerContainer()!;
+      let fresh: string[] = [];
+      store.edit((doc) => {
+        const out = duplicateLayers(doc, sceneId, ids);
+        fresh = out.ids;
+        return out.doc;
+      });
+      // The COPIES become the selection, so a duplicate-then-drag is one
+      // gesture rather than two — which is what ⌘D is for.
+      if (fresh.length > 0) select(fresh);
+    },
+    alignSelection(mode) {
+      const sceneId = state.sceneId;
+      const open = state.doc;
+      if (sceneId === null || open === null || state.selection.length === 0) return;
+      const ids = state.selection;
+      // The PLAYHEAD is an input: bounds are measured on what is RENDERED at
+      // this frame, so aligning at frame 0 and at frame 40 are different edits
+      // on a layer a block is moving. See align.ts.
+      const at = masterToSceneCached(open, state.frame)?.sceneFrame ?? 0;
+      let refusal: string | null = null;
+      const ran = store.edit((doc) => {
+        const out = alignLayers(doc, sceneId, ids, mode, at);
+        refusal = out.refusal;
+        return out.doc;
+      });
+      // `edit` collapses a same-document return into no history entry, so a
+      // refusal costs nothing and an already-aligned selection records no undo.
+      sayRefusal(ran, refusal);
+    },
+    enterIsolation(id) {
+      const sceneId = state.sceneId;
+      const scene = sceneId === null ? undefined : state.doc?.scenesById[sceneId];
+      if (scene === undefined || scene.layersById[id] === undefined) return;
+      // ALWAYS HEAD-ON ON ENTRY, whichever subtree and whatever the last one's
+      // camera was doing. `setIsolation` resets the stage's own copy too.
+      set({ isolation: id, isolationOrbit: false, selection: [id] });
+      // ISOLATION LIVES IN THE WORKING PANE, so entering with only the camera
+      // pane on screen would dim the scene and show the head-on view nowhere —
+      // the mode would look broken rather than off.
+      //
+      // ponytail: the layout is not restored on exit, so an author who entered
+      // from camera-only comes back to a split. Restoring it needs a
+      // remembered mode and a rule for what happens when they change the
+      // layout while inside, which is more state than "press the layout button
+      // again" is worth.
+      if (state.stageLayout.mode === "camera") {
+        store.setStageLayout({ ...state.stageLayout, mode: "split" });
+      }
+      bridge?.setIsolation(id);
+    },
+    exitIsolationAll() {
+      if (state.isolation === null) return;
+      set({ isolation: null, isolationOrbit: false });
+      bridge?.setIsolation(null);
+    },
+    exitIsolation() {
+      // ONE LEVEL, not all the way out. Entering is a walk down the tree and
+      // leaving has to be its inverse, or a nested subtree can only be left by
+      // jumping to the scene — which loses the author's place.
+      const at = state.isolation;
+      if (at === null) return;
+      const sceneId = state.sceneId;
+      const scene = sceneId === null ? undefined : state.doc?.scenesById[sceneId];
+      const up = scene === undefined ? null : parentOf(scene, at);
+      set({ isolation: up, isolationOrbit: false, selection: [at] });
+      bridge?.setIsolation(up);
+    },
+    moveLayerTo(id, to) {
+      const sceneId = layerContainer();
+      if (sceneId === null) return;
+      let refusal: string | null = null;
+      const ran = store.edit((doc) => {
+        const out = moveLayer(doc, sceneId, id, to);
+        refusal = out.refusal ?? null;
+        return out.doc;
+      });
+      sayRefusal(ran, refusal);
+    },
+    groupSelection() {
+      const ids = state.selection;
+      const sceneId = layerContainer();
+      if (ids.length < 2 || sceneId === null) return;
+      let groupId: string | null = null;
+      let refusal: string | null = null;
+      const ran = store.edit((doc) => {
+        const out = groupLayers(doc, sceneId, ids);
+        groupId = out.id;
+        refusal = out.refusal ?? null;
+        return out.doc;
+      });
+      // Same shape as align's: `edit` collapses a same-document return into no
+      // history entry, so a refusal costs nothing and says why in the strip.
+      sayRefusal(ran, refusal);
+      if (groupId !== null) select([groupId]);
+    },
+    ungroupSelection() {
+      const sceneId = layerContainer();
+      if (sceneId === null || state.selection.length === 0) return;
+      const targets = state.selection;
+      let freed: string[] = [];
+      let refusal: string | null = null;
+      const ran = store.edit((doc) => {
+        let next = doc;
+        for (const id of targets) {
+          const out = ungroupLayer(next, sceneId, id);
+          next = out.doc;
+          freed = [...freed, ...out.ids];
+          // The FIRST refusal, kept: dissolving a multi-selection stops being
+          // legible once two messages compete for one strip.
+          if (refusal === null && out.refusal !== undefined) refusal = out.refusal;
+        }
+        return next;
+      });
+      sayRefusal(ran, refusal);
+      if (freed.length > 0) select(freed);
+    },
+    toggleFlag(flag) {
+      const ids = state.selection;
+      const sceneId = layerContainer();
+      if (ids.length === 0 || sceneId === null || state.doc === null) return;
+      // Toggle from the FIRST selected layer, so a mixed selection lands on one
+      // value rather than each layer flipping to its own opposite. Read through
+      // `homeOf`: the container can be a `cmp_` definition id, which
+      // `scenesById` answers with undefined — and an undefined first meant
+      // `next` was always true, so a hidden layer inside a definition could
+      // never be un-hidden from here.
+      const first = homeOf(state.doc, sceneId)?.layersById[ids[0]!];
+      const next = first?.[flag] !== true;
+      store.edit((doc) => setLayerFlags(doc, sceneId, ids, { [flag]: next }));
+    },
+    renameLayer(id, label) {
+      const sceneId = layerContainer();
+      if (sceneId === null) return;
+      store.edit((doc) => renameLayer(doc, sceneId, id, label));
+    },
+    reorderLayer(id, toIndex) {
+      const sceneId = layerContainer();
+      if (sceneId === null) return;
+      store.edit((doc) => reorderLayer(doc, sceneId, id, toIndex));
+    },
+    restack(id, to) {
+      const sceneId = layerContainer();
+      if (sceneId === null) return;
+      store.edit((doc) => restackLayer(doc, sceneId, id, to));
+    },
+    nudge(dx, dy) {
+      const ids = state.selection;
+      const sceneId = state.sceneId;
+      if (ids.length === 0 || sceneId === null) return;
+      // Through the SAME transform math a drag uses, so a nudge and a drag can
+      // never disagree about what "move by 1px" means.
+      let refusal: string | null = null;
+      const ran = store.edit((doc) => {
+        const scene = doc.scenesById[sceneId];
+        if (scene === undefined) return doc;
+        const layersById = { ...scene.layersById };
+        let changed = false;
+        for (const id of ids) {
+          const layer = layersById[id];
+          if (layer === undefined) continue;
+          // NAMED, like every other locked skip in this lane. An arrow key is
+          // the easiest gesture to repeat without looking, so a locked layer
+          // that quietly stayed put while its siblings walked away is the one
+          // most likely to be noticed only much later.
+          if (layer.locked === true) {
+            refusal ??= `"${layer.label}" is locked, so it did not move — unlock it to include it.`;
+            continue;
+          }
+          const transform = applyToTransform(layer.transform, { kind: "move", dx, dy });
+          if (transform === layer.transform) continue;
+          layersById[id] = { ...layer, transform };
+          changed = true;
+        }
+        return changed ? { ...doc, scenesById: { ...doc.scenesById, [sceneId]: { ...scene, layersById } } } : doc;
+      });
+      // THE SITE THE REVIEW NAMED: an arrow key pressed mid-drag reached
+      // `historyBusy`, which wrote its message, and this `set` immediately
+      // replaced it with the `null` the un-run body left behind.
+      sayRefusal(ran, refusal);
+    },
+    setDockCollapsed(dockCollapsed) {
+      // A manual toggle takes ownership from focus mode: leaving the working
+      // view then keeps the author's choice instead of restoring over it.
+      set({ dockCollapsed, focusRestoreDock: null });
+    },
+    setRailCollapsed(railCollapsed) {
+      set({ railCollapsed });
+    },
+    setRailWidth(width) {
+      set({ railWidth: clampSize(width, RAIL_WIDTH.min, RAIL_WIDTH.max) });
+    },
+    setDockHeight(height) {
+      // The ceiling is the WINDOW's, resolved at the moment of the drag: a
+      // dock taller than the viewport is a dock with no stage behind it, and
+      // the same pixel height is fine on a desktop and absurd on a laptop.
+      const ceiling = dockCeiling(
+        typeof window === "undefined" ? DOCK_HEIGHT.max : window.innerHeight,
+      );
+      set({ dockHeight: clampSize(height, DOCK_HEIGHT.min, ceiling) });
+    },
+    setInspectorCollapsed(inspectorCollapsed) {
+      // Ownership rule — see setDockCollapsed.
+      set({ inspectorCollapsed, focusRestoreInspector: null });
+    },
+    /**
+     * Every panel out of the way, or every panel back.
+     *
+     * Derived from the three flags rather than a fourth "focus mode" bit,
+     * because a fourth bit has to answer "what does restoring mean when the
+     * author collapsed one panel by hand first" and there is no good answer.
+     * ANY panel open means the key hides them all; only when all three are
+     * already hidden does it bring them back. So the first press always
+     * reveals the stage, which is the whole point of the key.
+     */
+    togglePanels() {
+      const s = store.getState();
+      const anyOpen = !s.railCollapsed || !s.inspectorCollapsed || !s.dockCollapsed;
+      set({
+        railCollapsed: anyOpen,
+        inspectorCollapsed: anyOpen,
+        dockCollapsed: anyOpen,
+        // The sweep is the loudest manual toggle of all — both slots pass to
+        // the author (see setDockCollapsed).
+        focusRestoreInspector: null,
+        focusRestoreDock: null,
+      });
+    },
+    setDockPpf(dockPpf) {
+      set({ dockPpf: Math.max(0.2, Math.min(60, dockPpf)) });
+    },
+    attachDockFit(fit) {
+      dockFit = fit;
+    },
+    fitDock(sceneId) {
+      dockFit?.(sceneId);
+    },
+
+    // ---- the audio lane ------------------------------------------------------
+    /**
+     * ONE undo entry for the asset AND the clip.
+     *
+     * The two writes are one `edit()` on purpose: an undo that removed the clip
+     * and left an orphan asset behind, or removed the asset and left a clip
+     * pointing at nothing, would be a document `validateShotDoc` refuses to
+     * save — from the undo button.
+     *
+     * The DURATION comes from the STORED wav, never from the upload. The server
+     * transcodes every audio import to canonical 48 kHz PCM, so the original
+     * container's length and the stored one's differ by up to a partial frame,
+     * and the clip has to be timed against the bytes the mixer will actually
+     * read.
+     */
+    async importAudio(file, atFrame) {
+      const doc = state.doc;
+      if (doc === null) throw new Error("open a scene before importing audio");
+      const gen = generation;
+      const { uploaded } = await uploadOfKind(file, ["audio"], gen);
+      const bytes = await api.fetchAssetBytes(uploaded.path);
+      // The fence again, because there is a second await: `uploadOfKind` can
+      // only speak for its own.
+      if (gen !== generation) throw new Error(`${file.name} was imported into a scene that has closed`);
+      const seconds = wavDurationSeconds(bytes);
+      if (seconds === null || !(seconds > 0)) {
+        throw new Error(`${file.name} stored, but its duration could not be read from the stored WAV`);
+      }
+      const at = Math.max(0, Math.round(atFrame ?? state.frame));
+      store.edit((base) => {
+        // Content-addressed: a re-import of identical bytes answers with a path
+        // the document may already carry, and a second ShotAsset for one file
+        // is a duplicate the mixer would fetch twice.
+        const existing = Object.values(base.assets).find((a) => a.path === uploaded.path);
+        const asset = existing ?? {
+          id: freshId(usedIdsOf(base), ASSET_ID_PREFIX, slug(file.name.replace(/\.[^.]*$/, ""))),
+          path: uploaded.path,
+          hash: uploaded.hash,
+          kind: "audio" as const,
+        };
+        const withAsset =
+          existing === undefined ? { ...base, assets: { ...base.assets, [asset.id]: asset } } : base;
+        return addAudioClip(withAsset, {
+          asset: asset.id,
+          frame: at,
+          // Rounded UP: a clip one frame short of its source drops the tail,
+          // and the mixer already emits silence past the end, so rounding the
+          // other way costs nothing and losing audio costs the take.
+          durationFrames: Math.max(1, Math.ceil((seconds * base.fps.num) / base.fps.den)),
+        });
+      });
+    },
+    dragAudio(clipId, mode, delta) {
+      const active = gesture;
+      if (active === null) return;
+      active.scrub.capture((base) => writeAudioDrag(base, clipId, mode, delta));
+    },
+    dragAudioGain(clipId, gain) {
+      const active = gesture;
+      if (active === null) return;
+      // MAX_AUDIO_GAIN is validate.ts's ceiling; clamping here rather than at
+      // the handle keeps a live drag from ever building a refusable document.
+      const clamped = Math.max(0, Math.min(MAX_AUDIO_GAIN, gain));
+      active.scrub.capture((base) => updateAudioClip(base, clipId, { gain: clamped }));
+    },
+    toggleAudioMute(clipId) {
+      const clip = state.doc?.audio[clipId];
+      if (clip === undefined) return;
+      store.edit((base) => updateAudioClip(base, clipId, { muted: !(clip.muted ?? false) }));
+    },
+    removeAudio(clipId) {
+      store.edit((base) => removeAudioClip(base, clipId));
+    },
+    setPreviewMuted(previewMuted) {
+      set({ previewMuted });
+    },
+    setPreviewVolume(volume) {
+      set({ previewVolume: Math.max(0, Math.min(1, volume)) });
+    },
+
+    selectMarker(selectedMarker) {
+      // The BLOCK goes, for the reason a layer selection drops one: two
+      // subjects live at once and `deleteSelection` takes the first, so a stale
+      // block focus under a freshly clicked marker is a Delete whose target the
+      // author cannot see.
+      set(selectedMarker === null ? { selectedMarker } : { selectedMarker, selectedBlock: null });
+    },
+    addMarkerAtPlayhead() {
+      const open = state.doc;
+      if (open === null) return;
+      const at = state.frame;
+      const existing = (open.markers ?? []).find((m) => m.frame === at);
+      if (existing !== undefined) {
+        store.selectMarker(existing.id);
+        return;
+      }
+      const before = new Set((open.markers ?? []).map((m) => m.id));
+      store.edit((doc) => addMarker(doc, { frame: at }));
+      // Read back rather than re-derived: `addMarker` mints the id from the
+      // document's used ids, and a second guess at that rule is a second rule.
+      const created = store.getState().doc?.markers?.find((m) => !before.has(m.id));
+      if (created !== undefined) store.selectMarker(created.id);
+    },
+    dragMarker(markerId, frame) {
+      const active = gesture;
+      if (active === null) return;
+      const at = Math.max(0, Math.round(frame));
+      active.scrub.capture((base) => {
+        // A move that lands where the mark already is returns the base BY
+        // REFERENCE. `updateMarker` rebuilds the array unconditionally, so
+        // without this a drag that travelled nowhere would still record an undo
+        // entry and dirty the document.
+        const marker = base.markers?.find((m) => m.id === markerId);
+        return marker === undefined || marker.frame === at ? base : updateMarker(base, markerId, { frame: at });
+      });
+    },
+    setMarker(markerId, patch) {
+      store.edit((doc) => updateMarker(doc, markerId, patch));
+    },
+    removeMarker(markerId) {
+      store.edit((doc) => removeMarker(doc, markerId));
+      if (state.selectedMarker === markerId) set({ selectedMarker: null });
+    },
+    setAgentOpen(agentOpen) {
+      set({ agentOpen });
+    },
+    setAgentModel(agentModel) {
+      set({ agentModel });
+    },
+    setAgentCredentials(agentCredentials, agentCredentialsError) {
+      set({ agentCredentials, agentCredentialsError: agentCredentialsError ?? null });
+    },
+    setAgentRunning(agentRunning) {
+      set({ agentRunning });
+    },
+    setAgentError(agentError) {
+      set({ agentError });
+    },
+    setAgentSession(agentSessionId) {
+      set({ agentSessionId });
+    },
+    setAgentCost(agentCostUsd) {
+      set({ agentCostUsd });
+    },
+    appendAgentItem(item) {
+      set({ agentItems: [...state.agentItems, item] });
+    },
+    patchAgentProposal(id, patch) {
+      // Through the SHARED reducer, so a card's status transitions mean the
+      // same thing in every chrome.
+      set({ agentItems: patchProposalIn(state.agentItems, id, patch) });
+    },
+    clearAgentTranscript() {
+      // The COST goes with it. A stale "last turn ≈ $0.04" under an empty
+      // transcript is a number about a conversation that is no longer there.
+      set({ agentItems: [], agentError: null, agentSessionId: null, agentCostUsd: null });
+    },
+
+    setExportOpen(exportOpen) {
+      set({ exportOpen });
+    },
+    setRenderJob(renderJob) {
+      // Late frames from a job that is already terminal are DROPPED. SSE has no
+      // ordering guarantee across a reconnect, and a stale "frame 40/120"
+      // arriving after "done" would put the progress bar back.
+      const live = state.renderJob;
+      if (
+        renderJob !== null &&
+        live !== null &&
+        live.id === renderJob.id &&
+        live.phase !== "running" &&
+        renderJob.phase === "running"
+      ) {
+        return;
+      }
+      set({ renderJob });
+    },
+
+    selectBlock(selectedBlock) {
+      // …and the mirror of `selectMarker`: focusing a bar drops the mark, so
+      // Delete addresses the thing the author just clicked.
+      set(selectedBlock === null ? { selectedBlock } : { selectedBlock, selectedMarker: null });
+    },
+    beginBlockDrag() {
+      if (docHistory === null) return;
+      closeWheelFraming();
+      // One scrub at a time, the camera lane included: a dock drag started
+      // while the camera lane holds the history would throw out of engine.
+      if (gesture !== null || framing !== null) return;
+      // The SAME scrub machinery a canvas gesture uses, so a trim is one undo
+      // entry and Escape restores the base exactly.
+      gesture = { kind: "move", layerIds: [], scrub: docHistory.scrub(), screenScale: null, snap: null };
+    },
+    dragBlock(sceneId, layerId, blockId, edge, toFrame) {
+      const active = gesture;
+      if (active === null) return;
+      // THE SCENE COMES FROM THE ROW, not from `state.sceneId`. The dock is one
+      // master strip now, so the row under the pointer routinely belongs to a
+      // scene the playhead is not in — and `state.sceneId` follows the playhead.
+      active.scrub.capture((base) => {
+        // The camera's row holds SHOTS, not blocks. Routing on the row id keeps
+        // the dock's gesture identical for both while the document ops stay
+        // separate — a shot list is sorted and non-overlapping and a block list
+        // is neither, so one generic retimer would hide the re-sort.
+        if (layerId === CAMERA_ROW_ID) {
+          if (edge === "body") return moveShot(base, sceneId, blockId, toFrame);
+          return trimShot(base, sceneId, blockId, edge, toFrame);
+        }
+        if (edge === "body") return moveBlock(base, sceneId, layerId, blockId, toFrame);
+        return trimBlock(base, sceneId, layerId, blockId, edge, toFrame);
+      });
+    },
+    dragLifespan(sceneId, layerId, mode, delta) {
+      const active = gesture;
+      if (active === null) return;
+      // ONE capture for the bar AND its blocks — `writeLifespan` writes both, so
+      // a body drag cannot leave the layer's existence and its animation half a
+      // frame apart, and Escape restores them together.
+      active.scrub.capture((base) => writeLifespan(base, sceneId, layerId, mode, delta));
+    },
+    endBlockDrag(commit) {
+      const active = gesture;
+      gesture = null;
+      if (active === null) return;
+      if (commit) active.scrub.commit();
+      else active.scrub.discard();
+      syncHistoryFlags();
+    },
+    trimScene(sceneId, durationFrames) {
+      const active = gesture;
+      if (active === null) {
+        store.edit((doc) => trimScene(doc, sceneId, durationFrames));
+        return;
+      }
+      active.scrub.capture((base) => trimScene(base, sceneId, durationFrames));
+    },
+    reorderScene(sceneId, toIndex) {
+      store.edit((doc) => reorderScene(doc, sceneId, toIndex));
+    },
+    setSceneTransition(sceneId, next) {
+      // A plain transaction: there is no drag gesture on a transition in v1, so
+      // nothing to capture. The pure op deletes the key on null rather than
+      // storing a "none", and is identity when there was nothing to clear — so
+      // clearing a shot that has no transition adds no undo entry.
+      store.edit((doc) => setSceneTransition(doc, sceneId, next));
+    },
+    addScene() {
+      const open = state.doc;
+      if (open === null) return;
+      // ── THE ONE CREATE THAT CANNOT LAND AT THE PLAYHEAD ─────────────────
+      //
+      // Everything else this chrome creates goes where the playhead is. A SCENE
+      // cannot: inserting one mid-document shifts every master frame after it,
+      // and `doc.audio` and `doc.markers` are timed on MASTER frames (ops.ts) —
+      // so the insert would slide every scene later while the score and the
+      // beat marks stayed put. That is a retime of the whole video, and a
+      // silent desync, dressed up as a create.
+      //
+      // So the rule inverts rather than bending: the scene is APPENDED, and the
+      // PLAYHEAD goes to it. The author still ends up looking at the thing they
+      // just made, which is the half of "at the playhead" that was ever about
+      // them. Reordering it afterwards is a splice, and is what the strip's
+      // drag is for.
+      const before = new Set(open.scenes);
+      store.edit((doc) => {
+        const scene = createScene(usedIdsOf(doc), "scene", `Shot ${doc.scenes.length + 1}`);
+        return {
+          ...doc,
+          scenes: [...doc.scenes, scene.id],
+          scenesById: { ...doc.scenesById, [scene.id]: scene },
+        };
+      });
+      // Read back rather than re-derived: `createScene` mints the id from the
+      // document's used ids, and a second guess at that rule is a second rule.
+      const created = store.getState().doc?.scenes.find((id) => !before.has(id));
+      if (created !== undefined) store.focusScene(created);
+    },
+    splitAtPlayhead() {
+      const sceneId = state.sceneId;
+      const doc = state.doc;
+      if (sceneId === null || doc === null) return;
+      const sceneFrame = masterToSceneCached(doc, state.frame)?.sceneFrame ?? 0;
+      const focused = state.selectedBlock;
+      if (focused !== null) {
+        // A block in ANOTHER scene has no frame under this playhead to split
+        // at, so the author means the scene they are looking at rather than the
+        // bar they last clicked three scenes back.
+        if (focused.sceneId === sceneId) {
+          store.edit((d) => splitBlock(d, sceneId, focused.layerId, focused.blockId, sceneFrame).doc);
+          return;
+        }
+      }
+      // No block focused: the author means the SCENE. Raylight's list gives
+      // split one name and two subjects; the focused block is what picks.
+      store.edit((d) => splitScene(d, sceneId, sceneFrame).doc);
+    },
+
+    addBlock(slot, preset, durationFrames = 12) {
+      const sceneId = state.sceneId;
+      const ids = state.selection;
+      if (sceneId === null || ids.length === 0 || state.doc === null) return;
+      const sceneFrame = masterToSceneCached(state.doc, state.frame)?.sceneFrame ?? 0;
+      let first: string | null = null;
+      let refusal: string | null = null;
+      const ran = store.edit((doc) => {
+        const out = addPresetBlock(doc, sceneId, ids, slot, preset, durationFrames, sceneFrame);
+        first = out.blockIds[0] ?? null;
+        refusal = out.refusals[0] ?? null;
+        return out.doc;
+      });
+      // A locked layer in the selection is skipped, and now says so.
+      sayRefusal(ran, refusal);
+      // Focus the new block, so the timing controls are about the thing that
+      // just appeared rather than about nothing.
+      if (first !== null) set({ selectedBlock: { sceneId, layerId: ids[0]!, blockId: first } });
+    },
+    setBlockPreset(layerId, blockId, preset) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      // The PARAMS are dropped, deliberately. Params are preset-scoped: a
+      // `move`'s dx means nothing to `roll`, and carrying it over would leave
+      // a stale key that the new preset's spec ignores until someone switches
+      // back and finds a number they never typed. `resolveParams` fills the
+      // new preset's own defaults.
+      store.edit((doc) => setBlockPreset(doc, sceneId, layerId, blockId, preset));
+    },
+    removeBlock(layerId, blockId) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      store.edit((doc) => removeBlock(doc, sceneId, layerId, blockId));
+      const focused = state.selectedBlock;
+      if (focused?.blockId === blockId) set({ selectedBlock: null });
+    },
+    removeBlocksByPreset(slot, preset) {
+      const sceneId = state.sceneId;
+      const doc = state.doc;
+      if (sceneId === null || doc === null) return;
+      const scene = doc.scenesById[sceneId];
+      if (scene === undefined) return;
+      // ONE transaction over the whole selection: un-clicking "Fade" on four
+      // layers is one thing the author did, so it is one undo entry.
+      const ids = state.selection;
+      store.edit((d) => {
+        let next = d;
+        for (const layerId of ids) {
+          const layer = scene.layersById[layerId];
+          if (layer === undefined) continue;
+          for (const block of layer.blocks) {
+            if (block.slot === slot && block.preset === preset) {
+              next = removeBlock(next, sceneId, layerId, block.id);
+            }
+          }
+        }
+        return next;
+      });
+    },
+    setBlockParams(layerId, blockId, params) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      store.edit((doc) => setBlockParams(doc, sceneId, layerId, blockId, params));
+    },
+    setBlockEase(layerId, blockId, ease) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      store.edit((doc) => setBlockEase(doc, sceneId, layerId, blockId, ease));
+    },
+    setBlockTiming(layerId, blockId, frame, durationFrames) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      // Through the SAME two ops the dock's handles use, so typing a number and
+      // dragging an edge can never disagree about what a trim means.
+      store.edit((doc) => {
+        const moved = moveBlock(doc, sceneId, layerId, blockId, frame);
+        return trimBlock(moved, sceneId, layerId, blockId, "out", frame + durationFrames);
+      });
+    },
+
+    /**
+     * ⌘A selects everything IN SCOPE, which is not the same as everything.
+     *
+     * ── TWO HOLES, ONE RULE ─────────────────────────────────────────────
+     *
+     * It took the whole scene, so ⌘A then Delete inside a card removed the
+     * entire scene. Undo recovers it, which is the only reason this is a p1.
+     *
+     * And with a component DEFINITION open in the outline it selected the
+     * scene's layers, whose ids live in another home — `select`'s
+     * `leftDefinition` path then set `editingDef: null` and silently kicked the
+     * author out of the definition they were editing.
+     *
+     * The scope the OUTLINE shows is the one an author means, so both come from
+     * the same pair `FilePanel` reads: the open definition, else the scene
+     * narrowed by isolation. Isolation does not apply inside a definition —
+     * a definition's layers are in no scene and isolation is a spatial move.
+     *
+     * The isolated ROOT is excluded and its subtree included. `withDescendants`
+     * includes its seed, so the set is narrowed by hand: selecting the card you
+     * are inside, from inside it, is how a ⌘A then a drag moves the boundary
+     * out from under the author.
+     */
+    selectAll() {
+      const doc = state.doc;
+      const home = doc === null ? null : homeOf(doc, state.editingDef ?? state.sceneId ?? "");
+      if (home === null) return;
+      const all = Object.keys(home.layersById);
+      if (state.editingDef !== null || state.isolation === null) {
+        select(all);
+        return;
+      }
+      const inside = withDescendants(home, [state.isolation]);
+      select(all.filter((id) => id !== state.isolation && inside.has(id)));
+    },
+
+    // ---- the insertion lane ----------------------------------------------------
+    async completeImageDraw(file) {
+      const points = state.imagePick;
+      // Cleared FIRST, and on every path. A pending box that outlived its pick
+      // would be picked up by the next file the author chooses for something
+      // else entirely.
+      set({ imagePick: null });
+      if (file === null || points === null) return;
+      const gen = generation;
+      // THE SERVER DECIDES WHICH KIND THE BOX BECOMES. One drawn box takes
+      // either media file, and the fork is on the store's sniff rather than on
+      // anything read here — a browser MIME guess that disagreed with the
+      // extension map would mint a `video` layer over an image's bytes, which
+      // the save gate accepts and the texture cache renders as a black plane.
+      const { uploaded, kind } = await uploadOfKind(file, ["image", "video"], gen);
+      insertAssetLayer(uploaded, file.name, kind, (asset, ctx) =>
+        layerFromDraw("image", points, { ...ctx, asset, assetKind: kind }),
+      );
+    },
+    async addMeshLayer(file) {
+      // BEFORE THE UPLOAD. The moment a model is added is the only moment
+      // refusing costs nothing — nothing is built on it yet, and the author is
+      // still holding the file. It is measured against what has ALREADY
+      // loaded, because a GLB's count is unknowable until it is parsed; the
+      // effect is a cap on growth, never a lock on an existing document.
+      if (sumTriangles(state.meshTriangles) >= TRIANGLE_HARD_CAP) {
+        set({ error: TRIANGLE_CAP_REFUSAL });
+        return;
+      }
+      const gen = generation;
+      const { uploaded } = await uploadOfKind(file, ["model"], gen);
+      insertAssetLayer(uploaded, file.name, "model", (asset, ctx) => meshLayer(asset, ctx));
+    },
+    addDeviceLayer(preset) {
+      const at = insertContext();
+      if (at === null) return;
+      insertLayer(deviceLayer(preset, at.ctx));
+    },
+    addHtmlLayer() {
+      const at = insertContext();
+      if (at === null) return;
+      insertLayer(htmlLayer(at.ctx));
+    },
+    addClonerLayer() {
+      const sceneId = state.sceneId;
+      const ids = state.selection;
+      if (sceneId === null || ids.length === 0) return;
+      let created: string | null = null;
+      store.edit((doc) => {
+        const out = clonerLayers(doc, sceneId, ids);
+        created = out.id;
+        return out.doc;
+      });
+      // The CLONER becomes the selection, not the layers it swallowed: they are
+      // templates now, and the thing the author places next is the cloner.
+      if (created !== null) select([created]);
+    },
+
+    // ---- components (reusable subtrees) ----------------------------------------
+    createComponentFromSelection(name) {
+      const sceneId = state.sceneId;
+      const ids = state.selection;
+      if (sceneId === null || ids.length === 0) return;
+      let instance: string | null = null;
+      let refusal: string | null = null;
+      const ran = store.edit((doc) => {
+        const out = createComponent(doc, sceneId, ids, name);
+        instance = out.instanceId;
+        refusal = out.refusal ?? null;
+        return out.doc;
+      });
+      sayRefusal(ran, refusal);
+      // The INSTANCE becomes the selection, not the layers it swallowed: they
+      // are a definition now, and the thing the author places next is a
+      // placement of it. Same rule the cloner follows.
+      if (instance !== null) select([instance]);
+    },
+    placeComponent(defId) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      let instance: string | null = null;
+      let refusal: string | null = null;
+      const ran = store.edit((doc) => {
+        const out = addComponentInstance(doc, sceneId, defId);
+        instance = out.instanceId;
+        refusal = out.refusal ?? null;
+        return out.doc;
+      });
+      sayRefusal(ran, refusal);
+      if (instance !== null) select([instance]);
+    },
+    deleteComponent(defId) {
+      let refusal: string | null = null;
+      const ran = store.edit((doc) => {
+        const out = deleteComponent(doc, defId);
+        refusal = out.refusal ?? null;
+        return out.doc;
+      });
+      // Leaving a definition the author just deleted as the outline's subject
+      // would scope it to nothing. `ran` guards it too: a refused edit deleted
+      // nothing, so the outline must keep pointing at what is still there.
+      if (ran && refusal === null && state.editingDef === defId) set({ editingDef: null });
+      sayRefusal(ran, refusal);
+    },
+    renameComponent(defId, name) {
+      store.edit((doc) => renameComponent(doc, defId, name));
+    },
+    setComponentOverride(layerId, key, value) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      store.edit((doc) => {
+        const home = homeOf(doc, sceneId);
+        const layer = home?.layersById[layerId];
+        if (home === null || layer === undefined || layer.kind !== "component") return doc;
+        const overrides = { ...layer.component.overrides };
+        // Writing the DEFAULT clears the override rather than storing it: an
+        // instance that says nothing is an instance that follows its
+        // definition, and a stored value that happens to equal the default
+        // would stop following it the moment the definition changed.
+        if (value === null) delete overrides[key];
+        else overrides[key] = value;
+        return patchHome(doc, sceneId, {
+          layers: home.layers,
+          layersById: {
+            ...home.layersById,
+            [layerId]: { ...layer, component: { ...layer.component, overrides } },
+          },
+        });
+      });
+    },
+    editComponent(defId) {
+      // The OUTLINE's subject, not the stage's: entering a definition is a
+      // structural move (its layers live in no scene and have no camera), while
+      // isolation is a spatial one. Keeping them separate is what stops "what
+      // am I looking at" and "what am I editing" from having to agree.
+      //
+      // THE SELECTION GOES WITH IT. Changing the container while a selection
+      // from the old one survives leaves every container-scoped verb pointed
+      // at a home its own subject is not in — `toggleFlag` reads `undefined`
+      // and writes into the wrong forest, so ⌥H and ⌥L become silent no-ops.
+      // The usual way in is ComponentSection's "edit definition" with the
+      // INSTANCE selected, which is exactly that state.
+      if (defId === state.editingDef) return;
+      set({ editingDef: defId, selection: [], selectedBlock: null });
+      bridge?.setSelection([]);
+    },
+
+    // ---- the component registry (instance layers) ------------------------------
+    async refreshLibrary() {
+      try {
+        const library = await api.listComponents();
+        set({ library, libraryLoaded: true, libraryError: null });
+      } catch (e) {
+        // NOT `error`: a registry that will not answer is a fact about this
+        // panel, and putting it in the document-error strip would read as "your
+        // shot failed to save".
+        set({ libraryError: e instanceof Error ? e.message : String(e) });
+      }
+    },
+
+    async loadContract(componentId) {
+      if (state.contracts[componentId] !== undefined) return;
+      try {
+        const detail = await api.componentDetail(componentId);
+        set({ contracts: { ...store.getState().contracts, [componentId]: detail.contract } });
+      } catch {
+        // Silent: the inspector falls back to the snapshot the document carries,
+        // which is exactly why a snapshot is taken. A component that has left
+        // the project stays editable rather than going dead.
+      }
+    },
+
+    async addInstanceLayer(componentId) {
+      if (!state.libraryLoaded) await store.refreshLibrary();
+      const row = store.getState().library.find((r) => r.id === componentId);
+      if (row === undefined) {
+        store.reportError(`no component ${JSON.stringify(componentId)} in the registry`);
+        return;
+      }
+      if (row.host !== "three") {
+        // The same refusal the save gate makes, made EARLIER so the menu can
+        // never produce a document the server would reject. One rule, two
+        // places it is enforced, and the server's is the authority.
+        store.reportError(
+          `${row.name} is a "${row.host}" component — an instance layer mounts inside the scene's ` +
+            `3D canvas, so only three-class components can be instanced.`,
+        );
+        return;
+      }
+      let detail: api.ComponentDetail;
+      try {
+        detail = await api.componentDetail(componentId);
+      } catch (e) {
+        store.reportError(e instanceof Error ? e.message : String(e));
+        return;
+      }
+      set({ contracts: { ...store.getState().contracts, [componentId]: detail.contract } });
+      const at = insertContext();
+      if (at === null) return;
+      insertLayer(instanceLayer(componentId, row.name, bindingFor(detail), at.ctx));
+    },
+
+    setInstanceProp(layerId, key, value) {
+      patchInstance(layerId, (inst) => ({ ...inst, props: { ...inst.props, [key]: value } }));
+    },
+
+    clearInstanceProp(layerId, key) {
+      patchInstance(layerId, (inst) => {
+        if (!(key in inst.props)) return inst;
+        const props = { ...inst.props };
+        delete props[key];
+        return { ...inst, props };
+      });
+    },
+
+    setInstanceClockOffset(layerId, frames) {
+      const offset = Math.round(frames);
+      patchInstance(layerId, (inst) => {
+        // Absent IS zero everywhere in this lane, and codegen prints the block
+        // by key order — so a present-but-zero key is a key in the emitted file
+        // that says nothing.
+        if (offset === 0) {
+          const { clockOffsetFrames: _drop, ...rest } = inst;
+          return rest;
+        }
+        return { ...inst, clockOffsetFrames: offset };
+      });
+    },
+
+    async rebindInstance(layerId) {
+      const doc = state.doc;
+      const sceneId = state.sceneId;
+      if (doc === null || sceneId === null) return "no document";
+      const layer = doc.scenesById[sceneId]?.layersById[layerId];
+      if (layer === undefined || layer.kind !== "instance") return "not an instance layer";
+      const componentId = layer.instance.component;
+      let detail: api.ComponentDetail;
+      try {
+        detail = await api.componentDetail(componentId);
+      } catch (e) {
+        return e instanceof Error ? e.message : String(e);
+      }
+      set({ contracts: { ...store.getState().contracts, [componentId]: detail.contract } });
+      // The plan is computed against the contract the props were AUTHORED
+      // against (the frozen snapshot when the document carries one), because a
+      // key's last-known KIND is what lets the planner refuse to rebind a curve
+      // onto an asset just because both ride an engine "string" track.
+      const ref = layer.instance.contract;
+      const frozen = ref?.source === "snapshot" ? ref.contract : (store.getState().contracts[componentId] ?? null);
+      const ops = instancePropPlan(layer.instance.props, frozen, detail.contract);
+      patchInstance(layerId, (inst) => ({
+        ...inst,
+        props: applyInstanceRebinds(inst.props, ops),
+        ...bindingFor(detail),
+      }));
+      return null;
+    },
+
+    setScene(sceneId) {
+      // Pinning another scene leaves the isolated subtree off screen exactly as
+      // scrubbing into one does, so it drops through the same helper.
+      const isolation = isolationForScene(sceneId);
+      const wasIsolated = state.isolation;
+      set({ sceneId, isolation, ...(isolation === null ? { isolationOrbit: false } : {}) });
+      if (isolation !== wasIsolated) bridge?.setIsolation(isolation);
+    },
+    setView(view) {
+      set({ view });
+      bridge?.setView(view);
+    },
+    fitView() {
+      const view = bridge?.fitView();
+      if (view !== undefined) set({ view });
+      else set({ view: INITIAL_VIEW });
+    },
+    zoomActivePane(direction) {
+      if (state.activePane === "working") {
+        // Distance is the RECIPROCAL of zoom, so zooming in is dollying in.
+        // The same navigation band the stage's wheel obeys, so a button press
+        // and a notch cannot walk to different places. No document means no fit
+        // to derive it from, and the sanitisation clamp still holds.
+        const bounds = state.doc === null ? undefined : dollyBounds(state.doc.size);
+        store.setWorkingView(
+          dollyBy(state.workingView, direction === 1 ? -WORKING_ZOOM_STEP_PX : WORKING_ZOOM_STEP_PX, bounds),
+        );
+        return;
+      }
+      store.setView({ ...state.view, zoom: clampZoom(state.view.zoom * (direction === 1 ? 1.25 : 0.8)) });
+    },
+    fitActivePane() {
+      if (state.activePane === "working") store.fitWorkingView();
+      else store.fitView();
+    },
+    setStageLayout(layout) {
+      const stageLayout: StageLayout = {
+        mode: layout.mode,
+        splitRatio: clampSplitRatio(layout.splitRatio),
+      };
+      // THE ACTIVE PANE MUST EXIST. Collapsing to one pane while the zoom keys
+      // are pointed at the other would leave ⇧Z fitting a pane nobody can see,
+      // which reads as "the fit shortcut stopped working".
+      const activePane: StagePane =
+        stageLayout.mode === "split" ? state.activePane : stageLayout.mode;
+      // ── FOCUS MODE: the working view minimises the chrome ───────────────
+      //
+      // Entering "working" snapshots the inspector and dock collapse bits and
+      // collapses both — that view is for arranging in 3D, and the inspector
+      // and timeline are about the shot. The RAIL STAYS: the layer tree is
+      // the one panel that view needs. Leaving restores whatever was
+      // snapshotted; a null slot means the author toggled that panel inside
+      // the mode and took ownership (the collapse verbs null the slots), so
+      // their choice survives the exit. ONE set() for the whole switch —
+      // gestures.test.ts counts notifications.
+      const entering = stageLayout.mode === "working" && state.stageLayout.mode !== "working";
+      const leaving = stageLayout.mode !== "working" && state.stageLayout.mode === "working";
+      set({
+        stageLayout,
+        activePane,
+        ...(entering
+          ? {
+              focusRestoreInspector: state.inspectorCollapsed,
+              focusRestoreDock: state.dockCollapsed,
+              inspectorCollapsed: true,
+              dockCollapsed: true,
+            }
+          : {}),
+        ...(leaving
+          ? {
+              ...(state.focusRestoreInspector === null
+                ? {}
+                : { inspectorCollapsed: state.focusRestoreInspector }),
+              ...(state.focusRestoreDock === null ? {} : { dockCollapsed: state.focusRestoreDock }),
+              focusRestoreInspector: null,
+              focusRestoreDock: null,
+            }
+          : {}),
+      });
+      bridge?.setStageLayout(stageLayout);
+    },
+    setWorkingView(workingView) {
+      set({ workingView });
+      bridge?.setWorkingView(workingView);
+      // FOLLOW IS FOLLOW, whatever moved the view. The chrome's keyboard zoom
+      // reaches the working camera without going through the stage's
+      // `onWorkingViewChange`, so leaving it out here made the badge over the
+      // pane say "camera follows this view" while it silently did not — and the
+      // next mouse orbit crossed the whole accumulated gap in one jump.
+      if (state.cameraFollowsView) writeFramingFromView(workingView);
+    },
+    fitWorkingView() {
+      // HOME IS THE RESET, and inside a subtree that means back to the derived
+      // head-on rig rather than to the canvas fit. It is the exact pose the
+      // author entered on, because it goes back to the derivation instead of
+      // trying to represent it in the orbit rig's five numbers.
+      if (state.isolation !== null) {
+        if (!state.isolationOrbit) return;
+        set({ isolationOrbit: false });
+        bridge?.setIsolationOrbit(false);
+        return;
+      }
+      // The STAGE derives it, for the reason `fitView` does: the derivation
+      // depends on the working camera's lens, and the stage owns that lens.
+      const workingView = bridge?.fitWorkingView();
+      if (workingView === undefined) return;
+      set({ workingView });
+      if (state.cameraFollowsView) writeFramingFromView(workingView);
+    },
+    fitWorkingViewToSelection() {
+      const doc = state.doc;
+      const sceneId = state.sceneId;
+      const scene = doc === null || sceneId === null ? undefined : doc.scenesById[sceneId];
+      if (doc === null || scene === undefined) return;
+      // Numpad-dot inside a subtree is the same reset Home is: the derived rig
+      // already frames exactly what the author is inside, so re-deriving a
+      // perspective pose for it would answer a request to go back with a
+      // different view.
+      if (state.isolation !== null) {
+        store.fitWorkingView();
+        return;
+      }
+      // Frame all on an empty selection — the graceful half of the contract.
+      if (state.selection.length === 0) {
+        store.fitWorkingView();
+        return;
+      }
+      // The same derivation `fitCameraToSelection` uses — playhead as input,
+      // the stage's own FIT_MARGIN — pointed at the WORKING view instead of
+      // the document: the box becomes a target and a distance.
+      const sceneFrame = masterToSceneCached(doc, state.frame)?.sceneFrame ?? 0;
+      const box = framingForLayers(scene, state.selection, sceneFrame, doc.fps, doc.size, FIT_MARGIN);
+      if (box === null) {
+        store.fitWorkingView();
+        return;
+      }
+      // KEEPING the author's angles: numpad-dot moves the target and the
+      // distance, never where they stand.
+      // ponytail: the distance frames the box's HEIGHT head on, so it
+      // under-fits slightly at oblique angles; upgrade path is the diagonal
+      // derivation defaultWorkingView uses.
+      const head = workingViewForFraming(box, doc.size);
+      store.setWorkingView({
+        ...head,
+        theta: state.workingView.theta,
+        phi: state.workingView.phi,
+        // …AND THE LENS. `workingViewForFraming` rebuilds a view from scratch
+        // and so carries no `ortho`, which made numpad-dot silently drop an
+        // orthographic pane back to perspective — a fit is a change of DISTANCE
+        // and TARGET, never of projection.
+        ...(state.workingView.ortho === true ? { ortho: true } : {}),
+      });
+    },
+    setActivePane(activePane) {
+      set({ activePane });
+    },
+    setCameraFollowsView(cameraFollowsView) {
+      set({ cameraFollowsView });
+      // The stage needs it to bracket its own orbit and to draw the badge — see
+      // bridgeTypes. Arming it does NOT write anything: the first orbit does,
+      // and an author who armed it by accident can disarm it before moving.
+      bridge?.setCameraFollowsView(cameraFollowsView);
+    },
+    setShadingMode(shadingMode) {
+      // The mode BEFORE this one, so ⇧Z can come back to it. Only when the two
+      // differ: pressing wireframe twice must not make wireframe its own
+      // "previous" and strand the toggle.
+      set({
+        shadingMode,
+        ...(shadingMode === state.shadingMode ? {} : { previousShading: state.shadingMode }),
+      });
+      bridge?.setShadingMode(shadingMode);
+    },
+
+    openMaterialPicker(layerIds) {
+      const sceneId = state.sceneId;
+      const scene = state.doc === null || sceneId === null ? undefined : state.doc.scenesById[sceneId];
+      if (scene === undefined) return;
+      // MESH LAYERS ONLY. A material is a mesh's albedo; there is nothing to
+      // paint on a group or a text plane, and opening a picker over a
+      // selection that cannot take one would be a dialog with no effect.
+      const meshes = layerIds.filter((id) => scene.layersById[id]?.kind === "mesh");
+      if (meshes.length === 0) {
+        set({ error: "A material paints a model's surface, so it needs a mesh layer selected." });
+        return;
+      }
+      set({ materialPicker: { layerIds: meshes }, stageMenu: null });
+    },
+    closeMaterialPicker() {
+      if (state.materialPicker !== null) set({ materialPicker: null });
+    },
+    applyMeshMaterial(layerIds, generatorId) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      const ran = store.edit((doc) => {
+        const scene = doc.scenesById[sceneId];
+        if (scene === undefined) return doc;
+        const layersById = { ...scene.layersById };
+        let changed = false;
+        for (const id of layerIds) {
+          const layer = layersById[id];
+          if (layer === undefined || layer.kind !== "mesh") continue;
+          // PARAMS RESET. A new generator publishes a new vocabulary of keys,
+          // and carrying the old ones forward would leave values under names
+          // the new contract does not have — invisible in the inspector and
+          // written to disk forever.
+          layersById[id] = { ...layer, mesh: { ...layer.mesh, material: { generator: generatorId } } };
+          changed = true;
+        }
+        if (!changed) return doc;
+        return { ...doc, scenesById: { ...doc.scenesById, [sceneId]: { ...scene, layersById } } };
+      });
+      // `edit` has already said HISTORY_BUSY if a drag is holding the scrub;
+      // this clears any stale message once the write actually landed.
+      sayRefusal(ran, null);
+      if (!ran) return;
+      // ── AND SHOW IT ────────────────────────────────────────────────────
+      //
+      // The working pane paints `scene.overrideMaterial = clay` in solid and
+      // wireframe mode, so a material applied there is invisible and the
+      // author's honest reading is "nothing happened". The camera pane already
+      // shows it (it is the export), so this is a working-pane courtesy: one
+      // switch, only from the two modes that hide it, and only when a working
+      // pane is on screen. Workspace state, never a document write.
+      if (
+        state.stageLayout.mode !== "camera" &&
+        (state.shadingMode === "solid" || state.shadingMode === "wireframe")
+      ) {
+        store.setShadingMode("material");
+      }
+      set({ materialPicker: null });
+    },
+    removeMeshMaterial(layerIds) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      const ran = store.edit((doc) => {
+        const scene = doc.scenesById[sceneId];
+        if (scene === undefined) return doc;
+        const layersById = { ...scene.layersById };
+        let changed = false;
+        for (const id of layerIds) {
+          const layer = layersById[id];
+          if (layer === undefined || layer.kind !== "mesh" || layer.mesh.material === undefined) continue;
+          // DELETE THE KEY, never write `undefined`: the document is JSON, and
+          // `material: undefined` survives a spread but not a round trip, so
+          // the two halves would disagree about whether it is set.
+          const { material: _dropped, ...mesh } = layer.mesh;
+          layersById[id] = { ...layer, mesh };
+          changed = true;
+        }
+        if (!changed) return doc;
+        return { ...doc, scenesById: { ...doc.scenesById, [sceneId]: { ...scene, layersById } } };
+      });
+      sayRefusal(ran, null);
+    },
+
+    alignCameraToWorkingView() {
+      writeFramingFromView(state.workingView);
+    },
+    fitCameraToSelection() {
+      const doc = state.doc;
+      const sceneId = state.sceneId;
+      const scene = doc === null || sceneId === null ? undefined : doc.scenesById[sceneId];
+      if (doc === null || scene === undefined) return;
+      if (state.selection.length === 0) {
+        set({ error: "Select the layers you want in shot, then fit the camera to them." });
+        return;
+      }
+      // The PLAYHEAD is an input, exactly as it is for align: bounds are
+      // measured on what is rendered at this frame, so fitting at frame 0 and
+      // at frame 40 are different edits on a layer a block is moving.
+      const sceneFrame = masterToSceneCached(doc, state.frame)?.sceneFrame ?? 0;
+      // The stage's own FIT_MARGIN, so "fit" means one thing in this lane
+      // whether the author fits the view or the camera.
+      const box = framingForLayers(scene, state.selection, sceneFrame, doc.fps, doc.size, FIT_MARGIN);
+      if (box === null) {
+        set({
+          error:
+            "That selection has no width or height at this frame, so there is nothing for the " +
+            "camera to frame.",
+        });
+        return;
+      }
+      writeCamera((current) => ({ ...current, ...box }));
+    },
+    setSceneCamera(patch) {
+      // THROUGH `writeCamera`, which is the whole point: the inspector is a
+      // keyboard frustum. It gets the refusal-by-name under a shot and the
+      // animate fork for free, and there is no second answer to "what does
+      // writing the camera at this frame mean".
+      //
+      // The read side is coherent for free too. `shotOwningCamera` is null
+      // exactly when `cameraAt` returns `scene.camera`, so whenever the base
+      // write is ALLOWED the effective value the fields show IS the base, so a
+      // patch of one field can never carry a stale sibling into the document.
+      writeCamera((current) => ({ ...current, ...patch }));
+    },
+    setShotFraming(shotId, end, patch) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      store.edit((doc) =>
+        patchShotIn(doc, sceneId, shotId, (shot) => {
+          // A path move has no `from` or `to` — its poses are its waypoints,
+          // and there is no waypoint this writer could pick that the author
+          // meant. The inspector does not offer these fields for one, so this
+          // is a no-op rather than a refusal with nowhere to show.
+          if (shot.kind === "path") return shot;
+          const next = clampFraming({ ...shot[end], ...patch });
+          if (sameFraming(next, shot[end])) return shot;
+          return end === "from" ? { ...shot, from: next } : { ...shot, to: next };
+        }),
+      );
+    },
+    setShotKind(shotId, kind) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      store.edit((doc) =>
+        patchShotIn(doc, sceneId, shotId, (shot) =>
+          shot.kind === kind || shot.kind === "path" ? shot : { ...shot, kind },
+        ),
+      );
+    },
+    setShotEase(shotId, ease) {
+      const sceneId = state.sceneId;
+      if (sceneId === null) return;
+      store.edit((doc) => patchShotIn(doc, sceneId, shotId, (shot) => ({ ...shot, ease })));
+    },
+    addShotAtPlayhead(askedFor) {
+      const doc = state.doc;
+      const sceneId = state.sceneId;
+      const scene = doc === null || sceneId === null ? undefined : doc.scenesById[sceneId];
+      if (doc === null || sceneId === null || scene === undefined) return;
+      // EVERY scene's camera row has a "+ shot", and only one of them is under
+      // the playhead. Refused BY NAME rather than quietly retargeted or
+      // silently seeking: "at the playhead" is the whole rule for where a new
+      // thing lands, and a button that moved the playhead to make its own rule
+      // true would be a create with a hidden navigation inside it.
+      if (askedFor !== undefined && askedFor !== sceneId) {
+        set({
+          error:
+            `The playhead is in "${scene.name}", so there is nowhere in ` +
+            `"${doc.scenesById[askedFor]?.name ?? askedFor}" to put a camera move. ` +
+            `Move the playhead into that shot first.`,
+        });
+        return;
+      }
+      // ⇧C is a KEY, so it can arrive mid-drag with no pointer of its own,
+      // which is the hole ⌥C had. `edit` closes a wheel's scrub itself; a
+      // pointer's it cannot, and `transaction()` throws on it.
+      if (gesture !== null || (framing !== null && wheelFraming === null)) {
+        set({ error: HISTORY_BUSY });
+        return;
+      }
+      // AT THE PLAYHEAD, running forward. Deliberately not `writeFraming`'s
+      // "ends at the playhead": that rule belongs to a DRAG, where the pose
+      // under the pointer is the destination the author just chose. Here there
+      // is no pose yet: the author is asking for somewhere to author one, and a
+      // new thing landing anywhere but the playhead is the complaint this whole
+      // lane's timeline was written against.
+      const at = masterToSceneCached(doc, state.frame)?.sceneFrame ?? 0;
+      const covering = scene.shots.find((s) => at >= s.frame && at < s.frame + shotDuration(s));
+      if (covering !== undefined) {
+        set({
+          error:
+            `The camera is already moving here: "${covering.label}" covers frame ${at}. ` +
+            `Edit that move, or put the playhead after it and add another.`,
+        });
+        return;
+      }
+      // Shots are validated non-overlapping and a move past the scene's end
+      // never plays, so the room to the NEXT of those two is the length a move
+      // may have. Clamped rather than refused, because a shorter move is what
+      // the author asked for; only no room at all has no answer.
+      const next = scene.shots.find((s) => s.frame > at)?.frame ?? Infinity;
+      const room = Math.min(next, Math.max(1, Math.trunc(scene.durationFrames))) - at;
+      // Unreachable while `MIN_BLOCK_FRAMES` is 1: the playhead is clamped
+      // inside the scene, so there is always at least one frame of room. It is
+      // here because raising that constant would otherwise turn this clamp into
+      // a silent overlap, which is a document that will not save.
+      if (room < MIN_BLOCK_FRAMES) {
+        set({
+          error:
+            `There is no room for a camera move at frame ${at}: the next move, or the end of the ` +
+            `shot, is too close. Move the playhead earlier, or make the shot longer.`,
+        });
+        return;
+      }
+      const durationFrames = Math.max(
+        MIN_BLOCK_FRAMES,
+        Math.min(room, Math.round((doc.fps.num / doc.fps.den) * NEW_SHOT_SECONDS)),
+      );
+      // FROM EQUALS TO, and equals what is on screen right now. The move is a
+      // no-op until the author drags the frustum or types a field, which is the
+      // correct starting state: creating one must not move the camera.
+      const framingNow = cameraAt(scene, at, doc.fps);
+      const before = new Set(scene.shots.map((s) => s.id));
+      store.edit((d) =>
+        addShot(
+          d,
+          sceneId,
+          {
+            label: "Camera move",
+            // DOLLY, for `writeFraming`'s reason: its distance follows the live
+            // zoom, so a frustum drag on the new shot keeps tracking the value
+            // it writes. `zoom` pins the distance at the shot's start.
+            kind: "dolly",
+            from: framingNow,
+            to: framingNow,
+            frame: at,
+            durationFrames,
+          },
+          "camera-move",
+        ),
+      );
+      // The id is read back rather than re-derived: `addShot` mints it from the
+      // document's used ids, and a second guess at that rule is a second rule.
+      const created = store
+        .getState()
+        .doc?.scenesById[sceneId]?.shots.find((s) => !before.has(s.id));
+      if (created === undefined) return;
+      // Focused AND shown. The inspector's TAB is a view choice (types.ts), so
+      // moving it is safe; `animateMode` is the behaviour bit and stays where
+      // the author left it.
+      set({
+        selectedBlock: { sceneId, layerId: CAMERA_ROW_ID, blockId: created.id },
+        inspectorMode: "animate",
+        // A refusal from the LAST press must not still be on screen over a
+        // press that worked; the strip would read as a second failure.
+        error: null,
+      });
+    },
+    dismissError() {
+      set({ error: null });
+    },
+    reportError(message) {
+      set({ error: message });
+    },
+  };
+
+  return store;
+}
+
+/**
+ * The bits that belong to the AUTHOR'S WORKSPACE rather than to the document.
+ *
+ * They survive a close and a switch, because a zoom level or a collapsed dock
+ * that reset every time you opened a shot would be a setting nobody could keep.
+ * Everything NOT listed here is document state and is reset — which is the half
+ * that matters: leaking a selection or a playhead across documents would point
+ * the editor at layers that no longer exist.
+ */
+function workspacePrefs(state: ShotEditorState): Partial<ShotEditorState> {
+  return {
+    view: state.view,
+    // The split, the orbit and which pane is active are all "where the author
+    // is standing" rather than anything about the shot, so they cross a
+    // document switch with the zoom. They also never dirty the document: no
+    // action here goes through `edit`.
+    stageLayout: state.stageLayout,
+    workingView: state.workingView,
+    activePane: state.activePane,
+    // Follow crosses a document switch with them, and deliberately so: it is a
+    // way of working, not a property of the shot. It writes nothing on its own
+    // — only an orbit does — so carrying it cannot carry an edit with it.
+    cameraFollowsView: state.cameraFollowsView,
+    // How the author looks at the working pane, not anything about the shot.
+    shadingMode: state.shadingMode,
+    tool: state.tool,
+    inspectorMode: state.inspectorMode,
+    animateMode: state.animateMode,
+    dockCollapsed: state.dockCollapsed,
+    railCollapsed: state.railCollapsed,
+    inspectorCollapsed: state.inspectorCollapsed,
+    // The focus-mode restore slots ride with `stageLayout.mode`: the mode
+    // survives a document switch, so the pending restore must survive with
+    // it or "leave working restores the panels" silently breaks after one.
+    focusRestoreInspector: state.focusRestoreInspector,
+    focusRestoreDock: state.focusRestoreDock,
+    railWidth: state.railWidth,
+    dockHeight: state.dockHeight,
+    dockPpf: state.dockPpf,
+    // Monitoring level, not mix level — see ShotEditorState. It survives a
+    // document switch for the same reason the zoom does.
+    previewMuted: state.previewMuted,
+    previewVolume: state.previewVolume,
+  };
+}
+
+function sameIds(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((id, i) => id === b[i]);
+}
+
+function shotDuration(shot: Shot): number {
+  return Math.max(1, Math.trunc(shot.durationFrames));
+}
+
+/**
+ * Patch one shot's NON-TIMING fields.
+ *
+ * timelineOps' own `patchShot` is not reusable here and the reason is worth
+ * stating: it returns the document unchanged unless `frame` or
+ * `durationFrames` moved, because its two callers are the retimers and that
+ * short-circuit is what makes a zero-travel drag cost nothing. A kind, an ease
+ * or a framing edit would be silently dropped by it.
+ *
+ * No re-sort, for the mirror-image reason: nothing here touches `frame`, so the
+ * order `cameraAt` walks cannot change. A caller that ever does move a shot
+ * must use `moveShot`, which re-sorts.
+ */
+function patchShotIn(
+  doc: Doc3D,
+  sceneId: string,
+  shotId: string,
+  next: (shot: Shot) => Shot,
+): Doc3D {
+  const scene = doc.scenesById[sceneId];
+  if (scene === undefined) return doc;
+  const at = scene.shots.findIndex((s) => s.id === shotId);
+  if (at < 0) return doc;
+  const shot = scene.shots[at]!;
+  const updated = next(shot);
+  // Identity when nothing changed, so a field that re-committed the value it
+  // was showing costs no history entry and no save.
+  if (updated === shot) return doc;
+  const shots = [...scene.shots];
+  shots[at] = updated;
+  return { ...doc, scenesById: { ...doc.scenesById, [sceneId]: { ...scene, shots } } };
+}
+
+/** The clamp camera.ts's `sanitise` applies, on the one field whose bad values
+ *  an author cannot type their way out of: a zoom of 0 is an infinite distance,
+ *  and validation would refuse the whole document at save rather than the field
+ *  at the point of the edit. */
+function clampFraming(framing: Framing): Framing {
+  return {
+    ...framing,
+    zoom: Math.max(MIN_FRAMING_ZOOM, Math.min(MAX_FRAMING_ZOOM, framing.zoom)),
+  };
+}
+
+function sameFraming(a: Framing, b: Framing): boolean {
+  return (
+    a.x === b.x && a.y === b.y && a.zoom === b.zoom && a.rollDeg === b.rollDeg && a.focusZ === b.focusZ
+  );
+}
+
+/** "hero shot" -> "HeroShot". The generated component's name, which must be a
+ *  valid identifier; the STORE name keeps whatever the author typed. */
+export function pascalCase(input: string): string {
+  const parts = input.split(/[^A-Za-z0-9]+/).filter((p) => p.length > 0);
+  const joined = parts.map((p) => p[0]!.toUpperCase() + p.slice(1)).join("");
+  return /^[A-Za-z]/.test(joined) ? joined : `Shot${joined}`;
+}
+
+/** An asset kind as it reads INSIDE the refusal sentence "<file> is not …".
+ *  Total over the union, so a kind added to the schema cannot reach a picker
+ *  without an answer here. */
+const KIND_NAMES: Record<ShotAssetKind, string> = {
+  image: "an image",
+  video: "a video",
+  audio: "audio",
+  model: "a model (.glb / .gltf)",
+  font: "a font",
+};
+
+/** …and the list, joined so a two-kind picker reads as a sentence rather than
+ *  as an array. */
+function kindsPhrase(kinds: readonly ShotAssetKind[]): string {
+  const names = kinds.map((k) => KIND_NAMES[k]);
+  const last = names.pop();
+  if (last === undefined) return "a supported asset";
+  return names.length === 0 ? last : `${names.join(", ")} or ${last}`;
+}
+
+/** "Hero Shot" -> "hero-shot", for the document id. */
+export function slug(input: string): string {
+  return (
+    input
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "shot"
+  );
+}
+
+