Document live view parent frame events

[robertjamesprior]

Summary

The embedded live view client already posts connection and playback events to the parent window, and accepts one message back, but none of them were documented. An embedder following the docs rendered the iframe and had no signal for success or failure — a viewer that never connects looks exactly like one that is still loading.

Adds a "Parent frame events" section to browsers/live-view.mdx covering:

• The five events sent to the parent (KERNEL_CONNECTED, KERNEL_PLAYING, KERNEL_PAUSED, KERNEL_CONNECTION_TIMEOUT, KERNEL_READ_ONLY_CHANGED) and the one accepted from it (KERNEL_SET_READ_ONLY), with their payloads.
• The recommended health check: gate on KERNEL_PLAYING, since it fires only once frames actually arrive, and remount the iframe if it hasn't arrived within a bounded window.
• Why KERNEL_CONNECTION_TIMEOUT is not sufficient on its own — the watchdog behind it is cleared once negotiation begins, so a connection that stalls after that point never emits it.
• That the parent origin is derived from document.referrer, so a restrictive Referrer-Policy leaves the client unable to resolve the embedder's origin and causes KERNEL_SET_READ_ONLY to be rejected.

Events, payloads and the origin behaviour were read off the image client rather than taken from an existing description. Availability is described as "a recent browser image" rather than naming image tags, since those aren't a documented surface.

Testing

mint broken-links passes locally, which is what CI runs.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only change to live view embedding guidance; no runtime or API behavior changes in this repository.

Overview
Adds a Parent frame events section to the live view docs so embedders can observe iframe postMessage traffic and drive read-only mode without reloading.

The new content catalogs five outbound events (KERNEL_CONNECTED, KERNEL_PLAYING, KERNEL_PAUSED, KERNEL_CONNECTION_TIMEOUT, KERNEL_READ_ONLY_CHANGED) and inbound KERNEL_SET_READ_ONLY, including payload shapes and which behaviors need a recent browser image vs. legacy KERNEL_CONNECTED without capabilities.

It also documents operational guidance: use KERNEL_PLAYING as the health signal (with a TypeScript remount/watchdog example), why KERNEL_CONNECTION_TIMEOUT alone is insufficient after negotiation starts, and that parent origin trust depends on document.referrer (so strict Referrer-Policy can block KERNEL_SET_READ_ONLY).

^{Reviewed by Cursor Bugbot for commit 329afae. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Kernel	🟢 Ready	View Preview	Sep 18, 2026, 10:02 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[cursor]

Risk assessment: Very Low

Decision: No new approval. This automation already approved commit 329afae and the PR has not changed since.

Independent re-evaluation of the current diff:

• Scope: One file, browsers/live-view.mdx (+59 / -0). Adds a Parent frame events section: outbound/inbound event tables, an origin/referrer note, and a TypeScript example that gates on KERNEL_PLAYING.
• Codepaths / blast radius: Documentation-only. No application, API, config, CI, or infrastructure files change. The TypeScript block is example copy, not shipped runtime.
• Infrastructure / ops: None.
• Security / shared systems: None. This documents existing iframe postMessage events; it does not change auth, permissions, or runtime behavior.
• CODEOWNERS: No CODEOWNERS file. The main branch ruleset does not require code-owner review.

Risk is unchanged (Very Low). No approval to revoke.

  

_{Sent by Cursor Automation: Assign PR reviewers}