[Frontend][Shortcuts] Board bare-letter bindings fire behind the open shell help dialog

[Chris0Jeky]

Found by the fresh-context review of PR #2615 (#2007 AC5/AC6); pre-existing on main, not introduced by that PR, which only adds a second entry point into the dialog and prints the two keys inside it.

Defect. With the shell keyboard-help dialog open over a Legacy board (ShellKeyboardHelp.vue, role="dialog" aria-modal="true"), a plain f or n still reaches the board. AppShell.vue (~252) returns without stopPropagation when hasActiveKeyboardOwningSurface() is true and no app-shell binding matched, so the keydown bubbles to BoardView's useKeyboardShortcuts listener (useKeyboardShortcuts.ts ~67): f toggles the filter panel behind the modal; n clicks [data-action="toggle-add-card"] (ColumnLane.vue ~247) and focuses the add-card input, pulling focus out of the open dialog. boardShortcutsEnabled (BoardView.vue ~473-475) gates the board bindings on Paper dialogs (the #1959 class) but not on the shell's own help surface.

Repro. Legacy skin, open any board, press ? (or the toolbar help button), press f: the filter panel toggles behind the dialog. Press n: focus leaves the dialog for the add-card input.

Acceptance.

• Board bare-letter bindings do not fire while the shell help dialog (either skin twin) is open; either the shell stops propagation for non-matching keys while a keyboard-owning surface is active, or boardShortcutsEnabled also tests the shell help state (the useShellKeyboardHelp seam from PR fix(shortcuts): retire the lying Legacy help dialog and stop the ledger chip clipping #2615 exposes it).
• A spec dispatching f and n from document.body with bubbles: true while the help dialog is open asserts neither handler ran and focus stays inside the dialog.
• ? and Escape keep toggling and closing the dialog.

Refs #2007, #1968, PR #2615.

[Chris0Jeky]

[Claude lane claim v2]
lane: alpha-product-trust (session taskdeck-alpha-85, Taskdeck-Alpha checkout)
issue: #2621 (closes) with the #1968 keyboard-guard LOWs recorded on 2026-08-29T18:08 (Refs #1968)
base: origin/main at claim time (5f2d3fa, after PR #2615)
residual acceptance: (a) #2621: board bare-letter bindings (f, n, and the J/K/H/L card navigation if it is live) do not fire while the shell help dialog (either skin twin) is open; today AppShell.vue (~252 at the base) returns without stopPropagation for a non-matching key while hasActiveKeyboardOwningSurface() is true, so the keydown bubbles to BoardView's useKeyboardShortcuts listener; fix at the shell (stop propagation for every key while a keyboard-owning surface is active, except the keys the surface itself handles) or at the board (boardShortcutsEnabled also tests the shell help state through the useShellKeyboardHelp seam from #2615), with a spec dispatching from document.body with bubbles true; ? and Escape keep toggling and closing. (b) #1968 LOW: ? and mod+k fire over an active modal because hasActiveKeyboardOwningSurface() gates navigate actions only; decide per key whether the surface owns it (a modal should not have the palette opened over it; ? toggling the help dialog itself is the exception) and pin it. (c) #1968 LOW: bare-letter bindings leave shift undefined so Shift+H also navigates; constrain shift to false for bare letters in strokeMatches or the binding declarations, with a spec. (d) #1968 LOW: on layouts where ? needs AltGr the browser reports altKey true and the binding is unreachable; accept altKey for the ? binding when the produced key is ? (event.key), with a spec. (e) #1968 LOW: PaperShortcutsOverlay.spec.ts asserts against appShellSource text; replace with a behavioural assertion. (f) #1968 LOW, optional if cheap: hasActiveKeyboardOwningSurface() runs querySelectorAll plus getComputedStyle on every keydown including while typing; short-circuit when the target is an editable element (the existing isInteractiveTarget helper) before the DOM scan. Not in this slice: #1968 AC4 (P and Space under the revision lock, D-5 ruling), #2007 AC2/AC3 (D-5), #1276 (useShortcutContext).
owned paths/modules: frontend/taskdeck-web/src/components/shell/AppShell.vue (keydown handler and hasActiveKeyboardOwningSurface); src/utils/keyboardShortcuts.ts (strokeMatches, binding declarations); src/composables/useKeyboardShortcuts.ts and src/views/BoardView.vue (boardShortcutsEnabled) only if the fix is placed at the board; src/composables/useShellKeyboardHelp.ts only to expose the open state; specs: src/tests/components/AppShell.spec.ts, src/tests/utils/keyboardShortcuts.spec.ts, src/tests/components/paper/PaperShortcutsOverlay.spec.ts, src/tests/views/BoardView*.spec.ts, src/tests/guards/shortcutLedgerTruth.spec.ts (must stay green)
shared-path leases: PR #2615 (AppShell.vue, BoardView.vue, keyboardShortcuts.ts, the shortcut specs) merged 5f2d3fa, so the seam is free; the #2571 worktree touches AppShell.vue for one resetForLogout line and AppShell.spec.ts for one mock entry (issue-2571/poll-truth-residuals, PR pending): this worktree merges origin/main after #2571 lands or resolves that one-line overlap at update time; the #2214 worktree (Review seam) is disjoint
parallel-safe work: #2571 (Inbox store plus the single AppShell line), #2630 (Review seam)
open PRs/branches/review threads checked: PR #2226 merged (ledger), PR #2615 merged (help retirement), #2596/#2594/#2595/#2607 (fourth-actor PRs, none on this seam); no open PR touches keyboardShortcuts.ts or the shell keydown handler
human or decision gates: none for (a) to (f); AC4 and AC2/AC3 wait on D-5
status: active (worktree codex-2621-shell-keyboard-guard, being created)

[Chris0Jeky]

[Claude lane release v2]
lane: alpha-product-trust
issue: #2621 (closed by the merge) and #1968 (Refs: the keyboard-guard LOWs recorded on 2026-08-29T18:08 are closed; AC4 waits on the D-5 ruling)
PR: #2635, exact head 019f932 (round-2 fix 8eb4010 plus a base update after #2631 touched AppShell.vue), merge commit 86ca907, merge commit not squash
disposition: Shipped: the shell stops keys no shell binding consumed while a keyboard-owning surface (an open native dialog, an alertdialog, or an ARIA dialog explicitly marked modal) is active, with two carve-outs (Escape never; a keydown whose target is inside the surface); per-action ownership through a data-shell-surface marker on both help twins and both command palettes, order-independent (a key is allowed when some open surface is the action's own and every open surface carries the marker; any unmarked surface takes every shell key), so ? toggles the help dialog it owns and never opens over another modal, mod+k closes the palette it owns and never opens over another modal, quick capture never stacks; strokeMatches requires Shift up for a bare-letter binding that declares none (Shift+H no longer navigates) but not for punctuation (? is typed with Shift on most layouts); a layout-produced ? ignores Alt, and Ctrl while Alt is also down, so AltGr layouts reach the help key; the keyboard-owning-surface scan is memoised per event so typing no longer sweeps the DOM; the overlay spec's source-text assertion is replaced by descriptor-driven assertions that can fail plus a walk over every shell binding through the mounted shell.
review: one fresh-context independent reviewer subagent, FIX-FIRST in round 1 (HIGH: the selector's bare role="dialog" branch counted the Paper desktop card inspector, which uses that role without aria-modal, as a keyboard-owning surface, so ?, mod+k and quick capture went dead while a card was open; two spec-harness MEDIUMs) fixed in round 2 with a red-first non-modal role="dialog" probe; one read-only verification pass scoped to the round-2 diff, SHIP with three LOWs recorded (dialog[open] would also match a non-modal native dialog, none exists; ? closes a background help dialog under a clicked-open palette, cosmetic; the ledger walk lacks a default arm). Evidence: AppShell.spec red first in round 1 (6 failed / 41 passed) and the non-modal probe red first in round 2; 18 files / 391 across the shell, shortcut, board and card specs; the whole unit suite 371 files / 5753 passed / 3 skipped; re-proved at the base-updated head with 14 files / 348; typecheck, build, ESLint, diff check; hosted CI green at the exact head.
NOT verified: Playwright; a physical AltGr or Shift+H in a real browser (proved against synthesized KeyboardEvent flags); the board probe in the shell spec uses the real useKeyboardShortcuts composable and the board's own bindings rather than a mounted BoardView; the Paper desktop inspector in a real browser.
tracked: #2636 (a key pressed with focus inside a shell surface still reaches page-level listeners; CaptureModal Tab-then-n scenario recorded there).
remaining on #1968: AC4 (P and Space under the revision lock) waits on D-5; the notation guard still misses spaced "Ctrl +" and "Control+" (different file, recorded on the issue on 2026-08-29).
CLAUDE_SYNC_PACKET: merged=#263586ca907 closes=#2621 refs=#1968,#2636 docs=STATUS thirteenth block (coordinator, in assembly) worktree=codex-2621-shell-keyboard-guard removed after this comment