furumi_tui/ARCHITECTURE.md

# furumi_cli — Architecture

Cross-platform terminal client (cmus-style TUI) for the furumusic backend.
Targets: macOS, Linux (ALSA/Pulse/PipeWire), Windows (WASAPI, Windows Terminal).

## 1. Technology choices

### TUI: ratatui 0.30 + crossterm 0.29

Evaluated: **ratatui**, cursive, tui-realm, iocraft.

- **ratatui 0.30.x** — the de-facto standard (gitui, yazi, spotify-player all use it).
  0.30 split the project into workspace crates (`ratatui-core`, `ratatui-widgets`,
  `ratatui-crossterm`) with a stable core API. Stock widgets cover everything we
  need: `Tabs`, `List`, `Table`, nested `Layout` for tile grids.
- cursive — maintenance mode since 2024, rejected.
- tui-realm — viable framework on top of ratatui (termusic uses it), but a
  single-maintainer abstraction layer; we prefer plain ratatui with our own
  thin component layer.
- iocraft — too young, optimized for inline CLI output rather than fullscreen apps.
- termion — Unix-only, eliminated (we need Windows).

crossterm is the only backend that covers Windows. Caveats to handle:
- Enable kitty keyboard enhancement flags only when
  `supports_keyboard_enhancement()` returns true; always pop flags on exit.
- Filter key events to `KeyEventKind::Press` (Windows and kitty-enhanced
  terminals also deliver Repeat/Release — otherwise bindings double-fire).
- Restore the terminal on panic (panic hook) — a TUI that corrupts the shell
  is the #1 reliability complaint.

### Keybindings: crokey + TOML keymap

- **crokey 1.4** — parses/formats key combos (`ctrl-a`, `g`), serde support, used
  for the config file format.
- Keymap model copied from spotify-player: a `[[keymaps]]` TOML table mapping a
  *key sequence* (space-separated chords, e.g. `"g g"`, `"C-c x"`) to a
  `Command` enum, optionally parameterized (`{ SeekForward = { seconds = 10 } }`).
- A small chord state machine resolves sequences; bindings are layered:
  built-in defaults ← user config (`~/.config/furumi/keymap.toml`).
- Bindings resolve per *input context* (Global, LibraryGrid, TrackList,
  TextInput, Popup) so the same key can mean different things per view.

### Audio: rodio 0.22 + stream-download, behind a backend trait

Evaluated: **rodio**, kira, raw cpal+symphonia, gstreamer-rs, libmpv.

- **rodio 0.22** (`Player` / `DeviceSinkBuilder` API — note the 0.21/0.22 renames;
  most older tutorials are outdated). Symphonia is the default decoder; enable
  the `aac`, `isomp4`, `alac` features for m4a support. Pure Rust → trivial
  cross-compilation; cpal covers CoreAudio / ALSA / WASAPI.
