Custom playback integration phase 1: add CustomQueue scaffolding (#959)

## Add `CustomQueue` scaffolding (Phase 1 — Foundation)

Phase 1 of the custom playback integration. Pure scaffolding with **zero behavioral change** — all existing codepaths remain untouched.

### Motivation

Issues #766, #878, #378, #767, #153, #739 all stem from the same root cause: the app delegates queue management to Spotify/librespot, which only exposes a ~100-track window. The custom queue system will replace this with app-managed batched URIs playback when streaming is active

### Changes

**New: `state/queue.rs`**
- `CustomQueue` struct — full track list, batch window (`batch_start..batch_end`), shuffle/repeat state, source context
- `AdvanceResult` / `RetreatResult` / `ShuffleMode` enums
- Core methods: `advance`, `retreat`, `truncate_batch_to_current`, `set_shuffle_mode`, `append_radio_tracks`, `next_batch`, `expected_next_track`, etc.

**Modified: `state/player.rs`**
- Added `custom_queue` fields to `PlayerState`
- `playing_context_id()` falls back to `custom_queue.source_context` for URIs playback

**Modified: `state/mod.rs`**
- Wired `mod queue; pub use queue::*`
- Added `State::should_use_custom_queue()` (requires streaming + config)

**Modified: `config/mod.rs`**
- Added `custom_queue: bool` to `AppConfig` (default `true`)

**Docs: `docs/config.md`, `examples/app.toml`**
- Documented the new config option

### Design notes

- **Batch manager model** — only intervenes at batch boundaries; librespot handles within-batch transitions
- **`batch_end` over fixed size** — enables `truncate_batch_to_current()` for non-interrupting shuffle/repeat changes
- **`EndOfTrack` as sole position tracker** — skip commands don't advance queue position, avoiding desync with user-queued tracks
- **Streaming-only + config-gated** — `should_use_custom_queue()` = `is_streaming_enabled() && custom_queue`

Author: aome510

.vscode/settings.json

@@ -2,6 +2,7 @@
     "rust-analyzer.cargo.features": ["image", "notify", "fzf"],
     "chat.tools.terminal.autoApprove": {
         "cargo clippy": true,
-        "cargo fmt": true
+        "cargo fmt": true,
+        "cargo test": true
     }
 }

docs/config.md

@@ -67,6 +67,7 @@ A sample `app.toml` is available at [examples/app.toml](../examples/app.toml).
 | `sort_artist_albums_by_type`      | Sort albums by type on artist pages.                                                           | `false`                                                                |
 | `volume_scroll_step`              | Volume change step when using mouse scroll.                                                    | `5`                                                                    |
 | `enable_mouse_scroll_volume`      | Enable volume control via mouse scroll.                                                        | `true`                                                                 |
+| `custom_queue`                    | Enable app-managed queue for custom playback integration (requires `streaming` feature).       | `true`                                                                 |
 | `device`                          | Device configuration (see below).                                                              | See below                                                              |
 
 ### Notes

examples/app.toml

@@ -25,6 +25,7 @@ cover_img_length = 9
 cover_img_width = 5
 cover_img_pixels = 16
 seek_duration_secs = 5
+custom_queue = true
 
 [device]
 name = "spotify-player"

spotify_player/src/config/mod.rs

@@ -133,6 +133,11 @@ pub struct AppConfig {
 
     pub volume_scroll_step: u8,
     pub enable_mouse_scroll_volume: bool,
+
+    /// Enable app-managed queue for full playlist playback.
+    /// Requires streaming. When disabled, playback uses Spotify-native queue
+    /// management.
+    pub custom_queue: bool,
 }
 
 #[derive(Debug, Deserialize, Serialize, Clone)]
@@ -384,6 +389,8 @@ impl Default for AppConfig {
 
             volume_scroll_step: 5,
             enable_mouse_scroll_volume: true,
+
+            custom_queue: true,
         }
     }
 }

spotify_player/src/state/mod.rs

@@ -2,6 +2,7 @@ mod constant;
 mod data;
 mod model;
 mod player;
+mod queue;
 mod ui;
 
 use std::{collections::VecDeque, sync::Arc};
@@ -10,6 +11,8 @@ pub use constant::*;
 pub use data::*;
 pub use model::*;
 pub use player::*;
+#[allow(unused_imports)]
+pub use queue::*;
 pub use ui::*;
 
 use crate::config;
@@ -74,6 +77,16 @@ impl State {
                 && self.is_daemon)
     }
 
+    /// Returns `true` when the custom queue system should be used for new playback.
+    ///
+    /// Requires streaming to be enabled and the `custom_queue` config option
+    /// to be `true`.
+    #[cfg(feature = "streaming")]
+    #[allow(dead_code)]
+    pub fn should_use_custom_queue(&self) -> bool {
+        self.is_streaming_enabled() && config::get_config().app_config.custom_queue
+    }
+
     /// Returns `true` when the local librespot player is actively streaming
     /// audio (i.e. a `Playing` event has been received and no `Paused` / `stop`
     /// has occurred since).  Used by the UI to decide whether to allocate and

spotify_player/src/state/player.rs

@@ -1,6 +1,7 @@
 use super::model::{
     AlbumId, ArtistId, ContextId, Device, PlaybackMetadata, PlaylistId, ShowId, TracksId,
 };
+use super::queue::CustomQueue;
 
 /// Player state
 #[derive(Default, Debug)]
@@ -17,6 +18,11 @@ pub struct PlayerState {
 
     /// The currently playing Tracks context (for contexts not tracked by Spotify's playback, e.g. liked/top tracks)
     pub currently_playing_tracks_id: Option<TracksId>,
+
+    /// App-managed custom queue for full playlist/album playback.
+    /// Active when the integrated librespot player is streaming and the user
+    /// started playback from a track-table context.
+    pub custom_queue: Option<CustomQueue>,
 }
 
 impl PlayerState {
@@ -95,9 +101,14 @@ impl PlayerState {
                     }
                 }
                 None => self
-                    .currently_playing_tracks_id
-                    .clone()
-                    .map(ContextId::Tracks),
+                    .custom_queue
+                    .as_ref()
+                    .and_then(|q| q.source_context().cloned())
+                    .or_else(|| {
+                        self.currently_playing_tracks_id
+                            .clone()
+                            .map(ContextId::Tracks)
+                    }),
             },
             None => None,
         }