tui: configurable key bindings system

charles commented

2026-04-11 13:02:27 +00:00

Owner

User story

As a user, I want to rebind any key to any action, so that I can match my personal muscle memory (vim, emacs, or defaults).

Acceptance criteria

Key combo model

KeyCombo parses strings like Ctrl+Shift+K, Esc, ?, g g (chord) round-trippably
A KeyMap maps KeyCombo → ActionId, scoped by optional Screen
Chord support: a pending-prefix table allows g g, d d, etc.

Defaults

Defaults match spec §3.1 (global) and every screen's local bindings (e.g. gallery /, f, S, …)
Defaults compiled in as a static function so the app works without a config file

Overrides

[tui.keybinds] section in tui.toml loads overrides; unknown action ids produce a warning and are ignored
Runtime: reloading the config replaces the active KeyMap

Settings integration

Exposes reset_to_defaults() used by Settings → Key Bindings
Exposes an iterator over (Action, current_binding) for rendering the help overlay and the settings table

Tests

KeyCombo round-trip test for representative combos
Unit test: a TOML override replaces a default binding for one action and leaves others untouched
Unit test: chord sequences g g only fire on the second key within a 1 s window

Out of scope

Editor UI in Settings for rebinding (part of Settings ticket)
Help overlay UI (separate ticket)

References

Spec §3.1 "Global Key Bindings"
Spec §3.2 "Vim-style Navigation"
Spec §7.1 [tui.keybinds]

## User story As a user, I want to rebind any key to any action, so that I can match my personal muscle memory (vim, emacs, or defaults). ## Acceptance criteria ### Key combo model - [ ] `KeyCombo` parses strings like `Ctrl+Shift+K`, `Esc`, `?`, `g g` (chord) round-trippably - [ ] A `KeyMap` maps `KeyCombo → ActionId`, scoped by optional `Screen` - [ ] Chord support: a pending-prefix table allows `g g`, `d d`, etc. ### Defaults - [ ] Defaults match spec §3.1 (global) and every screen's local bindings (e.g. gallery `/`, `f`, `S`, …) - [ ] Defaults compiled in as a static function so the app works without a config file ### Overrides - [ ] `[tui.keybinds]` section in `tui.toml` loads overrides; unknown action ids produce a warning and are ignored - [ ] Runtime: reloading the config replaces the active `KeyMap` ### Settings integration - [ ] Exposes `reset_to_defaults()` used by Settings → Key Bindings - [ ] Exposes an iterator over `(Action, current_binding)` for rendering the help overlay and the settings table ### Tests - [ ] `KeyCombo` round-trip test for representative combos - [ ] Unit test: a TOML override replaces a default binding for one action and leaves others untouched - [ ] Unit test: chord sequences `g g` only fire on the second key within a 1 s window ## Out of scope - Editor UI in Settings for rebinding (part of Settings ticket) - Help overlay UI (separate ticket) ## References - Spec §3.1 "Global Key Bindings" - Spec §3.2 "Vim-style Navigation" - Spec §7.1 `[tui.keybinds]`

charles added this to the loom-tui v0.1.0 milestone

2026-04-11 13:02:27 +00:00

charles added the

area:navigation

type:user-story

labels

2026-04-11 13:02:27 +00:00

charles referenced this issue

2026-04-11 13:07:50 +00:00

tui: tracking — loom-tui v0.1.0 roadmap & implementation order #47

charles referenced this issue

2026-04-11 15:22:44 +00:00