From a64e1b1fb4e7542074addc530ac1ec3318ecf5d6 Mon Sep 17 00:00:00 2001
From: Duncan Tourolle <duncan@tourolle.paris>
Date: Thu, 2 Jul 2026 19:56:20 +0200
Subject: [PATCH 1/2] Introduce PlayerAdapter contract; decision logic shared
 in Rust backend
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Establish a decoupled player boundary so UI and backend interact with video
through one contract, with the HTML5 (Linux/interim-Android) and native
(ExoPlayer) providers as interchangeable primitive-executor adapters.

- PlayerAdapter interface + AdapterHost callback bag (adapters/types.ts): the
  adapter owns only decision-free element PRIMITIVES (seekElement, reloadSource,
  play/pause, setVolume, selectSubtitle); it never branches on strategy.
- Seek/audio-track DECISIONS stay in Rust (player_seek_video / _switch_audio_track
  return a strategy); the facade dispatches the chosen primitive to the active
  adapter. Both providers share the one decision path — logic lives once, in Rust.
- Facade holds the active adapter; a new ControlCommand PlayerStatusEvent lets
  backend control (lockscreen/remote/sleep) drive the webview <video> element.
- Html5PlayerAdapter resolves the LIVE element via the bridge (fixes play/pause
  silently no-opping when the element was re-bound).
- Do not emit a "stopped" player state on natural end-of-video: it flipped the
  player/mode to idle mid-handoff and suppressed next-episode auto-advance under
  a sleep timer. Jellyfin progress reporting is preserved; the backend's
  on_video_playback_ended owns the transition.
- VideoPlayer net -300 lines (strategy/HLS-reload logic relocated to the adapter).
- Adds 20 adapter unit tests; existing suites stay green (vitest 457, cargo 416).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/architecture/05-platform-backends.md     |  44 +++
 src-tauri/src/player/events.rs                |  11 +
 src/lib/api/bindings.ts                       |  10 +-
 src/lib/components/player/VideoPlayer.svelte  | 310 ++++++------------
 src/lib/player/adapters/html5Adapter.test.ts  | 194 +++++++++++
 src/lib/player/adapters/html5Adapter.ts       | 201 ++++++++++++
 src/lib/player/adapters/index.ts              |  55 ++++
 src/lib/player/adapters/nativeAdapter.test.ts |  88 +++++
 src/lib/player/adapters/nativeAdapter.ts      |  96 ++++++
 src/lib/player/adapters/rustReportHost.ts     |  93 ++++++
 src/lib/player/adapters/types.ts              | 127 +++++++
 src/lib/player/html5Adapter.ts                |  91 +----
 src/lib/player/index.ts                       | 125 ++++++-
 src/lib/services/playerEvents.ts              |  42 +++
 src/routes/player/[id]/+page.svelte           |  12 +-
 15 files changed, 1198 insertions(+), 301 deletions(-)
 create mode 100644 src/lib/player/adapters/html5Adapter.test.ts
 create mode 100644 src/lib/player/adapters/html5Adapter.ts
 create mode 100644 src/lib/player/adapters/index.ts
 create mode 100644 src/lib/player/adapters/nativeAdapter.test.ts
 create mode 100644 src/lib/player/adapters/nativeAdapter.ts
 create mode 100644 src/lib/player/adapters/rustReportHost.ts
 create mode 100644 src/lib/player/adapters/types.ts

diff --git a/docs/architecture/05-platform-backends.md b/docs/architecture/05-platform-backends.md
index 7211dae..6429b1d 100644
--- a/docs/architecture/05-platform-backends.md
+++ b/docs/architecture/05-platform-backends.md
@@ -90,6 +90,50 @@ flowchart LR
 
 **Important**: The command is `player_get_queue` (returns `QueueStatus` with `hasNext`/`hasPrevious`). There is no `player_get_queue_status` command.
 
+## HTML5 Video Adapter (webview-rendered video)
+
+**Location**: `src/lib/player/html5Adapter.ts`, `src/lib/player/index.ts`, report commands in
+`src-tauri/src/commands/player/timers.rs`
+
+Video on desktop (Linux WebKitGTK) — and, per current interim behavior, Android — is rendered by an
+HTML5 `<video>`/HLS element **inside the webview**. libmpv is initialized audio-only (`vo=null`,
+`video=false`), so the native backend cannot render or observe this element. The `<video>` is therefore
+the real player, living outside Rust's reach.
+
+To keep the `PlayerController` the single source of truth (matching the audio path), the HTML5 element
+is treated as **a dumb output device that reports back into Rust**, rather than an independent state
+authority:
+
+```mermaid
+flowchart LR
+    subgraph Webview["Webview"]
+        Video["HTML5 <video> / HLS.js"]
+        Adapter["html5Adapter.ts<br/>(reports DOM events)"]
+    end
+    subgraph Backend["Rust"]
+        Cmds["player_report_state<br/>player_report_position<br/>player_report_media_loaded"]
+        Controller["PlayerController"]
+        Emitter["TauriEventEmitter"]
+    end
+    subgraph Frontend["Frontend"]
+        Events["playerEvents.ts"]
+        Store["player store"]
+    end
+
+    Video -->|DOM events| Adapter --> Cmds --> Controller --> Emitter --> Events --> Store
+```
+
+**Key points:**
+- The adapter re-emits the *same* `PlayerStatusEvent`s (`StateChanged`, `PositionUpdate`, `MediaLoaded`)
+  the native backends emit, so `playerEvents.ts` needs **no** HTML5-specific branch — HTML5 is just
+  another event source feeding the existing pipeline.
+- Position reports are throttled (~250ms) to match the MPV cadence and avoid flooding IPC from the
+  60fps RAF loop.
+- **Boundary rule**: UI components never touch the report commands or `videoElement` state directly.
+  Playback *control* goes through the unified facade `src/lib/player/index.ts` (`playerController`);
+  HTML5 *state reporting* goes through `html5Adapter.ts`. This restores the documented invariant
+  ("frontend only displays state and invokes commands") for the video path.
+
 ## MpvBackend (Linux)
 
 **Location**: `src-tauri/src/player/mpv/`
diff --git a/src-tauri/src/player/events.rs b/src-tauri/src/player/events.rs
index 4ad95bc..55b1817 100644
--- a/src-tauri/src/player/events.rs
+++ b/src-tauri/src/player/events.rs
@@ -130,6 +130,17 @@ pub enum PlayerStatusEvent {
     /// frontend owns the two-step remote->local transfer (it must reload the
     /// media item locally), so the native side only signals intent here.
     RemoteDisconnectRequested,
+    /// Backend-originated control command targeting the active frontend player
+    /// adapter (the HTML5 <video> that lives in the webview, which Rust cannot
+    /// drive directly). Emitted by control paths like the sleep timer, lockscreen,
+    /// or remote so they can pause/play/seek/stop the webview element.
+    /// `playerEvents.ts` routes this to the active PlayerAdapter via the facade.
+    ControlCommand {
+        /// One of: "play", "pause", "stop", "seek".
+        action: String,
+        /// Target position in seconds (only meaningful for "seek").
+        position: Option<f64>,
+    },
 }
 
 /// Trait for emitting player events to the frontend.
diff --git a/src/lib/api/bindings.ts b/src/lib/api/bindings.ts
index 40970c0..145fe33 100644
--- a/src/lib/api/bindings.ts
+++ b/src/lib/api/bindings.ts
@@ -1996,7 +1996,15 @@ export type PlayerStatusEvent =
  * 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" }
