feat(tui): configurable keymaps and Vim mode

[fcoury-oai]

TL;DR

• Adds configurable TUI keymaps with versioned defaults, conflict validation, and docs.
• Adds Vim startup mode, shifted-letter compatibility, and Vim insert/normal cursor behavior fixes.
• Adds a guided /keymap picker for setting or removing root-level custom shortcuts from the TUI.

Problem

TUI keybindings were hardcoded across dozens of match arms in app.rs, textarea.rs, and overlay handlers. Adding or changing a single binding required touching multiple files, and users had no way to remap keys without forking the codebase or hand-editing undocumented TOML. Vim mode existed, but users could neither start directly in Vim normal mode nor customize the Vim keys. Shifted-letter Vim commands (I, A, O, D, Y) were also unreliable across terminal emulators because different terminals report the same physical keypress as either Shift+lowercase or plain UPPERCASE.

Mental model

The keymap system is a three-layer resolver sitting between terminal input and application actions:

1. Config layer (codex-rs/config/src/tui_keymap.rs) — defines the on-disk [tui.keymap] TOML contract. Each action lives under a context sub-table (global, chat, composer, editor, vim_normal, vim_operator, pager, list, approval, onboarding). Key specs are normalized at deserialization time into a canonical ctrl-alt-shift-<key> form. Unknown fields are rejected eagerly with #[serde(deny_unknown_fields)].

2. Runtime resolver (codex-rs/tui/src/keymap.rs) — converts TuiKeymap config into a RuntimeKeymap of Vec<KeyBinding> per action. Resolution precedence is: context-specific override → global fallback (for selected chat/composer actions) → versioned preset defaults. After resolution, per-context conflict validation rejects duplicate key-to-action mappings within the same dispatch scope. Presets are frozen (v1) or additive (v2 adds alt-d as forward-word delete); latest is always an alias to the newest.

3. Input matching (codex-rs/tui/src/key_hint.rs) — KeyBinding::is_press() checks incoming KeyEvents against bindings. A shifted-letter compatibility path (matches_shifted_ascii_letter_compat) ensures that a shift-a binding matches both Shift+a and plain A regardless of terminal behavior, while preserving additional modifiers like Ctrl.

A keypress flows: CrosstermEvent → TuiEvent::Key → App::handle_key_event (app/chat bindings) → ChatWidget → composer dispatch → TextArea::input → modal dispatch (Vim insert vs normal vs operator-pending) or standard editor keymap. Conflict validation follows those dispatch scopes: app-level actions are checked against chat and composer actions that can be intercepted before the composer sees them; unrelated contexts like vim_normal and pager are allowed to reuse the same key because they are never evaluated together.

The /keymap command adds a guided editing layer on top of that resolver rather than a second source of truth. It builds a searchable catalog of supported actions from the same runtime keymap, shows the current binding and source, captures one replacement key, validates the resulting TuiKeymap, then persists only the chosen root-level [tui.keymap.<context>] action. Users can also remove a custom root binding, which deletes that config entry and lets the action fall back to preset/default resolution again.

Non-goals

• Full Vim emulation: this is a single-line composer with basic modal editing, not a text editor. Visual mode, registers, counts, macros, and ex commands are out of scope.
• Dynamic reloading: keymaps are resolved once at startup. Changing config.toml requires restarting the TUI.
• Global conflict prevention: the same key appearing in independent scopes such as vim_normal and pager is allowed because they never evaluate simultaneously.
• Profile-scoped interactive edits: the guided /keymap flow writes root-level [tui.keymap.*] entries so shortcuts stay consistent across profiles. Profile-specific keymaps remain possible by editing config manually.

Tradeoffs

