fix(player): make Android native video actually visible, and usable

DR-172 reverted native video to opt-in after it shipped as audio with no
picture, naming the compositing as the suspect. The compositing was fine. Five
separate defects sat between ExoPlayer and the screen, each able to produce that
exact symptom on its own, and each invisible to the others.

DR-185 — the app shell painted over the surface. app.css clears the page's
opaque layers through three selectors, one of which targets `[data-app-shell]`,
an attribute NO component has ever set, in any commit. The shell paints
--color-background across the whole viewport and VideoPlayer stacks above it, so
the WebView composited opaque no matter what else was cleared. Invisible three
ways over: the CSS is valid, the selector is plausible, and a rule matching
nothing looks exactly like a rule matching something already transparent.

DR-182 — nothing could lift the poster card. Every markMediaReady() call site is
an HTML5 <video> event, and the native branch renders no element, so the black
title card covered the surface for the entire session. The first fix hooked
`player://position-update` / `player://state-changed`; those channels are never
emitted by the backend, so it passed a test that fired them by hand and did
nothing on a device. Driven from the player store now, as the seek bar already
was.

DR-183 — the JS bridges raced the page load. Installed 500ms after onCreate by
walking the view tree, while WebView binds injected objects at page-load time,
and the identity guard then declined to re-inject forever. setTransparent(true)
could never arrive. Installed from WryActivity.onWebViewCreate instead, which
wry calls immediately before the first loadUrl.

DR-184 — the SurfaceView was never detached. detachVideoSurface had no callers
anywhere, mirroring the DR-151 defect: every native video left its surface
parented to the content view and the next one stacked another beneath it.

