ci(android): ship Gradle in the builder image instead of downloading it

The release APK job died at the Gradle wrapper step, after the 11-minute Rust compile had already succeeded: Downloading https://services.gradle.org/distributions/gradle-8.14.3-bin.zip java.net.SocketException: Unexpected end of file from server `tauri android init` regenerates gen/android with a wrapper pointing at services.gradle.org, so every Android job re-downloaded ~130MB of Gradle at build time. That is slow on a good day and a hard build failure when the CDN drops the connection mid-transfer. It was also a standing violation of the rule that every build tool must already live in the builder image. Dockerfile.builder installs Gradle 8.14.3, keeping both the unpacked distribution (on PATH) and the original zip under /opt/gradle/dist. A `gradle --version` smoke-test fails the image build on a bad version rather than letting CI discover it. sync-android-sources.sh then repoints the regenerated wrapper at that local zip, which is the established place for fixing up the generated project. It parses the version the wrapper actually requests, so a future Tauri Gradle bump logs "not in image, will download" instead of pointing at a missing file. On dev machines /opt/gradle/dist does not exist and the properties file is left untouched. Verified by running the project's own wrapper jar inside a network namespace with no connectivity: it resolved and unpacked the local zip to 100% and proceeded into build-script evaluation. Note: this is inert until the builder image is rebuilt and pushed (scripts/build-builder-image.sh). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Merge branch 'fix/android-resume-position'
2026-08-13 07:47:43 +02:00 · 2026-08-12 22:14:44 +02:00 · 2026-08-12 22:14:20 +02:00 · 2026-08-12 20:11:12 +02:00 · 2026-08-12 20:09:17 +02:00 · 2026-08-12 20:07:57 +02:00
36 changed files with 5308 additions and 3076 deletions
@@ -96,6 +96,12 @@ jobs:
      - name: Install dependencies
        run: bun install
      # The Linux job previously had no version step at all, so a tagged release
      # built Linux packages from whatever version happened to be committed.
      - name: Set app version from tag
        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
        if: startsWith(github.ref, 'refs/tags/v')
      - name: Build for Linux
        run: bun run tauri build
        env:
@@ -156,15 +162,13 @@ jobs:
          restore-keys: |
            ${{ runner.os }}-bun-
      # The tag is the single source of truth for a release version; the script
      # stamps every file that carries it (package.json, tauri.conf.json,
      # Cargo.toml, Cargo.lock). This step used to sed only tauri.conf.json, so
      # the other three shipped whatever was committed.
      - name: Set app version from tag
-        run: |
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
-          # On a tag build the tag is the single source of truth for the version.
+        if: startsWith(github.ref, 'refs/tags/v')
          if echo "$GITHUB_REF" | grep -q '^refs/tags/v'; then
            VERSION="${GITHUB_REF#refs/tags/v}"
            echo "Setting version to $VERSION"
            sed -i "s/\"version\": \"[^\"]*\"/\"version\": \"$VERSION\"/" src-tauri/tauri.conf.json
          fi
          grep '"version"' src-tauri/tauri.conf.json
      - name: Build Windows (NSIS installer + exe)
        run: OUTPUT_DIR="$PWD/dist/windows" WIN_BUNDLES=nsis ./scripts/build-windows-cross.sh
@@ -217,48 +221,22 @@ jobs:
      - name: Install dependencies
        run: bun install
      # Stamp before `android init`: it derives its generated project (including
      # the initial versionCode) from tauri.conf.json.
      - name: Set app version from tag
-        run: |
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
-          # On a tag build, the tag is the single source of truth for the
+        if: startsWith(github.ref, 'refs/tags/v')
          # version name. On non-tag runs keep whatever is in tauri.conf.json.
          if echo "$GITHUB_REF" | grep -q '^refs/tags/v'; then
            VERSION="${GITHUB_REF#refs/tags/v}"
            echo "Setting version to $VERSION"
            sed -i "s/\"version\": \"[^\"]*\"/\"version\": \"$VERSION\"/" src-tauri/tauri.conf.json
          fi
          grep '"version"' src-tauri/tauri.conf.json
      - name: Initialize Android project
        run: bun run tauri android init
      # Re-run after init: tauri.properties only exists now, and its
      # autogenerated versionCode (0.0.15 -> 15) is both tiny and NOT monotonic
      # against the 1000 floor already shipped in the field. The script rewrites
      # it as 1000 + major*10000 + minor*100 + patch. Runs unconditionally so
      # untagged builds get a sane code too, derived from git describe.
      - name: Pin a monotonic Android versionCode
-        run: |
+        run: ./scripts/set-version.sh "${GITHUB_REF#refs/tags/}"
          # `tauri android init` autogenerates src-tauri/gen/android/app/tauri.properties
          # with a versionCode derived from the semver (e.g. 0.0.15 -> 15). That
          # number is (a) tiny and (b) NOT monotonic across our history: earlier
          # local/dev builds shipped versionCode 1000 (from a 0.1.0 config), so a
          # plain 15 would be a *downgrade* and Android would refuse the update.
          #
          # Derive an explicit code that is both monotonic in semver order and
          # always above the 1000 floor already in the field:
          #   code = 1000 + major*10000 + minor*100 + patch
          # e.g. 0.0.14 -> 1014, 0.0.15 -> 1015, 0.1.0 -> 1100, 1.0.0 -> 11000.
          # POSIX sh only (the runner uses dash): no here-strings, no \s in sed.
          PROPS="src-tauri/gen/android/app/tauri.properties"
          VERSION=$(grep '"version"' src-tauri/tauri.conf.json | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
          MAJ=$(echo "$VERSION" | cut -d. -f1)
          MIN=$(echo "$VERSION" | cut -d. -f2)
          PAT=$(echo "$VERSION" | cut -d. -f3)
          # Guard against a malformed/missing component so we never emit code 0.
          : "${MAJ:=0}" "${MIN:=0}" "${PAT:=0}"
          CODE=$(( 1000 + MAJ*10000 + MIN*100 + PAT ))
          echo "version=$VERSION -> versionCode=$CODE"
          if grep -q '^tauri.android.versionCode=' "$PROPS"; then
            sed -i "s/^tauri.android.versionCode=.*/tauri.android.versionCode=$CODE/" "$PROPS"
          else
            echo "tauri.android.versionCode=$CODE" >> "$PROPS"
          fi
          cat "$PROPS"
      - name: Sync custom Android sources & gradle config
        run: ./scripts/sync-android-sources.sh
@@ -6,6 +6,58 @@ Entries are grouped by the capability they change, not by commit. Requirement
 IDs in parentheses point at [docs/requirements.md](docs/requirements.md); the
 generated trace matrix lives in [docs/traceability.md](docs/traceability.md).
 ## v0.5.0
 ### ✨ Features
 - **Android video can render on the device's own video surface.** Settings →
  Video Playback → **Native Video** (experimental, off by default) hands
  decoding to ExoPlayer, which draws into a surface composited *behind* a
  transparent WebView, with the player controls layered on top of it.
  The backend had reported "this platform has a native video surface" on Android
  all along, but the frontend threw that answer away in two separate places, so
  the path had never actually run. Both are lifted. The setting can only ever
  *suppress* the backend's choice, never override it upward: turning it off
  forces the web player even where native is available, and turning it on does
  nothing on platforms whose backend never offered it — Linux cannot composite
  behind its webview, so it stays on the web player either way.
  Verified playing on a physical device. Still unverified: the mini-player
  transition, audio-track switching on the native path, and whether hardware
  decoding measurably improves battery or CPU — so the toggle stays off by
  default. (UR-003, UR-004 → DR-150)
 ### 🐛 Fixes
 - **The video surface now reaches the screen at all.** The player built its
  video surface, handed it to ExoPlayer, and then never added it to the view
  hierarchy, because the Activity reference it needed was never supplied — so
  native video would have decoded to a surface nobody could see, whatever else
  was fixed. This also silently disabled picture-in-picture for video, which
  gated on that same never-attached surface. (UR-003, UR-041 → DR-151)
 - **Platform playback support is no longer guessed from the browser user
  agent.** The frontend re-derived "does this platform decode audio natively" by
  string-matching `navigator.userAgent` — a second copy of a decision the
  backend already makes, free to drift out of step with the backends it was
  describing. The backend now reports its own capabilities and the frontend
  consumes them. (UR-003, UR-005 → DR-152)
 ### 🔧 Internal
 - **The git tag is now the single source of truth for a release version.** The
  version lived in four files that had to be edited in lockstep, and the release
  workflow rewrote exactly one of them — so a tagged build produced an installer
  named for the tag wrapped around package metadata naming the *previous*
  release, and the Linux job, which had no version step at all, shipped whatever
  happened to be committed. `scripts/set-version.sh` now writes all four from
  one argument and every release job calls it with the tag. The Android
  `versionCode` is derived in the same place, guarded by tests for the property
  that actually matters: it must increase monotonically and stay above the value
  already installed in the field, or Android silently refuses the update.
  (DR-153)
 ## v0.4.8
 ### 🐛 Fixes
@@ -87,6 +87,22 @@ RUN $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --sdk_root=$ANDROID_HOME \
 # Set NDK environment variable
 ENV NDK_HOME=$ANDROID_HOME/ndk/$NDK_VERSION
 # Gradle distribution. `tauri android init` regenerates gen/android with a
 # wrapper pointing at services.gradle.org, so every Android job would otherwise
 # download ~130MB of Gradle at build time — slow, and a hard failure when the
 # CDN hiccups ("Unexpected end of file from server"). Ship the distribution in
 # the image instead; scripts/sync-android-sources.sh repoints the regenerated
 # wrapper at this local copy. Keep GRADLE_VERSION in sync with the version
 # Tauri's generated wrapper requests.
 ENV GRADLE_VERSION=8.14.3 \
    GRADLE_HOME=/opt/gradle/gradle-8.14.3
 RUN mkdir -p /opt/gradle/dist && \
    wget -q "https://services.gradle.org/distributions/gradle-${GRADLE_VERSION}-bin.zip" \
        -O "/opt/gradle/dist/gradle-${GRADLE_VERSION}-bin.zip" && \
    unzip -q "/opt/gradle/dist/gradle-${GRADLE_VERSION}-bin.zip" -d /opt/gradle && \
    "$GRADLE_HOME/bin/gradle" --version
 ENV PATH="$GRADLE_HOME/bin:$PATH"
 # ---------------------------------------------------------------------------
 # Desktop packaging tools — kept in a trailing layer ON PURPOSE so that adding
 # or changing a packaging tool doesn't invalidate the expensive apt/rust/Android
@@ -312,6 +312,12 @@ Internal architecture, components, and application logic.
 | DR-146 | The no-audio-track fallback picks a track the renderer can actually play. When ExoPlayer selected no audio track, the recovery forced group 0 / track 0 unconditionally — but the most likely reason nothing was selected is that this very track cannot be decoded on this device, so the override reinstated the silence it was meant to fix. It now scans the groups for the first `isTrackSupported` track and overrides to that, and clears `setTrackTypeDisabled(TRACK_TYPE_AUDIO)` because audio may equally have been off at the type level, which an override alone does not undo. When no group holds a supported track the condition is logged as an error — the server was expected to transcode — rather than leaving a silent video with no explanation in the log | Playback | UR-004 | Done |
 | DR-148 | The video direct-play profile advertises only what the **webview** can decode. The audio codec list comes from `MediaCodecList`, which describes ExoPlayer — but video does not play through ExoPlayer on either platform: Android force-renders every video in the webview `<video>` element (the interim override in `VideoPlayer.svelte`, because the native SurfaceView sits behind an opaque webview) and Linux always has. Chromium and WebKit decode a far narrower set than the platform does, and the gap is widest on devices whose vendor licenses Dolby: a phone shipping `/vendor/etc/media_codecs_dolby_audio.xml` reports `ac3,eac3`, so Jellyfin direct-played an E-AC-3 track with `static=true` and the webview built a video decoder and no audio decoder at all — full picture, no sound. The defect is triggered by *capability*, not the lack of it, which is why it reproduced on one Motorola while a Fairphone and an Honor tablet played the same file on the same build: a device without the Dolby decoder never claims the codec, so the server transcodes to AAC and it plays. `video_audio_codecs` narrows the platform list to the webview-decodable set (`aac,mp3,opus,vorbis,flac`) for the video direct-play profile *only* — the audio-only profile keeps the full list, since that playback really is the native player's and narrowing it would transcode music that plays perfectly well. A list with nothing decodable still claims `aac` rather than going out empty, because a profile that claims nothing invites the server to give up instead of transcoding. The video codec list is deliberately untouched: HEVC direct-plays through the webview correctly, so the constraint is specific to audio | Playback | UR-004 | Done |
 | DR-149 | The client decides whether its own renderer can decode the audio, rather than trusting the server's negotiation. Advertising a webview-shaped profile (DR-148) turned out to be necessary but not sufficient: Jellyfin 10.11.5 enforces a `DirectPlayProfile`'s `Container` and `VideoCodec` — excluding either returns `SupportsDirectPlay: false` with `TranscodeReasons=ContainerNotSupported` / `VideoCodecNotSupported` — but **ignores its `AudioCodec`**, offering an E-AC-3 track for direct play against a profile listing only `aac,flac,mp3,opus,vorbis`. Neither a `VideoAudio` `CodecProfile` forbidding the codec nor a `MaxAudioChannels: 2` against a 6-channel track changes the answer, so no profile the client can send fixes it and the picture plays silent. The negotiated source's audio is therefore checked locally against what the webview decodes, and an undecodable track forces the existing h264/aac HLS transcode URL regardless of the server saying direct play is fine — `direct_play` and `needs_transcoding` are corrected to match, so the frontend and the reporting path agree with the URL actually used. The track judged is the one the server would serve: the default, or the first when nothing is marked default, since a supported track further down the list is not the one that plays. A source with no audio streams, or a stream whose codec the server did not name, is left alone — forcing a transcode on a guess spends server CPU on files that already play | Playback | UR-004 | Done |
 | DR-150 | Android video renders on the native ExoPlayer surface behind a transparent WebView, behind the `experimentalNativeVideo` opt-in. Rust already reported `use_html5_element: false` on Android, but two frontend overrides discarded it — `createAdapter()` hardcoded `"html5"`, and `VideoPlayer.svelte` forced `useHtml5Element = true` and stopped the native backend `player_play_item` had just started. 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, so promoting there is a black screen). Compositing requires clearing two independent opaque layers, and clearing only one leaves audio over a black picture — the WebView widget background and window drawable from Kotlin (`AndroidVideoSurface.setTransparent`), and the page's `html`/`body` and app-shell background from CSS (`data-native-video`). Transparency is declared in `tauri.android.conf.json` rather than the base config, because a transparent window on Linux has nothing behind it, and is toggled per playback session rather than set once, because a permanently transparent window shows the launcher through the rest of the app | Playback | UR-003, UR-004 | Done (behind `experimentalNativeVideo`, default off) |
 | DR-151 | The player's video SurfaceView actually reaches the view hierarchy. `JellyTauPlayer.setActivity()` had zero callers, so `currentActivity` was always null and `autoAttachSurface()` returned at "Cannot attach surface - no Activity reference". The surface was created and handed to ExoPlayer but never added to the content view, so native video decoded to a surface that was never on screen — independent of any webview transparency. `MainActivity.onCreate` now supplies the reference, which also revives PiP on the video path: `canEnterPip()` gates on `isVideoSurfaceAttached()`, which had been permanently false | Playback | UR-003, UR-041 | Done |
 | DR-152 | Platform playback facilities are reported by Rust, not sniffed from the user agent. `webviewAudio.ts` re-derived "does this platform have a native audio backend" by matching `navigator.userAgent` against `android`/`linux` — a second copy of the `cfg!` gate the backends are compiled under, free to drift from it. `player_get_capabilities` now returns `usesWebviewAudio` and `supportsNativeVideo` from the same cfg gates, and the frontend consumes them; the settings toggle for native video is hidden entirely where the platform cannot support it | Player | UR-003, UR-005 | Done |
 | DR-153 | The git tag is the single source of truth for a release version. The version lived in four files (`package.json`, `tauri.conf.json`, `Cargo.toml`, `Cargo.lock`) that had to be hand-edited in lockstep, and CI's release job rewrote exactly one of them — so a tagged build produced an installer named for the tag wrapped around package metadata naming the previous release, while the Linux job had no version step at all and shipped whatever was committed. `scripts/set-version.sh` writes all four from one argument and is the only thing that does; every release job calls it with the tag. The Android `versionCode` is derived in the same place as `1000 + major*10000 + minor*100 + patch`, which is monotonic in semver order and clears the 1000 floor already installed in the field — a lower code than the installed one makes Android refuse the update. A prerelease suffix is stripped before that arithmetic, which would otherwise abort the script, and a non-tag ref (CI passes `${GITHUB_REF#refs/tags/}` unconditionally) falls back to `git describe` rather than failing a branch build | Build | - | Done |
 | DR-154 | A watch position that cannot reach the server is queued, not dropped. `sync_queue` and its drain (DR-131) were built, tested and running, but the stop-report path never fed them: `HybridRepository::report_playback_stopped` is a bare pass-through to the online repository ("Playback reporting goes directly to server"), and on failure the error surfaced to a frontend `catch` whose own comment read "Server error - could queue, but for now just log". Both producers that *would* have queued it — `PlaybackReporter::queue_for_sync` in Rust and `syncService.queuePlaybackProgress` on the frontend — have no callers on the playback path, so closing a video while the server was unreachable lost the resume point outright even though `user_data.pending_sync` was dutifully set to 1 and nothing ever drains that flag for positions (unlike favourites, DR-120). The command layer now enqueues a `report_playback_stopped` row whenever the push fails, which the existing drain already knows how to parse and replay. The pending row for an item is **superseded in place** rather than appended to: progress is reported every 10s, so a server that stays down would otherwise add a row per tick, all of them obsoleted by the newest — the unbounded queue DR-131 exists to prevent. Only `pending`/`failed` rows are superseded, because an `abandoned` row has been given up on and reviving it would restore that same growing counter. Queueing is best-effort and never fails the command: the local position is already saved, so a failed *queue* write must not be reported as a lost position | Backend | UR-025, UR-002 | Done |
 | DR-155 | A watch position set on another device reaches this one. The resume check reads the local `user_data` row and nothing else, but `mirror_user_data` — the only path by which server `UserData` lands in that table — mirrored `is_favorite` alone, and returned early whenever that field was absent, which is exactly the shape of an ordinary watched episode. So `playback_position_ticks` was write-only from this device's perspective: watch 40 minutes in a browser, open JellyTau, and it resumed from whatever *this* device last saw or offered no resume at all — the same user-visible symptom as DR-150's Android bug, from an unrelated cause, which is why resume read as broadly flaky. The mirror now carries the position alongside the favourite flag under the same `pending_sync = 0` conflict rule, so a local position still waiting to be pushed is never pulled *backwards* by a server that has not yet heard where we got to; `COALESCE(excluded.x, user_data.x)` means a field the server omitted keeps its stored value rather than being nulled, and a row with neither field is still skipped rather than fabricated as zeroes. Mirroring alone was not sufficient: `get_item` — the call the player route makes — returned the cached copy on a hit and never consulted the server, so for an already-cached item the mirror never ran. It now refreshes in the background on a cache hit (`race_with_refresh`, the reusable form of what `get_items` already did inline), which is why browsing a season picked up other devices' state while opening the episode directly did not. The refreshed value lands for the next read, the cache-first race still answering immediately | Backend | UR-025, UR-002 | Done |
 | DR-143 | Flipping the offline downloaded-only gate actually re-queries the listing. The gate (DR-078) is a process-wide flag in Rust consulted only *while a query runs*, but no library surface re-queried when its inputs changed: `useServerReachabilityReload` fires only on the offline → **online** transition, and `GenericMediaListPage`, `GenericGenreBrowser` and the favourites page never even called its `checkServerReachability`. So going offline left the full server catalog on screen under a now-closed gate, and toggling "Show all server media" only greyed cards — `MediaCard.isServerOnly` is a pure frontend derivation that updates instantly — without adding or removing a single row. The filter therefore read as "shows everything until I filter, then greys some of it" while the backend gate was correct and simply never exercised. `catalogFilterVersion` is the refetch signal: `pushCatalogVisibility` now awaits `set_show_server_catalog` and bumps the version only **after** the backend accepts the new flag, since a reload racing the push would re-query under the old gate and undo itself. A failed push clears `lastIncludeCatalog` instead of latching it, so the next identical transition is retried rather than skipped as a no-op and left permanently disagreeing with the backend. `useOfflineFilterReload` subscribes pages to that signal, skipping the value they already loaded under; it is wired into both generic list components and the movies/music/tv/favourites landing pages and the `/library/[id]` detail page | UI | UR-052 | Done |
 | DR-135 | A download's media type comes from the item, not a default. `download_item` — the path a media card uses to queue an item while offline — never records `media_type`, and the reconnect resolver read that NULL as `'audio'`, so a **movie** queued from a card had its URL resolved by `get_audio_stream_url`. The file that landed on disk was an audio-only transcode, which is why a "downloaded" film could never play offline no matter how the path or protocol was fixed. The resolver now falls back to the item's own `item_type` (`VIDEO_ITEM_TYPES` in Rust, so the frontend never learns which types are video) and only defaults to audio when the item is not cached locally. An explicit `media_type` on the row still wins | Downloads | UR-071, UR-052 | Done |
 | DR-136 | Rows already downloaded under the audio default are repaired, not just prevented. They are identifiable after the fact — no `media_type`, but a video item — so on reconnect they are reset to `pending` with their audio URL cleared and re-resolved by DR-135's corrected logic, overwriting the audio file in place. Without this the fix is invisible to anyone who had already queued a film: the row still reads "downloaded" and still fails to play. Rows carrying an explicit `media_type` and genuine audio downloads are left untouched | Downloads | UR-071 | Done |
