Document computed telemetry readiness events

[robertjamesprior]

Replaces #606. That PR was auto-closed and can't be reopened: it was pushed from a shallow clone, so its branch history didn't connect to main. Same content, rebuilt on real history.

Description

browsers/telemetry/categories.mdx lists network_idle, page_layout_settled, page_navigation_settled, and interaction_scroll_settled in the category tables but never says what they mean. Each of those names appears exactly once in this repo, in that one table row.

Unlike the other event types in those tables, these four aren't 1-to-1 with a CDP notification. Kernel computes them from sequences of CDP events, so a reader can't infer the timing from the name. network_idle is the most likely to mislead: it shares a name with Playwright's networkidle wait state and uses the same 500 ms quiet-period heuristic, but it's an observation you receive once per navigation rather than something you await.

This adds a ### Computed readiness events section under Browser activity, following the shape of the existing ### Correlate captcha tasks and challenges section: a table of when each event fires, then the caveats that affect how you consume them.

Scope is deliberately limited to observable behavior a consumer can depend on: when each event fires, what gates it, how often, and when not to trust it. Internal mechanics (dedup windows, navigation-sequence fencing, lock ordering) are left out because they'll drift.

Source

Every claim is taken from the emitting code in kernel/kernel-images:

Claim	Source
500 ms and 1 s debounce constants	server/lib/cdpmonitor/computed.go
A layout shift restarts the 1 s wait	computed.go, onLayoutShift
page_load gates page_layout_settled	computed.go, pageLoadSeen guard
page_navigation_settled needs both inputs, fires once	computed.go, pendingNavigationSettled
Independent of network_idle by design	computed.go + server/lib/cdpmonitor/README.md
Per-navigation reset; stale timers discarded	computed.go, resetOnNavigation
network_idle can fire early on mid-flight attach	computed.go, onLoadingFinished
Computed state unreliable after a disconnect	monitor_disconnected schema docs
300 ms debounce and 5 px scroll threshold	server/lib/cdpmonitor/interaction.js

Testing

• Verified on the Mintlify preview build for this branch: the page returns 200, the new section and all four event names render, and no literal <Note> tag leaks into the output. mintlify dev wasn't run locally (CLI unavailable in the authoring environment); the preview deployment covers it.

Visual Proof

None attached. No new components, images, or navigation entries; the section reuses the existing table and <Note> patterns already on this page. Preview link is on the deployment comment below.

Related Issue

None.

Additional Notes

No docs.json change needed; this is a new ### on an existing page.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only change to categories.mdx with no runtime, API, or configuration impact.

Overview
Adds a Computed readiness events section under Browser activity on the telemetry categories page, documenting when Kernel-derived events fire and how to use them.

The new content explains that network_idle, page_layout_settled, and page_navigation_settled are computed from CDP sequences (not raw Chrome events), with a table of timing rules, per-navigation reset behavior, and guidance to prefer page_navigation_settled as the combined DOM + layout readiness signal. It also contrasts network_idle with Playwright’s networkidle wait, documents interaction_scroll_settled (300 ms debounce, 5 px threshold), and calls out caveats for mid-flight attach and unreliable state after monitor_disconnected.

^{Reviewed by Cursor Bugbot for commit 09630f7. 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, 7:34 PM

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

[robertjamesprior]

identified this as a high ROI add to docs to improve navigations

[cursor]

Risk assessment: Very Low

Verdict: Very Low risk. Approved.

What changed (from the diff):

• One file: browsers/telemetry/categories.mdx (+22 / −0)
• Adds a ### Computed readiness events section under the existing Browser activity heading
• Content is prose, a table, and a <Note> using patterns already on the page

Why Very Low:

• Documentation-only change on an existing Mintlify page
• No docs.json, navigation, CI, or config edits
• No application, API, auth, or infrastructure code
• No CODEOWNERS file in this repo, so code-owner review is not required
• Small, isolated surface with no production logic or shared-system impact

This is not a prompt or model-instruction change; it documents existing telemetry event names already listed in the category tables.

  

_{Sent by Cursor Automation: Assign PR reviewers}