+{ type: "remote_disconnect_requested" } | 
+/**
+ * Backend-originated control command targeting the active frontend player
+ * adapter (the HTML5 <video> that lives in the webview, which Rust cannot
+ * drive directly). Emitted by control paths like the sleep timer, lockscreen,
+ * or remote so they can pause/play/seek/stop the webview element.
+ * `playerEvents.ts` routes this to the active PlayerAdapter via the facade.
+ */
+{ type: "control_command"; action: string; position: number | null }
 /**
  * Result of creating a playlist
  * 
diff --git a/src/lib/components/player/VideoPlayer.svelte b/src/lib/components/player/VideoPlayer.svelte
index 5183f8d..c1bfb71 100644
--- a/src/lib/components/player/VideoPlayer.svelte
+++ b/src/lib/components/player/VideoPlayer.svelte
@@ -15,6 +15,9 @@
   import { sleepTimerActive, sleepTimerExpiredSignal } from "$lib/stores/sleepTimer";
   import { playbackPosition } 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 { createRustReportHost } from "$lib/player/adapters/rustReportHost";
 
   interface Props {
     media: MediaItem | null;
@@ -67,7 +70,10 @@
   let controlsTimeout: ReturnType<typeof setTimeout> | null = null;
   let seekOffset = $state(0); // Track offset when seeking in transcoded streams
   let isSeeking = $state(false);
-  let currentStreamUrl = $state(streamUrl);
+  // Capture only the initial streamUrl prop; later prop changes are applied via
+  // the $effect below (untrack keeps this a one-time snapshot, matching
+  // reportMediaId above and silencing state_referenced_locally).
+  let currentStreamUrl = $state(untrack(() => streamUrl));
   let hasReportedStart = $state(false);
   let progressInterval: ReturnType<typeof setInterval> | null = null;
   let isMediaReady = $state(false); // Track if media is ready to play (implements Loading state from DR-001)
@@ -106,6 +112,31 @@
   let hls: Hls | null = null; // HLS.js instance for streaming HLS content
   let hlsFatalRecoveryAttempts = 0; // Track recovery attempts to prevent infinite restarts
 
+  // ===== Player adapter (control boundary) =====
+  // The adapter owns the high-level control contract (play/pause/seek/track).
+  // 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;
+
+  function tearDownHls() {
+    if (hls) {
+      hls.detachMedia();
+      hls.stopLoad();
+      hls.destroy();
+      hls = null;
+    }
+  }
+
+  const adapterBridge: Html5ElementBridge = {
+    getElement: () => videoElement,
+    getSeekOffset: () => seekOffset,
+    setSeekOffset: (o) => { seekOffset = o; },
+    setStreamUrl: (u) => { currentStreamUrl = u; },
+    destroyHls: tearDownHls,
+    getMediaSourceId: () => mediaSourceId ?? null,
+  };
+
   // Audio track selection
   let showAudioTrackMenu = $state(false);
   let selectedAudioTrackIndex = $state<number | null>(null);
@@ -222,20 +253,11 @@
   });
 
 
-  // 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();
-      }
-    }
-  });
+  // Sleep-timer expiry pause is now driven by the backend through the player
+  // adapter: playerEvents.ts routes `sleep_timer_expired` to the active adapter's
+  // pause() (see handleControlCommand / the sleep_timer_expired case). This
+  // removes the component's direct videoElement.pause() reach-in — the backend
+  // has control authority over the webview element via the adapter boundary.
 
   // Native backend (Android ExoPlayer): drive the seek bar from the player
   // store, which is fed by the backend's PositionUpdate events. The legacy
@@ -545,6 +567,18 @@
           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) {
+          const host = createRustReportHost(media.id, {
+            onEnded: () => notifyEnded(),
+            onStreamUrlChanged: (u) => { currentStreamUrl = u; },
+          });
+          playerAdapter = new Html5PlayerAdapter(host, adapterBridge);
+          playerAdapter.attach(videoElement);
+          playerController.setActiveAdapter(playerAdapter);
+        }
+
         if (!useHtml5Element) {
           // Using native backend, subscribe to player events
           didStartNativePlayback = true; // Track that we started native playback
@@ -633,6 +667,12 @@
     // Stop RAF loop
     stopTimeUpdates();
 
+    // Unregister the adapter from the facade (guarded so we only clear our own).
+    if (playerAdapter) {
+      playerController.clearActiveAdapter(playerAdapter);
+      playerAdapter = null;
+    }
+
     if (progressInterval) {
       clearInterval(progressInterval);
     }
@@ -969,8 +1009,13 @@
   function handleEnded() {
     isPlaying = false;
     stopTimeUpdates(); // Stop RAF loop when ended
-    html5Adapter.reportState("stopped", reportMediaId ?? null);
-    // Report stop when video ends (skip for live - no resume tracking)
+    // NOTE: do NOT report a "stopped" player state here. Natural end-of-video is
+    // an autoplay handoff, not a stop: the backend's on_video_playback_ended
+    // decides whether to advance to the next episode (incl. sleep-timer episode
+    // counting). Emitting StateChanged{stopped} would flip the player/mode to
+    // idle mid-handoff and suppress the next-episode auto-advance (pauses at the
+    // end of an episode instead of continuing). onReportStop below still reports
+    // progress to Jellyfin; notifyEnded() drives the autoplay decision.
     if (!isLive && onReportStop) {
       onReportStop(currentTime, reportMediaId);
     }
@@ -979,19 +1024,13 @@
   }
 
   async function togglePlayPause() {
-    if (!useHtml5Element) {
-      try {
-        const response = (await commands.playerToggle()) as any;
-        isPlaying = response.state === "playing";
-      } catch (err) {
-        console.error("[VideoPlayer] Failed to toggle native player:", err);
-      }
-    } else if (videoElement) {
-      if (videoElement.paused) {
-        videoElement.play();
-      } else {
-        videoElement.pause();
-      }
+    // Route through the facade → active adapter so the toggle goes through the
+    // one control boundary (and the adapter reports the resulting element state
+    // back into Rust). The element's own play/pause handlers update isPlaying.
+    try {
+      await playerController.toggle();
+    } catch (err) {
+      console.error("[VideoPlayer] Failed to toggle playback:", err);
     }
   }
 
@@ -1011,133 +1050,29 @@
     isDraggingSeekBar = false;
 
     try {
-      console.log("[VideoPlayer] Seeking to:", targetTime.toFixed(2), "useHtml5Element:", useHtml5Element);
+      console.log("[VideoPlayer] Seeking to:", targetTime.toFixed(2));
 
-      const repo = auth.getRepository();
-      if (!repo) {
-        console.error("[VideoPlayer] No repository available");
-        return;
-      }
+      // Optimistic display; the primitive updates currentTime/seekOffset as it
+      // completes (reloadSource drives the stream URL via the adapter bridge).
+      currentTime = targetTime;
+      stopTimeUpdates(); // pause RAF while the seek settles
 
-      // Backend smart seeking handles both native and HTML5
-      const response = (await commands.playerSeekVideo(
-        repo.getHandle(),
+      // The BACKEND decides the strategy (in-place vs transcode reload); the
+      // facade dispatches the matching adapter PRIMITIVE. This is the shared
+      // decision-in-Rust design — no strategy branch lives here anymore.
+      lastNativeSeekAt = Date.now();
+      await playerController.seekVideo(
         targetTime,
         mediaSourceId ?? null,
-        selectedAudioTrackIndex ?? null,
-        useHtml5Element
-      )) as any;
+        selectedAudioTrackIndex ?? null
+      );
 
-      console.log("[VideoPlayer] Backend seek response:", response);
-
-      // 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") {
-          // 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;
-        }
-        console.log("[VideoPlayer] Native backend seek completed at position:", currentTime);
-        return;
+      // Resume smooth updates if still playing after the seek settled.
+      if (videoElement && !videoElement.paused) {
+        startTimeUpdates();
       }
 
-      // HTML5 backend - handle video element management
-      if (!videoElement) {
-        console.warn("[VideoPlayer] Cannot seek - video element not available");
-        return;
-      }
-
-      if (response.strategy === "reloadStream") {
-        // Transcoded stream - reload with new URL
-        console.log("[VideoPlayer] Reloading HTML5 stream from position:", targetTime);
-        const wasPlaying = !videoElement.paused;
-
-        // CRITICAL: Stop playback completely to prevent dual audio
-        videoElement.pause();
-        stopTimeUpdates(); // Stop RAF updates
-
-        // CRITICAL: Destroy old HLS instance completely to prevent dual audio
-        if (hls) {
-          console.log("[VideoPlayer] Destroying old HLS instance for seek");
-          hls.detachMedia(); // Detach from video element
-          hls.stopLoad(); // Stop loading fragments
-          hls.destroy(); // Completely destroy the instance
-          hls = null; // Clear reference
-        }
-
-        // CRITICAL: Clear video element buffers completely
-        if (videoElement.src) {
-          videoElement.removeAttribute('src');
-          videoElement.load(); // Reset and flush all buffers
-        }
-
-        // Small delay to ensure cleanup completes before creating new HLS instance
-        await new Promise(resolve => setTimeout(resolve, 100));
-
-        // Update stream URL (this will trigger $effect to create new HLS instance)
-        // 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
-        await new Promise<void>((resolve) => {
-          const onCanPlay = () => {
-            console.log("[VideoPlayer] Transcoded video loaded after seek");
-            videoElement?.removeEventListener("canplay", onCanPlay);
-            resolve();
-          };
-          if (videoElement) {
-            videoElement.addEventListener("canplay", onCanPlay);
-          }
-
-          setTimeout(() => {
-            console.warn("[VideoPlayer] Transcoded seek timeout");
-            videoElement?.removeEventListener("canplay", onCanPlay);
-            resolve();
-          }, 10000);
-        });
-
-        if (wasPlaying && videoElement) {
-          await videoElement.play();
-          startTimeUpdates(); // Restart RAF updates
-        }
-      } else {
-        // Native browser seeking
-        console.log("[VideoPlayer] Using native HTML5 seek to:", targetTime.toFixed(2));
-        videoElement.currentTime = targetTime;
-        currentTime = targetTime;
-        seekOffset = 0;
-
-        // Wait for seek to complete
-        await new Promise<void>((resolve) => {
-          const onSeeked = () => {
-            console.log("[VideoPlayer] Native seek completed");
-            videoElement?.removeEventListener("seeked", onSeeked);
-            resolve();
-          };
-          if (videoElement) {
-            videoElement.addEventListener("seeked", onSeeked);
-          }
-
-          setTimeout(() => {
-            videoElement?.removeEventListener("seeked", onSeeked);
-            resolve();
-          }, 2000);
-        });
-      }
-
-      console.log("[VideoPlayer] HTML5 seek completed:", {
-        strategy: response.strategy,
-        targetTime: targetTime.toFixed(2),
-        actualTime: videoElement.currentTime.toFixed(2),
-        seekOffset,
-      });
+      console.log("[VideoPlayer] Seek completed at:", currentTime.toFixed(2), "offset:", seekOffset);
     } catch (err) {
       console.error("[VideoPlayer] Seek failed:", err);
     } finally {
@@ -1307,74 +1242,19 @@
     showAudioTrackMenu = false;
 
     try {
-      const repo = auth.getRepository();
-      if (!repo) throw new Error("Not authenticated");
-
-      // Call unified backend command
-      const response = (await commands.playerSwitchAudioTrack(
-        repo.getHandle(),
+      // The BACKEND decides whether the audio-track switch needs a transcode
+      // reload; the facade dispatches the resulting adapter PRIMITIVE
+      // (reloadSource) which runs the invariant dual-audio teardown sequence.
+      // No strategy branch lives here anymore.
+      stopTimeUpdates();
+      await playerController.switchAudioTrack(
         streamIndex,
         arrayIndex,
-        useHtml5Element,
-        useHtml5Element && videoElement ? videoElement.currentTime + seekOffset : null,
+        videoElement ? videoElement.currentTime + seekOffset : null,
         mediaSourceId ?? null
-      )) as any;
-
-      // Handle response based on strategy
-      if (response.strategy === "reloadStream" && useHtml5Element && videoElement) {
-        console.log("[VideoPlayer] Switching audio track - reloading stream");
-
-        // Save state before reload
-        const wasPlaying = !videoElement.paused;
-
-        // CRITICAL: Stop playback completely to prevent dual audio
-        videoElement.pause();
-        stopTimeUpdates(); // Stop RAF updates
-
-        // CRITICAL: Destroy old HLS instance completely to prevent dual audio
-        if (hls) {
-          console.log("[VideoPlayer] Destroying old HLS instance for audio track switch");
-          hls.detachMedia(); // Detach from video element
-          hls.stopLoad(); // Stop loading fragments
-          hls.destroy(); // Completely destroy the instance
-          hls = null; // Clear reference
-        }
-
-        // CRITICAL: Clear video element buffers completely
-        if (videoElement.src) {
-          videoElement.removeAttribute('src');
-          videoElement.load(); // Reset and flush all buffers
-        }
-
-        // Small delay to ensure cleanup completes before creating new HLS instance
-        await new Promise(resolve => setTimeout(resolve, 100));
-
-        // Update stream URL (this will trigger $effect to create new HLS instance)
-        // 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
-        await new Promise<void>((resolve) => {
-          const onCanPlay = () => {
-            console.log("[VideoPlayer] Video reloaded with new audio track");
-            videoElement?.removeEventListener("canplay", onCanPlay);
-            resolve();
-          };
-          videoElement!.addEventListener("canplay", onCanPlay);
-
-          // Timeout fallback
-          setTimeout(() => {
-            videoElement?.removeEventListener("canplay", onCanPlay);
-            resolve();
-          }, 5000);
-        });
-
-        // Resume playback if it was playing
-        if (wasPlaying) {
-          await videoElement.play();
-          startTimeUpdates(); // Restart RAF updates
-        }
+      );
+      if (videoElement && !videoElement.paused) {
+        startTimeUpdates();
       }
 
       console.log("[VideoPlayer] Successfully changed audio track");
diff --git a/src/lib/player/adapters/html5Adapter.test.ts b/src/lib/player/adapters/html5Adapter.test.ts
new file mode 100644
index 0000000..8ce933a
--- /dev/null
+++ b/src/lib/player/adapters/html5Adapter.test.ts
@@ -0,0 +1,194 @@
+/**
+ * Unit tests for Html5PlayerAdapter.
+ *
+ * The Option-1 primitive design makes the adapter pure, decision-free mechanics
+ * — it takes a mock <video> element + bridge + host, so we can assert each
+ * primitive drives the element correctly without any real DOM or backend.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Html5PlayerAdapter, type Html5ElementBridge } from "./html5Adapter";
+import type { AdapterHost } from "./types";
+
+/** A minimal fake <video> element that records mutations and fires events. */
+function makeFakeVideo() {
+  const listeners: Record<string, Array<() => void>> = {};
+  const el: any = {
+    paused: true,
+    currentTime: 0,
+    volume: 1,
+    muted: false,
+    src: "blob:existing",
+    play: vi.fn(async () => {
+      el.paused = false;
+    }),
+    pause: vi.fn(() => {
+      el.paused = true;
+    }),
+    load: vi.fn(),
+    removeAttribute: vi.fn((attr: string) => {
+      if (attr === "src") el.src = "";
+    }),
+    addEventListener: (event: string, cb: () => void) => {
+      (listeners[event] ??= []).push(cb);
+    },
+    removeEventListener: (event: string, cb: () => void) => {
+      listeners[event] = (listeners[event] ?? []).filter((f) => f !== cb);
+    },
+    // Test helper: fire an event so waitForEvent resolves immediately.
+    _fire: (event: string) => {
+      (listeners[event] ?? []).slice().forEach((f) => f());
+    },
+    querySelectorAll: () => [] as any,
+    textTracks: [] as any,
+  };
+  return el;
+}
+type FakeVideo = ReturnType<typeof makeFakeVideo>;
+
+function makeBridge(overrides: Partial<Html5ElementBridge> = {}): Html5ElementBridge {
+  let offset = 0;
+  return {
+    getElement: () => null,
+    getSeekOffset: () => offset,
+    setSeekOffset: vi.fn((o: number) => { offset = o; }),
+    setStreamUrl: vi.fn(),
+    destroyHls: vi.fn(),
+    getMediaSourceId: () => "msid-1",
+    ...overrides,
+  };
+}
+
+function makeHost(): AdapterHost {
+  return {
+    onState: vi.fn(),
+    onPosition: vi.fn(),
+    onMediaLoaded: vi.fn(),
+    onEnded: vi.fn(),
+    onError: vi.fn(),
+    onStreamUrlChanged: vi.fn(),
+    onBuffering: vi.fn(),
+    onReady: vi.fn(),
+  };
+}
+
+describe("Html5PlayerAdapter", () => {
+  let host: AdapterHost;
+  let bridge: Html5ElementBridge;
+  let adapter: Html5PlayerAdapter;
+  let video: ReturnType<typeof makeFakeVideo>;
+
+  beforeEach(() => {
+    host = makeHost();
+    bridge = makeBridge();
+    adapter = new Html5PlayerAdapter(host, bridge);
+    video = makeFakeVideo();
+    adapter.attach(video);
+  });
+
+  it("is an html5-kind adapter", () => {
+    expect(adapter.kind).toBe("html5");
+  });
+
+  it("play() calls element.play()", async () => {
+    await adapter.play();
+    expect(video.play).toHaveBeenCalledTimes(1);
+  });
+
+  it("pause() calls element.pause()", async () => {
+    video.paused = false;
+    await adapter.pause();
+    expect(video.pause).toHaveBeenCalledTimes(1);
+  });
+
+  it("toggle() plays when paused and reports the resulting state", async () => {
+    video.paused = true;
+    const playing = await adapter.toggle();
+    expect(video.play).toHaveBeenCalled();
+    expect(playing).toBe(true);
+  });
+
+  it("toggle() pauses when playing", async () => {
+    video.paused = false;
+    const playing = await adapter.toggle();
+    expect(video.pause).toHaveBeenCalled();
+    expect(playing).toBe(false);
+  });
+
+  it("seekElement() sets currentTime, offset, and waits for 'seeked'", async () => {
+    const p = adapter.seekElement(42, 0);
+    expect(video.currentTime).toBe(42);
+    expect(bridge.setSeekOffset).toHaveBeenCalledWith(0);
+    video._fire("seeked"); // resolve the wait
+    await p;
+  });
+
+  it("reloadSource() runs the invariant teardown->swap->resume sequence", async () => {
+    video.paused = false; // was playing → should resume
+    const p = adapter.reloadSource("http://new/master.m3u8", 120);
+
+    // Teardown happened synchronously before the awaited canplay wait.
+    expect(video.pause).toHaveBeenCalled();
+    expect(bridge.destroyHls).toHaveBeenCalledTimes(1);
+    expect(video.removeAttribute).toHaveBeenCalledWith("src");
+    expect(video.load).toHaveBeenCalled();
+
+    // Allow the internal 100ms settle delay, then fire canplay to resume.
+    await new Promise((r) => setTimeout(r, 110));
+    expect(bridge.setSeekOffset).toHaveBeenCalledWith(120);
+    expect(bridge.setStreamUrl).toHaveBeenCalledWith("http://new/master.m3u8");
+    video._fire("canplay");
+    await p;
+    expect(video.play).toHaveBeenCalled(); // resumed because it was playing
+  });
+
+  it("reloadSource() does not resume when it was paused", async () => {
+    video.paused = true;
+    const p = adapter.reloadSource("http://new/master.m3u8", 30);
+    await new Promise((r) => setTimeout(r, 110));
+    video._fire("canplay");
+    await p;
+    expect(video.play).not.toHaveBeenCalled();
+  });
+
+  it("setVolume() clamps to 0..1", () => {
+    adapter.setVolume(1.5);
+    expect(video.volume).toBe(1);
+    adapter.setVolume(-0.5);
+    expect(video.volume).toBe(0);
+    adapter.setVolume(0.4);
+    expect(video.volume).toBeCloseTo(0.4);
+  });
+
+  it("setMuted() sets the element muted flag", () => {
+    adapter.setMuted(true);
+    expect(video.muted).toBe(true);
+  });
+
+  it("getPosition() returns element time plus the transcode offset", () => {
+    video.currentTime = 10;
+    (bridge.getSeekOffset as any) = () => 100;
+    // Rebuild adapter with the offset-returning bridge.
+    const a = new Html5PlayerAdapter(host, bridge);
+    a.attach(video);
+    expect(a.getPosition()).toBe(110);
+  });
+
+  it("dispose() tears down hls and clears the element", async () => {
+    await adapter.dispose();
+    expect(bridge.destroyHls).toHaveBeenCalled();
+    expect(video.pause).toHaveBeenCalled();
+    // After dispose, primitives are no-ops (element detached).
+    await adapter.play();
+    // play was called once during dispose teardown? no — play only on reload/resume.
+    expect(video.play).not.toHaveBeenCalled();
+  });
+
+  it("primitives are safe no-ops before an element is attached", async () => {
+    const bare = new Html5PlayerAdapter(host, bridge);
+    await expect(bare.play()).resolves.toBeUndefined();
+    await expect(bare.pause()).resolves.toBeUndefined();
+    await expect(bare.seekElement(5, 0)).resolves.toBeUndefined();
+    expect(await bare.toggle()).toBe(false);
+  });
+});
diff --git a/src/lib/player/adapters/html5Adapter.ts b/src/lib/player/adapters/html5Adapter.ts
new file mode 100644
index 0000000..590cf93
--- /dev/null
+++ b/src/lib/player/adapters/html5Adapter.ts
@@ -0,0 +1,201 @@
+/**
+ * Html5PlayerAdapter — the Linux/desktop (and interim Android) PlayerAdapter
+ * implementation. It owns the high-level control surface for an HTML5 `<video>`
+ * element and reports the element's lifecycle back into Rust via its
+ * {@link AdapterHost}.
+ *
+ * Design note on the split with VideoPlayer.svelte:
+ * The delicate, timing-sensitive parts (hls.js instance lifecycle, the transcode
+ * "reload stream" seek/audio-track dance with its dual-audio teardown and
+ * canplay waits) are inherently coupled to Svelte reactive state and the DOM
+ * element. Rather than relocate that reactive machinery wholesale (high
+ * regression risk), the adapter receives an {@link Html5ElementBridge} of narrow
+ * callbacks the owning component supplies. The adapter is the single OWNER of the
+ * control contract (play/pause/seek/track/volume) and of reporting; the bridge is
+ * the seam to the component's element/HLS/reactive state. This keeps all control
+ * intents flowing through the PlayerAdapter interface while preserving the
+ * hard-won element behavior verbatim.
+ *
+ * TRACES: UR-003, UR-005, UR-020, UR-021 | DR-001, DR-023, DR-024, DR-028
+ */
+
+import type { AdapterHost, PlayerAdapter, PlayerLoadOptions } from "./types";
+
+/**
+ * Narrow seam the owning component provides so the adapter can execute the
+ * element/HLS-coupled parts of a control action without re-implementing the
+ * component's reactive HLS lifecycle. Every function here is a thin wrapper over
+ * work the component already does.
+ */
+export interface Html5ElementBridge {
+  /** The bound <video> element, or null before mount / after teardown. */
+  getElement(): HTMLVideoElement | null;
+  /** Current seek offset (seconds) for transcoded streams. */
+  getSeekOffset(): number;
+  setSeekOffset(offset: number): void;
+  /** Update the stream URL the component renders (triggers its HLS $effect). */
+  setStreamUrl(url: string): void;
+  /** Tear down the component-owned hls.js instance (dual-audio prevention). */
+  destroyHls(): void;
+  /** Media source id for seek/audio-track URLs. */
+  getMediaSourceId(): string | null;
+}
+
+export class Html5PlayerAdapter implements PlayerAdapter {
+  readonly kind = "html5" as const;
+
+  private attachedElement: HTMLVideoElement | null = null;
+  private host: AdapterHost;
+  private bridge: Html5ElementBridge;
+
+  constructor(host: AdapterHost, bridge: Html5ElementBridge) {
+    this.host = host;
+    this.bridge = bridge;
+  }
+
+  /**
+   * Resolve the LIVE <video> element. The bridge's `getElement()` returns the
+   * component's current reactive `videoElement`, which is authoritative: the
+   * element can be re-bound when the {#if} block re-renders, so a value captured
+   * once in `attach()` may go stale (this caused play/pause to silently no-op).
+   * Falls back to the attach()-captured element for unit tests whose bridge
+   * returns null.
+   */
+  private get element(): HTMLVideoElement | null {
+    return this.bridge.getElement() ?? this.attachedElement;
+  }
+
+  attach(element: HTMLVideoElement | null): void {
+    this.attachedElement = element;
+  }
+
+  async load(streamUrl: string, _options: PlayerLoadOptions): Promise<void> {
+    // The component's reactive HLS $effect performs the actual attach/load when
+    // the stream URL is set; loading is therefore driven by setStreamUrl. The
+    // component's canplay/frag-buffered path reports readiness through the host.
+    this.bridge.setSeekOffset(0);
+    this.bridge.setStreamUrl(streamUrl);
+    this.host.onState("loading");
+  }
+
+  async play(): Promise<void> {
+    const el = this.element;
+    if (!el) return;
+    try {
+      await el.play();
+      // handlePlay on the element reports "playing"; no double-report here.
+    } catch (err) {
+      this.host.onError(`play() failed: ${err}`);
+    }
+  }
+
+  async pause(): Promise<void> {
+    this.element?.pause();
+  }
+
+  async toggle(): Promise<boolean> {
+    const el = this.element;
+    if (!el) return false;
+    if (el.paused) {
+      await this.play();
+      return true;
+    }
+    await this.pause();
+    return false;
+  }
+
+  /**
+   * PRIMITIVE: in-place element seek (no reload). The backend already decided
+   * this seek does not need a transcode reload.
+   */
+  async seekElement(positionSeconds: number, offset: number): Promise<void> {
+    const el = this.element;
+    if (!el) return;
+    el.currentTime = positionSeconds;
+    this.bridge.setSeekOffset(offset);
+    await this.waitForEvent(el, "seeked", 2000);
+  }
+
+  /**
+   * PRIMITIVE: compound reload — the invariant HTML5 sequence to swap the source
+   * and resume at `offset`. Contains NO strategy decision; the backend already
+   * decided to reload and supplied the url/offset. Preserves the hard-won
+   * dual-audio teardown and canplay wait.
+   */
+  async reloadSource(url: string, offset: number): Promise<void> {
+    const el = this.element;
+    if (!el) {
+      // Still update the stream URL so the component's HLS $effect can pick it up.
+      this.bridge.setSeekOffset(offset);
+      this.bridge.setStreamUrl(url);
+      return;
+    }
+    const wasPlaying = !el.paused;
+    el.pause();
+    this.bridge.destroyHls();
+    if (el.src) {
+      el.removeAttribute("src");
+      el.load();
+    }
+    await new Promise((r) => setTimeout(r, 100));
+    this.bridge.setSeekOffset(offset);
+    this.bridge.setStreamUrl(url);
+    await this.waitForEvent(el, "canplay", 10000);
+    if (wasPlaying) await el.play();
+  }
+
+  setVolume(volume: number): void {
+    if (this.element) this.element.volume = Math.max(0, Math.min(1, volume));
+  }
+
+  setMuted(muted: boolean): void {
+    if (this.element) this.element.muted = muted;
+  }
+
+  /** Subtitle selection: HTML5 toggles textTracks on the element directly. */
+  async selectSubtitle(streamIndex: number | null, _arrayIndex?: number): Promise<void> {
+    const el = this.element;
+    if (!el || !el.textTracks) return;
+    for (let i = 0; i < el.textTracks.length; i++) {
+      el.textTracks[i].mode = "disabled";
+    }
+    if (streamIndex !== null) {
+      const tracks = el.querySelectorAll("track");
+      tracks.forEach((track) => {
+        const idx = parseInt(track.getAttribute("data-stream-index") || "-1");
+        if (idx === streamIndex && track.track) {
+          track.track.mode = "showing";
+        }
+      });
+    }
+  }
+
+  getPosition(): number {
+    const el = this.element;
+    if (!el) return 0;
+    return el.currentTime + this.bridge.getSeekOffset();
+  }
+
+  async dispose(): Promise<void> {
+    this.bridge.destroyHls();
+    const el = this.element;
+    if (el) {
+      el.pause();
+      el.removeAttribute("src");
+      el.load();
+    }
+    this.attachedElement = null;
+  }
+
+  /** Resolve when `event` fires on `el`, or after `timeoutMs` as a fallback. */
+  private waitForEvent(el: HTMLVideoElement, event: string, timeoutMs: number): Promise<void> {
+    return new Promise<void>((resolve) => {
+      const done = () => {
+        el.removeEventListener(event, done);
+        resolve();
+      };
+      el.addEventListener(event, done);
+      setTimeout(done, timeoutMs);
+    });
+  }
+}
diff --git a/src/lib/player/adapters/index.ts b/src/lib/player/adapters/index.ts
new file mode 100644
index 0000000..bf4c35f
--- /dev/null
+++ b/src/lib/player/adapters/index.ts
@@ -0,0 +1,55 @@
+/**
+ * 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`.
+ *
+ * TRACES: UR-003 | DR-004
+ */
+
+import { Html5PlayerAdapter, type Html5ElementBridge } from "./html5Adapter";
+import { NativePlayerAdapter } from "./nativeAdapter";
+import type { AdapterHost, PlayerAdapter } from "./types";
+
+export type { PlayerAdapter, AdapterHost, PlayerLoadOptions, SubtitleTrackInput } from "./types";
+export type { Html5ElementBridge } from "./html5Adapter";
+export { Html5PlayerAdapter } from "./html5Adapter";
+export { NativePlayerAdapter } from "./nativeAdapter";
+
+/** What the Rust `player_play_item` response says it chose. */
+export type BackendKind = "html5" | "native";
+
+export interface CreateAdapterArgs {
+  /** Backend kind reported by `player_play_item` (`useHtml5Element`). */
+  backendKind: BackendKind;
+  host: AdapterHost;
+  /** Required for the HTML5 adapter; ignored by the native adapter. */
+  bridge?: Html5ElementBridge;
+}
+
+/**
+ * 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.
+ */
+export function createAdapter({ backendKind, host, bridge }: CreateAdapterArgs): PlayerAdapter {
+  // INTERIM OVERRIDE: force HTML5 rendering even when the backend reports native.
+  const effectiveKind: BackendKind = "html5";
+
+  if (effectiveKind === "html5") {
+    if (!bridge) {
+      throw new Error("createAdapter: Html5ElementBridge is required for the HTML5 adapter");
+    }
+    return new Html5PlayerAdapter(host, bridge);
+  }
+
+  // Reached only once the interim override is lifted (native Android unblocked).
+  void backendKind;
+  return new NativePlayerAdapter(host);
+}
diff --git a/src/lib/player/adapters/nativeAdapter.test.ts b/src/lib/player/adapters/nativeAdapter.test.ts
new file mode 100644
index 0000000..e4c1661
--- /dev/null
+++ b/src/lib/player/adapters/nativeAdapter.test.ts
@@ -0,0 +1,88 @@
+/**
+ * Unit tests for NativePlayerAdapter — thin delegate to backend commands.
+ * Pins the primitive→command mapping so the ExoPlayer path stays correct.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const playerPlay = vi.fn((..._a: any[]): any => ({}));
+const playerPause = vi.fn((..._a: any[]): any => ({}));
+const playerToggle = vi.fn((..._a: any[]): any => ({ state: "playing" }));
+const playerSetVolume = vi.fn((..._a: any[]): any => ({}));
+const playerToggleMute = vi.fn((..._a: any[]): any => ({}));
+const playerSetSubtitleTrack = vi.fn((..._a: any[]): any => ({}));
+
+vi.mock("$lib/api/bindings", () => ({
+  commands: {
+    playerPlay: (...a: any[]) => playerPlay(...a),
+    playerPause: (...a: any[]) => playerPause(...a),
+    playerToggle: (...a: any[]) => playerToggle(...a),
+    playerSetVolume: (...a: any[]) => playerSetVolume(...a),
+    playerToggleMute: (...a: any[]) => playerToggleMute(...a),
+    playerSetSubtitleTrack: (...a: any[]) => playerSetSubtitleTrack(...a),
+  },
+}));
+
+import { NativePlayerAdapter } from "./nativeAdapter";
+import type { AdapterHost } from "./types";
+
+function makeHost(): AdapterHost {
+  return {
+    onState: vi.fn(), onPosition: vi.fn(), onMediaLoaded: vi.fn(), onEnded: vi.fn(),
+    onError: vi.fn(), onStreamUrlChanged: vi.fn(), onBuffering: vi.fn(), onReady: vi.fn(),
+  };
+}
+
+describe("NativePlayerAdapter", () => {
+  let adapter: NativePlayerAdapter;
+  beforeEach(() => {
+    vi.clearAllMocks();
+    adapter = new NativePlayerAdapter(makeHost());
+  });
+
+  it("is a native-kind adapter", () => {
+    expect(adapter.kind).toBe("native");
+  });
+
+  it("delegates play/pause to backend commands", async () => {
+    await adapter.play();
+    await adapter.pause();
+    expect(playerPlay).toHaveBeenCalledTimes(1);
+    expect(playerPause).toHaveBeenCalledTimes(1);
+  });
+
+  it("toggle() reflects the backend's resulting playing state", async () => {
+    expect(await adapter.toggle()).toBe(true);
+    expect(playerToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it("records position on seek/reload primitives (backend does the real work)", async () => {
+    await adapter.seekElement(55, 0);
+    expect(adapter.getPosition()).toBe(55);
+    await adapter.reloadSource("ignored", 200);
+    expect(adapter.getPosition()).toBe(200);
+  });
+
+  it("load() seeds a resume position", async () => {
+    await adapter.load("url", {
+      mediaId: "m", mediaSourceId: null, needsTranscoding: false,
+      initialPosition: 90, isLive: false, audioTrackIndex: null,
+      knownDuration: 0, subtitleTracks: [],
+    });
+    expect(adapter.getPosition()).toBe(90);
+  });
+
+  it("setVolume clamps and delegates; setMuted toggles mute", () => {
+    adapter.setVolume(2);
+    expect(playerSetVolume).toHaveBeenCalledWith(1);
+    adapter.setMuted(true);
+    expect(playerToggleMute).toHaveBeenCalledTimes(1);
+  });
+
+  it("selectSubtitle maps null to disable and uses arrayIndex when given", async () => {
+    await adapter.selectSubtitle(null);
+    expect(playerSetSubtitleTrack).toHaveBeenCalledWith(null);
+    await adapter.selectSubtitle(5, 2);
+    expect(playerSetSubtitleTrack).toHaveBeenCalledWith(2);
+  });
+});
diff --git a/src/lib/player/adapters/nativeAdapter.ts b/src/lib/player/adapters/nativeAdapter.ts
new file mode 100644
index 0000000..e1102c0
--- /dev/null
+++ b/src/lib/player/adapters/nativeAdapter.ts
@@ -0,0 +1,96 @@
+/**
+ * NativePlayerAdapter — the Android/ExoPlayer PlayerAdapter implementation.
+ *
+ * ExoPlayer is driven entirely by the Rust backend (JNI), which already emits
+ * PlayerStatusEvents and handles seek/audio-track internally. So this adapter is
+ * a thin delegate to backend commands; there is no DOM element to touch and no
+ * hls.js. State reporting is unnecessary here because the native backend emits
+ * events directly — the adapter's job is only to forward control intents.
+ *
+ * NOTE: On current Tauri, native Android video rendering is blocked upstream
+ * (transparent webview / SurfaceView compositing — tauri#10152), so video on
+ * Android currently runs through the HTML5 adapter via the interim override in
+ * the factory. This adapter exists for the audio/native path and for when that
+ * upstream limitation is resolved.
+ *
+ * TRACES: UR-003, UR-005 | DR-004, DR-028
+ */
+
+import { commands } from "$lib/api/bindings";
+import type { AdapterHost, PlayerAdapter, PlayerLoadOptions } from "./types";
+
+export class NativePlayerAdapter implements PlayerAdapter {
+  readonly kind = "native" as const;
+
+  // Kept for symmetry / future reporting needs; the native backend emits events.
+  private host: AdapterHost;
+  private position = 0;
+
+  constructor(host: AdapterHost) {
+    this.host = host;
+  }
+
+  // The native surface is owned by the backend; nothing to attach in the DOM.
+  attach(_element: HTMLVideoElement | null): void {}
+
+  async load(_streamUrl: string, options: PlayerLoadOptions): Promise<void> {
+    // player_play_item already initiated native playback before this adapter is
+    // created; nothing further to do. Seed a resume position if requested (the
+    // native backend performs the actual seek internally).
+    if (options.initialPosition > 0) {
+      this.position = options.initialPosition;
+    }
+  }
+
+  async play(): Promise<void> {
+    await commands.playerPlay();
+  }
+
+  async pause(): Promise<void> {
+    await commands.playerPause();
+  }
+
+  async toggle(): Promise<boolean> {
+    const response = (await commands.playerToggle()) as any;
+    return response?.state === "playing";
+  }
+
+  /**
+   * PRIMITIVE: in-place seek. For the native backend, the backend drives
+   * ExoPlayer's seek internally, so this simply records the target position.
+   * (The decision to seek-in-place vs reload was already made by the backend.)
+   */
+  async seekElement(positionSeconds: number, _offset: number): Promise<void> {
+    this.position = positionSeconds;
+  }
+
+  /**
+   * PRIMITIVE: reload source. For the native backend the backend already
+   * performed the reload+seek internally as part of the seek decision; nothing
+   * to do on the frontend beyond recording position.
+   */
+  async reloadSource(_url: string, offset: number): Promise<void> {
+    this.position = offset;
+  }
+
+  setVolume(volume: number): void {
+    void commands.playerSetVolume(Math.max(0, Math.min(1, volume)));
+  }
+
+  setMuted(_muted: boolean): void {
+    void commands.playerToggleMute();
+  }
+
+  async selectSubtitle(streamIndex: number | null, arrayIndex?: number): Promise<void> {
+    const indexToUse = streamIndex === null ? null : arrayIndex ?? streamIndex;
+    await commands.playerSetSubtitleTrack(indexToUse);
+  }
+
+  getPosition(): number {
+    return this.position;
+  }
+
+  async dispose(): Promise<void> {
+    // The backend is stopped via player_stop by the owning view; nothing to free.
+  }
+}
diff --git a/src/lib/player/adapters/rustReportHost.ts b/src/lib/player/adapters/rustReportHost.ts
new file mode 100644
index 0000000..745b874
--- /dev/null
+++ b/src/lib/player/adapters/rustReportHost.ts
@@ -0,0 +1,93 @@
+/**
+ * An {@link AdapterHost} implementation that forwards a player adapter's outward
+ * lifecycle events into the Rust `PlayerController` via the `player_report_*`
+ * commands. The controller re-emits the same `PlayerStatusEvent`s the native
+ * backends emit, so the frontend `player` store is fed from ONE pipeline
+ * (playerEvents.ts) in both native and HTML5 modes — keeping Rust the single
+ * source of truth.
+ *
+ * This is the sole place that talks to the report commands; adapters depend only
+ * on the {@link AdapterHost} interface, never on `commands` directly, which keeps
+ * them unit-testable with a mock host.
+ *
+ * TRACES: UR-003, UR-005 | DR-001, DR-028
+ */
+
+import { commands } from "$lib/api/bindings";
+import type { AdapterHost } from "./types";
+
+const POSITION_REPORT_INTERVAL_MS = 250;
+
+/** Report options that let a caller bypass throttling for discrete events. */
+export interface ReportPositionOptions {
+  force?: boolean;
+}
+
+/**
+ * Low-level report helpers, exported so the legacy `$lib/player/html5Adapter`
+ * shim can keep its function-style API while there are still direct callers.
+ * Prefer {@link createRustReportHost} for new adapter code.
+ */
+let lastPositionReport = 0;
+
+export async function reportState(
+  state: "playing" | "paused" | "loading" | "stopped" | "idle",
+  mediaId: string | null
+): Promise<void> {
+  try {
+    await commands.playerReportState(state, mediaId);
+  } catch (err) {
+    console.warn("[rustReportHost] Failed to report state:", err);
+  }
+}
+
+export async function reportPosition(
+  position: number,
+  duration: number,
+  { force = false }: ReportPositionOptions = {}
+): 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("[rustReportHost] Failed to report position:", err);
+  }
+}
+
+export async function reportMediaLoaded(duration: number): Promise<void> {
+  try {
+    await commands.playerReportMediaLoaded(Number.isFinite(duration) ? duration : 0);
+  } catch (err) {
+    console.warn("[rustReportHost] Failed to report media loaded:", err);
+  }
+}
+
+export function resetReporting(): void {
+  lastPositionReport = 0;
+}
+
+/**
+ * Build an {@link AdapterHost} bound to a specific media id that forwards adapter
+ * events to Rust. `onStreamUrlChanged`, `onBuffering`, and `onReady` are wired by
+ * the owning view (they affect the `<video src>` / spinner), so this host accepts
+ * optional view callbacks and defaults them to no-ops.
+ */
+export function createRustReportHost(
+  mediaId: string,
+  view: Partial<Pick<AdapterHost, "onStreamUrlChanged" | "onBuffering" | "onReady" | "onEnded" | "onError">> = {}
+): AdapterHost {
+  return {
+    onState: (state) => void reportState(state, mediaId),
+    onPosition: (position, duration) => void reportPosition(position, duration),
+    onMediaLoaded: (duration) => void reportMediaLoaded(duration),
+    onEnded: view.onEnded ?? (() => {}),
+    onError: view.onError ?? ((message) => console.warn("[rustReportHost] adapter error:", message)),
+    onStreamUrlChanged: view.onStreamUrlChanged ?? (() => {}),
+    onBuffering: view.onBuffering ?? (() => {}),
+    onReady: view.onReady ?? (() => {}),
+  };
+}
diff --git a/src/lib/player/adapters/types.ts b/src/lib/player/adapters/types.ts
new file mode 100644
index 0000000..8bda02d
--- /dev/null
+++ b/src/lib/player/adapters/types.ts
@@ -0,0 +1,127 @@
+/**
+ * PlayerAdapter contract — the decoupled boundary between the UI/backend and a
+ * concrete video player implementation (Linux HTML5+hls.js, or Android native).
+ *
+ * The whole point: UI components and the Rust backend interact with video ONLY
+ * through this interface. All element / hls.js / ExoPlayer / textTracks detail —
+ * and the backend seek/audio-track *strategy* round-trip — is internal to an
+ * implementation. A control intent (from UI or a backend lockscreen/remote/sleep
+ * event) reaches the element by the facade dispatching to the active adapter.
+ *
+ * State flows OUTWARD through the {@link AdapterHost} callback bag rather than the
+ * adapter importing stores/commands directly — this keeps adapters unit-testable
+ * with a mock host and keeps the reporting-to-Rust wiring in one place.
+ *
+ * TRACES: UR-003, UR-005, UR-020, UR-021 | DR-001, DR-023, DR-024, DR-028
+ */
+
+/** A subtitle track handed to the adapter at load time (WebVTT for HTML5). */
+export interface SubtitleTrackInput {
+  index: number;
+  url: string;
+  language: string | null;
+  label: string;
+  mimeType: string;
+}
+
+/** Everything an adapter needs to load and begin a stream. */
+export interface PlayerLoadOptions {
+  /** Jellyfin item id — used as the media_id when reporting state to Rust. */
+  mediaId: string;
+  /** Media source id for subtitle/seek URLs (null for local/direct). */
+  mediaSourceId: string | null;
+  /** HEVC/10-bit content that needs server transcoding (affects seek strategy). */
+  needsTranscoding: boolean;
+  /** Resume position in seconds (0 = start from beginning). */
+  initialPosition: number;
+  /** Live stream — no seek bar, no resume, no progress reporting. */
+  isLive: boolean;
+  /** Preselected audio track stream index, or null for the default. */
+  audioTrackIndex: number | null;
+  /** Known total duration in seconds (from runTimeTicks), or 0 if unknown. */
+  knownDuration: number;
+  /** Subtitle tracks available for this media. */
+  subtitleTracks: SubtitleTrackInput[];
+}
+
+/**
+ * Callback bag the adapter uses to report the element's lifecycle outward. The
+ * facade supplies an implementation that forwards to Rust (via the
+ * `player_report_*` commands) and, where needed, to the UI.
+ */
+export interface AdapterHost {
+  /** Playback state changed (playing/paused/loading/stopped/idle). */
+  onState(state: "playing" | "paused" | "loading" | "stopped" | "idle"): void;
+  /** Position/duration tick (adapter throttles; host forwards to Rust). */
+  onPosition(position: number, duration: number): void;
+  /** Media finished loading and knows its duration. */
+  onMediaLoaded(duration: number): void;
+  /** Playback reached the natural end of the stream (fires at most once). */
+  onEnded(): void;
+  /** A non-fatal or fatal playback error occurred. */
+  onError(message: string): void;
+  /**
+   * The stream URL the adapter is now playing changed (e.g. transcode reload on
+   * seek/audio-track switch). Lets the owning view keep its `<video src>` in sync.
+   */
+  onStreamUrlChanged(url: string): void;
+  /** Buffering/ready transitions, so the view can show/hide its spinner. */
+  onBuffering(isBuffering: boolean): void;
+  onReady(): void;
+}
+
+/**
+ * One concrete player implementation per platform. Methods are high-level
+ * intents; strategy objects, hls instances, and textTracks never cross this line.
+ */
+export interface PlayerAdapter {
+  /** Which platform backend this adapter represents. */
+  readonly kind: "html5" | "native";
+
+  /**
+   * Bind the output target. For the HTML5 adapter this is the `<video>` element
+   * (pass null on teardown); the native adapter ignores it (ExoPlayer renders to
+   * its own surface).
+   */
+  attach(element: HTMLVideoElement | null): void;
+
+  /** Load a stream and begin playback at `options.initialPosition`. */
+  load(streamUrl: string, options: PlayerLoadOptions): Promise<void>;
+
+  play(): Promise<void>;
+  pause(): Promise<void>;
+  /** Toggle play/pause; resolves to the resulting playing state. */
+  toggle(): Promise<boolean>;
+
+  // --- Seek/reload PRIMITIVES (decision-free) ---------------------------------
+  // The backend DECIDES whether a seek is an in-place element seek or a full
+  // source reload (transcode). The adapter only executes the chosen primitive;
+  // it contains no strategy branch. This is what keeps the decision logic shared
+  // in Rust (Option 1).
+
+  /**
+   * In-place seek of the already-loaded source (no reload). `offset` is the
+   * transcode seek offset the element position is relative to (0 for direct).
+   */
+  seekElement(positionSeconds: number, offset: number): Promise<void>;
+
+  /**
+   * Compound reload: swap to `url` and resume at `offset` seconds. Runs the
+   * invariant mechanical sequence for this platform (html5: pause → hls teardown
+   * → clear src → set new url → wait ready → resume; native: ExoPlayer setMediaItem
+   * + seekTo). No decision is made here — the backend already decided to reload.
+   */
+  reloadSource(url: string, offset: number): Promise<void>;
+
+  setVolume(volume: number): void; // 0..1
+  setMuted(muted: boolean): void;
+
+  /** Enable a subtitle track (null disables) — DOM textTracks is a webview primitive. */
+  selectSubtitle(streamIndex: number | null, arrayIndex?: number): Promise<void>;
+
+  /** Current position in seconds (adapter's own truth, e.g. element.currentTime + offset). */
+  getPosition(): number;
+
+  /** Tear down: destroy hls, detach element, stop reporting. Idempotent. */
+  dispose(): Promise<void>;
+}
diff --git a/src/lib/player/html5Adapter.ts b/src/lib/player/html5Adapter.ts
index cd6d3c2..2721d74 100644
--- a/src/lib/player/html5Adapter.ts
+++ b/src/lib/player/html5Adapter.ts
@@ -1,84 +1,19 @@
 /**
- * HTML5 <video> → Rust reporting adapter ("html5+rust internal module").
+ * Compatibility shim.
  *
- * 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
+ * The HTML5 → Rust reporting functions moved to `adapters/rustReportHost.ts` as
+ * part of the PlayerAdapter refactor. Existing callers import the reporter as
+ * `import * as html5Adapter from "$lib/player/html5Adapter"`; this shim keeps
+ * that working while the migration proceeds. New adapter code should depend on
+ * the `AdapterHost` interface (see `adapters/types.ts`) instead.
  */
 
