koan_core/player/

state.rs

use std::fmt;
use std::path::PathBuf;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU64, Ordering};

use uuid::Uuid;

/// Stable identity for a queue entry. UUIDv7 — time-ordered, unique across duplicates.
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
pub struct QueueItemId(pub Uuid);

impl QueueItemId {
    pub fn new() -> Self {
        Self(Uuid::now_v7())
    }
}

impl Default for QueueItemId {
    fn default() -> Self {
        Self::new()
    }
}

impl fmt::Debug for QueueItemId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // Short form for logs: first 8 hex chars.
        write!(f, "QId({})", &self.0.to_string()[..8])
    }
}

/// Playback state.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum PlaybackState {
    Stopped = 0,
    Playing = 1,
    Paused = 2,
}

impl PlaybackState {
    pub fn from_u8(v: u8) -> Self {
        match v {
            1 => Self::Playing,
            2 => Self::Paused,
            _ => Self::Stopped,
        }
    }
}

/// Audio format info for the currently playing track.
#[derive(Debug, Clone)]
pub struct TrackInfo {
    pub id: QueueItemId,
    pub path: PathBuf,
    pub codec: String,
    pub sample_rate: u32,
    pub bit_depth: Option<u16>,
    pub bitrate_kbps: Option<u32>,
    pub channels: u16,
    pub duration_ms: u64,
}

// --- Playlist data model (single source of truth) ---

/// Minimum bytes written before streaming playback can begin.
pub const STREAM_THRESHOLD: u64 = 256 * 1024; // 256 KB

/// Load state of a playlist item — tracks download lifecycle.
#[derive(Debug, Clone)]
pub enum LoadState {
    Pending,
    Downloading {
        /// Total bytes expected, or 0 when the server sent no Content-Length.
        total: u64,
        /// How many bytes have landed. The download thread writes it per chunk
        /// without taking the playlist lock — which is the point: progress
        /// moves far too often to be worth a queue mutation each time.
        bytes_written: Arc<AtomicU64>,
    },
    Ready,
    Failed(String),
}

/// Resolved playback source for a playlist item.
pub enum PlaybackSource {
    /// File fully downloaded — play from path.
    Ready(PathBuf),
    /// File being downloaded — enough data buffered to start streaming.
    Streaming {
        path: PathBuf,
        bytes_written: Arc<AtomicU64>,
        total: u64,
    },
}

/// A single item in the playlist. Replaces QueueEntry + QueueEntryMeta + pending entries
/// as the canonical data. Created once when tracks are added to the playlist.
#[derive(Debug, Clone)]
pub struct PlaylistItem {
    pub id: QueueItemId,
    /// Database track ID — set for tracks loaded from DB, used for downloads.
    pub db_id: Option<i64>,
    pub path: PathBuf,
    pub title: String,
    pub artist: String,
    pub album_artist: String,
    pub album: String,
    pub year: Option<String>,
    pub codec: Option<String>,
    pub track_number: Option<i64>,
    pub disc: Option<i64>,
    pub duration_ms: Option<u64>,
    pub load_state: LoadState,
}

/// The playlist — one flat array, one cursor. Everything else derived.
#[derive(Debug, Clone, Default)]
pub struct Playlist {
    pub items: Vec<PlaylistItem>,
    pub cursor: Option<QueueItemId>,
}

// --- UI view types (kept for TUI compat) ---

/// Status of a track in the queue — for UI display.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum QueueEntryStatus {
    Queued,
    Playing,
    Played,
    Downloading,
    /// User double-clicked — this track is priority, will play when ready.
    PriorityPending,
    Failed,
}

/// A single entry in the UI-visible queue snapshot.
#[derive(Debug, Clone)]
pub struct QueueEntry {
    pub id: QueueItemId,
    /// Database track ID — set for tracks loaded from DB, used for downloads.
    pub db_id: Option<i64>,
    pub path: PathBuf,
    pub title: String,
    pub artist: String,
    pub album_artist: String,
    pub album: String,
    pub year: Option<String>,
    pub codec: Option<String>,
    pub track_number: Option<i64>,
    pub disc: Option<i64>,
    pub duration_ms: Option<u64>,
    pub status: QueueEntryStatus,
    pub download_progress: Option<(u64, u64)>,
    /// Why this entry cannot play, when `status` is `Failed`.
    pub error: Option<String>,
}

/// Pre-built visible queue — single atomic snapshot for the UI.
#[derive(Debug, Clone, Default)]
pub struct VisibleQueueSnapshot {
    pub entries: Vec<QueueEntry>,
    pub finished_count: usize,
    pub has_playing: bool,
    pub queue_count: usize,
}

/// Shared player state — atomics for lock-free reads from UI thread.
///
/// The engine writes these, the UI reads them. No mutexes in the hot path.
#[derive(Debug)]
pub struct SharedPlayerState {
    state: AtomicU8,
    position_ms: AtomicU64,
    track_info: parking_lot::RwLock<Option<TrackInfo>>,

    /// THE playlist + cursor — one lock, one truth.
    playlist: parking_lot::RwLock<Playlist>,

    /// Bumped on every playlist mutation so UI can skip redundant redraws.
    playlist_version: AtomicU64,

    /// Set by external signals (e.g. souvlaki Quit event) to request clean shutdown.
    quit_requested: AtomicBool,

    /// Set when metadata has been refreshed (e.g. download completed while streaming).
    /// The UI loop checks this to force a souvlaki/cover-art update without a track change.
    metadata_refresh_pending: AtomicBool,

    /// The rate the output device settled at for the current track, or 0 when
    /// nothing has played yet. Compared against the source rate, it is the one
    /// thing koan can say for certain about the path to the DAC: whether it
    /// handed the device the samples as they are, or something had to resample
    /// to reach it. Everything past that — other clients, the volume stage — is
    /// the system's, and not ours to claim.
    output_sample_rate: AtomicU64,

