feat(player): render Android video natively behind a transparent webview (DR-150, DR-151, DR-152)

Rust already reported `use_html5_element: false` on Android, but two frontend overrides threw that answer away, so ExoPlayer's video path had never actually run. Both are lifted behind an `experimentalNativeVideo` opt-in (default off). The flag is a suppressor, never a promoter: off forces HTML5 even where Rust says native, so an in-progress spike cannot ship as the default, but it can never select native where Rust reported HTML5 — Linux cannot composite behind WebKitGTK, and promoting there would be a black screen. Two blockers the spec did not anticipate, both in code assumed to be merely unreachable rather than broken: - `JellyTauPlayer.setActivity()` had zero callers, so `currentActivity` was always null and `autoAttachSurface()` bailed. The SurfaceView was created and wired to ExoPlayer but never added to the view hierarchy — video would have decoded to a surface that was never on screen, whatever the webview did. This also revives PiP on the video path, which gated on the same flag. - `createAdapter()` was not the real gate; it is never called in production. The actual override was in VideoPlayer.svelte, which forced HTML5 and stopped the native backend `player_play_item` had just started. Both sites now route through `createAdapter()`. Compositing needs two independent opaque layers cleared, not one. Clearing only the page leaves the WebView widget opaque — audio over a black picture, exactly the symptom the old INTERIM comment described. `videoSurface.ts` toggles both: the widget background and window drawable from Kotlin, the page backgrounds via a `data-native-video` attribute keyed by app.css. Transparency lives in `tauri.android.conf.json` so Linux keeps an opaque window, and is scoped to the playback session so the launcher never shows through the rest of the app. Phase 3's rect plumbing turned out to be unnecessary: video is fullscreen on the player route, and `fitSurfaceToScreen()` already letterboxes and re-fits on rotation. The mini-player transition remains unverified on device. Also removes the `navigator.userAgent` sniffing in webviewAudio.ts, which was a second copy of the Rust cfg gate free to drift from it. `player_get_capabilities` now reports `usesWebviewAudio` and `supportsNativeVideo` from those same gates. Tests: adapter selection covers the full matrix, including the regression guard that the flag off beats Rust. Written first and confirmed failing (2 of 7) before the fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 20:57:58 +02:00
parent 07d10dfed7
commit e144e62b31
16 changed files with 745 additions and 56 deletions
@@ -51,6 +51,30 @@ html, body {
  background-color: var(--color-background);
 }

