Embedded Loopbound WebView flickers rapidly on Android #73

Open
opened 2026-09-21 06:45:45 +02:00 by alexander · 5 comments
Owner

Symptom

Opening embedded Loopbound can make the game content flicker rapidly, appearing to disappear and reappear.

This issue records the BookWave / Android WebView half of the investigation. Loopbound's own confirmed render-churn defect remains tracked separately as alexander/Loopbound#8.

Current BookWave host state

Current authoritative main inspected: 3516344c3b16b8b114b6037aa68ecb30fc25d2e4.

LoopboundScreen.kt currently:

  • creates one remembered WebView per route/context;
  • hosts it with Compose AndroidView;
  • loads https://appassets.androidplatform.net/assets/loopbound/index.html only while view.url == null;
  • enables JavaScript + DOM storage for the local game;
  • uses a transparent WebView background;
  • gives the WebView MATCH_PARENT layout bounds;
  • destroys the WebView only when the route leaves composition;
  • sits inside the app-wide Compose navigation graph that is also a Haze source for the mini-player glass.

The obvious repeated-loadUrl() / repeated-WebView-creation hypothesis was not found.

Cross-repository findings

Loopbound itself has confirmed high-frequency UI churn:

  • 100 ms engine timer;
  • unconditional React notification after non-paused ticks;
  • idle game state may not change, but revision notifications still occur;
  • multiple nested useSyncExternalStore subscribers;
  • unstable subscribe function identity causes re-subscription;
  • idle character canvas repaints every 420 ms;
  • active task progress repaints every 100 ms.

Those patterns are old enough that they do not line up well with a newly appearing platform-specific flicker, but they can increase compositor/invalidation pressure.

Strong external match

Chromium issue 513436623 is currently an assigned P1 Mobile>WebView Android bug titled:

WebView continuous flickering caused by DefaultPassthroughCommandDecoder Finch experiment on Android WebView 147

Independent reports describe blank/blue/black/corrupted frames in Android WebView. Reports include Android 16/Samsung environments and indicate WebView 146 can be unaffected while 147 and later development builds reproduce the rendering problem.

Because BookWave embeds Loopbound in Android WebView rather than Capacitor/Chrome, this is presently the strongest trigger hypothesis.

Additional BookWave-side risk factors

These are contributors / isolation targets, not established bugs:

  1. The embedded WebView background is transparent, so a dropped/blank WebView compositor frame visibly exposes BookWave's backdrop rather than a stable opaque game background.
  2. The navigation graph is a Haze source for the mini player. Haze uses graphics-layer/backdrop capture on modern Android, while WebView is a platform AndroidView; this increases the complexity of the composition path.
  3. Playback state causes normal root Compose recomposition, though the remembered WebView itself is not recreated and its URL is not normally reloaded.
  4. The current Robolectric test checks only MATCH_PARENT host bounds. It does not prove real-device WebView frame stability, provider/version behavior, transparency, hardware/software composition, or Haze interaction.

Required device isolation before choosing a permanent mitigation

On one affected device and one exact BookWave APK:

  1. Record WebView.getCurrentWebViewPackage() package + version.
  2. Record the exact bundled BOOKWAVE_LOOPBOUND_VERSION.
  3. Compare embedded Loopbound with the same Loopbound snapshot in standalone Chrome/static hosting.
  4. Toggle Loopbound Reduce Motion and reopen; this removes the 420 ms idle canvas animation and CSS motion.
  5. In a diagnostic build only, compare:
    • current transparent hardware WebView;
    • opaque WebView background;
    • WebView excluded from the Haze source path if practical;
    • per-view software layer as an isolation experiment only, not an assumed permanent fix.
  6. Add WebViewClient page-start/page-finish logging to prove the page is not repeatedly navigating.
  7. Capture Logcat/render-process events during the flicker.

Acceptance

Do not close this as “Loopbound rendering” or “WebView bug” by assumption. A fix/mitigation should be based on the matrix above and should demonstrate on physical Android that the visible game no longer flashes while preserving scrolling, save persistence, mini-player usability and offline local-asset loading.