@@ -543,6 +549,10 @@ Internal architecture, components, and application logic.
 | UT-140 | `useOfflineFilterReload` skips the value a page already loaded under and reloads on each later change | DR-143 | Done |
 | UT-141 | The advertised channel cap: an unknown or zero reading falls back to stereo, a real route keeps its channels, an absurd driver reading is capped at 7.1, and mono is taken at its word | DR-141 | Done |
 | UT-148 | Forcing a transcode from the client: an undecodable default track forces one, a decodable track does not, the default track decides rather than the first, the first decides when nothing is marked default, and neither an audio-less source nor an unnamed codec is second-guessed | DR-149 | Done |
 | UT-149 | `createAdapter` returns the native adapter only when Rust reports native AND `experimentalNativeVideo` is on; the flag off forces HTML5 even when Rust says native, and the flag on never promotes a platform Rust reported as HTML5 | DR-150 | Done |
 | UT-150 | `set-version.sh` stamps all four manifests without touching dependency versions, and the Android versionCode is monotonic across an upgrade sequence, clears the 1000 floor, and survives a prerelease suffix | DR-153 | Done |
 | UT-151 | An unreportable stop lands in the queue and is pushed by the existing drain; re-queueing the same item supersedes the earlier position rather than adding a row, distinct items keep their own positions, and an abandoned row is not revived by a later report | DR-154 | Done |
 | UT-152 | Caching a server result mirrors its watch position locally — including for an item carrying a position but no favourite flag — without inventing a row for an item the server reported no user data for, and without pulling a still-unsynced local position backwards | DR-155 | Done |
 | UT-142 | The audio codecs offered for video direct play: a Dolby device's real `MediaCodecList` output drops `ac3`/`eac3`, AMR and raw PCM are dropped too, a fully-supported list is passed through untouched, a list with nothing decodable still claims `aac`, and stray spacing or casing does not decide whether the user gets sound | DR-148 | Done |
 | UT-143 | Subtitle URLs resolve to plain strings before they reach the markup (never a Promise), unresolvable tracks are dropped, a stale selection collapses to "Off", and a server-default track is never auto-selected | UR-020, DR-023 | Done |
 | UT-144 | VideoPlayer actually renders `<track kind="subtitles">` children carrying `data-stream-index`, with no `default` attribute and no async `getSubtitleUrl()` bound to `src` | UR-020, DR-023 | Done |
@@ -1,7 +1,19 @@
 # Spec: Android native video — transparent-webview spike
-**Status:** Proposed (spike — timeboxed, may conclude "not viable")
+**Status:** Spike succeeded — native video confirmed working on a physical
-**Requirements:** IR-004, UR-003, UR-004 → DR-001, DR-023, DR-024
+device (2026-08-11) with `experimentalNativeVideo` on. Shipped behind that flag,
 default off. Branch `feat/android-native-video`.
 **The spike's central question is answered: yes.** A `SurfaceView` *can* be
 composited behind a transparent Tauri WebView on Android. Nothing upstream
 blocked it and nothing upstream demonstrated it — this is, as far as the issue
 trackers show, the first working instance. The remaining flag is about test
 coverage and the unverified cases below, not about viability.
 **Requirements:** IR-004, UR-003, UR-004, UR-041 → DR-001, DR-004, DR-150, DR-151, DR-152
 **Note:** the original draft cited DR-023/DR-024 here. Those are the *subtitle*
 and *audio-track selection UI* requirements — unrelated to this work. The IDs
 actually implemented are DR-150 (native rendering behind the flag), DR-151 (the
 severed SurfaceView attach chain) and DR-152 (capabilities reported by Rust).
 **UX spec:** n/a — no intended visual change; the video surface must land exactly where the `<video>` element is today
 **Supersedes / revises:** acts on finding 2 of [playback-backend-unification.md](playback-backend-unification.md)
@@ -109,6 +121,46 @@ in here rather than leaving a second, subtler copy of the bug behind. If
 `get_player_status` does not currently expose enough to cover the audio case, add
 the field — that is backend work, and correct.
 ### Implementation findings (2026-08-11)
 Two blockers existed that this spec did not anticipate. Both were in code the
 spec assumed was merely *unreachable*; it was also *broken*.
 **1. The Kotlin attach chain was severed.** `JellyTauPlayer.setActivity()` had
 **zero callers** anywhere in the tree. `currentActivity` was therefore always
 null, so `autoAttachSurface()` logged "Cannot attach surface - no Activity
 reference" and returned. 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, *regardless* of webview transparency. Fixed by calling
 `JellyTauPlayer.setActivity(this)` from `MainActivity.onCreate`.
 Note the knock-on: `PictureInPictureManager.canEnterPip()` gates on
 `VideoOverlayManager.isVideoSurfaceAttached()`, which was permanently false. PiP
 on the video path was dead for the same reason.
 **2. `createAdapter()` was not the real gate.** It is never called by production
 code — `VideoPlayer.svelte` constructs `Html5PlayerAdapter` directly. The actual
 override was `VideoPlayer.svelte`'s INTERIM block, which read Rust's
 `useHtml5Element`, forced it to `true`, and called `playerStop()` to kill the
 native backend `player_play_item` had just started. Both sites are now fixed;
 `VideoPlayer.svelte` routes through `createAdapter()` so there is one gate.
 **Transparency needs two independent layers cleared,** not one. The spec's
 Phase 1 named only `html, body`. Clearing just the page leaves the WebView
 widget's own background opaque, which is a black screen with audio — the exact
 symptom the INTERIM comment described as "native surface not visible". Both are
 now toggled together by `$lib/utils/videoSurface.ts`:
 | Layer | Cleared by | Reachable from |
 |-------|-----------|----------------|
 | WebView widget background + window drawable | `AndroidVideoSurface.setTransparent()` (MainActivity) | Kotlin only |
 | `html`/`body` + app-shell `--color-background` | `data-native-video` attribute → app.css | CSS only |
 Transparency is scoped to `tauri.android.conf.json` rather than the base config:
 a transparent window on Linux is a regression, since nothing renders behind it.
 It is also toggled per-session rather than set once — a permanently transparent
 window shows the launcher through the rest of the app.
 ### Phase 3 — surface positioning
 The hard part, and where this most likely fails. The webview's `<video>` element
