diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index e89c74e..3908b9a 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`.