WebView UI controls on top of KeplerVideoSurfaceView on Vega OS

Hi,

We implemented the suggestion from How to render WebView UI controls on top of KeplerVideoSurfaceView on Vega OS? - #7 by amen and built a minimal reproduction, but the overlay still disappears the moment the native video surface becomes active. Details below.

SDK Version: v0.24 (0.24.12112) React Native Version: RN0.83 (@amazon-devices/react-native-kepler 4.0.1)

Environment where this reproduces

Device: Fire TV Stick (AFTCA002)
OS: Vega OS 2.0 (TV Ship, build 515)
Display: 3840 x 2160 (4K)
Vega SDK: 0.24.12112
RN for Vega: 0.83 / @amazon-devices/react-native-kepler 4.0.1
@amazon-devices/react-native-w3cmedia 2.3.2
@amazon-devices/webview 4.0.2
Build type: Release
Our sample matches your code snippets:

Metro assetExts — added ‘html’ with the exact .includes(‘html’) ? … : […] guard.
Asset load — Image.resolveAssetSource(require(‘./assets/player-overlay.html’)).uri.
Layout — KeplerVideoView + a transparent WebView container as siblings inside one parent View; WebView wired with onMessage, onLoadStart → setIsWebViewReady(false), onLoad → setIsWebViewReady(true).
Styles — container {flex:1}, overlayWebView {flex:1, transparent}, modalContainer {transparent, position:‘absolute’, top:0, left:0}.
TV input — useTVEventHandler from @amazon-devices/react-native-kepler forwarding keys via injectJavaScript.
Bidirectional comms — overlay → RN via window.ReactNativeWebView.postMessage(…) handled by onMessage; RN → overlay via webRef.current.injectJavaScript(…).
Readiness gating — all injectJavaScript calls gated behind an isWebViewReady flag (true in onLoad, false in onLoadStart).
HTML overlay — background: transparent on both html and body; only the control elements have visible styling.
Components — @amazon-devices/webview for the WebView, @amazon-devices/react-native-kepler for useTVEventHandler, KeplerVideoView (from @amazon-devices/react-native-w3cmedia) for the video, with a UI-thread VideoPlayer.
Result

Before playback: the overlay renders correctly and is fully interactive (play/pause, scrub, remote input all work).
The instant the native video surface activates (KeplerVideoView: onSurfaceViewCreated / W3CMEDIA: setVideoSurface), the overlay disappears. Only the video is visible afterward.
In the device log this lines up exactly with setVideoSurface:

[OverlaySpike] overlay → RN message: {“type”:“OVERLAY_READY”} # overlay visible & interactive
VwContents::SetSize width: 1920 height 1080 # WebView laid out
KeplerVideoView: onSurfaceViewCreated 1
VideoPlayer: setSurfaceHandle: 1
W3CMEDIA: setVideoSurface: surface = SurfaceRef:0x… # ← overlay disappears here
During the transition the WebView shows as Window role: Overlay and the app/video as Window role: Full screen, which appears to composite above the overlay. We also tried a headless KeplerVideoSurfaceView and an explicit zIndex on the overlay — same result in both cases, so this does not look like a JS-side styling or z-order issue.

the full source is inline below.

OverlaySpike.tsx

// @ts-nocheck
import React, {useRef, useState, useCallback} from 'react';
import {View, StyleSheet, Image} from 'react-native';
import {useTVEventHandler} from '@amazon-devices/react-native-kepler';
import {VideoPlayer, KeplerVideoView} from '@amazon-devices/react-native-w3cmedia';
import {WebView} from '@amazon-devices/webview';

// Public clear MP4 (URL mode — no MSE/DRM needed to show the compositing issue).
const VIDEO_URL = 'https://media.w3.org/2010/05/sintel/trailer.mp4';

// Per recipe: load the overlay HTML as a bundled asset.
const overlaySource = {
uri: Image.resolveAssetSource(require('./assets/player-overlay.html')).uri,
};

