Fix tests

scripts/build-android.sh

@@ -44,6 +44,9 @@ bun run build
 
 # Step 2: Build Android APK
 if [ "$BUILD_TYPE" = "release" ]; then
+    # Configure release signing from .env (single source of truth). Must run
+    # after sync-android-sources.sh, since gen/android is (re)generated there.
+    ./scripts/write-keystore-properties.sh
     echo "📦 Building release APK..."
     bun run tauri android build --apk true
 else

scripts/sync-android-sources.sh

@@ -70,6 +70,20 @@ if [ -d "$RES_SRC" ]; then
     # render well, and our adaptive-icon xml no longer references it, so a stray
     # ic_launcher_monochrome.png would just be dead weight.
     rm -f "$RES_DST"/mipmap-*/ic_launcher_monochrome.png
+
+    # `tauri android init` also emits the Android Studio DEFAULT adaptive icon
+    # as API-qualified VECTOR drawables:
+    #   drawable/ic_launcher_background.xml      (solid #3DDC84 green)
+    #   drawable-v24/ic_launcher_foreground.xml  (the Android robot)
+    # Because drawable-v24 is a more specific match than our unqualified
+    # mipmap-*/ic_launcher_*.png, on API 24+ the vector WINS and the app ships
+    # the green square robot instead of our jellyfish. Remove them so the
+    # adaptive-icon xml resolves @mipmap/ic_launcher_{background,foreground}
+    # to the real committed PNGs.
+    rm -f "$RES_DST"/drawable/ic_launcher_background.xml \
+          "$RES_DST"/drawable-v24/ic_launcher_foreground.xml \
+          "$RES_DST"/drawable*/ic_launcher_foreground.xml \
+          "$RES_DST"/drawable*/ic_launcher_background.xml
 fi
 
 echo "✓ Android sources synced successfully"

scripts/write-keystore-properties.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Regenerate src-tauri/gen/android/keystore.properties from the gitignored .env.
+#
+# .env is the single source of truth for local release signing. `tauri android
+# init` wipes/regenerates gen/android, so keystore.properties must be rewritten
+# from .env before every release build (this is the local mirror of what the CI
+# workflow does from Gitea secrets).
+#
+# Required .env vars:
+#   ANDROID_KEY_ALIAS, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_PASSWORD,
+#   ANDROID_KEYSTORE_FILE (absolute path to the .jks)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+ENV_FILE="$PROJECT_ROOT/.env"
+PROPS="$PROJECT_ROOT/src-tauri/gen/android/keystore.properties"
+
+if [ ! -f "$ENV_FILE" ]; then
+    echo "❌ $ENV_FILE not found — cannot configure release signing." >&2
+    echo "   Create it with ANDROID_KEY_ALIAS / ANDROID_KEYSTORE_PASSWORD /" >&2
+    echo "   ANDROID_KEY_PASSWORD / ANDROID_KEYSTORE_FILE." >&2
+    exit 1
+fi
+
+# Load .env without leaking it into the caller's environment beyond what we need.
+set -a
+# shellcheck disable=SC1090
+. "$ENV_FILE"
+set +a
+
+: "${ANDROID_KEY_ALIAS:?ANDROID_KEY_ALIAS missing from .env}"
+: "${ANDROID_KEYSTORE_PASSWORD:?ANDROID_KEYSTORE_PASSWORD missing from .env}"
+: "${ANDROID_KEY_PASSWORD:?ANDROID_KEY_PASSWORD missing from .env}"
+: "${ANDROID_KEYSTORE_FILE:?ANDROID_KEYSTORE_FILE missing from .env}"
+
+if [ ! -f "$ANDROID_KEYSTORE_FILE" ]; then
+    echo "❌ Keystore not found at ANDROID_KEYSTORE_FILE=$ANDROID_KEYSTORE_FILE" >&2
+    exit 1
+fi
+
+mkdir -p "$(dirname "$PROPS")"
+umask 077
+cat > "$PROPS" <<EOF
+storeFile=$ANDROID_KEYSTORE_FILE
+storePassword=$ANDROID_KEYSTORE_PASSWORD
+keyAlias=$ANDROID_KEY_ALIAS
+keyPassword=$ANDROID_KEY_PASSWORD
+EOF
+
+echo "🔐 Wrote release signing config to keystore.properties (from .env)"

src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlaybackService.kt

@@ -295,6 +295,14 @@ class JellyTauPlaybackService : MediaSessionService() {
         // Update MediaSession playback state
         session.setPlaybackState(buildPlaybackState(isPlaying, position))
 
+        // While casting, re-assert the remote volume provider. Metadata pushes
+        // arrive on the session poller thread and can race with (or arrive
+        // before) enableRemoteVolume(); this keeps the session routed to the
+        // remote (absolute) volume slider instead of the local media stream.
+        if (isRemoteVolumeEnabled) {
+            volumeProvider?.let { session.setPlaybackToRemote(it) }
+        }
+
         // Update the notification
         updateNotification(title, artist, isPlaying)
     }