+/* Native-video compositing (Android).
+ *
+ * TRACES: UR-003, UR-004 | DR-150
+ *
+ * When ExoPlayer renders into a SurfaceView *behind* the WebView, every opaque
+ * layer between the viewport and that surface hides the video. The WebView
+ * itself is made transparent by `"transparent": true` in
+ * tauri.android.conf.json; these rules clear the app's own painted backgrounds.
+ *
+ * Scoped to `[data-native-video="active"]` — set on <html> by
+ * $lib/stores/nativeVideo.ts only while a native video session is on screen —
+ * because every other screen genuinely needs its opaque background. The app
+ * shell (+layout.svelte) also paints --color-background across the viewport, so
+ * it is cleared here too; the shell is the layer directly over the surface.
+ *
+ * `background: transparent` (not a colour) is required: an alpha-0 colour still
+ * composites in some WebView versions.
+ */
+html[data-native-video="active"],
+html[data-native-video="active"] body,
+html[data-native-video="active"] [data-app-shell] {
+  background: transparent !important;
+}
+
 body {
  @apply text-white antialiased;
  font-family: system-ui, -apple-system, sans-serif;
@@ -143,6 +143,14 @@ async playerGetStatus() : Promise<PlayerStatus> {
 async playerGetQueue() : Promise<QueueStatus> {
    return await TAURI_INVOKE("player_get_queue");
 },
+/**
+ * Report this platform's playback capabilities to the frontend.
+ * 
+ * TRACES: UR-003, UR-005 | DR-004, DR-023, DR-024
+ */
+async playerGetCapabilities() : Promise<PlaybackCapabilities> {
+    return await TAURI_INVOKE("player_get_capabilities");
+},
 async playerAddToQueue(request: AddToQueueRequest) : Promise<QueueStatus> {
    return await TAURI_INVOKE("player_add_to_queue", { request });
 },
@@ -2293,6 +2301,30 @@ export type PlayTracksRequest = { trackIds: string[]; startIndex: number; shuffl
 * over playback from a remote session so we don't restart from 0.
 */
 startPosition?: number | null }
+/**
+ * What playback facilities this platform's backend actually provides.
+ * 
+ * The frontend is presentation-only and must not re-derive backend facts from
+ * `navigator.userAgent` — that sniffing was a second copy of the same platform
+ * decision Rust already makes with `cfg!`, and it drifted. These flags are the
+ * single source of truth; the frontend consumes them.
+ * 
+ * TRACES: UR-003, UR-005 | DR-004, DR-023, DR-024
+ */
+export type PlaybackCapabilities = { 
+/**
+ * True when audio is rendered by a webview `<audio>` element rather than a
+ * native backend. Native audio exists on Linux (mpv) and Android
+ * (ExoPlayer); everything else (Windows, future desktops) uses the webview.
+ */
+usesWebviewAudio: boolean; 
+/**
+ * True when video can be rendered by a native surface composited *behind*
+ * a transparent webview. Android only: ExoPlayer draws into a SurfaceView
+ * beneath the WebView. Linux cannot do this (WebKitGTK/Wayland
+ * compositing), so it stays on the HTML5 element.
+ */
+supportsNativeVideo: boolean }
 /**
 * Playback information
 */
@@ -26,8 +26,18 @@
  import { playbackPosition, playerState } from "$lib/stores/player";
  import * as html5Adapter from "$lib/player/html5Adapter";
  import { playerController } from "$lib/player";
-  import { Html5PlayerAdapter, type Html5ElementBridge } from "$lib/player/adapters";
+  import {
+    createAdapter,
+    Html5PlayerAdapter,
+    type PlayerAdapter,
+    type Html5ElementBridge,
+  } from "$lib/player/adapters";
  import { createRustReportHost } from "$lib/player/adapters/rustReportHost";
+  import { experimentalNativeVideo } from "$lib/stores/nativeVideo";
+  import {
+    enableNativeVideoCompositing,
+    disableNativeVideoCompositing,
+  } from "$lib/utils/videoSurface";
  import { isPipSupported, enterPip, setAutoEnterEnabled } from "$lib/utils/pictureInPicture";
  import {
    createTapGestureState,
@@ -166,7 +176,10 @@
  // VideoPlayer supplies a narrow bridge for the element/HLS-coupled parts and
  // registers the adapter with the facade so control intents — from UI OR from a
  // backend control event (lockscreen/remote/sleep) — reach this element.
-  let playerAdapter: Html5PlayerAdapter | null = null;
+  // Widened from Html5PlayerAdapter: the native path registers a
+  // NativePlayerAdapter here. Element-coupled work is guarded by
+  // `useHtml5Element`, not by narrowing this type.
+  let playerAdapter: PlayerAdapter | null = null;

  function tearDownHls() {
    if (hls) {
@@ -645,15 +658,16 @@
        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)");
+        // Rust reported a native backend (Android/ExoPlayer). Honour it only if
+        // the user opted into the experimental native path; otherwise fall back
+        // to the webview element, which is what shipped by default.
+        //
+        // The flag is a suppressor, never a promoter — see createAdapter(). When
+        // it is off we must also stop the native backend that player_play_item
+        // just started, or ExoPlayer and the <video> element both decode the
+        // same stream and the audio doubles.
+        if (!useHtml5Element && !$experimentalNativeVideo) {
+          console.log("[VideoPlayer] Native backend available but experimentalNativeVideo is off - using HTML5");
          useHtml5Element = true;
          try {
            await commands.playerStop();
@@ -661,6 +675,14 @@
          } catch (err) {
            console.warn("[VideoPlayer] Failed to stop native backend:", err);
          }
+        } else if (!useHtml5Element) {
+          // Native path: clear the opaque layers between the viewport and the
+          // ExoPlayer SurfaceView (webview widget background + page background).
+          // Paired with disableNativeVideoCompositing() in the teardown path —
+          // leaving this on renders the rest of the app over a transparent
+          // window.
+          console.log("[VideoPlayer] Using native ExoPlayer video surface");
+          enableNativeVideoCompositing();
        }

        // If using HTML5 element for non-transcoded content, stop the backend player
@@ -679,14 +701,24 @@
          didStartNativePlayback = true; // Track that we need to stop backend on unmount
        }

-        // Register the HTML5 player adapter with the facade so control intents
-        // (UI or backend lockscreen/remote/sleep events) route to this element.
-        if (useHtml5Element) {
+        // Register the adapter with the facade so control intents (UI, or a
+        // backend lockscreen/remote/sleep event) route to whatever is actually
+        // rendering. Both paths need one: the native adapter forwards control
+        // intents to ExoPlayer over IPC.
+        {
          const host = createRustReportHost(media.id, {
            onEnded: () => notifyEnded(),
            onStreamUrlChanged: (u) => { currentStreamUrl = u; },
          });
-          playerAdapter = new Html5PlayerAdapter(host, adapterBridge);
+          playerAdapter = createAdapter({
+            backendKind: useHtml5Element ? "html5" : "native",
+            host,
+            bridge: adapterBridge,
+            // useHtml5Element is already the resolved decision above, so the
+            // flag has had its say; pass it through for the invariant check.
+            experimentalNativeVideo: $experimentalNativeVideo,
+          });
+          // No-op for the native adapter, which owns no DOM element.
          playerAdapter.attach(videoElement);
          playerController.setActiveAdapter(playerAdapter);
        }
@@ -780,6 +812,14 @@
  });

  onDestroy(async () => {
+    // FIRST, and synchronously: restore the opaque webview/page backgrounds.
+    //
+    // This callback is async, so anything after an `await` may run a frame or
+    // more later. Leaving the window transparent for even that long shows the
+    // launcher/wallpaper through the app as the player unwinds. Unconditional
+    // and idempotent — a no-op when compositing was never enabled.
+    disableNativeVideoCompositing();
+
    // Stop RAF loop
    stopTimeUpdates();

@@ -0,0 +1,95 @@
+/**
+ * Adapter-selection regression guards.
+ *
+ * TRACES: UR-003, UR-004 | DR-150 | UT-149
+ *
+ * The selection rule has two inputs and one hard safety property:
+ *
+ *   - Rust says which backend the platform has (`backendKind`).
+ *   - The user opts in with `experimentalNativeVideo`.
+ *   - **The flag off must force HTML5 even when Rust says native.** That is the
+ *     regression guard: a broken spike must not be able to ship as the default.
+ *
+ * These are pure functions, so the whole matrix is testable without a device.
+ */
+
+import { describe, expect, it } from "vitest";
+import { createAdapter } from "./index";
+import { Html5PlayerAdapter } from "./html5Adapter";
+import { NativePlayerAdapter } from "./nativeAdapter";
+import type { AdapterHost } from "./types";
+
+const host: AdapterHost = {
+  reportState: () => {},
+  reportPosition: () => {},
+  reportEnded: () => {},
+} as unknown as AdapterHost;
+
+const bridge = {
+  getElement: () => null,
+} as any;
+
+describe("createAdapter", () => {
+  it("returns the native adapter when Rust says native and the flag is on", () => {
+    const adapter = createAdapter({
+      backendKind: "native",
+      host,
+      bridge,
+      experimentalNativeVideo: true,
+    });
+    expect(adapter).toBeInstanceOf(NativePlayerAdapter);
+    expect(adapter.kind).toBe("native");
+  });
+
+  // The regression guard: the flag is a suppressor, so off must beat Rust.
+  it("forces HTML5 when the flag is off even though Rust says native", () => {
+    const adapter = createAdapter({
+      backendKind: "native",
+      host,
+      bridge,
+      experimentalNativeVideo: false,
+    });
+    expect(adapter).toBeInstanceOf(Html5PlayerAdapter);
+    expect(adapter.kind).toBe("html5");
+  });
+
+  it("returns the HTML5 adapter when Rust says html5 and the flag is off", () => {
+    const adapter = createAdapter({
+      backendKind: "html5",
+      host,
+      bridge,
+      experimentalNativeVideo: false,
+    });
+    expect(adapter).toBeInstanceOf(Html5PlayerAdapter);
+  });
+
+  // The flag must never *promote* a platform Rust said has no native backend
+  // (e.g. Linux, where WebKitGTK cannot composite a surface behind the webview).
+  it("stays on HTML5 when Rust says html5 even with the flag on", () => {
+    const adapter = createAdapter({
+      backendKind: "html5",
+      host,
+      bridge,
+      experimentalNativeVideo: true,
+    });
+    expect(adapter).toBeInstanceOf(Html5PlayerAdapter);
+  });
+
+  it("defaults to HTML5 when the flag is omitted entirely", () => {
+    const adapter = createAdapter({ backendKind: "native", host, bridge });
+    expect(adapter).toBeInstanceOf(Html5PlayerAdapter);
+  });
+
+  it("requires a bridge for the HTML5 adapter", () => {
+    expect(() =>
+      createAdapter({ backendKind: "html5", host, experimentalNativeVideo: false })
+    ).toThrow(/bridge/i);
+  });
+
+  // The native adapter owns no DOM element, so it must not demand a bridge.
+  it("does not require a bridge for the native adapter", () => {
+    expect(() =>
+      createAdapter({ backendKind: "native", host, experimentalNativeVideo: true })
+    ).not.toThrow();
+  });
+});
@@ -2,13 +2,22 @@
 * Player adapter factory + public exports.
 *
 * `createAdapter` selects the concrete PlayerAdapter for the current platform.
- * It is the single place that encodes the INTERIM Android override: the Rust
- * backend may report a native ExoPlayer backend, but native Android video
- * rendering is blocked upstream (tauri#10152 — transparent webview / SurfaceView
- * compositing), so we render Android video through the HTML5 adapter for now.
- * When that upstream limitation is resolved, flip this to honor `backendKind`.
+ * Rust decides *which backend this platform has* (`useHtml5Element` from
+ * `player_play_item`); this factory consumes that decision rather than
+ * re-deriving it.
 *
- * TRACES: UR-003 | DR-004
+ * The `experimentalNativeVideo` flag is a **suppressor, never a promoter**: it
+ * can force the HTML5 path when Rust says native (so an in-progress spike cannot
+ * ship as a regression), but it can never select native on a platform whose Rust
+ * backend reported HTML5 — Linux has no way to composite a surface behind a
+ * WebKitGTK webview, so promoting there would produce a black screen.
+ *
+ * The previous unconditional HTML5 override cited tauri#10152 as an upstream
+ * blocker. That was stale: #10152 is a dormant *feature request*, the capability
+ * shipped in tauri 27d01834, and the black-screen bug (tauri#8381, #9408) was a
+ * broken `setBackgroundColor` JNI signature fixed in wry 0.39.4 — we ship 0.53.x.
+ *
+ * TRACES: UR-003, UR-004 | DR-004, DR-150 | UT-149
 */

 import { Html5PlayerAdapter, type Html5ElementBridge } from "./html5Adapter";
@@ -29,27 +38,36 @@ export interface CreateAdapterArgs {
  host: AdapterHost;
  /** Required for the HTML5 adapter; ignored by the native adapter. */
  bridge?: Html5ElementBridge;
+  /**
+   * User opt-in for the native video path. Defaults to **off**, so omitting it
+   * yields today's behaviour (HTML5 everywhere) rather than silently enabling
+   * the spike.
+   */
+  experimentalNativeVideo?: boolean;
 }

 /**
 * Build the adapter for this platform/stream.
 *
- * INTERIM: always returns the HTML5 adapter, because the native surface is not
- * visible through the webview on current Tauri (see module docs). The bridge is
- * therefore required.
+ * Native is chosen only when Rust reports a native backend AND the user has
+ * opted in. Every other combination is HTML5.
 */
-export function createAdapter({ backendKind, host, bridge }: CreateAdapterArgs): PlayerAdapter {
-  // INTERIM OVERRIDE: force HTML5 rendering even when the backend reports native.
-  const effectiveKind: BackendKind = "html5";
+export function createAdapter({
+  backendKind,
+  host,
+  bridge,
+  experimentalNativeVideo = false,
+}: CreateAdapterArgs): PlayerAdapter {
+  const effectiveKind: BackendKind =
+    backendKind === "native" && experimentalNativeVideo ? "native" : "html5";

-  if (effectiveKind === "html5") {
-    if (!bridge) {
-      throw new Error("createAdapter: Html5ElementBridge is required for the HTML5 adapter");
-    }
-    return new Html5PlayerAdapter(host, bridge);
+  if (effectiveKind === "native") {
+    // The native surface is owned by the backend — no DOM element, no bridge.
+    return new NativePlayerAdapter(host);
  }

-  // Reached only once the interim override is lifted (native Android unblocked).
-  void backendKind;
-  return new NativePlayerAdapter(host);
+  if (!bridge) {
+    throw new Error("createAdapter: Html5ElementBridge is required for the HTML5 adapter");
+  }
+  return new Html5PlayerAdapter(host, bridge);
 }
@@ -0,0 +1,70 @@
+/**
+ * Platform playback capabilities, read from Rust.
+ *
+ * TRACES: UR-003, UR-005 | DR-004, DR-152
+ *
+ * "Which backend does this platform have" is a *backend* fact, so Rust owns it
+ * (`player_get_capabilities`, gated on the same `cfg!` the backends are built
+ * under). This module is a thin cache over that command.
+ *
+ * It exists because the frontend used to re-derive the answer by sniffing
+ * `navigator.userAgent` for "android"/"linux" — a second, silently drifting copy
+ * of a decision Rust already makes. Consume the value; never re-derive it.
+ */
+
+import { commands } from "$lib/api/bindings";
+
+export interface PlaybackCapabilities {
+  /** Audio renders through a webview `<audio>` element, not a native backend. */
+  usesWebviewAudio: boolean;
+  /** Video can render on a native surface behind a transparent webview. */
+  supportsNativeVideo: boolean;
+}
+
+/**
+ * Conservative defaults for when the backend cannot be reached (very early
+ * startup, or a command failure). Both false = "assume no special platform
+ * facilities": no stray `<audio>` element is mounted, and video stays on the
+ * HTML5 path, which is the safe behaviour everywhere.
+ */
+const FALLBACK: PlaybackCapabilities = {
+  usesWebviewAudio: false,
+  supportsNativeVideo: false,
+};
+
+let cached: PlaybackCapabilities | null = null;
+let inflight: Promise<PlaybackCapabilities> | null = null;
+
+/**
+ * Fetch (and memoize) this platform's capabilities. Cached because the answer is
+ * compile-time constant in Rust — it cannot change during a session.
+ */
+export async function getPlaybackCapabilities(): Promise<PlaybackCapabilities> {
+  if (cached) return cached;
+  if (inflight) return inflight;
+
+  inflight = (async () => {
+    try {
+      const caps = (await commands.playerGetCapabilities()) as PlaybackCapabilities;
+      cached = {
+        usesWebviewAudio: !!caps?.usesWebviewAudio,
+        supportsNativeVideo: !!caps?.supportsNativeVideo,
+      };
+      return cached;
+    } catch (err) {
+      console.warn("[capabilities] player_get_capabilities failed:", err);
+      // Do NOT cache the fallback — a later call should get the real answer.
+      return FALLBACK;
+    } finally {
+      inflight = null;
+    }
+  })();
+
+  return inflight;
+}
+
+/** Reset the cache. Test-only. */
+export function __resetPlaybackCapabilitiesCache(): void {
+  cached = null;
+  inflight = null;
+}
@@ -23,31 +23,25 @@ import { events } from "$lib/api/bindings";
 import { playerController } from "$lib/player";
 import { createRustReportHost } from "$lib/player/adapters/rustReportHost";
 import { WebviewAudioAdapter } from "$lib/player/adapters/webviewAudioAdapter";
+import { getPlaybackCapabilities } from "$lib/services/playbackCapabilities";

 let unlisten: UnlistenFn | null = null;
 let audioEl: HTMLAudioElement | null = null;
 let adapter: WebviewAudioAdapter | null = null;

-/** Platforms whose Rust backend renders audio in the webview rather than natively. */
-function usesWebviewAudio(): boolean {
-  // Native audio backends exist only for Linux (mpv) and Android (ExoPlayer).
-  // Everything else (Windows, and any future desktop) uses the webview element.
-  // We detect "not linux/android" rather than "is windows" so new desktop
-  // targets are covered automatically, matching the Rust cfg gate.
-  if (typeof navigator === "undefined") return false;
-  const ua = navigator.userAgent.toLowerCase();
-  const isAndroid = ua.includes("android");
-  const isLinux = ua.includes("linux") && !isAndroid;
-  return !isAndroid && !isLinux;
-}
-
 /**
 * Initialize the webview audio controller. Safe to call unconditionally from the
 * root layout; it self-gates on platform and is idempotent.
 */
 export async function initWebviewAudio(): Promise<void> {
  if (unlisten) return;
-  if (!usesWebviewAudio()) return;
+
+  // Whether this platform needs the webview element is a backend fact, so Rust
+  // answers it. This used to sniff `navigator.userAgent` for "android"/"linux"
+  // — a duplicate of the Rust cfg gate that could drift out of step with the
+  // backends it was trying to describe.
+  const { usesWebviewAudio } = await getPlaybackCapabilities();
+  if (!usesWebviewAudio) return;

  audioEl = document.createElement("audio");
  audioEl.hidden = true;
@@ -0,0 +1,91 @@
+// Native-video compositing state.
+//
+// TRACES: UR-003, UR-004 | DR-150, DR-152
+//
+// Two separate concerns live here, deliberately:
+//
+//  1. `experimentalNativeVideo` — the user-facing opt-in flag. Rust already
+//     decides *which backend this platform has* (`useHtml5Element` from
+//     `player_play_item`); this flag only *suppresses* that decision so a
+//     half-working spike cannot ship as a regression. It never turns native on
+//     where Rust says HTML5.
+//
+//  2. `nativeVideoActive` — whether a native surface is on screen right now.
+//     Setting it toggles `data-native-video` on <html>, which is what the CSS in
+//     app.css keys off to clear the app's opaque backgrounds so the SurfaceView
+//     behind the WebView is visible. It is deliberately NOT derived from the
+//     flag: the backgrounds must come back the moment the player unmounts.
+//
+// Frontend-only preference, stored in localStorage per the `jellytau-view-mode`
+// precedent in library.ts — no Rust settings command backs this.
+
+import { writable } from "svelte/store";
+
+const STORAGE_KEY = "jellytau-experimental-native-video";
+
+/** The attribute app.css keys its transparency rules off. */
+const NATIVE_VIDEO_ATTR = "data-native-video";
+
+function load(): boolean {
+  if (typeof localStorage === "undefined") return false;
+  try {
+    return localStorage.getItem(STORAGE_KEY) === "true";
+  } catch {
+    // Private-mode / disabled storage — default to the safe (HTML5) path.
+    return false;
+  }
+}
+
+function persist(enabled: boolean) {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.setItem(STORAGE_KEY, String(enabled));
+  } catch {
+    // Quota or private-mode failure — keep the in-memory value.
+  }
+}
+
+function createExperimentalNativeVideoStore() {
+  const { subscribe, set } = writable<boolean>(load());
+
+  return {
+    subscribe,
+    set(enabled: boolean) {
+      persist(enabled);
+      set(enabled);
+    },
+    /** Read the current value without subscribing (init-time decisions). */
+    current: load,
+  };
+}
+
+/** User opt-in for the native Android video path. Default off. */
+export const experimentalNativeVideo = createExperimentalNativeVideoStore();
+
+function createNativeVideoActiveStore() {
+  const { subscribe, set } = writable<boolean>(false);
+
+  return {
+    subscribe,
+    /**
+     * Mark a native video surface as visible (or gone) and sync the <html>
+     * attribute that app.css uses to clear opaque backgrounds.
+     */
+    set(active: boolean) {
+      if (typeof document !== "undefined") {
+        if (active) {
+          document.documentElement.setAttribute(NATIVE_VIDEO_ATTR, "active");
+        } else {
+          document.documentElement.removeAttribute(NATIVE_VIDEO_ATTR);
+        }
+      }
+      set(active);
+    },
+  };
+}
+
+/**
+ * Whether a native video surface is currently on screen. Must be cleared on
+ * player teardown, or the rest of the app renders over a transparent window.
+ */
+export const nativeVideoActive = createNativeVideoActiveStore();
@@ -0,0 +1,86 @@
+/**
+ * Native video surface compositing, Android only.
+ *
+ * TRACES: UR-003, UR-004 | DR-150, DR-151
+ *
+ * On Android, ExoPlayer renders video into a SurfaceView that sits *behind* the
+ * Tauri WebView (`setZOrderMediaOverlay(false)`, added at index 0 of the content
+ * view by VideoOverlayManager). For that video to be visible, two independent
+ * opaque layers have to be cleared:
+ *
+ *  1. The **WebView widget's own background** — reachable only from Kotlin, via
+ *     the `AndroidVideoSurface` @JavascriptInterface installed by MainActivity.
+ *  2. The **web page's backgrounds** — the `html`/`body` colour in app.css and
+ *     the app shell's `bg-[var(--color-background)]`. Handled by the
+ *     `data-native-video` attribute, which $lib/stores/nativeVideo.ts sets and
+ *     app.css keys its transparency rules off.
+ *
+ * Clearing only one leaves a black screen with audio, which is exactly the
+ * failure mode the old INTERIM override in VideoPlayer.svelte was working
+ * around. Both must be toggled together, so this module owns both halves.
+ *
+ * Everything here is a no-op off Android — the bridge is simply absent.
+ */
+
+import { nativeVideoActive } from "$lib/stores/nativeVideo";
+
+interface AndroidVideoSurfaceBridge {
+  setTransparent(transparent: boolean): void;
+  isSupported(): boolean;
+}
+
+declare global {
+  interface Window {
+    AndroidVideoSurface?: AndroidVideoSurfaceBridge;
+  }
+}
+
+function bridge(): AndroidVideoSurfaceBridge | undefined {
+  if (typeof window === "undefined") return undefined;
+  return window.AndroidVideoSurface;
+}
+
+/**
+ * Whether the native-surface bridge exists on this platform. This reports only
+ * that the *plumbing* is present; whether native video should actually be used
+ * is Rust's decision (`player_get_capabilities`) gated by the user's
+ * `experimentalNativeVideo` flag.
+ */
+export function isNativeSurfaceBridgeAvailable(): boolean {
+  try {
+    return bridge()?.isSupported() ?? false;
+  } catch (err) {
+    console.warn("[videoSurface] isSupported check failed:", err);
+    return false;
+  }
+}
+
+/**
+ * Make the webview transparent so the video surface behind it shows through.
+ *
+ * MUST be paired with {@link disableNativeVideoCompositing} on teardown — a
+ * transparent window left behind shows the launcher through the whole app.
+ */
+export function enableNativeVideoCompositing(): void {
+  // Page layer first: if the Kotlin call succeeded but this threw, the user
+  // would see through the app to the home screen.
+  nativeVideoActive.set(true);
+  try {
+    bridge()?.setTransparent(true);
+  } catch (err) {
+    console.warn("[videoSurface] setTransparent(true) failed:", err);
+    nativeVideoActive.set(false);
+  }
+}
+
+/** Restore the opaque webview background. Safe to call unconditionally. */
+export function disableNativeVideoCompositing(): void {
+  try {
+    bridge()?.setTransparent(false);
+  } catch (err) {
+    console.warn("[videoSurface] setTransparent(false) failed:", err);
+  }
+  // Always clear the page layer, even if the bridge call failed, so the app is
+  // never left rendering over a transparent window.
+  nativeVideoActive.set(false);
+}
@@ -1,6 +1,6 @@
 <!-- TRACES: UR-023, UR-025, UR-027, UR-029, UR-057 | DR-030, DR-048, DR-077, DR-086, DR-132 -->
 <script lang="ts">
-  import { onMount } from "svelte";
+  import { onDestroy, onMount } from "svelte";
  import { commands } from "$lib/api/bindings";
  import type {
    AudioSettings,
@@ -26,6 +26,8 @@
    isNetworkDetectionSupported,
    reportNetworkState,
  } from "$lib/services/networkType";
+  import { experimentalNativeVideo } from "$lib/stores/nativeVideo";
+  import { getPlaybackCapabilities } from "$lib/services/playbackCapabilities";

  const episodeLimitOptions = [
    { value: 0, label: "Unlimited" },
@@ -97,8 +99,27 @@
    { label: "Unlimited", bytes: 0 },
  ];

+  // Native-video opt-in (Android). `supportsNativeVideo` comes from Rust, which
+  // owns the "does this platform have a native video surface" decision; the
+  // toggle is hidden entirely where it cannot apply.
+  let supportsNativeVideo = $state(false);
+  let nativeVideoEnabled = $state(false);
+
+  const unsubscribeNativeVideo = experimentalNativeVideo.subscribe((v) => {
+    nativeVideoEnabled = v;
+  });
+
+  function handleNativeVideoToggle() {
+    experimentalNativeVideo.set(!nativeVideoEnabled);
+  }
+
+  // Not returned from onMount: that callback is async, so its return value is a
+  // Promise and Svelte would never invoke it as a teardown.
+  onDestroy(unsubscribeNativeVideo);
+
  onMount(async () => {
    await loadSettings();
+    supportsNativeVideo = (await getPlaybackCapabilities()).supportsNativeVideo;
  });

  async function loadSettings() {
@@ -659,6 +680,46 @@
            </div>
          {/if}
        </div>
+
+        <!-- Native video (experimental). Only rendered where the platform's Rust
+             backend actually has a native video surface (Android). -->
+        {#if supportsNativeVideo}
+          <div class="bg-[var(--color-surface)] rounded-lg p-6 mt-4">
+            <div class="flex items-center justify-between">
+              <div class="pr-4">
+                <h3 class="text-xl font-semibold text-white">
+                  Native Video
+                  <span
+                    class="ml-2 align-middle text-xs font-medium uppercase tracking-wide text-amber-400 border border-amber-400/40 rounded px-1.5 py-0.5"
+                  >
+                    Experimental
+                  </span>
+                </h3>
+                <p class="text-sm text-gray-400 mt-1">
+                  Decode video with the device's hardware decoder instead of the
+                  built-in web player. Better performance and battery life, but
+                  less tested — turn this off if video fails to appear.
+                </p>
+              </div>
+              <button
+                onclick={handleNativeVideoToggle}
+                class="relative inline-flex h-8 w-14 shrink-0 items-center rounded-full transition-colors {nativeVideoEnabled
+                  ? 'bg-[var(--color-jellyfin)]'
+                  : 'bg-gray-600'}"
+                aria-label="Toggle native video"
+              >
+                <span
+                  class="inline-block h-6 w-6 transform rounded-full bg-white transition-transform {nativeVideoEnabled
+                    ? 'translate-x-7'
+                    : 'translate-x-1'}"
+                ></span>
+              </button>
+            </div>
+            <p class="text-xs text-gray-500 mt-3">
+              Takes effect the next time you start a video.
+            </p>
+          </div>
+        {/if}
      </div>

      <!-- Search Settings -->