Playback fix

Playback reporting (position sync / resume-on-another-device):
- player_configure_jellyfin now builds a PlaybackReporter sharing the player
  controller's Arc, so Start/Progress/Stopped actually reach Jellyfin on every
  auth path (login/restore/reauth); previously they never did.
- The PlaybackReporterWrapper now shares the same Arc the controller and MPV
  progress loop report through, instead of a dead parallel Option.
- Android position callbacks now emit throttled progress reports (30s/item),
  mirroring the MPV backend.

Duration flash on pause:
- resolveDuration() prefers the live store duration for the already-loaded
  track over the runTimeTicks estimate, so pausing no longer clobbers the
  slider's max to 0 when runTimeTicks is missing.

Video leaking into audio mini player:
- isVideoItem() also checks the backend PlayerMediaItem mediaType
  discriminator, so a video started via player_play_item (no Jellyfin `type`,
  mediaType "video") no longer surfaces in the audio mini player.

Middle-truncation of long media names:
- New truncateMiddle util applied to track/episode/card/mini-player titles so
  distinguishing tails (episode numbers, suffixes) stay visible.

Adds regression tests for the duration and mini-player fixes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -1,4 +1,7 @@
-# JellyTau
+<h1 align="center">
+  <img src="docs/assets/logo.png" alt="JellyTau logo" width="120" /><br />
+  JellyTau
+</h1>
 
 A cross-platform Jellyfin client built with Tauri, SvelteKit, and TypeScript.
 

docs/architecture/README.md

@@ -13,6 +13,7 @@ JellyTau uses a client-server architecture: business logic lives in a comprehens
 - **Business Logic in Rust**: Core logic — playback, repository, sync, downloads, connectivity — lives in Rust for performance, reliability, and type safety.
 - **Presentation in Svelte**: The frontend (~20.5k non-test lines) owns UI, layout, navigation, and interaction state and invokes Rust commands. It is intentionally UI-heavy, **not** a thin wrapper. Largest pieces: components + routes (~14.6k lines), stores (~3.4k), api/services/utils (~2.4k); `VideoPlayer.svelte` alone is ~1.6k lines.
 - **Events + Polling hybrid**: Rust emits events the frontend listens to, and the UI also polls status on short intervals in a few hot spots (e.g. queue status in `library/+layout.svelte`, playback progress in `VideoPlayer.svelte`).
+- **Unified player boundary**: UI components control playback only through the frontend facade `src/lib/player/index.ts` (`playerController`), never by calling `commands.player*` directly. Webview-rendered HTML5 video reports its state back into Rust via `src/lib/player/html5Adapter.ts` and the `player_report_*` commands, so the `PlayerController` stays the single source of truth in both native (MPV/ExoPlayer) and HTML5 modes (see [05-platform-backends.md](05-platform-backends.md)).
 - **Handle-Based Resources**: UUID handles for stateful Rust objects.
 - **Cache-First**: Parallel queries with intelligent fallback.
 - **Single source of truth for reachability**: Server reachability is derived from the outcome of *real repository traffic*, not a side-channel poller. The `OnlineRepository` reports each server result to the `ConnectivityMonitor` (classified via `RepoError`), which applies a time-window debounce before declaring the server offline and recovers instantly on the first success. The standalone `/System/Info/Public` probe runs *only while offline*, as a recovery detector for idle sessions.
@@ -166,6 +167,9 @@ src/lib/
 │   ├── repository-client.ts # RepositoryClient wrapper (~100 lines)
 │   ├── client.ts            # JellyfinClient (helper for streaming)
 │   └── sessions.ts          # SessionsApi (remote session control)
+├── player/                  # Unified player boundary (frontend)
+│   ├── index.ts             # playerController facade — the only write-side entry point for playback
+│   └── html5Adapter.ts      # Reports webview <video> DOM events back into Rust (player_report_*)
 ├── services/
 │   ├── playerEvents.ts      # Tauri event listener for player events
 │   └── playbackReporting.ts # Thin wrapper (~50 lines)

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

