@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/motionStamp.ts

@@ -0,0 +1,7 @@
+// THE MOTION PRESETS' STAMP, on demand: `stampMotionPreset` and its catalog
+// are a chunk of their own, kept out of the entry's budget like the Motion
+// section that offers them, and fetched at idle with it
+// (`prefetchInspectorSections`). The store's `applyMotionPreset` and
+// `previewMotion` import this module when first used; by then the idle fetch
+// has usually landed, so a pick waits on nothing.
+export { stampMotionPreset } from "@dailies-studio/shot/doc";

package/src/state/panelSize.ts

@@ -9,9 +9,58 @@
 // which is passed in per drag — a dock taller than the window is a dock with
 // no stage behind it.
 
-export const RAIL_WIDTH = { min: 168, max: 460, default: 232 } as const;
+import type { ShotEditorState } from "./types.js";
+import { componentEditOpen, workspaceOf } from "./workspace.js";
+import type { BoardRightPanel } from "./workspace.js";
+import { foldedDockContentH } from "../panels/timeline/model.js";
+
+export const RAIL_WIDTH = { min: 168, max: 460, default: 224 } as const;
 export const DOCK_HEIGHT = { min: 120, max: 640, default: 300 } as const;
 
+/**
+ * The dock's OTHER dimension: how wide one frame is drawn, in CSS px.
+ *
+ * It sits beside the panel bounds for the reason they are here at all: the
+ * store's clamp, the initial state, the wheel zoom, the slider and the tests
+ * were four separate restatements of `0.2`, `60` and `6`, which is three
+ * numbers with four owners. `setDockPpf` is the one writer and it reads this.
+ *
+ * The floor is where a frame is a fifth of a pixel, which is about as far out
+ * as a ten-minute document can be fitted; the ceiling is 60px a frame, where
+ * one second fills a laptop's lane and there is nothing left to see by going
+ * further. The default is the zoom a document opens at before `fit` measures
+ * the lane it actually has.
+ */
+export const DOCK_PPF = { min: 0.2, max: 60, default: 6 } as const;
+
+/**
+ * The inspector, which was a hardcoded 288 in CSS and draggable nowhere.
+ *
+ * 288 was too narrow for its own contents and there was no way to say so: the
+ * camera's Zoom / Roll / Focus row had ~66px per field, so `.numfield-label`
+ * hit its 14px floor and the three labels rendered "Z…", "R…", "F…". The panel
+ * had been WORKED AROUND rather than widened — `SceneDocSection` carries a
+ * comment about shortening a label because "`.insp-label` is capped at 60% of a
+ * 288px pill" — which is the sign a constant is wrong rather than a label.
+ *
+ * 320 was the first answer, chosen while the panel still had to fit THREE
+ * labelled pills in a row. It does not any more: `.numfield-label` is
+ * `flex: none` and the two-pill rule holds the row to two, so the width that
+ * was buying a third column is now buying nothing but a narrower stage. On a
+ * 1366 laptop that column is a twentieth of the screen.
+ *
+ * 288 with 8/10 padding leaves 252px across a row: 123px per pill in a
+ * two-pill row, of which ~61px is label — nine characters at 12px, and the
+ * longest label the panel has is "Spread".
+ *
+ * 304 is the Paper redesign's column (2026-10-04). Its rows put the label
+ * OUTSIDE the field and add a tick slider to the axis rows, which is what the
+ * extra 16px pays for. Bounds: 264 is where the inputs reach their 24px floor
+ * and there is nothing left to give; 480 is where the panel stops being a
+ * rail and starts taking the stage's width for a column of controls.
+ */
+export const INSPECTOR_WIDTH = { min: 264, max: 480, default: 304 } as const;
+
 /** Clamp to whole pixels. Whole, because a fractional panel width puts every
  *  box positioned off it on a half pixel and the seams stop being crisp. */
 export function clampSize(value: number, min: number, max: number): number {
@@ -19,8 +68,329 @@ export function clampSize(value: number, min: number, max: number): number {
   return Math.round(Math.min(max, Math.max(min, value)));
 }
 
-/** The dock's ceiling for a given window: its own max, or most of the window,
- *  whichever is smaller. */
-export function dockCeiling(viewportHeight: number): number {
-  return Math.max(DOCK_HEIGHT.min, Math.min(DOCK_HEIGHT.max, Math.round(viewportHeight * 0.7)));
+/**
+ * The docked shell's three bar heights, for the arithmetic that needs them.
+ * They mirror `--topbar-h`, `--panel-head-h` and `--dock-head-h` in
+ * packages/ui/src/tokens.css, pinned by rowMetrics.test.ts.
+ *
+ * THE TOP BAR is the window's first row. THE PANEL HEAD is the second: the
+ * canvas bar and both column heads, so one hairline crosses the window under
+ * them. THE DOCK HEAD is the timeline's head and transport, which is also the
+ * whole bottom row when the dock is collapsed.
+ */
+export const TOPBAR_H = 44;
+export const PANEL_HEAD_H = 40;
+export const DOCK_HEAD_H = 40;
+
+/**
+ * The tool footer's height: the docked row under the canvas cell that holds
+ * the tools. It mirrors `--tool-footer-h` in styles/shell.css `:root`, pinned
+ * by rowMetrics.test.ts.
+ *
+ * A ROW, NOT A FLOAT. The tools used to ride a pill over the bottom of the
+ * picture, so the canvas cell lost nothing to them and only the stage's inset
+ * did. The footer is a grid track of its own, so it takes its height from the
+ * canvas, and the dock's ceiling has to pay for it while it is shown.
+ */
+export const TOOL_FOOTER_H = 48;
+
+/** The state `toolFooterShown` reads. */
+export type ToolFooterFields = Pick<
+  ShotEditorState,
+  | "name"
+  | "doc"
+  | "editingDef"
+  | "materialWorkspace"
+  | "codeComponent"
+  | "componentsTab"
+  | "storyboardOpen"
+> &
+  Partial<Pick<ShotEditorState, "componentsOpen">>;
+
+/**
+ * Whether the tool footer is on screen. ONE ANSWER for every reader: App
+ * mounts the row and sets its track and its inset edge from it, and
+ * `fitShell` charges the dock's ceiling for it. Readers asking different
+ * versions of the question is how a row ends up drawn with nothing in it, or
+ * a dock sized for a footer that is not there.
+ *
+ * A LOADED DOCUMENT. With no document there is no timeline either, and a row
+ * of tools over a canvas that has nothing to draw into is noise.
+ *
+ * AT EVERY LEVEL OF THE STAGE: the Project context, a shot and a definition.
+ * The footer is not only the tools any more. Its right half is the view track
+ * (Video, 3D, Camera, Split), which applies at every level, and in the Project
+ * context its left half names the shot under the playhead (ToolFooter.tsx).
+ * The TOOLS still answer to the narrower question: ToolDockBar renders only
+ * inside a shot or a definition, for the reason argued there.
+ *
+ * ONLY IN THE STAGE WORKSPACE. The three modes show their own content in the
+ * canvas cell, and the tools address the film's canvas, which none of them is.
+ * The one exception is Components' Edit tab on a definition
+ * (`componentEditOpen`): it edits the definition's layers, so the tools are
+ * there while editing inside one.
+ */
+export function toolFooterShown(s: ToolFooterFields): boolean {
+  return (
+    s.name !== null &&
+    s.doc !== null &&
+    (workspaceOf(s) === "stage" || componentEditOpen(s))
+  );
+}
+
+/**
+ * The smallest canvas the docked shell leaves, whatever the author dragged.
+ *
+ * WIDTH: the canvas cell's two docked rows have to fit it. The canvas bar
+ * above the picture is one row of place, panes and zoom, and the tool footer
+ * under it is one `nowrap` row: the 377px tools, then the view track and the
+ * Clean view eye, which compact and fold to fit (tool-footer.css has the
+ * measured widths). 640 (616 of content inside the footer's 12px padding)
+ * holds the tools beside the COMPACT track; the full one needs a 660 column,
+ * and the folded picker fits down to 522.
+ * It also holds every canvas bar but the crowded ones that canvas.css gives
+ * way for. HEIGHT: enough picture between
+ * the canvas bar and the footer to judge a frame.
+ */
+export const CANVAS_MIN = { width: 640, height: 240 } as const;
+
+/**
+ * The dock's ceiling for a given window: what is left once the top bar, the
+ * panel head, the smallest canvas and (when it is shown) the tool footer have
+ * taken theirs, inside the dock's own bounds.
+ *
+ * THE FOOTER IS AN ARGUMENT, not a constant, because it is not always there:
+ * the modes collapse its row, and charging them for it would cost a 768px
+ * laptop 48px of storyboard strip for nothing. Every level of the stage
+ * workspace pays it, the Project context included. At 1366 by 768 the
+ * ceiling is 396 with the footer (768 - 44 - 40 - 240 - 48) and 444
+ * without it.
+ */
+export function dockCeiling(viewportHeight: number, footer = false): number {
+  const vh = Number.isFinite(viewportHeight) ? viewportHeight : 0;
+  return clampSize(
+    vh - TOPBAR_H - PANEL_HEAD_H - CANVAS_MIN.height - (footer ? TOOL_FOOTER_H : 0),
+    DOCK_HEIGHT.min,
+    DOCK_HEIGHT.max,
+  );
+}
+
+/** What the grid lays out, as opposed to what the author stored. */
+export interface ShellFit {
+  railWidth: number;
+  inspectorWidth: number;
+  /** The bottom row: the dock's height, or its head when it is collapsed. */
+  dockRow: number;
+}
+
+/**
+ * The docked shell's tracks for a window, from the sizes the author stored.
+ *
+ * DISPLAY ONLY. The stored sizes are the author's and are never rewritten
+ * here: a window too small for them shows the fitted sizes, and the stored
+ * ones come back the moment the window can hold them. The setters keep only
+ * each panel's own bounds (layoutPrefs.ts relies on that).
+ *
+ * THE RAIL GIVES FIRST, then the inspector, each down to its own minimum,
+ * until the canvas has `CANVAS_MIN.width`. Below both minimums the canvas
+ * takes the deficit: the chrome does not shrink past what its rows need.
+ *
+ * A COLLAPSED COLUMN STILL COUNTS. Its track keeps its width because the
+ * timeline's name column and meters sit under it, so collapsing a panel never
+ * moves a bar under the pointer, and the canvas simply spans over it.
+ *
+ * THE DOCK PAYS FOR THE TOOL FOOTER only while the footer is shown, which is
+ * why the footer's fields ride in with the sizes: `toolFooterShown` is the
+ * same question App asks before it mounts the row.
+ */
+export function fitShell(
+  viewportWidth: number,
+  viewportHeight: number,
+  stored: { railWidth: number; inspectorWidth: number; dockHeight: number; dockCollapsed: boolean } & ToolFooterFields &
+    Partial<Pick<ShotEditorState, "enteredScene" | "dockMode">>,
+): ShellFit {
+  const ceiling = dockCeiling(viewportHeight, toolFooterShown(stored));
+  return {
+    ...fitColumns(viewportWidth, stored),
+    dockRow: stored.dockCollapsed
+      ? DOCK_HEAD_H
+      : Math.min(stored.dockHeight, ceiling, foldedDockRow(viewportWidth, viewportHeight, stored)),
+  };
 }
+
+/**
+ * AN UNTOUCHED DOCK IS AS TALL AS ITS FOLDED ROWS. The first look at a shot is
+ * Shot, Camera and Sound, and a 300px dock under three rows is stage taken for
+ * nothing, so the row the grid gives the dock stops at the head plus the
+ * folded content (`foldedDockContentH`).
+ *
+ * Only the Rows view, and only while `dockHeight` is still exactly what
+ * `layoutFor` gave this window (the refit's own "untouched" test): a dragged
+ * height is the author's and always wins, and Graph and Sound need the room
+ * their own views draw. A definition keeps the shot's height (its Actions rows
+ * scroll), so entering a component never moves the dock. Infinity means "no
+ * opinion".
+ */
+function foldedDockRow(
+  viewportWidth: number,
+  viewportHeight: number,
+  s: { dockHeight: number } & ToolFooterFields & Partial<Pick<ShotEditorState, "enteredScene" | "dockMode">>,
+): number {
+  if (s.doc === null || (s.dockMode ?? "rows") !== "rows") return Infinity;
+  if (s.dockHeight !== layoutFor(viewportWidth, viewportHeight).dockHeight) return Infinity;
+  return Math.max(DOCK_HEIGHT.min, DOCK_HEAD_H + foldedDockContentH(s.doc, s.enteredScene ?? null));
+}
+
+/** `fitShell`'s two side columns: the rail gives first, then the inspector,
+ *  each down to its own minimum, until the canvas has `CANVAS_MIN.width`. */
+function fitColumns(
+  viewportWidth: number,
+  stored: { railWidth: number; inspectorWidth: number },
+): { railWidth: number; inspectorWidth: number } {
+  const vw = Number.isFinite(viewportWidth) ? viewportWidth : 0;
+  let rail = stored.railWidth;
+  let inspector = stored.inspectorWidth;
+  let over = rail + inspector - Math.max(0, vw - CANVAS_MIN.width);
+  if (over > 0) {
+    const cut = Math.min(over, Math.max(0, rail - RAIL_WIDTH.min));
+    rail -= cut;
+    over -= cut;
+  }
+  if (over > 0) inspector -= Math.min(over, Math.max(0, inspector - INSPECTOR_WIDTH.min));
+  return { railWidth: rail, inspectorWidth: inspector };
+}
+
+/** The board's right cell at its DISPLAY widths (S1, S3, Paper SB1): the
+ *  Plan panel, the inspector, comments and the agent at the inspector's 304,
+ *  the component sheet at 400. Never written to `inspectorWidth`, so Studio
+ *  keeps the author's own width. */
+export const BOARD_PANEL_W = { panel: 304, component: 400 } as const;
+
+/**
+ * The board's side columns as drawn. THE BOARD IS ONE FULL-WIDTH CANVAS: no
+ * left rail, ever, and a right cell only while `boardRightPanel` names an
+ * occupant. That cell draws at its display width, giving way down to the
+ * inspector's minimum when the window leaves the canvas under
+ * `CANVAS_MIN.width`.
+ */
+export function boardColumns(
+  viewportWidth: number,
+  panel: BoardRightPanel,
+): { railWidth: number; inspectorWidth: number } {
+  if (panel === null) return { railWidth: 0, inspectorWidth: 0 };
+  const vw = Number.isFinite(viewportWidth) ? viewportWidth : 0;
+  const want = panel === "component" ? BOARD_PANEL_W.component : BOARD_PANEL_W.panel;
+  return { railWidth: 0, inspectorWidth: Math.max(INSPECTOR_WIDTH.min, Math.min(want, vw - CANVAS_MIN.width)) };
+}
+
+/**
+ * A layout the author already chose, as far as storage remembers it.
+ *
+ * Every field optional and read one by one: an author who dragged only the
+ * rail keeps their rail and still gets a fitted dock, and a storage value that
+ * failed to parse is simply an absent field rather than a whole layout thrown
+ * away. Declared beside `layoutFor` because the two are read together and this
+ * is the module both the store and `layoutPrefs.ts` already depend on.
+ */
+export interface BootLayoutPrefs {
+  railWidth?: number;
+  inspectorWidth?: number;
+  dockHeight?: number;
+  railCollapsed?: boolean;
+  inspectorCollapsed?: boolean;
+  dockCollapsed?: boolean;
+}
+
+/**
+ * What the three panels should START at on a given window.
+ *
+ * ── WHY A FUNCTION AND NOT THREE MORE CONSTANTS ─────────────────────────
+ *
+ * The defaults above are one number each, and they were chosen on a desktop.
+ * The docked columns and the bottom row are subtracted from the canvas at
+ * EVERY window size, on a 2560 monitor and on a 1366 laptop alike, so a
+ * desktop's numbers leave a laptop a small picture.
+ *
+ * A FRACTION FOR THE DOCK, A BREAKPOINT FOR THE RAIL. The dock is the panel
+ * whose useful height really is proportional: it is a strip of rows, and 30%
+ * of the window shows about as many of them at any size. The rail is not —
+ * it holds names, and a name needs the width it needs — so it steps once,
+ * at the width below which the two side rails start costing more than they
+ * carry. The inspector does not move at all: 304 is already the width its
+ * own rows need, and taking more from a laptop would only make the rows worse.
+ *
+ * NEVER LARGER THAN THE DESKTOP DEFAULT. This function makes a small window
+ * smaller, never a large one bigger: an author who wants more dock on a big
+ * monitor drags for it, and a boot that silently spent 30% of a 1440p screen
+ * on the timeline would be taking that decision away from them.
+ *
+ * This is a BOOT value, applied once by `bootLayout` and re-applied on resize
+ * only to a panel the author has not touched. It is deliberately not folded
+ * into the constants above, which remain the answer to "what does this panel
+ * want" — the reset-to-default of a drag still lands there. `fitShell` is the
+ * other half: what a window too small for the stored sizes lays out.
+ */
+export function layoutFor(
+  viewportWidth: number,
+  viewportHeight: number,
+): { railWidth: number; inspectorWidth: number; dockHeight: number } {
+  const vw = Number.isFinite(viewportWidth) ? viewportWidth : 0;
+  const vh = Number.isFinite(viewportHeight) ? viewportHeight : 0;
+  return {
+    railWidth: vw > 0 && vw < 1440 ? 200 : RAIL_WIDTH.default,
+    inspectorWidth: INSPECTOR_WIDTH.default,
+    // Clamped to the DEFAULT rather than to DOCK_HEIGHT.max, per the rule
+    // above: 30% of a 1440p window is 432px of timeline nobody asked for.
+    //
+    // AND NEVER PAST THE FOOTER'S CEILING, so the fit is a number
+    // `setDockHeight` keeps verbatim in every context. Under a ~531px window
+    // 30% is more than `dockCeiling(vh, true)` allows, and a fit the setter
+    // clamps is a fit nobody can recognise afterwards: the resize refit and
+    // `authorLayout` both read "not the fitted number" as "the author dragged
+    // it", so the dock stopped refitting and its clamp was saved as a
+    // preference. The modes' taller ceiling costs nothing here: a window that
+    // short has no dock to spare.
+    dockHeight:
+      vh > 0
+        ? Math.min(
+            clampSize(Math.round(vh * 0.3), DOCK_HEIGHT.min, DOCK_HEIGHT.default),
+            dockCeiling(vh, true),
+          )
+        : DOCK_HEIGHT.default,
+  };
+}
+
+/**
+ * The material mode's preview: THE OBJECT, the hole at the right of the
+ * canvas cell, and nothing else in it.
+ *
+ * THE STORED WIDTH, not the drawn one. The hole draws at most half the canvas
+ * cell (`--material-preview-w` in styles/modes/material.css), and the seam's
+ * drag caps what it stores at that same half (`setMaterialColumnWidth`'s
+ * `ceiling`), so a narrow window shows less without rewriting the number.
+ *
+ * PIXELS, for the reason at the top of this file: a width the author dragged
+ * must not move on the next window resize.
+ *
+ * Every pixel of the hole is subject. The camera fits the subject to the
+ * SMALLER axis of the hole (see `isolationExtent`), so while it stays a tall
+ * narrow slot the width is the whole budget. 560 is roughly 30% of a 1920
+ * window, which is what it takes to read a material rather than identify one.
+ *
+ * Bounds: under 280 the hole is narrower than the graph's own node cards and
+ * stops being a preview; 960 is where it starts eating the graph it exists to
+ * annotate.
+ */
+export const MATERIAL_COLUMN = { min: 280, max: 960, default: 560 } as const;
+
+/**
+ * A code component's live preview, beside the code pane in the canvas cell.
+ * Stored in pixels for the same reason, and drawn no wider than the cell
+ * leaves after the code pane's own minimum (`CODE_PANE_MIN`, code.css's
+ * `min-width`), which the seam's drag passes as its ceiling.
+ *
+ * 420 is the width the pane always had. Under 240 the loop readout and the
+ * picture stop fitting; 1400 is a whole laptop canvas cell.
+ */
+export const CODE_LIVE_WIDTH = { min: 240, max: 1400, default: 420 } as const;
+export const CODE_PANE_MIN = 360;

package/src/state/pendingChanges.ts

@@ -0,0 +1,119 @@
+// What an author's unsent sync batches change, in words, for the dialog a
+// delete under live sync shows (R10, Paper page 21 "Renamed or deleted"):
+//
+//   One board.   opacity 0 → 1
+//   CardBoard    scale 1 → 1.1
+//   Badge        fill #34D399 → #FF7A3D
+//
+// One line per thing changed, however many ops it took: the ops collapse by
+// owner and field, and the values are read from the documents before and
+// after, so a drag of fifty mints is one line.
+import { applyOps } from "@dailies-studio/shot/doc";
+import type { Doc3D, SyncOp } from "@dailies-studio/shot/doc";
+
+export interface PendingSummary {
+  /** At most `max` lines, the owner column padded so the list aligns, then
+   *  "and N more" when there are more. */
+  lines: string[];
+  /** How many things changed. */
+  count: number;
+}
+
+/** The ordered lists whose items are layers or scenes: an `ins` or `rm` in
+ *  one is the other half of a `new` or `del`, or a move. */
+const SEQS = new Set(["layers", "roots", "scenes"]);
+
+type Rec = Record<string, unknown>;
+const rec = (v: unknown): Rec | null => (typeof v === "object" && v !== null ? (v as Rec) : null);
+
+function at(doc: Doc3D, p: readonly string[]): unknown {
+  let v: unknown = doc;
+  for (const k of p) v = rec(v)?.[k];
+  return v;
+}
+
+/** A layer's or scene's display name in either document. */
+function nameOf(docs: readonly Doc3D[], id: string): string {
+  for (const doc of docs) {
+    const scene = rec(doc.scenesById)?.[id];
+    if (scene !== undefined) return String(rec(scene)?.["name"] ?? id);
+    for (const table of [doc.scenesById, rec(doc)?.["components"]]) {
+      for (const owner of Object.values(rec(table) ?? {})) {
+        const layer = rec(rec(rec(owner)?.["layersById"])?.[id]);
+        if (layer !== null) return String(layer["label"] ?? id);
+      }
+    }
+  }
+  return id;
+}
+
+function value(v: unknown): string | null {
+  if (typeof v === "number") return String(Math.round(v * 1000) / 1000);
+  if (typeof v === "string") return v.length <= 24 ? v : null;
+  if (typeof v === "boolean") return v ? "on" : "off";
+  return null;
+}
+
+/** The field a path names, short: its last key, with the one before when
+ *  the last says little alone (`position.x`, `stops.0`). */
+function fieldOf(p: readonly string[]): string {
+  const last = p[p.length - 1] ?? "";
+  return last.length <= 1 || /^\d+$/.test(last) ? p.slice(-2).join(".") : last;
+}
+
+export function describePending(base: Doc3D, ops: readonly SyncOp[], max = 6): PendingSummary {
+  let after = base;
+  try {
+    after = applyOps(base, ops).doc;
+  } catch {
+    // Names then come from the base; values read as "changed".
+  }
+  const docs = [after, base];
+  /** owner + field → [owner, what]. Insertion order is first-change order. */
+  const out = new Map<string, [string, string]>();
+  const put = (owner: string, field: string, what: string, weak = false): void => {
+    const key = `${owner}\u0000${field}`;
+    if (weak && out.has(key)) return;
+    // A layer added or removed is one line, not one per field it carries.
+    const whole = out.get(`${owner}\u0000`)?.[1];
+    if (field !== "" && (whole === "added" || whole === "removed")) return;
+    out.set(key, [owner, what]);
+  };
+  for (const op of ops) {
+    const p = op.p;
+    const list = op.op === "ins" || op.op === "rm" || op.op === "mv";
+    if (list && SEQS.has(p[p.length - 2] ?? "")) {
+      // An item of a layer or scene list: added or removed by its `new` or
+      // `del`, otherwise moved.
+      put(nameOf(docs, p[p.length - 1]!), "", "moved", true);
+      continue;
+    }
+    const li = p.lastIndexOf("layersById");
+    const owned = li >= 0 ? { id: p[li + 1], rest: p.slice(li + 2) } : p[0] === "scenesById" ? { id: p[1], rest: p.slice(2) } : null;
+    const owner = owned?.id === undefined ? "Project" : nameOf(docs, owned.id);
+    const rest = owned?.id === undefined ? p : owned.rest;
+    if (rest.length === 0) {
+      put(owner, "", op.op === "del" ? "removed" : op.op === "new" ? "added" : "changed");
+      continue;
+    }
+    if (list) {
+      const name = p[p.length - 2] ?? "";
+      put(owner, name, op.op === "ins" ? `added to ${name}` : op.op === "rm" ? `removed from ${name}` : `reordered ${name}`);
+      continue;
+    }
+    const field = fieldOf(rest);
+    const now = value(at(after, p));
+    if ((field === "label" || field === "name") && now !== null && op.op !== "del") {
+      put(owner, field, `renamed "${now}"`);
+      continue;
+    }
+    const was = value(at(base, p));
+    put(owner, field, was !== null && now !== null ? `${field} ${was} → ${now}` : `${field} changed`);
+  }
+  const rows = [...out.values()];
+  const shown = rows.slice(0, max);
+  const width = Math.max(0, ...shown.map(([owner]) => owner.length)) + 2;
+  const lines = shown.map(([owner, what]) => owner.padEnd(width) + what);
+  if (rows.length > max) lines.push(`and ${rows.length - max} more`);
+  return { lines, count: rows.length };
+}

package/src/state/playHold.ts

@@ -0,0 +1,78 @@
+// THE ONE ANSWER TO "MAY THE TRANSPORT START", so the guard and the buttons
+// cannot drift.
+//
+// `setPlaying` is the single route to playback (Space through `handleKey`, the
+// Play menu row, the Play control in the dock and Code Studio's preview strip,
+// and WebMCP), and it refuses a start for two reasons: the board, and an
+// export lock. The menu row and the Play control grey themselves for the same
+// reasons, and until this file existed each of them restated the rule in its
+// own expression. The dock's own comment already claimed they were one rule,
+// that "the greying-out is the button agreeing with the guard rather than a
+// second rule"; this is that claim made literal, and it is the same move as
+// the label, enum and route consolidation one directory over.
+//
+// A SCENE STILL LOADING IS NOT A REFUSAL (bridge v51). Play is always
+// pressable then: the press is queued (`playIntent`), the control says it is
+// waiting (`SCENE_WAITING`), and the transport starts by itself once the stage
+// is ready (`stageReady`). A second press cancels the wait (`playOn`).
+//
+// IT ANSWERS FOR A START ONLY. Every caller pairs it with `!playOn`. A
+// transport already running, or a queued Play, must always be stoppable: an
+// export that begins later would otherwise leave the author with a running
+// clock and a dead pause button.
+//
+// The string it returns is the refusal the author reads, in the error strip
+// from `setPlaying` and as the button's own title. There is no separate code
+// for the reason because nothing branches on which reason it was.
+import type { ShotEditorState } from "./types.js";
+import { workspaceOf } from "./workspace.js";
+
+/** The board's refusal, one sentence for Space, the menu row and WebMCP. */
+export const BOARD_DOES_NOT_PLAY = "The storyboard doesn't play. Open Studio to play the film.";
+
+/** The Play control's title while a queued Play waits for the scene
+ *  (`playIntent` armed) or for the stage to hand over (starting). A wait, not
+ *  a refusal: it plays by itself. */
+export const SCENE_WAITING = "Getting the scene ready to play. Space cancels.";
+
+/** How far a Play pass has drawn, in whole percent. The one rounding for the
+ *  Play control's title, the store's progress writes and WebMCP's answer. */
+export function preparingPercent({ done, total }: { readonly done: number; readonly total: number }): number {
+  return total > 0 ? Math.floor((done * 100) / total) : 0;
+}
+
+/** The Play control's title while a Play pass draws (`playIntent` preparing). */
+export function preparingTitle(intent: { readonly done: number; readonly total: number }): string {
+  return `Preparing playback, ${preparingPercent(intent)}%. Space cancels.`;
+}
+
+/** IS PLAY ON: the transport running, or a queued Play waiting to start it.
+ *  Every toggle calls `setPlaying(!playOn(state))`, so a second press cancels
+ *  the wait. */
+export function playOn(state: Pick<ShotEditorState, "playing" | "playIntent">): boolean {
+  return state.playing || state.playIntent !== null;
+}
+
+/** IS THE STAGE READY TO PLAY: it owes the open subject no presentation
+ *  (`stageBusy`, bridge v51), and a stage on its way has reported in. Ready
+ *  with no stage expected at all: a bare store, a unit test and SSR. */
+export function stageReady(state: Pick<ShotEditorState, "stageBusy" | "stageExpected" | "stageInfo">): boolean {
+  return !state.stageBusy && !(state.stageExpected && state.stageInfo === null);
+}
+
+export function playHold(state: ShotEditorState): string | null {
+  // THE BOARD PLANS, IT DOES NOT PLAY. A Shot there is a few stills and the
+  // author's notes about it, so the transport stays at rest and the scrubber
+  // is the only way through the Shot. Code Studio opened over the board is
+  // its own workspace, and plays.
+  if (workspaceOf(state) === "storyboard") return BOARD_DOES_NOT_PLAY;
+  // A capture loop owns the clock while an export runs. The stage defers chrome
+  // seeks, so playback would not move the picture: it would only overwrite the
+  // frame the export restores at the end and play the preview audio over it.
+  if (state.exportLock !== null) {
+    return `playback is held while the ${
+      state.exportLock.where === "browser" ? "in-browser" : "studio server"
+    } export renders. Cancel it to play`;
+  }
+  return null;
+}