    /// Radio mode — automatically queue similar tracks when the queue runs low.
    /// Shared so GQL/MCP can toggle it without going through the TUI.
    radio_mode: AtomicBool,
}

impl SharedPlayerState {
    pub fn new() -> Arc<Self> {
        Arc::new(Self {
            state: AtomicU8::new(PlaybackState::Stopped as u8),
            position_ms: AtomicU64::new(0),
            track_info: parking_lot::RwLock::new(None),
            playlist: parking_lot::RwLock::new(Playlist::default()),
            playlist_version: AtomicU64::new(0),
            quit_requested: AtomicBool::new(false),
            metadata_refresh_pending: AtomicBool::new(false),
            output_sample_rate: AtomicU64::new(0),
            radio_mode: AtomicBool::new(false),
        })
    }

    // --- Playback state ---

    pub fn playback_state(&self) -> PlaybackState {
        PlaybackState::from_u8(self.state.load(Ordering::Acquire))
    }

    pub fn set_playback_state(&self, state: PlaybackState) {
        self.state.store(state as u8, Ordering::Release);
    }

    pub fn position_ms(&self) -> u64 {
        self.position_ms.load(Ordering::Acquire)
    }

    pub fn set_position_ms(&self, pos: u64) {
        self.position_ms.store(pos, Ordering::Release);
    }

    pub fn track_info(&self) -> Option<TrackInfo> {
        self.track_info.read().clone()
    }

    pub fn set_track_info(&self, info: Option<TrackInfo>) {
        *self.track_info.write() = info;
    }

    /// Download fraction (0.0..1.0) for the currently playing track, if streaming.
    /// Returns `None` for fully-downloaded or non-playing tracks.
    pub fn current_download_fraction(&self) -> Option<f64> {
        // Released before the playlist lock is taken: derive_visible_queue takes
        // these two in the opposite order, so holding both would close a cycle.
        let id = self.track_info.read().as_ref()?.id;
        let pl = self.playlist.read();
        pl.items
            .iter()
            .find(|item| item.id == id)
            .and_then(|item| match &item.load_state {
                LoadState::Downloading {
                    bytes_written,
                    total,
                    ..
                } => {
                    let written = bytes_written.load(Ordering::Acquire);
                    if *total > 0 {
                        Some((written as f64 / *total as f64).min(1.0))
                    } else {
                        None
                    }
                }
                _ => None,
            })
    }

    // --- Quit ---

    pub fn request_quit(&self) {
        self.quit_requested.store(true, Ordering::Release);
    }

    pub fn quit_requested(&self) -> bool {
        self.quit_requested.load(Ordering::Acquire)
    }

    // --- Metadata refresh (progressive enhancement) ---

    /// Signal that metadata has been refreshed mid-stream (e.g. download completed).
    /// The UI loop calls `take_metadata_refresh()` to consume this flag and
    /// force a souvlaki/cover-art update without waiting for a track change.
    pub fn signal_metadata_refresh(&self) {
        self.metadata_refresh_pending.store(true, Ordering::Release);
    }

    /// Returns true and clears the flag if a metadata refresh is pending.
    pub fn take_metadata_refresh(&self) -> bool {
        self.metadata_refresh_pending
            .compare_exchange(true, false, Ordering::AcqRel, Ordering::Acquire)
            .is_ok()
    }

    // --- Radio mode ---

    pub fn radio_mode(&self) -> bool {
        self.radio_mode.load(Ordering::Acquire)
    }

    pub fn set_radio_mode(&self, enabled: bool) {
        self.radio_mode.store(enabled, Ordering::Release);
    }

    // --- Output device rate ---

    /// `None` until a track has started and the device rate is known.
    pub fn output_sample_rate(&self) -> Option<u32> {
        match self.output_sample_rate.load(Ordering::Acquire) {
            0 => None,
            rate => Some(rate as u32),
        }
    }

    pub fn set_output_sample_rate(&self, rate: u32) {
        self.output_sample_rate
            .store(u64::from(rate), Ordering::Release);
    }

    // --- Playlist version ---

    pub fn playlist_version(&self) -> u64 {
        self.playlist_version.load(Ordering::Acquire)
    }

    fn bump_version(&self) {
        self.playlist_version.fetch_add(1, Ordering::AcqRel);
    }

    // --- Playlist mutations (called from player thread via commands) ---

    /// Append items to the playlist.
    pub fn add_items(&self, items: Vec<PlaylistItem>) {
        let mut pl = self.playlist.write();
        pl.items.extend(items);
        drop(pl);
        self.bump_version();
    }

    /// Insert items after a specific queue item.
    pub fn insert_items_after(&self, items: Vec<PlaylistItem>, after: QueueItemId) {
        let mut pl = self.playlist.write();
        let insert_at = match pl.items.iter().position(|item| item.id == after) {
            Some(pos) => pos + 1,
            None => pl.items.len(), // fallback: append
        };
        for (i, item) in items.into_iter().enumerate() {
            pl.items.insert(insert_at + i, item);
        }
        drop(pl);
        self.bump_version();
    }

    /// Update file paths for playlist items (after organize moves files).
    pub fn update_paths(&self, updates: &[(QueueItemId, PathBuf)]) {
        let mut pl = self.playlist.write();
        for (id, new_path) in updates {
            if let Some(item) = pl.items.iter_mut().find(|item| item.id == *id) {
                item.path = new_path.clone();
            }
        }
        drop(pl);
        self.bump_version();
    }

    /// Remove an item by ID.
    pub fn remove_item(&self, id: QueueItemId) {
        let mut pl = self.playlist.write();
        pl.items.retain(|item| item.id != id);
        // If cursor was on removed item, clear it (caller handles next_track).
        if pl.cursor == Some(id) {
            pl.cursor = None;
        }
        drop(pl);
        self.bump_version();
    }

