Ratatui Patterns

Modern-ratatui knowledge pack. Current stable: ratatui 0.30.2 (2026-06). Model training data predates 0.29. The biggest failure mode is reimplementing by hand what the library now provides; the second is asserting API shapes from memory. Both have the same fix: work from the bundled references, not from memory.

Hard Rules

1. Before writing any TUI render/layout/lifecycle code, read references/modernization-checklist.md. If the thing being built appears in it, use the built-in.
2. Before claiming an API exists or writing a signature, verify it in references/api-reference.md (generated from ratatui source, grep-friendly). If it is not there and not in references/limitations.md, pull live docs (below) before hand-rolling.
3. Custom render code is allowed only for needs listed in references/limitations.md (the verified beyond-API catalog). Anything else custom is a defect.
4. Render logic ships with TestBackend tests per references/testing.md.
5. Depend only on the ratatui umbrella crate, never on ratatui-core/-widgets directly. If default-features = false, re-add layout-cache.
6. Mouse events are opt-in. ratatui::init()/run() do not enable mouse capture; that needs EnableMouseCapture/DisableMouseCapture around the loop (references/api-reference.md §14).
7. The event loop can go async (crossterm's event-stream feature + EventStream for tokio::select!); Terminal::draw stays sync regardless (references/api-reference.md §14).

Files