## Symptom Opening embedded Loopbound can make the game content flicker rapidly, appearing to disappear and reappear. This issue records the **BookWave / Android WebView half** of the investigation. Loopbound's own confirmed render-churn defect remains tracked separately as `alexander/Loopbound#8`. ## Current BookWave host state Current authoritative `main` inspected: `3516344c3b16b8b114b6037aa68ecb30fc25d2e4`. `LoopboundScreen.kt` currently: - creates one remembered `WebView` per route/context; - hosts it with Compose `AndroidView`; - loads `https://appassets.androidplatform.net/assets/loopbound/index.html` only while `view.url == null`; - enables JavaScript + DOM storage for the local game; - uses a transparent WebView background; - gives the WebView MATCH_PARENT layout bounds; - destroys the WebView only when the route leaves composition; - sits inside the app-wide Compose navigation graph that is also a Haze source for the mini-player glass. The obvious repeated-`loadUrl()` / repeated-WebView-creation hypothesis was **not found**. ## Cross-repository findings Loopbound itself has confirmed high-frequency UI churn: - 100 ms engine timer; - unconditional React notification after non-paused ticks; - idle game state may not change, but revision notifications still occur; - multiple nested `useSyncExternalStore` subscribers; - unstable subscribe function identity causes re-subscription; - idle character canvas repaints every 420 ms; - active task progress repaints every 100 ms. Those patterns are old enough that they do not line up well with a newly appearing platform-specific flicker, but they can increase compositor/invalidation pressure. ## Strong external match Chromium issue **513436623** is currently an assigned P1 Mobile>WebView Android bug titled: > WebView continuous flickering caused by DefaultPassthroughCommandDecoder Finch experiment on Android WebView 147 Independent reports describe blank/blue/black/corrupted frames in Android WebView. Reports include Android 16/Samsung environments and indicate WebView 146 can be unaffected while 147 and later development builds reproduce the rendering problem. Because BookWave embeds Loopbound in Android WebView rather than Capacitor/Chrome, this is presently the strongest trigger hypothesis. ## Additional BookWave-side risk factors These are **contributors / isolation targets**, not established bugs: 1. The embedded WebView background is transparent, so a dropped/blank WebView compositor frame visibly exposes BookWave's backdrop rather than a stable opaque game background. 2. The navigation graph is a Haze source for the mini player. Haze uses graphics-layer/backdrop capture on modern Android, while WebView is a platform `AndroidView`; this increases the complexity of the composition path. 3. Playback state causes normal root Compose recomposition, though the remembered WebView itself is not recreated and its URL is not normally reloaded. 4. The current Robolectric test checks only MATCH_PARENT host bounds. It does not prove real-device WebView frame stability, provider/version behavior, transparency, hardware/software composition, or Haze interaction. ## Required device isolation before choosing a permanent mitigation On one affected device and one exact BookWave APK: 1. Record `WebView.getCurrentWebViewPackage()` package + version. 2. Record the exact bundled `BOOKWAVE_LOOPBOUND_VERSION`. 3. Compare embedded Loopbound with the same Loopbound snapshot in standalone Chrome/static hosting. 4. Toggle Loopbound Reduce Motion and reopen; this removes the 420 ms idle canvas animation and CSS motion. 5. In a diagnostic build only, compare: - current transparent hardware WebView; - opaque WebView background; - WebView excluded from the Haze source path if practical; - per-view software layer as an isolation experiment only, not an assumed permanent fix. 6. Add `WebViewClient` page-start/page-finish logging to prove the page is not repeatedly navigating. 7. Capture Logcat/render-process events during the flicker. ## Acceptance Do not close this as “Loopbound rendering” or “WebView bug” by assumption. A fix/mitigation should be based on the matrix above and should demonstrate on physical Android that the visible game no longer flashes while preserving scrolling, save persistence, mini-player usability and offline local-asset loading.
Author
Owner

Diagnostic instrumentation is now isolated in PR #74 on branch mcp/issue-73-webview-diagnostics.

Exact diagnostic HEAD: a7fd3617d6ddd7a27dd7b40c739a7edf7a41ed60
Base main: 3516344c3b16b8b114b6037aa68ecb30fc25d2e4

The change is observability-only: WebView provider/version, bundled Loopbound SHA, page start/commit/finish counters, hardware/layer state, and render-process-gone logging. Transparency, Haze topology, layer policy, Loopbound rendering, and issue #36 code are unchanged.

A debug APK build is being dispatched with Loopbound pinned to 331aa252753a8279a56c2a44b0ed34963336c3f2 and verifyDebug enabled. Physical-device isolation remains required before any mitigation is selected.

