feat(video): let mpv decode video at all, behind one shared flag

mpv has never decoded a video frame in this app: the backend sets `video: no`
unconditionally, because Linux video has always been the webview's job and
decoding it twice would burn a core for a picture nobody sees. The render path
built in the previous commit therefore had nothing to draw.

With native video on, mpv is configured for video *and* `vo=libmpv` — the render
API only works through that output, and the default would try to open a window
of its own. Set at construction, because mpv resolves its video output when it
initialises and flipping the property later does not re-open one.

The flag lives in `player::native_video`, read by all three things that must
agree: the backend (configured before anything plays), the surface (nothing to
draw otherwise), and `get_player_status` (which tells the frontend whether to
use a `<video>` element — two decoders on one stream would fight over the
audio). A function rather than three `env::var` checks, because a capability
answered in several places is a capability whose answers drift: four separate
bugs this cycle came from exactly that shape.

Also fixes an ordering bug the first run exposed. The surface was attached in
`setup` before the player backend was constructed, and the mpv handle is
registered *during* that construction — so it found nothing every time and
logged "no mpv handle". Attaching after the backend exists is the whole fix.

Confirmed on a real run: mpv accepts `vo=libmpv`, the GL context comes up on
Tauri's vbox, and `mpv_render_context_create` succeeds — which also proves the
libepoxy data-symbol handling is right, since a wrong `get_proc_address` would
have taken SIGSEGV on the first GL call rather than returning cleanly.

No frame has reached the screen yet. The webview is still opaque, so it will
paint over anything drawn beneath it until transparency is set up.

Security: quick-xml 0.38.4 carried RUSTSEC-2026-0194 (quadratic parse on
duplicate attribute names) and RUSTSEC-2026-0195 (unbounded namespace
allocation, memory-exhaustion DoS). `cargo deny` gates CI on advisories, so this
would have failed the next release. Fixed by plist 1.8 -> 1.10, which pulls
quick-xml 0.41. Licences, bans and sources still pass.

UT-216 pins the flag's parsing: absent, empty, `0`, `no` and anything
unrecognised all mean off. A half-set variable that half-enabled the renderer
would configure mpv for video with nothing drawing it — audio over a black
rectangle.

Also removes a wall-clock timer from the waitForRepository late-arrival test,
which failed once under load. The assertion is about ordering, so it now
publishes on a microtask and cannot race.

docs/requirements.md

@@ -739,6 +739,7 @@ Internal architecture, components, and application logic.
 | UT-213 | The direct-play negotiation, one test per branch, against `PlaybackInfo` fixtures whose shapes were all observed on a live server: a supported source direct-plays; a remuxable one direct-streams and reports itself as *not* transcoding; an unsupported codec transcodes; undecodable audio overrides the server's direct-play offer (silent picture is worse than a transcode); a pinned audio track forces a transcode; a ceiling below the source bitrate transcodes even though the codec is fine, and the ladder agrees that rung constrains it; direct play wins over direct stream when both are offered. Plus the ceiling: a per-playback override governs the stream being opened without disturbing the durable default the Settings screen shows, and dropping it returns to that default | DR-225, DR-227 | Done |
 | UT-214 | The loader comes from the transport, never the URL. hls.js is attached for `hls` when available and the element's own loader when not; progressive and local files load directly; the element's `src` is emptied only when hls.js drives it. The two cases that fail against a substring check, and the reason the field exists: a `progressive` stream whose URL contains `.m3u8` is *not* given an HLS loader, and an `hls` stream whose URL contains no `.m3u8` *is*. Both failed against the pre-DR-225 implementation before the fix landed | DR-224 | Done |
 | UT-215 | Waiting for the repository rather than racing it: it resolves immediately when the session is already restored, resolves when the session arrives later (the race the player page lost on mount), still rejects when there genuinely is no session, unsubscribes once settled so a later store change cannot re-settle it, and leaves no armed timer to reject an already-resolved promise | DR-013 | Done |
