@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/workspace.ts

@@ -0,0 +1,1147 @@
+// WHICH WORKSPACE THE WINDOW IS IN, and what that allows.
+//
+// The docked shell has one grid and four workspaces. The stage workspace is
+// the editor; the other three are modes that show their own content in the
+// same cells: the Storyboard, the material nodes and Components (a component
+// alone on the stage, with the Component Studio or Code Studio as its Edit
+// tab). The top bar, the columns and the bottom row stay on screen in every
+// one of them, so the chrome that used to be unreachable behind a full-window
+// mode (the app menu, the shot switcher, Export) has to know which workspace
+// it is in and refuse what does not apply there, with the reason.
+//
+// Pure functions of state, beside `storyboardBlocker` in spirit: every reader
+// (the shell's classes, the menu, the header, the cells) asks the same
+// question and gets the same answer.
+import {
+  COMPONENT_LISTING_ID_RE,
+  GENERATED_SHOTS_DIR,
+  INSTANCE_PROP_PREFIX,
+  WORKSPACE_COMPONENT_ID_RE,
+  clearReferenceProp,
+  componentFilesOf,
+  componentUsesOf,
+  exposedMasterValue,
+  exposedSpecOf,
+  homeOf,
+  instanceComponentIdsOf,
+  instanceExportOf,
+  instanceModuleOf,
+  layerSnapshotContract,
+  lockRefusal,
+  lockedLayerEdited,
+  patchHome,
+  setReferenceProp,
+  toTrackHex,
+} from "@dailies-studio/shot/doc";
+import type { ComponentDef3D, ComponentUse, Doc3D, Layer3D } from "@dailies-studio/shot/doc";
+import { coerceValue, controlLabel, humanizeKey } from "@dailies-studio/contract";
+import type { Contract } from "@dailies-studio/contract";
+import { formatHex, parseHex, valueEquals } from "@dailies-studio/engine";
+import type { Value } from "@dailies-studio/engine";
+import { isProjectComponent } from "@dailies-studio/ui";
+import type {
+  ComponentFileHome,
+  ComponentListingUpdate,
+  ComponentRow,
+  WorkspaceComponent,
+  WorkspaceComponentVersionInfo,
+} from "../api.js";
+import { isCutId, isGapId, isPartId, isReferenceId, shotNumberOf } from "./storyboardModel.js";
+import type { ComponentsSelection, ShotEditorState } from "./types.js";
+
+export type Workspace = "stage" | "storyboard" | "material" | "components";
+
+type WorkspaceFields = Pick<
+  ShotEditorState,
+  "materialWorkspace" | "codeComponent" | "editingDef" | "storyboardOpen"
+> &
+  Partial<Pick<ShotEditorState, "componentsOpen" | "componentsTab">>;
+
+/**
+ * Every field `workspaceOf` reads. A write that names none of them cannot
+ * move the workspace: the store's mode guards skip their work for it (`set`).
+ */
+export const WORKSPACE_KEYS = [
+  "materialWorkspace",
+  "codeComponent",
+  "editingDef",
+  "componentsOpen",
+  "storyboardOpen",
+] as const satisfies readonly (keyof WorkspaceFields)[];
+
+// The other direction, as `SHOT_KINDS` has it: every field a workspace is read
+// from is in the list, so a mode `workspaceOf` learns to read (a field added
+// to `WorkspaceFields`) fails to compile until it is listed, and a field taken
+// off the list does too. `componentsTab` is the one it never reads: the tab
+// inside Components (`componentEditOpen`'s).
+type _EveryWorkspaceFieldListed =
+  Exclude<keyof WorkspaceFields, "componentsTab"> extends (typeof WORKSPACE_KEYS)[number] ? true : never;
+const _workspaceFieldsListed: _EveryWorkspaceFieldListed = true;
+void _workspaceFieldsListed;
+
+/**
+ * The workspace on screen. One precedence, spelled once: each mode's own
+ * entry clears the others, so two are never open at once in practice, and
+ * this order says which wins if they ever are. An open definition is always
+ * Components: every door into a component lands there, standalone, never in
+ * the Shot that holds it.
+ */
+export function workspaceOf(s: WorkspaceFields): Workspace {
+  if (s.materialWorkspace !== null) return "material";
+  if (s.codeComponent !== null) return "components";
+  if (s.editingDef !== null) return "components";
+  if (s.componentsOpen === true) return "components";
+  if (s.storyboardOpen) return "storyboard";
+  return "stage";
+}
+
+/**
+ * Components' Edit tab on a Studio-made definition (mock C6): the layers
+ * outline, the tool footer and the def timeline are the editor here, so the
+ * stage's verbs apply to the definition's interior.
+ */
+export function componentEditOpen(s: WorkspaceFields): boolean {
+  return workspaceOf(s) === "components" && s.codeComponent === null && s.editingDef !== null && s.componentsTab === "edit";
+}
+
+/** How to get out of each mode, said once for every refusal below. */
+const LEAVE: Record<Exclude<Workspace, "stage" | "storyboard">, string> = {
+  material: "Close the material nodes",
+  components: "Close Components",
+};
+
+/**
+ * Why Export cannot run now, or null. The stage in these three modes is
+ * drawing one object or one component, not the film, and an export captures
+ * the stage. The board is fine: it draws over the film without replacing it.
+ */
+export function exportBlocker(
+  s: WorkspaceFields & Partial<Pick<ShotEditorState, "doc" | "componentBuilds" | "library">>,
+): string | null {
+  const ws = workspaceOf(s);
+  if (ws !== "stage" && ws !== "storyboard") {
+    return `${LEAVE[ws]} before exporting: the stage is showing ${ws === "material" ? "one object" : "one component"}, not the film.`;
+  }
+  // A FAILING BUILD keeps its last good module playing (graph.ts `lastGood`),
+  // so the film on screen is not what the source says. Exporting it would
+  // ship a stale component silently.
+  if (s.doc == null || s.componentBuilds === undefined) return null;
+  for (const id of instanceComponentIdsOf(s.doc)) {
+    if (s.componentBuilds[id]?.status !== "failed") continue;
+    const name = s.library?.find((r) => r.id === id)?.name ?? instanceExportOf(id);
+    return `A component has a failing build: ${name}. Fix it before exporting.`;
+  }
+  return null;
+}
+
+/**
+ * The app-menu rows each mode keeps, as exact ids or `prefix.` families.
+ * AN ALLOWLIST, on `MATERIAL_WORKSPACE_KEYS`' reasoning: a new row is refused
+ * in a mode until somebody decides it applies there, which is the safe
+ * direction. The rows kept everywhere are about the window, the account and
+ * the transport, never about the stage's selection.
+ */
+const EVERYWHERE = [
+  "acct.",
+  "help",
+  "file.save",
+  "file.versions",
+  "view.panel.",
+  "view.badges.",
+  "view.appearance.",
+  "time.play",
+  "time.previewMuted",
+  // The Storyboard row is the top bar's segment, which hands over from every
+  // mode (`setStoryboardOpen`).
+  "ctx.storyboard",
+];
+
+const ALLOWED: Record<"material" | "def" | "code", readonly string[]> = {
+  // The object's pane is a real working view and the timeline is on screen:
+  // the same verbs its keys keep (`MATERIAL_WORKSPACE_KEYS`).
+  material: [
+    ...EVERYWHERE,
+    "edit.undo",
+    "edit.redo",
+    "time.",
+    "view.fit",
+    "view.fitSelection",
+    "view.zoomIn",
+    "view.zoomOut",
+    "view.ortho",
+    "view.orbit.",
+    "view.preset.",
+  ],
+  // Components with a definition open on Preview: its own clock runs, and
+  // nothing edits the interior until the Edit tab.
+  def: [...EVERYWHERE, "edit.undo", "edit.redo", "time.step.", "time.fit", "time.mode."],
+  // Components with a code component open, or with nothing open yet. Undo and
+  // redo are face-dependent, so `commandBlocker` decides them below.
+  code: EVERYWHERE,
+};
+
+const allows = (list: readonly string[], id: string): boolean =>
+  list.some((rule) => (rule.endsWith(".") || rule.endsWith(":") ? id.startsWith(rule) : id === rule));
+
+/**
+ * Why nothing can change for a viewer. Every refusal in a read-only Project
+ * says this one sentence: the store's `viewOnly`, the menu, the keys, the
+ * tool rail and the panels.
+ */
+export const VIEW_ONLY = "You can view this Project but not edit it. Ask a Project admin for edit access.";
+
+/** Why the comment tool and the Comments tab refuse a caller the server says
+ *  may not comment (`LoadedShot.can.comment === false`). */
+export const NO_COMMENT = "You cannot comment on this Project. Ask a Project admin for access.";
+
+/** Why nothing can change while a saved version is on screen. */
+export const PREVIEW_ONLY = "You are looking at a saved version. Go back to the current version, or restore this one, to edit.";
+
+/** Why nothing can change while live sync holds the Project (R5). */
+export const SYNC_HOLD_REASON = {
+  upgrade: "This Project was upgraded by a newer version of the editor. Reload to keep editing.",
+  "older-server": "This editor is newer than the server it reaches. Editing waits until the server catches up.",
+  quota: "Edits cannot be stored on this device. Free up space, then try again.",
+} as const;
+
+/** The sentence a read-only chrome says: a version preview's, else a sync
+ *  hold's, else the viewer's. Every reader of `readOnly` that words a refusal
+ *  asks this. */
+export function readOnlyReason(s: { versionPreview?: unknown; syncStatus?: { hold: keyof typeof SYNC_HOLD_REASON | null } | null }): string {
+  if (s.versionPreview != null) return PREVIEW_ONLY;
+  const hold = s.syncStatus?.hold ?? null;
+  return hold === null ? VIEW_ONLY : SYNC_HOLD_REASON[hold];
+}
+
+/**
+ * The app-menu rows a viewer keeps, as exact ids or `prefix.` families. An
+ * allowlist for the reason `ALLOWED` is one: a new row is refused to a viewer
+ * until somebody decides it writes nothing. Each row here changes only the
+ * window, the view, the playhead or the selection, never the document.
+ */
+const VIEW_ONLY_ALLOWED = [
+  "acct.",
+  "help",
+  "file.export",
+  "file.versions",
+  "view.panel.",
+  "view.badges.",
+  "view.appearance.",
+  "view.layout.",
+  "view.shading.",
+  "view.preset.",
+  "view.orbit.",
+  "view.video",
+  "view.ortho",
+  "view.grid",
+  "view.zoomIn",
+  "view.zoomOut",
+  "view.zoomReset",
+  "view.fit",
+  "view.fitSelection",
+  "view.selectMovesPlayhead",
+  // The board's Project assets panel: a viewer reads it, every row locked.
+  "board-assets",
+  // A shot's board: a view, which writes nothing for a planned shot.
+  "board-open-board",
+  // The Preferences page and its View rows write the viewer's own prefs,
+  // never the document.
+  "prefs.",
+  "view.rulers",
+  "view.smartGuides",
+  "view.motionPaths",
+  "time.play",
+  "time.previewMuted",
+  "time.step.",
+  "time.fit",
+  "time.mode.",
+  "time.workArea.",
+  "edit.copy",
+  // The motion clip's copies read the document and write nothing to it.
+  "edit.copyAnimation",
+  "edit.copyEffects",
+  "edit.selectAll",
+  "edit.deselect",
+  "tool.select",
+  "ctx.",
+  "comp.edit:",
+  "layer.isolate.exitAll",
+  "isolation",
+  "code.path",
+  "shot-open",
+  "shot-zoom",
+  "shot-transition",
+  "shot-copy-effects",
+  // The right-click rows that only open, select or change the view, and the
+  // copies, which write nothing to the document.
+  "copy",
+  "copy-animation",
+  "copy-effects",
+  "open-3d",
+  "material",
+  "graph-open",
+  "graph-copy",
+  "key-select-track",
+  "path-key-seek",
+];
+
+/** Why a viewer cannot run this row (by its command id), or null. */
+export function viewOnlyBlocker(id: string): string | null {
+  return allows(VIEW_ONLY_ALLOWED, id) ? null : VIEW_ONLY;
+}
+
+/**
+ * Why an app-menu row (by its command id) cannot run in this workspace, or
+ * null. The menu and WebMCP's `run_command` both read rows through
+ * `appMenuEntries`, which applies this, so the two cannot disagree.
+ */
+export function commandBlocker(
+  s: WorkspaceFields &
+    Partial<Pick<ShotEditorState, "readOnly" | "versionPreview" | "syncStatus">>,
+  id: string,
+): string | null {
+  if (s.readOnly === true && viewOnlyBlocker(id) !== null) return readOnlyReason(s);
+  const ws = workspaceOf(s);
+  if (ws === "stage") return null;
+  if (ws === "storyboard") return boardCommandBlocker(id);
+  // The Edit tab edits the definition's layers with the stage's own verbs. An
+  // export still captures the stage, which shows one component.
+  if (componentEditOpen(s)) return id === "file.export" ? exportBlocker(s) : null;
+  const rows =
+    ws === "material" ? ALLOWED.material : s.codeComponent === null && s.editingDef !== null ? ALLOWED.def : ALLOWED.code;
+  if (allows(rows, id)) return null;
+  if (id === "file.export") return exportBlocker(s);
+  // In Code Studio the menu's undo walks the defaults history (`store.undo`);
+  // CodeMirror keeps its own for keys typed in the editor.
+  if (ws === "components" && s.codeComponent !== null && (id === "edit.undo" || id === "edit.redo")) return null;
+  return `${LEAVE[ws]} first: this acts on the scene, which is not on screen.`;
+}
+
+/** Why a component row cannot open in Components (D8): Dailies components
+ *  are three only. The Components list, the board's library and the Assets
+ *  tab say this one sentence on a dom row. */
+export const DOM_NOT_SUPPORTED = "Not supported: Dailies components are React Three Fiber";
+
+/** Why a built-in (`ComponentRow.builtin`: it ships inside a package) has no
+ *  door into Components: there is no source file and no master to open. The
+ *  doors that would refuse it on a press (Open in Components, Edit master)
+ *  show disabled with this sentence instead. */
+export const BUILTIN_NO_MASTER = "Built into Dailies: it has no source to open or edit.";
+
+/** Whether a registry id names a built-in. */
+export function isBuiltinComponent(library: readonly ComponentRow[], componentId: string | undefined): boolean {
+  return componentId !== undefined && library.some((row) => row.id === componentId && row.builtin === true);
+}
+
+/** One row of the Components list. A dom code component the Project uses is
+ *  listed with `refusal` set and never opens. */
+export interface ComponentsListRow {
+  sel: ComponentsSelection;
+  name: string;
+  refusal: string | null;
+  /** A Studio-made copy's `origin.source`: the workspace component (or the
+   *  Community listing) it was copied from. */
+  copyOf?: string;
+}
+
+/** Whether a module path is a Project's generated film (`src/shots/<Name>.tsx`),
+ *  a build product and never a code component of its own. */
+const isGeneratedFilm = (rel: string): boolean => rel.startsWith(`${GENERATED_SHOTS_DIR}/`);
+
+/**
+ * The Components list: this document's Studio-made definitions first, then
+ * every component of each code file made for it (`componentFiles`, in list
+ * order, registry order within a file), then the code components it uses
+ * (instance layers and board cards), in the order the document first uses
+ * them, each followed by the other components of its file, each once. A file
+ * made for it is listed even when nothing places it:
+ * membership is not a use. A built-in has no source file in this Project, a
+ * generated film is a build product, and a component the registry does not
+ * know is left out until the library answers. The open subject is not added:
+ * a component neither section lists has no row, and the crumb names it.
+ */
+export function componentsListOf(doc: Doc3D, library: readonly ComponentRow[]): ComponentsListRow[] {
+  const rows: ComponentsListRow[] = Object.values(doc.components ?? {}).map((def) => ({
+    sel: { kind: "studio", def: def.id },
+    name: def.name,
+    refusal: null,
+    ...(def.origin === undefined ? {} : { copyOf: def.origin.source }),
+  }));
+  const seen = new Set<string>();
+  const add = (row: ComponentRow): void => {
+    if (seen.has(row.id) || row.builtin === true) return;
+    seen.add(row.id);
+    rows.push({
+      sel: { kind: "code", module: row.id },
+      name: row.name,
+      refusal: row.host === "three" ? null : DOM_NOT_SUPPORTED,
+    });
+  };
+  for (const path of componentFilesOf(doc)) {
+    if (isGeneratedFilm(path)) continue;
+    for (const row of library) if (row.rel === path) add(row);
+  }
+  for (const use of componentUsesOf(doc)) {
+    if (use.component === undefined) continue;
+    const row = library.find((r) => r.id === use.component);
+    if (row !== undefined) add(row);
+    // THE FILE IS THE UNIT: Your library counts a file this Project uses as
+    // its own (`ownFilesOf`, and `homePaths` for every other Project), so the
+    // file's other components list here too, or they would show in neither
+    // section. By the use's module, not its row: a renamed or deleted export
+    // leaves a stale id whose file still holds the others.
+    const path = instanceModuleOf(use.component);
+    for (const mate of library) if (mate.rel === path) add(mate);
+  }
+  return rows;
+}
+
+/** One entry of YOUR LIBRARY (`libraryComponentsOf`): a code component of
+ *  the registry, or a Studio-made component another Project recorded and
+ *  someone added to the library. `why` is the rule that lists a code one,
+ *  the first that holds: a Dailies Library install, code made for no
+ *  Project, or "In your library" ticked (`WorkspaceComponent.library`). */
+export type LibraryEntry =
+  | {
+      kind: "code";
+      module: string;
+      name: string;
+      rel: string;
+      refusal: string | null;
+      why: "unassigned" | "installed" | "added";
+      /** An install's publisher, as the registry's provenance says it. */
+      publisher?: string;
+      /** The workspace store's row for it, once one was recorded. */
+      recorded?: WorkspaceComponent;
+    }
+  | { kind: "studio"; component: WorkspaceComponent };
+
+/** Why a component is in Your library whatever its "In your library" box
+ *  says. The Components panel shows the box ticked with this line. */
+export const LIBRARY_RULE = {
+  installed: "Dailies Library installs are always in your library.",
+  unassigned: "Code made for no Project is always in your library.",
+  copied: "Copied from your library.",
+} as const;
+
+/** The module paths `doc` itself lists as made for it or uses: what `homes`
+ *  says of every OTHER Project, read from the live document for this one, so
+ *  an edit counts before the server has seen it. */
+function ownFilesOf(doc: Doc3D): Set<string> {
+  const files = new Set(componentFilesOf(doc));
+  for (const use of componentUsesOf(doc)) if (use.component !== undefined) files.add(instanceModuleOf(use.component));
+  return files;
+}
+
+/** The files another Project lists or uses. Homes of this Project are left
+ *  to the live document, and a home the caller may not name (`projectId`
+ *  null) is still another Project's. */
+function filesElsewhere(doc: Doc3D, homes: readonly ComponentFileHome[]): Set<string> {
+  return new Set(homes.filter((h) => h.projectId !== doc.id).map((h) => h.path));
+}
+
+/** CODE MADE FOR NO PROJECT: the user's own three code that no Project lists
+ *  or uses, never a built-in and never a generated film. */
+function madeForNoProject(row: ComponentRow, own: ReadonlySet<string>, elsewhere: ReadonlySet<string>): boolean {
+  if (!isProjectComponent(row) || row.host !== "three" || isGeneratedFilm(row.rel)) return false;
+  return !own.has(row.rel) && !elsewhere.has(row.rel);
+}
+
+/** Case-insensitive by name, then by module or id, so the order never
+ *  depends on which list a row arrived in. */
+function entryOrder(a: LibraryEntry, b: LibraryEntry): number {
+  const key = (e: LibraryEntry): [string, string] =>
+    e.kind === "code" ? [e.name.toLowerCase(), e.module] : [e.component.name.toLowerCase(), e.component.id];
+  const [an, ak] = key(a);
+  const [bn, bk] = key(b);
+  if (an !== bn) return an < bn ? -1 : 1;
+  return ak < bk ? -1 : ak > bk ? 1 : 0;
+}
+
+/**
+ * YOUR LIBRARY: what every Project of this workspace offers beside its own.
+ *
+ *   (a) code made for no Project: the user's own three code whose file no
+ *       Project lists or uses (`homes` for the others, the live document for
+ *       this one). It waits while `homes` is null, so it never lists a file
+ *       some Project holds before the index has answered.
+ *   (b) Dailies Library installs (`library.scope` "shared"), even when a
+ *       Project lists them.
+ *   (c) what someone added with "In your library": a Studio-made component
+ *       of another Project, or code made for one. A flagged code row the
+ *       registry does not list has nothing to open, so it is left out.
+ *
+ * Less what This project already shows (`projectRows`): code by module, a
+ * definition by the copy that names it (`copyOf`) or by its own row.
+ * Sorted by name.
+ */
+export function libraryComponentsOf(
+  doc: Doc3D,
+  library: readonly ComponentRow[],
+  workspace: readonly WorkspaceComponent[] | null,
+  homes: readonly ComponentFileHome[] | null,
+  projectRows: readonly ComponentsListRow[],
+): LibraryEntry[] {
+  const shown = new Set(projectRows.flatMap((r) => (r.sel.kind === "code" ? [r.sel.module] : [])));
+  const own = ownFilesOf(doc);
+  const elsewhere = homes === null ? null : filesElsewhere(doc, homes);
+  const entries: LibraryEntry[] = [];
+  for (const row of library) {
+    if (shown.has(row.id)) continue;
+    const recorded = workspaceRowOf(workspace, doc.id, { kind: "code", module: row.id });
+    const why =
+      row.library?.scope === "shared"
+        ? "installed"
+        : elsewhere !== null && madeForNoProject(row, own, elsewhere)
+          ? "unassigned"
+          : recorded?.library === true
+            ? "added"
+            : null;
+    if (why === null) continue;
+    const publisher = why === "installed" ? row.library?.publisher : undefined;
+    entries.push({
+      kind: "code",
+      module: row.id,
+      name: row.name,
+      rel: row.rel,
+      refusal: row.host === "three" ? null : DOM_NOT_SUPPORTED,
+      why,
+      ...(publisher === undefined ? {} : { publisher }),
+      ...(recorded === undefined ? {} : { recorded }),
+    });
+  }
+  for (const c of workspace ?? []) {
+    if (c.library !== true || !("def" in c.home)) continue;
+    // A COPY IS THIS PROJECT'S NOW: a definition whose origin names the row
+    // (Use here, or the shot board's picker, made it) lists in the Project.
+    if (projectRows.some((r) => r.copyOf === c.id || workspaceRowOf([c], doc.id, r.sel) !== undefined)) continue;
+    entries.push({ kind: "studio", component: c });
+  }
+  return entries.sort(entryOrder);
+}
+
+/**
+ * Why `sel` is in Your library whatever its "In your library" box says, or
+ * null when the box decides: an install, code no Project lists or uses
+ * (this document counted from the live copy), or a copy of a definition the
+ * library holds. The same rules `libraryComponentsOf` lists by, so the box
+ * and the list never disagree.
+ */
+export function libraryRuleOf(
+  doc: Doc3D,
+  sel: ComponentsSelection,
+  library: readonly ComponentRow[],
+  workspace: readonly WorkspaceComponent[],
+  homes: readonly ComponentFileHome[],
+): string | null {
+  if (sel.kind === "studio") {
+    const source = doc.components?.[sel.def]?.origin?.source;
+    return source !== undefined && workspace.some((c) => c.id === source && c.library === true) ? LIBRARY_RULE.copied : null;
+  }
+  const row = library.find((r) => r.id === sel.module);
+  if (row === undefined) return null;
+  if (row.library?.scope === "shared") return LIBRARY_RULE.installed;
+  return madeForNoProject(row, ownFilesOf(doc), filesElsewhere(doc, homes)) ? LIBRARY_RULE.unassigned : null;
+}
+
+/** A Your library entry's name, whichever kind it is. */
+export function libraryEntryName(entry: LibraryEntry): string {
+  return entry.kind === "code" ? entry.name : entry.component.name;
+}
+
+/** Where a Your library entry comes from: an install's publisher (else
+ *  "Dailies Library"), other code's file name, a definition's home Project
+ *  by name (`homeName`), or "another Project" when the caller may not see
+ *  that Project. Here, beside the lists, so the shot board's picker reads it
+ *  without the Components rail. */
+export function libraryHomeLabel(entry: LibraryEntry): string {
+  if (entry.kind === "studio") return entry.component.homeName ?? "another Project";
+  if (entry.why === "installed") return entry.publisher ?? "Dailies Library";
+  return entry.rel.slice(entry.rel.lastIndexOf("/") + 1);
+}
+
+/** The workspace component a selection is, by its home. */
+export function workspaceRowOf(
+  list: readonly WorkspaceComponent[] | null,
+  projectId: string | undefined,
+  sel: ComponentsSelection | null,
+): WorkspaceComponent | undefined {
+  if (list === null || sel === null) return undefined;
+  return list.find((c) =>
+    sel.kind === "studio"
+      ? "def" in c.home && c.home.def === sel.def && c.home.projectId === projectId
+      : "component" in c.home && c.home.component === sel.module,
+  );
+}
+
+/** The contract keys the previous version did not have (versions newest
+ *  first, the first being the build on screen). None before a second one. */
+export function newPropKeys(keys: readonly string[], versions: readonly WorkspaceComponentVersionInfo[] | undefined): string[] {
+  const previous = versions?.[1];
+  if (previous === undefined) return [];
+  return keys.filter((k) => !previous.propKeys.includes(k));
+}
+
+/** Whether two selections name the same component. */
+export function sameComponent(a: ComponentsSelection | null, b: ComponentsSelection | null): boolean {
+  if (a === null || b === null) return a === b;
+  return a.kind === "studio" ? b.kind === "studio" && a.def === b.def : b.kind === "code" && a.module === b.module;
+}
+
+/** The component Components shows now, from the open subject. */
+export function componentsSubject(s: Pick<ShotEditorState, "codeComponent" | "editingDef">): ComponentsSelection | null {
+  if (s.codeComponent !== null) return { kind: "code", module: s.codeComponent };
+  if (s.editingDef !== null) return { kind: "studio", def: s.editingDef };
+  return null;
+}
+
+/** The Every use view when it is up for the component Components shows now,
+ *  else null: a view opened for another subject, or left behind by a door
+ *  out of Components, shows nothing. */
+export function usesViewOf(
+  s: WorkspaceFields & Pick<ShotEditorState, "codeComponent" | "editingDef" | "componentUses">,
+): { subject: ComponentsSelection; use: string | null } | null {
+  const view = s.componentUses;
+  if (view === null || workspaceOf(s) !== "components") return null;
+  return sameComponent(view.subject, componentsSubject(s)) ? view : null;
+}
+
+/** Components without the timeline row: nothing open, the Preview tab (its
+ *  transport sits 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. */
+export function componentsHideTimeline(
+  s: WorkspaceFields & Pick<ShotEditorState, "codeComponent" | "editingDef" | "componentsTab">,
+): boolean {
+  if (workspaceOf(s) !== "components") return false;
+  return s.codeComponent !== null || s.editingDef === null || s.componentsTab === "preview";
+}
+
+/** The board's half of `commandBlocker`. The board enters no Shot, so the
+ *  Studio's context rows (All shots) act on a view that is not on screen:
+ *  they are the Studio's. */
+function boardCommandBlocker(id: string): string | null {
+  if (id === "ctx.scene") return "All shots is the Studio's view. Close the Storyboard to see the whole film.";
+  return null;
+}
+
+/** The planned shot whose shot board is on screen, or null: the board is
+ *  closed, or it shows every shot. A closed board keeps `storyboardPlan` for
+ *  the way back, so every reader asks this rather than the field. */
+export function shotBoardOf(s: Pick<ShotEditorState, "storyboardOpen" | "storyboardPlan">): string | null {
+  return s.storyboardOpen ? s.storyboardPlan : null;
+}
+
+/** Which panel the board's right column shows: the agent, the comments, the
+ *  component sheet (S3: exactly one component card), the
+ *  inspector (any other card, a gap or a cut), the Plan panel (one shot
+ *  card), or nothing (no selection: the canvas takes the whole width). On a
+ *  shot board: the agent, the comments, the item inspector (`"sketch"`, any
+ *  sketch item selected), Project assets, else the Plan panel. Off the board,
+ *  the agent, the comments, then in Components the inspector while a
+ *  component is open and nothing on its home; elsewhere the Brief (S4) or
+ *  the inspector. */
+export type BoardRightPanel = "agent" | "comments" | "brief" | "component" | "inspector" | "assets" | "plan" | "sketch" | null;
+
+export function boardRightPanel(
+  s: Pick<
+    ShotEditorState,
+    | "storyboardOpen"
+    | "agentOpen"
+    | "commentsOpen"
+    | "briefOpen"
+    | "canComment"
+    | "storyboardSelection"
+    | "doc"
+    | "boardAssetsOpen"
+    | "materialWorkspace"
+    | "codeComponent"
+    | "editingDef"
+  > &
+    Partial<Pick<ShotEditorState, "storyboardPlan" | "sketchSelection" | "componentsOpen">>,
+): BoardRightPanel {
+  if (s.agentOpen) return "agent";
+  // The Comments tab, picked by the author, on the board or off it. Gated by
+  // `can.comment`: a caller who may not comment never sees the threads.
+  if (s.commentsOpen && s.canComment) return "comments";
+  if (!s.storyboardOpen) {
+    // COMPONENTS: the open component's inspector (its parts, This use, the
+    // Shot door's origin), never the Brief, which is a Shot's plan. The home
+    // has nothing to inspect, so its column steps aside like the board's.
+    if (workspaceOf(s) === "components") return componentsSubject(s) === null ? null : "inspector";
+    return s.briefOpen ? "brief" : "inspector";
+  }
+  // THE SHOT BOARD always has a panel: what is selected on the sketch, the
+  // assets it adds from, else the shot's plan.
+  if (s.storyboardPlan != null) {
+    if ((s.sketchSelection?.length ?? 0) > 0) return "sketch";
+    return s.boardAssetsOpen ? "assets" : "plan";
+  }
+  const board = s.storyboardSelection;
+  if (board.length === 1 && isReferenceId(board[0]!)) {
+    const item = s.doc?.resources?.references?.find((r) => r.id === board[0]);
+    if (item?.type === "component") return "component";
+  }
+  if (board.some((id) => isReferenceId(id) || isGapId(id) || isCutId(id))) return "inspector";
+  if (board.length === 1 && isPartId(board[0]!)) return "plan";
+  // Project assets, under any selected card's own panel: a press on a card
+  // shows that card, and a press on the ground brings the assets back.
+  if (s.boardAssetsOpen) return "assets";
+  return null;
+}
+
+// ── Every use (C4) ──────────────────────────────────────────────────────────
+//
+// A use is named by a KEY, so the list, the THIS USE panel and the store verbs
+// agree on it without passing objects around: a board card by its id, a layer
+// by its container (Shot or definition) and its id, since layer ids are only
+// unique inside one container.
+
+export const cardUseKey = (referenceId: string): string => `card:${referenceId}`;
+export const layerUseKey = (container: string, layerId: string): string => `layer:${container}:${layerId}`;
+
+export function useKeyOf(use: ComponentUse): string {
+  return use.referenceId !== undefined
+    ? cardUseKey(use.referenceId)
+    : layerUseKey(use.sceneId ?? use.inDef ?? "", use.layerId ?? "");
+}
+
+type UseTarget = { kind: "card"; id: string } | { kind: "layer"; container: string; id: string };
+
+function targetOf(key: string): UseTarget | null {
+  if (key.startsWith("card:")) return { kind: "card", id: key.slice(5) };
+  if (!key.startsWith("layer:")) return null;
+  const rest = key.slice(6);
+  const cut = rest.lastIndexOf(":");
+  return cut <= 0 ? null : { kind: "layer", container: rest.slice(0, cut), id: rest.slice(cut + 1) };
+}
+
+/** The layer a key names, with its container. */
+export function useLayerOf(key: string): { container: string; layerId: string } | null {
+  const target = targetOf(key);
+  return target?.kind === "layer" ? { container: target.container, layerId: target.id } : null;
+}
+
+/** The board card a key names. */
+export function useCardOf(key: string): string | null {
+  const target = targetOf(key);
+  return target?.kind === "card" ? target.id : null;
+}
+
+/** A code component's defaults from its live contract, for `componentUsesOf`,
+ *  as the engine values a use stores (`coerceValue`): a curve or a gradient
+ *  default is its decoded object in the contract and its canonical JSON in a
+ *  use, and comparing the two called every stored composite a change. */
+export function contractDefaultsFrom(
+  contracts: Readonly<Record<string, Contract>>,
+): (componentId: string) => Record<string, Value> | null {
+  return (id) => {
+    const contract = contracts[id];
+    if (contract === undefined) return null;
+    const out: Record<string, Value> = {};
+    for (const spec of Object.values(contract.keys)) {
+      const value = "default" in spec ? spec.default : undefined;
+      if (value === null || value === undefined) continue;
+      try {
+        const coerced = coerceValue(spec, value);
+        if (coerced.ok) out[spec.key] = coerced.value;
+      } catch {
+        // A spec this build cannot read has no default a use could match.
+      }
+    }
+    return out;
+  };
+}
+
+/** Every use of one component in this document, in walk order. The live
+ *  contracts go in twice: a code use's changes are measured against its
+ *  contract defaults, and a definition's prop aimed at an interior instance's
+ *  unset prop draws that prop's contract default (`exposedMasterValue`). */
+export function usesOfSubject(
+  doc: Doc3D,
+  sel: ComponentsSelection,
+  contracts: Readonly<Record<string, Contract>> = {},
+): ComponentUse[] {
+  return componentUsesOf(doc, { contractDefaults: contractDefaultsFrom(contracts), contracts }).filter((u) =>
+    sel.kind === "studio" ? u.def === sel.def : u.component === sel.module,
+  );
+}
+
+/** The use a key names, or null when it is gone. */
+export function useByKey(
+  doc: Doc3D,
+  key: string,
+  contracts: Readonly<Record<string, Contract>> = {},
+): ComponentUse | null {
+  return (
+    componentUsesOf(doc, { contractDefaults: contractDefaultsFrom(contracts), contracts }).find(
+      (u) => useKeyOf(u) === key,
+    ) ?? null
+  );
+}
+
+/** The list chip: "No changes", "1 change: Tilt", "2 changes". */
+export function changeLabel(use: Pick<ComponentUse, "overrides">, labelOf: (key: string) => string = (k) => k): string {
+  const n = use.overrides.length;
+  if (n === 0) return "No changes";
+  return n === 1 ? `1 change: ${labelOf(use.overrides[0]!)}` : `${n} changes`;
+}
+
+/** "03 Phone reveal", by the board's shot numbering. */
+export function shotLabel(doc: Doc3D, sceneId: string): string {
+  const name = doc.scenesById[sceneId]?.name ?? "";
+  const number = shotNumberOf(doc, sceneId);
+  return number === null ? name : `${number} ${name}`;
+}
+
+/** Where a board card is pinned, as the list says it. */
+function cardPlace(doc: Doc3D, use: ComponentUse): string {
+  const part = use.partId === null ? undefined : doc.storyboard?.parts.find((p) => p.id === use.partId);
+  if (part === undefined) {
+    return use.sceneId === null ? "Reference on the Style" : `Reference in ${shotLabel(doc, use.sceneId)}`;
+  }
+  const scene = part.scene !== undefined && doc.scenesById[part.scene] !== undefined ? part.scene : null;
+  return `Reference, pinned to ${scene === null ? part.label : shotLabel(doc, scene)}`;
+}
+
+/** The list row's kind badge, title and location for a use in THIS document. */
+export function useRowText(doc: Doc3D, use: ComponentUse): { kind: "BOARD" | "SHOT"; title: string; location: string } {
+  if (use.kind === "card") return { kind: "BOARD", title: cardPlace(doc, use), location: "This Project · Storyboard" };
+  const layer = `layer "${use.layerName ?? use.layerId ?? ""}"`;
+  if (use.sceneId !== null) {
+    return { kind: "SHOT", title: `${shotLabel(doc, use.sceneId)} · ${layer}`, location: "This Project · Studio" };
+  }
+  const def = use.inDef === undefined ? undefined : doc.components?.[use.inDef];
+  const owner = def?.name ?? "a component";
+  return { kind: "SHOT", title: `${def?.name ?? "Component"} · ${layer}`, location: `This Project · inside ${owner}` };
+}
+
+/** THIS USE's title: "Shot 03 · Phone hero", "Storyboard · Hero card". */
+export function useTitle(doc: Doc3D, use: ComponentUse): string {
+  if (use.kind === "card") return `Storyboard · ${use.referenceName ?? "Reference"}`;
+  const name = use.layerName ?? use.layerId ?? "";
+  if (use.sceneId !== null) {
+    const number = shotNumberOf(doc, use.sceneId);
+    return `${number === null ? (use.sceneName ?? "Shot") : `Shot ${number}`} · ${name}`;
+  }
+  const def = use.inDef === undefined ? undefined : doc.components?.[use.inDef];
+  return `${def?.name ?? "Component"} · ${name}`;
+}
+
+/** Why a value cannot be written to this use from a panel, or null. An
+ *  instance prop with keyframes is animated in its Shot: a base value written
+ *  with no playhead would change nothing on screen. */
+export function usePropRefusal(doc: Doc3D, key: string, prop: string, label = prop): string | null {
+  const target = targetOf(key);
+  if (target === null || target.kind === "card") return null;
+  const layer = homeOf(doc, target.container)?.layersById[target.id];
+  if (layer?.kind === "instance" && layer.tracks?.[`${INSTANCE_PROP_PREFIX}${prop}`] !== undefined) {
+    return `${label} is animated here. Change it in the Studio, on its keyframes.`;
+  }
+  return null;
+}
+
+/**
+ * One prop of one use set, or cleared with null so it follows the master
+ * again. The same document when the use is gone or the write is refused.
+ *
+ * `aliases` are the prop's `renamedFrom` keys. An override stored under one of
+ * them still reaches the renderer (`overrideFor`), so an explicit write takes
+ * them with it: a value set under the new key would leave the old one behind
+ * as dead weight, and a CLEAR that left it would keep showing the old value
+ * the author just reset.
+ */
+export function withUseValue(
+  doc: Doc3D,
+  key: string,
+  prop: string,
+  value: Value | null,
+  aliases: readonly string[] = [],
+): Doc3D {
+  const target = targetOf(key);
+  if (target === null || usePropRefusal(doc, key, prop) !== null) return doc;
+  if (target.kind === "card") {
+    const base = aliases.reduce((next, alias) => clearReferenceProp(next, target.id, alias), doc);
+    return value === null ? clearReferenceProp(base, target.id, prop) : setReferenceProp(base, target.id, prop, value);
+  }
+  return patchUseLayer(doc, target.container, target.id, (values) => {
+    const stale = aliases.filter((alias) => alias in values);
+    const without = (drop: readonly string[]): Record<string, Value> =>
+      Object.fromEntries(Object.entries(values).filter(([k]) => !drop.includes(k)));
+    // The same object when nothing moves, so an unchanged write is no edit.
+    if (value === null) return stale.length === 0 && !(prop in values) ? values : without([prop, ...stale]);
+    if (stale.length > 0) return { ...without(stale), [prop]: value };
+    return valueEquals(values[prop], value) ? values : { ...values, [prop]: value };
+  });
+}
+
+/** The stored props of a use that carry keyframes: an instance layer's
+ *  `instance.props.<key>` tracks. Reset all keeps these (`withUseReset`). */
+function animatedPropsOf(doc: Doc3D, key: string): string[] {
+  const target = targetOf(key);
+  if (target === null || target.kind === "card") return [];
+  const layer = homeOf(doc, target.container)?.layersById[target.id];
+  if (layer?.kind !== "instance") return [];
+  return Object.keys(layer.instance.props).filter((prop) => layer.tracks?.[`${INSTANCE_PROP_PREFIX}${prop}`] !== undefined);
+}
+
+/**
+ * Reset all to master: the use stores no values, apart from an animated
+ * instance prop's. Its stored value is the base under its track, the value
+ * the track was minted from and the one that returns when the track goes:
+ * clearing it left the next edit of that prop unkeyed (the router keys only
+ * over a base) and brought the contract default back in place of the authored
+ * value when the keyframes were removed. So those are kept, and `resetUse`
+ * says which.
+ */
+export function withUseReset(doc: Doc3D, key: string): Doc3D {
+  const target = targetOf(key);
+  if (target === null) return doc;
+  if (target.kind === "card") {
+    const stored = Object.keys(useByKey(doc, key)?.values ?? {});
+    return stored.reduce((next, prop) => clearReferenceProp(next, target.id, prop), doc);
+  }
+  const kept = new Set(animatedPropsOf(doc, key));
+  return patchUseLayer(doc, target.container, target.id, (values) => {
+    const stays = Object.keys(values).filter((prop) => kept.has(prop));
+    return stays.length === Object.keys(values).length ? values : Object.fromEntries(stays.map((prop) => [prop, values[prop]!]));
+  });
+}
+
+/** A component layer's overrides or an instance layer's props, rewritten. */
+function patchUseLayer(
+  doc: Doc3D,
+  container: string,
+  layerId: string,
+  next: (values: Record<string, Value>) => Record<string, Value>,
+): Doc3D {
+  const home = homeOf(doc, container);
+  const layer = home?.layersById[layerId];
+  if (home === null || home === undefined || layer === undefined) return doc;
+  let patched: Layer3D;
+  if (layer.kind === "component") {
+    const overrides = next(layer.component.overrides);
+    if (overrides === layer.component.overrides) return doc;
+    patched = { ...layer, component: { ...layer.component, overrides } };
+  } else if (layer.kind === "instance") {
+    const props = next(layer.instance.props);
+    if (props === layer.instance.props) return doc;
+    patched = { ...layer, instance: { ...layer.instance, props } };
+  } else {
+    return doc;
+  }
+  return patchHome(doc, container, { layers: home.layers, layersById: { ...home.layersById, [layerId]: patched } });
+}
+
+/**
+ * The master's value of one prop: what the definition DRAWS for its exposed
+ * prop (`exposedMasterValue`: the interior layer's value at the prop's target,
+ * else the prop's published `default`), or the code component's contract
+ * default. Undefined when it is not known.
+ *
+ * The layer and not `prop.default`: an un-overridden use renders the layer
+ * as it stands, and the published default drifts from it once the field is
+ * edited anywhere but the props panel (the layer's own section, a stage drag,
+ * an agent's `update_layer`). Measured against the stale default, a use that
+ * matched the screen read as changed, and a value typed to match the screen
+ * was stored as an override.
+ */
+export function masterValueOf(
+  doc: Doc3D,
+  contracts: Readonly<Record<string, Contract>>,
+  use: UseMaster,
+  prop: string,
+): Value | undefined {
+  if (use.def !== undefined) {
+    const def = doc.components?.[use.def];
+    const exposed = def?.exposed.find((p) => p.key === prop);
+    return def === undefined || exposed === undefined
+      ? undefined
+      : exposedMasterValue(def, exposed, { materials: doc.materials, contracts });
+  }
+  const contract = contractOfUse(doc, contracts, use);
+  return contract === null ? undefined : (contractDefaultsFrom({ master: contract })("master")?.[prop] ?? undefined);
+}
+
+/** What names a use's master: its definition or its module, and, for a layer,
+ *  where the layer is (whose snapshot contract stands in for the live one). */
+type UseMaster = Pick<ComponentUse, "def" | "component"> &
+  Partial<Pick<ComponentUse, "layerId" | "sceneId" | "inDef">>;
+
+/**
+ * The contract a code use's props come from: the live registry's, else, for
+ * a placed layer, the snapshot it carries, the fallback the Studio's own rows
+ * read (InstanceSection). A component that has left the project keeps its
+ * props readable in every panel that shows the use, not only in the Studio.
+ */
+export function contractOfUse(
+  doc: Doc3D,
+  contracts: Readonly<Record<string, Contract>>,
+  use: UseMaster,
+): Contract | null {
+  if (use.component === undefined) return null;
+  const live = contracts[use.component];
+  if (live !== undefined) return live;
+  const container = use.sceneId ?? use.inDef;
+  if (container === null || container === undefined || use.layerId === undefined) return null;
+  const layer = homeOf(doc, container)?.layersById[use.layerId];
+  return layer === undefined ? null : layerSnapshotContract(layer);
+}
+
+/** A prop's label as the master names it: the published label, or the
+ *  contract's (`controlLabel`); else its key humanized, never the raw key. */
+export function propLabelOf(
+  doc: Doc3D,
+  contracts: Readonly<Record<string, Contract>>,
+  use: UseMaster,
+  prop: string,
+): string {
+  if (use.def !== undefined) {
+    const label: unknown = doc.components?.[use.def]?.exposed.find((p) => p.key === prop)?.label;
+    return typeof label === "string" && label.trim() !== "" ? label : humanizeKey(prop);
+  }
+  const spec = contractOfUse(doc, contracts, use)?.keys[prop];
+  return spec === undefined ? humanizeKey(prop) : controlLabel(spec);
+}
+
+/** A colour as one canonical hex, or null when it is no colour this lane
+ *  reads (`toTrackHex`'s spellings: hex of any length, `rgb()`, `rgba()`). */
+function canonicalHex(css: string): string | null {
+  const hex = toTrackHex(css);
+  if (hex === null) return null;
+  try {
+    return formatHex(parseHex(hex));
+  } catch {
+    return null;
+  }
+}
+
+/** The control kind a use's master draws for one prop: the row's own spec
+ *  (`exposedSpecOf` for a definition's prop, the contract for a code
+ *  component's), else the published record's kind. */
+function propKindOf(
+  doc: Doc3D,
+  contracts: Readonly<Record<string, Contract>>,
+  use: UseMaster,
+  prop: string,
+): string | undefined {
+  if (use.def !== undefined) {
+    const def = doc.components?.[use.def];
+    const exposed = def?.exposed.find((p) => p.key === prop);
+    if (def === undefined || exposed === undefined) return undefined;
+    return exposedSpecOf(exposed, def, { materials: doc.materials, contracts })?.spec.kind ?? exposed.kind;
+  }
+  return contractOfUse(doc, contracts, use)?.keys[prop]?.kind;
+}
+
+/**
+ * Whether a use's value is the master's own. A COLOUR prop's value is
+ * compared as the colour it is: a published fill's default is captured in the
+ * spelling its layer holds (`rgba(30,215,96,0.18)`, `#FFF`), while every
+ * colour control writes `#rrggbb[aa]`, so the master's own colour typed back
+ * must read as the master's and store nothing. Any other kind compares as it
+ * is: a text that happens to spell a colour ("#FFF" over a master's
+ * "#ffffff") is what the author typed, and is kept.
+ */
+export function sameUseValue(a: Value, b: Value, kind: string | undefined): boolean {
+  if (valueEquals(a, b)) return true;
+  if (kind !== "color" || typeof a !== "string" || typeof b !== "string") return false;
+  const hex = canonicalHex(a);
+  return hex !== null && hex === canonicalHex(b);
+}
+
+/**
+ * THE ONE WRITE of a use's prop, for the panel's commits and its scrubs. A
+ * value equal to the master is stored as nothing, so the use keeps following
+ * the master (the rule `setComponentOverride` keeps). A locked layer and an
+ * animated instance prop refuse, with the reason. A definition's prop is
+ * written under its own key, taking any `renamedFrom` key it was stored under
+ * with it (`withUseValue`).
+ */
+export function writeUseValue(
+  doc: Doc3D,
+  contracts: Readonly<Record<string, Contract>>,
+  key: string,
+  prop: string,
+  value: Value | null,
+): { doc: Doc3D; refusal: string | null } {
+  const use = useByKey(doc, key, contracts);
+  if (use === null) return { doc, refusal: null };
+  const label = propLabelOf(doc, contracts, use, prop);
+  const animated = usePropRefusal(doc, key, prop, label);
+  if (animated !== null) return { doc, refusal: animated };
+  const master = masterValueOf(doc, contracts, use, prop);
+  const stored =
+    value !== null && master !== undefined && sameUseValue(value, master, propKindOf(doc, contracts, use, prop))
+      ? null
+      : value;
+  const aliases =
+    use.def === undefined ? [] : (doc.components?.[use.def]?.exposed.find((p) => p.key === prop)?.renamedFrom ?? []);
+  return unlockedUse(doc, withUseValue(doc, key, prop, stored, aliases));
+}
+
+/** Reset all to master, with the same lock rule. An animated instance prop
+ *  keeps its stored base (`withUseReset`), and the refusal line says which
+ *  were kept, so a reset that left values behind never reads as one that
+ *  did nothing. */
+export function resetUse(
+  doc: Doc3D,
+  key: string,
+  contracts: Readonly<Record<string, Contract>> = {},
+): { doc: Doc3D; refusal: string | null } {
+  const out = unlockedUse(doc, withUseReset(doc, key));
+  if (out.refusal !== null) return out;
+  const use = useByKey(doc, key, contracts);
+  const kept = use === null ? [] : animatedPropsOf(doc, key).map((prop) => propLabelOf(doc, contracts, use, prop));
+  if (kept.length === 0) return out;
+  const names = kept.length === 1 ? kept[0]! : `${kept.slice(0, -1).join(", ")} and ${kept.at(-1)!}`;
+  const said = kept.length === 1 ? "it is animated, and only its keyframes change it" : "they are animated, and only their keyframes change them";
+  return { doc: out.doc, refusal: `Kept ${names}: ${said}.` };
+}
+
+/** Code components cannot be detached: their master is source code. */
+export const DETACH_CODE_REFUSAL = "Code components cannot be detached; fork it to change the code.";
+/** A board card always shows its master: it has no layers to detach into. */
+export const DETACH_CARD_REFUSAL = "A board card shows the master. Use it in a shot to detach a copy there.";
+
+/** Why a use cannot be detached, or null: the store's refusal, which the
+ *  Detach button also wears as its reason before it is pressed. */
+export function detachRefusal(use: Pick<ComponentUse, "component">, key: string): string | null {
+  if (use.component !== undefined) return DETACH_CODE_REFUSAL;
+  return useLayerOf(key) === null ? DETACH_CARD_REFUSAL : null;
+}
+
+function unlockedUse(before: Doc3D, after: Doc3D): { doc: Doc3D; refusal: string | null } {
+  const locked = lockedLayerEdited(before, after);
+  return locked === null ? { doc: after, refusal: null } : { doc: before, refusal: lockRefusal(locked) };
+}
+
+/** A newer version of where a copied definition came from: the workspace
+ *  store's latest (`cpt_` origin) or the Community listing's (`cml-`). Code
+ *  components never have one: they are live across the workspace. */
+export interface CopyUpdate {
+  source: string;
+  from: "workspace" | "community";
+  version: number;
+}
+
+export function copyUpdateOf(
+  def: ComponentDef3D | undefined,
+  workspace: readonly WorkspaceComponent[] | null,
+  listings: Readonly<Record<string, ComponentListingUpdate>>,
+): CopyUpdate | null {
+  const origin = def?.origin;
+  if (origin === undefined) return null;
+  if (WORKSPACE_COMPONENT_ID_RE.test(origin.source)) {
+    const row = workspace?.find((c) => c.id === origin.source);
+    return row !== undefined && row.version > origin.version
+      ? { source: origin.source, from: "workspace", version: row.version }
+      : null;
+  }
+  if (COMPONENT_LISTING_ID_RE.test(origin.source)) {
+    const listing = listings[origin.source];
+    return listing !== undefined && listing.version > origin.version
+      ? { source: origin.source, from: "community", version: listing.version }
+      : null;
+  }
+  return null;
+}