From dccb5f53ddf9ba24a5033f15b421c3dbe6d00060 Mon Sep 17 00:00:00 2001
From: Duncan Tourolle <duncan@tourolle.paris>
Date: Sun, 16 Aug 2026 18:46:15 +0200
Subject: [PATCH] fix(android): stop the rotation cross-fade replaying the old
 video frame
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rotating with native video on shows the previous frame flashing in what become
the letterbox bars. It reads as a TextureView artefact — the view retains its
last frame, so between the rotation and fitSurfaceToScreen() landing that frame
sits at the old size — and two fixes were built on that reading:

  1. reveal after two postOnAnimation hops. An animation frame is not a video
     frame; at 24fps the next decoded frame can be several vsyncs away.
  2. reveal on onSurfaceTextureUpdated, i.e. when a real frame lands. This meant
     owning the SurfaceTextureListener and handing ExoPlayer the Surface directly
     instead of via setVideoTextureView, which installs its own and leaves us
     blind to frame arrival.

Neither stopped the flash. The mechanism is the WINDOW's rotation animation:
Android cross-fades a screenshot of the old orientation, that screenshot holds
the old video frame at the old size, and nothing at the TextureView level can
reach it. The app cannot pre-empt the screenshot either — onConfigurationChanged
fires after it is taken.

So the animation itself has to go: ROTATION_ANIMATION_JUMPCUT. That was accepted
and silently ignored, and the platform said why out loud —
"VRI[MainActivity]: setLayoutParams: not fullscreen" — because the attribute is
honoured only for a fullscreen window. FLAG_FULLSCREEN is therefore set with it,
scoped to while native compositing is active so the rest of the app keeps its
normal animation. After the change that complaint is gone from logcat.

The frame-arrival reveal is kept: it replaces a fixed-timeout guess with a real
signal, and its timeout is required rather than defensive — a resize while paused
means no new frame is ever coming, and revealing a stale frame beats a
permanently black player.

NOT CONFIRMED FIXED on device. The forced-rotation harness
(settings put system user_rotation) proved unreliable here, and screenrecord
fixes its canvas at start, so a rotation inside a recording never changes frame
dimensions — which defeated two separate attempts to measure this. DR-194 is
recorded as "Needs device verification" rather than Done.
---
 docs/requirements.md                          |   2 +-
 docs/traceability.md                          |   2 +-
 .../com/dtourolle/jellytau/MainActivity.kt    |  59 ++++++++
 .../jellytau/player/JellyTauPlayer.kt         | 136 +++++++++++++++---
 4 files changed, 178 insertions(+), 21 deletions(-)

diff --git a/docs/requirements.md b/docs/requirements.md
index bbac69ec..4aaa88c2 100644
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -349,7 +349,7 @@ Internal architecture, components, and application logic.
 | 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 | Forcing the WebView overlay to redraw from the Activity, because with the ExoPlayer **SurfaceView** beneath it the overlay's ordinary damage stopped reaching the screen: the page kept mutating — the clock text every second, the control bar's opacity going to 0 — while the display held whatever frame it last presented, over video that animated perfectly. Not a state defect; the live DOM showed the slider advancing 476 → 479 across three seconds behind a screen showing neither. Only **structural** changes got through, which is why the play overlay always appeared to work (an `{#if}` block, added and removed) while the progress bar never did, and why rotation lost the transport UI. A CSS animation cannot help, since opacity animates on the compositor without repainting the layer. **Superseded by DR-192**: this drove `postInvalidateOnAnimation` in a loop, which treats the symptom — the cause is the SurfaceView's separate layer, and removing that removes the need. Kept as the record of how the mechanism was identified | Android | UR-003, UR-004 | Superseded by DR-192 |
 | DR-195 | Play/pause works on the native path, because the frontend stops claiming a webview element is playing when there is none. `html5_playing` is Rust's record of "a webview `<video>` is active and in this state", and `toggle_playback`, `play` and `pause` all route transport to that element whenever it is set. The player route mirrored element state into it **unconditionally** — from `handleReportStart` and, fatally, from `handleReportProgress`, which VideoPlayer calls on a 10-second interval — so on the native path the frontend re-declared every ten seconds that an element was playing when none existed, and every transport intent was emitted into the void. The pause button was dead from the on-screen tap, from the control bar, and from a direct `player_toggle` invocation, while seek and skip kept working because `player_seek_video` decides elsewhere; that asymmetry is the signature. It also explains the flashing, since the control bar and the JRay overlay both key off `isPlaying`, which was being contradicted on every interval tick. DR-193 clearing the flag at load was necessary but insufficient on its own — the interval put it straight back. The mirror now lives in `mirrorElementStateToRust` in VideoPlayer, gated on `useHtml5Element`, which is the only place that knows whether an element renders at all; the route cannot tell the two paths apart, which is precisely how it came to lie. Confirmed on device by ADB: surface tap and control bar each pause (position frozen across repeated samples, transport label flipped) and resume | Playback | UR-005, UR-003 | Done |
