feat(keymap): key sequences and binding presets

[artyomsv]

Stage 2 and Stage 3 of the keybinding work, on top of the action registry that shipped in #138.

Ctrl+B then c now opens a tab, and a whole keymap can be selected in one line of ~/.quil/bindings.toml.

What changed

Key sequences. A binding can be several chords pressed in order. The status bar shows the keys typed so far while one is pending; Esc, a mouse click, and a paste all cancel; a combination bound to nothing says so rather than doing nothing quietly. Pressing the opening chord twice sends one literal chord to the pane, which is what keeps a tmux running inside a Quil pane reachable.

bindings.toml. Bindings leave config.toml for a file of their own, resolved in three layers — shipped defaults, selected preset, user overrides. config.Save rewrites the whole struct, so a preset resolved into KeybindingsConfig would be frozen the first time any unrelated setting was edited; that trap is why the table has to move. Existing installs migrate on first launch, diffing against the defaults so an untouched config yields zero overrides.

A tmux preset. preset = "tmux" gives prefix c, prefix %, prefix ", prefix z, prefix 1–9, prefix d and the rest. Presets replace rather than add, so it costs Ctrl+T and Ctrl+W; anything the preset does not name keeps its usual key.

Twelve new bindable actions. Alt+1–9 were fixed keys no setting could reach; they are ordinary actions now, along with next/previous tab and the shortcuts list.

Design notes worth review attention

The sequence probe is tier-agnostic, deliberately. pane.close is a late-tier action, so binding it to ctrl+b x leaves the opening chord in neither tier's chord map. A tier-scoped probe answers "no match", the key falls through to the pane, and the sequence can never complete however many times x is pressed. The tier split governs exact resolution of single chords only.

The two dispatch switches were left where they are. Running a resolved sequence needs a way to invoke an action, and the obvious move is extracting both switch blocks into methods. That was tried and abandoned: ~40 return sites would need reshaping, the multi-value ones (return m.toggleFocusForActiveTab()) cannot simply gain a , true, and TestHandleKey_EveryDispatchedActionHasACaseArm scrapes handleKey's source text for case arms and their position relative to the tier boundary. A completed sequence instead sets a local seqAction that the existing lookups consult — six small edits, and the case order the tier tests pin cannot move because the cases never move.

Shadow resolution runs before insertion, on parsed sequences. A binding that is a strict prefix of a longer one can never fire, so one of the pair has to be dropped. Doing it after insertion leaves the loser's prefixes in the partial-match set, so the dropped binding still swallows its own first chord. Doing it on serialized specs re-splits on ,, which is unreadable once a binding uses the comma key, and hides a malformed spec from the per-action fallback.

Cross-layer and intra-layer shadowing resolve differently, on purpose. Across layers the higher layer wins whichever is shorter — a user override has to be able to reclaim the prefix key as a plain chord, and a length rule would let a preset veto that. Within one layer the shorter is refused, because both sides tie on layer and length is then the only unambiguous tie-break.

One deliberate precedence change: a pending sequence outranks a plugin's raw_keys claim on its final chord. Scoped to multi-step bindings — a single chord never sets seqAction, so no existing binding moves. Without it, pane.close = "ctrl+b x" is dead on any pane whose plugin claims x.

There is no presets/default.toml. The registry already carries each action's shipped spec and Build already falls back to it, so a file would be a second copy free to drift from the one dispatch uses.

The comma key is bindable as comma. A literal , separates alternatives and splits a spec before any chord is parsed, so tmux's rename-window binding was otherwise inexpressible. The canonical form stays ,, because that is what a real key press reports.

Behaviour changes users will notice

• alt+1–9 leave the hardcoded-key table, so a binding that collides with one is reported as an ordinary duplicate rather than a collision with built-in behaviour. Existing conflict messages for those keys change wording.
• F1 → Shortcuts is 12 rows longer and scrolls sooner.
• config.toml's [keybindings] table is still written but no longer read.

Verification

./scripts/dev.sh vet                      exit 0
./scripts/dev.sh test ./internal/keymap/  ok
./scripts/dev.sh test ./internal/config/  ok
./scripts/dev.sh test ./internal/tui/     ok
./scripts/dev.sh test-race ./internal/tui/  ok   (23.7s, no races)
./scripts/promote-changelog.sh --check    valid

