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/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt

@@ -23,13 +23,33 @@ class MainActivity : TauriActivity() {
   private val audioManager by lazy { getSystemService(Context.AUDIO_SERVICE) as AudioManager }
 
   /**
-   * Whether backgrounding the app during video should auto-enter PiP.
-   * The frontend clears this when video isn't the active local surface
-   * (e.g. remote/cast playback) via AndroidPictureInPicture.setAutoEnterEnabled.
+   * Coarse override for whether backgrounding the app should auto-enter PiP.
+   *
+   * This is NOT what excludes audio/browsing/cast from PiP — that is the
+   * PictureInPictureManager.canEnterPip guard, which requires a local video
+   * surface to be actively rendering and is re-checked in onUserLeaveHint. This
+   * flag is only toggled by the background-audio feature (via
+   * AndroidPictureInPicture.setAutoEnterEnabled) so background-audio mode and
+   * auto-PiP stay mutually exclusive.
    */
   @Volatile
   private var autoEnterPipEnabled = true
 
+  /**
+   * Whether the user armed background-audio mode on the current video (UR-040).
+   * When true, leaving the app hands audio off to the native ExoPlayer audio
+   * service (frontend-driven) instead of entering PiP, and video decode stops.
+   * The frontend sets this via AndroidBackgroundAudio.setEnabled.
+   */
+  @Volatile
+  private var backgroundAudioEnabled = false
+
+  /**
+   * The WebView carrying the Svelte UI, cached once found so lifecycle overrides
+   * can dispatch DOM events into it (native → frontend signalling).
+   */
+  private var mediaWebView: WebView? = null
+
   override fun onCreate(savedInstanceState: Bundle?) {
     enableEdgeToEdge()
     super.onCreate(savedInstanceState)
@@ -49,15 +69,62 @@ class MainActivity : TauriActivity() {
    * Called when the user leaves the app via Home or the gesture equivalent
    * (but NOT via Back). This is the standard hook for auto-entering PiP so
    * video keeps playing in a floating window instead of being backgrounded.
+   *
+   * TRACES: UR-041 | IR-026 | DR-053
    */
   override fun onUserLeaveHint() {
     super.onUserLeaveHint()
-    if (autoEnterPipEnabled && PictureInPictureManager.canEnterPip(this)) {
+    // Never enter PiP while background-audio mode is armed — the two are mutually
+    // exclusive (the handoff runs from onStop instead).
+    if (autoEnterPipEnabled && !backgroundAudioEnabled &&
+        PictureInPictureManager.canEnterPip(this)) {
       android.util.Log.d("MainActivity", "User leaving with video active - entering PiP")
       PictureInPictureManager.enterPip(this)
     }
   }
 
+  /**
+   * The app is no longer visible (Home, app switch, or screen lock). When
+   * background-audio mode is armed, tell the frontend to hand video playback off
+   * to the native audio service. onStop (rather than onUserLeaveHint) is used
+   * because it fires on screen-lock too, which is the primary use case (UR-040).
+   *
+   * TRACES: UR-040 | IR-025
+   */
+  override fun onStop() {
+    super.onStop()
+    if (backgroundAudioEnabled) {
+      dispatchWebEvent("jellytau-background")
+    }
+  }
+
+  /** The app is visible again — tell the frontend to resume WebView video. */
+  override fun onStart() {
+    super.onStart()
+    if (backgroundAudioEnabled) {
+      dispatchWebEvent("jellytau-foreground")
+    }
+  }
+
+  /**
+   * Dispatch a DOM CustomEvent into the WebView (native → frontend). Mirrors the
+   * evaluateJavascript pattern already used to unmute video elements. Posted to
+   * the WebView thread; safe no-op if the WebView isn't found yet.
+   */
+  private fun dispatchWebEvent(name: String) {
+    val webView = mediaWebView ?: run {
+      android.util.Log.w("MainActivity", "dispatchWebEvent('$name'): no WebView")
+      return
+    }
+    webView.post {
+      webView.evaluateJavascript(
+        "window.dispatchEvent(new CustomEvent('$name'));",
+        null
+      )
+      android.util.Log.d("MainActivity", "Dispatched web event: $name")
+    }
+  }
+
   override fun onPictureInPictureModeChanged(
     isInPictureInPictureMode: Boolean,
     newConfig: android.content.res.Configuration
@@ -85,6 +152,7 @@ class MainActivity : TauriActivity() {
       }
 
       android.util.Log.d("MainActivity", "WebView found! Configuring settings...")
+      mediaWebView = webView
 
       // Add JavaScript interface for audio focus control
       webView.addJavascriptInterface(object : Any() {
@@ -129,6 +197,23 @@ class MainActivity : TauriActivity() {
       }, "AndroidPictureInPicture")
       android.util.Log.d("MainActivity", "JavaScript interface 'AndroidPictureInPicture' added")
 
+      // Add JavaScript interface for background-audio mode (UR-040). The frontend
+      // arms/disarms it via the player toggle; the Activity uses the flag in its
+      // lifecycle overrides to decide between the audio handoff and PiP.
+      webView.addJavascriptInterface(object : Any() {
+        /** Frontend arms/disarms background-audio mode for the current video. */
+        @JavascriptInterface
+        fun setEnabled(enabled: Boolean) {
+          backgroundAudioEnabled = enabled
+          android.util.Log.d("MainActivity", "backgroundAudioEnabled = $enabled")
+        }
+
+        /** Whether background audio is available on this device (needs PiP-era APIs unnecessary; audio service always present on Android). */
+        @JavascriptInterface
+        fun isSupported(): Boolean = true
+      }, "AndroidBackgroundAudio")
+      android.util.Log.d("MainActivity", "JavaScript interface 'AndroidBackgroundAudio' added")
+
       // Set WebChromeClient to handle video playback and audio focus
       webView.webChromeClient = object : WebChromeClient() {
         override fun onShowCustomView(view: View?, callback: CustomViewCallback?) {
@@ -152,7 +237,6 @@ class MainActivity : TauriActivity() {
         domStorageEnabled = true
         allowFileAccess = true
         allowContentAccess = true
-        setRenderPriority(WebSettings.RenderPriority.HIGH)
         mixedContentMode = WebSettings.MIXED_CONTENT_ALWAYS_ALLOW
 
         android.util.Log.d("MainActivity", "WebView fully configured for media playback")

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

@@ -18,6 +18,8 @@ import com.dtourolle.jellytau.player.JellyTauPlayer
 /**
  * Drives Android picture-in-picture for native (ExoPlayer) video playback.
  *
+ * TRACES: UR-041 | IR-026 | DR-053
+ *
  * PiP shrinks the whole Activity into a floating window, so the only thing that
  * should remain visible is the video SurfaceView that [VideoOverlayManager]
  * attached at the bottom of the z-order. The WebView carrying the Svelte UI is