+| UT-216 | The native-video opt-in is read from one place and only explicit truthy values enable it: absent, empty, `0`, `no`, `false` and anything unrecognised all mean off, because a half-set variable that half-enabled the renderer would configure mpv for video with nothing drawing it — audio over a black rectangle | DR-231 | Done |
 
 ### Integration Tests
 

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

@@ -2086,7 +2086,9 @@ pub async fn player_get_capabilities() -> Result<PlaybackCapabilities, String> {
 
     Ok(PlaybackCapabilities {
         uses_webview_audio: !native_audio,
-        supports_native_video: cfg!(target_os = "android"),
+        // TRACES: UR-080 | DR-235
+        supports_native_video: cfg!(target_os = "android")
+            || crate::player::native_video::enabled(),
     })
 }
 
@@ -2095,6 +2097,11 @@ pub(super) fn get_player_status(controller: &PlayerController) -> PlayerStatus {
     let (backend, use_html5_element) = if cfg!(target_os = "android") {
         // Android uses ExoPlayer native backend
         (VideoBackend::Native, false)
+    } else if crate::player::native_video::enabled() {
+        // mpv draws the picture on this desktop; the frontend must not also
+        // load it into a <video> element or the stream decodes twice and the
+        // two fight over the audio. TRACES: UR-080 | DR-235
+        (VideoBackend::Native, false)
     } else {
         // Linux and other platforms use HTML5 video element in frontend
         (VideoBackend::Html5, true)

src-tauri/src/lib.rs

@@ -1210,56 +1210,6 @@ pub fn run() {
             // listened for on the frontend via the generated bindings.
             builder.mount_events(app);
 
-            // Native video surface: put a GL area under Tauri's webview so mpv
-            // can draw beneath the controls (UR-080 / DR-231).
-            //
-            // 🔴 OFF BY DEFAULT — the naive reparent crashes the app on the
-            // first click. `tauri-runtime-wry`'s undecorated-resizing handler
-            // walks a hard-coded two-hop path on every button press in the
-            // webview:
-            //
-            //     webview.parent()          // "This one should be GtkBox"
-            //            .parent()          // ...and this one the GtkWindow
-            //            .downcast::<gtk::Window>().unwrap()
-            //
-            // Wrapping the webview in a GtkOverlay makes that chain
-            // webview → GtkOverlay → GtkBox, the downcast fails, and because the
-            // panic is non-unwinding it aborts the process. The decoration check
-            // that would otherwise make this handler inert runs *after* the
-            // unwrap, so no window configuration avoids it.
-            //
-            // This is the "only place Tauri-specific behaviour could still bite"
-            // that the spike named as the untested half of G1. It bites. The
-            // surface attaches perfectly and then dies on interaction, so
-            // "attached successfully" in the log is not the gate — a click is.
-            //
-            // Kept behind an env var rather than deleted so the next attempt has
-            // something to iterate on:  JELLYTAU_NATIVE_VIDEO=1 bun run tauri dev
-            //
-            // TRACES: UR-080 | DR-231
-            #[cfg(target_os = "linux")]
-            if std::env::var("JELLYTAU_NATIVE_VIDEO").as_deref() == Ok("1") {
-                use tauri::Manager;
-                log::warn!(
-                    "[INIT] JELLYTAU_NATIVE_VIDEO=1 — attaching the experimental \
-                     video surface (mpv drawn behind the webview, no reparenting)"
-                );
-                if let Some(window) = app.get_webview_window("main") {
-                    match window.default_vbox() {
-                        Ok(vbox) => {
-                            let handle = crate::player::mpv_backend::registered_handle();
-                            if crate::player::video_surface::attach(&vbox, handle) {
-                                info!("[INIT] Native video surface attached");
-                            } else {
-                                log::warn!("[INIT] Native video surface unavailable");
-                            }
-                        }
-                        Err(e) => {
-                            log::warn!("[INIT] No GTK vbox for the main window: {e}")
-                        }
-                    }
-                }
-            }
 
             // In-app update, desktop only.
             //
@@ -1400,6 +1350,61 @@ pub fn run() {
                 playback_reporter.clone(),
                 position_throttler.clone(),
             );
+            // Attached *after* the backend exists: the mpv handle is registered
+            // during its construction, and doing this in the order the code
+            // used to read produced "no mpv handle" every time — the surface was
+            // built before there was anything to draw from.
+            // Native video surface: put a GL area under Tauri's webview so mpv
+            // can draw beneath the controls (UR-080 / DR-231).
+            //
+            // 🔴 OFF BY DEFAULT — the naive reparent crashes the app on the
+            // first click. `tauri-runtime-wry`'s undecorated-resizing handler
+            // walks a hard-coded two-hop path on every button press in the
+            // webview:
+            //
+            //     webview.parent()          // "This one should be GtkBox"
+            //            .parent()          // ...and this one the GtkWindow
+            //            .downcast::<gtk::Window>().unwrap()
+            //
+            // Wrapping the webview in a GtkOverlay makes that chain
+            // webview → GtkOverlay → GtkBox, the downcast fails, and because the
+            // panic is non-unwinding it aborts the process. The decoration check
+            // that would otherwise make this handler inert runs *after* the
+            // unwrap, so no window configuration avoids it.
+            //
+            // This is the "only place Tauri-specific behaviour could still bite"
+            // that the spike named as the untested half of G1. It bites. The
+            // surface attaches perfectly and then dies on interaction, so
+            // "attached successfully" in the log is not the gate — a click is.
+            //
+            // Kept behind an env var rather than deleted so the next attempt has
+            // something to iterate on:  JELLYTAU_NATIVE_VIDEO=1 bun run tauri dev
+            //
+            // TRACES: UR-080 | DR-231
+            #[cfg(target_os = "linux")]
+            if crate::player::native_video::enabled() {
+                use tauri::Manager;
+                log::warn!(
+                    "[INIT] JELLYTAU_NATIVE_VIDEO=1 — attaching the experimental \
+                     video surface (mpv drawn behind the webview, no reparenting)"
+                );
+                if let Some(window) = app.get_webview_window("main") {
+                    match window.default_vbox() {
+                        Ok(vbox) => {
+                            let handle = crate::player::mpv_backend::registered_handle();
+                            if crate::player::video_surface::attach(&vbox, handle) {
+                                info!("[INIT] Native video surface attached");
+                            } else {
+                                log::warn!("[INIT] Native video surface unavailable");
+                            }
+                        }
+                        Err(e) => {
+                            log::warn!("[INIT] No GTK vbox for the main window: {e}")
+                        }
+                    }
+                }
+            }
+
             let player_controller = PlayerController::new(
                 backend,
                 playback_reporter.clone(),

src-tauri/src/player/mod.rs

@@ -24,6 +24,10 @@ pub mod android;
 #[cfg(target_os = "linux")]
 pub mod mpv_backend;
 
+/// Whether this process renders video natively — one answer, three consumers
+/// (UR-080 / DR-231, DR-235).
+pub mod native_video;
+
 /// mpv's render API into a framebuffer we own (UR-080 / DR-231, IR-033).
 ///
 /// Deliberately *not* GTK-gated beyond the platform that currently builds it:

src-tauri/src/player/mpv_backend.rs

@@ -163,9 +163,28 @@ impl MpvBackend {
                 message: format!("Failed to configure MPV audio-display: {:?}", e),
             })?;
 
-        mpv.set_property("video", "no").map_err(|e| PlayerError {
+        // Video is disabled unless this process is drawing it.
-            message: format!("Failed to configure MPV video: {:?}", e),
+        //
-        })?;
+        // `video: no` is why mpv has never decoded a frame here: Linux video has
+        // always gone through the webview, and decoding it twice would burn a
+        // core for a picture nobody sees. With native video on, mpv needs both
+        // the decoder *and* `vo=libmpv` — the render API only works through that
+        // output, and the default would try to open a window of its own.
+        //
+        // Set at construction because mpv resolves the video output when it
+        // initialises; flipping it later does not re-open one.
+        //
+        // TRACES: UR-080 | DR-231, DR-235
+        if super::native_video::enabled() {
+            mpv.set_property("vo", "libmpv").map_err(|e| PlayerError {
+                message: format!("Failed to select the libmpv video output: {:?}", e),
+            })?;
+            info!("[MpvBackend] native video enabled (vo=libmpv)");
+        } else {
+            mpv.set_property("video", "no").map_err(|e| PlayerError {
+                message: format!("Failed to configure MPV video: {:?}", e),
+            })?;
+        }
 
         // Set volume to 100% (we'll control via MPV's volume property)
         mpv.set_property("volume", 100i64)

src-tauri/src/player/native_video.rs

@@ -0,0 +1,78 @@
+//! Whether this process renders video natively, answered once.
+//!
+//! Three things need this and must agree: the mpv backend (which has to be
+//! configured for video *at construction*, before anything plays), the video
+//! surface (which has nothing to draw otherwise), and `get_player_status`
+//! (which tells the frontend whether to use a webview `<video>` element).
+//!
+//! It is a function rather than three `env::var` checks for the reason this
+//! codebase keeps rediscovering: a capability answered in several places is a
+//! capability whose answers drift. Four separate bugs this cycle came from
+//! exactly that shape — a webview's decode limits applied to ExoPlayer, a
+//! transcode target contradicting a direct-play claim, a codec list hardcoded in
+//! a URL builder. One source, read by everyone.
+//!
+//! TRACES: UR-080 | DR-231, DR-235
+
+/// The opt-in for native desktop video.
+///
+/// Off by default while the render path is unproven — the webview path still
+/// works and is what ships. This becomes the *default* (and then the only path)
+/// when DR-235 lands; the variable is how it is exercised until then.
+const ENV_FLAG: &str = "JELLYTAU_NATIVE_VIDEO";
+
+/// Whether mpv should decode and draw video in this process.
+///
+/// Read fresh rather than cached: it is consulted a handful of times at startup,
+/// and a `OnceLock` here would only make it harder to test.
+///
+/// TRACES: UR-080 | DR-231, DR-235
+pub fn enabled() -> bool {
+    // Only where a native renderer exists. On Android ExoPlayer already does
+    // this and `use_html5_element` is false for entirely separate reasons.
+    if !cfg!(all(target_os = "linux", not(target_os = "android"))) {
+        return false;
+    }
+    matches!(
+        std::env::var(ENV_FLAG).as_deref(),
+        Ok("1") | Ok("true") | Ok("yes")
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Absent, empty, or anything unrecognised means off. A half-set variable
+    /// must not half-enable a renderer — the failure mode would be mpv
+    /// configured for video with nothing drawing it, i.e. audio playing over a
+    /// black rectangle.
+    ///
+    /// TRACES: UR-080 | DR-231 | UT-216
+    #[test]
+    fn test_only_explicit_truthy_values_enable_it() {
+        let restore = std::env::var(ENV_FLAG).ok();
+
+        for value in ["", "0", "no", "false", "maybe", "2"] {
+            std::env::set_var(ENV_FLAG, value);
+            assert!(!enabled(), "{value:?} must not enable native video");
+        }
+
+        for value in ["1", "true", "yes"] {
+            std::env::set_var(ENV_FLAG, value);
+            assert_eq!(
+                enabled(),
+                cfg!(all(target_os = "linux", not(target_os = "android"))),
+                "{value:?} enables it exactly where a native renderer exists"
+            );
+        }
+
+        std::env::remove_var(ENV_FLAG);
+        assert!(!enabled(), "absent means off");
+
+        match restore {
+            Some(v) => std::env::set_var(ENV_FLAG, v),
+            None => std::env::remove_var(ENV_FLAG),
+        }
+    }
+}

src/lib/stores/auth.waitForRepository.test.ts

@@ -72,8 +72,11 @@ describe("waitForRepository", () => {
     const w = makeWaiter();
     const repo = {};
     const pending = w.waitForRepository(1000);
-    // Nothing yet; the page has already mounted and asked.
+    // Nothing yet; the page has already mounted and asked. Published on a
-    setTimeout(() => w.publish(repo), 10);
+    // microtask rather than a timer: the point is *ordering* (asked before it
+    // arrived), and a wall-clock delay would make this a race under load.
+    await Promise.resolve();
+    w.publish(repo);
     await expect(pending).resolves.toBe(repo);
   });