    /// Move an item relative to another entry.
    pub fn move_item(&self, id: QueueItemId, target: QueueItemId, after: bool) {
        let mut pl = self.playlist.write();
        let Some(from) = pl.items.iter().position(|item| item.id == id) else {
            return;
        };
        let item = pl.items.remove(from);
        let Some(to) = pl.items.iter().position(|item| item.id == target) else {
            // Target gone — put it back.
            let pos = from.min(pl.items.len());
            pl.items.insert(pos, item);
            return;
        };
        let insert_at = if after { to + 1 } else { to };
        pl.items.insert(insert_at, item);
        drop(pl);
        self.bump_version();
    }

    /// Batch move: extract items by ID, reinsert them at `target` position.
    /// Preserves the relative order of the moved items.
    pub fn move_items(&self, ids: &[QueueItemId], target: QueueItemId, after: bool) {
        use std::collections::HashSet;
        let id_set: HashSet<QueueItemId> = ids.iter().copied().collect();

        let mut pl = self.playlist.write();

        // Partition: extract moved items, keep the rest.
        let mut remaining = Vec::with_capacity(pl.items.len());
        let mut moved = Vec::with_capacity(ids.len());
        for item in pl.items.drain(..) {
            if id_set.contains(&item.id) {
                moved.push(item);
            } else {
                remaining.push(item);
            }
        }

        // Find target in the remaining items.
        let insert_at = match remaining.iter().position(|item| item.id == target) {
            Some(pos) => {
                if after {
                    pos + 1
                } else {
                    pos
                }
            }
            None => remaining.len(),
        };

        // Splice moved items in at the target position.
        for (i, item) in moved.into_iter().enumerate() {
            remaining.insert(insert_at + i, item);
        }

        pl.items = remaining;
        drop(pl);
        self.bump_version();
    }

    /// Set the cursor (what's playing / should play).
    pub fn set_cursor(&self, id: Option<QueueItemId>) {
        let mut pl = self.playlist.write();
        pl.cursor = id;
        drop(pl);
        self.bump_version();
    }

    /// Get the current cursor ID.
    pub fn cursor(&self) -> Option<QueueItemId> {
        self.playlist.read().cursor
    }

    /// Clear the entire playlist + cursor.
    pub fn clear_playlist(&self) {
        let mut pl = self.playlist.write();
        pl.items.clear();
        pl.cursor = None;
        drop(pl);
        self.bump_version();
    }

    // --- Called from decode thread (gapless) ---

    /// Move the cursor to the next item that can still play — the first item
    /// after the cursor that is not `Failed` — and return its ID.
    ///
    /// An item that is still downloading parks the cursor rather than being
    /// skipped, so playback resumes from it when its data lands. Skipping it
    /// would drop it from the queue for good.
    ///
    /// With no cursor set, starts from the top. A cursor pointing at an item
    /// that is no longer in the playlist yields `None` — restarting from the
    /// top would silently replay the queue.
    pub fn advance_cursor_loadable(&self) -> Option<QueueItemId> {
        let mut pl = self.playlist.write();
        let start = match pl.cursor {
            Some(cid) => pl.items.iter().position(|item| item.id == cid)? + 1,
            None => 0,
        };

        let next = pl
            .items
            .get(start..)?
            .iter()
            .find(|item| !matches!(item.load_state, LoadState::Failed(_)))
            .map(|item| item.id)?;

        pl.cursor = Some(next);
        drop(pl);
        self.bump_version();
        Some(next)
    }

    /// Peek at the next Ready item after a given item ID WITHOUT moving the cursor.
    /// Used by the decode thread for gapless lookahead — the cursor is moved
    /// later by update_playback_state when playback actually reaches the track.
    pub fn peek_next_ready_after(&self, after_id: QueueItemId) -> Option<(QueueItemId, PathBuf)> {
        let pl = self.playlist.read();
        // A reference item that has been removed means the lookahead has nothing
        // to follow; starting from the top would gaplessly replay the queue.
        let start = pl.items.iter().position(|item| item.id == after_id)? + 1;

        for i in start..pl.items.len() {
            if matches!(pl.items[i].load_state, LoadState::Ready) {
                let item = &pl.items[i];
                return Some((item.id, item.path.clone()));
            }
        }
        None
    }

    /// Retreat cursor to the previous item. Returns (id, path) if found.
    /// For prev_track — goes to the item before cursor regardless of load state.
    pub fn retreat_cursor(&self) -> Option<(QueueItemId, PathBuf)> {
        let mut pl = self.playlist.write();
        let cursor_pos = match pl.cursor {
            Some(cid) => pl.items.iter().position(|item| item.id == cid),
            None => None,
        };

        let prev_pos = cursor_pos.and_then(|p| p.checked_sub(1));

        match prev_pos {
            Some(pos) => {
                let item = &pl.items[pos];
                let result = (item.id, item.path.clone());
                pl.cursor = Some(item.id);
                drop(pl);
                self.bump_version();
                Some(result)
            }
            None => None,
        }
    }

    // --- Called from resolve thread ---

    /// Update the load state of a playlist item. Safe — just a field update under lock.
    pub fn update_load_state(&self, id: QueueItemId, new_state: LoadState) {
        let mut pl = self.playlist.write();
        if let Some(item) = pl.items.iter_mut().find(|item| item.id == id) {
            item.load_state = new_state;
        }
        drop(pl);
        self.bump_version();
    }

