@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/shortcuts.ts

@@ -0,0 +1,1606 @@
+// EVERY BINDING THIS CHROME HAS, as a table — and the one place a combo string
+// is written down.
+//
+// It lived inside HelpSection.tsx, which was fine while the manual was its only
+// reader. The app menu is the second, and a data table reached through a React
+// component is a data table that drags a Dialog into `state/menu.ts` (which is
+// deliberately JSX-free). So it moved here, beside `keymap.ts`, which is what
+// it documents. The manual imports it and re-exports it; nothing else changed.
+//
+// ── WHY IT IS HAND-WRITTEN AND NOT DERIVED ──────────────────────────────
+//
+// `resolveKey` is a FUNCTION with seven ordered lanes, not a table: the same
+// letter is two commands depending on where the pointer is, Escape is a
+// four-rung ladder, and one lane blanks every other key on purpose. There is no
+// inverse to invert.
+//
+// So each row carries the EXACT EVENT it claims to describe plus the action
+// kind the keymap must answer for it, and test/helpSection.test.tsx walks every
+// row through the real `resolveKey`. A binding change without a table edit is a
+// red test, not a stale manual — and now, not a stale menu either.
+//
+// The SHAPE of every row is still written out here. What some rows no longer
+// write is their WORDS: the three layout keys take combo, prose and menu id
+// from `state/layouts.ts`, which is the table the toolbar and the View menu
+// already read, so a rename cannot reach two of those three surfaces and stop.
+import type { KeyAction, KeyContext, KeyEventLike, SketchKeyAction } from "./keymap.js";
+import { cameraVerb } from "./cameraVerbs.js";
+import { LAYOUT_MODES, layoutSpec } from "./layouts.js";
+import { SHADING_MODES, shadingLabel } from "../stage/shading.js";
+import { VIEW_MODE_SPECS } from "./viewMode.js";
+import { specOf } from "../tools.js";
+import type { ShotTool } from "../tools.js";
+import { ALIGN_LABELS } from "@dailies-studio/shot/doc";
+
+/** The manual's sections, in the order it prints them. It reads this to render
+ *  them, so a new group is one edit here rather than a union the manual has to
+ *  be taught a second time. */
+export const SHORTCUT_GROUPS = [
+  "View",
+  // ITS OWN GROUP, not rows folded into "View". Every one of these moves the
+  // PLAYHEAD or the clock that drives it, which is the one subject an author
+  // looks for as a set — and the set is now large enough (a shuttle, three
+  // kinds of jump, a work area) that scattering it through the view keys would
+  // hide it. `HelpSection` derives its sections from this list, so the heading
+  // costs one word here and nothing there.
+  "Transport",
+  "3D view",
+  "Edit",
+  "Animate & camera",
+  "Material nodes",
+  "Storyboard",
+] as const;
+
+export type ShortcutGroup = (typeof SHORTCUT_GROUPS)[number];
+
+export interface ShortcutRow {
+  /** What the manual shows, house glyph style (⌘ ⇧ ⌥ — ⌘ is Ctrl on Windows). */
+  combo: string;
+  /**
+   * The Mac's chord, for the rows whose Mac keys are NOT the same keys under
+   * the Mac's glyphs, with the event it sends. Arrange's front and back are
+   * Ctrl+⇧] on Windows and Linux and ⌥⌘] on a Mac, because ⌘⇧] and ⌘⇧[ are
+   * the Mac's tab switch (founder decision 3, critic 5). `comboOf` prints this
+   * on a Mac and `combo` everywhere else; the manual's test walks both probes.
+   */
+  mac?: { combo: string; probe: KeyEventLike };
+  does: string;
+  group: ShortcutGroup;
+  /** The event this combo produces, so the test can ask the keymap itself. */
+  probe: KeyEventLike;
+  /**
+   * The app-menu row this binding belongs to, when one exists.
+   *
+   * ── WHY THE MENU READS THIS TABLE RATHER THAN TYPING ITS OWN GLYPHS ────
+   *
+   * `ZoomControls.tsx` typed its own hint and it drifted (it still claimed ⇧Z
+   * for a fit that moved to Home). The menu is forty-odd more chances to do
+   * that. Pointing a row at a table entry costs one field and inherits that
+   * entry's test: rebind the key, and the walk-through fails on the row whose
+   * accelerator the menu was about to render.
+   *
+   * A row that covers SEVERAL keys in one line of prose ("Num2 / 4 / 6 / 8")
+   * carries no id — its `combo` is not a single accelerator, and a menu row
+   * showing it would be lying about which key it is. Where a menu wanted the
+   * digits individually the prose row was SPLIT instead (the three layout
+   * digits, the two zoom directions, the two clear-transform channels), so
+   * every id maps to exactly one key and the manual gained the detail too.
+   */
+  menuId?: string;
+  /** Arrows answer differently with a selection; everything else omits it. */
+  hasSelection?: boolean;
+  /** The pen's two rows answer differently with a path open, and ONLY with one
+   *  open — Escape means deselect the rest of the time, which is why the
+   *  context carries "holds points" and not "the pen tool is armed". */
+  penActive?: boolean;
+  /** Escape's third meaning: leave one level of isolation. It only answers
+   *  that with NOTHING selected, so the row carries the bit and the test
+   *  probes with `hasSelection` false. */
+  isolation?: boolean;
+  /** Escape's FIRST meaning, above all the others: put the editor back. Only
+   *  while Video is on screen, so the row carries the bit. */
+  video?: boolean;
+  /** The modal starters (G/R/S) answer only with the cursor over the working
+   *  pane — the same letters arm tools everywhere else, and both readings
+   *  have rows. */
+  workingPane?: boolean;
+  /** The axis and terminator rows answer only while a transform is LIVE. */
+  transformModal?: boolean;
+  /** The material-graph rows answer only inside the node canvas — and answer
+   *  something ELSE outside it, which is the whole reason the lane exists. */
+  materialGraph?: boolean;
+  /** The storyboard rows answer only while the board is open, and answer
+   *  something ELSE outside it: Delete removes a layer there. */
+  storyboard?: boolean;
+  /** A shot board's sketch keys (`resolveShotBoardKey`). */
+  shotBoard?: boolean;
+  /** The rest of the context a row answers under, for the bits only a row or
+   *  two read (Escape's lower rungs, the clipboards). The manual's test spreads
+   *  it into the probe's context. */
+  context?: Omit<KeyContext, "editing" | "hasSelection">;
+  /** The action `resolveKey(probe)` must return (`resolveShotBoardKey` for a
+   *  shot board row). */
+  action: KeyAction["kind"] | SketchKeyAction["kind"];
+}
+
+const probe = (
+  key: string,
+  m: { shift?: boolean; ctrl?: boolean; alt?: boolean; meta?: boolean; code?: string } = {},
+): KeyEventLike => ({
+  key,
+  shiftKey: m.shift === true,
+  altKey: m.alt === true,
+  ctrlKey: m.ctrl === true,
+  metaKey: m.meta === true,
+  ...(m.code === undefined ? {} : { code: m.code }),
+});
+
+export const SHORTCUTS: readonly ShortcutRow[] = [
+  {
+    group: "View",
+    combo: "⇧S",
+    does: "Open or close the Storyboard",
+    probe: probe("s", { shift: true }),
+    action: "storyboardToggle",
+    menuId: "ctx.storyboard",
+  },
+  // ── THE TRANSPORT ────────────────────────────────────────────────────────
+  //
+  // Space and the step keys were rows of "View" when the playhead had three
+  // bindings between them. It has eleven now, so they moved into the group the
+  // rest of them are in rather than leaving the set split across two headings.
+  {
+    group: "Transport",
+    combo: "Space",
+    does: "Play / pause",
+    probe: probe(" "),
+    action: "playToggle",
+    menuId: "time.play",
+  },
+  {
+    group: "Transport",
+    combo: "← →",
+    does: "Step one frame (nothing selected)",
+    probe: probe("ArrowRight"),
+    action: "step",
+  },
+  {
+    group: "Transport",
+    combo: "⇧← ⇧→",
+    does: "Step one second (nothing selected)",
+    probe: probe("ArrowRight", { shift: true }),
+    action: "stepSeconds",
+  },
+  {
+    group: "Transport",
+    combo: "↑ ↓",
+    does: "To the previous / next edit point: a shot boundary, a lifespan edge, a marker",
+    probe: probe("ArrowUp"),
+    action: "jumpEdit",
+  },
+  // ── THE SHUTTLE, AND WHY IT IS NOT J / K / L ─────────────────────────────
+  //
+  // `L` is the Line tool and `⇧L` is the Arrow tool (`TOOL_SPECS`), and ⌥L is
+  // the lock. A shuttle on any of the three would shadow a binding that has no
+  // other key, so the run's third rung is ⇧K. See the block in keymap.ts.
+  {
+    group: "Transport",
+    combo: "J",
+    does: "Shuttle backwards: 1x, then 2x, then 4x in reverse",
+    probe: probe("j"),
+    action: "shuttle",
+  },
+  {
+    group: "Transport",
+    combo: "K",
+    does: "Stop, and put the speed back to 1x",
+    probe: probe("k"),
+    action: "shuttleStop",
+  },
+  {
+    group: "Transport",
+    combo: "⇧K",
+    does: "Shuttle forwards: 1x, then 2x, then 4x (L is the Line tool)",
+    probe: probe("k", { shift: true }),
+    action: "shuttle",
+  },
+  {
+    group: "Transport",
+    combo: ";",
+    does: "To the selection's in point",
+    probe: probe(";"),
+    action: "seekSelectionEdge",
+  },
+  {
+    group: "Transport",
+    combo: "'",
+    does: "To the selection's out point",
+    probe: probe("'"),
+    action: "seekSelectionEdge",
+  },
+  // ── THE WORK AREA ────────────────────────────────────────────────────────
+  //
+  // Session state, never the document: it is what playback loops inside while
+  // an author watches one stretch over and over. See `ShotEditorState.workArea`
+  // for why it is not a document field.
+  {
+    group: "Transport",
+    combo: "⌥I",
+    does: "Work area in at the playhead (playback loops inside it)",
+    probe: probe("i", { alt: true }),
+    action: "setWorkArea",
+    menuId: "time.workArea.in",
+  },
+  {
+    group: "Transport",
+    combo: "⌥O",
+    does: "Work area out at the playhead",
+    probe: probe("o", { alt: true }),
+    action: "setWorkArea",
+    menuId: "time.workArea.out",
+  },
+  {
+    group: "Transport",
+    combo: "⌥X",
+    does: "Clear the work area: loop the whole film again",
+    probe: probe("x", { alt: true }),
+    action: "clearWorkArea",
+    menuId: "time.workArea.clear",
+  },
+  // THE KEYFRAME JUMPS, on the alt lane since the shuttle took J and K. They
+  // had no row at all before, so the manual was silent about a working pair of
+  // keys — which is the state this table exists to prevent.
+  {
+    group: "Transport",
+    combo: "⌥J",
+    does: "To the previous keyframe on the focused track",
+    probe: probe("j", { alt: true }),
+    action: "jumpKeyframe",
+  },
+  {
+    group: "Transport",
+    combo: "⌥K",
+    does: "To the next keyframe on the focused track",
+    probe: probe("k", { alt: true }),
+    action: "jumpKeyframe",
+  },
+  // THREE ROWS, one per layout, in key order. Still one row per key, so the
+  // View ▸ Layout entries can each name their own and each is walked through
+  // `resolveKey` on its own, which a single "⇧1 / ⇧2 / ⇧3" line could not do.
+  // The words, the keys and the menu ids come out of `state/layouts.ts`, so a
+  // rename or a rebind reaches the manual with no edit here. `probe` is
+  // module-private, which is why the derivation lives in this file rather than
+  // beside the table. The probe's `key` is the digit (what AZERTY reports);
+  // the keymap reads `code`, so a US board's "!" answers the same.
+  ...LAYOUT_MODES.map((mode): ShortcutRow => {
+    const spec = layoutSpec(mode);
+    return {
+      group: "View",
+      combo: spec.key,
+      does: spec.does,
+      probe: probe(spec.code.slice("Digit".length), { shift: true, code: spec.code }),
+      action: "stageLayout",
+      menuId: spec.menuId,
+    };
+  }),
+  // The two view-mode rows stay written out: Video's key and Escape's are not a
+  // pair (`VIEW_MODE_SPECS` says so), and the Escape row carries a context bit
+  // no table can hold. What they no longer own is the key or the word.
+  {
+    group: "View",
+    combo: VIEW_MODE_SPECS.video.key,
+    does: `${VIEW_MODE_SPECS.video.label}: the finished picture, and the only view that plays`,
+    probe: probe("$", { shift: true, code: VIEW_MODE_SPECS.video.code }),
+    action: "viewMode",
+    menuId: "view.video",
+  },
+  {
+    group: "View",
+    // The spec's `key` is the GLYPH the manual prints ("Esc"); the event this
+    // sends is the browser's "Escape". Two spellings of one key, which is why
+    // the probe is not built from the combo the way the layout rows' are.
+    combo: VIEW_MODE_SPECS.edit.key,
+    does: `Leave ${VIEW_MODE_SPECS.video.label}, and put the editor back`,
+    probe: probe("Escape"),
+    video: true,
+    action: "viewMode",
+  },
+  {
+    group: "View",
+    combo: "[",
+    does: "Hide / show the left panel",
+    probe: probe("["),
+    action: "togglePanel",
+    menuId: "view.panel.rail",
+  },
+  {
+    group: "View",
+    combo: "]",
+    does: "Hide / show the right panel",
+    probe: probe("]"),
+    action: "togglePanel",
+    menuId: "view.panel.inspector",
+  },
+  {
+    group: "View",
+    combo: ".",
+    does: "Hide every panel",
+    probe: probe("."),
+    action: "togglePanel",
+    menuId: "view.panel.all",
+  },
+  {
+    group: "View",
+    combo: "⌥M",
+    does: "Sound mode on / off: the timeline's tracks and mixer",
+    probe: probe("m", { alt: true }),
+    action: "soundMode",
+    menuId: "time.mode.sound",
+  },
+  {
+    group: "View",
+    combo: "\\",
+    does: "Fit the timeline",
+    probe: probe("\\"),
+    action: "fitTimeline",
+    menuId: "time.fit",
+  },
+  {
+    group: "View",
+    combo: "⌘+",
+    does: "Zoom in",
+    probe: probe("=", { ctrl: true }),
+    action: "zoom",
+    menuId: "view.zoomIn",
+  },
+  {
+    group: "View",
+    combo: "⌘−",
+    does: "Zoom out",
+    probe: probe("-", { ctrl: true }),
+    action: "zoom",
+    menuId: "view.zoomOut",
+  },
+  {
+    group: "View",
+    combo: "⌘0",
+    does: "Zoom to 100%",
+    probe: probe("0", { ctrl: true }),
+    action: "zoomReset",
+    menuId: "view.zoomReset",
+  },
+  {
+    group: "View",
+    combo: "Home",
+    does: "Fit the active pane",
+    probe: probe("Home"),
+    action: "fit",
+    menuId: "view.fit",
+  },
+  {
+    group: "View",
+    combo: "⇧C",
+    does: "Fit the active pane (Blender's frame all)",
+    probe: probe("c", { shift: true }),
+    action: "fit",
+  },
+  {
+    group: "Edit",
+    combo: "C",
+    does: "Comment on the picture at the playhead",
+    probe: probe("c"),
+    action: "storyboardComment",
+  },
+  {
+    group: "View",
+    combo: "Z",
+    does: `Cycle working-pane shading (${SHADING_MODES.map((m) => shadingLabel(m).toLowerCase()).join(" / ")})`,
+    probe: probe("z"),
+    action: "shadingCycle",
+  },
+  {
+    group: "View",
+    combo: "⇧Z",
+    does: `${shadingLabel("wireframe")} on / off`,
+    probe: probe("z", { shift: true }),
+    action: "wireframeToggle",
+  },
+  {
+    group: "View",
+    combo: "⌥Z",
+    does: "Grid floor on / off (working pane)",
+    probe: probe("z", { alt: true }),
+    action: "gridToggle",
+    menuId: "view.grid",
+  },
+  {
+    group: "View",
+    combo: "⇧R",
+    does: "Rulers on / off (camera pane)",
+    probe: probe("r", { shift: true }),
+    action: "rulersToggle",
+    menuId: "view.rulers",
+  },
+
+  {
+    group: "3D view",
+    combo: "G",
+    does: "Grab the selection: move it with the mouse, click to place",
+    probe: probe("g"),
+    workingPane: true,
+    hasSelection: true,
+    action: "modalStart",
+  },
+  {
+    group: "3D view",
+    combo: "R",
+    // A Shot's 3D view only: inside a definition the one pane is the frame,
+    // where R arms Rect (the keymap's `framePane` bit). A code component's
+    // preview is no frame, so R keeps its rotate there.
+    does: "Rotate the selection (roll). Inside a Studio-made component, R arms Rect",
+    probe: probe("r"),
+    workingPane: true,
+    hasSelection: true,
+    action: "modalStart",
+  },
+  {
+    group: "3D view",
+    combo: "S",
+    does: "Scale the selection",
+    probe: probe("s"),
+    workingPane: true,
+    hasSelection: true,
+    action: "modalStart",
+  },
+  {
+    group: "3D view",
+    combo: "G / R / S",
+    does: "Nothing selected: move / roll / zoom the camera",
+    probe: probe("g"),
+    workingPane: true,
+    action: "modalStart",
+  },
+  {
+    group: "3D view",
+    combo: "X / Y / Z",
+    does: "Constrain the transform to an axis (again clears; G+Z = depth)",
+    probe: probe("x"),
+    transformModal: true,
+    action: "modalAxis",
+  },
+  {
+    group: "3D view",
+    combo: "⇧X / ⇧Y / ⇧Z",
+    does: "Constrain a move to the PLANE normal to that axis (⇧X moves in YZ)",
+    probe: probe("x", { shift: true }),
+    transformModal: true,
+    action: "modalAxis",
+  },
+  {
+    group: "3D view",
+    combo: "0-9",
+    does: "Type an exact value: G X 200 Enter",
+    probe: probe("2"),
+    transformModal: true,
+    action: "modalNumber",
+  },
+  {
+    group: "3D view",
+    combo: "Backspace",
+    does: "Erase a typed digit (empty gives the mouse back)",
+    probe: probe("Backspace"),
+    transformModal: true,
+    action: "modalNumberBack",
+  },
+  // `hasSelection` only because the row PROBES with R over a live modal, and
+  // the manual's example is a layer transform; the camera rolls under R as
+  // well (`framingDeltaFor`, and the gizmo's own arc).
+  {
+    group: "3D view",
+    combo: "G / R / S",
+    does: "Switch transform without leaving the gesture",
+    probe: probe("r"),
+    transformModal: true,
+    hasSelection: true,
+    action: "modalStart",
+  },
+  {
+    group: "3D view",
+    combo: "Enter",
+    does: "Confirm the transform (or click)",
+    probe: probe("Enter"),
+    transformModal: true,
+    action: "modalConfirm",
+  },
+  {
+    group: "3D view",
+    combo: "Esc",
+    does: "Cancel the transform (or right-click)",
+    probe: probe("Escape"),
+    transformModal: true,
+    action: "modalCancel",
+  },
+  {
+    group: "3D view",
+    combo: "Num1 / 3 / 7",
+    does: "Front / right / top view (⌘ = the opposite)",
+    probe: probe("1", { code: "Numpad1" }),
+    action: "workingViewPreset",
+  },
+  {
+    group: "3D view",
+    combo: "Num0",
+    // The verb table's own sentence, for the reason the layout rows take
+    // theirs from `layouts.ts`: the bar, the menu and this manual must not
+    // spell one verb three ways again.
+    does: cameraVerb("pilot").sentence,
+    probe: probe("0", { code: "Numpad0" }),
+    action: "pilotToggle",
+    menuId: cameraVerb("pilot").menuId,
+  },
+  {
+    group: "3D view",
+    combo: "Esc",
+    does: "Stop piloting the camera",
+    probe: probe("Escape"),
+    context: { pilot: true },
+    action: "pilotEject",
+  },
+  {
+    group: "3D view",
+    combo: "Num.",
+    does: "Frame the selection",
+    probe: probe(".", { code: "NumpadDecimal" }),
+    action: "fitSelection",
+    menuId: "view.fitSelection",
+  },
+  {
+    group: "3D view",
+    combo: "Num2 / 4 / 6 / 8",
+    does: "Orbit 15°; Num9 looks from the opposite side",
+    probe: probe("4", { code: "Numpad4" }),
+    action: "orbitStep",
+  },
+  {
+    group: "3D view",
+    combo: "Num5",
+    does: "Orthographic / perspective",
+    probe: probe("5", { code: "Numpad5" }),
+    action: "toggleWorkingOrtho",
+    menuId: "view.ortho",
+  },
+  // NO NUMPAD, NO PROBLEM. The numpad lane keys on `event.code`, so a laptop
+  // without one had no keyboard path at all to the three views a 3D pane is
+  // most often asked for. Blender maps the bare top-row digits; here those are
+  // kept free, so the alt lane takes them.
+  {
+    group: "3D view",
+    combo: "⌥1 / ⌥3 / ⌥7",
+    does: "Front / right / top view without a numpad (add ⇧ for the opposite side)",
+    probe: probe("1", { alt: true }),
+    action: "workingViewPreset",
+  },
+  {
+    group: "3D view",
+    combo: "⌥5",
+    does: "Orthographic / perspective without a numpad",
+    probe: probe("5", { alt: true }),
+    action: "toggleWorkingOrtho",
+  },
+  {
+    group: "3D view",
+    combo: "Num/",
+    does: "Go inside the selection, and back out",
+    probe: probe("/", { code: "NumpadDivide" }),
+    action: "toggleIsolation",
+  },
+  {
+    group: "3D view",
+    combo: "Num+ / Num−",
+    does: "Zoom the active pane",
+    probe: probe("+", { code: "NumpadAdd" }),
+    action: "zoom",
+  },
+
+  {
+    group: "Edit",
+    combo: "Arrows",
+    does: "Nudge selection 1 px (⇧ = 10)",
+    probe: probe("ArrowRight"),
+    hasSelection: true,
+    action: "nudge",
+  },
+  {
+    group: "Edit",
+    combo: "← →",
+    does: "Move the selected keyframes 1 frame (⇧ = 10)",
+    probe: probe("ArrowRight"),
+    context: { hasKeyframeSelection: true },
+    action: "nudgeKeys",
+  },
+  {
+    group: "Edit",
+    combo: "⌘Z",
+    does: "Undo",
+    probe: probe("z", { ctrl: true }),
+    action: "undo",
+    menuId: "edit.undo",
+  },
+  {
+    group: "Edit",
+    combo: "⌘⇧Z",
+    does: "Redo",
+    probe: probe("z", { ctrl: true, shift: true }),
+    action: "redo",
+    menuId: "edit.redo",
+  },
+  // The OTHER redo, which every Windows editor binds and this one has always
+  // answered. It had no row, so the deleted docs table was the only place it
+  // was written down. No `menuId`: one menu row cannot print two accelerators,
+  // and ⌘⇧Z is the one it shows.
+  {
+    group: "Edit",
+    combo: "⌘Y",
+    does: "Redo (the other one)",
+    probe: probe("y", { ctrl: true }),
+    action: "redo",
+  },
+  {
+    group: "Edit",
+    combo: "⌘C",
+    does: "Copy the selected layers",
+    probe: probe("c", { ctrl: true }),
+    hasSelection: true,
+    action: "copyLayers",
+    menuId: "edit.copy",
+  },
+  {
+    group: "Edit",
+    combo: "⌘X",
+    does: "Cut the selected layers",
+    probe: probe("x", { ctrl: true }),
+    hasSelection: true,
+    action: "cutLayers",
+    menuId: "edit.cut",
+  },
+  {
+    group: "Edit",
+    combo: "⌘V",
+    does: "Paste the copied layers into their Shot",
+    probe: probe("v", { ctrl: true }),
+    context: { hasLayerClip: true },
+    action: "pasteLayers",
+    menuId: "edit.paste",
+  },
+  {
+    group: "Edit",
+    combo: "⌘C",
+    does: "Copy the selected keyframes",
+    probe: probe("c", { ctrl: true }),
+    context: { hasKeyframeSelection: true },
+    action: "copyKeyframes",
+  },
+  {
+    group: "Edit",
+    combo: "⌘V",
+    does: "Paste the copied keyframes at the playhead",
+    probe: probe("v", { ctrl: true }),
+    context: { hasKeyframeClip: true },
+    action: "pasteKeyframes",
+  },
+  {
+    group: "Edit",
+    combo: "⌘⌥C",
+    does: "Copy the selected layer's animation",
+    probe: probe("c", { ctrl: true, alt: true }),
+    // A Mac's Option composes the letter, so its probe carries the composed
+    // key and the `code` the keymap reads instead (`chordChar`).
+    mac: { combo: "⌥⌘C", probe: probe("ç", { meta: true, alt: true, code: "KeyC" }) },
+    // ⌥⌘C is also Chrome's View > Developer > Inspect Elements on a Mac. The
+    // page still gets the keydown first: Chromium's
+    // `BrowserCommandController::IsReservedCommandOrKey` reserves only the
+    // tab, window and quit commands (not `IDC_DEV_TOOLS_INSPECT`), so a
+    // claimed chord is `preventDefault`ed and Inspect never opens. With no
+    // layer selected the keymap leaves it to Chrome. Checked against the
+    // Chromium source (2026-10-12), not yet on Mac hardware: confirm there.
+    hasSelection: true,
+    action: "copyAnimation",
+    menuId: "edit.copyAnimation",
+  },
+  {
+    group: "Edit",
+    combo: "⌘⌥V",
+    does: "Paste the copied animation onto the selected layers, at the playhead",
+    probe: probe("v", { ctrl: true, alt: true }),
+    mac: { combo: "⌥⌘V", probe: probe("√", { meta: true, alt: true, code: "KeyV" }) },
+    hasSelection: true,
+    context: { hasAnimationClip: true },
+    action: "pasteAnimation",
+    menuId: "edit.pasteAnimation.playhead",
+  },
+  {
+    group: "Edit",
+    combo: "⌘⇧⌥C",
+    does: "Copy the selected layer's effects",
+    probe: probe("c", { ctrl: true, alt: true, shift: true }),
+    mac: { combo: "⇧⌥⌘C", probe: probe("Ç", { meta: true, alt: true, shift: true, code: "KeyC" }) },
+    hasSelection: true,
+    action: "copyEffects",
+    menuId: "edit.copyEffects",
+  },
+  {
+    group: "Edit",
+    combo: "⌘⇧⌥V",
+    does: "Paste the copied effects onto the selected layers",
+    probe: probe("v", { ctrl: true, alt: true, shift: true }),
+    mac: { combo: "⇧⌥⌘V", probe: probe("◊", { meta: true, alt: true, shift: true, code: "KeyV" }) },
+    hasSelection: true,
+    context: { hasEffectsClip: true },
+    action: "pasteEffects",
+    menuId: "edit.pasteEffects",
+  },
+  {
+    group: "Edit",
+    combo: "⌘S",
+    does: "Save a named version",
+    probe: probe("s", { ctrl: true }),
+    action: "save",
+    menuId: "file.save",
+  },
+  {
+    group: "Edit",
+    combo: "⌘D",
+    does: "Duplicate",
+    probe: probe("d", { ctrl: true }),
+    action: "duplicate",
+    menuId: "edit.duplicate",
+  },
+  {
+    group: "Edit",
+    combo: "⌘A",
+    does: "Select all, in the scope you are in",
+    probe: probe("a", { ctrl: true }),
+    action: "selectAll",
+    menuId: "edit.selectAll",
+  },
+  // Blender's bare A, the same verb through a second key. Split off ⌘A's row so
+  // that row's combo is one accelerator the menu can print; this one carries no
+  // id, because a row may name only one key.
+  {
+    group: "Edit",
+    combo: "A",
+    does: "Select all (Blender's key)",
+    probe: probe("a"),
+    action: "selectAll",
+  },
+  {
+    group: "Edit",
+    combo: "⌘⇧A",
+    does: "Deselect all",
+    probe: probe("a", { ctrl: true, shift: true }),
+    action: "deselect",
+    menuId: "edit.deselect",
+  },
+  {
+    group: "Edit",
+    combo: "B",
+    does: "Box select with the next drag",
+    probe: probe("b"),
+    action: "boxSelect",
+  },
+  {
+    group: "Edit",
+    combo: "⇧D",
+    does: "Duplicate",
+    probe: probe("d", { shift: true }),
+    action: "duplicate",
+  },
+  {
+    group: "Edit",
+    combo: "Esc",
+    does: "Deselect",
+    probe: probe("Escape"),
+    action: "deselect",
+  },
+  {
+    group: "Edit",
+    combo: "Del",
+    does: "Delete selection",
+    probe: probe("Delete"),
+    action: "deleteSelection",
+    menuId: "edit.delete",
+  },
+  {
+    group: "Edit",
+    combo: "⇧Backspace",
+    does: "Ripple delete: remove the layers and close the gap",
+    probe: probe("Backspace", { shift: true }),
+    action: "rippleDelete",
+  },
+  {
+    group: "Edit",
+    combo: "⌘G",
+    does: "Group",
+    probe: probe("g", { ctrl: true }),
+    action: "group",
+    menuId: "edit.group",
+  },
+  {
+    group: "Edit",
+    combo: "⌘⇧G",
+    does: "Ungroup",
+    probe: probe("g", { ctrl: true, shift: true }),
+    action: "ungroup",
+    menuId: "edit.ungroup",
+  },
+  // ── ARRANGE, Figma's bracket chords ─────────────────────────────────────
+  //
+  // Each layer among its own siblings, which is paint order (the layers panel
+  // lists them front first). The probes carry `code`, because the keymap keys
+  // on the physical key: Shift turns `]` into `}` and Option into a quote. The
+  // front and back rows split by platform (`mac`): ⌘⇧] and ⌘⇧[ are the Mac's
+  // tab switch and are never claimed.
+  {
+    group: "Edit",
+    combo: "⌘]",
+    does: "Bring forward, past one sibling",
+    probe: probe("]", { ctrl: true, code: "BracketRight" }),
+    action: "arrange",
+    menuId: "layout.arrange.forward",
+  },
+  {
+    group: "Edit",
+    combo: "⌘[",
+    does: "Send backward, past one sibling",
+    probe: probe("[", { ctrl: true, code: "BracketLeft" }),
+    action: "arrange",
+    menuId: "layout.arrange.backward",
+  },
+  {
+    group: "Edit",
+    combo: "⌘⇧]",
+    does: "Bring to front, among its siblings",
+    probe: probe("}", { ctrl: true, shift: true, code: "BracketRight" }),
+    mac: { combo: "⌥⌘]", probe: probe("‘", { meta: true, alt: true, code: "BracketRight" }) },
+    action: "arrange",
+    menuId: "layout.arrange.front",
+  },
+  {
+    group: "Edit",
+    combo: "⌘⇧[",
+    does: "Send to back, among its siblings",
+    probe: probe("{", { ctrl: true, shift: true, code: "BracketLeft" }),
+    mac: { combo: "⌥⌘[", probe: probe("“", { meta: true, alt: true, code: "BracketLeft" }) },
+    action: "arrange",
+    menuId: "layout.arrange.back",
+  },
+  {
+    group: "Edit",
+    combo: "⌥L",
+    does: "Lock / unlock",
+    probe: probe("l", { alt: true }),
+    action: "toggleLock",
+    menuId: "layer.lock",
+  },
+  {
+    group: "Edit",
+    combo: "H",
+    does: "Hide the selection",
+    probe: probe("h"),
+    action: "setHidden",
+    menuId: "layer.hide",
+  },
+  {
+    group: "Edit",
+    combo: "⌥⇧H",
+    does: "Hide everything else",
+    probe: probe("Ó", { alt: true, shift: true, code: "KeyH" }),
+    action: "setHidden",
+    menuId: "layer.hideOthers",
+  },
+  {
+    group: "Edit",
+    combo: "⌘⇧H",
+    does: "Show everything again",
+    probe: probe("h", { ctrl: true, shift: true }),
+    action: "setHidden",
+    menuId: "layer.reveal",
+  },
+  // ── ALIGN, ⌥ + A D W S H V ──────────────────────────────────────────────
+  //
+  // The words come from `ALIGN_LABELS`, the table the align grid and the
+  // Arrange menu already read. Each probe carries `code`: a Mac's Option
+  // composes the letter.
+  ...(
+    [
+      ["left", "A"],
+      ["right", "D"],
+      ["top", "W"],
+      ["bottom", "S"],
+      ["hcenter", "H"],
+      ["vcenter", "V"],
+    ] as const
+  ).map(
+    ([mode, letter]): ShortcutRow => ({
+      group: "Edit",
+      combo: `⌥${letter}`,
+      does: ALIGN_LABELS[mode],
+      probe: probe(letter.toLowerCase(), { alt: true, code: `Key${letter}` }),
+      action: "align",
+      menuId: `layout.align.${mode}`,
+    }),
+  ),
+  // ── OPACITY ON THE BARE DIGITS ──────────────────────────────────────────
+  //
+  // One row for the tenths and one for 0, the Help sheet's two lines. Neither
+  // has a menu id: a row may name only one key.
+  {
+    group: "Edit",
+    combo: "1 to 9",
+    does: "Opacity 10% to 90%",
+    probe: probe("5", { code: "Digit5" }),
+    hasSelection: true,
+    action: "opacity",
+  },
+  {
+    group: "Edit",
+    combo: "0",
+    does: "Opacity 100%",
+    probe: probe("0", { code: "Digit0" }),
+    hasSelection: true,
+    action: "opacity",
+  },
+  {
+    group: "Edit",
+    combo: "Q",
+    does: "Trim the start to the playhead",
+    probe: probe("q"),
+    hasSelection: true,
+    action: "trimToPlayhead",
+    menuId: "layer.trim.in",
+  },
+  {
+    group: "Edit",
+    combo: "W",
+    does: "Trim the end to the playhead (keeps that frame)",
+    probe: probe("w"),
+    hasSelection: true,
+    action: "trimToPlayhead",
+    menuId: "layer.trim.out",
+  },
+  {
+    group: "Edit",
+    combo: "⇧H",
+    does: "Flip horizontal",
+    probe: probe("H", { shift: true, code: "KeyH" }),
+    hasSelection: true,
+    action: "flip",
+    menuId: "layer.flip.x",
+  },
+  {
+    group: "Edit",
+    combo: "⇧V",
+    does: "Flip vertical",
+    probe: probe("V", { shift: true, code: "KeyV" }),
+    hasSelection: true,
+    action: "flip",
+    menuId: "layer.flip.y",
+  },
+  // SPLIT INTO TWO from one "⌥G / ⌥R" line, for the layout digits' reason: the
+  // Layer ▸ Clear rows name one channel each.
+  {
+    group: "Edit",
+    combo: "⌥G",
+    does: "Clear the position",
+    probe: probe("g", { alt: true }),
+    action: "clearTransform",
+    menuId: "layer.clear.position",
+  },
+  {
+    group: "Edit",
+    combo: "⌥R",
+    does: "Clear the rotation",
+    probe: probe("r", { alt: true }),
+    action: "clearTransform",
+    menuId: "layer.clear.rotation",
+  },
+  // The third channel. It was live in `keymap.ts` with no row here, so the only
+  // place it was written down was the hand-kept table in docs/shot.md, and
+  // deleting that table left a working key documented nowhere. No `menuId`:
+  // the Layer ▸ Clear submenu carries position and rotation only.
+  {
+    group: "Edit",
+    combo: "⌥⇧S",
+    does: "Clear the size",
+    probe: probe("S", { alt: true, shift: true, code: "KeyS" }),
+    action: "clearTransform",
+  },
+  {
+    group: "Edit",
+    combo: "Enter",
+    does: "Edit inside the selection",
+    probe: probe("Enter"),
+    hasSelection: true,
+    action: "enterIsolation",
+    menuId: "layer.isolate",
+  },
+  {
+    group: "Edit",
+    combo: "Esc",
+    does: "Come back out one level",
+    probe: probe("Escape"),
+    isolation: true,
+    action: "exitIsolation",
+    menuId: "layer.isolate.exit",
+  },
+  // The rest of Escape's ladder, one level per press with nothing selected.
+  {
+    group: "Edit",
+    combo: "Esc",
+    does: "Back to the Shot you opened the component from",
+    probe: probe("Escape"),
+    context: { editingDef: true, componentsOrigin: true },
+    action: "backToShot",
+  },
+  {
+    group: "Edit",
+    combo: "Esc",
+    does: "Leave the component",
+    probe: probe("Escape"),
+    context: { editingDef: true },
+    action: "closeComponentContext",
+  },
+  {
+    group: "Edit",
+    combo: "Esc",
+    does: "Leave the code component",
+    probe: probe("Escape"),
+    context: { codeComponent: true },
+    action: "closeCodeComponent",
+  },
+  {
+    group: "Edit",
+    combo: "Esc",
+    does: "Leave Components",
+    probe: probe("Escape"),
+    context: { componentsOpen: true },
+    action: "leaveComponents",
+  },
+  {
+    group: "Edit",
+    combo: "Esc",
+    does: "Leave the Shot, back to all Shots",
+    probe: probe("Escape"),
+    context: { enteredScene: true },
+    action: "leaveScene",
+  },
+  {
+    group: "Edit",
+    combo: "Enter",
+    does: "Finish the path you are drawing",
+    probe: probe("Enter"),
+    penActive: true,
+    action: "penCommit",
+  },
+  {
+    group: "Edit",
+    combo: "Esc",
+    does: "Throw away the path you are drawing",
+    probe: probe("Escape"),
+    penActive: true,
+    action: "penAbandon",
+  },
+
+  {
+    group: "Animate & camera",
+    combo: "⇧A",
+    does: "Animate: edits write keyframes at the playhead",
+    probe: probe("a", { shift: true }),
+    action: "animateToggle",
+    menuId: "tool.animate",
+  },
+  {
+    group: "Animate & camera",
+    combo: "M",
+    does: "Drop a marker at the playhead",
+    probe: probe("m"),
+    action: "addMarker",
+    menuId: "time.marker.add",
+  },
+  {
+    group: "Animate & camera",
+    combo: "⌥C",
+    does: cameraVerb("toView").sentence,
+    probe: probe("c", { alt: true }),
+    action: "alignCameraToView",
+    menuId: cameraVerb("toView").menuId,
+  },
+  {
+    group: "Animate & camera",
+    combo: "⌘B",
+    does: "Split the layers under the playhead",
+    probe: probe("b", { ctrl: true }),
+    action: "splitAtPlayhead",
+    menuId: "edit.split",
+  },
+  {
+    group: "Animate & camera",
+    combo: "⌘⇧B",
+    does: "Split the shot at the playhead",
+    probe: probe("b", { ctrl: true, shift: true }),
+    action: "splitSceneAtPlayhead",
+  },
+  {
+    group: "Animate & camera",
+    combo: "⌘E",
+    does: "Export video",
+    probe: probe("e", { ctrl: true }),
+    action: "openExport",
+    menuId: "file.export",
+  },
+  // In "View" would be truer, and it is here because the manual's four groups
+  // are about the DOCUMENT and this one is about the chrome. It is last in the
+  // table so it reads as the outlier it is.
+  {
+    group: "View",
+    combo: "⌘K",
+    does: "Open the menu, ready to search",
+    probe: probe("k", { ctrl: true }),
+    action: "appMenu",
+    menuId: "app.menu",
+  },
+  {
+    group: "View",
+    combo: "⌘,",
+    does: "Open Preferences",
+    probe: probe(",", { ctrl: true }),
+    action: "openPrefs",
+    menuId: "prefs.open",
+  },
+  // The key the left column's search field shows as its hint, so the hint and
+  // the manual are one claim with one test behind it.
+  {
+    group: "View",
+    combo: "/",
+    does: "Search the left column",
+    probe: probe("/", { code: "Slash" }),
+    action: "focusSearch",
+  },
+];
+
+/**
+ * THE MATERIAL GRAPH'S BINDINGS, in a table of their own.
+ *
+ * ── WHY THEY ARE NOT ROWS OF `SHORTCUTS` ────────────────────────────────
+ *
+ * Every row of that table is walked through `resolveKey` with one fixed
+ * context, and these twelve answer their action ONLY with `materialGraph:
+ * true` — outside the canvas ⌘D duplicates a layer, Delete deletes the mesh
+ * and `F` arms a tool. Folded into the main table, each row would need the
+ * context bit set and the manual would print a key beside a sentence that is
+ * true in one place and false everywhere else.
+ *
+ * So: a second table, the same `ShortcutRow` shape, the same test treatment
+ * (see test/materialKeymap.test.ts), and `shortcutFor` indexes both — which is
+ * what lets the node right-click menu print an accelerator without typing one.
+ */
+/** The board's own lane, walked by test/storyboardKeymap.test.ts the way the
+ *  material rows are: every one means something else outside the board. The
+ *  two `storyboardCards` rows say they need a card selected. */
+export const STORYBOARD_SHORTCUTS: readonly ShortcutRow[] = [
+  {
+    group: "Storyboard",
+    combo: "Del",
+    does: "Delete the selected cards",
+    probe: probe("Delete"),
+    storyboard: true,
+    action: "storyboardDelete",
+  },
+  {
+    group: "Storyboard",
+    combo: "C",
+    does: "Comment on the selected card",
+    probe: probe("c"),
+    storyboard: true,
+    action: "storyboardComment",
+  },
+  {
+    group: "Storyboard",
+    combo: "N",
+    does: "Next open comment",
+    probe: probe("n"),
+    storyboard: true,
+    action: "storyboardNextThread",
+  },
+  {
+    group: "Storyboard",
+    combo: "⇧N",
+    does: "Previous open comment",
+    probe: probe("n", { shift: true }),
+    storyboard: true,
+    action: "storyboardPrevThread",
+  },
+  {
+    group: "Storyboard",
+    combo: "⌘A",
+    does: "Select every card",
+    probe: probe("a", { ctrl: true }),
+    storyboard: true,
+    action: "storyboardSelectAll",
+  },
+  {
+    group: "Storyboard",
+    combo: "⌘D",
+    does: "Duplicate the selected cards",
+    probe: probe("d", { ctrl: true }),
+    storyboard: true,
+    action: "storyboardDuplicate",
+  },
+  {
+    group: "Storyboard",
+    combo: "F2",
+    does: "Rename the selected planned shot",
+    probe: probe("F2"),
+    storyboard: true,
+    action: "storyboardRename",
+  },
+  // ── THE THREE CLIPBOARD ROWS ─────────────────────────────────────────────
+  //
+  // Documented here so the combos appear in the shortcut sheet, and resolving
+  // to an arm that returns FALSE so behaviour is byte-identical to leaving
+  // them unbound. The
+  // work is done by native document handlers in StoryboardView.tsx, because binding
+  // these for real would `preventDefault` the keydown, cancel the browser's
+  // own paste event, and silently take away pasting an image FILE onto the
+  // board. See `storyboardClipboard` in keymap.ts.
+  {
+    group: "Storyboard",
+    combo: "⌘C",
+    does: "Copy the selection",
+    probe: probe("c", { ctrl: true }),
+    storyboard: true,
+    action: "storyboardClipboard",
+  },
+  {
+    group: "Storyboard",
+    combo: "⌘X",
+    does: "Cut the selection",
+    probe: probe("x", { ctrl: true }),
+    storyboard: true,
+    action: "storyboardClipboard",
+  },
+  {
+    group: "Storyboard",
+    combo: "⌘V",
+    does: "Paste, including an image or video from the system clipboard",
+    probe: probe("v", { ctrl: true }),
+    storyboard: true,
+    action: "storyboardClipboard",
+  },
+  {
+    group: "Storyboard",
+    combo: "Esc",
+    does: "Clear the board selection, then the layer selection",
+    probe: probe("Escape"),
+    storyboard: true,
+    action: "storyboardEscape",
+  },
+  {
+    group: "Storyboard",
+    combo: "⇧S",
+    does: "Close the Storyboard",
+    probe: probe("s", { shift: true }),
+    storyboard: true,
+    action: "storyboardToggle",
+  },
+  // ── A SHOT BOARD'S SKETCH KEYS ───────────────────────────────────────────
+  //
+  // Answered by `resolveShotBoardKey` on the shot board's own element
+  // (ShotBoard.tsx), so each row says `shotBoard`. Bare C arms the Component
+  // tool there; on the whole board it still comments.
+  sketchRow("Arrows", "Move the selected sketch items 1px", probe("ArrowRight"), "sketchMove"),
+  sketchRow("⇧ Arrows", "Move the selected sketch items 10px", probe("ArrowRight", { shift: true }), "sketchMove"),
+  sketchRow("[", "Send the selected sketch item back one step", probe("["), "sketchRestack"),
+  sketchRow("]", "Bring the selected sketch item forward one step", probe("]"), "sketchRestack"),
+  sketchRow("Enter", "Edit the selected text on a sketch", probe("Enter"), "sketchEdit"),
+  sketchRow("V", "Sketch: Select", probe("v"), "sketchTool"),
+  sketchRow("T", "Sketch: Text", probe("t"), "sketchTool"),
+  sketchRow("R", "Sketch: Box", probe("r"), "sketchTool"),
+  sketchRow("A", "Sketch: Arrow", probe("a"), "sketchTool"),
+  sketchRow("I", "Sketch: add an image", probe("i"), "sketchTool"),
+  sketchRow("C", "Sketch: add a component", probe("c"), "sketchTool"),
+];
+
+/** One shot board row. */
+function sketchRow(combo: string, does: string, at: KeyEventLike, action: SketchKeyAction["kind"]): ShortcutRow {
+  return { group: "Storyboard", combo, does, probe: at, storyboard: true, shotBoard: true, action };
+}
+
+export const MATERIAL_SHORTCUTS: readonly ShortcutRow[] = [
+  {
+    group: "Material nodes",
+    combo: "Tab",
+    does: "Open the node palette",
+    probe: probe("Tab"),
+    materialGraph: true,
+    action: "graphPalette",
+    menuId: "graph.add",
+  },
+  {
+    group: "Material nodes",
+    combo: "⇧A",
+    does: "Open the node palette (Blender's Add)",
+    probe: probe("a", { shift: true }),
+    materialGraph: true,
+    action: "graphPalette",
+  },
+  {
+    group: "Material nodes",
+    combo: "⌘D",
+    does: "Duplicate the selected nodes",
+    probe: probe("d", { ctrl: true }),
+    materialGraph: true,
+    action: "graphDuplicate",
+    menuId: "graph.duplicate",
+  },
+  {
+    group: "Material nodes",
+    combo: "⇧D",
+    does: "Duplicate the selected nodes",
+    probe: probe("d", { shift: true }),
+    materialGraph: true,
+    action: "graphDuplicate",
+  },
+  {
+    group: "Material nodes",
+    combo: "⌘C",
+    does: "Copy the selected nodes",
+    probe: probe("c", { ctrl: true }),
+    materialGraph: true,
+    action: "graphCopy",
+    menuId: "graph.copy",
+  },
+  {
+    group: "Material nodes",
+    combo: "⌘X",
+    does: "Cut the selected nodes",
+    probe: probe("x", { ctrl: true }),
+    materialGraph: true,
+    action: "graphCut",
+    menuId: "graph.cut",
+  },
+  {
+    group: "Material nodes",
+    combo: "⌘V",
+    does: "Paste nodes",
+    probe: probe("v", { ctrl: true }),
+    materialGraph: true,
+    action: "graphPaste",
+    menuId: "graph.paste",
+  },
+  {
+    group: "Material nodes",
+    combo: "⌘A",
+    does: "Select every node in this scope",
+    probe: probe("a", { ctrl: true }),
+    materialGraph: true,
+    action: "graphSelectAll",
+  },
+  {
+    group: "Material nodes",
+    combo: "⌘G",
+    does: "Box the selected nodes into a group",
+    probe: probe("g", { ctrl: true }),
+    materialGraph: true,
+    action: "graphGroup",
+    menuId: "graph.group",
+  },
+  {
+    group: "Material nodes",
+    combo: "⌘⇧G",
+    does: "Take the group box away",
+    probe: probe("g", { ctrl: true, shift: true }),
+    materialGraph: true,
+    action: "graphUngroup",
+    menuId: "graph.ungroup",
+  },
+  {
+    group: "Material nodes",
+    combo: "Enter",
+    does: "Open the selected subgraph",
+    probe: probe("Enter"),
+    materialGraph: true,
+    action: "graphEnter",
+    menuId: "graph.enter",
+  },
+  {
+    group: "Material nodes",
+    combo: "P",
+    does: "Show / hide the preview on the selected cards",
+    probe: probe("p"),
+    materialGraph: true,
+    action: "graphPreviewToggle",
+    menuId: "graph.preview",
+  },
+  {
+    group: "Material nodes",
+    combo: "Home",
+    does: "Fit the whole graph",
+    probe: probe("Home"),
+    materialGraph: true,
+    action: "graphFrame",
+  },
+  {
+    group: "Material nodes",
+    combo: "F",
+    does: "Fit the whole graph",
+    probe: probe("f"),
+    materialGraph: true,
+    action: "graphFrame",
+  },
+  {
+    group: "Material nodes",
+    combo: "T",
+    does: "Tidy the graph, or just the selection",
+    probe: probe("t"),
+    materialGraph: true,
+    action: "graphTidy",
+    menuId: "graph.tidy",
+  },
+  {
+    group: "Material nodes",
+    combo: "Arrows",
+    does: "Nudge the selected nodes 8 px (⇧ = 80)",
+    probe: probe("ArrowRight"),
+    materialGraph: true,
+    action: "graphNudge",
+  },
+  {
+    group: "Material nodes",
+    combo: "Del",
+    does: "Delete the selected nodes and wires",
+    probe: probe("Delete"),
+    materialGraph: true,
+    action: "graphDelete",
+    menuId: "graph.delete",
+  },
+  {
+    group: "Material nodes",
+    combo: "Esc",
+    does: "Close the palette, then the selection, then one subgraph level, then the editor",
+    probe: probe("Escape"),
+    materialGraph: true,
+    action: "graphEscape",
+  },
+];
+
+/** By menu id, over BOTH tables: a node menu row prints its accelerator the
+ *  same way a layer menu row does. Built once — both tables are constants.
+ *  The storyboard rows name no menu row, so they are not indexed. */
+const BY_MENU_ID: ReadonlyMap<string, ShortcutRow> = new Map(
+  [...SHORTCUTS, ...MATERIAL_SHORTCUTS].flatMap((row) =>
+    row.menuId === undefined ? [] : [[row.menuId, row] as const],
+  ),
+);
+
+/**
+ * Is this a Mac? Read ONCE — the platform does not change mid-session, and a
+ * per-render probe would put a `navigator` touch inside every menu build.
+ *
+ * `navigator.platform` is deprecated but it is the only synchronous answer that
+ * works in a plain iframe, and a wrong guess here costs a glyph rather than a
+ * behaviour. Anything that is not a Mac gets the Windows/Linux spelling, which
+ * is the right default for the one that is not a Mac.
+ */
+const IS_MAC =
+  typeof navigator !== "undefined" &&
+  /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? "");
+
+/**
+ * A combo in the spelling THIS machine's keyboard uses.
+ *
+ * THE PLATFORM BRANCH THE OLD COMMENT PROMISED. It used to say there was none,
+ * deliberately, and that the whole chrome should take it at once or not at all —
+ * because a menu printing `Ctrl+Z` beside a manual printing ⌘Z is a second
+ * vocabulary for one key rather than a fix. That was right, and this is the
+ * "at once": both readers, the menus through `shortcutFor` and the manual
+ * through `HelpSection`, come through here, and the manual's footnote about ⌘
+ * meaning Ctrl is gone because the table now says Ctrl itself.
+ *
+ * The glyphs stay the authored form in `SHORTCUTS`, so there is still exactly
+ * one place a combo is written down. This is a rendering step, not a fork.
+ *
+ * A glyph NOT followed by a key is prose (`"⌘ and a click"`), so it becomes the
+ * bare word rather than a dangling `Ctrl+`.
+ */
+export function formatCombo(combo: string, mac: boolean = IS_MAC): string {
+  if (mac) return combo;
+  return combo
+    .replace(/⌘(?=\S)/g, "Ctrl+")
+    .replace(/⌘/g, "Ctrl")
+    .replace(/⇧(?=\S)/g, "Shift+")
+    .replace(/⇧/g, "Shift")
+    .replace(/⌥(?=\S)/g, "Alt+")
+    .replace(/⌥/g, "Alt");
+}
+
+/** The key that arms a tool, in this machine's spelling ("R", "⇧L" on a Mac,
+ *  "Shift+L" elsewhere), or null for a tool with no binding. */
+export function toolKey(t: ShotTool, mac: boolean = IS_MAC): string | null {
+  const spec = specOf(t);
+  return spec.key === null ? null : formatCombo(`${spec.shift === true ? "⇧" : ""}${spec.key.toUpperCase()}`, mac);
+}
+
+/**
+ * A row's chord in this machine's spelling: its own `mac` chord on a Mac when
+ * it has one (the keys differ there, not only the glyphs), `combo` otherwise.
+ * Every reader goes through here, so the menus and the manual agree.
+ */
+export function comboOf(row: ShortcutRow, mac: boolean = IS_MAC): string {
+  return mac && row.mac !== undefined ? row.mac.combo : formatCombo(row.combo, mac);
+}
+
+/** The combo string for a menu row, in this machine's spelling. */
+export function shortcutFor(menuId: string): string | undefined {
+  const row = BY_MENU_ID.get(menuId);
+  return row === undefined ? undefined : comboOf(row);
+}
+
+/**
+ * The combo for an ACTION, in this machine's spelling, for a refusal that has
+ * to name a key.
+ *
+ * `shortcutFor` cannot answer it: a binding only has a menu id when a menu row
+ * prints it, and the one caller here is a sentence rather than a row. Typing
+ * the glyphs into that sentence instead would be a second place a combo is
+ * written down, which this file's header exists to prevent, and a sentence is
+ * the surface least likely to be found when the key moves.
+ *
+ * The FIRST row claiming the action, which is the only row for every action a
+ * refusal names today. A second row on one action would be an alias, and an
+ * alias's first spelling is the one to teach.
+ */
+export function comboForAction(action: KeyAction["kind"]): string | undefined {
+  const row = SHORTCUTS.find((r) => r.action === action);
+  return row === undefined ? undefined : comboOf(row);
+}
+
+/**
+ * A `title=` suffix: " (Ctrl+Z)", or "" for a row with no binding.
+ *
+ * Here rather than in each toolbar, because every header control was writing
+ * the same three lines and several had skipped them entirely in favour of a
+ * literal "⌘Z" — which is the wrong spelling on every Windows machine the
+ * editor runs on. An UNBOUND row returning "" is the point: the timeline
+ * toggle has no key, and the caller should not have to know that.
+ */
+export function shortcutHint(menuId: string): string {
+  const combo = shortcutFor(menuId);
+  return combo === undefined ? "" : ` (${combo})`;
+}
+
+/**
+ * The exact event a menu row's key produces, for the handful of rows whose verb
+ * lives INSIDE `handleKey` and nowhere else.
+ *
+ * ── WHY A MENU ROW WOULD EVER SYNTHESISE A KEY ──────────────────────────
+ *
+ * `state/menu.ts`'s rule is that every entry calls an existing store verb, so a
+ * menu can never be a second implementation of an edit. Six actions have no
+ * verb to call: the scoped hide triple (⌥⇧H / ⌘⇧H reach for `relativesOf` and the
+ * isolation scope), the two clear-transform channels, and the zoom reset. Each
+ * is a thirty-line arm of `handleKey`'s switch, and copying one into a menu
+ * builder is exactly the second implementation the rule exists to prevent.
+ *
+ * `store.handleKey(probe)` is not a second binding site — it is a call INTO the
+ * one that exists, with the event that key produces. The arm derives its own
+ * context from state, so the menu row refuses for the same reasons and with the
+ * same sentence the key does. `resolveKey` reads `editing` off `event.target`,
+ * which a probe does not carry, so `isEditable(null)` is false and the call can
+ * never be swallowed by the field the author is typing in.
+ *
+ * Prefer a verb wherever one exists. This is for the rows where none does.
+ */
+export function probeFor(menuId: string): KeyEventLike | undefined {
+  return BY_MENU_ID.get(menuId)?.probe;
+}