---
type: decision
adr: 001
status: accepted
date: 2026-10-17
supersedes: 
tags: [adr, ratatui, tui]
---

# ADR-001: ratatui + crossterm as the TUI foundation

## Context
viexp needs a terminal UI with a three-pane Miller layout, an event loop, and later image
graphics. The Rust TUI ecosystem has one de-facto standard and several niche options.

## Options considered
| Option | Pros | Cons |
|--------|------|------|
| **ratatui + crossterm** | De-facto standard (yazi, felix, broot); 0.30 modular facade; ratatui-image companion; huge docs/community | Immediate-mode model to learn; subcrate churn in 2026 |
| cursive | widget-toolkit feel | slower cadence, different paradigm |
| tui-realm | retained mode on ratatui | extra complexity for one maintainer |
| tui-rs | — | dead upstream |
| hand-rolled on crossterm | total control | reinvents widgets; hunter died with this approach |

## Decision
Use **ratatui 0.30 (facade) with the crossterm backend**. Pin minor versions in Cargo.toml;
adopt the ratatui-org `ratatui-image` crate when previews arrive (Sprint 6).

## Consequences
- Positive: best-documented path; skills transfer to yazi/helix-adjacent tooling; image widget exists.
- Negative: immediate-mode rendering must be learned early (owned by Sprint 2); 0.30 subcrate
  split may cause dependency churn.
- Mitigations: pin versions; single render function per pane; UI state isolated in one struct.