@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/app/App.tsx

@@ -3,7 +3,7 @@
 // ── THE ONE STRUCTURAL RULE ──────────────────────────────────────────────
 //
 // `<StagePanel>` is the UNCONDITIONAL, UNKEYED FIRST CHILD of the shell root,
-// and every panel floats over it. Nothing this component renders may reorder,
+// and every panel is docked over it. Nothing this component renders may reorder,
 // reparent, key or conditionally wrap it, because a remount costs a full iframe
 // document load, a fresh WebGPU adapter request, every layer raster redrawn and
 // a dead stage for at least one connect poll. `test/stageIdentity.test.tsx`
@@ -15,71 +15,222 @@
 // element a containing block for fixed-position descendants, and the iframe is
 // `position: fixed; inset: 0`; the failure is the stage silently sizing itself
 // to a panel instead of the viewport.
-import { useCallback, useEffect, useRef, useState } from "react";
-import { FilePanel } from "../panels/files/FilePanel.js";
-import { HelpSection } from "../panels/help/HelpSection.js";
+import { Activity, useCallback, useEffect, useRef, useState } from "react";
+import { PanelBoundary, useToasts } from "@dailies-studio/ui";
+import type { ToastHandle } from "@dailies-studio/ui";
+import { requestEditAccess } from "../api.js";
+import { LeftColumn } from "../panels/files/LeftColumn.js";
+import { MissingAssetsNotice } from "../panels/files/MissingAssetsNotice.js";
 import { ResizeHandle } from "../panels/ResizeHandle.js";
-import { RAIL_WIDTH } from "../state/panelSize.js";
+import {
+  CANVAS_MIN,
+  INSPECTOR_WIDTH,
+  RAIL_WIDTH,
+  boardColumns,
+  fitShell,
+  layoutFor,
+  toolFooterShown,
+} from "../state/panelSize.js";
+import { CellSlot, CellSlotsProvider } from "../panels/stage/cellSlots.js";
+import { VIEW_ONLY, boardRightPanel, componentEditOpen, componentsHideTimeline, workspaceOf } from "../state/workspace.js";
+import { splitRatioAt, splitX } from "../stage/panes.js";
 import { Header } from "../panels/header/Header.js";
-import { InspectorPanel } from "../panels/inspector/InspectorPanel.js";
+import { SyncQuotaBanner } from "../panels/header/StatusBadges.js";
+import { SyncDeletedDialog } from "../panels/header/SyncDeletedDialog.js";
+import { RightColumn } from "../panels/inspector/RightColumn.js";
 import { StagePanel } from "../panels/stage/StagePanel.js";
 import { TimelineDock } from "../panels/timeline/TimelineDock.js";
-import { ToolDockBar } from "../panels/toolbar/ToolDockBar.js";
-import { ViewModeBar } from "../panels/toolbar/ViewModeBar.js";
-import { ShadingBar } from "../panels/toolbar/ShadingBar.js";
-import { CameraViewBar } from "../panels/toolbar/CameraViewBar.js";
-import { ExportDialog } from "../panels/export/ExportDialog.js";
+import { ToolFooter } from "../panels/toolbar/ToolFooter.js";
+import { CanvasBar } from "../panels/toolbar/CanvasBar.js";
 import { StageMenu } from "../panels/stage/StageMenu.js";
-import { MaterialPicker } from "../panels/material/MaterialPicker.js";
-import { AgentPanel } from "../panels/agent/AgentPanel.js";
+import { StillThumbsProvider, stillThumbsActive } from "../panels/storyboard/StillThumbs.js";
+import {
+  CodeStudio,
+  ComponentStudio,
+  ComponentsPreview,
+  ExportDialog,
+  LibraryBrowser,
+  AgentQuestionDialog,
+  MaterialWorkspace,
+  StoryboardView,
+  prefetchStoryboard,
+  prefetchInspectorSections,
+} from "./lazySurfaces.js";
+import { whenIdle } from "./lazyPanel.js";
 import { AudioPreviewBridge } from "../audio/index.js";
+import { ExportScrim } from "../panels/export/ExportScrim.js";
 import { subscribeStudioEvents } from "../state/renderEvents.js";
+import { reportStageFailures } from "../state/errorReports.js";
+import { startPosterCapture } from "../state/posterCapture.js";
+import { bootOpenFor, wantedDocOf } from "../state/bootOpen.js";
 import { useShotEditor, useStore } from "../state/context.js";
+import { useUnsavedWorkGuard } from "../state/unsavedGuard.js";
+import { useAccountPrefs } from "../state/accountPrefs.js";
+import { shownLayoutMode } from "../state/viewMode.js";
+import { CURRENT_SHOT_SCHEMA_VERSION } from "@dailies-studio/shot/doc";
 import type { StageInset } from "../bridgeTypes.js";