• Shifted-letter dual bindings: the default presets include both shift(KeyCode::Char('a')) and plain(KeyCode::Char('A')) for Vim commands that use uppercase letters. This duplicates entries but guarantees correctness across iTerm2, Terminal.app, Kitty, Alacritty, and Windows Terminal which all disagree on shift reporting. The alternative — relying solely on the matches_shifted_ascii_letter_compat runtime fallback — would work for user config but would make the defaults silently depend on a non-obvious compatibility path.
• Preset freezing: v1 is immutable even if we discover better defaults later. Users who pin preset = "v1" get stable behavior forever. New improvements go into v2+ and latest rotates forward. The cost is carrying dead default tables; the benefit is that config files written today never silently change behavior.
• Conflict validation is dispatch-order-aware: the validator runs two passes for the app scope because app-level handlers execute before composer handlers. If dispatch order changes, the two-pass structure must change in lockstep — this coupling is documented in validate_conflicts() but is not enforced structurally.
• Startup default is separate from keymap defaults: [tui].vim_mode_default = true starts the composer in Vim normal mode. [tui.keymap] only decides which keypresses trigger actions; it does not implicitly enable Vim mode.

Architecture

~/.codex/config.toml
    │
    ▼
TuiKeymap (config/tui_keymap.rs)
    │  normalize_keybinding_spec() at deser time
    │  deny_unknown_fields on all context structs
    ▼
RuntimeKeymap::from_config() (tui/keymap.rs)
    │  resolve_local! / resolve_with_global! macros
    │  validate_conflicts()
    ▼
App.keymap (tui/app.rs:969)
    │
    ├─► App-level dispatch: toggle_vim_mode, open_transcript, ...
    ├─► ChatKeymap: edit_previous_message, confirm
    ├─► ComposerKeymap: submit, queue, toggle_shortcuts
    ├─► EditorKeymap / VimNormalKeymap / VimOperatorKeymap → TextArea
    ├─► PagerKeymap → transcript/help overlays
    ├─► ListKeymap → popup list pickers
    ├─► ApprovalKeymap → tool approval modal
    └─► OnboardingKeymap → welcome/auth/trust screens

/keymap (tui/keymap_setup.rs)
    │  search/select action
    │  capture replacement key or remove custom binding
    ▼
ConfigEdit::SetPath / ConfigEdit::ClearPath (core/config/edit.rs)
    │  writes root `[tui.keymap.<context>]`
    ▼
next TUI startup resolves through RuntimeKeymap::from_config()

Observability

• Startup errors: invalid runtime key specs and conflicts fail TUI startup with the relevant tui.keymap... path, the offending value/action, and a link to the canonical keymap template at docs/default-keymap.toml. TOML shape errors such as unknown fields are rejected during config deserialization before runtime keymap resolution.
• Vim mode indicator: the composer footer renders -- NORMAL -- / -- INSERT -- when Vim mode is active, driven by vim_mode_label() in textarea.rs.
• Vim startup default: [tui].vim_mode_default is loaded into Config::tui_vim_mode_default; ChatWidget applies it when constructing the bottom pane so users can launch directly into normal mode.
• Customization hints: the TUI surfaces keymap hint text showing the current primary binding for frequently-used actions.
• Guided remapping: /keymap opens a searchable remap picker. Wide terminals show selected-action details in a side panel; narrow terminals keep a compact one-line description below the picker. Setting a binding replaces that action's root custom binding, while removing a binding clears only the root override and returns to defaults.

Tests

• Config validation: unknown-field rejection (misplaced_action_at_keymap_root_is_rejected), valid context placement.
• Startup default: config tests cover tui.vim_mode_default deserialization and ChatWidget integration tests assert both insert-mode and normal-mode startup.
• Runtime resolver: canonical parsing, conflict detection across all 10 contexts, shadowing between app and composer scopes, global fallback, multi-binding arrays, deduplication, explicit unbinding via [], function key range.
• Shifted-letter compatibility: shift-a matches both Shift+a and plain A; ctrl-shift-i matches Ctrl+I; no false positives on wrong case or unrelated uppercase letters.
• Vim cursor behavior: escape-to-normal moves cursor back one position, handles position-zero without underflow, respects grapheme and atomic element boundaries, snapshot-locked cursor coordinates.
• Preset integrity: defaults_pass_conflict_validation ensures built-in presets are self-consistent.
• Guided remapping: config edit tests cover setting and clearing nested [tui.keymap.*] paths; TUI tests cover the picker catalog, action menu, capture view, conflict handling, remove-custom-binding enablement, selected-detail updates, and wide/narrow snapshots.