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 {
        // The tail: a v7's leading hex is its timestamp, shared by a whole batch.
        let hex = self.0.simple().to_string();
        write!(f, "QId({})", &hex[hex.len() - 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 ---

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

/// Held back from the seekable extent of a downloading track.
///
/// Bytes are converted to time at the average bitrate, so on VBR the estimate
/// wanders either side of the truth; landing short of the write head costs a
/// couple of seconds of reach and landing past it costs a stall.
pub const SEEK_SAFETY_MS: u64 = 2_000;

/// What a playlist item can say about itself.
///
/// Only what is true of the item regardless of any transfer: whether the bytes
/// at its path can be played. Whether one is *arriving* is the download store's
/// business, and asking the item would mean two accounts of one fact that have
/// to be kept in step. Read [`LoadState`] for the two
/// together.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub enum ItemState {
    /// Nothing has resolved this yet.
    #[default]
    Pending,
    /// The file at `path` is there and playable.
    Ready,
    /// It cannot be made playable, and this is why. Not only download
    /// failures: a track with no local file and no remote copy fails here
    /// without a transfer ever being attempted.
    Failed(String),
}

/// An item's state, and any transfer against it, as one answer.
///
/// Derived rather than stored. `Downloading` carries the store's own figures —
/// the very same counter the downloader writes — so there is nothing to copy
/// and nothing that can drift.
#[derive(Debug, Clone)]
pub enum LoadState {
    Pending,
    Downloading {
        /// Where the bytes are going: the in-progress `.part` file, not the
        /// destination it is renamed to at the end.
        path: PathBuf,
        /// 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 any lock the player holds.
        bytes_written: Arc<crate::remote::downloads::ByteFeed>,
    },
    Ready,
    Failed(String),
}

impl LoadState {
    /// An item's state, with whatever the download store says about it.
    ///
    /// The store wins while a transfer is live, because it is the thing being
    /// told. Once one has settled the item's own state stands: a finished
    /// transfer leaves a file, and a file is what playback cares about.
    pub fn of(item: &PlaylistItem) -> Self {
        use crate::remote::downloads::{DownloadState, store};

        if let Some(transfer) = store().get(item.id) {
            match transfer.state {
                DownloadState::Queued | DownloadState::Running => {
                    return Self::Downloading {
                        path: transfer.source,
                        total: transfer.total,
                        bytes_written: transfer.written,
                    };
                }
                // A transfer that failed explains an item that cannot play,
                // but only while the item has not since been resolved some
                // other way — a retry, or a copy found on disk.
                DownloadState::Failed(reason) if item.state == ItemState::Pending => {
                    return Self::Failed(reason);
                }
                DownloadState::Failed(_) | DownloadState::Done => {}
            }
        }

        match &item.state {
            ItemState::Pending => Self::Pending,
            ItemState::Ready => Self::Ready,
            ItemState::Failed(reason) => Self::Failed(reason.clone()),
        }
    }
}

/// 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<crate::remote::downloads::ByteFeed>,
        total: u64,
    },
}

/// A single item in the playlist. 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>,
    /// The playlist entry this came from, when it came from a playlist.
    ///
    /// A playlist may hold the same track twice, and two copies are two queue
    /// items. Without this a playlist row can only ask "is my *track* playing?"
    /// and both copies answer yes. The entry id is the one thing that tells
    /// them apart, so the queue carries it.
    pub playlist_entry_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>,
    /// What the item can say about itself. Ask [`SharedPlayerState::load_state`]
    /// for this together with any transfer against it.
    pub state: ItemState,
}

/// 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 ---

