rdbms-playground/docs/adr/0049-input-field-readline-keymap.md

ADR-0049: Input-field readline keymap — Esc-clear + Ctrl-A/E/W/K/U (I1b)

Status

Accepted + implemented 2026-06-12 (issue #29). Closes Gitea #29 ("Command input keystroke support") and the deferred I1b readline requirement in requirements.md. Every fork below was escalated to the user and user-chosen before any code was written; implemented test-first (22 new Tier-1 tests in src/app.rs, all green; clippy nursery clean).

This ADR amends ADR-0046, which explicitly listed "readline shortcuts (I1b)" in its out-of-scope set: that item is now in scope and decided here. It is orthogonal to ADR-0003's input-mode model (simple vs advanced, the : sigil) — these are editing keys within the input field, not mode or sigil changes — and it extends the single-line cursor editing already shipped under requirement I1a (Left/Right/Home/End/ Backspace/Delete, app.rs).

Context

The input field already supported in-line cursor editing (I1a): Left/ Right by char (UTF-8 aware), Home/End to the extremes, Backspace/Delete. Two gaps remained, raised in issue #29:

1. No way to clear a partly-typed command in one keystroke — a user who started typing the wrong thing had to hold Backspace.
2. No readline cursor/kill shortcuts (Ctrl-A/Ctrl-E and friends) for keyboards without Home/End and for muscle-memory in a command-driven workflow. This is requirement I1b, deferred by ADR-0046.

Esc was free in the input field except that a live Tab-completion memo consumes it first (to undo the completion in one keystroke, ADR-0022). Ctrl-A/E/W/K/U were unbound. The existing chords are Ctrl-C (quit), Ctrl-O (nav focus cycle, ADR-0046), and Ctrl-] (demo caption toggle, ADR-0047) — none collide with a/e/w/k/u.

Decision

Bind the following in the input field (non-modal, non-navigation, both input modes), in App::handle_key:

Key	Action
Esc	Clear the input (empty buffer, cursor→0, scroll→0)
Ctrl-A	Cursor to line start (alias of Home)
Ctrl-E	Cursor to line end (alias of End)
Ctrl-W	Delete the word before the cursor
Ctrl-K	Kill from the cursor to end of line
Ctrl-U	Kill from start of line to the cursor

Behavioural rules:

• Esc precedence. A live completion memo still wins: the first Esc undoes the completion (ADR-0022), and Esc only clears when no memo is alive. This is a natural progression — Esc once to back out the completion, Esc again to clear.
• Esc does not clear while navigating the sidebar. When a sidebar panel is focused (Ctrl-O, ADR-0046 DC3), handle_key routes every key to the navigation handler before the input-field keymap, where Esc exits navigation mode (nav_exit). Entering nav mode never touched the input buffer, so Esc-to-close-the-panel returns focus to the input with the partly-typed command intact — it cannot reach the clear binding. Locked by a regression test.
• Single Esc clears (user-chosen over double-Esc). Discoverable and fast; the trade-off (an accidental Esc wipes an unsubmitted line) was accepted. A submitted line is always recoverable from history; only unsubmitted draft text is lost.
• Cursor-only keys don't touch history navigation. Ctrl-A/Ctrl-E, like Home/End, move the cursor without ending history recall.
• Buffer-mutating keys end history navigation. Esc-clear and Ctrl-W/K/U call cancel_history_navigation (the cleared/edited line is the new draft), matching Backspace/Delete.
• Ctrl-W is readline-style and UTF-8 safe. It eats any run of trailing whitespace, then the preceding run of non-whitespace; word boundaries are found on char boundaries so multi-byte words delete cleanly. It only ever deletes back to the cursor (a mid-line Ctrl-W leaves the suffix intact).

Helpers added: clear_input, delete_prev_word, kill_to_end, kill_to_start (src/app.rs), mirroring the existing cursor_left / delete_before_cursor style.

Forks (all user-chosen)

• Esc semantics: single-Esc-clears, not double-Esc — discoverable over accident-proof.
• Scope: the full I1b set (Esc-clear + Ctrl-A/E/W/K/U), not just the issue's literal Ctrl-A/E + Esc — closes the whole I1b requirement in one pass rather than leaving Ctrl-W/K/U for a follow-up.
• Documentation: a new ADR (this one), recording the input-field keymap convention and amending ADR-0046's OOS list — over folding it into ADR-0046 or shipping it I1a-style with no ADR.

Consequences

• I1b is complete; requirements.md I1b moves to [x].
• The new keys are not yet advertised on screen. Surfacing per-focus keybindings in the bottom status line is issue #27's domain (a separate, in-design UX change); this ADR makes the keys work, #27 will make them discoverable.
• Demo-mode badges (ADR-0047) are not extended to the new Ctrl- chords here. Esc already badges as [ESC]; Ctrl-A/E/W/K/U are glyph-less and would be invisible in an asciinema cast. Whether to add [CTRL-A]…[CTRL-U] badges is left to ADR-0047's scope and flagged as a follow-up — it is a cast-polish concern, not a #29 requirement.

Out of scope

• On-screen keybinding hints for the input field (issue #27).
• Demo badges for the new chords (ADR-0047 follow-up; flagged above).
• Multi-line input (I1) and its Ctrl-Enter submit — unrelated, still deferred.
• Word-wise cursor motion (Alt-B/Alt-F) and transpose/yank — not requested; not part of I1b.