-import { commands } from "$lib/api/bindings";
+export {
+  reportState,
+  reportPosition,
+  reportMediaLoaded,
+  resetReporting,
+} from "./adapters/rustReportHost";
 
-/** Player states mirrored to Rust (must match the strings playerEvents.ts handles). */
+/** @deprecated states are defined on the AdapterHost interface now. */
 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;
-}
diff --git a/src/lib/player/index.ts b/src/lib/player/index.ts
index 6b0fd87..e4dee1c 100644
--- a/src/lib/player/index.ts
+++ b/src/lib/player/index.ts
@@ -23,6 +23,34 @@ import type {
   PlayItemRequest,
 } from "$lib/api/bindings";
 import { auth } from "$lib/stores/auth";
+import type { PlayerAdapter } from "./adapters/types";
+
+// ---------------------------------------------------------------------------
+// Active player adapter registry
+//
+// When a video is playing, VideoPlayer registers its PlayerAdapter here so that
+// control intents — whether from UI or routed from a backend control event
+// (lockscreen/remote/sleep-timer) — reach the actual player element/surface.
+// When no adapter is registered (audio-only playback), control falls through to
+// the queue-level backend commands, which is the correct behavior there.
+// ---------------------------------------------------------------------------
+let activeAdapter: PlayerAdapter | null = null;
+
+function setActiveAdapter(adapter: PlayerAdapter): void {
+  activeAdapter = adapter;
+}
+
+function clearActiveAdapter(adapter?: PlayerAdapter): void {
+  // Only clear if it's still the one we think is active (guards against a newly
+  // mounted player's adapter being cleared by the outgoing player's teardown).
+  if (!adapter || activeAdapter === adapter) {
+    activeAdapter = null;
+  }
+}
+
+function getActiveAdapter(): PlayerAdapter | null {
+  return activeAdapter;
+}
 
 /**
  * Resolve the current repository handle, throwing a clear error if the user is
@@ -30,9 +58,19 @@ import { auth } from "$lib/stores/auth";
  * 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");
+  // The repository is the source of truth for the handle. We consult the auth
+  // store's isAuthenticated flag only as a best-effort guard — guarded in a
+  // try/catch so a not-yet-subscribable store (or a test double) can't block a
+  // valid repository handle.
+  try {
+    const authState = get(auth);
+    if (authState && authState.isAuthenticated === false) {
+      throw new Error("User not authenticated");
+    }
+  } catch (err) {
+    // get(auth) failed (e.g. non-store mock) — fall through to the repository,
+    // which is the authoritative source of the handle.
+    if (err instanceof Error && err.message === "User not authenticated") throw err;
   }
   const repo = auth.getRepository();
   if (!repo) {
@@ -46,23 +84,91 @@ function requireHandle(): string {
 // ---------------------------------------------------------------------------
 
 async function play() {
+  if (activeAdapter) return void (await activeAdapter.play());
   await commands.playerPlay();
 }
 
 async function pause() {
+  if (activeAdapter) return void (await activeAdapter.pause());
   await commands.playerPause();
 }
 
 async function toggle() {
+  if (activeAdapter) return void (await activeAdapter.toggle());
   await commands.playerToggle();
 }
 
 async function stop() {
+  // Stop is a queue/session-level action (clears playback); always go to backend.
+  // The adapter is disposed by VideoPlayer's own teardown.
   await commands.playerStop();
 }
 
 async function seek(positionSeconds: number) {
-  await commands.playerSeek(positionSeconds);
+  // Audio path: backend seeks the native backend directly.
+  if (!activeAdapter) {
+    await commands.playerSeek(positionSeconds);
+    return;
+  }
+  // Video path: ask the backend to DECIDE the strategy (in-place vs reload), then
+  // execute the matching adapter primitive. The decision logic stays in Rust
+  // (player_seek_video); the adapter only runs the chosen mechanical primitive.
+  await seekVideo(positionSeconds, null, null);
+}
+
+/**
+ * Video seek: backend decides strategy, facade dispatches the chosen adapter
+ * primitive. `mediaSourceId`/`audioTrackIndex` come from the video view (they are
+ * needed for the transcode reload URL). Requires an active video adapter.
+ */
+async function seekVideo(
+  positionSeconds: number,
+  mediaSourceId: string | null,
+  audioTrackIndex: number | null
+): Promise<void> {
+  const adapter = activeAdapter;
+  if (!adapter) {
+    await commands.playerSeek(positionSeconds);
+    return;
+  }
+  const response = (await commands.playerSeekVideo(
+    requireHandle(),
+    positionSeconds,
+    mediaSourceId,
+    audioTrackIndex,
+    adapter.kind === "html5"
+  )) as any;
+  // Serde keeps these snake_case (only the "strategy" tag is camelCase).
+  if (response.strategy === "reloadStream") {
+    await adapter.reloadSource(response.new_url ?? "", response.seek_offset ?? positionSeconds);
+  } else {
+    await adapter.seekElement(response.position ?? positionSeconds, 0);
+  }
+}
+
+/**
+ * Switch audio track: backend decides (may reload the stream), facade dispatches
+ * the resulting primitive. Requires an active video adapter.
+ */
+async function switchAudioTrack(
+  streamIndex: number,
+  arrayIndex: number,
+  currentPosition: number | null,
+  mediaSourceId: string | null
+): Promise<void> {
+  const adapter = activeAdapter;
+  if (!adapter) return;
+  const response = (await commands.playerSwitchAudioTrack(
+    requireHandle(),
+    streamIndex,
+    arrayIndex,
+    adapter.kind === "html5",
+    currentPosition,
+    mediaSourceId
+  )) as any;
+  if (response.strategy === "reloadStream") {
+    await adapter.reloadSource(response.new_url!, response.position!);
+  }
 }
 
 async function next() {
@@ -102,6 +208,7 @@ async function moveInQueue(fromIndex: number, toIndex: number) {
 // ---------------------------------------------------------------------------
 
 async function setVolume(volume: number) {
+  if (activeAdapter) activeAdapter.setVolume(volume);
   await commands.playerSetVolume(volume);
 }
 
@@ -110,10 +217,11 @@ async function toggleMute() {
 }
 
 // ---------------------------------------------------------------------------
-// Track selection (video)
+// Track selection (video) — dispatch to the active video adapter when present
 // ---------------------------------------------------------------------------
 
 async function setSubtitleTrack(streamIndex: number | null) {
+  if (activeAdapter) return void (await activeAdapter.selectSubtitle(streamIndex));
   await commands.playerSetSubtitleTrack(streamIndex);
 }
 
@@ -179,11 +287,18 @@ export const playerController = {
   setVolume,
   toggleMute,
   setSubtitleTrack,
+  seekVideo,
+  switchAudioTrack,
   playTracks,
   playAlbumTrack,
   playItem,
   addTrackById,
   addTracksByIds,
+  // Active-adapter registry (used by VideoPlayer to register its element adapter
+  // and by playerEvents.ts to route backend control commands to it).
+  setActiveAdapter,
+  clearActiveAdapter,
+  getActiveAdapter,
 };
 
 // ---------------------------------------------------------------------------
diff --git a/src/lib/services/playerEvents.ts b/src/lib/services/playerEvents.ts
index cccbd9b..63ba939 100644
--- a/src/lib/services/playerEvents.ts
+++ b/src/lib/services/playerEvents.ts
@@ -17,6 +17,7 @@ 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";
+import { playerController } from "$lib/player";
 import type { MediaItem } from "$lib/api/types";
 import { get } from "svelte/store";
 
@@ -116,9 +117,20 @@ function handlePlayerEvent(event: PlayerStatusEvent): void {
     case "sleep_timer_expired":
       // Backend stops its own playback; this signal lets HTML5 video (which
       // plays outside the backend on Linux) pause itself too.
+      // Preferred path: drive the active video adapter directly so the backend
+      // has real control authority over the webview element. The legacy
+      // sleepTimerExpiredSignal is kept for any remaining subscribers.
+      playerController.getActiveAdapter()?.pause();
       sleepTimerExpiredSignal.update((n) => n + 1);
       break;
 
+    case "control_command":
+      // Backend-originated control targeting the active frontend player adapter
+      // (lockscreen/remote/sleep). Route it to the adapter so a backend intent
+      // reaches the webview <video> element.
+      handleControlCommand(event.action, event.position);
+      break;
+
     case "show_next_episode_popup":
       handleShowNextEpisodePopup(
         event.current_episode,
@@ -292,6 +304,36 @@ function handleSleepTimerChanged(mode: SleepTimerMode, remainingSeconds: number)
   sleepTimer.set({ mode, remainingSeconds });
 }
 
+/**
+ * Route a backend-originated control command to the active player adapter, so a
+ * backend intent (lockscreen/remote/sleep) can drive the webview <video> element
+ * that Rust cannot reach directly. No-op when no video adapter is active (audio
+ * playback is already fully backend-driven).
+ */
+function handleControlCommand(action: string, position: number | null): void {
+  const adapter = playerController.getActiveAdapter();
+  if (!adapter) return;
+  switch (action) {
+    case "play":
+      void adapter.play();
+      break;
+    case "pause":
+      void adapter.pause();
+      break;
+    case "seek":
+      // Backend-driven in-place seek (e.g. lockscreen scrub). The backend has
+      // already decided this is a simple position change, so use the element
+      // seek primitive with no transcode offset.
+      if (position != null) void adapter.seekElement(position, 0);
+      break;
+    case "stop":
+      void adapter.pause();
+      break;
+    default:
+      console.warn("[playerEvents] Unknown control command:", action);
+  }
+}
+
 /**
  * Handle show next episode popup event.
  *
diff --git a/src/routes/player/[id]/+page.svelte b/src/routes/player/[id]/+page.svelte
index e401422..bd580ac 100644
--- a/src/routes/player/[id]/+page.svelte
+++ b/src/routes/player/[id]/+page.svelte
@@ -451,7 +451,10 @@
     savedProgress = null;
     const id = itemId;
     if (id) {
-      loadAndPlay(id, 0);
+      // forceRestart bypasses the resume-progress check; without it, passing a
+      // start position of 0 is treated as "no position" (`!startPosition`), which
+      // re-runs the resume check and re-shows this very dialog in a loop.
+      loadAndPlay(id, 0, true);
     }
   }
 
@@ -537,7 +540,12 @@
     if (id) {
       reportPlaybackStopped(id, positionSeconds);
     }
-    html5Adapter.reportState("stopped", id ?? null);
+    // Intentionally do NOT emit a "stopped" player state here. This runs on both
+    // natural end-of-video (an autoplay handoff the backend's on_video_playback_ended
+    // owns) and on player close/unmount (where player_stop already drives the
+    // backend state). Emitting StateChanged{stopped} on natural end flips the
+    // player/mode to idle mid-handoff and suppresses next-episode auto-advance —
+    // the "sleep timer pauses at the end of an episode instead of continuing" bug.
   }
 
   async function handleVideoEnded() {

From 37455bc4701c450dc6a9fe9fc502d1724f9b5fb5 Mon Sep 17 00:00:00 2001
From: Duncan Tourolle <duncan@tourolle.paris>
Date: Thu, 2 Jul 2026 20:01:43 +0200
Subject: [PATCH 2/2] Use incremental build

---
 scripts/build-and-deploy.sh | 14 +++++++++-----
 scripts/build-android.sh    | 23 +++++++++++++++++------
 2 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/scripts/build-and-deploy.sh b/scripts/build-and-deploy.sh
index 60b7edd..41d07e3 100755
--- a/scripts/build-and-deploy.sh
+++ b/scripts/build-and-deploy.sh
@@ -3,15 +3,19 @@
 
 set -e
 
-BUILD_TYPE="${1:-debug}"
-
 echo "🚀 Build and Deploy Android APK"
 echo ""
 
-# Build APK
-./scripts/build-android.sh "$BUILD_TYPE"
+# Pass all args (build type and/or --clean) through to the build script.
+./scripts/build-android.sh "$@"
 
 echo ""
 
-# Deploy APK
+# Deploy APK — extract build type (default debug), ignoring flags like --clean.
+BUILD_TYPE="debug"
+for arg in "$@"; do
+    case "$arg" in
+        debug|release) BUILD_TYPE="$arg" ;;
+    esac
+done
 ./scripts/deploy-android.sh "$BUILD_TYPE"
diff --git a/scripts/build-android.sh b/scripts/build-android.sh
index b56f76b..8d1e001 100755
--- a/scripts/build-android.sh
+++ b/scripts/build-android.sh
@@ -15,13 +15,24 @@ echo "Android SDK: $ANDROID_HOME"
 echo "NDK: $NDK_HOME"
 echo ""
 
-# Build type: debug or release (default: debug)
-BUILD_TYPE="${1:-debug}"
+# Parse args: build type (debug/release) and optional --clean flag.
+# By default the build is INCREMENTAL — Cargo and Vite reuse their caches.
+# Pass --clean (or CLEAN=1) to wipe all caches for a from-scratch build.
+BUILD_TYPE="debug"
+CLEAN="${CLEAN:-0}"
+for arg in "$@"; do
+    case "$arg" in
+        --clean) CLEAN=1 ;;
+        debug|release) BUILD_TYPE="$arg" ;;
+    esac
+done
 
-# Step 0: Clear build caches to ensure fresh builds
-echo "🧹 Clearing build caches..."
-rm -rf node_modules/.vite dist .svelte-kit .next build target src-tauri/target 2>/dev/null || true
-npm install > /dev/null 2>&1
+# Step 0: Optionally clear build caches for a fully fresh build.
+if [ "$CLEAN" = "1" ]; then
+    echo "🧹 Clearing build caches (clean build)..."
+    rm -rf node_modules/.vite dist .svelte-kit .next build target src-tauri/target 2>/dev/null || true
+    npm install > /dev/null 2>&1
+fi
 
 # Step 1: Sync Android source files
 echo "🔄 Syncing Android sources..."