@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/keymap.ts

@@ -27,23 +27,38 @@
 //
 //   ARROWS are listed as both "nudge the playhead" and "nudge the layer".
 //     SELECTION WINS; an empty selection falls through to the playhead. That is
-//     the only reading where both are reachable without a mode.
+//     the only reading where both are reachable without a mode. The playhead
+//     half then forks three ways — ⇧ is a second, ↑/↓ walk the edit points, and
+//     ←/→ step a frame — because the vertical pair was otherwise a second
+//     spelling of the horizontal one.
 //
 //   `C` was listed as both the cut tool and split-at-playhead. THE CUT TOOL IS
 //     GONE — it was a fourteenth row in the tool table that split a scene under
-//     the cursor, which `⌘B` already does from the playhead with no mode to
-//     arm and no mode to leave. `⌘B` is now the only splitter, and `⇧C` is
-//     Blender's "frame all" rather than the camera-move it used to be (the
-//     `+ shot` button owns that, via `store.addShotAtPlayhead`).
+//     the cursor, which `⌘⇧B` now does from the playhead with no mode to arm
+//     and no mode to leave. The splitters are `⌘B` (the razor, over the layers
+//     under the playhead) and `⌘⇧B` (the shot itself), and no letter arms
+//     either. `⇧C` is Blender's "frame all" rather than the camera-move it used
+//     to be (the `+ shot` button owns that, via `store.addShotAtPlayhead`).
 //
 //   SPACE is both play/pause and hold-to-pan. It fires on KEYUP, and only when
 //     no pan drag happened during the hold — which is why the stage owns the
 //     suppression (it is the half that knows) and the chrome, which cannot pan,
 //     always fires.
-import { toolForKey } from "../tools.js";
+import { isInsertTool, specOf, toolForKey } from "../tools.js";
 import type { ShotTool } from "../tools.js";
 import type { StageLayout } from "../stage/panes.js";
+// The layout table: the digit each of the three answers to, the words that name
+// one inside a sentence, and the tail both pane refusals below share with the
+// View menu and the segmented control.
+import { layoutForEvent, layoutSpec, paneOnlyRefusal } from "./layouts.js";
+import { formatCombo } from "./shortcuts.js";
+// The digit for Video, from the same table the bar and the menu row read.
+import { VIEW_MODE_SPECS } from "./viewMode.js";
+import { VIEW_ONLY } from "./workspace.js";
+import type { ViewMode } from "./viewMode.js";
+import type { SketchTool } from "./types.js";
 import { ORBIT_STEP_DEG } from "../stage/workingView.js";
+import type { AlignMode, FlipAxis, RestackTarget } from "@dailies-studio/shot/doc";
 
 export type KeyAction =
   | { kind: "tool"; tool: ShotTool }
@@ -51,10 +66,42 @@ export type KeyAction =
   | { kind: "redo" }
   | { kind: "save" }
   | { kind: "playToggle" }
+  /**
+   * SHUTTLE: one rung along `SHUTTLE_RATES`, and run.
+   *
+   * `dir` is which way along the LADDER, never which way the picture goes: from
+   * −2 a `+1` is −1, which is still reverse and slower. The store owns the
+   * ladder because the rung depends on the rate the transport is already at,
+   * which this table deliberately does not take.
+   */
+  | { kind: "shuttle"; dir: -1 | 1 }
+  /** Stop, and put the rate back to 1. NOT `playToggle`: an author leaning on K
+   *  means "stop", and a toggle would start the transport again on the second
+   *  press of a key whose whole job is to end a shuttle. */
+  | { kind: "shuttleStop" }
   /** Move the playhead by whole frames. */
   | { kind: "step"; delta: number }
+  /** Move the playhead by whole SECONDS. Its own action and not a `step` with a
+   *  bigger delta, because this table cannot know the fps: a second is
+   *  `doc.fps` frames, and inventing a number here would be a second opinion on
+   *  the document's own rate. `delta` is ±1 second. */
+  | { kind: "stepSeconds"; delta: -1 | 1 }
+  /** The playhead to the previous / next EDIT POINT: a shot boundary, a layer's
+   *  lifespan edge, or a marker. The three places something in the film
+   *  actually changes, which is what an author scanning a cut is looking for. */
+  | { kind: "jumpEdit"; dir: -1 | 1 }
+  /** The playhead to the selection's own in or out point. */
+  | { kind: "seekSelectionEdge"; edge: "in" | "out" }
+  /** Put one edge of the work area at the playhead. */
+  | { kind: "setWorkArea"; edge: "in" | "out" }
+  /** Drop the work area: playback goes back to looping the whole document. */
+  | { kind: "clearWorkArea" }
   /** Move the selection, in design px. */
   | { kind: "nudge"; dx: number; dy: number }
+  | { kind: "nudgeKeys"; delta: number }
+  | { kind: "jumpKeyframe"; dir: -1 | 1 }
+  | { kind: "copyKeyframes" }
+  | { kind: "pasteKeyframes" }
   | { kind: "fit" }
   /** Fit the whole document across the timeline dock. A SECOND fit and not an
    *  arm of the first: `⇧Z` addresses the active stage pane, and the dock is
@@ -62,28 +109,84 @@ export type KeyAction =
   | { kind: "fitTimeline" }
   | { kind: "zoom"; direction: 1 | -1 }
   | { kind: "zoomReset" }
-  /** How many panes the stage shows. `toggle` means "…and back again if that
-   *  is where we already are", which is what numpad-0 needs and what the
-   *  1 / 2 / 3 row deliberately does NOT: pressing 2 twice must not leave the
-   *  split. */
+  /** WHICH EDITOR the stage shows, and over how much of it. `toggle` means
+   *  "…and back again if that is where we already are", which is what numpad-0
+   *  needs and what the ⇧1 / ⇧2 / ⇧3 row deliberately does NOT: pressing ⇧2
+   *  twice must not leave the split. Asking for any of the three also ends a
+   *  screening. See `setViewLayout`. */
   | { kind: "stageLayout"; mode: StageLayout["mode"]; toggle?: boolean }
+  /** WATCHING OR WORKING: ⇧4 goes to the finished picture, Escape's top rung
+   *  comes back. Not a layout. It is drawn OVER whichever of the three the
+   *  author left, and hands it back untouched. */
+  | { kind: "viewMode"; mode: ViewMode }
   /** Point the shot camera where the working pane is looking. */
   | { kind: "alignCameraToView" }
+  /** PILOT the shot camera from the Camera pane, or stop: Num0. Blender's
+   *  numpad-0 looks through the camera; ours also puts the author's hand on
+   *  it, and the badge over the pane with its ESC is what keeps that honest. */
+  | { kind: "pilotToggle" }
+  /** Escape's first rung while piloting: hands are off the camera, which stays
+   *  where it is. */
+  | { kind: "pilotEject" }
   /** Drop a marker at the playhead. */
   | { kind: "addMarker" }
   /** Hide a side rail, or every panel at once. */
   | { kind: "togglePanel"; panel: "rail" | "inspector" | "all" }
+  /**
+   * Open the app menu, with its search field focused.
+   *
+   * The only action in this table whose effect is CHROME rather than document or
+   * workspace state, which is why the store answers it by parking a mailbox
+   * (`appMenu`) rather than by doing anything: a keydown listener on the window
+   * cannot reach a component's popover, and a second listener inside that
+   * component is the thing this file's header forbids.
+   */
+  | { kind: "appMenu" }
+  /** Put the caret in the left column's search box. A mailbox for `appMenu`'s
+   *  reason: only the panel holds the input. */
+  | { kind: "focusSearch" }
   | { kind: "animateToggle" }
   | { kind: "openExport" }
   | { kind: "deleteSelection" }
+  /** Delete the selected layers AND pull everything after them back, closing
+   *  the gap they leave. Its own action and not a flag on `deleteSelection`,
+   *  because plain delete leaving a gap is the deliberate answer: a gap shows
+   *  the scene background, which is a picture in this product. */
+  | { kind: "rippleDelete" }
   | { kind: "duplicate" }
+  /** The selected layers onto the layer clip (`store.copyLayers`), and the
+   *  same plus a delete; the paste lands copies in their Shot. */
+  | { kind: "copyLayers" }
+  | { kind: "cutLayers" }
+  | { kind: "pasteLayers" }
+  /** The motion clip (`store.copyAnimation` / `copyEffects`) and its pastes
+   *  onto the selection. Animation pastes at the playhead from the keyboard;
+   *  "At original time" is a menu row only. */
+  | { kind: "copyAnimation" }
+  | { kind: "pasteAnimation" }
+  | { kind: "copyEffects" }
+  | { kind: "pasteEffects" }
   | { kind: "selectAll" }
   | { kind: "deselect" }
+  /** THE RAZOR: cut the layers under the playhead. See `store.splitAtPlayhead`
+   *  for the subject ladder it walks. */
   | { kind: "splitAtPlayhead" }
+  /** Cut the SHOT in two at the playhead. A separate verb and a separate key
+   *  because it is a different subject, not a different mode of the razor: one
+   *  cuts content inside a shot, the other cuts the shot itself and moves every
+   *  master frame after it. */
+  | { kind: "splitSceneAtPlayhead" }
   | { kind: "group" }
   | { kind: "ungroup" }
+  /** ARRANGE the selection (`store.restack`): each layer among its own
+   *  siblings, which is paint order. The bracket chords, see `arrangeChord`. */
+  | { kind: "arrange"; to: RestackTarget }
+  /** An Arrange chord over the storyboard or the material graph, CLAIMED and
+   *  dropped: nothing there stacks, and the layer selection under the canvas
+   *  is not the subject (the lanes' own rule), but on a Mac ⌘[ and ⌘] would
+   *  otherwise be the browser's Back and Forward, out of the editor. */
+  | { kind: "arrangeNowhere" }
   | { kind: "toggleLock" }
-  | { kind: "toggleHidden" }
   /** Finish the path the pen is drawing, keeping it. */
   | { kind: "penCommit" }
   /** Throw away the path the pen is drawing. */
@@ -92,13 +195,25 @@ export type KeyAction =
   | { kind: "enterIsolation" }
   /** Come back up ONE level. */
   | { kind: "exitIsolation" }
