# src/tui KNOWLEDGE BASE
## OVERVIEW
Mission Control Ratatui display shell: input, render, event drain, local UI state; runtime truth lives outside TUI.
## STRUCTURE
```text
src/tui/
├── mod.rs # module boundary, TuiEvent, run_tui, channel helpers
├── terminal.rs # raw mode, alt screen, mouse/paste, terminal cleanup
├── worker.rs # blocking worker outcome/final-event reconciliation
├── transcript.rs # transcript sanitizing, wrapping, render cache helpers
├── controller/ # child AGENTS.md; app loop, event drain, pacing, input bridge, worker lifecycle
├── events/ # delivery/backpressure helpers
├── input/ # child AGENTS.md; key/mouse/clipboard/autocomplete/submit
├── render/ # child AGENTS.md; Ratatui widgets and pane projection
├── screens/ # startup/primary-agent screens
├── sessions/ # session picker commands/history previews
├── transcript_cards/ # transcript card projection: copy mapping, visual lines
└── state/ # child AGENTS.md; display-only reducers and modal state
```
## WHERE TO LOOK
| TUI entry/lifecycle | `mod.rs`, `terminal.rs` | channel setup, terminal guard, public crate-local seam |
| Worker completion | `worker.rs` | final event storage, `RunFinished`, cancellation display |
| Event application | `controller/drain.rs` | output/activity/control events mutate display state |
| Main loop | `controller/app/mod.rs`, `controller/pacing.rs` | frame cadence, input bridge, redraw decisions; see `controller/AGENTS.md` |
| Activity/UI flow | `controller/drain.rs`, `controller/app/mod.rs` | event application, redraw, input bridge, worker lifecycle |
| Text transcript | `transcript.rs`, `transcript_cards/` | sanitization, wrapping, activity links |
| Rendering details | `render/AGENTS.md` then `render/` | panes, modals, header, prompt, transcript, activity |
| State details | `state/AGENTS.md` then `state/` | display model, modals, caches, selectors |
## CONVENTIONS
- TUI owns presentation only: focus, scroll, modals, panes, toasts, prompt cursor, render caches.
- Runtime events remain the input contract; request shaping, replay, auth, and tool dispatch stay outside `src/tui/`.
- `MissionControlState` stays display-only; session/replay/provider code owns durable execution truth.
- Final/critical events must reconstruct readable state; preview deltas are best-effort and may drop.
- Provider work stays on blocking worker/thread/channel path; no async side-channel in UI.
- `send_critical` reports saturation; `send_best_effort` protects provider/tool progress.
- Sanitize transcript/status/control text before display; keep status terse and factual.
- TestBackend proves render/state projection only; not real TTY/write/flush validation.
## ANTI-PATTERNS
- Do not add provider request shaping, auth policy, session replay, or tool dispatch under `src/tui/`.
- Do not render unsanitized escape/control sequences from tool output, Git diff, prompts, provider events, or errors.
- Do not let preview floods block final reconciliation or worker completion.
- Do not treat `ratatui::backend::TestBackend` as evidence for terminal compatibility.