diff --git a/AGENTS.md b/AGENTS.md index 34b5e49..b11237f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -186,6 +186,11 @@ The TUI is keyboard-first and cross-platform. - Use semantic `Action` values rather than checking raw keys inside views. - Add default bindings in `src/config/default_keymap.toml`. - Preserve user overrides and context-specific bindings. +- Tabs are ordered Library, Playlists, Queue, Podcasts, Settings, Logs + (`1`–`6`). `Tab::ALL` defines that order for the tab bar, Tab/Shift+Tab, + and `GoToTab` indices. Changing it, or the meaning of any other + positional action argument, requires a new `KEYMAP_VERSION` and an + in-memory migration of older keymap files; never rewrite the user's file. - Account for narrow terminals, Unicode display width, and empty/loading/error states. - Restore raw mode, alternate screen, bracketed paste, and keyboard diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 06dbf21..646e698 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -257,6 +257,18 @@ The audio engine is similarly isolated. The application owns the logical queue, while `player::Controller` owns rodio playback and receives explicit commands. Prefetching prepares the next source before the current item ends. +### Versioned key bindings + +Key bindings are semantic `Action` values loaded from the bundled defaults and +merged with the user's `keymap.toml`. Some actions carry positional meaning +(`GoToTab(index)` follows the displayed tab order), so changing the tab order +changes what an existing user file means. The keymap file therefore carries a +format `version`. Files from an older format are adapted in memory when they +are loaded and the user is told once per start; Furumi never rewrites a +user's configuration. The current format, version 2, orders tabs as Library, +Playlists, Queue, Podcasts, Settings, Logs; unversioned files use the earlier +order and have their tab indices remapped. + ## Scripted visualizations Visualizations are an extension boundary rather than hard-coded rendering diff --git a/CHANGELOG.md b/CHANGELOG.md index 3145a1d..8983577 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- A Podcasts tab on `4`. It is a placeholder in this build and states that + podcasts are not available yet. +- An optional top-level `version` in `keymap.toml`; the current format is + `version = 2`, and a `podcasts` binding context. + +### Changed + +- Tab order is now `1` Library, `2` Playlists, `3` Queue, `4` Podcasts, + `5` Settings, `6` Logs, for the tab bar, Tab/Shift+Tab, and the default + number keys. +- Keymap files without `version` keep their tab shortcuts: `GoToTab` indices + are remapped in memory (3 → 4 Settings, 4 → 5 Logs, and 5 → 3 Podcasts + from the prototype podcast build) with a one-time startup notice. The file + is not rewritten; `version = 2` files are used as written. +- The help window names the target tab for number-key shortcuts + ("Go to Settings") instead of "Go to tab N". + ## [0.2.8] - 2026-09-02 ### Added diff --git a/README.md b/README.md index 6a2cd17..fb925d9 100644 --- a/README.md +++ b/README.md @@ -149,6 +149,34 @@ The **Additional settings** window also contains the music save directory and visualization controls. Use Up/Down (or j/k) to navigate, Enter to select, and Esc to return to Settings. Long lists scroll with the selection. +### Tabs and key bindings + +The number keys open the tabs in the order they are shown, and Tab / +Shift+Tab cycle through them: + +| Key | Tab | +| --- | --- | +| `1` | Library | +| `2` | Playlists | +| `3` | Queue | +| `4` | Podcasts | +| `5` | Settings | +| `6` | Logs | + +The Podcasts tab is a placeholder in this build; podcast support is not +available yet. Press `?` for the full list of bindings and commands. + +Bindings can be overridden in `keymap.toml` in the platform config directory +(`~/.config/furumi/keymap.toml` on Linux and macOS); the bundled +`src/config/default_keymap.toml` documents the format. Start the file with +`version = 2`, the current format: its `GoToTab` indices are used exactly as +written (`0` Library … `5` Logs). Files without `version` were written for the +older tab order (Settings and Logs on `4`/`5`, Podcasts on `6` in the +prototype podcast build); Furumi adapts their tab shortcuts in memory so they +keep opening the same tabs, shows a short notice at startup, and never +rewrites the file. Add `version = 2` once the indices match the new order to +take them literally and silence the notice. + ### Now playing in tmux While Furumi is running, a second invocation can print a cheap, single-line