/// 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>,
    /// The playlist row this came from — see `PlaylistItem::playlist_entry_id`.
    pub playlist_entry_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,
    /// Where a session starts, and where a stopped one stands. While one is
    /// running the playhead is read off the timeline instead.
    position_ms: AtomicU64,
    timeline: std::sync::OnceLock<Arc<crate::audio::buffer::PlaybackTimeline>>,
    track_info: parking_lot::RwLock<Option<TrackInfo>>,

    /// The playlist and its cursor, under one lock.
    playlist: parking_lot::RwLock<Playlist>,

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

    /// Bumped only when what a saved session holds changes: the items and
    /// their metadata, not the cursor or load states. What decides whether
    /// the saved queue has to be written again.
    content_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,
}

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

    // --- 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);
        self.changed();
    }

    /// Where the playhead is, read off the samples the output has played, so
    /// it is right whenever it is asked and nothing has to keep it up to date.
    pub fn position_ms(&self) -> u64 {
        if self.playback_state() != PlaybackState::Stopped
            && let Some((_, at)) = self.timeline.get().and_then(|t| t.playhead())
        {
            return at;
        }
        self.position_ms.load(Ordering::Acquire)
    }

    /// The timeline the playhead is read from. Set once, by the player.
    pub(crate) fn attach_timeline(&self, timeline: Arc<crate::audio::buffer::PlaybackTimeline>) {
        let _ = self.timeline.set(timeline);
    }

    pub fn set_position_ms(&self, pos: u64) {
        self.position_ms.store(pos, Ordering::Release);
        // Deliberately silent. The playhead advances on its own and is
        // published as an anchor rather than as a reading — a wake per
        // position would be the tick this whole arrangement removes. A seek, a
        // pause and a track change all move something else here as well, and
        // those are exactly the ones a client has to be told about.
    }

    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;
        self.changed();
    }

    /// How far into the currently playing track a seek can land.
    ///
    /// A track on disk is seekable end to end. One still downloading is
    /// seekable only as far as its bytes reach: bytes map to time by the
    /// average bitrate, exact for lossless and CBR and drifting on VBR, which
    /// is what `SEEK_SAFETY_MS` covers. Zero when nothing is playing.
    ///
    /// The one value both the clamp in `Player::seek` and the extent front ends
    /// draw on the seek bar come from — a bar that shows a reachable position
    /// the player then refuses is worse than no bar.
    pub fn seekable_ms(&self) -> u64 {
        let Some(info) = self.track_info.read().clone() else {
            return 0;
        };

        // 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 pl = self.playlist.read();
        let Some(item) = pl.items.iter().find(|item| item.id == info.id) else {
            return info.duration_ms;
        };

        let LoadState::Downloading {
            total,
            bytes_written,
            ..
        } = LoadState::of(item)
        else {
            return info.duration_ms;
        };

        // A container that could not describe itself from the bytes downloaded
        // states no duration, and cannot be seeked at all until the rest of it
        // lands — there is no index to seek against and no end to seek within.
        // Ogg is the one that does this; it keeps its duration in its last page.
        if info.duration_ms == 0 {
            return 0;
        }

        let written = bytes_written.load(Ordering::Acquire);
        let reached = if total > 0 && info.duration_ms > 0 {
            ((written as f64 / total as f64) * info.duration_ms as f64) as u64
        } else if let Some(kbps) = info.bitrate_kbps.filter(|k| *k > 0) {
            // No Content-Length. Bytes still say how much audio has arrived,
            // given what the probe measured the bitrate to be: 1 kbps is
            // 1 bit per ms, so bits divided by kbps is milliseconds.
            written.saturating_mul(8) / kbps as u64
        } else {
            // Nothing to derive a position from — forward seeking would be a
            // guess, so allow only what has already been played.
            return self.position_ms();
        };

        reached.saturating_sub(SEEK_SAFETY_MS).min(info.duration_ms)
    }

    /// The duration to show for what is playing.
    ///
    /// The container's own answer wherever it gave one. A partial file that
    /// could not be read far enough to state a duration has none, and the
    /// library's figure stands in — it came from the server, it is right, and
    /// a transport that reads 0:00 for nine hours of music is worse than one
    /// reading a figure the container has not caught up with yet.
    pub fn duration_ms(&self) -> u64 {
        let Some(info) = self.track_info.read().clone() else {
            return 0;
        };
        if info.duration_ms > 0 {
            return info.duration_ms;
        }
        // Released before the playlist lock, as everywhere else here.
        self.playlist
            .read()
            .items
            .iter()
            .find(|item| item.id == info.id)
            .and_then(|item| item.duration_ms)
            .unwrap_or(0)
    }

    /// `seekable_ms`, but `None` when the whole track is reachable — which is
    /// every track that is not mid-download. What a front end draws a boundary
    /// from: no boundary is the normal case and should cost no mark.
    pub fn seek_ceiling_ms(&self) -> Option<u64> {
        let duration = self.duration_ms();
        if duration == 0 {
            return None;
        }
        let seekable = self.seekable_ms();
        (seekable < duration).then_some(seekable)
    }

    /// 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 LoadState::of(item) {
                LoadState::Downloading {
                    bytes_written,
                    total,
                    ..
                } => {
                    let written = bytes_written.load(Ordering::Acquire);
                    (total > 0).then(|| (written as f64 / total as f64).min(1.0))
                }
                _ => 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 ---

    /// 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);
        self.changed();
    }

    /// 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()
    }

    // --- 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);
        self.changed();
    }

    /// Back to "not known yet", for the window where the device is between
    /// rates. A switch takes as long as the hardware needs to reclock — the
    /// better part of a second on USB — and the previous track's rate is not
    /// an answer for this one.
    pub fn clear_output_sample_rate(&self) {
        self.output_sample_rate.store(0, 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);
        self.changed();
    }

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

    /// `bump_version`, for a change to what a saved session holds.
    fn bump_content(&self) {
        self.content_version.fetch_add(1, Ordering::AcqRel);
        self.bump_version();
    }

    /// Say that something here moved, without saying what.
    ///
    /// Every version and atomic in this struct stays exactly as it was — they
    /// are what a watcher consults to find out what changed. This is what
    /// spares it looking when nothing did. See `crate::signal`.
    pub fn changed(&self) {
        crate::signal::engine_changed().bump();
    }

    // --- 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_content();
    }

    /// 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_content();
    }

    /// 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_content();
    }

    /// 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_content();
    }

    /// 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_content();
    }

    /// 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_content();
    }

    /// 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();
    }

    pub fn cursor(&self) -> Option<QueueItemId> {
        self.playlist.read().cursor
    }

    /// The path of the item under the cursor, without copying the playlist.
    pub fn cursor_path(&self) -> Option<PathBuf> {
        let pl = self.playlist.read();
        let cursor = pl.cursor?;
        pl.items
            .iter()
            .find(|item| item.id == cursor)
            .map(|item| item.path.clone())
    }

    /// 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_content();
    }

    // --- 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.state, ItemState::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].state, ItemState::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.
    pub fn update_item_state(&self, id: QueueItemId, new_state: ItemState) {
        let mut pl = self.playlist.write();
        if let Some(item) = pl.items.iter_mut().find(|item| item.id == id) {
            item.state = new_state;
        }
        drop(pl);
        self.bump_version();
    }

    /// Take what a finished download's own tags can add.
    ///
    /// Streaming starts on partial Symphonia tags, so an item with nothing
    /// behind it takes the lot once the whole file is there. An item that came
    /// out of the library does not: the record is what the queue was built
    /// from and what every other track on it carries, and a file whose tags
    /// disagree — a server album titled one way, the file inside titled
    /// another — would split its album in two the moment it finished
    /// downloading. The duration is the file's to know either way.
    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) {
            if item.db_id.is_none() {
                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_content();
    }

    /// 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 LoadState::of(item) {
                LoadState::Ready => Some(PlaybackSource::Ready(item.path.clone())),
                LoadState::Downloading {
                    path,
                    total,
                    bytes_written,
                } => {
                    let written = bytes_written.load(Ordering::Acquire);
                    (written >= STREAM_THRESHOLD).then_some(PlaybackSource::Streaming {
                        path,
                        bytes_written,
                        total,
                    })
                }
                _ => None,
            })
    }

    /// Put back to `Pending` every queue item whose file has gone, and say
    /// which they were so they can be fetched again.
    ///
    /// The queue holds paths, and clearing downloads deletes the files under
    /// them. An item left claiming `Ready` opens nothing when it is played —
    /// it is not broken, it is a remote track that has to be fetched a second
    /// time. Only items with a database row behind them: one without has
    /// nowhere to be fetched from, and parking the cursor on it would be worse
    /// than letting it fail honestly.
    pub fn reset_items_with_missing_files(&self) -> Vec<(i64, QueueItemId)> {
        let mut pl = self.playlist.write();
        let mut reset = Vec::new();
        for item in pl.items.iter_mut() {
            let Some(db_id) = item.db_id else { continue };
            if !matches!(item.state, ItemState::Ready) {
                continue;
            }
            if item.path.exists() {
                continue;
            }
            item.state = ItemState::Pending;
            reset.push((db_id, item.id));
        }
        drop(pl);
        if !reset.is_empty() {
            self.bump_version();
        }
        reset
    }

    /// The item's path if it is `Ready`. A caller that can stream wants `item_playback_source`.
    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.state, ItemState::Ready) {
                Some(item.path.clone())
            } else {
                None
            }
        })
    }

    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.state, ItemState::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)> {
        crate::remote::downloads::store()
            .all()
            .iter()
            .filter(|d| !d.state.is_settled())
            .map(|d| (d.id, d.bytes_written(), d.total))
            .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(LoadState::of)
    }

    // --- 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)
        }
    }

    /// Put the items in exactly this order.
    ///
    /// Items not named keep their relative order and follow at the end, so a
    /// stale order cannot lose anything. The items themselves are moved, not
    /// rebuilt: their ids, load states and download progress are what the rest
    /// of the player is holding on to.
    pub fn reorder_to(&self, order: &[QueueItemId]) {
        let mut pl = self.playlist.write();
        let mut taken: Vec<Option<PlaylistItem>> = pl.items.drain(..).map(Some).collect();
        let mut sorted = Vec::with_capacity(taken.len());
        for id in order {
            if let Some(slot) = taken
                .iter_mut()
                .find(|i| i.as_ref().is_some_and(|i| i.id == *id))
                && let Some(item) = slot.take()
            {
                sorted.push(item);
            }
        }
        sorted.extend(taken.into_iter().flatten());
        pl.items = sorted;
        drop(pl);
        self.bump_content();
    }

    /// 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_content();
    }

    /// 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_content();
    }

    /// 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_content();
    }

    /// 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_content();
    }

    /// 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);

            // The byte count is the download thread's own counter, written per
            // chunk without the playlist lock, so a transfer never bumps the
            // playlist version. Derived once per row because every branch below
            // wants the item's state and its transfer together.
            let load_state = LoadState::of(item);

            let dl_progress = match &load_state {
                LoadState::Downloading {
                    total,
                    bytes_written,
                    ..
                } => Some((bytes_written.load(Ordering::Relaxed), *total)),
                _ => None,
            };

            let status = if is_cursor {
                has_playing = true;
                match &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 &load_state {
                    LoadState::Ready => QueueEntryStatus::Played,
                    LoadState::Downloading { .. } => QueueEntryStatus::Downloading,
                    LoadState::Pending => QueueEntryStatus::Downloading,
                    LoadState::Failed(_) => QueueEntryStatus::Failed,
                }
            } else {
                queue_count += 1;
                match &load_state {
                    LoadState::Ready => QueueEntryStatus::Queued,
                    LoadState::Downloading { .. } => QueueEntryStatus::Downloading,
                    // Waiting its turn, not arriving: a spinner on every one
                    // of these read as the whole album downloading at once.
                    LoadState::Pending => QueueEntryStatus::Queued,
                    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,
                playlist_entry_id: item.playlist_entry_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 &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, state: ItemState) -> PlaylistItem {
        PlaylistItem {
            playlist_entry_id: None,
            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),
            state,
        }
    }

    /// An item with a transfer running against it, told to the store the way
    /// the downloader tells it.
    fn downloading_item(
        title: &str,
        total: u64,
        written: Arc<crate::remote::downloads::ByteFeed>,
    ) -> PlaylistItem {
        let item = make_item(title, ItemState::Pending);
        let store = crate::remote::downloads::store();
        store.queued(crate::remote::downloads::Download {
            id: item.id,
            track_id: 1,
            title: title.into(),
            artist: String::new(),
            source: PathBuf::from(format!("/cache/{title}.flac.part")),
            dest: PathBuf::from(format!("/cache/{title}.flac")),
            total,
            written: written.clone(),
            state: crate::remote::downloads::DownloadState::Queued,
            bytes_per_second: 0,
        });
        store.started(item.id, total, written);
        item
    }

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

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

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

    const DURATION_MS: u64 = 32_523_787;

    /// A nine-hour track under the cursor, `downloaded` bytes of `total` in.
    /// `total` of 0 stands for a server that sent no Content-Length.
    fn streaming_state(
        downloaded: u64,
        total: u64,
        bitrate_kbps: Option<u32>,
    ) -> Arc<SharedPlayerState> {
        streaming_state_with_duration(downloaded, total, bitrate_kbps, DURATION_MS)
    }

    /// The same, but saying what the container managed to state about itself.
    /// A partial Ogg states nothing, which is zero here.
    fn streaming_state_with_duration(
        downloaded: u64,
        total: u64,
        bitrate_kbps: Option<u32>,
        container_duration_ms: u64,
    ) -> Arc<SharedPlayerState> {
        let written = crate::remote::downloads::ByteFeed::new();
        written.set(downloaded);
        let item = make_item("train", ItemState::Pending);
        let id = item.id;
        let path = item.path.clone();

        // The transfer goes where transfers go. Ids are unique per item, so
        // tests sharing the process store never see each other's.
        let store = crate::remote::downloads::store();
        store.queued(crate::remote::downloads::Download {
            id,
            track_id: 1,
            title: "train".into(),
            artist: String::new(),
            source: PathBuf::from("/cache/train.opus.part"),
            dest: PathBuf::from("/cache/train.opus"),
            total,
            written: written.clone(),
            state: crate::remote::downloads::DownloadState::Queued,
            bytes_per_second: 0,
        });
        store.started(id, total, written);

        let state = SharedPlayerState::new();
        state.add_items(vec![item]);
        state.set_cursor(Some(id));
        state.set_track_info(Some(TrackInfo {
            id,
            path,
            codec: "Opus".into(),
            sample_rate: 48_000,
            bit_depth: None,
            bitrate_kbps,
            channels: 2,
            duration_ms: container_duration_ms,
        }));
        state
    }

    // --- seekable_ms ---

    #[test]
    fn a_track_on_disk_is_seekable_end_to_end() {
        let item = ready_item("done");
        let id = item.id;
        let path = item.path.clone();
        let state = SharedPlayerState::new();
        state.add_items(vec![item]);
        state.set_cursor(Some(id));
        state.set_track_info(Some(TrackInfo {
            id,
            path,
            codec: "FLAC".into(),
            sample_rate: 44_100,
            bit_depth: Some(16),
            bitrate_kbps: None,
            channels: 2,
            duration_ms: 200_000,
        }));

        assert_eq!(state.seekable_ms(), 200_000);
        // Nothing to draw a boundary for, so front ends are told there isn't one.
        assert_eq!(state.seek_ceiling_ms(), None);
    }

    #[test]
    fn a_downloading_track_is_seekable_as_far_as_its_bytes_reach() {
        // A quarter of a nine-hour file in: a quarter of the way through it,
        // less the margin the byte-to-time estimate is worth.
        let state = streaming_state(100, 400, None);
        assert_eq!(state.seekable_ms(), 32_523_787 / 4 - SEEK_SAFETY_MS);
        assert_eq!(
            state.seek_ceiling_ms(),
            Some(32_523_787 / 4 - SEEK_SAFETY_MS)
        );
    }

    #[test]
    fn a_transfer_without_a_content_length_falls_back_to_bitrate() {
        // No total to take a fraction of. 128 kbps is 128 bits per ms, so a
        // megabyte is 8 388 608 bits and a little over 65 seconds.
        let state = streaming_state(1024 * 1024, 0, Some(128));
        assert_eq!(state.seekable_ms(), 1024 * 1024 * 8 / 128 - SEEK_SAFETY_MS);
    }

    #[test]
    fn nothing_to_estimate_from_allows_no_forward_seek() {
        // Neither a length nor a bitrate: anywhere past the playhead is a
        // guess, and a guess that lands past the write head is a stall.
        let state = streaming_state(1024 * 1024, 0, None);
        state.set_position_ms(12_000);
        assert_eq!(state.seekable_ms(), 12_000);
    }

    #[test]
    fn the_seekable_extent_never_exceeds_the_track() {
        // A download reporting more bytes than it advertised must not offer a
        // seek past the end of the music.
        let state = streaming_state(500, 400, None);
        assert_eq!(state.seekable_ms(), 32_523_787);
    }

    #[test]
    fn nothing_playing_is_seekable_nowhere() {
        assert_eq!(SharedPlayerState::new().seekable_ms(), 0);
        assert_eq!(SharedPlayerState::new().seek_ceiling_ms(), None);
    }

    #[test]
    fn a_container_that_cannot_state_its_duration_cannot_be_seeked() {
        // A partial Ogg keeps its duration in a last page that has not arrived,
        // so it opens and plays but has nothing to seek against. Half the bytes
        // being present does not change that.
        let state = streaming_state_with_duration(200, 400, Some(128), 0);
        assert_eq!(state.seekable_ms(), 0);
    }

    #[test]
    fn the_library_duration_stands_in_for_a_silent_container() {
        // What is shown on the transport, so nine hours of music does not read
        // as 0:00 while it caches.
        let state = streaming_state_with_duration(200, 400, Some(128), 0);
        assert_eq!(state.duration_ms(), 200_000, "the item's own figure");
        // And it is a display figure only — it grants no seeking.
        assert_eq!(state.seekable_ms(), 0);
        assert_eq!(state.seek_ceiling_ms(), Some(0));
    }

    #[test]
    fn the_container_duration_wins_where_there_is_one() {
        let state = streaming_state(200, 400, None);
        assert_eq!(state.duration_ms(), DURATION_MS);
    }

    #[test]
    fn the_download_landing_restores_seeking() {
        // The sequence the whole design turns on: a track that opened without a
        // duration gets one when the finished file is re-read, and is seekable
        // end to end from that moment — no restart, no handover.
        let state = streaming_state_with_duration(400, 400, Some(128), 0);
        assert_eq!(state.seekable_ms(), 0);

        // What the downloader does when the bytes land: settle the transfer,
        // then say the file is playable. In that order — while the store still
        // says a transfer is running, it is.
        let id = state.cursor().expect("cursor");
        crate::remote::downloads::store().finished(id);
        state.update_item_state(id, ItemState::Ready);
        let info = state.track_info().expect("track info");
        state.set_track_info(Some(TrackInfo {
            duration_ms: DURATION_MS,
            ..info
        }));

        assert_eq!(state.seekable_ms(), DURATION_MS);
        assert_eq!(state.seek_ceiling_ms(), None, "no boundary left to draw");
    }

    // --- 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 = crate::remote::downloads::ByteFeed::new();
        let bytes_queued = crate::remote::downloads::ByteFeed::new();
        let dl_cursor = downloading_item("downloading-at-cursor", 1_000_000, bytes_cursor.clone());
        let dl_queued = downloading_item("downloading-queued", 500_000, 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);
    }

    /// The saved queue is rewritten when its contents move, and only then:
    /// a track change or a download landing is a position save.
    #[test]
    fn only_a_change_to_what_is_saved_moves_the_content_version() {
        let state = SharedPlayerState::new();
        let a = make_item("a", ItemState::Pending);
        let b = make_item("b", ItemState::Ready);
        let (a_id, b_id) = (a.id, b.id);

        let start = state.content_version();
        state.add_items(vec![a, b]);
        let added = state.content_version();
        assert_ne!(added, start);

        state.set_cursor(Some(a_id));
        state.update_item_state(a_id, ItemState::Ready);
        state.advance_cursor_loadable();
        state.retreat_cursor();
        assert_eq!(state.content_version(), added);
        assert_eq!(state.cursor_path(), Some(PathBuf::from("/music/a.flac")));

        state.move_item_to(b_id, None);
        assert_ne!(state.content_version(), added);
    }

    #[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 = crate::remote::downloads::ByteFeed::new();
        let item = downloading_item("downloading", 1_000, bytes.clone());
        state.add_items(vec![item]);

        let version = state.playlist_version();
        bytes.set(250);

        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"
        );
        // Every transfer the process knows about, not just this playlist's —
        // a fetch with no queue item behind it is still a transfer, and the
        // store is what is asked. Other tests share it, so this looks for its
        // own rather than asserting the whole list.
        assert!(
            state
                .downloads_in_flight()
                .contains(&(snap.entries[0].id, 250, 1_000)),
            "the counter should be visible through the store"
        );
    }

    #[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 {
            playlist_entry_id: None,
            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),
            state: ItemState::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());
    }

    // --- update_item_metadata ---

    #[test]
    fn test_update_item_metadata_leaves_library_tags_alone() {
        let state = SharedPlayerState::new();
        let mut item = make_album_item("A1", "Nite Versions (mixed)", "Soulwax");
        item.db_id = Some(29615);
        let id = item.id;
        state.add_items(vec![item]);

        state.update_item_metadata(
            id,
            "[unknown]".into(),
            "Soulwax".into(),
            "Soulwax".into(),
            "Nite Versions".into(),
            Some(54_000),
        );

        let pl = state.playlist.read();
        assert_eq!(pl.items[0].album, "Nite Versions (mixed)");
        assert_eq!(pl.items[0].title, "A1");
        assert_eq!(pl.items[0].duration_ms, Some(54_000));
    }

    #[test]
    fn test_update_item_metadata_fills_in_an_item_with_nothing_behind_it() {
        let state = SharedPlayerState::new();
        let item = make_album_item("A1", "", "");
        let id = item.id;
        state.add_items(vec![item]);

        state.update_item_metadata(
            id,
            "Teachers".into(),
            "Soulwax".into(),
            "Soulwax".into(),
            "Nite Versions".into(),
            Some(148_000),
        );

        let pl = state.playlist.read();
        assert_eq!(pl.items[0].title, "Teachers");
        assert_eq!(pl.items[0].album, "Nite Versions");
        assert_eq!(pl.items[0].duration_ms, Some(148_000));
    }

    // --- 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_item_state(id, ItemState::Ready);
        assert!(matches!(state.item_load_state(id), Some(LoadState::Ready)));
    }
}