<!-- Generated: 2026-07-12 | Files scanned: 124 | Token estimate: ~700 -->

# Frontend / TUI

## Render Pipeline

```
ratatui::Terminal::draw(|frame|)
  → view::draw(frame, AppStateRest)
    → render_main_panel / render_overlay (based on overlay state)
    → render_input_bar
    → draw_status_bar
    → render_toasts (top-right floating notifications)
```

## Layout

```
┌──────────────────────────────────────────────┐
│ Chat Panel (main_area: Min 3)                │
│  ┌────────────────────────────────────────┐  │
│  │ User: Hello                           │  │
│  │ Agent: Hi there, how can I help?      │  │
│  │                                       │  │
│  │ Toast notifications (top-right)       │  │
│  └────────────────────────────────────────┘  │
├──────────────────────────────────────────────┤
│ Input Bar (3 lines)                          │
│ > Some text...                               │
├──────────────────────────────────────────────┤
│ Status Bar (1 line)                          │
│  ┌ Provider │ Model │ Tokens │ Mode │ Quit ─┤
└──────────────────────────────────────────────┘
```

## Key Files

| File | Lines | Purpose |
|------|-------|---------|
| `src/view/mod.rs` | 623 | Frame draw, overlays (16 types), input bar, toasts |
| `src/view/chat.rs` | 155 | Chat transcript rendering with markdown |
| `src/view/markdown.rs` | 144 | Markdown → ratatui `Span` rendering (pulldown-cmark + syntect) |
| `src/view/status.rs` | ~50 | Status bar with provider/model/tokens |
| `src/view/workflow.rs` | 88 | Workflow progress visualization |
| `src/view/theme.rs` | 23 | Color palette (23 named colors) |
| `src/controller/input.rs` | 281 | Key event → Action mapping |

## Overlays (16 types)

`Overlay::Help | Settings | Bash | QuitConfirm | Workflow | KeyInput | Editor | Effort | Mcp | Todo | Rewind | Learning | Usage | Loading | ModelSelector | ClearConfirm`

Each overlay renders a centered popup via `render_overlay()`.

## State Mutations

State is mutated in-place from two locations:
- `src/controller/input.rs` — keyboard shortcuts and overlay interactions
- `src/app/runtime/actions/mod.rs` — `apply_action()` reducer for all programmatic actions

## Toast Notifications

`render_toasts()` — floating stack at top-right, color-coded by severity:
- Info: blue, Success: green, Warning: yellow, Error: red, Lesson: cyan
- Max 4 visible, auto-expire after 5s lifetime