Keybindings, focus, and input capture
One service owns the keyboard: packages/core/src/keymap/. It resolves a
keystroke to a command, knows which pane is focused, lets a pane take the keyboard
outright and give it back, ships defaults that work on each host, and exposes the
whole map to the user and to the agent.
Key specs
A spec is one or more +-separated strokes, separated by spaces. Modifier
tokens are mod (ctrl, or cmd on macOS), ctrl, meta, alt, shift; the last
token is the key. Modifiers match exactly — a spec that doesn't name alt
rejects an alt-chord, so mod+b and mod+alt+b bind independently.
| Spec | Meaning |
|---|---|
mod+k | Ctrl+K, or ⌘K on macOS |
alt+shift+left | arrow aliases: left/right/up/down, plus space, esc |
mod+k mod+s | a sequence — press one stroke, then the next |
code:KeyW | the physical key, whatever character it produces |
mod++ | the + key |
Two key identities, and why
A bare token matches the character the key produces (e.key). A code:
prefix matches the physical position (e.code).
Use code: for anything positional. w is the character W wherever it lives, so
a WASD binding written as characters scatters across an AZERTY keyboard; code:KeyW
stays under the same finger. Use the character form for mnemonic bindings (mod+s
for save), which should follow the user's layout.
One promotion is automatic: a digit or ASCII punctuation key combined with
shift resolves positionally, because e.key reports the shifted glyph.
shift+1 arrives as !, so a character spec for it could never match — this is
why mod+shift+1 silently never fired before.
labelSpec renders a spec for display (⌘K on macOS, Ctrl+K elsewhere),
resolving code: specs through navigator.keyboard.getLayoutMap() when available
so the label matches what is printed on the user's keys.
formatSpec writes the space key back as space, never as a literal ' '.
Strokes are space-separated, so ctrl+ would re-parse as ctrl++ — a stored
override for ctrl+space would corrupt on reload.
Conditions: the when clause
A binding may carry a when string over a closed vocabulary of context keys,
combined with &&, ||, !, ==, != and parentheses. The vocabulary is
closed on purpose: it fits on one screen, the Shortcuts pane can explain any
clause, and keymap.context can hand the agent the complete list so it cannot
invent a key that silently never matches.
| Key | Type | Meaning |
|---|---|---|
paneFocus | string | View id of the focused pane, e.g. editor.buffer |
paneInstance | string | Instance id of the focused pane (editor.buffer#3) |
capture | string | keyboard / pointer / full, or null |
captureView | string | View id holding capture |
textInput | boolean | An input/textarea/contenteditable holds DOM focus |
dialogOpen | boolean | A modal dialog is open |
fullscreenArea | boolean | A pane is presented over the whole shell (the name predates the workbench) |
windowFocused | boolean | A tab group holds focus (the name is the floating desktop's) |
shellView | string | boot, oobe or desktop |
platform | string | mac / win / linux |
host | string | browser or desktop |
The legacy scope: '<viewId>' field is shorthand for
when: "paneFocus == '<viewId>'" and is normalized to it at merge time.
Precedence
resolveKey picks a winner in this order:
- The capture gate. If a pane holds the keyboard, the candidate set is filtered before anything else is considered (see below).
source: 'user'beats a shipped default.override: true— for shortcuts that must never be shadowed.alt+x(the minibuffer) is the one that ships with it. The spotlight'smod+kdeliberately does not: a focused terminal shadowing it withterminal.clearis the iTerm/VS Code convention and is intended.- The more specific satisfied
when— namingpaneInstancebeats namingpaneFocusbeats naming nothing.priorityis an explicit thumb. - Registration order, earlier first.
Desktop and window bindings
Every chord below was checked against reserved.ts before it was chosen. The
conventional ones are unavailable: alt+tab does not reach the page on Windows or
Linux (unless system-key capture is live, which it is not by
default), meta+m is macOS minimize, and meta+space / ctrl+space are Spotlight
and the IME toggle. A binding that silently never fires is worse than a less familiar
one that does, which is the whole reason that table exists.
| Action | Binding | Why not the convention |
|---|---|---|
| Spotlight (ask / run / open) | mod+k | mod+space is macOS Spotlight and the Windows IME switch |
| Cycle groups | alt+` / alt+shift+` | alt+tab is OS-level; only Keyboard Lock can take it, and only in a fullscreen capturing pane |
| Directional group focus | alt+←↑↓→ | — |
| Split the focused tab to a side / maximize the group | mod+shift+←↑↓→ / mod+alt+↑ | the keys that snapped halves on the floating desktop |
| Show / hide the left, right, bottom dock | mod+alt+[ / mod+alt+] / mod+alt+j | not t/n/b (a pane's region strips) and not mod+b/mod+j (bound by panes) |
Presets
keymap.preset selects a named alternative default set — today default and i3.
A preset is expressed as ordinary overrides, the same shape the Shortcuts pane writes, and applied through the same resolver. There is deliberately no second dispatcher and no second notion of "a default". It layers between the shipped defaults and the user's own edits, so:
- a preset's
disabledentry suppresses a shipped default (that is how the i3 set takesmod+kaway from the spotlight, with no special case in the resolver); - a hand rebind still beats the preset it was layered over;
- switching back to
defaultremoves the set cleanly, because it was never saved as if the user had typed it.
The i3 set makes two forced deviations, both worth stating because they look like
mistakes. The i3 modifier is the Super key, which a web page never receives as a
chord on its own, so mod here is ctrl/cmd. And workspace switching stays on
mod+alt+<n>: plain mod+<n> is browser tab switching and is not cancellable.
Input capture
A pane that needs the keyboard takes capture. While it is held, the resolver
only considers bindings belonging to that pane, plus anything marked
capturePassthrough.
| Mode | Swallows |
|---|---|
pointer | the mouse only; every shortcut still works |
keyboard | unmodified keys only — an editor gets t, the shell keeps mod+s |
full | every shortcut but the capturing pane's own — a pointer-locked game |
Two invariants are enforced by the store, not by each pane:
- Only the focused pane may hold capture, and losing focus releases it. Before
this,
hassault.playkeptwindow-level listeners alive whether or not it was the pane you were in. - Release runs
onReleaseexactly once, whoever triggered it — the Escape ladder, a focus change, or unmount.
Declaring capture in a view's manifest grants it on focus and drops it on blur
(what editors and terminals want). The deprecated editor: true flag is exactly
capture: { mode: 'keyboard', escape: 'passthrough' }. A pane that captures only
sometimes — a game, and only once pointer-locked — declares nothing and calls
useCapture().request() at the moment it needs the keyboard.
The Escape ladder
Escape used to be claimed independently by the dialog layer (capture phase), the
frame's area-fullscreen exit (bubble phase), and the browser's own pointer-lock
release, with no ordering — pressing it in a fullscreened area with a dialog open
did two things at once. It is now one ordered ladder in
keymap/dispatch.ts; the first rung that applies wins.
- A half-typed chord → abandon it.
- A modal dialog → dismiss it.
- Capture held with
escape: 'release'→ release. - Capture held with
escape: 'passthrough'→ deliver Escape to the pane, and release only if it is held pastkeymap.escapeHoldMs(default 400 ms). - An in-window fullscreened area → exit.
- A popover or context menu → close the most recent.
- Otherwise → let it through.
Escape reaches the pane that has focus. An editor, terminal or notebook declares a
passthrough capture, so a tap of Escape goes to it (closing autocomplete, leaving
vim insert mode) rather than to the shell. That holds in fullscreen too: while a
passthrough capture is held, followCaptureWithEscapeLock (installed by
installKeymap) keeps navigator.keyboard.lock(['Escape']) on. Before this,
only the game took the lock. Escape in a fullscreen editor went to the host,
which left fullscreen and put the dashboard back in a window.
To leave fullscreen from a capturing pane, hold Escape: that releases the capture, and with it the lock. The next Escape goes to the host. F11 and the fullscreen command also work at any time.
The host acts on Escape before the page when it has something of its own to undo:
pointer lock, or document fullscreen. Keyboard Lock is the only way to keep the key
then, and it is Chromium-only and only in document fullscreen. Where it can't
help (pointer lock outside fullscreen, or a non-Chromium browser), hostTakesEscape()
is true and rung 4 degrades to rung 3. A windowed pane with no pointer lock never
degrades, because the page owns Escape there outright.
The capture badge shows which case applies: it reads "Hold Esc to release" or
"Esc to release" from hostTakesEscape() at that moment. Promising a gesture
that silently doesn't work is worse than offering the tap.
System-key capture
A pane can ask for the chords the OS itself owns by declaring systemKeys on its
capture — hassault.play is the only one that does (in the dashboard only while
flying a replay's drone camera, since the pane is a launcher; on the web client,
for play). Asking is not getting: the
full navigator.keyboard.lock() runs only when all of these hold.
| Gate | Why |
|---|---|
| Keyboard Lock exists | Chromium only (the desktop shell is Chromium everywhere); Firefox and Safari have no implementation |
| The document is fullscreen | The spec excludes F11 and, with it, a native shell's borderless window — see setDocumentFullscreen in fullscreen.ts, which is why the desktop layout now enters document fullscreen alongside the OS window |
keymap.captureSystemKeys is on | Off by default. A window that swallows alt+tab without saying so is indistinguishable from a frozen machine |
ctrl+alt+del and the other platform secure-attention sequences are never
capturable by anyone. When the gates do not all open, lockSystemKeys() falls back
to the Escape-only lock — the behaviour that shipped before — so callers never
branch. The capture badge states "Alt+Tab is captured" whenever it is in force,
and the release gesture is then the only way out.
Its fullscreen is a display mode (DirectX exclusive), not a keyboard grab —
alt+tab still works there, it just costs a mode switch. Games that actually
swallow alt+tab install a low-level OS keyboard hook, usually inside anti-cheat.
This feature is therefore more invasive than the thing it imitates, which is why it
is opt-in twice over. What is worth taking from CS is raw mouse input:
requestPointerLock({ unadjustedMovement: true }), independent of all of the above.
Host reservations
Some chords never reach the page. keymap/reserved.ts is a table of them per
host and platform, with preventable marking the ones preventDefault() can
reclaim (browser Back on alt+left) versus the ones that never arrive at all
(mod+1..9 tab switching).
An entry may also be lockable: a chord that Keyboard Lock genuinely hands over
while system-key capture is in force, so checkReserved
stops reporting it as taken once the keyboardLock context key is set. It is set
on the browser's own tab/window chords and on alt+tab/alt+f4; it is not set
on anything scoped to a single platform, because a secure-attention sequence stays
with the OS at every setting. Where support is unclear, unset is the honest answer
— the cost is a badge that is too pessimistic rather than a binding that never
fires.
It is consumed three ways: the Shortcuts pane badges a conflicting binding live,
auditKeymap() logs unreachable defaults in dev, and keymap.set refuses to
write a binding the host would swallow — otherwise the user "successfully" rebinds
and then finds nothing happens.
This is why defaults split by host. KeybindingDecl takes hosts and
platforms, so one command can ship two:
// mod+1..9 is browser tab switching and is NOT cancellable — in a tab these
// bindings never once fired. The browser build gets alt+N instead.
{ key: 'mod+1', command: 'workspace.switch:1', hosts: ['desktop'] },
{ key: 'alt+1', command: 'workspace.switch:1', hosts: ['browser'] },
ctrl+space gets the same treatment: it is the IME toggle on Windows and the
input-source switch on macOS, so area.fullscreen ships as mod+alt+f there.
Global shortcuts (desktop)
A binding marked global: true is registered with the OS so it fires while the
app is unfocused. Gated on the shortcuts.global capability, so it is a no-op in
the browser. The frontend owns which command each accelerator runs
(keymap/global.ts); the shell side (apps/desktop/src/shortcuts.ts) is a dumb
registrar that emits a global-shortcut event, so a rebind never needs a shell
change. On Wayland the registration goes through the desktop portal (the shell turns
on Chromium's GlobalShortcutsPortal), which may ask the user once. Sequences are ineligible — the OS grabs one chord, not a prefix — and
code: specs are rejected rather than registered as the wrong key.
Focus
Focus is one field: frame.focusedInstanceId. The view id and location are
derived from it (findPaneAnywhere) rather than stored, so they cannot drift.
Beside it, frame.focusedWindowId names the focused window, for the window
verbs (snap, minimize, cycle): a window verb acts on the whole window, including the
tabs that aren't showing.
A sanitizeFocus pass runs after every action, so a closed pane can never leave
focus dangling.
Pane containers carry data-pane-instance and tabIndex={-1}, and
focusInstance / focusAreaDirection call focusPaneDom — so alt+arrow moves
the real caret, not just the accent border. A pane can nominate a better target
with data-autofocus.
User customization
Overrides live in their own document, $HORRIBLE_DATA_DIR/keymap.json, behind
GET/PUT/DELETE /api/keymap. Deliberately not a setting: SettingValue is
string | number | boolean, and GET /api/settings hands the whole bag to the
browser on every boot.
An entry either adds a binding, or disables one (disabled: true). A
rebind is both — add the new, disable the default — and the two must land
together, which is why the endpoint is whole-document rather than per-binding.
Omitting the disable half is the "I changed it but the old key still works" bug.
A corrupt keymap file falls back to defaults rather than raising: a bad keymap must never lock the user out of the UI that would fix it.
The Shortcuts pane is the UI. The command palette shows each command's live shortcut in place of its id.
Agent tools
| Tool | Purpose |
|---|---|
keymap.list | commands, bindings, conditions, source, reserved status |
keymap.describe | what a key does / what binds a command, and why a binding is not firing |
keymap.set | write a user override (gated — persistent user-visible state) |
keymap.reset | clear overrides for a command, or all |
keymap.context | the when vocabulary and its current values |
keymap.describe reporting the reason a binding lost — shadowed, condition
false, swallowed by a capturing pane, taken by the host — is what makes "I don't
like this, change Tab so it does X" resolvable in one turn.
Adding a binding
export const myModule: ModuleManifest = {
id: 'my',
title: 'My module',
commands: [{ id: 'my.thing', title: 'My: Do the thing', run: doThing }],
keybindings: [
{ key: 'mod+alt+t', command: 'my.thing' },
// Only while my pane is focused, and shadowing any global on the same key.
{ key: 'n', command: 'my.next', when: "paneFocus == 'my.pane'" },
],
};
Never install a keydown listener in a component. The one exception is a pane
that captures input, and it takes capture so the shell knows.