@@ -124,6 +176,32 @@ the video is effectively fullscreen on Android, which it is in the player route.
 rotation or the mini-player transition without visible artefacts, the spike fails
 and we keep HTML5. Do not ship a janky native path for a codec win.
 **Update: no rect plumbing was needed.** The premise — that the surface must be
 positioned to match a laid-out `<video>` box — does not hold on the player route,
 where video is fullscreen. `VideoOverlayManager` adds the SurfaceView at index 0
 of `android.R.id.content` with `MATCH_PARENT`, and `fitSurfaceToScreen()`
 (`JellyTauPlayer.kt`) already letterboxes/pillarboxes to the real video aspect
 ratio and re-centres via a `Gravity.CENTER` `FrameLayout.LayoutParams`. Rotation
 is handled by an `OnLayoutChangeListener` that re-fits on any bounds change. The
 frontend's native branch is a bare `flex-1` box, so there is no rect to report
 and nothing to keep in sync.
 Fullscreen playback is confirmed working on device. But this reasoning rests
 entirely on the fullscreen assumption, so **the mini-player transition is the
 known gap** — it is the one case where the surface is *not* fullscreen, and
 therefore the one case where the "no rect plumbing needed" conclusion could
 still turn out to be wrong. If artefacts appear there, the fix is the rect
 reporting this section originally proposed, scoped to that transition alone.
 ### A trap for the next implementer
 There is a **stale duplicate player** at
 `src-tauri/android/app/src/main/java/com/dtourolle/jellytau/player/JellyTauPlayer.kt`
 (only commit: `cfddc1e` "First working POC"). No `sourceSets` entry points at it,
 so it is not compiled — but edits made there silently do nothing. The canonical
 tree is `src-tauri/android/src`, synced into `gen/` by
 `scripts/sync-android-sources.sh`.
 ### What we gain if it works
 - **Hardware decode via MediaCodec** — `CodecDetector.kt` already reports
@@ -145,12 +223,13 @@ and we keep HTML5. Do not ship a janky native path for a codec win.
 The spike is **complete** when one of these is true:
 **Success path**
- [ ] Transparent WebView confirmed working on a physical device.
+- [x] Transparent WebView confirmed working on a physical device (reported by the maintainer; the config that enables it is now committed in `tauri.android.conf.json`).
- [ ] `experimentalNativeVideo` off → behaviour byte-identical to today.
+- [x] `experimentalNativeVideo` off → behaviour byte-identical to today. Guarded by `adapterSelection.test.ts`, which asserts the flag-off case forces HTML5 even when Rust reports native.
- [ ] `webviewAudio.ts` no longer inspects `navigator.userAgent`; the platform's audio backend is read from Rust.
+- [x] `webviewAudio.ts` no longer inspects `navigator.userAgent`; the platform's audio backend is read from Rust (`player_get_capabilities` → `usesWebviewAudio`).
- [ ] `experimentalNativeVideo` on → video plays via ExoPlayer/MediaCodec, correctly positioned, with working seek, audio-track switch, and subtitle selection through the existing `PlayerAdapter` contract.
+- [x] `experimentalNativeVideo` on → video plays via ExoPlayer, correctly positioned, on a physical device (2026-08-11). The surface reaches the hierarchy and is visible through the transparent WebView — the whole point of the spike.
- [ ] No artefacts on rotation, background/foreground, or mini-player transition.
+- [ ] Seek, audio-track switch and subtitle selection exercised through `NativePlayerAdapter`. Playback is confirmed; these individual controls are not yet each verified on the native path.
- [ ] `adb shell dumpsys media.metrics` (or logcat) confirms a hardware decoder is in use.
+- [ ] No artefacts on rotation, background/foreground, or **mini-player transition** — the last is the one case the fullscreen assumption does not cover, so it is the likeliest place to find a problem.
 - [ ] `adb shell dumpsys media.metrics` (or logcat) confirms a hardware decoder is in use. Plausible but unmeasured — do not claim the MediaCodec win until this is read.
 - [ ] Measured battery/thermal or CPU improvement over the HTML5 path on the same clip.
 **Failure path**
@@ -159,8 +238,15 @@ The spike is **complete** when one of these is true:
 - [ ] `nativeAdapter.ts:11-14` no longer cites tauri#10152.
 Either way:
- [ ] `bun run check`, `bun run test`, `bun run check:boundary` pass.
+- [x] `bun run check` (0 errors), `bun run test` (892 passed), `bun run check:boundary` pass.
- [ ] `cargo fmt` / `cargo clippy` clean; `bun run test:rust` passes.
+- [x] `cargo fmt` / `cargo clippy` clean (no new warnings); `cargo test` passes (603 lib + 7 doc).
 > Note: this environment has no host WebKitGTK dev packages, no Android SDK and
 > no `bun`, so all of the above were run inside the CI builder image
 > (`gitea.tourolle.paris/dtourolle/jellytau-builder:latest`). On Fedora the bind
 > mount needs `:z` for SELinux, and `scripts/build-android.sh` hardcodes
 > `ANDROID_HOME="$HOME/Android/Sdk"`, so the image's SDK at `/opt/android-sdk`
 > must be symlinked there rather than passed by env var.
 ## Testing
@@ -179,7 +265,7 @@ native adapter), write the failing test first.
 ## TRACES
- `createAdapter` → `// TRACES: UR-003, UR-004 | DR-023, DR-024`
+- `createAdapter` → `// TRACES: UR-003, UR-004 | DR-004, DR-150 | UT-149`
 - Adapter-selection tests → `UT-xxx`
 - No new requirement IDs; this spike either satisfies existing IR-004 expectations or documents why it cannot.
@@ -175,8 +175,8 @@ describe("live requirements.md", () => {
    expect(defined.UR).toBe(71);
    expect(defined.IR).toBe(32);
-    expect(defined.DR).toBe(144);
+    expect(defined.DR).toBe(150);
    expect(defined.JA).toBe(35);
-    expect(defined.total).toBe(282);
+    expect(defined.total).toBe(288);
  });
 });
@@ -0,0 +1,111 @@
 #!/bin/bash
 # Stamp the release version into every file that carries it.
 #
 # The git tag is the single source of truth for a release version. The versions
 # committed in package.json / tauri.conf.json / Cargo.toml are a placeholder for
 # dev builds; a tagged build overwrites all of them from the tag so they cannot
 # disagree with each other or with the tag.
 #
 # Usage:
 #   ./scripts/set-version.sh 0.5.0        # explicit
 #   JELLYTAU_VERSION=0.5.0 ./scripts/set-version.sh
 #   ./scripts/set-version.sh              # derive from git describe (dev builds)
 #
 # Accepts the version with or without a leading "v".
 #
 # Why a script and not four sed lines in CI: the version lived in four files and
 # CI only ever rewrote one of them (tauri.conf.json), so a tagged release shipped
 # a matching installer name and mismatched package metadata. Keeping the write in
 # one place is what makes "the tag is authoritative" actually true.
 set -euo pipefail
 cd "$(dirname "$0")/.."
 VERSION="${1:-${JELLYTAU_VERSION:-}}"
 # CI passes "${GITHUB_REF#refs/tags/}" unconditionally, which on an untagged
 # build is still a full ref ("refs/heads/master"). Treat anything that is not a
 # bare version as "no version given" and fall through to git describe, so a
 # branch build gets a sane dev version instead of failing the job.
 case "$VERSION" in
  refs/*) VERSION="" ;;
 esac
 if [ -z "$VERSION" ]; then
  # No explicit version: derive from the most recent tag. Dev builds land on
  # something like 0.5.0 (exact tag) or 0.5.0-3-gabc1234 (ahead of the tag).
  VERSION="$(git describe --tags --always --match 'v*' 2>/dev/null || echo "0.0.0")"
 fi
 # Tags are written v0.5.0; the files carry a bare semver.
 VERSION="${VERSION#v}"
 # Validate before writing anything — a malformed version silently propagated
 # into four files is far worse than a failed script.
 if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'; then
  echo "❌ Not a valid semver: '$VERSION'" >&2
  echo "   Expected MAJOR.MINOR.PATCH with an optional -prerelease/+build suffix." >&2
  exit 1
 fi
 echo "📌 Setting version to $VERSION"
 # --- The three committed manifests -----------------------------------------
 # Anchored to the first "version" key so a dependency's version is never hit.
 # package.json — the top-level "version", which sits in the first few lines.
 perl -0pi -e 's/("version"\s*:\s*)"[^"]*"/$1"'"$VERSION"'"/' package.json
 # tauri.conf.json — likewise; this is the one the bundler reads for installer
 # names, and the one CI used to patch alone.
 perl -0pi -e 's/("version"\s*:\s*)"[^"]*"/$1"'"$VERSION"'"/' src-tauri/tauri.conf.json
 # Cargo.toml — only the [package] version, never a dependency's. Restricted to
 # the first occurrence of a line-anchored `version = "..."`.
 perl -0pi -e 's/^(version\s*=\s*)"[^"]*"/$1"'"$VERSION"'"/m' src-tauri/Cargo.toml
 # Cargo.lock — the jellytau entry. Left alone if the lock has not been generated
 # yet; the next cargo invocation writes it. Cargo would otherwise rewrite the
 # lock mid-build and dirty the tree.
 if [ -f src-tauri/Cargo.lock ]; then
  perl -0pi -e 's/(name = "jellytau"\nversion = )"[^"]*"/$1"'"$VERSION"'"/' src-tauri/Cargo.lock
 fi
 # --- Android versionCode ----------------------------------------------------
 # Only when the generated Android project exists (i.e. after `tauri android
 # init`); on Linux/Windows jobs there is nothing to stamp.
 #
 # `tauri android init` derives a versionCode from the semver (0.0.15 -> 15).
 # That is both tiny and NOT monotonic across our history: earlier local/dev
 # builds shipped versionCode 1000 (from a 0.1.0 config), so a plain 15 is a
 # *downgrade* and Android refuses the update.
 #
 #   code = 1000 + major*10000 + minor*100 + patch
 # e.g. 0.0.14 -> 1014, 0.0.15 -> 1015, 0.1.0 -> 1100, 1.0.0 -> 11000.
 PROPS="src-tauri/gen/android/app/tauri.properties"
 if [ -f "$PROPS" ]; then
  # Strip any -rc1/+build suffix first: it is not numeric, and feeding it to
  # $(( )) would abort the script under `set -e`.
  CORE="${VERSION%%-*}"
  CORE="${CORE%%+*}"
  MAJ=$(echo "$CORE" | cut -d. -f1)
  MIN=$(echo "$CORE" | cut -d. -f2)
  PAT=$(echo "$CORE" | cut -d. -f3)
  : "${MAJ:=0}" "${MIN:=0}" "${PAT:=0}"
  CODE=$(( 1000 + MAJ*10000 + MIN*100 + PAT ))
  echo "   versionCode=$CODE (from $CORE)"
  if grep -q '^tauri.android.versionCode=' "$PROPS"; then
    sed -i "s/^tauri.android.versionCode=.*/tauri.android.versionCode=$CODE/" "$PROPS"
  else
    echo "tauri.android.versionCode=$CODE" >> "$PROPS"
  fi
 fi
 # --- Report -----------------------------------------------------------------
 echo "✅ Version stamped:"
 grep -m1 '"version"' package.json | sed 's/^/   package.json:      /'
 grep -m1 '"version"' src-tauri/tauri.conf.json | sed 's/^/   tauri.conf.json:   /'
 grep -m1 '^version' src-tauri/Cargo.toml | sed 's/^/   Cargo.toml:        /'
 [ -f "$PROPS" ] && grep '^tauri.android.versionCode=' "$PROPS" | sed 's/^/   tauri.properties:  /'
 exit 0
