docs: bootstrap vault, roadmap and research

2026-10-17 21:14:19 +03:00
parent 749afadcd4
commit 8fa0632d69
34 changed files with 1508 additions and 0 deletions
@@ -0,0 +1,33 @@
+---
+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.