+  /** Back to the Shot a door into Components came from: its Shot, frame and
+   *  selection. The bar's "Back to Shot" makes the same move by click. */
+  | { kind: "backToShot" }
+  | { kind: "closeComponentContext" }
+  /** Leave the code studio. The panel owns the confirm when the buffer is
+   *  dirty, because only the panel can ask. */
+  | { kind: "closeCodeComponent" }
+  /** Leave Components while it shows no component (its empty state). */
+  | { kind: "leaveComponents" }
+  /** Back out of the entered shot, to the scene context. */
+  | { kind: "leaveScene" }
   /** Begin a Blender-style modal transform in the working pane. The stage
    *  decides the TARGET (selection = layers, empty = the camera); the action
    *  only carries which transform the letter named. */
   | { kind: "modalStart"; mode: "move" | "rotate" | "scale" }
-  /** Constrain the live modal transform to one axis; the same axis again
-   *  clears it (the reducer owns that toggle, not this table). */
-  | { kind: "modalAxis"; axis: "x" | "y" | "z" }
+  /** Constrain the live modal transform to one axis — or, with `plane`, to the
+   *  PLANE normal to it (Blender's `⇧X`). The same constraint again clears it
+   *  (the reducer owns that toggle, not this table). */
+  | { kind: "modalAxis"; axis: "x" | "y" | "z"; plane: boolean }
   /** One character typed into the live transform's numeric buffer: a digit, a
    *  decimal point, or `-` to flip the sign (Blender's own rule). `G X 200
    *  Enter` is what this exists for. */
@@ -133,15 +248,110 @@ export type KeyAction =
   /**
    * Hide explicitly, rather than toggling `selection[0]`'s own flag.
    *
-   * `"selection"` hides what is selected, `"others"` hides everything else
-   * (⇧H), `"reveal"` unhides the whole scene (⌥H). The toggle had no way back
+   * `"selection"` hides what is selected (H), `"others"` hides everything else
+   * (⌥⇧H), `"reveal"` unhides the whole scene (⌘⇧H). The toggle had no way back
    * once the hidden layers were deselected, which is most of the time.
    */
   | { kind: "setHidden"; scope: "selection" | "others" | "reveal" }
-  /** ⌥G / ⌥R / ⌥S: back to the layer's own zero on one channel. */
+  /** ⌥G / ⌥R / ⌥⇧S: back to the layer's own zero on one channel. */
   | { kind: "clearTransform"; channel: "offset" | "rotation" | "scale" }
+  /** ⌥A / ⌥D / ⌥W / ⌥S / ⌥H / ⌥V: the six alignments (`store.alignSelection`). */
+  | { kind: "align"; mode: AlignMode }
+  /** A bare digit with a selection: opacity in tenths, and 0 is full. */
+  | { kind: "opacity"; value: number }
+  /** Q / W: trim the selection's in or out point to the playhead. W keeps the
+   *  playhead's own frame, so the out lands one past it. */
+  | { kind: "trimToPlayhead"; edge: "in" | "out" }
+  /** ⇧H / ⇧V: mirror the selection on the screen's x or y (Figma's keys). */
+  | { kind: "flip"; axis: FlipAxis }
   /** ⇧Z: wireframe on, and back to whatever the shading was. Blender's. */
-  | { kind: "wireframeToggle" };
+  | { kind: "wireframeToggle" }
+  /** ⌥Z: the working pane's grid floor on / off. The alt lane is where this
+   *  chrome keeps the verbs whose letter is already spoken for, and the grid
+   *  is the Z family's overlay (Blender keeps its grid behind ⇧⌥Z's overlay
+   *  toggle; this stage has exactly one overlay floor, so one key does). */
+  | { kind: "gridToggle" }
+  /** ⌥M: the dock's Sound face on / off (gap 8). M for mixer; bare M drops a
+   *  marker, so the mixer takes the alt lane. */
+  | { kind: "soundMode" }
+  /** ⇧R: the camera pane's rulers on / off (Paper page 24). Figma's and
+   *  Photoshop's key family; the plain letter stays rotate / rect. */
+  | { kind: "rulersToggle" }
+  /** ⌘, : the Preferences dialog, every Mac app's key for it. */
+  | { kind: "openPrefs" }
+  // ── THE STORYBOARD'S OWN LANE ────────────────────────────────────────────
+  //
+  // Prefixed `storyboard`, produced only with `storyboard: true` (or, for the
+  // toggle, from the ordinary shell), for the graph lane's reason: Delete over
+  // a card must remove the card, never the layer the shell still has selected
+  // underneath the board.
+  | { kind: "storyboardToggle" }
+  | { kind: "storyboardDelete" }
+  | { kind: "storyboardSelectAll" }
+  | { kind: "storyboardEscape" }
+  | { kind: "storyboardDuplicate" }
+  | { kind: "storyboardRename" }
+  // COMMENTS (plan C5, S5): C comments on the board card selected or, off
+  // the board, arms the comment tool on the Studio's camera pane. N and
+  // Shift+N walk the open threads in board order, on the board only.
+  | { kind: "storyboardComment" }
+  | { kind: "storyboardNextThread" }
+  | { kind: "storyboardPrevThread" }
+  /**
+   * ⌘C / ⌘X / ⌘V ON THE BOARD, AND ITS ARM RETURNS `false`. That is the whole
+   * design and it is not a stub.
+   *
+   * These three currently fall through to `null`, nothing is
+   * `preventDefault`ed, and THAT IS PRECISELY why the browser's own `paste`
+   * event still reaches the board and lands image and video FILES from the
+   * system clipboard. Binding them to a handled action would make `handleKey`
+   * answer true, which preventDefaults the keydown, which cancels the paste
+   * event, which is the only thing carrying `clipboardData.files`. The
+   * capability would disappear and nothing would say so.
+   *
+   * So the document handlers in StoryboardView.tsx do the work, and these rows exist
+   * only so the three combos are documented and `shortcutFor` can print them in
+   * a menu. `ShortcutRow.action` is required, so a documented combo must
+   * resolve to something; resolving to an arm that returns `false` keeps
+   * behaviour byte-identical.
+   *
+   * A test asserts the arm returns false. It fails the moment someone tidies
+   * this to `true`, which is the point.
+   */
+  | { kind: "storyboardClipboard" }
+  // ── THE MATERIAL GRAPH'S OWN LANE ────────────────────────────────────────
+  //
+  // Every one of these is prefixed `graph` and every one of them is produced
+  // ONLY with `materialGraph: true`. That is not decoration: `graphDelete` and
+  // `deleteSelection` are the same key over two different subjects, and a lane
+  // that answered the layer verb inside the canvas would delete the MESH the
+  // author is painting rather than the node under their cursor.
+  /** Open the node palette. */
+  | { kind: "graphPalette" }
+  /** Remove the selected nodes and wires. */
+  | { kind: "graphDelete" }
+  | { kind: "graphDuplicate" }
+  | { kind: "graphCopy" }
+  | { kind: "graphCut" }
+  | { kind: "graphPaste" }
+  | { kind: "graphSelectAll" }
+  /** Box the selection, and take it back out again. */
+  | { kind: "graphGroup" }
+  | { kind: "graphUngroup" }
+  /** Go INTO the selected Subgraph node's function body. */
+  | { kind: "graphEnter" }
+  /** Show or hide the live thumbnail on the selected cards. */
+  | { kind: "graphPreviewToggle" }
+  /** Fit the whole graph in the canvas. */
+  | { kind: "graphFrame" }
+  | { kind: "graphTidy" }
+  /** Move the selected nodes, in GRAPH px. */
+  | { kind: "graphNudge"; dx: number; dy: number }
+  /** Escape, whose meaning inside the workspace is a four-rung ladder the
+   *  STORE owns — the palette, then the selection, then one function level,
+   *  then the workspace itself. The table cannot answer it, because three of
+   *  the four rungs are state this file deliberately does not take. */
+  | { kind: "graphEscape" };
 
 /** What the key event lands in. Only what actually changes the ANSWER — a
  *  keymap that took the whole store would be a keymap nobody could test. */