-| DR-194 | The previous frame stops flashing in the letterbox bars on rotation. A TextureView retains its last frame, and between a rotation and `fitSurfaceToScreen()` landing that retained frame is stretched across the **old** rect — larger than the new one along at least one axis — so the previous frame appears where the bars should be. Nothing is wrong with the video: it is one or two frames of stale texture at a stale size, and it is specific to DR-192's move to a TextureView, since a SurfaceView's separate layer never showed it. The view is hidden across an actual size change and revealed after two `postOnAnimation` hops — the first lands after layout is applied, the second after a frame has been drawn into the new bounds, which is the state worth waiting for. Scoped to a real size change so steady-state playback never touches alpha. Unlike DR-191's permanent invalidation loop this is a discrete reset at a discrete event, which is the difference between a bounded workaround and a treadmill | Android | UR-003, UR-066 | Done |
+| DR-194 | The previous frame flashing on rotation. It reads as a TextureView artefact — the view retains its last frame, so between a rotation and `fitSurfaceToScreen()` landing that frame sits at the old size — and two fixes were built on that reading: revealing after two `postOnAnimation` hops, then revealing on `onSurfaceTextureUpdated`, which required owning the `SurfaceTextureListener` and handing ExoPlayer the Surface directly rather than via `setVideoTextureView`. **Neither stopped the flash.** The mechanism is the *window's* rotation animation: Android cross-fades a **screenshot of the old orientation**, that screenshot contains the old video frame at the old size, and no TextureView bookkeeping can reach it — nor can the app pre-empt the screenshot, since `onConfigurationChanged` fires after it is taken. The only lever is to stop the animation: `ROTATION_ANIMATION_JUMPCUT`. That was accepted and silently ignored at first, and the platform said why out loud — `VRI[MainActivity]: setLayoutParams: not fullscreen` — because the attribute is honoured only for a fullscreen window. `FLAG_FULLSCREEN` (deprecated for hiding system bars, which immersive mode does instead, but still what marks the window fullscreen for this decision) is therefore set alongside it, scoped to while native compositing is active so the rest of the app keeps its normal animation. The frame-arrival reveal is kept: it replaced a fixed-timeout guess with a real signal, and its timeout is required rather than defensive, since a resize while paused means no new frame is ever coming. **The flash is not confirmed fixed on device** — the forced-rotation harness (`settings put system user_rotation`) proved unreliable, and `screenrecord` fixes its canvas at start so a rotation inside a recording never changes frame dimensions, which defeated two attempts at measuring it | Android | UR-003, UR-066 | Needs device verification |
 | DR-193 | Play/pause reaches the player that is actually rendering. `toggle_playback`, `play` and `pause` all route to the webview element when `is_html5_active()`, which is `html5_playing.is_some()` — a flag written **only** by the element's own state reports and cleared only when it reports "stopped"/"idle" (or on a background-audio handoff). An element that went away without that final report, or webview-rendered music earlier in the same process, therefore left the flag set, and on Android's native video path every transport intent was emitted as a `ControlCommand` at an element that no longer existed: the pause button did nothing, from the on-screen tap and from the control bar alike, while seek and skip kept working because `player_seek_video` decides elsewhere. Whether it happened at all depended on what had played before, which is exactly what made it read as flaky rather than broken. `load_and_play` — the native load path, and the one the HTML5 video path deliberately avoids via `set_current_item` — now clears the flag, because loading into the native backend *is* the statement that native renders this item. Nothing is lost on the webview path: an element re-establishes its own authority the moment it reports again, so this is the existing "element is gone" semantics applied where it can be known directly rather than inferred from a report that may never arrive | Playback | UR-005, UR-003 | Done |
 | DR-192 | Native video presents through a **TextureView**, not a SurfaceView. A SurfaceView renders on its own layer *outside* the app window and punches a transparent region through it; everything drawn above that hole — for us the entire Svelte UI in a transparent WebView — depends on that composition path, and Android's own graphics documentation states that "overlays do not currently work correctly with SurfaceView or TextureView". The consequences were four symptoms of one cause (DR-191): a frozen progress bar, controls that would not fade, rotation losing the transport UI, and overlays that lingered after the DOM removed them. A TextureView is an ordinary view whose frames are drawn as a texture in the window's normal rendering pass, so there is no second layer and no transparent region, and the WebView above composites like it would over any other view — which is why media3 offers `surface_type="texture_view"` and why it is the standard remedy for ExoPlayer overlay problems. The trade is accepted rather than hidden: TextureView costs more power and memory than SurfaceView and adds a frame of latency, but hardware decode through MediaCodec is untouched, so the reason native video exists survives it. `setVideoTextureView` installs ExoPlayer's own `SurfaceTextureListener`, so the old `SurfaceHolder.Callback` wiring is deleted rather than ported — adding a listener of ours would displace it and the video would never appear. PiP needs no change, since a TextureView is a View and the aspect-ratio probe reads its measured bounds | Android | UR-003, UR-004, UR-041 | 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 |
