@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/menu.ts

@@ -15,9 +15,60 @@
 // drift from the shortcuts, and a fix to `duplicateSelection` fixes it in three
 // places at once. A menu entry that reached into the document itself would be a
 // second implementation of an edit that already exists.
-import type { MenuEntry } from "@dailies-studio/ui";
+import {
+  ALIGN_LABELS,
+  ALIGN_MODES,
+  DISTRIBUTE_MODES,
+  GENERATED_SHOTS_DIR,
+  MATERIAL_GRAPH_PARAMETER_TYPES,
+  MIN_DISTRIBUTE,
+  SKETCHES_MAX,
+  componentDefsOf,
+  copyAnimation,
+  copyEffects,
+  homeOf,
+  maskTargetOf,
+  materialGraphNodeSpec,
+  parentOf,
+  sceneWindows,
+  sketchesOf,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D, RestackTarget } from "@dailies-studio/shot/doc";
+import type { MenuEntry, OpenMenuOptions } from "@dailies-studio/ui";
+import type { ReactNode } from "react";
+import type { StudioThemePreference } from "@dailies-studio/ui/theme";
+import { SHADING_MODES, shadingLabel } from "../stage/shading.js";
+import {
+  ORBIT_STEP_DEG,
+  orbitByDegrees,
+  presetWorkingView,
+} from "../stage/workingView.js";
+import type { WorkingViewPreset } from "../stage/workingView.js";
+import { SHOT_TOOLS, specOf } from "../tools.js";
+import { MASK_ALPHA_SWATCH, MASK_ICON, MASK_LUMA_SWATCH } from "../icons.js";
+import { toolRefusal } from "./keymap.js";
+import { isolationInsertRefusal } from "./isolationTrail.js";
+import { cameraVerb } from "./cameraVerbs.js";
+// The layout table and its two refusals: the words, the menu ids and the
+// sentences this menu shares with the digits and the segmented control.
+import { LAYOUT_MODES, layoutRefusal, layoutSpec, paneOnlyRefusal } from "./layouts.js";
+import {
+  VIEW_MODE_SPECS,
+  inDefinition,
+  inShotContext,
+  isSceneContext,
+  shownLayoutMode,
+  toolLayoutMode,
+} from "./viewMode.js";
+import { isCloudWorkspace } from "./posterCapture.js";
+import { formatCombo, probeFor, shortcutFor, toolKey } from "./shortcuts.js";
+import { boardTargetOf, isPartId } from "./storyboardModel.js";
+import { agentGate, agentInEditor } from "../panels/agent/agentGate.js";
+import { BOARD_CLOSED, LAST_SHOT, NO_SHOT_BOARD, TEMPLATES_DO_NOT_STACK, instanceDriftOf, storyboardBlocker } from "./store.js";
+import { commandBlocker, readOnlyReason, shotBoardOf, viewOnlyBlocker, workspaceOf } from "./workspace.js";
 import type { ShotEditorStore } from "./store.js";
 import type { ShotEditorState } from "./types.js";
+import { SCENE_WAITING, playHold, playOn, preparingTitle } from "./playHold.js";
 
 /** The layers a menu acts on, and what they are. Computed by the caller,
  *  because the stage knows the raw hit stack and the outliner knows the row. */