export const OverlaySpike = () => {
const video = useRef<VideoPlayer | null>(null);
const webRef = useRef(null);
const [videoReady, setVideoReady] = useState(false);
const [isWebViewReady, setIsWebViewReady] = useState(false);

if (video.current === null) {
if (global.navigator === undefined) { global.navigator = {}; }
if (global.window === undefined) { global.window = global; }
video.current = new VideoPlayer();
}

const started = useRef(false);
if (!started.current) {
started.current = true;
(async () => {
try {
const vp = video.current;
await vp.initialize();
setVideoReady(true);
// Short delay so the overlay is visibly on screen BEFORE video starts.
await new Promise(r => setTimeout(r, 5000));
vp.src = VIDEO_URL;
vp.autoplay = true;
vp.load();
vp.play();
} catch (e) {
console.error('\[OverlaySpike\] init failed', e);
}
})();
}

const handleTransportMessage = useCallback((event: any) => {
try {
const data = JSON.parse(event.nativeEvent.data);
console.log('\[OverlaySpike\] overlay -> RN message:', JSON.stringify(data));
} catch (\_) {}
}, [ ]);

const tvEventHandler = useCallback((evt: any) => {
if (!evt || !isWebViewReady || !webRef.current) { return; }
const js = `(function(){ if (window.onTvKey) window.onTvKey(${JSON.stringify(evt.eventType)}); })();true;`;
try { webRef.current.injectJavaScript(js); } catch (\_) {}
}, \[isWebViewReady\]);
useTVEventHandler(tvEventHandler);

return (

{/\* Native video base (rendered first). */}
{videoReady ? (

) : null}
{/* Transparent overlay (sibling on top). \*/}

<WebView
ref={webRef}
source={overlaySource}
style={styles.overlayWebView}
javaScriptEnabled={true}
domStorageEnabled={true}
allowSystemKeyEvents={true}
allowFileAccess={true}
onMessage={handleTransportMessage}
onLoadStart={() => setIsWebViewReady(false)}
onLoad={() => setIsWebViewReady(true)}
/>


);
};

const styles = StyleSheet.create({
container: {flex: 1},
// absoluteFill covers the full 4K panel (literal 1920x1080 would cover only
// the top-left quadrant on this device). Does not affect the disappearance.
backgroundVideo: {...StyleSheet.absoluteFillObject},
overlayWebView: {flex: 1, backgroundColor: 'rgba(0,0,0,0)'},
modalContainer: {...StyleSheet.absoluteFillObject, backgroundColor: 'rgba(0,0,0,0)'},
});

player-overlay.html


<!doctype html>

