Document live view parent frame events

browsers/live-view.mdx

@@ -88,6 +88,65 @@ connect-src https://*.onkernel.com:8443
 ```
 </Info>
 
+## 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` (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. |
+| `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`. |
+
+<Info>
+    `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`.
+</Info>
+
+### 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`.