    /// Update playlist item metadata after a full download completes.
    /// Used for progressive enhancement: streaming started with partial Symphonia tags,
    /// now the full file is available so we can refresh with complete lofty metadata.
    pub fn update_item_metadata(
        &self,
        id: QueueItemId,
        title: String,
        artist: String,
        album_artist: String,
        album: String,
        duration_ms: Option<u64>,
    ) {
        let mut pl = self.playlist.write();
        if let Some(item) = pl.items.iter_mut().find(|item| item.id == id) {
            item.title = title;
            item.artist = artist;
            item.album_artist = album_artist;
            item.album = album;
            if let Some(dur) = duration_ms {
                item.duration_ms = Some(dur);
            }
        }
        drop(pl);
        self.bump_version();
    }

    /// Get the playback source for an item if it's ready to play.
    /// Returns `None` if not enough data is available yet.
    pub fn item_playback_source(&self, id: QueueItemId) -> Option<PlaybackSource> {
        let pl = self.playlist.read();
        pl.items
            .iter()
            .find(|item| item.id == id)
            .and_then(|item| match &item.load_state {
                LoadState::Ready => Some(PlaybackSource::Ready(item.path.clone())),
                LoadState::Downloading {
                    total,
                    bytes_written,
                    ..
                } => {
                    let written = bytes_written.load(Ordering::Acquire);
                    if written >= STREAM_THRESHOLD {
                        Some(PlaybackSource::Streaming {
                            path: item.path.clone(),
                            bytes_written: bytes_written.clone(),
                            total: *total,
                        })
                    } else {
                        None
                    }
                }
                _ => None,
            })
    }

    /// Get the path of an item if it's Ready (legacy convenience — use item_playback_source for streaming).
    pub fn item_path_if_ready(&self, id: QueueItemId) -> Option<PathBuf> {
        let pl = self.playlist.read();
        pl.items.iter().find(|item| item.id == id).and_then(|item| {
            if matches!(item.load_state, LoadState::Ready) {
                Some(item.path.clone())
            } else {
                None
            }
        })
    }

    /// Check if the cursor is on the given item.
    pub fn is_cursor(&self, id: QueueItemId) -> bool {
        self.playlist.read().cursor == Some(id)
    }

    /// Get QueueItemIds of all playlist items sharing the same album as the given item.
    /// Matches on both album name and album artist to avoid false positives
    /// (e.g. two different "Greatest Hits" by different artists).
    pub fn same_album_item_ids(&self, id: QueueItemId) -> Vec<QueueItemId> {
        let pl = self.playlist.read();
        let Some(cursor) = pl.items.iter().find(|item| item.id == id) else {
            return vec![];
        };
        let album = cursor.album.clone();
        let album_artist = cursor.album_artist.clone();
        pl.items
            .iter()
            .filter(|item| {
                item.id != id && item.album == album && item.album_artist == album_artist
            })
            .map(|item| item.id)
            .collect()
    }

    /// Get all playlist items that are Pending and have a db_id.
    /// Returns `(db_id, QueueItemId)` pairs suitable for the download queue.
    pub fn pending_downloads(&self) -> Vec<(i64, QueueItemId)> {
        let pl = self.playlist.read();
        pl.items
            .iter()
            .filter(|item| matches!(item.load_state, LoadState::Pending))
            .filter_map(|item| item.db_id.map(|db_id| (db_id, item.id)))
            .collect()
    }

    /// Every item mid-transfer, with the bytes it has and the bytes it expects.
    ///
    /// Progress moves without the playlist version moving — the download thread
    /// writes the byte counter directly — so anything following the version
    /// alone shows a frozen bar. This is how a watcher sees it move.
    pub fn downloads_in_flight(&self) -> Vec<(QueueItemId, u64, u64)> {
        let pl = self.playlist.read();
        pl.items
            .iter()
            .filter_map(|item| match &item.load_state {
                LoadState::Downloading {
                    total,
                    bytes_written,
                } => Some((item.id, bytes_written.load(Ordering::Relaxed), *total)),
                _ => None,
            })
            .collect()
    }

    /// Get the db_id for a specific playlist item.
    pub fn item_db_id(&self, id: QueueItemId) -> Option<i64> {
        let pl = self.playlist.read();
        pl.items
            .iter()
            .find(|item| item.id == id)
            .and_then(|item| item.db_id)
    }

    /// Get the load state of a specific playlist item.
    pub fn item_load_state(&self, id: QueueItemId) -> Option<LoadState> {
        let pl = self.playlist.read();
        pl.items
            .iter()
            .find(|item| item.id == id)
            .map(|item| item.load_state.clone())
    }

    // --- Snapshot helpers for undo ---

    /// Get the full playlist snapshot (items + cursor) for undo of ClearPlaylist.
    pub fn snapshot_playlist(&self) -> (Vec<PlaylistItem>, Option<QueueItemId>) {
        let pl = self.playlist.read();
        (pl.items.clone(), pl.cursor)
    }

    /// Get an item by ID (for undo of RemoveFromPlaylist).
    pub fn get_item(&self, id: QueueItemId) -> Option<PlaylistItem> {
        let pl = self.playlist.read();
        pl.items.iter().find(|item| item.id == id).cloned()
    }

    /// Get the ID of the item immediately before the given ID (None if first).
    pub fn item_before(&self, id: QueueItemId) -> Option<QueueItemId> {
        let pl = self.playlist.read();
        let pos = pl.items.iter().position(|item| item.id == id)?;
        if pos == 0 {
            None
        } else {
            Some(pl.items[pos - 1].id)
        }
    }