<html>
  <head>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <style>
      /* Per recipe: transparent on both html and body; only controls are visible. */
      html, body {
        margin: 0; height: 100vh; width: 100vw;
        background: transparent !important;
        overflow: hidden; font-family: sans-serif; color: #fff;
      }
      .top { position: absolute; top: 0; left: 0; right: 0; padding: 48px 64px;
        background: linear-gradient(to bottom, rgba(0,0,0,0.75), rgba(0,0,0,0)); }
      .title { font-size: 52px; font-weight: 700; }
      .controls { position: absolute; left: 0; right: 0; bottom: 0; padding: 48px 64px 64px;
        background: linear-gradient(to top, rgba(0,0,0,0.85), rgba(0,0,0,0)); }
      .track { position: relative; height: 10px; border-radius: 6px; background: rgba(255,255,255,0.3); }
      .fill { position: absolute; top: 0; left: 0; height: 10px; border-radius: 6px; width: 35%; background: #00a0ff; }
      .btns { display: flex; justify-content: center; align-items: center; gap: 72px; margin-top: 36px; }
      .play { width: 104px; height: 104px; border-radius: 50%; background: rgba(255,255,255,0.18);
        border: 3px solid #fff; display: flex; align-items: center; justify-content: center; font-size: 52px; }
    </style>
  </head>
  <body>
    <div class="top"><div class="title">Overlay controls</div></div>
    <div class="controls">
      <div class="track"><div class="fill" id="fill"></div></div>
      <div class="btns"><div class="play" id="play">&#10073;&#10073;</div></div>
    </div>
    <script>
      var playing = true;
      window.onTvKey = function (key) {
        if (key === 'select' || key === 'playpause') {
          playing = !playing;
          document.getElementById('play').innerHTML = playing ? '&#10073;&#10073;' : '&#9654;';
        }
        postToNative({ type: 'TRANSPORT', key: key });
      };
      function postToNative(msg) {
        try {
          if (window.ReactNativeWebView && window.ReactNativeWebView.postMessage) {
            window.ReactNativeWebView.postMessage(JSON.stringify(msg));
          }
        } catch (e) {}
      }
      postToNative({ type: 'OVERLAY_READY' });
    </script>
  </body>
</html>

metro.config.js


const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
const defaultConfig = getDefaultConfig(\__dirname);
const config = {
resolver: {
assetExts: defaultConfig.resolver.assetExts.includes('html')
? defaultConfig.resolver.assetExts
: \[...defaultConfig.resolver.assetExts, 'html'\],
},
};
module.exports = mergeConfig(defaultConfig, config);

App.tsx


import React from 'react';
import {OverlaySpike} from './OverlaySpike';

export const App = () => {
return ;
};

Questions

  1. What in your validated setup keeps the transparent WebView above the active video surface? Is there a required prop/call we’re missing? (KeplerVideoView exposes only showControls, showCaptions, videoPlayer, scalingmode.)
  2. Is this OS-build- or resolution-dependent? Which OS build and resolution was the recipe validated on? (We’re on OS 2.0 build 515 at 4K.)

Thanks,
Hari

Hi @Hari_K,

Thank you for the detailed bug report on the WebView overlay disappearing over KeplerVideoSurfaceView when the native video surface activates.

We stood up a minimal repro matching your stack (RN 0.83, react-native-kepler 4.x, webview 4.0.2, react-native-w3cmedia 2.3.2) and confirmed the native sequence you reported: KeplerVideoView: onSurfaceViewCreated → VideoPlayer: setSurfaceHandle → W3CMEDIA:setVideoSurface. We agree with your read that this is window/surface-level compositing rather than a React Native z-order or styling issue.

Our team is investigating this issue and will provide an update as soon as we have more information.

To help us trace the compositing path on the exact build where you see this, could you please share the full device logs captured during a reproduction (from app launch through setVideoSurface), following our Vega log collection guide: Manage Files, Crash Reports, and Logs - Amazon Vega Docs . The complete loggingctl capture - rather than an excerpt — will let us compare the Window role transitions on your OS 2.0 build against what we see locally.

Thanks for helping us improve the Vega platform.

Warm regards,
Aishwarya

Hi @amen ,

I’m not able to attach or paste the entire logs here. I have attached the requested logs in the support ticket Amazon Developer Sign-In please do let me know if you need any further details.

Thanks,
Hari

Hello all

We are hitting what looks like the same window-level compositing issue, from the opposite direction, and on the RN 0.72 track rather than 0.83 — so it may be wider than webview 4.0.x.

Environment

  • Device: Fire TV Stick (Carnival), armv7l
  • OS: Vega OS 2.0 (TV Ship/77)
  • Display: 3840x2160 (4K)
  • RN for Vega 0.72 / @amazon-devices/react-native-kepler 2.x
  • @amazon-devices/webview 3.5.13
  • @amazon-devices/react-native-w3cmedia 2.3.5
  • Build type: Release

What we are doing

Our app plays video two ways: natively through KeplerVideoView, or through a web-based player inside a WebView. To avoid paying the web player’s start-up cost on every playback, we keep that WebView mounted while the user browses, rendered behind the rest of the UI and showing nothing.

What we observe

While a WebView is mounted anywhere in the app, a KeplerVideoSurfaceView renders black. Audio plays normally and playback progresses — only the video is missing. Unmounting the WebView fixes it immediately and reliably. Two distinct cases:

  1. A small, downscaled surface (video in a focused card, roughly a quarter of
    the screen) is black every time.
  2. A full-screen surface is black intermittently. Leaving the screen and starting playback again usually clears it after a few attempts, which makes it look like a race rather than a fixed ordering.

So this is the mirror image of the report above: there the video wins and the WebView overlay disappears; here the WebView wins and the video surface stays black.

What we ruled out, each on a device build

  • Opaque or transparent paint at every level: the RN root view, the WebView’s
    container, the WebView style, and the page’s own body.
  • Tree order: the WebView above and below the rest of the app tree.
  • RN zIndex and elevation on either side.
  • Collapsing the WebView to no size instead of unmounting it.
  • Mounting the WebView after the video surface is already created and rendering frames — the video goes black the moment the WebView appears.
  • The page’s content: with source={{ uri: 'about:blank' }}, so no app code, no player, no JavaScript and nothing painted, a mounted WebView still blacks out the video surface.

That last one is the part we would highlight. An empty WebView is enough, so for us this is not about WebView transparency, z-order or anything the page does — it appears to be the existence of the WebView’s native window.

Questions

  1. Is this the same defect you are already investigating, or should we file it separately?
  2. Is there any supported way to keep a WebView mounted without it taking part in the stacking of a sibling video surface — for example suspending or detaching its native window while keeping its JavaScript context alive? Today unmounting is our only option, and it costs us the whole web player start-up on every switch between the two players.
  3. Is a fix expected to give apps control over sibling ordering, or will the platform decide it? That determines whether we design around this or wait.

Happy to attach a full loggingctl capture of either case if useful.

Hi @Luis,

Thank you for the detailed report on KeplerVideoSurfaceView rendering black while a WebView is mounted, and for listing everything you’ve already ruled out.

Our team is investigating this issue and will provide an update as soon as we have more information.

To help with the investigation, could you please share the full device logs (loggingctl) for both cases, following our Vega log collection guide: Manage Files, Crash Reports, and Logs - Amazon Vega Docs

  1. Small, downscaled surface: from app launch until the video renders black
  2. Full-screen surface: from app launch through a reproduction where the video stays black

If the forum doesn’t allow you to upload the logs, please share a link to them instead.

Thanks for helping us improve the Vega platform.

Warm regards,
Aishwarya

Hi @amen ,

Logs attached bellow. Two notes on how they were produced, because both narrow the problem.

First, in these captures the WebView’s page is source={{ uri: 'about:blank' }} and the WebView is mounted unconditionally from app launch. No application page, player, or JavaScript in the webview is involved — the page never progresses past booting, which you can see in our own instrumentation as page-released … { pageState: 'booting' }. The WebView renderer process comes up one second after app start:

09:58:57.609  stemd: stem{pid=26959} ready and associated with a component,
              id="com.amazon.webview.renderer_service"

and stays for the session. So what is on screen alongside the video surface is an empty WebView’s native window and nothing else.

Second, our first attempt at a capture was rate-limited by journald — it carried Suppressed N messages from Toolkit/UI notices, and the GWSI_LOG:<seq> counters showed about a third of the lines missing, concentrated around surface creation. These captures were taken with the limit raised. If you collect logs for this internally, it may be worth checking the same thing.

In the attached session there are four playback attempts with the WebView mounted throughout. One rendered; three were black with audio playing normally. That intermittency matches what I described for the full-screen case.

What the logs show about where it fails may be more useful than the black frame itself. On a failing attempt, the native side creates and configures the surface:

09:59:41.313  VideoSurfaceViewManager: onSurfaceCreated view:0x1012c40
09:59:41.313  VideoSurfaceViewManager: setWindowScalingMode: Set scale mode to: fit
09:59:41.332  WARNING [KeplerScript-JavaScript] Unsupported top level event type
              topOnKeplerVideoSurfaceViewCreated dispatched

and the component is never told. There is no Emitted event for KeplerVideoSurfaceViewCreated handle:N, no KeplerVideoView: onSurfaceViewCreated, and therefore no VideoPlayer: setSurfaceHandle. The decoder and audio run regardless, which is what the user sees.

On the attempt that rendered, in the same session and the same build, the whole chain completes in 37 ms:

09:59:54.786  VideoSurfaceViewManager: onSurfaceCreated:2
09:59:54.792  VideoSurfaceViewManager: Emitted event for KeplerVideoSurfaceViewCreated handle:2
09:59:54.792  GWSI_LOG: Window 3 lifecycle state changed: Bound -> Visible
09:59:54.812  KeplerVideoView: onSurfaceViewCreated 2
09:59:54.812  VideoPlayer: setSurfaceHandle: 2

Across four surface mounts in this session, setSurfaceHandle was reached once. We are on @amazon-devices/react-native-w3cmedia 2.3.5, where KeplerVideoView binds the surface only inside its internal surface-created callback, so a missed event leaves the pipeline with no render target for the life of that surface, and the application has no way to notice or retry.

Questions, in addition to the three in my earlier post:

  • Is the surface-created event delivery expected to be reliable, and is the Unsupported top level event type topOnKeplerVideoSurfaceViewCreated dispatched warning relevant? It appears on every attempt, including the one that succeeded, where it lands immediately after the handler has already run — which suggests the event goes out over two paths and one of them is unregistered.

  • Is there a recommended ordering between surface creation and calling load() on the player? We currently mount the surface after the stream has loaded; if the platform expects the surface to exist first, we will change that and retest.

  • Does any of this change if the WebView is present but its window is never shown? We have not found a way to express that through @amazon-devices/webview 3.5.13, which is the subject of my second question in the earlier post.

Happy to capture more, including with specific log tags raised if you tell us which ones your team wants.

logsfull.txt (2.6 MB)