[OC-023] Implement the TUI shell

[tcballard]

Gate: G1 — Nostr-only product

Planning source: validated implementation plan PR #1

---

• Depends on: OC-021.
• Deliverable: ANSI-16 ratatui layout, attach/reconnect, conversation sidebar, scroll/input modes, status bar, detach behavior, and terminal restoration.
• Acceptance: snapshot tests use 80×24 and narrow layouts; no truecolor escapes; crashes/signals restore the terminal; quitting detaches without stopping the daemon.
• Excludes: final command set and QR.

Maintainer reconciliation — 2026-09-04

Next closure evidence/work: #224 remains unmerged and combines renderer/raw input. Remaining shell slices: scroll/compose controls, reconnect/backoff and panic/SIGINT/SIGTERM restoration. Live messaging remains #25.

Baseline reviewed: main 87c3bcb7d65e3e2ab8ae317694b751f8efe9a8ed. Implementation presence is not a live conformance claim.

[bulters]

Would like to pick this one up.

Verified against main (5b6a6ef) that no Cargo.toml in the workspace pulls in ratatui or crossterm, so the raw-event loop is still open. Reading the crate, the deterministic half is already there — UiModel::render, the narrow fallback, parse_input, and tests/ui.rs covering 80×24 and 24×10 with the no-truecolor assertions. The gap is main.rs: it is a line-oriented stdin loop rendering at a hardcoded 80×24, InputMode::Scroll is never set, a mid-session disconnect keeps looping on a dead stream, and TerminalGuard's Drop will not fire on a panic or a signal.

Proposed approach, in four small PRs rather than one large one, so each is reviewable on its own and the first is a pure refactor:

1. Port rendering to a ratatui Widget, keeping UiModel as the state type. No behaviour change. The existing snapshot coverage moves to TestBackend buffers, where "no truecolor" becomes an assertion that no cell carries Color::Rgb or Color::Indexed(n > 15) — a stricter check than grepping the string for 38;2.
2. crossterm raw-mode event loop with real terminal geometry and resize handling, so the narrow layout becomes reachable in the binary instead of only in tests. Key events arrive over a blocking thread and a tokio channel, which keeps the dependency footprint to crossterm alone — no event-stream/futures — given the = pins, the cargo-deny policy and the 10 MiB aggregate ceiling.
3. Reachable scroll and compose modes with keybindings.
4. Reconnect with backoff on ClientError::Disconnected, plus terminal restoration through an RAII guard, a panic hook, and SIGINT/SIGTERM. Quit detaches the client only; the daemon is untouched.

Scope check I would like your read on: I am treating OC-023 as the shell alone, with live population of the sidebar left to OC-024 (#25). That is the narrower reading, and it is also forced — nothing can fill UiModel.conversations today, because the client cannot consume daemon events at all. I opened #223 with the detail.

Baseline here is green across the full docs/development.md check suite, and the release aggregate is 5,786 KiB against the 10 MiB ceiling, so I will re-run check-release-size.sh once the deps land rather than at review time.

Staying inside the stated exclusions: no new command set, no QR. Happy to adjust any of this if you would rather it land differently.

[bulters]

Correcting the plan I posted above: the first two PRs do not separate, and #224 now carries both.

Porting the renderer to ratatui while input stayed line-oriented produces a frame that corrupts itself. Three reasons, all of which I had on screen before folding the loop in:

• the terminal echoes typed characters into cells the buffer diff cannot see, so they are never repainted
• ratatui hides the cursor unless Frame::set_cursor_position is called, so that echo lands wherever the last diff write ended — in practice, in the middle of the status bar
• Terminal::resize only clears on a horizontal shrink, so a grown viewport keeps whatever the smaller frame left behind

I tried to keep the split by parking the caret on the prompt row and forcing a full repaint each frame. It stops the corruption but cannot fix resize at all: with the process blocked on a line read, nothing wakes it when the window changes. Terminal::clear is also unusable in that arrangement, because it queries the cursor position first — that returns nothing on a pipe and races the stdin reader for the reply in a terminal.

So #224 is now the renderer port plus the raw-mode event loop, verified under a pty: a resize alone reflows the frame, moving the divider from column 27 to 29 and extending addressed rows to 40, with no key pressed. The remaining two PRs are unchanged — reachable scroll/compose modes, then reconnect with backoff and restoration through a panic hook and SIGINT/SIGTERM. That last one matters more than I first thought: panic = "abort" in the release profile means the Drop guard never runs on a panic, so the hook is the only thing that can restore the terminal.

Scope reading is unchanged: still the shell only, with live population left to OC-024 (#25).