diff --git a/docs/traceability.md b/docs/traceability.md
index ac78ced2..4813672e 100644
--- a/docs/traceability.md
+++ b/docs/traceability.md
@@ -1,6 +1,6 @@
 # Code Traceability Matrix
 
-**Generated:** 8/16/2026, 6:03:00 PM
+**Generated:** 8/16/2026, 6:45:35 PM
 
 ## Summary
 
diff --git a/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt b/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt
index b6f36e76..c01eeafb 100644
--- a/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt
+++ b/src-tauri/android/src/main/java/com/dtourolle/jellytau/MainActivity.kt
@@ -191,6 +191,37 @@ class MainActivity : TauriActivity() {
     super.onDestroy()
   }
 
+  /**
+   * Rotation (and any other config change this Activity handles itself).
+   *
+   * Two things have to happen here rather than later, and both are about the
+   * *previous* video frame surviving the transition:
+   *
+   *  - The video view is hidden until a new frame arrives. The equivalent call
+   *    in `fitSurfaceToScreen` runs from the content view's layout listener,
+   *    which is after the rotation — by then the stale frame has been on screen
+   *    for the whole transition.
+   *  - The window's rotation animation is a **cross-fade of a screenshot** of
+   *    the old orientation, and that screenshot contains the old video frame at
+   *    the old size. No amount of TextureView bookkeeping can touch it, which is
+   *    why hiding on frame-arrival alone did not stop the flash. `JUMPCUT` drops
+   *    the cross-fade, so there is no old frame to fade through; it is set only
+   *    while native compositing is active (see setTransparent) so the rest of
+   *    the app keeps the normal animation.
+   *
+   * TRACES: UR-003, UR-066 | DR-194
+   */
+  override fun onConfigurationChanged(newConfig: android.content.res.Configuration) {
+    super.onConfigurationChanged(newConfig)
+    try {
+      if (com.dtourolle.jellytau.player.JellyTauPlayer.isInitialized()) {
+        com.dtourolle.jellytau.player.JellyTauPlayer.getInstance().hideUntilFreshFrame()
+      }
+    } catch (e: Exception) {
+      android.util.Log.w("MainActivity", "hideUntilFreshFrame on config change failed", e)
+    }
+  }
+
   override fun onPictureInPictureModeChanged(
     isInPictureInPictureMode: Boolean,
     newConfig: android.content.res.Configuration
@@ -381,6 +412,34 @@ class MainActivity : TauriActivity() {
             window.setBackgroundDrawable(
               android.graphics.drawable.ColorDrawable(color)
             )
+            // Drop the rotation cross-fade while a native video surface is
+            // composited behind the page. The animation fades a *screenshot* of
+            // the old orientation, which still holds the previous video frame at
+            // the old size — that is the "previous frame flashing in the black
+            // bars", and it lives in the window animation rather than in
+            // anything the TextureView owns. (DR-194)
+            val attrs = window.attributes
+            attrs.rotationAnimation = if (transparent) {
+              android.view.WindowManager.LayoutParams.ROTATION_ANIMATION_JUMPCUT
+            } else {
+              android.view.WindowManager.LayoutParams.ROTATION_ANIMATION_ROTATE
+            }
+            window.attributes = attrs
+            // `rotationAnimation` is honoured only for a **fullscreen** window —
+            // the platform says so out loud, logging
+            // "VRI[MainActivity]: setLayoutParams: not fullscreen" when the
+            // attribute is set on ours, and then animating normally regardless.
+            // Without this the JUMPCUT above is accepted and ignored, and the
+            // cross-fade keeps showing the old orientation's screenshot, stale
+            // video frame and all. FLAG_FULLSCREEN is deprecated for *hiding
+            // system bars* (immersive mode does that, on player entry), but it
+            // is still what marks the window fullscreen for this decision.
+            @Suppress("DEPRECATION")
+            if (transparent) {
+              window.addFlags(android.view.WindowManager.LayoutParams.FLAG_FULLSCREEN)
+            } else {
+              window.clearFlags(android.view.WindowManager.LayoutParams.FLAG_FULLSCREEN)
+            }
             android.util.Log.d("MainActivity", "WebView transparent = $transparent")
           }
         }