@@ -326,8 +334,17 @@ class JellyTauPlaybackService : MediaSessionService() {
      *
      * The reported playback speed is 1.0 while playing and 0.0 while paused so
      * Android does not extrapolate the position past a paused track.
+     *
+     * While remote volume control is enabled (casting), the state is forced to
+     * STATE_PLAYING regardless of [isPlaying]. Android only surfaces the remote
+     * (absolute) volume slider for a session that is actively playing; if a
+     * periodic metadata/position push reports paused (e.g. before the remote
+     * session has actually started), reporting STATE_PAUSED here makes the
+     * system tear down the remote slider set up by setPlaybackToRemote() and
+     * fall back to the local media-stream volume.
      */
     private fun buildPlaybackState(isPlaying: Boolean, position: Long): PlaybackStateCompat {
+        val playing = isPlaying || isRemoteVolumeEnabled
         return PlaybackStateCompat.Builder()
             .setActions(
                 PlaybackStateCompat.ACTION_PLAY or
@@ -338,9 +355,9 @@ class JellyTauPlaybackService : MediaSessionService() {
                 PlaybackStateCompat.ACTION_SEEK_TO
             )
             .setState(
-                if (isPlaying) PlaybackStateCompat.STATE_PLAYING else PlaybackStateCompat.STATE_PAUSED,
+                if (playing) PlaybackStateCompat.STATE_PLAYING else PlaybackStateCompat.STATE_PAUSED,
                 position,
-                if (isPlaying) 1.0f else 0.0f
+                if (playing) 1.0f else 0.0f
             )
             .build()
     }

src-tauri/src/auth/mod.rs

@@ -133,7 +133,7 @@ impl AuthManager {
 
         log::info!("[AuthManager] Connecting to server: {}", normalized_url);
 
-        match self.http_client.get_json_with_retry::<PublicSystemInfo>(&endpoint).await {
+        match self.http_client.get_json_fast::<PublicSystemInfo>(&endpoint).await {
             Ok(info) => {
                 log::info!("[AuthManager] Connected to server: {} ({})", info.server_name, info.version);
 

src-tauri/src/commands/catalog.rs

@@ -0,0 +1,469 @@
+//! Tauri commands for the offline "browse & queue" feature.
+//!
+//! Two backend pieces support browsing the full server catalog while offline
+//! and queueing downloads that fire on reconnect:
+//!
+//! - [`sync_full_catalog`] walks every library while online and persists all
+//!   items to the offline cache so the whole catalog is browsable (greyed out)
+//!   offline. It reuses [`HybridRepository::cache_items_from_server`], which in
+//!   turn reuses `OfflineRepository::save_to_cache` (sets `synced_at`, which is
+//!   what `get_items` branch 3 serves offline).
+//! - [`resume_queued_downloads`] resolves and pumps the `pending` download rows
+//!   that were queued offline (they have `stream_url IS NULL`), mirroring the
+//!   heal-and-pump pattern in `player_preload_upcoming`.
+
+use std::sync::Arc;
+
+use log::{info, warn};
+use tauri::State;
+
+use crate::commands::repository::RepositoryManagerWrapper;
+use crate::commands::download::{pump_download_queue, DownloadManagerWrapper};
+use crate::commands::storage::DatabaseWrapper;
+use crate::repository::types::GetItemsOptions;
+use crate::storage::db_service::{DatabaseService, Query, QueryParam};
+
+/// app_settings key holding the RFC-3339 timestamp of the last successful
+/// full-catalog sync.
+const LAST_CATALOG_SYNC_KEY: &str = "last_catalog_sync";
+
+/// Item types worth caching for offline browsing: containers the library
+/// landing pages render plus the playable leaves users queue for download.
+const CATALOG_ITEM_TYPES: &[&str] = &[
+    "MusicAlbum",
+    "Movie",
+    "Series",
+    "Season",
+    "Episode",
+    "Audio",
+    "BoxSet",
+];
+
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CatalogSyncResult {
+    /// Total items persisted to the offline cache across all libraries.
+    pub items_cached: usize,
+    /// Libraries that failed to sync (e.g. server hiccup); best-effort.
+    pub libraries_failed: usize,
+}
+
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CatalogSyncStatus {
+    /// RFC-3339 timestamp of the last successful sync, if any.
+    pub last_synced_at: Option<String>,
+}
+
+/// Walk every library on the server and persist all items to the offline cache
+/// so the full catalog is browsable offline (greyed out when not downloaded).
+///
+/// Best-effort: a library that fails to fetch is counted and skipped rather than
+/// aborting the whole sync. Runs libraries sequentially to avoid hammering the
+/// server. Uses `Recursive=true` so a single request per library returns the
+/// containers and their playable children.
+#[tauri::command]
+#[specta::specta]
+pub async fn sync_full_catalog(
+    repository: State<'_, RepositoryManagerWrapper>,
+    db: State<'_, DatabaseWrapper>,
+    handle: String,
+) -> Result<CatalogSyncResult, String> {
+    use crate::repository::MediaRepository;
+
+    let repo = repository.0.get(&handle).ok_or("Repository not found")?;
+
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    let libraries = repo.get_libraries().await.map_err(|e| e.to_string())?;
+    info!("[Catalog] Full sync starting across {} libraries", libraries.len());
+
+    let include_types: Vec<String> = CATALOG_ITEM_TYPES.iter().map(|s| s.to_string()).collect();
+
+    let mut items_cached = 0usize;
+    let mut libraries_failed = 0usize;
+
+    for library in &libraries {
+        let opts = GetItemsOptions {
+            recursive: Some(true),
+            include_item_types: Some(include_types.clone()),
+            limit: Some(100_000),
+            ..Default::default()
+        };
+
+        match repo.cache_items_from_server(&library.id, Some(opts)).await {
+            Ok(items) => {
+                info!(
+                    "[Catalog] Cached {} items from library '{}'",
+                    items.len(),
+                    library.name
+                );
+                items_cached += items.len();
+            }
+            Err(e) => {
+                warn!("[Catalog] Failed to sync library '{}': {:?}", library.name, e);
+                libraries_failed += 1;
+            }
+        }
+    }
+
+    // Record the sync time so callers can skip re-syncing too eagerly.
+    let now = chrono::Utc::now().to_rfc3339();
+    let upsert = Query::with_params(
+        "INSERT INTO app_settings (key, value, updated_at) VALUES (?, ?, CURRENT_TIMESTAMP)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP",
+        vec![
+            QueryParam::String(LAST_CATALOG_SYNC_KEY.to_string()),
+            QueryParam::String(now),
+        ],
+    );
+    if let Err(e) = db_service.execute(upsert).await {
+        warn!("[Catalog] Failed to persist last-sync timestamp: {}", e);
+    }
+
+    info!(
+        "[Catalog] Full sync complete: {} items cached, {} libraries failed",
+        items_cached, libraries_failed
+    );
+
+    Ok(CatalogSyncResult {
+        items_cached,
+        libraries_failed,
+    })
+}
+
+/// Report the last-synced timestamp so the UI can show a hint / decide whether
+/// to trigger a fresh sync.
+#[tauri::command]
+#[specta::specta]
+pub async fn catalog_sync_status(
+    db: State<'_, DatabaseWrapper>,
+) -> Result<CatalogSyncStatus, String> {
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+
+    let query = Query::with_params(
+        "SELECT value FROM app_settings WHERE key = ?",
+        vec![QueryParam::String(LAST_CATALOG_SYNC_KEY.to_string())],
+    );
+    let last_synced_at: Option<String> = db_service
+        .query_optional(query, |row| row.get(0))
+        .await
+        .map_err(|e| e.to_string())?;
+
+    Ok(CatalogSyncStatus { last_synced_at })
+}
+
+/// Control whether offline library queries reveal the full synced catalog
+/// (greyed-out, non-downloaded media) or only downloaded/local media.
+///
+/// The frontend calls this from the "Show all server media" toggle: pass `true`
+/// when online, or when offline with the toggle on; pass `false` when offline
+/// with the toggle off so library pages show downloaded media only. Fixes the
+/// bug where offline library pages showed every server item regardless of the
+/// toggle.
+#[tauri::command]
+#[specta::specta]
+pub fn set_show_server_catalog(show: bool) {
+    crate::repository::offline::set_include_catalog_browse(show);
+}
+
+#[derive(specta::Type, Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ResumeQueuedResult {
+    /// Rows whose stream URL was resolved and are now pump-eligible.
+    pub resolved: usize,
+    /// Rows that couldn't be resolved (item metadata / URL lookup failed).
+    pub failed: usize,
+}
+
+/// Core of [`resume_queued_downloads`], factored out for testing: select every
+/// `pending`/`stream_url IS NULL` row, resolve each via `resolve` (returning
+/// `None` leaves the row pending), and heal the row so the pump can start it.
+/// The `resolve` closure receives `(item_id, media_type, quality_preset)`.
+pub(crate) async fn resolve_pending_download_urls<F, Fut>(
+    db_service: &Arc<crate::storage::db_service::RusqliteService>,
+    target_dir: &str,
+    resolve: F,
+) -> Result<ResumeQueuedResult, String>
+where
+    F: Fn(String, String, String) -> Fut,
+    Fut: std::future::Future<Output = Option<String>>,
+{
+    let rows_query = Query::new(
+        "SELECT id, item_id, COALESCE(media_type, 'audio'), COALESCE(quality_preset, 'original')
+         FROM downloads
+         WHERE status = 'pending' AND stream_url IS NULL",
+    );
+    let rows: Vec<(i64, String, String, String)> = db_service
+        .query_many(rows_query, |row| {
+            Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?))
+        })
+        .await
+        .map_err(|e| e.to_string())?;
+
+    if rows.is_empty() {
+        return Ok(ResumeQueuedResult { resolved: 0, failed: 0 });
+    }
+
+    info!("[Catalog] Resolving {} offline-queued downloads on reconnect", rows.len());
+
+    let mut resolved = 0usize;
+    let mut failed = 0usize;
+
+    for (download_id, item_id, media_type, quality) in rows {
+        let stream_url = match resolve(item_id.clone(), media_type, quality).await {
+            Some(url) => url,
+            None => {
+                failed += 1;
+                continue;
+            }
+        };
+
+        // Heal the row so the pump can start it. Guard on stream_url IS NULL so a
+        // concurrent resolver doesn't clobber an already-started row.
+        let update = Query::with_params(
+            "UPDATE downloads SET stream_url = ?, target_dir = ?
+             WHERE id = ? AND status = 'pending' AND stream_url IS NULL",
+            vec![
+                QueryParam::String(stream_url),
+                QueryParam::String(target_dir.to_string()),
+                QueryParam::Int64(download_id),
+            ],
+        );
+        match db_service.execute(update).await {
+            Ok(n) if n > 0 => resolved += 1,
+            Ok(_) => {} // already resolved by someone else; not a failure
+            Err(e) => {
+                warn!("[Catalog] Failed to persist URL for download {}: {}", download_id, e);
+                failed += 1;
+            }
+        }
+    }
+
+    Ok(ResumeQueuedResult { resolved, failed })
+}
+
+/// Resolve the stream URL for every download row that was queued while offline
+/// (`status = 'pending' AND stream_url IS NULL`), then pump the queue so they
+/// start. Call this on reconnect.
+///
+/// Audio rows resolve via `get_audio_stream_url`; video rows (media_type =
+/// 'video') via the pure `get_video_download_url` builder using the row's stored
+/// `quality_preset` — mirroring `enqueue_video_downloads`. Rows whose URL can't
+/// be resolved are left pending (they retry on the next reconnect).
+#[tauri::command]
+#[specta::specta]
+pub async fn resume_queued_downloads(
+    repository: State<'_, RepositoryManagerWrapper>,
+    db: State<'_, DatabaseWrapper>,
+    download_manager: State<'_, DownloadManagerWrapper>,
+    app: tauri::AppHandle,
+    handle: String,
+) -> Result<ResumeQueuedResult, String> {
+    use crate::repository::MediaRepository;
+
+    use crate::repository::HybridRepository;
+
+    let repo = repository.0.get(&handle).ok_or("Repository not found")?;
+
+    // The pump needs a target_dir; use the same storage root the other download
+    // paths use (the database's parent directory — see `storage_get_path`).
+    let (db_service, target_dir) = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        let target_dir = database
+            .path()
+            .parent()
+            .ok_or_else(|| "Database path has no parent directory".to_string())?
+            .to_string_lossy()
+            .to_string();
+        (Arc::new(database.service()), target_dir)
+    };
+
+    // Recover stale downloads: rows left in 'downloading' when the app was killed
+    // mid-transfer are orphaned — nothing ever restarts them, so they show as
+    // permanently "downloading". Reset them to 'pending' and clear the stale
+    // stream_url so they get re-resolved and restarted from scratch below.
+    let recover_query = Query::new(
+        "UPDATE downloads SET status = 'pending', stream_url = NULL, progress = 0, \
+         bytes_downloaded = 0, started_at = NULL \
+         WHERE status = 'downloading'",
+    );
+    match db_service.execute(recover_query).await {
+        Ok(n) if n > 0 => info!("[Catalog] Reset {} stale 'downloading' rows to pending", n),
+        Ok(_) => {}
+        Err(e) => warn!("[Catalog] Failed to reset stale downloads: {}", e),
+    }
+
+    // Resolve each row's URL against the (now reachable) repository.
+    let repo_for_resolve = Arc::clone(&repo);
+    let outcome = resolve_pending_download_urls(
+        &db_service,
+        &target_dir,
+        move |item_id: String, media_type: String, quality: String| {
+            let repo = Arc::clone(&repo_for_resolve);
+            async move {
+                if media_type == "video" {
+                    Some(<HybridRepository as MediaRepository>::get_video_download_url(
+                        repo.as_ref(),
+                        &item_id,
+                        &quality,
+                        None,
+                    ))
+                } else {
+                    match repo.get_audio_stream_url(&item_id).await {
+                        Ok(url) => Some(url),
+                        Err(e) => {
+                            warn!("[Catalog] Failed to resolve audio URL for {}: {:?}", item_id, e);
+                            None
+                        }
+                    }
+                }
+            }
+        },
+    )
+    .await
+    .map_err(|e| e.to_string())?;
+
+    let ResumeQueuedResult { resolved, failed } = outcome;
+
+    // Kick the pump so the newly-resolved rows actually start.
+    if resolved > 0 {
+        let active_downloads = {
+            let manager = download_manager.0.lock().map_err(|e| e.to_string())?;
+            manager.get_active_downloads()
+        };
+        pump_download_queue(app, db_service, active_downloads).await;
+    }
+
+    info!("[Catalog] Resume complete: {} resolved, {} failed", resolved, failed);
+
+    Ok(ResumeQueuedResult { resolved, failed })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::storage::db_service::RusqliteService;
+    use rusqlite::Connection;
+    use std::sync::Mutex;
+
+    fn test_db() -> Arc<RusqliteService> {
+        let conn = Connection::open_in_memory().unwrap();
+        conn.execute_batch(
+            r#"
+            CREATE TABLE downloads (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                item_id TEXT NOT NULL,
+                status TEXT NOT NULL,
+                stream_url TEXT,
+                target_dir TEXT,
+                media_type TEXT,
+                quality_preset TEXT
+            );
+            "#,
+        )
+        .unwrap();
+        Arc::new(RusqliteService::new(Arc::new(Mutex::new(conn))))
+    }
+
+    async fn insert_download(
+        db: &Arc<RusqliteService>,
+        item_id: &str,
+        status: &str,
+        stream_url: Option<&str>,
+        media_type: Option<&str>,
+    ) {
+        let q = Query::with_params(
+            "INSERT INTO downloads (item_id, status, stream_url, media_type) VALUES (?, ?, ?, ?)",
+            vec![
+                QueryParam::String(item_id.to_string()),
+                QueryParam::String(status.to_string()),
+                stream_url.map(|s| QueryParam::String(s.to_string())).unwrap_or(QueryParam::Null),
+                media_type.map(|s| QueryParam::String(s.to_string())).unwrap_or(QueryParam::Null),
+            ],
+        );
+        db.execute(q).await.unwrap();
+    }
+
+    async fn get_row(db: &Arc<RusqliteService>, item_id: &str) -> (String, Option<String>, Option<String>) {
+        let q = Query::with_params(
+            "SELECT status, stream_url, target_dir FROM downloads WHERE item_id = ?",
+            vec![QueryParam::String(item_id.to_string())],
+        );
+        db.query_one(q, |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
+            .await
+            .unwrap()
+    }
+
+    #[tokio::test]
+    async fn resolves_offline_queued_row_and_leaves_resolved_rows_untouched() {
+        let db = test_db();
+        // A row queued offline: pending with no URL yet.
+        insert_download(&db, "queued-1", "pending", None, None).await;
+        // An already-resolved pending row: must NOT be touched.
+        insert_download(&db, "already", "pending", Some("http://existing/url"), None).await;
+        // A completed row: irrelevant.
+        insert_download(&db, "done", "completed", Some("http://done/url"), None).await;
+
+        let out = resolve_pending_download_urls(&db, "/data/downloads", |item_id, _mt, _q| async move {
+            Some(format!("http://resolved/{item_id}"))
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(out.resolved, 1);
+        assert_eq!(out.failed, 0);
+
+        // The offline-queued row now has a URL + target dir and stays pending.
+        let (status, url, target) = get_row(&db, "queued-1").await;
+        assert_eq!(status, "pending");
+        assert_eq!(url.as_deref(), Some("http://resolved/queued-1"));
+        assert_eq!(target.as_deref(), Some("/data/downloads"));
+
+        // The already-resolved row is unchanged (not re-resolved).
+        let (_s, url2, _t) = get_row(&db, "already").await;
+        assert_eq!(url2.as_deref(), Some("http://existing/url"));
+    }
+
+    #[tokio::test]
+    async fn counts_unresolvable_rows_as_failed_and_leaves_them_pending() {
+        let db = test_db();
+        insert_download(&db, "bad", "pending", None, None).await;
+
+        // Resolver returns None (e.g. server lookup failed).
+        let out = resolve_pending_download_urls(&db, "/data", |_id, _mt, _q| async move { None })
+            .await
+            .unwrap();
+
+        assert_eq!(out.resolved, 0);
+        assert_eq!(out.failed, 1);
+
+        // Still pending with no URL, so a later reconnect can retry it.
+        let (status, url, _t) = get_row(&db, "bad").await;
+        assert_eq!(status, "pending");
+        assert_eq!(url, None);
+    }
+
+    #[tokio::test]
+    async fn video_rows_use_media_type_in_resolver() {
+        let db = test_db();
+        insert_download(&db, "vid-1", "pending", None, Some("video")).await;
+
+        let out = resolve_pending_download_urls(&db, "/data", |item_id, media_type, _q| async move {
+            assert_eq!(media_type, "video");
+            Some(format!("http://transcode/{item_id}"))
+        })
+        .await
+        .unwrap();
+
+        assert_eq!(out.resolved, 1);
+        let (_s, url, _t) = get_row(&db, "vid-1").await;
+        assert_eq!(url.as_deref(), Some("http://transcode/vid-1"));
+    }
+}

src-tauri/src/commands/download/mod.rs

@@ -1268,13 +1268,50 @@ fn spawn_download_worker(
             debug!("   Unregistered download {}. Active downloads: {}", download_id, active.len());
         }
 
+        // The pump runs downloads in the background, so the terminal status MUST
+        // be persisted to the DB here — the frontend event handler only writes it
+        // when that download happens to be loaded in its store, which is not the
+        // case for auto-pumped rows (or any completion while the downloads page is
+        // closed). `check_for_local_download` filters on status = 'completed', so a
+        // missed write leaves finished files unrecognized: albums never show as
+        // downloaded and playback never switches from the (expiring) stream to the
+        // local file, cutting tracks off mid-play.
+        let db_service = {
+            let db = app.state::<DatabaseWrapper>();
+            let database = match db.0.lock() {
+                Ok(d) => d,
+                Err(e) => {
+                    error!("[pump] Failed to lock database after download {}: {}", download_id, e);
+                    return;
+                }
+            };
+            Arc::new(database.service())
+        };
+
         match result {
             Ok(res) => {
                 info!("Download completed successfully: {} bytes", res.bytes_downloaded);
+                let file_path = target_path.to_string_lossy().to_string();
+
+                let update = Query::with_params(
+                    "UPDATE downloads SET status = 'completed', progress = 1.0, \
+                     bytes_downloaded = ?, file_size = ?, file_path = ?, \
+                     completed_at = CURRENT_TIMESTAMP WHERE id = ?",
+                    vec![
+                        QueryParam::Int64(res.bytes_downloaded as i64),
+                        QueryParam::Int64(res.bytes_downloaded as i64),
+                        QueryParam::String(file_path.clone()),
+                        QueryParam::Int64(download_id),
+                    ],
+                );
+                if let Err(e) = db_service.execute(update).await {
+                    error!("[pump] Failed to persist completed status for download {}: {}", download_id, e);
+                }
+
                 let completed_event = DownloadEvent::Completed {
                     download_id,
                     item_id,
-                    file_path: target_path.to_string_lossy().to_string(),
+                    file_path,
                 };
                 match app.emit("download-event", completed_event) {
                     Ok(_) => debug!("   Completed event emitted successfully"),
@@ -1283,6 +1320,18 @@ fn spawn_download_worker(
             }
             Err(e) => {
                 error!("Download failed: {:?}", e);
+
+                let update = Query::with_params(
+                    "UPDATE downloads SET status = 'failed', error_message = ? WHERE id = ?",
+                    vec![
+                        QueryParam::String(e.to_string()),
+                        QueryParam::Int64(download_id),
+                    ],
+                );
+                if let Err(db_err) = db_service.execute(update).await {
+                    error!("[pump] Failed to persist failed status for download {}: {}", download_id, db_err);
+                }
+
                 let failed_event = DownloadEvent::Failed {
                     download_id,
                     item_id,
@@ -1296,17 +1345,6 @@ fn spawn_download_worker(
         }
 
         // A slot just freed — start the next pending download (if any).
-        let db_service = {
-            let db = app.state::<DatabaseWrapper>();
-            let database = match db.0.lock() {
-                Ok(d) => d,
-                Err(e) => {
-                    error!("[pump] Failed to lock database after download {}: {}", download_id, e);
-                    return;
-                }
-            };
-            Arc::new(database.service())
-        };
         pump_download_queue(app.clone(), db_service, active_downloads).await;
     });
 }

src-tauri/src/commands/mod.rs

@@ -2,6 +2,7 @@
 // TRACES: UR-002, UR-003, UR-004, UR-005, UR-009, UR-011, UR-012, UR-017, UR-019, UR-025 |
 //         DR-015, DR-017, DR-021, DR-028
 pub mod auth;
+pub mod catalog;
 pub mod connectivity;
 pub mod conversions;
 pub mod device;
@@ -17,6 +18,7 @@ pub mod storage;
 pub mod sync;
 
 pub use auth::*;
+pub use catalog::*;
 pub use connectivity::*;
 pub use conversions::*;
 pub use device::*;

src-tauri/src/commands/player/mod.rs

@@ -696,6 +696,11 @@ pub async fn player_stop(
         let controller = player.0.lock().await;
         controller.stop().map_err(|e| e.to_string())?;
 
+        // A genuine local stop returns the manager to Idle so it no longer
+        // reports Local (or a stale Remote) — otherwise a later play/pause would
+        // route to the wrong device.
+        playback_mode.0.set_mode(crate::playback_mode::PlaybackMode::Idle);
+
         // Handle session state based on type (local playback only)
         {
             let mut session_mgr = session.0.lock().map_err(|e| e.to_string())?;
@@ -1538,6 +1543,9 @@ pub async fn player_play_album_track(
         play_selection_on_remote(&controller, session_id, &media_items, start_index).await?;
         controller.set_queue(media_items, start_index).map_err(|e| e.to_string())?;
     } else {
+        // Local playback is now authoritative (see player_play_tracks); set it
+        // before starting so the mode-changed event precedes the state events.
+        playback_mode.0.set_mode(crate::playback_mode::PlaybackMode::Local);
         controller
             .play_queue(media_items, start_index)
             .map_err(|e| e.to_string())?;
@@ -1714,6 +1722,16 @@ pub async fn player_play_tracks(
             .set_queue(media_items, request.start_index)
             .map_err(|e| e.to_string())?;
     } else {
+        // Starting local playback makes Local the authoritative mode. Without
+        // this, a prior Remote mode lingers in the manager and later play/pause
+        // commands route back to the (stopped) remote session. Set it BEFORE
+        // starting playback so the PlaybackModeChanged event reaches the frontend
+        // ahead of the state_changed events it will emit — otherwise the frontend
+        // (still thinking it's remote) filters those state events out. Skip during
+        // a transfer: transfer_to_local drives the mode itself once complete.
+        if !playback_mode.0.is_transferring() {
+            playback_mode.0.set_mode(crate::playback_mode::PlaybackMode::Local);
+        }
         controller
             .play_queue_from(media_items, request.start_index, request.start_position)
             .map_err(|e| e.to_string())?;

src-tauri/src/jellyfin/http_client.rs

@@ -217,6 +217,45 @@ impl HttpClient {
             .map_err(|e| format!("Failed to parse JSON: {}", e))
     }
 
+    /// Make a GET request and deserialize JSON with a short timeout and no retries.
+    ///
+    /// Intended for the initial "connect to server" probe on the login screen:
+    /// a wrong/unreachable URL must fail fast instead of burning through the
+    /// default 30s-per-attempt timeout and exponential backoff retries.
+    pub async fn get_json_fast<T: DeserializeOwned>(&self, url: &str) -> Result<T, String> {
+        // Short timeout so an unreachable host fails quickly.
+        const FAST_TIMEOUT: Duration = Duration::from_secs(10);
+
+        let request = self
+            .client
+            .get(url)
+            .timeout(FAST_TIMEOUT)
+            .build()
+            .map_err(|e| format!("Failed to build request: {}", e))?;
+
+        // No retry: connection failures on a wrong URL won't succeed on retry,
+        // they'd only multiply the wait the user sees before an error.
+        let response = self
+            .client
+            .execute(request)
+            .await
+            .map_err(|e| format!("Request failed: {}", e))?;
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let error_text = response
+                .text()
+                .await
+                .unwrap_or_else(|_| "Unknown error".to_string());
+            return Err(format!("HTTP {}: {}", status, error_text));
+        }
+
+        response
+            .json::<T>()
+            .await
+            .map_err(|e| format!("Failed to parse JSON: {}", e))
+    }
+
     /// Quick ping to check if a server is reachable (no retry)
     pub async fn ping(&self, url: &str) -> bool {
         let request = self.client.get(url)

src-tauri/src/lib.rs

@@ -23,6 +23,7 @@ use log::{error, info};
 use log::warn;
 
 use commands::{
+    sync_full_catalog, catalog_sync_status, set_show_server_catalog, resume_queued_downloads,
     cancel_download, clear_stale_downloads, delete_album_downloads, delete_all_downloads, delete_download,
     download_album, download_item, download_item_and_start, download_video, download_series, download_season,
     get_download_storage_stats, get_downloads, get_download_manager_stats, set_max_concurrent_downloads,
@@ -585,6 +586,10 @@ fn specta_builder() -> Builder<tauri::Wry> {
             start_download,
             enqueue_download,
             enqueue_video_downloads,
+            sync_full_catalog,
+            catalog_sync_status,
+            set_show_server_catalog,
+            resume_queued_downloads,
             get_download_manager_stats,
             set_max_concurrent_downloads,
             get_smart_cache_stats,
@@ -920,6 +925,9 @@ pub fn run() {
                 player_arc.clone(),
             );
             let playback_mode_arc = Arc::new(playback_mode_manager);
+            // Broadcast mode changes so the frontend's mirror store reconciles to
+            // this authoritative one (prevents remote/local control desync).
+            playback_mode_arc.set_event_emitter(event_emitter.clone());
             let playback_mode_wrapper = PlaybackModeManagerWrapper(playback_mode_arc.clone());
             app.manage(playback_mode_wrapper);
 
@@ -930,9 +938,11 @@ pub fn run() {
                 playback_mode_arc.clone(),
             );
             session_poller.set_event_emitter(event_emitter.clone());
-            session_poller.start();
+            // Note: start() is deferred until after the connectivity monitor is
+            // created below, so the poller can report reachability from its first
+            // poll (it drives offline detection + recovery while the user is idle).
             let session_poller_arc = Arc::new(session_poller);
-            let session_poller_wrapper = SessionPollerWrapper(session_poller_arc);
+            let session_poller_wrapper = SessionPollerWrapper(session_poller_arc.clone());
             app.manage(session_poller_wrapper);
 
             // On Android, set up the MediaSession (lockscreen) handler and the
@@ -994,6 +1004,12 @@ pub fn run() {
             let mut connectivity_monitor = ConnectivityMonitor::new(http_client);
             connectivity_monitor.set_app_handle(app.handle().clone());
 
+            // Wire the connectivity reporter into the session poller so its
+            // continuous background polls drive reachability (offline detection
+            // + recovery) even when the user isn't browsing, then start it.
+            session_poller_arc.set_connectivity_reporter(connectivity_monitor.reporter());
+            session_poller_arc.start();
+
             // Wrap in Arc for sharing with AuthManager
             let connectivity_arc = Arc::new(tokio::sync::Mutex::new(connectivity_monitor));
             let connectivity_wrapper = ConnectivityMonitorWrapper(connectivity_arc.clone());

src-tauri/src/playback_mode/mod.rs

@@ -9,7 +9,7 @@ use tokio::sync::Mutex as TokioMutex;
 use tokio::time::{sleep, Duration};
 
 use crate::jellyfin::JellyfinClient;
-use crate::player::{PlayerController, QueueContext};
+use crate::player::{PlayerController, PlayerEventEmitter, PlayerStatusEvent, QueueContext};
 
 /// Playback mode - local device, remote session, or idle
 #[derive(specta::Type, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
@@ -48,6 +48,9 @@ pub struct PlaybackModeManager {
     player_controller: Arc<TokioMutex<PlayerController>>,
     current_mode: Arc<RwLock<PlaybackMode>>,
     is_transferring: Arc<AtomicBool>,
+    /// Optional emitter used to notify the frontend when the mode changes, so its
+    /// mirror store stays in sync with this authoritative one. `None` in tests.
+    event_emitter: Arc<Mutex<Option<Arc<dyn PlayerEventEmitter>>>>,
 }
 
 impl PlaybackModeManager {
@@ -61,19 +64,53 @@ impl PlaybackModeManager {
             player_controller,
             current_mode: Arc::new(RwLock::new(PlaybackMode::Idle)),
             is_transferring: Arc::new(AtomicBool::new(false)),
+            event_emitter: Arc::new(Mutex::new(None)),
         }
     }
 
+    /// Wire the event emitter so `set_mode` notifies the frontend. Called once
+    /// during setup; safe to leave unset (tests do), in which case mode changes
+    /// simply aren't broadcast.
+    pub fn set_event_emitter(&self, emitter: Arc<dyn PlayerEventEmitter>) {
+        *self.event_emitter.lock_safe() = Some(emitter);
+    }
+
     /// Get current playback mode
     pub fn get_mode(&self) -> PlaybackMode {
         self.current_mode.read_safe().clone()
     }
 
-    /// Set playback mode (internal use)
+    /// Set playback mode (internal use).
+    ///
+    /// Broadcasts a `PlaybackModeChanged` event when the mode actually changes so
+    /// the frontend's mirror store reconciles to this authoritative value. The
+    /// write lock is released before emitting to avoid holding it across the
+    /// emitter call.
     pub fn set_mode(&self, mode: PlaybackMode) {
         log::info!("[PlaybackMode] Setting mode to: {:?}", mode);
+        let changed = {
             let mut current = self.current_mode.write_safe();
-        *current = mode;
+            let changed = *current != mode;
+            *current = mode.clone();
+            changed
+        };
+
+        if !changed {
+            return;
+        }
+
+        let (mode_str, session_id) = match &mode {
+            PlaybackMode::Local => ("local".to_string(), None),
+            PlaybackMode::Idle => ("idle".to_string(), None),
+            PlaybackMode::Remote { session_id } => ("remote".to_string(), Some(session_id.clone())),
+        };
+
+        if let Some(emitter) = self.event_emitter.lock_safe().as_ref() {
+            emitter.emit(PlayerStatusEvent::PlaybackModeChanged {
+                mode: mode_str,
+                session_id,
+            });
+        }
     }
 
     /// Check if currently transferring
@@ -702,6 +739,84 @@ mod tests {
         );
     }
 
+    /// Capturing emitter so we can assert what `set_mode` broadcasts.
+    struct CapturingEmitter {
+        events: Mutex<Vec<PlayerStatusEvent>>,
+    }
+
+    impl PlayerEventEmitter for CapturingEmitter {
+        fn emit(&self, event: PlayerStatusEvent) {
+            self.events.lock().unwrap().push(event);
+        }
+    }
+
+    fn manager_with_emitter() -> (PlaybackModeManager, Arc<CapturingEmitter>) {
+        let emitter = Arc::new(CapturingEmitter {
+            events: Mutex::new(Vec::new()),
+        });
+        let manager = PlaybackModeManager::new(
+            Arc::new(Mutex::new(None)),
+            Arc::new(TokioMutex::new(crate::player::PlayerController::default())),
+        );
+        manager.set_event_emitter(emitter.clone());
+        (manager, emitter)
+    }
+
+    /// set_mode broadcasts a PlaybackModeChanged event with the right payload so
+    /// the frontend can reconcile its mirror store to this authoritative one.
+    #[test]
+    fn test_set_mode_emits_change_event() {
+        let (manager, emitter) = manager_with_emitter();
+
+        manager.set_mode(PlaybackMode::Remote {
+            session_id: "sess-1".to_string(),
+        });
+        manager.set_mode(PlaybackMode::Local);
+        manager.set_mode(PlaybackMode::Idle);
+
+        let events = emitter.events.lock().unwrap();
+        assert_eq!(events.len(), 3, "one event per real mode change");
+
+        match &events[0] {
+            PlayerStatusEvent::PlaybackModeChanged { mode, session_id } => {
+                assert_eq!(mode, "remote");
+                assert_eq!(session_id.as_deref(), Some("sess-1"));
+            }
+            other => panic!("expected PlaybackModeChanged, got {:?}", other),
+        }
+        match &events[1] {
+            PlayerStatusEvent::PlaybackModeChanged { mode, session_id } => {
+                assert_eq!(mode, "local");
+                assert_eq!(session_id.as_deref(), None);
+            }
+            other => panic!("expected PlaybackModeChanged, got {:?}", other),
+        }
+        match &events[2] {
+            PlayerStatusEvent::PlaybackModeChanged { mode, session_id } => {
+                assert_eq!(mode, "idle");
+                assert_eq!(session_id.as_deref(), None);
+            }
+            other => panic!("expected PlaybackModeChanged, got {:?}", other),
+        }
+    }
+
+    /// Setting the same mode twice must not re-emit — the frontend reconciler
+    /// (and the event channel) shouldn't be spammed on no-op transitions.
+    #[test]
+    fn test_set_mode_deduplicates_no_op() {
+        let (manager, emitter) = manager_with_emitter();
+
+        manager.set_mode(PlaybackMode::Local);
+        manager.set_mode(PlaybackMode::Local);
+        manager.set_mode(PlaybackMode::Local);
+
+        assert_eq!(
+            emitter.events.lock().unwrap().len(),
+            1,
+            "repeated identical mode set emits only once"
+        );
+    }
+
     /// The resume position handed to a remote session is derived from a live
     /// playback position. Guards the seconds->ticks conversion and the
     /// at-the-start threshold (Bug: casting restarted the track from 0).

src-tauri/src/player/events.rs

@@ -124,6 +124,21 @@ pub enum PlayerStatusEvent {
         /// All active controllable sessions from Jellyfin
         sessions: Vec<crate::jellyfin::client::SessionInfo>,
     },
+    /// The authoritative playback mode changed in the Rust backend.
+    ///
+    /// The Rust `PlaybackModeManager` is the single source of truth for which
+    /// device playback commands route to (local vs a remote session). The
+    /// frontend keeps a mirror store for the UI; without this event that mirror
+    /// drifts out of sync (e.g. a mode transition happens inside a transfer or a
+    /// local stop that the frontend never learns about), and controls then route
+    /// to the wrong device — the classic "it keeps playing on the remote" bug.
+    /// The frontend reconciles its store to this payload whenever it fires.
+    PlaybackModeChanged {
+        /// New mode: "local", "remote", or "idle".
+        mode: String,
+        /// Session id when `mode == "remote"`, otherwise `None`.
+        session_id: Option<String>,
+    },
     /// The user asked to disconnect from the remote session and resume locally.
     ///
     /// Emitted when the lockscreen Stop button is pressed while casting. The

src-tauri/src/repository/hybrid.rs

@@ -79,6 +79,26 @@ impl HybridRepository {
             .await
     }
 
+    /// Fetch a folder's items from the live server and persist them to the
+    /// offline cache synchronously (unlike `get_items`, which saves in a
+    /// fire-and-forget background task after a 100ms cache race).
+    ///
+    /// Used by the full-catalog pre-sync (`sync_full_catalog`) to deterministically
+    /// walk every library while online so the whole catalog is browsable — greyed
+    /// out — offline. Returns the items fetched so the caller can recurse into
+    /// containers. Server-only: errors if unreachable.
+    pub async fn cache_items_from_server(
+        &self,
+        parent_id: &str,
+        options: Option<GetItemsOptions>,
+    ) -> Result<Vec<MediaItem>, RepoError> {
+        let result = self.online.get_items(parent_id, options).await?;
+        if !result.items.is_empty() {
+            self.offline.save_to_cache(parent_id, &result.items).await?;
+        }
+        Ok(result.items)
+    }
+
     /// Search only the live Jellyfin server (full library).
     pub async fn search_server_only(
         &self,

src-tauri/src/repository/offline.rs

@@ -1,5 +1,6 @@
 // Offline repository - queries SQLite database for cached data
 use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
 
 use async_trait::async_trait;
 use log::debug;
@@ -7,6 +8,30 @@ use log::debug;
 use super::{MediaRepository, types::*};
 use crate::storage::db_service::{DatabaseService, Query, QueryParam, RusqliteService};
 
+/// Whether offline library queries may include catalog items that are merely
+/// *browsed/synced* but not downloaded (the greyed-out "browse the whole server"
+/// view). Defaults to `true` so online browsing (which reads this same cache as
+/// a fast path) still sees the full catalog.
+///
+/// While offline, the frontend drives this from the "Show all server media"
+/// toggle: OFF means library pages show only downloaded/local media, ON reveals
+/// the full greyed-out catalog. See `set_include_catalog_browse` and the
+/// `showServerCatalog` UI flag. Fixes the bug where offline library pages showed
+/// every server item regardless of the toggle.
+static INCLUDE_CATALOG_BROWSE: AtomicBool = AtomicBool::new(true);
+
+/// Set whether offline `get_items` includes non-downloaded (synced-only) catalog
+/// items. Called from the frontend: `true` when online or when the offline
+/// "Show all server media" toggle is on; `false` when offline with the toggle
+/// off (show downloaded/local media only).
+pub fn set_include_catalog_browse(include: bool) {
+    INCLUDE_CATALOG_BROWSE.store(include, Ordering::Relaxed);
+}
+
+fn include_catalog_browse() -> bool {
+    INCLUDE_CATALOG_BROWSE.load(Ordering::Relaxed)
+}
+
 pub struct OfflineRepository {
     db_service: Arc<RusqliteService>,
     server_id: String,
@@ -558,7 +583,20 @@ impl MediaRepository for OfflineRepository {
         // Use CTE to find items that are either:
         // 1. Playable items (Audio, Movie, Episode) with completed downloads (offline mode)
         // 2. Container items (MusicAlbum, Series, Season) with at least one downloaded child (offline mode)
-        // 3. Cached items with recent synced_at timestamp (online mode - for fast browsing)
+        // 3. Cached items with recent synced_at timestamp (fast online browsing, or the
+        //    offline "Show all server media" catalog view) — only when the catalog-browse
+        //    flag is set. When offline with the toggle off, this branch is omitted so the
+        //    page shows downloaded/local media only. See `set_include_catalog_browse`.
+        let catalog_branch = if include_catalog_browse() {
+            "UNION
+
+                -- Cached items for fast browsing (online) or the offline catalog view
+                SELECT DISTINCT i.id
+                FROM items i
+                WHERE i.synced_at IS NOT NULL"
+        } else {
+            ""
+        };
         let sql = format!(
             "WITH available_items AS (
                 -- Playable items with completed downloads
@@ -578,12 +616,7 @@ impl MediaRepository for OfflineRepository {
                 WHERE d.status = 'completed'
                   AND i.item_type IN ('MusicAlbum', 'Series', 'Season', 'BoxSet', 'Folder', 'CollectionFolder')
 
-                UNION
-
-                -- Cached items for fast browsing (when online)
-                SELECT DISTINCT i.id
-                FROM items i
-                WHERE i.synced_at IS NOT NULL
+                {catalog_branch}
             )
             SELECT i.id, i.name, i.item_type, i.server_id, i.parent_id, i.library_id, i.overview, i.genres,
                     i.runtime_ticks, i.production_year, i.community_rating, i.official_rating,
@@ -1874,6 +1907,57 @@ mod tests {
         assert_eq!(tracks.items[0].id, "track-1");
     }
 
+    /// Regression: offline library pages must honor the "Show all server media"
+    /// toggle. With `include_catalog_browse` off, `get_items` returns only
+    /// downloaded media — not the whole synced catalog. With it on, the full
+    /// (synced-but-not-downloaded) catalog is revealed. Fixes the bug where
+    /// offline library pages showed every server item regardless of the toggle.
+    #[tokio::test]
+    async fn test_get_items_toggle_gates_synced_catalog() {
+        use crate::storage::db_service::DatabaseService;
+        let db_service = create_test_db();
+
+        for sql in [
+            // Two movies in a library, both merely synced (browsed) — no download.
+            "INSERT INTO items (id, server_id, name, item_type, library_id, synced_at) \
+             VALUES ('movie-dl', 'test-server', 'Downloaded', 'Movie', 'lib-1', '2026-01-01')",
+            "INSERT INTO items (id, server_id, name, item_type, library_id, synced_at) \
+             VALUES ('movie-cat', 'test-server', 'CatalogOnly', 'Movie', 'lib-1', '2026-01-01')",
+            // Only the first movie is actually downloaded.
+            "INSERT INTO downloads (item_id, status) VALUES ('movie-dl', 'completed')",
+            // A library row so the library-parent EXISTS clause matches.
+            "INSERT INTO libraries (id, server_id, name) VALUES ('lib-1', 'test-server', 'Movies')",
+        ] {
+            db_service.execute(Query::new(sql)).await.unwrap();
+        }
+
+        let repo = OfflineRepository::new(
+            db_service.clone(),
+            "test-server".to_string(),
+            "test-user".to_string(),
+        );
+        let opts = Some(GetItemsOptions {
+            include_item_types: Some(vec!["Movie".to_string()]),
+            ..Default::default()
+        });
+
+        // Toggle OFF: only the downloaded movie is returned.
+        set_include_catalog_browse(false);
+        let local_only = repo.get_items("lib-1", opts.clone()).await.unwrap();
+        let ids: Vec<&str> = local_only.items.iter().map(|i| i.id.as_str()).collect();
+        assert_eq!(ids, vec!["movie-dl"], "toggle off should show downloaded media only");
+
+        // Toggle ON: both the downloaded and the catalog-only movie are returned.
+        set_include_catalog_browse(true);
+        let full_catalog = repo.get_items("lib-1", opts).await.unwrap();
+        let mut ids: Vec<&str> = full_catalog.items.iter().map(|i| i.id.as_str()).collect();
+        ids.sort();
+        assert_eq!(ids, vec!["movie-cat", "movie-dl"], "toggle on should reveal the full catalog");
+
+        // Restore default for other tests sharing this process-global flag.
+        set_include_catalog_browse(true);
+    }
+
     /// Regression: TV episodes link to their season/series via `season_id` /
     /// `series_id` (NOT `parent_id`, which is NULL in the cache). A downloaded
     /// episode must make both its Season and Series available offline, and

src-tauri/src/session_poller/mod.rs

@@ -32,6 +32,13 @@ pub struct SessionPollerManager {
     jellyfin_client: Arc<Mutex<Option<JellyfinClient>>>,
     playback_mode_manager: Arc<PlaybackModeManager>,
     event_emitter: Arc<Mutex<Option<Arc<dyn PlayerEventEmitter>>>>,
+    /// Optional connectivity reporter. The session poller is the one piece of
+    /// server traffic that runs continuously even when the user is idle (not
+    /// browsing the library), so feeding its poll outcomes into the reporter is
+    /// what lets the app detect going offline — and, crucially, recover when the
+    /// server returns — without any user interaction. Repository traffic alone
+    /// can't do this because it only happens while browsing.
+    connectivity_reporter: Arc<Mutex<Option<crate::connectivity::ConnectivityReporter>>>,
 
     // Polling state
     is_running: Arc<AtomicBool>,
@@ -52,6 +59,7 @@ impl SessionPollerManager {
             jellyfin_client,
             playback_mode_manager,
             event_emitter: Arc::new(Mutex::new(None)),
+            connectivity_reporter: Arc::new(Mutex::new(None)),
             is_running: Arc::new(AtomicBool::new(false)),
             current_hint: Arc::new(RwLock::new(PollingHint::Normal)),
             current_interval_ms: Arc::new(AtomicU64::new(10000)), // Default 10s
@@ -64,6 +72,13 @@ impl SessionPollerManager {
         *self.event_emitter.lock_safe() = Some(emitter);
     }
 
+    /// Wire the connectivity reporter so each poll outcome updates reachability.
+    /// A successful poll recovers the app to online instantly; sustained poll
+    /// failures flip it offline (subject to the reporter's debounce window).
+    pub fn set_connectivity_reporter(&self, reporter: crate::connectivity::ConnectivityReporter) {
+        *self.connectivity_reporter.lock_safe() = Some(reporter);
+    }
+
     /// Start the background polling thread
     pub fn start(&self) {
         if self.is_running.swap(true, Ordering::Relaxed) {
@@ -77,6 +92,7 @@ impl SessionPollerManager {
         let client = self.jellyfin_client.clone();
         let mode_manager = self.playback_mode_manager.clone();
         let emitter = self.event_emitter.clone();
+        let connectivity_reporter = self.connectivity_reporter.clone();
         let is_running = self.is_running.clone();
         let hint = self.current_hint.clone();
         let interval_ms = self.current_interval_ms.clone();
@@ -96,18 +112,35 @@ impl SessionPollerManager {
 
                 debug!("[SessionPoller] Polling with interval: {}ms", new_interval);
 
-                // Fetch sessions
-                let sessions_result = rt.block_on(async {
+                // Fetch sessions. `had_client` distinguishes "server didn't
+                // answer" from "no client configured" so we only feed real
+                // request outcomes into the connectivity reporter.
+                let (sessions_result, had_client) = rt.block_on(async {
                     let client_opt = client.lock_safe().clone();
                     match client_opt {
-                        Some(c) => c.get_sessions().await,
+                        Some(c) => (c.get_sessions().await, true),
                         None => {
                             debug!("[SessionPoller] Jellyfin client not configured, skipping poll");
-                            Ok(Vec::new())
+                            (Ok(Vec::new()), false)
                         }
                     }
                 });
 
+                // Drive the connectivity reporter from this poll's outcome. This
+                // is what recovers the app to online when the server returns
+                // while the user is idle, and detects going offline when no
+                // library browsing is happening. See connectivity/mod.rs.
+                if had_client {
+                    if let Some(reporter) = connectivity_reporter.lock_safe().clone() {
+                        rt.block_on(async {
+                            match &sessions_result {
+                                Ok(_) => reporter.report_success().await,
+                                Err(e) => reporter.report_network_failure(Some(e.clone())).await,
+                            }
+                        });
+                    }
+                }
+
                 // Emit event if successful
                 match sessions_result {
                     Ok(sessions) => {

src/lib/api/bindings.ts

@@ -806,6 +806,51 @@ async enqueueDownload(downloadId: number, streamUrl: string, targetDir: string)
 async enqueueVideoDownloads(handle: string, downloadIds: number[], targetDir: string) : Promise<null> {
     return await TAURI_INVOKE("enqueue_video_downloads", { handle, downloadIds, targetDir });
 },
+/**
+ * Walk every library on the server and persist all items to the offline cache
+ * so the full catalog is browsable offline (greyed out when not downloaded).
+ * 
+ * Best-effort: a library that fails to fetch is counted and skipped rather than
+ * aborting the whole sync. Runs libraries sequentially to avoid hammering the
+ * server. Uses `Recursive=true` so a single request per library returns the
+ * containers and their playable children.
+ */
+async syncFullCatalog(handle: string) : Promise<CatalogSyncResult> {
+    return await TAURI_INVOKE("sync_full_catalog", { handle });
+},
+/**
+ * Report the last-synced timestamp so the UI can show a hint / decide whether
+ * to trigger a fresh sync.
+ */
+async catalogSyncStatus() : Promise<CatalogSyncStatus> {
+    return await TAURI_INVOKE("catalog_sync_status");
+},
+/**
+ * Control whether offline library queries reveal the full synced catalog
+ * (greyed-out, non-downloaded media) or only downloaded/local media.
+ * 
+ * The frontend calls this from the "Show all server media" toggle: pass `true`
+ * when online, or when offline with the toggle on; pass `false` when offline
+ * with the toggle off so library pages show downloaded media only. Fixes the
+ * bug where offline library pages showed every server item regardless of the
+ * toggle.
+ */
+async setShowServerCatalog(show: boolean) : Promise<void> {
+    await TAURI_INVOKE("set_show_server_catalog", { show });
+},
+/**
+ * Resolve the stream URL for every download row that was queued while offline
+ * (`status = 'pending' AND stream_url IS NULL`), then pump the queue so they
+ * start. Call this on reconnect.
+ * 
+ * Audio rows resolve via `get_audio_stream_url`; video rows (media_type =
+ * 'video') via the pure `get_video_download_url` builder using the row's stored
+ * `quality_preset` — mirroring `enqueue_video_downloads`. Rows whose URL can't
+ * be resolved are left pending (they retry on the next reconnect).
+ */
+async resumeQueuedDownloads(handle: string) : Promise<ResumeQueuedResult> {
+    return await TAURI_INVOKE("resume_queued_downloads", { handle });
+},
 /**
  * Get download manager statistics
  */
@@ -1505,6 +1550,20 @@ export type CachedLibrary = { id: string; serverId: string; name: string; collec
  * Cached person info returned to frontend
  */
 export type CachedPerson = { id: string; serverId: string; name: string; overview: string | null; primaryImageTag: string | null; premiereDate: string | null; endDate: string | null }
+export type CatalogSyncResult = { 
+/**
+ * Total items persisted to the offline cache across all libraries.
+ */
+itemsCached: number; 
+/**
+ * Libraries that failed to sync (e.g. server hiccup); best-effort.
+ */
+librariesFailed: number }
+export type CatalogSyncStatus = { 
+/**
+ * RFC-3339 timestamp of the last successful sync, if any.
+ */
+lastSyncedAt: string | null }
 /**
  * Connectivity status
  */
@@ -1989,6 +2048,18 @@ export type PlayerStatusEvent =
  * Remote sessions updated (for cast/remote control UI)
  */
 { type: "sessions_updated"; sessions: SessionInfo[] } | 
+/**
+ * The authoritative playback mode changed in the Rust backend.
+ * 
+ * The Rust `PlaybackModeManager` is the single source of truth for which
+ * device playback commands route to (local vs a remote session). The
+ * frontend keeps a mirror store for the UI; without this event that mirror
+ * drifts out of sync (e.g. a mode transition happens inside a transfer or a
+ * local stop that the frontend never learns about), and controls then route
+ * to the wrong device — the classic "it keeps playing on the remote" bug.
+ * The frontend reconciles its store to this payload whenever it fires.
+ */
+{ type: "playback_mode_changed"; mode: string; session_id: string | null } | 
 /**
  * The user asked to disconnect from the remote session and resume locally.
  * 
@@ -2066,6 +2137,15 @@ export type RemoteSessionStatus = { position: number; duration: number | null; i
  * TRACES: UR-005 | DR-005
  */
 export type RepeatMode = "off" | "all" | "one"
+export type ResumeQueuedResult = { 
+/**
+ * Rows whose stream URL was resolved and are now pump-eligible.
+ */
+resolved: number; 
+/**
+ * Rows that couldn't be resolved (item metadata / URL lookup failed).
+ */
+failed: number }
 /**
  * Options for search queries
  */

src/lib/components/library/AsyncImageLoading.test.ts

@@ -1,432 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { render, waitFor } from "@testing-library/svelte";
-
-/**
- * Integration tests for async image loading pattern used in components
- *
- * Pattern:
- * - Component has $state<string> imageUrl = ""
- * - Component has async loadImageUrl() function
- * - Component uses $effect to call loadImageUrl when dependencies change
- * - For lists: uses Map<string, string> to cache URLs per item
- */
-
-// Mock repository with getImageUrl
-const createMockRepository = () => ({
-  getImageUrl: vi.fn(),
-});
-
-describe.skip("Async Image Loading Pattern", () => {
-  // Detailed async pattern tests - core functionality verified in repository-client.test.ts
-  let mockRepository: any;
-
-  beforeEach(() => {
-    mockRepository = createMockRepository();
-    vi.clearAllMocks();
-  });
-
-  afterEach(() => {
-    vi.clearAllTimers();
-  });
-
-  describe("Single Image Loading", () => {
-    it("should load image URL asynchronously on component mount", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image.jpg");
-
-      // Simulating component with async image loading
-      const imageUrl = await mockRepository.getImageUrl("item123", "Primary");
-
-      expect(imageUrl).toBe("https://server.com/image.jpg");
-      expect(mockRepository.getImageUrl).toHaveBeenCalledWith("item123", "Primary");
-    });
-
-    it("should show placeholder while loading", async () => {
-      mockRepository.getImageUrl.mockImplementation(
-        () => new Promise((resolve) => setTimeout(() => resolve("https://server.com/image.jpg"), 100))
-      );
-
-      vi.useFakeTimers();
-      const promise = mockRepository.getImageUrl("item123", "Primary");
-
-      // Initially no URL
-      expect(promise).toBeInstanceOf(Promise);
-
-      vi.advanceTimersByTime(100);
-      vi.useRealTimers();
-
-      const result = await promise;
-      expect(result).toBe("https://server.com/image.jpg");
-    });
-
-    it("should reload image when item changes", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image1.jpg");
-
-      const url1 = await mockRepository.getImageUrl("item1", "Primary");
-      expect(url1).toBe("https://server.com/image1.jpg");
-
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image2.jpg");
-
-      const url2 = await mockRepository.getImageUrl("item2", "Primary");
-      expect(url2).toBe("https://server.com/image2.jpg");
-
-      expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(2);
-    });
-
-    it("should not reload image if item ID hasn't changed", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image.jpg");
-
-      // First load
-      await mockRepository.getImageUrl("item123", "Primary");
-
-      // Would normally use $effect to track changes
-      // If item ID is same, should not reload (handled by component caching)
-      // This test documents the expected behavior
-    });
-
-    it("should handle load errors gracefully", async () => {
-      mockRepository.getImageUrl.mockRejectedValue(new Error("Network error"));
-
-      // Component should catch error and show placeholder
-      try {
-        await mockRepository.getImageUrl("item123", "Primary");
-      } catch (e) {
-        expect(e).toBeInstanceOf(Error);
-      }
-    });
-  });
-
-  describe("List Image Caching (Map-based)", () => {
-    it("should cache URLs using Map<string, string>", () => {
-      // Simulating component state: imageUrls = $state<Map<string, string>>(new Map())
-      const imageUrls = new Map<string, string>();
-
-      // Load first item
-      imageUrls.set("item1", "https://server.com/image1.jpg");
-      expect(imageUrls.has("item1")).toBe(true);
-      expect(imageUrls.get("item1")).toBe("https://server.com/image1.jpg");
-
-      // Load second item
-      imageUrls.set("item2", "https://server.com/image2.jpg");
-      expect(imageUrls.size).toBe(2);
-
-      // Check cache hit
-      expect(imageUrls.get("item1")).toBe("https://server.com/image1.jpg");
-    });
-
-    it("should load images only once per item", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image.jpg");
-
-      const imageUrls = new Map<string, string>();
-
-      // Simulate loading multiple items
-      const items = [
-        { id: "item1", name: "Album 1" },
-        { id: "item2", name: "Album 2" },
-        { id: "item1", name: "Album 1 (again)" }, // Same ID
-      ];
-
-      for (const item of items) {
-        if (!imageUrls.has(item.id)) {
-          const url = await mockRepository.getImageUrl(item.id, "Primary");
-          imageUrls.set(item.id, url);
-        }
-      }
-
-      // Should only call once per unique ID
-      expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(2);
-    });
-
-    it("should update single item without affecting others", async () => {
-      const imageUrls = new Map<string, string>();
-
-      imageUrls.set("item1", "https://server.com/image1.jpg");
-      imageUrls.set("item2", "https://server.com/image2.jpg");
-      imageUrls.set("item3", "https://server.com/image3.jpg");
-
-      // Update item2
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image2_updated.jpg");
-      const newUrl = await mockRepository.getImageUrl("item2", "Primary");
-      imageUrls.set("item2", newUrl);
-
-      // Others should remain unchanged
-      expect(imageUrls.get("item1")).toBe("https://server.com/image1.jpg");
-      expect(imageUrls.get("item2")).toBe("https://server.com/image2_updated.jpg");
-      expect(imageUrls.get("item3")).toBe("https://server.com/image3.jpg");
-    });
-
-    it("should clear cache when data changes", () => {
-      const imageUrls = new Map<string, string>();
-
-      imageUrls.set("item1", "https://server.com/image1.jpg");
-      imageUrls.set("item2", "https://server.com/image2.jpg");
-
-      // Clear cache
-      imageUrls.clear();
-
-      expect(imageUrls.size).toBe(0);
-      expect(imageUrls.has("item1")).toBe(false);
-    });
-
-    it("should support Map operations efficiently", () => {
-      const imageUrls = new Map<string, string>();
-
-      // Add items
-      for (let i = 0; i < 100; i++) {
-        imageUrls.set(`item${i}`, `https://server.com/image${i}.jpg`);
-      }
-
-      expect(imageUrls.size).toBe(100);
-
-      // Check specific item
-      expect(imageUrls.has("item50")).toBe(true);
-      expect(imageUrls.get("item50")).toBe("https://server.com/image50.jpg");
-
-      // Iterate
-      let count = 0;
-      imageUrls.forEach(() => {
-        count++;
-      });
-      expect(count).toBe(100);
-    });
-  });
-
-  describe("Component Lifecycle ($effect integration)", () => {
-    it("should trigger load on prop change", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image.jpg");
-
-      // Simulate $effect tracking prop changes
-      let effectCount = 0;
-      const trackingEffect = vi.fn(() => {
-        effectCount++;
-        return mockRepository.getImageUrl("item123", "Primary");
-      });
-
-      trackingEffect();
-      expect(effectCount).toBe(1);
-
-      trackingEffect();
-      expect(effectCount).toBe(2);
-    });
-
-    it("should skip load if conditions not met", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image.jpg");
-
-      // Simulate conditional loading (e.g., if (!imageUrl && primaryImageTag))
-      let imageUrl = "";
-      const primaryImageTag = "";
-
-      if (!imageUrl && primaryImageTag) {
-        imageUrl = await mockRepository.getImageUrl("item123", "Primary");
-      }
-
-      expect(mockRepository.getImageUrl).not.toHaveBeenCalled();
-    });
-
-    it("should handle dependent state updates", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image.jpg");
-
-      // Simulate component state changes triggering effects
-      const state = {
-        item: { id: "item1", primaryImageTag: "tag1" },
-        imageUrl: "",
-      };
-
-      const loadImage = async () => {
-        if (state.item.primaryImageTag) {
-          state.imageUrl = await mockRepository.getImageUrl(state.item.id, "Primary");
-        }
-      };
-
-      await loadImage();
-      expect(state.imageUrl).toBe("https://server.com/image.jpg");
-
-      // Change item
-      state.item = { id: "item2", primaryImageTag: "tag2" };
-      state.imageUrl = "";
-
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image2.jpg");
-      await loadImage();
-      expect(state.imageUrl).toBe("https://server.com/image2.jpg");
-    });
-  });
-
-  describe("Error Handling in Async Loading", () => {
-    it("should set empty string on error", async () => {
-      mockRepository.getImageUrl.mockRejectedValue(new Error("Network error"));
-
-      let imageUrl = "";
-
-      try {
-        imageUrl = await mockRepository.getImageUrl("item123", "Primary");
-      } catch {
-        imageUrl = ""; // Set to empty on error
-      }
-
-      expect(imageUrl).toBe("");
-    });
-
-    it("should allow retry after error", async () => {
-      mockRepository.getImageUrl
-        .mockRejectedValueOnce(new Error("Network error"))
-        .mockResolvedValueOnce("https://server.com/image.jpg");
-
-      let imageUrl = "";
-
-      // First attempt fails
-      try {
-        imageUrl = await mockRepository.getImageUrl("item123", "Primary");
-      } catch {
-        imageUrl = "";
-      }
-
-      // Retry succeeds
-      imageUrl = await mockRepository.getImageUrl("item123", "Primary");
-      expect(imageUrl).toBe("https://server.com/image.jpg");
-    });
-
-    it("should handle concurrent load requests", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image.jpg");
-
-      // Simulate loading multiple images concurrently
-      const imageUrls = new Map<string, string>();
-      const items = [
-        { id: "item1" },
-        { id: "item2" },
-        { id: "item3" },
-      ];
-
-      const promises = items.map(item =>
-        mockRepository.getImageUrl(item.id, "Primary")
-          .then((url: string) => imageUrls.set(item.id, url))
-          .catch(() => imageUrls.set(item.id, ""))
-      );
-
-      await Promise.all(promises);
-
-      expect(imageUrls.size).toBe(3);
-      expect(imageUrls.has("item1")).toBe(true);
-      expect(imageUrls.has("item2")).toBe(true);
-      expect(imageUrls.has("item3")).toBe(true);
-    });
-  });
-
-  describe("Performance Characteristics", () => {
-    it("should not reload unnecessarily", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image.jpg");
-
-      // Simulate $effect with dependency tracking
-      let dependencyValue = "same";
-      let previousDependency = "same";
-
-      const loadImage = async () => {
-        if (dependencyValue !== previousDependency) {
-          previousDependency = dependencyValue;
-          return await mockRepository.getImageUrl("item123", "Primary");
-        }
-      };
-
-      await loadImage();
-      expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(1);
-
-      // No change in dependency
-      await loadImage();
-      expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(1);
-
-      // Change dependency
-      dependencyValue = "changed";
-      await loadImage();
-      expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(2);
-    });
-
-    it("should handle large lists efficiently", async () => {
-      const imageUrls = new Map<string, string>();
-      let loadCount = 0;
-
-      mockRepository.getImageUrl.mockImplementation(() => {
-        loadCount++;
-        return Promise.resolve("https://server.com/image.jpg");
-      });
-
-      // Simulate loading 1000 items but caching URLs
-      const items = Array.from({ length: 1000 }, (_, i) => ({ id: `item${i % 10}` }));
-
-      for (const item of items) {
-        if (!imageUrls.has(item.id)) {
-          const url = await mockRepository.getImageUrl(item.id, "Primary");
-          imageUrls.set(item.id, url);
-        }
-      }
-
-      // Should only load 10 unique images
-      expect(loadCount).toBe(10);
-      expect(imageUrls.size).toBe(10);
-    });
-
-    it("should not block rendering during async loading", () => {
-      mockRepository.getImageUrl.mockImplementation(
-        () => new Promise((resolve) =>
-          setTimeout(() => resolve("https://server.com/image.jpg"), 1000)
-        )
-      );
-
-      // Async operation should not block component rendering
-      const renderTiming = {
-        startRender: Date.now(),
-        loadStart: null as number | null,
-        loadComplete: null as number | null,
-      };
-
-      // Render happens immediately
-      renderTiming.startRender = Date.now();
-
-      // Load happens asynchronously
-      mockRepository.getImageUrl("item123", "Primary").then(() => {
-        renderTiming.loadComplete = Date.now();
-      });
-
-      // Render should complete before load finishes
-      expect(Date.now() - renderTiming.startRender).toBeLessThan(1000);
-    });
-  });
-
-  describe("Backend Integration", () => {
-    it("should call backend with correct parameters", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image.jpg");
-
-      await mockRepository.getImageUrl("item123", "Primary", {
-        maxWidth: 300,
-      });
-
-      expect(mockRepository.getImageUrl).toHaveBeenCalledWith(
-        "item123",
-        "Primary",
-        {
-          maxWidth: 300,
-        }
-      );
-    });
-
-    it("should handle backend URL correctly", async () => {
-      const backendUrl = "https://server.com/Items/item123/Images/Primary?maxWidth=300&api_key=token";
-      mockRepository.getImageUrl.mockResolvedValue(backendUrl);
-
-      const url = await mockRepository.getImageUrl("item123", "Primary", { maxWidth: 300 });
-
-      expect(url).toBe(backendUrl);
-      // Frontend never constructs URLs directly
-      expect(url).toContain("api_key=");
-    });
-
-    it("should not require URL construction in frontend", async () => {
-      // Frontend receives pre-constructed URL from backend
-      const preConstructedUrl = "https://server.com/Items/item123/Images/Primary?api_key=token";
-      mockRepository.getImageUrl.mockResolvedValue(preConstructedUrl);
-
-      const url = await mockRepository.getImageUrl("item123", "Primary");
-
-      // Frontend just uses the URL
-      expect(url).toContain("https://");
-      expect(url).toContain("item123");
-    });
-  });
-});

src/lib/components/library/GenericMediaListPage.searchEvent.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Regression test: media-list search must surface server results.
+ *
+ * `repository_search` is two-phase — `repo.search()` resolves instantly with
+ * cache-only (downloaded) results, and the merged cache+server union arrives
+ * later via a `search-event`. A consumer that ignores that event only ever
+ * shows downloaded content, so search "finds nothing" for un-downloaded media.
+ *
+ * This test models that two-phase backend faithfully and would fail against a
+ * version of GenericMediaListPage that does not subscribe to `search-event`.
+ *
+ * TRACES: UR-008
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/svelte";
+import GenericMediaListPage from "./GenericMediaListPage.svelte";
+import type { MediaListConfig } from "./GenericMediaListPage.svelte";
+
+vi.mock("$app/navigation", () => ({ goto: vi.fn() }));
+
+vi.mock("$lib/stores/library", () => ({
+  currentLibrary: {
+    subscribe: vi.fn((fn) => {
+      fn({ id: "lib123", name: "Music" });
+      return vi.fn();
+    }),
+  },
+  // Consumed as a store ($viewMode) by LibraryGrid, which this page renders.
+  viewMode: {
+    subscribe: vi.fn((fn) => {
+      fn("grid");
+      return vi.fn();
+    }),
+  },
+}));
+
+vi.mock("$lib/stores/auth", () => ({
+  auth: { getRepository: vi.fn() },
+}));
+
+vi.mock("$lib/composables/useServerReachabilityReload", () => ({
+  useServerReachabilityReload: vi.fn(() => ({ markLoaded: vi.fn() })),
+}));
+
+// Capture the `search-event` handler the component registers so the test can
+// drive the deferred (server) phase manually.
+let searchEventHandler: ((event: { payload: unknown }) => void) | null = null;
+vi.mock("@tauri-apps/api/event", () => ({
+  listen: vi.fn(async (name: string, handler: (event: { payload: unknown }) => void) => {
+    if (name === "search-event") searchEventHandler = handler;
+    return () => {};
+  }),
+}));
+
+const ALBUM_CONFIG: MediaListConfig = {
+  itemType: "MusicAlbum",
+  title: "Albums",
+  backPath: "/library/music",
+  searchPlaceholder: "Search albums...",
+  sortOptions: [{ key: "SortName", label: "Title" }],
+  defaultSort: "SortName",
+  displayComponent: "grid",
+};
+
+describe("GenericMediaListPage — two-phase search", () => {
+  beforeEach(() => {
+    searchEventHandler = null;
+    vi.clearAllMocks();
+  });
+
+  it("renders server results that arrive after the cache-only phase", async () => {
+    // Phase 1 (synchronous) returns cache-only — empty, as it is for a user who
+    // has downloaded nothing. This is the exact condition that used to show
+    // "nothing found" even though the server has matching albums.
+    let capturedRequestId: number | undefined;
+    const search = vi.fn(async (_q: string, _opts: unknown, requestId: number) => {
+      capturedRequestId = requestId;
+      return { items: [], totalRecordCount: 0 };
+    });
+
+    const getItems = vi.fn().mockResolvedValue({ items: [], totalRecordCount: 0 });
+    vi.mocked((await import("$lib/stores/auth")).auth.getRepository).mockReturnValue({
+      getItems,
+      search,
+    } as any);
+
+    const { container } = render(GenericMediaListPage, { props: { config: ALBUM_CONFIG } });
+
+    // Let the initial (mount) load finish so the debounced search effect is armed.
+    await waitFor(() => expect(getItems).toHaveBeenCalled());
+
+    const input = container.querySelector("input") as HTMLInputElement;
+    fireEvent.input(input, { target: { value: "Rumours" } });
+
+    // Debounced search fires after 300ms and returns the empty cache result.
+    // The `search-event` listener is registered lazily as part of searching.
+    await waitFor(() => expect(search).toHaveBeenCalled());
+    await waitFor(() => expect(searchEventHandler).not.toBeNull());
+    // Cache-only phase: nothing to show yet (the results counter reads zero).
+    await waitFor(() =>
+      expect(screen.getByText(/0 musicalbums matching/)).toBeTruthy()
+    );
+
+    // Phase 2: backend emits the merged cache+server union for this request.
+    expect(capturedRequestId).toBeTypeOf("number");
+    searchEventHandler!({
+      payload: {
+        requestId: capturedRequestId,
+        result: {
+          items: [{ id: "album1", name: "Rumours", type: "MusicAlbum" }],
+          totalRecordCount: 1,
+        },
+      },
+    });
+
+    // The server result must now be reflected in the list. Old code (no
+    // listener) never reached this state — the count stayed at zero.
+    await waitFor(() =>
+      expect(screen.getByText(/1 musicalbum matching/)).toBeTruthy()
+    );
+  });
+
+  it("ignores a search-event whose requestId is stale", async () => {
+    const search = vi.fn(async () => ({ items: [], totalRecordCount: 0 }));
+    const getItems = vi.fn().mockResolvedValue({ items: [], totalRecordCount: 0 });
+    vi.mocked((await import("$lib/stores/auth")).auth.getRepository).mockReturnValue({
+      getItems,
+      search,
+    } as any);
+
+    const { container } = render(GenericMediaListPage, { props: { config: ALBUM_CONFIG } });
+    await waitFor(() => expect(getItems).toHaveBeenCalled());
+
+    const input = container.querySelector("input") as HTMLInputElement;
+    fireEvent.input(input, { target: { value: "Rumours" } });
+    await waitFor(() => expect(search).toHaveBeenCalled());
+    await waitFor(() => expect(searchEventHandler).not.toBeNull());
+
+    // A superseded query's late result (wrong requestId) must not render.
+    searchEventHandler!({
+      payload: {
+        requestId: -999,
+        result: {
+          items: [{ id: "stale", name: "Stale Album", type: "MusicAlbum" }],
+          totalRecordCount: 1,
+        },
+      },
+    });
+
+    await new Promise((r) => setTimeout(r, 0));
+    expect(screen.queryByText("Stale Album")).toBeNull();
+  });
+});

src/lib/components/library/GenericMediaListPage.svelte

@@ -1,6 +1,7 @@
 <!-- TRACES: UR-007, UR-029, UR-030 | DR-007, DR-032, DR-033 -->
 <script lang="ts">
-  import { onMount } from "svelte";
+  import { onMount, onDestroy } from "svelte";
+  import { listen, type UnlistenFn } from "@tauri-apps/api/event";
   import { goto } from "$app/navigation";
   import { navigateBack } from "$lib/utils/navigation";
   import { currentLibrary } from "$lib/stores/library";
@@ -13,7 +14,7 @@
   import BackButton from "$lib/components/common/BackButton.svelte";
   import ResultsCounter from "$lib/components/common/ResultsCounter.svelte";
   import { useServerReachabilityReload } from "$lib/composables/useServerReachabilityReload";
-  import type { MediaItem, Library, ItemType } from "$lib/api/types";
+  import type { MediaItem, Library, ItemType, SearchResult } from "$lib/api/types";
   import LibraryGrid from "./LibraryGrid.svelte";
   import TrackList from "./TrackList.svelte";
   import AlphabetScrollBar from "./AlphabetScrollBar.svelte";
@@ -54,6 +55,31 @@
   let searchTimeout: ReturnType<typeof setTimeout> | null = null;
   let initialLoadDone = false;
 
+  /**
+   * Payload of the backend `search-event` (mirrors Rust `SearchUpdateEvent`).
+   * `repo.search()` resolves instantly with cache-only (downloaded) results;
+   * the merged cache+server union arrives later via this event.
+   */
+  interface SearchUpdateEvent {
+    requestId: number;
+    result: SearchResult;
+  }
+
+  // Monotonic id identifying the latest search request. The deferred
+  // `search-event` is only applied when its requestId still matches, so
+  // out-of-order / superseded server results never clobber fresher ones.
+  let searchRequestId = 0;
+  let unlistenSearch: UnlistenFn | null = null;
+
+  async function ensureSearchListener() {
+    if (unlistenSearch) return;
+    unlistenSearch = await listen<SearchUpdateEvent>("search-event", (event) => {
+      const { requestId, result } = event.payload;
+      if (requestId !== searchRequestId) return;
+      items = excludePodcasts(result.items);
+    });
+  }
+
   $effect(() => {
     sortBy = config.defaultSort;
   });
@@ -82,12 +108,26 @@
       // Use backend search if search query is provided, otherwise use getItems with sort
       // HACK: excludePodcasts drops the "Podcasts" folder stored in the music library.
       if (debouncedSearchQuery.trim()) {
-        const result = await repo.search(debouncedSearchQuery, {
+        // Phase 1: instant cache-only (downloaded) results. The merged
+        // cache+server union arrives later via the `search-event` listener,
+        // tagged with this requestId so superseded queries are ignored.
+        await ensureSearchListener();
+        const requestId = ++searchRequestId;
+        const result = await repo.search(
+          debouncedSearchQuery,
+          {
             includeItemTypes: [config.itemType],
             limit: 10000,
-        });
+          },
+          requestId
+        );
+        // Only apply if this is still the active query.
+        if (requestId === searchRequestId) {
           items = excludePodcasts(result.items);
+        }
       } else {
+        // Leaving search — invalidate any in-flight server results.
+        searchRequestId++;
         const result = await repo.getItems($currentLibrary.id, {
           includeItemTypes: [config.itemType],
           sortBy,
@@ -120,6 +160,11 @@
     }, 300);
   });
 
+  onDestroy(() => {
+    if (unlistenSearch) unlistenSearch();
+    if (searchTimeout) clearTimeout(searchTimeout);
+  });
+
   function handleSort(newSort: string) {
     sortBy = newSort;
     loadItems();

src/lib/components/library/GenericMediaListPage.test.ts

@@ -15,6 +15,13 @@ vi.mock("$lib/stores/library", () => ({
       return vi.fn();
     }),
   },
+  // Consumed as a store ($viewMode) by LibraryGrid, which this page renders.
+  viewMode: {
+    subscribe: vi.fn((fn) => {
+      fn("grid");
+      return vi.fn();
+    }),
+  },
 }));
 
 vi.mock("$lib/stores/auth", () => ({
@@ -32,7 +39,12 @@ vi.mock("$lib/composables/useServerReachabilityReload", () => ({
   })),
 }));
 
-describe.skip("GenericMediaListPage", () => {
+// The component lazily subscribes to the backend `search-event` when searching.
+vi.mock("@tauri-apps/api/event", () => ({
+  listen: vi.fn(async () => () => {}),
+}));
+
+describe("GenericMediaListPage", () => {
   // Component integration tests - core sorting/search/debouncing logic tested in backend-integration.test.ts
   beforeEach(() => {
     vi.clearAllMocks();
@@ -66,6 +78,16 @@ describe.skip("GenericMediaListPage", () => {
     });
 
     it("should load items on mount", async () => {
+      const mockGetItemsFn = vi.fn().mockResolvedValue({
+        items: [],
+        totalRecordCount: 0,
+      });
+
+      vi.mocked((await import("$lib/stores/auth")).auth.getRepository).mockReturnValue({
+        getItems: mockGetItemsFn,
+        search: vi.fn(),
+      } as any);
+
       const config = {
         itemType: "Audio" as const,
         title: "Tracks",
@@ -80,9 +102,7 @@ describe.skip("GenericMediaListPage", () => {
         props: { config },
       });
 
-      await waitFor(() => {
-        // loadItems should have been called
-      });
+      await waitFor(() => expect(mockGetItemsFn).toHaveBeenCalledWith("lib123", expect.anything()));
     });
 
     it("should display sort options", () => {
@@ -111,8 +131,14 @@ describe.skip("GenericMediaListPage", () => {
   });
 
   describe("Search Functionality", () => {
-    it("should debounce search input for 300ms", async () => {
-      vi.useFakeTimers();
+    it("should debounce rapid keystrokes into a single search for the final value", async () => {
+      const mockSearchFn = vi.fn().mockResolvedValue({ items: [], totalRecordCount: 0 });
+      const mockGetItemsFn = vi.fn().mockResolvedValue({ items: [], totalRecordCount: 0 });
+
+      vi.mocked((await import("$lib/stores/auth")).auth.getRepository).mockReturnValue({
+        getItems: mockGetItemsFn,
+        search: mockSearchFn,
+      } as any);
 
       const config = {
         itemType: "Audio" as const,
@@ -128,29 +154,33 @@ describe.skip("GenericMediaListPage", () => {
         props: { config },
       });
 
+      // Let the mount load settle so the debounce effect is armed.
+      await waitFor(() => expect(mockGetItemsFn).toHaveBeenCalled());
+
+      // Drive the debounce window deterministically with fake timers, flushing
+      // the async loadItems() microtasks after the timer fires.
+      vi.useFakeTimers();
       const searchInput = container.querySelector("input") as HTMLInputElement;
 
-      // Type into search
       fireEvent.input(searchInput, { target: { value: "t" } });
-      expect(searchInput.value).toBe("t");
-
-      // Search should not trigger immediately
-      vi.advanceTimersByTime(100);
-
-      // Add more characters
+      await vi.advanceTimersByTimeAsync(100);
+      fireEvent.input(searchInput, { target: { value: "te" } });
+      await vi.advanceTimersByTimeAsync(100);
+      fireEvent.input(searchInput, { target: { value: "tes" } });
+      await vi.advanceTimersByTimeAsync(100);
       fireEvent.input(searchInput, { target: { value: "test" } });
 
-      // Still shouldn't trigger (only 100ms passed total)
-      vi.advanceTimersByTime(100);
-
-      // Now advance to 300ms total - search should trigger
-      vi.advanceTimersByTime(100);
-
-      await waitFor(() => {
-        // Search should have been debounced
-      });
+      // 200ms after the final keystroke: still inside the 300ms window, so no
+      // search has fired despite four keystrokes.
+      await vi.advanceTimersByTimeAsync(200);
+      expect(mockSearchFn).not.toHaveBeenCalled();
 
+      // Cross the threshold: exactly one search, for the final value.
+      await vi.advanceTimersByTimeAsync(100);
       vi.useRealTimers();
+
+      expect(mockSearchFn).toHaveBeenCalledTimes(1);
+      expect(mockSearchFn).toHaveBeenCalledWith("test", expect.anything(), expect.any(Number));
     });
 
     it("should use backend search when search query is provided", async () => {
@@ -159,8 +189,13 @@ describe.skip("GenericMediaListPage", () => {
         totalRecordCount: 1,
       });
 
+      const mockGetItemsFn = vi.fn().mockResolvedValue({
+        items: [],
+        totalRecordCount: 0,
+      });
+
       const mockRepository = {
-        getItems: vi.fn(),
+        getItems: mockGetItemsFn,
         search: mockSearchFn,
       };
 
@@ -178,25 +213,27 @@ describe.skip("GenericMediaListPage", () => {
         displayComponent: "tracklist" as const,
       };
 
-      vi.useFakeTimers();
       const { container } = render(GenericMediaListPage, {
         props: { config },
       });
 
+      // Wait for the initial mount load so the debounced search effect is armed.
+      await waitFor(() => expect(mockGetItemsFn).toHaveBeenCalled());
+
       const searchInput = container.querySelector("input") as HTMLInputElement;
       fireEvent.input(searchInput, { target: { value: "test" } });
 
-      // Advance timer to trigger debounced search
-      vi.advanceTimersByTime(300);
-
+      // search() is called as search(query, options, requestId).
       await waitFor(() => {
-        expect(mockSearchFn).toHaveBeenCalledWith("test", expect.objectContaining({
+        expect(mockSearchFn).toHaveBeenCalledWith(
+          "test",
+          expect.objectContaining({
             includeItemTypes: ["Audio"],
             limit: 10000,
-        }));
+          }),
+          expect.any(Number)
+        );
       });
-
-      vi.useRealTimers();
     });
 
     it("should use getItems without search for empty query", async () => {
@@ -416,15 +453,18 @@ describe.skip("GenericMediaListPage", () => {
     });
 
     it("should include correct itemType in search request", async () => {
-      vi.useFakeTimers();
-
       const mockSearchFn = vi.fn().mockResolvedValue({
         items: [],
         totalRecordCount: 0,
       });
 
+      const mockGetItemsFn = vi.fn().mockResolvedValue({
+        items: [],
+        totalRecordCount: 0,
+      });
+
       const mockRepository = {
-        getItems: vi.fn(),
+        getItems: mockGetItemsFn,
         search: mockSearchFn,
       };
 
@@ -446,17 +486,20 @@ describe.skip("GenericMediaListPage", () => {
         props: { config },
       });
 
+      await waitFor(() => expect(mockGetItemsFn).toHaveBeenCalled());
+
       const searchInput = container.querySelector("input") as HTMLInputElement;
       fireEvent.input(searchInput, { target: { value: "album" } });
-      vi.advanceTimersByTime(300);
 
       await waitFor(() => {
-        expect(mockSearchFn).toHaveBeenCalledWith("album", expect.objectContaining({
+        expect(mockSearchFn).toHaveBeenCalledWith(
+          "album",
+          expect.objectContaining({
             includeItemTypes: ["MusicAlbum"],
-        }));
+          }),
+          expect.any(Number)
+        );
       });
-
-      vi.useRealTimers();
     });
   });
 
@@ -536,6 +579,7 @@ describe.skip("GenericMediaListPage", () => {
 
     it("should handle missing library gracefully", async () => {
       const { goto } = await import("$app/navigation");
+      vi.mocked(goto).mockClear();
 
       const mockGetItemsFn = vi.fn();
 
@@ -548,14 +592,12 @@ describe.skip("GenericMediaListPage", () => {
         mockRepository as any
       );
 
-      // Mock currentLibrary to return null
-      vi.resetModules();
-      vi.mocked((await import("$lib/stores/library")).currentLibrary.subscribe).mockImplementation(
-        (fn: any) => {
+      // Deliver a null current library for this test only.
+      const currentLibrary = vi.mocked((await import("$lib/stores/library")).currentLibrary);
+      currentLibrary.subscribe.mockImplementation((fn: any) => {
         fn(null);
         return vi.fn();
-        }
-      );
+      });
 
       const config = {
         itemType: "Audio" as const,
@@ -571,9 +613,15 @@ describe.skip("GenericMediaListPage", () => {
         props: { config },
       });
 
-      // Should navigate to back path when library is missing
-      await waitFor(() => {
-        // goto would be called with config.backPath
+      // With no current library, loadItems bails out to the back path and never
+      // queries the repository.
+      await waitFor(() => expect(goto).toHaveBeenCalledWith("/library/music"));
+      expect(mockGetItemsFn).not.toHaveBeenCalled();
+
+      // Restore the default (non-null) library for subsequent tests.
+      currentLibrary.subscribe.mockImplementation((fn: any) => {
+        fn({ id: "lib123", name: "Music" });
+        return vi.fn();
       });
     });
   });

src/lib/components/library/MediaCard.serverOnly.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/svelte";
+
+// Controllable stores for the offline "server only" branch. Declared via
+// vi.hoisted so they exist when the hoisted vi.mock factories run. A tiny
+// writable shim avoids importing svelte inside the hoisted block.
+const h = vi.hoisted(() => {
+  function shim<T>(initial: T) {
+    let value = initial;
+    const subs = new Set<(v: T) => void>();
+    return {
+      set(v: T) {
+        value = v;
+        subs.forEach((fn) => fn(value));
+      },
+      subscribe(fn: (v: T) => void) {
+        subs.add(fn);
+        fn(value);
+        return () => subs.delete(fn);
+      },
+    };
+  }
+  return {
+    isConnectedStore: shim(true),
+    showServerCatalogStore: shim(false),
+    downloadsStore: shim({ downloads: {} as Record<string, any> }),
+    downloadItem: vi.fn(async () => 1),
+    getUserId: vi.fn(() => "user-1"),
+  };
+});
+
+const { isConnectedStore, showServerCatalogStore, downloadsStore, downloadItem, getUserId } = h;
+
+vi.mock("$lib/stores/connectivity", () => ({
+  isConnected: { subscribe: h.isConnectedStore.subscribe },
+}));
+
+vi.mock("$lib/services/offlineCatalog", () => ({
+  showServerCatalog: { subscribe: h.showServerCatalogStore.subscribe },
+}));
+
+vi.mock("$lib/stores/downloads", () => ({
+  downloads: { subscribe: h.downloadsStore.subscribe, downloadItem: h.downloadItem },
+}));
+
+vi.mock("$lib/stores/auth", () => ({
+  auth: { getUserId: h.getUserId },
+}));
+
+// CachedImage does async repo/image work irrelevant to these tests.
+vi.mock("$lib/components/common/CachedImage.svelte", async () => ({
+  default: (await import("./__mocks__/StubImage.svelte")).default,
+}));
+
+import MediaCard from "./MediaCard.svelte";
+
+const track = {
+  id: "track-1",
+  name: "Some Song",
+  type: "Audio" as const,
+  serverId: "server-1",
+  artists: ["Artist A"],
+  albumName: "Album X",
+};
+
+describe("MediaCard server-only (offline browse & queue)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    isConnectedStore.set(true);
+    showServerCatalogStore.set(false);
+    downloadsStore.set({ downloads: {} });
+  });
+
+  it("shows no queue button while online", () => {
+    render(MediaCard, { props: { item: track } });
+    expect(screen.queryByLabelText(/Queue download/i)).toBeNull();
+  });
+
+  it("shows no queue button when offline but the reveal toggle is off", () => {
+    isConnectedStore.set(false);
+    render(MediaCard, { props: { item: track } });
+    expect(screen.queryByLabelText(/Queue download/i)).toBeNull();
+  });
+
+  it("reveals a queue button when offline and the reveal toggle is on", () => {
+    isConnectedStore.set(false);
+    showServerCatalogStore.set(true);
+    render(MediaCard, { props: { item: track } });
+    expect(screen.getByLabelText(/Queue download for Some Song/i)).toBeTruthy();
+  });
+
+  it("queues the item for download with its metadata on click", async () => {
+    isConnectedStore.set(false);
+    showServerCatalogStore.set(true);
+    render(MediaCard, { props: { item: track } });
+
+    await fireEvent.click(screen.getByLabelText(/Queue download for Some Song/i));
+
+    expect(downloadItem).toHaveBeenCalledTimes(1);
+    const args = downloadItem.mock.calls[0] as unknown as any[];
+    expect(args[0]).toBe("track-1"); // itemId
+    expect(args[1]).toBe("user-1"); // userId
+    expect(args[5]).toBe("Some Song"); // itemName
+    expect(args[6]).toBe("Artist A"); // artistName
+    expect(args[7]).toBe("Album X"); // albumName
+  });
+
+  it("shows a Queued badge (not the button) for a pending download", () => {
+    isConnectedStore.set(false);
+    showServerCatalogStore.set(true);
+    downloadsStore.set({
+      downloads: { "track-1": { itemId: "track-1", status: "pending", progress: 0 } },
+    });
+    render(MediaCard, { props: { item: track } });
+
+    expect(screen.getByText(/Queued/i)).toBeTruthy();
+    expect(screen.queryByLabelText(/Queue download/i)).toBeNull();
+  });
+
+  it("does not grey out a completed download", () => {
+    isConnectedStore.set(false);
+    showServerCatalogStore.set(true);
+    downloadsStore.set({
+      downloads: { "track-1": { itemId: "track-1", status: "completed", progress: 1 } },
+    });
+    render(MediaCard, { props: { item: track } });
+
+    expect(screen.queryByLabelText(/Queue download/i)).toBeNull();
+  });
+});

src/lib/components/library/MediaCard.svelte

@@ -2,6 +2,9 @@
   import type { MediaItem, Library } from "$lib/api/types";
   import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import { downloads } from "$lib/stores/downloads";
+  import { isConnected } from "$lib/stores/connectivity";
+  import { showServerCatalog } from "$lib/services/offlineCatalog";
+  import { auth } from "$lib/stores/auth";
   import CachedImage from "$lib/components/common/CachedImage.svelte";
 
   interface Props {
@@ -25,6 +28,55 @@
   );
   const downloadProgress = $derived(downloadInfo?.progress || 0);
 
+  // A media item (not a library) is "server only" when it exists in the cache
+  // but isn't downloaded/downloading — and we're offline with the reveal toggle
+  // on. Such cards render greyed out with a "queue for download" button and are
+  // inert to tap (nothing to play offline).
+  const isMediaItem = $derived("type" in item);
+  const isQueued = $derived(downloadInfo?.status === "pending");
+  // Actively transferring (as opposed to merely queued/pending for reconnect).
+  const isActivelyDownloading = $derived(downloadInfo?.status === "downloading");
+  // "Server only" = offline, reveal on, and not already downloaded or actively
+  // transferring. A `pending` (queued-for-reconnect) item stays server-only so
+  // it can show the Queued badge in place of the queue button.
+  const isServerOnly = $derived(
+    isMediaItem && !$isConnected && $showServerCatalog && !isDownloaded && !isActivelyDownloading
+  );
+
+  let queueError = $state<string | null>(null);
+
+  // Queue this item for download on next reconnect. Offline, this just persists
+  // a `pending` downloads row (no stream_url); the reconnect handler resolves
+  // the URL and the pump starts it. See offlineCatalog service.
+  async function queueForDownload(e: Event) {
+    e.stopPropagation();
+    if (!isMediaItem) return;
+    const media = item as MediaItem;
+    const userId = auth.getUserId();
+    if (!userId) {
+      queueError = "Not signed in";
+      return;
+    }
+    try {
+      queueError = null;
+      // Derive a sensible on-disk path; the backend heals stream_url on reconnect.
+      const filePath = `downloads/${media.id}`;
+      await downloads.downloadItem(
+        media.id,
+        userId,
+        filePath,
+        undefined,
+        undefined,
+        media.name,
+        media.artists?.join(", ") ?? undefined,
+        media.albumName ?? undefined
+      );
+    } catch (err) {
+      console.error("[MediaCard] Failed to queue download:", err);
+      queueError = "Failed to queue";
+    }
+  }
+
   const sizeClasses = {
     small: "w-24",
     medium: "w-36",
@@ -76,10 +128,12 @@
   });
 </script>
 
-<button
-  type="button"
-  class="group/card flex flex-col text-left {sizeClasses[size]} flex-shrink-0 transition-transform duration-200 hover:scale-105"
-  {onclick}
+<svelte:element
+  this={isServerOnly ? "div" : "button"}
+  type={isServerOnly ? undefined : "button"}
+  role={isServerOnly ? "group" : undefined}
+  class="group/card flex flex-col text-left {sizeClasses[size]} flex-shrink-0 transition-transform duration-200 {isServerOnly ? '' : 'hover:scale-105'}"
+  onclick={isServerOnly ? undefined : onclick}
 >
   <div class="relative {aspectRatio()} w-full rounded-lg overflow-hidden bg-[var(--color-surface)] shadow-md group-hover/card:shadow-2xl transition-shadow duration-200">
     <CachedImage
@@ -88,11 +142,12 @@
       tag={imageTag}
       maxWidth={maxWidth}
       alt={item.name}
-      class="w-full h-full object-cover transition-transform duration-300 group-hover/card:scale-110"
+      class="w-full h-full object-cover transition-transform duration-300 group-hover/card:scale-110 {isServerOnly ? 'opacity-40 grayscale' : ''}"
     />
 
-    <!-- Hover overlay with smooth gradient -->
-    <div class="absolute inset-0 bg-gradient-to-t from-black/60 via-black/0 to-black/0 opacity-0 group-hover/card:opacity-100 transition-opacity duration-300 flex items-center justify-center">
+    <!-- Hover overlay with smooth gradient (play affordance; hidden for
+         server-only cards, which can't be played offline) -->
+    <div class="absolute inset-0 bg-gradient-to-t from-black/60 via-black/0 to-black/0 opacity-0 {isServerOnly ? '' : 'group-hover/card:opacity-100'} transition-opacity duration-300 flex items-center justify-center">
       <div class="transform scale-90 group-hover/card:scale-100 opacity-0 group-hover/card:opacity-100 transition-all duration-300">
         <div class="w-14 h-14 rounded-full bg-[var(--color-jellyfin)] hover:bg-[var(--color-jellyfin)]/90 flex items-center justify-center shadow-2xl">
           <svg class="w-7 h-7 text-white ml-1" fill="currentColor" viewBox="0 0 24 24">
@@ -163,9 +218,43 @@
         {/if}
       </div>
     {/if}
+
+    <!-- Server-only: queue-for-download control (kept at full opacity over the
+         greyed artwork). Queued items show a "queued" badge instead. -->
+    {#if isServerOnly}
+      <div class="absolute inset-0 flex items-center justify-center">
+        {#if isQueued}
+          <div class="flex flex-col items-center gap-1 text-white" title="Queued — will download on reconnect">
+            <div class="w-11 h-11 rounded-full bg-black/60 flex items-center justify-center shadow-lg">
+              <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
+              </svg>
+            </div>
+            <span class="text-[10px] font-medium bg-black/60 px-1.5 py-0.5 rounded-full">Queued</span>
+          </div>
+        {:else}
+          <button
+            type="button"
+            onclick={queueForDownload}
+            class="w-11 h-11 rounded-full bg-[var(--color-jellyfin)] hover:bg-[var(--color-jellyfin)]/90 flex items-center justify-center shadow-lg transition-colors"
+            title="Queue download for next connection"
+            aria-label="Queue download for {item.name}"
+          >
+            <svg class="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M12 4v12m0 0l-4-4m4 4l4-4M4 20h16" />
+            </svg>
+          </button>
+        {/if}
+      </div>
+      {#if queueError}
+        <div class="absolute bottom-1 left-1 right-1 text-center text-[10px] text-red-200 bg-black/70 rounded px-1 py-0.5">
+          {queueError}
+        </div>
+      {/if}
+    {/if}
   </div>
 
-  <div class="mt-2 space-y-0.5">
+  <div class="mt-2 space-y-0.5 {isServerOnly ? 'opacity-60' : ''}">
     <p class="text-sm font-medium text-white truncate group-hover/card:text-[var(--color-jellyfin)] transition-colors">
       {truncateMiddle(item.name, 40)}
     </p>
@@ -173,4 +262,4 @@
       <p class="text-xs text-gray-400 truncate">{subtitle()}</p>
     {/if}
   </div>
-</button>
+</svelte:element>

src/lib/components/library/MediaCard.test.ts

@@ -1,373 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { render, screen, waitFor } from "@testing-library/svelte";
-import MediaCard from "./MediaCard.svelte";
-
-vi.mock("$lib/stores/auth", () => ({
-  auth: {
-    getRepository: vi.fn(() => ({
-      getImageUrl: vi.fn(),
-    })),
-  },
-}));
-
-describe.skip("MediaCard - Async Image Loading", () => {
-  // Component rendering tests skipped - core async logic tested in repository-client.test.ts
-  let mockRepository: any;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockRepository = {
-      getImageUrl: vi.fn(),
-    };
-
-    vi.mocked((global as any).__stores_auth?.auth?.getRepository).mockReturnValue(mockRepository);
-  });
-
-  afterEach(() => {
-    vi.clearAllTimers();
-  });
-
-  describe("Image Loading", () => {
-    it("should load image URL asynchronously", async () => {
-      const mockImageUrl = "https://server.com/Items/item123/Images/Primary?api_key=token";
-      mockRepository.getImageUrl.mockResolvedValue(mockImageUrl);
-
-      const mediaItem = {
-        id: "item123",
-        name: "Test Album",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "abc123",
-      };
-
-      const { container } = render(MediaCard, {
-        props: { item: mediaItem },
-      });
-
-      // Component should render immediately with placeholder
-      expect(container).toBeTruthy();
-
-      // Wait for image URL to load
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalledWith(
-          "item123",
-          "Primary",
-          expect.objectContaining({
-            maxWidth: 300,
-          })
-        );
-      });
-    });
-
-    it("should show placeholder while image is loading", async () => {
-      const mockImageUrl = "https://server.com/Items/item123/Images/Primary?api_key=token";
-      mockRepository.getImageUrl.mockImplementation(
-        () => new Promise((resolve) => setTimeout(() => resolve(mockImageUrl), 100))
-      );
-
-      const mediaItem = {
-        id: "item123",
-        name: "Test Album",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "abc123",
-      };
-
-      const { container } = render(MediaCard, {
-        props: { item: mediaItem },
-      });
-
-      // Placeholder should be visible initially
-      const placeholder = container.querySelector(".placeholder");
-      if (placeholder) {
-        expect(placeholder).toBeTruthy();
-      }
-
-      // Wait for image to load
-      vi.useFakeTimers();
-      vi.advanceTimersByTime(100);
-      vi.useRealTimers();
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalled();
-      });
-    });
-
-    it("should update image URL when item changes", async () => {
-      const mockImageUrl1 = "https://server.com/Items/item1/Images/Primary?api_key=token";
-      const mockImageUrl2 = "https://server.com/Items/item2/Images/Primary?api_key=token";
-
-      mockRepository.getImageUrl.mockResolvedValueOnce(mockImageUrl1);
-
-      const mediaItem1 = {
-        id: "item1",
-        name: "Album 1",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "tag1",
-      };
-
-      const { rerender } = render(MediaCard, {
-        props: { item: mediaItem1 },
-      });
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalledWith("item1", "Primary", expect.any(Object));
-      });
-
-      // Change item
-      mockRepository.getImageUrl.mockResolvedValueOnce(mockImageUrl2);
-
-      const mediaItem2 = {
-        id: "item2",
-        name: "Album 2",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "tag2",
-      };
-
-      await rerender({ item: mediaItem2 });
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalledWith("item2", "Primary", expect.any(Object));
-      });
-    });
-
-    it("should not reload image if item ID hasn't changed", async () => {
-      const mockImageUrl = "https://server.com/Items/item123/Images/Primary?api_key=token";
-      mockRepository.getImageUrl.mockResolvedValue(mockImageUrl);
-
-      const mediaItem = {
-        id: "item123",
-        name: "Test Album",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "abc123",
-      };
-
-      const { rerender } = render(MediaCard, {
-        props: { item: mediaItem },
-      });
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(1);
-      });
-
-      // Rerender with same item
-      await rerender({ item: mediaItem });
-
-      // Should not call getImageUrl again
-      expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(1);
-    });
-
-    it("should handle missing primary image tag gracefully", async () => {
-      const mediaItem = {
-        id: "item123",
-        name: "Test Album",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        // primaryImageTag is undefined
-      };
-
-      const { container } = render(MediaCard, {
-        props: { item: mediaItem },
-      });
-
-      // Should render without calling getImageUrl
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).not.toHaveBeenCalled();
-      });
-
-      // Should show placeholder
-      expect(container).toBeTruthy();
-    });
-
-    it("should handle image load errors gracefully", async () => {
-      mockRepository.getImageUrl.mockRejectedValue(new Error("Failed to load image"));
-
-      const mediaItem = {
-        id: "item123",
-        name: "Test Album",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "abc123",
-      };
-
-      const { container } = render(MediaCard, {
-        props: { item: mediaItem },
-      });
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalled();
-      });
-
-      // Should still render without crashing
-      expect(container).toBeTruthy();
-    });
-  });
-
-  describe("Image Options", () => {
-    it("should pass correct options to getImageUrl", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image");
-
-      const mediaItem = {
-        id: "item123",
-        name: "Test Album",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "abc123",
-      };
-
-      render(MediaCard, {
-        props: { item: mediaItem },
-      });
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalledWith(
-          "item123",
-          "Primary",
-          {
-            maxWidth: 300,
-          }
-        );
-      });
-    });
-
-    it("should include tag in image options when available", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image");
-
-      const mediaItem = {
-        id: "item123",
-        name: "Test Album",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "tag123",
-      };
-
-      render(MediaCard, {
-        props: { item: mediaItem },
-      });
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalledWith(
-          "item123",
-          "Primary",
-          {
-            maxWidth: 300,
-          }
-        );
-      });
-    });
-  });
-
-  describe("Caching", () => {
-    it("should cache image URLs to avoid duplicate requests", async () => {
-      const mockImageUrl = "https://server.com/Items/item123/Images/Primary?api_key=token";
-      mockRepository.getImageUrl.mockResolvedValue(mockImageUrl);
-
-      const mediaItem = {
-        id: "item123",
-        name: "Test Album",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "abc123",
-      };
-
-      // Render same item multiple times
-      const { rerender } = render(MediaCard, {
-        props: { item: mediaItem },
-      });
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(1);
-      });
-
-      // Rerender with same item
-      await rerender({ item: mediaItem });
-
-      // Should still only have called once (cached)
-      expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(1);
-    });
-
-    it("should have separate cache entries for different items", async () => {
-      const mockImageUrl1 = "https://server.com/Items/item1/Images/Primary?api_key=token";
-      const mockImageUrl2 = "https://server.com/Items/item2/Images/Primary?api_key=token";
-
-      let callCount = 0;
-      mockRepository.getImageUrl.mockImplementation(() => {
-        callCount++;
-        return Promise.resolve(callCount === 1 ? mockImageUrl1 : mockImageUrl2);
-      });
-
-      const item1 = {
-        id: "item1",
-        name: "Album 1",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "tag1",
-      };
-
-      const item2 = {
-        id: "item2",
-        name: "Album 2",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "tag2",
-      };
-
-      const { rerender } = render(MediaCard, {
-        props: { item: item1 },
-      });
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(1);
-      });
-
-      await rerender({ item: item2 });
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(2);
-      });
-
-      // Change back to item 1 - should use cached value
-      await rerender({ item: item1 });
-
-      expect(mockRepository.getImageUrl).toHaveBeenCalledTimes(2);
-    });
-  });
-
-  describe("Reactive Updates", () => {
-    it("should respond to property changes via $effect", async () => {
-      mockRepository.getImageUrl.mockResolvedValue("https://server.com/image");
-
-      const mediaItem = {
-        id: "item123",
-        name: "Test Album",
-        type: "MusicAlbum" as const,
-        serverId: "server-1",
-        primaryImageTag: "abc123",
-      };
-
-      const { rerender } = render(MediaCard, {
-        props: { item: mediaItem },
-      });
-
-      await waitFor(() => {
-        expect(mockRepository.getImageUrl).toHaveBeenCalled();
-      });
-
-      const previousCallCount = mockRepository.getImageUrl.mock.calls.length;
-
-      // Update a property that shouldn't trigger reload
-      await rerender({
-        item: {
-          ...mediaItem,
-          name: "Updated Album Name",
-        },
-      });
-
-      // Should not call getImageUrl again (same primaryImageTag)
-      expect(mockRepository.getImageUrl.mock.calls.length).toBe(previousCallCount);
-    });
-  });
-});

src/lib/components/library/TrackList.test.ts

@@ -54,8 +54,9 @@ import { invoke } from "@tauri-apps/api/core";
 import TrackList from "./TrackList.svelte";
 import type { MediaItem } from "$lib/api/types";
 import { auth } from "$lib/stores/auth";
+import { toast } from "$lib/stores/toast";
 
-describe.skip("TrackList", () => {
+describe("TrackList", () => {
   const mockRepository = {
     getAudioStreamUrl: vi.fn(),
     getImageUrl: vi.fn(),
@@ -118,7 +119,8 @@ describe.skip("TrackList", () => {
 
       expect(getAllByText("Song 1").length).toBeGreaterThan(0);
       expect(getAllByText("Song 2").length).toBeGreaterThan(0);
-      expect(getAllByText(/Song 3 with a Very Long Name/).length).toBeGreaterThan(0);
+      // Long names are abbreviated in the middle via truncateMiddle(name, 48).
+      expect(getAllByText(/Song 3 with a Very Long .*Should Be Truncated/).length).toBeGreaterThan(0);
     });
 
     it("shows loading skeleton when loading=true", () => {
@@ -137,10 +139,12 @@ describe.skip("TrackList", () => {
     });
 
     it("shows artist column by default", () => {
-      const { getByText } = render(TrackList, { props: { tracks: mockTracks } });
+      const { getByText, getAllByText } = render(TrackList, { props: { tracks: mockTracks } });
 
+      // Header only exists in the desktop table.
       expect(getByText("Artist")).toBeTruthy();
-      expect(getByText("Artist 1")).toBeTruthy();
+      // Artist name renders in both desktop and mobile views.
+      expect(getAllByText("Artist 1").length).toBeGreaterThan(0);
     });
 
     it("hides artist column when showArtist=false", () => {
@@ -153,10 +157,12 @@ describe.skip("TrackList", () => {
     });
 
     it("shows album column by default", () => {
-      const { getByText } = render(TrackList, { props: { tracks: mockTracks } });
+      const { getByText, getAllByText } = render(TrackList, { props: { tracks: mockTracks } });
 
+      // Header only exists in the desktop table.
       expect(getByText("Album")).toBeTruthy();
-      expect(getByText("Album 1")).toBeTruthy();
+      // Album name renders in both desktop and mobile views.
+      expect(getAllByText("Album 1").length).toBeGreaterThan(0);
     });
 
     it("hides album column when showAlbum=false", () => {
@@ -185,12 +191,13 @@ describe.skip("TrackList", () => {
         },
       ];
 
-      // Component renders both desktop and mobile views
+      // formatDuration(undefined) renders an empty string, so the row still
+      // renders without crashing and the track title is present.
       const { getAllByText } = render(TrackList, {
         props: { tracks: tracksWithoutDuration },
       });
 
-      expect(getAllByText("-").length).toBeGreaterThan(0);
+      expect(getAllByText("Song 1").length).toBeGreaterThan(0);
     });
 
     it("handles tracks without artist", () => {
@@ -198,20 +205,24 @@ describe.skip("TrackList", () => {
         {
           ...mockTracks[0],
           artists: undefined,
+          artistItems: undefined,
         },
       ];
 
-      const { getByText } = render(TrackList, {
+      // The artist fallback renders "-" in both desktop and mobile views.
+      const { getAllByText } = render(TrackList, {
         props: { tracks: tracksWithoutArtist },
       });
 
-      expect(getByText("-")).toBeTruthy();
+      expect(getAllByText("-").length).toBeGreaterThan(0);
     });
 
     it("renders multiple artists joined with comma", () => {
-      const { getByText } = render(TrackList, { props: { tracks: mockTracks } });
+      // Tracks fall back to artists.join(", ") when artistItems is absent;
+      // the joined string renders in both desktop and mobile views.
+      const { getAllByText } = render(TrackList, { props: { tracks: mockTracks } });
 
-      expect(getByText("Artist 3, Artist 4")).toBeTruthy();
+      expect(getAllByText("Artist 3, Artist 4").length).toBeGreaterThan(0);
     });
   });
 
@@ -278,25 +289,8 @@ describe.skip("TrackList", () => {
       });
     });
 
-    it.skip("calls getAudioStreamUrl for each track", async () => {
-      // NOTE: This test is skipped because the code was refactored to use player_play_tracks
-      // which sends trackIds to the backend. The backend now handles all metadata/stream fetching.
-      // This test expected the old behavior where frontend called getAudioStreamUrl.
-    });
-
-    it.skip("includes artwork URLs in queue items", async () => {
-      // NOTE: This test is skipped because the code was refactored.
-      // Stream URLs and artwork URLs are no longer fetched by frontend.
-      // Backend handles all metadata and stream URL fetching via player_play_tracks.
-    });
-
-    it.skip("handles tracks without artwork gracefully", async () => {
-      // NOTE: This test is skipped because the code no longer includes artwork URLs
-      // in queue items sent to backend. Backend handles artwork fetching independently.
-    });
-
-    it("shows error alert when playback fails", async () => {
-      const alertSpy = vi.spyOn(window, "alert").mockImplementation(() => {});
+    it("shows error toast when playback fails", async () => {
+      const toastSpy = vi.spyOn(toast, "error").mockImplementation(() => "");
       (invoke as any).mockRejectedValue(new Error("Network error"));
 
       const { container } = render(TrackList, { props: { tracks: mockTracks } });
@@ -309,16 +303,19 @@ describe.skip("TrackList", () => {
       await fireEvent.click(firstTrackButton!);
 
       await waitFor(() => {
-        expect(alertSpy).toHaveBeenCalledWith(
-          expect.stringContaining("Failed to play track")
+        expect(toastSpy).toHaveBeenCalledWith(
+          expect.stringContaining("Failed to play track"),
+          expect.anything()
         );
       });
 
-      alertSpy.mockRestore();
+      toastSpy.mockRestore();
     });
 
     it("handles auth errors gracefully", async () => {
-      const alertSpy = vi.spyOn(window, "alert").mockImplementation(() => {});
+      const toastSpy = vi.spyOn(toast, "error").mockImplementation(() => "");
+      // No repository → requireHandle() throws "No repository available",
+      // which the default handler surfaces via toast.error.
       (auth.getRepository as any).mockReturnValue(null as any);
 
       const { container } = render(TrackList, { props: { tracks: mockTracks } });
@@ -331,22 +328,18 @@ describe.skip("TrackList", () => {
       await fireEvent.click(firstTrackButton!);
 
       await waitFor(() => {
-        expect(alertSpy).toHaveBeenCalledWith(
-          expect.stringContaining("Not authenticated")
+        expect(toastSpy).toHaveBeenCalledWith(
+          expect.stringContaining("Failed to play track"),
+          expect.anything()
         );
       });
 
-      alertSpy.mockRestore();
+      toastSpy.mockRestore();
 
       // Restore mock for other tests
       (auth.getRepository as any).mockReturnValue(mockRepository as any);
     });
 
-    it.skip("handles stream URL generation errors", async () => {
-      // NOTE: This test is skipped because stream URLs are no longer fetched by frontend.
-      // The code now uses player_play_tracks which sends trackIds to backend.
-      // Backend handles all stream URL generation, so this error path no longer exists.
-    });
   });
 
   describe("Custom Callback Tests", () => {

src/lib/components/library/__mocks__/StubImage.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+  // Minimal stand-in for CachedImage in unit tests: renders nothing meaningful,
+  // just accepts the same props so MediaCard renders without hitting the repo.
+  let { alt = "" }: { alt?: string; [key: string]: unknown } = $props();
+</script>
+
+<div data-testid="stub-image" aria-label={alt}></div>

src/lib/services/offlineCatalog.ts

@@ -0,0 +1,129 @@
+// Offline catalog service - "browse & queue" for offline mode.
+//
+// Two responsibilities:
+//  1. Full-catalog pre-sync: while online, walk every library and persist all
+//     items to the offline cache so the whole catalog is browsable (greyed out)
+//     offline. Backed by the `syncFullCatalog` Rust command.
+//  2. Resume-on-reconnect: when the server becomes reachable again, resolve the
+//     stream URLs of downloads that were queued while offline and let the pump
+//     start them. Backed by `resumeQueuedDownloads`.
+//
+// It also owns the `showServerCatalog` UI flag (the offline banner toggle that
+// reveals greyed-out, non-downloaded server media).
+//
+// TRACES: UR-002
+
+import { writable, type Writable } from "svelte/store";
+import { commands } from "$lib/api/bindings";
+import { auth } from "$lib/stores/auth";
+import { isConnected } from "$lib/stores/connectivity";
+
+/**
+ * When true (and offline), library grids reveal greyed-out versions of media
+ * that exists on the server but isn't downloaded, each with a button to queue
+ * a download for the next reconnect. Toggled from the offline banner.
+ */
+export const showServerCatalog: Writable<boolean> = writable(false);
+
+// Keep the backend's offline library queries in sync with the UI toggle. The
+// offline cache holds the whole synced catalog, so `get_items` would otherwise
+// return every server item even offline with the toggle off. Include the
+// non-downloaded catalog only when online (fast browsing reads the same cache)
+// or when the "Show all server media" toggle is on.
+let lastIncludeCatalog: boolean | null = null;
+function pushCatalogVisibility(connected: boolean, showCatalog: boolean): void {
+  const include = connected || showCatalog;
+  if (include === lastIncludeCatalog) return;
+  lastIncludeCatalog = include;
+  commands.setShowServerCatalog(include).catch((err) => {
+    console.warn("[OfflineCatalog] Failed to set catalog visibility:", err);
+  });
+}
+
+let connectedNow = true;
+let showCatalogNow = false;
+isConnected.subscribe((v) => {
+  connectedNow = v;
+  pushCatalogVisibility(connectedNow, showCatalogNow);
+});
+showServerCatalog.subscribe((v) => {
+  showCatalogNow = v;
+  pushCatalogVisibility(connectedNow, showCatalogNow);
+});
+
+/** Last time a full catalog sync completed, for a UI hint. */
+export const lastCatalogSync: Writable<string | null> = writable(null);
+
+// Guard against overlapping syncs (they can be slow on large libraries).
+let syncInProgress = false;
+
+function currentHandle(): string | null {
+  try {
+    return auth.getRepository().getHandle();
+  } catch {
+    return null; // not connected yet
+  }
+}
+
+/**
+ * Walk every library and cache the full catalog. Best-effort and non-blocking:
+ * safe to call on startup (while online) and on reconnect. No-ops if not
+ * connected or a sync is already running.
+ */
+export async function syncCatalog(): Promise<void> {
+  if (syncInProgress) return;
+  const handle = currentHandle();
+  if (!handle) return;
+
+  syncInProgress = true;
+  try {
+    const result = await commands.syncFullCatalog(handle);
+    console.info(
+      `[OfflineCatalog] Synced ${result.itemsCached} items (${result.librariesFailed} libraries failed)`
+    );
+    await refreshSyncStatus();
+  } catch (err) {
+    console.warn("[OfflineCatalog] Full catalog sync failed:", err);
+  } finally {
+    syncInProgress = false;
+  }
+}
+
+/**
+ * Resolve URLs for downloads queued while offline and pump them. Call on
+ * reconnect. No-ops if not connected.
+ */
+export async function resumeQueued(): Promise<void> {
+  const handle = currentHandle();
+  if (!handle) return;
+  try {
+    const result = await commands.resumeQueuedDownloads(handle);
+    if (result.resolved > 0 || result.failed > 0) {
+      console.info(
+        `[OfflineCatalog] Resumed queued downloads: ${result.resolved} resolved, ${result.failed} failed`
+      );
+    }
+  } catch (err) {
+    console.warn("[OfflineCatalog] Failed to resume queued downloads:", err);
+  }
+}
+
+/** Refresh the last-synced timestamp from the backend. */
+export async function refreshSyncStatus(): Promise<void> {
+  try {
+    const status = await commands.catalogSyncStatus();
+    lastCatalogSync.set(status.lastSyncedAt ?? null);
+  } catch (err) {
+    console.debug("[OfflineCatalog] Failed to fetch sync status:", err);
+  }
+}
+
+/**
+ * Called when the server becomes reachable again: resume queued downloads first
+ * (fast, user-visible), then refresh the catalog in the background.
+ */
+export async function onReconnected(): Promise<void> {
+  await resumeQueued();
+  // Fire-and-forget: don't block reconnection handling on a potentially long walk.
+  void syncCatalog();
+}

src/lib/stores/auth.ts

@@ -201,6 +201,11 @@ function createAuthStore() {
           onServerReconnected: () => {
             // Retry session verification when server becomes reachable
             retryVerification();
+            // Resume downloads queued while offline, then refresh the catalog.
+            // Lazy import to avoid an auth <-> offlineCatalog import cycle.
+            import("$lib/services/offlineCatalog")
+              .then((m) => m.onReconnected())
+              .catch((err) => console.warn("[Auth] Catalog reconnect failed:", err));
           },
         }).catch((error) => {
           console.error("[Auth] Failed to start connectivity monitoring:", error);

src/lib/stores/playbackMode.test.ts

@@ -295,6 +295,68 @@ describe("playbackMode store", () => {
     });
   });
 
+  describe("refresh (reconcile to Rust authoritative mode)", () => {
+    it("adopts the Rust mode and aligns the selected session", async () => {
+      const { playbackMode } = await import("./playbackMode");
+
+      // Start disagreeing with Rust: store thinks local, Rust says remote.
+      playbackMode.setMode("local");
+      mockInvoke.mockResolvedValueOnce({ type: "remote", session_id: "sess-xyz" });
+
+      await playbackMode.refresh();
+
+      const state = get(playbackMode);
+      expect(state.mode).toBe("remote");
+      expect(state.remoteSessionId).toBe("sess-xyz");
+      // The merged UI stores follow selectedSession, so it must be aligned too.
+      expect(mockSelectSession).toHaveBeenCalledWith("sess-xyz");
+    });
+
+    it("clears the selected session when Rust reports non-remote", async () => {
+      const { playbackMode } = await import("./playbackMode");
+
+      playbackMode.setMode("remote", "sess-old");
+      mockInvoke.mockResolvedValueOnce({ type: "idle" });
+
+      await playbackMode.refresh();
+
+      const state = get(playbackMode);
+      expect(state.mode).toBe("idle");
+      expect(state.remoteSessionId).toBeNull();
+      expect(mockSelectSession).toHaveBeenCalledWith(null);
+    });
+  });
+
+  describe("transfer reconciles to Rust on completion", () => {
+    it("refreshes from Rust after a successful transferToRemote", async () => {
+      const { playbackMode } = await import("./playbackMode");
+
+      // First call: the transfer command; second call: the finally refresh.
+      mockInvoke.mockResolvedValueOnce(undefined);
+      mockInvoke.mockResolvedValueOnce({ type: "remote", session_id: "session-456" });
+
+      await playbackMode.transferToRemote("session-456");
+
+      expect(mockInvoke).toHaveBeenCalledWith("playback_mode_get_current");
+    });
+
+    it("still reconciles to Rust when transferToRemote throws mid-transfer", async () => {
+      const { playbackMode } = await import("./playbackMode");
+
+      // Transfer command fails, leaving the optimistic state possibly wrong.
+      mockInvoke.mockRejectedValueOnce(new Error("boom"));
+      // The finally refresh reads the true mode (Rust never left local).
+      mockInvoke.mockResolvedValueOnce({ type: "local" });
+
+      await expect(playbackMode.transferToRemote("session-456")).rejects.toThrow("boom");
+
+      // The reconciling read must have happened despite the throw.
+      expect(mockInvoke).toHaveBeenCalledWith("playback_mode_get_current");
+      const state = get(playbackMode);
+      expect(state.mode).toBe("local");
+    });
+  });
+
   describe("clearError", () => {
     it("should clear transfer error", async () => {
       const { playbackMode } = await import("./playbackMode");

src/lib/stores/playbackMode.ts

@@ -48,12 +48,16 @@ function createPlaybackModeStore() {
   async function refreshMode(): Promise<void> {
     try {
       const rustMode = (await commands.playbackModeGetCurrent()) as RustPlaybackMode;
+      const remoteSessionId = rustMode.type === "remote" ? rustMode.session_id || null : null;
 
       update((s) => ({
         ...s,
         mode: rustMode.type,
-        remoteSessionId: rustMode.type === "remote" ? rustMode.session_id || null : null,
+        remoteSessionId,
       }));
+      // Keep the selected session aligned so the merged UI stores follow the
+      // authoritative mode.
+      sessions.selectSession(remoteSessionId);
     } catch (error) {
       console.error("Failed to get playback mode:", error);
     }
@@ -135,6 +139,10 @@ function createPlaybackModeStore() {
       throw error;
     } finally {
       currentTransferAbort = null;
+      // Snap back to whatever the Rust manager actually settled on. If any step
+      // above threw mid-transfer, the optimistic update may not match reality;
+      // Rust is authoritative, so reconcile to it.
+      await refreshMode();
     }
   }
 
@@ -263,6 +271,9 @@ function createPlaybackModeStore() {
         console.warn("[PlaybackMode] Failed to clear transferring flag:", e);
       }
       currentTransferAbort = null;
+      // Reconcile to the authoritative Rust mode in case a step above threw and
+      // left our optimistic state inconsistent (see transferToRemote).
+      await refreshMode();
     }
   }
 
@@ -288,6 +299,27 @@ function createPlaybackModeStore() {
             console.error("[PlaybackMode] Lockscreen-triggered transfer failed:", e),
           );
         }
+        return;
+      }
+
+      // The Rust PlaybackModeManager is the single source of truth for routing.
+      // Reconcile our mirror store to it whenever it changes, so the UI and the
+      // event filter in playerEvents.ts can't drift and start routing controls to
+      // the wrong device. We deliberately do NOT reconcile while a transfer is in
+      // flight: transfers emit intermediate mode changes (and briefly hold the
+      // transferring flag), and the transfer functions own the final state.
+      if (event.payload.type === "playback_mode_changed") {
+        const currentState = get({ subscribe });
+        if (currentState.isTransferring) {
+          return;
+        }
+        const mode = event.payload.mode as PlaybackMode;
+        const remoteSessionId =
+          mode === "remote" ? event.payload.session_id ?? null : null;
+        console.log("[PlaybackMode] Backend mode changed →", mode, remoteSessionId);
+        update((s) => ({ ...s, mode, remoteSessionId }));
+        // Keep the selected session in step so the merged UI stores follow.
+        sessions.selectSession(remoteSessionId);
       }
     });
 

src/lib/utils/layoutShell.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Regression tests for the app's fixed bottom-UI (mini player + bottom nav)
+ * layout rules.
+ *
+ * The bug these guard against: on the library route the layout used to render
+ * its OWN in-flow mini player while the root ALSO painted a fixed bottom nav on
+ * top of it, and the library scroller only reserved 1rem — so the last row hid
+ * behind the nav. The fix unified everything onto the root: the root owns the
+ * single fixed bottom UI on every route/platform, and every scroll container
+ * reserves the measured `bottomUiHeight`.
+ *
+ * TRACES: UR-005 | DR-009
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  showBottomNav,
+  showGlobalMiniPlayer,
+  routeOwnsLayout,
+  showBottomUi,
+  reservedBottomPadding,
+} from "./layoutShell";
+
+const authed = (pathname: string) => ({ pathname, isAuthenticated: true });
+
+describe("showGlobalMiniPlayer", () => {
+  it("shows on the main library page (regression: was hidden on non-Android)", () => {
+    expect(showGlobalMiniPlayer({ pathname: "/library" })).toBe(true);
+  });
+
+  it("shows on a deep library page", () => {
+    expect(showGlobalMiniPlayer({ pathname: "/library/abc123" })).toBe(true);
+  });
+
+  it("shows on home, search, downloads", () => {
+    expect(showGlobalMiniPlayer({ pathname: "/" })).toBe(true);
+    expect(showGlobalMiniPlayer({ pathname: "/search" })).toBe(true);
+    expect(showGlobalMiniPlayer({ pathname: "/downloads" })).toBe(true);
+  });
+
+  it("hides on the full-screen player, login, and settings", () => {
+    expect(showGlobalMiniPlayer({ pathname: "/player/xyz" })).toBe(false);
+    expect(showGlobalMiniPlayer({ pathname: "/login" })).toBe(false);
+    expect(showGlobalMiniPlayer({ pathname: "/settings" })).toBe(false);
+  });
+
+  it("does NOT depend on platform or on /library — the root owns it everywhere", () => {
+    // The signature intentionally has no `isAndroid` input: the old bug was a
+    // platform/route split that let a second in-flow mini player exist.
+    expect(showGlobalMiniPlayer({ pathname: "/library" })).toBe(true);
+  });
+});
+
+describe("showBottomNav", () => {
+  it("shows on authenticated content routes including library", () => {
+    expect(showBottomNav(authed("/library"))).toBe(true);
+    expect(showBottomNav(authed("/"))).toBe(true);
+    expect(showBottomNav(authed("/settings"))).toBe(true);
+  });
+
+  it("hides when unauthenticated", () => {
+    expect(showBottomNav({ pathname: "/library", isAuthenticated: false })).toBe(false);
+  });
+
+  it("hides on the full-screen player and login", () => {
+    expect(showBottomNav(authed("/player/xyz"))).toBe(false);
+    expect(showBottomNav(authed("/login"))).toBe(false);
+  });
+});
+
+describe("routeOwnsLayout", () => {
+  it("is true for library/settings/player/login (they manage their own scroll)", () => {
+    expect(routeOwnsLayout({ pathname: "/library" })).toBe(true);
+    expect(routeOwnsLayout({ pathname: "/library/abc" })).toBe(true);
+    expect(routeOwnsLayout({ pathname: "/settings" })).toBe(true);
+    expect(routeOwnsLayout({ pathname: "/player/x" })).toBe(true);
+    expect(routeOwnsLayout({ pathname: "/login" })).toBe(true);
+  });
+
+  it("is false for routes that render into the root scroller", () => {
+    expect(routeOwnsLayout({ pathname: "/" })).toBe(false);
+    expect(routeOwnsLayout({ pathname: "/search" })).toBe(false);
+    expect(routeOwnsLayout({ pathname: "/downloads" })).toBe(false);
+  });
+});
+
+describe("layout invariant: a reservation owner exists wherever bottom UI shows", () => {
+  // The core anti-regression check. Every route falls into exactly one of two
+  // reservation regimes:
+  //   - route owns its layout  -> the route's own scroller reserves bottomUiHeight
+  //   - route does NOT own it   -> the root scroller reserves bottomUiHeight
+  // The bug was that the library route was implicitly a THIRD regime: it owned
+  // its layout, showed a fixed nav from the root, but reserved only 1rem. That
+  // can't recur now because library both owns its layout (so it reserves
+  // internally) and the mini player is root-owned (no second in-flow bar).
+  const routes = ["/", "/search", "/downloads", "/library", "/library/abc", "/settings"];
+
+  for (const pathname of routes) {
+    it(`${pathname}: exactly one reservation owner`, () => {
+      if (!showBottomUi(authed(pathname))) return; // no bottom UI -> nothing to reserve
+      // Ownership is a total boolean, so exactly one regime always applies —
+      // there is no route that shows bottom UI with no reservation owner.
+      expect(typeof routeOwnsLayout({ pathname })).toBe("boolean");
+    });
+  }
+
+  it("library shows bottom UI AND owns its layout, so it reserves internally", () => {
+    // Directly pins the regression: library must NOT rely on the root scroller
+    // (it has none — the root gives owning routes a clipped, non-scrolling box).
+    expect(showBottomUi(authed("/library"))).toBe(true);
+    expect(routeOwnsLayout({ pathname: "/library" })).toBe(true);
+  });
+});
+
+describe("reservedBottomPadding", () => {
+  it("returns an exact px fit when no extra room requested", () => {
+    expect(reservedBottomPadding(120)).toBe("120px");
+  });
+
+  it("adds breathing room via calc for layout-owning routes", () => {
+    expect(reservedBottomPadding(120, 1)).toBe("calc(120px + 1rem)");
+  });
+
+  it("never returns negative padding", () => {
+    expect(reservedBottomPadding(-50)).toBe("0px");
+    expect(reservedBottomPadding(-50, 1)).toBe("calc(0px + 1rem)");
+  });
+
+  it("reserves 1rem-only when the bottom UI is collapsed to 0 (nothing playing, nav-only measured elsewhere)", () => {
+    expect(reservedBottomPadding(0, 1)).toBe("calc(0px + 1rem)");
+  });
+});

src/lib/utils/layoutShell.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure layout-shell logic for the app's fixed bottom UI (mini player stacked
+ * over the bottom nav).
+ *
+ * These rules used to live as inline `$derived` booleans scattered across the
+ * root and library `+layout.svelte` files, and diverged per platform/route —
+ * which is exactly how the "last row hidden behind the nav" bug kept coming
+ * back. The invariant is now a single source of truth:
+ *
+ *   - The ROOT layout owns the single fixed bottom UI on every route/platform.
+ *     There is no per-route/per-platform second mini player.
+ *   - Whatever fixed bottom UI is showing has a live-measured height
+ *     (`bottomUiHeight`), and every scroll container reserves exactly that much
+ *     bottom space so the last row can never render behind the nav.
+ *
+ * Keeping this pure makes the invariant unit-testable (jsdom has no layout
+ * engine, so the geometry itself can't be tested — but the decision logic can).
+ *
+ * TRACES: UR-005 | DR-009
+ */
+
+export interface BottomUiVisibilityInput {
+  /** Current route pathname, e.g. `$page.url.pathname`. */
+  pathname: string;
+  /** Whether the user is authenticated. */
+  isAuthenticated: boolean;
+}
+
+/**
+ * The bottom nav is shown on every authenticated route except the full-screen
+ * player and the login route.
+ */
+export function showBottomNav({
+  pathname,
+  isAuthenticated,
+}: BottomUiVisibilityInput): boolean {
+  return (
+    isAuthenticated &&
+    !pathname.startsWith("/player/") &&
+    !pathname.startsWith("/login")
+  );
+}
+
+/**
+ * The global (root-owned) mini player is shown on every route except the
+ * full-screen player, login, and settings. Crucially this is NOT gated on
+ * platform or on `/library` — the root owns the mini player everywhere, so the
+ * library route must never render its own second one.
+ */
+export function showGlobalMiniPlayer({ pathname }: { pathname: string }): boolean {
+  return (
+    !pathname.startsWith("/player/") &&
+    !pathname.startsWith("/login") &&
+    !pathname.startsWith("/settings")
+  );
+}
+
+/**
+ * Routes that own their own full-height layout (their own scroll container +
+ * bottom-space reservation). The root leaves these as a plain non-scrolling box
+ * and does NOT add bottom padding — the route reserves `bottomUiHeight` itself.
+ * Every other route scrolls in the root wrapper, which reserves the space.
+ */
+export function routeOwnsLayout({ pathname }: { pathname: string }): boolean {
+  return (
+    pathname.startsWith("/library") ||
+    pathname.startsWith("/settings") ||
+    pathname.startsWith("/player/") ||
+    pathname.startsWith("/login")
+  );
+}
+
+/**
+ * Whether any fixed bottom UI is showing for this route (mini player, nav, or
+ * both). When true, the active scroll container must reserve `bottomUiHeight`.
+ */
+export function showBottomUi(input: BottomUiVisibilityInput): boolean {
+  return showBottomNav(input) || showGlobalMiniPlayer({ pathname: input.pathname });
+}
+
+/**
+ * The bottom padding (in CSS) a scroll container must reserve so its last row
+ * clears the fixed bottom UI. `bottomUiHeight` is the live-measured height of
+ * the root's fixed bottom UI wrapper.
+ *
+ * @param bottomUiHeight measured height in px of the fixed bottom UI (0 if none)
+ * @param extraRem       breathing room added on top (routes that own their
+ *                       layout add 1rem; the root wrapper reserves an exact fit)
+ */
+export function reservedBottomPadding(
+  bottomUiHeight: number,
+  extraRem = 0,
+): string {
+  const px = Math.max(0, bottomUiHeight);
+  return extraRem > 0 ? `calc(${px}px + ${extraRem}rem)` : `${px}px`;
+}

src/routes/+layout.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { onMount, onDestroy } from "svelte";
+  import { get } from "svelte/store";
   import { page } from "$app/stores";
   import { goto } from "$app/navigation";
   import { platform } from "@tauri-apps/plugin-os";
@@ -7,8 +8,9 @@
   import { auth, needsReauth, isAuthenticated } from "$lib/stores/auth";
   import { connectivity, isConnected } from "$lib/stores/connectivity";
   import { initPlayerEvents, cleanupPlayerEvents } from "$lib/services/playerEvents";
-  import { initDownloadEvents, cleanupDownloadEvents } from "$lib/stores/downloads";
+  import { downloads, initDownloadEvents, cleanupDownloadEvents } from "$lib/stores/downloads";
   import { syncService } from "$lib/services/syncService";
+  import { onReconnected as onCatalogReconnected, syncCatalog, refreshSyncStatus, showServerCatalog, lastCatalogSync } from "$lib/services/offlineCatalog";
   import { playbackMode } from "$lib/stores/playbackMode";
   import { sessions } from "$lib/stores/sessions";
   import { currentMedia, isPlaying, playbackPosition, playbackDuration } from "$lib/stores/player";
@@ -18,6 +20,13 @@
   import SleepTimerModal from "$lib/components/player/SleepTimerModal.svelte";
   import BottomNav from "$lib/components/BottomNav.svelte";
   import { isInitialized, pendingSyncCount, isAndroid, showSleepTimerModal, bottomUiHeight } from "$lib/stores/appState";
+  import {
+    showBottomNav as computeShowBottomNav,
+    showGlobalMiniPlayer as computeShowGlobalMiniPlayer,
+    routeOwnsLayout as computeRouteOwnsLayout,
+    showBottomUi as computeShowBottomUi,
+    reservedBottomPadding,
+  } from "$lib/utils/layoutShell";
   // Shuffle/repeat/next/previous come from the event-driven queue store, the
   // single source of truth (updated instantly on queue_changed).
   import { isShuffle as shuffle, repeatMode as repeat, hasNext, hasPrevious } from "$lib/stores/queue";
@@ -32,15 +41,26 @@
   // Route-level visibility for the fixed bottom UI (the mini player itself also
   // self-gates on playback state; when it renders nothing the in-flow slot
   // collapses to 0 and the ResizeObserver shrinks the reserved padding).
+  // All layout-shell visibility/reservation rules live in one pure, unit-tested
+  // module ($lib/utils/layoutShell) so they can't drift per route/platform.
+  // The root owns the single fixed bottom UI (mini player + nav) on every route;
+  // the library route used to render its own in-flow mini player, which double-
+  // stacked with this fixed one and hid the last row behind the nav.
   const pathname = $derived($page.url.pathname);
   const showBottomNav = $derived(
-    $isAuthenticated && !pathname.startsWith('/player/') && !pathname.startsWith('/login')
+    computeShowBottomNav({ pathname, isAuthenticated: $isAuthenticated })
   );
-  const showGlobalMiniPlayer = $derived(
-    !pathname.startsWith('/player/') &&
-      !pathname.startsWith('/login') &&
-      !pathname.startsWith('/settings') &&
-      ($isAndroid || !pathname.startsWith('/library'))
+  const showGlobalMiniPlayer = $derived(computeShowGlobalMiniPlayer({ pathname }));
+
+  // The library and settings routes own their own full-height layout (their own
+  // scroll container + bottom-space reservation), so the root must leave their
+  // wrapper as a plain non-scrolling box. Every other top-level page (search,
+  // downloads, sessions, home) renders straight into the root, so the root
+  // wrapper has to scroll AND reserve the fixed bottom UI's height — otherwise
+  // the mini player / bottom nav overlay the last rows of content.
+  const routeOwnsLayout = $derived(computeRouteOwnsLayout({ pathname }));
+  const showBottomUi = $derived(
+    computeShowBottomUi({ pathname, isAuthenticated: $isAuthenticated })
   );
 
   $effect(() => {
@@ -83,9 +103,26 @@
     // Initialize download event listener
     await initDownloadEvents();
 
+    // Prime the downloads store from the DB. The store starts empty each launch,
+    // and download badges (e.g. AlbumDownloadButton) derive purely from it, so
+    // without an initial refresh a previously-downloaded album shows as
+    // not-downloaded until the user opens the Downloads page.
+    const userId = get(auth).user?.id;
+    if (userId) {
+      downloads.refresh(userId).catch((err) =>
+        console.error("Initial downloads refresh failed:", err)
+      );
+    }
+
     // Start sync service for offline mutation queue
     syncService.start();
 
+    // Kick off a best-effort full-catalog pre-sync so the whole server catalog
+    // is browsable (greyed out) offline, and load the last-sync hint for the
+    // offline banner. Non-blocking — no-ops when not connected.
+    void syncCatalog();
+    void refreshSyncStatus();
+
     // Initialize playback mode and session monitoring
     playbackMode.initializeSessionMonitoring();
     await playbackMode.refresh();
@@ -114,6 +151,8 @@
               onServerReconnected: () => {
                 // Retry session verification when server becomes reachable
                 auth.retryVerification();
+                // Resume offline-queued downloads and refresh the catalog.
+                void onCatalogReconnected();
               },
             }).catch((monitorError) => {
               console.error("[Layout] Failed to start connectivity monitoring:", monitorError);
@@ -153,13 +192,35 @@
             {$pendingSyncCount} pending sync{$pendingSyncCount !== 1 ? 's' : ''}
           </span>
         {/if}
+        <button
+          type="button"
+          onclick={() => showServerCatalog.update((v) => !v)}
+          class="ml-1 bg-white/20 hover:bg-white/30 px-2 py-0.5 rounded-full text-xs transition-colors"
+          aria-pressed={$showServerCatalog}
+          title={$lastCatalogSync ? `Catalog last synced ${new Date($lastCatalogSync).toLocaleString()}` : 'Catalog not yet synced'}
+        >
+          {$showServerCatalog ? 'Hide server media' : 'Show all server media'}
+        </button>
       </div>
     {/if}
 
-    <!-- Main content -->
+    <!-- Main content. Routes that own their full-height layout (library,
+         settings, player, login) get a plain clipped box and manage their own
+         scrolling internally. All other top-level pages render directly here, so
+         this wrapper must scroll and reserve the fixed bottom UI's measured
+         height so the mini player / bottom nav never overlap the last rows. -->
+    {#if routeOwnsLayout}
       <div class="flex-1 overflow-hidden">
         {@render children()}
       </div>
+    {:else}
+      <div
+        class="flex-1 overflow-y-auto min-h-0"
+        style="padding-bottom: {showBottomUi ? reservedBottomPadding($bottomUiHeight) : '0'}; overscroll-behavior: contain"
+      >
+        {@render children()}
+      </div>
+    {/if}
 
     <!-- Re-authentication modal -->
     <ReauthModal isOpen={$needsReauth} />

src/routes/library/+layout.svelte

@@ -5,13 +5,10 @@
   import { commands } from "$lib/api/bindings";
   import { auth, isAuthenticated, isLoading as isAuthLoading, currentUser } from "$lib/stores/auth";
   import { library } from "$lib/stores/library";
-  import { currentMedia, isPlaying, playbackPosition, playbackDuration } from "$lib/stores/player";
-  import { isShuffle, repeatMode, hasNext as hasNextStore, hasPrevious as hasPreviousStore } from "$lib/stores/queue";
-  import { isAndroid, bottomUiHeight } from "$lib/stores/appState";
+  import { bottomUiHeight } from "$lib/stores/appState";
+  import { reservedBottomPadding } from "$lib/utils/layoutShell";
   import { useScrollGuard } from "$lib/composables/useScrollGuard";
   import Search from "$lib/components/Search.svelte";
-  import MiniPlayer from "$lib/components/player/MiniPlayer.svelte";
-  import AudioPlayer from "$lib/components/player/AudioPlayer.svelte";
   import SleepTimerModal from "$lib/components/player/SleepTimerModal.svelte";
 
   // Scroll guard prevents accidental taps on library cards during/after scrolling (Android)
@@ -21,19 +18,8 @@
   let { children } = $props();
 
   let searchQuery = $state("");
-  let showFullPlayer = $state(false);
   let showOverflowMenu = $state(false);
   let showSleepTimerModal = $state(false);
-  // Queue status (shuffle, repeat, hasNext, hasPrevious) is event-driven via the
-  // queue store, which listens for queue_changed events from the backend. This
-  // updates instantly when toggling shuffle/repeat (no polling lag).
-  const shuffle = $derived($isShuffle);
-  const repeat = $derived($repeatMode);
-  const hasNext = $derived($hasNextStore);
-  const hasPrevious = $derived($hasPreviousStore);
-  // Platform comes from the shared appState store (set once in the root layout),
-  // so this layout and the root layout never disagree about Android — otherwise
-  // both can suppress their mini players and none appears. See $lib/stores/appState.
 
   onMount(() => {
     return () => {
@@ -204,57 +190,18 @@
       </div>
     </header>
 
-    <!-- Main content. The mini player is an in-flow flex sibling below this
-         scroller (not a fixed overlay), so the list can never render behind it.
-         Android keeps the global fixed bottom UI (nav + mini player), so there we
-         reserve its real measured height (`bottomUiHeight`, observed live in the
-         root layout) plus a little breathing room. Non-Android reserves none —
-         the in-flow bar below owns that space. -->
+    <!-- Main content. The fixed bottom UI (mini player + nav) is owned entirely
+         by the root layout on every platform, and its live-measured height is
+         published to `bottomUiHeight`. We reserve exactly that here (plus a
+         little breathing room) so the last row never hides behind the nav. -->
     <main
       class="flex-1 overflow-y-auto p-4 min-h-0"
-      style="padding-bottom: {$isAndroid ? `calc(${$bottomUiHeight}px + 1rem)` : '1rem'}; overscroll-behavior: contain"
+      style="padding-bottom: {reservedBottomPadding($bottomUiHeight, 1)}; overscroll-behavior: contain"
       onscroll={scrollGuard.onScroll}
     >
       {@render children()}
     </main>
 
-    <!-- Mini Player (only show on non-Android platforms - Android uses global mini player) -->
-    <!-- Hide on player page since full player is already there. Rendered in
-         normal flex flow so it sits above the list rather than overlapping it. -->
-    {#if !$isAndroid && !$page.url.pathname.startsWith('/player/')}
-      <MiniPlayer
-        media={$currentMedia}
-        isPlaying={$isPlaying}
-        position={$playbackPosition}
-        duration={$playbackDuration}
-        {shuffle}
-        {repeat}
-        {hasNext}
-        {hasPrevious}
-        className="flex-shrink-0"
-        onExpand={() => showFullPlayer = true}
-        onSleepTimerClick={() => showSleepTimerModal = true}
-      />
-    {/if}
-
-    <!-- Full Audio Player -->
-    {#if showFullPlayer}
-      <AudioPlayer
-        media={$currentMedia}
-        isPlaying={$isPlaying}
-        position={$playbackPosition}
-        duration={$playbackDuration}
-        {shuffle}
-        {repeat}
-        {hasNext}
-        {hasPrevious}
-        onClose={() => {
-          showFullPlayer = false;
-          window.history.back();
-        }}
-      />
-    {/if}
-
     <!-- Sleep Timer Modal -->
     <SleepTimerModal
       isOpen={showSleepTimerModal}