    /// For each ID, the ID of the item before it (or None if first), returned in
    /// playlist order regardless of the order `ids` arrives in.
    ///
    /// Undo replays these left to right, so an item whose recorded predecessor is
    /// also in `ids` must come after it — otherwise the predecessor is missing at
    /// replay time and the item lands at the end of the playlist instead.
    pub fn items_before(&self, ids: &[QueueItemId]) -> Vec<(QueueItemId, Option<QueueItemId>)> {
        use std::collections::HashSet;
        let wanted: HashSet<QueueItemId> = ids.iter().copied().collect();
        let pl = self.playlist.read();
        pl.items
            .iter()
            .enumerate()
            .filter(|(_, item)| wanted.contains(&item.id))
            .map(|(pos, item)| {
                let before = if pos == 0 {
                    None
                } else {
                    Some(pl.items[pos - 1].id)
                };
                (item.id, before)
            })
            .collect()
    }

    /// The nearest item before `id` that is not itself being removed — where
    /// playback resumes from after a batch delete that takes out the cursor.
    /// `None` means resume from the top of what survives.
    pub fn surviving_item_before(
        &self,
        id: QueueItemId,
        removed: &[QueueItemId],
    ) -> Option<QueueItemId> {
        use std::collections::HashSet;
        let removed: HashSet<QueueItemId> = removed.iter().copied().collect();
        let pl = self.playlist.read();
        let pos = pl.items.iter().position(|item| item.id == id)?;
        pl.items[..pos]
            .iter()
            .rev()
            .find(|item| !removed.contains(&item.id))
            .map(|item| item.id)
    }

    /// Restore a full playlist from snapshot (for redo of ClearPlaylist undo).
    pub fn restore_playlist(&self, items: Vec<PlaylistItem>, cursor: Option<QueueItemId>) {
        let mut pl = self.playlist.write();
        pl.items = items;
        pl.cursor = cursor;
        drop(pl);
        self.bump_version();
    }

    /// Remove multiple items by IDs.
    pub fn remove_items(&self, ids: &[QueueItemId]) {
        use std::collections::HashSet;
        let id_set: HashSet<QueueItemId> = ids.iter().copied().collect();
        let mut pl = self.playlist.write();
        pl.items.retain(|item| !id_set.contains(&item.id));
        if let Some(cursor) = pl.cursor
            && id_set.contains(&cursor)
        {
            pl.cursor = None;
        }
        drop(pl);
        self.bump_version();
    }

    /// Insert a single item after a given ID (or at front if None).
    pub fn insert_item_at(&self, item: PlaylistItem, after: Option<QueueItemId>) {
        let mut pl = self.playlist.write();
        let insert_at = match after {
            Some(after_id) => {
                match pl.items.iter().position(|i| i.id == after_id) {
                    Some(pos) => pos + 1,
                    None => pl.items.len(), // fallback
                }
            }
            None => 0,
        };
        pl.items.insert(insert_at, item);
        drop(pl);
        self.bump_version();
    }

    /// Move a single item to after `after` (or to front if None).
    pub fn move_item_to(&self, id: QueueItemId, after: Option<QueueItemId>) {
        let mut pl = self.playlist.write();
        let Some(from) = pl.items.iter().position(|item| item.id == id) else {
            return;
        };
        let item = pl.items.remove(from);
        let insert_at = match after {
            Some(after_id) => match pl.items.iter().position(|i| i.id == after_id) {
                Some(pos) => pos + 1,
                None => pl.items.len(),
            },
            None => 0,
        };
        pl.items.insert(insert_at, item);
        drop(pl);
        self.bump_version();
    }

    /// Batch move: reposition each item to after its given predecessor.
    /// Processes in order so earlier insertions don't corrupt later positions.
    pub fn move_items_to(&self, entries: &[(QueueItemId, Option<QueueItemId>)]) {
        for &(id, after) in entries {
            self.move_item_to(id, after);
        }
    }

    // --- Called from UI thread (read lock) ---

