build uses android signing key

Reviewed-on: #9

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,455 @@
+//! 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 })
+}
+
+#[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/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, 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,9 @@ fn specta_builder() -> Builder<tauri::Wry> {
             start_download,
             enqueue_download,
             enqueue_video_downloads,
+            sync_full_catalog,
+            catalog_sync_status,
+            resume_queued_downloads,
             get_download_manager_stats,
             set_max_concurrent_downloads,
             get_smart_cache_stats,
@@ -930,9 +934,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 +1000,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/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/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,38 @@ 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");
+},
+/**
+ * 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 +1537,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
  */
@@ -2066,6 +2112,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/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/__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,102 @@
+// 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";
+
+/**
+ * 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);
+
+/** 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/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";
@@ -43,6 +45,20 @@
       ($isAndroid || !pathname.startsWith('/library'))
   );
 
+  // 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(
+    pathname.startsWith('/library') ||
+      pathname.startsWith('/settings') ||
+      pathname.startsWith('/player/') ||
+      pathname.startsWith('/login')
+  );
+  const showBottomUi = $derived(showBottomNav || showGlobalMiniPlayer);
+
   $effect(() => {
     const el = bottomUiEl;
     if (!el) {
@@ -83,9 +99,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 +147,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 +188,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 -->
-    <div class="flex-1 overflow-hidden">
-      {@render children()}
-    </div>
+    <!-- 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 ? `${$bottomUiHeight}px` : '0'}; overscroll-behavior: contain"
+      >
+        {@render children()}
+      </div>
+    {/if}
 
     <!-- Re-authentication modal -->
     <ReauthModal isOpen={$needsReauth} />