[robertjamesprior]

Three corrections to the live view embedding guidance, plus a pass over the prose that changed.

The media reason row. It said the bound expires if ICE never reached checking. Since kernel-images#417 the client keeps the media bound armed through connected, so it expires only if ICE never arrives at connected or completed — completed is the other way a healthy connect can land when gathering is already done. An embedder branching on reason would otherwise expect media to fire earlier than it does. This row is the one kernel/docs#698 carried, which this PR supersedes.

The example watchdog. It remounted 15s after mount. The client's connect bounds run in sequence — transport, then signaling, then media — and sum to 48s, so an embedder following the snippet tore the frame down before the client could report which stage stalled. The example now uses 60s, and the prose says why the timer needs room above the budget: it also covers loading the frame itself.

The transport and peer rows. A socket close at any point before the connect succeeds reports transport, not only one before signaling, and peer also covers ICE reaching failed or closed and the data channel closing before the connect. The retry advice under the example follows: remounting repeats a construction or offer throw, but it can fix an ICE failure, so that case is worth one retry.

The note claiming KERNEL_CONNECTION_TIMEOUT stops firing once negotiation begins is corrected the same way: the media bound stays armed past checking until ICE reaches connected or completed, so a connect stalling in between does report one. What never emits it is a viewer whose frames stop after it connected.

Paired with kernel-images#472, which serves the bounds with the page from the live view proxy's environment, so a region can retune them without a browser image release. The defaults stay at transport 15s, signaling 3s and media 30s. Merge order doesn't matter for the docs themselves, but the two describe the same client.

Docs only, prose and one snippet constant. I didn't run mint broken-links on this revision because mint isn't installed in this environment; the change touches no links and the check passed on the previous revision.

---

Note

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

Overview
Updates live view iframe embedding docs so reason handling and watchdog timing match current client connect behavior.

The media timeout reason now states ICE must reach connected or completed within the bound (not merely checking), including peers that stall after checking. KERNEL_CONNECTION_TIMEOUT guidance is updated the same way: the media bound stays active until those states, and viewers that lose frames after a successful connect will not emit it.

The example remount watchdog increases from 15s to 50s, with new prose that sequential connect stages default to 48s total and embedders should allow extra time for iframe load and waking a sleeping browser.

Reviewed by Cursor Bugbot for commit 044c381. Bugbot is set up for automated code reviews on this repo. Configure here.

---

Note

Low Risk
Documentation-only updates to embedding guidance; no runtime or API behavior changes.

Overview
Updates live view embedding docs so they match current client connect behavior (post kernel-images#417).

The media timeout reason is corrected: the bound applies until ICE reaches connected or completed, not merely checking, so embedders branching on reason won't expect media too early.

The “viewer never starts” section adds that default stage timeouts sum to 48s (transport → signaling → media) and that remount timers must exceed that budget plus iframe load time. The sample watchdog timeout changes from 15s to 60s.

Guidance on KERNEL_CONNECTION_TIMEOUT is rewritten: the media bound clears at connected/completed (not when negotiation starts), so mid-connect stalls can still emit the event; viewers that fail after frames were playing will not.

Reviewed by Cursor Bugbot for commit cf3da30. Bugbot is set up for automated code reviews on this repo. Configure here.

---

Note

Low Risk
Documentation-only updates to live view embedding guidance; no runtime or API changes in this repo.

Overview
Aligns live view iframe embedding docs in browsers/live-view.mdx with current connect-stage behavior so embedders branch on reason and watchdog timing correctly.

The reason table is updated: transport covers socket closure anytime before connect succeeds; media fires when ICE never reaches connected or completed (not merely checking); peer also covers ICE failed/closed and early data-channel closure.

The “never starts” section adds that default stage bounds run transport → signaling → media and sum to 48s, so remount timers must exceed that plus iframe load. The sample watchdog changes from 15s to 60s. KERNEL_CONNECTION_TIMEOUT prose now matches the media bound (clears at connected/completed; no timeout after a successful connect). Remount guidance splits peer by cause—environment vs network—and limits blind retries accordingly.

^{Reviewed by Cursor Bugbot for commit 46f1d17. 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	Oct 20, 2026, 3:45 PM

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

[Sayan-]

overal looks good. needs a deslop to conform to docs language guidance

[masnwilliams]

lgtm. the media row and the timeout note now match the client: the bound stays armed until ICE reaches connected or completed, and the 48s total checks out against the 15/3/30 defaults. a few small notes inline, none blocking.

non-blocking follow-up, separate from this PR: the transport and peer rows still don't match how the client picks a reason. a socket close at any point before the connect succeeds reports transport, not only before signaling. ICE failed/closed or the data channel closing before connect falls through to peer. that makes the line 166 advice wrong for ICE failures, since remounting can fix a network-path failure. worth a separate pass.

[masnwilliams]

the wake doesn't add time on top of the budget. the proxy wakes the browser before the socket opens, so that time is already inside the 15s transport bound. only loading the page itself is extra. maybe:

Suggested change

Gate on `KERNEL_PLAYING`. It fires only once frames actually arrive, so it is the signal that distinguishes a working viewer from one that is still connecting or has silently failed. The terminal events below tell you when the client has stopped trying. Start a timer when you mount the iframe and remount if `KERNEL_PLAYING` has not arrived. The timer has to outlast the client's connect bounds, which run in sequence — transport, then signaling, then media — and sum to 48s by default. If you wait less than that, you'll tear the frame down before it can report a stage that stalled late. The timer also covers loading the frame, including waking a browser that has gone to sleep, so leave room above the budget when you set it:

Gate on `KERNEL_PLAYING`. It fires only once frames actually arrive, so it is the signal that distinguishes a working viewer from one that is still connecting or has silently failed. The terminal events below tell you when the client has stopped trying. Start a timer when you mount the iframe and remount if `KERNEL_PLAYING` has not arrived. The timer has to outlast the client's connect bounds, which run in sequence — transport, then signaling, then media — and sum to 48s by default. If you wait less than that, you'll tear the frame down before it can report a stage that stalled late. The timer also covers loading the frame itself, so leave room above the budget when you set it:

[masnwilliams]

nit: 50s leaves 2s over a 48s budget, which is thin for "leave room above the budget", and once the bounds can be tuned per region the budget can grow past 48s. 60s seems safer and costs little, because FAILED/TIMEOUT already show the fallback right away and this timer only catches silent stalls.

Suggested change

	}, 50000);
	}, 60000);

[masnwilliams]

nit: the docs style guide asks for contractions.

Suggested change

	Do not gate on `KERNEL_CONNECTION_TIMEOUT` alone. It only covers a connect that is still negotiating: the media bound clears once ICE reaches `connected` or `completed`, and a viewer whose frames stop after it connected never emits one. Log it alongside `KERNEL_PLAYING` to capture the connection state at the moment things stalled.
	Don't gate on `KERNEL_CONNECTION_TIMEOUT` alone. It only covers a connect that is still negotiating: the media bound clears once ICE reaches `connected` or `completed`, and a viewer whose frames stop after it connected never emits one. Log it alongside `KERNEL_PLAYING` to capture the connection state at the moment things stalled.

[Sayan-]

I'm not sure we should be encoding timeout values in our docs, esp since we may tune these dynamically, etc. I don't have a counter proposal, however, at this point.

[Sayan-]

Thanks for iterating! No other blocks from me