@@ -30,38 +81,201 @@ export interface MenuTargets {
   meshIds: readonly string[];
   /** Do any of the mesh targets already carry a material? Drives "Remove". */
   hasMaterial: boolean;
+  /** The FIRST target's flags, resolved against the container the outline is
+   *  actually showing. They live here rather than being re-read in the entry
+   *  builder because that second lookup only knew about scenes, so both labels
+   *  read "Hide"/"Lock" for every layer inside an open component definition. */
+  hidden: boolean;
+  locked: boolean;
+  /** The first target places a component (Studio-made or code), so it opens
+   *  in Components. Drives "Open in Components". */
+  opensComponent: boolean;
+  /** ACROSS ALL TARGETS, unlike the flags above: does any target qualify? A
+   *  row that acts on the whole selection shows when any member can take it. */
+  hasGroup: boolean;
+  /** A group or a component instance, the two kinds Flatten dissolves. */
+  hasFlattenable: boolean;
+  /** The label of the layer Copy animation copies from: the first target
+   *  with a track (`store.copyAnimation`'s own rule), or absent. */
+  animationSource?: string;
+  /** The same for Copy effects: the first target with a shadow or a glow. */
+  effectsSource?: string;
+  /** Does any target name a mask (`maskTargetOf`: a mask, or a group holding
+   *  one)? Drives Invert mask and Release mask. */
+  hasMask: boolean;
+  /** Why "Use as mask" cannot run on these targets, or absent when it can. */
+  maskRefusal?: string;
+}
+
+/** A cloner's children are its templates, and a mask there would be cloned
+ *  with them (`clonerMaskRefusal`). The menu's short form of that refusal. */
+export const CLONER_MASK_REFUSAL = "A cloner child cannot be a mask. Mask the cloner instead.";
+
+/** What only the surface that opened the layer menu can do. */
+export interface LayerMenuHooks {
+  /** Rename this one layer the surface's own way: the outliner's inline edit,
+   *  the stage's prompt. Absent, the menu has no Rename row (the app menu has
+   *  its own, and an agent renames through `renameLayer`). */
+  onRename?(id: string): void;
+  /** The layer the author right-clicked, when it is in the selection: "Use
+   *  as mask" makes THAT layer the mask (Paper page 25). Absent, the store
+   *  picks the backmost selected layer. */
+  subject?: string;
+}
+
+/** Arrange's four rows, in Figma's order. */
+const ARRANGE: readonly (readonly [RestackTarget, string])[] = [
+  ["front", "Bring to front"],
+  ["forward", "Bring forward"],
+  ["backward", "Send backward"],
+  ["back", "Send to back"],
+];
+
+/**
+ * Why Arrange cannot run on these layers, or null when it can: the sentence a
+ * dimmed Arrange row carries, in the app menu and the right-click menu alike.
+ *
+ * A cloner's direct children are its TEMPLATES. Clone i draws `children[i % n]`,
+ * so their order picks which clone draws which template and two of them never
+ * meet on screen: they do not stack, and `restackLayers` refuses a selection of
+ * nothing else (founder decision 6). A mixed selection runs, and leaves its
+ * templates where they are. The way to reorder templates is the outline drag.
+ */
+function arrangeRefusal(
+  state: ShotEditorState,
+  ids: readonly string[],
+): string | null {
+  if (ids.length === 0) return "Select a layer to arrange it";
+  const container = state.editingDef ?? state.sceneId;
+  const home =
+    state.doc === null || container === null ? null : homeOf(state.doc, container);
+  if (home === null) return null;
+  const templatesOnly = ids.every((id) => {
+    const parent = parentOf(home, id);
+    return parent !== null && home.layersById[parent]?.kind === "cloner";
+  });
+  return templatesOnly ? TEMPLATES_DO_NOT_STACK : null;
+}
+
+/**
+ * ARRANGE, Figma's: each selected layer among its own siblings, per parent,
+ * which is paint order (`store.restack`, `restackLayers`). The app menu's
+ * Arrange and the right-click menu build the same four rows here, so
+ * the two cannot disagree about when they run; `idOf` only names them, because
+ * the right-click menu keys its rows on bare ids. The accelerator is always the
+ * table's `layout.arrange.*` row.
+ */
+function arrangeRows(
+  store: ShotEditorStore,
+  state: ShotEditorState,
+  ids: readonly string[],
+  idOf: (to: RestackTarget) => string,
+): MenuEntry[] {
+  const no = arrangeRefusal(state, ids);
+  return ARRANGE.map(([to, label]) => ({
+    kind: "action" as const,
+    id: idOf(to),
+    label,
+    shortcut: shortcutFor(`layout.arrange.${to}`),
+    disabled: no !== null,
+    ...(no === null ? {} : { title: no }),
+    onSelect: () => store.restack(ids, to),
+  }));
 }
 
 export function layerMenuEntries(
   store: ShotEditorStore,
   state: ShotEditorState,
   targets: MenuTargets,
+  hooks: LayerMenuHooks = {},
 ): MenuEntry[] {
   if (targets.ids.length === 0) return [];
-  const layers = state.sceneId === null ? undefined : state.doc?.scenesById[state.sceneId]?.layersById;
-  const first = layers?.[targets.ids[0]!];
   // The label follows what the FIRST target is, not what the whole set is. A
   // mixed selection has no honest single word, and "Hide/Show" reading off the
   // subject the author right-clicked is the behaviour every outliner has.
-  const hidden = first?.hidden === true;
-  const locked = first?.locked === true;
+  const { hidden, locked } = targets;
+  const many = targets.ids.length > 1;
+  const one = many ? undefined : targets.ids[0];
+  // With several layers selected a copy still reads ONE of them, so the row
+  // names which.
+  const from = (verb: string, source: string): string => (many ? `${verb} from ${source}` : verb);
+  const row = (id: string, label: string, onSelect: () => void, shortcut?: string): MenuEntry => ({
+    kind: "action",
+    id,
+    label,
+    shortcut,
+    onSelect,
+  });
 
   // The `id`s are STABLE and independent of the label, because the label flips
   // (Hide/Show, Lock/Unlock) and the menu keys its rows on the id. A key that
   // changed with the word would remount the row every time the flag did.
+  //
+  // Rows that do not apply are ABSENT, not dimmed: a right-click menu's
+  // subject is what was clicked, so a dimmed row could only explain itself.
+  // The mask rows are the exception Paper draws (page 25): Invert and Release
+  // stay in place, dimmed, beside the "Use as mask" that made them, so the
+  // three read as one family wherever the author looks for them.
   const entries: MenuEntry[] = [
-    { kind: "action", id: "duplicate", label: "Duplicate", onSelect: () => store.duplicateSelection() },
+    row("copy", "Copy", () => store.copyLayers(), shortcutFor("edit.copy")),
+    ...(store.hasLayerClip() ? [row("paste", "Paste", () => store.pasteLayers(), shortcutFor("edit.paste"))] : []),
+    row("duplicate", "Duplicate", () => store.duplicateSelection(), shortcutFor("edit.duplicate")),
+    { kind: "separator" },
+    // ── Motion and effects, from one layer onto others ──
+    ...(targets.animationSource === undefined
+      ? []
+      : [
+          row(
+            "copy-animation",
+            from("Copy animation", targets.animationSource),
+            () => store.copyAnimation(),
+            shortcutFor("edit.copyAnimation"),
+          ),
+        ]),
+    ...(store.hasAnimationClip() ? [pasteAnimationMenu(store, "paste-animation-")] : []),
+    ...(targets.effectsSource === undefined
+      ? []
+      : [
+          row(
+            "copy-effects",
+            from("Copy effects", targets.effectsSource),
+            () => store.copyEffects(),
+            shortcutFor("edit.copyEffects"),
+          ),
+        ]),
+    ...(store.hasEffectsClip()
+      ? [row("paste-effects", "Paste effects", () => store.pasteEffects(), shortcutFor("edit.pasteEffects"))]
+      : []),
+    { kind: "separator" },
+    ...(one !== undefined && hooks.onRename !== undefined
+      ? [row("rename", "Rename…", () => hooks.onRename?.(one)), { kind: "separator" as const }]
+      : []),
+    // ── Structure ──
+    ...(many ? [row("group", "Group", () => store.groupSelection(), shortcutFor("edit.group"))] : []),
+    ...(targets.hasGroup ? [row("ungroup", "Ungroup", () => store.ungroupSelection(), shortcutFor("edit.ungroup"))] : []),
+    ...(targets.hasFlattenable ? [row("flatten", "Flatten", () => store.flattenSelection())] : []),
+    row("make-component", "Make component", () => store.createComponentFromSelection()),
+    ...maskRows(store, targets, hooks.subject),
+    { kind: "separator" },
+    // ARRANGE, where Figma's right-click has it: the menu is on the layer the
+    // author is pointing at, and "put it in front of that" is the question.
+    ...arrangeRows(store, state, targets.ids, (to) => `arrange-${to}`),
     { kind: "separator" },
     {
       kind: "action",
       id: "hidden",
       label: hidden ? "Show" : "Hide",
+      // The accelerator is H's, which HIDES. It is printed on the hide reading
+      // only: ⌘⇧H is the reveal key and it reveals EVERYTHING, so claiming it for
+      // "Show this one" would name a key that does something wider.
+      shortcut: hidden ? undefined : shortcutFor("layer.hide"),
       onSelect: () => store.toggleFlag("hidden"),
     },
     {
       kind: "action",
       id: "locked",
       label: locked ? "Unlock" : "Lock",
+      shortcut: shortcutFor("layer.lock"),
       onSelect: () => store.toggleFlag("locked"),
     },
     { kind: "separator" },
@@ -72,6 +286,7 @@ export function layerMenuEntries(
       kind: "action",
       id: "isolation",
       label: "Exit isolation",
+      shortcut: shortcutFor("layer.isolate.exit"),
       onSelect: () => store.exitIsolation(),
     });
   } else {
@@ -79,6 +294,7 @@ export function layerMenuEntries(
       kind: "action",
       id: "isolation",
       label: "Isolate",
+      shortcut: shortcutFor("layer.isolate"),
       onSelect: () => {
         const id = targets.ids[0];
         if (id !== undefined) store.enterIsolation(id);
@@ -86,13 +302,37 @@ export function layerMenuEntries(
     });
   }
 
+  // ── Editing this layer somewhere else ────────────────────────────────────
+  //
+  // Isolate above is "edit it here, alone". This one is "open what it
+  // places": a component layer places a component that has no camera and no
+  // slot in this scene's timeline, so it opens alone in Components.
+  //
+  // Absent, not disabled, on layers that place nothing, the convention the
+  // material rows already follow.
+  if (targets.opensComponent) {
+    const instance = targets.ids[0]!;
+    entries.push({ kind: "separator" });
+    entries.push({
+      kind: "action",
+      id: "open-3d",
+      label: "Open in Components",
+      onSelect: () => void store.openComponentContext(instance),
+    });
+  }
+
   if (targets.meshIds.length > 0) {
     entries.push({ kind: "separator" });
     entries.push({
       kind: "action",
       id: "material",
-      label: "Apply material…",
-      onSelect: () => store.openMaterialPicker(targets.meshIds),
+      label: "Material Nodes…",
+      disabled: targets.meshIds.length !== 1,
+      onSelect: () => {
+        const meshId = targets.meshIds[0];
+        if (targets.meshIds.length === 1 && meshId !== undefined)
+          store.openMaterialWorkspace(meshId);
+      },
     });
     if (targets.hasMaterial) {
       entries.push({
@@ -110,32 +350,2105 @@ export function layerMenuEntries(
     id: "delete",
     label: "Delete",
     danger: true,
+    shortcut: shortcutFor("edit.delete"),
     onSelect: () => store.deleteSelection(),
   });
-  return entries;
+  // A VIEWER'S layer menu LEAVES OUT what it cannot run, rather than dimming
+  // it (Paper page 23): what is left is the copy rows and the ones that only
+  // open or look. The other menus dim, through `gateForViewer`.
+  return state.readOnly
+    ? omitRows(entries, (id) => viewOnlyBlocker(id) !== null)
+    : gateForViewer(state, entries);
 }
 
 /**
- * The targets for a set of layer ids, read off the open document.
+ * THE MASK ROWS (gap 7, Paper page 25): "Use as mask" with its two modes, then
+ * Invert mask and Release mask. Shared by the right-click menu and the app
+ * menu's Layer branch, which splices `layerMenuEntries` whole. No shortcut:
+ * Paper draws none and the keymap binds none.
+ */
+function maskRows(store: ShotEditorStore, targets: MenuTargets, subject: string | undefined): MenuEntry[] {
+  const refused = targets.maskRefusal;
+  const mode = (
+    id: string,
+    label: string,
+    detail: string,
+    m: "alpha" | "luma",
+    icon: ReactNode,
+    def?: string,
+  ): MenuEntry => ({
+    kind: "action",
+    id,
+    label,
+    detail,
+    icon,
+    ...(def === undefined ? {} : { shortcut: def }),
+    disabled: refused !== undefined,
+    ...(refused === undefined ? {} : { title: refused }),
+    onSelect: () => store.maskSelection(m, subject),
+  });
+  // Invert and Release keep an EMPTY icon slot, so their labels sit under
+  // "Use as mask"'s and the three read as one family.
+  const noMask = targets.hasMask ? {} : { disabled: true, title: "Select a mask or its Mask group" };
+  return [
+    {
+      kind: "submenu",
+      label: "Use as mask",
+      icon: MASK_ICON,
+      ...(refused === undefined ? {} : { disabled: true, title: refused, detail: refused }),
+      items: [
+        mode("mask-alpha", "Alpha", "Uses the mask's opacity", "alpha", MASK_ALPHA_SWATCH, "Default"),
+        mode("mask-luma", "Luma", "Uses the mask's brightness", "luma", MASK_LUMA_SWATCH),
+      ],
+    },
+    { kind: "action", id: "mask-invert", label: "Invert mask", icon: null, ...noMask, onSelect: () => store.editMask("invert") },
+    { kind: "action", id: "mask-release", label: "Release mask", icon: null, ...noMask, onSelect: () => store.editMask(null) },
+  ];
+}
+
+/** The right-click menu on a motion path dot (gap 3). It acts on that one
+ *  Position key, so it is short: seek to it, curve the path, make the key a
+ *  corner on a bezier path (schema v40), and delete it. A viewer keeps the
+ *  seek, which writes nothing, and sees the rest dimmed. */
+export function pathKeyMenuEntries(
+  store: ShotEditorStore,
+  state: ShotEditorState,
+  ref: { layerId: string; keyId: string },
+): MenuEntry[] {
+  const container = state.editingDef ?? state.sceneId;
+  const track =
+    state.doc === null || container === null
+      ? undefined
+      : homeOf(state.doc, container)?.layersById[ref.layerId]?.tracks?.["transform.position"];
+  const curved = track?.spatialInterp !== undefined;
+  // On a bezier path the dot's double-click is corner/smooth, not the seek.
+  const corner = store.pathKeyCorner(ref.layerId, ref.keyId);
+  return gateForViewer(state, [
+    {
+      kind: "action",
+      id: "path-key-seek",
+      label: "Seek to key",
+      ...(corner === null ? { shortcut: "Double-click" } : {}),
+      onSelect: () => store.seekPathKey(ref.layerId, ref.keyId),
+    },
+    {
+      kind: "action",
+      id: "path-key-curve",
+      // `MenuEntry` has no checked state: the on marker sits in the shortcut
+      // column, the register the keyframe menu's "current" uses.
+      label: "Curved path",
+      ...(curved ? { shortcut: "on" } : {}),
+      onSelect: () =>
+        store.setPathCurve([ref.layerId], curved ? null : { type: "catmull-rom", tension: 0.5 }),
+    },
+    ...(corner === null
+      ? []
+      : [
+          {
+            kind: "action" as const,
+            id: "path-key-corner",
+            label: corner ? "Smooth" : "Corner",
+            shortcut: "Double-click",
+            onSelect: () => store.setPathKeyCorner(ref.layerId, ref.keyId, !corner),
+          },
+        ]),
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "path-key-delete",
+      label: "Delete key",
+      danger: true,
+      onSelect: () => store.deletePathKey(ref.layerId, ref.keyId),
+    },
+  ]);
+}
+
+/** Paste animation's two rows, under one submenu: the playhead is the default
+ *  and carries the key; the original time is the menu-only reading. */
+function pasteAnimationMenu(store: ShotEditorStore, idPrefix: string): MenuEntry {
+  return {
+    kind: "submenu",
+    label: "Paste animation",
+    items: [
+      {
+        kind: "action",
+        id: `${idPrefix}playhead`,
+        label: "At playhead",
+        shortcut: shortcutFor("edit.pasteAnimation.playhead"),
+        onSelect: () => store.pasteAnimation("playhead"),
+      },
+      {
+        kind: "action",
+        id: `${idPrefix}original`,
+        label: "At original time",
+        onSelect: () => store.pasteAnimation("original"),
+      },
+    ],
+  };
+}
+
+/** Drop each row `refused` names, a submenu left empty, and the separators
+ *  that leaves doubled or at either end. */
+function omitRows(entries: MenuEntry[], refused: (id: string) => boolean): MenuEntry[] {
+  const kept: MenuEntry[] = [];
+  for (const entry of entries) {
+    if (entry.kind === "action" && refused(entry.id)) continue;
+    if (entry.kind === "submenu") {
+      const items = omitRows(entry.items, refused);
+      if (items.length > 0) kept.push({ ...entry, items });
+      continue;
+    }
+    if (entry.kind === "separator" && (kept.length === 0 || kept[kept.length - 1]!.kind === "separator")) continue;
+    kept.push(entry);
+  }
+  while (kept.length > 0 && kept[kept.length - 1]!.kind === "separator") kept.pop();
+  return kept;
+}
+
+/** How both shot surfaces open `shotMenuEntries`: Paper's 432px wide surface.
+ *  One constant so the outline row and the timeline row cannot drift apart on
+ *  the box any more than on the rows. */
+export const SHOT_MENU_OPTIONS: OpenMenuOptions = { width: "wide" };
+
+/**
+ * What a right-click on a SHOT offers. Two surfaces open it — the outline's
+ * shot rows and the timeline's shot rows — and they have to agree completely,
+ * which is `layerMenuEntries`' argument applied to the other subject.
  *
- * Shared by both callers so "which of these can take a material" is answered
- * once. A component definition's interior is deliberately not searched: the
- * menu acts on what the outline is showing, which `editingDef` already scopes.
+ * `onRename` is a callback rather than a store verb because renaming is an
+ * INLINE edit: the store has `renameScene`, but which row goes into edit mode is
+ * a property of the surface that was clicked. The menu says "Rename" and the
+ * surface decides what that looks like.
+ *
+ * Every other entry is an existing verb, the same rule the layer menu follows.
+ *
+ * Both surfaces open it with `SHOT_MENU_OPTIONS`, for the same reason.
  */
-export function menuTargetsFor(state: ShotEditorState, ids: readonly string[]): MenuTargets {
-  const layers =
-    state.editingDef !== null
-      ? state.doc?.components?.[state.editingDef]?.layersById
-      : state.sceneId === null
-        ? undefined
-        : state.doc?.scenesById[state.sceneId]?.layersById;
-  const meshIds: string[] = [];
-  let hasMaterial = false;
-  for (const id of ids) {
-    const layer = layers?.[id];
-    if (layer === undefined || layer.kind !== "mesh") continue;
-    meshIds.push(id);
-    if (layer.mesh.material !== undefined) hasMaterial = true;
+export function shotMenuEntries(
+  store: ShotEditorStore,
+  state: ShotEditorState,
+  sceneId: string,
+  onRename: () => void,
+): MenuEntry[] {
+  const doc = state.doc;
+  const scene = doc?.scenesById[sceneId];
+  if (doc === undefined || doc === null || scene === undefined) return [];
+  const only = doc.scenes.length <= 1;
+  const last = doc.scenes[doc.scenes.length - 1] === sceneId;
+  // ON THE BOARD a Shot and its planned shot are one thing, so Duplicate and
+  // Delete take both, the strip's pairing; off it, the Shot alone.
+  const part = state.storyboardOpen ? doc.storyboard?.parts.find((p) => p.scene === sceneId) : undefined;
+
+  const entries: MenuEntry[] = [
+    {
+      kind: "action",
+      id: "shot-open",
+      label: "Open",
+      onSelect: () => store.enterScene(sceneId),
+    },
+    { kind: "action", id: "shot-rename", label: "Rename", onSelect: onRename },
+    {
+      kind: "action",
+      id: "shot-duplicate",
+      label: "Duplicate",
+      onSelect: () => (part === undefined ? store.duplicateScene(sceneId) : store.duplicateBoardShot(part.id)),
+    },
+    { kind: "separator" },
+    // The double-click used to do this and now opens the shot. It keeps the `\`
+    // key and it keeps a name here, because "show me this shot end to end" is a
+    // real request and it no longer has a gesture of its own.
+    {
+      kind: "action",
+      id: "shot-zoom",
+      label: "Zoom the timeline to this shot",
+      // The board's strip stands where the timeline does.
+      disabled: state.storyboardOpen,
+      title: state.storyboardOpen ? "The timeline is not on screen on the Storyboard." : undefined,
+      onSelect: () => store.fitDock(sceneId),
+    },
+  ];
+
+  // A seam belongs to the shot BEFORE it, so the last shot has none. Selecting
+  // the outgoing shot and seeking to its final frame is what the strip's cut
+  // diamond has always done: it puts the inspector's Transition section on the
+  // seam and the stage on the frame the blend starts from.
+  if (!last) {
+    entries.push({
+      kind: "action",
+      id: "shot-transition",
+      label:
+        scene.transition === undefined
+          ? "Add a transition after this shot"
+          : "Edit the transition after this shot",
+      onSelect: () => {
+        const window =
+          state.doc === null
+            ? undefined
+            : sceneWindows(state.doc).find((w) => w.id === sceneId);
+        store.setScene(sceneId);
+        if (window !== undefined)
+          store.seek(Math.max(window.start, window.end - 1));
+      },
+    });
+  }
+
+  // THE SHOT'S POST EFFECTS, copied whole onto another Shot. No chord: the
+  // keys belong to the layer pair. Paste is absent until there is a copy.
+  entries.push({ kind: "separator" });
+  entries.push({
+    kind: "action",
+    id: "shot-copy-effects",
+    label: "Copy effects",
+    onSelect: () => store.copyShotEffects(sceneId),
+  });
+  if (store.hasShotEffectsClip()) {
+    entries.push({
+      kind: "action",
+      id: "shot-paste-effects",
+      label: "Paste effects",
+      onSelect: () => store.pasteShotEffects([sceneId]),
+    });
   }
-  return { ids, meshIds, hasMaterial };
+
+  entries.push({ kind: "separator" });
+  entries.push({
+    kind: "action",
+    id: "shot-delete",
+    label: "Delete",
+    danger: true,
+    // A courtesy, never the guard: `deleteScene` refuses the last shot BY NAME,
+    // which is the message an author who reaches it should get.
+    disabled: only,
+    title: only ? LAST_SHOT : undefined,
+    onSelect: () => (part === undefined ? store.deleteScene(sceneId) : store.deleteBoardShot(part.id)),
+  });
+  return gateForViewer(state, entries);
+}
+
+/**
+ * The surface-local callbacks the app menu cannot express as store verbs.
+ *
+ * Every one of them ASKS THE AUTHOR SOMETHING — a name, a file — and neither a
+ * prompt nor a file dialog is a store verb: `<input type=file>` can only be
+ * opened by a click on a real element, and which row goes into edit mode is a
+ * property of the surface that was clicked. `shotMenuEntries`' `onRename`
+ * established the pattern; this is the same hatch with more doors.
+ */
+export interface AppMenuHooks {
+  /** Chrome preference lives with StudioThemeProvider, never in the shot document. */
+  themePreference: StudioThemePreference;
+  onThemePreference(preference: StudioThemePreference): void;
+  onRegenerate(): void;
+  onCopyPath(path: string): void;
+  onRenameScene(sceneId: string): void;
+  onRenameLayer(layerId: string): void;
+  onRenameComponent(defId: string): void;
+  /** Click the hidden audio `<input>`; the menu itself is not one. */
+  onImportAudio(): void;
+  onOpenHelp(): void;
+  /** Leave the editor for a Worker route. A hook and not `location.assign` in
+   *  here, because `menu.ts` is a pure function and a test that called a row
+   *  would navigate the test runner's own jsdom. */
+  onNavigate(href: string): void;
+}
+
+/**
+ * THE APP MENU: every verb this chrome has, under one button in the top-left.
+ *
+ * ── WHY IT EXISTS AT ALL, GIVEN EVERY VERB ALREADY HAS A KEY ────────────
+ *
+ * Because a key is not an affordance. `restack` (bring to front / send to back)
+ * was fully implemented with zero buttons and zero keys until this menu gave it
+ * rows (the bracket chords came later); `closeShot`,
+ * `deleteComponent`, `exitIsolationAll`, `toggleWorkingOrtho`, the six
+ * working-view presets and the three panel-size resets are each reachable by
+ * exactly one gesture nobody discovers, or by none. A laptop with no numpad
+ * cannot press Numpad1. The manual lists 60 bindings, which is a reference, not
+ * a way in.
+ *
+ * ── THE SAME THREE RULES AS THE MENUS ABOVE ─────────────────────────────
+ *
+ * DATA, not JSX, so the whole tree is one testable function. EVERY LEAF IS AN
+ * EXISTING VERB, so the menu can never be a second implementation of an edit
+ * (the six that have no verb call `store.handleKey` with their own key's event
+ * — see `probeFor`). And REBUILT ON EVERY OPEN, so `disabled` and `checked` are
+ * computed rather than subscribed.
+ *
+ * ── AND ONE RULE THE RIGHT-CLICK MENUS DO NOT HAVE ──────────────────────
+ *
+ * THE TOP-LEVEL ROWS NEVER MOVE. A right-click menu's shape may follow its
+ * subject (`layerMenuEntries` omits the material rows on a non-mesh selection,
+ * deliberately). A global menu's may not: an author learns "Layer is the sixth
+ * row", and a tree that reorders itself with the selection makes that knowledge
+ * wrong. So a whole branch that does not apply is DIMMED, never dropped — which
+ * is what Framer's dimmed Text and Vector submenus are, and why
+ * `MenuEntry`'s submenu arm grew a `disabled` field. Inside a submenu the
+ * contents may still vary; nobody counts rows two levels down.
+ */
+export function appMenuEntries(
+  store: ShotEditorStore,
+  state: ShotEditorState,
+  hooks: AppMenuHooks,
+): MenuEntry[] {
+  const doc = state.doc;
+  const sel = state.selection;
+  const targets = menuTargetsFor(state, sel);
+  const one = sel.length === 1 ? sel[0] : undefined;
+  const open = doc !== null;
+  // The three contexts, from the one place that spells them (the store's own
+  // `inSceneContext` is private to its closure). Local names because the rest
+  // of this function reads them dozens of times. `isSceneContext` already
+  // carries the "a document is open" term, so `open &&` would be saying it
+  // twice.
+  const inDef = inDefinition(state);
+  const inShot = inShotContext(state);
+  const sceneContext = isSceneContext(state);
+  // A VISIBLE working pane, which is `noWorkingPane()`'s condition inverted. Not
+  // a call to that helper: it is module-private AND it writes the error strip as
+  // a side effect, so asking it a question would paint a refusal every time the
+  // menu opened.
+  const pane = shownLayoutMode(state) !== "camera";
+  // The lead clause stays local on purpose: three callers refuse for three
+  // different reasons and each owns its own opening ("Rect draws in…", "that
+  // key aims…"). Only the tail is one rule, so only the tail is shared.
+  const noPane = formatCombo(`That aims ${layoutSpec("working").noun}, and ` + paneOnlyRefusal("camera"));
+  const defs = doc === null ? {} : componentDefsOf(doc);
+  const defIds = Object.keys(defs);
+  const drifted = one !== undefined && instanceDriftOf(state, one).length > 0;
+  // Read once per open, not subscribed: the Worker stamps the marker into the
+  // HTML, so it cannot change without a reload.
+  const hosted = isCloudWorkspace();
+
+  /**
+   * A branch, dimmed when NOTHING INSIDE IT CAN BE USED.
+   *
+   * One derived rule instead of a hand-written predicate per submenu. The
+   * hand-written version was already wrong on its second use: "Camera" carried
+   * `disabled: inDef`, which is true, and in the scene context it opened onto
+   * four dimmed rows anyway — a branch you can enter that offers nothing, which
+   * is worse than a dimmed one because it costs a click to find out.
+   *
+   * Applied BOTTOM-UP: an inner branch built with this already carries its own
+   * `disabled`, so an outer one reading its children gets the right answer with
+   * no recursion. `[].every()` is true, which is the behaviour an empty branch
+   * wants: a submenu with no reachable rows dims itself.
+   *
+   * `also` is for the conditions no row expresses: a submenu whose every row is
+   * legal but whose SUBJECT is missing (no document open).
+   */
+  const branch = (
+    label: string,
+    items: MenuEntry[],
+    also = false,
+  ): MenuEntry => ({
+    kind: "submenu",
+    label,
+    items,
+    disabled:
+      also ||
+      items
+        .filter((e) => e.kind !== "separator")
+        .every((e) => e.disabled === true),
+  });
+
+  /** A row whose only home is `handleKey`'s switch. See `probeFor`. */
+  const keyRow = (
+    menuId: string,
+    label: string,
+    extra?: { disabled?: boolean; title?: string },
+  ): MenuEntry => {
+    const probe = probeFor(menuId);
+    return {
+      kind: "action",
+      id: menuId,
+      label,
+      shortcut: shortcutFor(menuId),
+      disabled: extra?.disabled === true || probe === undefined,
+      ...(extra?.title === undefined ? {} : { title: extra.title }),
+      onSelect: () => {
+        if (probe !== undefined) store.handleKey(probe);
+      },
+    };
+  };
+
+  // ── File ────────────────────────────────────────────────────────────────
+  const file: MenuEntry[] = [
+    {
+      kind: "action",
+      id: "file.save",
+      label: "Save version…",
+      shortcut: shortcutFor("file.save"),
+      // The pending autosave lands first, as ⌘S always did; then the Version
+      // history panel asks for a name.
+      disabled: !open,
+      onSelect: () => {
+        void store.flush().catch(() => {});
+        store.askVersionName();
+      },
+    },
+    {
+      kind: "action",
+      id: "file.versions",
+      label: "Version history",
+      disabled: !open,
+      onSelect: () => store.openVersions(!state.versionsOpen),
+    },
+    // No separators in here: File is one short run, and its rows need no
+    // grouping to be read.
+    {
+      kind: "action",
+      id: "file.import.audio",
+      label: "Import audio…",
+      // The audio lane's own import button is the other door, and that lane
+      // is only drawn once there is a clip in it, so until this row existed
+      // the first import had no discoverable gesture.
+      disabled: !open,
+      onSelect: hooks.onImportAudio,
+    },
+    {
+      kind: "action",
+      id: "file.export",
+      label: "Export…",
+      shortcut: shortcutFor("file.export"),
+      disabled: !open,
+      onSelect: () => store.setExportOpen(true),
+    },
+  ];
+
+  // ── Edit ────────────────────────────────────────────────────────────────
+  const edit: MenuEntry[] = [
+    {
+      kind: "action",
+      id: "edit.undo",
+      label: "Undo",
+      shortcut: shortcutFor("edit.undo"),
+      disabled: !state.canUndo,
+      onSelect: () => store.undo(),
+    },
+    {
+      kind: "action",
+      id: "edit.redo",
+      label: "Redo",
+      shortcut: shortcutFor("edit.redo"),
+      disabled: !state.canRedo,
+      onSelect: () => store.redo(),
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "edit.copy",
+      label: "Copy",
+      shortcut: shortcutFor("edit.copy"),
+      disabled: sel.length === 0,
+      onSelect: () => store.copyLayers(),
+    },
+    {
+      kind: "action",
+      id: "edit.cut",
+      label: "Cut",
+      shortcut: shortcutFor("edit.cut"),
+      disabled: sel.length === 0,
+      onSelect: () => store.cutLayers(),
+    },
+    {
+      kind: "action",
+      id: "edit.paste",
+      label: "Paste",
+      shortcut: shortcutFor("edit.paste"),
+      disabled: !store.hasLayerClip(),
+      onSelect: () => store.pasteLayers(),
+    },
+    {
+      kind: "action",
+      id: "edit.duplicate",
+      label: "Duplicate",
+      shortcut: shortcutFor("edit.duplicate"),
+      disabled: sel.length === 0,
+      onSelect: () => store.duplicateSelection(),
+    },
+    {
+      kind: "action",
+      id: "edit.delete",
+      label: "Delete",
+      shortcut: shortcutFor("edit.delete"),
+      danger: true,
+      // NOT gated on the layer selection: `deleteSelection` has a subject ladder
+      // (marker → audio → keyframe → camera move → layers), so a focused marker
+      // with nothing selected is a real subject and the row must stay live for it.
+      disabled: !open,
+      onSelect: () => store.deleteSelection(),
+    },
+    { kind: "separator" },
+    // The motion clip, the layer menu's pair of pairs. Dimmed here and absent
+    // there, by the rule each kind of menu follows.
+    {
+      kind: "action",
+      id: "edit.copyAnimation",
+      label: "Copy animation",
+      shortcut: shortcutFor("edit.copyAnimation"),
+      disabled: targets.animationSource === undefined,
+      title: sel.length > 0 && targets.animationSource === undefined ? "The selected layers have no animation" : undefined,
+      onSelect: () => store.copyAnimation(),
+    },
+    {
+      kind: "submenu",
+      label: "Paste animation",
+      disabled: sel.length === 0 || !store.hasAnimationClip(),
+      items: [
+        {
+          kind: "action",
+          id: "edit.pasteAnimation.playhead",
+          label: "At playhead",
+          shortcut: shortcutFor("edit.pasteAnimation.playhead"),
+          onSelect: () => store.pasteAnimation("playhead"),
+        },
+        {
+          kind: "action",
+          id: "edit.pasteAnimation.original",
+          label: "At original time",
+          onSelect: () => store.pasteAnimation("original"),
+        },
+      ],
+    },
+    {
+      kind: "action",
+      id: "edit.copyEffects",
+      label: "Copy effects",
+      shortcut: shortcutFor("edit.copyEffects"),
+      disabled: targets.effectsSource === undefined,
+      title: sel.length > 0 && targets.effectsSource === undefined ? "The selected layers have no shadow or glow" : undefined,
+      onSelect: () => store.copyEffects(),
+    },
+    {
+      kind: "action",
+      id: "edit.pasteEffects",
+      label: "Paste effects",
+      shortcut: shortcutFor("edit.pasteEffects"),
+      disabled: sel.length === 0 || !store.hasEffectsClip(),
+      onSelect: () => store.pasteEffects(),
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "edit.selectAll",
+      label: "Select all",
+      shortcut: shortcutFor("edit.selectAll"),
+      disabled: !open,
+      onSelect: () => store.selectAll(),
+    },
+    {
+      kind: "action",
+      id: "edit.deselect",
+      label: "Deselect",
+      shortcut: shortcutFor("edit.deselect"),
+      disabled: sel.length === 0,
+      onSelect: () => store.select([]),
+    },
+    // Paper's grouping: Split sits in the selection run, right under Deselect.
+    // Group and Ungroup are not in Paper's Edit specimen, but they are shipped
+    // verbs with no other menu door, so they stay as the last run.
+    {
+      kind: "action",
+      id: "edit.split",
+      label: "Split at playhead",
+      shortcut: shortcutFor("edit.split"),
+      disabled: !open,
+      onSelect: () => store.splitAtPlayhead(),
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "edit.group",
+      label: "Group",
+      shortcut: shortcutFor("edit.group"),
+      // Two members minimum, the floor `groupSelection` itself enforces.
+      disabled: sel.length < 2,
+      title: sel.length < 2 ? "Select two or more layers to group" : undefined,
+      onSelect: () => store.groupSelection(),
+    },
+    {
+      kind: "action",
+      id: "edit.ungroup",
+      label: "Ungroup",
+      shortcut: shortcutFor("edit.ungroup"),
+      // No button anywhere in the chrome before this row.
+      disabled: sel.length === 0,
+      onSelect: () => store.ungroupSelection(),
+    },
+  ];
+
+  // ── Arrange: order, align, distribute ───────────────────────────────────
+  //
+  // Not "Layout": View ▸ Layout is the 3D / Split / Camera switch. The order
+  // rows act on the whole selection, each layer among its own siblings
+  // (`arrangeRows`), and dim only with nothing to act on or nothing but cloner
+  // templates, saying which. Row ids keep `layout.*` for the shortcut table.
+  const arrange = arrangeRows(store, state, sel, (to) => `layout.arrange.${to}`);
+
+  const alignRows = (distribute: boolean): MenuEntry[] =>
+    ALIGN_MODES.filter((mode) => DISTRIBUTE_MODES.has(mode) === distribute).map(
+      (mode) => {
+        // A distribution needs a first, a last and something between them. An
+        // alignment does not: ONE layer aligns to the canvas, which is the rule
+        // `alignLayers` states and the align grid already follows.
+        const short = distribute && sel.length < MIN_DISTRIBUTE;
+        return {
+          kind: "action" as const,
+          id: `layout.align.${mode}`,
+          label: ALIGN_LABELS[mode],
+          shortcut: shortcutFor(`layout.align.${mode}`),
+          disabled: sel.length === 0 || short,
+          ...(short
+            ? {
+                title: `${ALIGN_LABELS[mode]}: needs ${MIN_DISTRIBUTE} or more layers`,
+              }
+            : {}),
+          onSelect: () => store.alignSelection(mode),
+        };
+      },
+    );
+
+  const arrangeMenu: MenuEntry[] = [
+    ...arrange,
+    { kind: "separator" },
+    ...alignRows(false),
+    { kind: "separator" },
+    ...alignRows(true),
+  ];
+
+  // ── View ────────────────────────────────────────────────────────────────
+  // THREE LAYOUTS AND ONE FLAG, which is the shape of the thing rather than
+  // four alternatives. The 3D view, the split and the frame are three editors
+  // and exactly one is on screen, so they are a radio set answered by
+  // `stageLayout.mode`. Video is drawn OVER whichever one the author left and
+  // hands it back untouched, so it is a checkbox and it sits under a rule.
+  //
+  // The bottom strip's control carries the same three words beside Edit and
+  // Video; these rows are where the digits are taught.
+  const stageLayoutRows: MenuEntry[] = LAYOUT_MODES.map((mode) => {
+    // The table's rows, in key order, so the menu lists them the way the digits
+    // and the toolbar do. `title` and not `label`: the chip's word has to fit a
+    // segmented track, a menu row has to read as a noun beside "Split".
+    const spec = layoutSpec(mode);
+    // The SAME sentence the digits and the control refuse with, from the same
+    // function: only a definition refuses, and it refuses all three. A menu
+    // that invented its own wording would be a second explanation of one rule.
+    const no = layoutRefusal(inDef);
+    return {
+      kind: "action" as const,
+      id: spec.menuId,
+      label: spec.title,
+      shortcut: shortcutFor(spec.menuId),
+      // EXACTLY ONE ROW: three rows name three layouts, so a split ticks Split
+      // and nothing else. It reads the LAYOUT and not what is on screen,
+      // deliberately: under Video these rows say which editor is waiting
+      // underneath, and the Video row below says that one is on top.
+      checked: state.stageLayout.mode === mode,
+      disabled: no !== null,
+      ...(no === null ? {} : { title: no }),
+      onSelect: () => store.setViewLayout(mode),
+    };
+  });
+
+  // AND THE FLAG, under its own rule. Checkable rather than a fourth radio row:
+  // it is orthogonal to the three above, and a menu that folded it in would be
+  // saying the author chose between the camera view and Video when the camera
+  // view is what Video is drawn on.
+  const videoRefusal = layoutRefusal(inDef);
+  const videoRow: MenuEntry = {
+    kind: "action",
+    id: "view.video",
+    label: VIEW_MODE_SPECS.video.label,
+    shortcut: shortcutFor("view.video"),
+    checked: state.video,
+    disabled: videoRefusal !== null,
+    ...(videoRefusal === null ? {} : { title: videoRefusal }),
+    onSelect: () => store.setViewMode(state.video ? "edit" : "video"),
+  };
+
+  const shadingRows: MenuEntry[] = SHADING_MODES.map((mode) => ({
+    kind: "action" as const,
+    id: `view.shading.${mode}`,
+    label: shadingLabel(mode),
+    checked: state.shadingMode === mode,
+    // The camera pane is always the graded render and is not addressable.
+    disabled: !pane,
+    ...(pane ? {} : { title: noPane }),
+    onSelect: () => store.setShadingMode(mode),
+  }));
+
+  const presetRows: MenuEntry[] = (
+    [
+      ["front", "Front"],
+      ["back", "Back"],
+      ["right", "Right"],
+      ["left", "Left"],
+      ["top", "Top"],
+      ["bottom", "Bottom"],
+    ] as const satisfies ReadonlyArray<readonly [WorkingViewPreset, string]>
+  ).map(([preset, label]) => ({
+    kind: "action" as const,
+    id: `view.preset.${preset}`,
+    label,
+    disabled: !pane,
+    ...(pane ? {} : { title: noPane }),
+    onSelect: () =>
+      store.setWorkingView(presetWorkingView(state.workingView, preset)),
+  }));
+
+  const orbitRows: MenuEntry[] = (
+    [
+      ["left", -1, 0],
+      ["right", 1, 0],
+      ["up", 0, -1],
+      ["down", 0, 1],
+    ] as const
+  ).map(([dir, dx, dy]) => ({
+    kind: "action" as const,
+    id: `view.orbit.${dir}`,
+    label: `Orbit ${dir} ${ORBIT_STEP_DEG}°`,
+    disabled: !pane,
+    ...(pane ? {} : { title: noPane }),
+    onSelect: () =>
+      store.setWorkingView(
+        orbitByDegrees(
+          state.workingView,
+          dx * ORBIT_STEP_DEG,
+          dy * ORBIT_STEP_DEG,
+        ),
+      ),
+  }));
+
+  // ── THE WORK PLANE'S SECOND HOME ─────────────────────────────────────────
+  //
+  // The canvas bar shows the plane select only while the spline tool is armed
+  // (the moment it matters), so the plane needs a home that is always there.
+  // Same gate as `WorkPlaneBar`: an entered Shot whose working pane is on
+  // screen, or a definition, which occupies that pane whatever the layout.
+  const planeKind = state.sceneId === null ? "xy" : (state.workPlanes[state.sceneId]?.kind ?? "xy");
+  const planeOn = state.sceneId !== null && state.enteredScene !== null && (pane || inDef);
+  const planeNo = planeOn ? null : state.enteredScene === null ? "The work plane belongs to a Shot. Open one first." : noPane;
+  const planeNote = "The plane Shift+P draws spline anchors on. Selection needs one selected layer.";
+  const workPlaneRows: MenuEntry[] = (
+    [
+      ["xy", "XY"],
+      ["xz", "XZ"],
+      ["yz", "YZ"],
+      ["view", "View"],
+    ] as const
+  ).map(([kind, label]) => ({
+    kind: "action" as const,
+    id: `view.workPlane.${kind}`,
+    label,
+    checked: planeKind === kind,
+    disabled: planeNo !== null,
+    title: planeNo ?? planeNote,
+    onSelect: () => store.setWorkPlane({ kind }),
+  }));
+  workPlaneRows.push({
+    kind: "action",
+    id: "view.workPlane.selection",
+    label: "Selection",
+    checked: planeKind === "selection",
+    disabled: planeNo !== null || sel.length !== 1,
+    title: planeNo ?? planeNote,
+    onSelect: () => {
+      if (sel.length === 1) store.setWorkPlane({ kind: "selection", layerId: sel[0]! });
+    },
+  });
+
+  const workingView: MenuEntry[] = [
+    ...presetRows,
+    { kind: "separator" },
+    ...orbitRows,
+    {
+      kind: "action",
+      id: "view.orbit.half",
+      label: "Orbit 180°",
+      disabled: !pane,
+      ...(pane ? {} : { title: noPane }),
+      onSelect: () =>
+        store.setWorkingView(orbitByDegrees(state.workingView, 180, 0)),
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "view.ortho",
+      label: "Orthographic",
+      shortcut: shortcutFor("view.ortho"),
+      checked: state.workingView.ortho === true,
+      // No button anywhere before this row: Num5 was the only way in, and a
+      // laptop has no Num5.
+      disabled: !pane,
+      ...(pane ? {} : { title: noPane }),
+      onSelect: () =>
+        store.setWorkingView({
+          ...state.workingView,
+          ortho: state.workingView.ortho !== true,
+        }),
+    },
+  ];
+
+  // ── THE CAMERA VERBS, FROM THE ONE TABLE ────────────────────────────────
+  //
+  // Words, sentences and menu ids come out of `cameraVerbs.ts`, which the
+  // Camera bar over the stage and the shortcut manual read too. Only the
+  // gating is decided here, because only the menu knows the state.
+  const noShotCamera = "A component definition has no shot camera.";
+  const driven =
+    state.cameraDriver === null
+      ? null
+      : `The camera is driven by ${state.cameraDriver}, so the shot camera has no effect while it is.`;
+  const pilot = cameraVerb("pilot");
+  const toView = cameraVerb("toView");
+  const frameSel = cameraVerb("frameSelection");
+  const addMove = cameraVerb("addMove");
+  const camera: MenuEntry[] = [
+    {
+      kind: "action",
+      id: pilot.menuId,
+      label: pilot.label,
+      shortcut: shortcutFor(pilot.menuId),
+      checked: state.pilot,
+      // No pane gate: the store brings the Camera pane on screen itself when
+      // the 3D layout has none. A definition has no shot camera to pilot, and
+      // a driven camera would move nothing the picture shows.
+      disabled: !open || inDef || driven !== null,
+      ...(inDef ? { title: noShotCamera } : driven !== null ? { title: driven } : { title: pilot.sentence }),
+      onSelect: () => store.setPilot(!state.pilot),
+    },
+    {
+      kind: "action",
+      id: toView.menuId,
+      label: toView.label,
+      shortcut: shortcutFor(toView.menuId),
+      disabled: !pane || inDef || driven !== null,
+      ...(inDef
+        ? { title: noShotCamera }
+        : driven !== null
+          ? { title: driven }
+          : pane
+            ? { title: toView.sentence }
+            : { title: noPane }),
+      onSelect: () => store.alignCameraToWorkingView(),
+    },
+    {
+      kind: "action",
+      id: frameSel.menuId,
+      label: frameSel.label,
+      disabled: sel.length === 0 || inDef || driven !== null,
+      ...(inDef
+        ? { title: noShotCamera }
+        : driven !== null
+          ? { title: driven }
+          : sel.length === 0
+            ? { title: "Select a layer first." }
+            : { title: frameSel.sentence }),
+      onSelect: () => store.fitCameraToSelection(),
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: addMove.menuId,
+      label: addMove.label,
+      // ⇧C was reassigned to frame-all, so this verb has NO key producer left.
+      // The dock's "+ move" button and this row are its only doors.
+      disabled: !inShot,
+      title: inShot ? addMove.sentence : "Open a shot to add a move to it",
+      onSelect: () => store.addShotAtPlayhead(state.enteredScene ?? undefined),
+    },
+  ];
+
+  const appearance: MenuEntry[] = (
+    [
+      ["system", "System"],
+      ["light", "Light"],
+      ["dark", "Dark"],
+    ] as const satisfies ReadonlyArray<readonly [StudioThemePreference, string]>
+  ).map(([preference, label]) => ({
+    kind: "action" as const,
+    id: `view.appearance.${preference}`,
+    label,
+    checked: hooks.themePreference === preference,
+    onSelect: () => hooks.onThemePreference(preference),
+  }));
+
+  const panels: MenuEntry[] = [
+    {
+      kind: "action",
+      // One name per panel, the one its toggle button and its docs use: the
+      // column holds the outline, the board's rail or a mode's library, so
+      // "Outline" named only one of its occupants. The id never changes.
+      id: "view.panel.rail",
+      label: "Left panel",
+      shortcut: shortcutFor("view.panel.rail"),
+      checked: !state.railCollapsed,
+      onSelect: () => store.setRailCollapsed(!state.railCollapsed),
+    },
+    {
+      kind: "action",
+      id: "view.panel.inspector",
+      label: "Right panel",
+      shortcut: shortcutFor("view.panel.inspector"),
+      checked: !state.inspectorCollapsed,
+      onSelect: () => store.setInspectorCollapsed(!state.inspectorCollapsed),
+    },
+    {
+      kind: "action",
+      id: "view.panel.dock",
+      // The one panel toggle with no key bound. `PanelToggles` reads its hint
+      // from this id, so binding a key here shows it on that button too.
+      label: "Timeline",
+      checked: !state.dockCollapsed,
+      onSelect: () => store.setDockCollapsed(!state.dockCollapsed),
+    },
+    {
+      kind: "action",
+      id: "view.panel.all",
+      label: "Every panel",
+      shortcut: shortcutFor("view.panel.all"),
+      checked:
+        !state.railCollapsed &&
+        !state.inspectorCollapsed &&
+        !state.dockCollapsed,
+      onSelect: () => store.togglePanels(),
+    },
+    { kind: "separator" },
+    ...(agentInEditor()
+      ? [
+          {
+            kind: "action" as const,
+            id: "view.panel.agent",
+            label: "Agent",
+            checked: state.agentOpen,
+            // The credentials probe is the only thing that says there is an agent lane
+            // on this server at all; a null answer means the route never replied.
+            disabled: state.agentCredentials === null,
+            title:
+              state.agentCredentials === null
+                ? (state.agentCredentialsError ?? "Checking for the agent backend…")
+                : undefined,
+            onSelect: () => store.setAgentOpen(!state.agentOpen),
+          },
+        ]
+      : []),
+    {
+      kind: "action",
+      // The shipped library, which had a top-bar button until Paper's bar
+      // dropped it. It picks what a Project uses, so it needs one open.
+      id: "view.panel.library",
+      label: "Library",
+      checked: state.libraryBrowserOpen,
+      disabled: state.name === null,
+      onSelect: () => store.setLibraryBrowserOpen(!state.libraryBrowserOpen),
+    },
+    // NO "Inspector: Design / Animate" ROWS. They set `inspectorMode`, which
+    // was the deleted tab bit — the inspector has one face now, so there is
+    // nothing for a view command to switch. ⇧A's `tool.animate` row is a
+    // different verb that happens to share a word: it turns record mode on, so
+    // edits write keyframes, and it lives under Tool.
+  ];
+
+  // THE TWO DIAGNOSTIC CHIPS, and only those. The save-state and codegen chips
+  // are deliberately absent: they exist to tell the author something is unsaved
+  // or broken, and a warning with an off switch is a warning that is off on the
+  // day it matters. These two describe the MACHINE, which is exactly what an
+  // author recording their film does not want in the recording.
+  const statusBadges: MenuEntry[] = [
+    {
+      kind: "action",
+      id: "view.badges.fps",
+      label: "Playback rate",
+      checked: state.showFpsBadge,
+      onSelect: () => store.setFpsBadge(!state.showFpsBadge),
+    },
+    {
+      kind: "action",
+      id: "view.badges.backend",
+      label: "Renderer backend",
+      checked: state.showBackendBadge,
+      onSelect: () => store.setBackendBadge(!state.showBackendBadge),
+    },
+  ];
+
+  const view: MenuEntry[] = [
+    branch("Layout", stageLayoutRows),
+    videoRow,
+    branch("Shading", shadingRows),
+    {
+      // The grid floor lives in the working pane only, the key's own gate.
+      kind: "action",
+      id: "view.grid",
+      label: "Grid",
+      shortcut: shortcutFor("view.grid"),
+      checked: state.showGrid,
+      disabled: !pane,
+      ...(pane ? {} : { title: noPane }),
+      onSelect: () => store.toggleGrid(),
+    },
+    branch(layoutSpec("working").title, workingView),
+    branch("Work plane", workPlaneRows),
+    branch("Camera", camera),
+    branch("Status badges", statusBadges),
+    branch("Appearance", appearance),
+    { kind: "separator" },
+    {
+      // Paper page 24: the rulers draw on the camera pane, and the guides
+      // they create are only dragged out of them.
+      kind: "action",
+      id: "view.rulers",
+      label: "Rulers",
+      shortcut: shortcutFor("view.rulers"),
+      checked: state.rulers,
+      onSelect: () => store.setEditorPref("rulers", !state.rulers),
+    },
+    {
+      // Snapping to the frame and the other layers. User guides snap either
+      // way, and Ctrl drops both for one drag.
+      kind: "action",
+      id: "view.smartGuides",
+      label: "Smart guides",
+      checked: state.smartGuides,
+      onSelect: () => store.setEditorPref("smartGuides", !state.smartGuides),
+    },
+    {
+      // Paper page 24: the selected layers' Position paths on the stage. A
+      // viewer sees them too; only the editor can drag a key.
+      kind: "action",
+      id: "view.motionPaths",
+      label: "Motion paths",
+      checked: state.motionPaths,
+      onSelect: () => store.setEditorPref("motionPaths", !state.motionPaths),
+    },
+    {
+      // Paper page 23: the editor's behaviour toggles sit in one block after
+      // Appearance. A single plain pick moves a paused playhead onto it.
+      kind: "action",
+      id: "view.selectMovesPlayhead",
+      label: "Move playhead to selection",
+      checked: state.selectMovesPlayhead,
+      onSelect: () => store.setSelectMovesPlayhead(!state.selectMovesPlayhead),
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "view.zoomIn",
+      label: "Zoom in",
+      shortcut: shortcutFor("view.zoomIn"),
+      disabled: !open,
+      onSelect: () => store.zoomActivePane(1),
+    },
+    {
+      kind: "action",
+      id: "view.zoomOut",
+      label: "Zoom out",
+      shortcut: shortcutFor("view.zoomOut"),
+      disabled: !open,
+      onSelect: () => store.zoomActivePane(-1),
+    },
+    keyRow("view.zoomReset", "Zoom to 100%", { disabled: !open }),
+    {
+      kind: "action",
+      id: "view.fit",
+      label: "Fit the active pane",
+      shortcut: shortcutFor("view.fit"),
+      disabled: !open,
+      onSelect: () => store.fitActivePane(),
+    },
+    {
+      kind: "action",
+      id: "view.fitSelection",
+      // NAMED FOR ITS PANE, because "Frame selection with camera" sits one
+      // branch away and the two used to read as one verb: this one moves the
+      // author's own view and writes nothing.
+      label: `Frame the selection in ${layoutSpec("working").noun}`,
+      shortcut: shortcutFor("view.fitSelection"),
+      disabled: sel.length === 0 || !pane,
+      ...(pane ? {} : { title: noPane }),
+      onSelect: () => store.fitWorkingViewToSelection(),
+    },
+    { kind: "separator" },
+    branch("Panels", panels),
+  ];
+
+  // ── Tool ────────────────────────────────────────────────────────────────
+  const tool: MenuEntry[] = [
+    ...SHOT_TOOLS.map((t) => {
+      const spec = specOf(t);
+      const no = toolRefusal(
+        t,
+        toolLayoutMode(state),
+        sceneContext,
+        state.readOnly && readOnlyReason(state),
+        isolationInsertRefusal(state),
+      );
+      return {
+        kind: "action" as const,
+        id: `tool.${t}`,
+        label: spec.label,
+        ...(spec.key === null ? {} : { shortcut: toolKey(t)! }),
+        checked: state.tool === t,
+        disabled: no !== null,
+        ...(no === null ? {} : { title: no }),
+        onSelect: () => store.setTool(t),
+      };
+    }),
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "tool.animate",
+      label: "Animate mode",
+      shortcut: shortcutFor("tool.animate"),
+      // A checkbox and NOT a member of the tool radio above: it changes what an
+      // edit MEANS, not what a drag does. See tools.ts.
+      checked: state.animateMode,
+      title: "Animate: edits write keyframes at the playhead",
+      onSelect: () => store.setAnimateMode(!state.animateMode),
+    },
+  ];
+
+  // ── Layer: our dimmed Text / Vector ─────────────────────────────────────
+  //
+  // The right-click menu, spliced in whole, plus the verbs it has no room for.
+  // Splicing rather than rebuilding is what keeps the two from disagreeing about
+  // what Delete does — this branch IS the right-click menu.
+  const layer: MenuEntry[] = [
+    {
+      kind: "action",
+      id: "layer.rename",
+      label: "Rename…",
+      disabled: one === undefined,
+      onSelect: () => {
+        if (one !== undefined) hooks.onRenameLayer(one);
+      },
+    },
+    { kind: "separator" },
+    ...layerMenuEntries(store, state, targets),
+    { kind: "separator" },
+    keyRow("layer.trim.in", "Trim in to playhead", { disabled: sel.length === 0 }),
+    keyRow("layer.trim.out", "Trim out to playhead", { disabled: sel.length === 0 }),
+    { kind: "separator" },
+    keyRow("layer.flip.x", "Flip horizontal", { disabled: sel.length === 0 }),
+    keyRow("layer.flip.y", "Flip vertical", { disabled: sel.length === 0 }),
+    { kind: "separator" },
+    keyRow("layer.hideOthers", "Hide everything else", {
+      disabled: sel.length === 0,
+    }),
+    keyRow("layer.reveal", "Reveal everything"),
+    { kind: "separator" },
+    keyRow("layer.clear.position", "Clear the position", {
+      disabled: sel.length === 0,
+    }),
+    keyRow("layer.clear.rotation", "Clear the rotation", {
+      disabled: sel.length === 0,
+    }),
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "layer.isolate.exitAll",
+      label: "Exit every level of isolation",
+      // Escape is the one-level version and has always existed; this verb had no
+      // gesture but the breadcrumb's first crumb.
+      disabled: state.isolation === null,
+      onSelect: () => store.exitIsolationAll(),
+    },
+  ];
+
+  // ── Timeline ────────────────────────────────────────────────────────────
+  const timeline: MenuEntry[] = [
+    {
+      kind: "action",
+      id: "time.play",
+      // The Play control's own rules (PlayButton.tsx): a queued Play reads as
+      // the wait it is, and a second press calls it off.
+      label: state.playing ? "Pause" : state.playIntent !== null ? "Cancel play" : "Play",
+      shortcut: shortcutFor("time.play"),
+      // A capture loop owns the clock while an export runs, and the board does
+      // not play. `setPlaying` refuses underneath this on the same `playHold`,
+      // so the greying-out is the menu agreeing with it rather than a second
+      // rule. A scene still loading greys nothing: the press is queued. It
+      // gates the START only: a running transport or a queued Play stays
+      // stoppable from here.
+      //
+      // `exportLock` used to be tested a second time, unconditionally. It was
+      // always redundant, because both lock sites write `playing: false` in the
+      // same `set` as the lock, and it contradicted the sentence above by
+      // greying out Pause as well.
+      disabled: !open || (!playOn(state) && playHold(state) !== null),
+      title:
+        !open || state.playing
+          ? undefined
+          : state.playIntent === null
+            ? (playHold(state) ?? undefined)
+            : state.playIntent.phase === "preparing"
+              ? preparingTitle(state.playIntent)
+              : SCENE_WAITING,
+      onSelect: () => store.setPlaying(!playOn(state)),
+    },
+    {
+      kind: "action",
+      id: "time.step.next",
+      label: "Next frame",
+      disabled: !open,
+      onSelect: () => store.step(1),
+    },
+    {
+      kind: "action",
+      id: "time.step.prev",
+      label: "Previous frame",
+      disabled: !open,
+      onSelect: () => store.step(-1),
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "time.marker.add",
+      label: "Add a marker here",
+      shortcut: shortcutFor("time.marker.add"),
+      disabled: !open,
+      onSelect: () => store.addMarkerAtPlayhead(),
+    },
+    { kind: "separator" },
+    // ── THE WORK AREA ────────────────────────────────────────────────────
+    //
+    // Session state and never the document: it is what playback loops inside
+    // while an author watches one stretch over and over. The bracket is drawn
+    // on the dock's ruler (`WorkAreaBracket`, Header.tsx) and the three keys
+    // are in the Transport group of the shortcut table; without these rows the
+    // capability existed only as a chord nobody would find, which is the state
+    // the app menu exists to prevent.
+    //
+    // NOT GREYED OUT INSIDE A SHOT OR A DEFINITION, unlike Play. The two are
+    // different kinds of refusal. `setPlaying` refuses silently, so the menu
+    // dims the row to agree with it; `setWorkAreaEdge` refuses BY NAME with the
+    // sentence that says an entered shot already loops on its own and to come
+    // back out. A dimmed row swallows that sentence and leaves the author with
+    // a grey word and no reason, so these stay live wherever a document is
+    // open and let the verb do the talking.
+    {
+      kind: "action",
+      id: "time.workArea.in",
+      label: "Work area in at the playhead",
+      shortcut: shortcutFor("time.workArea.in"),
+      disabled: !open,
+      onSelect: () => store.setWorkAreaEdge("in"),
+    },
+    {
+      kind: "action",
+      id: "time.workArea.out",
+      label: "Work area out at the playhead",
+      shortcut: shortcutFor("time.workArea.out"),
+      disabled: !open,
+      onSelect: () => store.setWorkAreaEdge("out"),
+    },
+    {
+      kind: "action",
+      id: "time.workArea.clear",
+      label: "Clear the work area",
+      shortcut: shortcutFor("time.workArea.clear"),
+      // THE ONE THAT DOES DIM, because `clearWorkArea` returns on a null area
+      // and has nothing to say about it: there is no bracket, so "clear it" is
+      // a row with no subject rather than a refusal with a reason.
+      disabled: !open || state.workArea === null,
+      onSelect: () => store.clearWorkArea(),
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "time.mode.rows",
+      label: "Rows",
+      checked: state.dockMode === "rows",
+      onSelect: () => store.setDockMode("rows"),
+    },
+    {
+      kind: "action",
+      id: "time.mode.graph",
+      label: "Graph",
+      checked: state.dockMode === "graph",
+      onSelect: () => store.setDockMode("graph"),
+    },
+    {
+      kind: "action",
+      id: "time.mode.sound",
+      label: "Sound",
+      shortcut: shortcutFor("time.mode.sound"),
+      checked: state.dockMode === "sound",
+      onSelect: () => store.setDockMode("sound"),
+    },
+    {
+      kind: "action",
+      id: "time.fit",
+      label: "Fit the timeline",
+      shortcut: shortcutFor("time.fit"),
+      disabled: !open,
+      onSelect: () => store.fitDock(),
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "time.previewMuted",
+      label: "Mute the preview",
+      // MONITORING ONLY, never the mix and never the export.
+      checked: state.previewMuted,
+      onSelect: () => store.setPreviewMuted(!state.previewMuted),
+    },
+  ];
+
+  // ── Shot: the timeline row's own menu, for the shot at the playhead ─────
+  const shot: MenuEntry[] = [
+    ...(state.sceneId === null
+      ? []
+      : shotMenuEntries(store, state, state.sceneId, () => {
+          if (state.sceneId !== null) hooks.onRenameScene(state.sceneId);
+        })),
+    ...(open && state.sceneId !== null ? [{ kind: "separator" } as const] : []),
+    ...(open ? boardMenuEntries(store, state) : []),
+  ];
+
+  // ── Component ───────────────────────────────────────────────────────────
+  const defRows = (
+    idPrefix: string,
+    run: (defId: string) => void,
+  ): MenuEntry[] =>
+    defIds.map((defId) => ({
+      kind: "action" as const,
+      id: `${idPrefix}:${defId}`,
+      label: defs[defId]?.name ?? defId,
+      checked: state.editingDef === defId ? true : undefined,
+      onSelect: () => run(defId),
+    }));
+
+  const component: MenuEntry[] = [
+    {
+      kind: "action",
+      id: "comp.create",
+      label: "Make a component from the selection",
+      disabled: sel.length === 0,
+      title:
+        sel.length === 0
+          ? "Select the layers to turn into a component first"
+          : undefined,
+      onSelect: () => store.createComponentFromSelection(),
+    },
+    {
+      kind: "action",
+      id: "comp.createEmpty",
+      label: "New empty component",
+      // Never in the scene context: a definition's layers live inside a shot's
+      // container, and `insertContext` is what refuses otherwise.
+      disabled: sceneContext,
+      title: sceneContext
+        ? "Open a shot first: a component is made of its elements"
+        : undefined,
+      onSelect: () => store.createEmptyComponent("Component"),
+    },
+    { kind: "separator" },
+    branch(
+      "Place",
+      defRows("comp.place", (defId) => store.placeComponent(defId)),
+      sceneContext,
+    ),
+    branch(
+      "Open in Components",
+      defRows("comp.edit", (defId) => store.editComponent(defId)),
+    ),
+    {
+      kind: "action",
+      id: "comp.rebind",
+      // The inspector's word for the same verb, offered under the same
+      // condition: one code-component layer whose contract has drifted
+      // (`instanceDriftOf`, which the drift notice reads too). Never
+      // automatic: it is a statement that the live contract is the one this
+      // instance means, and only the author can make it.
+      label: "Accept current contract",
+      disabled: !drifted,
+      title: drifted ? undefined : "Select one code component whose contract has changed",
+      onSelect: () => {
+        if (one === undefined) return;
+        // The verb answers with its refusal rather than writing the error
+        // strip, so the row says it the way the inspector's button does.
+        void store.rebindInstance(one).then((refusal) => {
+          if (refusal !== null) store.reportError(refusal);
+        });
+      },
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "comp.rename",
+      label: "Rename this definition…",
+      disabled: !inDef,
+      onSelect: () => {
+        if (state.editingDef !== null)
+          hooks.onRenameComponent(state.editingDef);
+      },
+    },
+    {
+      kind: "action",
+      id: "comp.delete",
+      label: "Delete this definition",
+      danger: true,
+      // Implemented with zero callers before this row. It refuses while
+      // instances exist, naming where they are, so this is safe to offer bare.
+      disabled: !inDef,
+      onSelect: () => {
+        if (state.editingDef !== null) store.deleteComponent(state.editingDef);
+      },
+    },
+  ];
+
+  // ── Code ────────────────────────────────────────────────────────────────
+  //
+  // Every save regenerates the shot's contracted component at
+  // `src/shots/<doc.name>.tsx`. When codegen refuses to overwrite a hand edit it
+  // sets `emitWarning` and stays refused, and until this submenu the only way
+  // out was the CLI.
+  const code: MenuEntry[] = [
+    {
+      kind: "action",
+      id: "code.path",
+      label: "Copy the generated file's path",
+      disabled: doc === null,
+      onSelect: () => {
+        if (doc !== null) hooks.onCopyPath(`${GENERATED_SHOTS_DIR}/${doc.name}.tsx`);
+      },
+    },
+    {
+      kind: "action",
+      id: "code.regenerate",
+      label: "Regenerate the component…",
+      danger: true,
+      // Dimmed until there is something to un-stick, and it SAYS so: this
+      // discards hand edits, and offering it against a file nobody has touched
+      // is offering a destructive verb with nothing to destroy.
+      disabled: !open || state.emitWarning === null,
+      title:
+        state.emitWarning === null
+          ? "Nothing to regenerate: the generated file matches this document"
+          : state.emitWarning,
+      onSelect: hooks.onRegenerate,
+    },
+  ];
+
+  // ── The root ────────────────────────────────────────────────────────────
+  //
+  // Group 1 is Framer's surface switcher, answered honestly: `/api/surfaces`
+  // returns at most `["shot"]`, so there is no second surface to switch to — but
+  // there ARE three nested CONTEXTS, they are mutually exclusive, they are the
+  // product's real "where am I", and until this menu they had no global
+  // affordance at all (a double-click in, a breadcrumb out).
+  // The store's own refusal: nothing holds the board open, and opening hands
+  // over from any mode except Code Studio with unsaved buffers
+  // (`storyboardBlocker`), which the header's switch asks about first.
+  const boardHeld = state.storyboardOpen ? null : storyboardBlocker(state);
+  return gateForWorkspace(state, [
+    {
+      kind: "action",
+      id: "ctx.scene",
+      label: "Project",
+      checked: sceneContext,
+      disabled: !open || sceneContext,
+      onSelect: () => {
+        store.editComponent(null);
+        store.leaveScene();
+      },
+    },
+    {
+      kind: "action",
+      id: "ctx.shot",
+      label: "Shot",
+      checked: inShot,
+      disabled: doc === null || doc.scenes.length === 0 || inShot,
+      onSelect: () => {
+        // From a definition, "Shot" is one level out. From the scene context it
+        // is the shot the PLAYHEAD is in, which is what `sceneId` answers and
+        // what a double-click on the strip already uses.
+        if (inDef) store.editComponent(null);
+        else if (state.sceneId !== null) store.enterScene(state.sceneId);
+      },
+    },
+    {
+      kind: "action",
+      id: "ctx.component",
+      label: "Component",
+      checked: inDef,
+      // OUR DIMMED "Text": there is nothing to enter without one instance
+      // selected, and the row stays where an author learned it either way.
+      disabled:
+        inDef || one === undefined || !targets.opensComponent,
+      title:
+        inDef || one !== undefined
+          ? undefined
+          : "Select one component layer to open it in Components",
+      onSelect: () => {
+        if (one !== undefined) void store.openComponentContext(one);
+      },
+    },
+    // A fourth "where am I": the board is a per-Project place, and the
+    // top-level rows never move, so it is added here and never reordered.
+    {
+      kind: "action",
+      id: "ctx.storyboard",
+      label: "Storyboard",
+      shortcut: shortcutFor("ctx.storyboard"),
+      checked: state.storyboardOpen,
+      // A menu row cannot ask, so unsaved code in Code Studio holds it.
+      disabled: !open || boardHeld !== null,
+      ...(open && boardHeld !== null ? { title: boardHeld } : {}),
+      onSelect: () => store.setStoryboardOpen(!state.storyboardOpen),
+    },
+    { kind: "separator" },
+    branch("File", file),
+    branch("Edit", edit),
+    branch("View", view),
+    branch("Arrange", arrangeMenu, sel.length === 0),
+    branch("Tool", tool),
+    branch("Layer", layer, sel.length === 0),
+    branch("Timeline", timeline, !open),
+    branch("Shot", shot),
+    branch("Component", component),
+    branch("Code", code),
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "prefs.open",
+      label: "Preferences…",
+      shortcut: shortcutFor("prefs.open"),
+      onSelect: () => store.setPrefsOpen(true),
+    },
+    { kind: "action", id: "help", label: "Help", onSelect: hooks.onOpenHelp },
+    // ── PROJECT HOME ALWAYS; AUTH HOSTED ONLY ─────────────────────────────
+    //
+    // Local and hosted workspaces both own `/projects/`, so Project Home is a
+    // fixed row. Profile and Sign out are the exception to the "top-level rows
+    // never move" rule: `isCloudWorkspace()` reads a meta tag fixed for the
+    // page, and both stay hidden locally because the CLI has neither
+    // `/auth/logout` nor an account to have a profile.
+    //
+    // This narrows a stated decision in docs/cloud.md ("no editor cloud-awareness
+    // chrome"). These rows are NAVIGATION AND IDENTITY, not state or status:
+    // nothing here polls, nothing lands in the header, and the workspace's
+    // state still surfaces only as each call's own answer, as that note says.
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "acct.projects",
+      label: "Go to Projects",
+      onSelect: () => hooks.onNavigate("/projects/"),
+    },
+    ...(hosted
+      ? ([
+          {
+            kind: "action",
+            id: "acct.profile",
+            label: "Profile",
+            // The dashboard's own view, reached the way any other surface
+            // reaches it. onNavigate flushes autosave first, so leaving the
+            // editor from a menu never drops an edit.
+            onSelect: () => hooks.onNavigate("/projects/?view=profile"),
+          },
+          {
+            kind: "action",
+            id: "acct.signout",
+            label: "Sign out",
+            // A GET, because sign-out has to work as a plain link — and it still
+            // revokes the session row server-side (worker/src/auth.ts).
+            onSelect: () => hooks.onNavigate("/auth/logout"),
+          },
+        ] satisfies MenuEntry[])
+      : []),
+  ]);
+}
+
+/**
+ * THE WORKSPACE GATE over the whole menu. The top bar stays on screen in every
+ * mode now, so this menu is reachable from inside the material nodes and both
+ * studios, where most of its rows would act on a scene that is not on screen.
+ * A row the mode refuses is dimmed with the reason (`commandBlocker`), never
+ * dropped (top-level rows never move), and a branch left with nothing to use
+ * dims too, the rule `branch` states.
+ */
+function gateForWorkspace(state: ShotEditorState, entries: MenuEntry[]): MenuEntry[] {
+  // A viewer's menu is gated in every workspace, the stage one too.
+  if (workspaceOf(state) === "stage" && !state.readOnly) return entries;
+  return gateRows(entries, (id) => commandBlocker(state, id));
+}
+
+/**
+ * A VIEWER'S RIGHT-CLICK: every row that writes is dimmed with `VIEW_ONLY`.
+ * Each context-menu builder returns through this, so no surface that opens
+ * one has to know. The app menu gets the same answer from `commandBlocker`.
+ */
+export function gateForViewer(
+  state: Pick<ShotEditorState, "readOnly"> & Partial<Pick<ShotEditorState, "versionPreview" | "syncStatus">>,
+  entries: MenuEntry[],
+): MenuEntry[] {
+  const reason = readOnlyReason(state);
+  return state.readOnly ? gateRows(entries, (id) => viewOnlyBlocker(id) && reason) : entries;
+}
+
+/** Dim each row `reasonOf` refuses, with the reason. A submenu left with
+ *  nothing to use dims too. */
+function gateRows(entries: MenuEntry[], reasonOf: (id: string) => string | null): MenuEntry[] {
+  return entries.map((entry) => {
+    if (entry.kind === "separator") return entry;
+    if (entry.kind === "submenu") {
+      const inner = gateRows(entry.items, reasonOf);
+      const rows = inner.filter((e) => e.kind !== "separator");
+      const empty = rows.every((e) => e.disabled === true);
+      // A branch dimmed because every row is dimmed says why, in the words of
+      // its first row: a dimmed branch with no reason is what the rule forbids.
+      const why = entry.title ?? (empty ? rows.find((e) => e.title !== undefined)?.title : undefined);
+      return { ...entry, items: inner, disabled: entry.disabled === true || empty, ...(why === undefined ? {} : { title: why }) };
+    }
+    const reason = reasonOf(entry.id);
+    return reason === null ? entry : { ...entry, disabled: true, title: reason };
+  });
+}
+
+// ---- The storyboard's menu rows ----------------------------------------------
+
+/**
+ * THE BOARD'S OWN ROWS (A v2): the still, cut and motion verbs, in the app
+ * menu's Shot branch so WebMCP `run_command` reaches every one. A row that
+ * cannot run is dimmed WITH ITS REASON, never dropped.
+ */
+export function boardMenuEntries(store: ShotEditorStore, state: ShotEditorState): MenuEntry[] {
+  const doc = state.doc;
+  const one = state.storyboardSelection.length === 1 ? state.storyboardSelection[0]! : null;
+  // THE SHOT BOARD'S ROWS act on the open shot board and its sketch; Open in
+  // Studio and Add motion on that shot, else the selected one, else the one
+  // that links the entered Shot.
+  const plan = shotBoardOf(state);
+  const partId = plan ?? (one !== null && isPartId(one) ? one : boardTargetOf(state));
+  const gate = agentGate(state.agentCredentials, state.agentCredentialsError);
+  // THE BOARD CLOSED dims every row with why: each one writes to a board that
+  // is not on screen.
+  const noBoard = state.storyboardOpen ? undefined : BOARD_CLOSED;
+  const noPlan = noBoard ?? (plan === null ? NO_SHOT_BOARD : undefined);
+  const sketches = plan === null || doc === null ? [] : sketchesOf(doc, plan);
+  const sketch = sketches.find((s) => s.id === state.storyboardSketch);
+  const full = sketches.length >= SKETCHES_MAX ? `A shot holds at most ${SKETCHES_MAX} sketches.` : undefined;
+  const noSketch = noPlan ?? (sketch === undefined ? "Add a sketch first." : undefined);
+  const playing = state.sketchPlaying;
+  const noPlay = playing ? undefined : (noSketch ?? (sketch?.items.length === 0 ? "Put something on the sketch to play it." : undefined));
+  const noShot = noBoard ?? (partId === null ? "Select a planned shot first" : undefined);
+  const noMotion = noBoard ?? (!gate.ready ? gate.title : partId === null ? "Select a planned shot first" : undefined);
+  return [
+    {
+      kind: "action",
+      id: "board.sketch.add",
+      label: "Add sketch",
+      disabled: (noPlan ?? full) !== undefined,
+      title: noPlan ?? full,
+      onSelect: () => {
+        if (plan !== null) store.addSketch(plan);
+      },
+    },
+    {
+      kind: "action",
+      id: "board.sketch.duplicate",
+      label: "Duplicate sketch",
+      disabled: (noSketch ?? full) !== undefined,
+      title: noSketch ?? full,
+      onSelect: () => {
+        if (sketch !== undefined) store.duplicateSketch(sketch.id);
+      },
+    },
+    {
+      kind: "action",
+      id: "board.sketch.remove",
+      label: "Delete sketch",
+      danger: true,
+      disabled: noSketch !== undefined,
+      title: noSketch,
+      onSelect: () => {
+        if (sketch !== undefined) store.removeSketch(sketch.id);
+      },
+    },
+    {
+      kind: "action",
+      id: "board.sketch.play",
+      label: playing ? "Stop playing" : "Play sketch",
+      disabled: noPlay !== undefined,
+      title: noPlay,
+      onSelect: () => store.setSketchPlaying(!playing),
+    },
+    {
+      kind: "action",
+      id: "board.openStudio",
+      label: "Open in Studio",
+      disabled: noShot !== undefined,
+      title: noShot,
+      onSelect: () => {
+        if (partId !== null) store.openPlannedShot(partId);
+      },
+    },
+    ...(agentInEditor()
+      ? [
+          {
+            kind: "action" as const,
+            id: "board.motion",
+            label: "Add motion",
+            disabled: noMotion !== undefined,
+            title: noMotion,
+            onSelect: () => {
+              if (partId !== null) store.requestMotionForPart(partId);
+            },
+          },
+        ]
+      : []),
+  ];
+}
+
+
+/** What a right-click in the node canvas landed on. Computed by the canvas,
+ *  which is the only half that knows the hit and the point it happened at. */
+export interface MaterialNodeMenuTargets {
+  /** The material being edited. Carried rather than re-derived, so a menu built
+   *  in one slot cannot act on another's graph after the rail moved. */
+  materialId: string;
+  /** The scope trail the canvas was showing — `[]` is the main graph. */
+  path: readonly string[];
+  nodeIds: readonly string[];
+  edgeIds: readonly string[];
+  /** Where the press happened, in GRAPH coordinates: what "Add node here" and
+   *  "Insert reroute" both mean by "here". */
+  at: { x: number; y: number };
+}
+
+/**
+ * What a right-click on the node canvas offers.
+ *
+ * `layerMenuEntries`' three rules, verbatim: DATA and not JSX, every leaf an
+ * existing store verb, and OMIT rather than dim. The last one is why this
+ * function is a pile of `if` blocks instead of a list with `disabled` flags —
+ * "Expose as control" over a Colour node is a real offer, over a Subgraph node
+ * it is nothing, and a dimmed row invites a click to find out why.
+ *
+ * The one place a `disabled` survives is Delete over a selection that is only
+ * the output node, and even there the row is ABSENT: the store's refusal names
+ * the subject better than a tooltip could, and a menu that offered it would be
+ * offering something that cannot happen.
+ */
+export function materialNodeMenuEntries(
+  store: ShotEditorStore,
+  state: ShotEditorState,
+  targets: MaterialNodeMenuTargets,
+): MenuEntry[] {
+  const { materialId, path, nodeIds, edgeIds, at } = targets;
+  const graph = state.doc?.materials?.[materialId];
+  if (graph === undefined) return [];
+  const nodes = nodeIds
+    .map((id) => graph.nodesById[id])
+    .filter((node) => node !== undefined);
+  const one = nodes.length === 1 ? nodes[0]! : undefined;
+  const point: [number, number] = [at.x, at.y];
+
+  const entries: MenuEntry[] = [
+    {
+      kind: "action",
+      id: "graph-add",
+      label: "Add node here…",
+      shortcut: shortcutFor("graph.add"),
+      onSelect: () => store.openMaterialPalette({ x: at.x, y: at.y }),
+    },
+  ];
+
+  if (nodes.length > 0) {
+    entries.push({ kind: "separator" });
+    entries.push({
+      kind: "action",
+      id: "graph-duplicate",
+      label: "Duplicate",
+      shortcut: shortcutFor("graph.duplicate"),
+      onSelect: () => store.duplicateMaterialNodes(materialId, path, nodeIds),
+    });
+    entries.push({
+      kind: "action",
+      id: "graph-copy",
+      label: "Copy",
+      shortcut: shortcutFor("graph.copy"),
+      onSelect: () => store.copyMaterialNodes(materialId, path, nodeIds),
+    });
+    entries.push({
+      kind: "action",
+      id: "graph-cut",
+      label: "Cut",
+      shortcut: shortcutFor("graph.cut"),
+      onSelect: () => store.cutMaterialNodes(materialId, path, nodeIds),
+    });
+  }
+  entries.push({
+    kind: "action",
+    id: "graph-paste",
+    label: "Paste here",
+    shortcut: shortcutFor("graph.paste"),
+    onSelect: () =>
+      store.pasteMaterialNodes(materialId, path, { x: at.x, y: at.y }),
+  });
+
+  // ── The value seam, and it only ever offers ONE direction ───────────────
+  //
+  // A literal can become a control and a control can become a literal, and no
+  // node is both — so the two rows are never present together and neither is
+  // ever dimmed.
+  if (
+    one !== undefined &&
+    MATERIAL_GRAPH_PARAMETER_TYPES.some((type) => type === one.kind)
+  ) {
+    entries.push({ kind: "separator" });
+    entries.push({
+      kind: "action",
+      id: "graph-promote",
+      label: "Expose as control",
+      onSelect: () => store.promoteMaterialLiteral(materialId, path, one.id),
+    });
+  } else if (one?.kind === "parameter") {
+    entries.push({ kind: "separator" });
+    entries.push({
+      kind: "action",
+      id: "graph-demote",
+      label: "Inline value",
+      onSelect: () =>
+        store.demoteMaterialParameterNode(materialId, path, one.id),
+    });
+  }
+
+  // ── Boxes and functions ────────────────────────────────────────────────
+  const grouped = nodes.find(
+    (node) => node.kind === "group" || node.groupId !== undefined,
+  );
+  const groupId = grouped?.kind === "group" ? grouped.id : grouped?.groupId;
+  const boxable = nodes.filter((node) => node.kind !== "group");
+  if (boxable.length > 0 || groupId !== undefined)
+    entries.push({ kind: "separator" });
+  if (boxable.length > 0) {
+    entries.push({
+      kind: "action",
+      id: "graph-group",
+      label: "Group",
+      shortcut: shortcutFor("graph.group"),
+      onSelect: () =>
+        store.groupMaterialNodes(
+          materialId,
+          path,
+          boxable.map((node) => node.id),
+        ),
+    });
+  }
+  if (groupId !== undefined) {
+    entries.push({
+      kind: "action",
+      id: "graph-ungroup",
+      label: "Ungroup",
+      shortcut: shortcutFor("graph.ungroup"),
+      onSelect: () => store.ungroupMaterialNodes(materialId, path, groupId),
+    });
+  }
+  if (nodes.length > 0 && nodes.every((node) => node.kind !== "subgraph")) {
+    entries.push({
+      kind: "action",
+      id: "graph-collapse",
+      label: "Collapse to subgraph",
+      onSelect: () =>
+        store.createMaterialSubgraph(materialId, nodeIds, "Function"),
+    });
+  }
+  if (one?.kind === "subgraph") {
+    entries.push({
+      kind: "action",
+      id: "graph-open",
+      label: "Open subgraph",
+      shortcut: shortcutFor("graph.enter"),
+      onSelect: () => store.enterMaterialSubgraph(one.id),
+    });
+    entries.push({
+      kind: "action",
+      id: "graph-expand",
+      label: "Expand subgraph",
+      onSelect: () => store.expandMaterialSubgraph(materialId, path, one.id),
+    });
+  }
+
+  if (one !== undefined) {
+    entries.push({ kind: "separator" });
+    entries.push({
+      kind: "action",
+      id: "graph-preview",
+      label: "Preview on card",
+      shortcut: shortcutFor("graph.preview"),
+      checked: one.preview === true,
+      onSelect: () =>
+        store.setMaterialNodePreview(
+          materialId,
+          path,
+          one.id,
+          one.preview !== true,
+        ),
+    });
+  }
+
+  // ── Layout ─────────────────────────────────────────────────────────────
+  if (nodes.length > 1) {
+    entries.push({ kind: "separator" });
+    entries.push({
+      kind: "submenu",
+      label: "Align",
+      items: ALIGN_MODES.map((mode) => ({
+        kind: "action" as const,
+        id: `graph-align-${mode}`,
+        label: ALIGN_LABELS[mode],
+        // A distribution needs three, and this is the ONE dimmed row in the
+        // menu: it is inside a submenu, where the rule is about the branch
+        // rather than the rows, and dropping half the grid would move the
+        // alignments an author has learned by position.
+        disabled: DISTRIBUTE_MODES.has(mode) && nodes.length < MIN_DISTRIBUTE,
+        onSelect: () =>
+          store.alignMaterialNodes(materialId, path, nodeIds, mode),
+      })),
+    });
+  }
+  // UNCONDITIONAL, unlike every other layout row: with nothing selected this is
+  // still the answer to "put this graph back in order", which is exactly when
+  // an author reaches for it. The verb reads the same empty selection as "all
+  // of it in this scope".
+  if (nodes.length <= 1) entries.push({ kind: "separator" });
+  entries.push({
+    kind: "action",
+    id: "graph-tidy",
+    label: nodes.length > 1 ? "Tidy selection" : "Tidy graph",
+    shortcut: shortcutFor("graph.tidy"),
+    onSelect: () => store.tidyMaterialNodes(materialId, path, nodeIds),
+  });
+  if (nodes.length > 0) {
+    entries.push({
+      kind: "action",
+      id: "graph-snap-now",
+      label: "Snap to grid",
+      onSelect: () => store.snapMaterialNodesToGrid(materialId, path, nodeIds),
+    });
+  }
+  entries.push({
+    kind: "action",
+    id: "graph-snap",
+    label: "Snap while dragging",
+    checked: state.materialSnapToGrid,
+    onSelect: () => store.setMaterialSnapToGrid(!state.materialSnapToGrid),
+  });
+
+  // ── Wires ──────────────────────────────────────────────────────────────
+  if (edgeIds.length > 0) {
+    entries.push({ kind: "separator" });
+    if (edgeIds.length === 1) {
+      const edgeId = edgeIds[0]!;
+      entries.push({
+        kind: "action",
+        id: "graph-reroute",
+        label: "Insert reroute",
+        onSelect: () =>
+          store.insertMaterialReroute(materialId, path, edgeId, point),
+      });
+    }
+    entries.push({
+      kind: "action",
+      id: "graph-disconnect",
+      label:
+        edgeIds.length === 1
+          ? "Disconnect"
+          : `Disconnect ${edgeIds.length} wires`,
+      onSelect: () => store.disconnectMaterialEdges(materialId, path, edgeIds),
+    });
+  }
+
+  // ABSENT rather than dimmed when nothing in the selection can go — which is
+  // the output node on its own, and a function's boundary nodes.
+  const deletable = nodes.some(
+    (node) =>
+      node.kind !== "fn-input" &&
+      node.kind !== "fn-output" &&
+      materialGraphNodeSpec(node.kind)?.category !== "output",
+  );
+  if (deletable || edgeIds.length > 0) {
+    entries.push({ kind: "separator" });
+    entries.push({
+      kind: "action",
+      id: "graph-delete",
+      label: "Delete",
+      danger: true,
+      shortcut: shortcutFor("graph.delete"),
+      onSelect: () =>
+        store.deleteMaterialGraphItems(materialId, path, nodeIds, edgeIds),
+    });
+  }
+  return gateForViewer(state, entries);
+}
+
+/**
+ * The targets for a set of layer ids, read off the open document.
+ *
+ * Shared by both callers so "which of these can take a material" is answered
+ * once. A component definition's interior is deliberately not searched: the
+ * menu acts on what the outline is showing, which `editingDef` already scopes.
+ */
+export function menuTargetsFor(
+  state: ShotEditorState,
+  ids: readonly string[],
+): MenuTargets {
+  const layers =
+    state.editingDef !== null
+      ? state.doc?.components?.[state.editingDef]?.layersById
+      : state.sceneId === null
+        ? undefined
+        : state.doc?.scenesById[state.sceneId]?.layersById;
+  const meshIds: string[] = [];
+  let hasMaterial = false;
+  for (const id of ids) {
+    const layer = layers?.[id];
+    if (layer === undefined || layer.kind !== "mesh") continue;
+    meshIds.push(id);
+    if (layer.mesh.material !== undefined) hasMaterial = true;
+  }
+  // Everything below reads the FIRST target only. Opening N definitions from
+  // one click is not a thing an author asked for; and the flag labels already
+  // follow the first target by the same reasoning.
+  const first = ids.length === 0 ? undefined : layers?.[ids[0]!];
+  // The flags below read EVERY target. The copy sources follow the store's
+  // own rule (the first selected layer that has some), so the row names the
+  // layer the verb will actually read.
+  const kinds = ids.map((id) => layers?.[id]?.kind);
+  const container = state.editingDef ?? state.sceneId;
+  const doc = state.doc;
+  const sourceOf = (copy: (d: Doc3D, c: string, id: string) => { source: string } | null): string | undefined => {
+    if (doc === null || container === null) return undefined;
+    for (const id of ids) {
+      const clip = copy(doc, container, id);
+      if (clip !== null) return clip.source;
+    }
+    return undefined;
+  };
+  const animationSource = sourceOf(copyAnimation);
+  const effectsSource = sourceOf(copyEffects);
+  const home = doc === null || container === null ? null : homeOf(doc, container);
+  const hasMask = home !== null && ids.some((id) => maskTargetOf(home, id) !== null);
+  const underCloner =
+    home !== null &&
+    ids.some((id) => {
+      const parent = parentOf(home, id);
+      return parent !== null && home.layersById[parent]?.kind === "cloner";
+    });
+  return {
+    ids,
+    meshIds,
+    hasMaterial,
+    hidden: first?.hidden === true,
+    locked: first?.locked === true,
+    opensComponent: first?.kind === "component" || first?.kind === "instance",
+    hasGroup: kinds.includes("group"),
+    hasFlattenable: kinds.includes("group") || kinds.includes("component"),
+    ...(animationSource === undefined ? {} : { animationSource }),
+    ...(effectsSource === undefined ? {} : { effectsSource }),
+    hasMask,
+    ...(underCloner ? { maskRefusal: CLONER_MASK_REFUSAL } : {}),
+  };
 }