@@ -15,6 +15,8 @@ import com.dtourolle.jellytau.player.JellyTauPlayer
 object VideoOverlayManager {
 
     private var attachedSurfaceView: SurfaceView? = null
+    private var contentLayoutListener: android.view.View.OnLayoutChangeListener? = null
+    private var listenerContentView: ViewGroup? = null
 
     /**
      * Attach the video SurfaceView to the Activity's content view.
@@ -51,6 +53,23 @@ object VideoOverlayManager {
             contentView.addView(surfaceView, 0, layoutParams)
             attachedSurfaceView = surfaceView
 
+            // Re-fit the video whenever the content view's bounds change (e.g. on
+            // device rotation) so the video is letterboxed to fit instead of being
+            // stretched/cropped by the MATCH_PARENT surface.
+            removeLayoutListener()
+            val listener = android.view.View.OnLayoutChangeListener {
+                _, left, top, right, bottom, oldLeft, oldTop, oldRight, oldBottom ->
+                if (right - left != oldRight - oldLeft || bottom - top != oldBottom - oldTop) {
+                    player.fitSurfaceToScreen()
+                }
+            }
+            contentView.addOnLayoutChangeListener(listener)
+            contentLayoutListener = listener
+            listenerContentView = contentView
+
+            // Fit once now that the surface is attached and the parent is sized.
+            player.fitSurfaceToScreen()
+
             android.util.Log.d("VideoOverlayManager", "Video surface attached to view hierarchy")
         } catch (e: Exception) {
             android.util.Log.e("VideoOverlayManager", "Failed to attach video surface", e)
@@ -64,6 +83,7 @@ object VideoOverlayManager {
      */
     fun detachVideoSurface(activity: Activity) {
         try {
+            removeLayoutListener()
             attachedSurfaceView?.let { surfaceView ->
                 val contentView = activity.window.decorView.findViewById<ViewGroup>(android.R.id.content)
                 contentView.removeView(surfaceView)
@@ -83,4 +103,12 @@ object VideoOverlayManager {
     fun isVideoSurfaceAttached(): Boolean {
         return attachedSurfaceView != null
     }
+
+    private fun removeLayoutListener() {
+        contentLayoutListener?.let { listener ->
+            listenerContentView?.removeOnLayoutChangeListener(listener)
+        }
+        contentLayoutListener = null
+        listenerContentView = null
+    }
 }

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

@@ -87,48 +87,39 @@ class JellyTauPlaybackService : MediaSessionService() {
         val jellyTauPlayer = JellyTauPlayer.getInstance()
         val exoPlayer = jellyTauPlayer.getExoPlayer()
 
-        // Wrap the ExoPlayer to intercept commands
+        // Wrap the ExoPlayer to intercept commands from Media3 controllers
+        // (e.g. Android Auto / Wear / system surfaces that bind to the Media3
+        // session rather than the MediaSessionCompat).
+        //
+        // We do NOT execute on ExoPlayer directly here. Every transport command
+        // is routed to Rust via nativeOnMediaCommand, which is the single decision
+        // point: in local mode Rust drives ExoPlayer, in remote (cast) mode Rust
+        // forwards to the remote Jellyfin session. Executing on ExoPlayer here too
+        // would double-handle local commands and incorrectly drive the local
+        // player while casting.
         wrappedPlayer = object : ForwardingPlayer(exoPlayer) {
             override fun play() {
-                // Execute immediately for instant lockscreen response
-                super.play()
-                // Then notify Rust for state management
                 nativeOnMediaCommand("play")
             }
 
             override fun pause() {
-                // Execute immediately for instant lockscreen response
-                super.pause()
-                // Then notify Rust for state management
                 nativeOnMediaCommand("pause")
             }
 
             override fun seekToNext() {
-                // Execute immediately for instant lockscreen response
-                super.seekToNext()
-                // Then notify Rust for queue management
                 nativeOnMediaCommand("next")
             }
 
             override fun seekToPrevious() {
-                // Execute immediately for instant lockscreen response
-                super.seekToPrevious()
-                // Then notify Rust for queue management
                 nativeOnMediaCommand("previous")
             }
 
             override fun seekTo(positionMs: Long) {
-                // Execute immediately for instant lockscreen response
-                super.seekTo(positionMs)
-                // Then notify Rust of seek
                 val positionSeconds = positionMs / 1000.0
                 nativeOnMediaCommand("seek:$positionSeconds")
             }
 
             override fun stop() {
-                // Execute immediately for instant lockscreen response
-                super.stop()
-                // Then notify Rust for state management
                 nativeOnMediaCommand("stop")
             }
         }
@@ -160,36 +151,44 @@ class JellyTauPlaybackService : MediaSessionService() {
             )
             isActive = true
 
-            // Set callback to handle lock screen button presses
+            // Set callback to handle lock screen button presses.
+            //
+            // All transport commands are routed through Rust via nativeOnMediaCommand
+            // rather than directly to ExoPlayer. Rust is the single decision point:
+            // in local mode it drives ExoPlayer, in remote (cast) mode it forwards
+            // the command to the remote Jellyfin session. This keeps the lockscreen
+            // working identically for both, and avoids the ExoPlayer-only behaviour
+            // that left remote playback uncontrollable from the lockscreen.
             setCallback(object : MediaSessionCompat.Callback() {
                 override fun onPlay() {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Play pressed")
-                    wrappedPlayer?.play()
+                    nativeOnMediaCommand("play")
                 }
 
                 override fun onPause() {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Pause pressed")
-                    wrappedPlayer?.pause()
+                    nativeOnMediaCommand("pause")
                 }
 
                 override fun onSkipToNext() {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Next pressed")
-                    wrappedPlayer?.seekToNext()
+                    nativeOnMediaCommand("next")
                 }
 
                 override fun onSkipToPrevious() {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Previous pressed")
-                    wrappedPlayer?.seekToPrevious()
+                    nativeOnMediaCommand("previous")
                 }
 
                 override fun onStop() {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Stop pressed")
-                    wrappedPlayer?.stop()
+                    nativeOnMediaCommand("stop")
                 }
 
                 override fun onSeekTo(position: Long) {
                     android.util.Log.d("JellyTauPlaybackService", "Lock screen: Seek to $position")
-                    wrappedPlayer?.seekTo(position)
+                    val positionSeconds = position / 1000.0
+                    nativeOnMediaCommand("seek:$positionSeconds")
                 }
             })
         }
@@ -253,9 +252,19 @@ class JellyTauPlaybackService : MediaSessionService() {
             .build()
     }
 
+    // Last-known metadata/state, retained so lightweight position ticks can
+    // rebuild a correct PlaybackState without re-sending the (heavier) metadata
+    // and notification. Kept in sync by updateMediaMetadata().
+    private var lastTitle: String = ""
+    private var lastArtist: String = ""
+    private var lastIsPlaying: Boolean = false
+
     /**
-     * Update the MediaSession metadata and playback state.
-     * This updates both the MediaSession and the notification.
+     * Update the MediaSession metadata and playback state, plus the notification.
+     *
+     * Call this when the track or play/pause state changes. For frequent position
+     * updates during playback, use [updatePlaybackPosition] instead, which is much
+     * cheaper (no metadata rebuild, no notification rebuild).
      */
     fun updateMediaMetadata(
         title: String,
@@ -267,6 +276,10 @@ class JellyTauPlaybackService : MediaSessionService() {
     ) {
         val session = mediaSessionCompat ?: return
 
+        lastTitle = title
+        lastArtist = artist
+        lastIsPlaying = isPlaying
+
         // Update MediaSession metadata
         val metadataBuilder = android.support.v4.media.MediaMetadataCompat.Builder()
             .putString(android.support.v4.media.MediaMetadataCompat.METADATA_KEY_TITLE, title)
@@ -280,7 +293,42 @@ class JellyTauPlaybackService : MediaSessionService() {
         session.setMetadata(metadataBuilder.build())
 
         // Update MediaSession playback state
-        val stateBuilder = PlaybackStateCompat.Builder()
+        session.setPlaybackState(buildPlaybackState(isPlaying, position))
+
+        // Update the notification
+        updateNotification(title, artist, isPlaying)
+    }
+
+    /**
+     * Update only the playback position (and play/pause state) on the MediaSession.
+     *
+     * This is the cheap path used for the periodic (250ms) position ticks: it
+     * refreshes the lockscreen scrubber without rebuilding metadata or the
+     * notification. Without this, the lockscreen scrubber freezes at the position
+     * from the last play/pause and drifts out of sync with actual playback.
+     *
+     * @param position Position in milliseconds
+     * @param isPlaying Whether playback is currently active
+     */
+    fun updatePlaybackPosition(position: Long, isPlaying: Boolean) {
+        val session = mediaSessionCompat ?: return
+        val notificationStateChanged = isPlaying != lastIsPlaying
+        lastIsPlaying = isPlaying
+        session.setPlaybackState(buildPlaybackState(isPlaying, position))
+        // Only rebuild the notification when the play/pause icon actually flips.
+        if (notificationStateChanged) {
+            updateNotification(lastTitle, lastArtist, isPlaying)
+        }
+    }
+
+    /**
+     * Build a PlaybackStateCompat with the standard transport actions.
+     *
+     * 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.
+     */
+    private fun buildPlaybackState(isPlaying: Boolean, position: Long): PlaybackStateCompat {
+        return PlaybackStateCompat.Builder()
             .setActions(
                 PlaybackStateCompat.ACTION_PLAY or
                 PlaybackStateCompat.ACTION_PAUSE or
@@ -292,13 +340,9 @@ class JellyTauPlaybackService : MediaSessionService() {
             .setState(
                 if (isPlaying) PlaybackStateCompat.STATE_PLAYING else PlaybackStateCompat.STATE_PAUSED,
                 position,
-                1.0f
+                if (isPlaying) 1.0f else 0.0f
             )
-
-        session.setPlaybackState(stateBuilder.build())
-
-        // Update the notification
-        updateNotification(title, artist, isPlaying)
+            .build()
     }
 
     /**

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

@@ -161,6 +161,9 @@ class JellyTauPlayer(private val appContext: Context) {
     /** SurfaceView for video playback */
     private var surfaceView: SurfaceView? = null
     private var surfaceHolder: SurfaceHolder? = null
+    /** Last reported video frame size, used to fit the surface to the screen preserving aspect ratio */
+    private var videoWidth: Int = 0
+    private var videoHeight: Int = 0
     private var currentMediaType: MediaType = MediaType.AUDIO
     private var currentActivity: java.lang.ref.WeakReference<android.app.Activity>? = null
 
@@ -262,7 +265,11 @@ class JellyTauPlayer(private val appContext: Context) {
             }
 
             override fun onVideoSizeChanged(videoSize: androidx.media3.common.VideoSize) {
-                android.util.Log.d("JellyTauPlayer", "▶ Video size: ${videoSize.width}x${videoSize.height}")
+                android.util.Log.d("JellyTauPlayer", "▶ Video size: ${videoSize.width}x${videoSize.height} par=${videoSize.pixelWidthHeightRatio}")
+                // Apply pixel aspect ratio so anamorphic content isn't distorted
+                videoWidth = (videoSize.width * videoSize.pixelWidthHeightRatio).toInt()
+                videoHeight = videoSize.height
+                fitSurfaceToScreen()
             }
 
             override fun onRenderedFirstFrame() {
@@ -760,10 +767,16 @@ class JellyTauPlayer(private val appContext: Context) {
             android.util.Log.d("JellyTauPlayer", "Started position updates coroutine")
             while (isActive) {
                 if (exoPlayer.isPlaying) {
-                    val position = exoPlayer.currentPosition / 1000.0
+                    val positionMs = exoPlayer.currentPosition.coerceAtLeast(0)
+                    val position = positionMs / 1000.0
                     val duration = if (exoPlayer.duration > 0) exoPlayer.duration / 1000.0 else 0.0
                     android.util.Log.v("JellyTauPlayer", "Position update: $position / $duration")
                     nativeOnPositionUpdate(position, duration)
+
+                    // Keep the lockscreen scrubber live. Without this the
+                    // MediaSession position only refreshes on play/pause, so the
+                    // scrubber freezes mid-track and drifts out of sync.
+                    JellyTauPlaybackService.getInstance()?.updatePlaybackPosition(positionMs, true)
                 }
                 delay(POSITION_UPDATE_INTERVAL_MS)
             }
@@ -867,17 +880,62 @@ class JellyTauPlayer(private val appContext: Context) {
 
     /**
      * Resize the video surface (for orientation changes).
+     *
+     * Re-fits the surface to the screen preserving the video's aspect ratio so
+     * nothing is cropped when the device rotates.
      */
     fun resizeSurface(width: Int, height: Int) {
+        fitSurfaceToScreen()
+    }
+
+    /**
+     * Size the video SurfaceView so the video fits entirely inside its parent
+     * (the full-screen content view) while preserving aspect ratio (letterbox/
+     * pillarbox). A raw SurfaceView with MATCH_PARENT otherwise stretches the
+     * video to the surface bounds, which crops the bottom on rotation.
+     */
+    fun fitSurfaceToScreen() {
         mainHandler.post {
-            surfaceView?.let { view ->
-                view.layoutParams = view.layoutParams.apply {
-                    this.width = width
-                    this.height = height
-                }
-                view.requestLayout()
-                android.util.Log.d("JellyTauPlayer", "Video surface resized to ${width}x${height}")
+            val view = surfaceView ?: return@post
+            val parent = view.parent as? ViewGroup
+            // Available area: prefer the parent's measured size, fall back to the screen.
+            val availW = parent?.width?.takeIf { it > 0 }
+                ?: appContext.resources.displayMetrics.widthPixels
+            val availH = parent?.height?.takeIf { it > 0 }
+                ?: appContext.resources.displayMetrics.heightPixels
+
+            if (videoWidth <= 0 || videoHeight <= 0 || availW <= 0 || availH <= 0) {
+                return@post
             }
+
+            val videoAspect = videoWidth.toFloat() / videoHeight.toFloat()
+            val viewAspect = availW.toFloat() / availH.toFloat()
+
+            val targetW: Int
+            val targetH: Int
+            if (videoAspect > viewAspect) {
+                // Video is wider than the screen → fit width, letterbox top/bottom
+                targetW = availW
+                targetH = (availW / videoAspect).toInt()
+            } else {
+                // Video is taller than the screen → fit height, pillarbox sides
+                targetH = availH
+                targetW = (availH * videoAspect).toInt()
+            }
+
+            val lp = view.layoutParams
+            // FrameLayout child: center the fitted surface within the full-screen parent.
+            if (lp is FrameLayout.LayoutParams) {
+                lp.gravity = android.view.Gravity.CENTER
+            }
+            lp.width = targetW
+            lp.height = targetH
+            view.layoutParams = lp
+            view.requestLayout()
+            android.util.Log.d(
+                "JellyTauPlayer",
+                "Video surface fitted to ${targetW}x${targetH} (video ${videoWidth}x${videoHeight}, avail ${availW}x${availH})"
+            )
         }
     }
 

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

@@ -1087,7 +1087,7 @@ pub async fn enqueue_video_downloads(
 /// (FIFO within a priority), registers each, flips it to `downloading`, and
 /// spawns a worker. Each spawned worker calls this again on completion/failure,
 /// so the queue drains itself without any frontend involvement.
-async fn pump_download_queue(
+pub(crate) async fn pump_download_queue(
     app: tauri::AppHandle,
     db_service: Arc<crate::storage::db_service::RusqliteService>,
     active_downloads: Arc<Mutex<std::collections::HashSet<i64>>>,

src-tauri/src/commands/playback_mode.rs

@@ -51,6 +51,22 @@ pub async fn playback_mode_transfer_to_remote(
     manager.0.transfer_to_remote(session_id, position).await
 }
 
+/// Set the transferring flag on the playback mode manager.
+///
+/// Used by the frontend remote->local flow to mark the whole two-step sequence
+/// as a transfer, so `player_play_tracks` starts LOCAL playback instead of
+/// casting back to the remote session it's leaving. Always pair `true` with a
+/// later `false` (including on error) so the flag can't stick.
+#[tauri::command]
+#[specta::specta]
+pub async fn playback_mode_set_transferring(
+    manager: State<'_, PlaybackModeManagerWrapper>,
+    transferring: bool,
+) -> Result<(), String> {
+    manager.0.set_transferring(transferring);
+    Ok(())
+}
+
 /// Transfer playback from remote session back to local device
 ///
 /// Parameters:

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

@@ -378,6 +378,65 @@ pub(super) async fn check_for_local_download(
     }
 }
 
+/// Re-point queued streaming items at completed local downloads.
+///
+/// Sources are resolved once when the queue is built, so downloads that finish
+/// while it plays (preloaded upcoming tracks) — or that existed before the
+/// connection dropped — would otherwise keep streaming. Called before advancing
+/// so the next track always prefers the on-disk copy.
+///
+/// Returns the number of items switched to a local source.
+pub(super) async fn refresh_queue_local_sources(
+    controller: &PlayerController,
+    db: &DatabaseWrapper,
+) -> Result<usize, String> {
+    // Collect remote item IDs first; the queue lock must not be held across awaits.
+    let remote_ids: Vec<String> = {
+        let queue = controller.queue();
+        let queue_lock = queue.lock().map_err(|e| e.to_string())?;
+        queue_lock
+            .items()
+            .iter()
+            .filter_map(|item| match &item.source {
+                MediaSource::Remote { jellyfin_item_id, .. } => Some(jellyfin_item_id.clone()),
+                _ => None,
+            })
+            .collect()
+    };
+
+    if remote_ids.is_empty() {
+        return Ok(0);
+    }
+
+    let mut local_paths: Vec<(String, String)> = Vec::new();
+    for id in remote_ids {
+        if let Some(path) = check_for_local_download(db, &id).await? {
+            local_paths.push((id, path));
+        }
+    }
+
+    if local_paths.is_empty() {
+        return Ok(0);
+    }
+
+    let queue = controller.queue();
+    let mut queue_lock = queue.lock().map_err(|e| e.to_string())?;
+    let mut switched = 0;
+    for item in queue_lock.items_mut() {
+        if let MediaSource::Remote { jellyfin_item_id, .. } = &item.source {
+            if let Some((id, path)) = local_paths.iter().find(|(id, _)| id == jellyfin_item_id) {
+                info!("[Player] Switching queued track {} to local download: {}", id, path);
+                item.source = MediaSource::Local {
+                    file_path: PathBuf::from(path),
+                    jellyfin_item_id: Some(id.clone()),
+                };
+                switched += 1;
+            }
+        }
+    }
+    Ok(switched)
+}
+
 /// Play a single media item (audio or video)
 ///
 /// Accepts a PlayItemRequest with all optional fields properly defaulted.
@@ -679,6 +738,7 @@ pub async fn player_next(
     player: State<'_, PlayerStateWrapper>,
     session: State<'_, MediaSessionManagerWrapper>,
     playback_mode: State<'_, super::playback_mode::PlaybackModeManagerWrapper>,
+    db: State<'_, DatabaseWrapper>,
 ) -> Result<PlayerStatus, String> {
     debug!("[player_next] Command called from frontend");
 
@@ -697,6 +757,10 @@ pub async fn player_next(
     } else {
         // Local playback
         let controller = player.0.lock().await;
+        // Prefer downloads that completed since the queue was built
+        if let Err(e) = refresh_queue_local_sources(&controller, &db).await {
+            warn!("[player_next] Failed to refresh local sources: {}", e);
+        }
         controller.next().map_err(|e| e.to_string())?;
         controller.emit_queue_changed();
 
@@ -732,6 +796,7 @@ pub async fn player_previous(
     player: State<'_, PlayerStateWrapper>,
     session: State<'_, MediaSessionManagerWrapper>,
     playback_mode: State<'_, super::playback_mode::PlaybackModeManagerWrapper>,
+    db: State<'_, DatabaseWrapper>,
 ) -> Result<PlayerStatus, String> {
     // Check if we're in remote mode
     let mode = playback_mode.0.get_mode();
@@ -748,6 +813,10 @@ pub async fn player_previous(
     } else {
         // Local playback
         let controller = player.0.lock().await;
+        // Prefer downloads that completed since the queue was built
+        if let Err(e) = refresh_queue_local_sources(&controller, &db).await {
+            warn!("[player_previous] Failed to refresh local sources: {}", e);
+        }
         controller.previous().map_err(|e| e.to_string())?;
         controller.emit_queue_changed();
 
@@ -1669,12 +1738,23 @@ pub async fn player_preload_upcoming(
     player: State<'_, PlayerStateWrapper>,
     db: State<'_, DatabaseWrapper>,
     smart_cache: State<'_, SmartCacheWrapper>,
+    download_manager: State<'_, crate::commands::download::DownloadManagerWrapper>,
+    app: tauri::AppHandle,
     user_id: String,
     _download_base_path: String,
 ) -> Result<PreloadResult, String> {
-    let db_service = {
+    // The pump only starts rows that carry both a stream URL and a target dir,
+    // so resolve the same storage root the user-initiated download paths use
+    // (storage_get_path = the database's parent directory).
+    let (db_service, target_dir) = {
         let database = db.0.lock().map_err(|e| e.to_string())?;
-        Arc::new(database.service())
+        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)
     };
 
     // Get cache settings
@@ -1712,10 +1792,12 @@ pub async fn player_preload_upcoming(
 
     // Process each upcoming item
     for item in upcoming_items {
-        // Only process items with Remote source (not already local)
-        let jellyfin_id = match &item.source {
-            MediaSource::Remote { jellyfin_item_id, .. } => {
-                jellyfin_item_id.clone()
+        // Only process items with Remote source (not already local). The
+        // source already carries the resolved stream URL — reuse it so the
+        // pump can start the download without any extra resolution step.
+        let (jellyfin_id, stream_url) = match &item.source {
+            MediaSource::Remote { jellyfin_item_id, stream_url } => {
+                (jellyfin_item_id.clone(), stream_url.clone())
             }
             MediaSource::Local { .. } => {
                 already_downloaded += 1;
@@ -1727,9 +1809,13 @@ pub async fn player_preload_upcoming(
             }
         };
 
-        // Check if already downloaded
+        // Check if already downloaded or actively in flight. Stale pending rows
+        // without a stream URL are NOT skipped here — the upsert below heals
+        // them so the pump can finally start them.
         let query = Query::with_params(
-            "SELECT file_path FROM downloads WHERE item_id = ? AND user_id = ? AND status IN ('completed', 'downloading', 'pending') LIMIT 1",
+            "SELECT file_path FROM downloads WHERE item_id = ? AND user_id = ?
+             AND (status IN ('completed', 'downloading')
+                  OR (status = 'pending' AND stream_url IS NOT NULL)) LIMIT 1",
             vec![
                 QueryParam::String(jellyfin_id.clone()),
                 QueryParam::String(user_id.clone()),
@@ -1746,14 +1832,29 @@ pub async fn player_preload_upcoming(
             continue;
         }
 
-        // Queue for download with low priority (preload priority = -100)
-        let file_path = format!("{}/{}.mp3", sanitize_filename(&item.album.clone().unwrap_or_default()), sanitize_filename(&item.title));
+        // Queue for download with low priority (preload priority = -100) so
+        // user-initiated downloads always win a pump slot first.
+        let album_dir = item
+            .album
+            .as_deref()
+            .filter(|a| !a.is_empty())
+            .unwrap_or("Unknown Album");
+        let file_path = format!(
+            "downloads/{}/{}.mp3",
+            sanitize_filename(album_dir),
+            sanitize_filename(&item.title)
+        );
 
-        // Insert download record with preload priority
+        // Insert with the stream URL + target dir the pump needs to start it.
+        // On conflict, heal pre-existing rows that were queued without a URL
+        // (they could never start) instead of leaving them stuck.
         let insert_query = Query::with_params(
-            "INSERT INTO downloads (item_id, user_id, file_path, status, priority, queued_at, item_name, artist_name, album_name)
-             VALUES (?, ?, ?, 'pending', -100, CURRENT_TIMESTAMP, ?, ?, ?)
-             ON CONFLICT(item_id, user_id) DO NOTHING",
+            "INSERT INTO downloads (item_id, user_id, file_path, status, priority, queued_at, item_name, artist_name, album_name, download_source, media_type, stream_url, target_dir)
+             VALUES (?, ?, ?, 'pending', -100, CURRENT_TIMESTAMP, ?, ?, ?, 'auto', 'audio', ?, ?)
+             ON CONFLICT(item_id, user_id) DO UPDATE SET
+                 stream_url = excluded.stream_url,
+                 target_dir = excluded.target_dir
+             WHERE downloads.status = 'pending' AND downloads.stream_url IS NULL",
             vec![
                 QueryParam::String(jellyfin_id),
                 QueryParam::String(user_id.clone()),
@@ -1761,6 +1862,8 @@ pub async fn player_preload_upcoming(
                 QueryParam::String(item.title.clone()),
                 item.artist.clone().map(QueryParam::String).unwrap_or(QueryParam::Null),
                 item.album.clone().map(QueryParam::String).unwrap_or(QueryParam::Null),
+                QueryParam::String(stream_url),
+                QueryParam::String(target_dir.clone()),
             ],
         );
 
@@ -1780,6 +1883,16 @@ pub async fn player_preload_upcoming(
         }
     }
 
+    // Kick the pump so the queued preloads actually start; without this they'd
+    // only begin once some other download activity pumps the queue.
+    if queued_count > 0 {
+        let active_downloads = {
+            let manager = download_manager.0.lock().map_err(|e| e.to_string())?;
+            manager.get_active_downloads()
+        };
+        crate::commands::download::pump_download_queue(app, db_service, active_downloads).await;
+    }
+
     info!("[Preload] Result: queued={}, already_downloaded={}, skipped={}", queued_count, already_downloaded, skipped);
 
     Ok(PreloadResult {
@@ -1826,9 +1939,10 @@ pub async fn player_get_cache_config(
 #[specta::specta]
 pub async fn player_configure_jellyfin(
     player: State<'_, PlayerStateWrapper>,
+    db: State<'_, DatabaseWrapper>,
     server_url: String,
     access_token: String,
-    _user_id: String,
+    user_id: String,
     device_id: String,
 ) -> Result<(), String> {
     log::info!("[PlayerCommand] Configuring Jellyfin client for playback reporting");
@@ -1839,12 +1953,31 @@ pub async fn player_configure_jellyfin(
         device_id,
     };
 
-    let client = JellyfinClient::new(config)?;
+    // Legacy client (used for remote session control / casting).
+    let client = JellyfinClient::new(config.clone())?;
+
+    // Build the PlaybackReporter the player and backends (MPV + ExoPlayer)
+    // actually report through. Without this, Start/Progress/Stopped never reach
+    // Jellyfin, so playback position never syncs and you can't resume on another
+    // device. The reporter shares the player controller's Arc, so populating it
+    // here lights up reporting on both desktop and Android, on every auth path
+    // that configures the player (login / restore / reauth).
+    let db_service = {
+        let database = db.0.lock().map_err(|e| e.to_string())?;
+        Arc::new(database.service())
+    };
+    let reporter_client = JellyfinClient::new(config)?;
+    let reporter = crate::playback_reporting::PlaybackReporter::new(
+        db_service,
+        Arc::new(TokioMutex::new(Some(reporter_client))),
+        user_id,
+    );
 
     let controller = player.0.lock().await;
     controller.set_jellyfin_client(Some(client));
+    controller.set_playback_reporter(Some(reporter)).await;
 
-    log::info!("[PlayerCommand] Jellyfin client configured successfully");
+    log::info!("[PlayerCommand] Jellyfin client and playback reporter configured successfully");
     Ok(())
 }
 
@@ -1858,13 +1991,105 @@ pub async fn player_disable_jellyfin(
 
     let controller = player.0.lock().await;
     controller.set_jellyfin_client(None);
+    controller.set_playback_reporter(None).await;
 
-    log::info!("[PlayerCommand] Jellyfin client disabled");
+    log::info!("[PlayerCommand] Jellyfin client and playback reporter disabled");
     Ok(())
 }
 
 #[cfg(test)]
 mod tests {
+    /// Queue items enqueued as Remote must flip to Local once a completed
+    /// download exists on disk — this is what makes preloaded tracks (and
+    /// offline playback after a connection drop) actually use the cache.
+    #[tokio::test]
+    async fn test_refresh_queue_local_sources_switches_completed_downloads() {
+        use super::{refresh_queue_local_sources, DatabaseWrapper};
+        use crate::player::{MediaItem, MediaSource, MediaType, PlayerController};
+        use crate::storage::Database;
+        use std::sync::Mutex;
+
+        // A real file on disk for the completed download; a missing file for
+        // the second entry to prove nonexistent files are not switched.
+        let dir = std::env::temp_dir().join("jellytau-test-refresh-sources");
+        std::fs::create_dir_all(&dir).unwrap();
+        let existing = dir.join("track-a.mp3");
+        std::fs::write(&existing, b"audio").unwrap();
+        let missing = dir.join("track-b-missing.mp3");
+        let _ = std::fs::remove_file(&missing);
+
+        let database = Database::open_in_memory().unwrap();
+        {
+            let conn = database.connection();
+            let conn = conn.lock().unwrap();
+            conn.execute_batch(&format!(
+                r#"
+                INSERT INTO servers (id, name, url) VALUES ('srv', 'Test', 'http://test');
+                INSERT INTO users (id, server_id, username) VALUES ('user1', 'srv', 'tester');
+                INSERT INTO downloads (item_id, user_id, file_path, status)
+                    VALUES ('track-a', 'user1', '{}', 'completed');
+                INSERT INTO downloads (item_id, user_id, file_path, status)
+                    VALUES ('track-b', 'user1', '{}', 'completed');
+                "#,
+                existing.display(),
+                missing.display()
+            ))
+            .unwrap();
+        }
+        let db = DatabaseWrapper(Mutex::new(database));
+
+        let make_item = |id: &str| MediaItem {
+            id: id.to_string(),
+            title: id.to_string(),
+            name: None,
+            artist: None,
+            album: None,
+            album_name: None,
+            album_id: None,
+            artist_items: None,
+            artists: None,
+            primary_image_tag: None,
+            item_type: None,
+            playlist_id: None,
+            duration: None,
+            artwork_url: None,
+            media_type: MediaType::Audio,
+            source: MediaSource::Remote {
+                stream_url: format!("http://test/Audio/{}/stream", id),
+                jellyfin_item_id: id.to_string(),
+            },
+            video_codec: None,
+            needs_transcoding: false,
+            video_width: None,
+            video_height: None,
+            subtitles: vec![],
+            series_id: None,
+            server_id: None,
+        };
+
+        let controller = PlayerController::default();
+        controller
+            .set_queue(vec![make_item("track-a"), make_item("track-b")], 0)
+            .unwrap();
+
+        let switched = refresh_queue_local_sources(&controller, &db).await.unwrap();
+        assert_eq!(switched, 1, "only the download whose file exists switches");
+
+        let queue = controller.queue();
+        let queue_lock = queue.lock().unwrap();
+        match &queue_lock.items()[0].source {
+            MediaSource::Local { file_path, jellyfin_item_id } => {
+                assert_eq!(file_path, &existing);
+                assert_eq!(jellyfin_item_id.as_deref(), Some("track-a"));
+            }
+            other => panic!("track-a should be local, got {:?}", other),
+        }
+        assert!(
+            matches!(queue_lock.items()[1].source, MediaSource::Remote { .. }),
+            "track-b's file is missing, it must stay remote"
+        );
+    }
+
     /// Test track index finding in album
     /// This reproduces the bug where clicking songs 1-5 always played song 13
     #[test]

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

@@ -347,10 +347,16 @@ pub async fn player_add_tracks_by_ids(
 #[specta::specta]
 pub async fn player_skip_to(
     player: State<'_, PlayerStateWrapper>,
+    db: State<'_, DatabaseWrapper>,
     index: usize,
 ) -> Result<PlayerStatus, String> {
     let controller = player.0.lock().await;
 
+    // Prefer downloads that completed since the queue was built
+    if let Err(e) = super::refresh_queue_local_sources(&controller, &db).await {
+        log::warn!("[player_skip_to] Failed to refresh local sources: {}", e);
+    }
+
     // Skip to the index and get the item to play
     let item = {
         let queue = controller.queue();

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

@@ -6,6 +6,7 @@
 use tauri::State;
 
 use super::PlayerStateWrapper;
+use crate::jellyfin::client::LmsSyncGroup;
 
 /// Play items on a remote Jellyfin session (casting)
 #[tauri::command]
@@ -129,3 +130,92 @@ pub async fn remote_session_toggle_mute(
         Err("Jellyfin client not configured".to_string())
     }
 }
+
+// --- JellyLMS multi-room sync groups (fuse / unfuse LMS zones) --------------
+//
+// The frontend addresses LMS players by MAC address, which it derives from a
+// session's device id (`lms-{mac}`). These commands forward to the JellyLMS
+// plugin REST API via the configured JellyfinClient.
+
+/// List current LMS sync groups.
+#[tauri::command]
+#[specta::specta]
+pub async fn lms_get_sync_groups(
+    player: State<'_, PlayerStateWrapper>,
+) -> Result<Vec<LmsSyncGroup>, String> {
+    let client_opt = {
+        let controller = player.0.lock().await;
+        controller.jellyfin_client().lock().map_err(|e| e.to_string())?.clone()
+    };
+
+    if let Some(client) = client_opt {
+        client.lms_get_sync_groups().await
+    } else {
+        Err("Jellyfin client not configured".to_string())
+    }
+}
+
+/// Fuse LMS zones into a sync group. `master_mac` keeps playing and the
+/// `slave_macs` zones join it in sync.
+#[tauri::command]
+#[specta::specta]
+pub async fn lms_create_sync_group(
+    player: State<'_, PlayerStateWrapper>,
+    master_mac: String,
+    slave_macs: Vec<String>,
+) -> Result<(), String> {
+    log::info!("[LmsSync] Fusing zones: master={}, slaves={:?}", master_mac, slave_macs);
+
+    let client_opt = {
+        let controller = player.0.lock().await;
+        controller.jellyfin_client().lock().map_err(|e| e.to_string())?.clone()
+    };
+
+    if let Some(client) = client_opt {
+        client.lms_create_sync_group(&master_mac, slave_macs).await
+    } else {
+        Err("Jellyfin client not configured".to_string())
+    }
+}
+
+/// Remove a single LMS zone from its sync group (decouple one player).
+#[tauri::command]
+#[specta::specta]
+pub async fn lms_unsync_player(
+    player: State<'_, PlayerStateWrapper>,
+    mac: String,
+) -> Result<(), String> {
+    log::info!("[LmsSync] Decoupling zone {}", mac);
+
+    let client_opt = {
+        let controller = player.0.lock().await;
+        controller.jellyfin_client().lock().map_err(|e| e.to_string())?.clone()
+    };
+
+    if let Some(client) = client_opt {
+        client.lms_unsync_player(&mac).await
+    } else {
+        Err("Jellyfin client not configured".to_string())
+    }
+}
+
+/// Dissolve an entire LMS sync group, identified by its master's MAC.
+#[tauri::command]
+#[specta::specta]
+pub async fn lms_dissolve_sync_group(
+    player: State<'_, PlayerStateWrapper>,
+    master_mac: String,
+) -> Result<(), String> {
+    log::info!("[LmsSync] Dissolving group with master {}", master_mac);
+
+    let client_opt = {
+        let controller = player.0.lock().await;
+        controller.jellyfin_client().lock().map_err(|e| e.to_string())?.clone()
+    };
+
+    if let Some(client) = client_opt {
+        client.lms_dissolve_sync_group(&master_mac).await
+    } else {
+        Err("Jellyfin client not configured".to_string())
+    }
+}

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

@@ -142,6 +142,7 @@ pub async fn player_play_next_episode(
 pub async fn player_on_playback_ended(
     player: State<'_, PlayerStateWrapper>,
     repository_manager: State<'_, crate::commands::repository::RepositoryManagerWrapper>,
+    db: State<'_, DatabaseWrapper>,
     item_id: Option<String>,
     repository_handle: Option<String>,
 ) -> Result<(), String> {
@@ -174,8 +175,14 @@ pub async fn player_on_playback_ended(
     // Handle the decision
     match decision {
         AutoplayDecision::Stop => {
-            log::debug!("[Autoplay] Decision: Stop playback");
+            log::info!("[Autoplay] Decision: Stop playback");
             let controller = controller_arc.lock().await;
+            // Clear the queue so the frontend's currentQueueItem becomes null and
+            // the mini player hides. Without this, the queue still holds the last
+            // track and the bar would linger (the frontend keeps the bar visible
+            // through transient idle blips as long as a queue item exists).
+            controller.clear_queue();
+            controller.emit_queue_changed();
             if let Some(emitter) = controller.event_emitter() {
                 // Emit StateChanged to idle to clear the current media from mini player
                 // Note: Do NOT emit PlaybackEnded here - it would cause an infinite loop
@@ -187,9 +194,14 @@ pub async fn player_on_playback_ended(
             }
         }
         AutoplayDecision::AdvanceToNext => {
-            log::debug!("[Autoplay] Decision: Advance to next track");
+            log::info!("[Autoplay] Decision: Advance to next track");
             // Advance to next track in queue
             let controller = controller_arc.lock().await;
+            // Prefer downloads that completed since the queue was built (e.g.
+            // preloaded upcoming tracks) over continuing to stream.
+            if let Err(e) = super::refresh_queue_local_sources(&controller, &db).await {
+                log::warn!("[Autoplay] Failed to refresh local sources: {}", e);
+            }
             if let Err(e) = controller.next() {
                 log::error!("[Autoplay] Failed to advance to next track: {}", e);
                 // Emit PlaybackEnded event on error
@@ -235,3 +247,51 @@ pub async fn player_on_playback_ended(
 
     Ok(())
 }
+
+// ===== HTML5 video state-report commands =====
+//
+// On platforms where video renders in the webview (Linux WebKitGTK HTML5
+// <video>), the real player lives outside the native backend, so the frontend
+// HTML5 adapter reports DOM events back through these commands. The controller
+// re-emits them through the same PlayerStatusEvent pipeline the native backends
+// use, keeping the Rust controller the single source of truth and the frontend
+// player store fed from one place (playerEvents.ts) in both modes.
+
+/// Report an HTML5 <video> state change (playing/paused/loading/stopped/idle).
+#[tauri::command]
+#[specta::specta]
+pub async fn player_report_state(
+    player: State<'_, PlayerStateWrapper>,
+    state: String,
+    media_id: Option<String>,
+) -> Result<(), String> {
+    let controller = player.0.lock().await;
+    controller.report_html5_state(state, media_id);
+    Ok(())
+}
+
+/// Report an HTML5 <video> position tick (seconds). The adapter should throttle
+/// these to roughly match the native backends' ~250ms cadence.
+#[tauri::command]
+#[specta::specta]
+pub async fn player_report_position(
+    player: State<'_, PlayerStateWrapper>,
+    position: f64,
+    duration: f64,
+) -> Result<(), String> {
+    let controller = player.0.lock().await;
+    controller.report_html5_position(position, duration);
+    Ok(())
+}
+
+/// Report that the HTML5 <video> finished loading and knows its duration.
+#[tauri::command]
+#[specta::specta]
+pub async fn player_report_media_loaded(
+    player: State<'_, PlayerStateWrapper>,
+    duration: f64,
+) -> Result<(), String> {
+    let controller = player.0.lock().await;
+    controller.report_html5_media_loaded(duration);
+    Ok(())
+}

src-tauri/src/commands/repository.rs

@@ -52,6 +52,7 @@ pub struct RepositoryManagerWrapper(pub RepositoryManager);
 #[specta::specta]
 pub async fn repository_create(
     manager: State<'_, RepositoryManagerWrapper>,
+    player: State<'_, crate::commands::player::PlayerStateWrapper>,
     db: State<'_, crate::commands::storage::DatabaseWrapper>,
     connectivity: State<'_, crate::commands::connectivity::ConnectivityMonitorWrapper>,
     server_url: String,
@@ -115,6 +116,14 @@ pub async fn repository_create(
     manager.0.create(handle.clone(), hybrid);
     info!("[REPO] Repository stored successfully");
 
+    // Give the player controller a repository for next-episode lookups. The
+    // Android playback-ended callback has no repository handle, so without
+    // this the episode autoplay countdown never triggers there.
+    if let Some(repo) = manager.0.get(&handle) {
+        let controller = player.0.lock().await;
+        controller.set_repository(repo);
+    }
+
     Ok(handle)
 }
 
@@ -179,6 +188,23 @@ pub async fn repository_get_item(
         .map_err(|e| format!("{:?}", e))
 }
 
+/// Query the optional JRay plugin for the actors on screen at time `t`
+/// (seconds) in an item. Returns an empty list when JRay isn't installed or
+/// has no data for the item, so the caller can render nothing without error.
+#[tauri::command]
+#[specta::specta]
+pub async fn repository_jray_actors_at(
+    manager: State<'_, RepositoryManagerWrapper>,
+    handle: String,
+    item_id: String,
+    t: f64,
+) -> Result<Vec<crate::repository::JRayActor>, String> {
+    let repo = manager.0.get(&handle).ok_or("Repository not found")?;
+    repo.as_ref().get_jray_actors(&item_id, t)
+        .await
+        .map_err(|e| format!("{:?}", e))
+}
+
 /// Get latest items in a library
 #[tauri::command]
 #[specta::specta]
@@ -410,6 +436,49 @@ pub async fn repository_get_audio_stream_url(
         .map_err(|e| format!("{:?}", e))
 }
 
+/// Get Live TV channels (broadcast / IPTV) for browsing
+#[tauri::command]
+#[specta::specta]
+pub async fn repository_get_live_tv_channels(
+    manager: State<'_, RepositoryManagerWrapper>,
+    handle: String,
+) -> Result<Vec<MediaItem>, String> {
+    let repo = manager.0.get(&handle).ok_or("Repository not found")?;
+    repo.as_ref()
+        .get_live_tv_channels()
+        .await
+        .map_err(|e| format!("{:?}", e))
+}
+
+/// Get the root list of plugin "Channels"
+#[tauri::command]
+#[specta::specta]
+pub async fn repository_get_channels(
+    manager: State<'_, RepositoryManagerWrapper>,
+    handle: String,
+) -> Result<SearchResult, String> {
+    let repo = manager.0.get(&handle).ok_or("Repository not found")?;
+    repo.as_ref()
+        .get_channels()
+        .await
+        .map_err(|e| format!("{:?}", e))
+}
+
+/// Open a live stream for a Live TV channel / live item
+#[tauri::command]
+#[specta::specta]
+pub async fn repository_open_live_stream(
+    manager: State<'_, RepositoryManagerWrapper>,
+    handle: String,
+    item_id: String,
+) -> Result<LiveStreamInfo, String> {
+    let repo = manager.0.get(&handle).ok_or("Repository not found")?;
+    repo.as_ref()
+        .open_live_stream(&item_id)
+        .await
+        .map_err(|e| format!("{:?}", e))
+}
+
 /// Report playback start
 #[tauri::command]
 #[specta::specta]

src-tauri/src/jellyfin/client.rs

@@ -384,6 +384,82 @@ impl JellyfinClient {
         let sessions = self.get_sessions().await?;
         Ok(sessions.into_iter().find(|s| s.id.as_deref() == Some(session_id)))
     }
+
+    // --- JellyLMS multi-room sync groups -----------------------------------
+    //
+    // The JellyLMS plugin exposes a REST API under `/JellyLms` for grouping LMS
+    // players ("zones") into synchronized multi-room sync groups. Players are
+    // addressed by MAC address; JellyTau maps a Jellyfin session to a MAC by
+    // stripping the `lms-` prefix off the session's device id (see
+    // LmsDeviceDiscoveryService in the jellyLMS repo, which registers each player
+    // with deviceId = "lms-{MacAddress}").
+
+    /// List current LMS sync groups.
+    pub async fn lms_get_sync_groups(&self) -> Result<Vec<LmsSyncGroup>, String> {
+        self.get("/JellyLms/SyncGroups").await
+    }
+
+    /// Fuse LMS zones: create a sync group with `master_mac` as the sync master
+    /// and `slave_macs` joining it. The master keeps playing; slaves follow.
+    pub async fn lms_create_sync_group(
+        &self,
+        master_mac: &str,
+        slave_macs: Vec<String>,
+    ) -> Result<(), String> {
+        let payload = serde_json::json!({
+            "MasterMac": master_mac,
+            "SlaveMacs": slave_macs,
+        });
+        self.post("/JellyLms/SyncGroups", &payload).await
+    }
+
+    /// Remove a single LMS player from whatever sync group it's in.
+    pub async fn lms_unsync_player(&self, mac: &str) -> Result<(), String> {
+        self.delete(&format!("/JellyLms/SyncGroups/Players/{}", mac)).await
+    }
+
+    /// Dissolve an entire LMS sync group, identified by its master's MAC.
+    pub async fn lms_dissolve_sync_group(&self, master_mac: &str) -> Result<(), String> {
+        self.delete(&format!("/JellyLms/SyncGroups/{}", master_mac)).await
+    }
+
+    /// Make a DELETE request to the Jellyfin API (used by the JellyLMS endpoints).
+    async fn delete(&self, endpoint: &str) -> Result<(), String> {
+        let url = format!("{}{}", self.config.server_url, endpoint);
+
+        log::debug!("[JellyfinClient] DELETE {}", endpoint);
+
+        let response = self.http_client
+            .delete(&url)
+            .header("X-Emby-Authorization", self.get_auth_header())
+            .send()
+            .await
+            .map_err(|e| format!("Network request failed: {}", e))?;
+
+        let status = response.status();
+        if !status.is_success() {
+            let error_text = response.text().await.unwrap_or_else(|_| "Unknown error".to_string());
+            return Err(format!("Jellyfin API error {}: {}", status.as_u16(), error_text));
+        }
+        Ok(())
+    }
+}
+
+/// An LMS multi-room sync group, as returned by JellyLMS `/JellyLms/SyncGroups`.
+///
+/// Mirrors the plugin's `SyncGroup` model. The master is the sync source; slaves
+/// follow it in lockstep.
+#[derive(specta::Type, Debug, Clone, Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LmsSyncGroup {
+    #[serde(alias = "MasterMac")]
+    pub master_mac: String,
+    #[serde(default, alias = "MasterName")]
+    pub master_name: String,
+    #[serde(default, alias = "SlaveMacs")]
+    pub slave_macs: Vec<String>,
+    #[serde(default, alias = "SlaveNames")]
+    pub slave_names: Vec<String>,
 }
 
 /// Default value for supports_remote_control when missing from API

src-tauri/src/lib.rs

@@ -40,6 +40,8 @@ use commands::{
     player_set_sleep_timer, player_cancel_sleep_timer, player_get_sleep_timer,
     player_get_autoplay_settings, player_set_autoplay_settings,
     player_cancel_autoplay_countdown, player_play_next_episode, player_on_playback_ended,
+    // HTML5 video state-report commands
+    player_report_state, player_report_position, player_report_media_loaded,
     // Queue manipulation commands
     player_add_to_queue, player_add_track_by_id, player_add_tracks_by_ids,
     player_remove_from_queue, player_move_in_queue, player_skip_to,
@@ -52,11 +54,13 @@ use commands::{
     // Remote session control commands
     remote_play_on_session, remote_send_command, remote_session_seek, remote_session_set_volume,
     remote_session_toggle_mute,
+    // LMS multi-room sync group commands
+    lms_get_sync_groups, lms_create_sync_group, lms_unsync_player, lms_dissolve_sync_group,
     // Session polling commands
     sessions_set_polling_hint, sessions_poll_now, SessionPollerWrapper,
     // Playback mode commands
     playback_mode_get_current, playback_mode_set, playback_mode_is_transferring,
-    playback_mode_transfer_to_remote, playback_mode_transfer_to_local,
+    playback_mode_transfer_to_remote, playback_mode_transfer_to_local, playback_mode_set_transferring,
     playback_mode_get_remote_status,
     // Playback reporting commands
     playback_reporter_init, playback_reporter_destroy,
@@ -94,11 +98,12 @@ use commands::{
     storage_save_series_audio_preference, storage_get_series_audio_preference,
     // Repository commands
     repository_create, repository_destroy, repository_get_libraries, repository_get_items,
-    repository_get_item, repository_get_latest_items, repository_get_resume_items,
+    repository_get_item, repository_jray_actors_at, repository_get_latest_items, repository_get_resume_items,
     repository_get_next_up_episodes, repository_get_recently_played_audio, repository_get_resume_movies,
     repository_get_rediscover_albums,
     repository_get_genres, repository_search, repository_get_playback_info,
     repository_get_video_stream_url, repository_get_audio_stream_url,
+    repository_get_live_tv_channels, repository_get_channels, repository_open_live_stream,
     repository_report_playback_start, repository_report_playback_progress, repository_report_playback_stopped,
     repository_get_image_url, repository_mark_favorite, repository_unmark_favorite,
     repository_get_person, repository_get_items_by_person, repository_get_similar_items,
@@ -145,54 +150,126 @@ use player::{MediaCommandHandler, RemoteVolumeHandler, set_media_command_handler
 
 /// Handler for media commands from Android MediaSession (lockscreen/notification controls).
 ///
-/// Routes commands from the system media controls back to the PlayerController.
+/// Routes commands from the system media controls to the right place depending on
+/// playback mode: in local mode it drives the local `PlayerController`; in remote
+/// (cast) mode it forwards transport commands to the remote Jellyfin session so
+/// the lockscreen can control whatever is casting. Stop while casting requests a
+/// disconnect back to local playback.
 #[cfg(target_os = "android")]
 struct MediaSessionHandler {
     player: Arc<TokioMutex<PlayerController>>,
+    playback_mode: Arc<PlaybackModeManager>,
+    event_emitter: Arc<TauriEventEmitter>,
+}
+
+#[cfg(target_os = "android")]
+impl MediaSessionHandler {
+    /// Forward a transport command to the active remote Jellyfin session.
+    ///
+    /// Runs async on the Tauri runtime because JNI callbacks arrive on arbitrary
+    /// threads without a Tokio context.
+    fn handle_remote_command(&self, command: &str, session_id: String) {
+        use crate::player::{PlayerEventEmitter, PlayerStatusEvent};
+
+        // Stop while casting means "disconnect and resume locally". The frontend
+        // owns the remote->local transfer (it reloads the item locally), so we
+        // just signal intent.
+        if command == "stop" {
+            self.event_emitter
+                .emit(PlayerStatusEvent::RemoteDisconnectRequested);
+            return;
+        }
+
+        let jellyfin_client = {
+            let player = self.player.blocking_lock();
+            player.jellyfin_client()
+        };
+        let command = command.to_string();
+
+        tauri::async_runtime::spawn(async move {
+            let client = {
+                let guard = match jellyfin_client.lock() {
+                    Ok(g) => g,
+                    Err(e) => {
+                        error!("[MediaSession] Failed to lock Jellyfin client: {}", e);
+                        return;
+                    }
+                };
+                match guard.as_ref() {
+                    Some(c) => c.clone(),
+                    None => {
+                        warn!("[MediaSession] No Jellyfin client for remote command");
+                        return;
+                    }
+                }
+            };
+
+            // Map lockscreen transport commands onto Jellyfin session commands.
+            let result = match command.as_str() {
+                "play" => client.send_session_command(session_id, "Unpause").await,
+                "pause" => client.send_session_command(session_id, "Pause").await,
+                "next" => client.send_session_command(session_id, "NextTrack").await,
+                "previous" => client.send_session_command(session_id, "PreviousTrack").await,
+                cmd if cmd.starts_with("seek:") => match cmd[5..].parse::<f64>() {
+                    Ok(seconds) => {
+                        let ticks = (seconds * 10_000_000.0) as i64;
+                        client.session_seek(session_id, ticks).await
+                    }
+                    Err(_) => {
+                        warn!("[MediaSession] Bad seek command: {}", command);
+                        Ok(())
+                    }
+                },
+                _ => {
+                    warn!("[MediaSession] Unknown remote command: {}", command);
+                    Ok(())
+                }
+            };
+
+            if let Err(e) = result {
+                error!("[MediaSession] Remote command '{}' failed: {}", command, e);
+            }
+        });
+    }
+
+    /// Drive the local player for a transport command.
+    fn handle_local_command(&self, command: &str) {
+        // Use blocking_lock since this is called from a non-async JNI callback
+        let controller = self.player.blocking_lock();
+
+        let result = match command {
+            "play" => controller.play(),
+            "pause" => controller.pause(),
+            "next" => controller.next(),
+            "previous" => controller.previous(),
+            "stop" => controller.stop(),
+            cmd if cmd.starts_with("seek:") => match cmd[5..].parse::<f64>() {
+                Ok(pos) => controller.seek(pos),
+                Err(_) => {
+                    warn!("[MediaSession] Bad seek command: {}", command);
+                    Ok(())
+                }
+            },
+            _ => {
+                warn!("[MediaSession] Unknown command: {}", command);
+                Ok(())
+            }
+        };
+
+        if let Err(e) = result {
+            error!("[MediaSession] Command '{}' failed: {}", command, e);
+        }
+    }
 }
 
 #[cfg(target_os = "android")]
 impl MediaCommandHandler for MediaSessionHandler {
     fn on_command(&self, command: &str) {
-        // Use blocking_lock since this is called from a non-async JNI callback
-        let controller = self.player.blocking_lock();
-
-        match command {
-            "play" => {
-                if let Err(e) = controller.play() {
-                    error!("[MediaSession] Play failed: {}", e);
-                }
-            }
-            "pause" => {
-                if let Err(e) = controller.pause() {
-                    error!("[MediaSession] Pause failed: {}", e);
-                }
-            }
-            "next" => {
-                if let Err(e) = controller.next() {
-                    error!("[MediaSession] Next failed: {}", e);
-                }
-            }
-            "previous" => {
-                if let Err(e) = controller.previous() {
-                    error!("[MediaSession] Previous failed: {}", e);
-                }
-            }
-            "stop" => {
-                if let Err(e) = controller.stop() {
-                    error!("[MediaSession] Stop failed: {}", e);
-                }
-            }
-            cmd if cmd.starts_with("seek:") => {
-                if let Ok(pos) = cmd[5..].parse::<f64>() {
-                    if let Err(e) = controller.seek(pos) {
-                        error!("[MediaSession] Seek failed: {}", e);
-                    }
-                }
-            }
-            _ => {
-                warn!("[MediaSession] Unknown command: {}", command);
+        match self.playback_mode.get_mode() {
+            playback_mode::PlaybackMode::Remote { session_id } => {
+                self.handle_remote_command(command, session_id);
             }
+            _ => self.handle_local_command(command),
         }
     }
 }
@@ -401,6 +478,9 @@ fn specta_builder() -> Builder<tauri::Wry> {
             player_cancel_autoplay_countdown,
             player_play_next_episode,
             player_on_playback_ended,
+            player_report_state,
+            player_report_position,
+            player_report_media_loaded,
             // Preload commands
             player_preload_upcoming,
             player_set_cache_config,
@@ -417,6 +497,11 @@ fn specta_builder() -> Builder<tauri::Wry> {
             remote_session_seek,
             remote_session_set_volume,
             remote_session_toggle_mute,
+            // LMS multi-room sync group commands
+            lms_get_sync_groups,
+            lms_create_sync_group,
+            lms_unsync_player,
+            lms_dissolve_sync_group,
             // Session polling commands
             sessions_set_polling_hint,
             sessions_poll_now,
@@ -427,6 +512,7 @@ fn specta_builder() -> Builder<tauri::Wry> {
             playback_mode_transfer_to_remote,
             playback_mode_get_remote_status,
             playback_mode_transfer_to_local,
+            playback_mode_set_transferring,
             // Playback reporting commands
             playback_reporter_init,
             playback_reporter_destroy,
@@ -553,6 +639,7 @@ fn specta_builder() -> Builder<tauri::Wry> {
             repository_get_libraries,
             repository_get_items,
             repository_get_item,
+            repository_jray_actors_at,
             repository_get_latest_items,
             repository_get_resume_items,
             repository_get_next_up_episodes,
@@ -564,6 +651,9 @@ fn specta_builder() -> Builder<tauri::Wry> {
             repository_get_playback_info,
             repository_get_video_stream_url,
             repository_get_audio_stream_url,
+            repository_get_live_tv_channels,
+            repository_get_channels,
+            repository_open_live_stream,
             repository_report_playback_start,
             repository_report_playback_progress,
             repository_report_playback_stopped,
@@ -592,6 +682,81 @@ fn specta_builder() -> Builder<tauri::Wry> {
         ])
 }
 
+/// Configure GStreamer (the media backend behind WebKitGTK's HTML5 `<video>`
+/// element on Linux) to prefer hardware-accelerated VAAPI decoding when the
+/// host provides it, falling back to software decoding otherwise.
+///
+/// All variables are only set if the user has not already exported them, so an
+/// explicit override (e.g. forcing software decode for debugging) is respected.
+/// They must be applied before WebKitGTK builds its GStreamer pipeline, hence the
+/// call at the very top of `run()`.
+#[cfg(target_os = "linux")]
+fn enable_linux_hardware_video_decoding() {
+    // Boost the rank of the modern stateless VAAPI decoders (gst-plugins-bad
+    // `va` plugin) so GStreamer selects them ahead of the software decoders. The
+    // `MAX` rank wins decoder autoplugging when the hardware/driver supports the
+    // codec; unsupported codecs simply fall through to software.
+    let rank_overrides = "vah264dec:MAX,vah265dec:MAX,vavp9dec:MAX,vaav1dec:MAX,\
+                          vampeg2dec:MAX,vavp8dec:MAX";
+
+    set_env_if_unset("GST_PLUGIN_FEATURE_RANK", rank_overrides);
+
+    // Ensure WebKit keeps GStreamer's hardware/DMABUF video path enabled. Setting
+    // this to "0" would force software decoding, so only default it to "1".
+    set_env_if_unset("WEBKIT_GST_ENABLE_HW_VIDEO_DECODER", "1");
+
+    info!("[INIT] Linux hardware video decoding (VAAPI) enabled where supported");
+
+    log_available_vaapi_decoders();
+}
+
+/// Probe (via `gst-inspect-1.0`, which ships with GStreamer) which VAAPI hardware
+/// video decoders GStreamer can actually load on this host, and log the result so
+/// it is clear at startup whether hardware decoding is genuinely available or
+/// whether playback will fall back to software.
+#[cfg(target_os = "linux")]
+fn log_available_vaapi_decoders() {
+    const HW_DECODERS: &[&str] = &[
+        "vah264dec", "vah265dec", "vavp9dec", "vaav1dec", "vampeg2dec", "vavp8dec",
+    ];
+
+    let available: Vec<&str> = HW_DECODERS
+        .iter()
+        .copied()
+        .filter(|name| {
+            std::process::Command::new("gst-inspect-1.0")
+                .arg(name)
+                .stdout(std::process::Stdio::null())
+                .stderr(std::process::Stdio::null())
+                .status()
+                .map(|s| s.success())
+                .unwrap_or(false)
+        })
+        .collect();
+
+    if available.is_empty() {
+        log::warn!(
+            "[INIT] No VAAPI hardware video decoders found via gst-inspect-1.0; \
+             video will use software decoding. Install the GStreamer 'va' plugin \
+             (gst-plugins-bad) and a VAAPI driver to enable hardware decoding."
+        );
+    } else {
+        info!(
+            "[INIT] VAAPI hardware video decoders available to GStreamer: {}",
+            available.join(", ")
+        );
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn set_env_if_unset(key: &str, value: &str) {
+    if std::env::var_os(key).is_none() {
+        // SAFETY: called once at startup before any threads that read the
+        // environment (WebKitGTK/GStreamer) are spawned.
+        std::env::set_var(key, value);
+    }
+}
+
 #[cfg_attr(mobile, tauri::mobile_entry_point)]
 pub fn run() {
     // Initialize logger
@@ -599,6 +764,13 @@ pub fn run() {
         .filter_level(log::LevelFilter::Info)
         .init();
 
+    // On Linux, video plays through WebKitGTK's HTML5 <video> element, which uses
+    // GStreamer as its media backend. Enable hardware-accelerated (VAAPI) decoding
+    // when available so video transcoding/decoding does not fall back to the CPU.
+    // These must be set before WebKitGTK initializes its GStreamer pipeline.
+    #[cfg(target_os = "linux")]
+    enable_linux_hardware_video_decoding();
+
     // NOTE: TypeScript bindings are generated by the `export_typescript_bindings`
     // test (`cargo test export_typescript_bindings`), NOT at runtime. Calling
     // `.export()` here would try to write `../src/lib/api/bindings.ts` at app
@@ -720,16 +892,11 @@ pub fn run() {
 
             let player_arc = Arc::new(TokioMutex::new(player_controller));
 
-            // On Android, set up the MediaSession handler for lockscreen controls
+            // On Android, register the player controller for autoplay decisions.
+            // The MediaSession (lockscreen) handler is set up later, once the
+            // playback mode manager exists, so it can route to remote sessions.
             #[cfg(target_os = "android")]
             {
-                info!("[INIT] Setting up MediaSession handler for lockscreen controls...");
-                let handler = Arc::new(MediaSessionHandler {
-                    player: player_arc.clone(),
-                });
-                set_media_command_handler(handler);
-
-                // Register player controller for autoplay decisions
                 player::android::set_player_controller(player_arc.clone());
             }
 
@@ -768,9 +935,19 @@ pub fn run() {
             let session_poller_wrapper = SessionPollerWrapper(session_poller_arc);
             app.manage(session_poller_wrapper);
 
-            // On Android, set up remote volume handler for volume button intercept in remote mode
+            // On Android, set up the MediaSession (lockscreen) handler and the
+            // remote volume handler. Both need the playback mode manager so they
+            // can route to the active remote session while casting.
             #[cfg(target_os = "android")]
             {
+                info!("[INIT] Setting up MediaSession handler for lockscreen controls...");
+                let media_handler = Arc::new(MediaSessionHandler {
+                    player: player_arc.clone(),
+                    playback_mode: playback_mode_arc.clone(),
+                    event_emitter: event_emitter.clone(),
+                });
+                set_media_command_handler(media_handler);
+
                 info!("[INIT] Setting up remote volume handler for Android...");
                 let handler = Arc::new(RemoteVolumeSessionHandler {
                     playback_mode: playback_mode_arc.clone(),
@@ -846,9 +1023,13 @@ pub fn run() {
             let repository_manager_wrapper = RepositoryManagerWrapper(repository_manager);
             app.manage(repository_manager_wrapper);
 
-            // Initialize playback reporter wrapper (initially empty, set on login)
+            // Initialize playback reporter wrapper. This MUST share the same Arc
+            // the player controller and MPV progress loop report through (created
+            // above at `playback_reporter`), otherwise `playback_reporter_init`
+            // would populate a dead, parallel Option and no Start/Progress/Stopped
+            // would ever reach Jellyfin.
             info!("[INIT] Initializing playback reporter wrapper...");
-            let playback_reporter_wrapper = PlaybackReporterWrapper(Arc::new(tokio::sync::Mutex::new(None)));
+            let playback_reporter_wrapper = PlaybackReporterWrapper(playback_reporter.clone());
             app.manage(playback_reporter_wrapper);
 
             info!("[INIT] Application setup completed successfully");

src-tauri/src/playback_mode/mod.rs

@@ -81,6 +81,19 @@ impl PlaybackModeManager {
         self.is_transferring.load(Ordering::Relaxed)
     }
 
+    /// Set the transferring flag directly.
+    ///
+    /// The remote->local transfer is driven from the frontend in two steps
+    /// (`player_play_tracks` to start local playback, then
+    /// `playback_mode_transfer_to_local` to stop the remote). The first step's
+    /// routing depends on this flag: while it's set, `player_play_tracks` plays
+    /// locally instead of casting back to the remote session. The frontend must
+    /// raise the flag *before* that first call and lower it when the sequence is
+    /// done (or aborts), so it can't be left stuck on.
+    pub fn set_transferring(&self, transferring: bool) {
+        self.is_transferring.store(transferring, Ordering::Relaxed);
+    }
+
     /// Send volume command to remote session
     /// Commands: "SetVolume", "VolumeUp", "VolumeDown"
     #[allow(dead_code)] // Called from Android JNI callback

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

@@ -17,7 +17,8 @@ use super::backend::{PlayerBackend, PlayerError};
 use super::events::{PlayerStatusEvent, SharedEventEmitter};
 use super::media::{MediaItem, MediaType};
 use super::state::PlayerState;
-use crate::playback_reporting::{PlaybackReporter, EventThrottler};
+use crate::playback_reporting::{PlaybackReporter, EventThrottler, PlaybackOperation};
+use crate::utils::conversions::seconds_to_ticks;
 
 /// Global reference to the JavaVM for JNI callbacks
 static JAVA_VM: OnceLock<JavaVM> = OnceLock::new();
@@ -584,6 +585,75 @@ pub extern "system" fn Java_com_dtourolle_jellytau_player_JellyTauPlayer_nativeO
     } else {
         log::error!("[Android] WARNING: No event emitter for position update!");
     }
+
+    // Throttled progress reporting to Jellyfin so playback position syncs and can
+    // be resumed on another device. ExoPlayer only fires position updates while
+    // playing, but guard on the stored state anyway. Mirrors the MPV backend's
+    // progress loop; both share the same EventThrottler (every 30s per item).
+    report_android_progress(position);
+}
+
+/// Report throttled playback progress to Jellyfin from the Android position
+/// callback. No-op until the reporter/throttler are wired (post-login) or when
+/// not actively playing.
+fn report_android_progress(position: f64) {
+    let item_id = match SHARED_STATE.get() {
+        Some(state) => {
+            let state = state.lock_safe();
+            if !state.state.is_playing() {
+                return;
+            }
+            match state.current_media.as_ref().and_then(|m| m.jellyfin_id().map(|s| s.to_string())) {
+                Some(id) => id,
+                None => return,
+            }
+        }
+        None => return,
+    };
+
+    let throttler = match POSITION_THROTTLER.get() {
+        Some(t) => t,
+        None => return,
+    };
+    if !throttler.should_report(&item_id) {
+        return;
+    }
+
+    let reporter_arc = match PLAYBACK_REPORTER.get() {
+        Some(r) => r.clone(),
+        None => return,
+    };
+
+    let position_ticks = seconds_to_ticks(position);
+    let item_id_for_task = item_id.clone();
+
+    // The reporter is async; the JNI callback is sync. Spawn onto the Tokio
+    // runtime when present, otherwise a throwaway runtime on a new thread.
+    let spawn_report = move || async move {
+        let reporter_guard = reporter_arc.lock().await;
+        if let Some(reporter) = reporter_guard.as_ref() {
+            let operation = PlaybackOperation::Progress {
+                item_id: item_id_for_task.clone(),
+                position_ticks,
+                is_paused: false,
+            };
+            match reporter.report(operation, true).await {
+                Ok(_) => debug!("[Android] Reported progress for {}", item_id_for_task),
+                Err(e) => log::warn!("[Android] Failed to report progress: {}", e),
+            }
+        }
+    };
+
+    if let Ok(handle) = tokio::runtime::Handle::try_current() {
+        handle.spawn(spawn_report());
+    } else {
+        std::thread::spawn(move || {
+            let rt = tokio::runtime::Runtime::new().unwrap();
+            rt.block_on(spawn_report());
+        });
+    }
+
+    throttler.mark_reported(&item_id);
 }
 
 /// Called when player state changes.
@@ -1117,6 +1187,92 @@ pub fn disable_remote_volume() -> Result<(), String> {
     Ok(())
 }
 
+use crate::player::LockscreenMetadata;
+
+/// Push now-playing metadata and playback state to the Android lockscreen.
+///
+/// Calls `JellyTauPlaybackService.updateMediaMetadata(...)`. The service must be
+/// running (in remote mode it is started via [`enable_remote_volume`]); if it
+/// isn't, this is a no-op rather than an error so it can be called freely on
+/// every poll tick.
+pub fn update_lockscreen_metadata(meta: &LockscreenMetadata) -> Result<(), String> {
+    let vm = JAVA_VM.get().ok_or("JavaVM not initialized")?;
+    let mut env = vm.attach_current_thread().map_err(|e| e.to_string())?;
+
+    let context = APP_CONTEXT.get().ok_or("Context not initialized")?;
+
+    let class_loader = env
+        .call_method(context, "getClassLoader", "()Ljava/lang/ClassLoader;", &[])
+        .map_err(|e| format!("Failed to get ClassLoader: {}", e))?
+        .l()
+        .map_err(|e| format!("Failed to convert ClassLoader: {}", e))?;
+
+    let service_class_name = env
+        .new_string("com.dtourolle.jellytau.player.JellyTauPlaybackService")
+        .map_err(|e| format!("Failed to create class name string: {}", e))?;
+
+    let service_class_obj = env
+        .call_method(
+            &class_loader,
+            "loadClass",
+            "(Ljava/lang/String;)Ljava/lang/Class;",
+            &[JValue::Object(&service_class_name.into())],
+        )
+        .map_err(|e| format!("Failed to load JellyTauPlaybackService class: {}", e))?
+        .l()
+        .map_err(|e| format!("Failed to convert to Class: {}", e))?;
+
+    let service_class = JClass::from(service_class_obj);
+
+    let service_obj = env
+        .call_static_method(
+            &service_class,
+            "getInstance",
+            "()Lcom/dtourolle/jellytau/player/JellyTauPlaybackService;",
+            &[],
+        )
+        .map_err(|e| format!("Failed to get service instance: {}", e))?
+        .l()
+        .map_err(|e| format!("Failed to convert to object: {}", e))?;
+
+    // Service not running yet (e.g. nothing has played) - nothing to update.
+    if service_obj.is_null() {
+        return Ok(());
+    }
+
+    let title = env
+        .new_string(&meta.title)
+        .map_err(|e| format!("Failed to create title string: {}", e))?;
+    let artist = env
+        .new_string(&meta.artist)
+        .map_err(|e| format!("Failed to create artist string: {}", e))?;
+    // album is nullable on the Kotlin side; pass a real String or JObject::null().
+    let album_obj = match &meta.album {
+        Some(a) => env
+            .new_string(a)
+            .map_err(|e| format!("Failed to create album string: {}", e))?
+            .into(),
+        None => jni::objects::JObject::null(),
+    };
+
+    env.call_method(
+        &service_obj,
+        "updateMediaMetadata",
+        "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;JJZ)V",
+        &[
+            JValue::Object(&title.into()),
+            JValue::Object(&artist.into()),
+            JValue::Object(&album_obj),
+            JValue::Long(meta.duration_ms),
+            JValue::Long(meta.position_ms),
+            JValue::Bool(meta.is_playing as u8),
+        ],
+    )
+    .map_err(|e| format!("Failed to update lockscreen metadata: {}", e))?;
+
+    Ok(())
+}
+
 /// Stub implementations for non-Android platforms
 #[cfg(not(target_os = "android"))]
 pub fn enable_remote_volume(_initial_volume: i32) -> Result<(), String> {

src-tauri/src/player/events.rs

@@ -78,6 +78,11 @@ pub enum PlayerStatusEvent {
         /// Remaining seconds (for time-based timer)
         remaining_seconds: u32,
     },
+    /// Time-based sleep timer expired: playback must stop. The backend stops
+    /// its own (MPV/ExoPlayer) playback, but HTML5 video on Linux plays in the
+    /// webview outside the backend's control — the frontend pauses it on this
+    /// event.
+    SleepTimerExpired,
     /// Show next episode popup with countdown
     ShowNextEpisodePopup {
         /// Current episode that just finished
@@ -119,6 +124,12 @@ pub enum PlayerStatusEvent {
         /// All active controllable sessions from Jellyfin
         sessions: Vec<crate::jellyfin::client::SessionInfo>,
     },
+    /// The user asked to disconnect from the remote session and resume locally.
+    ///
+    /// Emitted when the lockscreen Stop button is pressed while casting. The
+    /// frontend owns the two-step remote->local transfer (it must reload the
+    /// media item locally), so the native side only signals intent here.
+    RemoteDisconnectRequested,
 }
 
 /// Trait for emitting player events to the frontend.

src-tauri/src/player/mod.rs

@@ -46,6 +46,37 @@ pub use android::{
     set_media_command_handler, set_remote_volume_handler, get_detected_codecs,
 };
 
+/// Metadata for the lockscreen / media notification.
+///
+/// Used to drive the Android MediaSession from Rust in remote (cast) mode, where
+/// the local ExoPlayer is idle and so can't supply now-playing info. The session
+/// poller fills this in from the remote Jellyfin session and pushes it to the
+/// notification so the lockscreen stays in sync while casting.
+#[derive(Debug, Clone)]
+pub struct LockscreenMetadata {
+    pub title: String,
+    pub artist: String,
+    pub album: Option<String>,
+    /// Track duration in milliseconds.
+    pub duration_ms: i64,
+    /// Current playback position in milliseconds.
+    pub position_ms: i64,
+    pub is_playing: bool,
+}
+
+/// Push now-playing metadata to the Android lockscreen. No-op off Android, so the
+/// session poller can call it unconditionally and stay platform-agnostic.
+pub fn update_lockscreen_metadata(_meta: &LockscreenMetadata) -> Result<(), String> {
+    #[cfg(target_os = "android")]
+    {
+        return android::update_lockscreen_metadata(_meta);
+    }
+    #[cfg(not(target_os = "android"))]
+    {
+        Ok(())
+    }
+}
+
 use crate::utils::lock::MutexSafe;
 use log::{debug, error, warn};
 use std::sync::{Arc, Mutex};
@@ -134,9 +165,18 @@ impl PlayerController {
         self.jellyfin_client.clone()
     }
 
-    /// Configure the playback reporter for dual sync (local DB + server)
-    /// Will be called from initialization commands after login
-    #[allow(dead_code)]
+    /// Configure the media repository used for next-episode lookups.
+    ///
+    /// The Android ExoPlayer ended-callback calls `on_playback_ended` with no
+    /// repository handle (unlike the Linux HTML5 path, which passes one per
+    /// call), so the controller needs a repository of its own or episode
+    /// autoplay silently decides Stop.
+    pub fn set_repository(&self, repo: Arc<dyn MediaRepository>) {
+        *self.repository.lock_safe() = Some(repo);
+    }
+
+    /// Configure the playback reporter for dual sync (local DB + server).
+    /// Called from `player_configure_jellyfin` on login/restore/reauth.
     pub async fn set_playback_reporter(&self, reporter: Option<PlaybackReporter>) {
         let mut reporter_guard = self.playback_reporter.lock().await;
         *reporter_guard = reporter;
@@ -566,6 +606,13 @@ impl PlayerController {
         self.queue.clone()
     }
 
+    /// Clear the queue entirely (used when playback genuinely stops, e.g. the
+    /// sleep timer fires or the queue ends with repeat off). Pair with
+    /// `emit_queue_changed` so the frontend hides the mini player.
+    pub fn clear_queue(&self) {
+        self.queue.lock_safe().clear();
+    }
+
     /// Toggle shuffle
     pub fn toggle_shuffle(&self) {
         self.queue.lock_safe().toggle_shuffle();
@@ -670,6 +717,10 @@ impl PlayerController {
                                 mode: SleepTimerMode::Off,
                                 remaining_seconds: 0,
                             });
+                            // Tell the frontend playback must stop: HTML5 video
+                            // (Linux) plays outside the backend, so stopping the
+                            // backend below doesn't reach it.
+                            emitter.emit(PlayerStatusEvent::SleepTimerExpired);
                         }
                         drop(timer);
 
@@ -726,6 +777,44 @@ impl PlayerController {
         }
     }
 
+    // ===== HTML5 video report methods =====
+    //
+    // On platforms where video is rendered in the webview (Linux WebKitGTK
+    // HTML5 <video>), the real player lives outside the native backend, so it
+    // cannot emit PlayerStatusEvents itself. The frontend HTML5 adapter reports
+    // DOM events here, and these methods re-emit them through the SAME event
+    // pipeline the native backends use. This keeps the frontend's player store
+    // fed from one place (playerEvents.ts) in both native and HTML5 modes, so
+    // the Rust controller stays the single source of truth for player state.
+
+    /// Report an HTML5 <video> state change (playing/paused/loading/stopped).
+    ///
+    /// Re-emits a `StateChanged` event identical to what MpvBackend/ExoPlayer
+    /// would emit, so `playerEvents.ts` needs no HTML5-specific branch.
+    pub fn report_html5_state(&self, state: String, media_id: Option<String>) {
+        if let Some(emitter) = self.event_emitter.lock_safe().as_ref() {
+            emitter.emit(PlayerStatusEvent::StateChanged { state, media_id });
+        }
+    }
+
+    /// Report an HTML5 <video> position tick.
+    ///
+    /// Re-emits a `PositionUpdate` event mirroring the native backends' periodic
+    /// position updates (the adapter is expected to throttle to ~250ms like MPV).
+    pub fn report_html5_position(&self, position: f64, duration: f64) {
+        if let Some(emitter) = self.event_emitter.lock_safe().as_ref() {
+            emitter.emit(PlayerStatusEvent::PositionUpdate { position, duration });
+        }
+    }
+
+    /// Report that the HTML5 <video> element finished loading and knows its
+    /// duration. Mirrors the native `MediaLoaded` event.
+    pub fn report_html5_media_loaded(&self, duration: f64) {
+        if let Some(emitter) = self.event_emitter.lock_safe().as_ref() {
+            emitter.emit(PlayerStatusEvent::MediaLoaded { duration });
+        }
+    }
+
     // ===== Autoplay Methods =====
 
     /// Get autoplay settings
@@ -842,9 +931,17 @@ impl PlayerController {
             let repo = self.repository.lock_safe().clone();
             let jellyfin_id = current.jellyfin_id().unwrap_or(&current.id);
             let next_ep_result = if let Some(repo) = &repo {
-                self.fetch_next_episode_for_item(jellyfin_id, repo).await?
+                // Degrade lookup failures to Stop: playback already ended, and
+                // surfacing an error here just kills autoplay silently upstream.
+                match self.fetch_next_episode_for_item(jellyfin_id, repo).await {
+                    Ok(next) => next,
+                    Err(e) => {
+                        warn!("[PlayerController] Next-episode lookup failed for {}: {}", jellyfin_id, e);
+                        None
+                    }
+                }
             } else {
-                debug!("[PlayerController] No repository available for audio-path episode lookup");
+                warn!("[PlayerController] No repository available for episode lookup - cannot autoplay next episode");
                 None
             };
             if let Some(next_ep) = next_ep_result {
@@ -899,7 +996,7 @@ impl PlayerController {
             debug!("[PlayerController] Cleared stale end_reason for video: {:?}", stale_reason);
         }
 
-        debug!("[PlayerController] on_video_playback_ended: item_id={}", item_id);
+        log::info!("[PlayerController] on_video_playback_ended: item_id={}", item_id);
 
         // Check sleep timer state
         let timer_mode = {
@@ -932,8 +1029,17 @@ impl PlayerController {
             _ => {}
         }
 
-        // Fetch next episode for the video that just ended
-        if let Some(next_ep) = self.fetch_next_episode_for_item(item_id, &repo).await? {
+        // Fetch next episode for the video that just ended. Degrade lookup
+        // failures to Stop: playback already ended, and propagating an error
+        // here just kills autoplay silently upstream.
+        let next_ep_result = match self.fetch_next_episode_for_item(item_id, &repo).await {
+            Ok(next) => next,
+            Err(e) => {
+                warn!("[PlayerController] Next-episode lookup failed for {}: {}", item_id, e);
+                None
+            }
+        };
+        if let Some(next_ep) = next_ep_result {
             let settings = self.autoplay_settings.lock_safe().clone();
 
             let limit_reached = self.increment_autoplay_count();
@@ -983,7 +1089,7 @@ impl PlayerController {
         let season_id = match &current_repo_item.season_id {
             Some(sid) => sid.clone(),
             None => {
-                debug!("[PlayerController] Current item has no season_id, cannot find next episode");
+                log::info!("[PlayerController] Current item has no season_id, cannot find next episode");
                 return Ok(None);
             }
         };
@@ -1005,19 +1111,19 @@ impl PlayerController {
         // (offline repo ignores sort_by and sorts by sort_name instead)
         let mut episodes = result.items;
         episodes.sort_by_key(|e| e.index_number.unwrap_or(i32::MAX));
-        debug!("[PlayerController] Season has {} episodes, looking for next after {}", episodes.len(), current_repo_item.id);
+        log::info!("[PlayerController] Season has {} episodes, looking for next after {}", episodes.len(), current_repo_item.id);
 
         // Find the current episode by ID and return the next one
         if let Some(current_idx) = episodes.iter().position(|e| e.id == current_repo_item.id) {
             if current_idx + 1 < episodes.len() {
                 let next = &episodes[current_idx + 1];
-                debug!("[PlayerController] Found next episode: {} (index {})", next.name, current_idx + 1);
+                log::info!("[PlayerController] Found next episode: {} (index {})", next.name, current_idx + 1);
                 return Ok(Some((current_repo_item, next.clone())));
             } else {
-                debug!("[PlayerController] Current episode is the last in the season");
+                log::info!("[PlayerController] Current episode is the last in the season");
             }
         } else {
-            debug!("[PlayerController] Current episode not found in season episodes");
+            log::info!("[PlayerController] Current episode not found in season episodes (ids: {:?})", episodes.iter().map(|e| e.id.as_str()).take(20).collect::<Vec<_>>());
         }
 
         Ok(None)
@@ -1071,6 +1177,83 @@ impl Default for PlayerController {
 mod tests {
     use super::*;
 
+    /// Test emitter that captures events for asserting the HTML5 report methods
+    /// re-emit through the normal PlayerStatusEvent pipeline.
+    struct CapturingEmitter {
+        events: std::sync::Mutex<Vec<PlayerStatusEvent>>,
+    }
+
+    impl CapturingEmitter {
+        fn new() -> Self {
+            Self {
+                events: std::sync::Mutex::new(Vec::new()),
+            }
+        }
+        fn events(&self) -> Vec<PlayerStatusEvent> {
+            self.events.lock_safe().clone()
+        }
+    }
+
+    impl PlayerEventEmitter for CapturingEmitter {
+        fn emit(&self, event: PlayerStatusEvent) {
+            self.events.lock_safe().push(event);
+        }
+    }
+
+    #[test]
+    fn test_report_html5_state_emits_state_changed() {
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+
+        controller.report_html5_state("playing".to_string(), Some("item-1".to_string()));
+
+        let events = emitter.events();
+        assert_eq!(events.len(), 1);
+        match &events[0] {
+            PlayerStatusEvent::StateChanged { state, media_id } => {
+                assert_eq!(state, "playing");
+                assert_eq!(media_id.as_deref(), Some("item-1"));
+            }
+            other => panic!("expected StateChanged, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn test_report_html5_position_emits_position_update() {
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+
+        controller.report_html5_position(12.5, 300.0);
+
+        let events = emitter.events();
+        assert_eq!(events.len(), 1);
+        match &events[0] {
+            PlayerStatusEvent::PositionUpdate { position, duration } => {
+                assert_eq!(*position, 12.5);
+                assert_eq!(*duration, 300.0);
+            }
+            other => panic!("expected PositionUpdate, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn test_report_html5_media_loaded_emits_media_loaded() {
+        let controller = PlayerController::default();
+        let emitter = Arc::new(CapturingEmitter::new());
+        controller.set_event_emitter(emitter.clone());
+
+        controller.report_html5_media_loaded(420.0);
+
+        let events = emitter.events();
+        assert_eq!(events.len(), 1);
+        match &events[0] {
+            PlayerStatusEvent::MediaLoaded { duration } => assert_eq!(*duration, 420.0),
+            other => panic!("expected MediaLoaded, got {:?}", other),
+        }
+    }
+
     #[test]
     fn test_controller_volume_default() {
         let controller = PlayerController::default();
@@ -1729,4 +1912,280 @@ mod tests {
         let reason = controller.take_end_reason();
         assert!(reason.is_none(), "take_end_reason should clear the state");
     }
+
+    // ===== Next-episode autoplay decision tests =====
+
+    use crate::repository::types as repo_types;
+
+    /// Mock repository serving a single season of episodes for next-episode
+    /// lookup tests. Only `get_item` and `get_items` are used by
+    /// `fetch_next_episode_for_item`; everything else is unreachable.
+    struct MockEpisodeRepo {
+        episodes: Vec<repo_types::MediaItem>,
+    }
+
+    impl MockEpisodeRepo {
+        fn season(count: usize) -> Self {
+            let episodes = (1..=count)
+                .map(|i| {
+                    let mut item = make_repo_episode(&format!("ep{}", i), i as i32);
+                    item.name = format!("Episode {}", i);
+                    item
+                })
+                .collect();
+            Self { episodes }
+        }
+    }
+
+    fn make_repo_episode(id: &str, index: i32) -> repo_types::MediaItem {
+        repo_types::MediaItem {
+            id: id.to_string(),
+            name: format!("Episode {}", index),
+            item_type: "Episode".to_string(),
+            is_folder: false,
+            server_id: "server".to_string(),
+            parent_id: Some("season1".to_string()),
+            library_id: None,
+            overview: None,
+            genres: None,
+            runtime_ticks: None,
+            production_year: None,
+            premiere_date: None,
+            community_rating: None,
+            official_rating: None,
+            primary_image_tag: None,
+            backdrop_image_tags: None,
+            parent_backdrop_image_tags: None,
+            album_id: None,
+            album_name: None,
+            album_artist: None,
+            artists: None,
+            artist_items: None,
+            index_number: Some(index),
+            series_id: Some("series1".to_string()),
+            series_name: Some("Test Series".to_string()),
+            season_id: Some("season1".to_string()),
+            season_name: Some("Season 1".to_string()),
+            parent_index_number: Some(1),
+            user_data: None,
+            media_streams: None,
+            media_sources: None,
+            people: None,
+        }
+    }
+
+    #[async_trait::async_trait]
+    impl crate::repository::MediaRepository for MockEpisodeRepo {
+        async fn get_libraries(&self) -> Result<Vec<repo_types::Library>, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_items(
+            &self,
+            parent_id: &str,
+            _options: Option<repo_types::GetItemsOptions>,
+        ) -> Result<repo_types::SearchResult, repo_types::RepoError> {
+            assert_eq!(parent_id, "season1", "episode lookup must query the season");
+            Ok(repo_types::SearchResult {
+                items: self.episodes.clone(),
+                total_record_count: self.episodes.len(),
+            })
+        }
+        async fn get_item(&self, item_id: &str) -> Result<repo_types::MediaItem, repo_types::RepoError> {
+            self.episodes
+                .iter()
+                .find(|e| e.id == item_id)
+                .cloned()
+                .ok_or(repo_types::RepoError::NotFound {
+                    message: format!("{} not found", item_id),
+                })
+        }
+        async fn get_latest_items(&self, _: &str, _: Option<usize>) -> Result<Vec<repo_types::MediaItem>, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_resume_items(&self, _: Option<&str>, _: Option<usize>) -> Result<Vec<repo_types::MediaItem>, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_next_up_episodes(&self, _: Option<&str>, _: Option<usize>) -> Result<Vec<repo_types::MediaItem>, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_recently_played_audio(&self, _: Option<usize>) -> Result<Vec<repo_types::MediaItem>, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_rediscover_albums(&self, _: Option<&str>, _: Option<usize>) -> Result<Vec<repo_types::MediaItem>, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_resume_movies(&self, _: Option<usize>) -> Result<Vec<repo_types::MediaItem>, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_genres(&self, _: Option<&str>) -> Result<Vec<repo_types::Genre>, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn search(&self, _: &str, _: Option<repo_types::SearchOptions>) -> Result<repo_types::SearchResult, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_playback_info(&self, _: &str) -> Result<repo_types::PlaybackInfo, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_audio_stream_url(&self, _: &str) -> Result<String, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_live_tv_channels(&self) -> Result<Vec<repo_types::MediaItem>, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_channels(&self) -> Result<repo_types::SearchResult, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn open_live_stream(&self, _: &str) -> Result<repo_types::LiveStreamInfo, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn report_playback_start(&self, _: &str, _: i64) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn report_playback_progress(&self, _: &str, _: i64) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn report_playback_stopped(&self, _: &str, _: i64) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
+        fn get_image_url(&self, _: &str, _: repo_types::ImageType, _: Option<repo_types::ImageOptions>) -> String {
+            unimplemented!()
+        }
+        fn get_subtitle_url(&self, _: &str, _: &str, _: i32, _: &str) -> String {
+            unimplemented!()
+        }
+        fn get_video_download_url(&self, _: &str, _: &str, _: Option<&str>) -> String {
+            unimplemented!()
+        }
+        async fn mark_favorite(&self, _: &str) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn unmark_favorite(&self, _: &str) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_person(&self, _: &str) -> Result<repo_types::MediaItem, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_items_by_person(&self, _: &str, _: Option<repo_types::GetItemsOptions>) -> Result<repo_types::SearchResult, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_similar_items(&self, _: &str, _: Option<usize>) -> Result<repo_types::SearchResult, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn create_playlist(&self, _: &str, _: &[String]) -> Result<repo_types::PlaylistCreatedResult, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn delete_playlist(&self, _: &str) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn rename_playlist(&self, _: &str, _: &str) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn get_playlist_items(&self, _: &str) -> Result<Vec<repo_types::PlaylistEntry>, repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn add_to_playlist(&self, _: &str, _: &[String]) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn remove_from_playlist(&self, _: &str, _: &[String]) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
+        async fn move_playlist_item(&self, _: &str, _: &str, _: u32) -> Result<(), repo_types::RepoError> {
+            unimplemented!()
+        }
+    }
+
+    /// Video (HTML5/Linux) path: ending mid-season must produce the
+    /// next-episode popup with auto-advance.
+    #[tokio::test]
+    async fn test_video_playback_ended_offers_next_episode() {
+        let controller = PlayerController::default();
+        let repo: Arc<dyn MediaRepository> = Arc::new(MockEpisodeRepo::season(3));
+
+        let decision = controller
+            .on_video_playback_ended("ep2", repo)
+            .await
+            .expect("decision should succeed");
+
+        match decision {
+            AutoplayDecision::ShowNextEpisodePopup {
+                current_episode,
+                next_episode,
+                auto_advance,
+                ..
+            } => {
+                assert_eq!(current_episode.id, "ep2");
+                assert_eq!(next_episode.id, "ep3");
+                assert!(auto_advance, "default settings should auto-advance");
+            }
+            other => panic!("Expected ShowNextEpisodePopup, got {:?}", other),
+        }
+    }
+
+    /// Last episode of the season: no popup, stop.
+    #[tokio::test]
+    async fn test_video_playback_ended_last_episode_stops() {
+        let controller = PlayerController::default();
+        let repo: Arc<dyn MediaRepository> = Arc::new(MockEpisodeRepo::season(3));
+
+        let decision = controller
+            .on_video_playback_ended("ep3", repo)
+            .await
+            .expect("decision should succeed");
+
+        assert!(matches!(decision, AutoplayDecision::Stop));
+    }
+
+    /// Android/ExoPlayer path: `on_playback_ended` has no per-call repository,
+    /// so the controller-level repository (wired up in `repository_create`)
+    /// must be used for the next-episode lookup. Regression test for episode
+    /// autoplay never triggering on Android because no repository was set.
+    #[tokio::test]
+    async fn test_playback_ended_uses_controller_repository_for_episodes() {
+        let controller = PlayerController::default();
+        controller.set_repository(Arc::new(MockEpisodeRepo::season(3)));
+
+        // Queue holds the episode that just finished playing
+        let episode = MediaItem {
+            media_type: MediaType::Video,
+            source: MediaSource::Remote {
+                stream_url: "http://example.com/ep1.mkv".to_string(),
+                jellyfin_item_id: "ep1".to_string(),
+            },
+            ..create_test_items(1).remove(0)
+        };
+        controller.play_queue(vec![episode], 0).unwrap();
+
+        // Clear the NewTrackLoaded reason to simulate natural track end
+        controller.take_end_reason();
+
+        let decision = controller.on_playback_ended().await.unwrap();
+
+        match decision {
+            AutoplayDecision::ShowNextEpisodePopup { next_episode, .. } => {
+                assert_eq!(next_episode.id, "ep2");
+            }
+            other => panic!("Expected ShowNextEpisodePopup, got {:?}", other),
+        }
+    }
+
+    /// Without a controller repository the Android episode path must still
+    /// stop gracefully (previous behavior) rather than error.
+    #[tokio::test]
+    async fn test_playback_ended_without_repository_stops() {
+        let controller = PlayerController::default();
+
+        let episode = MediaItem {
+            media_type: MediaType::Video,
+            source: MediaSource::Remote {
+                stream_url: "http://example.com/ep1.mkv".to_string(),
+                jellyfin_item_id: "ep1".to_string(),
+            },
+            ..create_test_items(1).remove(0)
+        };
+        controller.play_queue(vec![episode], 0).unwrap();
+        controller.take_end_reason();
+
+        let decision = controller.on_playback_ended().await.unwrap();
+        assert!(matches!(decision, AutoplayDecision::Stop));
+    }
 }

src-tauri/src/player/queue.rs

@@ -62,6 +62,14 @@ impl QueueManager {
         &self.items
     }
 
+    /// Mutable access to queue items.
+    ///
+    /// Used to re-point streaming entries at a completed local download
+    /// without disturbing queue order, shuffle state, or the current index.
+    pub fn items_mut(&mut self) -> &mut [MediaItem] {
+        &mut self.items
+    }
+
     /// Get the current item index
     pub fn current_index(&self) -> Option<usize> {
         self.current_index
@@ -122,6 +130,18 @@ impl QueueManager {
         self.context = context;
     }
 
+    /// Clear the queue entirely, returning it to the empty state.
+    ///
+    /// Used when playback genuinely stops (sleep timer fires, or the queue ends
+    /// with repeat off) so the frontend's `currentQueueItem` becomes null and
+    /// the mini player hides. History and shuffle order are reset too.
+    pub fn clear(&mut self) {
+        self.items.clear();
+        self.current_index = None;
+        self.history.clear();
+        self.shuffle_order.clear();
+    }
+
     /// Add items to the queue
     pub fn add(&mut self, items: Vec<MediaItem>, position: AddPosition) {
         if items.is_empty() {
@@ -559,6 +579,21 @@ mod tests {
         assert_eq!(queue.current().unwrap().id, "item_0");
     }
 
+    /// Test clearing the queue returns it to the empty state so the frontend
+    /// hides the mini player on a genuine stop.
+    #[test]
+    fn test_clear() {
+        let mut queue = QueueManager::new();
+        queue.set_queue(create_test_items(3), 1);
+        assert_eq!(queue.current_index(), Some(1));
+
+        queue.clear();
+
+        assert_eq!(queue.items().len(), 0);
+        assert_eq!(queue.current_index(), None);
+        assert!(queue.current().is_none());
+    }
+
     /// Test next track navigation
     ///
     /// @req-test: UR-005 - Control media playback (skip to next track)

src-tauri/src/repository/hybrid.rs

@@ -45,6 +45,12 @@ impl HybridRepository {
         self.online.download_bytes(url).await
     }
 
+    /// Query the JRay plugin for actors on screen at time `t`. Online-only
+    /// (the plugin lives on the Jellyfin server); empty when JRay isn't present.
+    pub async fn get_jray_actors(&self, item_id: &str, t: f64) -> Result<Vec<super::JRayActor>, RepoError> {
+        self.online.get_jray_actors(item_id, t).await
+    }
+
     /// Get video stream URL with optional seeking support.
     /// This method is online-only since offline playback uses local file paths.
     pub async fn get_video_stream_url(
@@ -415,6 +421,21 @@ impl MediaRepository for HybridRepository {
         self.online.get_audio_stream_url(item_id).await
     }
 
+    async fn get_live_tv_channels(&self) -> Result<Vec<MediaItem>, RepoError> {
+        // Live TV requires server communication - delegate to online repository
+        self.online.get_live_tv_channels().await
+    }
+
+    async fn get_channels(&self) -> Result<SearchResult, RepoError> {
+        // Plugin channels require server communication - delegate to online repository
+        self.online.get_channels().await
+    }
+
+    async fn open_live_stream(&self, item_id: &str) -> Result<LiveStreamInfo, RepoError> {
+        // Opening a live stream requires server communication - delegate to online
+        self.online.open_live_stream(item_id).await
+    }
+
     async fn report_playback_start(&self, item_id: &str, position_ticks: i64) -> Result<(), RepoError> {
         // Playback reporting goes directly to server
         self.online.report_playback_start(item_id, position_ticks).await
@@ -722,6 +743,18 @@ mod tests {
             unimplemented!()
         }
 
+        async fn get_live_tv_channels(&self) -> Result<Vec<MediaItem>, RepoError> {
+            unimplemented!()
+        }
+
+        async fn get_channels(&self) -> Result<SearchResult, RepoError> {
+            unimplemented!()
+        }
+
+        async fn open_live_stream(&self, _item_id: &str) -> Result<LiveStreamInfo, RepoError> {
+            unimplemented!()
+        }
+
         async fn report_playback_start(&self, _item_id: &str, _position_ticks: i64) -> Result<(), RepoError> {
             unimplemented!()
         }
@@ -887,6 +920,18 @@ mod tests {
             unimplemented!()
         }
 
+        async fn get_live_tv_channels(&self) -> Result<Vec<MediaItem>, RepoError> {
+            unimplemented!()
+        }
+
+        async fn get_channels(&self) -> Result<SearchResult, RepoError> {
+            unimplemented!()
+        }
+
+        async fn open_live_stream(&self, _item_id: &str) -> Result<LiveStreamInfo, RepoError> {
+            unimplemented!()
+        }
+
         async fn report_playback_start(&self, _item_id: &str, _position_ticks: i64) -> Result<(), RepoError> {
             unimplemented!()
         }
@@ -976,6 +1021,7 @@ mod tests {
             id: id.to_string(),
             name: name.to_string(),
             item_type: "Movie".to_string(),
+            is_folder: false,
             server_id: "test-server".to_string(),
             parent_id: Some("parent-123".to_string()),
             library_id: Some("library-456".to_string()),
@@ -983,6 +1029,7 @@ mod tests {
             genres: Some(vec!["Action".to_string(), "Adventure".to_string()]),
             runtime_ticks: Some(7200000000),
             production_year: Some(2024),
+            premiere_date: None,
             community_rating: Some(8.5),
             official_rating: Some("PG-13".to_string()),
             primary_image_tag: Some("image-tag-123".to_string()),

src-tauri/src/repository/mod.rs

@@ -4,7 +4,7 @@ pub mod offline;
 pub mod hybrid;
 
 pub use types::*;
-pub use online::OnlineRepository;
+pub use online::{OnlineRepository, JRayActor};
 pub use offline::OfflineRepository;
 pub use hybrid::HybridRepository;
 
@@ -117,6 +117,19 @@ pub trait MediaRepository: Send + Sync {
     /// @req: JA-007 - Get playback info and stream URL
     async fn get_audio_stream_url(&self, item_id: &str) -> Result<String, RepoError>;
 
+    /// Get Live TV channels (broadcast / IPTV) for browsing.
+    async fn get_live_tv_channels(&self) -> Result<Vec<MediaItem>, RepoError>;
+
+    /// Get the root list of plugin "Channels" (Jellyfin Channels feature).
+    /// Drill-down into a channel reuses `get_items(channel_id, ...)`.
+    async fn get_channels(&self) -> Result<SearchResult, RepoError>;
+
+    /// Open a live stream (Live TV channel or live channel item) for playback.
+    ///
+    /// Returns the server transcoding URL plus identifiers needed to manage the
+    /// stream. Required before a live channel can be played over HLS.
+    async fn open_live_stream(&self, item_id: &str) -> Result<LiveStreamInfo, RepoError>;
+
     /// Report playback start
     ///
     /// @req: UR-025 - Sync watch history and progress back to Jellyfin

src-tauri/src/repository/offline.rs

@@ -29,6 +29,7 @@ impl OfflineRepository {
             id: item.id.clone(),
             name: item.name,
             item_type: item.item_type,
+            is_folder: item.is_folder,
             server_id: item.server_id,
             parent_id: item.parent_id,
             library_id: item.library_id,
@@ -38,6 +39,7 @@ impl OfflineRepository {
                 .and_then(|s| serde_json::from_str::<Vec<String>>(s).ok()),
             runtime_ticks: item.runtime_ticks,
             production_year: item.production_year,
+            premiere_date: item.premiere_date,
             community_rating: item.community_rating,
             official_rating: item.official_rating,
             primary_image_tag: item.primary_image_tag,
@@ -92,6 +94,7 @@ struct CachedItem {
     id: String,
     name: String,
     item_type: String,
+    is_folder: bool,
     server_id: String,
     parent_id: Option<String>,
     library_id: Option<String>,
@@ -99,6 +102,7 @@ struct CachedItem {
     genres: Option<String>,
     runtime_ticks: Option<i64>,
     production_year: Option<i32>,
+    premiere_date: Option<String>,
     community_rating: Option<f64>,
     official_rating: Option<String>,
     primary_image_tag: Option<String>,
@@ -143,6 +147,9 @@ fn row_to_cached_item(row: &rusqlite::Row) -> rusqlite::Result<CachedItem> {
         season_id: row.get(20)?,
         season_name: row.get(21)?,
         parent_index_number: row.get(22)?,
+        // Appended as the final columns in every SELECT that maps through this fn.
+        is_folder: row.get::<_, Option<i64>>(23)?.unwrap_or(0) != 0,
+        premiere_date: row.get(24)?,
     })
 }
 
@@ -230,24 +237,24 @@ impl OfflineRepository {
             let query = Query::with_params(
                 "INSERT OR REPLACE INTO items (
                     id, server_id, library_id, parent_id,
-                    name, item_type, overview,
+                    name, item_type, is_folder, overview,
                     genres, series_id, series_name,
                     season_id, season_name, index_number, parent_index_number,
                     album_id, album_name, album_artist, artists,
-                    production_year, runtime_ticks,
+                    production_year, premiere_date, runtime_ticks,
                     primary_image_tag, backdrop_image_tags,
                     community_rating, official_rating,
                     synced_at
                 ) VALUES (
                     ?1, ?2, ?3, ?4,
-                    ?5, ?6, ?7,
-                    ?8, ?9, ?10,
-                    ?11, ?12, ?13, ?14,
-                    ?15, ?16, ?17, ?18,
-                    ?19, ?20,
-                    ?21, ?22,
+                    ?5, ?6, ?7, ?8,
+                    ?9, ?10, ?11,
+                    ?12, ?13, ?14, ?15,
+                    ?16, ?17, ?18, ?19,
+                    ?20, ?21, ?22,
                     ?23, ?24,
-                    ?25
+                    ?25, ?26,
+                    ?27
                 )",
                 vec![
                     QueryParam::String(item.id.clone()),
@@ -261,6 +268,7 @@ impl OfflineRepository {
                     },
                     QueryParam::String(item.name.clone()),
                     QueryParam::String(item.item_type.clone()),
+                    QueryParam::Int(if item.is_folder { 1 } else { 0 }),
                     match &item.overview {
                         Some(o) => QueryParam::String(o.clone()),
                         None => QueryParam::Null,
@@ -313,6 +321,10 @@ impl OfflineRepository {
                         Some(y) => QueryParam::Int(y),
                         None => QueryParam::Null,
                     },
+                    match &item.premiere_date {
+                        Some(d) => QueryParam::String(d.clone()),
+                        None => QueryParam::Null,
+                    },
                     match item.runtime_ticks {
                         Some(r) => QueryParam::Int64(r),
                         None => QueryParam::Null,
@@ -441,6 +453,13 @@ impl MediaRepository for OfflineRepository {
         let limit = opts.limit.unwrap_or(10000);  // Match frontend limit for full library loading
         let start_index = opts.start_index.unwrap_or(0);
 
+        // SortBy=Random is the only sort the landing pages rely on offline (the
+        // hero "surprise" pool); everything else keeps the stable name order.
+        let order_by = match opts.sort_by.as_deref() {
+            Some("Random") => "RANDOM()",
+            _ => "i.sort_name ASC, i.name ASC",
+        };
+
         // Build type filter for optional filtering
         let type_filter = if let Some(include_item_types) = &opts.include_item_types {
             if !include_item_types.is_empty() {
@@ -491,13 +510,13 @@ impl MediaRepository for OfflineRepository {
                     i.runtime_ticks, i.production_year, i.community_rating, i.official_rating,
                     i.primary_image_tag, i.album_id, i.album_name, i.album_artist, i.artists,
                     i.index_number, i.series_id, i.series_name, i.season_id, i.season_name,
-                    i.parent_index_number
-             FROM items i
+                    i.parent_index_number, i.is_folder, i.premiere_date
+            FROM items i
              INNER JOIN available_items ai ON i.id = ai.id
              WHERE i.server_id = ? AND i.parent_id = ?{}
-             ORDER BY i.sort_name ASC, i.name ASC
+             ORDER BY {}
              LIMIT {} OFFSET {}",
-            type_filter, limit, start_index
+            type_filter, order_by, limit, start_index
         );
 
         let query = Query::with_params(
@@ -556,8 +575,8 @@ impl MediaRepository for OfflineRepository {
                     i.runtime_ticks, i.production_year, i.community_rating, i.official_rating,
                     i.primary_image_tag, i.album_id, i.album_name, i.album_artist, i.artists,
                     i.index_number, i.series_id, i.series_name, i.season_id, i.season_name,
-                    i.parent_index_number
-             FROM items i
+                    i.parent_index_number, i.is_folder, i.premiere_date
+            FROM items i
              INNER JOIN downloaded_items di ON i.id = di.id
              WHERE i.id = ?",
             vec![QueryParam::String(item_id.to_string())],
@@ -601,8 +620,8 @@ impl MediaRepository for OfflineRepository {
                         i.runtime_ticks, i.production_year, i.community_rating, i.official_rating,
                         i.primary_image_tag, i.album_id, i.album_name, i.album_artist, i.artists,
                         i.index_number, i.series_id, i.series_name, i.season_id, i.season_name,
-                        i.parent_index_number
-                 FROM items i
+                        i.parent_index_number, i.is_folder, i.premiere_date
+                FROM items i
                  INNER JOIN downloaded_items di ON i.id = di.id
                  WHERE i.server_id = ? AND i.library_id = ?
                  ORDER BY i.synced_at DESC
@@ -639,8 +658,8 @@ impl MediaRepository for OfflineRepository {
                             i.community_rating, i.official_rating, i.primary_image_tag,
                             i.album_id, i.album_name, i.album_artist, i.artists,
                             i.index_number, i.series_id, i.series_name, i.season_id,
-                            i.season_name, i.parent_index_number
-                     FROM items i
+                            i.season_name, i.parent_index_number, i.is_folder, i.premiere_date
+                    FROM items i
                      JOIN user_data ud ON i.id = ud.item_id
                      INNER JOIN downloads d ON i.id = d.item_id
                      WHERE i.server_id = ? AND ud.user_id = ? AND i.library_id = ?
@@ -664,8 +683,8 @@ impl MediaRepository for OfflineRepository {
                             i.community_rating, i.official_rating, i.primary_image_tag,
                             i.album_id, i.album_name, i.album_artist, i.artists,
                             i.index_number, i.series_id, i.series_name, i.season_id,
-                            i.season_name, i.parent_index_number
-                     FROM items i
+                            i.season_name, i.parent_index_number, i.is_folder, i.premiere_date
+                    FROM items i
                      JOIN user_data ud ON i.id = ud.item_id
                      INNER JOIN downloads d ON i.id = d.item_id
                      WHERE i.server_id = ? AND ud.user_id = ?
@@ -752,8 +771,8 @@ impl MediaRepository for OfflineRepository {
                        i.community_rating, i.official_rating, i.primary_image_tag,
                        i.album_id, i.album_name, i.album_artist, i.artists,
                        i.index_number, i.series_id, i.series_name, i.season_id,
-                       i.season_name, i.parent_index_number
-                FROM ranked_plays rp
+                       i.season_name, i.parent_index_number, i.is_folder, i.premiere_date
+               FROM ranked_plays rp
                 JOIN items i ON rp.display_id = i.id
                 INNER JOIN downloaded_items di ON i.id = di.id
                 ORDER BY rp.most_recent_play DESC",
@@ -800,8 +819,8 @@ impl MediaRepository for OfflineRepository {
                         i.community_rating, i.official_rating, i.primary_image_tag,
                         i.album_id, i.album_name, i.album_artist, i.artists,
                         i.index_number, i.series_id, i.series_name, i.season_id,
-                        i.season_name, i.parent_index_number
-                 FROM items i
+                        i.season_name, i.parent_index_number, i.is_folder, i.premiere_date
+                FROM items i
                  JOIN user_data ud ON i.id = ud.item_id
                  INNER JOIN downloads d ON i.id = d.item_id
                  WHERE i.server_id = ? AND ud.user_id = ? AND i.item_type = 'Movie'
@@ -934,8 +953,8 @@ impl MediaRepository for OfflineRepository {
                     i.community_rating, i.official_rating, i.primary_image_tag,
                     i.album_id, i.album_name, i.album_artist, i.artists,
                     i.index_number, i.series_id, i.series_name, i.season_id,
-                    i.season_name, i.parent_index_number
-             FROM items i
+                    i.season_name, i.parent_index_number, i.is_folder, i.premiere_date
+            FROM items i
              JOIN items_fts fts ON fts.rowid = i.rowid
              INNER JOIN downloaded_items di ON i.id = di.id
              WHERE i.server_id = ? AND items_fts MATCH ?{}
@@ -980,6 +999,21 @@ impl MediaRepository for OfflineRepository {
         Err(RepoError::Offline)
     }
 
+    async fn get_live_tv_channels(&self) -> Result<Vec<MediaItem>, RepoError> {
+        // Live TV is inherently online-only.
+        Err(RepoError::Offline)
+    }
+
+    async fn get_channels(&self) -> Result<SearchResult, RepoError> {
+        // Plugin channels are inherently online-only.
+        Err(RepoError::Offline)
+    }
+
+    async fn open_live_stream(&self, _item_id: &str) -> Result<LiveStreamInfo, RepoError> {
+        // Live streams cannot be opened offline.
+        Err(RepoError::Offline)
+    }
+
     async fn report_playback_start(&self, _item_id: &str, _position_ticks: i64) -> Result<(), RepoError> {
         // Cannot report to server while offline
         Err(RepoError::Offline)
@@ -1071,6 +1105,7 @@ impl MediaRepository for OfflineRepository {
             id: person_data.0,
             name: person_data.1,
             item_type: "Person".to_string(),
+            is_folder: false,
             server_id: self.server_id.clone(),
             parent_id: None,
             library_id: None,
@@ -1078,6 +1113,7 @@ impl MediaRepository for OfflineRepository {
             genres: None,
             runtime_ticks: None,
             production_year: None,
+            premiere_date: None,
             community_rating: None,
             official_rating: None,
             primary_image_tag: person_data.3,
@@ -1131,8 +1167,8 @@ impl MediaRepository for OfflineRepository {
                         i.community_rating, i.official_rating, i.primary_image_tag,
                         i.album_id, i.album_name, i.album_artist, i.artists,
                         i.index_number, i.series_id, i.series_name, i.season_id,
-                        i.season_name, i.parent_index_number
-                 FROM items i
+                        i.season_name, i.parent_index_number, i.is_folder, i.premiere_date
+                FROM items i
                  JOIN item_people ip ON i.id = ip.item_id
                  INNER JOIN downloaded_items di ON i.id = di.id
                  WHERE i.server_id = ? AND ip.person_id = ?
@@ -1242,7 +1278,7 @@ impl MediaRepository for OfflineRepository {
                     i.runtime_ticks, i.production_year, i.community_rating, i.official_rating, \
                     i.primary_image_tag, i.album_id, i.album_name, i.album_artist, i.artists, \
                     i.index_number, i.series_id, i.series_name, i.season_id, i.season_name, \
-                    i.parent_index_number \
+                    i.parent_index_number, i.is_folder, i.premiere_date \
              FROM playlist_items pi \
              JOIN items i ON pi.item_id = i.id \
              WHERE pi.playlist_id = ? \
@@ -1280,6 +1316,8 @@ impl MediaRepository for OfflineRepository {
                     season_id: row.get(21)?,
                     season_name: row.get(22)?,
                     parent_index_number: row.get(23)?,
+                    is_folder: row.get::<_, Option<i64>>(24)?.unwrap_or(0) != 0,
+                    premiere_date: row.get(25)?,
                 };
                 Ok((entry_id.to_string(), cached))
             })
@@ -1446,10 +1484,12 @@ mod tests {
                 parent_id TEXT REFERENCES items(id) ON DELETE CASCADE,
                 name TEXT NOT NULL,
                 item_type TEXT NOT NULL,
+                is_folder INTEGER DEFAULT 0,
                 overview TEXT,
                 genres TEXT,
                 runtime_ticks INTEGER,
                 production_year INTEGER,
+                premiere_date TEXT,
                 community_rating REAL,
                 official_rating TEXT,
                 primary_image_tag TEXT,
@@ -1518,6 +1558,7 @@ mod tests {
             id: id.to_string(),
             name: name.to_string(),
             item_type: "Audio".to_string(),
+            is_folder: false,
             server_id: "test-server".to_string(),
             parent_id: parent_id.map(|s| s.to_string()),
             library_id: None,
@@ -1525,6 +1566,7 @@ mod tests {
             genres: None,
             runtime_ticks: None,
             production_year: None,
+            premiere_date: None,
             community_rating: None,
             official_rating: None,
             primary_image_tag: None,

src-tauri/src/repository/online.rs

@@ -11,6 +11,30 @@ use crate::connectivity::ConnectivityReporter;
 use crate::jellyfin::HttpClient;
 use super::{MediaRepository, types::*};
 
+/// A single actor returned by the JRay plugin's "context at time t" endpoint.
+///
+/// Mirrors the `actors[]` objects from `GET /Plugins/JRay/Items/{id}/jray?t=`.
+/// `jellyfin_id` (a Jellyfin Person item GUID) is preferred for navigation;
+/// the IMDb/TMDb ids are informational fallbacks. Unknown ids are `""`.
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
+pub struct JRayActor {
+    pub name: String,
+    #[serde(default)]
+    pub imdb_id: String,
+    #[serde(default)]
+    pub tmdb_id: String,
+    #[serde(default)]
+    pub jellyfin_id: String,
+}
+
+/// Envelope returned by the JRay `jray?t=` endpoint. Extra keys (future
+/// `locations`, `trivia`, …) are ignored so the client tolerates schema growth.
+#[derive(Debug, Clone, Deserialize)]
+struct JRayContext {
+    #[serde(default)]
+    actors: Vec<JRayActor>,
+}
+
 /// Online repository - fetches data from Jellyfin server via HTTP
 pub struct OnlineRepository {
     http_client: Arc<HttpClient>,
@@ -104,6 +128,20 @@ impl OnlineRepository {
             .map_err(|e| format!("Failed to read bytes: {}", e))
     }
 
+    /// Query the JRay plugin for the actors on screen at time `t` (seconds) in
+    /// the given item. Returns an empty list when the plugin isn't installed or
+    /// has no truth data for the item (HTTP 404), so callers can treat "no JRay"
+    /// and "nobody on screen" identically. Other failures propagate.
+    pub async fn get_jray_actors(&self, item_id: &str, t: f64) -> Result<Vec<JRayActor>, RepoError> {
+        let endpoint = format!("/Plugins/JRay/Items/{}/jray?t={}", item_id, t);
+        match self.get_json::<JRayContext>(&endpoint).await {
+            Ok(context) => Ok(context.actors),
+            // No plugin / no truth data for this item — not an error to the user.
+            Err(RepoError::NotFound { .. }) => Ok(Vec::new()),
+            Err(e) => Err(e),
+        }
+    }
+
     /// Make authenticated GET request
     async fn get_json<T: for<'de> Deserialize<'de>>(&self, endpoint: &str) -> Result<T, RepoError> {
         let result = self.get_json_inner(endpoint).await;
@@ -363,10 +401,13 @@ struct JellyfinItem {
     name: String,
     #[serde(rename = "Type")]
     item_type: String,
+    #[serde(default)]
+    is_folder: bool,
     parent_id: Option<String>,
     overview: Option<String>,
     genres: Option<Vec<String>>,
     production_year: Option<i32>,
+    premiere_date: Option<String>,
     community_rating: Option<f64>,
     official_rating: Option<String>,
     run_time_ticks: Option<i64>,
@@ -450,12 +491,14 @@ impl JellyfinItem {
             id: self.id,
             name: self.name,
             item_type: self.item_type,
+            is_folder: self.is_folder,
             server_id,
             parent_id: self.parent_id,
             library_id: None, // Not provided by Jellyfin API directly
             overview: self.overview,
             genres: self.genres,
             production_year: self.production_year,
+            premiere_date: self.premiere_date,
             community_rating: self.community_rating,
             official_rating: self.official_rating,
             runtime_ticks: self.run_time_ticks,
@@ -583,7 +626,7 @@ impl MediaRepository for OnlineRepository {
         // Request image fields for list views (People only needed in get_item
         // detail view). Genres is needed so cached items carry their genres,
         // which lets the offline store derive genre lists + per-genre counts.
-        endpoint.push_str("&Fields=BackdropImageTags,ParentBackdropImageTags,Genres");
+        endpoint.push_str("&Fields=BackdropImageTags,ParentBackdropImageTags,Genres,PremiereDate");
 
         let response: ItemsResponse = self.get_json(&endpoint).await?;
 
@@ -598,7 +641,7 @@ impl MediaRepository for OnlineRepository {
     }
 
     async fn get_item(&self, item_id: &str) -> Result<MediaItem, RepoError> {
-        let endpoint = format!("/Users/{}/Items/{}?Fields=BackdropImageTags,ParentBackdropImageTags,People,MediaStreams,MediaSources", self.user_id, item_id);
+        let endpoint = format!("/Users/{}/Items/{}?Fields=BackdropImageTags,ParentBackdropImageTags,People,MediaStreams,MediaSources,PremiereDate", self.user_id, item_id);
 
         let item: JellyfinItem = self.get_json(&endpoint).await?;
         let media_item = item.to_media_item(self.user_id.clone());
@@ -728,12 +771,14 @@ impl MediaRepository for OnlineRepository {
                     id: album_id,
                     name: first_track.album_name.clone().unwrap_or_else(|| "Unknown Album".to_string()),
                     item_type: "MusicAlbum".to_string(),
+                    is_folder: true,
                     server_id: first_track.server_id.clone(),
                     parent_id: None,
                     library_id: None,
                     overview: None,
                     genres: None,
                     production_year: None,
+                    premiere_date: None,
                     community_rating: None,
                     official_rating: None,
                     runtime_ticks: None,
@@ -901,7 +946,7 @@ impl MediaRepository for OnlineRepository {
 
         // Request image fields for list views (plus Genres so cached items
         // carry genres for offline genre lists/counts).
-        endpoint.push_str("&Fields=BackdropImageTags,ParentBackdropImageTags,Genres");
+        endpoint.push_str("&Fields=BackdropImageTags,ParentBackdropImageTags,Genres,PremiereDate");
 
         let response: ItemsResponse = self.get_json(&endpoint).await?;
         Ok(SearchResult {
@@ -1139,6 +1184,105 @@ impl MediaRepository for OnlineRepository {
         Ok(url)
     }
 
+    async fn get_live_tv_channels(&self) -> Result<Vec<MediaItem>, RepoError> {
+        // Live TV channels (broadcast tuners / IPTV M3U). Returned as items with
+        // type "TvChannel" — playable via open_live_stream.
+        let endpoint = format!(
+            "/LiveTv/Channels?UserId={}&Fields=PrimaryImageAspectRatio,Overview&EnableImageTypes=Primary",
+            self.user_id
+        );
+        let response: ItemsResponse = self.get_json(&endpoint).await?;
+        Ok(response
+            .items
+            .into_iter()
+            .map(|item| item.to_media_item(self.server_url.clone()))
+            .collect())
+    }
+
+    async fn get_channels(&self) -> Result<SearchResult, RepoError> {
+        // Root list of plugin "Channels". Drill-down into a channel folder reuses
+        // get_items(channel_id, ...).
+        let endpoint = format!("/Channels?UserId={}", self.user_id);
+        let response: ItemsResponse = self.get_json(&endpoint).await?;
+        let total = response.total_record_count;
+        let items = response
+            .items
+            .into_iter()
+            .map(|item| item.to_media_item(self.server_url.clone()))
+            .collect();
+        Ok(SearchResult {
+            items,
+            total_record_count: total,
+        })
+    }
+
+    async fn open_live_stream(&self, item_id: &str) -> Result<LiveStreamInfo, RepoError> {
+        // Live channels require a PlaybackInfo call with AutoOpenLiveStream so the
+        // server opens the live stream and returns a ready-to-play transcoding URL.
+        // We send a minimal request; the server applies its own defaults for live.
+        #[derive(Debug, Serialize)]
+        #[serde(rename_all = "PascalCase")]
+        struct OpenLiveStreamRequest {
+            user_id: String,
+            #[serde(rename = "AutoOpenLiveStream")]
+            auto_open_live_stream: bool,
+            is_playback: bool,
+            max_streaming_bitrate: u64,
+        }
+
+        #[derive(Debug, Deserialize)]
+        #[serde(rename_all = "PascalCase")]
+        struct OpenLiveStreamResponse {
+            #[serde(default)]
+            media_sources: Vec<LiveMediaSource>,
+            play_session_id: Option<String>,
+        }
+
+        #[derive(Debug, Deserialize)]
+        #[serde(rename_all = "PascalCase")]
+        struct LiveMediaSource {
+            id: String,
+            transcoding_url: Option<String>,
+            live_stream_id: Option<String>,
+        }
+
+        let endpoint = format!("/Items/{}/PlaybackInfo", item_id);
+        let request = OpenLiveStreamRequest {
+            user_id: self.user_id.clone(),
+            auto_open_live_stream: true,
+            is_playback: true,
+            max_streaming_bitrate: 20_000_000,
+        };
+
+        let response: OpenLiveStreamResponse =
+            self.post_json_response(&endpoint, &request).await?;
+
+        let source = response.media_sources.into_iter().next().ok_or(RepoError::NotFound {
+            message: "No live media source returned".to_string(),
+        })?;
+
+        // The transcoding URL is server-relative; make it absolute. If the server
+        // did not provide one (rare for live), fall back to the HLS master endpoint.
+        let stream_url = match source.transcoding_url {
+            Some(url) => format!("{}{}", self.server_url, url),
+            None => format!(
+                "{}/Videos/{}/master.m3u8?api_key={}&MediaSourceId={}&LiveStreamId={}&VideoCodec=h264&AudioCodec=aac&TranscodingProtocol=hls&TranscodingContainer=ts",
+                self.server_url,
+                item_id,
+                self.access_token,
+                source.id,
+                source.live_stream_id.clone().unwrap_or_default(),
+            ),
+        };
+
+        Ok(LiveStreamInfo {
+            stream_url,
+            play_session_id: response.play_session_id,
+            live_stream_id: source.live_stream_id,
+            media_source_id: Some(source.id),
+        })
+    }
+
     async fn report_playback_start(
         &self,
         item_id: &str,
@@ -1855,4 +1999,34 @@ mod tests {
         assert_eq!(urlencoding::encode("Star Wars"), "Star%20Wars");
         assert_eq!(urlencoding::encode("Tom & Jerry"), "Tom%20%26%20Jerry");
     }
+
+    #[test]
+    fn test_jray_context_deserializes_actors() {
+        // The jray?t= envelope as documented in the JRay truth file format.
+        let json = r#"{
+            "actors": [
+                { "name": "Tom Hanks", "imdb_id": "nm0000158", "tmdb_id": "31", "jellyfin_id": "abc123-guid" }
+            ]
+        }"#;
+        let ctx: JRayContext = serde_json::from_str(json).expect("should parse");
+        assert_eq!(ctx.actors.len(), 1);
+        assert_eq!(ctx.actors[0].name, "Tom Hanks");
+        assert_eq!(ctx.actors[0].jellyfin_id, "abc123-guid");
+    }
+
+    #[test]
+    fn test_jray_context_ignores_unknown_keys_and_missing_ids() {
+        // Future fields (locations/trivia) must be ignored, and absent id keys
+        // must default to "" rather than failing to parse.
+        let json = r#"{
+            "actors": [ { "name": "Extra" } ],
+            "locations": ["Beach"],
+            "trivia": "filmed in 1994"
+        }"#;
+        let ctx: JRayContext = serde_json::from_str(json).expect("should tolerate extra keys");
+        assert_eq!(ctx.actors.len(), 1);
+        assert_eq!(ctx.actors[0].name, "Extra");
+        assert_eq!(ctx.actors[0].imdb_id, "");
+        assert_eq!(ctx.actors[0].jellyfin_id, "");
+    }
 }

src-tauri/src/repository/types.rs

@@ -104,6 +104,10 @@ pub struct MediaItem {
     pub name: String,
     #[serde(rename = "type")]
     pub item_type: String,
+    /// Whether this item is a folder/container (vs a playable leaf). Used to
+    /// decide whether a channel item drills into a list or plays directly.
+    #[serde(default)]
+    pub is_folder: bool,
     pub server_id: String,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub parent_id: Option<String>,
@@ -115,6 +119,10 @@ pub struct MediaItem {
     pub genres: Option<Vec<String>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub production_year: Option<i32>,
+    /// ISO-8601 release/air date (Jellyfin `PremiereDate`). Used to sort
+    /// podcast episodes by release date.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub premiere_date: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub community_rating: Option<f64>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -249,6 +257,20 @@ pub struct PlaybackInfo {
     pub needs_transcoding: bool,
 }
 
+/// Live stream information returned from opening a Live TV / channel stream.
+///
+/// Unlike on-demand video, a live channel must be "opened" before it can be
+/// streamed; the server returns a transcoding URL (already absolute) plus a
+/// `live_stream_id` that can later be used to close the stream.
+#[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LiveStreamInfo {
+    pub stream_url: String,
+    pub play_session_id: Option<String>,
+    pub live_stream_id: Option<String>,
+    pub media_source_id: Option<String>,
+}
+
 /// Genre
 #[derive(specta::Type, Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -481,12 +503,14 @@ mod tests {
                 id: "1".to_string(),
                 name: "Test".to_string(),
                 item_type: "Audio".to_string(),
+                is_folder: false,
                 server_id: "server1".to_string(),
                 parent_id: None,
                 library_id: None,
                 overview: None,
                 genres: None,
                 production_year: None,
+                premiere_date: None,
                 community_rating: None,
                 official_rating: None,
                 runtime_ticks: None,
@@ -620,12 +644,14 @@ mod tests {
                 id: "track1".to_string(),
                 name: "Test Track".to_string(),
                 item_type: "Audio".to_string(),
+                is_folder: false,
                 server_id: "server1".to_string(),
                 parent_id: None,
                 library_id: None,
                 overview: None,
                 genres: None,
                 production_year: None,
+                premiere_date: None,
                 community_rating: None,
                 official_rating: None,
                 runtime_ticks: None,
@@ -679,12 +705,14 @@ mod tests {
                 id: "1".to_string(),
                 name: "Track".to_string(),
                 item_type: "Audio".to_string(),
+                is_folder: false,
                 server_id: "s1".to_string(),
                 parent_id: None,
                 library_id: None,
                 overview: None,
                 genres: None,
                 production_year: None,
+                premiere_date: None,
                 community_rating: None,
                 official_rating: None,
                 runtime_ticks: None,

src-tauri/src/session_poller/mod.rs

@@ -112,6 +112,18 @@ impl SessionPollerManager {
                 match sessions_result {
                     Ok(sessions) => {
                         debug!("[SessionPoller] Fetched {} sessions", sessions.len());
+
+                        // In remote (cast) mode, mirror the remote session's
+                        // now-playing onto the Android lockscreen. The local
+                        // ExoPlayer is idle while casting, so without this the
+                        // lockscreen shows stale local metadata and a frozen
+                        // scrubber. Driving it here (native poll thread) rather
+                        // than from the WebView keeps it live even when the
+                        // screen is locked and JS timers are throttled.
+                        if let PlaybackMode::Remote { session_id } = mode_manager.get_mode() {
+                            Self::push_remote_lockscreen(&sessions, &session_id);
+                        }
+
                         if let Some(em) = emitter.lock_safe().as_ref() {
                             em.emit(crate::player::PlayerStatusEvent::SessionsUpdated {
                                 sessions,
@@ -150,6 +162,66 @@ impl SessionPollerManager {
         *self.current_hint.write_safe() = hint;
     }
 
+    /// Push the remote session's now-playing onto the Android lockscreen.
+    ///
+    /// Looks up the active remote session by id and forwards its title/artist/
+    /// album, duration and position to the media notification. Silently does
+    /// nothing if the session isn't found or has no now-playing item (e.g. the
+    /// remote stopped) - the next state change will refresh it.
+    fn push_remote_lockscreen(
+        sessions: &[crate::jellyfin::client::SessionInfo],
+        session_id: &str,
+    ) {
+        // 100ns Jellyfin ticks -> milliseconds.
+        const TICKS_PER_MS: i64 = 10_000;
+
+        let Some(session) = sessions
+            .iter()
+            .find(|s| s.id.as_deref() == Some(session_id))
+        else {
+            return;
+        };
+
+        let Some(now_playing) = session.now_playing_item.as_ref() else {
+            return;
+        };
+
+        let title = now_playing.name.clone().unwrap_or_default();
+        let artist = now_playing
+            .artists
+            .as_ref()
+            .map(|a| a.join(", "))
+            .filter(|s| !s.is_empty())
+            .or_else(|| now_playing.album_artist.clone())
+            .unwrap_or_default();
+        let album = now_playing.album.clone();
+        let duration_ms = now_playing.run_time_ticks.unwrap_or(0) / TICKS_PER_MS;
+
+        let (position_ms, is_playing) = session
+            .play_state
+            .as_ref()
+            .map(|ps| {
+                (
+                    ps.position_ticks.unwrap_or(0) / TICKS_PER_MS,
+                    !ps.is_paused.unwrap_or(false),
+                )
+            })
+            .unwrap_or((0, false));
+
+        let meta = crate::player::LockscreenMetadata {
+            title,
+            artist,
+            album,
+            duration_ms,
+            position_ms,
+            is_playing,
+        };
+
+        if let Err(e) = crate::player::update_lockscreen_metadata(&meta) {
+            warn!("[SessionPoller] Failed to update lockscreen metadata: {}", e);
+        }
+    }
+
     /// Calculate polling interval based on mode and hint
     fn calculate_interval(mode: &PlaybackMode, hint: PollingHint) -> u64 {
         match hint {

src-tauri/src/storage/schema.rs

@@ -22,6 +22,7 @@ pub const MIGRATIONS: &[(&str, &str)] = &[
     ("015_device_id", MIGRATION_015),
     ("016_autoplay_max_episodes", MIGRATION_016),
     ("017_downloads_resume_url", MIGRATION_017),
+    ("018_items_is_folder", MIGRATION_018),
 ];
 
 /// Initial schema migration
@@ -680,3 +681,15 @@ const MIGRATION_017: &str = r#"
 ALTER TABLE downloads ADD COLUMN stream_url TEXT;
 ALTER TABLE downloads ADD COLUMN target_dir TEXT;
 "#;
+
+/// Migration to record whether a cached item is a folder/container vs a playable
+/// leaf. Needed so channel items (which can be either) route to the player or to
+/// a browse list correctly. Existing cached rows predate the column and have an
+/// unknown folder flag, so we force a refresh by clearing their `synced_at`,
+/// causing the hybrid repository to re-fetch them from the server on next browse.
+const MIGRATION_018: &str = r#"
+ALTER TABLE items ADD COLUMN is_folder INTEGER DEFAULT 0;
+
+-- Force re-fetch of all cached items so is_folder is populated from the server.
+UPDATE items SET synced_at = NULL;
+"#;

src/lib/api/bindings.ts

@@ -197,6 +197,25 @@ async playerPlayNextEpisode(item: PlayItemRequest) : Promise<PlayerStatus> {
 async playerOnPlaybackEnded(itemId: string | null, repositoryHandle: string | null) : Promise<null> {
     return await TAURI_INVOKE("player_on_playback_ended", { itemId, repositoryHandle });
 },
+/**
+ * Report an HTML5 <video> state change (playing/paused/loading/stopped/idle).
+ */
+async playerReportState(state: string, mediaId: string | null) : Promise<null> {
+    return await TAURI_INVOKE("player_report_state", { state, mediaId });
+},
+/**
+ * Report an HTML5 <video> position tick (seconds). The adapter should throttle
+ * these to roughly match the native backends' ~250ms cadence.
+ */
+async playerReportPosition(position: number, duration: number) : Promise<null> {
+    return await TAURI_INVOKE("player_report_position", { position, duration });
+},
+/**
+ * Report that the HTML5 <video> finished loading and knows its duration.
+ */
+async playerReportMediaLoaded(duration: number) : Promise<null> {
+    return await TAURI_INVOKE("player_report_media_loaded", { duration });
+},
 /**
  * Preload upcoming tracks from the queue
  * This queues background downloads for the next N tracks that aren't already downloaded
@@ -270,6 +289,31 @@ async remoteSessionSetVolume(sessionId: string, volume: number) : Promise<null>
 async remoteSessionToggleMute(sessionId: string) : Promise<null> {
     return await TAURI_INVOKE("remote_session_toggle_mute", { sessionId });
 },
+/**
+ * List current LMS sync groups.
+ */
+async lmsGetSyncGroups() : Promise<LmsSyncGroup[]> {
+    return await TAURI_INVOKE("lms_get_sync_groups");
+},
+/**
+ * Fuse LMS zones into a sync group. `master_mac` keeps playing and the
+ * `slave_macs` zones join it in sync.
+ */
+async lmsCreateSyncGroup(masterMac: string, slaveMacs: string[]) : Promise<null> {
+    return await TAURI_INVOKE("lms_create_sync_group", { masterMac, slaveMacs });
+},
+/**
+ * Remove a single LMS zone from its sync group (decouple one player).
+ */
+async lmsUnsyncPlayer(mac: string) : Promise<null> {
+    return await TAURI_INVOKE("lms_unsync_player", { mac });
+},
+/**
+ * Dissolve an entire LMS sync group, identified by its master's MAC.
+ */
+async lmsDissolveSyncGroup(masterMac: string) : Promise<null> {
+    return await TAURI_INVOKE("lms_dissolve_sync_group", { masterMac });
+},
 /**
  * Set polling frequency hint based on UI state
  */
@@ -322,6 +366,17 @@ async playbackModeGetRemoteStatus() : Promise<RemoteSessionStatus> {
 async playbackModeTransferToLocal(currentItemId: string, positionTicks: number) : Promise<null> {
     return await TAURI_INVOKE("playback_mode_transfer_to_local", { currentItemId, positionTicks });
 },
+/**
+ * Set the transferring flag on the playback mode manager.
+ * 
+ * Used by the frontend remote->local flow to mark the whole two-step sequence
+ * as a transfer, so `player_play_tracks` starts LOCAL playback instead of
+ * casting back to the remote session it's leaving. Always pair `true` with a
+ * later `false` (including on error) so the flag can't stick.
+ */
+async playbackModeSetTransferring(transferring: boolean) : Promise<null> {
+    return await TAURI_INVOKE("playback_mode_set_transferring", { transferring });
+},
 /**
  * Initialize playback reporter (called after login)
  */
@@ -1032,6 +1087,14 @@ async repositoryGetItems(handle: string, parentId: string, options: GetItemsOpti
 async repositoryGetItem(handle: string, itemId: string) : Promise<MediaItem> {
     return await TAURI_INVOKE("repository_get_item", { handle, itemId });
 },
+/**
+ * Query the optional JRay plugin for the actors on screen at time `t`
+ * (seconds) in an item. Returns an empty list when JRay isn't installed or
+ * has no data for the item, so the caller can render nothing without error.
+ */
+async repositoryJrayActorsAt(handle: string, itemId: string, t: number) : Promise<JRayActor[]> {
+    return await TAURI_INVOKE("repository_jray_actors_at", { handle, itemId, t });
+},
 /**
  * Get latest items in a library
  */
@@ -1098,6 +1161,24 @@ async repositoryGetVideoStreamUrl(handle: string, itemId: string, mediaSourceId:
 async repositoryGetAudioStreamUrl(handle: string, itemId: string) : Promise<string> {
     return await TAURI_INVOKE("repository_get_audio_stream_url", { handle, itemId });
 },
+/**
+ * Get Live TV channels (broadcast / IPTV) for browsing
+ */
+async repositoryGetLiveTvChannels(handle: string) : Promise<MediaItem[]> {
+    return await TAURI_INVOKE("repository_get_live_tv_channels", { handle });
+},
+/**
+ * Get the root list of plugin "Channels"
+ */
+async repositoryGetChannels(handle: string) : Promise<SearchResult> {
+    return await TAURI_INVOKE("repository_get_channels", { handle });
+},
+/**
+ * Open a live stream for a Live TV channel / live item
+ */
+async repositoryOpenLiveStream(handle: string, itemId: string) : Promise<LiveStreamInfo> {
+    return await TAURI_INVOKE("repository_open_live_stream", { handle, itemId });
+},
 /**
  * Report playback start
  */
@@ -1499,14 +1580,47 @@ export type ImageOptions = { maxWidth?: number | null; maxHeight?: number | null
  * Image type
  */
 export type ImageType = "Primary" | "Backdrop" | "Banner" | "Thumb" | "Logo"
+/**
+ * A single actor returned by the JRay plugin's "context at time t" endpoint.
+ * 
+ * Mirrors the `actors[]` objects from `GET /Plugins/JRay/Items/{id}/jray?t=`.
+ * `jellyfin_id` (a Jellyfin Person item GUID) is preferred for navigation;
+ * the IMDb/TMDb ids are informational fallbacks. Unknown ids are `""`.
+ */
+export type JRayActor = { name: string; imdb_id?: string; tmdb_id?: string; jellyfin_id?: string }
 /**
  * Library (media collection)
  */
 export type Library = { id: string; name: string; collectionType: string; imageTag?: string | null }
+/**
+ * Live stream information returned from opening a Live TV / channel stream.
+ * 
+ * Unlike on-demand video, a live channel must be "opened" before it can be
+ * streamed; the server returns a transcoding URL (already absolute) plus a
+ * `live_stream_id` that can later be used to close the stream.
+ */
+export type LiveStreamInfo = { streamUrl: string; playSessionId: string | null; liveStreamId: string | null; mediaSourceId: string | null }
+/**
+ * An LMS multi-room sync group, as returned by JellyLMS `/JellyLms/SyncGroups`.
+ * 
+ * Mirrors the plugin's `SyncGroup` model. The master is the sync source; slaves
+ * follow it in lockstep.
+ */
+export type LmsSyncGroup = { masterMac: string; masterName?: string; slaveMacs?: string[]; slaveNames?: string[] }
 /**
  * Media item
  */
-export type MediaItem = { id: string; name: string; type: string; serverId: string; parentId?: string | null; libraryId?: string | null; overview?: string | null; genres?: string[] | null; productionYear?: number | null; communityRating?: number | null; officialRating?: string | null; runTimeTicks?: number | null; primaryImageTag?: string | null; backdropImageTags?: string[] | null; parentBackdropImageTags?: string[] | null; albumId?: string | null; albumName?: string | null; albumArtist?: string | null; artists?: string[] | null; artistItems?: ArtistItem[] | null; indexNumber?: number | null; parentIndexNumber?: number | null; seriesId?: string | null; seriesName?: string | null; seasonId?: string | null; seasonName?: string | null; userData?: UserData | null; mediaStreams?: MediaStream[] | null; mediaSources?: MediaSource[] | null; people?: Person[] | null }
+export type MediaItem = { id: string; name: string; type: string; 
+/**
+ * Whether this item is a folder/container (vs a playable leaf). Used to
+ * decide whether a channel item drills into a list or plays directly.
+ */
+isFolder?: boolean; serverId: string; parentId?: string | null; libraryId?: string | null; overview?: string | null; genres?: string[] | null; productionYear?: number | null; 
+/**
+ * ISO-8601 release/air date (Jellyfin `PremiereDate`). Used to sort
+ * podcast episodes by release date.
+ */
+premiereDate?: string | null; communityRating?: number | null; officialRating?: string | null; runTimeTicks?: number | null; primaryImageTag?: string | null; backdropImageTags?: string[] | null; parentBackdropImageTags?: string[] | null; albumId?: string | null; albumName?: string | null; albumArtist?: string | null; artists?: string[] | null; artistItems?: ArtistItem[] | null; indexNumber?: number | null; parentIndexNumber?: number | null; seriesId?: string | null; seriesName?: string | null; seasonId?: string | null; seasonName?: string | null; userData?: UserData | null; mediaStreams?: MediaStream[] | null; mediaSources?: MediaSource[] | null; people?: Person[] | null }
 /**
  * Media session type tracking the high-level playback context
  */
@@ -1848,6 +1962,13 @@ export type PlayerStatusEvent =
  * Sleep timer state changed
  */
 { type: "sleep_timer_changed"; mode: SleepTimerMode; remaining_seconds: number } | 
+/**
+ * Time-based sleep timer expired: playback must stop. The backend stops
+ * its own (MPV/ExoPlayer) playback, but HTML5 video on Linux plays in the
+ * webview outside the backend's control — the frontend pauses it on this
+ * event.
+ */
+{ type: "sleep_timer_expired" } | 
 /**
  * Show next episode popup with countdown
  */
@@ -1867,7 +1988,15 @@ export type PlayerStatusEvent =
 /**
  * Remote sessions updated (for cast/remote control UI)
  */
-{ type: "sessions_updated"; sessions: SessionInfo[] }
+{ type: "sessions_updated"; sessions: SessionInfo[] } | 
+/**
+ * The user asked to disconnect from the remote session and resume locally.
+ * 
+ * Emitted when the lockscreen Stop button is pressed while casting. The
+ * frontend owns the two-step remote->local transfer (it must reload the
+ * media item locally), so the native side only signals intent here.
+ */
+{ type: "remote_disconnect_requested" }
 /**
  * Result of creating a playlist
  * 
@@ -1884,7 +2013,17 @@ export type PlaylistEntry =
 /**
  * The underlying media item
  */
-({ id: string; name: string; type: string; serverId: string; parentId?: string | null; libraryId?: string | null; overview?: string | null; genres?: string[] | null; productionYear?: number | null; communityRating?: number | null; officialRating?: string | null; runTimeTicks?: number | null; primaryImageTag?: string | null; backdropImageTags?: string[] | null; parentBackdropImageTags?: string[] | null; albumId?: string | null; albumName?: string | null; albumArtist?: string | null; artists?: string[] | null; artistItems?: ArtistItem[] | null; indexNumber?: number | null; parentIndexNumber?: number | null; seriesId?: string | null; seriesName?: string | null; seasonId?: string | null; seasonName?: string | null; userData?: UserData | null; mediaStreams?: MediaStream[] | null; mediaSources?: MediaSource[] | null; people?: Person[] | null }) & { 
+({ id: string; name: string; type: string; 
+/**
+ * Whether this item is a folder/container (vs a playable leaf). Used to
+ * decide whether a channel item drills into a list or plays directly.
+ */
+isFolder?: boolean; serverId: string; parentId?: string | null; libraryId?: string | null; overview?: string | null; genres?: string[] | null; productionYear?: number | null; 
+/**
+ * ISO-8601 release/air date (Jellyfin `PremiereDate`). Used to sort
+ * podcast episodes by release date.
+ */
+premiereDate?: string | null; communityRating?: number | null; officialRating?: string | null; runTimeTicks?: number | null; primaryImageTag?: string | null; backdropImageTags?: string[] | null; parentBackdropImageTags?: string[] | null; albumId?: string | null; albumName?: string | null; albumArtist?: string | null; artists?: string[] | null; artistItems?: ArtistItem[] | null; indexNumber?: number | null; parentIndexNumber?: number | null; seriesId?: string | null; seriesName?: string | null; seasonId?: string | null; seasonName?: string | null; userData?: UserData | null; mediaStreams?: MediaStream[] | null; mediaSources?: MediaSource[] | null; people?: Person[] | null }) & { 
 /**
  * The playlist-scoped entry ID (Jellyfin's PlaylistItemId)
  */

src/lib/api/repository-client.ts

@@ -3,6 +3,7 @@
 // NO direct HTTP calls - everything routes through Rust backend
 
 import { commands } from "./bindings";
+import type { JRayActor } from "./bindings";
 import type { QualityPreset } from "./quality-presets";
 import type {
   Library,
@@ -11,6 +12,7 @@ import type {
   GetItemsOptions,
   SearchOptions,
   PlaybackInfo,
+  LiveStreamInfo,
   ImageType,
   ImageOptions,
   Genre,
@@ -89,6 +91,15 @@ export class RepositoryClient {
     return commands.repositoryGetItem(this.ensureHandle(), itemId);
   }
 
+  /**
+   * Query the optional JRay plugin for the actors on screen at time `t`
+   * (seconds) in an item. Resolves to an empty array when JRay isn't installed
+   * or has no data for the item.
+   */
+  async jrayActorsAt(itemId: string, t: number): Promise<JRayActor[]> {
+    return commands.repositoryJrayActorsAt(this.ensureHandle(), itemId, t);
+  }
+
   async getLatestItems(parentId: string, limit?: number): Promise<MediaItem[]> {
     return commands.repositoryGetLatestItems(this.ensureHandle(), parentId, limit ?? null);
   }
@@ -161,6 +172,23 @@ export class RepositoryClient {
     );
   }
 
+  // ===== Live TV / Channels =====
+
+  /** Browse Live TV channels (broadcast / IPTV). */
+  async getLiveTvChannels(): Promise<MediaItem[]> {
+    return commands.repositoryGetLiveTvChannels(this.ensureHandle());
+  }
+
+  /** Browse the root list of plugin "Channels". Drill-down uses getItems(channelId). */
+  async getChannels(): Promise<SearchResult> {
+    return commands.repositoryGetChannels(this.ensureHandle());
+  }
+
+  /** Open a live stream for a Live TV channel / live item before HLS playback. */
+  async openLiveStream(itemId: string): Promise<LiveStreamInfo> {
+    return commands.repositoryOpenLiveStream(this.ensureHandle(), itemId);
+  }
+
   // ===== URL Construction Methods (sync, no server call) =====
 
   /**

src/lib/api/types.ts

@@ -12,6 +12,7 @@ export type {
   ImageOptions,
   ImageType,
   Library,
+  LiveStreamInfo,
   MediaItem,
   MediaSource,
   MediaStream,
@@ -51,6 +52,7 @@ export type ItemType =
   | "CollectionFolder"
   | "Channel"
   | "ChannelFolderItem"
+  | "TvChannel"
   | "Person";
 
 export type LibraryType =
@@ -63,6 +65,7 @@ export type LibraryType =
   | "boxsets"
   | "playlists"
   | "channels"
+  | "livetv"
   | "unknown";
 
 export type PersonType =

src/lib/components/BottomNav.svelte

@@ -2,6 +2,11 @@
 <script lang="ts">
   import { page } from '$app/stores';
   import { goto } from '$app/navigation';
+  import { library } from '$lib/stores/library';
+
+  // When a className is supplied the parent positions this bar (e.g. inside a
+  // measured in-flow stack); otherwise it self-positions as a fixed bottom bar.
+  let { className = "fixed bottom-0 left-0 right-0 z-40" }: { className?: string } = $props();
 
   // Determine if a route is active
   function isActive(path: string): boolean {
@@ -15,7 +20,7 @@
 </script>
 
 <!-- Navigation bar visible on all platforms -->
-<nav class="fixed bottom-0 left-0 right-0 bg-[var(--color-surface)] border-t border-gray-800 z-40">
+<nav class="{className} bg-[var(--color-surface)] border-t border-gray-800">
   <div class="flex items-center justify-around px-4 py-2">
     <!-- Home Button -->
     <button
@@ -43,7 +48,7 @@
 
     <!-- Library Button -->
     <button
-      onclick={() => goto('/library')}
+      onclick={() => { library.setCurrentLibrary(null); goto('/library'); }}
       class="flex flex-col items-center gap-1 py-2 px-4 transition-colors {isActive('/library') ? 'text-[var(--color-jellyfin)]' : 'text-gray-400 hover:text-white'}"
       aria-label="Library"
     >

src/lib/components/downloads/StorageManagement.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { commands } from "$lib/api/bindings";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import { auth } from "$lib/stores/auth";
   import { downloads } from "$lib/stores/downloads";
   import { goto } from "$app/navigation";
@@ -152,7 +153,7 @@
                 class="flex-1 min-w-0 text-left"
               >
                 <p class="text-sm font-medium text-white truncate group-hover:text-[var(--color-jellyfin)] transition-colors">
-                  {album.album_name}
+                  {truncateMiddle(album.album_name, 40)}
                 </p>
                 <p class="text-xs text-gray-400 truncate">
                   {album.artist_name || "Unknown Artist"} • {album.track_count} {album.track_count === 1 ? "track" : "tracks"}

src/lib/components/library/ArtistDetailView.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { onMount } from "svelte";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import { auth } from "$lib/stores/auth";
   import type { MediaItem } from "$lib/api/types";
   import LibraryGrid from "./LibraryGrid.svelte";
@@ -171,7 +172,7 @@
               {/if}
             </div>
             <p class="text-sm font-medium text-white truncate group-hover:text-[var(--color-jellyfin)] transition-colors">
-              {album.name}
+              {truncateMiddle(album.name, 40)}
             </p>
             {#if album.productionYear}
               <p class="text-xs text-gray-400">{album.productionYear}</p>

src/lib/components/library/EpisodeFocusView.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { goto } from "$app/navigation";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import type { MediaItem } from "$lib/api/types";
   import CachedImage from "$lib/components/common/CachedImage.svelte";
 
@@ -159,7 +160,7 @@
 
         <!-- Episode title -->
         <h1 class="text-4xl font-bold text-white drop-shadow-lg">
-          {episode.name}
+          {truncateMiddle(episode.name, 64)}
         </h1>
 
         <!-- Metadata -->

src/lib/components/library/EpisodeRow.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { onMount } from "svelte";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import type { MediaItem } from "$lib/api/types";
   import { downloads } from "$lib/stores/downloads";
   import { formatDuration } from "$lib/utils/duration";
@@ -134,7 +135,7 @@
             {episodeNumber}.
           </span>
           <h3 class="text-white font-medium truncate group-hover/row:text-[var(--color-jellyfin)] transition-colors">
-            {episode.name}
+            {truncateMiddle(episode.name, 56)}
           </h3>
           <!-- Played indicator -->
           {#if episode.userData?.isPlayed}

src/lib/components/library/GenericGenreBrowser.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { onMount } from "svelte";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import { goto } from "$app/navigation";
   import { navigateBack } from "$lib/utils/navigation";
   import { currentLibrary } from "$lib/stores/library";
@@ -229,7 +230,7 @@
                 />
               </div>
               <p class="font-medium text-white truncate group-hover:text-[var(--color-jellyfin)] transition-colors">
-                {item.name}
+                {truncateMiddle(item.name, 40)}
               </p>
               {#if item.productionYear}
                 <p class="text-sm text-gray-400">

src/lib/components/library/LibraryListView.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { MediaItem, Library } from "$lib/api/types";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import { downloads } from "$lib/stores/downloads";
   import { formatDuration } from "$lib/utils/duration";
   import CachedImage from "$lib/components/common/CachedImage.svelte";
@@ -106,7 +107,7 @@
       <!-- Title & Subtitle -->
       <div class="flex-1 min-w-0 text-left">
         <p class="text-sm font-medium text-white truncate group-hover:text-[var(--color-jellyfin)] transition-colors">
-          {item.name}
+          {truncateMiddle(item.name, 56)}
         </p>
         {#if subtitle}
           <p class="text-xs text-gray-400 truncate">{subtitle}</p>

src/lib/components/library/MediaCard.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { MediaItem, Library } from "$lib/api/types";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import { downloads } from "$lib/stores/downloads";
   import CachedImage from "$lib/components/common/CachedImage.svelte";
 
@@ -166,7 +167,7 @@
 
   <div class="mt-2 space-y-0.5">
     <p class="text-sm font-medium text-white truncate group-hover/card:text-[var(--color-jellyfin)] transition-colors">
-      {item.name}
+      {truncateMiddle(item.name, 40)}
     </p>
     {#if subtitle()}
       <p class="text-xs text-gray-400 truncate">{subtitle()}</p>

src/lib/components/library/PlaylistDetailView.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { onMount } from "svelte";
   import { goto } from "$app/navigation";
-  import { commands } from "$lib/api/bindings";
+  import { playerController } from "$lib/player";
   import type { MediaItem, PlaylistEntry } from "$lib/api/types";
   import { auth } from "$lib/stores/auth";
   import { toast } from "$lib/stores/toast";
@@ -48,10 +48,8 @@
   async function handlePlayAll() {
     if (entries.length === 0) return;
     try {
-      const repo = auth.getRepository();
-      const repositoryHandle = repo.getHandle();
       const trackIds = entries.map(e => e.id);
-      await commands.playerPlayTracks(repositoryHandle, {
+      await playerController.playTracks({
         trackIds,
         startIndex: 0,
         shuffle: false,
@@ -70,10 +68,8 @@
   async function handleShufflePlay() {
     if (entries.length === 0) return;
     try {
-      const repo = auth.getRepository();
-      const repositoryHandle = repo.getHandle();
       const trackIds = entries.map(e => e.id);
-      await commands.playerPlayTracks(repositoryHandle, {
+      await playerController.playTracks({
         trackIds,
         startIndex: 0,
         shuffle: true,

src/lib/components/library/TrackList.svelte

@@ -1,9 +1,9 @@
 <script lang="ts">
-  import { commands } from "$lib/api/bindings";
+  import { playerController } from "$lib/player";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import type { PlayTracksContext } from "$lib/api/bindings";
   import { goto } from "$app/navigation";
   import { queue } from "$lib/stores/queue";
-  import { auth } from "$lib/stores/auth";
   import { currentMedia } from "$lib/stores/player";
   import { toast } from "$lib/stores/toast";
   import type { MediaItem } from "$lib/api/types";
@@ -53,17 +53,10 @@
     try {
       isPlayingTrack = track.id;
 
-      // Validate auth before proceeding
-      const repo = auth.getRepository();
-      if (!repo) {
-        throw new Error("Not authenticated");
-      }
-
       // If this is an album, use the backend album command (more efficient)
       if (context && context.type === "album") {
-        const repositoryHandle = repo.getHandle();
         console.log(`[TrackList] Playing track: "${track.name}" (ID: ${track.id}, index in list: ${index})`);
-        await commands.playerPlayAlbumTrack(repositoryHandle, {
+        await playerController.playAlbumTrack({
           albumId: context.albumId,
           albumName: context.albumName,
           trackId: track.id,
@@ -74,7 +67,6 @@
 
       // Use new backend command for non-album contexts (playlists, custom queues, etc.)
       // Backend handles all metadata fetching and queue building
-      const repositoryHandle = repo.getHandle();
       const trackIds = tracks.map((t) => t.id);
 
       // Determine context for queue
@@ -89,7 +81,7 @@
         playContext = { type: "custom", label: null };
       }
 
-      await commands.playerPlayTracks(repositoryHandle, {
+      await playerController.playTracks({
         trackIds,
         startIndex: index,
         shuffle: false,
@@ -242,7 +234,7 @@
             <span
               class="text-white font-medium truncate group-hover:text-[var(--color-jellyfin)] transition-colors {currentlyPlayingId === track.id ? 'text-[var(--color-jellyfin)]' : ''}"
             >
-              {track.name}
+              {truncateMiddle(track.name, 48)}
             </span>
           </div>
 
@@ -356,7 +348,7 @@
               {#if currentlyPlayingId === track.id}
                 <span class="inline-block mr-1">▶</span>
               {/if}
-              {track.name}
+              {truncateMiddle(track.name, 48)}
             </p>
             <p class="text-sm text-gray-400 truncate flex flex-wrap items-center gap-1">
               {#if showArtist && showAlbum}

src/lib/components/player/AudioPlayer.svelte

@@ -1,9 +1,9 @@
 <!-- TRACES: UR-004, UR-005, UR-028 | DR-009 -->
 <script lang="ts">
-  import { commands } from "$lib/api/bindings";
+  import { playerController } from "$lib/player";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import { goto } from "$app/navigation";
   import type { MediaItem } from "$lib/api/types";
-  import { auth } from "$lib/stores/auth";
   import { sleepTimerActive } from "$lib/stores/sleepTimer";
   import { queue, queueItems, currentQueueIndex } from "$lib/stores/queue";
   import {
@@ -74,28 +74,28 @@
   async function handleSeekEnd() {
     seeking = false;
     seekPending = true; // Keep showing target position until backend catches up
-    await commands.playerSeek(seekValue);
+    await playerController.seek(seekValue);
   }
 
   // Control handlers for Controls component
   async function handlePlayPause() {
-    await commands.playerToggle();
+    await playerController.toggle();
   }
 
   async function handlePrevious() {
-    await commands.playerPrevious();
+    await playerController.previous();
   }
 
   async function handleNext() {
-    await commands.playerNext();
+    await playerController.next();
   }
 
   async function handleToggleShuffle() {
-    await commands.playerToggleShuffle();
+    await playerController.toggleShuffle();
   }
 
   async function handleCycleRepeat() {
-    await commands.playerCycleRepeat();
+    await playerController.cycleRepeat();
   }
 
   // Prefer album ID for artwork (all tracks in an album share the same cover)
@@ -128,7 +128,7 @@
   async function handleQueueItemClick(index: number) {
     try {
       queue.skipTo(index);
-      await commands.playerSkipTo(index);
+      await playerController.skipTo(index);
     } catch (e) {
       console.error("Failed to skip to queue item:", e);
     }
@@ -242,7 +242,7 @@
     <div class="p-6 space-y-6 flex-shrink-0">
       <!-- Title & Artist -->
       <div class="text-center">
-        <h1 class="text-2xl font-bold text-white truncate">{displayMedia?.name}</h1>
+        <h1 class="text-2xl font-bold text-white truncate">{truncateMiddle(displayMedia?.name, 48)}</h1>
         <div class="text-lg text-gray-400 mt-1 flex items-center justify-center gap-1 flex-wrap">
           {#if displayMedia?.artistItems?.length}
             {#each displayMedia?.artistItems as artist, i}

src/lib/components/player/MiniPlayer.svelte

@@ -14,7 +14,8 @@
    * @req: UR-010 - Control playback of Jellyfin remote sessions
    */
 
-  import { commands } from "$lib/api/bindings";
+  import { playerController } from "$lib/player";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import { goto } from "$app/navigation";
   import type { MediaItem } from "$lib/api/types";
   import { auth } from "$lib/stores/auth";
@@ -105,23 +106,23 @@
 
   // Control handlers for Controls component
   async function handlePlayPause() {
-    await commands.playerToggle();
+    await playerController.toggle();
   }
 
   async function handlePrevious() {
-    await commands.playerPrevious();
+    await playerController.previous();
   }
 
   async function handleNext() {
-    await commands.playerNext();
+    await playerController.next();
   }
 
   async function handleToggleShuffle() {
-    await commands.playerToggleShuffle();
+    await playerController.toggleShuffle();
   }
 
   async function handleCycleRepeat() {
-    await commands.playerCycleRepeat();
+    await playerController.cycleRepeat();
   }
 
   // Scrubbing (seek) handler
@@ -133,7 +134,7 @@
     const newPosition = percent * displayDuration;
 
     try {
-      await commands.playerSeek(newPosition);
+      await playerController.seek(newPosition);
       haptics.tap();
     } catch (err) {
       console.error("Failed to seek:", err);
@@ -322,7 +323,7 @@
           <div
             class="text-sm font-medium text-white truncate block w-full text-left"
           >
-            {displayMedia?.name}
+            {truncateMiddle(displayMedia?.name, 40)}
           </div>
           <div class="text-xs text-gray-400 truncate flex items-center gap-1">
             {#if displayMedia?.artistItems?.length}

src/lib/components/player/Queue.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
-  import { commands } from "$lib/api/bindings";
+  import { playerController } from "$lib/player";
+  import { truncateMiddle } from "$lib/utils/truncateMiddle";
   import { dndzone, SOURCES, TRIGGERS } from "svelte-dnd-action";
   import type { MediaItem } from "$lib/api/types";
   import { auth } from "$lib/stores/auth";
@@ -79,7 +80,7 @@
         queue.moveInQueue(fromIndex, toIndex);
 
         // Sync with backend
-        await commands.playerMoveInQueue(fromIndex, toIndex);
+        await playerController.moveInQueue(fromIndex, toIndex);
       } catch (e) {
         console.error("Failed to move queue item:", e);
         // The store already updated optimistically, refresh if needed
@@ -106,7 +107,7 @@
     e.stopPropagation();
     try {
       queue.removeFromQueue(index);
-      await commands.playerRemoveFromQueue(index);
+      await playerController.removeFromQueue(index);
     } catch (err) {
       console.error("Failed to remove from queue:", err);
     }
@@ -198,7 +199,7 @@
                 <!-- Info -->
                 <div class="flex-1 min-w-0">
                   <p class="text-sm font-medium truncate {currentIndex === index ? 'text-[var(--color-jellyfin)]' : 'text-white'}">
-                    {item.name}
+                    {truncateMiddle(item.name, 48)}
                   </p>
                   {#if item.artists?.length}
                     <p class="text-xs text-gray-400 truncate">

src/lib/components/player/VideoPlayer.scrubRegression.test.ts

@@ -0,0 +1,221 @@
+/**
+ * VideoPlayer scrub regression tests (Android backend path)
+ *
+ * Reproduces the reported bug: with a sleep timer active, scrubbing the
+ * video seek bar "seeks, then jumps back to the old position".
+ *
+ * Root cause history:
+ * - Native init called onDestroy() after an await -> lifecycle_outside_component
+ *   -> the catch treated init as failed and silently flipped useHtml5Element to
+ *   true, so seeks went down the HTML5 path while ExoPlayer kept playing.
+ * - The native SurfaceView has never been visible through the webview, so the
+ *   INTERIM behavior (until the video-player API refactor) is: when the backend
+ *   reports native mode, VideoPlayer deliberately overrides to HTML5 rendering
+ *   and stops the native backend (single audio source, webview owns playback).
+ *
+ * These tests pin the interim behavior: Android's native response is
+ * overridden, the backend is stopped exactly once, and scrubbing keeps
+ * working (and holds its position) with a sleep timer active.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ---- Mocks (must precede component import) --------------------------------
+
+const channelHandlers: Record<string, (event: any) => void> = {};
+vi.mock("@tauri-apps/api/event", () => ({
+  listen: vi.fn(async (channel: string, handler: any) => {
+    channelHandlers[channel] = handler;
+    return () => {
+      delete channelHandlers[channel];
+    };
+  }),
+}));
+
+vi.mock("@tauri-apps/api/core", () => ({
+  invoke: vi.fn(),
+}));
+
+const playerPlayItem = vi.fn(async () => ({
+  // What Android reports: native ExoPlayer backend
+  useHtml5Element: false,
+  backend: "exoplayer",
+  state: { kind: "playing" },
+}));
+const playerSeekVideo = vi.fn(async (_h: string, position: number) => ({
+  strategy: "native",
+  position,
+}));
+const playerStop = vi.fn(async () => ({}));
+const playerToggle = vi.fn(async () => ({ state: "playing" }));
+const playerSetSleepTimer = vi.fn(async (mode: any) => ({ mode, remainingSeconds: 0 }));
+const playerCancelSleepTimer = vi.fn(async () => ({ mode: { kind: "off" }, remainingSeconds: 0 }));
+
+vi.mock("$lib/api/bindings", () => ({
+  commands: {
+    playerPlayItem: (...a: any[]) => playerPlayItem(...(a as [])),
+    playerSeekVideo: (...a: any[]) => playerSeekVideo(...(a as [string, number])),
+    playerStop: (...a: any[]) => playerStop(...(a as [])),
+    playerToggle: (...a: any[]) => playerToggle(...(a as [])),
+    playerSetSleepTimer: (...a: any[]) => playerSetSleepTimer(...(a as [any])),
+    playerCancelSleepTimer: (...a: any[]) => playerCancelSleepTimer(...(a as [])),
+    playerSetSubtitleTrack: vi.fn(async () => ({})),
+    playerSwitchAudioTrack: vi.fn(async () => ({})),
+    storageGetSeriesAudioPreference: vi.fn(async () => null),
+    storageSaveSeriesAudioPreference: vi.fn(async () => ({})),
+  },
+  events: {
+    playerStatusEvent: { listen: vi.fn(async () => () => {}) },
+  },
+}));
+
+vi.mock("$lib/stores/auth", () => ({
+  auth: {
+    getUserId: () => "user-1",
+    getRepository: () => ({
+      getHandle: () => "repo-1",
+      getSubtitleUrl: async () => "",
+      jrayActorsAt: async () => [],
+    }),
+  },
+}));
+
+vi.mock("$app/navigation", () => ({
+  goto: vi.fn(),
+}));
+
+// Use the REAL sleepTimer store module so timer activation flows exactly as
+// in production (playerEvents.ts writes to it on every backend tick).
+
+import { render, fireEvent, waitFor } from "@testing-library/svelte";
+import { tick } from "svelte";
+import VideoPlayer from "./VideoPlayer.svelte";
+import { sleepTimer, sleepTimerExpiredSignal } from "$lib/stores/sleepTimer";
+import type { MediaItem } from "$lib/api/types";
+
+function makeEpisode(): MediaItem {
+  return {
+    id: "ep1",
+    name: "Episode 1",
+    type: "Episode",
+    runTimeTicks: 24 * 60 * 10_000_000, // 24 min
+  } as MediaItem;
+}
+
+/** Simulate one backend sleep-timer tick, exactly as playerEvents.ts does. */
+function sleepTimerTick(remaining = 2) {
+  sleepTimer.set({
+    mode: { kind: "episodes", remaining },
+    remainingSeconds: 0,
+  });
+}
+
+async function mountAndroidPlayer() {
+  const utils = render(VideoPlayer, {
+    props: {
+      media: makeEpisode(),
+      streamUrl: "http://server/videos/ep1/master.m3u8",
+      mediaSourceId: "src-1",
+      needsTranscoding: false,
+      onClose: vi.fn(),
+    },
+  });
+
+  // Init: backend reports native, component overrides to HTML5 and stops it.
+  await waitFor(() => expect(playerPlayItem).toHaveBeenCalled());
+  await waitFor(() => expect(playerStop).toHaveBeenCalled());
+
+  const slider = utils.container.querySelector(
+    'input[type="range"]'
+  ) as HTMLInputElement;
+  const video = utils.container.querySelector("video") as HTMLVideoElement;
+  expect(slider).not.toBeNull();
+  expect(video).not.toBeNull();
+  return { ...utils, slider, video };
+}
+
+/** Scrub the seek bar to `target` seconds like a user drag. */
+async function scrubTo(
+  slider: HTMLInputElement,
+  video: HTMLVideoElement,
+  target: number
+) {
+  await fireEvent.mouseDown(slider);
+  slider.value = String(target);
+  await fireEvent.input(slider);
+  await fireEvent.change(slider);
+  await fireEvent.mouseUp(slider);
+  // Resolve the "wait for seeked" step of the HTML5 native-seek path.
+  await fireEvent(video, new Event("seeked"));
+  await tick();
+}
+
+describe("VideoPlayer scrubbing with active sleep timer (Android)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    for (const key of Object.keys(channelHandlers)) delete channelHandlers[key];
+    sleepTimer.set({ mode: { kind: "off" }, remainingSeconds: 0 });
+    sleepTimerExpiredSignal.set(0);
+  });
+
+  it("overrides the native backend response to HTML5 rendering and stops the backend once", async () => {
+    await mountAndroidPlayer();
+    // The native backend must be stopped so it doesn't play audio behind the
+    // webview (frozen picture + double audio source).
+    expect(playerStop).toHaveBeenCalledTimes(1);
+  });
+
+  it("scrubbing without a timer seeks via the HTML5 path and keeps the new position", async () => {
+    const { slider, video } = await mountAndroidPlayer();
+
+    await scrubTo(slider, video, 600);
+
+    await waitFor(() =>
+      expect(playerSeekVideo).toHaveBeenCalledWith(
+        "repo-1",
+        600,
+        "src-1",
+        null,
+        true // HTML5 path: the webview owns playback after the override
+      )
+    );
+    expect(parseFloat(slider.value)).toBeCloseTo(600);
+  });
+
+  it("scrubbing still works (and holds position) after enabling an episodes sleep timer", async () => {
+    const { slider, video } = await mountAndroidPlayer();
+
+    // Enable "2 more episodes" timer; backend then ticks every second.
+    sleepTimerTick(2);
+    await tick();
+    sleepTimerTick(2);
+    await tick();
+
+    await scrubTo(slider, video, 600);
+    await waitFor(() => expect(playerSeekVideo).toHaveBeenCalledTimes(1));
+    expect(parseFloat(slider.value)).toBeCloseTo(600);
+
+    // Timer ticks after the seek must not snap the bar back.
+    sleepTimerTick(2);
+    await tick();
+    expect(parseFloat(slider.value)).toBeCloseTo(600);
+
+    // A second scrub must also work.
+    await scrubTo(slider, video, 900);
+    await waitFor(() => expect(playerSeekVideo).toHaveBeenCalledTimes(2));
+    expect(parseFloat(slider.value)).toBeCloseTo(900);
+  });
+
+  it("sleep-timer ticks alone never move the seek bar", async () => {
+    const { slider } = await mountAndroidPlayer();
+
+    const before = slider.value;
+    for (let i = 0; i < 5; i++) {
+      sleepTimerTick(2);
+      await tick();
+    }
+
+    expect(slider.value).toBe(before);
+    expect(playerSeekVideo).not.toHaveBeenCalled();
+  });
+});

src/lib/components/player/VideoPlayer.svelte

@@ -1,7 +1,9 @@
 <!-- TRACES: UR-003, UR-005, UR-020, UR-021, UR-026 | DR-010, DR-023, DR-024 -->
 <script lang="ts">
   import { onMount, onDestroy, untrack } from "svelte";
+  import { goto } from "$app/navigation";
   import { commands } from "$lib/api/bindings";
+  import type { JRayActor } from "$lib/api/bindings";
   import { listen } from "@tauri-apps/api/event";
   import Hls from "hls.js";
   import type { MediaItem } from "$lib/api/types";
@@ -10,7 +12,9 @@
   import SleepTimerModal from "./SleepTimerModal.svelte";
   import SleepTimerIndicator from "./SleepTimerIndicator.svelte";
   import CachedImage from "../common/CachedImage.svelte";
-  import { sleepTimerActive } from "$lib/stores/sleepTimer";
+  import { sleepTimerActive, sleepTimerExpiredSignal } from "$lib/stores/sleepTimer";
+  import { playbackPosition } from "$lib/stores/player";
+  import * as html5Adapter from "$lib/player/html5Adapter";
 
   interface Props {
     media: MediaItem | null;
@@ -30,9 +34,10 @@
     onEnded?: () => void; // Called when video playback ends naturally
     onNext?: () => void; // Called when user clicks next episode button
     hasNext?: boolean; // Whether there is a next episode available
+    isLive?: boolean; // Live stream (Live TV) - no seek bar, no resume, no progress reporting
   }
 
-  let { media, streamUrl, mediaSourceId, initialPosition, needsTranscoding = false, onClose, onSeek, onReportProgress, onReportStart, onReportStop, onEnded, onNext, hasNext = false }: Props = $props();
+  let { media, streamUrl, mediaSourceId, initialPosition, needsTranscoding = false, onClose, onSeek, onReportProgress, onReportStart, onReportStop, onEnded, onNext, hasNext = false, isLive = false }: Props = $props();
 
   // The id this player instance reports progress against. Snapshotted from the
   // media prop so a late reportStop (e.g. from onDestroy during autoplay
@@ -85,6 +90,16 @@
 
   // Backend info from Rust (Rust decides which backend to use based on platform)
   let useHtml5Element = $state(true); // Default to HTML5, Rust will override if using native backend
+  let backendChosen = false; // playerPlayItem succeeded and told us which backend to use
+  let nativeUnlisteners: Array<() => void> = []; // raw-channel listeners for native backend mode
+  // Position updates captured before a native seek can land after it and snap
+  // the bar back; suppress backend position feeds briefly after each seek
+  // (same idea as the MPV backend's last_seek_time suppression).
+  let lastNativeSeekAt = 0;
+  const NATIVE_SEEK_SETTLE_MS = 1500;
+  function nativeSeekSettling(): boolean {
+    return Date.now() - lastNativeSeekAt < NATIVE_SEEK_SETTLE_MS;
+  }
   let didStartNativePlayback = $state(false); // Track if we started playback (to know if we should stop on unmount)
   let didStopBackendEarly = $state(false); // Track if we stopped backend early for non-transcoded content
   let swipeType = $state<"brightness" | null>(null);
@@ -200,11 +215,39 @@
       seekOffset = 0;
       isMediaReady = false; // Reset to loading state when stream URL changes
       hasPerformedInitialSeek = false; // Reset so new video can seek to initial position
+      lastAppliedInitialPosition = undefined; // New stream - forget the previously-applied resume point
       endedFired = false; // New stream loaded - allow onEnded to fire again
+      html5Adapter.resetReporting(); // New stream - clear position-report throttle
     }
   });
 
 
+  // Pause playback when the time-based sleep timer expires. The backend stops
+  // its own (MPV/ExoPlayer) playback itself, but the HTML5 <video> element
+  // plays in the webview outside the backend's control, so it must be paused
+  // here or the sleep timer never actually stops video playback on Linux.
+  let lastSleepExpirySeen = $sleepTimerExpiredSignal;
+  $effect(() => {
+    if ($sleepTimerExpiredSignal !== lastSleepExpirySeen) {
+      lastSleepExpirySeen = $sleepTimerExpiredSignal;
+      if (useHtml5Element && videoElement && !videoElement.paused) {
+        console.log("[VideoPlayer] Sleep timer expired - pausing playback");
+        videoElement.pause();
+      }
+    }
+  });
+
+  // Native backend (Android ExoPlayer): drive the seek bar from the player
+  // store, which is fed by the backend's PositionUpdate events. The legacy
+  // "player://position-update" raw channel was never emitted by the backend,
+  // so without this the bar only moves when the user scrubs.
+  $effect(() => {
+    const position = $playbackPosition;
+    if (!useHtml5Element && !isDraggingSeekBar && !isSeeking && !nativeSeekSettling()) {
+      currentTime = position;
+    }
+  });
+
   // Set up HLS.js for HLS streams
   $effect(() => {
     if (!useHtml5Element || !videoElement || !currentStreamUrl) {
@@ -278,6 +321,25 @@
           console.log('[VideoPlayer] HLS manifest parsed, ready to play');
         });
 
+        // On the Android WebView the element's own `canplay` may not fire for
+        // MSE-fed HLS, so treat the first buffered fragment as "ready" too.
+        // This reveals the <video> element (otherwise it stays invisible behind
+        // the black poster card while audio plays).
+        hls.on(Hls.Events.FRAG_BUFFERED, () => {
+          markMediaReady();
+        });
+
+        // The canplay-fallback timeout is normally armed from the element's
+        // `loadstart` event, but with hls.js the element's `src` is "" and
+        // `loadstart` may not fire, so arm a backstop here directly.
+        if (canplayFallbackTimeout) clearTimeout(canplayFallbackTimeout);
+        canplayFallbackTimeout = setTimeout(() => {
+          if (!isMediaReady && videoElement && videoElement.readyState >= 2) {
+            console.warn('[VideoPlayer] HLS canplay fallback - revealing video (readyState:', videoElement.readyState, ')');
+            markMediaReady();
+          }
+        }, 5000);
+
         // Reset recovery attempts for new HLS instance
         hlsFatalRecoveryAttempts = 0;
 
@@ -370,18 +432,36 @@
     }
   });
 
-  // Handle initial position changes (for resuming same video from different position)
+  // Handle initial position changes (for resuming the *same* loaded video from a
+  // different position, e.g. the resume point is re-chosen without a reload).
+  //
+  // This must only react to a genuine change of the `initialPosition` prop to a
+  // value we haven't already applied. The previous version re-fired on the very
+  // first seek (it also depended on, and wrote, `hasPerformedInitialSeek`), and
+  // since seeking a transcoded/HLS stream re-buffers and fires `canplay` again,
+  // the two seek paths ping-ponged forever — the player appeared to pause/resume
+  // in a loop. We now snapshot the last-applied position and only seek when the
+  // prop actually moves to a new value, untracking the writes so this effect
+  // can't re-trigger itself.
+  let lastAppliedInitialPosition = $state<number | undefined>(undefined);
   $effect(() => {
-    // Track initialPosition changes - if it changes and video is ready, seek to new position
     const pos = initialPosition;
-    if (pos && pos > 0 && isMediaReady && videoElement && hasPerformedInitialSeek) {
-      // Position changed after initial seek was done - seek to new position
-      console.log("[VideoPlayer] Initial position changed, seeking to:", pos);
-      hasPerformedInitialSeek = false; // Reset flag to allow handleCanPlay to seek
-      // Trigger seek directly since canplay won't fire for same video
-      videoElement.currentTime = pos;
-      currentTime = pos;
+    if (!pos || pos <= 0 || !isMediaReady) return;
+    // Only act on a real change to a not-yet-applied position.
+    if (pos === untrack(() => lastAppliedInitialPosition)) return;
+    // Skip the very first application; handleCanPlay owns the initial seek.
+    if (!untrack(() => hasPerformedInitialSeek)) {
+      lastAppliedInitialPosition = pos;
+      return;
     }
+    untrack(() => {
+      console.log("[VideoPlayer] Initial position changed, seeking to:", pos);
+      lastAppliedInitialPosition = pos;
+      if (videoElement) {
+        videoElement.currentTime = pos;
+        currentTime = pos;
+      }
+    });
   });
 
   // Set up progress reporting interval
@@ -428,11 +508,30 @@
 
         // Rust tells us which backend it's using
         useHtml5Element = response.useHtml5Element;
+        backendChosen = true;
         console.log(`[VideoPlayer] Backend: ${response.backend}, useHtml5Element: ${useHtml5Element}`);
 
+        // INTERIM (until the video-player API refactor lands): always render
+        // through the webview HTML5 element, including Android. The native
+        // ExoPlayer SurfaceView sits behind an opaque webview and has never
+        // actually been visible (an init bug kept the app on the HTML5 path
+        // since the POC), so true native mode plays audio behind a frozen
+        // picture. Stop the native backend and let the webview own playback,
+        // matching Linux behavior and avoiding dual audio.
+        if (!useHtml5Element) {
+          console.warn("[VideoPlayer] Native video backend reported - overriding to HTML5 rendering (native surface not visible through webview)");
+          useHtml5Element = true;
+          try {
+            await commands.playerStop();
+            didStopBackendEarly = true;
+          } catch (err) {
+            console.warn("[VideoPlayer] Failed to stop native backend:", err);
+          }
+        }
+
         // If using HTML5 element for non-transcoded content, stop the backend player
         // For transcoded content, we need to keep the backend running to handle seeking/audio track switching
-        if (useHtml5Element && !needsTranscoding) {
+        if (useHtml5Element && !needsTranscoding && !didStopBackendEarly) {
           try {
             console.log("[VideoPlayer] Using HTML5 for direct stream - stopping backend player to prevent dual audio");
             await commands.playerStop();
@@ -449,38 +548,48 @@
         if (!useHtml5Element) {
           // Using native backend, subscribe to player events
           didStartNativePlayback = true; // Track that we started native playback
-          const unlisten1 = await listen("player://position-update", (event: any) => {
-            if (!isDraggingSeekBar) {
-              currentTime = event.payload.position;
-            }
-          });
-
-          const unlisten2 = await listen("player://state-changed", (event: any) => {
-            isPlaying = event.payload.state === "playing";
-          });
-
-          // Clean up listeners on destroy
-          onDestroy(() => {
-            unlisten1();
-            unlisten2();
-          });
+          isPlaying = (response.state?.kind ?? response.state) === "playing";
+          // Cleanup happens in the component's top-level onDestroy. Calling
+          // onDestroy() here — after an await — throws lifecycle_outside_component,
+          // which the catch below used to misread as an init failure: it flipped
+          // useHtml5Element to true, so every seek went down the HTML5 path and
+          // never reached ExoPlayer (the video "seeked" then snapped back).
+          nativeUnlisteners.push(
+            await listen("player://position-update", (event: any) => {
+              if (!isDraggingSeekBar && !isSeeking && !nativeSeekSettling()) {
+                currentTime = event.payload.position;
+              }
+            })
+          );
+          nativeUnlisteners.push(
+            await listen("player://state-changed", (event: any) => {
+              isPlaying = event.payload.state === "playing";
+            })
+          );
         }
       } catch (err) {
         console.error("[VideoPlayer] Failed to initialize player:", err);
-        // Fallback to HTML5 on error
-        useHtml5Element = true;
-
-        // For non-transcoded content, try to stop any backend player that might have started
-        if (!needsTranscoding) {
-          try {
-            await commands.playerStop();
-            didStopBackendEarly = true;
-          } catch (stopErr) {
-            // Ignore errors when stopping
-          }
+        if (backendChosen) {
+          // The backend already accepted the item; a later error (e.g. event
+          // subscription) must not silently switch the seek/controls path to
+          // HTML5 while the native backend keeps playing.
+          console.warn("[VideoPlayer] Backend already initialized - keeping native mode despite error");
         } else {
-          // For transcoded content, keep backend for seeking
-          didStartNativePlayback = true;
+          // Fallback to HTML5 on error
+          useHtml5Element = true;
+
+          // For non-transcoded content, try to stop any backend player that might have started
+          if (!needsTranscoding) {
+            try {
+              await commands.playerStop();
+              didStopBackendEarly = true;
+            } catch (stopErr) {
+              // Ignore errors when stopping
+            }
+          } else {
+            // For transcoded content, keep backend for seeking
+            didStartNativePlayback = true;
+          }
         }
       }
     }
@@ -488,12 +597,15 @@
     // Load series audio preference (for TV shows)
     await loadSeriesAudioPreference();
 
-    // Report progress every 10 seconds while playing
-    progressInterval = setInterval(() => {
-      if (isPlaying && !isSeeking && onReportProgress) {
-        onReportProgress(currentTime, false, reportMediaId);
-      }
-    }, 10000);
+    // Report progress every 10 seconds while playing. Live streams have no
+    // meaningful position to report, so skip progress reporting entirely.
+    if (!isLive) {
+      progressInterval = setInterval(() => {
+        if (isPlaying && !isSeeking && onReportProgress) {
+          onReportProgress(currentTime, false, reportMediaId);
+        }
+      }, 10000);
+    }
 
     // Debug logging every second
     debugLogInterval = setInterval(() => {
@@ -528,6 +640,12 @@
       clearInterval(debugLogInterval);
     }
 
+    // Remove native backend event listeners
+    for (const unlisten of nativeUnlisteners) {
+      unlisten();
+    }
+    nativeUnlisteners = [];
+
     // Clean up HLS.js instance - prevent dual audio on unmount
     if (hls) {
       console.log("[VideoPlayer] Destroying HLS.js instance on unmount");
@@ -555,8 +673,8 @@
       }
     }
 
-    // Report stop when component is destroyed
-    if (onReportStop && currentTime > 0) {
+    // Report stop when component is destroyed (skip for live - no resume tracking)
+    if (!isLive && onReportStop && currentTime > 0) {
       onReportStop(currentTime, reportMediaId);
     }
   });
@@ -567,6 +685,9 @@
       const newCurrentTime = seekOffset + videoElement.currentTime;
       if (videoElement.readyState >= 2) {
         currentTime = newCurrentTime;
+        // Feed the Rust controller a throttled position tick (~250ms) so it
+        // stays the source of truth for HTML5 video without flooding IPC.
+        html5Adapter.reportPosition(currentTime, duration);
       }
     }
 
@@ -616,6 +737,10 @@
       console.log("[VideoPlayer] videoDuration state is now:", videoDuration);
     }
 
+    // Tell the Rust controller the media is loaded and its duration (mirrors the
+    // native MediaLoaded event so the backend has a duration for HTML5 video).
+    html5Adapter.reportMediaLoaded(duration);
+
     // Use setTimeout to log the derived value after reactive updates
     setTimeout(() => {
       console.log("[VideoPlayer] Derived duration value:", duration);
@@ -623,6 +748,20 @@
     }, 0);
   }
 
+  // Flip out of the Loading state and reveal the <video> element (which is
+  // `invisible` and covered by the black poster card until then). Multiple
+  // signals can legitimately mean "ready": the native `canplay` event, hls.js
+  // buffering its first fragment, or the element actually reaching `playing`.
+  // On the Android system WebView the HLS path feeds the element through MSE
+  // with `src=""`, so `loadstart`/`canplay` don't fire reliably and the
+  // canplay-fallback timeout was never armed — audio played while the video
+  // stayed invisible. Any of these callers now reveals it.
+  function markMediaReady() {
+    if (isMediaReady) return;
+    console.log("[VideoPlayer] Marking media ready");
+    isMediaReady = true;
+  }
+
   async function handleCanPlay() {
     // Media is ready to play - transition from Loading to Playing state (DR-001)
     console.log("[VideoPlayer] canplay event fired - media is ready");
@@ -639,6 +778,7 @@
     if (initialPosition && initialPosition > 0 && !hasPerformedInitialSeek && videoElement) {
       console.log("[VideoPlayer] Seeking to initial position:", initialPosition);
       hasPerformedInitialSeek = true;
+      lastAppliedInitialPosition = initialPosition; // mark this value as applied so the change-effect ignores it
 
       // Pause video to prevent autoplay from starting at position 0
       const wasPlaying = !videoElement.paused;
@@ -719,6 +859,9 @@
   function handlePlaying() {
     console.log("[VideoPlayer] playing event - playback resumed");
     isBuffering = false;
+    // Safety net: if we reached `playing` we are definitely renderable, even if
+    // `canplay`/hls FRAG_BUFFERED were missed on this WebView.
+    markMediaReady();
   }
 
   function handleLoadStart() {
@@ -746,11 +889,67 @@
     }, 5000);
   }
 
+  // ===== JRay "who's on screen" pause overlay (optional plugin) =====
+  // On pause, ask the JRay Jellyfin plugin which actors are on screen at the
+  // current timestamp and show them as a tappable overlay. If the plugin isn't
+  // installed (or has no data for this item), the call resolves to [] and the
+  // overlay simply doesn't render. Tapping an actor with a resolved Jellyfin
+  // Person id navigates to that person's library page.
+  let jrayActors = $state<JRayActor[]>([]);
+  // Monotonic token so a slow in-flight request can't overwrite a newer pause
+  // (or a resume that cleared the list).
+  let jrayRequestId = 0;
+
+  async function fetchJrayActors() {
+    const itemId = media?.id;
+    if (!itemId) return;
+    const token = ++jrayRequestId;
+    const t = currentTime;
+    try {
+      const actors = await auth.getRepository().jrayActorsAt(itemId, t);
+      // Discard if a newer pause/resume happened while we were waiting.
+      if (token === jrayRequestId) {
+        jrayActors = actors;
+      }
+    } catch (err) {
+      console.warn("[VideoPlayer] JRay lookup failed:", err);
+      if (token === jrayRequestId) jrayActors = [];
+    }
+  }
+
+  function clearJrayActors() {
+    jrayRequestId++; // invalidate any in-flight request
+    jrayActors = [];
+  }
+
+  function openJrayActor(actor: JRayActor) {
+    if (actor.jellyfin_id) {
+      goto(`/library/${actor.jellyfin_id}`);
+    }
+  }
+
+  // Drive the JRay overlay off the single `isPlaying` flag so it works for both
+  // the HTML5 <video> (desktop) and the native ExoPlayer path (Android, which
+  // updates isPlaying via the player://state-changed event). Fetch when we go
+  // paused, clear when we resume. untrack() keeps this from re-running on every
+  // currentTime tick — only isPlaying transitions matter.
+  $effect(() => {
+    if (isPlaying) {
+      untrack(clearJrayActors);
+    } else if (isMediaReady) {
+      untrack(fetchJrayActors);
+    }
+  });
+
   function handlePlay() {
     isPlaying = true;
     startTimeUpdates(); // Start RAF loop for smooth time updates
-    // Report playback start on first play
-    if (!hasReportedStart && onReportStart) {
+    // Mirror the DOM state into the Rust PlayerController so it is the single
+    // source of truth for HTML5 video (the <video> lives in the webview, which
+    // Rust cannot observe directly). See html5Adapter.ts.
+    html5Adapter.reportState("playing", reportMediaId ?? null);
+    // Report playback start on first play (skip for live - no resume tracking)
+    if (!isLive && !hasReportedStart && onReportStart) {
       onReportStart(currentTime, reportMediaId);
       hasReportedStart = true;
     }
@@ -759,6 +958,8 @@
   function handlePause() {
     isPlaying = false;
     stopTimeUpdates(); // Stop RAF loop when paused
+    html5Adapter.reportState("paused", reportMediaId ?? null);
+    html5Adapter.reportPosition(currentTime, duration, { force: true });
     // Report progress when paused
     if (onReportProgress) {
       onReportProgress(currentTime, true, reportMediaId);
@@ -768,8 +969,9 @@
   function handleEnded() {
     isPlaying = false;
     stopTimeUpdates(); // Stop RAF loop when ended
-    // Report stop when video ends
-    if (onReportStop) {
+    html5Adapter.reportState("stopped", reportMediaId ?? null);
+    // Report stop when video ends (skip for live - no resume tracking)
+    if (!isLive && onReportStop) {
       onReportStop(currentTime, reportMediaId);
     }
     // Notify parent that video has ended (for next episode popup)
@@ -831,10 +1033,12 @@
       // For native backend, the backend handles everything internally
       if (!useHtml5Element) {
         // Backend already stopped, reloaded, and seeked if needed
+        lastNativeSeekAt = Date.now();
         currentTime = response.position ?? targetTime;
         if (response.strategy === "reloadStream") {
-          seekOffset = response.seekOffset ?? targetTime;
-          currentStreamUrl = response.newUrl ?? currentStreamUrl;
+          // Serde keeps these fields snake_case (only the "strategy" tag is camelCase)
+          seekOffset = response.seek_offset ?? targetTime;
+          currentStreamUrl = response.new_url ?? currentStreamUrl;
         } else {
           seekOffset = 0;
         }
@@ -876,8 +1080,9 @@
         await new Promise(resolve => setTimeout(resolve, 100));
 
         // Update stream URL (this will trigger $effect to create new HLS instance)
-        seekOffset = response.seekOffset ?? targetTime;
-        currentStreamUrl = response.newUrl ?? currentStreamUrl;
+        // Serde keeps these fields snake_case (only the "strategy" tag is camelCase)
+        seekOffset = response.seek_offset ?? targetTime;
+        currentStreamUrl = response.new_url ?? currentStreamUrl;
         currentTime = targetTime;
 
         // Wait for video to be ready
@@ -1145,7 +1350,8 @@
         await new Promise(resolve => setTimeout(resolve, 100));
 
         // Update stream URL (this will trigger $effect to create new HLS instance)
-        currentStreamUrl = response.newUrl!;
+        // Serde keeps new_url snake_case (only the "strategy" tag is camelCase)
+        currentStreamUrl = response.new_url!;
         seekOffset = response.position!;
 
         // Wait for video to be ready
@@ -1400,6 +1606,44 @@
         </svg>
       </button>
     {/if}
+
+    <!-- JRay "who's on screen" overlay: shown while paused when the JRay plugin
+         returned actors for the current timestamp. Tapping an actor with a
+         resolved Jellyfin Person id opens their library page. -->
+    {#if !isPlaying && !isSeeking && jrayActors.length > 0}
+      <div class="absolute top-4 right-4 max-w-xs bg-black/70 rounded-lg p-3 backdrop-blur-sm pointer-events-auto">
+        <div class="text-white/60 text-xs font-medium uppercase tracking-wide mb-2">On screen</div>
+        <div class="flex flex-col gap-2">
+          {#each jrayActors as actor (actor.name + actor.jellyfin_id)}
+            {#if actor.jellyfin_id}
+              <button
+                class="flex items-center gap-2 text-left text-white text-sm hover:text-blue-300 transition-colors group"
+                onclick={() => openJrayActor(actor)}
+              >
+                <!-- Headshot from the actor's Jellyfin Person item. Falls back to
+                     a placeholder inside CachedImage when no image exists. -->
+                <CachedImage
+                  itemId={actor.jellyfin_id}
+                  imageType="Primary"
+                  maxWidth={80}
+                  alt={actor.name}
+                  class="w-8 h-8 rounded-full object-cover flex-shrink-0 ring-1 ring-white/20 group-hover:ring-blue-300/60"
+                />
+                <span>{actor.name}</span>
+              </button>
+            {:else}
+              <span class="flex items-center gap-2 text-white/80 text-sm">
+                <!-- No resolved Jellyfin id → no headshot available. -->
+                <span class="w-8 h-8 rounded-full bg-gray-700 flex-shrink-0 flex items-center justify-center text-xs text-gray-400">
+                  {actor.name.slice(0, 1)}
+                </span>
+                <span>{actor.name}</span>
+              </span>
+            {/if}
+          {/each}
+        </div>
+      </div>
+    {/if}
   </div>
 
   <!-- Controls -->
@@ -1413,26 +1657,35 @@
       <h2 class="text-white text-lg font-semibold">{media?.name || "Video"}</h2>
     </div>
 
-    <!-- Progress bar -->
-    <div class="flex items-center gap-2 mb-2">
-      <span class="text-white text-sm w-12">{formatTime(currentTime)}</span>
-      <input
-        type="range"
-        min="0"
-        max={duration || 100}
-        value={currentTime}
-        oninput={handleSeekBarInput}
-        onchange={handleSeekBarChange}
-        onmousedown={() => isDraggingSeekBar = true}
-        onmouseup={() => isDraggingSeekBar = false}
-        ontouchstart={() => isDraggingSeekBar = true}
-        ontouchend={() => isDraggingSeekBar = false}
-        class="flex-1 h-1 bg-white/30 rounded-full appearance-none cursor-pointer
-               [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-3 [&::-webkit-slider-thumb]:h-3
-               [&::-webkit-slider-thumb]:bg-white [&::-webkit-slider-thumb]:rounded-full"
-      />
-      <span class="text-white text-sm w-12 text-right">{formatTime(duration)}</span>
-    </div>
+    <!-- Progress bar (hidden for live streams - no fixed timeline) -->
+    {#if isLive}
+      <div class="flex items-center gap-2 mb-2">
+        <span class="flex items-center gap-1.5 text-white text-sm font-semibold">
+          <span class="inline-block w-2 h-2 rounded-full bg-red-500"></span>
+          LIVE
+        </span>
+      </div>
+    {:else}
+      <div class="flex items-center gap-2 mb-2">
+        <span class="text-white text-sm w-12">{formatTime(currentTime)}</span>
+        <input
+          type="range"
+          min="0"
+          max={duration || 100}
+          value={currentTime}
+          oninput={handleSeekBarInput}
+          onchange={handleSeekBarChange}
+          onmousedown={() => isDraggingSeekBar = true}
+          onmouseup={() => isDraggingSeekBar = false}
+          ontouchstart={() => isDraggingSeekBar = true}
+          ontouchend={() => isDraggingSeekBar = false}
+          class="flex-1 h-1 bg-white/30 rounded-full appearance-none cursor-pointer
+                 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-3 [&::-webkit-slider-thumb]:h-3
+                 [&::-webkit-slider-thumb]:bg-white [&::-webkit-slider-thumb]:rounded-full"
+        />
+        <span class="text-white text-sm w-12 text-right">{formatTime(duration)}</span>
+      </div>
+    {/if}
 
     <!-- Control buttons -->
     <div class="flex items-center justify-between">

src/lib/components/player/VolumeControl.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { commands } from "$lib/api/bindings";
+  import { playerController } from "$lib/player";
   import { volume, isMuted, mergedVolume } from "$lib/stores/player";
   import { isRemoteMode } from "$lib/stores/playbackMode";
   import { selectedSession, sessions } from "$lib/stores/sessions";
@@ -31,7 +31,7 @@
       // Remote mode: send volume as 0-100 integer to remote session
       await sessions.sendVolume($selectedSession.id, Math.round(newVolume * 100));
     } else {
-      await commands.playerSetVolume(newVolume);
+      await playerController.setVolume(newVolume);
     }
   }
 
@@ -39,7 +39,7 @@
     if ($isRemoteMode && $selectedSession) {
       await sessions.sendToggleMute($selectedSession.id);
     } else {
-      await commands.playerToggleMute();
+      await playerController.toggleMute();
     }
   }
 

src/lib/components/sessions/SessionPickerModal.svelte

@@ -4,6 +4,7 @@
   import { sessions, controllableSessions, selectedSession } from "$lib/stores";
   import { playbackMode, isTransferring, transferError } from "$lib/stores/playbackMode";
   import { playbackPosition } from "$lib/stores/player";
+  import { lmsSync, isLmsSession, macForSession } from "$lib/stores/lmsSync";
   import type { Session } from "$lib/api/types";
 
   interface Props {
@@ -14,6 +15,20 @@
 
   let { isOpen = false, onClose, onSelectSession }: Props = $props();
 
+  // MACs currently part of any sync group, for rendering toggle state.
+  const groupedMacs = $derived(new Set(($lmsSync.groups ?? []).flatMap(
+    (g) => [g.masterMac, ...(g.slaveMacs ?? [])]
+  )));
+
+  // The sync master is the LMS zone we're currently controlling. Zones can only
+  // be fused once we have a master to fuse them into.
+  const masterMac = $derived(isLmsSession($selectedSession) ? macForSession($selectedSession) : null);
+
+  function isZoneFused(session: Session): boolean {
+    const mac = macForSession(session);
+    return mac !== null && groupedMacs.has(mac);
+  }
+
   async function handleSessionSelect(session: Session) {
     try {
       // Transfer playback to remote session, resuming at our current position
@@ -31,6 +46,32 @@
     }
   }
 
+  // Toggle an LMS zone in/out of the current master's sync group. If there's no
+  // master yet (we're not controlling an LMS zone), the click falls back to a
+  // normal transfer so the user can start playing on a zone first.
+  async function handleLmsZoneToggle(session: Session) {
+    const zoneMac = macForSession(session);
+    if (!zoneMac) return;
+
+    if (!masterMac) {
+      // No master yet — start playback on this zone; it becomes the master.
+      await handleSessionSelect(session);
+      await lmsSync.refresh();
+      return;
+    }
+
+    try {
+      if (isZoneFused(session)) {
+        await lmsSync.decoupleZone(zoneMac);
+      } else {
+        await lmsSync.fuseZone(masterMac, zoneMac);
+      }
+    } catch (error) {
+      console.error("Failed to toggle LMS zone:", error);
+      // Error is surfaced via the lmsSync store
+    }
+  }
+
   async function handleTransferToLocal() {
     try {
       await playbackMode.transferToLocal();
@@ -80,6 +121,7 @@
   $effect(() => {
     if (isOpen) {
       sessions.refresh();
+      lmsSync.refresh();
     }
   });
 </script>
@@ -167,14 +209,24 @@
             <!-- Available sessions -->
             {#each $controllableSessions as session (session.id)}
               {#if session.id !== $selectedSession?.id}
+                {@const lmsZone = isLmsSession(session)}
+                {@const fused = lmsZone && isZoneFused(session)}
                 <button
-                  onclick={() => handleSessionSelect(session)}
-                  class="w-full p-4 rounded-lg border border-gray-800 hover:border-[var(--color-jellyfin)]/50 hover:bg-[var(--color-jellyfin)]/5 transition-all text-left"
+                  onclick={() => (lmsZone ? handleLmsZoneToggle(session) : handleSessionSelect(session))}
+                  disabled={$lmsSync.isBusy}
+                  aria-pressed={lmsZone ? fused : undefined}
+                  class="w-full p-4 rounded-lg border transition-all text-left disabled:opacity-60
+                    {fused
+                      ? 'border-[var(--color-jellyfin)] bg-[var(--color-jellyfin)]/10'
+                      : 'border-gray-800 hover:border-[var(--color-jellyfin)]/50 hover:bg-[var(--color-jellyfin)]/5'}"
                 >
                   <div class="flex items-center gap-3">
                     <div class="w-10 h-10 rounded-lg bg-gray-800 flex items-center justify-center flex-shrink-0">
                       <svg class="w-5 h-5 text-gray-400" fill="currentColor" viewBox="0 0 24 24">
-                        {#if getSessionIcon(session.client) === "tv"}
+                        {#if lmsZone}
+                          <!-- speaker icon for LMS zones -->
+                          <path d="M12 2a1 1 0 011 1v18a1 1 0 01-1 1H6a2 2 0 01-2-2V4a2 2 0 012-2h6zm0 2H6v16h6V4zm-3 9a2 2 0 110 4 2 2 0 010-4zm0-2a4 4 0 100 8 4 4 0 000-8zm0-4a1 1 0 110 2 1 1 0 010-2zm9 0h2v2h-2V7zm0 4h2v2h-2v-2z" />
+                        {:else if getSessionIcon(session.client) === "tv"}
                           <path d="M21 3H3c-1.1 0-2 .9-2 2v12c0 1.1.9 2 2 2h5v2h8v-2h5c1.1 0 1.99-.9 1.99-2L23 5c0-1.1-.9-2-2-2zm0 14H3V5h18v12z" />
                         {:else if getSessionIcon(session.client) === "web"}
                           <path d="M20 4H4c-1.1 0-1.99.9-1.99 2L2 18c0 1.1.9 2 2 2h16c1.1 0 2-.9 2-2V6c0-1.1-.9-2-2-2zm-5 14H4v-4h11v4zm0-5H4V9h11v4zm5 5h-4V9h4v9z" />
@@ -187,14 +239,33 @@
                     </div>
                     <div class="flex-1 min-w-0">
                       <h3 class="font-medium text-white truncate">{session.deviceName}</h3>
-                      <p class="text-sm text-gray-400 truncate">{session.client}</p>
+                      <p class="text-sm text-gray-400 truncate">
+                        {#if lmsZone}
+                          {fused ? "In sync group — tap to remove" : masterMac ? "Tap to add to group" : "Speaker zone"}
+                        {:else}
+                          {session.client}
+                        {/if}
+                      </p>
                       {#if session.nowPlayingItem}
                         <p class="text-xs text-gray-500 truncate mt-1">
                           Playing: {session.nowPlayingItem.name}
                         </p>
                       {/if}
                     </div>
-                    {#if session.playState}
+                    {#if lmsZone}
+                      <!-- Fuse toggle indicator -->
+                      <div class="flex-shrink-0">
+                        {#if fused}
+                          <svg class="w-5 h-5 text-[var(--color-jellyfin)]" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+                            <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z" />
+                          </svg>
+                        {:else}
+                          <svg class="w-5 h-5 text-gray-600" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+                            <circle cx="12" cy="12" r="9" stroke-width="2" />
+                          </svg>
+                        {/if}
+                      </div>
+                    {:else if session.playState}
                       <div class="flex-shrink-0">
                         {#if session.playState.isPaused}
                           <svg class="w-4 h-4 text-gray-500" fill="currentColor" viewBox="0 0 24 24">
@@ -295,6 +366,27 @@
         </div>
       {/if}
 
+      <!-- LMS sync error -->
+      {#if $lmsSync.error}
+        <div class="absolute bottom-0 left-0 right-0 bg-red-500/90 text-white px-6 py-3 flex items-center justify-between z-10 rounded-b-2xl">
+          <div class="flex items-center gap-2">
+            <svg class="w-5 h-5 flex-shrink-0" fill="currentColor" viewBox="0 0 24 24">
+              <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z" />
+            </svg>
+            <span class="text-sm">{$lmsSync.error}</span>
+          </div>
+          <button
+            onclick={() => lmsSync.clearError()}
+            class="text-white hover:text-gray-200 transition-colors"
+            aria-label="Dismiss error"
+          >
+            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
+      {/if}
+
       <!-- Error Display -->
       {#if $transferError}
         <div class="absolute bottom-0 left-0 right-0 bg-red-500/90 text-white px-6 py-3 flex items-center justify-between z-10 rounded-b-2xl">

src/lib/player/html5Adapter.ts

@@ -0,0 +1,84 @@
+/**
+ * HTML5 <video> → Rust reporting adapter ("html5+rust internal module").
+ *
+ * On platforms where video renders in the webview (Linux WebKitGTK HTML5
+ * <video>; and, per the current interim behavior, Android too), the real player
+ * is the DOM element, which the Rust backend cannot observe directly. This
+ * module is the single place that reports the element's lifecycle back into
+ * Rust, so the `PlayerController` stays the source of truth and the frontend
+ * `player` store is fed from ONE pipeline (playerEvents.ts) in both native and
+ * HTML5 modes.
+ *
+ * The VideoPlayer component owns the element and its UI; it calls these
+ * functions from its DOM event handlers. Keeping the `commands.playerReport*`
+ * calls here (rather than scattered in the component) is the boundary: UI code
+ * never talks to the report commands directly.
+ *
+ * TRACES: UR-003, UR-005 | DR-001, DR-028
+ */
+
+import { commands } from "$lib/api/bindings";
+
+/** Player states mirrored to Rust (must match the strings playerEvents.ts handles). */
+export type Html5PlayerState = "playing" | "paused" | "loading" | "stopped" | "idle";
+
+/**
+ * Report an HTML5 <video> state transition to Rust. The controller re-emits a
+ * `StateChanged` event identical to the native backends', so the frontend
+ * player store updates through its normal path.
+ */
+export async function reportState(
+  state: Html5PlayerState,
+  mediaId: string | null
+): Promise<void> {
+  try {
+    await commands.playerReportState(state, mediaId);
+  } catch (err) {
+    console.warn("[html5Adapter] Failed to report state:", err);
+  }
+}
+
+/**
+ * Position reporting is throttled to ~250ms to match the native backends'
+ * cadence and avoid flooding the IPC channel from the 60fps RAF loop.
+ */
+let lastPositionReport = 0;
+const POSITION_REPORT_INTERVAL_MS = 250;
+
+/**
+ * Report an HTML5 <video> position tick to Rust (throttled). Safe to call every
+ * animation frame; only forwards at most every {@link POSITION_REPORT_INTERVAL_MS}.
+ */
+export async function reportPosition(
+  position: number,
+  duration: number,
+  { force = false }: { force?: boolean } = {}
+): Promise<void> {
+  const now = Date.now();
+  if (!force && now - lastPositionReport < POSITION_REPORT_INTERVAL_MS) {
+    return;
+  }
+  lastPositionReport = now;
+  try {
+    await commands.playerReportPosition(position, Number.isFinite(duration) ? duration : 0);
+  } catch (err) {
+    console.warn("[html5Adapter] Failed to report position:", err);
+  }
+}
+
+/**
+ * Report that the HTML5 <video> finished loading metadata and knows its
+ * duration. Mirrors the native `MediaLoaded` event.
+ */
+export async function reportMediaLoaded(duration: number): Promise<void> {
+  try {
+    await commands.playerReportMediaLoaded(Number.isFinite(duration) ? duration : 0);
+  } catch (err) {
+    console.warn("[html5Adapter] Failed to report media loaded:", err);
+  }
+}
+
+/** Reset internal throttle state (call when a new stream loads). */
+export function resetReporting(): void {
+  lastPositionReport = 0;
+}

src/lib/player/index.ts

@@ -0,0 +1,219 @@
+/**
+ * Unified frontend player API (the boundary).
+ *
+ * This is the single write-side entry point for playback. Every UI component
+ * that wants to *control* the player calls a method here; nothing else should
+ * invoke `commands.player*` directly. The Rust `PlayerController` remains the
+ * single source of truth — these methods only send intent-level commands and
+ * let state flow back through `PlayerStatusEvent` → `playerEvents.ts` → the
+ * `player`/`queue` stores.
+ *
+ * Reads stay on the established stores: this module re-exports the read-only
+ * derived + merged (remote-session-aware) stores so UI can import state and
+ * actions from one place, in both local and remote modes.
+ *
+ * TRACES: UR-005 | DR-001, DR-009
+ */
+
+import { get } from "svelte/store";
+import { commands } from "$lib/api/bindings";
+import type {
+  PlayTracksContext,
+  PlayAlbumTrackRequest,
+  PlayItemRequest,
+} from "$lib/api/bindings";
+import { auth } from "$lib/stores/auth";
+
+/**
+ * Resolve the current repository handle, throwing a clear error if the user is
+ * not authenticated. Centralizes the `auth.getRepository().getHandle()` dance
+ * that was previously duplicated across every context-play call site.
+ */
+function requireHandle(): string {
+  const authState = get(auth);
+  if (!authState.isAuthenticated) {
+    throw new Error("User not authenticated");
+  }
+  const repo = auth.getRepository();
+  if (!repo) {
+    throw new Error("No repository available");
+  }
+  return repo.getHandle();
+}
+
+// ---------------------------------------------------------------------------
+// Transport controls (no repository handle required)
+// ---------------------------------------------------------------------------
+
+async function play() {
+  await commands.playerPlay();
+}
+
+async function pause() {
+  await commands.playerPause();
+}
+
+async function toggle() {
+  await commands.playerToggle();
+}
+
+async function stop() {
+  await commands.playerStop();
+}
+
+async function seek(positionSeconds: number) {
+  await commands.playerSeek(positionSeconds);
+}
+
+async function next() {
+  await commands.playerNext();
+}
+
+async function previous() {
+  await commands.playerPrevious();
+}
+
+async function skipTo(index: number) {
+  await commands.playerSkipTo(index);
+}
+
+// ---------------------------------------------------------------------------
+// Queue mode controls
+// ---------------------------------------------------------------------------
+
+async function toggleShuffle() {
+  await commands.playerToggleShuffle();
+}
+
+async function cycleRepeat() {
+  await commands.playerCycleRepeat();
+}
+
+async function removeFromQueue(index: number) {
+  await commands.playerRemoveFromQueue(index);
+}
+
+async function moveInQueue(fromIndex: number, toIndex: number) {
+  await commands.playerMoveInQueue(fromIndex, toIndex);
+}
+
+// ---------------------------------------------------------------------------
+// Volume
+// ---------------------------------------------------------------------------
+
+async function setVolume(volume: number) {
+  await commands.playerSetVolume(volume);
+}
+
+async function toggleMute() {
+  await commands.playerToggleMute();
+}
+
+// ---------------------------------------------------------------------------
+// Track selection (video)
+// ---------------------------------------------------------------------------
+
+async function setSubtitleTrack(streamIndex: number | null) {
+  await commands.playerSetSubtitleTrack(streamIndex);
+}
+
+// ---------------------------------------------------------------------------
+// Context-aware playback (repository handle required — resolved internally)
+// ---------------------------------------------------------------------------
+
+/**
+ * Play a set of tracks by ID with an explicit queue context. The backend
+ * fetches all metadata and builds the queue; the frontend queue store updates
+ * from the resulting `queue_changed` event.
+ */
+async function playTracks(request: {
+  trackIds: string[];
+  startIndex: number;
+  shuffle: boolean;
+  context: PlayTracksContext;
+  startPosition?: number;
+}) {
+  await commands.playerPlayTracks(requireHandle(), request);
+}
+
+/** Play a single track within its album context (more efficient than playTracks). */
+async function playAlbumTrack(request: PlayAlbumTrackRequest) {
+  await commands.playerPlayAlbumTrack(requireHandle(), request);
+}
+
+/** Play a single explicit media item (used by the video path). */
+async function playItem(request: PlayItemRequest) {
+  return commands.playerPlayItem(request);
+}
+
+/** Add a single track to the queue by ID. */
+async function addTrackById(trackId: string, position: "next" | "end" = "end") {
+  await commands.playerAddTrackById(requireHandle(), { trackId, position });
+}
+
+/** Add multiple tracks to the queue by ID. */
+async function addTracksByIds(
+  trackIds: string[],
+  position: "next" | "end" = "end"
+) {
+  await commands.playerAddTracksByIds(requireHandle(), { trackIds, position });
+}
+
+/**
+ * The unified player facade. Import this and call its methods instead of
+ * reaching for `commands.player*` in UI code.
+ */
+export const playerController = {
+  play,
+  pause,
+  toggle,
+  stop,
+  seek,
+  next,
+  previous,
+  skipTo,
+  toggleShuffle,
+  cycleRepeat,
+  removeFromQueue,
+  moveInQueue,
+  setVolume,
+  toggleMute,
+  setSubtitleTrack,
+  playTracks,
+  playAlbumTrack,
+  playItem,
+  addTrackById,
+  addTracksByIds,
+};
+
+// ---------------------------------------------------------------------------
+// Read-side re-exports: UI reads state from ONE place, in both local & remote
+// modes. These remain the single source of truth fed by playerEvents.ts.
+// ---------------------------------------------------------------------------
+
+export {
+  playerState,
+  currentMedia,
+  isPlaying,
+  isPaused,
+  isLoading,
+  playbackPosition,
+  playbackDuration,
+  volume,
+  isMuted,
+  mergedMedia,
+  mergedIsPlaying,
+  mergedPosition,
+  mergedDuration,
+  mergedVolume,
+} from "$lib/stores/player";
+
+export {
+  queueItems,
+  currentQueueIndex,
+  currentQueueItem,
+  isShuffle,
+  repeatMode,
+  hasNext,
+  hasPrevious,
+} from "$lib/stores/queue";

src/lib/services/playerEvents.regression.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Player Events Service — regression tests
+ *
+ * These tests intentionally use the REAL player store (and its real derived
+ * stores), unlike playerEvents.test.ts which mocks the store away. The bugs
+ * covered here live in the interaction between the event handler and the
+ * store's position/duration fields, so a mocked store cannot catch them.
+ *
+ * TRACES: UR-005 | DR-001
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { get, writable } from "svelte/store";
+import type { MediaItem } from "$lib/api/types";
+import type { PlayerStatusEvent } from "$lib/api/bindings";
+
+// Capture the handler that initPlayerEvents registers so we can drive events
+// directly, exactly as the Tauri event bridge would.
+let registeredHandler: ((event: { payload: PlayerStatusEvent }) => void) | null = null;
+
+vi.mock("@tauri-apps/api/event", () => ({
+  listen: vi.fn(async (_event: string, handler: any) => {
+    registeredHandler = handler;
+    return () => {};
+  }),
+}));
+
+vi.mock("@tauri-apps/api/core", () => ({
+  invoke: vi.fn(),
+}));
+
+// The current queue item is what handleStateChanged seeds playing/paused state
+// from. Back it with a writable so each test can install its own item.
+const currentQueueItemStore = writable<MediaItem | null>(null);
+vi.mock("$lib/stores/queue", () => ({
+  queue: { subscribe: vi.fn() },
+  currentQueueItem: { subscribe: (run: any) => currentQueueItemStore.subscribe(run) },
+}));
+
+// Keep the player in local mode so events aren't skipped as remote.
+// playerEvents.ts reads `get(playbackMode)` (.mode/.isTransferring) and player.ts
+// imports `isRemoteMode` from the same module — provide both.
+vi.mock("$lib/stores/playbackMode", () => ({
+  playbackMode: {
+    setMode: vi.fn(),
+    initializeSessionMonitoring: vi.fn(),
+    subscribe: (run: any) => {
+      run({ mode: "local", isTransferring: false });
+      return () => {};
+    },
+  },
+  isRemoteMode: { subscribe: (run: any) => (run(false), () => {}) },
+}));
+
+// Remote-mode merged stores in player.ts read this; stub as no remote session.
+vi.mock("$lib/stores/sessions", () => ({
+  selectedSession: { subscribe: (run: any) => (run(null), () => {}) },
+}));
+
+vi.mock("$lib/stores/sleepTimer", () => ({
+  sleepTimer: { set: vi.fn() },
+}));
+
+vi.mock("$lib/stores/nextEpisode", () => ({
+  nextEpisode: { showPopup: vi.fn(), updateCountdown: vi.fn() },
+}));
+
+vi.mock("$lib/services/preload", () => ({
+  preloadUpcomingTracks: vi.fn().mockResolvedValue(undefined),
+}));
+
+function makeItem(overrides: Partial<MediaItem> = {}): MediaItem {
+  return {
+    id: "track-1",
+    name: "Test Track",
+    type: "Audio",
+    runTimeTicks: null,
+    ...overrides,
+  } as MediaItem;
+}
+
+async function fire(event: PlayerStatusEvent): Promise<void> {
+  if (!registeredHandler) throw new Error("handler not registered");
+  await registeredHandler({ payload: event });
+  // Let any async work inside the handler settle.
+  await Promise.resolve();
+}
+
+describe("Player Events — pause must not zero the slider duration", () => {
+  beforeEach(async () => {
+    // initPlayerEvents is a singleton; reset it so each test re-registers its
+    // own handler and starts from idle player state.
+    const { cleanupPlayerEvents } = await import("./playerEvents");
+    const { player } = await import("$lib/stores/player");
+    cleanupPlayerEvents();
+    player.setIdle();
+    vi.clearAllMocks();
+    registeredHandler = null;
+    currentQueueItemStore.set(null);
+  });
+
+  it("preserves the live duration across pause when runTimeTicks is missing", async () => {
+    // runTimeTicks is null — the previous code recomputed duration as 0 here,
+    // which collapsed the slider's max and snapped the thumb to the start.
+    const item = makeItem({ runTimeTicks: null });
+    currentQueueItemStore.set(item);
+
+    const { initPlayerEvents } = await import("./playerEvents");
+    const { player, playbackDuration, playbackPosition } = await import("$lib/stores/player");
+
+    await initPlayerEvents();
+
+    // 1. Track starts playing.
+    await fire({ type: "state_changed", state: "playing", media_id: item.id });
+    // 2. Backend reports the real duration once media is loaded / position ticks.
+    await fire({ type: "position_update", position: 42, duration: 180 });
+
+    expect(get(playbackPosition)).toBe(42);
+    expect(get(playbackDuration)).toBe(180);
+
+    // 3. User pauses. Position AND duration must survive — duration is what
+    //    drives the slider's max, so a 0 here is what caused the regression.
+    await fire({ type: "state_changed", state: "paused", media_id: item.id });
+
+    expect(get(playbackPosition)).toBe(42);
+    expect(get(playbackDuration)).toBe(180);
+
+    // Sanity: the store is genuinely paused, not reset to idle/loading.
+    expect(get(player).state.kind).toBe("paused");
+  });
+
+  it("falls back to the runTimeTicks estimate when no live duration is known yet", async () => {
+    // 70s in ticks (1 tick = 100ns) → 700_000_000.
+    const item = makeItem({ runTimeTicks: 700_000_000 });
+    currentQueueItemStore.set(item);
+
+    const { initPlayerEvents } = await import("./playerEvents");
+    const { playbackDuration } = await import("$lib/stores/player");
+
+    await initPlayerEvents();
+
+    // No position_update yet, so there is no live duration to prefer.
+    await fire({ type: "state_changed", state: "paused", media_id: item.id });
+
+    expect(get(playbackDuration)).toBe(70);
+  });
+});

src/lib/services/playerEvents.ts

@@ -10,10 +10,10 @@
 
 import { type UnlistenFn } from "@tauri-apps/api/event";
 import { commands, events, type PlayerStatusEvent, type SleepTimerMode } from "$lib/api/bindings";
-import { player, playbackPosition, currentMedia } from "$lib/stores/player";
+import { player, playbackPosition, playbackDuration, currentMedia } from "$lib/stores/player";
 import { queue, currentQueueItem } from "$lib/stores/queue";
 import { playbackMode } from "$lib/stores/playbackMode";
-import { sleepTimer } from "$lib/stores/sleepTimer";
+import { sleepTimer, sleepTimerExpiredSignal } from "$lib/stores/sleepTimer";
 import { nextEpisode, nextEpisodeItem as nextEpisodeItemStore } from "$lib/stores/nextEpisode";
 import { autoPlayNext } from "$lib/services/nextEpisodeService";
 import { preloadUpcomingTracks } from "$lib/services/preload";
@@ -113,6 +113,12 @@ function handlePlayerEvent(event: PlayerStatusEvent): void {
       handleSleepTimerChanged(event.mode, event.remaining_seconds);
       break;
 
+    case "sleep_timer_expired":
+      // Backend stops its own playback; this signal lets HTML5 video (which
+      // plays outside the backend on Linux) pause itself too.
+      sleepTimerExpiredSignal.update((n) => n + 1);
+      break;
+
     case "show_next_episode_popup":
       handleShowNextEpisodePopup(
         event.current_episode,
@@ -142,6 +148,26 @@ function handlePositionUpdate(position: number, duration: number): void {
   // Note: Sleep timer logic is now handled entirely in the Rust backend
 }
 
+/**
+ * Resolve the duration to seed playing/paused state with.
+ *
+ * For the same track that is already loaded, the live store duration (kept
+ * fresh by media_loaded / position_update events) is authoritative and is
+ * preferred — falling back to the runTimeTicks estimate only when the store
+ * has no usable duration yet. This avoids clobbering a known-good duration
+ * with 0 when runTimeTicks is missing (which would zero the slider's max).
+ */
+function resolveDuration(currentItem: MediaItem, isSameTrack: boolean): number {
+  const estimate = currentItem.runTimeTicks ? currentItem.runTimeTicks / 10000000 : 0;
+  if (isSameTrack) {
+    const live = get(playbackDuration);
+    if (live > 0) {
+      return live;
+    }
+  }
+  return estimate;
+}
+
 /**
  * Handle state change events.
  *
@@ -171,7 +197,7 @@ async function handleStateChanged(state: string, _mediaId: string | null): Promi
         const previous = get(currentMedia);
         const isSameTrack = previous?.id === currentItem.id;
         const startPosition = isSameTrack ? get(playbackPosition) : 0;
-        const initialDuration = currentItem.runTimeTicks ? currentItem.runTimeTicks / 10000000 : 0;
+        const initialDuration = resolveDuration(currentItem, isSameTrack);
         player.setPlaying(currentItem, startPosition, initialDuration);
 
         // Trigger preloading of upcoming tracks in the background
@@ -180,9 +206,15 @@ async function handleStateChanged(state: string, _mediaId: string | null): Promi
           console.debug("[playerEvents] Preload failed (non-critical):", e);
         });
       } else if (state === "paused" && currentItem) {
-        // Keep current position from store
+        // Keep current position and duration from store. The same track is
+        // already loaded on pause, so its live duration (from media_loaded /
+        // position_update) is authoritative — recomputing from runTimeTicks
+        // would clobber it with 0 when runTimeTicks is missing, forcing the
+        // slider's max to 0 and flashing the thumb to the start.
+        const previous = get(currentMedia);
+        const isSameTrack = previous?.id === currentItem.id;
         const currentPosition = get(playbackPosition);
-        const initialDuration = currentItem.runTimeTicks ? currentItem.runTimeTicks / 10000000 : 0;
+        const initialDuration = resolveDuration(currentItem, isSameTrack);
         player.setPaused(currentItem, currentPosition, initialDuration);
       } else if (state === "loading" && currentItem) {
         player.setLoading(currentItem);

src/lib/stores/appState.ts

@@ -9,6 +9,10 @@ export const isAndroid = writable(false);
 // Shuffle/repeat/next/previous state now lives in the event-driven queue store
 // ($lib/stores/queue), the single source of truth.
 export const showSleepTimerModal = writable(false);
+// Measured height (px) of the fixed bottom UI on Android: BottomNav stacked with
+// the global mini player. Published by the root layout via ResizeObserver so the
+// library list can reserve exactly that much bottom padding (no magic rem guesses).
+export const bottomUiHeight = writable(0);
 
 // Library-specific state
 export const librarySearchQuery = writable("");

src/lib/stores/library.ts

@@ -152,6 +152,47 @@ function createLibraryStore() {
     }
   }
 
+  // Load Live TV channels (broadcast / IPTV) into the items list. Live TV uses a
+  // dedicated Jellyfin endpoint rather than the generic /Items browse.
+  async function loadLiveTvChannels() {
+    update((s) => ({ ...s, loadingCount: s.loadingCount + 1, error: null }));
+    try {
+      const repo = auth.getRepository();
+      const channels = await repo.getLiveTvChannels();
+      update((s) => ({
+        ...s,
+        items: channels,
+        totalItems: channels.length,
+        loadingCount: Math.max(0, s.loadingCount - 1),
+      }));
+      return channels;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to load Live TV channels";
+      update((s) => ({ ...s, loadingCount: Math.max(0, s.loadingCount - 1), error: message }));
+      throw error;
+    }
+  }
+
+  // Load the root list of plugin "Channels" into the items list.
+  async function loadChannels() {
+    update((s) => ({ ...s, loadingCount: s.loadingCount + 1, error: null }));
+    try {
+      const repo = auth.getRepository();
+      const result = await repo.getChannels();
+      update((s) => ({
+        ...s,
+        items: result.items,
+        totalItems: result.totalRecordCount,
+        loadingCount: Math.max(0, s.loadingCount - 1),
+      }));
+      return result;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to load channels";
+      update((s) => ({ ...s, loadingCount: Math.max(0, s.loadingCount - 1), error: message }));
+      throw error;
+    }
+  }
+
   async function loadItem(itemId: string) {
     update((s) => ({ ...s, loadingCount: s.loadingCount + 1, error: null }));
 
@@ -297,6 +338,8 @@ function createLibraryStore() {
     subscribe,
     loadLibraries,
     loadItems,
+    loadLiveTvChannels,
+    loadChannels,
     loadItem,
     search,
     setCurrentLibrary,

src/lib/stores/lmsSync.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { get } from "svelte/store";
+import type { Session } from "$lib/api/types";
+
+const mockInvoke = vi.fn();
+vi.mock("$lib/api/bindings", () => ({
+  commands: {
+    lmsGetSyncGroups: () => mockInvoke("lms_get_sync_groups"),
+    lmsCreateSyncGroup: (masterMac: string, slaveMacs: string[]) =>
+      mockInvoke("lms_create_sync_group", { masterMac, slaveMacs }),
+    lmsUnsyncPlayer: (mac: string) => mockInvoke("lms_unsync_player", { mac }),
+    lmsDissolveSyncGroup: (masterMac: string) =>
+      mockInvoke("lms_dissolve_sync_group", { masterMac }),
+  },
+}));
+
+import { lmsSync, isLmsSession, macForSession } from "./lmsSync";
+
+function session(deviceId: string | null): Session {
+  return { id: "s", deviceId } as unknown as Session;
+}
+
+describe("LMS session detection", () => {
+  it("detects LMS zones by the lms- device-id prefix", () => {
+    expect(isLmsSession(session("lms-aa:bb:cc:dd:ee:ff"))).toBe(true);
+    expect(isLmsSession(session("chromecast-123"))).toBe(false);
+    expect(isLmsSession(session(null))).toBe(false);
+    expect(isLmsSession(null)).toBe(false);
+  });
+
+  it("recovers the MAC from an LMS session, null otherwise", () => {
+    expect(macForSession(session("lms-aa:bb:cc:dd:ee:ff"))).toBe("aa:bb:cc:dd:ee:ff");
+    expect(macForSession(session("web-xyz"))).toBeNull();
+    expect(macForSession(null)).toBeNull();
+  });
+});
+
+describe("lmsSync store", () => {
+  beforeEach(() => {
+    mockInvoke.mockReset();
+    lmsSync.reset();
+  });
+
+  it("fusing preserves existing slaves and adds the new zone", async () => {
+    // Initial group: master M with slave A.
+    mockInvoke.mockResolvedValueOnce([{ masterMac: "M", masterName: "M", slaveMacs: ["A"], slaveNames: [] }]);
+    await lmsSync.refresh();
+
+    // create returns void; refresh after returns the updated group.
+    mockInvoke.mockResolvedValueOnce(undefined);
+    mockInvoke.mockResolvedValueOnce([{ masterMac: "M", masterName: "M", slaveMacs: ["A", "B"], slaveNames: [] }]);
+
+    await lmsSync.fuseZone("M", "B");
+
+    expect(mockInvoke).toHaveBeenCalledWith("lms_create_sync_group", {
+      masterMac: "M",
+      slaveMacs: ["A", "B"],
+    });
+    expect(get(lmsSync).groups[0].slaveMacs).toEqual(["A", "B"]);
+  });
+
+  it("decoupling a slave unsyncs just that player", async () => {
+    mockInvoke.mockResolvedValueOnce([{ masterMac: "M", masterName: "M", slaveMacs: ["A"], slaveNames: [] }]);
+    await lmsSync.refresh();
+
+    mockInvoke.mockResolvedValueOnce(undefined); // unsync
+    mockInvoke.mockResolvedValueOnce([{ masterMac: "M", masterName: "M", slaveMacs: [], slaveNames: [] }]);
+
+    await lmsSync.decoupleZone("A");
+
+    expect(mockInvoke).toHaveBeenCalledWith("lms_unsync_player", { mac: "A" });
+  });
+
+  it("decoupling the master dissolves the whole group", async () => {
+    mockInvoke.mockResolvedValueOnce([{ masterMac: "M", masterName: "M", slaveMacs: ["A"], slaveNames: [] }]);
+    await lmsSync.refresh();
+
+    mockInvoke.mockResolvedValueOnce(undefined); // dissolve
+    mockInvoke.mockResolvedValueOnce([]);
+
+    await lmsSync.decoupleZone("M");
+
+    expect(mockInvoke).toHaveBeenCalledWith("lms_dissolve_sync_group", { masterMac: "M" });
+  });
+
+  it("treats a missing plugin (refresh error) as no groups, not fatal", async () => {
+    mockInvoke.mockRejectedValueOnce(new Error("404"));
+    await lmsSync.refresh();
+    expect(get(lmsSync).groups).toEqual([]);
+  });
+});

src/lib/stores/lmsSync.ts

@@ -0,0 +1,133 @@
+/**
+ * LMS multi-room sync ("fuse zones") store.
+ *
+ * The JellyLMS plugin registers each LMS player as a Jellyfin session whose
+ * device id is `lms-{MacAddress}`. We use that prefix both to detect which cast
+ * targets are fuseable LMS zones and to recover the MAC the SyncGroups API needs.
+ *
+ * Fusing model (per product decision): the currently-controlled zone is the sync
+ * master; other selected zones join it. Toggling an already-grouped zone off
+ * decouples just that zone; toggling the master off dissolves the group.
+ *
+ * TRACES: UR-010 | JA-021, JA-025 | DR-037
+ */
+
+import { writable, get } from "svelte/store";
+import { commands } from "$lib/api/bindings";
+import type { Session } from "$lib/api/types";
+import type { LmsSyncGroup } from "$lib/api/bindings";
+
+const LMS_DEVICE_PREFIX = "lms-";
+
+/** Is this cast target an LMS zone (and therefore fuseable)? */
+export function isLmsSession(session: Session | null | undefined): boolean {
+  return !!session?.deviceId?.startsWith(LMS_DEVICE_PREFIX);
+}
+
+/** Recover the LMS player MAC from a session, or null if it isn't an LMS zone. */
+export function macForSession(session: Session | null | undefined): string | null {
+  const deviceId = session?.deviceId;
+  if (!deviceId?.startsWith(LMS_DEVICE_PREFIX)) return null;
+  return deviceId.slice(LMS_DEVICE_PREFIX.length);
+}
+
+interface LmsSyncState {
+  groups: LmsSyncGroup[];
+  isBusy: boolean;
+  error: string | null;
+}
+
+function createLmsSyncStore() {
+  const { subscribe, update, set } = writable<LmsSyncState>({
+    groups: [],
+    isBusy: false,
+    error: null,
+  });
+
+  /** Refresh the list of current sync groups from the server. */
+  async function refresh(): Promise<void> {
+    try {
+      const groups = await commands.lmsGetSyncGroups();
+      update((s) => ({ ...s, groups, error: null }));
+    } catch (error) {
+      // The plugin may not be installed; treat as "no groups" rather than fatal.
+      console.warn("[LmsSync] Failed to load sync groups:", error);
+      update((s) => ({ ...s, groups: [] }));
+    }
+  }
+
+  /** All MACs that are part of any sync group (master or slave). */
+  function groupedMacs(): Set<string> {
+    const macs = new Set<string>();
+    for (const g of get({ subscribe }).groups) {
+      macs.add(g.masterMac);
+      for (const slave of g.slaveMacs ?? []) macs.add(slave);
+    }
+    return macs;
+  }
+
+  /**
+   * Add an LMS zone to the master's sync group (fuse it in).
+   * Preserves any zones already grouped with the master.
+   */
+  async function fuseZone(masterMac: string, zoneMac: string): Promise<void> {
+    if (masterMac === zoneMac) return;
+    update((s) => ({ ...s, isBusy: true, error: null }));
+    try {
+      const existing = get({ subscribe }).groups.find((g) => g.masterMac === masterMac);
+      const slaves = new Set(existing?.slaveMacs ?? []);
+      slaves.add(zoneMac);
+      await commands.lmsCreateSyncGroup(masterMac, [...slaves]);
+      await refresh();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to fuse zone";
+      update((s) => ({ ...s, error: message }));
+      throw error;
+    } finally {
+      update((s) => ({ ...s, isBusy: false }));
+    }
+  }
+
+  /**
+   * Remove a single zone from its group. If the zone is a group's master, the
+   * whole group is dissolved (a group can't outlive its master).
+   */
+  async function decoupleZone(zoneMac: string): Promise<void> {
+    update((s) => ({ ...s, isBusy: true, error: null }));
+    try {
+      const asMaster = get({ subscribe }).groups.find((g) => g.masterMac === zoneMac);
+      if (asMaster) {
+        await commands.lmsDissolveSyncGroup(zoneMac);
+      } else {
+        await commands.lmsUnsyncPlayer(zoneMac);
+      }
+      await refresh();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to decouple zone";
+      update((s) => ({ ...s, error: message }));
+      throw error;
+    } finally {
+      update((s) => ({ ...s, isBusy: false }));
+    }
+  }
+
+  function clearError(): void {
+    update((s) => ({ ...s, error: null }));
+  }
+
+  function reset(): void {
+    set({ groups: [], isBusy: false, error: null });
+  }
+
+  return {
+    subscribe,
+    refresh,
+    groupedMacs,
+    fuseZone,
+    decoupleZone,
+    clearError,
+    reset,
+  };
+}
+
+export const lmsSync = createLmsSyncStore();

src/lib/stores/movies.ts

@@ -4,6 +4,7 @@
 import { writable, derived } from "svelte/store";
 import type { MediaItem } from "$lib/api/types";
 import { auth } from "./auth";
+import { buildHeroMix } from "$lib/utils/heroMix";
 
 /** A single "by genre" row: the genre name plus the movies in it. */
 export interface GenreRow {
@@ -42,30 +43,9 @@ function createMoviesStore() {
 
   const { subscribe, set, update } = writable<MoviesState>(initialState);
 
-  /**
-   * Build the hero rotation. Prefer in-progress movies (most personal), then
-   * fall back to recently added. De-duplicates by id and prefers items that
-   * carry backdrop/primary artwork for a good banner.
-   */
-  function buildHero(continueWatching: MediaItem[], recentlyAdded: MediaItem[]): MediaItem[] {
-    const hasArt = (i: MediaItem) =>
-      !!(i.backdropImageTags && i.backdropImageTags.length > 0) || !!i.primaryImageTag;
-
-    const result: MediaItem[] = [];
-    const seen = new Set<string>();
-
-    for (const pool of [continueWatching, recentlyAdded]) {
-      for (const item of pool) {
-        if (result.length >= 6) break;
-        if (hasArt(item) && !seen.has(item.id)) {
-          seen.add(item.id);
-          result.push(item);
-        }
-      }
-    }
-
-    return result.slice(0, 6);
-  }
+  /** Artwork check for hero candidates: needs a backdrop or a primary image. */
+  const hasArt = (i: MediaItem) =>
+    !!(i.backdropImageTags && i.backdropImageTags.length > 0) || !!i.primaryImageTag;
 
   async function loadSections(libraryId: string) {
     update(s => ({
@@ -77,12 +57,25 @@ function createMoviesStore() {
     try {
       const repo = auth.getRepository();
 
-      const [resume, latest] = await Promise.all([
+      const [resume, latest, surprise] = await Promise.all([
         repo.getResumeMovies(SECTION_LIMIT),
         repo.getLatestItems(libraryId, SECTION_LIMIT),
+        // Random pool so the hero rotation changes between visits (SortBy=Random
+        // shuffles server-side online, and via SQLite RANDOM() offline).
+        repo
+          .getItems(libraryId, {
+            includeItemTypes: ["Movie"],
+            sortBy: "Random",
+            recursive: true,
+            limit: SECTION_LIMIT,
+          })
+          .then(r => r.items)
+          .catch(() => [] as MediaItem[]),
       ]);
 
-      const heroItems = buildHero(resume, latest);
+      // Mix the hero: in-progress movies first (most personal), then recent
+      // additions, then random picks from across the library.
+      const heroItems = buildHeroMix([resume, latest, surprise], hasArt);
 
       update(s => ({
         ...s,

src/lib/stores/music.ts

@@ -6,6 +6,7 @@ import type { MediaItem, Genre } from "$lib/api/types";
 import { auth } from "./auth";
 import { excludePodcasts } from "$lib/utils/podcastFilter";
 import { selectDiverseGenres, sampleAcross } from "$lib/utils/genreDiversity";
+import { buildHeroMix } from "$lib/utils/heroMix";
 
 /** A single "by genre" row: the genre name plus the albums in it. */
 export interface GenreRow {
@@ -52,33 +53,9 @@ function createMusicStore() {
 
   const { subscribe, set, update } = writable<MusicState>(initialState);
 
-  /**
-   * Build the hero rotation from a mix of recently played and rediscover
-   * albums, interleaved so the banner alternates "fresh in your ears" with
-   * "remember this?". De-duplicates by id and prefers items that have artwork.
-   */
-  function buildHero(recent: MediaItem[], rediscover: MediaItem[]): MediaItem[] {
-    const hasArt = (i: MediaItem) =>
-      !!i.primaryImageTag || !!(i.backdropImageTags && i.backdropImageTags.length > 0);
-
-    const recentPool = recent.filter(hasArt);
-    const rediscoverPool = rediscover.filter(hasArt);
-
-    const result: MediaItem[] = [];
-    const seen = new Set<string>();
-    const maxLen = Math.max(recentPool.length, rediscoverPool.length);
-
-    for (let i = 0; i < maxLen && result.length < 6; i++) {
-      for (const candidate of [recentPool[i], rediscoverPool[i]]) {
-        if (candidate && !seen.has(candidate.id)) {
-          seen.add(candidate.id);
-          result.push(candidate);
-        }
-      }
-    }
-
-    return result.slice(0, 6);
-  }
+  /** Artwork check for hero candidates: needs a primary image or backdrop. */
+  const hasArt = (i: MediaItem) =>
+    !!i.primaryImageTag || !!(i.backdropImageTags && i.backdropImageTags.length > 0);
 
   async function loadSections(libraryId: string) {
     update(s => ({
@@ -90,7 +67,7 @@ function createMusicStore() {
     try {
       const repo = auth.getRepository();
 
-      const [recentlyPlayed, newlyAdded, playlistsResult, rediscover] = await Promise.all([
+      const [recentlyPlayed, newlyAdded, playlistsResult, rediscover, surprise] = await Promise.all([
         repo.getRecentlyPlayedAudio(SECTION_LIMIT),
         repo.getItems(libraryId, {
           includeItemTypes: ["MusicAlbum"],
@@ -107,6 +84,17 @@ function createMusicStore() {
           limit: SECTION_LIMIT,
         }),
         repo.getRediscoverAlbums(libraryId, SECTION_LIMIT),
+        // Random pool so the hero rotation changes between visits (SortBy=Random
+        // shuffles server-side online, and via SQLite RANDOM() offline).
+        repo
+          .getItems(libraryId, {
+            includeItemTypes: ["MusicAlbum"],
+            sortBy: "Random",
+            recursive: true,
+            limit: SECTION_LIMIT,
+          })
+          .then(r => r.items)
+          .catch(() => [] as MediaItem[]),
       ]);
 
       // HACK: drop the "Podcasts" folder that lives inside the music library.
@@ -114,8 +102,11 @@ function createMusicStore() {
       const newlyAddedAlbums = excludePodcasts(newlyAdded.items);
       const playlistItems = excludePodcasts(playlistsResult.items);
       const rediscoverAlbums = excludePodcasts(rediscover);
+      const surpriseAlbums = excludePodcasts(surprise);
 
-      const heroItems = buildHero(recentlyPlayedAlbums, rediscoverAlbums);
+      // Mix the hero: fresh-in-your-ears first, then "remember this?", then
+      // random albums from across the library.
+      const heroItems = buildHeroMix([recentlyPlayedAlbums, rediscoverAlbums, surpriseAlbums], hasArt);
 
       update(s => ({
         ...s,

src/lib/stores/playbackMode.ts

@@ -10,7 +10,7 @@
  */
 
 import { writable, get, derived } from "svelte/store";
-import { commands } from "$lib/api/bindings";
+import { commands, events } from "$lib/api/bindings";
 import { sessions, selectedSession } from "./sessions";
 import { auth } from "./auth";
 import { ticksToSeconds } from "$lib/utils/playbackUnits";
@@ -198,6 +198,12 @@ function createPlaybackModeStore() {
       // Get repository for handle (backend will fetch playback info via player_play_tracks)
       const repository = auth.getRepository();
 
+      // Mark the whole sequence as a transfer in the *Rust* manager too. Without
+      // this, player_play_tracks sees mode=Remote and casts the track back to the
+      // remote session instead of playing it locally (the frontend's own
+      // isTransferring flag is invisible to Rust). Cleared in `finally`.
+      await commands.playbackModeSetTransferring(true);
+
       // Start local playback (events allowed through because isTransferring=true)
       // Use player_play_tracks - backend fetches all metadata from single ID
       const repositoryHandle = repository.getHandle();
@@ -248,6 +254,14 @@ function createPlaybackModeStore() {
       console.error("Transfer to local failed:", error);
       throw error;
     } finally {
+      // Always lower the Rust transferring flag so it can't stick on if any step
+      // above threw (transfer_to_local lowers it on success, but not if we never
+      // reached it). Safe to call unconditionally.
+      try {
+        await commands.playbackModeSetTransferring(false);
+      } catch (e) {
+        console.warn("[PlaybackMode] Failed to clear transferring flag:", e);
+      }
       currentTransferAbort = null;
     }
   }
@@ -261,6 +275,22 @@ function createPlaybackModeStore() {
     let consecutiveMisses = 0;
     const DISCONNECT_THRESHOLD = 3; // ~6s at 2s polling interval
 
+    // The lockscreen Stop button (while casting) asks the native side to
+    // disconnect from the remote session and resume locally. The remote->local
+    // transfer must be driven here because it reloads the media item locally,
+    // which only the frontend can currently do.
+    events.playerStatusEvent.listen((event) => {
+      if (event.payload.type === "remote_disconnect_requested") {
+        const currentState = get({ subscribe });
+        if (currentState.mode === "remote") {
+          console.log("[PlaybackMode] Lockscreen requested disconnect; transferring to local");
+          transferToLocal().catch((e) =>
+            console.error("[PlaybackMode] Lockscreen-triggered transfer failed:", e),
+          );
+        }
+      }
+    });
+
     selectedSession.subscribe((session) => {
       const currentState = get({ subscribe });
 

src/lib/stores/player.ts

@@ -250,12 +250,36 @@ export const mergedVolume = derived(
   }
 );
 
+/**
+ * Whether an item is video content and therefore must NOT appear in the audio
+ * mini player. Checks the Jellyfin item type (Movie/Episode/live TV) AND the
+ * backend queue item's `mediaType` discriminator.
+ *
+ * The `mediaType` check is essential: a video started via `player_play_item`
+ * (every Movie/Episode goes through VideoPlayer) is pushed onto the backend
+ * queue as a PlayerMediaItem with NO `type` field but `mediaType: "video"`.
+ * Without this, that queue item's absent `type` slips past the Movie/Episode
+ * check and the video surfaces in the audio mini player after leaving /player.
+ */
+function isVideoItem(item: MediaItem | null): boolean {
+  if (!item) return false;
+  const type = item.type;
+  if (type === "Movie" || type === "Episode" || type === "TvChannel") {
+    return true;
+  }
+  // Backend PlayerMediaItem carries a lowercase mediaType discriminator that is
+  // present even when the Jellyfin `type` is absent (video-only play requests).
+  const mediaType = (item as { mediaType?: string }).mediaType;
+  return mediaType === "video";
+}
+
 /**
  * Should show audio miniplayer - state machine gated
  * Only true when:
  * 1. In remote mode with an active session playing media, OR
- * 2. Player is in playing or paused state (not idle, loading, error)
- *    AND current media is audio (not video: Movie or Episode)
+ * 2. There is an audio item loaded/queued and we are not in a genuine
+ *    stopped state. The bar stays visible through transient idle/loading/
+ *    seeking blips so it never flickers while advancing between tracks.
  */
 export const shouldShowAudioMiniPlayer = derived(
   [player, currentMedia, currentQueueItem, isRemoteMode, selectedSession],
@@ -265,22 +289,25 @@ export const shouldShowAudioMiniPlayer = derived(
       return true;
     }
 
-    // Local mode: hide only when there is genuinely nothing loaded
-    // (idle/stopped/error). Keep showing through loading/seeking transitions
-    // so the mini player doesn't blink out when advancing between tracks.
-    const state = $player.state;
-    if (state.kind === "idle" || state.kind === "error") {
-      return false;
-    }
-
     // Determine media type from the player state, falling back to the queue
     // item (the player store can momentarily lack media during transitions).
-    const mediaType = $media?.type ?? $queueItem?.type;
-    if (mediaType === "Movie" || mediaType === "Episode") {
+    const item = $media ?? $queueItem;
+    if (isVideoItem(item)) {
       return false;
     }
 
-    // Show for audio content
+    const state = $player.state;
+
+    // A genuine stop clears the queue too, so when the player reports
+    // idle/error we only hide if there is also no queue item to fall back to.
+    // This keeps the bar visible through a transient idle/stopped blip emitted
+    // mid-transition (e.g. sleep-timer churn or a stop-then-load track change),
+    // while still hiding once playback has truly ended and the queue is empty.
+    if (state.kind === "idle" || state.kind === "error") {
+      return $queueItem != null;
+    }
+
+    // playing / paused / loading / seeking — audio is active, show the bar.
     return true;
   }
 );

src/lib/stores/playerVisibility.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Tests for `shouldShowAudioMiniPlayer` visibility invariant.
+ *
+ * The mini player must NOT flicker out while advancing between tracks. The
+ * backend can momentarily report an idle/stopped state mid-transition, so the
+ * bar stays visible as long as a queue item still exists, and only hides once
+ * playback has genuinely ended and the queue has been cleared.
+ *
+ * TRACES: UR-005 | DR-009
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { writable } from "svelte/store";
+import { get } from "svelte/store";
+import type { MediaItem } from "$lib/api/types";
+
+// Mock the dependency stores so we can drive remote mode and the current queue
+// item independently of the real backend listeners.
+const isRemoteMode = writable(false);
+const selectedSession = writable<any>(null);
+const currentQueueItem = writable<MediaItem | null>(null);
+
+vi.mock("./playbackMode", () => ({ isRemoteMode }));
+vi.mock("./sessions", () => ({ selectedSession }));
+vi.mock("./queue", () => ({ currentQueueItem }));
+
+// Imported after the mocks so player.ts picks up the mocked stores.
+const { player, shouldShowAudioMiniPlayer } = await import("./player");
+
+const audioItem = { id: "a1", type: "Audio" } as unknown as MediaItem;
+const videoItem = { id: "v1", type: "Movie" } as unknown as MediaItem;
+
+describe("shouldShowAudioMiniPlayer", () => {
+  beforeEach(() => {
+    isRemoteMode.set(false);
+    selectedSession.set(null);
+    currentQueueItem.set(null);
+    player.setIdle();
+  });
+
+  it("shows while an audio track is playing", () => {
+    player.setPlaying(audioItem, 0, 100);
+    expect(get(shouldShowAudioMiniPlayer)).toBe(true);
+  });
+
+  it("stays visible through a transient idle blip while still queued", () => {
+    // A track is queued (e.g. mid-transition the backend emits idle but the
+    // next track is already in the queue).
+    currentQueueItem.set(audioItem);
+    player.setIdle();
+    expect(get(shouldShowAudioMiniPlayer)).toBe(true);
+  });
+
+  it("stays visible through loading/seeking transitions", () => {
+    currentQueueItem.set(audioItem);
+    player.setLoading(audioItem);
+    expect(get(shouldShowAudioMiniPlayer)).toBe(true);
+    player.setSeeking(audioItem, 10);
+    expect(get(shouldShowAudioMiniPlayer)).toBe(true);
+  });
+
+  it("hides once playback ends and the queue is cleared", () => {
+    currentQueueItem.set(null);
+    player.setIdle();
+    expect(get(shouldShowAudioMiniPlayer)).toBe(false);
+  });
+
+  it("hides for video content even while playing", () => {
+    player.setPlaying(videoItem, 0, 100);
+    expect(get(shouldShowAudioMiniPlayer)).toBe(false);
+  });
+
+  it("hides for video content reported only via the queue item", () => {
+    currentQueueItem.set(videoItem);
+    player.setIdle();
+    expect(get(shouldShowAudioMiniPlayer)).toBe(false);
+  });
+
+  it("hides a video queue item that has no Jellyfin `type` but mediaType 'video'", () => {
+    // Regression: player_play_item (every Movie/Episode via VideoPlayer) pushes
+    // a backend PlayerMediaItem onto the queue with item_type: None but
+    // media_type: Video → serialized with no `type` and mediaType: "video".
+    // Without the mediaType check this slipped past the Movie/Episode guard and
+    // surfaced the last-played video in the audio mini player after leaving
+    // /player.
+    const videoQueueItem = { id: "v2", mediaType: "video" } as unknown as MediaItem;
+    currentQueueItem.set(videoQueueItem);
+    player.setIdle();
+    expect(get(shouldShowAudioMiniPlayer)).toBe(false);
+  });
+
+  it("hides for a live TV channel", () => {
+    const channelItem = { id: "c1", type: "TvChannel" } as unknown as MediaItem;
+    player.setPlaying(channelItem, 0, 0);
+    expect(get(shouldShowAudioMiniPlayer)).toBe(false);
+  });
+
+  it("shows in remote mode when the session has a now-playing item", () => {
+    isRemoteMode.set(true);
+    selectedSession.set({ nowPlayingItem: { id: "r1" } });
+    expect(get(shouldShowAudioMiniPlayer)).toBe(true);
+  });
+});

src/lib/stores/sleepTimer.ts

@@ -58,6 +58,14 @@ function createSleepTimerStore() {
 
 export const sleepTimer = createSleepTimerStore();
 
+/**
+ * Incremented each time the backend reports the time-based sleep timer
+ * expired. The backend stops its own (MPV/ExoPlayer) playback itself, but
+ * HTML5 video on Linux plays in the webview outside the backend's control —
+ * VideoPlayer watches this signal and pauses the <video> element.
+ */
+export const sleepTimerExpiredSignal = writable(0);
+
 // Derived stores for convenient access
 export const sleepTimerMode = derived(sleepTimer, ($s) => $s.mode);
 

src/lib/stores/tv.ts

@@ -4,6 +4,7 @@
 import { writable, derived } from "svelte/store";
 import type { MediaItem } from "$lib/api/types";
 import { auth } from "./auth";
+import { buildHeroMix } from "$lib/utils/heroMix";
 
 /** A single "by genre" row: the genre name plus the series in it. */
 export interface GenreRow {
@@ -45,36 +46,11 @@ function createTvStore() {
 
   const { subscribe, set, update } = writable<TvState>(initialState);
 
-  /**
-   * Build the hero rotation. Prefer in-progress episodes (most personal),
-   * then fall back to next-up, then recently added. De-duplicates by id and
-   * prefers items that carry backdrop/primary artwork for a good banner.
-   */
-  function buildHero(
-    continueWatching: MediaItem[],
-    nextUp: MediaItem[],
-    recentlyAdded: MediaItem[]
-  ): MediaItem[] {
-    const hasArt = (i: MediaItem) =>
-      !!(i.backdropImageTags && i.backdropImageTags.length > 0) ||
-      !!(i.parentBackdropImageTags && i.parentBackdropImageTags.length > 0) ||
-      !!i.primaryImageTag;
-
-    const result: MediaItem[] = [];
-    const seen = new Set<string>();
-
-    for (const pool of [continueWatching, nextUp, recentlyAdded]) {
-      for (const item of pool) {
-        if (result.length >= 6) break;
-        if (hasArt(item) && !seen.has(item.id)) {
-          seen.add(item.id);
-          result.push(item);
-        }
-      }
-    }
-
-    return result.slice(0, 6);
-  }
+  /** Artwork check for hero candidates: own/parent backdrop or primary image. */
+  const hasArt = (i: MediaItem) =>
+    !!(i.backdropImageTags && i.backdropImageTags.length > 0) ||
+    !!(i.parentBackdropImageTags && i.parentBackdropImageTags.length > 0) ||
+    !!i.primaryImageTag;
 
   async function loadSections(libraryId: string) {
     update(s => ({
@@ -86,17 +62,30 @@ function createTvStore() {
     try {
       const repo = auth.getRepository();
 
-      const [resume, nextUp, latest] = await Promise.all([
+      const [resume, nextUp, latest, surprise] = await Promise.all([
         repo.getResumeItems(libraryId, SECTION_LIMIT),
         repo.getNextUpEpisodes(undefined, SECTION_LIMIT),
         repo.getLatestItems(libraryId, SECTION_LIMIT),
+        // Random pool so the hero rotation changes between visits (SortBy=Random
+        // shuffles server-side online, and via SQLite RANDOM() offline).
+        repo
+          .getItems(libraryId, {
+            includeItemTypes: ["Series"],
+            sortBy: "Random",
+            recursive: true,
+            limit: SECTION_LIMIT,
+          })
+          .then(r => r.items)
+          .catch(() => [] as MediaItem[]),
       ]);
 
       // Resume items are already video-only from the server, but keep episodes
       // (and the occasional movie that lives in a mixed library) defensively.
       const continueWatching = resume.filter(i => i.type === "Episode" || i.type === "Movie");
 
-      const heroItems = buildHero(continueWatching, nextUp, latest);
+      // Mix the hero: in-progress episodes first (most personal), then next-up,
+      // recent additions, and random series from across the library.
+      const heroItems = buildHeroMix([continueWatching, nextUp, latest, surprise], hasArt);
 
       update(s => ({
         ...s,

src/lib/utils/heroMix.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import type { MediaItem } from "$lib/api/types";
+import { buildHeroMix, shuffle } from "./heroMix";
+
+/** Minimal MediaItem for hero tests; `art: false` strips the image tags. */
+function item(id: string, art = true): MediaItem {
+  return {
+    id,
+    name: `Item ${id}`,
+    type: "Movie",
+    primaryImageTag: art ? `tag-${id}` : undefined,
+  } as MediaItem;
+}
+
+const hasArt = (i: MediaItem) => !!i.primaryImageTag;
+
+describe("shuffle", () => {
+  it("returns a permutation without mutating the input", () => {
+    const input = [1, 2, 3, 4, 5];
+    const copy = [...input];
+    const result = shuffle(input);
+    expect(input).toEqual(copy);
+    expect([...result].sort()).toEqual([...input].sort());
+  });
+});
+
+describe("buildHeroMix", () => {
+  it("returns empty for empty pools", () => {
+    expect(buildHeroMix([[], []], hasArt)).toEqual([]);
+  });
+
+  it("caps the rotation at count", () => {
+    const pool = Array.from({ length: 20 }, (_, i) => item(`a${i}`));
+    expect(buildHeroMix([pool], hasArt, 6)).toHaveLength(6);
+  });
+
+  it("filters items without artwork", () => {
+    const result = buildHeroMix([[item("a", false), item("b")]], hasArt);
+    expect(result.map(i => i.id)).toEqual(["b"]);
+  });
+
+  it("de-duplicates across pools", () => {
+    const a = item("a");
+    const result = buildHeroMix([[a], [a, item("b")]], hasArt);
+    const ids = result.map(i => i.id);
+    expect(ids).toHaveLength(new Set(ids).size);
+    expect(ids).toContain("a");
+    expect(ids).toContain("b");
+  });
+
+  it("leads with an item from the first non-empty pool", () => {
+    const personal = [item("p1"), item("p2"), item("p3")];
+    const rest = [item("r1"), item("r2"), item("r3")];
+    for (let run = 0; run < 20; run++) {
+      const result = buildHeroMix([personal, rest], hasArt);
+      expect(["p1", "p2", "p3"]).toContain(result[0].id);
+    }
+  });
+
+  it("takes at most perPool items per pool before backfilling", () => {
+    const a = [item("a1"), item("a2"), item("a3"), item("a4")];
+    const b = [item("b1"), item("b2"), item("b3"), item("b4")];
+    // count 4 with perPool 2: exactly 2 from each pool, no backfill needed.
+    for (let run = 0; run < 20; run++) {
+      const result = buildHeroMix([a, b], hasArt, 4, 2);
+      const fromA = result.filter(i => i.id.startsWith("a")).length;
+      const fromB = result.filter(i => i.id.startsWith("b")).length;
+      expect(fromA).toBe(2);
+      expect(fromB).toBe(2);
+    }
+  });
+
+  it("backfills from leftovers when samples fall short of count", () => {
+    const a = [item("a1"), item("a2"), item("a3"), item("a4"), item("a5"), item("a6")];
+    const result = buildHeroMix([a], hasArt, 6, 2);
+    expect(result).toHaveLength(6);
+  });
+});

src/lib/utils/heroMix.ts

@@ -0,0 +1,59 @@
+// Hero banner mix builder, shared by the movies/TV/music landing stores.
+//
+// The hero used to show the first N items of fixed pools (continue watching,
+// recently played, latest), which made it identical on every visit. Instead we
+// sample a couple of items at random from each pool — pools are ordered most
+// personal first — and shuffle the rotation, so the banner is a fresh mix each
+// time while still leading with something personal.
+// TRACES: UR-034 | DR-038
+import type { MediaItem } from "$lib/api/types";
+
+/** Fisher-Yates shuffle; returns a new array, input is untouched. */
+export function shuffle<T>(items: T[]): T[] {
+  const result = [...items];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+
+/**
+ * Build a varied hero rotation from ordered pools (most personal first).
+ *
+ * Takes up to `perPool` random items from each pool, de-duplicated by id and
+ * filtered to items with usable artwork. The first pick from the first
+ * non-empty pool leads the rotation (so a resumable/recent item greets the
+ * user), the rest are shuffled. If that yields fewer than `count` items, the
+ * remainder is backfilled from whatever is left across all pools.
+ */
+export function buildHeroMix(
+  pools: MediaItem[][],
+  hasArt: (item: MediaItem) => boolean,
+  count = 6,
+  perPool = 2
+): MediaItem[] {
+  const seen = new Set<string>();
+  const usable = pools.map(pool =>
+    pool.filter(item => {
+      if (!hasArt(item) || seen.has(item.id)) return false;
+      seen.add(item.id);
+      return true;
+    })
+  );
+
+  const picked = new Set<string>();
+  const picks: MediaItem[] = [];
+  for (const pool of usable) {
+    for (const item of shuffle(pool).slice(0, perPool)) {
+      picked.add(item.id);
+      picks.push(item);
+    }
+  }
+
+  if (picks.length === 0) return [];
+
+  const [leader, ...rest] = picks;
+  const leftovers = shuffle(usable.flat().filter(item => !picked.has(item.id)));
+  return [leader, ...shuffle(rest), ...leftovers].slice(0, count);
+}

src/lib/utils/truncateMiddle.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import { truncateMiddle } from "./truncateMiddle";
+
+describe("truncateMiddle", () => {
+  it("returns short strings unchanged", () => {
+    expect(truncateMiddle("short", 32)).toBe("short");
+    expect(truncateMiddle("exactly-len", 11)).toBe("exactly-len");
+  });
+
+  it("abbreviates in the middle keeping head and tail", () => {
+    const result = truncateMiddle("long_media_name_like_this", 16);
+    expect(result).toContain("…");
+    expect(result.length).toBe(16);
+    expect(result.startsWith("long")).toBe(true);
+    expect(result.endsWith("this")).toBe(true);
+  });
+
+  it("never exceeds maxLength", () => {
+    for (const len of [1, 2, 3, 5, 10, 25]) {
+      expect(truncateMiddle("a".repeat(100), len).length).toBeLessThanOrEqual(len);
+    }
+  });
+
+  it("handles null and undefined", () => {
+    expect(truncateMiddle(null)).toBe("");
+    expect(truncateMiddle(undefined)).toBe("");
+  });
+
+  it("falls back to head-truncation when there is no room for content", () => {
+    expect(truncateMiddle("abcdef", 1)).toBe("a");
+    expect(truncateMiddle("abcdef", 0)).toBe("");
+  });
+
+  it("supports a custom ellipsis", () => {
+    const result = truncateMiddle("long_media_name_like_this", 16, "...");
+    expect(result).toContain("...");
+    expect(result.length).toBe(16);
+  });
+});