- **stream-download 0.24** bridges HTTP to rodio: background download exposing
  blocking `Read + Seek`, built on reqwest (shares our authenticated client,
  auth headers included), seek into undownloaded regions via HTTP Range
  (the backend's `/stream/{id}` supports Range), temp-file storage, retries.
- kira — game-audio oriented, no network story, rejected.
- gstreamer / libmpv — best playback quality but heavy system dependencies;
  not acceptable as the only backend for a portable CLI.

Playback lives behind a trait so backends can be added later (termusic ships
rodio + mpv + gstreamer this way):

```rust
trait AudioBackend {
    fn play(&mut self, source: TrackSource) -> Result<()>;
    fn pause(&mut self); fn resume(&mut self);
    fn seek(&mut self, pos: Duration) -> Result<()>;
    fn set_volume(&mut self, v: f32);
    fn position(&self) -> Duration;
    fn events(&self) -> Receiver<PlayerEvent>; // TrackEnded, Failed, ...
}
```

Gapless-ish playback: pre-open the `stream-download` source and decoder for the
next queue item and append it to the rodio `Player` before the current track
ends. (True gapless is impossible for AAC/M4A anyway — symphonia has no AAC
gapless trim.)

### Async runtime: tokio

Needed for: crossterm `EventStream`, reqwest, stream-download, device-sync
polling, debounced search. The audio decode thread is rodio's own; everything
else is async tasks talking over channels.

## 2. Application architecture

Elm-style (TEA) core with a component-per-view UI layer — the pattern from the
official ratatui component template and spotify-player.

```
                 ┌────────────────────────────────────────────┐
                 │                  main loop                  │
                 │  recv Event -> keymap -> Action -> update() │
                 │  tick -> draw(&state)                       │
                 └───────▲──────────────────────────┬──────────┘
        Event (mpsc)     │                          │ Command (spawn task / send msg)
   ┌─────────────────────┼──────────────┐           │
   │ terminal input (crossterm stream)  │   ┌───────▼────────┐
   │ api task results                   │   │  side effects  │
   │ player events (TrackEnded, ...)    │   │ api::Client    │
   │ device-sync poll results/commands  │   │ player::Engine │
   │ tick (render + position updates)   │   │ sync::Poller   │
   └────────────────────────────────────┘   └────────────────┘
```

Key rules:

- **Single source of truth**: one `AppState` struct, mutated only in `update()`.
  Views are pure render functions over `&AppState`.
- **No blocking in the UI loop.** All I/O (HTTP, audio open) happens in spawned
  tasks that report back via the event channel. Every remote list is a
  `Loadable<T> { NotAsked, Loading, Loaded(T), Failed(Error) }` so views can
  render spinners and errors honestly.
- **Input → Action indirection**: raw key events are translated by the keymap
  into semantic `Action`s (`PlayPause`, `FocusNextTab`, `Select`, `Back`,
  `SeekForward(10)`). Views never see raw keys; this is what makes bindings
  configurable and the app testable.

### Module layout (single crate now, splittable later)

```
src/
  main.rs            // setup: terminal guard, tokio, channels, run loop
  config/            // Config + keymap loading (figment or manual TOML merge)
  api/               // typed client for /api/player/*
    client.rs        //   reqwest wrapper: base_url, bearer auth, retries
    auth.rs          //   password login, token store, auto-refresh (15min TTL)
    models.rs        //   ArtistCard, Release, TrackItem, PlaylistCard, ...
  player/            // playback engine
    backend.rs       //   AudioBackend trait
    rodio_backend.rs //   rodio Player + stream-download sources
    queue.rs         //   queue, shuffle, repeat_mode, next-track prefetch
  sync/              // connected devices: heartbeat/poll loop, command handling
  app/               // AppState, Action, Event, update()
  ui/                // ratatui rendering
    views/           //   library_grid, artist, release, playlists, search,
                     //   queue, devices, now_playing bar, popups
    theme.rs
```

The `api`, `player`, and `app` layers do not import `ui` or ratatui. If a
shared core for furumi_macos/android ever makes sense, those modules extract
into workspace crates without surgery.

## 3. UI model

Persistent layout: a tab bar on top, the active view in the middle, a
now-playing/status bar at the bottom (track, position gauge, volume, shuffle/
repeat, active device indicator).

Tabs (each owns a navigation stack, like a browser per tab):

1. **Library** — paginated grid of artist tiles (`GET /artists`).
   `Enter` on a tile pushes **Artist view** (`GET /artists/{id}`: metadata,
   top tracks, releases list). Selecting a release pushes **Release view**
   (`GET /releases/{id}`: metadata + track list). `Esc`/`Backspace` pops.
2. **Search** — debounced `GET /search?q=` with artists/releases/tracks sections.
3. **Playlists** — own + saved playlists, likes ("Liked tracks" virtual playlist).
4. **Queue** — current play queue, reorder/remove.
5. **Devices** — connected devices list, pick active device, transfer playback.

Navigation state is `Vec<Route>` per tab; a `Route` is an enum
(`ArtistGrid { page }`, `Artist { id }`, `Release { id }`, ...). Views cache
their loaded data in `AppState` keyed by route so Back is instant.

Tile grid: computed from terminal width (`Layout` columns × rows), each tile a
bordered block with artist name (cover art rendering in-terminal is a later,
optional feature — e.g. ratatui-image with kitty/sixel detection, never a
hard dependency).

## 4. Backend integration notes

(Verified against the furumusic source; base path `/api/player`.)

- **Auth**: `POST /api/auth/password` → access token (15 min) + refresh token
  (60 days). Client stores tokens at `~/.config/furumi/credentials.json`
  (0600) and refreshes proactively via `POST /api/auth/refresh`. All API calls
  go through one client that retries once on 401 after refreshing.
- **Streaming**: `GET /api/player/stream/{track_id}` with `Accept-Ranges:
  bytes` — exactly what stream-download needs for seek. Original files are
  served untranscoded (mp3/flac/ogg/m4a/...), hence the symphonia feature set.
- **Playback state**: persisted server-side via `PUT /api/player/state`
  (queue, position, shuffle, repeat, volume). We push throttled updates
  (on track change + every ~10s while playing) and restore on startup.
- **History/scrobbling**: `POST /history` on track completion;
  `POST /lastfm/now-playing` and `/lastfm/scrobble` if last.fm is connected.
- **Connected devices**: *polling, not websockets.* The sync task:
  - sends `POST /devices/poll` every ~5s while the app runs (device TTL is
    30s; commands TTL 20s) with our stable `device_id` (generated once,
    persisted) and current `playback_state`;
  - applies returned commands (`transfer_state` → load queue/position and
    start/stop locally; play/pause/seek commands when we are the active
    device but controlled remotely);
  - feeds the device list into the Devices tab. Activating another device =
    `POST /devices/active`; we then stop local audio and become a remote
    control (UI keeps working, actions are sent via `POST /devices/command`).
- **Jams** (collaborative sessions) exist in the API — out of scope for v1,
  but the sync task's command-handling design must not preclude them.

## 5. Reliability checklist

- Terminal guard type + panic hook: raw mode/alternate screen/keyboard flags
  always restored, even on panic.
- Every spawned task's failure becomes an `Event::TaskFailed` rendered as a
  status-bar error — no silent hangs, no `unwrap` on I/O.
- Token refresh races guarded by a single-flight lock.
- Audio device disappearance (headphones unplugged) → backend emits
  `PlayerEvent::Failed`, engine retries on default device, pauses on repeated
  failure.
- Config/keymap parse errors are reported with line context and fall back to
  defaults — a typo in keymap.toml must not brick the app.

## 6. Suggested initial dependencies

```toml
[dependencies]
ratatui = "0.30"
crossterm = "0.29"
crokey = "1.4"
tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time"] }
rodio = { version = "0.22", features = ["symphonia-aac", "symphonia-isomp4", "symphonia-alac"] } # check exact feature names
stream-download = { version = "0.24", features = ["reqwest"] }
reqwest = { version = "0.12", features = ["json", "rustls-tls"], default-features = false }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
toml = "0.8"
thiserror = "2"
anyhow = "1"
directories = "6"      # config/cache paths per-OS
tracing = "0.1"        # file-based logging (never stdout — it's the UI)
tracing-subscriber = "0.3"
```

## 7. Build order (milestones)

1. Skeleton: terminal guard, event loop, tab bar, status bar, keymap with defaults.
2. `api` crate-module: auth + artists/releases/tracks; Library grid → Artist → Release navigation.
3. Playback: rodio backend + stream-download, queue, now-playing bar, seek/volume.
4. Likes, playlists, search, history reporting.
5. Device sync: heartbeat/poll, transfer playback, remote-control mode.
6. Polish: server-side state restore, last.fm, config file, themes, optional cover art.