The tier-agnostic probe was checked by mutation: scoping it to the early tier fails 10 tests, including the two written for it.

Every chord in every shipped preset is validated against a real tea.KeyPressMsg — %, ", &, [, ? and the comma alias included. That check lives in internal/tui because internal/keymap does not import bubbletea and so can never build one.

Deliberately out of scope

config.Save still emits [keybindings]. Until a release has passed, an auto-update rollback lands a binary that cannot read bindings.toml, and stripping the table now would reset that user's whole keymap with no recovery. Tracked in techdebt/3-1-strip-legacy-keybindings-from-save.md, which names the guard the follow-up needs and the test to invert.

Post-review changes

• Conflict messages quote user-supplied action IDs. A [bindings] table key is arbitrary text, and ExpandPrefix runs before Build filters unknown IDs, so a raw key could reach a %s verb and from there F1 → Shortcuts. lipgloss measures ANSI as zero cells, so an escape sequence survived every width budget — an OSC 52 payload could set the clipboard on one keypress. Quoted, and unregistered IDs are now left to Build, which reports them as unknown actions and already quotes.
• A completed sequence now performs the notes-mode structural teardown. It bypasses the notes block entirely, so pane.split_h = "${prefix} %" restructured the layout with the editor still bound to a pane that moved.
• A pending sequence is dropped when the active pane changes under it. A daemon broadcast can move the active pane with no keypress; the existing mouse-click cancel doesn't see that route.
• The dropped-sequence flash names the prefix, not the chord that ended it. Ctrl+B is readline's backward-char, so the machine arms on ordinary typing and the next character could be part of a password.
• A failed migration no longer discards the user's config.toml bindings. LoadBindings legitimately returns defaults when no bindings.toml exists, so a write failure silently replaced a customized keymap with no indication why.
• ConflictShadowed no longer claims "shadowed by a longer sequence" in the cross-layer case, where the loser is the longer one, and no longer names a winner that was itself dropped later in the same pass.
• Smaller: an unparseable key drops a pending prefix rather than leaving it armed; the timeout arms only when something is pending; the flash clears even in modes that skip the machine; a preset's sequence_timeout is carried rather than parsed and discarded; WriteBindings' temp file uses O_EXCL.
• .claude/CLAUDE.md and the scoped rule no longer describe internal/keymap as stdlib-only, and the rule's paths: globs now match the new test files.

Test coverage added for the one deliberate precedence change (a completed sequence beating a plugin's raw_keys claim), verified by mutation: removing the guard fails the new test and only that test, with its control row still passing.

Second review round

• A pending sequence is dropped when a dialog opens. A dialog can appear with no keypress — MsgPluginError matches a pattern against a pane's PTY output, and the upgrade prompt is driven from a window resize — and while one is up the view draws only the dialog, so the pending indicator isn't visible either. Dismissing it left a prefix armed with no way to know, and under the tmux preset the next character could be x (close pane) or d (quit). The pane-identity check covers the broadcast route; the pane is unchanged across a dialog.
• A regression guard that Conflict.String() emits no control bytes, for both routes user text takes into one. Conflict.Detail comes from err.Error() on input that failed to parse, so it bypasses validateBaseKey by construction — every constructor quotes today and nothing pinned it. Verified by mutation.
• Two gofmt violations the field insertions introduced. Neither vet nor the test job checks formatting, so CI was green with both present.
• Notes-mode focus keys keep working from a sequence. A completed sequence bypasses the notes block, so it now reproduces that block arm for arm rather than only its structural half. pane.left/pane.right switch editor↔pane focus in notes mode; through the ordinary late-tier arm they navigated to a different pane, and the next broadcast re-synced it back — the move silently undid itself. Under a vim-style prefix keymap that's the normal way to press them.
• Regression tests for the three behaviours that had none (focus switch, structural teardown with a non-structural control, pane-change and dialog cancels), verified by mutation.
• Corrected the isAction comment: Esc closes the context menu but not the overlay, which deliberately forwards it to the running tool — so a sequence-bound overlay toggle can't close what it opened, and the tool's own quit key is the way out.