Keyboard shortcuts#

PacketBench binds keys on several surfaces at once: an app-shell listener on window, a per-view listener, a per-pane listener, and — when you opt in — three accelerators registered with the operating system. Most of the time only one of them can plausibly want a keypress. The interesting cases are the ones where two can, and those are decided by explicit checks in the code rather than by listener order.

This page lists every binding PacketBench ships, grouped by the surface that owns it, and then states the precedence rules that decide which surface consumes a key when more than one is listening.

Ordering. Within each table, rows appear in source order — the order the owning handler tests them — so the table reads in the same sequence the code executes. The view-switch table follows declaration order in src/lib/routeRegistry.ts. Nothing here is alphabetical.

Global#

Bound on window at the app shell, so they are live on every view. src/hooks/useGlobalShortcuts.ts:29-88 owns the first four; src/hooks/useAgentTabHoists.ts:37-70 and src/hooks/useSideChatHotkey.ts:11-24 own the rest, each in its own listener.

View switching#

Every view-switch chord is declared once, in the route registry, and every consumer — the left rail, the status strip, the command palette — derives its label from the same row. Adding a shell route without a registry entry is a compile error (src/lib/routeRegistry.ts:104-110).

Three shell routes carry no chord and are reachable only from the rail or the palette: Memory (src/lib/routeRegistry.ts:182), Git Hosts (:197) and the Welcome screen (:106). That is a deliberate absence, not an oversight — the number row ran out at six and the registry makes an unbound route a one-line row rather than a missing case.

Workspace and terminal panes#

The bare y / n / Esc approval keys are bound on window by every pane that is waiting, so a single press reaches all of them and preventDefault cannot stop a sibling. Rather than fight that, each handler decides whether the press is addressed to it, in this order (src/hooks/useApprovalShortcuts.ts:36-50):

The composer#

One handler serves both composer variants — the chat composer and the launch composer (src/components/agents/composer/buildComposerKeyboardHandler.ts:51-188). Rows are in the order the handler tests them, which is also their precedence.

While either popover is open, Enter and Tab are always swallowed. A half-typed @query whose directory scan has not landed, or an unmatched /xyz, is never sent as a literal message by the same keystroke that was meant to complete it; an empty list dismisses the popover so the next Enter submits.

Agent approvals and review#

These listen on document, not window, and each is gated by a per-tile focus flag so only one conversation tile in a workspace mosaic answers a press.

The edit handler stays passive while any permission is pending (PendingApprovalsSection.tsx:73, ReviewBar.tsx:72): both bind y and n, so permissions are answered first and only then do the same two keys mean apply/reject.

Dictation#

Three accelerators are registered with the operating system, and only when Settings → Integrations & Data → Dictation → Global dictation shortcuts is on. PacketBench unregisters only what it successfully registered itself; an existing OS or application binding is reported as a conflict, never taken over (src/hooks/useDictationGlobalShortcuts.ts:43-53, :147-153).

All three accelerators are stored as @tauri-apps/plugin-global-shortcut strings using CommandOrControl, which resolves to Cmd on macOS and Ctrl elsewhere (src/components/views/tools/KeyboardShortcutsCard.tsx:271-277). They must all differ from each other, including the fixed open shortcut (src/types/dictation.ts:253-265).

The toggle carries a 400 ms repeat guard. Win32 RegisterHotKey delivers repeated WM_HOTKEY messages while a key is held with no intervening release, so an unguarded toggle would start a capture and stop it again on the next repeat, transcribing a fraction of a second (src/hooks/useDictationGlobalShortcuts.ts:35-41).

Modals, palettes and lists#

Rebinding#

Settings → Integrations & Data → Keyboard Shortcuts owns the global dictation accelerators and nothing else. Every other binding on this page is in-app and is not editable.

Capture listens on the row's own DOM node in the capture phase, not on window, so a simultaneous interaction elsewhere in Settings cannot rebind the shortcut by accident (KeyboardShortcutsCard.tsx:153-155).

