@dailies-studio/shot-editor 0.1.0

package/src/state/keymap.ts

@@ -0,0 +1,560 @@
+// The keymap, as a PURE function from a key event to an action.
+//
+// Pure so it can be walked as a table by a test, and so "what does this key do"
+// has exactly one answer that a reader can find. The store turns actions into
+// document edits; nothing else in this chrome may bind a key.
+//
+// ── THE ONE ORDERED RULE ─────────────────────────────────────────────────
+//
+//   1. A field being typed into wins. Always, before anything else is even
+//      considered.
+//   1b. A pen path in progress owns Enter and Escape, and only those two.
+//   1c. A LIVE MODAL TRANSFORM owns its terminators and axis keys, pen-style,
+//      and blanks every other bare key so a tool cannot arm mid-modal.
+//   1d. NUMPAD codes resolve as working-view verbs, BEFORE the modifier lanes
+//      because ⌘Numpad1 is "back view", not a browser combo.
+//   2. MODIFIER COMBOS resolve next: ctrl/meta first, then alt.
+//   3. Bare and shifted letters resolve LAST, and `toolForKey` is consulted
+//      only when `!ctrl && !meta && !alt` — with the working pane's modal
+//      starters (G/R/S) checked immediately before it.
+//
+// That order is what lets `Z`, `⇧Z`, `⌘Z`, `⌘⇧Z` and z-as-axis mean five
+// different things without any of them shadowing another. Reverse it — check
+// the letter first — and `⌘Z` arms whatever tool `Z` is bound to before undo
+// is ever reached.
+//
+// ── THREE AMBIGUITIES IN RAYLIGHT'S PUBLISHED LIST, RESOLVED ────────────
+//
+//   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.
+//
+//   `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`).
+//
+//   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 type { ShotTool } from "../tools.js";
+import type { StageLayout } from "../stage/panes.js";
+import { ORBIT_STEP_DEG } from "../stage/workingView.js";
+
+export type KeyAction =
+  | { kind: "tool"; tool: ShotTool }
+  | { kind: "undo" }
+  | { kind: "redo" }
+  | { kind: "save" }
+  | { kind: "playToggle" }
+  /** Move the playhead by whole frames. */
+  | { kind: "step"; delta: number }
+  /** Move the selection, in design px. */
+  | { kind: "nudge"; dx: number; dy: number }
+  | { 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
+   *  never a pane. */
+  | { 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. */
+  | { kind: "stageLayout"; mode: StageLayout["mode"]; toggle?: boolean }
+  /** Point the shot camera where the working pane is looking. */
+  | { kind: "alignCameraToView" }
+  /** Drop a marker at the playhead. */
+  | { kind: "addMarker" }
+  /** Hide a side rail, or every panel at once. */
+  | { kind: "togglePanel"; panel: "rail" | "inspector" | "all" }
+  | { kind: "animateToggle" }
+  | { kind: "openExport" }
+  | { kind: "deleteSelection" }
+  | { kind: "duplicate" }
+  | { kind: "selectAll" }
+  | { kind: "deselect" }
+  | { kind: "splitAtPlayhead" }
+  | { kind: "group" }
+  | { kind: "ungroup" }
+  | { kind: "toggleLock" }
+  | { kind: "toggleHidden" }
+  /** Finish the path the pen is drawing, keeping it. */
+  | { kind: "penCommit" }
+  /** Throw away the path the pen is drawing. */
+  | { kind: "penAbandon" }
+  /** Edit the selected layer's subtree alone. */
+  | { kind: "enterIsolation" }
+  /** Come back up ONE level. */
+  | { kind: "exitIsolation" }
+  /** 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" }
+  /** 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. */
+  | { kind: "modalNumber"; ch: string }
+  /** Backspace over that buffer; emptying it hands the transform back to the
+   *  mouse, which is what makes a mistyped digit recoverable. */
+  | { kind: "modalNumberBack" }
+  | { kind: "modalConfirm" }
+  | { kind: "modalCancel" }
+  /** Cycle the working pane's shading (solid → wireframe → material →
+   *  rendered). The camera pane is always the graded render. */
+  | { kind: "shadingCycle" }
+  /** Snap the working camera to an axis view, Blender numpad style. */
+  | {
+      kind: "workingViewPreset";
+      preset: "front" | "back" | "right" | "left" | "top" | "bottom";
+    }
+  /** Frame the selection in the working view (numpad-dot). */
+  | { kind: "fitSelection" }
+  /** Orbit the working view by a fixed number of DEGREES, numpad 2/4/6/8 and
+   *  the half turn on 9. Degrees rather than pixels, so the step means the same
+   *  thing whatever `ORBIT_DEG_PER_PX` is. */
+  | { kind: "orbitStep"; dx: number; dy: number }
+  /** Numpad-slash: Blender's local view, which is this editor's isolation. In
+   *  or out, decided by where the author already is. */
+  | { kind: "toggleIsolation" }
+  /** Numpad-5: the working camera's own projection. Editor state, no schema. */
+  | { kind: "toggleWorkingOrtho" }
+  /** Bare B: arm a one-shot box select, Blender's own. Consumed by the STAGE,
+   *  which reads it beside `e.shiftKey` in its marquee lane. */
+  | { kind: "boxSelect" }
+  /**
+   * 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
+   * 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. */
+  | { kind: "clearTransform"; channel: "offset" | "rotation" | "scale" }
+  /** ⇧Z: wireframe on, and back to whatever the shading was. Blender's. */
+  | { kind: "wireframeToggle" };
+
+/** 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. */
+export interface KeyContext {
+  /** The event target is a field, a textarea or a contenteditable. */
+  editing: boolean;
+  hasSelection: boolean;
+  /**
+   * The pen HOLDS AT LEAST ONE POINT — not "the path tool is armed".
+   *
+   * The distinction is the whole reason this field exists. Escape with a
+   * half-drawn path must abandon the path and nothing else; Escape with the
+   * pen armed but empty must still mean deselect, exactly as it did before
+   * the pen had a keymap entry. Defining this as "tool === path" would take
+   * Escape away from the chrome for as long as the tool was armed, which is
+   * a regression a keymap test would then happily pin as intended.
+   *
+   * Absent counts as false, so every caller that has no pen keeps today's
+   * answers.
+   */
+  penActive?: boolean;
+  /** 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;
+  /**
+   * 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
+   * 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;
+  /** A modal transform is LIVE. Owns its terminator and axis keys, the way
+   *  `penActive` owns Enter/Escape. Absent = false. */
+  transformModal?: boolean;
+}
+
+export interface KeyEventLike {
+  key: string;
+  shiftKey: boolean;
+  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. */
+  code?: string;
+}
+
+/** How far a plain arrow moves a layer, and how far a shifted one does. Design
+ *  px, so the nudge is the same size at every zoom — a nudge that scaled with
+ *  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;
+
+/**
+ * The view-mode digits, LEFT TO RIGHT as the toolbar draws them.
+ *
+ * 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.
+ */
+const LAYOUT_KEYS: Readonly<Record<string, StageLayout["mode"]>> = {
+  "1": "working",
+  "2": "split",
+  "3": "camera",
+};
+
+const ARROWS: Readonly<Record<string, readonly [number, number]>> = {
+  ArrowLeft: [-1, 0],
+  ArrowRight: [1, 0],
+  ArrowUp: [0, -1],
+  ArrowDown: [0, 1],
+};
+
+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.
+  if (context.editing) return null;
+
+  const key = event.key;
+  const lower = key.length === 1 ? key.toLowerCase() : key;
+  const mod = event.metaKey || event.ctrlKey;
+
+  // 1b. A PATH IN PROGRESS owns Enter and Escape, and only those two.
+  //
+  //     Above every other lane because both keys already mean something here
+  //     (Escape deselects, Enter is unclaimed) and a half-drawn path is the
+  //     more local subject: an author pressing Escape mid-path is abandoning
+  //     the path, not their selection. Two keys and no more, so everything
+  //     else still reaches the chrome while the pen is up.
+  if (context.penActive === true && !mod) {
+    if (key === "Enter") return { kind: "penCommit" };
+    if (key === "Escape") return { kind: "penAbandon" };
+  }
+
+  // 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
+  //     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
+  //     is live, and that suppression is the listener's to own, not this
+  //     table's to hide.
+  //
+  //     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
+  //     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" };
+    // 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" };
+    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
+    // TABLE rather than being intercepted inside the modal's own listener,
+    // because this file's header says nothing else in this chrome may bind a
+    // key — and a lane that quietly claimed the digits would make that false.
+    //
+    // `-` toggles the sign the way Blender's does, and `.` starts a decimal.
+    if (/^[0-9.-]$/.test(key)) return { kind: "modalNumber", ch: key };
+    if (key === "Backspace") return { kind: "modalNumberBack" };
+    return null;
+  }
+
+  // 1d. NUMPAD, by `code` and not by `key`, which is what makes it NumLock-
+  //     agnostic the way Blender's is: NumLock-off Numpad7 reports key "Home"
+  //     but code "Numpad7", and it should mean "top view" either way. Before
+  //     the modifier lanes because ⌘Numpad1 is "back view", not a browser
+  //     combo.
+  if (event.code !== undefined && event.code.startsWith("Numpad")) {
+    switch (event.code) {
+      case "Numpad1":
+        return { kind: "workingViewPreset", preset: mod ? "back" : "front" };
+      case "Numpad3":
+        return { kind: "workingViewPreset", preset: mod ? "left" : "right" };
+      case "Numpad7":
+        return { kind: "workingViewPreset", preset: mod ? "bottom" : "top" };
+      case "Numpad9":
+        // Blender's "look from the opposite side": a half turn of the azimuth,
+        // which is the one preset that is relative rather than absolute.
+        if (!mod) return { kind: "orbitStep", dx: 180, dy: 0 };
+        break;
+      case "Numpad2":
+      case "Numpad4":
+      case "Numpad6":
+      case "Numpad8": {
+        // ORBIT BY A FIXED STEP, Blender's own 15 degrees. The arrows around
+        // the 5 turn the view the way dragging would, which is what makes the
+        // numpad usable for a precise angle without a mouse at all.
+        //
+        // The magnitude lives in `workingView.ts` beside `ORBIT_DEG_PER_PX`,
+        // never here: a keymap that invented its own step would be a second
+        // opinion on how far a turn is.
+        // NUMLOCK ON ONLY, which `key.length === 1` is this file's test for.
+        // With NumLock off these four report "ArrowLeft" / "ArrowUp" and so on,
+        // and the lane below deliberately lets those FALL THROUGH to keep their
+        // `key` meanings — an arrow nudges the selection, and stealing that for
+        // an orbit would take the nudge away from anyone using the numpad as a
+        // cursor pad.
+        if (mod || key.length !== 1) break;
+        const step: Record<string, { dx: number; dy: number }> = {
+          Numpad4: { dx: -1, dy: 0 },
+          Numpad6: { dx: 1, dy: 0 },
+          Numpad8: { dx: 0, dy: -1 },
+          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 };
+      }
+      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 };
+        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 };
+        break;
+      case "NumpadDivide":
+        // LITERALLY Blender's local view. Ours is isolation, and the two mean
+        // the same thing now that the camera is handed over on the first
+        // gesture.
+        if (!mod) return { kind: "toggleIsolation" };
+        break;
+      case "NumpadDecimal":
+        if (!mod) return { kind: "fitSelection" };
+        break;
+      case "Numpad5":
+        if (!mod) return { kind: "toggleWorkingOrtho" };
+        break;
+    }
+    // An UNMODIFIED NumLock-on digit or operator (key length 1) stops here —
+    // otherwise Numpad2 would switch the stage layout because its key is "2".
+    // NumLock-off navigation keys (arrows, End, PageUp) and NumpadEnter have
+    // longer keys and FALL THROUGH to keep their `key` meanings.
+    //
+    // THE `!mod` IS LOAD-BEARING, and it is the whole reason this lane sits
+    // above the modifier lanes rather than being folded into them: ⌘Numpad+,
+    // ⌘Numpad− and ⌘Numpad0 are the zoom verbs, and swallowing them here left
+    // the browser to page-zoom the entire chrome instead. Only the numpad
+    // combos this lane actually CLAIMS (the view presets) may stop here.
+    if (!mod && key.length === 1) return null;
+  }
+
+  // 2a. ctrl / meta.
+  if (mod) {
+    switch (lower) {
+      case "z":
+        return event.shiftKey ? { kind: "redo" } : { kind: "undo" };
+      case "y":
+        return { kind: "redo" };
+      case "s":
+        return { kind: "save" };
+      case "d":
+        return { kind: "duplicate" };
+      case "e":
+        // Export. The one destination-producing verb in the whole chrome, so
+        // it gets the letter rather than a chord.
+        return { kind: "openExport" };
+      case "a":
+        return { kind: "selectAll" };
+      case "b":
+        // Split at the playhead, and the ONLY splitter now that the cut tool is
+        // gone — see the header.
+        return { kind: "splitAtPlayhead" };
+      case "g":
+        return event.shiftKey ? { kind: "ungroup" } : { kind: "group" };
+      case "0":
+        return { kind: "zoomReset" };
+      case "=":
+      case "+":
+        return { kind: "zoom", direction: 1 };
+      case "-":
+        return { 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;
+    }
+  }
+
+  // 2b. alt.
+  if (event.altKey) {
+    switch (lower) {
+      case "l":
+        return { 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" };
+      case "a":
+        // Blender's deselect-all. Its own action and NOT Escape's lane, which
+        // also leaves a subtree.
+        return { kind: "deselect" };
+      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 ────────────────────────
+      //
+      // 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.
+      case "g":
+        return { kind: "clearTransform", channel: "offset" };
+      case "r":
+        return { kind: "clearTransform", channel: "rotation" };
+      case "s":
+        return { kind: "clearTransform", channel: "scale" };
+      default:
+        return null;
+    }
+  }
+
+  // 3. Bare and shifted.
+  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] };
+  }
+  const mode = LAYOUT_KEYS[key];
+  if (mode !== undefined) return { kind: "stageLayout", mode };
+  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" };
+  // 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
+  // own work is a chord too many. Every one has a button too (the header's
+  // panel toggles), because a keyboard-only affordance is undiscoverable.
+  if (key === "[") return { kind: "togglePanel", panel: "rail" };
+  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.
+  if (key === "Escape") {
+    if (context.hasSelection) return { kind: "deselect" };
+    if (context.isolation === true) return { kind: "exitIsolation" };
+    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" };
+  // 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 ──────────────────────────────────────────
+  //
+  // 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.
+  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
+  // marquee lane — no bridge message and no store verb.
+  if (lower === "b" && !event.shiftKey) return { kind: "boxSelect" };
+  // `⇧D` duplicates, Blender's own. A plain alias: `duplicateSelection` already
+  // offsets the copy and selects it, so Blender's duplicate-then-grab has no
+  // job here.
+  if (lower === "d" && event.shiftKey) return { kind: "duplicate" };
+  // ── THE HIDE TRIPLE ───────────────────────────────────────────────────
+  //
+  // `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" };
+  // ⇧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.
+  if (lower === "z" && event.shiftKey) return { kind: "wireframeToggle" };
+  // BARE Z cycles the working pane's shading — Blender's viewport-shading key.
+  // Fifth meaning on the letter: `⇧Z` fit, `⌘Z` undo, `⌘⇧Z` redo, z-as-axis
+  // in lane 1c, and this one — none shadowing another, by lane order alone.
+  if (lower === "z" && !event.shiftKey) return { kind: "shadingCycle" };
+  // ⇧C FRAMES EVERYTHING, matching Blender. It used to add a camera move at the
+  // playhead — so a Blender user reaching for "show me everything" WROTE THE
+  // DOCUMENT and autosaved it, which is the worst possible answer to a view
+  // 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 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" };
+
+  // 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
+  // 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) {
+    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" };
+  }
+
+  const tool = toolForKey(lower, event.shiftKey);
+  return tool === null ? null : { kind: "tool", tool };
+}
+
+/** 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;
+  const el = target as HTMLElement;
+  if (el.isContentEditable) return true;
+  return el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.tagName === "SELECT";
+}