+import type { ShotEditorState } from "../state/types.js";
+
+/**
+ * The two halves disagreeing about the schema, said in a sentence.
+ *
+ * DERIVED FROM THE OPEN DOCUMENT, never stored, and that is the whole point.
+ * It began as one `set({ error })` at load, which is how every other message
+ * in this shell works — and it was wrong for this one, because `state.error`
+ * is transient by design: `beginScrub` and `openMaterialWorkspace` both clear
+ * it, so the warning was gone by the author's second gesture and stayed gone
+ * while every save the session would attempt was still doomed.
+ *
+ * A condition that lasts until a process is restarted has to be said for as
+ * long as it lasts. Derived, it cannot be dismissed, it cannot go stale, and
+ * it disappears by itself the moment a document at the right version loads.
+ *
+ * ── WHY IT IS A WARNING AND NOT A LOCKED DOOR ──────────────────────────
+ *
+ * The document is readable and everything in it is real; the editor simply
+ * cannot save what it is about to let the author build. Refusing to open it
+ * would take away the one thing that still works. So: keep working, and know.
+ */
+export function schemaMismatchNotice(version: number | null): string | null {
+  if (version === null || version === CURRENT_SHOT_SCHEMA_VERSION) return null;
+  return version < CURRENT_SHOT_SCHEMA_VERSION
+    ? `The dev server is older than this editor: it migrated this document to schema ${version}, and the editor is at ${CURRENT_SHOT_SCHEMA_VERSION}. Saves will be refused (and new node kinds rejected) until you restart it: stop it and run \`dailies dev\` again.`
+    : `This editor is older than the dev server: the document is at schema ${version} and the editor is at ${CURRENT_SHOT_SCHEMA_VERSION}. Rebuild it: \`pnpm --filter @dailies-studio/shot-editor build\`.`;
+}
+
+/** Components with nothing in the right column: the home, unless Agent or
+ *  Comments is open (`boardRightPanel`). The column is drawn 0 wide and its
+ *  resize handle is not mounted. The Version history takes the panel width. */
+function componentsColumnEmpty(s: ShotEditorState): boolean {
+  return workspaceOf(s) === "components" && !s.versionsOpen && boardRightPanel(s) === null;
+}
 
 export function App() {
   const store = useStore();
   const [stageError, setStageError] = useState<string | null>(null);
-  const onConnectError = useCallback((message: string | null) => setStageError(message), []);
+  const onConnectError = useCallback(
+    (message: string | null) => setStageError(message),
+    [],
+  );
 
   const name = useShotEditor((s) => s.name);
   const error = useShotEditor((s) => s.error);
   const reportedStageError = useShotEditor((s) => s.stageError);
   const exportOpen = useShotEditor((s) => s.exportOpen);
-  const agentOpen = useShotEditor((s) => s.agentOpen);
+  const materialWorkspace = useShotEditor((s) => s.materialWorkspace);
+  // An open definition is always the Components workspace. Its Edit tab is
+  // the editor (mock C6): the layers outline in the left column, the tool
+  // footer and the def timeline (`componentEditOpen`).
+  const componentStudio = useShotEditor((s) => s.editingDef !== null);
+  const componentEdit = useShotEditor(componentEditOpen);
+  // The OTHER family's studio. Mutually exclusive with the one above by
+  // construction: each entry clears the other's subject, so the two
+  // `.stage-window` holes can never both be mounted and `measureInset` can
+  // never have to choose.
+  const codeStudio = useShotEditor((s) => s.codeComponent !== null);
+  // The fourth mode, the storyboard. Its preview is a hole in the bottom row.
+  const storyboardOpen = useShotEditor((s) => s.storyboardOpen);
+  const stillsActive = useShotEditor(stillThumbsActive);
+  // WHICH WORKSPACE, for the one class every mode rule keys on (`is-mode`):
+  // the four legacy classes above stay, because tests and the CLI's e2e read
+  // them, and each mode's own rules are about that mode alone.
+  const workspace = useShotEditor(workspaceOf);
+  // Components without the timeline: nothing open, the Preview tab (its
+  // transport is in the canvas cell), or a code component (its Edit tab has
+  // its own footer). Only a Studio-made component's Edit tab keeps it.
+  const componentsEmpty = useShotEditor(componentsHideTimeline);
+  // And the right column with nothing in it there (the home): 0 wide, no seam.
+  const columnEmpty = useShotEditor(componentsColumnEmpty);
+  // THE TOOL FOOTER'S ROW, opened by a class in the same commit that mounts
+  // the footer (see `.shell.has-tool-footer` in styles/shell.css). One
+  // predicate for the class, the mount, the inset's edge and the dock's ceiling.
+  const footerShown = useShotEditor(toolFooterShown);
+  // Preferences > Canvas > Toolbar position: the same row, moved above the
+  // stage (`.shell.tool-footer-top` in styles/shell.css).
+  const footerTop = useShotEditor((s) => s.toolbarPosition === "top");
+  // The VERSION alone and not the document: this re-renders the shell, and
+  // subscribing to `doc` here would do it on every keystroke.
+  const schemaNotice = schemaMismatchNotice(
+    useShotEditor((s) => s.doc?.schemaVersion ?? null),
+  );
+  const saveConflict = useShotEditor((s) => s.saveConflict);
 
   useOpenFromUrl();
   useKeymap();
   useExternalChangeRelay();
+  useWindowDropGuard();
+  // Hosted only: the editor prefs on the account (boot merge, then saves).
+  useAccountPrefs();
 
   // Subscribed for the WHOLE session, not while the dialog is open: closing the
   // dialog must not stop the render or lose its progress, and the header badge
   // reads the same store bit.
   useEffect(() => subscribeStudioEvents(store), [store]);
+  // Hosted only: what breaks on the stage reaches the admin panel.
+  useEffect(() => reportStageFailures(store), [store]);
+
+  // The browser's own close confirmation, while anything is not on disk. See
+  // unsavedGuard.ts: a failed save deliberately does not retry, so the
+  // in-memory document IS the only copy until the author acts on it.
+  useUnsavedWorkGuard(
+    useShotEditor((s) => s.dirty),
+    useShotEditor((s) => s.saveState),
+    useShotEditor((s) => s.syncUnstored),
+  );
 
-  const railCollapsed = useShotEditor((s) => s.railCollapsed);
+
+  // A debounced hosted-lane poster attempt after a save settles: the stage
+  // captures the poster frame through the Tier-1 exact capture and it is
+  // uploaded for the dashboard card. Owed until it lands (see posterCapture.ts);
+  // every failure stays silent and the card keeps its gradient.
+  useEffect(() => startPosterCapture({ store }), [store]);
+
+  // THE OTHER MAIN WORKSPACE, FETCHED AT IDLE. Studio is in the entry; the
+  // Storyboard is a chunk (lazySurfaces.tsx). Fetched once the first paint is
+  // done, so switching to it is as quick as it was when it shipped in the
+  // entry, and never on the boot's critical path. A failure is silent: the
+  // board fetches again when it opens, and says so there if it cannot. The
+  // inspector's two template sections come at the same idle moment, so the
+  // first text, image or video layer selected draws its Template field.
+  useEffect(
+    () =>
+      whenIdle(() => {
+        if (workspaceOf(store.getState()) !== "storyboard") prefetchStoryboard().catch(() => {});
+        prefetchInspectorSections().catch(() => {});
+      }),
+    [store],
+  );
+
+  // THE INSERT DRAWER SHOWS THE RAIL: it docks in the left column, so a
+  // collapsed rail draws open while it is up, without writing the author's
+  // collapse (it comes back when the drawer closes).
+  const railCollapsed = useShotEditor((s) => s.railCollapsed && (s.insertDrawer === null || s.readOnly));
   const inspectorCollapsed = useShotEditor((s) => s.inspectorCollapsed);
   // The MODE alone, not the whole layout: the divider's own drag writes the
-  // ratio dozens of times a second, and subscribing to that here would
+  // split ratio dozens of times a second, and subscribing to that here would
   // re-render the entire shell on every frame of it. `--split-x` carries the
   // position, written imperatively beside `--rail-w`.
-  const stageLayout = { mode: useShotEditor((s) => s.stageLayout.mode) };
+  //
+  // WHAT IS ON SCREEN, not what is chosen: Video draws the frame over the
+  // author's split without writing it, so the seam handle would otherwise be
+  // left lying across a picture with no seam under it.
+  const stageLayout = { mode: useShotEditor(shownLayoutMode) };
 
-  // The dragged sizes reach CSS as variables on the shell, which is what lets
-  // the control strip and the timeline dock position themselves off the rail
-  // without any of the three knowing about the others.
+  // The dragged sizes reach CSS as variables on the shell, and the variables
+  // ARE the grid's tracks: `--rail-w`, `--inspector-w` and `--dock-row-h`.
   //
-  // WRITTEN IMPERATIVELY, OUTSIDE REACT. The values exist only to become two
+  // WRITTEN IMPERATIVELY, OUTSIDE REACT. The values exist only to become
   // custom properties, and subscribing them here re-rendered the entire shell
   // — every panel, every dock row — on every pointermove of a resize drag,
-  // to do a style write. A raw store subscription writes the same two
-  // variables and renders nothing.
+  // to do a style write. A raw store subscription writes the same variables
+  // and renders nothing.
   //
-  // `--rail-w` is omitted while the rail is collapsed ON PURPOSE: an inline
-  // style beats a class rule, so writing it unconditionally would override
-  // `.is-rail-collapsed { --rail-w: 0px }` and the strip would keep a gap
-  // where the hidden rail used to be.
+  // THROUGH `fitShell`, which is display only: a window too small for the
+  // stored sizes shows smaller tracks, and the stored ones come back when the
+  // window can hold them. A collapsed column keeps its track (the canvas spans
+  // over it in CSS), so these are written unconditionally.
   const shellRef = useRef<HTMLDivElement | null>(null);
+  const shownShell = () => fitShell(window.innerWidth, window.innerHeight, store.getState());
   useEffect(() => {
     const el = shellRef.current;
     if (el === null) return;
@@ -91,31 +242,106 @@ export function App() {
     // is a FORCED LAYOUT, and this is a raw store subscription — so it ran once
     // per playback frame, for four numbers that a seek cannot possibly change.
     //
-    // These seven fields are every piece of state that moves an edge. `name` is
-    // on the list because the header's title is content-sized and a long
-    // document name wraps the strip; the window's own resize comes through the
-    // ResizeObserver instead, which forces the measure outright.
+    // These fields are every piece of state that moves an edge. The window's
+    // own resize comes through the ResizeObserver instead, which forces the
+    // measure outright.
     let lastEdges = "";
     const edgesOf = (s: ReturnType<typeof store.getState>): string =>
       [
         s.railCollapsed,
+        s.insertDrawer === null,
         s.inspectorCollapsed,
         s.dockCollapsed,
         s.railWidth,
         s.dockHeight,
         s.agentOpen,
+        s.inspectorWidth,
+        // The tool footer opens and closes its own grid row, and its top is
+        // the inset's bottom edge. Its own predicate, plus the two fields that
+        // can move an edge while that answer stays the same.
+        toolFooterShown(s),
+        // And which edge it eats: the toolbar position pref moves it.
+        s.toolbarPosition,
+        s.enteredScene ?? "",
         s.name,
+        s.materialWorkspace?.layerId ?? "",
+        s.materialColumnWidth,
+        s.codeLiveWidth,
+        // The modes can MOVE the hole without mounting or unmounting it: a
+        // subject change re-lays the canvas cell around one continuous
+        // `.stage-window`.
+        // The querySelector bit below only says whether A hole exists, so
+        // without these keys the measure was skipped and the stage kept
+        // framing the subject into the old rect.
+        s.codeComponent ?? "",
+        s.editingDef ?? "",
+        // Components' Preview | Edit swaps the hole for the studio's.
+        s.componentsTab,
+        // The board's right cell opens, closes and changes width with its
+        // occupant (`boardColumns`).
+        boardRightPanel(s) ?? "",
+        s.versionsOpen,
+        // A workspace swap moves content between cells without mounting or
+        // unmounting a shell child, so the child-list observer below cannot
+        // see it: the workspace itself is an edge.
+        workspaceOf(s),
       ].join("|");
     const write = (force: boolean): void => {
       raf = 0;
       const s = store.getState();
-      if (s.railCollapsed) el.style.removeProperty("--rail-w");
-      else el.style.setProperty("--rail-w", `${s.railWidth}px`);
-      el.style.setProperty("--dock-h", `${s.dockHeight}px`);
+      const fit = fitShell(window.innerWidth, window.innerHeight, s);
+      const ws = workspaceOf(s);
+      // THE BOARD DRAWS ITS COLUMNS AT DISPLAY WIDTHS (`boardColumns`): no
+      // rail, and the right cell only while it has an occupant, at 320, or 400
+      // for the component sheet. None of it is
+      // written back to `inspectorWidth` or `railWidth`, so Studio keeps the
+      // author's own sizes. The Version history takes the panel width.
+      const board = ws === "storyboard" ? boardColumns(window.innerWidth, s.versionsOpen ? "inspector" : boardRightPanel(s)) : null;
+      el.style.setProperty("--rail-w", `${board?.railWidth ?? fit.railWidth}px`);
+      // The Components home has no right cell either: the card grid runs to
+      // the window's edge.
+      const inspectorW = board?.inspectorWidth ?? (componentsColumnEmpty(s) ? 0 : fit.inspectorWidth);
+      el.style.setProperty("--inspector-w", `${inspectorW}px`);
+      // No document, no timeline (TimelineDock renders nothing): the bottom
+      // row closes rather than showing the stage through an empty cell. The
+      // board is one canvas to the window's foot, so it closes there too.
+      // Components closes it too, except on a Studio-made component's Edit
+      // tab (`componentsHideTimeline`).
+      const row = s.doc === null || ws === "storyboard" || componentsHideTimeline(s) ? 0 : fit.dockRow;
+      el.style.setProperty("--dock-row-h", `${row}px`);
+      // The material workspace's object: the stored width of its hole at the
+      // right of the canvas cell (material.css caps it at half the cell).
+      el.style.setProperty("--material-col-w", `${s.materialColumnWidth}px`);
+      // A code component's live pane, beside the code (code.css).
+      el.style.setProperty("--code-live-w", `${s.codeLiveWidth}px`);
       // Where the stage's own divider is, so the handle can sit on it without
       // the shell re-rendering per frame of the drag.
-      el.style.setProperty("--split-x", `${Math.round(s.stageLayout.splitRatio * window.innerWidth)}px`);
-      const edges = edgesOf(s);
+      //
+      // THROUGH `splitX`, WITH THE INSET, which is the same call the renderer's
+      // scissor makes — the seam divides the canvas the author can SEE rather
+      // than the window. Doing the arithmetic here as well is how the handle
+      // and the seam it claims to sit on drift a column apart.
+      el.style.setProperty(
+        "--split-x",
+        `${splitX(s.stageLayout.splitRatio, window.innerWidth, s.stageInset)}px`,
+      );
+      // ── AND ONE BIT THAT IS NOT STATE ────────────────────────────────
+      //
+      // Whether the stage's WINDOW is mounted. In the material mode the stage
+      // is visible through exactly one element and nowhere else, and that
+      // element appears the moment the mesh gets a graph — a document write,
+      // with every field above it unchanged. So the edge list alone said
+      // "nothing moved", the measure was skipped, and the object rendered
+      // somewhere behind the mode instead of into the hole left for it.
+      //
+      // A `querySelector` and not a store field, because the honest question is
+      // about the DOM: no bit of state means "the hole is up" without deriving
+      // it a second way and being wrong when the two disagree. It costs one
+      // selector match per store notification and forces no layout — the
+      // rect is only read past the early return below.
+      // The dock row as DRAWN, too: an untouched dock fits its folded content
+      // (`fitShell`), so a document write can move the bottom edge alone.
+      const edges = `${edgesOf(s)}|${fit.dockRow}|${el.querySelector(STAGE_WINDOW) === null ? 0 : 1}`;
       if (!force && edges === lastEdges) return;
       lastEdges = edges;
       // ── AND THE STAGE IS TOLD WHERE IT IS COVERED ────────────────────
@@ -124,15 +350,28 @@ export function App() {
       // panes are the whole window and it cannot see any of this. It used to
       // carry a hardcoded 116 for the top edge and nothing at all for the
       // other three, which put two mode bars behind the opaque header and the
-      // G / R / S pill behind the 232px left rail — where it has never once
-      // been visible in the default layout.
+      // stage's G / R / S readout behind the 232px left rail, where it had
+      // never once been visible in the default layout.
       //
-      // MEASURED, not derived from the CSS constants. `.control-strip` is
-      // `flex-wrap: wrap` and grows past any constant on a narrow window, and
-      // `.timeline-dock` is content-driven under a max-height. Reading the
-      // boxes is both shorter than reproducing the layout and correct when
-      // someone changes it.
-      store.stage()?.setStageInset(measureInset(el));
+      // MEASURED, not derived from the track sizes: the modes swap their own
+      // holes in, the control strip wraps, and reading the boxes is both
+      // shorter than reproducing the layout and correct when someone changes
+      // it.
+      // THROUGH THE STORE, not straight down the bridge. This runs at mount,
+      // where `store.stage()` is still null because the iframe has not
+      // connected — so the push was simply dropped, and nothing re-sent it
+      // until a panel edge happened to move. The store remembers it and
+      // re-pushes it on every attach with the rest of the workspace.
+      const inset = measureInset(el, store.getState().toolbarPosition);
+      store.setStageInset(inset);
+      // The scrims cover exactly what the author can see of the stage, which
+      // is the inset: every box around the picture is docked now, the tool
+      // footer included, so what frames the picture and what covers it are
+      // one rect.
+      el.style.setProperty("--window-t", `${inset.top}px`);
+      el.style.setProperty("--window-r", `${inset.right}px`);
+      el.style.setProperty("--window-b", `${inset.bottom}px`);
+      el.style.setProperty("--window-l", `${inset.left}px`);
     };
     // COALESCED TO THE FRAME. This is a raw store subscription so it fires on
     // every pointermove of a panel resize, and `getBoundingClientRect` is a
@@ -148,156 +387,609 @@ export function App() {
       });
     };
     write(true);
-    const unsubscribe = store.subscribe(() => schedule(false));
+    // The COLD channel: every edge above is a cold field, so a transport
+    // tick can move none of them, and the raw channel ran this measure (a
+    // state read, a join and a `querySelector`) sixty times a second during
+    // playback to find that out. The observers below cover what the store
+    // cannot see.
+    const unsubscribe = store.subscribeCold(() => schedule(false));
+    // ── AND A WINDOW THAT CHANGES SIZE GETS THE LAYOUT FOR ITS NEW SIZE ──
+    //
+    // `bootLayout` fits the three panels to the window once, at startup. A
+    // window can change size afterwards — a laptop docked to a monitor, a
+    // split-screen tile — and leaving the boot sizes there would keep a 1366
+    // laptop's 200px rail on a 2560 display for the rest of the session.
+    //
+    // ONLY WHAT THE AUTHOR HAS NOT TOUCHED. The test is whether a panel still
+    // holds exactly the number `layoutFor` last gave it: a dragged panel is
+    // some other number and is left alone forever after, which is the whole
+    // rule and needs no flag to record it. A drag that happens to land on the
+    // fitted value to the pixel is indistinguishable from no drag, and being
+    // re-fitted is the right answer for it anyway.
+    let fitted = layoutFor(window.innerWidth, window.innerHeight);
+    const refit = (): void => {
+      const next = layoutFor(window.innerWidth, window.innerHeight);
+      const s = store.getState();
+      if (s.railWidth === fitted.railWidth) store.setRailWidth(next.railWidth);
+      if (s.inspectorWidth === fitted.inspectorWidth)
+        store.setInspectorWidth(next.inspectorWidth);
+      if (s.dockHeight === fitted.dockHeight)
+        store.setDockHeight(next.dockHeight);
+      fitted = next;
+    };
     // The store cannot see a WINDOW resize, and that is exactly when the
     // control strip wraps and the top edge moves — so its tick FORCES the
     // measure rather than asking the store whether anything changed.
-    const observer = new ResizeObserver(() => schedule(true));
+    const observer = new ResizeObserver(() => {
+      refit();
+      schedule(true);
+    });
     observer.observe(el);
+    // ── AND A PANEL THAT ARRIVES AFTER THE MEASURE WAS SCHEDULED ─────────
+    //
+    // A RACE, and the losing side is unrecoverable. Everything above schedules
+    // the measure from STATE: the store notifies, `edgesOf` says an edge could
+    // have moved, and a frame is booked. But the panels themselves arrive when
+    // REACT COMMITS, and nothing orders that commit against the booked frame —
+    // opening a document sets `name` synchronously, and whether the rail, the
+    // inspector and the dock are in the DOM by the time the callback runs is a
+    // question about React's scheduler, not about this code.
+    //
+    // Losing that race is permanent, which is what makes it worth closing.
+    // `edgesOf` is a list of state, and no state changes when a panel finishes
+    // mounting, so a measure taken one frame early is never retried: the stage
+    // spends the session believing the inspector and the dock are not there,
+    // and everything derived from the inset — the overlay's furniture, the
+    // head-on framing, the split seam — is quietly wrong by the width of a
+    // panel. It reads as "the framing is a bit off", never as a bug.
+    //
+    // The commit IS the signal: a panel appearing or disappearing is a change
+    // to the shell's own child list, so this fires after it, whichever way the
+    // race went. DIRECT CHILDREN ONLY, and that is what makes it affordable —
+    // every panel the inset is measured from is a child of the shell, while a
+    // `subtree` observer would fire on every timeline row and every inspector
+    // keystroke and force a layout read for each, sixty times a second during
+    // playback, for four numbers a seek cannot move.
+    const panels = new MutationObserver(() => schedule(true));
+    panels.observe(el, { childList: true });
     return () => {
       if (raf !== 0) cancelAnimationFrame(raf);
       unsubscribe();
       observer.disconnect();
+      panels.disconnect();
     };
   }, [store]);
 
   return (
-    <div
-      ref={shellRef}
-      className={`shell${railCollapsed ? " is-rail-collapsed" : ""}${
-        inspectorCollapsed ? " is-inspector-collapsed" : ""
-      }`}
-    >
-      {/* FIRST, unconditional, unkeyed. See the header. */}
-      <StagePanel onConnectError={onConnectError} />
-
-      <Header />
-      <aside className="left-rail">
-        <FilePanel />
-        {/* Pinned to the rail's bottom (margin-top: auto) — the manual lives in
-            the corner that is otherwise empty, and stays put when the layer
-            tree grows because the rail scrolls as one column. */}
-        <HelpSection />
-      </aside>
-      {/* A SIBLING of the rail, not a child: the rail scrolls, and a handle
-          inside a scrolling box scrolls away from the edge it is supposed to
-          be on. Positioned off the same --rail-w the rail's width comes from,
-          so the two cannot disagree. */}
-      {railCollapsed ? null : (
-        <ResizeHandle
-          axis="x"
-          getValue={() => store.getState().railWidth}
-          sign={1}
-          onChange={(w) => store.setRailWidth(w)}
-          onReset={() => store.setRailWidth(RAIL_WIDTH.default)}
-          className="rail-resize"
-          label="Resize the left panel"
-        />
-      )}
-      {/* ── THE SPLIT DIVIDER DRAGS ────────────────────────────────────────
-          `splitRatio` has been in the schema, clamped twice and read by the
-          scissor since the split landed, and NOTHING ever moved it: the stage
-          drew a 1px seam and `panes.ts`'s header claimed the chrome laid out a
-          handle from the same rects. It did not.
-
-          CHROME-SIDE, because a stage-side handle needs a new stage-to-chrome
-          bridge message AND `pointerEvents: auto` inside an overlay whose
-          `pointerEvents: none` is a stated invariant — without it every drag
-          would end the moment the cursor crossed the divider.
-
-          Against `window.innerWidth`, which IS the pane width: the stage iframe
-          is pinned `inset: 0`, so its viewport is the whole window (panes.ts).
-          `clampSplitRatio` and `setStageLayout` already bound the value twice,
-          so there is no third validation here. */}
-      {stageLayout.mode !== "split" ? null : (
-        <ResizeHandle
-          axis="x"
-          getValue={() => store.getState().stageLayout.splitRatio * window.innerWidth}
-          sign={1}
-          onChange={(px) =>
-            store.setStageLayout({
-              ...store.getState().stageLayout,
-              splitRatio: px / Math.max(1, window.innerWidth),
-            })
-          }
-          onReset={() => store.setStageLayout({ ...store.getState().stageLayout, splitRatio: 0.5 })}
-          className="split-resize"
-          label="Resize the split"
-        />
-      )}
-      {/* ONE control strip along the top of the stage. These three were three
-          separately-positioned floats — tools centred on the bottom edge, the
-          view modes and camera verbs stacked at the top left — which cost the
-          bottom of the frame to a bar and split "what am I doing" across two
-          corners. As one flex row they read left to right in the order a
-          gesture is decided: which pane, what the camera does, which tool. */}
-      <div className="control-strip">
-        <ViewModeBar />
-        <ShadingBar />
-        <CameraViewBar />
-        <ToolDockBar />
-      </div>
-      {agentOpen ? <AgentPanel /> : <InspectorPanel />}
-      <TimelineDock />
-      {/* Renders nothing. Mounted HERE and not in the stage: audio is not part
-          of the document, and the stage is a GL iframe that must never
-          remount. Unconditional, so it survives every shell state. */}
-      <AudioPreviewBridge />
-
-      {exportOpen && name !== null && <ExportDialog onClose={() => store.setExportOpen(false)} />}
-
-      {/* Both portal out of the layout, so they hang here rather than inside a
-          panel: the stage menu opens over whichever half was right-clicked, and
-          the picker is a mode over the whole shell. Unconditional, because each
-          renders nothing until its own state field is set. */}
-      <StageMenu />
-      <MaterialPicker />
-
-      {name === null ? (
-        <div className="empty-state">
-          <h1>Dailies shot</h1>
-          <p>Open a scene, or create one, to start.</p>
-        </div>
-      ) : null}
-
-      <div className="overlay-strip" role="status" aria-live="polite">
-        {[stageError, reportedStageError, error].filter((m): m is string => m !== null).map((message) => (
-          <div key={message} className="overlay-message">
-            <span>{message}</span>
-            <button type="button" onClick={() => store.dismissError()} title="Dismiss">
-              ×
-            </button>
+    // THE BOARD'S STILL QUEUE wraps the cells, so the strip (a cell portal)
+    // and the inspector's Move section (a shell child) share one queue. It is
+    // a stable wrapper, so the shell under it never remounts; `active` makes
+    // the queue only while the board is open or the Brief shows its sketches.
+    <StillThumbsProvider active={stillsActive}>
+      <CellSlotsProvider>
+        <div
+          ref={shellRef}
+          className={`shell${railCollapsed ? " is-rail-collapsed" : ""}${
+            inspectorCollapsed ? " is-inspector-collapsed" : ""
+          }${
+            materialWorkspace === null ? "" : " is-material-workspace"
+          }${componentStudio ? " is-component-studio" : ""}${componentEdit ? " is-component-edit" : ""}${
+            codeStudio ? " is-code-studio" : ""
+          }${componentsEmpty ? " is-components-empty" : ""}${storyboardOpen ? " is-storyboard" : ""}${workspace === "stage" ? "" : " is-mode"}${
+            footerShown ? " has-tool-footer" : ""
+          }${footerTop ? " tool-footer-top" : ""}`}
+        >
+          {/* FIRST, unconditional, unkeyed. See the header. */}
+          <StagePanel onConnectError={onConnectError} />
+
+          <Header />
+          {/* A BOUNDARY EACH, and OUTSIDE the mode rather than inside it. The
+              placement rule in ErrorBoundary.tsx says a boundary belongs inside
+              the panel container; these four ARE their own container, and a
+              boundary inside one cannot catch a throw in that component's own
+              body — which is exactly the bug worth catching here (a malformed
+              `storyboard.parts`, a reference row of an unexpected shape). The
+              rule's actual concern is the stage, and the stage is an earlier
+              sibling that a catch here never touches. `.shell > .panel-crash` in
+              styles/shell.css puts the fallback in the centre column on the
+              overlay tier, so a crash card is never painted underneath the stage
+              iframe.
+
+              Each mode below is its eager shell (lazySurfaces.tsx): null until
+              the mode is first wanted, then its chunk, behind the mode's own
+              skeleton. A chunk that fails to load lands in the same boundary. */}
+          <PanelBoundary label="Material workspace">
+            <MaterialWorkspace />
+          </PanelBoundary>
+          {/* The Component Studio. A SIBLING of the stage like every panel, and
+              it renders nothing until a definition is open on the Studio face,
+              so it is unconditional here for the reason `StageMenu` is. Like
+              every mode it shows its parts in the docked cells (cellSlots.tsx). */}
+          <PanelBoundary label="Component studio">
+            <ComponentStudio />
+          </PanelBoundary>
+          {/* And the third, for the OTHER component family: one code component's
+              source beside its own render. Unconditional here for the same reason,
+              and it renders nothing until `codeComponent` is set. */}
+          <PanelBoundary label="Code studio">
+            <CodeStudio />
+          </PanelBoundary>
+          {/* Components' Preview tab and its empty state (the two studios
+              above are its Edit tab). Unconditional for the same reason. */}
+          <PanelBoundary label="Components">
+            <ComponentsPreview />
+          </PanelBoundary>
+          {/* And the fourth: the Project's planning board. Unconditional here for
+              the same reason, and it renders nothing until `storyboardOpen`. */}
+          <PanelBoundary label="Storyboard">
+            <StoryboardView />
+          </PanelBoundary>
+          <LeftColumn />
+          {/* A SIBLING of the rail, not a child: a grid item on the rail's seam,
+              on the same --rail-w track the rail's width comes from, so the two
+              cannot disagree. It runs down through the timeline, because the
+              timeline's name column is that same track.
+
+              AND IT SERVES EVERY WORKSPACE BUT THE BOARD. A mode shows its own
+              left column in this same cell (the material library, the
+              component library, the file tree), so the seam drags there too.
+              The board has no left column: it is one full-width canvas.
+
+              FROM THE SHOWN WIDTH, AND NO WIDER THAN THE CANVAS ALLOWS. A drag
+              starts from what the author sees, not from a stored size the window
+              is too small for, and a drag that would squeeze the canvas under its
+              minimum stops where the track stops. */}
+          {railCollapsed || workspace === "storyboard" ? null : (
+            <ResizeHandle
+              axis="x"
+              getValue={() => shownShell().railWidth}
+              sign={1}
+              onChange={(w) =>
+                store.setRailWidth(
+                  Math.min(w, window.innerWidth - CANVAS_MIN.width - shownShell().inspectorWidth),
+                )
+              }
+              onReset={() => store.setRailWidth(RAIL_WIDTH.default)}
+              className="rail-resize"
+              label="Resize the left panel"
+            />
+          )}
+          {/* ── THE SPLIT DIVIDER DRAGS ────────────────────────────────────────
+              `splitRatio` has been in the schema, clamped twice and read by the
+              scissor since the split landed, and NOTHING ever moved it: the stage
+              drew a 1px seam and `panes.ts`'s header claimed the chrome laid out a
+              handle from the same rects. It did not.
+
+              CHROME-SIDE, because a stage-side handle needs a new stage-to-chrome
+              bridge message AND `pointerEvents: auto` inside an overlay whose
+              `pointerEvents: none` is a stated invariant — without it every drag
+              would end the moment the cursor crossed the divider.
+
+              Against `window.innerWidth`, which IS the pane width: the stage iframe
+              is pinned `inset: 0`, so its viewport is the whole window (panes.ts).
+              `clampSplitRatio` and `setStageLayout` already bound the value twice,
+              so there is no third validation here. */}
+          {/* The stage's own panes are on screen only in the stage workspace. In
+              a mode the stage frames one subject into a hole, and a divider at
+              the split's x would lie across the hole and take its drags. */}
+          {stageLayout.mode !== "split" || workspace !== "stage" ? null : (
+            <ResizeHandle
+              axis="x"
+              getValue={() =>
+                splitX(
+                  store.getState().stageLayout.splitRatio,
+                  window.innerWidth,
+                  store.getState().stageInset,
+                )
+              }
+              sign={1}
+              onChange={(px) =>
+                store.setStageLayout({
+                  ...store.getState().stageLayout,
+                  splitRatio: splitRatioAt(
+                    px,
+                    window.innerWidth,
+                    store.getState().stageInset,
+                  ),
+                })
+              }
+              onReset={() =>
+                store.setStageLayout({
+                  ...store.getState().stageLayout,
+                  splitRatio: 0.5,
+                })
+              }
+              className="split-resize"
+              label="Resize the split"
+            />
+          )}
+          {/* THE CANVAS BAR, docked over the canvas cell: where am I, which panes
+              are up and how each is drawn, then the badges and the zoom. It names
+              the PLACE; the tools name the GESTURE and live in the footer under the
+              canvas. See CanvasBar.tsx. */}
+          <div className="control-strip">
+            {/* INSIDE the positioned strip, per PanelBoundary's placement rule.
+                Hidden on the board, which has no canvas bar: see the timeline
+                dock below for why an `<Activity>`. */}
+            <Activity mode={workspace === "storyboard" ? "hidden" : "visible"}>
+              <PanelBoundary label="Toolbar">
+                <CanvasBar />
+              </PanelBoundary>
+            </Activity>
+          </div>
+          {/* THE TOOL FOOTER, docked under the canvas cell: a grid row of its own
+              (`foot-t / main-b`), so it follows every dock drag and collapse with
+              no arithmetic and nothing floats over the picture. See `.tool-footer`
+              in styles/tool-footer.css.
+
+              MOUNTED AT EVERY LEVEL OF THE STAGE (`toolFooterShown`): a loaded
+              document in the stage workspace, the Project context included. In
+              every mode the row closes and the canvas takes its height back,
+              rather than drawing a bar about a picture that is not on screen.
+
+              ToolFooter holds the tools (or, in the Project context, the shot
+              under the playhead) on the left and the view track on the right.
+              The boundary is INSIDE the positioned box, per PanelBoundary's
+              placement rule.
+
+              RIGHT AFTER THE CANVAS BAR in the DOM, though the grid draws it
+              further down: the grid places every cell explicitly, so source
+              order is only the TAB order, and the tools belong with the canvas
+              they act on, before the inspector and the timeline. */}
+          {footerShown ? (
+            <div className="tool-footer">
+              <PanelBoundary label="Tools">
+                <ToolFooter />
+              </PanelBoundary>
+            </div>
+          ) : null}
+          {/* ── AND THE RIGHT RAIL DRAGS TOO ──────────────────────────────────
+              The inspector was a CSS literal with no writer, and the panel had
+              been worked around rather than widened: a comment in SceneDocSection
+              records a label being SHORTENED because `.insp-label` is capped at
+              60% of a 288px pill. A width the author can set is the honest fix.
+
+              A SIBLING of the column, never a child: a grid item on its seam, the
+              same reason `.rail-resize` sits out here, and it runs down through
+              the timeline's meters cell, which is the same track.
+
+              `sign={-1}` because this rail is on the RIGHT: moving the pointer
+              along +x makes it narrower.
+
+              Hidden while collapsed, and on the Components home, whose column
+              has no occupant and is drawn at 0: a handle for a hidden column
+              is an 8px strip of dead canvas, and its drag would size a column
+              nobody can see.
+
+              NOT ON THE BOARD, whose right panel is drawn at fixed display
+              widths (`boardColumns`) that a drag would never move. */}
+          {inspectorCollapsed || workspace === "storyboard" || columnEmpty ? null : (
+            <ResizeHandle
+              axis="x"
+              getValue={() => shownShell().inspectorWidth}
+              sign={-1}
+              onChange={(w) =>
+                store.setInspectorWidth(
+                  Math.min(w, window.innerWidth - CANVAS_MIN.width - shownShell().railWidth),
+                )
+              }
+              onReset={() => store.setInspectorWidth(INSPECTOR_WIDTH.default)}
+              className="inspector-resize"
+              label="Resize the right panel"
+            />
+          )}
+          <RightColumn />
+          {/* STUDIO'S PANELS SLEEP ON THE BOARD. The board shows none of them
+              (storyboard.css hides their cells), but a hidden cell still
+              re-rendered on every store change the board made. Inside a hidden
+              `<Activity>` they keep their state (the dock's scroll, its open
+              rows) and stop rendering and running effects until Studio is back.
+              The stage is never inside one: it is the shell's first child, and
+              stageIdentity.test.tsx holds it there. The left column's Files
+              panel sleeps the same way (LeftColumn.tsx); the tool footer is
+              not mounted on the board at all (`toolFooterShown`). */}
+          <Activity mode={workspace === "storyboard" ? "hidden" : "visible"}>
+            <TimelineDock />
+          </Activity>
+          {/* THE MODES' CELLS (panels/stage/cellSlots.tsx). The canvas cell holds
+              nothing in the stage workspace, so the picture shows through it; a
+              mode portals its centre here. The bottom cell stands in for the
+              timeline in the two modes whose strip replaces it. */}
+          <CellSlot name="centre" className="canvas-cell" />
+          <CellSlot name="bottom" className="bottom-cell" />
+          {/* Renders nothing. Mounted HERE and not in the stage: audio is not part
+              of the document, and the stage is a GL iframe that must never
+              remount. Unconditional, so it survives every shell state. */}
+          <AudioPreviewBridge />
+          {/* A SIBLING of the stage panel, never a wrapper: the iframe must not
+              remount, and anything inside it would be captured by the export it
+              describes. Renders nothing unless an in-browser export is running. */}
+          <ExportScrim />
+
+          {exportOpen && name !== null && (
+            <ExportDialog onClose={() => store.setExportOpen(false)} />
+          )}
+
+          {/* Portals out of the layout, so it hangs here rather than inside a
+              panel: the stage menu opens over whichever half was right-clicked.
+              Unconditional, because it renders nothing until its state field is set. */}
+          <StageMenu />
+          {/* The library browser hangs here for the same reason. It is a `Dialog`
+              and not a workspace: it portals to `document.body` at 1100, so it
+              opens over the board and both studios rather than refusing while
+              one of them is up. */}
+          <LibraryBrowser />
+          {/* An MCP agent's question to the person ("The storyboard is
+              ready"): a Dialog over whatever is on screen, its chunk loaded
+              the first time one opens. */}
+          <AgentQuestionDialog />
+
+          {name === null ? (
+            <div className="empty-state">
+              <h1>No Project open</h1>
+              <p>Open a Project to start.</p>
+              {/* A plain link: with no Project there is nothing to flush first. */}
+              <a className="btn is-primary" href="/projects/" data-testid="empty-go-projects">
+                Go to Projects
+              </a>
+            </div>
+          ) : null}
+
+          {/* Top of the work area (Paper page 21): editing is held until it clears. */}
+          <SyncQuotaBanner />
+          {/* A delete under live sync, with changes still waiting (R10). */}
+          <SyncDeletedDialog />
+
+          <div className="overlay-strip" role="status" aria-live="polite">
+            {/* FIRST, and with no dismiss: it outlives every message under it and
+                is the reason some of them are about to appear. */}
+            {schemaNotice === null ? null : (
+              <div
+                className="overlay-message is-sticky"
+                data-testid="schema-mismatch"
+              >
+                <span>{schemaNotice}</span>
+              </div>
+            )}
+            {/* Sticky too: autosave is stopped until the author acts on it. */}
+            {saveConflict === null ? null : (
+              <div className="overlay-message is-sticky" data-testid="save-conflict">
+                {saveConflict === "deleted" ? (
+                  <>
+                    <span>This Project was deleted or renamed somewhere else, so your edits are not saving.</span>
+                    <a className="overlay-action" href="/projects/">
+                      Back to Projects
+                    </a>
+                  </>
+                ) : (
+                  <>
+                    <span>
+                      This Project changed in another tab or by an agent, so your edits are not saving. Reload
+                      takes the latest version, and Undo then brings yours back.
+                    </span>
+                    <button type="button" className="overlay-action" onClick={() => void store.reloadLatest()}>
+                      Reload
+                    </button>
+                  </>
+                )}
+              </div>
+            )}
+            {/* Sticky: it goes when the file is relinked or removed. */}
+            <MissingAssetsNotice />
+            <ViewOnlyToast />
+            {/* Each row clears its own message: a stage error is not `error`.
+                VIEW_ONLY is not a row: ViewOnlyToast says it, with a way on. */}
+            {(
+              [
+                [stageError, () => setStageError(null)],
+                [reportedStageError, () => store.dismissStageError()],
+                [error === VIEW_ONLY ? null : error, () => store.dismissError()],
+              ] as const
+            )
+              .filter((row): row is readonly [string, () => void] => row[0] !== null)
+              .map(([message, dismiss]) => (
+                <div key={message} className="overlay-message">
+                  <span>{message}</span>
+                  <button
+                    type="button"
+                    onClick={dismiss}
+                    title="Dismiss"
+                  >
+                    ×
+                  </button>
+                </div>
+              ))}
           </div>
-        ))}
-      </div>
-    </div>
+        </div>
+      </CellSlotsProvider>
+    </StillThumbsProvider>
   );
 }
 