Precedence#

Four mechanisms decide who consumes a key. They are listed here in the order they take effect.

The handled flag unwinds one layer at a time#

Every window-level handler returns early on e.defaultPrevented (src/hooks/useGlobalShortcuts.ts:34, src/components/ui/Modal.tsx:92, src/components/workspace/WorkspaceMosaicContainer.tsx:107, src/hooks/useApprovalShortcuts.ts:69). An inner surface that has already acted — xterm, an open dropdown, an inline field editor, the palette's own list — marks the press handled, and one press unwinds exactly one layer.

The flag alone is not enough, and the code says why. Listeners fire in registration order, and the zoom-exit listener registers when a pane is zoomed, which is before any dialog opened afterwards registers its own. Zoom therefore ran first, called preventDefault, and Modal then bailed on exactly the flag zoom had just set: zooming a pane and opening any dialog meant Esc closed the zoom and left the dialog open (src/components/workspace/WorkspaceMosaicContainer.tsx:88-97). The explicit checks in the next two sections are what actually order the layers.

Focus classification decides who yields#

src/lib/keyboardTarget.ts is the single definition of "the user is typing", and every global listener routes its guard through it rather than re-deriving a tag check.

xterm renders a focus-holding <textarea> inside its container, so a focused terminal trips the tag check on its own; the container lookup additionally covers keydowns raised on the viewport or canvas before that textarea takes focus (src/lib/keyboardTarget.ts:21-28).

Escape has a fixed ladder#

More surfaces want Esc than want any other key. From highest priority to lowest:

Rank 6 is scoped for a reason worth knowing: reviewStore.open is a global flag that nothing resets on a view change, so an unscoped read left Esc permanently dead after opening a review in Agents and switching to Workspace — with the un-exitable zoom and the on-screen "Press Esc" hint both still showing (src/components/workspace/WorkspaceMosaicContainer.tsx:114-121).

Nested dialogs order by React nesting depth first and registration order second. Depth has to lead: React runs child effects before parent effects, so a dialog rendered inside another dialog's children registers first, and raw ordering would get that case exactly backwards (src/lib/modalStack.ts:15-18).

Chords match the physical key, not the character#

resolveViewHotkey compares KeyboardEvent.code against the registry's code field before it falls back to the shifted glyph (src/lib/routeRegistry.ts:356-365). Physical Digit1 resolves to Agents on AZERTY, QWERTZ and Dvorak, where the same position reports & or 1 rather than !. The shifted-glyph map survives only as a fallback for events that do not carry code, and only for the number-row chords — the mnemonic letter chords never had glyph entries (src/lib/viewHotkeys.ts:16-22).

Chords also yield to an open dialog, which focus classification alone would not catch: switching view unmounts the outgoing view, and takes any open dialog and its half-typed form down with it (src/hooks/useGlobalShortcuts.ts:77-79, src/lib/modalStack.ts:57-59).

Two tiles, one keypress#

Approval keys are bound at document level, so every mounted conversation tile would answer a single press. Exactly one handler may be live per tile, and it is armed by keyboardScopeActive: undefined means there is no pane context — the standalone Agents view — and the handler arms as before; defined means it arms only for the focused tile (src/components/agents/chat/PendingApprovalsSection.tsx:36-43, src/components/workspace/ConversationTile.tsx:244). The cards themselves moved into the transcript; the handler deliberately did not move with them (src/components/agents/chat/InlineApprovals.tsx:42-53).

Gaps and asymmetries#

These are real, present in 0.13.1, and documented rather than smoothed over.

Related#

• Workspaces & terminals — pane zoom, the approval overlay and the ownership rule in context
• Dictation & analytics — what the three accelerators actually do once recording starts
• Settings — the Keyboard Shortcuts card and where it lives
• Flight Deck — the launch dialog that owns Ctrl+Enter
• Issues & git hosts — the board reached by Ctrl+Shift+3
• Architecture internals — where the app shell's listeners are mounted