@@ -0,0 +1,169 @@
 /**
 * Guards for scripts/set-version.sh — the release version stamper.
 *
 * TRACES: DR-153 | UT-150
 *
 * These run the real script against a throwaway copy of the manifests, because
 * the failure modes are all in the shell, not in any TS logic: a regex that also
 * matches a dependency's version, arithmetic that aborts on a `-rc1` suffix, or
 * a CI ref reaching the validator verbatim.
 *
 * The versionCode formula matters most. Android refuses an update whose code is
 * lower than the installed one, and builds already in the field shipped code
 * 1000 — so any formula that can emit a smaller number for a *newer* release
 * bricks updates for those users, silently and irreversibly.
 */
 import { describe, expect, it, beforeEach, afterEach } from "vitest";
 import { execFileSync } from "child_process";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
 const script = path.join(repoRoot, "scripts", "set-version.sh");
 let tmp: string;
 /** A minimal repo skeleton: just the files the script rewrites. */
 function seed(dir: string) {
  fs.mkdirSync(path.join(dir, "src-tauri", "gen", "android", "app"), { recursive: true });
  fs.mkdirSync(path.join(dir, "scripts"), { recursive: true });
  fs.copyFileSync(script, path.join(dir, "scripts", "set-version.sh"));
  fs.chmodSync(path.join(dir, "scripts", "set-version.sh"), 0o755);
  fs.writeFileSync(
    path.join(dir, "package.json"),
    JSON.stringify({ name: "jellytau", version: "0.0.1", dependencies: { hls: "1.2.3" } }, null, 2)
  );
  fs.writeFileSync(
    path.join(dir, "src-tauri", "tauri.conf.json"),
    JSON.stringify({ productName: "jellytau", version: "0.0.1" }, null, 2)
  );
  // A dependency carrying its own `version =` is the trap: a greedy regex
  // rewrites it too and the build then resolves the wrong crate.
  fs.writeFileSync(
    path.join(dir, "src-tauri", "Cargo.toml"),
    ['[package]', 'name = "jellytau"', 'version = "0.0.1"', '', '[dependencies]', 'serde = { version = "1.0.100" }', ''].join("\n")
  );
  fs.writeFileSync(
    path.join(dir, "src-tauri", "Cargo.lock"),
    ['[[package]]', 'name = "serde"', 'version = "1.0.100"', '', '[[package]]', 'name = "jellytau"', 'version = "0.0.1"', ''].join("\n")
  );
  fs.writeFileSync(
    path.join(dir, "src-tauri", "gen", "android", "app", "tauri.properties"),
    "tauri.android.versionCode=1\n"
  );
 }
 function run(version: string, dir = tmp) {
  return execFileSync("bash", [path.join(dir, "scripts", "set-version.sh"), version], {
    cwd: dir,
    encoding: "utf-8",
  });
 }
 function read(rel: string): string {
  return fs.readFileSync(path.join(tmp, rel), "utf-8");
 }
 function versionCode(): number {
  const m = read("src-tauri/gen/android/app/tauri.properties").match(
    /^tauri\.android\.versionCode=(\d+)$/m
  );
  return m ? Number(m[1]) : NaN;
 }
 beforeEach(() => {
  tmp = fs.mkdtempSync(path.join(os.tmpdir(), "setversion-"));
  seed(tmp);
 });
 afterEach(() => {
  fs.rmSync(tmp, { recursive: true, force: true });
 });
 describe("set-version.sh", () => {
  it("stamps the version into all four manifests", () => {
    run("0.5.0");
    expect(JSON.parse(read("package.json")).version).toBe("0.5.0");
    expect(JSON.parse(read("src-tauri/tauri.conf.json")).version).toBe("0.5.0");
    expect(read("src-tauri/Cargo.toml")).toContain('version = "0.5.0"');
    expect(read("src-tauri/Cargo.lock")).toMatch(/name = "jellytau"\nversion = "0\.5\.0"/);
  });
  it("accepts a leading v, as git tags are written", () => {
    run("v0.5.0");
    expect(JSON.parse(read("package.json")).version).toBe("0.5.0");
  });
  // The regression that motivates anchoring the patterns.
  it("does not rewrite dependency versions", () => {
    run("0.5.0");
    expect(read("src-tauri/Cargo.toml")).toContain('serde = { version = "1.0.100" }');
    expect(read("src-tauri/Cargo.lock")).toMatch(/name = "serde"\nversion = "1\.0\.100"/);
    expect(JSON.parse(read("package.json")).dependencies.hls).toBe("1.2.3");
  });
  describe("Android versionCode", () => {
    // Codes below 1000 are already in the field; a newer release must never
    // produce a smaller number than an older one.
    it("clears the 1000 floor shipped by earlier builds", () => {
      run("0.0.1");
      expect(versionCode()).toBeGreaterThan(1000);
    });
    it("uses 1000 + major*10000 + minor*100 + patch", () => {
      const cases: Array<[string, number]> = [
        ["0.0.14", 1014],
        ["0.0.15", 1015],
        ["0.1.0", 1100],
        ["0.4.8", 1408],
        ["0.5.0", 1500],
        ["1.0.0", 11000],
      ];
      for (const [version, code] of cases) {
        seed(tmp);
        run(version);
        expect(versionCode(), `versionCode for ${version}`).toBe(code);
      }
    });
    it("increases monotonically across an upgrade sequence", () => {
      const ordered = ["0.0.14", "0.0.15", "0.1.0", "0.4.8", "0.5.0", "1.0.0"];
      const codes = ordered.map((v) => {
        seed(tmp);
        run(v);
        return versionCode();
      });
      const sorted = [...codes].sort((a, b) => a - b);
      expect(codes).toEqual(sorted);
      expect(new Set(codes).size).toBe(codes.length);
    });
    // `$(( 0-rc1 ))` aborts the script under `set -e`, so the suffix has to be
    // stripped before the arithmetic.
    it("derives the code from the numeric core of a prerelease", () => {
      run("0.6.0-rc1");
      expect(versionCode()).toBe(1600);
      expect(JSON.parse(read("package.json")).version).toBe("0.6.0-rc1");
    });
  });
  describe("input validation", () => {
    it("rejects a malformed version without writing anything", () => {
      expect(() => run("not-a-version")).toThrow();
      // The manifests must be untouched, not half-written.
      expect(JSON.parse(read("package.json")).version).toBe("0.0.1");
      expect(JSON.parse(read("src-tauri/tauri.conf.json")).version).toBe("0.0.1");
    });
    // CI passes "${GITHUB_REF#refs/tags/}" unconditionally; on a branch build
    // that is still a full ref, and must not fail the job.
    it("falls back to a dev version when handed a non-tag ref", () => {
      const out = run("refs/heads/master");
      expect(out).not.toMatch(/refs\/heads/);
      expect(JSON.parse(read("package.json")).version).not.toBe("0.0.1");
    });
  });
 });
@@ -118,4 +118,26 @@ if [ -d "$RES_SRC" ]; then
          "$RES_DST"/drawable*/ic_launcher_background.xml
 fi
 # Gradle wrapper distribution. `tauri android init` regenerates the wrapper
 # pointing at services.gradle.org, so each build downloads ~130MB of Gradle —
 # slow, and a hard failure when the CDN drops the connection mid-transfer
 # ("Unexpected end of file from server"), which is what broke the release APK
 # job. The builder image ships the matching distribution under /opt/gradle/dist,
 # so when it's present repoint the wrapper at that local zip and build offline.
 # Outside the image (dev machines) the properties file is left untouched and the
 # wrapper downloads as usual.
 WRAPPER_PROPS="$PROJECT_ROOT/src-tauri/gen/android/gradle/wrapper/gradle-wrapper.properties"
 if [ -f "$WRAPPER_PROPS" ]; then
    WANTED_VERSION="$(sed -n 's#.*/gradle-\([0-9.]*\)-\(bin\|all\)\.zip.*#\1#p' "$WRAPPER_PROPS")"
    LOCAL_DIST="/opt/gradle/dist/gradle-${WANTED_VERSION}-bin.zip"
    if [ -n "$WANTED_VERSION" ] && [ -f "$LOCAL_DIST" ]; then
        # distributionUrl is a java.util.Properties value: ':' must stay escaped.
        sed -i "s#^distributionUrl=.*#distributionUrl=file\\\\:///opt/gradle/dist/gradle-${WANTED_VERSION}-bin.zip#" \
            "$WRAPPER_PROPS"
        echo "  Gradle wrapper -> local distribution ($WANTED_VERSION, offline)"
    elif [ -n "$WANTED_VERSION" ]; then
        echo "  Gradle wrapper: $WANTED_VERSION not in image, will download"
    fi
 fi
 echo "✓ Android sources synced successfully"