diff --git a/src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlayer.kt b/src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlayer.kt
index 51e05360..83da5f70 100644
--- a/src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlayer.kt
+++ b/src-tauri/android/src/main/java/com/dtourolle/jellytau/player/JellyTauPlayer.kt
@@ -38,6 +38,12 @@ class JellyTauPlayer(private val appContext: Context) {
         /** AudioEffect priority. Positive = higher priority than the default. */
         private const val EFFECT_PRIORITY = 1000
 
+        /**
+         * How long to wait for a fresh frame after a resize before revealing the
+         * view anyway. Playback may be paused, in which case no frame is coming.
+         */
+        private const val FRESH_FRAME_TIMEOUT_MS = 400L
+
         /**
          * Canonical 10-band ISO centre frequencies (Hz), mirroring EQ_BANDS in
          * settings.rs. Kept in sync deliberately: Rust owns the band layout, this
@@ -226,6 +232,16 @@ class JellyTauPlayer(private val appContext: Context) {
 
     /** TextureView for video playback — see getOrCreateSurfaceView() for why. */
     private var videoView: TextureView? = null
+
+    /** The Surface handed to ExoPlayer, owned here rather than by the player. */
+    private var videoSurface: android.view.Surface? = null
+
+    /**
+     * True while the view is hidden waiting for a new frame after a resize.
+     * See fitSurfaceToScreen (DR-194).
+     */
+    @Volatile
+    private var awaitingFreshFrame = false
     /** Last reported video frame size, used to fit the surface to the screen preserving aspect ratio */
     private var videoWidth: Int = 0
     private var videoHeight: Int = 0
@@ -1123,9 +1139,57 @@ class JellyTauPlayer(private val appContext: Context) {
                 // The view is opaque where video is drawn; the WebView above it
                 // is what supplies transparency, exactly as before.
                 isOpaque = true
+
+                // Own the listener rather than calling `setVideoTextureView`,
+                // which installs ExoPlayer's own and leaves us blind to frame
+                // arrival. `onSurfaceTextureUpdated` is the only honest signal
+                // that a NEW frame has landed in the texture, and that is
+                // precisely what the letterbox artefact waits on — see
+                // fitSurfaceToScreen. Handing ExoPlayer the Surface directly is
+                // the same wiring `setVideoTextureView` does internally.
+                //
+                // TRACES: UR-003, UR-004 | DR-194
+                surfaceTextureListener = object : TextureView.SurfaceTextureListener {
+                    override fun onSurfaceTextureAvailable(
+                        texture: android.graphics.SurfaceTexture,
+                        width: Int,
+                        height: Int
+                    ) {
+                        videoSurface?.release()
+                        videoSurface = android.view.Surface(texture)
+                        exoPlayer.setVideoSurface(videoSurface)
+                        android.util.Log.d("JellyTauPlayer", "Video surface attached to ExoPlayer")
+                    }
+
+                    override fun onSurfaceTextureSizeChanged(
+                        texture: android.graphics.SurfaceTexture,
+                        width: Int,
+                        height: Int
+                    ) {
+                    }
+
+                    override fun onSurfaceTextureDestroyed(
+                        texture: android.graphics.SurfaceTexture
+                    ): Boolean {
+                        exoPlayer.setVideoSurface(null)
+                        videoSurface?.release()
+                        videoSurface = null
+                        return true
+                    }
+
+                    override fun onSurfaceTextureUpdated(
+                        texture: android.graphics.SurfaceTexture
+                    ) {
+                        // A genuinely new frame is now in the texture, so
+                        // whatever was retained from before the resize is gone.
+                        if (awaitingFreshFrame) {
+                            awaitingFreshFrame = false
+                            videoView?.alpha = 1f
+                        }
+                    }
+                }
             }
-            exoPlayer.setVideoTextureView(videoView)
-            android.util.Log.d("JellyTauPlayer", "Video TextureView created and attached to ExoPlayer")
+            android.util.Log.d("JellyTauPlayer", "Video TextureView created")
         }
         return videoView!!.hashCode()
     }
