From 4e8caa4245ae238e3856203467f5d7ce798cdc11 Mon Sep 17 00:00:00 2001 From: robertjamesprior <83608739+robertjamesprior@users.noreply.github.com> Date: Fri, 18 Sep 2026 21:28:35 +0000 Subject: [PATCH 1/2] Document live view parent frame events The embedded live view already posts connection and playback events to the parent window, but none of them were documented, so an embedder had no supported way to tell a working viewer from one that never starts. Documents the five outbound events and the one inbound event, the recommended health check gating on KERNEL_PLAYING, and the referrer requirement for read-only control. Co-Authored-By: Claude Opus 5 --- browsers/live-view.mdx | 59 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/browsers/live-view.mdx b/browsers/live-view.mdx index 7cfefa9..e68794f 100644 --- a/browsers/live-view.mdx +++ b/browsers/live-view.mdx @@ -88,6 +88,65 @@ connect-src https://*.onkernel.com:8443 ``` +## Parent frame events + +When the live view is embedded in an iframe, the client posts messages to the parent window as the connection and playback state change, and accepts one message back. Use them to tell a working viewer apart from one that never starts. + +### Sent to the parent + +| Event | Payload | Meaning | +| --- | --- | --- | +| `KERNEL_CONNECTED` | `connected`, `capabilities` | Signaling is established. Frames are not necessarily rendering yet. | +| `KERNEL_PLAYING` | `playing: true` | Video frames are rendering. | +| `KERNEL_PAUSED` | `playing: false` | Playback has stopped. | +| `KERNEL_CONNECTION_TIMEOUT` | `reason`, `iceConnectionState`, `connectionState`, `signalingState`, `socketOpen` | The client's connection watchdog expired. Useful for diagnostics. | +| `KERNEL_READ_ONLY_CHANGED` | `readOnly`, `requestId` | Acknowledges a `KERNEL_SET_READ_ONLY` request. | + +### Accepted from the parent + +| Event | Payload | Effect | +| --- | --- | --- | +| `KERNEL_SET_READ_ONLY` | `readOnly` (boolean), `requestId` (string, optional) | Toggles interactivity without reloading the iframe. Acknowledged with `KERNEL_READ_ONLY_CHANGED`. | + + + `KERNEL_CONNECTION_TIMEOUT`, `KERNEL_READ_ONLY_CHANGED` and `KERNEL_SET_READ_ONLY` require a recent browser image. `KERNEL_CONNECTED`, `KERNEL_PLAYING` and `KERNEL_PAUSED` are available on all current images. + + Messages are exchanged with the parent origin derived from `document.referrer`. If the referrer is unavailable — for example under a restrictive `Referrer-Policy` — the client cannot resolve your origin and will reject `KERNEL_SET_READ_ONLY`. + + +### Detecting a viewer that never starts + +Gate on `KERNEL_PLAYING`. It fires only once frames actually arrive, so it is the one signal that distinguishes a working viewer from one that is still connecting or has silently failed. Start a timer when you mount the iframe and remount if `KERNEL_PLAYING` has not arrived: + +```typescript Typescript/Javascript +const iframe = document.querySelector('#kernel-live-view'); +const src = iframe.src; +const liveViewOrigin = new URL(src).origin; + +let attempts = 0; +let watchdog; + +function arm() { + clearTimeout(watchdog); + watchdog = setTimeout(() => { + if (attempts++ >= 2) return showFallback(); + iframe.src = 'about:blank'; + iframe.src = src; + arm(); + }, 15000); +} + +window.addEventListener('message', (event) => { + if (event.origin !== liveViewOrigin) return; + if (event.data?.type === 'KERNEL_PLAYING') clearTimeout(watchdog); + if (event.data?.type === 'KERNEL_PAUSED') arm(); +}); + +arm(); +``` + +Do not gate on `KERNEL_CONNECTION_TIMEOUT` alone. The watchdog behind it is cleared once negotiation begins, so a connection that stalls after that point never emits it. Log it alongside `KERNEL_PLAYING` to capture the connection state at the moment things stalled. + ## Kiosk mode Kiosk mode provides a fullscreen live view experience without browser UI elements like the address bar and tabs. You can enable kiosk mode when creating a browser by setting the `kiosk_mode` parameter to `true`. From 329afae46061a67b83d337414bfbed1a1fec34ad Mon Sep 17 00:00:00 2001 From: robertjamesprior <83608739+robertjamesprior@users.noreply.github.com> Date: Fri, 18 Sep 2026 22:01:51 +0000 Subject: [PATCH 2/2] Mark KERNEL_CONNECTED capabilities as recent-image only The event ships on all current images, but the capabilities field was added alongside the read-only acknowledgement work; older active images post only { type: 'KERNEL_CONNECTED', connected: true }. Co-Authored-By: Claude Opus 5 --- browsers/live-view.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/browsers/live-view.mdx b/browsers/live-view.mdx index e68794f..6286292 100644 --- a/browsers/live-view.mdx +++ b/browsers/live-view.mdx @@ -96,7 +96,7 @@ When the live view is embedded in an iframe, the client posts messages to the pa | Event | Payload | Meaning | | --- | --- | --- | -| `KERNEL_CONNECTED` | `connected`, `capabilities` | Signaling is established. Frames are not necessarily rendering yet. | +| `KERNEL_CONNECTED` | `connected`, `capabilities` (recent images only) | Signaling is established. Frames are not necessarily rendering yet. | | `KERNEL_PLAYING` | `playing: true` | Video frames are rendering. | | `KERNEL_PAUSED` | `playing: false` | Playback has stopped. | | `KERNEL_CONNECTION_TIMEOUT` | `reason`, `iceConnectionState`, `connectionState`, `signalingState`, `socketOpen` | The client's connection watchdog expired. Useful for diagnostics. | @@ -109,7 +109,7 @@ When the live view is embedded in an iframe, the client posts messages to the pa | `KERNEL_SET_READ_ONLY` | `readOnly` (boolean), `requestId` (string, optional) | Toggles interactivity without reloading the iframe. Acknowledged with `KERNEL_READ_ONLY_CHANGED`. | - `KERNEL_CONNECTION_TIMEOUT`, `KERNEL_READ_ONLY_CHANGED` and `KERNEL_SET_READ_ONLY` require a recent browser image. `KERNEL_CONNECTED`, `KERNEL_PLAYING` and `KERNEL_PAUSED` are available on all current images. + `KERNEL_CONNECTION_TIMEOUT`, `KERNEL_READ_ONLY_CHANGED` and `KERNEL_SET_READ_ONLY` require a recent browser image. `KERNEL_CONNECTED`, `KERNEL_PLAYING` and `KERNEL_PAUSED` are available on all current images, but `capabilities` is sent only by recent ones — older images post `{ type: 'KERNEL_CONNECTED', connected: true }`, so treat a missing `capabilities` as unknown rather than unsupported. Messages are exchanged with the parent origin derived from `document.referrer`. If the referrer is unavailable — for example under a restrictive `Referrer-Policy` — the client cannot resolve your origin and will reject `KERNEL_SET_READ_ONLY`.