    /// Derive the visible queue from the playlist + cursor. O(n).
    /// Called once per UI tick.
    pub fn derive_visible_queue(&self) -> VisibleQueueSnapshot {
        // Read before the playlist lock — see current_download_fraction.
        let playing_duration_ms = self.track_info.read().as_ref().map(|ti| ti.duration_ms);
        let pl = self.playlist.read();

        let cursor_pos = match pl.cursor {
            Some(cid) => pl.items.iter().position(|item| item.id == cid),
            None => None,
        };

        let mut entries = Vec::with_capacity(pl.items.len());
        let mut finished_count = 0;
        let mut has_playing = false;
        let mut queue_count = 0;

        for (i, item) in pl.items.iter().enumerate() {
            let is_cursor = cursor_pos == Some(i);
            let is_before_cursor = cursor_pos.is_some_and(|cp| i < cp);

            // Byte count comes from the shared atomic, not from the load
            // state's own copy: the download thread writes it per chunk
            // without taking the playlist lock, which is what keeps a
            // transfer from bumping the playlist version a thousand times.
            let dl_progress = match &item.load_state {
                LoadState::Downloading {
                    total,
                    bytes_written,
                    ..
                } => Some((bytes_written.load(Ordering::Relaxed), *total)),
                _ => None,
            };

            let status = if is_cursor {
                has_playing = true;
                match &item.load_state {
                    LoadState::Ready => QueueEntryStatus::Playing,
                    LoadState::Downloading { .. } => QueueEntryStatus::PriorityPending,
                    LoadState::Pending => QueueEntryStatus::PriorityPending,
                    LoadState::Failed(_) => QueueEntryStatus::Failed,
                }
            } else if is_before_cursor {
                finished_count += 1;
                match &item.load_state {
                    LoadState::Ready => QueueEntryStatus::Played,
                    LoadState::Downloading { .. } => QueueEntryStatus::Downloading,
                    LoadState::Pending => QueueEntryStatus::Downloading,
                    LoadState::Failed(_) => QueueEntryStatus::Failed,
                }
            } else {
                queue_count += 1;
                match &item.load_state {
                    LoadState::Ready => QueueEntryStatus::Queued,
                    LoadState::Downloading { .. } => QueueEntryStatus::Downloading,
                    LoadState::Pending => QueueEntryStatus::Downloading,
                    LoadState::Failed(_) => QueueEntryStatus::Failed,
                }
            };

            // Override duration from TrackInfo if we have it and this is playing.
            let duration_ms =
                if has_playing && status == QueueEntryStatus::Playing && item.duration_ms.is_none()
                {
                    playing_duration_ms
                } else {
                    item.duration_ms
                };

            entries.push(QueueEntry {
                id: item.id,
                db_id: item.db_id,
                path: item.path.clone(),
                title: item.title.clone(),
                artist: item.artist.clone(),
                album_artist: item.album_artist.clone(),
                album: item.album.clone(),
                year: item.year.clone(),
                codec: item.codec.clone(),
                track_number: item.track_number,
                disc: item.disc,
                duration_ms,
                status,
                download_progress: dl_progress,
                error: match &item.load_state {
                    LoadState::Failed(reason) => Some(reason.clone()),
                    _ => None,
                },
            });
        }

        VisibleQueueSnapshot {
            entries,
            finished_count,
            has_playing,
            queue_count,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // --- helpers ---

    fn make_item(title: &str, load_state: LoadState) -> PlaylistItem {
        PlaylistItem {
            id: QueueItemId::new(),
            db_id: None,
            path: PathBuf::from(format!("/music/{title}.flac")),
            title: title.to_string(),
            artist: "Artist".to_string(),
            album_artist: "Artist".to_string(),
            album: "Album".to_string(),
            year: None,
            codec: Some("FLAC".to_string()),
            track_number: None,
            disc: None,
            duration_ms: Some(200_000),
            load_state,
        }
    }

    fn ready_item(title: &str) -> PlaylistItem {
        make_item(title, LoadState::Ready)
    }

    fn pending_item(title: &str) -> PlaylistItem {
        make_item(title, LoadState::Pending)
    }

    fn failed_item(title: &str) -> PlaylistItem {
        make_item(title, LoadState::Failed("nope".into()))
    }

    // --- advance_cursor_loadable ---

    #[test]
    fn advance_parks_on_a_still_downloading_track() {
        // A track that has not arrived yet must hold the cursor, not be skipped:
        // skipping it drops it from the queue for good, and it is the item whose
        // TrackReady has to resume playback.
        let state = SharedPlayerState::new();
        let item0 = ready_item("track-0");
        let item1 = pending_item("track-1");
        let item2 = ready_item("track-2");
        let (id0, id1) = (item0.id, item1.id);

        state.add_items(vec![item0, item1, item2]);

        assert_eq!(state.advance_cursor_loadable(), Some(id0));
        assert_eq!(state.advance_cursor_loadable(), Some(id1));
        assert_eq!(state.cursor(), Some(id1));
    }

    #[test]
    fn advance_skips_failed_items() {
        let state = SharedPlayerState::new();
        let item0 = ready_item("track-0");
        let item1 = failed_item("track-1");
        let item2 = ready_item("track-2");
        let (id0, id2) = (item0.id, item2.id);

        state.add_items(vec![item0, item1, item2]);
        state.set_cursor(Some(id0));

        assert_eq!(state.advance_cursor_loadable(), Some(id2));
    }

    #[test]
    fn advance_stops_at_end_of_playlist() {
        let state = SharedPlayerState::new();
        let item0 = ready_item("track-0");
        let item1 = ready_item("track-1");
        let id1 = item1.id;

        state.add_items(vec![item0, item1]);
        state.set_cursor(Some(id1));

        assert_eq!(state.advance_cursor_loadable(), None);
        assert_eq!(
            state.cursor(),
            Some(id1),
            "cursor unchanged on a failed advance"
        );
    }

    #[test]
    fn advance_with_only_failed_items_returns_none() {
        let state = SharedPlayerState::new();
        state.add_items(vec![failed_item("bad-0"), failed_item("bad-1")]);

        assert_eq!(state.advance_cursor_loadable(), None);
    }

    #[test]
    fn advance_from_a_vanished_cursor_does_not_restart_the_queue() {
        let state = SharedPlayerState::new();
        let item0 = ready_item("track-0");
        let item1 = ready_item("track-1");
        let id0 = item0.id;

        state.add_items(vec![item0, item1]);
        let ghost = QueueItemId::new();
        state.set_cursor(Some(ghost));

        assert_eq!(state.advance_cursor_loadable(), None);
        assert_ne!(state.cursor(), Some(id0));
    }

    // --- peek_next_ready_after ---

    #[test]
    fn peek_after_a_removed_item_returns_none() {
        // The decode thread's lookahead runs seconds ahead of what is audible.
        // Removing the track it is pre-decoding must end the lookahead, not send
        // it back to the top of the queue.
        let state = SharedPlayerState::new();
        let item0 = ready_item("track-0");
        let item1 = ready_item("track-1");
        let item2 = ready_item("track-2");
        let (id0, id1, id2) = (item0.id, item1.id, item2.id);

        state.add_items(vec![item0, item1, item2]);
        assert_eq!(
            state.peek_next_ready_after(id1).map(|(id, _)| id),
            Some(id2)
        );

        state.remove_item(id2);
        assert!(
            state.peek_next_ready_after(id2).is_none(),
            "a vanished reference must not resolve to the head of the queue"
        );
        assert_ne!(
            state.peek_next_ready_after(id2).map(|(id, _)| id),
            Some(id0)
        );
    }

    // --- surviving_item_before ---

    #[test]
    fn surviving_predecessor_skips_items_being_removed() {
        let state = SharedPlayerState::new();
        let items: Vec<_> = (0..4).map(|i| ready_item(&format!("track-{i}"))).collect();
        let ids: Vec<_> = items.iter().map(|i| i.id).collect();
        state.add_items(items);

        // Deleting 1..=3 leaves 0 as the resume point for a cursor on 3.
        assert_eq!(
            state.surviving_item_before(ids[3], &ids[1..4]),
            Some(ids[0])
        );
        // Deleting everything from the top leaves nothing to resume after.
        assert_eq!(state.surviving_item_before(ids[2], &ids), None);
    }

    // --- retreat_cursor ---

    #[test]
    fn test_retreat_cursor_goes_to_previous_item() {
        let state = SharedPlayerState::new();
        let item0 = ready_item("track-0");
        let item1 = ready_item("track-1");
        let id0 = item0.id;
        let id1 = item1.id;

        state.add_items(vec![item0, item1]);
        state.set_cursor(Some(id1));

        let result = state.retreat_cursor();
        assert!(result.is_some(), "expected to retreat to previous item");
        assert_eq!(result.unwrap().0, id0, "should retreat to first item");
        assert_eq!(state.cursor(), Some(id0));
    }

    #[test]
    fn test_retreat_cursor_returns_none_when_at_first_item() {
        let state = SharedPlayerState::new();
        let item0 = ready_item("only-track");
        let id0 = item0.id;

        state.add_items(vec![item0]);
        state.set_cursor(Some(id0));

        let result = state.retreat_cursor();
        assert!(result.is_none(), "cannot retreat before the first item");
        // Cursor stays on the first item.
        assert_eq!(state.cursor(), Some(id0));
    }

    #[test]
    fn test_retreat_cursor_returns_none_when_cursor_is_unset() {
        let state = SharedPlayerState::new();
        state.add_items(vec![ready_item("track-0")]);

        let result = state.retreat_cursor();
        assert!(
            result.is_none(),
            "retreat with no cursor should return None"
        );
    }

    // --- derive_visible_queue ---

    #[test]
    fn test_derive_visible_queue_statuses() {
        // playlist: [played, playing, queued]
        let state = SharedPlayerState::new();
        let item0 = ready_item("played-track");
        let item1 = ready_item("playing-track");
        let item2 = ready_item("queued-track");
        let id1 = item1.id;

        state.add_items(vec![item0, item1, item2]);
        state.set_cursor(Some(id1));

        let snap = state.derive_visible_queue();

        assert_eq!(snap.entries.len(), 3);
        assert_eq!(snap.entries[0].status, QueueEntryStatus::Played);
        assert_eq!(snap.entries[1].status, QueueEntryStatus::Playing);
        assert_eq!(snap.entries[2].status, QueueEntryStatus::Queued);
        assert!(snap.has_playing);
        assert_eq!(snap.finished_count, 1);
        assert_eq!(snap.queue_count, 1);
    }

    #[test]
    fn test_derive_visible_queue_downloading_statuses() {
        // A Downloading item at cursor → PriorityPending; after cursor → Downloading.
        let state = SharedPlayerState::new();
        let bytes_cursor = Arc::new(AtomicU64::new(0));
        let bytes_queued = Arc::new(AtomicU64::new(0));
        let dl_cursor = make_item(
            "downloading-at-cursor",
            LoadState::Downloading {
                total: 1_000_000,
                bytes_written: bytes_cursor.clone(),
            },
        );
        let dl_queued = make_item(
            "downloading-queued",
            LoadState::Downloading {
                total: 500_000,
                bytes_written: bytes_queued.clone(),
            },
        );
        let id_cursor = dl_cursor.id;

        state.add_items(vec![dl_cursor, dl_queued]);
        state.set_cursor(Some(id_cursor));

        let snap = state.derive_visible_queue();

        assert_eq!(snap.entries[0].status, QueueEntryStatus::PriorityPending);
        assert_eq!(snap.entries[1].status, QueueEntryStatus::Downloading);
    }

    #[test]
    fn progress_follows_the_counter_without_touching_the_playlist() {
        // The download thread writes bytes and nothing else. A queue derived
        // afterwards must see them — the version has not moved, and the load
        // state it was given is the one it still holds.
        let state = SharedPlayerState::new();
        let bytes = Arc::new(AtomicU64::new(0));
        let item = make_item(
            "downloading",
            LoadState::Downloading {
                total: 1_000,
                bytes_written: bytes.clone(),
            },
        );
        state.add_items(vec![item]);

        let version = state.playlist_version();
        bytes.store(250, Ordering::Release);

        let snap = state.derive_visible_queue();
        assert_eq!(snap.entries[0].download_progress, Some((250, 1_000)));
        assert_eq!(
            state.playlist_version(),
            version,
            "progress must not read as a queue mutation"
        );
        assert_eq!(
            state.downloads_in_flight(),
            vec![(snap.entries[0].id, 250, 1_000)]
        );
    }

    #[test]
    fn test_derive_visible_queue_no_cursor_all_queued() {
        let state = SharedPlayerState::new();
        state.add_items(vec![ready_item("a"), ready_item("b"), ready_item("c")]);

        let snap = state.derive_visible_queue();

        assert_eq!(snap.entries.len(), 3);
        for entry in &snap.entries {
            assert_eq!(entry.status, QueueEntryStatus::Queued);
        }
        assert!(!snap.has_playing);
        assert_eq!(snap.finished_count, 0);
        assert_eq!(snap.queue_count, 3);
    }

    // --- same_album_item_ids ---

    fn make_album_item(title: &str, album: &str, album_artist: &str) -> PlaylistItem {
        PlaylistItem {
            id: QueueItemId::new(),
            db_id: None,
            path: PathBuf::from(format!("/music/{title}.flac")),
            title: title.to_string(),
            artist: "Artist".to_string(),
            album_artist: album_artist.to_string(),
            album: album.to_string(),
            year: None,
            codec: Some("FLAC".to_string()),
            track_number: None,
            disc: None,
            duration_ms: Some(200_000),
            load_state: LoadState::Ready,
        }
    }

    #[test]
    fn test_same_album_item_ids_returns_album_mates() {
        let state = SharedPlayerState::new();
        let a1 = make_album_item("A1", "Album A", "Artist A");
        let a2 = make_album_item("A2", "Album A", "Artist A");
        let b1 = make_album_item("B1", "Album B", "Artist B");
        let a3 = make_album_item("A3", "Album A", "Artist A");

        let id_a1 = a1.id;
        let id_a2 = a2.id;
        let id_a3 = a3.id;

        state.add_items(vec![a1, a2, b1, a3]);

        let mates = state.same_album_item_ids(id_a1);
        assert_eq!(mates.len(), 2);
        assert!(mates.contains(&id_a2));
        assert!(mates.contains(&id_a3));
    }

    #[test]
    fn test_same_album_item_ids_distinguishes_album_artists() {
        // Two albums named the same but by different artists — should NOT match.
        let state = SharedPlayerState::new();
        let a1 = make_album_item("A1", "Greatest Hits", "Artist A");
        let b1 = make_album_item("B1", "Greatest Hits", "Artist B");

        let id_a1 = a1.id;

        state.add_items(vec![a1, b1]);

        let mates = state.same_album_item_ids(id_a1);
        assert!(mates.is_empty(), "different album_artist should not match");
    }

    #[test]
    fn test_same_album_item_ids_unknown_id_returns_empty() {
        let state = SharedPlayerState::new();
        state.add_items(vec![ready_item("track-0")]);

        let bogus = QueueItemId::new();
        let mates = state.same_album_item_ids(bogus);
        assert!(mates.is_empty());
    }

    // --- move_item_to ---

    #[test]
    fn test_move_item_to_reorders_playlist() {
        // Start: [A, B, C]. Move C to after A → [A, C, B].
        let state = SharedPlayerState::new();
        let item_a = ready_item("A");
        let item_b = ready_item("B");
        let item_c = ready_item("C");
        let id_a = item_a.id;
        let id_b = item_b.id;
        let id_c = item_c.id;

        state.add_items(vec![item_a, item_b, item_c]);
        state.move_item_to(id_c, Some(id_a));

        let (items, _) = state.snapshot_playlist();
        let titles: Vec<&str> = items.iter().map(|i| i.title.as_str()).collect();
        assert_eq!(titles, vec!["A", "C", "B"]);
        assert_eq!(items[0].id, id_a);
        assert_eq!(items[1].id, id_c);
        assert_eq!(items[2].id, id_b);
    }

    #[test]
    fn test_move_item_to_front_when_after_is_none() {
        // Start: [A, B, C]. Move C to front (after=None) → [C, A, B].
        let state = SharedPlayerState::new();
        let item_a = ready_item("A");
        let item_b = ready_item("B");
        let item_c = ready_item("C");
        let id_c = item_c.id;

        state.add_items(vec![item_a, item_b, item_c]);
        state.move_item_to(id_c, None);

        let (items, _) = state.snapshot_playlist();
        let titles: Vec<&str> = items.iter().map(|i| i.title.as_str()).collect();
        assert_eq!(titles, vec!["C", "A", "B"]);
    }

    // --- move_items (batch) ---

    #[test]
    fn test_move_items_batch_preserves_relative_order() {
        // Start: [A, B, C, D]. Move [A, C] after D → [B, D, A, C].
        let state = SharedPlayerState::new();
        let item_a = ready_item("A");
        let item_b = ready_item("B");
        let item_c = ready_item("C");
        let item_d = ready_item("D");
        let id_a = item_a.id;
        let id_b = item_b.id;
        let id_c = item_c.id;
        let id_d = item_d.id;

        state.add_items(vec![item_a, item_b, item_c, item_d]);
        state.move_items(&[id_a, id_c], id_d, true);

        let (items, _) = state.snapshot_playlist();
        let titles: Vec<&str> = items.iter().map(|i| i.title.as_str()).collect();
        assert_eq!(titles, vec!["B", "D", "A", "C"]);
        assert_eq!(items[0].id, id_b);
        assert_eq!(items[1].id, id_d);
        assert_eq!(items[2].id, id_a);
        assert_eq!(items[3].id, id_c);
    }

    // --- pending_downloads ---

    #[test]
    fn test_pending_downloads_collects_pending_with_db_id() {
        let state = SharedPlayerState::new();
        let mut item_a = ready_item("local");
        item_a.db_id = None;

        let mut item_b = pending_item("remote-1");
        item_b.db_id = Some(10);
        let id_b = item_b.id;

        let mut item_c = ready_item("cached");
        item_c.db_id = Some(20);

        let mut item_d = pending_item("remote-2");
        item_d.db_id = Some(30);
        let id_d = item_d.id;

        // Pending without db_id — should NOT appear (no way to download).
        let item_e = pending_item("orphan");

        state.add_items(vec![item_a, item_b, item_c, item_d, item_e]);

        let pending = state.pending_downloads();
        assert_eq!(pending.len(), 2);
        assert_eq!(pending[0], (10, id_b));
        assert_eq!(pending[1], (30, id_d));
    }

    #[test]
    fn test_item_db_id_and_load_state() {
        let state = SharedPlayerState::new();
        let mut item = pending_item("track");
        item.db_id = Some(42);
        let id = item.id;
        state.add_items(vec![item]);

        assert_eq!(state.item_db_id(id), Some(42));
        assert!(matches!(
            state.item_load_state(id),
            Some(LoadState::Pending)
        ));

        state.update_load_state(id, LoadState::Ready);
        assert!(matches!(state.item_load_state(id), Some(LoadState::Ready)));
    }
}