@@ -1194,6 +1258,31 @@ class JellyTauPlayer(private val appContext: Context) {
      * pillarbox). A raw SurfaceView with MATCH_PARENT otherwise stretches the
      * video to the surface bounds, which crops the bottom on rotation.
      */
+    /**
+     * Hide the video view now, and keep it hidden until a genuinely new frame
+     * arrives (or the timeout fires).
+     *
+     * Called from `MainActivity.onConfigurationChanged`, i.e. at the *start* of a
+     * rotation. [fitSurfaceToScreen] is too late for this: it runs from the
+     * content view's layout listener, after the rotation has already happened,
+     * so the stale frame has been on screen for the whole transition by then.
+     *
+     * TRACES: UR-003, UR-066 | DR-194
+     */
+    fun hideUntilFreshFrame() {
+        mainHandler.post {
+            val view = videoView ?: return@post
+            awaitingFreshFrame = true
+            view.alpha = 0f
+            mainHandler.postDelayed({
+                if (awaitingFreshFrame) {
+                    awaitingFreshFrame = false
+                    videoView?.alpha = 1f
+                }
+            }, FRESH_FRAME_TIMEOUT_MS)
+        }
+    }
+
     fun fitSurfaceToScreen() {
         mainHandler.post {
             val view = videoView ?: return@post
@@ -1229,38 +1318,47 @@ class JellyTauPlayer(private val appContext: Context) {
                 lp.gravity = android.view.Gravity.CENTER
             }
 
-            // Hide the view across a resize, and reveal it once the new bounds
-            // hold a freshly drawn frame.
+            // Hide the view across a resize, and reveal it when a genuinely NEW
+            // video frame lands in the texture.
             //
             // A TextureView retains its last frame. Between a rotation and this
             // re-fit landing, that retained frame is stretched across the OLD
-            // rect — which is larger than the new one along at least one axis —
-            // so the previous frame flashes in what should be the letterbox
-            // bars. Nothing is wrong with the video; it is one or two frames of
-            // stale texture at a stale size.
+            // rect — larger than the new one along at least one axis — so the
+            // previous frame flashes in what should be the letterbox bars.
             //
-            // Two `postOnAnimation` hops rather than one: the first runs after
-            // layout has been applied, the second after a frame has actually
-            // been drawn into the new bounds, which is the thing worth waiting
-            // for. Scoped to an actual size change so steady-state playback
-            // never touches alpha.
+            // Waiting a fixed number of animation frames does NOT fix it, which
+            // the first attempt at this proved on device: an animation frame is
+            // not a video frame, and at 24fps the next decoded frame can be
+            // several vsyncs away. The tell was that pausing and playing cleared
+            // the artefact by hand — that forces a fresh frame, which is the
+            // real precondition. So the reveal is driven by
+            // `onSurfaceTextureUpdated` instead.
+            //
+            // The timeout is not belt-and-braces, it is required: if playback is
+            // paused when the resize happens, no new frame is coming and the
+            // video would stay invisible forever. Revealing a stale frame after
+            // a beat is strictly better than a permanently black player.
+            //
+            // Scoped to an actual size change so steady-state playback never
+            // touches alpha.
             //
             // TRACES: UR-003, UR-066 | DR-194
             val sizeChanged = lp.width != targetW || lp.height != targetH
             if (sizeChanged) {
+                awaitingFreshFrame = true
                 view.alpha = 0f
+                mainHandler.postDelayed({
+                    if (awaitingFreshFrame) {
+                        awaitingFreshFrame = false
+                        videoView?.alpha = 1f
+                    }
+                }, FRESH_FRAME_TIMEOUT_MS)
             }
 
             lp.width = targetW
             lp.height = targetH
             view.layoutParams = lp
             view.requestLayout()
-
-            if (sizeChanged) {
-                view.postOnAnimation {
-                    view.postOnAnimation { view.alpha = 1f }
-                }
-            }
             android.util.Log.d(
                 "JellyTauPlayer",
                 "Video surface fitted to ${targetW}x${targetH} (video ${videoWidth}x${videoHeight}, avail ${availW}x${availH})"