From 09630f7fb7a998967beb4799beb495c2329e1f31 Mon Sep 17 00:00:00 2001 From: robertjamesprior <83608739+robertjamesprior@users.noreply.github.com> Date: Fri, 18 Sep 2026 19:34:06 +0000 Subject: [PATCH] Document computed telemetry readiness events network_idle, page_layout_settled, page_navigation_settled, and interaction_scroll_settled were listed in the category tables with no explanation of when they fire. Unlike the other event types there, Kernel computes them from sequences of CDP events, so the name alone doesn't convey the timing. Co-Authored-By: Claude Opus 5 --- browsers/telemetry/categories.mdx | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index e89c74ec..3908b9ad 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -115,6 +115,28 @@ These categories report what's happening in the page. Capturing any of them atta `interaction` events are browser-native DOM events observed in the page, not calls to the [computer-control](/browsers/computer-controls) API (those are reported by the `control` category). +### Computed readiness events + +Three of the event types above don't come from Chrome. Kernel computes them from sequences of CDP events, so Kernel defines when they fire: + +| Event type | Category | Fires | +| --- | --- | --- | +| `network_idle` | `network` | 500 ms after the target's in-flight request count reaches zero. | +| `page_layout_settled` | `page` | 1 s after `page_load` with no intervening `page_layout_shift`. Each shift restarts the 1 s wait. | +| `page_navigation_settled` | `page` | Once both `page_dom_content_loaded` and `page_layout_settled` have fired for the same navigation. | + +Each fires at most once per navigation, and all three reset on `page_navigation`. A timer from a previous navigation never fires against the current one. + +`page_navigation_settled` is deliberately independent of `network_idle`, so a single hung request can't stall it. It does depend on `page_layout_settled`, which in turn needs `page_load`, so a page where `load` never fires emits neither. If you want one readiness signal per navigation, consume `page_navigation_settled`: it's the only one gated on both the DOM and visual stability. + +The 1 s layout window covers late-loading web fonts and deferred image reflows. `network_idle` uses the same 500 ms quiet-period heuristic as Playwright's `networkidle` wait state, but it's an observation rather than a wait: it reports that a quiet period happened, and won't re-arm if traffic resumes. + + +`network_idle` counts requests on a single target. If telemetry attaches to a page that's already loading, the monitor can miss requests that started earlier, so `network_idle` might fire before the page is really quiet. After a `monitor_disconnected`, treat in-progress `network_idle` and `page_layout_settled` state as unreliable until `monitor_reconnected` arrives. + + +Kernel computes `interaction_scroll_settled` the same way: it fires 300 ms after the last `scroll` event on a target, and only when the position moved more than 5 px on either axis, so scroll jitter doesn't emit an event. + ### The monitor category `monitor` reports the health of the CDP collector itself: `monitor_disconnected`, `monitor_reconnected`, `monitor_reconnect_failed`, and `monitor_init_failed`.