@@ -64,6 +64,20 @@ class MainActivity : TauriActivity() {
    // so on devices with a tall opaque 3-button bar. (UR-066)
    WindowInsetsBridge.install(this)
    // Hand the player an Activity reference so it can attach its video
    // SurfaceView to the content view behind the WebView.
    //
    // Without this, JellyTauPlayer.currentActivity stays null forever and
    // autoAttachSurface() logs "Cannot attach surface - no Activity reference"
    // and returns — so the SurfaceView is created, wired to ExoPlayer, and then
    // never added to the view hierarchy. Native video decoded to a surface that
    // was never on screen. setActivity() stores into a companion-object
    // WeakReference, so calling it here (before Rust initializes the player over
    // JNI) is safe and is the case it was written for.
    //
    // TRACES: UR-003, UR-041 | DR-151
    com.dtourolle.jellytau.player.JellyTauPlayer.setActivity(this)
    // Configure WebView for media playback after Tauri initialization
    handler.postDelayed({
      configureWebViewForMedia()
@@ -271,6 +285,46 @@ class MainActivity : TauriActivity() {
      }, "AndroidNetworkType")
      android.util.Log.d("MainActivity", "JavaScript interface 'AndroidNetworkType' added")
      // Native video compositing: let the frontend make the WebView transparent
      // so the ExoPlayer SurfaceView behind it is visible (UR-003, UR-004).
      //
      // Toggled rather than set once because a transparent WebView is only
      // correct while a native video is on screen — every other screen needs its
      // opaque background, and leaving the window transparent shows the
      // launcher/wallpaper through the app.
      //
      // The CSS in app.css clears the *web* layer's backgrounds; this clears the
      // WebView widget's own background, which CSS cannot reach. Both are
      // required — an opaque WebView hides the surface no matter what the page
      // paints.
      //
      // TRACES: UR-003, UR-004 | DR-150
      webView.addJavascriptInterface(object : Any() {
        /** Make the WebView background transparent (true) or opaque (false). */
        @JavascriptInterface
        fun setTransparent(transparent: Boolean) {
          handler.post {
            val color = if (transparent) {
              android.graphics.Color.TRANSPARENT
            } else {
              android.graphics.Color.BLACK
            }
            mediaWebView?.setBackgroundColor(color)
            // The WebView's window/surface must also stop painting opaque, or a
            // hardware-accelerated WebView still composites its own background.
            window.setBackgroundDrawable(
              android.graphics.drawable.ColorDrawable(color)
            )
            android.util.Log.d("MainActivity", "WebView transparent = $transparent")
          }
        }
        /** Whether native-video compositing is available on this platform. */
        @JavascriptInterface
        fun isSupported(): Boolean = true
      }, "AndroidVideoSurface")
      android.util.Log.d("MainActivity", "JavaScript interface 'AndroidVideoSurface' added")
      // Window insets (safe areas). The push path above races the page load, so
      // the frontend pulls the current values on mount through this bridge.
      webView.addJavascriptInterface(WindowInsetsBridge.jsInterface(), "AndroidInsets")
@@ -1003,6 +1003,16 @@ pub async fn player_stop(
                .clone()
        };
        client.send_session_command(session_id, "Stop").await?;
        // Stopping the remote session ends the cast, so the manager returns to
        // Idle — same as a local stop. This is also what hands OS volume control
        // back to this device: set_mode releases the Android remote volume
        // provider on any exit from remote mode. Without it the mode stayed
        // Remote and the system volume slider remained stuck on the remote
        // session with no way back to the local speaker.
        playback_mode
            .0
            .set_mode(crate::playback_mode::PlaybackMode::Idle);
    } else {
        // Local playback
        let controller = player.0.lock().await;
@@ -1654,6 +1664,43 @@ pub async fn player_get_queue(
    Ok(get_queue_status(&controller))
 }
 /// 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
 #[derive(specta::Type, Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct 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.
    pub uses_webview_audio: bool,
    /// 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.
    pub supports_native_video: bool,
 }
 /// Report this platform's playback capabilities to the frontend.
 ///
 /// TRACES: UR-003, UR-005 | DR-004, DR-023, DR-024
 #[tauri::command]
 #[specta::specta]
 pub async fn player_get_capabilities() -> Result<PlaybackCapabilities, String> {
    // Mirrors the cfg gates the backends themselves are built under.
    let native_audio = cfg!(any(target_os = "android", target_os = "linux"));
    Ok(PlaybackCapabilities {
        uses_webview_audio: !native_audio,
        supports_native_video: cfg!(target_os = "android"),
    })
 }
 pub(super) fn get_player_status(controller: &PlayerController) -> PlayerStatus {
    // Determine backend at compile time based on platform
    let (backend, use_html5_element) = if cfg!(target_os = "android") {
@@ -712,9 +712,19 @@ pub async fn repository_report_playback_progress(
 }
 /// Report playback stopped
 ///
 /// A stop-report that cannot reach the server is queued rather than dropped:
 /// this is the position the resume point is built from, and losing it is
 /// exactly the "it forgot where I was" the sync queue exists to prevent. The
 /// drain (DR-131) pushes it on the next reconnect. Queueing is best-effort —
 /// failing the command because the *queue* write failed would tell the caller
 /// the report was lost when the local position was already saved.
 ///
 /// TRACES: UR-025 | DR-154 | UT-151
 #[tauri::command]
 #[specta::specta]
 pub async fn repository_report_playback_stopped(
    db: State<'_, crate::commands::storage::DatabaseWrapper>,
    manager: State<'_, RepositoryManagerWrapper>,
    handle: String,
    item_id: String,
@@ -723,10 +733,39 @@ pub async fn repository_report_playback_stopped(
    // Milliseconds across the boundary; the Jellyfin API wants ticks.
    let position_ticks = position_ms * 10_000;
    let repo = manager.0.get(&handle).ok_or("Repository not found")?;
-    repo.as_ref()
+
    let result = repo
        .as_ref()
        .report_playback_stopped(&item_id, position_ticks)
        .await;
    if let Err(e) = &result {
        let db_service = {
            let database = db.0.lock().map_err(|err| err.to_string())?;
            Arc::new(database.service())
        };
        let user_id = repo.user_id().to_string();
        if let Err(queue_err) = crate::commands::sync_drain::enqueue_playback_stopped(
            &db_service,
            &user_id,
            &item_id,
            position_ticks,
        )
        .await
-        .map_err(|e| format!("{:?}", e))
+        {
            warn!(
                "[Repository] Stop-report for {} failed ({:?}) and could not be queued: {}",
                item_id, e, queue_err
            );
        } else {
            debug!(
                "[Repository] Stop-report for {} failed ({:?}); queued for the next reconnect",
                item_id, e
            );
        }
    }
    result.map_err(|e| format!("{:?}", e))
 }
 /// Get image URL for an item
@@ -355,6 +355,65 @@ async fn mark_failed(
    Ok(())
 }
 /// Queue a watch position that could not be reported to the server.
 ///
 /// The stop-report path pushed straight to the server and, on failure, logged
 /// and dropped the position — so closing a video while the server was
 /// unreachable lost the resume point outright, even though the queue and its
 /// drain (DR-131) were built and running. This is the missing producer.
 ///
 /// The pending row for an item is *replaced* rather than appended to. Progress
 /// is reported every 10s, so a server that stays down would otherwise grow one
 /// row per tick, all of them superseded by the newest — the unbounded queue
 /// DR-131 exists to prevent. Only `pending`/`failed` rows are superseded:
 /// an `abandoned` row has been given up on and must not be revived, and a
 /// `completed` one is history.
 ///
 /// TRACES: UR-025 | DR-154 | UT-151
 pub async fn enqueue_playback_stopped(
    db: &Arc<RusqliteService>,
    user_id: &str,
    item_id: &str,
    position_ticks: i64,
 ) -> Result<(), String> {
    let payload = format!(r#"{{"position_ticks": {}}}"#, position_ticks);
    // Supersede an already-queued position for this item, keeping its place in
    // the queue order (created_at) so a later item cannot overtake it.
    let updated = db
        .execute(Query::with_params(
            "UPDATE sync_queue \
             SET payload = ?, status = 'pending', error_message = NULL \
             WHERE user_id = ? AND item_id = ? AND operation = 'report_playback_stopped' \
               AND status IN ('pending', 'failed')",
            vec![
                QueryParam::String(payload.clone()),
                QueryParam::String(user_id.to_string()),
                QueryParam::String(item_id.to_string()),
            ],
        ))
        .await?;
    if updated == 0 {
        db.execute(Query::with_params(
            "INSERT INTO sync_queue (user_id, operation, item_id, payload, status, created_at) \
             VALUES (?, 'report_playback_stopped', ?, ?, 'pending', CURRENT_TIMESTAMP)",
            vec![
                QueryParam::String(user_id.to_string()),
                QueryParam::String(item_id.to_string()),
                QueryParam::String(payload),
            ],
        ))
        .await?;
    }
    debug!(
        "[SyncQueue] Queued unreported stop for {} at {} ticks",
        item_id, position_ticks
    );
    Ok(())
 }
 /// Drain on every offline→online transition.
 ///
 /// TRACES: UR-025 | DR-131
@@ -781,6 +840,143 @@ mod tests {
        assert_eq!(row_state(&db, "theirs").await.0, "pending");
    }
    /// The bug DR-154 fixes: a stop-report that could not reach the server was
    /// logged and dropped, so the watch position was lost outright. It must
    /// land in the queue the drain already knows how to push.
    ///
    /// TRACES: UR-025 | DR-154 | UT-151
    #[tokio::test]
    async fn test_failed_stop_report_is_queued_rather_than_dropped() {
        let db = test_db();
        enqueue_playback_stopped(&db, "u1", "ep1", 5_000_000_000)
            .await
            .unwrap();
        // The very drain that already exists must be able to push it.
        let sink = RecordingSink::new();
        let report = drain_sync_queue(&db, &sink, "u1").await.unwrap();
        assert_eq!(
            sink.calls(),
            vec![QueuedOp::PlaybackStopped {
                item_id: "ep1".to_string(),
                position_ticks: 5_000_000_000,
            }]
        );
        assert_eq!(report.pushed, 1);
        assert_eq!(report.remaining, 0);
    }
    /// Progress is reported every 10s, and a server that stays unreachable
    /// would otherwise add a row per tick — an unbounded queue of positions
    /// that are all superseded by the newest one. The pending row for an item
    /// is replaced in place, so the queue holds the latest position only.
    ///
    /// TRACES: UR-025 | DR-154 | UT-151
    #[tokio::test]
    async fn test_requeueing_the_same_item_supersedes_the_earlier_position() {
        let db = test_db();
        enqueue_playback_stopped(&db, "u1", "ep1", 1_000)
            .await
            .unwrap();
        enqueue_playback_stopped(&db, "u1", "ep1", 2_000)
            .await
            .unwrap();
        enqueue_playback_stopped(&db, "u1", "ep1", 3_000)
            .await
            .unwrap();
        let sink = RecordingSink::new();
        drain_sync_queue(&db, &sink, "u1").await.unwrap();
        // One row, carrying the newest position — not three.
        assert_eq!(
            sink.calls(),
            vec![QueuedOp::PlaybackStopped {
                item_id: "ep1".to_string(),
                position_ticks: 3_000,
            }]
        );
    }
    /// Distinct items must not collide — superseding is per item, not global.
    ///
    /// TRACES: UR-025 | DR-154 | UT-151
    #[tokio::test]
    async fn test_requeueing_keeps_positions_for_different_items_apart() {
        let db = test_db();
        enqueue_playback_stopped(&db, "u1", "ep1", 1_000)
            .await
            .unwrap();
        enqueue_playback_stopped(&db, "u1", "ep2", 2_000)
            .await
            .unwrap();
        let sink = RecordingSink::new();
        drain_sync_queue(&db, &sink, "u1").await.unwrap();
        let mut calls = sink.calls();
        calls.sort_by_key(|op| match op {
            QueuedOp::PlaybackStopped { item_id, .. } => item_id.clone(),
            _ => String::new(),
        });
        assert_eq!(
            calls,
            vec![
                QueuedOp::PlaybackStopped {
                    item_id: "ep1".to_string(),
                    position_ticks: 1_000,
                },
                QueuedOp::PlaybackStopped {
                    item_id: "ep2".to_string(),
                    position_ticks: 2_000,
                },
            ]
        );
    }
    /// A row already abandoned (DR-131 gave up on it) must not be resurrected
    /// by a later report — that would restore the queue-that-only-grows this
    /// whole area exists to prevent. The new report is queued as its own row.
    ///
    /// TRACES: UR-025 | DR-154 | UT-151
    #[tokio::test]
    async fn test_requeueing_does_not_revive_an_abandoned_row() {
        let db = test_db();
        seed(
            &db,
            &[(
                "u1",
                "report_playback_stopped",
                "ep1",
                Some(r#"{"position_ticks": 111}"#),
                "abandoned",
                MAX_SYNC_ATTEMPTS,
                "2026-08-01T10:00:00Z",
            )],
        )
        .await;
        enqueue_playback_stopped(&db, "u1", "ep1", 999)
            .await
            .unwrap();
        let sink = RecordingSink::new();
        drain_sync_queue(&db, &sink, "u1").await.unwrap();
        // Only the fresh row is pushed; the abandoned one stays abandoned.
        assert_eq!(
            sink.calls(),
            vec![QueuedOp::PlaybackStopped {
                item_id: "ep1".to_string(),
                position_ticks: 999,
            }]
        );
    }
    /// Nothing queued means no server calls at all — a reconnect must not
    /// generate traffic just because it happened.
    ///
@@ -123,6 +123,7 @@ use commands::{
    player_get_audio_settings,
    player_get_autoplay_settings,
    player_get_cache_config,
    player_get_capabilities,
    player_get_eq_presets,
    player_get_queue,
    // Session management commands
@@ -682,6 +683,7 @@ fn specta_builder() -> Builder<tauri::Wry> {
            player_cycle_repeat,
            player_get_status,
            player_get_queue,
            player_get_capabilities,
            player_add_to_queue,
            player_add_track_by_id,
            player_add_tracks_by_ids,
@@ -27,6 +27,10 @@ const TICKS_PER_SECOND: f64 = 10_000_000.0;
 /// send a resume position, so a fresh track casts from 0 rather than ~0.
 const RESUME_THRESHOLD_SECONDS: f64 = 0.5;
 /// Volume level (0-100) the remote volume slider starts at. The real level is
 /// corrected by the session poller once the remote session reports its volume.
 const DEFAULT_REMOTE_VOLUME: i32 = 50;
 /// Convert a live playback position (seconds) into the `StartPositionTicks` to
 /// hand to a remote session, or `None` if we're effectively at the start.
 ///
@@ -42,6 +46,50 @@ fn start_position_ticks_from_seconds(position_seconds: f64) -> Option<i64> {
    }
 }
 /// Platform hook for attaching/detaching the OS remote-volume control.
 ///
 /// On Android, entering remote mode hands the `MediaSession` a
 /// `VolumeProviderCompat` so hardware volume buttons and the system slider drive
 /// the *remote* session; leaving remote mode must hand it back to the local
 /// media stream. Behind a trait so the routing rule (see
 /// [`PlaybackModeManager::set_mode`]) is unit-testable off-device — the real
 /// implementation is JNI and only exists on Android.
 pub trait RemoteVolumeControl: Send + Sync {
    /// Attach remote-volume control (and, on Android, start the playback service).
    fn enable(&self, initial_volume: i32);
    /// Return volume control to the local device speaker.
    fn disable(&self);
 }
 /// Production hook: forwards to the Android JNI bridge; no-op elsewhere.
 struct PlatformRemoteVolumeControl;
 impl RemoteVolumeControl for PlatformRemoteVolumeControl {
    #[allow(unused_variables)]
    fn enable(&self, initial_volume: i32) {
        #[cfg(target_os = "android")]
        {
            if let Err(e) = crate::player::enable_remote_volume(initial_volume) {
                log::warn!(
                    "[PlaybackMode] Failed to enable remote volume/service: {}",
                    e
                );
                // Non-fatal - continue; the next poll tick will retry metadata.
            }
        }
    }
    fn disable(&self) {
        #[cfg(target_os = "android")]
        {
            if let Err(e) = crate::player::disable_remote_volume() {
                log::warn!("[PlaybackMode] Failed to disable remote volume: {}", e);
                // Non-fatal - the mode change itself has already happened.
            }
        }
    }
 }
 /// Manages playback mode transfers between local and remote sessions
 pub struct PlaybackModeManager {
    jellyfin_client: Arc<Mutex<Option<JellyfinClient>>>,
@@ -51,6 +99,8 @@ pub struct PlaybackModeManager {
    /// Optional emitter used to notify the frontend when the mode changes, so its
    /// mirror store stays in sync with this authoritative one. `None` in tests.
    event_emitter: Arc<Mutex<Option<Arc<dyn PlayerEventEmitter>>>>,
    /// Platform hook for OS-level remote volume routing (swapped in tests).
    remote_volume: Arc<dyn RemoteVolumeControl>,
 }
 impl PlaybackModeManager {
@@ -65,6 +115,24 @@ impl PlaybackModeManager {
            current_mode: Arc::new(RwLock::new(PlaybackMode::Idle)),
            is_transferring: Arc::new(AtomicBool::new(false)),
            event_emitter: Arc::new(Mutex::new(None)),
            remote_volume: Arc::new(PlatformRemoteVolumeControl),
        }
    }
    /// Construct with a custom remote-volume hook (tests).
    #[cfg(test)]
    fn with_remote_volume(
        jellyfin_client: Arc<Mutex<Option<JellyfinClient>>>,
        player_controller: Arc<TokioMutex<PlayerController>>,
        remote_volume: Arc<dyn RemoteVolumeControl>,
    ) -> Self {
        Self {
            jellyfin_client,
            player_controller,
            current_mode: Arc::new(RwLock::new(PlaybackMode::Idle)),
            is_transferring: Arc::new(AtomicBool::new(false)),
            event_emitter: Arc::new(Mutex::new(None)),
            remote_volume,
        }
    }
@@ -86,19 +154,39 @@ impl PlaybackModeManager {
    /// the frontend's mirror store reconciles to this authoritative value. The
    /// write lock is released before emitting to avoid holding it across the
    /// emitter call.
    ///
    /// Also owns **OS volume routing**, which is derived from the transition
    /// rather than from each call site: entering remote mode attaches the remote
    /// volume control, and *any* exit from remote mode hands it back to the local
    /// speaker. Doing this per-call-site is what caused the bug where stopping a
    /// remote session (`player_stop` → Idle) left Android stuck on the remote
    /// volume slider — only the transfer-to-local path tore it down.
    ///
    /// TRACES: UR-010 | DR-059, IR-021
    pub fn set_mode(&self, mode: PlaybackMode) {
        log::info!("[PlaybackMode] Setting mode to: {:?}", mode);
-        let changed = {
+        let (changed, was_remote) = {
            let mut current = self.current_mode.write_safe();
            let changed = *current != mode;
            let was_remote = matches!(*current, PlaybackMode::Remote { .. });
            *current = mode.clone();
-            changed
+            (changed, was_remote)
        };
        if !changed {
            return;
        }
        // Volume routing follows the transition. Note remote->remote (switching
        // target session) re-arms rather than releasing control.
        let is_remote = matches!(mode, PlaybackMode::Remote { .. });
        if is_remote {
            self.remote_volume.enable(DEFAULT_REMOTE_VOLUME);
        } else if was_remote {
            log::info!("[PlaybackMode] Leaving remote mode - restoring local volume control");
            self.remote_volume.disable();
        }
        let (mode_str, session_id) = match &mode {
            PlaybackMode::Local => ("local".to_string(), None),
            PlaybackMode::Idle => ("idle".to_string(), None),
@@ -122,18 +210,13 @@ impl PlaybackModeManager {
    /// Both symptoms share this one cause, so this must not be skipped on any
    /// remote-entry path (notably the empty-queue early return in
    /// `transfer_to_remote_inner`). No-op / non-Android builds do nothing.
-    #[allow(unused_variables)]
+    ///
    /// [`set_mode`](Self::set_mode) already arms this on entry into remote mode;
    /// calling it again is harmless (the service start is idempotent) and keeps
    /// the guarantee when the mode was already remote, which `set_mode` skips as
    /// a no-op transition.
    fn enable_remote_control(&self) {
-        #[cfg(target_os = "android")]
+        self.remote_volume.enable(DEFAULT_REMOTE_VOLUME);
        {
            if let Err(e) = crate::player::enable_remote_volume(50) {
                log::warn!(
                    "[PlaybackMode] Failed to enable remote volume/service: {}",
                    e
                );
                // Non-fatal - continue; the next poll tick will retry metadata.
            }
        }
    }
    /// Check if currently transferring
@@ -766,18 +849,10 @@ impl PlaybackModeManager {
        // This will be improved in Phase 3 when repository is migrated to Rust.
        log::debug!("[PlaybackMode] Cannot load media item in Rust yet - frontend handled it");
-        // Update mode to local
+        // Update mode to local. This also returns volume control to the local
        // device speaker — set_mode owns that for every exit from remote mode.
        self.set_mode(PlaybackMode::Local);
        // Disable remote volume control on Android (return to system volume)
        #[cfg(target_os = "android")]
        {
            if let Err(e) = crate::player::disable_remote_volume() {
                log::warn!("[PlaybackMode] Failed to disable remote volume: {}", e);
                // Non-fatal - continue with transfer
            }
        }
        log::info!("[PlaybackMode] Successfully transferred to local");
        Ok(())
    }
@@ -893,6 +968,118 @@ mod tests {
        }
    }
    /// Records enable/disable calls so tests can assert volume routing.
    struct RecordingVolumeControl {
        calls: Mutex<Vec<&'static str>>,
    }
    impl RemoteVolumeControl for RecordingVolumeControl {
        fn enable(&self, _initial_volume: i32) {
            self.calls.lock().unwrap().push("enable");
        }
        fn disable(&self) {
            self.calls.lock().unwrap().push("disable");
        }
    }
    fn manager_with_volume_control() -> (PlaybackModeManager, Arc<RecordingVolumeControl>) {
        let volume = Arc::new(RecordingVolumeControl {
            calls: Mutex::new(Vec::new()),
        });
        let manager = PlaybackModeManager::with_remote_volume(
            Arc::new(Mutex::new(None)),
            Arc::new(TokioMutex::new(crate::player::PlayerController::default())),
            volume.clone(),
        );
        (manager, volume)
    }
    /// Leaving remote mode must hand volume control back to the local device.
    ///
    /// Stopping a remote session (`player_stop`) drives the manager
    /// Remote -> Idle without going through `transfer_to_local`. Before this was
    /// centralised in `set_mode`, only the transfer path tore the Android
    /// `VolumeProviderCompat` down, so a plain stop left the system stuck on the
    /// remote volume slider with no way back to the phone speaker.
    ///
    /// @req-test: UR-010 - Control playback of Jellyfin remote sessions
    #[test]
    fn test_leaving_remote_mode_restores_local_volume() {
        let (manager, volume) = manager_with_volume_control();
        manager.set_mode(PlaybackMode::Remote {
            session_id: "sess-1".to_string(),
        });
        // The stop path: remote -> idle, no transfer involved.
        manager.set_mode(PlaybackMode::Idle);
        assert_eq!(
            *volume.calls.lock().unwrap(),
            vec!["enable", "disable"],
            "remote->idle must return volume control to the local speaker"
        );
    }
    /// The same must hold for remote -> local (transfer back to this device).
    ///
    /// @req-test: UR-010 - Control playback of Jellyfin remote sessions
    #[test]
    fn test_remote_to_local_restores_local_volume() {
        let (manager, volume) = manager_with_volume_control();
        manager.set_mode(PlaybackMode::Remote {
            session_id: "sess-1".to_string(),
        });
        manager.set_mode(PlaybackMode::Local);
        assert_eq!(
            *volume.calls.lock().unwrap(),
            vec!["enable", "disable"],
            "remote->local must return volume control to the local speaker"
        );
    }
    /// Volume routing must not be touched by transitions that never involve
    /// remote mode — an idle->local start would otherwise issue a pointless
    /// `setPlaybackToLocal` on every playback start.
    ///
    /// @req-test: UR-010 - Control playback of Jellyfin remote sessions
    #[test]
    fn test_non_remote_transitions_leave_volume_routing_alone() {
        let (manager, volume) = manager_with_volume_control();
        manager.set_mode(PlaybackMode::Local);
        manager.set_mode(PlaybackMode::Idle);
        manager.set_mode(PlaybackMode::Local);
        assert!(
            volume.calls.lock().unwrap().is_empty(),
            "local/idle transitions must not touch remote volume routing"
        );
    }
    /// Switching directly between two remote sessions stays remote: control must
    /// remain attached (re-armed for the new session), never handed back local.
    ///
    /// @req-test: UR-010 - Control playback of Jellyfin remote sessions
    #[test]
    fn test_remote_to_remote_keeps_remote_volume() {
        let (manager, volume) = manager_with_volume_control();
        manager.set_mode(PlaybackMode::Remote {
            session_id: "sess-1".to_string(),
        });
        manager.set_mode(PlaybackMode::Remote {
            session_id: "sess-2".to_string(),
        });
        assert_eq!(
            *volume.calls.lock().unwrap(),
            vec!["enable", "enable"],
            "remote->remote re-arms control without releasing it to local"
        );
    }
    /// Setting the same mode twice must not re-emit — the frontend reconciler
    /// (and the event channel) shouldn't be spammed on no-op transitions.
    #[test]
@@ -319,6 +319,49 @@ impl HybridRepository {
        }
    }
    /// [`Self::parallel_race`], plus a callback fired on the fast path so the
    /// caller can refresh the cache in the background.
    ///
    /// A plain cache hit answers from data that may be arbitrarily old, which
    /// is right for the *response* and wrong for what it leaves behind: per-user
    /// state (watch positions, favourites) only reaches the local tables when a
    /// server result is cached, so a surface that always hits cache never learns
    /// what another device did. `get_items` had a bespoke version of this; this
    /// is the same idea, reusable.
    ///
    /// The callback runs only on a cache hit — on a miss the server result is
    /// already being fetched and cached by the normal path.
    ///
    /// TRACES: UR-002, UR-025 | DR-155
    async fn race_with_refresh<T, F1, F2, R>(
        &self,
        cache_future: F1,
        server_future: F2,
        on_cache_hit: R,
    ) -> Result<T, RepoError>
    where
        T: MeaningfulContent + Clone + Send + 'static,
        F1: std::future::Future<Output = Result<T, RepoError>> + Send,
        F2: std::future::Future<Output = Result<T, RepoError>> + Send,
        R: FnOnce(),
    {
        let cache_result = cache_future.await;
        if let Ok(data) = &cache_result {
            if data.has_content() {
                debug!("[HybridRepo] Cache hit, returning immediately (refreshing in background)");
                on_cache_hit();
                return Ok(data.clone());
            }
        }
        debug!("[HybridRepo] Cache miss, querying server");
        match server_future.await {
            Ok(data) => Ok(data),
            Err(e) => cache_result.or(Err(e)),
        }
    }
    /// Simple timeout wrapper for cache queries (100ms timeout)
    ///
    /// @req: DR-013 - Repository pattern (cache-first with timeout)
@@ -489,6 +532,21 @@ impl MediaRepository for HybridRepository {
        }
    }
    /// A single item, cache-first — and, on a cache hit, refreshed in the
    /// background so the stored copy keeps up with the server.
    ///
    /// The background refresh is what carries per-user state home: caching an
    /// item runs `mirror_user_data`, which is the only path by which a watch
    /// position set on another device reaches the local `user_data` row the
    /// resume check reads. Without it a cache hit returned this device's own
    /// stale position forever and cross-device resume silently did nothing —
    /// `get_items` already refreshes this way, so browsing a season worked
    /// while opening the episode directly did not.
    ///
    /// The refreshed value lands for the *next* read rather than this one: the
    /// point of the cache-first race is to answer immediately.
    ///
    /// TRACES: UR-025, UR-002 | DR-155 | UT-152
    async fn get_item(&self, item_id: &str) -> Result<MediaItem, RepoError> {
        let offline = Arc::clone(&self.offline);
        let online = Arc::clone(&self.online);
@@ -497,9 +555,32 @@ impl MediaRepository for HybridRepository {
        let cache_future = self.cache_with_timeout(async move { offline.get_item(&item_id).await });
        let online_for_refresh = Arc::clone(&self.online);
        let offline_for_save = Arc::clone(&self.offline);
        let refresh_id = item_id_clone.clone();
        let on_cache_hit = move || {
            tokio::spawn(async move {
                match online_for_refresh.get_item(&refresh_id).await {
                    Ok(fresh) => {
                        // `save_to_cache` files the row under a parent; the item's
                        // own parent keeps it where a later listing expects it.
                        let parent = fresh
                            .parent_id
                            .clone()
                            .unwrap_or_else(|| "item".to_string());
                        if let Err(e) = offline_for_save.save_to_cache(&parent, &[fresh]).await {
                            debug!("[HybridRepo] Background item refresh failed: {:?}", e);
                        }
                    }
                    Err(e) => debug!("[HybridRepo] Background item refresh unavailable: {:?}", e),
                }
            });
        };
        let server_future = async move { online.get_item(&item_id_clone).await };
-        self.parallel_race(cache_future, server_future).await
+        self.race_with_refresh(cache_future, server_future, on_cache_hit)
            .await
    }
    async fn get_latest_items(
@@ -665,40 +665,63 @@ impl OfflineRepository {
    }
    /// Mirror the server's per-user state for an item into the local
-    /// `user_data` table, so favourites marked on any other client are visible
+    /// `user_data` table, so favourites marked — and positions watched — on any
-    /// here — including offline, where the local table is the only source.
+    /// other client are visible here, including offline, where the local table
    /// is the only source.
    ///
    /// The `WHERE user_data.pending_sync = 0` on the conflict clause is the
-    /// conflict rule: a toggle made while the server was unreachable is still
+    /// conflict rule: a change made while the server was unreachable is still
    /// waiting to be pushed, and must not be clobbered by the stale value the
-    /// server is still reporting. Rows carrying no favourite state are skipped
+    /// server is still reporting. For a position that means it is never pulled
-    /// entirely rather than written as `0`, which would fabricate an
+    /// *backwards* by a server that has not yet heard where we got to.
    /// "unfavourited" record from an endpoint that simply omits `UserData`.
    ///
-    /// TRACES: UR-069 | DR-114 | UT-102
+    /// Each field is mirrored only when the server actually reported it —
    /// `COALESCE(excluded.x, user_data.x)` keeps the stored value for anything
    /// absent, and a row with neither field is skipped outright rather than
    /// written as zeroes, which would fabricate an "unfavourited, unwatched"
    /// record from an endpoint that simply omits `UserData`.
    ///
    /// The position half is what makes cross-device resume work: the resume
    /// check reads this table alone, so before it was mirrored an item watched
    /// elsewhere resumed from whatever *this* device last saw, or not at all.
    ///
    /// TRACES: UR-025, UR-069 | DR-114, DR-155 | UT-102, UT-152
    async fn mirror_user_data(&self, item: &MediaItem, now: &str) -> Result<(), RepoError> {
-        let Some(is_favorite) = item.user_data.as_ref().and_then(|ud| ud.is_favorite) else {
+        let user_data = item.user_data.as_ref();
        let is_favorite = user_data.and_then(|ud| ud.is_favorite);
        let position_ticks = user_data.and_then(|ud| ud.playback_position_ticks);
        // Nothing the server actually told us about — do not invent a row.
        if is_favorite.is_none() && position_ticks.is_none() {
            return Ok(());
-        };
+        }
        let query = Query::with_params(
-            "INSERT INTO user_data (user_id, item_id, is_favorite, synced_at, pending_sync)
+            "INSERT INTO user_data
-             VALUES (?1, ?2, ?3, ?4, 0)
+                (user_id, item_id, is_favorite, playback_position_ticks, synced_at, pending_sync)
             VALUES (?1, ?2, ?3, ?4, ?5, 0)
             ON CONFLICT(user_id, item_id) DO UPDATE SET
-                is_favorite = excluded.is_favorite,
+                is_favorite = COALESCE(excluded.is_favorite, user_data.is_favorite),
                playback_position_ticks = COALESCE(
                    excluded.playback_position_ticks, user_data.playback_position_ticks),
                synced_at = excluded.synced_at
             WHERE user_data.pending_sync = 0",
            vec![
                QueryParam::String(self.user_id.clone()),
                QueryParam::String(item.id.clone()),
-                QueryParam::Int(if is_favorite { 1 } else { 0 }),
+                is_favorite
                    .map(|f| QueryParam::Int(if f { 1 } else { 0 }))
                    .unwrap_or(QueryParam::Null),
                position_ticks
                    .map(QueryParam::Int64)
                    .unwrap_or(QueryParam::Null),
                QueryParam::String(now.to_string()),
            ],
        );
-        // A missing item row (FK) is not fatal here — the favourite mirror is
+        // A missing item row (FK) is not fatal here — the mirror is best-effort
-        // best-effort metadata, and failing the whole cache write over it would
+        // metadata, and failing the whole cache write over it would break
-        // break browsing.
+        // browsing.
        if let Err(e) = self.db_service.execute(query).await {
            debug!(
                "[OfflineRepo] user_data mirror skipped for {}: {}",
@@ -1426,6 +1449,14 @@ impl MediaRepository for OfflineRepository {
                FROM items i
                 INNER JOIN downloaded_items di ON i.id = di.id
                 WHERE i.server_id = ? AND i.library_id = ?
                 -- Collapse leaves into the container that was added: a new
                 -- 14-track album should read as one album, not 14 songs. Only
                 -- drops a leaf when its own container is present in the same
                 -- result, so a standalone track or movie still appears.
                 AND NOT EXISTS (
                     SELECT 1 FROM downloaded_items parent
                     WHERE parent.id IN (i.album_id, i.season_id, i.series_id, i.parent_id)
                 )
                 ORDER BY i.synced_at DESC
                 LIMIT {}", limit_val
            ),
@@ -3544,6 +3575,32 @@ mod tests {
        .unwrap();
    }
    /// Like `insert_item`, but sets `library_id` — which `get_latest_items`
    /// filters on, so rows without it are invisible to that query.
    async fn insert_library_item(
        db: &Arc<RusqliteService>,
        id: &str,
        item_type: &str,
        library_id: &str,
        album_id: Option<&str>,
    ) {
        db.execute(Query::with_params(
            "INSERT INTO items (id, server_id, library_id, name, item_type, album_id, synced_at)
             VALUES (?1, 'test-server', ?2, ?3, ?4, ?5, '2024-01-01')",
            vec![
                QueryParam::String(id.to_string()),
                QueryParam::String(library_id.to_string()),
                QueryParam::String(format!("Name {id}")),
                QueryParam::String(item_type.to_string()),
                album_id
                    .map(|s| QueryParam::String(s.to_string()))
                    .unwrap_or(QueryParam::Null),
            ],
        ))
        .await
        .unwrap();
    }
    async fn seed_completed_download(db: &Arc<RusqliteService>, item_id: &str, file_size: i64) {
        db.execute(Query::with_params(
            "INSERT INTO downloads (item_id, status, file_size) VALUES (?1, 'completed', ?2)",
@@ -3578,6 +3635,36 @@ mod tests {
        )
    }
    /// A newly-synced album appears once in "recently added", not once per track.
    ///
    /// The downloaded-items CTE deliberately matches both the leaves and their
    /// container, which is right for browsing but wrong here: it made a 3-track
    /// album occupy 4 slots in the row. Tracks whose album is itself in the
    /// result are now collapsed into it.
    #[tokio::test]
    async fn test_get_latest_items_collapses_tracks_into_their_album() {
        let db = create_test_db();
        insert_library_item(&db, "album-1", "MusicAlbum", "lib-1", None).await;
        for track in ["track-1", "track-2", "track-3"] {
            insert_library_item(&db, track, "Audio", "lib-1", Some("album-1")).await;
            seed_completed_download(&db, track, 1000).await;
        }
        // A movie has no container, so it must still show up on its own.
        insert_library_item(&db, "movie-1", "Movie", "lib-1", None).await;
        seed_completed_download(&db, "movie-1", 2000).await;
        let repo = make_repo(&db);
        let latest = repo.get_latest_items("lib-1", Some(16)).await.unwrap();
        let ids: Vec<&str> = latest.iter().map(|i| i.id.as_str()).collect();
        assert!(
            !ids.iter().any(|id| id.starts_with("track-")),
            "individual tracks must collapse into their album, got: {ids:?}"
        );
        assert!(ids.contains(&"album-1"), "the album itself is listed");
        assert!(ids.contains(&"movie-1"), "containerless items still listed");
    }
    /// UT: downloaded-only browse returns a downloaded leaf AND its container,
    /// filtered to the requested album parent. A non-downloaded sibling is omitted.
    ///
@@ -4374,4 +4461,142 @@ mod tests {
            "an unsynced local toggle must survive a cache write"
        );
    }
    /// UT-152 — the server's watch position is mirrored locally, so an item
    /// watched on another device resumes here.
    ///
    /// The resume check reads only the local `user_data` row, and the mirror
    /// previously carried `is_favorite` alone — so a position set on any other
    /// client never reached this device and cross-device resume silently did
    /// nothing. The `pending_sync` guard is the same conflict rule favourites
    /// use: a local position still waiting to be pushed must not be pulled
    /// backwards by the stale value the server is still reporting.
    ///
    /// TRACES: UR-025, UR-069 | DR-155 | UT-152
    #[tokio::test]
    async fn test_save_to_cache_mirrors_playback_position_without_clobbering_pending() {
        use crate::storage::db_service::DatabaseService;
        let db_service = create_test_db();
        let repo = OfflineRepository::new(
            db_service.clone(),
            "test-server".to_string(),
            "test-user".to_string(),
        );
        let position = |id: &'static str| {
            let db = db_service.clone();
            async move {
                db.query_optional(
                    Query::with_params(
                        "SELECT playback_position_ticks, pending_sync FROM user_data \
                         WHERE user_id = ? AND item_id = ?",
                        vec![
                            QueryParam::String("test-user".to_string()),
                            QueryParam::String(id.to_string()),
                        ],
                    ),
                    |row| Ok((row.get::<_, Option<i64>>(0)?, row.get::<_, Option<i32>>(1)?)),
                )
                .await
                .unwrap()
            }
        };
        // Watched 20 minutes into this episode on another device.
        let mut watched = create_test_item("ep-1", "Watched Elsewhere", None);
        watched.user_data = Some(UserData {
            playback_position_ticks: Some(12_000_000_000),
            ..Default::default()
        });
        // No user data at all — must not fabricate a position of 0.
        let untouched = create_test_item("ep-2", "No User Data", None);
        repo.save_to_cache("parent-1", &[watched.clone(), untouched])
            .await
            .unwrap();
        assert_eq!(
            position("ep-1").await,
            Some((Some(12_000_000_000), Some(0))),
            "the server's position should be mirrored as synced"
        );
        assert_eq!(
            position("ep-2").await,
            None,
            "an item without UserData should not get an invented position"
        );
        // Watched further here while the server was unreachable: pending_sync = 1.
        db_service
            .execute(Query::with_params(
                "UPDATE user_data SET playback_position_ticks = ?, pending_sync = 1 \
                 WHERE user_id = ? AND item_id = ?",
                vec![
                    QueryParam::Int64(30_000_000_000),
                    QueryParam::String("test-user".to_string()),
                    QueryParam::String("ep-1".to_string()),
                ],
            ))
            .await
            .unwrap();
        // The server still reports the older position; caching must not win.
        repo.save_to_cache("parent-1", &[watched]).await.unwrap();
        assert_eq!(
            position("ep-1").await,
            Some((Some(30_000_000_000), Some(1))),
            "an unsynced local position must not be pulled backwards"
        );
    }
    /// UT-152 — a server item carrying *only* a position (no favourite flag)
    /// still gets mirrored.
    ///
    /// The mirror used to return early whenever `is_favorite` was absent, which
    /// is exactly the shape of an ordinary watched episode: Jellyfin reports
    /// `PlaybackPositionTicks` with no favourite state. That early return is why
    /// the position never landed.
    ///
    /// TRACES: UR-025 | DR-155 | UT-152
    #[tokio::test]
    async fn test_position_is_mirrored_even_when_no_favourite_flag_is_present() {
        use crate::storage::db_service::DatabaseService;
        let db_service = create_test_db();
        let repo = OfflineRepository::new(
            db_service.clone(),
            "test-server".to_string(),
            "test-user".to_string(),
        );
        let mut watched = create_test_item("ep-3", "Position Only", None);
        watched.user_data = Some(UserData {
            is_favorite: None,
            playback_position_ticks: Some(9_000_000_000),
            ..Default::default()
        });
        repo.save_to_cache("parent-1", &[watched]).await.unwrap();
        let stored = db_service
            .query_optional(
                Query::with_params(
                    "SELECT playback_position_ticks FROM user_data \
                     WHERE user_id = ? AND item_id = ?",
                    vec![
                        QueryParam::String("test-user".to_string()),
                        QueryParam::String("ep-3".to_string()),
                    ],
                ),
                |row| row.get::<_, Option<i64>>(0),
            )
            .await
            .unwrap();
        assert_eq!(
            stored,
            Some(Some(9_000_000_000)),
            "a position with no favourite flag must still be mirrored"
        );
    }
 }
@@ -670,6 +670,26 @@ fn build_get_items_endpoint(
    endpoint
 }
 /// Build the Jellyfin endpoint for a "recently added" listing.
 ///
 /// `GroupItems=true` is the load-bearing parameter: Jellyfin defaults it to
 /// `false`, which returns each newly-added *leaf* separately, so importing one
 /// 14-track album pushed 14 rows into "recently added" and buried everything
 /// else. With grouping on, the server collapses children into the container
 /// that was added — an album appears once, while movies (which have no such
 /// container) are unaffected.
 ///
 /// Pulled out of `get_latest_items` so the query can be asserted without an
 /// HTTP server, matching `build_favorites_endpoint`.
 fn build_latest_items_endpoint(user_id: &str, parent_id: &str, limit: Option<usize>) -> String {
    format!(
        "/Users/{}/Items/Latest?ParentId={}&Limit={}&GroupItems=true&Fields=BackdropImageTags,ParentBackdropImageTags,UserData",
        user_id,
        parent_id,
        limit.unwrap_or(16)
    )
 }
 /// Build the Jellyfin endpoint for a favourites listing.
 ///
 /// Pulled out of `get_favorites` so the query can be asserted without an HTTP
@@ -908,11 +928,7 @@ impl MediaRepository for OnlineRepository {
        parent_id: &str,
        limit: Option<usize>,
    ) -> Result<Vec<MediaItem>, RepoError> {
-        let limit_str = limit.unwrap_or(16);
+        let endpoint = build_latest_items_endpoint(&self.user_id, parent_id, limit);
        let endpoint = format!(
            "/Users/{}/Items/Latest?ParentId={}&Limit={}&Fields=BackdropImageTags,ParentBackdropImageTags,UserData",
            self.user_id, parent_id, limit_str
        );
        let items: Vec<JellyfinItem> = self.get_json(&endpoint).await?;
        Ok(items
@@ -1772,6 +1788,7 @@ impl MediaRepository for OnlineRepository {
        )
    }
    /// TRACES: UR-071 | DR-123
    fn get_video_download_url(
        &self,
        item_id: &str,
@@ -1789,27 +1806,43 @@ impl MediaRepository for OnlineRepository {
        // Map the frontend quality preset to concrete transcode params. For
        // "original" we request a direct static copy (no transcode) which is
        // byte-range resumable; other presets ask the server to transcode.
        //
        // 🔴 It is `videoBitRate`/`audioBitRate` — **capital R**. Jellyfin binds
        // query keys case-insensitively, so `maxHeight`/`videoCodec` casing is
        // free, but `videoBitrate` (lowercase r) is a *different token*: it
        // fails to bind, is silently dropped, and the requested cap vanishes
        // with no error. That is why every "480p"/"720p" download came back at
        // full original quality. See `Jellyfin.Api` BaseEncodingJobOptions.
        //
        // `allowVideoStreamCopy=false` forces a real re-encode. Without it the
        // server may stream-copy the source when it already satisfies the cap —
        // fine in itself, but it also means a mis-typed cap degrades silently.
        // Note `enableAutoStreamCopy=false` alone does NOT stop a *video* copy;
        // video copy is gated by `allowVideoStreamCopy`.
        match quality {
            "high" => {
-                params.push("videoBitrate=8000000".to_string());
+                params.push("videoBitRate=8000000".to_string());
                params.push("maxHeight=1080".to_string());
-                params.push("audioBitrate=384000".to_string());
+                params.push("audioBitRate=384000".to_string());
                params.push("videoCodec=h264".to_string());
                params.push("audioCodec=aac".to_string());
                params.push("allowVideoStreamCopy=false".to_string());
            }
            "medium" => {
-                params.push("videoBitrate=4000000".to_string());
+                params.push("videoBitRate=4000000".to_string());
                params.push("maxHeight=720".to_string());
-                params.push("audioBitrate=256000".to_string());
+                params.push("audioBitRate=256000".to_string());
                params.push("videoCodec=h264".to_string());
                params.push("audioCodec=aac".to_string());
                params.push("allowVideoStreamCopy=false".to_string());
            }
            "low" => {
-                params.push("videoBitrate=1500000".to_string());
+                params.push("videoBitRate=1500000".to_string());
                params.push("maxHeight=480".to_string());
-                params.push("audioBitrate=128000".to_string());
+                params.push("audioBitRate=128000".to_string());
                params.push("videoCodec=h264".to_string());
                params.push("audioCodec=aac".to_string());
                params.push("allowVideoStreamCopy=false".to_string());
            }
            // "original" (and any unknown value) → direct, resumable copy.
            _ => {
@@ -2548,7 +2581,7 @@ mod tests {
        // with no transcode params.
        assert!(url.contains("Static=true"), "url: {url}");
        assert!(
-            !url.contains("videoBitrate"),
+            !url.contains("videoBitRate"),
            "original must not transcode: {url}"
        );
        assert!(
@@ -2568,7 +2601,7 @@ mod tests {
                "{quality} must use stream.mp4: {url}"
            );
            assert!(
-                url.contains("videoBitrate="),
+                url.contains("videoBitRate="),
                "{quality} must set bitrate: {url}"
            );
            assert!(
@@ -2584,6 +2617,66 @@ mod tests {
        }
    }
    /// The bitrate params are spelled `videoBitRate`/`audioBitRate` — **capital
    /// R**. Jellyfin binds query keys case-insensitively, so this is not a
    /// casing preference: `videoBitrate` is a *different token* that fails to
    /// bind and is silently discarded, taking the user's quality cap with it.
    /// Nothing errors — the download just returns the full-size original, which
    /// is exactly how this bug went unnoticed.
    #[test]
    fn test_video_download_url_bitrate_params_use_capital_r_spelling() {
        let repo = create_test_repository();
        for quality in ["high", "medium", "low"] {
            let url = repo.get_video_download_url("item123", quality, None);
            assert!(
                url.contains("videoBitRate="),
                "{quality} must spell it videoBitRate (capital R): {url}"
            );
            assert!(
                url.contains("audioBitRate="),
                "{quality} must spell it audioBitRate (capital R): {url}"
            );
            // The lowercase-r spellings never bind — they must not appear at
            // all, or the cap is silently dropped by the server.
            assert!(
                !url.contains("videoBitrate="),
                "{quality} emits the unbindable lowercase-r spelling: {url}"
            );
            assert!(
                !url.contains("audioBitrate="),
                "{quality} emits the unbindable lowercase-r spelling: {url}"
            );
        }
    }
    /// A correctly-spelled cap is still only *conditionally* honored: the server
    /// may stream-copy the source when it already satisfies the cap. Video copy
    /// is gated by `allowVideoStreamCopy` (NOT `enableAutoStreamCopy`, which
    /// only governs audio), so the transcode presets must disable it to
    /// guarantee a real re-encode at the requested bitrate.
    #[test]
    fn test_video_download_url_transcode_presets_forbid_video_stream_copy() {
        let repo = create_test_repository();
        for quality in ["high", "medium", "low"] {
            let url = repo.get_video_download_url("item123", quality, None);
            assert!(
                url.contains("allowVideoStreamCopy=false"),
                "{quality} must forbid video stream copy: {url}"
            );
        }
        // "original" is a deliberate direct copy — it must NOT disable copying.
        let original = repo.get_video_download_url("item123", "original", None);
        assert!(
            !original.contains("allowVideoStreamCopy=false"),
            "original must remain a direct copy: {original}"
        );
    }
    #[test]
    fn test_video_download_url_passes_media_source_id() {
        let repo = create_test_repository();
@@ -2706,6 +2799,25 @@ mod tests {
        assert!(!off.contains("Filters=IsFavorite"));
    }
    /// A newly-added album must arrive as one entry, not one per track.
    ///
    /// Jellyfin's `/Items/Latest` defaults to `GroupItems=false`, which returns
    /// every new Audio track individually — so ripping a 14-track album filled
    /// the whole "recently added" row with that one album. `GroupItems=true`
    /// makes the server collapse children into their parent container.
    #[test]
    fn test_latest_items_endpoint_groups_children_into_containers() {
        let endpoint = build_latest_items_endpoint("u1", "lib-1", Some(16));
        assert!(
            endpoint.contains("GroupItems=true"),
            "latest items must be grouped so an album counts once, got: {}",
            endpoint
        );
        assert!(endpoint.contains("ParentId=lib-1"));
        assert!(endpoint.contains("Limit=16"));
    }
    /// UT-099 — a Jellyfin item's `UserData` reaches `MediaItem.user_data`.
    ///
    /// Before DR-113 this mapping was hardcoded to `None`, so nothing outside
@@ -97,9 +97,14 @@ fn belongs_to_series(item: &MediaItem, series_id: &str) -> bool {
 ///    working through.
 /// 2. **The server's Next Up** for this series — it accounts for watch history
 ///    we do not cache locally.
-/// 3. **The first unwatched episode** in series order. This is the offline path:
+/// 3. **The episode after the furthest-watched one**, falling back to the first
-///    `OfflineRepository::get_next_up_episodes` returns an empty vec, so without
+///    unwatched episode when nothing has been watched or the series is finished.
-///    this rung the whole feature would be online-only.
+///    This is the offline path: `OfflineRepository::get_next_up_episodes`
 ///    returns an empty vec, so without this rung the whole feature would be
 ///    online-only. It deliberately does *not* return the first unwatched
 ///    episode outright — an unwatched episode behind the viewer's furthest
 ///    point was skipped on purpose, and sending them back to it is the bug
 ///    DR-101 was reopened for.
 /// 4. **The first episode**, so a never-watched series opens on its premiere
 ///    rather than on nothing.
 ///
@@ -136,7 +141,18 @@ pub fn pick_current_episode(
        return Some(matched.unwrap_or(found).clone());
    }
-    // 3. First unwatched in series order.
+    // 3. The episode after the furthest-watched one. Not simply the first
    //    unwatched: a viewer who skipped the pilot but is deep into season 3
    //    must not be dragged back to S1E1. An earlier gap is a deliberate skip;
    //    where they stopped is the *last* thing they watched.
    if let Some(furthest) = episodes.iter().rposition(is_played) {
        if let Some(found) = episodes.get(furthest + 1) {
            return Some(found.clone());
        }
    }
    // Nothing watched yet (or the furthest-watched episode is the finale):
    // the first unwatched episode in series order.
    if let Some(found) = episodes.iter().find(|e| !is_played(e)) {
        return Some(found.clone());
    }
@@ -352,6 +368,54 @@ mod tests {
        assert_eq!(current.id, "s2e2");
    }
    /// A viewer deep in season 3 who never watched the pilot must not be sent
    /// back to it: the gap was a skip, not the place they stopped.
    #[test]
    fn resumes_after_the_furthest_watched_episode_not_the_first_gap() {
        let mut eps = [season(1, 4), season(2, 4), season(3, 4)].concat();
        for ep in eps.iter_mut() {
            // Everything through S3E3 watched, except the never-watched pilot.
            let watched_through = ep.parent_index_number < Some(3) || ep.index_number <= Some(3);
            if watched_through && ep.id != "s1e1" {
                *ep = watched(ep.clone());
            }
        }
        let current = pick_current_episode(SERIES, &eps, &[], &[]).unwrap();
        assert_eq!(current.id, "s3e4");
    }
    /// The furthest-watched episode being a finale must still roll into the
    /// next season rather than stopping the series.
    #[test]
    fn resumes_into_the_next_season_after_a_skipped_earlier_episode() {
        let mut eps = [season(1, 3), season(2, 3)].concat();
        for ep in eps.iter_mut() {
            if ep.parent_index_number == Some(1) && ep.id != "s1e1" {
                *ep = watched(ep.clone());
            }
        }
        let current = pick_current_episode(SERIES, &eps, &[], &[]).unwrap();
        assert_eq!(current.id, "s2e1");
    }
    /// Specials sort last, so watching one must not mark the series finished
    /// while numbered episodes remain.
    #[test]
    fn a_watched_special_does_not_end_the_series() {
        let mut eps = [season(1, 3), vec![episode("s0e1", 0, 1)]].concat();
        sort_series_order(&mut eps);
        for ep in eps.iter_mut() {
            if ep.id == "s1e1" || ep.id == "s0e1" {
                *ep = watched(ep.clone());
            }
        }
        let current = pick_current_episode(SERIES, &eps, &[], &[]).unwrap();
        assert_eq!(current.id, "s1e2");
    }
    #[test]
    fn crosses_a_season_boundary_when_a_season_is_finished() {
        let mut eps = [season(1, 3), season(2, 3)].concat();
@@ -0,0 +1,10 @@
 {
  "$schema": "https://schema.tauri.app/config/2",
  "app": {
    "windows": [
      {
        "transparent": true
      }
    ]
  }
 }
@@ -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 });
 },
@@ -1464,6 +1472,15 @@ async repositoryReportPlaybackProgress(handle: string, itemId: string, positionM
 },
 /**
 * Report playback stopped
 * 
 * A stop-report that cannot reach the server is queued rather than dropped:
 * this is the position the resume point is built from, and losing it is
 * exactly the "it forgot where I was" the sync queue exists to prevent. The
 * drain (DR-131) pushes it on the next reconnect. Queueing is best-effort —
 * failing the command because the *queue* write failed would tell the caller
 * the report was lost when the local position was already saved.
 * 
 * TRACES: UR-025 | DR-154 | UT-151
 */
 async repositoryReportPlaybackStopped(handle: string, itemId: string, positionMs: number) : Promise<null> {
    return await TAURI_INVOKE("repository_report_playback_stopped", { handle, itemId, positionMs });
@@ -2293,6 +2310,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
 */
@@ -45,9 +45,16 @@
     * TRACES: UR-068 | DR-119
     */
    showFavorite?: boolean;
    /**
     * Force the artwork box to a fixed aspect ratio instead of deriving one from
     * the item. Use on rows that mix item kinds (e.g. the home "Your Libraries"
     * strip, where square music art next to 16:9 video art would otherwise give
     * the cards different heights). Artwork still fills the box via object-cover.
     */
    aspect?: "square" | "video" | "poster";
  }
-  let { item, size = "medium", showProgress = false, showDownloadStatus = true, sizeLabel, downloadedBadge, onRemove, onclick, onLongPress, showFavorite = true }: Props = $props();
+  let { item, size = "medium", showProgress = false, showDownloadStatus = true, sizeLabel, downloadedBadge, onRemove, onclick, onLongPress, showFavorite = true, aspect }: Props = $props();
  // Long-press detection. We arm a timer on pointerdown; if it fires before the
  // pointer is released (or moves too far), we treat it as a long press and set a
@@ -179,7 +186,14 @@
    "kind" in item && (item.kind === "track" || item.kind === "album" || item.kind === "artist" || item.kind === "playlist")
  );
  const FIXED_ASPECT = {
    square: "aspect-square",
    video: "aspect-video",
    poster: "aspect-[2/3]",
  } as const;
  const aspectRatio = $derived(() => {
    if (aspect) return FIXED_ASPECT[aspect];
    if ("kind" in item) {
      return isMusicType ? "aspect-square" : "aspect-[2/3]";
    }
@@ -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
+        // Rust reported a native backend (Android/ExoPlayer). Honour it only if
-        // through the webview HTML5 element, including Android. The native
+        // the user opted into the experimental native path; otherwise fall back
-        // ExoPlayer SurfaceView sits behind an opaque webview and has never
+        // to the webview element, which is what shipped by default.
-        // 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
+        // The flag is a suppressor, never a promoter — see createAdapter(). When
-        // picture. Stop the native backend and let the webview own playback,
+        // it is off we must also stop the native backend that player_play_item
-        // matching Linux behavior and avoiding dual audio.
+        // just started, or ExoPlayer and the <video> element both decode the
-        if (!useHtml5Element) {
+        // same stream and the audio doubles.
-          console.warn("[VideoPlayer] Native video backend reported - overriding to HTML5 rendering (native surface not visible through webview)");
+        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,16 +701,61 @@
          didStartNativePlayback = true; // Track that we need to stop backend on unmount
        }
-        // Register the HTML5 player adapter with the facade so control intents
+        // Register the adapter with the facade so control intents (UI, or a
-        // (UI or backend lockscreen/remote/sleep events) route to this element.
+        // backend lockscreen/remote/sleep event) route to whatever is actually
-        if (useHtml5Element) {
+        // 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);
          // The native (ExoPlayer) path has no <video> element, so `canplay`
          // never fires and the handleCanPlay initial-seek below never runs —
          // resume-at-position played from the beginning on Android. Hand the
          // resume point to the adapter, which issues the backend seek.
          //
          // HTML5 keeps its existing element-driven seek: seeking before the
          // element has metadata is clamped back to 0, which is precisely what
          // handleCanPlay waits for.
          // TRACES: UR-005 | DR-004, DR-028
          if (!useHtml5Element) {
            hasPerformedInitialSeek = true; // native path owns the initial seek
            lastAppliedInitialPosition = initialPosition;
            await playerAdapter.load(currentStreamUrl, {
              mediaId: media.id,
              mediaSourceId: mediaSourceId ?? null,
              needsTranscoding,
              initialPosition: initialPosition ?? 0,
              isLive,
              audioTrackIndex: null,
              knownDuration: media.durationMs ? media.durationMs / 1000 : 0,
              // ExoPlayer already received these as SubtitleConfigurations via
              // player_play_item; mapped to the adapter shape for the contract.
              subtitleTracks: sentSubtitleTracks.map((t) => ({
                index: t.streamIndex,
                url: t.url,
                language: t.srclang,
                label: t.label,
                mimeType: "text/vtt",
              })),
            });
            if (initialPosition && initialPosition > 0 && !isLive) {
              currentTime = initialPosition;
            }
          }
        }
        if (!useHtml5Element) {
@@ -780,6 +847,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
+ * Rust decides *which backend this platform has* (`useHtml5Element` from
- * backend may report a native ExoPlayer backend, but native Android video
+ * `player_play_item`); this factory consumes that decision rather than
- * rendering is blocked upstream (tauri#10152 — transparent webview / SurfaceView
+ * re-deriving it.
 * 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
+ * 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
+ * Native is chosen only when Rust reports a native backend AND the user has
- * visible through the webview on current Tauri (see module docs). The bridge is
+ * opted in. Every other combination is HTML5.
 * therefore required.
 */
-export function createAdapter({ backendKind, host, bridge }: CreateAdapterArgs): PlayerAdapter {
+export function createAdapter({
-  // INTERIM OVERRIDE: force HTML5 rendering even when the backend reports native.
+  backendKind,
-  const effectiveKind: BackendKind = "html5";
+  host,
  bridge,
  experimentalNativeVideo = false,
 }: CreateAdapterArgs): PlayerAdapter {
  const effectiveKind: BackendKind =
    backendKind === "native" && experimentalNativeVideo ? "native" : "html5";
-  if (effectiveKind === "html5") {
+  if (effectiveKind === "native") {
-    if (!bridge) {
+    // The native surface is owned by the backend — no DOM element, no bridge.
-      throw new Error("createAdapter: Html5ElementBridge is required for the HTML5 adapter");
+    return new NativePlayerAdapter(host);
    }
    return new Html5PlayerAdapter(host, bridge);
  }
-  // Reached only once the interim override is lifted (native Android unblocked).
+  if (!bridge) {
-  void backendKind;
+    throw new Error("createAdapter: Html5ElementBridge is required for the HTML5 adapter");
-  return new NativePlayerAdapter(host);
+  }
  return new Html5PlayerAdapter(host, bridge);
 }
@@ -11,6 +11,7 @@ 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 => ({}));
 const playerSeek = vi.fn((..._a: any[]): any => ({}));
 vi.mock("$lib/api/bindings", () => ({
  commands: {
@@ -20,6 +21,7 @@ vi.mock("$lib/api/bindings", () => ({
    playerSetVolume: (...a: any[]) => playerSetVolume(...a),
    playerToggleMute: (...a: any[]) => playerToggleMute(...a),
    playerSetSubtitleTrack: (...a: any[]) => playerSetSubtitleTrack(...a),
    playerSeek: (...a: any[]) => playerSeek(...a),
  },
 }));
@@ -72,6 +74,39 @@ describe("NativePlayerAdapter", () => {
    expect(adapter.getPosition()).toBe(90);
  });
  // Regression: resume-at-position was broken on Android. player_play_item
  // carries no start position, and ExoPlayer always begins at 0, so recording
  // the number frontend-side left the backend playing from the beginning. The
  // adapter must actually *issue* the seek.
  it("load() issues the resume seek to the backend, not just records it", async () => {
    await adapter.load("url", {
      mediaId: "m", mediaSourceId: null, needsTranscoding: false,
      initialPosition: 90, isLive: false, audioTrackIndex: null,
      knownDuration: 0, subtitleTracks: [],
    });
    expect(playerSeek).toHaveBeenCalledWith(90);
  });
  it("load() does not seek when starting from the beginning", async () => {
    await adapter.load("url", {
      mediaId: "m", mediaSourceId: null, needsTranscoding: false,
      initialPosition: 0, isLive: false, audioTrackIndex: null,
      knownDuration: 0, subtitleTracks: [],
    });
    expect(playerSeek).not.toHaveBeenCalled();
  });
  // A live stream has no meaningful resume point; seeking one is at best a
  // no-op and at worst knocks the HLS window off its live edge.
  it("load() never seeks a live stream", async () => {
    await adapter.load("url", {
      mediaId: "m", mediaSourceId: null, needsTranscoding: false,
      initialPosition: 90, isLive: true, audioTrackIndex: null,
      knownDuration: 0, subtitleTracks: [],
    });
    expect(playerSeek).not.toHaveBeenCalled();
  });
  it("setVolume clamps and delegates; setMuted toggles mute", () => {
    adapter.setVolume(2);
    expect(playerSetVolume).toHaveBeenCalledWith(1);
@@ -43,10 +43,21 @@ export class NativePlayerAdapter implements PlayerAdapter {
  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
+    // created, so there is no stream to load here — but it carries no start
-    // native backend performs the actual seek internally).
+    // position, and ExoPlayer always begins at 0. The resume seek must be
-    if (options.initialPosition > 0) {
+    // issued explicitly or "resume at position" silently plays from the top.
    //
    // Recording the position without seeking (what this used to do) is what
    // broke Android resume: the frontend believed it had resumed while
    // ExoPlayer played from the beginning.
    //
    // Live streams have no resume point — seeking one knocks the HLS window off
    // its live edge, so they are excluded.
    //
    // TRACES: UR-005 | DR-004, DR-028
    if (options.initialPosition > 0 && !options.isLive) {
      this.position = options.initialPosition;
      await commands.playerSeek(options.initialPosition);
    }
  }
@@ -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;
 }
@@ -103,15 +103,15 @@ export async function reportPlaybackStopped(itemId: string, positionSeconds: num
    }
  }
-  // Queue for sync to server (the sync service will handle retry logic)
+  // Report to the server. Rust queues the position for the next reconnect if
  // the server cannot be reached (DR-154), so a throw here means the report
  // did not land *this time* — not that the position was lost.
  if (userId && positionSeconds > 0) {
    try {
      // Get the repository to check if we should queue
      const repo = auth.getRepository();
      await repo.reportPlaybackStopped(itemId, positionMs);
    } catch (e) {
-      console.error("[PlaybackReporting] Failed to report to server:", e);
+      console.warn("[PlaybackReporting] Stop-report did not reach the server; queued for sync:", e);
      // Server error - could queue, but for now just log
    }
  }
 }
@@ -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);
 }
@@ -159,12 +159,15 @@
    {#if shortcutLibraries.length > 0}
      <div>
        <h2 class="text-xl font-bold text-white mb-4 px-4">Your Libraries</h2>
-        <div class="flex gap-4 overflow-x-auto px-4 pb-2">
+        <div class="flex gap-4 overflow-x-auto px-4 pb-2 items-start">
          {#each shortcutLibraries as lib (lib.id)}
            <div class="flex-shrink-0">
              <!-- Uniform 16:9 artwork so music (square) and video libraries
                   line up at the same height in this mixed row. -->
              <MediaCard
                item={lib}
                size="medium"
                aspect="video"
                onclick={() => handleLibraryClick(lib)}
              />
            </div>
@@ -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 -->