Vibe Rust Tui

Vibe Rust TUI

UI conventions for vibe/cli-rust/. Every screen follows them so the TUI reads as one product. Process rules (porting from Python, scenarios, goldens) live in migrate-cli-to-rust; local code rules live in vibe/cli-rust/AGENTS.md.

Shortcut hints

• Name keys and actions only through src/hints.rs: key::*, action::* and the shared pairs (hints::NAVIGATE, SELECT, SEARCH, CANCEL, CLOSE, BACK). Never write a key or action as a string literal at a call site. A single letter key ("d", "r") is fine as long as its action comes from action::*. When a key or verb is missing, add it to src/hints.rs.
• A hint is an unpadded (key, action) pair (hints::Hint). The renderer owns all spacing; never bake spaces into a label.
• Wording: actions are lowercase verbs (navigate, select, close); keys keep their canonical casing (Enter, Esc, Ctrl+C, Backspace). Combined keys use / (Space/Enter, Esc/Ctrl+C).
• Vertical navigation is key::NAV (↑↓/jk) whenever j/k work; use key::ARROWS (↑↓) only where a focused text field owns the letters. Horizontal navigation is key::LEFT_RIGHT (←→).
• Footers read key action key action, ending with the Esc hint. Inline status lines (loading line, narrator) are the one exception and read key to action.
• Render every footer through ui/hint_line.rs (draw, draw_clipped, line, spans, styled): they apply the shared key/action styles and clip to the box. Never place hint text with hardcoded x offsets or custom key styles. Center a hint with hints::width.
• Onboarding and dialogs follow the same footer form (Enter continue, Esc back), not sentences like "Press Esc to go back".

Keyboard navigation

• Every navigable list accepts j/k alongside ↑/↓ when no text field is focused. Match only plain keys (no Ctrl/Alt/Super) so Ctrl+J/Ctrl+K keep their editing meaning.
• Show the navigation keys a screen actually handles: write ↑↓/jk only where j/k are wired.
• Edges: ↑↓/jk (and ←→ across dialog options) wrap at both ends; PageUp/PageDown/Home/End clamp. Move through list_nav::wrap, or list_nav::wrap_selectable when some rows (section headers, notes, blanks) cannot take the cursor; never hand-roll saturating_sub/min(len - 1) for arrow moves. The only lists that do not wrap are the ones attached to the composer: Down past the newest queued prompt leaves queue mode, and Up at the top of the subagent list returns focus to the composer.
• Back: Esc goes back exactly one level (field → list, detail → list, auth flow → its /mcp list) and closes only at the top level. Backspace edits text and is never a navigation key. A nested view's footer ends with hints::BACK (Esc back); a top-level view's footer ends with hints::CLOSE or hints::CANCEL.
• Digits: a row's digit shortcut exists if and only if the row displays its number (1. Trust folder). Pressing it is the same as moving to the row and pressing Enter. Parse it with list_nav::digit; never accept digits on unnumbered rows, and never number rows that do not accept their digit.

Scrolling

• A scrolling list keeps the highlighted option in view through ui/list_scroll.rs follow, passing which lines are options; never write its own scroll = selected reconciliation. It moves the viewport the least and brings the option's non-selectable neighbours along: its section header above it, the list's leading lines for the first option, the trailing lines for the last one. Wrapping from the bottom back to the top therefore always shows the very top of the list.
• Mouse-wheel scrolling sets the list's free_scroll and skips follow until the next keyboard move; it only clamps the offset.

Searchable lists

• Use search_field::Search, search_field::handle_key and search_field::paste for any filterable list, and build its footer with search_field::hints.
• The model: lists open with the list focused; / focuses the field; typing filters live (letters, including j/k, go to the field); ↑↓, PageUp/PageDown and Enter keep acting on the list while the field is focused; Esc first leaves the field (the filter stays), then clears the filter, then closes the screen.
• Do not add other entry points into search (Tab, Left, type-to-search on open). Do not make Enter only "apply" the filter: it acts on the highlighted item.
• The list footer includes hints::SEARCH.
• The search row sits directly under the title, followed by one blank row, and reads / placeholder (Search plugins, Search settings). It is always visible in the list view and hidden in detail views. Draw it only with ui/search_field.rs draw_row, which owns the / and the field's indent; never put a search field at the bottom of a list or in the footer. The project picker is the one exception: its labelled Search projects: field shares the form Field of its create view.