@@ -149,6 +359,31 @@ export interface KeyContext {
   /** The event target is a field, a textarea or a contenteditable. */
   editing: boolean;
   hasSelection: boolean;
+  /**
+   * At least one KEYFRAME is selected.
+   *
+   * A subject of its own, above the layer selection on the rungs that both
+   * could claim: the arrows nudge keys when there are keys, and layers
+   * otherwise. That is `deleteSelection`'s own most-specific-subject-wins
+   * logic, applied to the other gesture that has two possible targets.
+   *
+   * Absent counts as false, so every caller that predates keyframes keeps
+   * today's answers. */
+  hasKeyframeSelection?: boolean;
+  /** Sound mode has clips picked (`selectedAudio`): Q / W, Escape and Delete
+   *  answer to them. */
+  hasAudioSelection?: boolean;
+  /** Something is on the keyframe clipboard. Gates ⌘V so that with an empty
+   *  clipboard the key falls through to the browser rather than being
+   *  swallowed by a verb with nothing to do. Absent = false. */
+  hasKeyframeClip?: boolean;
+  /** Something is on the layer clip, which gates ⌘V the same way. Absent =
+   *  false. */
+  hasLayerClip?: boolean;
+  /** An animation, or a layer's effects, is on the motion clip. Gates ⌥⌘V and
+   *  ⇧⌥⌘V the way `hasLayerClip` gates ⌘V. Absent = false. */
+  hasAnimationClip?: boolean;
+  hasEffectsClip?: boolean;
   /**
    * The pen HOLDS AT LEAST ONE POINT — not "the path tool is armed".
    *
@@ -166,19 +401,82 @@ export interface KeyContext {
   /** The author is inside an isolated subtree. Only Escape's precedence reads
    *  it, and only once nothing is selected — see the lane. Absent = false. */
   isolation?: boolean;
+  /** A component DEFINITION is open (the outline is scoped to its interior).
+   *  A rung on Escape's ladder, so the gesture that opened a component context
+   *  can close all of it. Absent = false. */
+  editingDef?: boolean;
+  /** Components was opened from a Shot (`componentsOrigin`), so Escape goes
+   *  back to that Shot, frame and selection. Absent = false. */
+  componentsOrigin?: boolean;
+  /** THE STORYBOARD IS OPEN. Mode-level, unlike `materialGraph`: there is no
+   *  working stage pane beside this canvas (the preview is a monitor that
+   *  takes its own pointer), and a key pressed over the inspector must still
+   *  delete a card. Absent = false. */
+  storyboard?: boolean;
+  /** A CODE component is open (its source beside its own render). The other
+   *  family's rung, at the same height as the definition's because both put
+   *  the stage in the component context and neither can nest in the other.
+   *  Absent = false. */
+  codeComponent?: boolean;
+  /** Components is up with no component open (its empty state). Escape
+   *  leaves it, at the subjects' height. Absent = false. */
+  componentsOpen?: boolean;
+  /** A SHOT is open (the author is authoring its elements rather than
+   *  arranging shots). Escape's LAST rung, below the definition, because the
+   *  component context nests inside the shot context and Escape climbs out one
+   *  level per press. Absent = false. */
+  enteredScene?: boolean;
+  /**
+   * THE AUTHOR IS PILOTING THE SHOT CAMERA from the Camera pane.
+   *
+   * Escape's first rung of all: a mode the author armed most recently, and
+   * one whose badge promises "ESC TO EJECT". Video and pilot never coexist
+   * (entering Video ejects), so the order between the two rungs is moot.
+   * Absent = false.
+   */
+  pilot?: boolean;
+  /**
+   * THE AUTHOR IS WATCHING: Video is on screen (`viewMode.ts`'s `videoView`).
+   *
+   * Escape's TOP rung, above the deselect, because the selection SURVIVES a
+   * screening: it is invisible in Video and comes back with the handles, so
+   * an author who watched their shot and pressed Escape means "put the editor
+   * back", not "drop what I had selected". Absent = false.
+   */
+  video?: boolean;
   /**
    * The CURSOR IS OVER THE WORKING PANE and a modal transform could start.
    *
    * Stage-side callers only: the chrome has no cursor-over-pane answer, and
-   * passing nothing keeps G arming the move tool from a panel exactly as it
-   * always has. Cursor position and not `activePane`, because a modal needs an
+   * passing nothing leaves G unbound from a panel. Cursor position and not `activePane`, because a modal needs an
    * anchor point and activePane is only written on press/wheel — the mouse can
    * hover one pane while the other is active. Absent = false.
    */
   workingPane?: boolean;
+  /**
+   * The working pane under the cursor is also the FRAME being edited: an open
+   * definition's one pane (StageApp's `framePane`). A letter a tool claims
+   * keeps its tool there, as it does over the camera pane, so R arms Rect
+   * while G and S keep their modals. Stage-side only, like `workingPane`.
+   * Absent = false.
+   */
+  framePane?: boolean;
   /** A modal transform is LIVE. Owns its terminator and axis keys, the way
    *  `penActive` owns Enter/Escape. Absent = false. */
   transformModal?: boolean;
+  /**
+   * THE KEY LANDED INSIDE THE MATERIAL GRAPH CANVAS.
+   *
+   * Measured from the event's target (`closest(".material-graph-canvas")`) and
+   * not from "the workspace is open", which is the distinction the whole lane
+   * rests on: the workspace shows a stage pane BESIDE the graph, and a key
+   * pressed over that pane still aims the working view. Only the canvas itself
+   * owns the graph verbs.
+   *
+   * Absent = false, so every caller and probe that predates the lane keeps
+   * today's answers.
+   */
+  materialGraph?: boolean;
 }
 
 export interface KeyEventLike {
@@ -187,9 +485,16 @@ export interface KeyEventLike {
   altKey: boolean;
   ctrlKey: boolean;
   metaKey: boolean;
-  /** `KeyboardEvent.code`, for the numpad lane. Optional so every caller and
-   *  probe that predates it keeps today's answers; absent = no numpad. */
+  /** `KeyboardEvent.code`: the numpad lane, the shifted layout digits, and
+   *  the chord letters when `key` is composed (see `chordChar`). Optional so
+   *  every caller and probe that predates it keeps today's answers; absent =
+   *  no numpad, and no shifted-digit layout key. */
   code?: string;
+  /** `KeyboardEvent.repeat`: the key is held and this keydown is the OS
+   *  repeating it. The table answers a repeat as it answers the press; the
+   *  play toggle ignores it, so a held Space toggles once (the store's
+   *  `handleKey`). Absent = a press. */
+  repeat?: boolean;
 }
 
 /** How far a plain arrow moves a layer, and how far a shifted one does. Design
@@ -197,21 +502,89 @@ export interface KeyEventLike {
  *  the view would be a different edit depending on how far you were zoomed in. */
 export const NUDGE_PX = 1;
 export const NUDGE_COARSE_PX = 10;
+/** Shift's multiplier on a keyframe nudge, in FRAMES. Ten, the same relationship
+ *  the layer nudge has — but frames rather than px, because a keyframe moves in
+ *  time and a design pixel means nothing on that axis. */
+export const NUDGE_COARSE_FRAMES = 10;
 
 /**
- * The view-mode digits, LEFT TO RIGHT as the toolbar draws them.
+ * …and the same pair for the GRAPH canvas, which is a different space.
  *
- * Keyed on `event.key` and not on a folded letter, which is what keeps them
- * bare-only for free: shift-1 reports "!" on every layout that has one, so a
- * shifted digit falls through to the tool lane and finds nothing rather than
- * needing a guard. The modifier lanes above have already returned by here, so
- * ⌘1 stays the browser's tab switch.
+ * A node lives in canvas px, where one px is invisible: the cards are ~180 px
+ * wide and the grid they land on is 16. So the fine step is half a grid cell,
+ * which is the smallest nudge that reads as a move, and the coarse one is ten
+ * of those — the same 10x relationship the layer nudge has, so the modifier
+ * means one thing in both places.
  */
-const LAYOUT_KEYS: Readonly<Record<string, StageLayout["mode"]>> = {
-  "1": "working",
-  "2": "split",
-  "3": "camera",
-};
+export const GRAPH_NUDGE_PX = 8;
+export const GRAPH_NUDGE_COARSE_PX = 80;
+
+/**
+ * The Project context's refusal for anything that acts on elements, in one
+ * sentence: a tool "draws" them, a rail button that inserts without a drag
+ * "adds" them. The keys and the board's tool rail both say it this way.
+ */
+export function sceneContextRefusal(label: string, verb: string): string {
+  return `${label} ${verb} elements, and elements live inside a shot. Open a shot from the timeline to add one to it.`;
+}
+
+/**
+ * Why this tool's key does nothing in this layout, or null when it works.
+ *
+ * The seven creating tools draw on the frame, which over a Shot is the CAMERA
+ * pane and nowhere else (see `isInsertTool`), so in the working-only layout
+ * their letters armed a tool that no press could reach. That is worse than a
+ * dead key: with the tool armed, a press in the working pane falls through the
+ * stage's generic lanes and ORBITS the view, deselects, or drags whatever was
+ * selected, so the author sees the tool do the wrong thing rather than
+ * nothing, and has no reason to suspect the layout.
+ *
+ * `mode` is the layout the tools are judged against, which every caller reads
+ * through `toolLayoutMode`: inside a definition the stage's one pane is both
+ * the frame and the 3D view, so every tool's pane is on screen.
+ *
+ * A MESSAGE rather than a boolean, and pure: the store owns `state.error` (this
+ * is `noWorkingPane`'s job the other way round, and it names the digit to press
+ * for the same reason), and the tool dock puts the identical sentence in the
+ * disabled button's title — so what the key says and what the button says about
+ * where a tool works cannot drift apart.
+ */
+export function toolRefusal(
+  tool: ShotTool,
+  mode: StageLayout["mode"],
+  /** The author is in the SCENE context — arranging shots, not authoring the
+   *  elements of one. Absent = false, so every caller that predates the two
+   *  contexts keeps today's answers. */
+  sceneContext = false,
+  /** The Project is view only for this person: true, or the sentence that
+   *  says why (`readOnlyReason`). Absent = false. */
+  readOnly: boolean | string = false,
+  /** Why the isolated layer cannot take an insert (`isolationInsertRefusal`),
+   *  or null. True in every layout, so it outranks the pane answer. */
+  isolation: string | null = null,
+): string | null {
+  if (!isInsertTool(tool)) return null;
+  // Every creating tool writes the document, so a viewer has none of them.
+  if (readOnly !== false) return readOnly === true ? VIEW_ONLY : readOnly;
+  // THE CONTEXT ANSWER COMES FIRST, because it is the one that is true whatever
+  // the layout is: elements live inside a shot, so no layout up here makes a
+  // creating tool legal, and a layout sentence would send the author to a
+  // digit that would not help.
+  if (sceneContext) return sceneContextRefusal(specOf(tool).label, "draws");
+  if (isolation !== null) return isolation;
+  const pane = specOf(tool).pane;
+  // The lead clause is this tool's own; the tail is the one every "this layout
+  // cannot do that" refusal shares (`paneOnlyRefusal`), so the digits it names
+  // follow a rebind and the words follow a rename with no edit here. Both arms
+  // have narrowed `mode` to a single pane by the time they ask.
+  if (pane === "camera" && mode === "working") {
+    return formatCombo(`${specOf(tool).label} draws in ${layoutSpec(pane).noun}, and ${paneOnlyRefusal(mode)}`);
+  }
+  if (pane === "working" && mode === "camera") {
+    return formatCombo(`${specOf(tool).label} draws in ${layoutSpec(pane).noun}, and ${paneOnlyRefusal(mode)}`);
+  }
+  return null;
+}
 
 const ARROWS: Readonly<Record<string, readonly [number, number]>> = {
   ArrowLeft: [-1, 0],
@@ -220,7 +593,72 @@ const ARROWS: Readonly<Record<string, readonly [number, number]>> = {
   ArrowDown: [0, 1],
 };
 
-export function resolveKey(event: KeyEventLike, context: KeyContext): KeyAction | null {
+/**
+ * ARRANGE ON THE BRACKET KEYS, Figma's chords (founder decision 3, critic 5).
+ *
+ * ⌘] / Ctrl+] brings the selection forward one sibling and ⌘[ / Ctrl+[ sends
+ * it backward, on every platform. To the FRONT and BACK the chord splits by
+ * platform, as Figma's does: Ctrl+⇧ on Windows and Linux, ⌥⌘ on a Mac. ⌘⇧]
+ * and ⌘⇧[ are the Mac's next and previous TAB, so they are never claimed: they
+ * answer null and the browser keeps them. The split reads the modifier itself
+ * (meta is a Mac's command key, and Windows never delivers its own) rather
+ * than the platform, so this table stays a pure function of the event.
+ *
+ * Keyed on `event.code`, never `key`: Shift makes `]` a `}` and Option makes it
+ * a quote on a Mac, so the character is no witness to the key. ⌘[ and ⌘] ARE
+ * taken from Chrome's Back and Forward on a Mac, as Figma takes them, and
+ * `handleKey` claims them like ⌘K. The bare brackets stay the panel toggles,
+ * in lane 3.
+ */
+function arrangeChord(event: KeyEventLike): KeyAction | null {
+  const side =
+    event.code === "BracketRight" ? 1 : event.code === "BracketLeft" ? -1 : 0;
+  if (side === 0) return null;
+  const { shiftKey: shift, altKey: alt, ctrlKey: ctrl, metaKey: meta } = event;
+  if (!shift && !alt)
+    return { kind: "arrange", to: side > 0 ? "forward" : "backward" };
+  const macFront = meta && alt && !shift && !ctrl;
+  const pcFront = ctrl && shift && !alt && !meta;
+  if (macFront || pcFront)
+    return { kind: "arrange", to: side > 0 ? "front" : "back" };
+  return null;
+}
+
+/**
+ * An Arrange chord over a canvas with nothing to arrange (the storyboard, the
+ * material graph, lanes 1e and 1f): CLAIMED and dropped, so ⌘[ and ⌘] are not
+ * the browser's Back and Forward there either. A character lane 2a keeps for
+ * itself before it asks `arrangeChord` (a letter, a digit, the zoom keys: a
+ * layout can put `+` or `=` on a bracket key) is left to the browser, as every
+ * combo those lanes do not bind.
+ */
+function arrangeNowhere(event: KeyEventLike, lower: string): KeyAction | null {
+  if (/^[a-z0-9=+-]$/.test(lower)) return null;
+  return arrangeChord(event) === null ? null : { kind: "arrangeNowhere" };
+}
+
+/**
+ * The letter or digit a ctrl or alt chord names.
+ *
+ * A plain one in `key` wins, so a non-QWERTY layout keeps its own letters
+ * (AZERTY's ⌘A is the key printed A). When `key` is NOT a plain letter or digit
+ * the physical key answers instead: a Mac's Option composes it ("ç" for ⌥⌘C,
+ * "¬" for ⌥L, a dead key for ⌥I), Shift turns a digit into punctuation, and a
+ * Cyrillic layout reports "я" on the key every shortcut chart calls Z.
+ * Anything else (`=`, `+`, `-`, a bracket) comes back as it was typed.
+ */
+function chordChar(event: KeyEventLike, lower: string): string {
+  if (/^[a-z0-9]$/.test(lower)) return lower;
+  const code = event.code ?? "";
+  if (/^Key[A-Z]$/.test(code)) return code.slice(3).toLowerCase();
+  if (/^Digit[0-9]$/.test(code)) return code.slice(5);
+  return lower;
+}
+
+export function resolveKey(
+  event: KeyEventLike,
+  context: KeyContext,
+): KeyAction | null {
   // 1. A field owns its own keystrokes. Every editor that has ever swallowed
   //    Space while the author was naming something shipped that bug by checking
   //    the KEY before the TARGET.
@@ -230,6 +668,21 @@ export function resolveKey(event: KeyEventLike, context: KeyContext): KeyAction
   const lower = key.length === 1 ? key.toLowerCase() : key;
   const mod = event.metaKey || event.ctrlKey;
 
+  // 1a. WINDOWS ALTGR IS NOT A CHORD. AltGr arrives as ctrlKey + altKey, so a
+  //     Polish author typing "ć" or a German one typing "@" or "€" would
+  //     otherwise reach the ctrl lane and fire whatever the physical key's
+  //     letter is bound to. A composed character (one that is not a plain
+  //     letter or digit) is typing, never a shortcut. A Mac's ⌥⌘ carries
+  //     metaKey and is a real chord, so it passes.
+  if (
+    event.ctrlKey &&
+    event.altKey &&
+    !event.metaKey &&
+    key.length === 1 &&
+    !/^[a-z0-9]$/i.test(key)
+  )
+    return null;
+
   // 1b. A PATH IN PROGRESS owns Enter and Escape, and only those two.
   //
   //     Above every other lane because both keys already mean something here
@@ -244,9 +697,14 @@ export function resolveKey(event: KeyEventLike, context: KeyContext): KeyAction
 
   // 1c. A LIVE MODAL TRANSFORM owns everything bare.
   //
-  //     Enter/Escape terminate it and x/y/z constrain it (shift allowed —
-  //     shift is the live precision modifier, so ⇧Z mid-modal is still the z
-  //     axis, not fit). Every OTHER bare key answers null so no tool can arm
+  //     Enter/Escape terminate it and x/y/z constrain it. SHIFT IS PART OF THE
+  //     CONSTRAINT: `⇧X` locks to the PLANE normal to x — Blender's own
+  //     binding, and the one thing a keyboard-only author could not say here
+  //     (the drawn gizmo grew plane pads for it; this is the same constraint on
+  //     the keys). It used to fall through as "still the z axis, not fit",
+  //     which was right while there was no plane to mean instead. Shift keeps
+  //     its precision job on MOTION, which is a different event entirely.
+  //     Every OTHER bare key answers null so no tool can arm
   //     and no panel can toggle under an open scrub. Modifier combos fall
   //     through on purpose: the table stays honest about what ⌘Z means — the
   //     stage's capture listener is the one that swallows it while the modal
@@ -255,25 +713,28 @@ export function resolveKey(event: KeyEventLike, context: KeyContext): KeyAction
   //
   //     ALT FALLS THROUGH, and `mod` alone does not cover it: `mod` is
   //     ctrl/meta, so ⌥G reached this lane and RESTARTED the modal instead of
-  //     reaching lane 2b's `clearTransform` (Blender's ⌥G / ⌥R / ⌥S, "clear
+  //     reaching lane 2b's `clearTransform` (Blender's ⌥G / ⌥R, and ⌥⇧S, "clear
   //     this channel"), and ⌥X set an axis. The alt bindings are a different
   //     verb that happens to share a letter, so the lane has to let them past.
   if (context.transformModal === true && !mod && !event.altKey) {
     if (key === "Enter") return { kind: "modalConfirm" };
     if (key === "Escape") return { kind: "modalCancel" };
-    if (lower === "x") return { kind: "modalAxis", axis: "x" };
-    if (lower === "y") return { kind: "modalAxis", axis: "y" };
-    if (lower === "z") return { kind: "modalAxis", axis: "z" };
+    if (lower === "x")
+      return { kind: "modalAxis", axis: "x", plane: event.shiftKey === true };
+    if (lower === "y")
+      return { kind: "modalAxis", axis: "y", plane: event.shiftKey === true };
+    if (lower === "z")
+      return { kind: "modalAxis", axis: "z", plane: event.shiftKey === true };
     // SWITCHING TRANSFORM MID-GESTURE, which in Blender feels like a mode
     // change rather than a restart: `G` then `R` keeps the anchor the author
     // started from, so the rotation is measured from where they pressed and not
     // from wherever the pointer had wandered to.
     if (lower === "g") return { kind: "modalStart", mode: "move" };
-    // `R` NEEDS A SELECTION, exactly as the starter lane below does and for the
-    // same reason: the CAMERA has no modal roll. Without the guard, switching
-    // to rotate on a camera modal armed a transform that could never emit,
-    // under a pill that still said CAMERA MOVE.
-    if (lower === "r" && context.hasSelection) return { kind: "modalStart", mode: "rotate" };
+    // `R` NEEDS NO SELECTION ANY MORE: the camera has a modal roll, so
+    // switching to rotate mid-gesture is symmetric with `G` and `S` whichever
+    // subject the modal is on. `framingDeltaFor`'s rotate arm is what it emits
+    // into, and `axisRefusal` names the two axes a framing cannot turn about.
+    if (lower === "r") return { kind: "modalStart", mode: "rotate" };
     if (lower === "s") return { kind: "modalStart", mode: "scale" };
     // NUMERIC ENTRY: `G X 200 Enter`, which is the single biggest thing a
     // Blender user's fingers reach for and finds missing. It goes through the
@@ -330,20 +791,30 @@ export function resolveKey(event: KeyEventLike, context: KeyContext): KeyAction
           Numpad2: { dx: 0, dy: 1 },
         };
         const one = step[event.code]!;
-        return { kind: "orbitStep", dx: one.dx * ORBIT_STEP_DEG, dy: one.dy * ORBIT_STEP_DEG };
+        return {
+          kind: "orbitStep",
+          dx: one.dx * ORBIT_STEP_DEG,
+          dy: one.dy * ORBIT_STEP_DEG,
+        };
       }
       case "Numpad0":
-        // A TOGGLE, matching Blender: numpad-0 goes to the camera and numpad-0
-        // again comes back. Straight to `camera` meant an author who pressed it
-        // twice was stuck there with no way back but the mouse.
-        if (!mod) return { kind: "stageLayout", mode: "camera", toggle: true };
+        // PILOT, and back: Blender's numpad-0 looks through the camera, and
+        // ours puts the author's hands on it in the Camera pane. A toggle, so
+        // pressing it twice leaves the camera where it is and the hands off.
+        // The layouts keep ⇧1 / ⇧2 / ⇧3; the store brings the Camera pane on
+        // screen if the 3D layout has none.
+        if (!mod) return { kind: "pilotToggle" };
         break;
       case "NumpadAdd":
       case "NumpadSubtract":
         // The existing zoom verb, which already routes to the active pane —
         // so it dollies the working camera and zooms the flat one, correctly,
         // with no new action.
-        if (!mod) return { kind: "zoom", direction: event.code === "NumpadAdd" ? 1 : -1 };
+        if (!mod)
+          return {
+            kind: "zoom",
+            direction: event.code === "NumpadAdd" ? 1 : -1,
+          };
         break;
       case "NumpadDivide":
         // LITERALLY Blender's local view. Ours is isolation, and the two mean
@@ -371,96 +842,353 @@ export function resolveKey(event: KeyEventLike, context: KeyContext): KeyAction
     if (!mod && key.length === 1) return null;
   }
 
+  // 1e. THE MATERIAL GRAPH CANVAS owns its own vocabulary.
+  //
+  //     Above the modifier lanes because ⌘D, ⌘G and ⌘A all mean something else
+  //     in here, and BELOW the field lane because a node's inline number field
+  //     is still a field. The lane answers `"pass"` for exactly the keys that
+  //     have to keep meaning what they mean everywhere — undo, redo, save, the
+  //     app menu, and the space bar — and `null` for everything it does not
+  //     claim, which is what keeps a bare tool letter from arming the rect tool
+  //     under a graph nobody could draw a rectangle in.
+  if (context.materialGraph === true) {
+    const graph = materialGraphKey(event, key, lower, mod);
+    if (graph !== "pass") return graph;
+  }
+
+  // 1f. THE STORYBOARD holds the canvas while it is open, on the graph lane's
+  //     terms: pass what must keep meaning what it means everywhere, blank the
+  //     rest, because nothing under the board can take a tool letter.
+  if (context.storyboard === true) {
+    const board = storyboardKey(event, key, lower, mod);
+    if (board !== "pass") return board;
+  }
+
   // 2a. ctrl / meta.
+  //
+  //     EVERY CASE NAMES THE MODIFIERS IT OWNS, and a combo it does not own
+  //     answers null. The lane used to switch on the letter alone, so ⌘⇧C
+  //     copied, ⌥⌘S saved and Ctrl+Alt+D duplicated: every extra modifier was
+  //     a second spelling of the bare chord, and no chord with one could ever
+  //     be bound to anything else. A refused combo is null and not
+  //     `arrangeChord`: a letter is never a bracket.
   if (mod) {
-    switch (lower) {
+    const shift = event.shiftKey;
+    const alt = event.altKey;
+    const plain = !shift && !alt;
+    switch (chordChar(event, lower)) {
       case "z":
-        return event.shiftKey ? { kind: "redo" } : { kind: "undo" };
+        if (alt) return null;
+        return shift ? { kind: "redo" } : { kind: "undo" };
       case "y":
-        return { kind: "redo" };
+        return plain ? { kind: "redo" } : null;
+      // ── KEYFRAME COPY / PASTE, AND ONLY WHEN THERE IS ONE ─────────────
+      //
+      // Both fall through to the BROWSER when their subject is absent, which
+      // is why they answer `null` rather than a no-op verb: ⌘C with nothing
+      // keyframed must still copy whatever the page has selected, and a
+      // chrome that swallowed it would break the one shortcut every user
+      // trusts. The field lane returns above this, so text copy is untouched
+      // either way. Keys first, then layers, the most specific subject the way
+      // `deleteSelection` reads it. The store keeps one clip: a copy of either
+      // clears the other, so at most one of the two paste bits is set.
+      // ── THE MOTION CLIP ON ⌥ ──────────────────────────────────────────
+      //
+      // ⌥⌘C / ⌥⌘V carry a layer's animation and ⇧⌥⌘C / ⇧⌥⌘V its effects. Each
+      // needs a selected layer (and a paste a clip of its kind), else it is the
+      // browser's, the same rule as the plain pair below.
+      case "c":
+        if (alt) {
+          if (!context.hasSelection) return null;
+          return shift ? { kind: "copyEffects" } : { kind: "copyAnimation" };
+        }
+        if (!plain) return null;
+        if (context.hasKeyframeSelection === true) return { kind: "copyKeyframes" };
+        return context.hasSelection ? { kind: "copyLayers" } : null;
+      case "x":
+        if (!plain) return null;
+        if (context.hasKeyframeSelection === true) return null;
+        return context.hasSelection ? { kind: "cutLayers" } : null;
+      case "v":
+        if (alt) {
+          if (!context.hasSelection) return null;
+          if (shift) return context.hasEffectsClip === true ? { kind: "pasteEffects" } : null;
+          return context.hasAnimationClip === true ? { kind: "pasteAnimation" } : null;
+        }
+        if (!plain) return null;
+        if (context.hasKeyframeClip === true) return { kind: "pasteKeyframes" };
+        return context.hasLayerClip === true ? { kind: "pasteLayers" } : null;
       case "s":
-        return { kind: "save" };
+        return plain ? { kind: "save" } : null;
       case "d":
-        return { kind: "duplicate" };
+        return plain ? { kind: "duplicate" } : null;
       case "e":
         // Export. The one destination-producing verb in the whole chrome, so
         // it gets the letter rather than a chord.
-        return { kind: "openExport" };
+        return plain ? { kind: "openExport" } : null;
       case "a":
-        return { kind: "selectAll" };
+        // ⌘A selects all and ⌘⇧A drops it, the pair every design tool ships.
+        // ⌥A was the deselect until the alt lane was cleared for new verbs.
+        if (alt) return null;
+        return shift ? { kind: "deselect" } : { kind: "selectAll" };
+      case "h":
+        // ⌘⇧H shows everything again. The reveal moved here off ⌥H, which is
+        // left free; ⌘H alone is the Mac's "hide the app" and is never claimed.
+        return shift && !alt ? { kind: "setHidden", scope: "reveal" } : null;
+      case ",":
+        return plain ? { kind: "openPrefs" } : null;
+      case "k":
+        // The app menu, with its search focused — the ⌘K every tool now ships.
+        // It CLAIMS Chrome's own ⌘K (the address bar's search shortcut), which is
+        // deliberate and is why `handleKey` answers true: the alternative is a
+        // menu whose advertised key opens the browser instead.
+        return plain ? { kind: "appMenu" } : null;
       case "b":
-        // Split at the playhead, and the ONLY splitter now that the cut tool is
-        // gone — see the header.
-        return { kind: "splitAtPlayhead" };
+        // THE TWO SPLITTERS, and the only ones now that the cut tool is gone —
+        // see the header. ⇧ picks the bigger subject, the same way it does on
+        // ⌘G / ⌘⇧G: the bare key cuts inside the shot and the shifted one cuts
+        // the shot. Nothing else claims ⌘⇧B, so the shift has to be read
+        // HERE or a shot split would silently resolve as a razor.
+        if (alt) return null;
+        return shift ? { kind: "splitSceneAtPlayhead" } : { kind: "splitAtPlayhead" };
       case "g":
-        return event.shiftKey ? { kind: "ungroup" } : { kind: "group" };
+        if (alt) return null;
+        return shift ? { kind: "ungroup" } : { kind: "group" };
       case "0":
-        return { kind: "zoomReset" };
+        return plain ? { kind: "zoomReset" } : null;
+      // The zoom keys own Shift: "+" IS a shifted "=" on most layouts.
       case "=":
       case "+":
-        return { kind: "zoom", direction: 1 };
+        return alt ? null : { kind: "zoom", direction: 1 };
       case "-":
-        return { kind: "zoom", direction: -1 };
+        return alt ? null : { kind: "zoom", direction: -1 };
       default:
         // An unclaimed modifier combo belongs to the BROWSER (⌘T, ⌘W, ⌘R).
         // Falling through to the letter lane here would arm a tool on ⌘R and
-        // reload the page at the same time.
-        return null;
+        // reload the page at the same time. The one exception is Arrange's
+        // bracket chords, asked HERE, after every character above: a layout
+        // whose bracket key types a character this lane binds keeps that
+        // meaning (German `+` sits on BracketRight, and ⌘+ is zoom in).
+        return arrangeChord(event);
     }
   }
 
-  // 2b. alt.
+  // 2b. alt. A Mac's Option composes the key ("¬" for ⌥L, a dead key for ⌥I,
+  //     "⁄" for ⇧⌥1), so the letter comes from `code` when `key` is not one
+  //     (`chordChar`). Like lane 2a, every case names whether it owns Shift.
   if (event.altKey) {
-    switch (lower) {
+    const shift = event.shiftKey;
+    const altKey = chordChar(event, lower);
+    switch (altKey) {
       case "l":
-        return { kind: "toggleLock" };
+        return shift ? null : { kind: "toggleLock" };
       case "h":
-        // REVEAL EVERYTHING, Blender's own ⌥H, replacing a toggle that read
-        // `selection[0]`'s flag — so five layers hidden one at a time had no
-        // key that brought them back.
-        return { kind: "setHidden", scope: "reveal" };
+        // ⌥⇧H HIDES EVERYTHING ELSE. It was ⇧H, which is cleared for a new
+        // verb. Bare ⌥H centres horizontally (the align block below).
+        return shift
+          ? { kind: "setHidden", scope: "others" }
+          : { kind: "align", mode: "hcenter" };
+      // ── ALIGN, Figma's ⌥ letters ───────────────────────────────────────
+      //
+      // A and D are the left and right edges, W and S the top and bottom (the
+      // WASD block), H and V the two centres. Bare only: ⌥⇧S is the size
+      // clear and ⌥⇧H hides everything else.
       case "a":
-        // Blender's deselect-all. Its own action and NOT Escape's lane, which
-        // also leaves a subtree.
-        return { kind: "deselect" };
+        return shift ? null : { kind: "align", mode: "left" };
+      case "d":
+        return shift ? null : { kind: "align", mode: "right" };
+      case "w":
+        return shift ? null : { kind: "align", mode: "top" };
+      case "v":
+        return shift ? null : { kind: "align", mode: "vcenter" };
       case "c":
         // ⌥C and not bare C, because the alt lane is where this chrome keeps
         // the verbs whose letter is already spoken for.
-        return { kind: "alignCameraToView" };
-      // ── CLEAR TRANSFORM, Blender's ⌥G / ⌥R / ⌥S ────────────────────────
+        return shift ? null : { kind: "alignCameraToView" };
+      case "m":
+        return shift ? null : { kind: "soundMode" };
+      case "z":
+        // ⌥Z: the grid floor. Z is the viewport-look letter (bare Z shading,
+        // ⇧Z wireframe), and the grid is that family's overlay.
+        return shift ? null : { kind: "gridToggle" };
+      // ── THE KEYFRAME JUMPS, MOVED HERE OFF BARE J / K ──────────────────
+      //
+      // They held the bare letters until the shuttle arrived, and the shuttle
+      // has the better claim: J and K are the transport's own keys in every
+      // NLE an author comes here from, and a keyframe jump is the more local
+      // verb of the two. So they take the alt lane, which is where this file
+      // keeps the verbs whose letter is spoken for — the same move ⌥C and ⌥Z
+      // already made.
+      case "j":
+        return shift ? null : { kind: "jumpKeyframe", dir: -1 };
+      case "k":
+        return shift ? null : { kind: "jumpKeyframe", dir: 1 };
+      // ── THE WORK AREA: ⌥I, ⌥O, ⌥X ──────────────────────────────────────
+      //
+      // I and O are in and out in every editor that has the idea, and both
+      // BARE letters are tools here (`i` is Media, `o` is Ellipse), so the alt
+      // lane is where they land. ⌥X clears, because X is the axis letter and
+      // has no meaning of its own outside a live modal.
+      case "i":
+        return shift ? null : { kind: "setWorkArea", edge: "in" };
+      case "o":
+        return shift ? null : { kind: "setWorkArea", edge: "out" };
+      case "x":
+        return shift ? null : { kind: "clearWorkArea" };
+      // ── CLEAR TRANSFORM, Blender's ⌥G / ⌥R, and ⌥⇧S ───────────────────
       //
       // Back to the layer's own zero: position, rotation, or size. It is the
       // fastest way out of a transform that went wrong several edits ago, and
-      // undo cannot reach it once anything else has happened since.
+      // undo cannot reach it once anything else has happened since. Size is
+      // ⌥⇧S: bare ⌥S is align bottom.
       case "g":
-        return { kind: "clearTransform", channel: "offset" };
+        return shift ? null : { kind: "clearTransform", channel: "offset" };
       case "r":
-        return { kind: "clearTransform", channel: "rotation" };
+        return shift ? null : { kind: "clearTransform", channel: "rotation" };
       case "s":
-        return { kind: "clearTransform", channel: "scale" };
+        return shift
+          ? { kind: "clearTransform", channel: "scale" }
+          : { kind: "align", mode: "bottom" };
+      // ── AXIS VIEWS WITHOUT A NUMPAD, Blender's "Emulate Numpad" ────────
+      //
+      // The numpad lane above keys on `event.code.startsWith("Numpad")`, so a
+      // laptop without one had NO KEYBOARD PATH to front, right or top — the
+      // three views a 3D pane is most often asked for. Blender ships a
+      // preference that maps the top-row digits; this chrome keeps the bare
+      // digits free and puts the stage layouts on ⇧1 / ⇧2 / ⇧3. The alt lane
+      // is where this file keeps the verbs whose letter is spoken for, so they
+      // land here with the same digits, and ⇧ for the opposite side.
+      case "1":
+        return {
+          kind: "workingViewPreset",
+          preset: shift ? "back" : "front",
+        };
+      case "3":
+        return {
+          kind: "workingViewPreset",
+          preset: shift ? "left" : "right",
+        };
+      case "7":
+        return {
+          kind: "workingViewPreset",
+          preset: shift ? "bottom" : "top",
+        };
+      case "5":
+        return shift ? null : { kind: "toggleWorkingOrtho" };
       default:
         return null;
     }
   }
 
   // 3. Bare and shifted.
+  // ── KEYFRAMES BEFORE LAYERS, ON THE HORIZONTAL PAIR ONLY ────────────────
+  //
+  // A selected keyframe is a MORE SPECIFIC subject than the layer under it —
+  // the same most-specific-wins ladder `deleteSelection` walks — so ←/→ moves
+  // the keys in time when there are keys. ⇧ is the same 10x it is everywhere
+  // else in this table.
+  //
+  // ↑/↓ ARE DELIBERATELY NOT CLAIMED. A keyframe's other axis is its VALUE, and
+  // there is no step size that means anything across kinds: 1 is imperceptible
+  // on a position and the whole range on an opacity. It stays a drag in the
+  // graph, where the axis has a scale on it.
+  if (
+    (key === "ArrowLeft" || key === "ArrowRight") &&
+    context.hasKeyframeSelection === true
+  ) {
+    const dir = key === "ArrowLeft" ? -1 : 1;
+    return {
+      kind: "nudgeKeys",
+      delta: dir * (event.shiftKey ? NUDGE_COARSE_FRAMES : 1),
+    };
+  }
   const arrow = ARROWS[key];
   if (arrow !== undefined) {
-    const step = event.shiftKey ? NUDGE_COARSE_PX : NUDGE_PX;
     // SELECTION WINS. With nothing selected the same keys move the playhead,
     // which is the only reading where both meanings are reachable without a
     // mode to switch between them.
-    return context.hasSelection
-      ? { kind: "nudge", dx: arrow[0] * step, dy: arrow[1] * step }
-      : { kind: "step", delta: arrow[0] !== 0 ? arrow[0] : arrow[1] };
+    if (context.hasSelection) {
+      const step = event.shiftKey ? NUDGE_COARSE_PX : NUDGE_PX;
+      return { kind: "nudge", dx: arrow[0] * step, dy: arrow[1] * step };
+    }
+    const dir = arrow[0] !== 0 ? arrow[0] : arrow[1];
+    // ── THE PLAYHEAD'S OWN THREE READINGS ────────────────────────────────
+    //
+    // ⇧ IS A SECOND, on all four arrows. Shift is the coarse step everywhere
+    // else in this table (10 px on a nudge, 10 frames on a keyframe), and a
+    // frame's own coarse unit is the second — which is also the only jump size
+    // that means the same thing at 24, 30 and 60 fps. It cannot be spelled as
+    // a frame count here: see `stepSeconds`.
+    if (event.shiftKey) return { kind: "stepSeconds", delta: dir < 0 ? -1 : 1 };
+    // ↑ / ↓ WALK THE EDIT POINTS. Bare, and it costs nothing: with nothing
+    // selected the vertical pair used to be a second, identical spelling of
+    // ←/→'s one-frame step, so the only key this claims is a duplicate. What
+    // it buys is the gesture an author scanning a cut actually wants —
+    // straight to the next place something happens.
+    if (arrow[0] === 0) return { kind: "jumpEdit", dir: dir < 0 ? -1 : 1 };
+    return { kind: "step", delta: dir };
+  }
+  // ── BARE DIGITS SET OPACITY, the After Effects and Figma keys ───────────
+  //
+  // 1 is 10% through 9 at 90%, and 0 is 100%. Selection only, by `key`: a
+  // shifted digit is a layout (`layoutForEvent`), a numpad digit returned in
+  // lane 1d, and a live modal kept the digits as typed numbers in lane 1c.
+  // With nothing selected the digits answer null and stay free.
+  if (/^[0-9]$/.test(key) && !event.shiftKey && context.hasSelection) {
+    const n = Number(key);
+    return { kind: "opacity", value: n === 0 ? 1 : n / 10 };
   }
-  const mode = LAYOUT_KEYS[key];
-  if (mode !== undefined) return { kind: "stageLayout", mode };
+  // ── THE SHUTTLE: J, K, ⇧K ────────────────────────────────────────────────
+  //
+  // J runs backwards and steps down the ladder, K stops, ⇧K runs forwards and
+  // steps up. Both bare letters were free once the keyframe jumps moved to the
+  // alt lane above, and ⌘K stays the app menu (a lane resolved long before
+  // this one).
+  //
+  // ── L IS NOT AVAILABLE, AND IS NOT SHADOWED ──────────────────────────────
+  //
+  // Every NLE spells this J / K / L, and this chrome cannot: bare `L` is the
+  // LINE tool (`TOOL_SPECS.line.key`), reached through `toolForKey` at the
+  // bottom of this lane, and ⇧L is the Arrow tool beside it. A shuttle bound
+  // above them would shadow both, which is the one thing this file's header
+  // forbids — the tool would still be armable from the dock and from nowhere
+  // on the keyboard, with nothing saying so. The alt lane cannot take it
+  // either: ⌥L is `toggleLock`.
+  //
+  // So the third rung is ⇧K, on the shuttle's own remaining letter. Shift
+  // already means "the same verb, the other subject" in this table (⌘B / ⌘⇧B,
+  // ⌘G / ⌘⇧G, ⌘A / ⌘⇧A), and K is the letter an author's hand is already on.
+  if (lower === "j" && !event.shiftKey) return { kind: "shuttle", dir: -1 };
+  if (lower === "k")
+    return event.shiftKey ? { kind: "shuttle", dir: 1 } : { kind: "shuttleStop" };
+  // `;` and `'` seek to the selection's own in and out — the two keys to the
+  // right of the shuttle's run, and free: no tool claims a punctuation mark,
+  // and the bracket pair one row up already proved this lane safe to be bare.
+  if (key === ";") return { kind: "seekSelectionEdge", edge: "in" };
+  if (key === "'") return { kind: "seekSelectionEdge", edge: "out" };
+  // The three layouts on ⇧1 / ⇧2 / ⇧3, LEFT TO RIGHT as the toolbar draws
+  // them, by the physical key (`layoutForEvent`). The modifier lanes above
+  // have already returned by here, so ⌘1 stays the browser's tab switch. The
+  // BARE digits answer nothing: they are kept free for numeric verbs.
+  const mode = layoutForEvent(event);
+  if (mode !== null) return { kind: "stageLayout", mode };
+  // ── AND ⇧4 IS THE PICTURE ─────────────────────────────────────────────
+  //
+  // Next in the row the three layouts occupy. It is deliberately NOT a toggle
+  // (Escape is the way back, one rung above every other Escape verb) because
+  // ⇧4 names a place rather than a switch, exactly as ⇧1 / ⇧2 / ⇧3 do.
+  if (event.shiftKey && event.code === VIEW_MODE_SPECS.video.code)
+    return { kind: "viewMode", mode: "video" };
   if (key === " ") return { kind: "playToggle" };
   // `\` fits the timeline. It is the NLE convention (Premiere and Resolve both
   // bind "zoom to sequence" to it) and it is a key no letter lane can reach, so
   // the dock's fit costs the tool table nothing.
   if (key === "\\") return { kind: "fitTimeline" };
+  // `/` puts the caret in the column's search, the key the field's own hint
+  // shows. By `key`, so a layout that types `/` with Shift still reaches it;
+  // the numpad's `/` returned in lane 1d as isolation. A field already owns
+  // its keystrokes (lane 1), so typing a path into an input is untouched.
+  if (key === "/") return { kind: "focusSearch" };
   // The bracket keys hide their own side, and `.` hides everything. Bare, and
   // safe to be bare: none of the three is a tool letter, and this lane's
   // complaint was that the panels leave too little stage — a chord to see your
@@ -470,30 +1198,75 @@ export function resolveKey(event: KeyEventLike, context: KeyContext): KeyAction
   if (key === "]") return { kind: "togglePanel", panel: "inspector" };
   if (key === ".") return { kind: "togglePanel", panel: "all" };
   // ESCAPE, IN PRECEDENCE ORDER: abandon the pen (lane 1b, above), then
-  // deselect, then leave one level of isolation. Innermost subject first, and
-  // the two are ordered rather than exclusive because an author inside a card
-  // with a child selected presses Escape twice — once to drop the selection,
-  // once to come out. Collapsing them would make the second press do nothing
-  // and the first do too much.
+  // deselect, then leave one level of isolation, then the definition's own two
+  // rungs (its layers back to its Studio, then the Studio out of the definition
+  // entirely), then leave the shot. Innermost subject first, and they are
+  // ordered rather than exclusive because an author inside a card with a child
+  // selected presses Escape twice — once to drop the selection, once to come
+  // out. Collapsing them would make the second press do nothing and the first
+  // do too much.
+  //
+  // The definition sits above the shot because it NESTS INSIDE one: the
+  // component context is entered from the shot context and every ladder in this
+  // chrome climbs one level per press. The component context and isolation are
+  // mutually exclusive since v14 (entering a definition clears isolation), so at
+  // most one of the two middle rungs fires — but a selection inside either still
+  // takes the first press.
+  //
+  // A SHOT DOOR GOES BACK TO ITS SHOT. When Components was opened from a
+  // Shot (`componentsOrigin`), one press restores that Shot, its frame and its
+  // selection, which is what "Back to Shot" in the bar does.
   if (key === "Escape") {
-    if (context.hasSelection) return { kind: "deselect" };
+    // ── RUNG -1: HANDS OFF THE CAMERA ───────────────────────────────────
+    //
+    // The pilot badge promises "ESC TO EJECT", and a mode that writes the
+    // document on every drag has to be the first thing Escape leaves. The
+    // selection, the container and the screening all survive it.
+    if (context.pilot === true) return { kind: "pilotEject" };
+    // ── RUNG 0: PUT THE EDITOR BACK ─────────────────────────────────────
+    //
+    // Above the deselect, and that order is the whole rule: the selection
+    // survives a screening (Video simply stops drawing its handles), so an
+    // author who pressed ⇧4, watched, and pressed Escape is asking for the
+    // editor back and would be surprised to find their selection gone and the
+    // picture unchanged. Every rung below is about the CONTAINER the author is
+    // inside; this one is about whether they are looking or working, which sits
+    // over all of them.
+    if (context.video === true) return { kind: "viewMode", mode: "edit" };
+    if (context.hasSelection || context.hasAudioSelection === true) return { kind: "deselect" };
     if (context.isolation === true) return { kind: "exitIsolation" };
+    if (context.componentsOrigin === true) return { kind: "backToShot" };
+    if (context.editingDef === true) return { kind: "closeComponentContext" };
+    // The other family's subject, at the same height and never both: the two
+    // are mutually exclusive by construction (each entry clears the other), so
+    // this is a sibling rung rather than one below.
+    if (context.codeComponent === true) return { kind: "closeCodeComponent" };
+    if (context.componentsOpen === true) return { kind: "leaveComponents" };
+    if (context.enteredScene === true) return { kind: "leaveScene" };
     return { kind: "deselect" };
   }
   // ENTER goes the other way: into the selected layer. Unclaimed until now, and
   // the pen already owns it while a path is open (lane 1b).
-  if (key === "Enter" && context.hasSelection) return { kind: "enterIsolation" };
-  if (key === "Delete" || key === "Backspace") return { kind: "deleteSelection" };
+  if (key === "Enter" && context.hasSelection)
+    return { kind: "enterIsolation" };
+  // ⇧BACKSPACE IS THE RIPPLE, above the plain delete because that line reads
+  // neither key's modifiers. Backspace and not Delete, and only Backspace: the
+  // two keys are one binding everywhere else in this table, and splitting them
+  // by name is what keeps a Del pressed near the shift key from closing a gap
+  // the author wanted. Every NLE spells the ripple with a shift for the same
+  // reason.
+  if (key === "Backspace" && event.shiftKey) return { kind: "rippleDelete" };
+  if (key === "Delete" || key === "Backspace")
+    return { kind: "deleteSelection" };
   // HOME frames the active pane, the Blender "frame all". A key no field
   //  shares (lane 1 already returned for a field) and no tool can reach.
   if (key === "Home") return { kind: "fit" };
   if (lower === "a" && event.shiftKey) return { kind: "animateToggle" };
-  // ── BLENDER'S SELECTION KEYS ──────────────────────────────────────────
+  // ── BLENDER'S SELECTION KEY ───────────────────────────────────────────
   //
-  // Bare `A` selects all and `⌥A` deselects, which is muscle memory a Blender
-  // user brings with them. `A` was free; the alt lane handles its partner.
-  // `⌥A` must be its own action rather than reusing Escape's lane, because
-  // Escape also LEAVES A SUBTREE and deselecting must not.
+  // Bare `A` selects all, which is muscle memory a Blender user brings with
+  // them. Its partner is ⌘⇧A in lane 2a, its own action rather than Escape's,
+  // because Escape also LEAVES A SUBTREE and deselecting must not.
   if (lower === "a" && !event.shiftKey) return { kind: "selectAll" };
   // `B` arms a one-shot box select. Stage-local: the letter still has one owner
   // here, and the stage reads the armed bit beside `e.shiftKey` in its own
@@ -507,10 +1280,17 @@ export function resolveKey(event: KeyEventLike, context: KeyContext): KeyAction
   //
   // `toggleFlag` reads `selection[0]`'s own flag, so after hiding five layers
   // one at a time there was NO key that brought them back — the selection was
-  // gone with them. Explicit verbs fix that: H hides, ⌥H reveals everything,
-  // ⇧H hides everything else. The outliner's eye button keeps the toggle.
-  if (lower === "h" && !event.shiftKey && !event.altKey) return { kind: "setHidden", scope: "selection" };
-  if (lower === "h" && event.shiftKey) return { kind: "setHidden", scope: "others" };
+  // gone with them. Explicit verbs fix that: H hides, ⌘⇧H reveals everything
+  // (lane 2a), ⌥⇧H hides everything else (lane 2b). The outliner's eye button
+  // keeps the toggle.
+  if (lower === "h" && !event.shiftKey)
+    return { kind: "setHidden", scope: "selection" };
+  // ⇧H / ⇧V FLIP, Figma's keys. Only with a selection, so with none both stay
+  // free for the browser.
+  if (event.shiftKey && context.hasSelection) {
+    if (lower === "h") return { kind: "flip", axis: "x" };
+    if (lower === "v") return { kind: "flip", axis: "y" };
+  }
   // ⇧Z IS THE WIREFRAME TOGGLE, matching Blender. It used to fit the active
   // pane, which `Home` already does and which is the Blender-correct key for
   // it — so the letter was spent on a duplicate.
@@ -525,36 +1305,292 @@ export function resolveKey(event: KeyEventLike, context: KeyContext): KeyAction
   // key. The `+ shot` button in the dock is where an author looks for a move,
   // and it is still there.
   if (lower === "c" && event.shiftKey) return { kind: "fit" };
+  // BARE C ARMS THE COMMENT TOOL (S5): the next click on the camera pane
+  // leaves a Studio comment at the playhead. On the board the same key
+  // comments on the selected card.
+  if (lower === "c" && !event.shiftKey) return { kind: "storyboardComment" };
   // BARE M drops a marker, which is the binding Premiere, Resolve and Final Cut
   // all ship. Guarded to bare rather than left open, because ⇧M is "go to the
   // next marker" in the same three tools and this chrome does not have that
   // verb yet — claiming the shifted letter now would make it unavailable later
   // without breaking somebody's muscle memory twice.
   if (lower === "m" && !event.shiftKey) return { kind: "addMarker" };
+  // Q AND W TRIM TO THE PLAYHEAD: Premiere's letters, without the ripple. Bare
+  // and selection only: neither letter is a tool (`toolForKey`), and with
+  // nothing selected both stay free.
+  if (!event.shiftKey && (context.hasSelection || context.hasAudioSelection === true)) {
+    if (lower === "q") return { kind: "trimToPlayhead", edge: "in" };
+    if (lower === "w") return { kind: "trimToPlayhead", edge: "out" };
+  }
 
-  // THE MODAL STARTERS, checked immediately before the tool table so bare G
-  // and R shadow the move/rect tools ONLY with the cursor over the working
+  // THE MODAL STARTERS, checked immediately before the tool table so bare G, R
+  // and S shadow the move/rect tools ONLY with the cursor over a 3D working
   // pane. Blender's letters, Blender's scope: a transform needs an anchor
   // under the cursor, so from a panel or the camera pane the letters keep
-  // arming tools exactly as before. `R` additionally requires a selection —
-  // with nothing selected G/S address the CAMERA (the stage decides that from
-  // the same selection), but the camera has no modal roll, so R falls through
-  // to the rect tool rather than claiming a dead key.
-  if (context.workingPane === true && !event.shiftKey) {
+  // arming tools exactly as before.
+  //
+  // ── R NO LONGER NEEDS A SELECTION ──────────────────────────────────────
+  //
+  // With nothing selected all three address the CAMERA (the stage decides that
+  // from the same selection), and the camera now HAS a modal roll — so R is
+  // symmetric with G and S rather than falling through to the rect tool.
+  //
+  // THIS TAKES A KEY FROM THE RECT TOOL, deliberately and only here: R still
+  // arms rect over the camera pane, over every panel and from the toolbar. The
+  // trade is that roll was otherwise unreachable by any gesture at all (the
+  // frustum gizmo has no grip for it — see `framingDeltaFor`), and an
+  // unreachable channel costs more than one shadowed letter in one pane.
+  //
+  // ── BUT NOT OVER A DEFINITION'S FRAME ─────────────────────────────────
+  //
+  // Inside a definition the stage draws one working pane, and it is the frame
+  // the tools draw on (`framePane`), so the trade above does not hold there:
+  // the starters would shadow R over the whole stage while the footer says
+  // "Rect (R)", and the camera roll they bought does not exist. A letter a
+  // tool claims keeps its tool over the frame. Today that is R alone, so G
+  // and S keep their modals.
+  if (
+    context.workingPane === true &&
+    !event.shiftKey &&
+    !(context.framePane === true && toolForKey(lower) !== null)
+  ) {
     if (lower === "g") return { kind: "modalStart", mode: "move" };
     if (lower === "s") return { kind: "modalStart", mode: "scale" };
-    if (lower === "r" && context.hasSelection) return { kind: "modalStart", mode: "rotate" };
+    if (lower === "r") return { kind: "modalStart", mode: "rotate" };
   }
 
+  // ⇧S OPENS THE STORYBOARD from the ordinary shell. Unclaimed by every tool
+  // (`toolForKey` binds ⇧L and ⇧P, never ⇧S) and by the modal starters above,
+  // which read the bare letter only.
+  if (lower === "s" && event.shiftKey) return { kind: "storyboardToggle" };
+  // ⇧R IS THE RULERS, for the same reason: the modal starters and the tool
+  // table read bare R only.
+  if (lower === "r" && event.shiftKey) return { kind: "rulersToggle" };
+
   const tool = toolForKey(lower, event.shiftKey);
   return tool === null ? null : { kind: "tool", tool };
 }
 
+/**
+ * The storyboard's lane, as its own function so lane 1f reads as one line.
+ * `"pass"` keeps undo, redo, save, the app menu and SPACE, which plays.
+ * `null` blanks every tool letter and modal starter.
+ *
+ * THE ARROWS DO NOTHING HERE: a focused strip or Story card walks with them
+ * and stops them there, and a card has no position to nudge.
+ */
+function storyboardKey(
+  event: KeyEventLike,
+  key: string,
+  lower: string,
+  mod: boolean,
+): KeyAction | null | "pass" {
+  if (mod) {
+    switch (lower) {
+      case "z":
+      case "y":
+      case "s":
+      case "k":
+        return "pass";
+      case "a":
+        return { kind: "storyboardSelectAll" };
+      case "d":
+        return { kind: "storyboardDuplicate" };
+      // THE CLIPBOARD, AND ITS ARM RETURNS FALSE ON PURPOSE. See the union.
+      // Native DOM copy / cut / paste handlers do the work, and they are the
+      // only route by which a pasted PNG can reach the board.
+      case "c":
+      case "x":
+      case "v":
+        return { kind: "storyboardClipboard" };
+      default:
+        return arrangeNowhere(event, lower);
+    }
+  }
+  if (event.altKey) return null;
+  const comment = commentKey(event, lower);
+  if (comment !== null) return comment;
+  if (key === " ") return "pass";
+  if (key === "Delete" || key === "Backspace") return { kind: "storyboardDelete" };
+  if (key === "Escape") return { kind: "storyboardEscape" };
+  if (key === "F2") return { kind: "storyboardRename" };
+  // `/` passes through: the board has no search field of its own.
+  if (key === "/") return "pass";
+  if (lower === "s" && event.shiftKey) return { kind: "storyboardToggle" };
+  return null;
+}
+
+/**
+ * THE SHOT BOARD'S SKETCH KEYS: the arrows move the selected items (Shift:
+ * 10), `[` and `]` restack one step, Enter edits the one text item selected,
+ * and V T R A I C arm its tools. Bare C is Component there, not Comment: a
+ * sketch has no card to comment on.
+ *
+ * THEIR OWN UNION AND THEIR OWN RESOLVER, outside `KeyAction`: only the shot
+ * board's element answers them (ShotBoard.tsx) and stops them there, so an
+ * arrow pressed in the inspector moves nothing. The store's `handleKey` never
+ * meets one, and its dispatch stays exhaustive over `KeyAction`.
+ */
+export type SketchKeyAction =
+  | { kind: "sketchMove"; dx: number; dy: number }
+  | { kind: "sketchRestack"; by: 1 | -1 }
+  | { kind: "sketchEdit" }
+  | { kind: "sketchTool"; tool: SketchTool };
+
+/** A key on a shot board: its sketch lane first (bare or shifted, never with
+ *  ⌘ or ⌥, never into a field), then the board's own lane. */
+export function resolveShotBoardKey(event: KeyEventLike, context: KeyContext): KeyAction | SketchKeyAction | null {
+  if (!context.editing && !event.ctrlKey && !event.metaKey && !event.altKey) {
+    const sketch = sketchKey(event, event.key, event.key.toLowerCase());
+    if (sketch !== null) return sketch;
+  }
+  return resolveKey(event, { ...context, storyboard: true });
+}
+
+const SKETCH_TOOL_KEYS: Readonly<Record<string, SketchTool>> = {
+  v: "select",
+  t: "text",
+  r: "box",
+  a: "arrow",
+  i: "image",
+  c: "component",
+};
+const ARROW_STEPS: Readonly<Record<string, readonly [number, number]>> = {
+  ArrowLeft: [-1, 0],
+  ArrowRight: [1, 0],
+  ArrowUp: [0, -1],
+  ArrowDown: [0, 1],
+};
+
+function sketchKey(event: KeyEventLike, key: string, lower: string): SketchKeyAction | null {
+  const step = ARROW_STEPS[key];
+  if (step !== undefined) {
+    const by = event.shiftKey ? 10 : 1;
+    return { kind: "sketchMove", dx: step[0] * by, dy: step[1] * by };
+  }
+  if (key === "[") return { kind: "sketchRestack", by: -1 };
+  if (key === "]") return { kind: "sketchRestack", by: 1 };
+  if (key === "Enter") return { kind: "sketchEdit" };
+  const tool = event.shiftKey ? undefined : SKETCH_TOOL_KEYS[lower];
+  return tool === undefined ? null : { kind: "sketchTool", tool };
+}
+
+/** The comment keys: bare C (Shift+C stays "fit"), N and Shift+N. */
+function commentKey(event: KeyEventLike, lower: string): KeyAction | null {
+  if (lower === "c" && !event.shiftKey) return { kind: "storyboardComment" };
+  if (lower === "n") return { kind: event.shiftKey ? "storyboardPrevThread" : "storyboardNextThread" };
+  return null;
+}
+
+/**
+ * The graph canvas's lane, as its own function so lane 1e reads as one line.
+ *
+ * `"pass"` means "this key is not mine, keep walking the ordinary lanes" and is
+ * reserved for the four that must survive a context change: ⌘Z, ⌘⇧Z / ⌘Y, ⌘S
+ * and ⌘K. Everything else in this lane is either a graph verb or `null`.
+ *
+ * SPACE USED TO BE A FIFTH, and is not any more. Over this canvas it is
+ * hold-to-pan, which React Flow implements on its OWN window listener — so the
+ * lane has to return `null` rather than `"pass"`: `null` means `handleKey`
+ * reports the key unhandled and never calls `preventDefault`, which is exactly
+ * what lets that listener see it. Play/pause is untouched everywhere else in
+ * the workspace, including the dock right below this canvas.
+ *
+ * THE NULL RETURN IS THE POINT elsewhere too. Bare letters reach the tool table
+ * at the bottom of `resolveKey`, and a graph canvas has no rectangle to draw and
+ * no pen to arm — an `R` that silently armed the rect tool would leave the
+ * author back on the stage with a tool they never chose, several clicks later.
+ */
+function materialGraphKey(
+  event: KeyEventLike,
+  key: string,
+  lower: string,
+  mod: boolean,
+): KeyAction | null | "pass" {
+  if (mod) {
+    switch (lower) {
+      // The four that mean the same thing everywhere in this chrome.
+      case "z":
+      case "y":
+      case "s":
+      case "k":
+        return "pass";
+      case "d":
+        return { kind: "graphDuplicate" };
+      case "c":
+        return { kind: "graphCopy" };
+      case "x":
+        return { kind: "graphCut" };
+      case "v":
+        return { kind: "graphPaste" };
+      case "a":
+        return { kind: "graphSelectAll" };
+      case "g":
+        return event.shiftKey
+          ? { kind: "graphUngroup" }
+          : { kind: "graphGroup" };
+      default:
+        // An unclaimed combo belongs to the BROWSER, exactly as in lane 2a,
+        // which claims Arrange's brackets, and so does this lane.
+        return arrangeNowhere(event, lower);
+    }
+  }
+  // The alt lane's verbs are all about layers and the working view, and none of
+  // them has a meaning over a node. Blanked rather than passed, so ⌥G cannot
+  // clear a mesh's position from inside the graph.
+  if (event.altKey) return null;
+
+  // SPACE BELONGS TO REACT FLOW HERE — hold-to-pan, on its own window
+  // listener. `null` and not `"pass"`: see the header. Play/pause keeps the
+  // key everywhere in this workspace that is not this canvas.
+  if (key === " ") return null;
+  // TAB and ⇧A both open the palette: Tab is what Blender's and Unreal's node
+  // editors bind, ⇧A is Blender's Add menu, and an author arrives with one or
+  // the other in their fingers. Tab is not a focus trap here because the canvas
+  // has no tabbable content of its own; the panels around it still do.
+  if (key === "Tab") return { kind: "graphPalette" };
+  if (lower === "a" && event.shiftKey) return { kind: "graphPalette" };
+  if (key === "Delete" || key === "Backspace") return { kind: "graphDelete" };
+  if (lower === "d" && event.shiftKey) return { kind: "graphDuplicate" };
+  if (key === "Enter") return { kind: "graphEnter" };
+  if (lower === "p" && !event.shiftKey) return { kind: "graphPreviewToggle" };
+  // HOME is this chrome's "frame all" and `F` is what every node editor binds.
+  // Both, because the graph is the one surface an author reaches from muscle
+  // memory built somewhere else.
+  if (key === "Home" || (lower === "f" && !event.shiftKey))
+    return { kind: "graphFrame" };
+  // T for TIDY. A bare letter this lane used to blank; it is the one arrangement
+  // key a node editor is expected to have, and there is no tool for it to
+  // collide with because this canvas arms none.
+  if (lower === "t" && !event.shiftKey) return { kind: "graphTidy" };
+  const arrow = ARROWS[key];
+  if (arrow !== undefined) {
+    const step = event.shiftKey ? GRAPH_NUDGE_COARSE_PX : GRAPH_NUDGE_PX;
+    return { kind: "graphNudge", dx: arrow[0] * step, dy: arrow[1] * step };
+  }
+  if (key === "Escape") return { kind: "graphEscape" };
+  return null;
+}
+
 /** Is the event target something the author is typing into? Exported because
  *  both documents ask it and neither should re-derive it. */
 export function isEditable(target: EventTarget | null): boolean {
-  if (target === null || typeof (target as HTMLElement).tagName !== "string") return false;
+  if (target === null || typeof (target as HTMLElement).tagName !== "string")
+    return false;
   const el = target as HTMLElement;
   if (el.isContentEditable) return true;
-  return el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.tagName === "SELECT";
+  return (
+    el.tagName === "INPUT" ||
+    el.tagName === "TEXTAREA" ||
+    el.tagName === "SELECT"
+  );
+}
+
+/** Is the target a control the keyboard focused, which Enter and Space press?
+ *  Not part of `isEditable`: a focused button does not own letters or Delete. */
+export function ownsActivation(target: EventTarget | null): boolean {
+  if (target === null || typeof (target as HTMLElement).matches !== "function") return false;
+  return (target as HTMLElement).matches(
+    'button:focus-visible, [role="menuitem"]:focus-visible, [role="option"]:focus-visible, [role="tab"]:focus-visible, [role="radio"]:focus-visible',
+  );
 }