DR-191 — the overlay stopped repainting. Incremental damage (the clock's text,
the control bar's opacity) never reached the screen while structural changes did,
so the progress bar froze, the controls would not fade, and the play overlay
appeared to work because it is added and removed from the DOM. Driven from the
Activity via postInvalidateOnAnimation while compositing is on.

Two UI defects only this path could reveal came with them: isPlaying froze at
its initial value, leaving the play overlay dimming and covering the video
(DR-186), and the control bar's auto-hide was armed solely by mousemove, which a
touchscreen never fires (DR-189). Immersive mode now applies on entering the
player rather than only via the fullscreen button (DR-187).

Verified on a device (Honor ROD2-W09, Android 16): logcat carries
`WebView transparent = true` and `Marking media ready` with video on screen —
the pair DR-172 went looking for and could not find — and skip, seek, rotation
and subtitle rendering were exercised by hand.

The default stays OFF (DR-188). Turning it on surfaced a further unverified
sub-path: returning from background audio is HTML5-only, so playback stays dead
(DR-190, proposed). Shipping it would have repeated DR-161 exactly — a verified
sub-path made default over an unverified one.

docs/requirements.md

@@ -340,6 +340,15 @@ Internal architecture, components, and application logic.
 | DR-179 | Jellyfin is told what was played: progress while it plays, and a stop when it ends. A device trace of 35 minutes' playback requested `/Sessions/Playing/Progress` **zero** times and sent 14 `Stopped` reports, every one of them at position 0. Three faults, one subject. *Progress never left the device*: the frontend service writes it to the local DB by design, and nothing on the Rust side reported it for webview-rendered media — so the server learned a position only when the player was closed, and a crash or a swipe-away cost the session. It is now reported from the controller's own position ticks, through the 30s throttler it already owned and shares with the native audio path, which covers all three rendering paths in one place instead of adding a second frequent IPC caller. *Zero-position stops were sent*: Jellyfin stores the reported position as the resume point, so a zero does not merely fail to inform, it instructs the server to forget — and no zero was ever real, each one coming from asking a player that was not rendering the media (see DR-178). They are withheld; one landed 40s after the frontend had correctly reported 15:22 for the same episode, overwriting it. *A finished episode reported nothing at all*: Jellyfin decides "watched" from the stop report and its percentage, and in background audio-only mode nobody sends one — the webview is suspended and its element was torn down at the handoff, while the backend advances to the next episode without a word about the one that ended, so an episode listened to end-to-end on the lockscreen never counted as watched. `on_playback_ended` now reports it stopped at its **runtime** (not the last tick, which can be seconds short or, on a handoff whose ticks stopped early, nowhere near the end) before any advance, since after one the queue's current item is the next episode. Scoped to the audio-only handoff, the case the frontend provably cannot cover, so foreground playback keeps its single existing report; music ending natively remains unreported and wants its own change. The reporting seam is a `PlaybackReportSink` the controller sends to, which also collapses three copies of the spawn-a-task-and-hope block into one and is what let all of this be written as failing tests rather than found on a device a second time | Player | UR-025, UR-005, UR-040 | Done (pending device verification) |
 | DR-180 | A background-audio handoff of a **downloaded** episode starts where the video left off. The handoff prefers a local file over the audio-only stream (DR-128), but the two begin in different places and were treated alike: a stream is built with `StartTimeTicks`, so the server makes the handoff point that stream's zero and the base is the handoff position with no seek — while a file has no such parameter and begins at the episode's own zero, so basing it at the handoff position claimed minutes of audio that were about to play from the beginning. Backgrounding a downloaded episode therefore restarted it while the lockscreen scrubber, dutifully adding the base, showed the position it should have been at. `background_audio_plan` splits the two: a file gets no base and a real seek, a stream keeps the base and no seek (seeking one would skip *past* the content by the handoff position again). The same distinction settles an inbound seek — `seek_absolute` re-opens a *streamed* handoff at the requested position because a chunked length-less transcode cannot honour a seek, which is not true of local media, and `resume_stream_at` refuses a non-remote source outright, so routing a lockscreen scrub of a downloaded episode through it failed the seek rather than performing it | Player | UR-040, UR-071 | Done (pending device verification) |
 | DR-181 | A resumed transcode plays. Every video stream URL carried the resume position as `StartTimeTicks`, which is correct for a progressive response and fatal for an HLS one: Jellyfin builds each segment URI by echoing the **master playlist's** query string into it, and its segment handler opens by rejecting any request carrying `StartTimeTicks > 0` (`ArgumentException` → `400`). One position on the playlist therefore 400s every `hls1/main/N.ts` behind it, so hls.js exhausted its retries and gave up — presenting as an episode that will not resume while the same episode from the beginning is fine, the `> 0` being exactly why the beginning survived. The parameter is also unnecessary there: a playlist spans the whole item and asking for segment N *is* the seek, which the server transcodes from. So it is removed from the URL builder entirely rather than conditionalised — the builder has one caller shape and no way to know whether the response will be segmented — and the position becomes what it always was for HLS, a seek issued once the player has loaded: the seek path reloads at zero and seeks the element, and the resume path lets the player seek itself. The progressive `/Audio/universal` builder used by the background-audio handoff is a different endpoint with no segments and keeps its `StartTimeTicks`, which is why an audio-only handoff resumes correctly and a video one did not | Playback | UR-004, UR-074 | Done |
+| DR-182 | Native video shows a picture. The poster/title card is an opaque `bg-black` overlay drawn over the whole video area while `isMediaReady` is false, and **every** signal that clears it is emitted by the HTML5 `<video>` element — `canplay`, `loadedmetadata`, hls.js `FRAG_BUFFERED`, the `playing` event, and two `readyState` timeouts. The native path renders no such element (`{#if !!useHtml5Element}`), so on Android nothing could ever clear it: ExoPlayer decoded to a live SurfaceView behind a black div for the entire session. That is DR-172's "audio with no picture" report, and it is indistinguishable on screen from the compositing failure DR-172 attributed it to — which is why the flag was reverted rather than fixed. Both the overlay and the native branch date from the original POC commit, so the native path has never been able to reveal itself; the 2026-08-11 device verification predates neither and does not contradict this, since a spike run that never reached a steady state would not have shown it. The backend's own events are the equivalent signals and `nativeSignalRevealsVideo` is the rule for reading them: `state === "playing"` mirrors the element's `playing` event, and a position tick carrying a real position or duration mirrors the `readyState` backstops, covering a first state event that is dropped or arrives before the listener is attached. `buffering`/`paused`/`stopped`/`error` deliberately do not qualify — revealing on `error` would replace the title card with a transparent hole showing the launcher through the app. The rule is a pure module rather than a branch inside the component because the decision that was missing is exactly the part worth guarding, and the component needs a DOM and a mounted player to exercise | UI | UR-003, UR-004, UR-041 | Done |
+| DR-183 | The JavaScript bridges are installed before the page that uses them loads. WebView binds an injected object into JS at **page-load time**: an `addJavascriptInterface` call landing after the page has loaded does not appear to that page. They were installed from `configureWebViewForMedia`, which finds the WebView by walking the view tree 500 ms after `onCreate` — a race against Tauri's own page load, and one that is *permanent* when lost, because the identity guard added for DR-097's stale-proxy bug then declines to re-inject on every later resume pass. The whole set (`AndroidVideoSurface`, `AndroidPictureInPicture`, `AndroidBackgroundAudio`, `AndroidNetworkType`, `AndroidImmersive`, `AndroidInsets`) would simply be absent from `window`, and silently: every call site optional-chains the bridge, so a missing one is a no-op rather than an error. This is a candidate explanation for DR-172's other piece of evidence — `WebView transparent = false` logged, `= true` never appearing, i.e. the enable call never reaching Kotlin at all. `WryActivity.setWebView()` calls the `onWebViewCreate` hook immediately before wry issues the first `loadUrl` (confirmed in wry 0.55's `main_pipe.rs`, where the `setWebView` JNI call precedes `load_url`), so a bridge installed there is bound by the time any page runs. The hook can fire during `super.onCreate()`, before the rest of our own `onCreate`, so only work needing nothing but the WebView moves into it — insets stay in `configureWebViewForMedia`, which runs later and on every resume. The tree-walk path is kept as a fallback, and `enableNativeVideoCompositing` now logs an explicit error when the bridge is missing, so the ambiguity that left DR-172 unresolved cannot recur silently | Android | UR-003, UR-004, UR-040, UR-041 | Done |
+| DR-184 | The video SurfaceView leaves the view hierarchy when the video does. `VideoOverlayManager.detachVideoSurface` had **no callers anywhere in the tree** — the mirror of the DR-151 defect, where `setActivity` had none — so `attachVideoSurface` was one-way: `JellyTauPlayer.clearVideoSurface()` dropped its `surfaceView` reference and cleared ExoPlayer's without removing the view, leaving it parented to the content view for the life of the process, with the next native video adding another SurfaceView beneath it. The stack was invisible while the WebView was opaque, which is why it went unnoticed. Two consequences outlive the leak: `isVideoSurfaceAttached()` gates `PictureInPictureManager.canEnterPip` through `isNativeVideoPath()`, so it reported an attached surface forever after the first native video (saved from offering PiP over nothing only by the `isPlayingVideo()` check beside it), and every abandoned surface held its `OnLayoutChangeListener` on the content view. Detach is called from `clearVideoSurface`, which covers stop, the switch to audio, and the background-audio handoff, and always runs on the main thread because every caller is already inside a `mainHandler.post`. It removes the view from its *own* parent rather than looking the content view up from an Activity reference, so an Activity recreated underneath it cannot strand the view | Android | UR-003, UR-041 | Done |
+| DR-185 | The app shell stops painting over the video surface. `app.css` clears the page's opaque layers for native video through three selectors, and one of them — `html[data-native-video="active"] [data-app-shell]` — was written against an attribute **no component has ever set, in any commit**. The shell is `+layout.svelte`'s root `div`, which paints `--color-background` across the entire viewport; VideoPlayer is `fixed inset-0 z-50` and correctly makes *itself* transparent on the native path, but it stacks *above* the shell, so the WebView still composited the shell's opaque background over the whole screen and the SurfaceView behind it could never be seen. This is the missing half of the compositing DR-172 went looking for: the spec's own layer table lists this layer as "cleared by `data-native-video` → app.css", which was written but never wired, and `html`/`body` being genuinely transparent made the CSS look correct in isolation. The failure is invisible three ways over — the CSS is valid, the selector is plausible, and a rule matching nothing looks exactly like a rule matching something already transparent — while the symptom (black screen, audio fine) is identical to a real compositing failure, which is how it survived DR-150 through DR-172. Fixed by setting the attribute the rule was written for, and guarded by asserting the *relationship* rather than the rule: every attribute the compositing block targets must be set somewhere in the app, so a selector aimed at nothing fails the suite instead of failing silently on a device | UI | UR-003, UR-004, UR-041 | Done |
+| DR-186 | The play overlay comes down when the backend plays. `isPlaying` was assigned once from the `player_play_item` response and thereafter only by the `player://state-changed` listener — a channel the backend never emits, the same dead wire that DR-182's first fix was mistakenly hung on. On the native path the flag therefore froze at whatever the initial response said: with ExoPlayer playing, the UI still believed it was paused, so the `bg-black/30` play-button overlay stayed raised across the whole video area and the transport button kept showing ▶. The video was simultaneously dimmed and covered while it played, which reads as "the overlay never goes away" and is easily mistaken for a second compositing fault. The mirror reads the same `player` store `playerEvents.ts` feeds, which is what the architecture already says is authoritative — the player reports state, the UI consumes it — and is gated to the native path so HTML5 keeps its element-event wiring, which is authoritative there | UI | UR-003, UR-005 | Done |
+| DR-187 | The system bars go away with the player, not only with the fullscreen button. `enterImmersive()` had exactly one caller, `toggleFullscreen()`, so opening the player left the status and navigation bars painted over it until the user pressed a button most never press. On the native path this is worse than cosmetic: the SurfaceView fills the content view, so the bars sit directly on top of the video. The player is a full-screen surface by construction — `fixed inset-0 z-50` over a `MATCH_PARENT` surface — so entry is the right moment. Called synchronously in `onMount` before any `await`, per the native-mode pitfall, and paired with the `exitImmersive()` already unconditional in `onDestroy`, so a player torn down while immersive cannot leave the rest of the app without bars | UI | UR-066, UR-003 | Done |
+| DR-188 | Native Android video is **ready to be the default except for the background-audio handoff**, and the flip therefore waits. The picture defects behind DR-172 are all found, fixed and device-verified — DR-185 (the app shell painted over the surface through a CSS rule targeting an attribute nothing set), DR-182 (nothing could lift the poster card on a path with no `<video>` element), DR-183 (the JS bridges raced the page load, so `setTransparent(true)` could never arrive), DR-184 (the SurfaceView was never detached), plus DR-186 and DR-187, the two UI defects only this path could reveal. On a device logcat now carries `WebView transparent = true` and `Marking media ready` with video on screen, which is the pair DR-172 went looking for and could not find, and skip, seek and rotation were exercised by hand. Turning the default on then surfaced a *different* unverified sub-path: returning from background audio is HTML5-only (DR-190), so on the native path playback simply stays dead. Shipping it would have repeated DR-161 exactly — a verified sub-path made default over an unverified one — so the default stays off and the flip is gated on DR-190 rather than on more confidence | UI | UR-003, UR-004, UR-041 | Blocked by DR-190 |
+| DR-191 | The WebView overlay keeps repainting over the native video surface. With the ExoPlayer SurfaceView composited *under* a transparent WebView, the WebView's ordinary damage stopped reaching the screen: the page went on mutating — the clock text every second, the control bar's opacity going to 0 — while the display kept showing whatever frame the overlay last presented, over video that animated perfectly. It reads as three separate bugs (a frozen progress bar, controls that will not fade, overlays that linger) and is one. It is not a state defect: reading the live DOM over the devtools socket showed the slider advancing 476 → 479 across three seconds while the screen showed neither value. **Structural** changes do get through — injecting a single element made the whole overlay catch up at once, jumping the displayed clock from 6:39 to 19:35 — which is also why the play overlay always appeared to work: it lives in an `{#if}` block and is added and removed from the DOM, while the progress bar only changes text and the control bar only changes a class. A CSS animation does not help, because opacity animates on the compositor without repainting the layer. The redraw is therefore driven from the Activity, via `postInvalidateOnAnimation` so it rides vsync rather than outpacing the frames it asks for, started and stopped with the compositing itself so the cost belongs to native video playback, which is already decoding. This is a workaround for platform compositing behaviour rather than a fix for a defect of ours, and is deliberately narrow and self-cancelling | Android | UR-003, UR-004 | Done |
+| DR-190 | The background-audio handoff can return to the native path. Everything that restores playback on the way back is written around the WebView `<video>`: `applyPendingForegroundSeek` returns early on `!videoElement`, the HLS re-init `$effect` returns early on `!useHtml5Element`, and `pendingForegroundSeek`/`pendingForegroundPlay` — which own the post-handoff position and play/pause — are consumed only by `handleCanPlay` and `markMediaReady`, an element event and a path that reaches the same guard. On the native path there is no element, so `exitBackgroundAudioHandoff` completes, clears `handoffState`, blanks and reassigns `currentStreamUrl` to force an effect that will not run, and nothing ever restarts ExoPlayer: the user returns from the lockscreen to a dead player. This never showed while the path was opt-in and its picture was invisible anyway. The return needs the native equivalent of the element reload — re-issue the item to the backend, seek to the position `player_exit_background_audio` reports, then honour `wasPlaying` — routed through the adapter rather than the element, so both paths restore through one contract | Playback | UR-040, UR-003 | Proposed |
 | DR-161 | Native video is the default, so picture-in-picture has a real surface. DR-160 makes PiP work on the HTML5 path, but that path can only ever shrink the *UI* into the PiP window; showing the video itself needs the SurfaceView behind the WebView, which is what `experimentalNativeVideo` gates. The flag now defaults to on when the user has never chosen, with an explicit stored choice still winning in both directions so anyone who turned it off keeps it off. This is a deliberate acceptance of risk: the flag existed because the native path was an unfinished spike, and `VideoPlayer.scrubRegression.test.ts` documents its history — a native init that flipped to HTML5 mid-lifecycle and left seeks going down one path while ExoPlayer played on another. Those tests pin the **flag-off** interim override (native response overridden to HTML5, backend stopped once), which the default no longer selects, so they now mock the flag off rather than inherit it: they still guard that path, but they no longer describe what ships. The native scrub/seek path is consequently not covered by the suite and needs device verification | UI | UR-041, UR-003 | Needs device verification |
 | DR-159 | The background-audio handoff stops leaking its relative timeline. The handoff plays the episode as a *relative* stream — the audio-only URL is built with `StartTimeTicks` = the position the screen was locked at, so ExoPlayer's zero is the handoff point — and `background_audio_base` holds the offset that turns one back into a real position. The base was a **display-only** correction, applied in exactly two places (the lockscreen scrubber and the internal truncation maths) while every other consumer worked in the relative timeline treating the number as absolute. Each crossing threw away exactly `base` seconds, which is why the jump-back distance varied with where the screen was locked and read as random. Three crossings were live: progress reporting to Jellyfin sent the relative position every 30s, so the server was told `real − base` — and since DR-155 now mirrors the server's position back and refreshes on a cache hit, that regressed value returned as the resume point (lock at 40 min, listen to 90, reopen at 50); lockscreen seeks went out absolute and came back relative, against a chunked length-less transcode that cannot honour a seek at all, so a clamped seek landed at stream zero; and media3's own `seekToDefaultPosition`/`seekBack`/`seekForward` bypassed the `ForwardingPlayer` wrapper entirely, reaching the real ExoPlayer — `Util.handlePlayButtonAction` seeking an ended player to the relative zero being the same mechanism as DR-129's truncation bug through a different door. The fix converts **once, at the boundary**: `JellyTauPlayer`'s position tick adds the base (and shifts the duration with it, since the stream's own length is only what remains) before either `nativeOnPositionUpdate` or the lockscreen sees it, so position updates, progress reports, the frontend and the truncation check all speak the episode's timeline and none needs to know a handoff happened. The base is consequently *removed* from `claim_stream_resume`, `truncated_stream_resume_position` and `player_exit_background_audio`, where adding it now double-counts, and the lockscreen's `positionOffsetMs` addition goes with it (the field remains, read-only, as the tick's input). Inbound seeks go the other way: `seek_absolute` is the new boundary for every outside seek, re-opening the stream at the requested position via `resume_stream_at` when a handoff is active — which is what `onSeekTo` had claimed for months in a comment describing code that did not exist — and an ordinary seek otherwise. `seekToDefaultPosition` is swallowed rather than forwarded, since Rust already owns what "play after the stream ended" means and the `play()` that follows reaches it. Exit reads the position *before* clearing either base, or a tick landing in between hands back a relative one | Player | UR-040, UR-005, UR-025 | Done (pending device verification) |
 | DR-158 | A watched toggle, on the episode row, the season header, the series and movie hero, and the Episode Focus View. Both halves of the backend already existed and neither had a caller: `mark_played` (`POST /PlayedItems`) was reachable only from the sync drain replaying rows the *reporter* had queued, and `clear_watch_history` (`DELETE /PlayedItems`) only from the destructive "erase this series' history" button — so the sole way to mark something watched was to play it. Jellyfin applies both recursively over a season or series, so the container case needs no client-side fan-out *online*. Offline it does: `storage_set_watched` writes the item **and its descendants** (drawn from `items` by `parent_id`/`album_id`/`season_id`/`series_id`, so an uncached id selects nothing and the statement no-ops instead of raising a foreign-key error), because otherwise marking a season watched with no server would tick the season and leave every episode inside it unwatched. It is deliberately separate from `storage_mark_played`, which stays the single-item "this finished playing" path that increments `play_count`. Un-marking clears the resume position as well as the flag, matching the server. `QueuedOp::MarkUnplayed` gives the queue the missing direction — pushing as `clear_watch_history` — so the toggle works offline both ways rather than only one; without it un-marking would have been the half that needed a connection. The button is an everyday toggle, so unlike `ClearHistoryButton` it does not confirm, and it holds an optimistic state because the caller's `watched` prop only catches up after a reload (a season means a round trip, during which the button would otherwise appear to ignore the tap) | UI | UR-073 | Done |
@@ -361,9 +370,9 @@ Internal architecture, components, and application logic.
 |----------|-------------------------|-------------------------|
 | UR-001 | IR-001, IR-002 | - |
 | UR-002 | IR-013 | DR-003, DR-012, DR-013, DR-014 |
-| UR-003 | IR-003, IR-004, IR-011 | DR-002, DR-004, DR-010 |
-| UR-004 | IR-003, IR-004, IR-008, IR-011 | DR-002, DR-004, DR-006, DR-129, DR-171, DR-176, DR-177, DR-181 |
-| UR-005 | - | DR-001, DR-005, DR-009, DR-178, DR-179 |
+| UR-003 | IR-003, IR-004, IR-011 | DR-002, DR-004, DR-010, DR-182, DR-183, DR-184, DR-185, DR-186, DR-187, DR-188, DR-190, DR-191 |
+| UR-004 | IR-003, IR-004, IR-008, IR-011 | DR-002, DR-004, DR-006, DR-129, DR-171, DR-176, DR-177, DR-181, DR-182, DR-183, DR-185, DR-188 |
+| UR-005 | - | DR-001, DR-005, DR-009, DR-178, DR-179, DR-186 |
 | UR-006 | IR-005, IR-006, IR-007, IR-008 | - |
 | UR-007 | IR-010 | DR-007, DR-008, DR-016 |
 | UR-008 | IR-010 | DR-007, DR-011 |
@@ -398,8 +407,8 @@ Internal architecture, components, and application logic.
 | UR-037 | IR-010 | DR-042 |
 | UR-038 | IR-010 | DR-043 |
 | UR-039 | - | DR-045, DR-046 |
-| UR-040 | IR-025 | DR-051, DR-052, DR-129, DR-130, DR-159, DR-178, DR-179, DR-180 |
-| UR-041 | IR-026 | DR-053, DR-160, DR-161, DR-172 |
+| UR-040 | IR-025 | DR-051, DR-052, DR-129, DR-130, DR-159, DR-178, DR-179, DR-180, DR-183, DR-190 |
+| UR-041 | IR-026 | DR-053, DR-160, DR-161, DR-172, DR-182, DR-183, DR-184, DR-185, DR-188 |
 | UR-042 | IR-009, IR-014 | DR-054 |
 | UR-043 | IR-027 | DR-055 |
 | UR-044 | - | DR-056 |
@@ -423,7 +432,7 @@ Internal architecture, components, and application logic.
 | UR-063 | - | DR-105 |
 | UR-064 | - | DR-106 |
 | UR-065 | IR-030 | DR-108, DR-109, DR-110, DR-111 |
-| UR-066 | IR-031 | DR-112, DR-157 |
+| UR-066 | IR-031 | DR-112, DR-157, DR-187 |
 | UR-067 | - | DR-115, DR-116, DR-117, DR-118 |
 | UR-068 | - | DR-119 |
 | UR-069 | - | DR-113, DR-114, DR-120 |
@@ -619,6 +628,10 @@ Internal architecture, components, and application logic.
 | UT-147 | The native subtitle payload and the track-selection index come from the same resolved list: the wire shape keeps `mime_type` and stream order, `playerPlayItem` actually sends it, and the index is a position in the sent list (so a track whose URL failed to resolve cannot shift the others) rather than the menu's row number | UR-020, IR-016 | Done |
 | UT-182 | An HLS video URL never carries `StartTimeTicks` — with a position supplied or not — while the master playlist, codec, media source and chosen audio track still ride on it | DR-181 | Done |
 | UT-183 | A reloaded stream is resumed by seeking the element to the absolute position with the transcode offset cleared to zero — never by carrying the position as an offset base, which since DR-181 would display the position while playing the item from its start — and a reload to 0:00 waits for no seek | DR-181 | Done |
+| UT-184 | The native reveal rule fires on `state === "playing"` and on a position tick carrying a position or a duration, and on nothing else — not `buffering`, `paused`, `stopped`, `ended` or `error`, not an empty tick, and not a negative position | DR-182 | Done |
+| UT-187 | On the native path the play overlay follows the backend: it clears when the backend resumes after a pause and is raised again when the backend pauses, and the system bars are hidden on player entry rather than only by the fullscreen button | DR-186, DR-187 | Done |
+| UT-186 | Every attribute the native-video compositing block in app.css targets is set somewhere in the app — `[data-app-shell]` in particular — so a selector aimed at nothing fails the suite instead of failing silently on a device | DR-185 | Done |
+| UT-185 | Mounted on the native path (backend reports native, opt-in flag on, no `<video>` element rendered and the backend not stopped), VideoPlayer keeps the poster card up until the backend reports something, drops it on a playing state or a position tick with a duration, and keeps it up through `error` and `stopped` | DR-182 | Done |
 
 ### Integration Tests
 

docs/specs/android-native-video-spike.md

@@ -1,8 +1,12 @@
 # Spec: Android native video — transparent-webview spike
 
-**Status:** Spike succeeded — native video confirmed working on a physical
-device (2026-08-11) with `experimentalNativeVideo` on. Shipped behind that flag,
-default off. Branch `feat/android-native-video`.
+**Status:** Spike succeeded (2026-08-11); shipped behind `experimentalNativeVideo`,
+default off. Flipping that default shipped **audio with no picture** and was
+reverted (DR-172). Three defects behind that have since been fixed — DR-182
+(nothing on the native path could lift the poster overlay), DR-183 (the JS
+bridges raced the page load), DR-184 (the SurfaceView was never detached).
+Branch `fix/android-native-video-visible`. **The default stays off until the
+device criteria below are green.**
 
 **The spike's central question is answered: yes.** A `SurfaceView` *can* be
 composited behind a transparent Tauri WebView on Android. Nothing upstream
@@ -227,6 +231,9 @@ The spike is **complete** when one of these is true:
 - [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.
 - [x] `webviewAudio.ts` no longer inspects `navigator.userAgent`; the platform's audio backend is read from Rust (`player_get_capabilities` → `usesWebviewAudio`).
 - [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.
+- [x] The poster/title card comes down on the native path. It never could: every `markMediaReady()` call site is a `<video>` element event and the native branch renders no element, so an opaque `bg-black` overlay covered the ExoPlayer surface for the whole session. See DR-182; guarded by `mediaReady.test.ts` (UT-184) and `VideoPlayer.nativeReveal.test.ts` (UT-185), the latter written failing first.
+- [x] The `AndroidVideoSurface` bridge is installed before the page that calls it loads, via `WryActivity.onWebViewCreate` instead of a 500 ms tree walk, and a missing bridge now logs an error instead of no-oping. See DR-183.
+- [x] The SurfaceView is detached when video stops, instead of accumulating one leaked view per native video. See DR-184.
 - [ ] 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.
 - [ ] 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.
@@ -238,9 +245,26 @@ The spike is **complete** when one of these is true:
 - [ ] `nativeAdapter.ts:11-14` no longer cites tauri#10152.
 
 Either way:
-- [x] `bun run check` (0 errors), `bun run test` (892 passed), `bun run check:boundary` pass.
+- [x] `bun run check` (0 errors), `bun run test` (997 passed), `bun run check:boundary` pass.
 - [x] `cargo fmt` / `cargo clippy` clean (no new warnings); `cargo test` passes (603 lib + 7 doc).
 
+### Why the 2026-08-11 verification and DR-172 do not contradict each other
+
+The spike was reported working on device; the same path then shipped as audio
+with no picture. Both are consistent with DR-182: the poster overlay is drawn
+only while `isMediaReady` is false, and the native path has no way to set it, so
+what the surface shows depends entirely on **whether that overlay is on screen**
+— not on whether compositing works. Any run that reached the player through a
+path leaving `isMediaReady` already true (a handoff return, a re-render, a
+session that had previously played on the HTML5 path) shows video; a cold start
+into the native path never does. That is also why DR-172 read the symptom as a
+compositing failure: on screen the two are identical, and the one piece of
+evidence separating them — `WebView transparent = true` never being logged —
+points at DR-183 rather than at the compositing itself.
+
+**This reasoning is not yet device-confirmed.** It explains the reports and is
+backed by the code, but the criteria above are what settle it.
+
 > 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

scripts/extract-traces.test.ts

@@ -175,8 +175,8 @@ describe("live requirements.md", () => {
 
     expect(defined.UR).toBe(75);
     expect(defined.IR).toBe(32);
-    expect(defined.DR).toBe(172);
+    expect(defined.DR).toBe(181);
     expect(defined.JA).toBe(35);
-    expect(defined.total).toBe(314);
+    expect(defined.total).toBe(323);
   });
 });

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

@@ -10,6 +10,13 @@ import android.webkit.WebView
 import android.view.View
 import androidx.activity.enableEdgeToEdge
 
+/**
+ * How often to ask the WebView overlay to redraw while a native video surface is
+ * behind it. Roughly one display frame — `postInvalidateOnAnimation` coalesces
+ * to vsync, so this only governs how often we *ask*. See [MainActivity.overlayRepaint].
+ */
+private const val OVERLAY_REPAINT_MS = 16L
+
 class MainActivity : TauriActivity() {
   private val handler = Handler(Looper.getMainLooper())
   private var configAttempts = 0
@@ -52,6 +59,96 @@ class MainActivity : TauriActivity() {
    */
   private var bridgesInstalledOn: WebView? = null
 
+  /**
+   * wry hands us the WebView here, and this is the only point at which the
+   * bridges can be installed *deterministically*.
+   *
+   * WebView binds an injected object into JS at **page-load time**: an
+   * addJavascriptInterface call that lands after the page has loaded does not
+   * appear to that page at all. The bridges used to be installed from
+   * [configureWebViewForMedia], which finds the WebView by walking the view
+   * tree 500 ms after onCreate — a race against Tauri's own page load, and one
+   * that is *permanent* when lost, because the identity guard then declines to
+   * re-inject on the resume passes. The whole set (`AndroidVideoSurface`,
+   * `AndroidPictureInPicture`, `AndroidBackgroundAudio`, `AndroidNetworkType`,
+   * `AndroidImmersive`, `AndroidInsets`) simply would not exist in `window`,
+   * silently: every one of them is called through an optional chain, so a
+   * missing bridge is a no-op rather than an error. That is a candidate
+   * explanation for DR-172's central piece of evidence — native video shipped
+   * with `WebView transparent = false` logged and `= true` never appearing,
+   * i.e. the enable call never reaching Kotlin.
+   *
+   * `WryActivity.setWebView()` calls this immediately before wry issues the
+   * first `loadUrl`, so a bridge installed here is bound by the time any page
+   * runs. Note this can fire during `super.onCreate()`, i.e. *before* the rest
+   * of our own onCreate — so only work that needs nothing but the WebView
+   * belongs here. Insets are deliberately left to
+   * [configureWebViewForMedia], which runs later and on every resume.
+   *
+   * TRACES: UR-003, UR-004 | DR-183
+   */
+  override fun onWebViewCreate(webView: WebView) {
+    super.onWebViewCreate(webView)
+    android.util.Log.d("MainActivity", "onWebViewCreate - installing bridges before first page load")
+    mediaWebView = webView
+    installJavascriptBridges(webView)
+    configureWebViewSettings(webView)
+  }
+
+  /**
+   * Keeps the WebView overlay repainting while a native video surface is behind
+   * it. Null when not running.
+   *
+   * With the ExoPlayer SurfaceView composited *under* a transparent WebView, the
+   * WebView's ordinary damage stops reaching the screen: the page kept mutating
+   * — the clock text changing every second, the control bar's opacity going to
+   * 0 — and none of it appeared, while the video underneath animated fine. The
+   * overlay froze on whatever frame it last managed to present, which is why the
+   * progress bar "stayed there and did not update" and the controls would not
+   * fade. It is not a state bug: reading the DOM over the devtools socket showed
+   * the slider value advancing (476 → 479 over three seconds) behind a screen
+   * showing neither.
+   *
+   * A *structural* change did force it through — injecting one element made the
+   * whole overlay catch up at once, jumping the displayed clock from 6:39 to
+   * 19:35 — so the pixels are reachable; it is the incremental damage that gets
+   * dropped. A CSS animation does not do it: opacity animates on the compositor
+   * without repainting the layer, which is exactly why that attempt changed
+   * nothing.
+   *
+   * So the redraw is driven from here instead. `postInvalidateOnAnimation`
+   * rather than a fixed-rate timer, so it rides the display's vsync and cannot
+   * outpace the frames it is asking for, and it runs *only* while compositing is
+   * on — the cost belongs to native video playback, which is already decoding.
+   *
+   * This is a workaround for platform compositing behaviour, not a fix for a
+   * defect of ours; the honest form of it is narrow and self-cancelling.
+   *
+   * TRACES: UR-003, UR-004 | DR-191
+   */
+  private var overlayRepaint: Runnable? = null
+
+  private fun startOverlayRepaint() {
+    if (overlayRepaint != null) return
+    val tick = object : Runnable {
+      override fun run() {
+        val webView = mediaWebView ?: return
+        webView.postInvalidateOnAnimation()
+        // Re-post through the same field so stopOverlayRepaint() can cancel it.
+        overlayRepaint?.let { handler.postDelayed(it, OVERLAY_REPAINT_MS) }
+      }
+    }
+    overlayRepaint = tick
+    handler.post(tick)
+    android.util.Log.d("MainActivity", "Overlay repaint started")
+  }
+
+  private fun stopOverlayRepaint() {
+    overlayRepaint?.let { handler.removeCallbacks(it) }
+    overlayRepaint = null
+    android.util.Log.d("MainActivity", "Overlay repaint stopped")
+  }
+
   override fun onCreate(savedInstanceState: Bundle?) {
     enableEdgeToEdge()
     super.onCreate(savedInstanceState)
@@ -165,7 +262,9 @@ class MainActivity : TauriActivity() {
 
   private fun configureWebViewForMedia() {
     try {
-      val webView = findWebView(window.decorView)
+      // onWebViewCreate normally got here first; the tree walk is the fallback
+      // for a WebView we were never handed.
+      val webView = mediaWebView ?: findWebView(window.decorView)
 
       if (webView == null) {
         android.util.Log.w("MainActivity", "WebView not found (attempt ${configAttempts + 1}/$maxConfigAttempts)")
@@ -183,33 +282,47 @@ class MainActivity : TauriActivity() {
       android.util.Log.d("MainActivity", "WebView found! Configuring settings...")
       mediaWebView = webView
 
-      // Register the @JavascriptInterface bridges EXACTLY ONCE per WebView.
-      //
-      // configureWebViewForMedia() runs from onCreate's delayed post AND from
-      // every onResume (plus each WebView re-find), so this used to re-inject
-      // all four bridges repeatedly - 5 times in a 45s session. WebView binds
-      // injected objects at page-load time; re-injecting over a live page
-      // leaves JS holding a stale proxy. The object stays truthy while its
-      // methods vanish, which surfaced as a flood of
-      // "WebView: Unknown object" chromium errors and, in JS,
-      // "TypeError: setEnabled is not a function".
-      //
-      // The visible bug: the background-audio toggle turned blue but never
-      // reached native, so backgroundAudioEnabled stayed false, onStop never
-      // dispatched 'jellytau-background', and a locked screen killed audio
-      // instantly (UR-040). Audio focus and PiP broke the same way.
-      //
-      // The settings/WebChromeClient work below is idempotent and must keep
-      // running on resume; only the bridge injection is one-shot.
-
       // Re-push the safe-area insets. Unlike addJavascriptInterface this is
       // idempotent and MUST re-run: a page load discards the inline style the
       // last push set, so the WebView would otherwise be left with no insets.
       WindowInsetsBridge.attachWebView(webView)
 
+      // Normally already done by onWebViewCreate; this is the fallback path.
+      installJavascriptBridges(webView)
+      configureWebViewSettings(webView)
+
+    } catch (e: Exception) {
+      android.util.Log.e("MainActivity", "Failed to configure WebView for media", e)
+    }
+  }
+
+  /**
+   * Register the @JavascriptInterface bridges EXACTLY ONCE per WebView.
+   *
+   * This runs from [onWebViewCreate] — the only point early enough to be bound
+   * before the first page load — and from [configureWebViewForMedia] as a
+   * fallback. The latter runs from onCreate's delayed post AND from every
+   * onResume (plus each WebView re-find), so without the identity guard this
+   * re-injected every bridge repeatedly — 5 times in a 45s session. WebView
+   * binds injected objects at page-load time; re-injecting over a live page
+   * leaves JS holding a stale proxy. The object stays truthy while its methods
+   * vanish, which surfaced as a flood of "WebView: Unknown object" chromium
+   * errors and, in JS, "TypeError: setEnabled is not a function".
+   *
+   * The visible bug: the background-audio toggle turned blue but never reached
+   * native, so backgroundAudioEnabled stayed false, onStop never dispatched
+   * 'jellytau-background', and a locked screen killed audio instantly (UR-040).
+   * Audio focus and PiP broke the same way.
+   *
+   * Settings/WebChromeClient work is idempotent and must keep running on
+   * resume, so it lives in [configureWebViewSettings], not here.
+   *
+   * TRACES: UR-003, UR-004, UR-040, UR-041 | DR-183
+   */
+  private fun installJavascriptBridges(webView: WebView) {
+    try {
       if (webView === bridgesInstalledOn) {
         android.util.Log.d("MainActivity", "JS bridges already installed on this WebView - skipping re-injection")
-        configureWebViewSettings(webView)
         return
       }
       bridgesInstalledOn = webView
@@ -329,6 +442,7 @@ class MainActivity : TauriActivity() {
               android.graphics.drawable.ColorDrawable(color)
             )
             android.util.Log.d("MainActivity", "WebView transparent = $transparent")
+            if (transparent) startOverlayRepaint() else stopOverlayRepaint()
           }
         }
 
@@ -371,10 +485,8 @@ class MainActivity : TauriActivity() {
         dispatchWebEvent("jellytau-network-changed")
       }
 
-      configureWebViewSettings(webView)
-
     } catch (e: Exception) {
-      android.util.Log.e("MainActivity", "Failed to configure WebView for media", e)
+      android.util.Log.e("MainActivity", "Failed to install JavaScript bridges", e)
     }
   }
 

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

@@ -77,16 +77,29 @@ object VideoOverlayManager {
     }
 
     /**
-     * Detach the video SurfaceView from the Activity's view hierarchy.
+     * Detach the video SurfaceView from the view hierarchy.
      *
-     * @param activity The Activity to detach the surface from
+     * Must be called on the main thread.
+     *
+     * This had **no callers at all**, which made [attachVideoSurface] one-way:
+     * `JellyTauPlayer.clearVideoSurface()` dropped its `surfaceView` reference
+     * without removing the view, so every native video left its SurfaceView
+     * parented to the content view for the life of the process and the next one
+     * added another beneath it. The stack was invisible while the WebView was
+     * opaque, and [isVideoSurfaceAttached] — which gates
+     * `PictureInPictureManager.canEnterPip` — stayed true forever afterwards.
+     *
+     * Removes from the view's *own* parent rather than looking the content view
+     * up from an Activity, so it cannot leave a view behind when the Activity
+     * has been recreated under it.
+     *
+     * TRACES: UR-003, UR-041 | DR-184
      */
-    fun detachVideoSurface(activity: Activity) {
+    fun detachVideoSurface() {
         try {
             removeLayoutListener()
             attachedSurfaceView?.let { surfaceView ->
-                val contentView = activity.window.decorView.findViewById<ViewGroup>(android.R.id.content)
-                contentView.removeView(surfaceView)
+                (surfaceView.parent as? ViewGroup)?.removeView(surfaceView)
                 attachedSurfaceView = null
                 android.util.Log.d("VideoOverlayManager", "Video surface detached from view hierarchy")
             }

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

@@ -1228,14 +1228,25 @@ class JellyTauPlayer(private val appContext: Context) {
     }
 
     /**
-     * Clear the video surface when switching to audio playback.
+     * Clear the video surface when switching to audio playback, or on stop.
+     *
+     * Detaching is not optional bookkeeping: dropping the reference without
+     * removing the view left the SurfaceView parented to the content view for
+     * the life of the process, and the next video stacked another one under it.
+     * See VideoOverlayManager.detachVideoSurface.
+     *
+     * Always called on the main thread (every caller runs inside a
+     * `mainHandler.post`), which is what touching the view hierarchy requires.
+     *
+     * TRACES: UR-003, UR-041 | DR-184
      */
     private fun clearVideoSurface() {
         surfaceView?.let {
             exoPlayer.clearVideoSurface()
+            com.dtourolle.jellytau.VideoOverlayManager.detachVideoSurface()
             surfaceView = null
             surfaceHolder = null
-            android.util.Log.d("JellyTauPlayer", "Video surface cleared")
+            android.util.Log.d("JellyTauPlayer", "Video surface cleared and detached")
         }
     }
 

src/lib/components/player/VideoPlayer.nativeReveal.test.ts

@@ -0,0 +1,306 @@
+/**
+ * VideoPlayer native-path reveal tests (Android / ExoPlayer)
+ *
+ * Reproduces "native video plays as audio with no picture" (DR-172).
+ *
+ * The poster/title card is an opaque `bg-black` overlay drawn while
+ * `isMediaReady` is false. Every signal that clears it — `canplay`,
+ * `loadedmetadata`, hls.js `FRAG_BUFFERED`, the `playing` event and two
+ * `readyState` timeouts — comes from the HTML5 `<video>` element. On the native
+ * path there is no such element, so nothing ever cleared it: ExoPlayer decoded
+ * and fed its SurfaceView correctly the whole time, behind a black div.
+ *
+ * These tests pin the **flag-on** path: the backend reports native, the user
+ * opted in, and the video area must be revealed by the *backend's* own signals.
+ *
+ * TRACES: UR-003, UR-004, UR-041 | DR-182 | UT-185
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ---- Mocks (must precede component import) --------------------------------
+
+const channelHandlers: Record<string, (event: any) => void> = {};
+
+// The native path is what these tests guard, so the opt-in flag is mocked ON.
+// Stated explicitly rather than inherited: the default has moved twice
+// (DR-161 on, DR-172 off) and a test that inherits it silently changes meaning.
+vi.mock("$lib/stores/nativeVideo", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("$lib/stores/nativeVideo")>();
+  return {
+    ...actual,
+    experimentalNativeVideo: {
+      subscribe: (run: (v: boolean) => void) => {
+        run(true);
+        return () => {};
+      },
+      set: () => {},
+      current: () => true,
+    },
+  };
+});
+
+vi.mock("@tauri-apps/api/event", () => ({
+  listen: vi.fn(async (channel: string, handler: any) => {
+    channelHandlers[channel] = handler;
+    return () => {
+      delete channelHandlers[channel];
+    };
+  }),
+}));
+
+vi.mock("@tauri-apps/api/core", () => ({
+  invoke: vi.fn(),
+}));
+
+const playerPlayItem = vi.fn(async () => ({
+  // What Android reports: native ExoPlayer backend, no HTML5 element.
+  useHtml5Element: false,
+  backend: "exoplayer",
+  state: { kind: "playing" },
+}));
+const playerStop = vi.fn(async () => ({}));
+
+vi.mock("$lib/api/bindings", () => ({
+  commands: {
+    playerPlayItem: (...a: any[]) => playerPlayItem(...(a as [])),
+    playerStop: (...a: any[]) => playerStop(...(a as [])),
+    playerSeek: vi.fn(async () => ({})),
+    playerPlay: vi.fn(async () => ({})),
+    playerPause: vi.fn(async () => ({})),
+    playerToggle: vi.fn(async () => ({ state: "playing" })),
+    playerSeekVideo: vi.fn(async (_h: string, position: number) => ({
+      strategy: "native",
+      position,
+    })),
+    playerSetSubtitleTrack: vi.fn(async () => ({})),
+    playerSwitchAudioTrack: vi.fn(async () => ({})),
+    playerSetSleepTimer: vi.fn(async (mode: any) => ({ mode, remainingSeconds: 0 })),
+    playerCancelSleepTimer: vi.fn(async () => ({
+      mode: { kind: "off" },
+      remainingSeconds: 0,
+    })),
+    playerGetStreamingQualities: vi.fn(async () => []),
+    playerGetVideoSettings: vi.fn(async () => ({ streamingQuality: "original" })),
+    storageGetSeriesAudioPreference: vi.fn(async () => null),
+    storageSaveSeriesAudioPreference: vi.fn(async () => ({})),
+  },
+  events: {
+    playerStatusEvent: { listen: vi.fn(async () => () => {}) },
+  },
+}));
+
+vi.mock("$lib/stores/auth", () => ({
+  auth: {
+    getUserId: () => "user-1",
+    getRepository: () => ({
+      getHandle: () => "repo-1",
+      getSubtitleUrl: async () => "",
+      jrayActorsAt: async () => [],
+    }),
+  },
+}));
+
+vi.mock("$app/navigation", () => ({
+  goto: vi.fn(),
+}));
+
+// The immersive bridge is native-only; assert the call rather than its effect.
+const enterImmersive = vi.fn();
+vi.mock("$lib/utils/immersive", () => ({
+  enterImmersive: (...a: any[]) => enterImmersive(...a),
+  exitImmersive: vi.fn(),
+  isImmersiveSupported: () => true,
+}));
+
+import { render, waitFor } from "@testing-library/svelte";
+import { tick } from "svelte";
+import VideoPlayer from "./VideoPlayer.svelte";
+import { player } from "$lib/stores/player";
+import type { MediaItem } from "$lib/api/types";
+
+function makeEpisode(): MediaItem {
+  return {
+    id: "ep1",
+    name: "Episode 1",
+    kind: "episode",
+    durationMs: 24 * 60 * 1000,
+  } as MediaItem;
+}
+
+async function mountNativePlayer() {
+  const utils = render(VideoPlayer, {
+    props: {
+      media: makeEpisode(),
+      streamUrl: "http://server/videos/ep1/master.m3u8",
+      mediaSourceId: "src-1",
+      needsTranscoding: false,
+      onClose: vi.fn(),
+    },
+  });
+
+  await waitFor(() => expect(playerPlayItem).toHaveBeenCalled());
+  // The native path must NOT be overridden to HTML5 and must NOT be stopped —
+  // if it were, these tests would be guarding the HTML5 path by accident.
+  await waitFor(() =>
+    expect(utils.container.querySelector("video")).toBeNull()
+  );
+  expect(playerStop).not.toHaveBeenCalled();
+  return utils;
+}
+
+/** The opaque poster/title card drawn while the media is not yet revealed. */
+function poster(container: HTMLElement): HTMLElement | null {
+  return container.querySelector('[data-testid="video-poster"]');
+}
+
+/**
+ * Report backend playback state the way the app actually does.
+ *
+ * NOT via `player://position-update` / `player://state-changed`: those channels
+ * are **never emitted by the backend**, which is exactly the trap this test
+ * exists to avoid. An earlier version of it fired those handlers by hand, went
+ * green, and guarded nothing — on the device the poster stayed up while
+ * ExoPlayer played behind it. `playerEvents.ts` feeds the `player` store, and
+ * the store is what the component must read.
+ */
+async function backendReports(
+  kind: "playing" | "paused" | "error",
+  position = 0,
+  duration = 0
+) {
+  const media = makeEpisode();
+  if (kind === "playing") player.setPlaying(media, position, duration);
+  else if (kind === "paused") player.setPaused(media, position, duration);
+  else player.setError("Decoder failed", media);
+  await tick();
+}
+
+describe("VideoPlayer native path reveals the video (DR-172)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    for (const key of Object.keys(channelHandlers)) delete channelHandlers[key];
+    player.setIdle();
+  });
+
+  it("keeps the poster up until the backend reports something", async () => {
+    const { container } = await mountNativePlayer();
+    // Nothing has been heard from ExoPlayer yet, so the title card is correct.
+    expect(poster(container)).not.toBeNull();
+  });
+
+  it("clears the poster when the backend reports playing", async () => {
+    const { container } = await mountNativePlayer();
+
+    await backendReports("playing", 0, 1440);
+
+    // The surface is rendering behind the webview; an opaque overlay over it is
+    // exactly the "audio with no picture" defect.
+    await waitFor(() => expect(poster(container)).toBeNull());
+  });
+
+  it("clears the poster when the backend reports a paused position with a duration", async () => {
+    const { container } = await mountNativePlayer();
+
+    // Backstop for a backend that starts paused: a position carrying a real
+    // duration means the media is loaded and the surface has content,
+    // mirroring the HTML5 readyState fallback.
+    await backendReports("paused", 12, 1440);
+
+    await waitFor(() => expect(poster(container)).toBeNull());
+  });
+
+  it("clears the play overlay when the backend resumes after a pause (DR-186)", async () => {
+    const { container } = await mountNativePlayer();
+
+    await backendReports("paused", 5, 1440);
+    await waitFor(() =>
+      expect(container.querySelector('[data-testid="play-overlay"]')).not.toBeNull()
+    );
+
+    await backendReports("playing", 6, 1440);
+
+    // This overlay is `bg-black/30` across the whole video area: left up, it
+    // both dims and covers the ExoPlayer surface while it plays. Before the
+    // mirror, nothing after init could take it down, because the only other
+    // writer was the never-emitted `player://state-changed` channel.
+    await waitFor(() =>
+      expect(container.querySelector('[data-testid="play-overlay"]')).toBeNull()
+    );
+  });
+
+  it("raises the play overlay again when the backend reports paused (DR-186)", async () => {
+    const { container } = await mountNativePlayer();
+
+    await backendReports("playing", 5, 1440);
+    await waitFor(() =>
+      expect(container.querySelector('[data-testid="play-overlay"]')).toBeNull()
+    );
+
+    await backendReports("paused", 6, 1440);
+
+    // The mirror has to work in both directions, or pausing leaves no affordance
+    // to resume.
+    await waitFor(() =>
+      expect(container.querySelector('[data-testid="play-overlay"]')).not.toBeNull()
+    );
+  });
+
+  it("hides the system bars on entry, not only on the fullscreen button (DR-187)", async () => {
+    await mountNativePlayer();
+
+    // The player owns the whole screen; on the native path the system bars would
+    // otherwise sit directly on top of the ExoPlayer surface.
+    expect(enterImmersive).toHaveBeenCalled();
+  });
+
+  it("hides the control bar once playback starts, however late (DR-189)", async () => {
+    // Reproduce the device sequence: the backend is still starting when the
+    // player mounts, so playback begins *after* the first countdown window.
+    playerPlayItem.mockResolvedValueOnce({
+      useHtml5Element: false,
+      backend: "exoplayer",
+      state: { kind: "loading" },
+    } as any);
+    vi.useFakeTimers();
+    try {
+      const utils = render(VideoPlayer, {
+        props: {
+          media: makeEpisode(),
+          streamUrl: "http://server/videos/ep1/master.m3u8",
+          mediaSourceId: "src-1",
+          needsTranscoding: false,
+          onClose: vi.fn(),
+        },
+      });
+      await vi.advanceTimersByTimeAsync(50);
+
+      // The three seconds after entry elapse while the backend is still
+      // starting, so the bar correctly stays up. This is the exact window that
+      // defeated the first attempt: a one-shot timer armed on entry fired here,
+      // declined, and was never re-armed.
+      await vi.advanceTimersByTimeAsync(3500);
+      expect(utils.container.querySelector("[data-player-controls]")?.className).not.toContain("opacity-0");
+
+      // Playback starts late; the countdown has to restart on its own.
+      player.setPlaying(makeEpisode(), 5, 1440);
+      await vi.advanceTimersByTimeAsync(3500);
+
+      await vi.waitFor(() =>
+        expect(utils.container.querySelector("[data-player-controls]")?.className).toContain("opacity-0")
+      );
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("does not clear the poster on an errored backend", async () => {
+    const { container } = await mountNativePlayer();
+
+    await backendReports("error");
+
+    // Revealing here would replace the title card with a transparent hole
+    // showing the launcher through the app.
+    expect(poster(container)).not.toBeNull();
+  });
+});

src/lib/components/player/VideoPlayer.svelte

@@ -25,7 +25,7 @@
     type RenderableSubtitleTrack,
   } from "./subtitleTracks";
   import { sleepTimerActive, sleepTimerExpiredSignal } from "$lib/stores/sleepTimer";
-  import { playbackPosition, playerState } from "$lib/stores/player";
+  import { playbackPosition, playbackDuration, playerState } from "$lib/stores/player";
   import * as html5Adapter from "$lib/player/html5Adapter";
   import { playerController } from "$lib/player";
   import {
@@ -40,6 +40,8 @@
     enableNativeVideoCompositing,
     disableNativeVideoCompositing,
   } from "$lib/utils/videoSurface";
+  import { nativeSignalRevealsVideo } from "./mediaReady";
+  import { shouldHideControls } from "./controlsVisibility";
   import {
     isPipSupported,
     enterPip,
@@ -154,7 +156,9 @@
   let pipListenerCleanup: (() => void) | null = null;
   let showSleepTimerModal = $state(false);
   let isBuffering = $state(false);
-  let controlsTimeout: ReturnType<typeof setTimeout> | null = null;
+  // Bumped by every reveal so the auto-hide effect restarts its countdown even
+  // when no other input to that decision changed (a tap during playback).
+  let lastControlsInteraction = $state(0);
   let seekOffset = $state(0); // Track offset when seeking in transcoded streams
   let isSeeking = $state(false);
   // Capture only the initial streamUrl prop; later prop changes are applied via
@@ -441,6 +445,88 @@
     }
   });
 
+  // Auto-hide the control bar.
+  //
+  // An `$effect` rather than a timer armed by input, because the conditions that
+  // *permit* hiding arrive on their own schedule. The first attempt armed a
+  // one-shot timer from `revealControls()` on entry; three seconds later
+  // playback had not started yet, `shouldHideControls` correctly declined, and
+  // nothing re-armed it — so the bar sat over the video for the whole film. The
+  // timer has to follow the state, not the input event.
+  //
+  // Re-runs whenever any input changes: each run cancels the previous timer, so
+  // starting playback, closing a menu or finishing a seek re-arms it, and
+  // pausing or opening a menu cancels it. `lastControlsInteraction` is read so a
+  // tap restarts the countdown even when nothing else changed.
+  //
+  // TRACES: UR-003, UR-066 | DR-189 | UT-188
+  $effect(() => {
+    void lastControlsInteraction;
+    if (!showControls) return;
+    if (
+      !shouldHideControls({
+        isPlaying,
+        isSeeking,
+        menuOpen: showAudioTrackMenu || showSubtitleMenu || showQualityMenu,
+      })
+    ) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      showControls = false;
+    }, 3000);
+    return () => clearTimeout(timer);
+  });
+
+  // Reveal the video on the native path.
+  //
+  // The poster/title card is opaque and covers the whole video area, so on this
+  // path it is the only thing between the viewer and the ExoPlayer surface —
+  // every other markMediaReady() call site is a `<video>` element event, and
+  // there is no `<video>` here.
+  //
+  // Driven from the same stores as the seek bar above, deliberately: the
+  // `player://position-update` and `player://state-changed` channels the native
+  // branch subscribes to are **never emitted by the backend** (see the comment
+  // on the effect above — the seek bar had to be moved off them for the same
+  // reason). Hooking the reveal to those channels looks right, passes a test
+  // that fires them by hand, and does nothing on a device.
+  //
+  // TRACES: UR-003, UR-004 | DR-182 | UT-185
+  $effect(() => {
+    if (useHtml5Element || isMediaReady) return;
+    const state = $playerState.kind;
+    const position = $playbackPosition;
+    const duration = $playbackDuration;
+    if (
+      nativeSignalRevealsVideo({ kind: "state", state }) ||
+      nativeSignalRevealsVideo({ kind: "position", position, duration })
+    ) {
+      markMediaReady();
+    }
+  });
+
+  // Mirror the backend's play/pause into the UI on the native path.
+  //
+  // `isPlaying` is assigned once from the player_play_item response and then
+  // only by the `player://state-changed` listener — a channel the backend never
+  // emits, exactly as for the reveal above. So on the native path it was
+  // whatever the initial response said, forever: with ExoPlayer playing, the UI
+  // still believed it was paused, which raised the `bg-black/30` play overlay
+  // over the video surface and left the transport button showing ▶. The video
+  // was both dimmed and covered while it played.
+  //
+  // The player is the authoritative source of playback state and the UI is a
+  // consumer of it (see the architecture docs), so this reads the same store
+  // `playerEvents.ts` feeds rather than tracking it locally. HTML5 keeps its own
+  // element-event wiring, which is authoritative for that path.
+  //
+  // TRACES: UR-003, UR-005 | DR-186 | UT-187
+  $effect(() => {
+    if (useHtml5Element) return;
+    isPlaying = $playerState.kind === "playing";
+  });
+
   // Set up HLS.js for HLS streams
   $effect(() => {
     if (!useHtml5Element || !videoElement || !currentStreamUrl) {
@@ -695,6 +781,21 @@
       nativeUnlisteners.push(subscribeAppForegrounded(exitBackgroundAudioHandoff));
     }
 
+    // The video player owns the whole screen, so the system bars go away with it
+    // — not only when the fullscreen button is pressed, which was the sole
+    // caller of enterImmersive(). The status and navigation bars stayed painted
+    // over the player on entry, and on the native path they sit directly on top
+    // of the ExoPlayer surface, which fills the content view.
+    //
+    // Synchronous, before any await, per the native-mode pitfall above. Paired
+    // with the unconditional exitImmersive() in onDestroy. (UR-066, DR-187)
+    enterImmersive();
+
+    // Arm the control-bar auto-hide on entry. Without this the bar only ever
+    // hides after the first pointer/touch event, which on a touchscreen meant
+    // "after the user happens to tap" — and before DR-189 wired touch up, never.
+    revealControls();
+
     // Initialize player via Rust - Rust will decide which backend to use based on platform
     if (media && currentStreamUrl) {
       try {
@@ -1676,18 +1777,25 @@
     return `${mins}:${secs.toString().padStart(2, "0")}`;
   }
 
-  function handleMouseMove() {
+  /**
+   * Show the control bar and arm its auto-hide.
+   *
+   * This used to be `handleMouseMove` and was wired *only* to the container's
+   * `onmousemove`. A touchscreen never fires `mousemove`, so on Android the
+   * timer was never armed and the bar stayed up for the whole film — hidden in
+   * plain sight while the native video surface was itself invisible. It is now
+   * armed on entry and on every touch interaction as well.
+   *
+   * TRACES: UR-003, UR-066 | DR-189 | UT-188
+   */
+  function revealControls() {
     showControls = true;
-    if (controlsTimeout) {
-      clearTimeout(controlsTimeout);
-    }
-    controlsTimeout = setTimeout(() => {
-      if (isPlaying) {
-        showControls = false;
-      }
-    }, 3000);
+    lastControlsInteraction = Date.now();
   }
 
+  // Kept as the mouse entry point; desktop still drives it from pointer motion.
+  const handleMouseMove = revealControls;
+
   async function seekRelative(seconds: number) {
     isSeeking = true;
 
@@ -1850,6 +1958,10 @@
     playerGestureActive = false;
     swipeGestureActive = false;
     swipeType = null;
+    // Touch is the only input on the platform this player mostly runs on, and
+    // it is what `mousemove` never covers: show the bar and re-arm its hide.
+    // (DR-189)
+    revealControls();
   }
 
   /**
@@ -2117,7 +2229,10 @@
 
     <!-- Title card with loading spinner (Loading state from DR-001) -->
     {#if !isMediaReady}
-      <div class="absolute inset-0 flex items-center justify-center bg-black">
+      <div
+        data-testid="video-poster"
+        class="absolute inset-0 flex items-center justify-center bg-black"
+      >
         <!-- Poster/Title Card -->
         {#if media?.imageId}
           <CachedImage
@@ -2196,6 +2311,7 @@
            See DR-098. -->
       <button
         data-player-surface
+        data-testid="play-overlay"
         class="absolute inset-0 flex items-center justify-center bg-black/30"
         onclick={handleSurfaceClick}
         aria-label="Play"

src/lib/components/player/controlsVisibility.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Control-bar auto-hide rule (DR-189).
+ *
+ * TRACES: UR-003, UR-066 | DR-189 | UT-188
+ */
+
+import { describe, it, expect } from "vitest";
+import { shouldHideControls } from "./controlsVisibility";
+
+const playing = { isPlaying: true, isSeeking: false, menuOpen: false };
+
+describe("shouldHideControls", () => {
+  it("hides the bar during uninterrupted playback", () => {
+    expect(shouldHideControls(playing)).toBe(true);
+  });
+
+  it("keeps the bar while paused", () => {
+    // A user who paused by tapping the surface has no other way back.
+    expect(shouldHideControls({ ...playing, isPlaying: false })).toBe(false);
+  });
+
+  it("keeps the bar while seeking", () => {
+    // The position readout is the point of the bar mid-seek.
+    expect(shouldHideControls({ ...playing, isSeeking: true })).toBe(false);
+  });
+
+  it("keeps the bar while a menu is open", () => {
+    // The menus are anchored to the bar; hiding it takes the open menu with it.
+    expect(shouldHideControls({ ...playing, menuOpen: true })).toBe(false);
+  });
+});

src/lib/components/player/controlsVisibility.ts

@@ -0,0 +1,40 @@
+/**
+ * When the player's control bar may auto-hide.
+ *
+ * TRACES: UR-003, UR-066 | DR-189 | UT-188
+ *
+ * The bar's hide timer used to be armed from exactly one place — the container's
+ * `onmousemove`. A touchscreen never fires `mousemove`, so on Android the timer
+ * was never set and the bar stayed on screen for the whole film. It went
+ * unnoticed while the video itself was invisible: with nothing to obscure, a
+ * permanent control bar looks like the UI, not like a defect.
+ *
+ * The decision is separated from the timer so it can be tested without a clock
+ * or a DOM: it is a rule about state, and the parts that were wrong here were
+ * the conditions, not the `setTimeout`.
+ */
+
+/** Everything that decides whether the bar may disappear right now. */
+export interface ControlsHideContext {
+  /** Hiding controls over a paused player strands the user with no affordance. */
+  isPlaying: boolean;
+  /** A seek in flight is exactly when the position readout is worth watching. */
+  isSeeking: boolean;
+  /** True while any of the track / subtitle / quality menus is open. */
+  menuOpen: boolean;
+}
+
+/**
+ * Whether the control bar may hide now.
+ *
+ * Requires playback to be running: a paused player keeps its controls, which is
+ * both the convention and the only way back for a user who paused by tapping.
+ * A menu open over the bar pins it too — the menus are anchored to the bar, so
+ * hiding it would take the open menu with it, mid-interaction.
+ */
+export function shouldHideControls(ctx: ControlsHideContext): boolean {
+  if (!ctx.isPlaying) return false;
+  if (ctx.isSeeking) return false;
+  if (ctx.menuOpen) return false;
+  return true;
+}

src/lib/components/player/mediaReady.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Native-path reveal rule (DR-182).
+ *
+ * TRACES: UR-003, UR-004 | DR-182 | UT-184
+ */
+
+import { describe, it, expect } from "vitest";
+import { nativeSignalRevealsVideo } from "./mediaReady";
+
+describe("nativeSignalRevealsVideo", () => {
+  it("reveals on the backend's playing state", () => {
+    expect(nativeSignalRevealsVideo({ kind: "state", state: "playing" })).toBe(true);
+  });
+
+  it.each(["buffering", "paused", "stopped", "ended", "error", "idle", ""])(
+    "leaves the poster up on state %s",
+    (state) => {
+      expect(nativeSignalRevealsVideo({ kind: "state", state })).toBe(false);
+    }
+  );
+
+  it("reveals on a position tick that carries a duration", () => {
+    expect(
+      nativeSignalRevealsVideo({ kind: "position", position: 0, duration: 1440 })
+    ).toBe(true);
+  });
+
+  it("reveals on a position tick that has advanced, even with no duration", () => {
+    // Live streams report no duration; an advancing position is still proof
+    // that the surface has content.
+    expect(
+      nativeSignalRevealsVideo({ kind: "position", position: 3.2, duration: 0 })
+    ).toBe(true);
+  });
+
+  it("leaves the poster up on an empty position tick", () => {
+    // A tick before anything is loaded proves nothing, and revealing here would
+    // show a transparent hole through the app.
+    expect(
+      nativeSignalRevealsVideo({ kind: "position", position: 0, duration: 0 })
+    ).toBe(false);
+  });
+
+  it("does not treat a negative position as progress", () => {
+    expect(
+      nativeSignalRevealsVideo({ kind: "position", position: -1, duration: 0 })
+    ).toBe(false);
+  });
+});

src/lib/components/player/mediaReady.ts

@@ -0,0 +1,48 @@
+/**
+ * When the video area may be revealed on the **native** (ExoPlayer) path.
+ *
+ * TRACES: UR-003, UR-004 | DR-182 | UT-184
+ *
+ * VideoPlayer draws an opaque `bg-black` poster/title card over the video area
+ * until `isMediaReady`. Every signal that clears it is emitted by the HTML5
+ * `<video>` element — `canplay`, `loadedmetadata`, hls.js `FRAG_BUFFERED`, the
+ * `playing` event, and two `readyState` timeouts. The native path has no such
+ * element, so on Android nothing ever cleared the card: ExoPlayer decoded to a
+ * live SurfaceView behind a black div, which is the "audio with no picture"
+ * report of DR-172 and is indistinguishable from a compositing failure.
+ *
+ * The backend's own events are the equivalent signals, and this is the rule for
+ * reading them. It is a pure function rather than a branch inside the component
+ * because the component cannot be exercised without a DOM and a mounted player,
+ * and this decision is exactly the part that was missing and needs a guard.
+ */
+
+/** A player event that might mean "the surface has a picture on it". */
+export type NativeRevealSignal =
+  | { kind: "state"; state: string }
+  | { kind: "position"; position: number; duration: number };
+
+/**
+ * Whether `signal` proves the native backend is rendering, and the poster card
+ * should therefore come down.
+ *
+ * Two signals qualify, mirroring the HTML5 path's primary event and its
+ * backstop:
+ *
+ *  - **`state === "playing"`** — the direct equivalent of the `<video>`
+ *    `playing` event. ExoPlayer reports this once it is actually drawing.
+ *  - **a position tick carrying a real position or duration** — the equivalent
+ *    of the `readyState` fallbacks. It covers a first state event that is
+ *    dropped or arrives before the listener is attached; a tick means the media
+ *    is loaded and the surface has content.
+ *
+ * Everything else — `buffering`, `paused`, `stopped`, `error` — leaves the card
+ * up. Revealing on `error` in particular would replace the title card with a
+ * transparent hole showing the launcher through the app.
+ */
+export function nativeSignalRevealsVideo(signal: NativeRevealSignal): boolean {
+  if (signal.kind === "state") {
+    return signal.state === "playing";
+  }
+  return signal.duration > 0 || signal.position > 0;
+}

src/lib/stores/nativeVideo.ts

@@ -27,31 +27,52 @@ const STORAGE_KEY = "jellytau-experimental-native-video";
 const NATIVE_VIDEO_ATTR = "data-native-video";
 
 /**
- * Whether the native path is on. **Off** unless the user turned it on.
+ * Whether the native path is on, defaulting to **on** when the user has never
+ * chosen.
  *
- * DR-161 briefly made this default to on, so picture-in-picture could shrink a
- * real video surface. On a device that shipped as **audio with no picture**:
- * ExoPlayer decoded correctly and fed its SurfaceView, but the SurfaceView sits
- * *behind* the WebView and the compositing that clears the opaque layers above it
- * never took effect — logcat showed `WebView transparent = false` and never
- * `= true`. So the video was rendering the whole time, behind the page.
+ * This default has moved three times, so the history is the documentation:
  *
- * That is the defect the flag existed to contain, and it is why the default is
- * back off: video working matters more than PiP showing the native surface, and
- * PiP still works without it via the HTML5 path (DR-160). Native video remains
- * available in Settings for anyone testing it.
+ *  - **off** while the path was a spike (DR-150).
+ *  - **on** for picture-in-picture (DR-161), which shipped as *audio with no
+ *    picture* — ExoPlayer decoded correctly into a live SurfaceView while the
+ *    page stayed opaque over it.
+ *  - **off** again (DR-172), which named the compositing as the suspect but did
+ *    not find it.
+ *  - **on** now, because the four defects behind that symptom were found and
+ *    each is fixed and verified on a device: the app shell painted over the
+ *    surface through a CSS rule targeting an attribute nothing set (DR-185); the
+ *    poster card had no way to lift on a path with no `<video>` element
+ *    (DR-182); the JS bridges raced the page load, so `setTransparent(true)`
+ *    could never arrive (DR-183); and the SurfaceView was never detached
+ *    (DR-184). Two further UI defects that only this path could show — the play
+ *    overlay never clearing (DR-186) and the system bars staying over the player
+ *    (DR-187) — are fixed with it.
+ *
+ * The picture is genuinely fixed and device-verified — `WebView transparent =
+ * true` and `Marking media ready` now appear in logcat with video on screen,
+ * the pair DR-172 went looking for and could not find. **The default is still
+ * off**, because turning it on surfaced a different gap: the background-audio
+ * handoff (UR-040) can only *return* through the HTML5 element.
+ * `applyPendingForegroundSeek` bails on `!videoElement`, the HLS re-init effect
+ * bails on `!useHtml5Element`, and `handleCanPlay` — the event that owns the
+ * post-handoff position and play state — is an element event that never fires
+ * natively. So coming back from background audio leaves playback dead.
+ *
+ * That is the same shape of mistake as DR-161: a verified sub-path shipped as a
+ * default over an unverified one. The evidence standard this branch set for the
+ * picture applies to the handoff too, so the flip waits for it (DR-190).
  *
  * An explicit stored choice still wins in both directions, so anyone who turned
  * it on keeps it on.
  *
- * TRACES: UR-003, UR-004 | DR-172
+ * TRACES: UR-003, UR-004 | DR-188
  */
 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.
+    // Private-mode / disabled storage — default to the path whose handoff works.
     return false;
   }
 }
@@ -80,9 +101,9 @@ function createExperimentalNativeVideoStore() {
 }
 
 /**
- * User opt-in for the native Android video path. **Defaults to off** again since
- * DR-172 — see `load()`. The name says "experimental" because the flag
- * remains a suppressor of Rust's backend choice, not a promoter of it.
+ * User opt-in for the native Android video path. **Defaults to off** — see
+ * `load()`. The name says "experimental" because the flag remains a suppressor
+ * of Rust's backend choice, not a promoter of it.
  */
 export const experimentalNativeVideo = createExperimentalNativeVideoStore();
 

src/lib/utils/nativeVideoLayers.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Every opaque layer the native-video CSS claims to clear must actually exist.
+ *
+ * TRACES: UR-003, UR-004 | DR-185 | UT-186
+ *
+ * The compositing rules in app.css clear the page's painted backgrounds so the
+ * ExoPlayer SurfaceView behind the WebView can be seen. One of the three
+ * selectors, `[data-app-shell]`, was written against an attribute that **no
+ * component ever set** — in any commit — so the app shell went on painting
+ * `--color-background` across the whole viewport, underneath a player that had
+ * correctly made itself transparent. The WebView therefore composited opaque
+ * and the surface could never show through.
+ *
+ * That failure is invisible three ways over: the CSS is valid, the selector is
+ * plausible, and the symptom (black screen, audio fine) is identical to a
+ * genuine compositing failure — which is how it survived DR-150 through DR-172.
+ * A rule that matches nothing is the specific defect worth a tripwire, so this
+ * asserts the relationship rather than the rule: every attribute the block
+ * targets is set somewhere in the app.
+ */
+
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const srcRoot = path.resolve(here, "../..");
+
+function read(file: string): string {
+  return fs.readFileSync(file, "utf-8");
+}
+
+/** Every .svelte file under src/. */
+function svelteFiles(dir: string, found: string[] = []): string[] {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) svelteFiles(full, found);
+    else if (entry.name.endsWith(".svelte")) found.push(full);
+  }
+  return found;
+}
+
+/**
+ * The selector list of the `[data-native-video="active"]` rule in app.css.
+ * Returned verbatim, one selector per entry.
+ */
+function compositingSelectors(css: string): string[] {
+  const marker = 'html[data-native-video="active"]';
+  const start = css.indexOf(marker);
+  expect(start, "app.css no longer contains the native-video rule").toBeGreaterThan(-1);
+  const open = css.indexOf("{", start);
+  return css
+    .slice(start, open)
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+describe("native-video compositing layers (DR-185)", () => {
+  const css = read(path.join(srcRoot, "app.css"));
+  const selectors = compositingSelectors(css);
+  const markup = svelteFiles(srcRoot).map(read).join("\n");
+
+  it("clears the app shell, which paints over the whole viewport", () => {
+    // The shell is the layer directly between the player and the WebView; if it
+    // stays painted, nothing below it can be seen however transparent the
+    // player and the WebView widget are.
+    expect(selectors.some((s) => s.includes("[data-app-shell]"))).toBe(true);
+    expect(markup).toContain("data-app-shell");
+  });
+
+  it("targets no attribute that nothing in the app sets", () => {
+    const attributes = selectors
+      .flatMap((selector) => [...selector.matchAll(/\[([a-zA-Z-]+)(?:[=\]])/g)])
+      .map((match) => match[1])
+      // data-native-video is set imperatively on <html> by nativeVideo.ts, not
+      // in markup, so it is verified against that module instead.
+      .filter((attr) => attr !== "data-native-video");
+
+    const unset = [...new Set(attributes)].filter((attr) => !markup.includes(attr));
+    expect(unset, `app.css targets attributes no component sets: ${unset.join(", ")}`)
+      .toEqual([]);
+  });
+
+  it("still sets data-native-video on <html> from the store", () => {
+    const store = read(path.join(srcRoot, "lib/stores/nativeVideo.ts"));
+    expect(store).toContain("data-native-video");
+    expect(store).toContain("documentElement");
+  });
+});

src/lib/utils/videoSurface.ts

@@ -1,7 +1,7 @@
 /**
  * Native video surface compositing, Android only.
  *
- * TRACES: UR-003, UR-004 | DR-150, DR-151
+ * TRACES: UR-003, UR-004 | DR-150, DR-151, DR-183
  *
  * On Android, ExoPlayer renders video into a SurfaceView that sits *behind* the
  * Tauri WebView (`setZOrderMediaOverlay(false)`, added at index 0 of the content
@@ -65,8 +65,23 @@ 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);
+  const androidVideoSurface = bridge();
+  if (!androidVideoSurface) {
+    // Say so loudly. Every bridge call in this file is optional-chained, so a
+    // missing bridge is silent — and a silently-skipped setTransparent(true) is
+    // indistinguishable on screen from a compositing failure: ExoPlayer renders
+    // correctly behind a WebView that never stopped painting its own opaque
+    // background. That ambiguity is what DR-172 was left holding. MainActivity's
+    // console bridge forwards this to logcat under the JellyTauWeb tag.
+    console.error(
+      "[videoSurface] AndroidVideoSurface bridge is MISSING - the webview will " +
+        "stay opaque and native video will play as audio with no picture"
+    );
+    return;
+  }
   try {
-    bridge()?.setTransparent(true);
+    androidVideoSurface.setTransparent(true);
+    console.log("[videoSurface] compositing enabled (setTransparent(true) sent)");
   } catch (err) {
     console.warn("[videoSurface] setTransparent(true) failed:", err);
     nativeVideoActive.set(false);

src/routes/+layout.svelte

@@ -260,7 +260,16 @@
 
   TRACES: UR-066 | DR-112
 -->
+<!--
+  data-app-shell marks the layer app.css clears for native video. This div
+  paints --color-background across the entire viewport, *under* a VideoPlayer
+  that makes itself transparent on the native path — so while it stays painted,
+  the ExoPlayer SurfaceView behind the WebView cannot be seen no matter what
+  else is cleared. The rule in app.css was written for this attribute; the
+  attribute was never added. (DR-185)
+-->
 <div
+  data-app-shell
   class="h-screen bg-[var(--color-background)] overflow-hidden flex flex-col
          pt-[var(--safe-top)] pl-[var(--safe-left)] pr-[var(--safe-right)]"
   style:padding-bottom={shellPadsBottom ? "var(--safe-bottom)" : undefined}

src/routes/settings/+page.svelte

@@ -744,10 +744,11 @@
                 </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 in
-                  principle, but incomplete: on some devices the picture does not
-                  appear at all and only the sound plays. Leave this off unless
-                  you are helping test it.
+                  built-in web player, for better performance and battery life,
+                  and so picture-in-picture shows the video rather than the app.
+                  The picture works, but background audio does not come back from
+                  the lockscreen on this path yet — leave it off unless you are
+                  helping test it.
                 </p>
               </div>
               <button