Diagnostic instrumentation is now isolated in PR #74 on branch `mcp/issue-73-webview-diagnostics`. Exact diagnostic HEAD: `a7fd3617d6ddd7a27dd7b40c739a7edf7a41ed60` Base main: `3516344c3b16b8b114b6037aa68ecb30fc25d2e4` The change is observability-only: WebView provider/version, bundled Loopbound SHA, page start/commit/finish counters, hardware/layer state, and render-process-gone logging. Transparency, Haze topology, layer policy, Loopbound rendering, and issue #36 code are unchanged. A debug APK build is being dispatched with Loopbound pinned to `331aa252753a8279a56c2a44b0ed34963336c3f2` and verifyDebug enabled. Physical-device isolation remains required before any mitigation is selected.
Author
Owner

Additional physical-device observation:

  • The deployed web version of the same Loopbound game does not flicker in a normal browser.
  • In BookWave, the embedded game flickers rapidly when first opened, but the flicker can stop after the WebView has been open for a while.
  • The startup flicker is severe enough to be uncomfortable to look at.

This strengthens the current hypothesis that the trigger is in the Android embedded WebView/compositor/startup composition path rather than a continuously faulty Loopbound React/render loop. Loopbound render churn may still amplify the problem, but a persistent game-side loop alone does not fit the observed 'bad at startup, then settles' shape well.

Next device capture should record:

  1. time from opening Loopbound until flicker stops;
  2. whether page-start/commit/finish counters remain at one document load during the whole flicker period;
  3. WebView provider/version and exact bundled Loopbound SHA;
  4. whether Reduce Motion changes flicker severity/duration;
  5. opaque WebView background next, then Haze-path isolation if needed.

Do not broaden this into a Loopbound rendering rewrite without evidence.

Additional physical-device observation: - The deployed web version of the same Loopbound game does **not** flicker in a normal browser. - In BookWave, the embedded game flickers rapidly when first opened, but the flicker can stop after the WebView has been open for a while. - The startup flicker is severe enough to be uncomfortable to look at. This strengthens the current hypothesis that the trigger is in the Android embedded WebView/compositor/startup composition path rather than a continuously faulty Loopbound React/render loop. Loopbound render churn may still amplify the problem, but a persistent game-side loop alone does not fit the observed 'bad at startup, then settles' shape well. Next device capture should record: 1. time from opening Loopbound until flicker stops; 2. whether page-start/commit/finish counters remain at one document load during the whole flicker period; 3. WebView provider/version and exact bundled Loopbound SHA; 4. whether Reduce Motion changes flicker severity/duration; 5. opaque WebView background next, then Haze-path isolation if needed. Do not broaden this into a Loopbound rendering rewrite without evidence.
Author
Owner

Deep-dive update — WebView compositor hypothesis

CI / diagnostic PR

PR #74 is now at 4dba6000259d480e75f85c9d55a0f3b1d101a206.

The previous failed PR check was not a source failure. The pull-request workflow had been dispatched with issue number 73 as the PR number, while the diagnostic branch belongs to PR #74. Preflight correctly rejected that mismatch before verifyDebug.

While reviewing the instrumentation I also corrected one real architecture problem before rerunning: the first diagnostic commit called android.util.Log directly, but BookWave's logging contract reserves that API for AndroidLogSink. Diagnostics now go through the existing structured/redacted Logger.

The corrected run has passed PR #74 · Preflight; verifyDebug is currently running.

External WebView evidence

The active Chromium issue 513436623 is an assigned P1 Android WebView bug titled:

WebView continuous flickering caused by DefaultPassthroughCommandDecoder Finch experiment on Android WebView 147

Chromium's current production-supported WebView flag list exposes DefaultPassthroughCommandDecoder as “Use the passthrough GLES2 command decoder.” Chromium's current field-trial configuration explicitly enables that feature for the android_webview platform.

WebView DevTools documentation is especially relevant: WebView receives A/B rollouts through variations/Finch, and its Flags UI can override a field-trial feature specifically to determine whether an experiment is the root cause of an app regression. Therefore package/version alone is useful but not sufficient evidence: two devices/builds on similar WebView versions can have different variation state.

References:

Revised physical-device isolation order

