vibe-rust-tui

Vibe Rust TUI

UI conventions for vibe/cli-rust/. Every screen follows them so the TUI reads as one product. Local code rules, scenarios and goldens live in vibe/cli-rust/AGENTS.md and client-e2e/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 an OptionList (src/option_list.rs) with step(down, len, wrap, selectable), whose selectable skips rows (section headers, notes, blanks) that cannot take the cursor; list_nav::wrap is only for the onboarding's fixed two-choice screens. 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 is an OptionList: its renderer calls layout(lines, area) (the option on each line, None for headers) or layout_rows(len, area), which keeps the highlight in view through ui/list_scroll.rs follow and records the click hit map; 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.
• The wheel and the scrollbar (wheel, detach_at) free the viewport until the next keyboard move (step, select); a freed viewport only clamps its offset. highlight moves the highlight without reattaching it.

Mouse

• Every clickable list is an OptionList<R>: route its press, drag and release through mouse::option_gesture (it keeps text selection working inside the bottom app) or OptionList::mouse, and add it to mouse::option_list so it gets the wheel, scrollbar and hover. Never hit-test rows by hand.
• The click rule R is part of the list's type and comes from the item's per-item actions, the keys that act on the highlighted item. Navigation, search, Esc and whole-list keys (r refresh or reload, Tab switching the save target) do not count.
  • One action, choosing the item (tool approval, questions, /theme, /plugins, subagents, config choices, the remote project picker): SingleAction, one click confirms. A click yields the option index.
  • Several actions (/model and /thinking: Enter or s; /resume: Enter or d; /mcp: Enter, d or e; /config: Enter or Ctrl+R): MultiAction, a click highlights and a click on the highlight does what Enter does. A click yields Click::Highlight or Click::Confirm; a highlight click moves like an arrow key (/resume previews).
• A row's own click targets (the /log-level badges) are one action each, so a click on one acts at once.
• The free-text row of a question is an input: a click places the caret and a click on its number toggles it in multi-select. It never submits.

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.

Selection

• The focused row is the list-cursor bar: ui/list_cursor.rs style() across the full row width (block-cursor colors, bold). No glyph cursors (›, ▸, >) for focus.
• Draw the bar only through list_cursor: paint(f, area) fills a row area, styles(highlighted) / styles_on(highlighted, bg) give the (text, dim) styles of a row, marker_style styles the current-value marker on it. Never read theme::block_cursor_bg/block_cursor_fg outside ui/theme/ and ui/list_cursor.rs (a unit test enforces it). Text-field carets are not list cursors: use theme::block_caret (TextArea-like fields) or theme::fixed::input_caret (compact Input-like fields).
• Horizontal options (dialog buttons) render each option as a label chip; the selected chip takes list_cursor::style(). Keep labels at the same columns when switching selection.
• The current value (the active model, theme, level, layer or session) is marked with list_cursor::marker(true) (› ) in list_cursor::current_color(), in a two-column slot that stays blank (list_cursor::BLANK) on other rows.
• (String, Style) row renderers paint the full-width bar for rows where list_cursor::is_bar holds, and keep a span's own background instead of overwriting it.

Colors

• Every color value lives in src/ui/theme/: theme-dependent colors in the theme palettes (theme::foreground(), theme::muted_style(), ...), fixed brand and terminal colors in ui/theme/fixed.rs (ORANGE, LOADING_GRADIENT, onboarding colors, sgr::* escape codes, the Monokai/Alabaster named palette via fixed::named), syntax colors in ui/theme/syntax.rs. A fixed color such as the brand orange is fine, but it is defined once there and imported everywhere else.
• Outside src/ui/theme/, never write Color::Rgb(..), Color::Indexed(..), a named Color::* variant or a raw SGR color code. When a screen needs a new color, add a named constant or theme accessor first. tests/units/color_literals.rs fails on any literal outside the theme module (only update_prompt/ansi.rs, which converts any Color to SGR, and test code are exempt).

Verification

• Any change to a hint, a key, a list behavior (wrap, back, digits, scroll, search, clicks) or a selection style is user-visible: update the affected client-e2e scenarios (screen_contains, key sequences, mouse coordinates) and regenerate their goldens as described in vibe/cli-rust/AGENTS.md. A new behavior gets its own scenario (for example mcp/mcp_wrap_scroll).
• Shared helpers carry their own unit tests (tests/units/option_list.rs, option_clicks.rs, list_nav.rs, list_scroll.rs, search_field.rs); extend them when a helper changes instead of testing the rule screen by screen.
• tests/units/color_literals.rs guards the color and list-cursor rules. Do not add exemptions to make it pass: move the color into src/ui/theme/ or route the bar through list_cursor.