Background-audio handoff for video + repository/player refactor

Hand video playback off to a native audio-only stream when the app is
backgrounded or locked, with no on-device video decode (UR-040). Adds
player_enter/exit_background_audio commands, an audio-only stream URL
for video items across the repository layer, and the frontend handoff
state machine wired into VideoPlayer. Includes accompanying
repository/offline/player refactoring and regenerates the traceability
matrix.

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

@@ -1,4 +1,6 @@
 //! Queue manipulation commands (add / remove / move / skip).
+//!
+//! TRACES: UR-015 | DR-005, DR-020
 
 use std::path::PathBuf;
 
@@ -150,16 +152,25 @@ pub async fn player_add_track_by_id(
 ) -> Result<QueueStatus, String> {
     use crate::player::queue::AddPosition;
 
-    info!("player_add_track_by_id called: track_id={}, position={}",
-          request.track_id, request.position);
+    info!(
+        "player_add_track_by_id called: track_id={}, position={}",
+        request.track_id, request.position
+    );
 
     // Get repository (hybrid - supports offline/online)
-    let repository = repository_manager.0.get(&repository_handle)
+    let repository = repository_manager
+        .0
+        .get(&repository_handle)
         .ok_or("Repository not found - user may need to log in")?;
 
     // Fetch track metadata via repository
-    info!("Fetching metadata for track {} via repository", request.track_id);
-    let track = repository.get_item(&request.track_id).await
+    info!(
+        "Fetching metadata for track {} via repository",
+        request.track_id
+    );
+    let track = repository
+        .get_item(&request.track_id)
+        .await
         .map_err(|e| format!("Failed to fetch track metadata: {}", e))?;
 
     // Check for local download first
@@ -173,7 +184,9 @@ pub async fn player_add_track_by_id(
         }
     } else {
         // Get stream URL from repository (works online/offline)
-        let stream_url = repository.get_audio_stream_url(&track.id).await
+        let stream_url = repository
+            .get_audio_stream_url(&track.id)
+            .await
             .map_err(|e| format!("Failed to get stream URL for {}: {}", track.name, e))?;
 
         MediaSource::Remote {
@@ -188,23 +201,30 @@ pub async fn player_add_track_by_id(
         id: track.id.clone(),
         title: track.name.clone(),
         name: Some(track.name.clone()), // Frontend compatibility
-        artist: track.album_artist.clone().or_else(|| track.artists.as_ref().and_then(|a| a.first().cloned())),
+        artist: track
+            .album_artist
+            .clone()
+            .or_else(|| track.artists.as_ref().and_then(|a| a.first().cloned())),
         album: track.album_name.clone(),
         album_name: track.album_name.clone(), // Frontend compatibility
         album_id: track.album_id.clone(),
         artist_items: track.artist_items.clone(), // For clickable artist links
-        artists: track.artists.clone(), // Fallback artist info
+        artists: track.artists.clone(),           // Fallback artist info
         primary_image_tag: track.primary_image_tag.clone(), // For frontend image display
         item_type: Some(track.item_type.clone()), // Frontend compatibility
         playlist_id: None,
         duration: track.runtime_ticks.map(|t| t as f64 / 10_000_000.0),
         artwork_url: primary_image_tag_for_url.and_then(|tag| {
             track.album_id.as_ref().map(|album_id| {
-                repository.get_image_url(album_id, ImageType::Primary, Some(ImageOptions {
-                    max_width: Some(300),
-                    tag: Some(tag),
-                    ..Default::default()
-                }))
+                repository.get_image_url(
+                    album_id,
+                    ImageType::Primary,
+                    Some(ImageOptions {
+                        max_width: Some(300),
+                        tag: Some(tag),
+                        ..Default::default()
+                    }),
+                )
             })
         }),
         media_type: MediaType::Audio,
@@ -250,18 +270,25 @@ pub async fn player_add_tracks_by_ids(
 ) -> Result<QueueStatus, String> {
     use crate::player::queue::AddPosition;
 
-    info!("player_add_tracks_by_ids called: {} tracks, position={}",
-          request.track_ids.len(), request.position);
+    info!(
+        "player_add_tracks_by_ids called: {} tracks, position={}",
+        request.track_ids.len(),
+        request.position
+    );
 
     // Get repository (hybrid - supports offline/online)
-    let repository = repository_manager.0.get(&repository_handle)
+    let repository = repository_manager
+        .0
+        .get(&repository_handle)
         .ok_or("Repository not found - user may need to log in")?;
 
     // Fetch metadata and build MediaItems for all tracks
     let mut media_items = Vec::new();
     for track_id in &request.track_ids {
         info!("Fetching metadata for track {} via repository", track_id);
-        let track = repository.get_item(track_id).await
+        let track = repository
+            .get_item(track_id)
+            .await
             .map_err(|e| format!("Failed to fetch track metadata for {}: {}", track_id, e))?;
 
         // Check for local download first
@@ -275,7 +302,9 @@ pub async fn player_add_tracks_by_ids(
             }
         } else {
             // Get stream URL from repository (works online/offline)
-            let stream_url = repository.get_audio_stream_url(&track.id).await
+            let stream_url = repository
+                .get_audio_stream_url(&track.id)
+                .await
                 .map_err(|e| format!("Failed to get stream URL for {}: {}", track.name, e))?;
 
             MediaSource::Remote {
@@ -290,23 +319,30 @@ pub async fn player_add_tracks_by_ids(
             id: track.id.clone(),
             title: track.name.clone(),
             name: Some(track.name.clone()), // Frontend compatibility
-            artist: track.album_artist.clone().or_else(|| track.artists.as_ref().and_then(|a| a.first().cloned())),
+            artist: track
+                .album_artist
+                .clone()
+                .or_else(|| track.artists.as_ref().and_then(|a| a.first().cloned())),
             album: track.album_name.clone(),
             album_name: track.album_name.clone(), // Frontend compatibility
             album_id: track.album_id.clone(),
             artist_items: track.artist_items.clone(), // For clickable artist links
-            artists: track.artists.clone(), // Fallback artist info
+            artists: track.artists.clone(),           // Fallback artist info
             primary_image_tag: track.primary_image_tag.clone(), // For frontend image display
             item_type: Some(track.item_type.clone()), // Frontend compatibility
             playlist_id: None,
             duration: track.runtime_ticks.map(|t| t as f64 / 10_000_000.0),
             artwork_url: primary_image_tag_for_url.and_then(|tag| {
                 track.album_id.as_ref().map(|album_id| {
-                    repository.get_image_url(album_id, ImageType::Primary, Some(ImageOptions {
-                        max_width: Some(300),
-                        tag: Some(tag),
-                        ..Default::default()
-                    }))
+                    repository.get_image_url(
+                        album_id,
+                        ImageType::Primary,
+                        Some(ImageOptions {
+                            max_width: Some(300),
+                            tag: Some(tag),
+                            ..Default::default()
+                        }),
+                    )
                 })
             }),
             media_type: MediaType::Audio,
@@ -339,7 +375,10 @@ pub async fn player_add_tracks_by_ids(
     drop(queue_lock);
     controller.emit_queue_changed();
 
-    info!("Successfully added {} tracks to queue", request.track_ids.len());
+    info!(
+        "Successfully added {} tracks to queue",
+        request.track_ids.len()
+    );
     Ok(result)
 }