Keep one exact BookWave APK + one exact bundled Loopbound SHA for each A/B pair.

  1. Baseline diagnostic capture

    • record WebView provider/version and Loopbound SHA;
    • record approximate time until visible flicker stops;
    • prove whether page-start / page-visible / page-finish remain one document navigation during repeated visible flashes;
    • check for render-process exit.
  2. Direct Finch hypothesis A/B

    • open WebView DevTools;
    • find DefaultPassthroughCommandDecoder;
    • explicitly set it Disabled;
    • force-stop/restart BookWave as required by WebView DevTools;
    • reproduce with the same APK and Loopbound snapshot.
    • Reset the flag to Default afterward.

    If disabling this feature removes the flicker while everything else is unchanged, that is much stronger causal evidence than changing BookWave rendering first.

  3. Opaque WebView background A/B

    • diagnostic build only. This tests whether transient blank/corrupted WebView frames are being made dramatically visible by the transparent host.
  4. Haze isolation A/B

    • remove/exclude the Loopbound destination from the navigation graph's Haze source path without otherwise changing the WebView.
    • Haze uses a captured graphics layer; platform interop such as AndroidView has special capture/composition constraints. This is a plausible interaction surface, not an established cause.
  5. Loopbound Reduce Motion

    • tests whether canvas/CSS paint frequency changes severity or settling time. Since the same web deployment is stable and Loopbound's render churn continues after the embedded flicker settles, render churn is presently better treated as an amplifier candidate than a sufficient cause.
  6. Per-view software layer

    • diagnostic only, last. Android documents LAYER_TYPE_SOFTWARE as forcing one View through the software pipeline. A change here would strongly implicate the GPU/compositor path, but it is too invasive/performance-sensitive to assume as a permanent fix.

Interpretation of the observed “starts bad, then settles” behavior

The fact that the deployed browser version is stable while the embedded WebView can flicker violently on entry and later settle further weakens a simple continuously-running Loopbound React-loop explanation. It does not yet prove Chromium issue 513436623, because that issue is described as continuous flickering and BookWave's symptom may be transient.

The most discriminating next evidence is therefore the same-device Finch flag A/B plus the new navigation counters. Do not perform a broad Loopbound or BookWave rendering rewrite until those tests are available.

## Deep-dive update — WebView compositor hypothesis ### CI / diagnostic PR PR #74 is now at `4dba6000259d480e75f85c9d55a0f3b1d101a206`. The previous failed PR check was not a source failure. The pull-request workflow had been dispatched with issue number `73` as the PR number, while the diagnostic branch belongs to PR `#74`. Preflight correctly rejected that mismatch before `verifyDebug`. While reviewing the instrumentation I also corrected one real architecture problem before rerunning: the first diagnostic commit called `android.util.Log` directly, but BookWave's logging contract reserves that API for `AndroidLogSink`. Diagnostics now go through the existing structured/redacted `Logger`. The corrected run has passed `PR #74 · Preflight`; `verifyDebug` is currently running. ### External WebView evidence The active Chromium issue 513436623 is an assigned P1 Android WebView bug titled: > WebView continuous flickering caused by DefaultPassthroughCommandDecoder Finch experiment on Android WebView 147 Chromium's current production-supported WebView flag list exposes `DefaultPassthroughCommandDecoder` as “Use the passthrough GLES2 command decoder.” Chromium's current field-trial configuration explicitly enables that feature for the `android_webview` platform. WebView DevTools documentation is especially relevant: WebView receives A/B rollouts through variations/Finch, and its Flags UI can override a field-trial feature specifically to determine whether an experiment is the root cause of an app regression. Therefore package/version alone is useful but not sufficient evidence: two devices/builds on similar WebView versions can have different variation state. References: - https://issues.chromium.org/issues/513436623 - https://chromium.googlesource.com/chromium/src/+/HEAD/android_webview/docs/developer-ui.md - https://chromium.googlesource.com/chromium/src/+/HEAD/android_webview/docs/commandline-flags.md - https://chromium.googlesource.com/chromium/src/+/main/testing/variations/fieldtrial_testing_config.json ### Revised physical-device isolation order Keep one exact BookWave APK + one exact bundled Loopbound SHA for each A/B pair. 1. **Baseline diagnostic capture** - record WebView provider/version and Loopbound SHA; - record approximate time until visible flicker stops; - prove whether page-start / page-visible / page-finish remain one document navigation during repeated visible flashes; - check for render-process exit. 2. **Direct Finch hypothesis A/B** - open WebView DevTools; - find `DefaultPassthroughCommandDecoder`; - explicitly set it **Disabled**; - force-stop/restart BookWave as required by WebView DevTools; - reproduce with the same APK and Loopbound snapshot. - Reset the flag to Default afterward. If disabling this feature removes the flicker while everything else is unchanged, that is much stronger causal evidence than changing BookWave rendering first. 3. **Opaque WebView background A/B** - diagnostic build only. This tests whether transient blank/corrupted WebView frames are being made dramatically visible by the transparent host. 4. **Haze isolation A/B** - remove/exclude the Loopbound destination from the navigation graph's Haze source path without otherwise changing the WebView. - Haze uses a captured graphics layer; platform interop such as AndroidView has special capture/composition constraints. This is a plausible interaction surface, not an established cause. 5. **Loopbound Reduce Motion** - tests whether canvas/CSS paint frequency changes severity or settling time. Since the same web deployment is stable and Loopbound's render churn continues after the embedded flicker settles, render churn is presently better treated as an amplifier candidate than a sufficient cause. 6. **Per-view software layer** - diagnostic only, last. Android documents `LAYER_TYPE_SOFTWARE` as forcing one View through the software pipeline. A change here would strongly implicate the GPU/compositor path, but it is too invasive/performance-sensitive to assume as a permanent fix. ### Interpretation of the observed “starts bad, then settles” behavior The fact that the deployed browser version is stable while the embedded WebView can flicker violently on entry and later settle further weakens a simple continuously-running Loopbound React-loop explanation. It does **not** yet prove Chromium issue 513436623, because that issue is described as continuous flickering and BookWave's symptom may be transient. The most discriminating next evidence is therefore the same-device Finch flag A/B plus the new navigation counters. Do not perform a broad Loopbound or BookWave rendering rewrite until those tests are available.
Author
Owner

