hmbown--codewhale/crates/tui/AGENTS.md

crates/tui — agent guidance

Scope: the TUI, the runtime engine embedded in it, and everything a user sees. Read the repo-root AGENTS.md first; this file adds the rules that are specific to this crate.

The shell grammar (do not regress it)

The default shell is the underwater system (src/tui/underwater.rs, ocean.rs, widgets/, views/). Its contract, in one list:

• One owner per fact. Route/mode/permission/context live in the header; Tasks/To-do in the top strip; receipts and the single live row in the transcript; phase/cost/detail keys in the footer. Never restate a fact in a second place.
• One live row. Settled receipts are still; only the active row and the footer phase mark move. Decorative motion exists only in empty idle water and stops the instant the user types or anything needs attention.
• Phase is typed. ShellPhase::from_app derives idle/typing/working/ waiting/approval/done/failed from real app state. Never invent state in a renderer; never compare English strings to detect state (use the enums — the permission chip maps from ApprovalMode for exactly this reason).
• Treatment is typed. OceanTreatment (ombre/flat/classic) parses once from settings. Every underwater treatment keeps ambient life; appearance and motion (low_motion, fancy_animations) are independent axes.
• Footer notices go through the toast system (push_status_toast / active_status_toast), never the legacy status_message sink directly: toasts carry level + TTL, errors hold sticky, acknowledgements expire.
• Compact tiers shed chrome, not content. At small sizes a room drops titles/captions/spacers before it drops the object the user opened it to manipulate, and bodies budget from the footer's wrapped height (wrapped_footer_lines / action_footer_lines).
• Rows are objects. Anything selectable has a hitbox recorded at render time, keyboard + mouse parity, and visible focus. Destructive controls arm before they fire.

Localization rules

• Every user-visible string goes through tr(locale, MessageId::…). No hardcoded English in render paths — the raw-parity tests (shipped_complete_packs_have_raw_key_parity_with_english, message_id_list_english_pack_stay_in_exact_sync) enforce the key sets, and they exist because the old gate was blinded by the English fallback.
• Adding a string = enum variant + ALL_MESSAGE_IDS entry + en.json key
  • a translation in every complete pack. See locales/AGENTS.md.
• Glyphs (▸ · ▾ ─), key names (Enter, Alt+?), and commands (/fleet setup) are composed in code, not embedded in translations.

Verification

cargo test -p codewhale-tui --bins --locked            # full unit suite
cargo test -p codewhale-tui --test qa_pty --locked     # PTY snapshots
cargo test -p codewhale-tui --test release_runtime_qa --locked
cargo clippy --workspace --all-targets --locked -- -D warnings

Run clippy with --all-targets: --bin alone skips test targets and lets lints reach CI.

Real-terminal QA gotchas (learned the hard way):

• The local tmux server may carry NO_COLOR=1 and TERM=dumb from old VHS runs — launch panes with env -u NO_COLOR or all color QA silently lies. tmux also force-enables the low-motion runtime overlay; prove full motion with TMUX/TMUX_PANE removed.
• Scripted PTY input: one Enter on the slash menu both accepts the highlighted match and runs it (#573). A scripted second Enter lands inside whatever modal just opened. Send one key, wait, capture.
• Judge motion from repeated captures diffed over time, never single screenshots. Layout gates: 40x12, 60x16, 80x24, 100x32, 140x40.
• CODEWHALE_TUI_DEBUG=1 writes per-frame diff sizes to ~/.codewhale/logs/tui-render.log. Streaming should be tens of cells per frame; a multi-thousand-cell frame is only acceptable on a genuine layout transition.

Sharp edges

• run_verifiers_background_* can flake under full-suite parallelism; rerun in isolation before blaming a change.
• The workflow history card renders with Locale::En until locale is threaded through ToolCell::lines_with_mode (~30 call sites) — known debt, not a bug to "fix" casually.
• The classic treatment exists in code but persisted settings normalize it away; do not expand it without a product decision.
• See the do-not-delete module list in the repo-root AGENTS.md before trusting any dead-code audit.