@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/storyboardModel.ts

@@ -0,0 +1,528 @@
+// The storyboard's pure editor model: what each card draws as, the board's
+// cards by planned shot, and its rows by Shot. The document's own derived
+// views (windows, status, the brief) live in `@dailies-studio/shot/doc`'s
+// storyboard.ts and are reused here.
+//
+// Pure so the store, the board and the menus ask one implementation and the
+// tests can pin it without mounting anything.
+import { videoFrameSeconds, referencesByPart, visibleStills, gapsOf, sceneWindows, cutPlays, seamWindow, partOfScene, partFramesOf, sketchesOf, boardSlots } from "@dailies-studio/shot/doc";
+import type { Doc3D, ReferenceItem3D, Scene3D, SceneWindow, ShotAsset, StillGap, StoryboardPart3D, VisibleStill } from "@dailies-studio/shot/doc";
+import { framesToSeconds } from "@dailies-studio/engine";
+import { resolveGlPresetSpec } from "@dailies-studio/transitions";
+import type { LibraryItem } from "../api.js";
+import { formatDuration } from "../panels/timeline/model.js";
+
+// A part's colour and the part a Shot's first plan write makes live in the
+// data plane, so a new Project's scaffold makes Shot 1's part the same way.
+export { PART_PALETTE, paletteColor, pinPartFor } from "@dailies-studio/shot/doc";
+
+/** `library` is a shipped shot, material, blueprint or image pack cited by
+ *  the board. A shipped COMPONENT never draws as one: dropping it installs it,
+ *  and the card is an ordinary `component`. */
+export type CardKind = "image" | "video" | "note" | "component" | "library" | "text" | "transition" | "sound" | "native" | "link";
+
+/** Share the runtime's midpoint seek so a boundary cannot decode the previous
+ *  picture. A partial final frame uses the midpoint of its available interval;
+ *  a frame starting beyond the source is refused, never relabelled. */
+export function storyboardVideoSeconds(frame: number, fps: Doc3D["fps"], duration: number): number | null {
+  if (!Number.isFinite(duration) || duration <= 0) return null;
+  const start = (frame * fps.den) / fps.num;
+  if (start >= duration) return null;
+  return Math.min(videoFrameSeconds(frame, fps), start + (duration - start) / 2);
+}
+
+/** The components the board cites, for the rail's used-components list. */
+export function storyboardComponentsOf(doc: Doc3D): Array<{ component: string; referenceIds: string[] }> {
+  const byComponent = new Map<string, string[]>();
+  for (const item of doc.resources?.references ?? []) {
+    if (item.type !== "component" || item.component === undefined) continue;
+    const ids = byComponent.get(item.component) ?? [];
+    ids.push(item.id);
+    byComponent.set(item.component, ids);
+  }
+  return [...byComponent.entries()].map(([component, referenceIds]) => ({ component, referenceIds }));
+}
+
+export function isPartId(id: string): boolean {
+  return id.startsWith("part_");
+}
+
+export function isReferenceId(id: string): boolean {
+  return id.startsWith("ref_");
+}
+
+/** A stored still's id (v37). The computed default has none. */
+export function isStillId(id: string): boolean {
+  return id.startsWith("stl_");
+}
+
+/** A gap's derived id, `gap_<from still>_<to still>` (`gapsOf`). Never
+ *  stored, so no document verb may ever be handed one. */
+export function isGapId(id: string): boolean {
+  return id.startsWith("gap_");
+}
+
+/** A cut's derived id, `cut_<outgoing Shot>`. Never stored. */
+export function isCutId(id: string): boolean {
+  return id.startsWith("cut_");
+}
+
+export function cutIdOf(sceneId: string): string {
+  return `cut_${sceneId}`;
+}
+
+/** An id the board selects that names no stored row: a gap or a cut. Delete,
+ *  Duplicate and Rename strip these before any edit. */
+export function isDerivedBoardId(id: string): boolean {
+  return isGapId(id) || isCutId(id);
+}
+
+/** The card kind a reference draws as. An element card (v33) is its own. */
+export function cardKindOf(item: ReferenceItem3D, assets: Doc3D["assets"]): CardKind {
+  if (item.type !== "asset") return item.type;
+  return assets[item.asset]?.kind === "video" ? "video" : "image";
+}
+
+/** An element card in the brief's own words: `text "Ship faster"`,
+ *  `sound sfx`, `native device phone`. One line, for a card body that has
+ *  no picture of its own. */
+export function elementSummary(
+  item: Extract<ReferenceItem3D, { type: "text" | "transition" | "sound" | "native" }>,
+): string {
+  switch (item.type) {
+    case "text":
+      return `"${item.copy}"`;
+    case "transition":
+      return item.kind.replace(/^gl\//, "") + (item.durationFrames === undefined ? "" : ` · ${item.durationFrames} frames`);
+    case "sound":
+      return item.role + (item.asset === undefined ? " · no file yet" : "") + (item.hitMs ? ` · hit ${item.hitMs} ms` : "");
+    case "native":
+      return item.kind + (item.variant === undefined ? "" : ` · ${item.variant}`);
+  }
+}
+
+/**
+ * Case-insensitive match over what a person would type for a shipped item:
+ * its name, its id, a tag or a vibe. `matchesComponent`'s rule, widened to
+ * the two lists the catalog row carries, because "premium" or "typography"
+ * is how the library skill tells an agent to choose and an author searches
+ * the same way.
+ *
+ * AND OVER THE PROSE THE CARD PRINTS. The library browser draws `description`,
+ * `useFor` and `avoidFor` on every card, and a search that cannot find the
+ * words on the card in front of you is a search that looks broken. Those three
+ * plus `category` are exactly what `get_library_item`'s own matcher already
+ * reads (packages/cli/src/mcpLibraryTools.ts), so widening here makes the
+ * rail, the browser and the agent answer one question one way instead of the
+ * three spellings this repo had.
+ */
+export function matchesLibraryItem(row: LibraryItem, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (q === "") return true;
+  const haystack = [
+    row.id,
+    row.name,
+    row.category ?? "",
+    row.useFor ?? "",
+    row.avoidFor ?? "",
+    row.description ?? "",
+    ...row.tags,
+    ...(row.vibe ?? []),
+  ]
+    .join(" ")
+    .toLowerCase();
+  return haystack.includes(q);
+}
+
+/** A link pin's address as a person reads it: the host, without `www.`. The
+ *  validator admits only `https:` addresses, so a parse failure is a document
+ *  that skipped the gate, and it reads as the raw text. Links are never
+ *  fetched. */
+export function linkHost(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www[.]/, "");
+  } catch {
+    return url;
+  }
+}
+
+/** A stored name without its content hash: `1a2b3c4d-logo.png` reads `logo.png`. */
+export function storedName(path: string): string {
+  return path.replace(/^[0-9a-f]{8}-/u, "");
+}
+
+/** Why a registry component on a host other than three is not placed: an
+ *  instance layer only renders a three component. */
+export function instanceHostRefusal(host: string): string {
+  return `A "${host}" component cannot be an instance layer: carry its look with text, image or html layers.`;
+}
+
+// ── A v2: the board as rows BY SHOT ───────────────────────────────────────────
+//
+// The frame and the strip read the film Shot by Shot, in playing order: each
+// Shot with its planned shot (when one links it), its master window, its
+// stills, the gaps between them and the cut into the next Shot. Derived once,
+// pure, so the subject, the menu rows and the tests read one answer.
+
+export interface BoardShotCut {
+  /** `cut_<this Shot>`. */
+  id: string;
+  /** The next Shot in playing order. */
+  incoming: string;
+  /** Whether a transition blends here (`cutPlays`). */
+  plays: boolean;
+}
+
+export interface BoardShot {
+  sceneId: string;
+  scene: Scene3D;
+  /** The planned shot that links this Shot, or null. */
+  part: StoryboardPart3D | null;
+  /** Master frames, `end` exclusive. */
+  window: SceneWindow;
+  stills: VisibleStill[];
+  gaps: StillGap[];
+  /** The cut into the next Shot; null on the last. */
+  cut: BoardShotCut | null;
+}
+
+export function boardShots(doc: Doc3D): BoardShot[] {
+  const parts = doc.storyboard?.parts ?? [];
+  const windows = sceneWindows(doc);
+  return windows.map((window, at): BoardShot => {
+    const scene = doc.scenesById[window.id]!;
+    const stills = visibleStills(scene);
+    const next = windows[at + 1];
+    return {
+      sceneId: window.id,
+      scene,
+      part: parts.find((p) => p.scene === window.id) ?? null,
+      window,
+      stills,
+      gaps: gapsOf(stills),
+      cut: next === undefined ? null : { id: cutIdOf(window.id), incoming: next.id, plays: cutPlays(doc, window.id, next.id) },
+    };
+  });
+}
+
+/** One entry of the strip: a built Shot, or a planned shot
+ *  with no Shot yet, drawn where the plan puts it. */
+export type StoryEntry =
+  | {
+      kind: "shot";
+      shot: BoardShot;
+      /** The planned shot's label when one links it, else the Shot's name. */
+      name: string;
+      /** The chip right after this card: the cut out of this Shot, where its
+       *  transition is saved. Null on the last. A placeholder after the chip
+       *  does not take it: the cut still plays into the next built Shot. */
+      cut: { id: string; label: string } | null;
+    }
+  | { kind: "placeholder"; part: StoryboardPart3D };
+
+/**
+ * THE FILM AS THE BOARD READS IT: every Shot in playing order, and each
+ * planned shot that has no Shot where Make shot would put it, in shot's
+ * `boardSlots` order, the one `screenshot_shot { sketches: "all" }` draws in
+ * too. Pure, so the shot row and the tests read one order.
+ */
+export function storyEntries(doc: Doc3D): StoryEntry[] {
+  const shots = new Map(boardShots(doc).map((shot) => [shot.sceneId, shot]));
+  return boardSlots(doc).map((slot): StoryEntry => {
+    if (slot.sceneId === null) return { kind: "placeholder", part: slot.part };
+    // Non-null: both read `sceneWindows`, one entry per Shot.
+    const shot = shots.get(slot.sceneId)!;
+    const cut = shot.cut === null ? null : { id: shot.cut.id, label: cutLabel(doc, shot) };
+    return { kind: "shot", shot, name: shot.part?.label ?? shot.scene.name, cut };
+  });
+}
+
+/** A cut chip's words: the transition's preset and its played length where
+ *  one blends (`cutPlays`), "Cut" where none does. */
+export function cutLabel(doc: Doc3D, shot: BoardShot): string {
+  const transition = shot.scene.transition;
+  if (shot.cut === null || !shot.cut.plays || transition === undefined) return "Cut";
+  const name = resolveGlPresetSpec(transition.kind)?.label ?? transition.kind;
+  const frames = seamWindow(doc, shot.sceneId)?.durationFrames ?? transition.durationFrames;
+  return `${name} ${formatDuration(framesToSeconds(frames, doc.fps))}`;
+}
+
+/** What the board's one subject is: a still, a gap or a cut, each in its
+ *  Shot. Derived from the selection, never stored, so an edit that removes
+ *  the thing it names leaves nothing stale to clean up. */
+export type BoardSubject =
+  | { kind: "still"; id: string; sceneId: string; still: VisibleStill }
+  | { kind: "gap"; id: string; sceneId: string; gap: StillGap }
+  | { kind: "cut"; id: string; sceneId: string; cut: BoardShotCut };
+
+/** The subject an id names in this document, or null when it names none (an
+ *  unknown id, a still a trim hid, a cut out of the last Shot). */
+export function boardSubjectAt(doc: Doc3D, id: string): BoardSubject | null {
+  if (!isStillId(id) && !isGapId(id) && !isCutId(id)) return null;
+  for (const shot of boardShots(doc)) {
+    if (isStillId(id)) {
+      const still = shot.stills.find((s) => s.id === id);
+      if (still !== undefined) return { kind: "still", id, sceneId: shot.sceneId, still };
+    } else if (isGapId(id)) {
+      const gap = shot.gaps.find((g) => g.id === id);
+      if (gap !== undefined) return { kind: "gap", id, sceneId: shot.sceneId, gap };
+    } else if (shot.cut?.id === id) {
+      return { kind: "cut", id, sceneId: shot.sceneId, cut: shot.cut };
+    }
+  }
+  return null;
+}
+
+/** The board's subject: the selection's one id, when it names a still, a gap
+ *  or a cut. A multi-selection has none. */
+export function boardSubjectOf(doc: Doc3D | null, selection: readonly string[]): BoardSubject | null {
+  if (doc === null || selection.length !== 1) return null;
+  return boardSubjectAt(doc, selection[0]!);
+}
+
+/** A Shot's name on the board: its planned shot's label (`partOfScene`),
+ *  else the Shot's own name. What "Between 02 and 03" says. */
+export function shotNameOf(doc: Doc3D, sceneId: string): string {
+  return partOfScene(doc, sceneId)?.label ?? doc.scenesById[sceneId]?.name ?? sceneId;
+}
+
+/** A Shot's two-digit number as the strip counts it ("02"): its place in
+ *  `storyEntries`, placeholders included, so "Between 02 and 03" and the
+ *  Notes head name the cards the author sees. Null for a Shot the strip does not draw. */
+export function shotNumberOf(doc: Doc3D, sceneId: string): string | null {
+  const at = storyEntries(doc).findIndex((e) => e.kind === "shot" && e.shot.sceneId === sceneId);
+  return at < 0 ? null : String(at + 1).padStart(2, "0");
+}
+
+/** A still's name: its label, else "Frame N" by its place in the Shot's
+ *  stills. What a move's "from → to" head says. */
+export function stillNameOf(stills: readonly VisibleStill[], frame: number): string {
+  const at = stills.findIndex((s) => s.frame === frame);
+  const label = at < 0 ? "" : (stills[at]!.label?.trim() ?? "");
+  return label !== "" ? label : `Frame ${at < 0 ? stills.length + 1 : at + 1}`;
+}
+
+/**
+ * THE MOVE SECTION'S AGENT ASK ("Follow the motion notes", ON): restage the
+ * gap's keys of Shot `sceneId` over `[from, to]` (Shot-local) by its planned
+ * shot's numbered How it moves notes. Prefilled, never sent: the author reads
+ * it and presses send. The rules are what the section reads back: keys
+ * outside the gap are flagged, and a track whose ends sit on the stills reads
+ * as following no notes.
+ */
+export function movePrompt(doc: Doc3D, sceneId: string, from: number, to: number): string {
+  const scene = doc.scenesById[sceneId];
+  const beats = partOfScene(doc, sceneId)?.motion ?? [];
+  const lines = [
+    `Restage the move in Shot ${sceneId}${scene === undefined ? "" : ` ("${scene.name}")`} between frames ${from} and ${to} so it follows the motion notes.`,
+    "",
+    "How it moves:",
+    ...(beats.length === 0
+      ? ["(no notes yet: stagger the moving layers in a readable order)"]
+      : beats.map((beat, at) => {
+          const pin = beat.layer === undefined ? "" : ` (layer ${beat.layer}${beat.path === undefined ? "" : `, track ${beat.path}`})`;
+          return `${at + 1}. ${beat.text}${pin}`;
+        })),
+    "",
+    "Rules:",
+    `- Every key you write sits inside frames ${from} to ${to}, on whole frames of the Shot's own clock.`,
+    "- Give every key an explicit easeOut.",
+    "- The last key of each track holds its value.",
+    `- When a track has keys before frame ${from}, keep a key at frame ${from}.`,
+    "- Write it all in one shot_batch.",
+  ];
+  return lines.join("\n");
+}
+
+/** "Match Sketch 1 at 0.00s. Animate toward Sketch 2 by 1.60s.": what a
+ *  part's sketches ask of the build, each by its Shot-local time when it has
+ *  one. Empty for a part with no sketches. */
+export function sketchTaskOf(doc: Doc3D, part: StoryboardPart3D): string {
+  const sketches = part.sketches ?? [];
+  const at = (frame: number | undefined, word: string): string =>
+    frame === undefined ? "" : ` ${word} ${formatDuration(framesToSeconds(frame, doc.fps))}`;
+  if (sketches.length === 0) return "";
+  const first = `Match Sketch 1${at(sketches[0]!.frame, "at")}.`;
+  const later = sketches.slice(1).map((sketch, i) => `Sketch ${i + 2}${at(sketch.frame, "by")}`);
+  return later.length === 0 ? first : `${first} Animate toward ${later.join(", then ")}.`;
+}
+
+/**
+ * "BUILD PLANNED SHOTS" (S1): ask the agent to build these planned shots in
+ * the Studio, by their stored ids, each with what the board says about it.
+ * Prefilled like `movePrompt`. The board marks the parts Building while the
+ * run is out (`boardBuilding`, session state, never saved). One part is the
+ * shot board's "Ask agent": it leads with the task for that shot alone.
+ */
+export function buildPlannedPrompt(doc: Doc3D, partIds: readonly string[]): string {
+  const parts = (doc.storyboard?.parts ?? []).filter((p) => partIds.includes(p.id));
+  const one = parts.length === 1 ? parts[0]! : null;
+  const lines =
+    one === null ? [`Build these ${parts.length} planned shots from the storyboard in the Studio, in order:`] : [];
+  for (const part of parts) {
+    // A part that links a Shot is built INTO it: add_scene refuses its part
+    // (`already-planned`). A link to a Shot that is gone reads as none. A
+    // linked part names both lengths: the Shot's is the one the board shows.
+    const shot = part.scene === undefined ? undefined : doc.scenesById[part.scene];
+    const lengthOf = (frames: number): string => formatDuration(framesToSeconds(frames, doc.fps));
+    const length =
+      shot === undefined
+        ? lengthOf(part.durationFrames)
+        : `planned ${lengthOf(part.durationFrames)}, its Shot runs ${lengthOf(shot.durationFrames)}`;
+    const task = sketchTaskOf(doc, part);
+    const title = `${partTitleOf(doc, part.id) ?? part.label} (#${part.id}), ${length}.${task === "" ? "" : ` ${task}`}`;
+    lines.push(one === null ? `- ${title}` : `Task: build ${title}`);
+    if (part.notes !== undefined) lines.push(`  What we see: ${part.notes.trim().replace(/\s+/g, " ")}`);
+    if (part.voice !== undefined) lines.push(`  Voice: “${part.voice}”`);
+    const sketches = part.sketches ?? [];
+    if (sketches.length > 0) {
+      lines.push(
+        `  Sketches: ${sketches.map((sketch, i) => `${sketch.id} (Sketch ${i + 1})`).join(", ")}. ` +
+          "Look at one with screenshot_shot and its sketch id.",
+      );
+    }
+    lines.push(
+      shot === undefined
+        ? `  No Shot yet: make it with add_scene and part "#${part.id}".`
+        : `  Its Shot: ${shot.name} (#${part.scene}). Build into it, never add_scene for it.`,
+    );
+    if (part.built !== undefined) {
+      lines.push(`  Already marked built at frame ${part.built.frame} of its Shot: change it only if asked.`);
+    }
+  }
+  lines.push(
+    "",
+    "Read the whole board first with get_storyboard: the Style cards guide every shot, a card pinned to a part guides only that one, and each sketch is printed as layout text in layer units.",
+    parts.some((part) => (part.sketches?.length ?? 0) > 0)
+      ? "Match Sketch 1's positions and sizes, animate toward the later sketches by their times, and keep the Style. Then check your frames with screenshot_shot."
+      : "Keep the Style. Then check your frames with screenshot_shot.",
+    "A part with no Shot gets one from add_scene carrying its part ({ op: \"add_scene\", part: \"#part_id\" }): that links it and places it in the plan's order, in one write.",
+    "Never add_scene for a part that already has a Shot. Build each Shot in one shot_batch.",
+  );
+  return lines.join("\n");
+}
+
+/** A shot card's status (D5): Built once "Mark shot built" ran, Building while
+ *  this session's agent run is out for it, else Planned. Never stored. */
+export type ShotStatus = "planned" | "building" | "built";
+
+export function shotStatusOf(part: StoryboardPart3D | null, building: readonly { part: string }[]): ShotStatus {
+  if (part === null) return "planned";
+  if (part.built !== undefined) return "built";
+  return building.some((b) => b.part === part.id) ? "building" : "planned";
+}
+
+export const SHOT_STATUS_LABEL: Record<ShotStatus, string> = { planned: "Planned", building: "Building", built: "Built" };
+
+/** A shot card's length in frames (decision 1, agent experience plan): its
+ *  linked Shot's (`partFramesOf`, the length every agent text promises), else
+ *  the plan's. "Mark shot built" sets the picture and the Built status, never
+ *  the length. A Shot no part links has only its own. */
+export function shotLengthOf(doc: Doc3D, part: StoryboardPart3D | null, scene: Scene3D | null): number {
+  return part === null ? (scene?.durationFrames ?? 0) : partFramesOf(doc, part);
+}
+
+/** The board's Style row: the cards no planned shot holds, in rank order. */
+export function styleItemsOf(doc: Doc3D): ReferenceItem3D[] {
+  return referencesByPart(doc).global.references;
+}
+
+/** The first image card Sketch 1 draws (v44), the card picture until the
+ *  board draws a sketch itself. A migrated part picture is exactly this. */
+export function sketchPictureOf(doc: Doc3D, part: StoryboardPart3D): ShotAsset | undefined {
+  for (const item of part.sketches?.[0]?.items ?? []) {
+    if (item.kind !== "ref") continue;
+    const card = doc.resources?.references?.find((r) => r.id === item.ref);
+    const asset = card?.type === "asset" ? doc.assets[card.asset] : undefined;
+    if (asset?.kind === "image") return asset;
+  }
+  return undefined;
+}
+
+/** A planned shot as the board's cards name it ("03 Make it move"): its
+ *  place in `storyEntries`, then its label. Null for a part that is gone. */
+export function partTitleOf(doc: Doc3D, partId: string): string | null {
+  const part = doc.storyboard?.parts.find((p) => p.id === partId);
+  if (part === undefined) return null;
+  const at = storyEntries(doc).findIndex((e) => (e.kind === "shot" ? e.shot.part?.id : e.part.id) === partId);
+  return at < 0 ? part.label : `${String(at + 1).padStart(2, "0")} ${part.label}`;
+}
+
+/** What the drop dialog's scope writes. */
+export type DropScope = "style" | "shot" | "keep";
+
+/**
+ * THE DROP DIALOG'S "AGENT READS" LINE, in `storyboardBrief`'s own words:
+ * cards dropped with one note print as "Together (N cards). Note: …" under
+ * Global or under their planned shot. Keep makes no card, so the brief says
+ * nothing about it.
+ */
+export function dropBriefLine(count: number, note: string, scope: DropScope, partLabel: string | null): string {
+  if (scope === "keep") return "Agent reads nothing yet. Kept files wait in Assets until a card uses them.";
+  const where = scope === "style" ? "Global, the whole reel" : (partLabel ?? "the shot you pick");
+  const text = note.trim().replace(/\s+/g, " ");
+  const cards = count === 1 ? "1 card" : `Together (${count} cards)`;
+  return `Agent reads, under ${where}: ${cards}.${text === "" ? " No note yet: say why so it knows what to take." : ` Note: ${text}`}`;
+}
+
+/** The planned shot the board is adding to: the open shot board's
+ *  (`storyboardPlan`), else null, which is Style. Where a board Add, a paste
+ *  and Select all land. The board enters no Shot, so the plan is the only
+ *  thing that can name one. */
+export function boardTargetOf(s: { doc: Doc3D | null; storyboardPlan: string | null }): string | null {
+  if (s.doc === null || s.storyboardPlan === null) return null;
+  return s.doc.storyboard?.parts.some((p) => p.id === s.storyboardPlan) === true ? s.storyboardPlan : null;
+}
+
+/** The shot board's view state, as `sketchViewIn` revalidates it. */
+export interface SketchView {
+  storyboardPlan: string | null;
+  storyboardSketch: string | null;
+  sketchSelection: readonly string[];
+  sketchPlaying: boolean;
+  sketchGuide: { partId: string; sketchId: string } | null;
+}
+
+/**
+ * THE SHOT BOARD'S VIEW AFTER A WRITE: only the keys that must change, so a
+ * write that touched nothing here patches nothing. A delete, an undo or an
+ * agent write can take the plan, its sketch or an item away:
+ *
+ * - a plan whose part is gone closes, with everything under it;
+ * - a sketch that is gone gives way to the plan's first, and a plan that
+ *   gains its first sketch (an agent's `set_sketch`) shows it;
+ * - the selection keeps only items of the sketch on screen;
+ * - Play stops with no sketch to play;
+ * - the Studio guide goes with its sketch.
+ */
+export function sketchViewIn(doc: Doc3D, s: SketchView): Partial<SketchView> {
+  const out: Partial<SketchView> = {};
+  const part = s.storyboardPlan === null ? undefined : doc.storyboard?.parts.find((p) => p.id === s.storyboardPlan);
+  if (s.storyboardPlan !== null && part === undefined) out.storyboardPlan = null;
+  const sketches = part === undefined ? [] : sketchesOf(doc, part.id);
+  const sketch = sketches.find((k) => k.id === s.storyboardSketch) ?? sketches[0];
+  const sketchId = sketch?.id ?? null;
+  if (sketchId !== s.storyboardSketch) out.storyboardSketch = sketchId;
+  const items = new Set(sketch?.items.map((item) => item.id) ?? []);
+  const kept = s.sketchSelection.filter((id) => items.has(id));
+  if (kept.length !== s.sketchSelection.length) out.sketchSelection = kept;
+  if (s.sketchPlaying && sketch === undefined) out.sketchPlaying = false;
+  const guide = s.sketchGuide;
+  if (guide !== null && !sketchesOf(doc, guide.partId).some((k) => k.id === guide.sketchId)) out.sketchGuide = null;
+  return out;
+}
+
+/**
+ * A NEW SHOT'S DEFAULT NAME: "Shot N" from the count of Shots and planned
+ * shots, stepped past any name a Shot or a planned shot already has, so two
+ * cards never read the same.
+ */
+export function nextShotName(doc: Doc3D): string {
+  const parts = doc.storyboard?.parts ?? [];
+  const taken = new Set<string>(parts.map((p) => p.label));
+  for (const id of doc.scenes) taken.add(doc.scenesById[id]?.name ?? "");
+  for (let n = Math.max(doc.scenes.length, parts.length) + 1; ; n += 1) {
+    if (!taken.has(`Shot ${n}`)) return `Shot ${n}`;
+  }
+}
+