CI follow-up: the structured-logger conversion exposed one compile error in the diagnostic branch: RenderProcessGoneDetail.rendererPriorityAtExit must be invoked as a method. This is fixed in 102bef18128262e2eeb184091b4d6be6fa94ee8a.

Current PR #74 HEAD: 102bef18128262e2eeb184091b4d6be6fa94ee8a
Current main/base: 91a742291144204aa1c61403c424a0b4999c27c8

Actions run 209 is checking that exact HEAD. Its preflight has passed and verifyDebug is running. No mitigation/rendering behavior has been added; PR #74 remains instrumentation-only.

CI follow-up: the structured-logger conversion exposed one compile error in the diagnostic branch: `RenderProcessGoneDetail.rendererPriorityAtExit` must be invoked as a method. This is fixed in `102bef18128262e2eeb184091b4d6be6fa94ee8a`. Current PR #74 HEAD: `102bef18128262e2eeb184091b4d6be6fa94ee8a` Current main/base: `91a742291144204aa1c61403c424a0b4999c27c8` Actions run 209 is checking that exact HEAD. Its preflight has passed and `verifyDebug` is running. No mitigation/rendering behavior has been added; PR #74 remains instrumentation-only.
Author
Owner

Physical-device update from the diagnostic branch:

  • The flicker is currently not reproducible on the new BookWave diagnostic branch.
  • This branch still contains no intentional rendering mitigation. Its diff is limited to WebView diagnostics/logging and associated formatting.
  • Current PR #74 HEAD is d48fcd9bc9997e00732c4557657e825911bb4de1; current base is 32e554dacdb79ddc866027c84cbcd5789283de7b.
  • Therefore, absence of flicker should not yet be attributed to a BookWave rendering fix.

Interpretation:

  • the symptom may be intermittent;
  • WebView provider/Finch experiment state may have changed;
  • startup/warm-state/cache/timing could matter;
  • the added callbacks/logging could theoretically perturb timing, but there is no evidence yet that they are causally suppressing the flicker.

Before closing #73 or implementing a permanent workaround, reproduce with several cold starts of the same exact APK. If flicker stays absent, capture the diagnostic provider/version + Loopbound SHA and compare against the previously affected build/device state. If possible, test the prior known-flickering APK again on the same device; if that is now also stable, the strongest explanation shifts toward WebView/platform/experiment state rather than BookWave source changes.

Physical-device update from the diagnostic branch: - The flicker is currently **not reproducible** on the new BookWave diagnostic branch. - This branch still contains no intentional rendering mitigation. Its diff is limited to WebView diagnostics/logging and associated formatting. - Current PR #74 HEAD is `d48fcd9bc9997e00732c4557657e825911bb4de1`; current base is `32e554dacdb79ddc866027c84cbcd5789283de7b`. - Therefore, absence of flicker should not yet be attributed to a BookWave rendering fix. Interpretation: - the symptom may be intermittent; - WebView provider/Finch experiment state may have changed; - startup/warm-state/cache/timing could matter; - the added callbacks/logging could theoretically perturb timing, but there is no evidence yet that they are causally suppressing the flicker. Before closing #73 or implementing a permanent workaround, reproduce with several cold starts of the same exact APK. If flicker stays absent, capture the diagnostic provider/version + Loopbound SHA and compare against the previously affected build/device state. If possible, test the prior known-flickering APK again on the same device; if that is now also stable, the strongest explanation shifts toward WebView/platform/experiment state rather than BookWave source changes.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#73
No description provided.