-/** `?shot=<name>` on load. The URL is a MIRROR the store writes, and reading it
- *  once at boot is what makes a reload land back where the author was — the
- *  same reason the canvas lane mirrors its focused board.
- *
- *  With NO name in the URL, open the first document there is. A bare `/shot`
- *  is how a hosted workspace is entered — nobody types a query string at a
- *  front door — and greeting a new author with an empty stage hides the fact
- *  that their project already has content. Guarded on `name === null` so it
- *  can only ever fill a vacuum, never replace something already open. */
+/** A Viewer's edit attempt (Paper page 21, "View only"): a toast with the way
+ *  on, "Request edit access", in place of the error row. The request is
+ *  always 202 (packages/worker/src/requests.ts), so "sent" is all it can say.
+ *  One at a time: a second attempt replaces the first. */
+function ViewOnlyToast() {
+  const store = useStore();
+  const error = useShotEditor((s) => s.error);
+  const { toast, node } = useToasts();
+  const shown = useRef<ToastHandle | null>(null);
+  useEffect(() => {
+    if (error !== VIEW_ONLY) return;
+    store.dismissError();
+    shown.current?.dismiss();
+    shown.current = toast({
+      message: VIEW_ONLY,
+      action: {
+        label: "Request edit access",
+        run: () => {
+          const projectId = store.getState().doc?.id;
+          if (projectId === undefined) return;
+          requestEditAccess(projectId).then(
+            () => toast({ message: "Request sent. A Project admin will see it.", severity: "success" }),
+            (e: unknown) => toast({ message: e instanceof Error ? e.message : String(e), severity: "error" }),
+          );
+        },
+      },
+    });
+  }, [error, store, toast]);
+  return node;
+}
+
+/** `?scene=<stable-slug>` opens exactly one Project. A bare editor never picks
+ * one on the author's behalf; Project Home owns that choice. `?shot=` remains
+ * the original document-key spelling for old deep links. */
 function useOpenFromUrl(): void {
   const store = useStore();
   useEffect(() => {
-    const wanted = new URLSearchParams(window.location.search).get("shot");
-    if (wanted !== null && wanted.length > 0) {
-      void store.openShot(wanted);
-      return;
-    }
-    void (async () => {
-      await store.refreshShots();
-      const first = store.getState().shots[0];
-      if (first !== undefined && store.getState().name === null) {
-        await store.openShot(first.name);
+    const params = new URLSearchParams(window.location.search);
+    // ── `?scene=` IS THE DOCUMENT AND `?shot=` IS THE SEGMENT ─────────────
+    //
+    // The words moved when the chrome's vocabulary did, and `?shot=<docName>`
+    // is the ORIGINAL spelling of the first — old links carry it and must keep
+    // working. So one precedence rule rather than a guess: `scene=` names the
+    // document and wins, and `shot=` is read AS A DOCUMENT NAME only when
+    // `scene=` is absent.
+    //
+    // A URL carrying BOTH is the ordinary shape this chrome now writes (see
+    // `mirrorUrl`), not a stale bookmark: `scene=` is the document and `shot=`
+    // is the shot inside it, read below once that document is loaded.
+    const wanted = wantedDocOf(params);
+    // ?def= REOPENS A COMPONENT CONTEXT. It rides the open rather than being a
+    // second effect because it addresses INTO the document: a definition id
+    // means nothing until the document holding it is loaded, and `editComponent`
+    // called against an empty store would be validated away on the first write.
+    // A stale id (the definition was deleted since the link was made) opens the
+    // shot and nothing else, which is the same degradation `?focus=` takes.
+    const reopenDef = (): void => {
+      // ?shot=<sc_…> REOPENS THE SHOT CONTEXT, and it rides the open for the
+      // same reason `?def=` does: a shot id means nothing until the document
+      // holding it is loaded. It is read ONLY when `scene=` supplied the
+      // document — otherwise `shot=` is the original spelling of the document
+      // name and `wanted` has already consumed it, so treating it as a shot id
+      // would refuse a link that used to work.
+      const shot = params.get("shot");
+      // NON-EMPTY `scene=`, not merely present. `?scene=&shot=sc_x` is a URL a
+      // hand edit or a truncating share sheet produces, and `wanted` already
+      // rejects it as a document name — so a bare presence check here would
+      // enter a shot id against whatever document the "open the first one"
+      // fallback happened to load.
+      const named = params.get("scene");
+      if (
+        named !== null &&
+        named.length > 0 &&
+        shot !== null &&
+        shot.length > 0
+      ) {
+        // Membership in `doc.scenes`, never `scenesById[shot] !== undefined`:
+        // that map is a plain object and `?shot=constructor` is a string a link
+        // can carry, so the presence guard would pass on `Object`'s own
+        // constructor. `enterScene` refuses it too; this is the outer half.
+        if (store.getState().doc?.scenes.includes(shot) === true)
+          store.enterScene(shot);
+      }
+      const def = params.get("def");
+      if (
+        def !== null &&
+        def.length > 0 &&
+        store.getState().doc?.components?.[def] !== undefined
+      ) {
+        // `?def=` reopens the definition in Components. An old `&edit=1` face
+        // flag means nothing now: there is one place.
+        store.editComponent(def);
       }
-    })();
+      // `?code=` REOPENS THE OTHER FAMILY'S SUBJECT. Validated by the REGISTRY
+      // rather than by the document, which is the whole difference between the
+      // two: a code component is a file in the repo, so whether a link to it
+      // still works has nothing to do with which shot is open. `openCodeComponent`
+      // does that lookup itself and reports an id the registry has lost, so
+      // there is nothing to check here.
+      const code = params.get("code");
+      if (code !== null && code.length > 0) {
+        // `?file=` IS THE BUFFER, and it rides BEHIND the subject rather than
+        // beside it: it names a file to read inside the code studio, and there
+        // is no code studio until `code=` has opened one. Awaited for that
+        // reason — opening the file first would land a buffer in a mode that
+        // is about to replace the whole buffer set.
+        //
+        // GATED ON THE SUBJECT ACTUALLY OPENING, not on the promise settling:
+        // `openCodeComponent` refuses by RETURNING (an id the registry lost, a
+        // builtin, an unreadable file), so a resolved promise says nothing
+        // about whether the mode is on screen. `openCodeFile` refuses the same
+        // case itself; this check keeps the reason legible at the call site.
+        //
+        // The path is otherwise unvalidated here, like `?material=`:
+        // `openCodeFile` reads through `/api/files`, which is the only thing
+        // that knows whether a path is editable, and it reports its own refusal.
+        const file = params.get("file");
+        void store.openCodeComponent(code).then(() => {
+          if (file === null || file.length === 0) return;
+          if (store.getState().codeComponent === null) return;
+          void store.openCodeFile(file);
+        });
+      }
+      reopenMaterial();
+      // ?storyboard=1 REOPENS THE BOARD, after the material reopen and only
+      // over the stage: opening hands over from a mode, but a link carrying
+      // both is a link the mirror never wrote, and the board yields.
+      if (params.get("storyboard") === "1" && workspaceOf(store.getState()) === "stage") store.setStoryboardOpen(true);
+      // ?plan=<partId>&sketch=<id> REOPENS THE SHOT BOARD on the board just
+      // opened, and only on it: a plan that is gone opens the whole board.
+      // `openShotBoard` takes a Shot id too, so it is checked as a part here.
+      const plan = params.get("plan");
+      if (
+        plan !== null &&
+        store.getState().storyboardOpen &&
+        store.getState().doc?.storyboard?.parts.some((p) => p.id === plan) === true
+      ) {
+        store.openShotBoard(plan);
+        const sketch = params.get("sketch");
+        if (sketch !== null && sketch.length > 0) store.selectSketch(sketch);
+      }
+      // ?thread=<id> OPENS A COMMENT THREAD (an inbox item, an email link)
+      // where it sits (`openThread`), and in the Comments tab. A DOOR, NOT A
+      // PLACE: the mirror never writes it, so it leaves the URL once read.
+      // Left in, every reload would open the thread again over the mode the
+      // author has moved to since, and a card thread hands over to the board.
+      const thread = params.get("thread");
+      if (thread !== null && thread !== "") {
+        const url = new URL(window.location.href);
+        url.searchParams.delete("thread");
+        window.history.replaceState(null, "", url);
+        void store.openThread(thread);
+      }
+    };
+    // ?material=<layerId>&slot=<index> REOPENS THE SHADER, and it rides the
+    // open behind the shot and the definition for the same reason both of them
+    // do: a layer id means nothing until the document holding it is loaded, and
+    // `openMaterialWorkspace` resolves the layer through whichever container
+    // the chrome is currently in — so entering the shot has to have happened
+    // first or the mesh is not reachable and the call refuses.
+    //
+    // The SLOT is passed through unchecked on purpose. The slot list is pushed
+    // up by the stage when the model finishes parsing, which is well after
+    // boot, so validating here would reject every deep link into a submesh.
+    // `openMaterialWorkspace` already drops a slot on a primitive, and
+    // `onHistoryChange` drops one the loaded model turns out not to have.
+    const reopenMaterial = (): void => {
+      const material = params.get("material");
+      if (material === null || material.length === 0) return;
+      const raw = params.get("slot");
+      const slot = raw === null || raw === "" ? null : Number(raw);
+      if (slot !== null && !Number.isInteger(slot)) return;
+      store.openMaterialWorkspace(material, { slot });
+    };
+    if (wanted !== null) {
+      // ADOPT the boot open when main.tsx already started it (see bootOpen.ts:
+      // the fetch overlaps the mount instead of following it); initiate only
+      // when there is none — a test's own store, or a future second mount.
+      // The continuation still runs after the doc lands and against live store
+      // state, exactly as before.
+      void (bootOpenFor(store, wanted) ?? store.openShot(wanted)).then(
+        reopenDef,
+      );
+    }
   }, [store]);
 }
 
@@ -309,32 +1001,81 @@ function useOpenFromUrl(): void {
  * panel and a stage is a keymap where "what does ⇧A do" has three answers and
  * a reader has to find all three to be sure.
  */
-/** The panels that float over the stage, per edge they eat into. Hidden ones
- *  measure 0x0 and are skipped, which is what makes a collapsed rail give the
- *  stage its corner back. */
-const INSET_PANELS = {
-  top: [".shell-header", ".control-strip"],
-  left: [".left-rail"],
-  right: [".inspector", ".agent-panel"],
-  bottom: [".timeline-dock"],
-} as const;
+/** The docked cells around the canvas, per edge they eat into. Hidden ones
+ *  are skipped, which is what makes a collapsed rail give the stage its
+ *  corner back.
+ *
+ *  The tool footer is a docked cell like the rest: the picture is framed away
+ *  from it and the scrims stop at it. WHICH edge is the toolbar position pref:
+ *  under the stage it sits above the dock, so it is the larger of the bottom
+ *  edges whenever it is mounted; on top it sits under the canvas bar, so it is
+ *  the larger of the top edges. Built from the pref, never a special case in
+ *  the measure. */
+function insetPanels(toolbar: "bottom" | "top") {
+  const footer = ".tool-footer";
+  return {
+    top: [".shell-header", ".control-strip", ...(toolbar === "top" ? [footer] : [])],
+    left: [".left-rail"],
+    right: [".inspector-column"],
+    bottom: [".timeline-dock", ".bottom-cell", ...(toolbar === "bottom" ? [footer] : [])],
+  };
+}
+
+/**
+ * The one element that is a WINDOW onto the stage rather than a lid over it.
+ *
+ * A mode paints its own parts in the cells around this one, the canvas cell
+ * included, so the stage's whole visible area IS this rect. That makes the
+ * per-side max below the wrong sum: it knows only the docked cells, so it
+ * would frame the subject into the whole canvas cell, under the mode's parts.
+ *
+ * A SHARED CLASS and not one selector per mode. There are four (the material
+ * workspace's object, the Component Studio's subject, Code Studio's render and
+ * the board's preview); a second selector here is a third place the rule lives,
+ * and the failure when someone forgets it is silent — the mode paints, the
+ * measure falls through to the per-panel maxes, and the stage frames the
+ * subject into a rect it can see none of.
+ */
+const STAGE_WINDOW = ".stage-window";
 
 /**
  * How far the chrome's furniture reaches into the stage, per side, in CSS px.
  *
- * ZERO-SIZED ELEMENTS ARE SKIPPED and that is not an optimisation. A
- * `display: none` panel reports an all-zero rect, and for the RIGHT edge
- * `shell.right - 0` is the whole window — so a collapsed inspector would tell
- * the stage its entire width was covered and every badge would render off
- * screen.
+ * A PANEL NOBODY CAN SEE COVERS NOTHING, and there are two ways to be one.
+ * Zero-sized is the older test and it is not an optimisation: for the RIGHT
+ * edge `shell.right - 0` is the whole window, so a collapsed inspector that
+ * measured zero would tell the stage its entire width was covered and every
+ * badge would render off screen. Hidden is the second, and it is why the two
+ * are asked separately now. See `edge`.
  */
-function measureInset(shell: HTMLElement): StageInset {
+export function measureInset(shell: HTMLElement, toolbar: "bottom" | "top"): StageInset {
+  const panels = insetPanels(toolbar);
   const box = shell.getBoundingClientRect();
-  const edge = (selectors: readonly string[], of: (r: DOMRect) => number): number => {
+  // A WINDOW WINS OUTRIGHT. Not merged with the panels below: when one is on
+  // screen the stage is visible THERE and nowhere else, so the four numbers are
+  // that rect's four distances and no panel can add to them.
+  const port = shell.querySelector(STAGE_WINDOW)?.getBoundingClientRect();
+  if (port !== undefined && port.width > 0 && port.height > 0) {
+    const hole = {
+      top: port.top - box.top,
+      left: port.left - box.left,
+      right: box.right - port.right,
+      bottom: box.bottom - port.bottom,
+    };
+    return hole;
+  }
+  const edge = (
+    selectors: readonly string[],
+    of: (r: DOMRect) => number,
+  ): number => {
     let most = 0;
     for (const selector of selectors) {
       const el = shell.querySelector(selector);
       if (el === null) continue;
+      // AND A HIDDEN ONE, which is not the same question. A collapsed column is
+      // `visibility: hidden` and keeps its whole track, so it measures full
+      // width while covering nothing: the canvas spans over it.
+      if (window.getComputedStyle(el).visibility === "hidden") continue;
       const rect = el.getBoundingClientRect();
       if (rect.width === 0 || rect.height === 0) continue;
       most = Math.max(most, of(rect));
@@ -342,18 +1083,44 @@ function measureInset(shell: HTMLElement): StageInset {
     return most;
   };
   return {
-    top: edge(INSET_PANELS.top, (r) => r.bottom - box.top),
-    left: edge(INSET_PANELS.left, (r) => r.right - box.left),
-    right: edge(INSET_PANELS.right, (r) => box.right - r.left),
-    bottom: edge(INSET_PANELS.bottom, (r) => box.bottom - r.top),
+    top: edge(panels.top, (r) => r.bottom - box.top),
+    left: edge(panels.left, (r) => r.right - box.left),
+    right: edge(panels.right, (r) => box.right - r.left),
+    bottom: edge(panels.bottom, (r) => box.bottom - r.top),
   };
 }
 
+/**
+ * A file dropped on the chrome must not navigate the tab away from the
+ * editor. The panels that take drops prevent the default themselves, so this
+ * only answers for everywhere else, and it leaves text fields their own drop.
+ * The stage iframe is its own document and guards itself (StagePanel.tsx).
+ */
+function useWindowDropGuard(): void {
+  useEffect(() => {
+    const guard = (e: DragEvent): void => {
+      if (e.defaultPrevented) return;
+      const t = e.target;
+      if (t instanceof HTMLElement && (t.isContentEditable || t.closest("input, textarea") !== null))
+        return;
+      e.preventDefault();
+      if (e.dataTransfer !== null) e.dataTransfer.dropEffect = "none";
+    };
+    window.addEventListener("dragover", guard);
+    window.addEventListener("drop", guard);
+    return () => {
+      window.removeEventListener("dragover", guard);
+      window.removeEventListener("drop", guard);
+    };
+  }, []);
+}
+
 function useKeymap(): void {
   const store = useStore();
   useEffect(() => {
     const onKeyDown = (e: KeyboardEvent): void => {
-      if (store.handleKey({ ...keyOf(e), target: e.target })) e.preventDefault();
+      if (store.handleKey({ ...keyOf(e), target: e.target }))
+        e.preventDefault();
     };
     window.addEventListener("keydown", onKeyDown);
     return () => window.removeEventListener("keydown", onKeyDown);
@@ -370,6 +1137,8 @@ function keyOf(e: KeyboardEvent) {
     ctrlKey: e.ctrlKey,
     metaKey: e.metaKey,
     code: e.code,
+    // A held key's OS repeats: the play toggle ignores them (`handleKey`).
+    repeat: e.repeat,
   };
 }
 
@@ -385,10 +1154,20 @@ function useExternalChangeRelay(): void {
       if (e.origin !== window.location.origin) return;
       const data = e.data as { type?: unknown; data?: unknown } | null;
       if (data?.type !== "studio:shot-doc-changed") return;
-      store.adoptExternalChange((data.data ?? {}) as { name?: string; origin?: string; clientId?: string });
+      // THE MAIN STAGE ONLY. The inspector's component preview is a second
+      // stage page (ComponentStage), and it relays the same push: two relays
+      // meant two reloads of one write.
+      const main = document.querySelector<HTMLIFrameElement>("iframe.stage-frame")?.contentWindow;
+      if (main !== undefined && main !== null && e.source !== main) return;
+      store.adoptExternalChange(
+        (data.data ?? {}) as {
+          name?: string;
+          origin?: string;
+          clientId?: string;
+        },
+      );
     };
     window.addEventListener("message", onMessage);
     return () => window.removeEventListener("message", onMessage);
   }, [store]);
 }
-