browser-debugger-cli 0.13.0 → 0.14.0

package/dist/runtime/dom/inspectRules.js

@@ -37,24 +37,218 @@ export function trackStyleSheets(cdp) {
 export function styleSheetHeaders(cdp) {
     return headersByConnection.get(cdp)?.values() ?? [];
 }
+/** Time allowed for the matched rules behind the default hints; a read within it clears the slow mark */
+export const HINTS_BUDGET_MS = 1000;
+/** Time allowed for them with --rules or --why */
+export const RULES_BUDGET_MS = 5000;
+/** Answers that came faster are not kept: reading again is cheap and always current */
+const KEEP_ANSWERS_SLOWER_THAN_MS = 300;
+/**
+ * How long a kept answer is reused. Page state such as `:checked`, `:hover`
+ * or `:focus` changes without any CDP event, so answers are kept only briefly
+ * (and dropped by every command that may change the page, see {@link resetMatchedStyles}).
+ */
+const KEPT_ANSWER_TTL_MS = 5000;
+/** Answers kept per document (one can be several MB on CSS-heavy pages) */
+const MAX_KEPT_ANSWERS = 4;
+/** Stylesheet events: kept answers are dropped and the slow mark cleared */
+const STYLESHEET_EVENTS = ['CSS.styleSheetAdded', 'CSS.styleSheetChanged', 'CSS.styleSheetRemoved'];
+/** Other events after which kept answers may be stale */
+const STYLE_CHANGE_EVENTS = [
+    'CSS.mediaQueryResultChanged',
+    'DOM.attributeModified',
+    'DOM.attributeRemoved',
+    'DOM.inlineStyleInvalidated',
+    'DOM.childNodeInserted',
+    'DOM.childNodeRemoved',
+    'DOM.childNodeCountUpdated',
+    'DOM.pseudoElementAdded',
+    'DOM.pseudoElementRemoved',
+];
+/** Matched-styles state per connection */
+const documentStylesByConnection = new WeakMap();
+/**
+ * The matched-styles state of a connection, tracked from its first use: a
+ * new document (`DOM.documentUpdated`) starts afresh (a request still running
+ * for the old one no longer holds back new ones), stylesheet changes drop the
+ * kept answers and the slow mark, style and DOM changes the kept answers.
+ * Events of other sessions (iframes) are ignored.
+ *
+ * @param cdp - CDP connection
+ * @returns State
+ */
+function documentStyles(cdp) {
+    const existing = documentStylesByConnection.get(cdp);
+    if (existing)
+        return existing;
+    const state = { requests: new Map(), slow: false, document: 0 };
+    documentStylesByConnection.set(cdp, state);
+    cdp.on('DOM.documentUpdated', (_params, sessionId) => {
+        if (sessionId)
+            return;
+        state.document++;
+        state.requests.clear();
+        state.running = undefined;
+        state.slow = false;
+    });
+    for (const event of STYLESHEET_EVENTS) {
+        cdp.on(event, (_params, sessionId) => {
+            if (sessionId)
+                return;
+            state.requests.clear();
+            state.slow = false;
+        });
+    }
+    for (const event of STYLE_CHANGE_EVENTS) {
+        cdp.on(event, (_params, sessionId) => {
+            if (!sessionId)
+                state.requests.clear();
+        });
+    }
+    return state;
+}
+/**
+ * Forget the kept answers of a connection (requests still running stay
+ * shared). For commands that may change the page in ways CDP reports no
+ * event for: clicks, typing, hovering, scripts, emulation.
+ *
+ * @param cdp - CDP connection
+ */
+export function resetMatchedStyles(cdp) {
+    documentStylesByConnection.get(cdp)?.requests.clear();
+}
+/**
+ * Record an answer: a fast one clears the slow mark and is dropped, a slow
+ * one is kept for {@link KEPT_ANSWER_TTL_MS}, a failed one is dropped.
+ *
+ * @param state - Document state
+ * @param nodeId - Node id of the element
+ * @param request - The request
+ * @param tookMs - How long Chrome took
+ */
+function settleRequest(state, nodeId, request, tookMs) {
+    if (state.running === request.promise)
+        state.running = undefined;
+    if (request.document !== state.document)
+        return;
+    const answered = request.answer !== 'failed';
+    if (answered && tookMs <= HINTS_BUDGET_MS)
+        state.slow = false;
+    if (answered && tookMs > KEEP_ANSWERS_SLOWER_THAN_MS) {
+        request.expiresAt = Date.now() + KEPT_ANSWER_TTL_MS;
+    }
+    else if (state.requests.get(nodeId) === request) {
+        state.requests.delete(nodeId);
+    }
+}
+/**
+ * Send a matched-styles request and share it while it runs, dropping the
+ * least recently used entries beyond {@link MAX_KEPT_ANSWERS}.
+ *
+ * @param cdp - CDP connection
+ * @param state - Document state
+ * @param nodeId - Node id of the element
+ * @returns The request
+ */
+function sendMatchedRequest(cdp, state, nodeId) {
+    const sentAt = Date.now();
+    const request = {
+        document: state.document,
+        promise: cdp
+            .send('CSS.getMatchedStylesForNode', { nodeId })
+            .then((response) => response)
+            .catch((error) => {
+            log.debug(`CSS.getMatchedStylesForNode failed: ${String(error)}`);
+            return 'failed';
+        }),
+    };
+    state.running = request.promise;
+    void request.promise.then((answer) => {
+        request.answer = answer;
+        settleRequest(state, nodeId, request, Date.now() - sentAt);
+    });
+    state.requests.set(nodeId, request);
+    for (const oldest of state.requests.keys()) {
+        if (state.requests.size <= MAX_KEPT_ANSWERS)
+            break;
+        state.requests.delete(oldest);
+    }
+    return request;
+}
+/**
+ * The element's request still running or kept answer, unless expired;
+ * marked as the most recently used.
+ *
+ * @param state - Document state
+ * @param nodeId - Node id of the element
+ * @returns The request, or undefined
+ */
+function keptRequest(state, nodeId) {
+    const kept = state.requests.get(nodeId);
+    if (!kept)
+        return undefined;
+    state.requests.delete(nodeId);
+    if (kept.expiresAt !== undefined && kept.expiresAt <= Date.now())
+        return undefined;
+    state.requests.set(nodeId, kept);
+    return kept;
+}
+/**
+ * The element's request, sent once Chrome has answered the one it is
+ * working on (another element's, or this one's sent by a concurrent call).
+ *
+ * @param cdp - CDP connection
+ * @param state - Document state
+ * @param nodeId - Node id of the element
+ * @param deadline - When to give up waiting
+ * @returns The request, or undefined when the running one outlasted the deadline
+ */
+async function requestWhenFree(cdp, state, nodeId, deadline) {
+    while (state.running) {
+        const kept = state.requests.get(nodeId);
+        if (kept)
+            return kept;
+        if ((await raceTimeout(state.running, deadline - Date.now())) === undefined)
+            return undefined;
+    }
+    return state.requests.get(nodeId) ?? sendMatchedRequest(cdp, state, nodeId);
+}
 /**
  * The rules that match an element, with its inline style and what its
- * ancestors pass down, or why they are missing.
+ * ancestors pass down, or why they are missing. A request still running for
+ * the element is shared; a slow answer (over {@link KEEP_ANSWERS_SLOWER_THAN_MS})
+ * is reused for {@link KEPT_ANSWER_TTL_MS} unless the document, its
+ * stylesheets or its DOM change or a command may have changed the page.
+ * Another element's request is sent only after the one Chrome is working on,
+ * within the budget. When the request this call sent or shared outlasts the
+ * budget, the document is marked slow: `skipWhenSlow` reads then return
+ * `skipped` at once (unless the answer is kept) until a read is fast again,
+ * a stylesheet changes or the page navigates.
  *
  * @param cdp - CDP connection
  * @param nodeId - Node id of the element
  * @param budgetMs - Time allowed
- * @returns Matched styles, `timeout` (longer than the budget) or `failed` (CDP error)
+ * @param options - `skipWhenSlow`: do not wait on a document marked slow (the default hints)
+ * @returns Matched styles, `timeout` (longer than the budget), `failed` (CDP error)
+ *   or `skipped` (slow document)
  */
-export async function matchedStyles(cdp, nodeId, budgetMs) {
-    const request = cdp
-        .send('CSS.getMatchedStylesForNode', { nodeId })
-        .then((response) => response)
-        .catch((error) => {
-        log.debug(`CSS.getMatchedStylesForNode failed: ${String(error)}`);
-        return 'failed';
-    });
-    return (await raceTimeout(request, budgetMs)) ?? 'timeout';
+export async function matchedStyles(cdp, nodeId, budgetMs, options = {}) {
+    const state = documentStyles(cdp);
+    const kept = keptRequest(state, nodeId);
+    if (kept?.answer)
+        return kept.answer;
+    if (options.skipWhenSlow && state.slow)
+        return 'skipped';
+    const deadline = Date.now() + budgetMs;
+    const request = kept ?? (await requestWhenFree(cdp, state, nodeId, deadline));
+    if (!request)
+        return 'timeout';
+    const answer = await raceTimeout(request.promise, deadline - Date.now());
+    if (answer)
+        return answer;
+    if (request.document === state.document)
+        state.slow = true;
+    return 'timeout';
 }
 /**
  * File name of a URL, without query or hash; the host for a site's root.

package/dist/runtime/dom/layout.d.ts

@@ -11,8 +11,6 @@ import type { CDPConnection } from '../../connection/cdp.js';
 import type { DomLayoutCommand } from '../../ipc/protocol/commands.js';
 import type { LayoutComputedStyle, LayoutResult, PageLayout } from '../../ipc/protocol/domTypes.js';
 import { type ElementGeometry } from './elementGeometry.js';
-/** Matches measured per command (the rest are counted as omitted) */
-export declare const LAYOUT_ELEMENT_LIMIT = 100;
 /**
  * Page-side end of a visible span kept clear of an overlay scrollbar along
  * an edge (16 CSS px wide): overlay scrollbars (macOS, mobile) show for about a

package/dist/runtime/dom/layout.js

@@ -7,6 +7,7 @@
  * shows. The measurements are classified outside the page
  * ({@link classifyViewportPosition}).
  */
+import { LAYOUT_ELEMENT_LIMIT } from '../../constants.js';
 import { CommandError } from '../../errors/index.js';
 import { operationFailedError } from '../../errors/messages.js';
 import { ELEMENT_GEOMETRY_JS, FRAME_OFFSET_JS, VIEWPORT_SIZE_JS, classifyViewportPosition, } from './elementGeometry.js';
@@ -20,8 +21,6 @@ import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 const log = createLogger('dom');
-/** Matches measured per command (the rest are counted as omitted) */
-export const LAYOUT_ELEMENT_LIMIT = 100;
 /**
  * Page-side end of a visible span kept clear of an overlay scrollbar along
  * an edge (16 CSS px wide): overlay scrollbars (macOS, mobile) show for about a

package/dist/runtime/dom/reactEventHelpers.d.ts

@@ -107,7 +107,10 @@ export declare const FILL_READ_BACK_SCRIPT: string;
  * dialog or bubble can swallow input while the page looks normal.
  * Slotted text hit-tests as its shadow host, so an element in a shadow root
  * that shows slotted content (a button labelled through a `<slot>`) is
- * topmost where its host is hit.
+ * topmost where its host is hit. An element that is not topmost because an
+ * ancestor in the flat tree clips it away (a collapsed
+ * `height: 0; overflow: hidden` accordion, {@link ANCESTOR_CLIP_JS}) is
+ * reported as hidden by it, not as covered.
  */
 export declare const CLICK_ELEMENT_SCRIPT: string;
 /**

package/dist/runtime/dom/reactEventHelpers.js

@@ -7,6 +7,7 @@
  */
 import { FILL_REFUSALS, LABEL_WITHOUT_CONTROL, NAME_QUERY_PLACEHOLDER, VIA_LABEL_SUFFIX, } from '../../errors/messages.js';
 import { REVEAL_SNAPSHOT_JS } from './actionEffectsScripts.js';
+import { ANCESTOR_CLIP_JS } from './elementGeometry.js';
 import { DISABLED_CAUSE_JS, ELEMENT_DESCRIPTION_JS, ELEMENT_IDENTITY_JS, } from './elementInfo.js';
 import { FIND_ELEMENTS_JS, LABEL_CONTROL_JS } from './targetNode.js';
 /**
@@ -484,7 +485,10 @@ export const FILL_READ_BACK_SCRIPT = `(() => {
  * dialog or bubble can swallow input while the page looks normal.
  * Slotted text hit-tests as its shadow host, so an element in a shadow root
  * that shows slotted content (a button labelled through a `<slot>`) is
- * topmost where its host is hit.
+ * topmost where its host is hit. An element that is not topmost because an
+ * ancestor in the flat tree clips it away (a collapsed
+ * `height: 0; overflow: hidden` accordion, {@link ANCESTOR_CLIP_JS}) is
+ * reported as hidden by it, not as covered.
  */
 export const CLICK_ELEMENT_SCRIPT = `
 (function(selector, parts, index, action) {
@@ -639,7 +643,10 @@ export const CLICK_ELEMENT_SCRIPT = `
   else if (el.closest('[inert]')) obstruction = 'inert (the page made it non-interactive)';
   else if (style.pointerEvents === 'none') obstruction = 'not clickable (pointer-events: none)';
   else if (!hasSize) obstruction = 'zero-size';
-  else if (!hittable) obstruction = 'covered by another element' + coveredBy();
+  else if (!hittable) {
+    const collapsed = (${ANCESTOR_CLIP_JS})(el, rect, describe).collapsed;
+    obstruction = collapsed ? 'hidden (' + collapsed + ')' : 'covered by another element' + coveredBy();
+  }
 
   if (action === 'hover') (${REVEAL_SNAPSHOT_JS})(el);
 

package/dist/runtime/dom/targetNode.d.ts

@@ -26,16 +26,20 @@ export declare const UNBIND_TARGET_SCRIPT = "delete window.__bdgTarget; delete w
  * the text nodes of hidden ones (display or visibility; not those of
  * `<script>`, `<style>` or `<noscript>`), so text filters match hidden
  * elements like Playwright's and `:visible` decides visibility; button inputs
- * use their value. Whitespace is collapsed; filter texts arrive normalized
- * (`has-text` lowercased). `:visible` is checked before the text filters,
- * which read the text.
+ * use their value. Text is read in the flat tree, as `bdg dom query` shows
+ * it: the text a web component's open shadow root renders, slotted content
+ * in place of its slots. A visible component, slot or element holding either
+ * ({@link COMPOSED_JS}) is read with {@link FLAT_TEXT_JS}, including the
+ * selects and editable regions `innerText` reads. Whitespace is collapsed;
+ * filter texts arrive normalized (`has-text` lowercased). `:visible` is
+ * checked before the text filters, which read the text.
  *
  * Steps and `:has()` match CSS relative to an element (`:scope > css`). A
  * descendant step also searches the open shadow roots under the element (the
  * whole step CSS inside one shadow tree); a child step stays in the
  * element's own tree.
  */
-export declare const FILTER_MATCHING_JS = "(shadowRoots) => {\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const walker = el.ownerDocument.createTreeWalker(el, 5, {\n      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)\n    });\n    let text = '';\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      if (node.nodeType === 3) text += node.data;\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n}";
+export declare const FILTER_MATCHING_JS = "(shadowRoots) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const flatText = (el, limit, fields) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const view = el.ownerDocument.defaultView;\n  let text = '';\n  const nodesOf = (node) =>\n    node.localName === 'slot' ? node.assignedNodes({ flatten: true }) : Array.from((node.shadowRoot || node).childNodes);\n  const read = (node, visible) => {\n    if (text.length >= limit) return;\n    if (node.nodeType === 3 && visible) text += node.data.replace(/\\s+/g, ' ');\n    if (node.nodeType !== 1) return;\n    if (/^(input|textarea)$/.test(node.localName)) return;\n    if (!fields && (node.localName === 'select' || node.isContentEditable)) return;\n    const style = view.getComputedStyle(node);\n    if (node.checkVisibility && !node.checkVisibility() && style.display !== 'contents') return;\n    if (node.localName === 'br') text += '\\n';\n    const apart = style.display.startsWith('inline') || style.display === 'contents' ? '' : '\\n';\n    text += apart;\n    const own = node.textContent || '';\n    if (composed(node)) nodesOf(node).forEach((child) => read(child, style.visibility === 'visible'));\n    else if (own.length > limit - text.length) text += own.slice(0, limit - text.length);\n    else text += typeof node.innerText === 'string' ? node.innerText : own;\n    text += apart;\n  };\n  const visible = view.getComputedStyle(el).visibility === 'visible';\n  nodesOf(el).forEach((child) => read(child, visible));\n  return text.slice(0, limit);\n};\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const nodes = el.localName === 'slot' ? el.assignedNodes({ flatten: true }) : (el.shadowRoot || el).childNodes;\n    let text = '';\n    for (const node of nodes) {\n      if (node.nodeType === 3) text += node.data;\n      else if (node.nodeType === 1 && !skipped.test(node.localName)) text += hiddenText(node);\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    const text = !rendered ? hiddenText(el) : composed(el) ? flatText(el, Infinity, true) : el.innerText;\n    return text.replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n}";
 /**
  * Page-side selector search that also reaches into open shadow roots and
  * same-origin iframes (recursively), like a user sees the page.
@@ -49,7 +53,7 @@ export declare const FILTER_MATCHING_JS = "(shadowRoots) => {\n  const skipped =
  * reached. Cross-origin iframes are separate processes and cannot be
  * searched. Throws a `SyntaxError` for an invalid selector.
  */
-export declare const DEEP_QUERY_JS = "function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const roots = [];\n  const visit = (root) => {\n    roots.push(root);\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const shadowRoots = roots.filter((root) => root.host);\n  const { passesAll, descend } = ((shadowRoots) => {\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const walker = el.ownerDocument.createTreeWalker(el, 5, {\n      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)\n    });\n    let text = '';\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      if (node.nodeType === 3) text += node.data;\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n})(shadowRoots);\n  const result = new Set();\n  for (const el of found) {\n    for (const part of parts) {\n      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;\n      for (const match of descend(el, part.steps || [])) result.add(match);\n    }\n  }\n  const rootOrder = new Map(roots.map((root, i) => [root, i]));\n  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;\n  return [...result].sort((a, b) =>\n    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)\n  );\n}";
+export declare const DEEP_QUERY_JS = "function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const roots = [];\n  const visit = (root) => {\n    roots.push(root);\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const shadowRoots = roots.filter((root) => root.host);\n  const { passesAll, descend } = ((shadowRoots) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const flatText = (el, limit, fields) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const view = el.ownerDocument.defaultView;\n  let text = '';\n  const nodesOf = (node) =>\n    node.localName === 'slot' ? node.assignedNodes({ flatten: true }) : Array.from((node.shadowRoot || node).childNodes);\n  const read = (node, visible) => {\n    if (text.length >= limit) return;\n    if (node.nodeType === 3 && visible) text += node.data.replace(/\\s+/g, ' ');\n    if (node.nodeType !== 1) return;\n    if (/^(input|textarea)$/.test(node.localName)) return;\n    if (!fields && (node.localName === 'select' || node.isContentEditable)) return;\n    const style = view.getComputedStyle(node);\n    if (node.checkVisibility && !node.checkVisibility() && style.display !== 'contents') return;\n    if (node.localName === 'br') text += '\\n';\n    const apart = style.display.startsWith('inline') || style.display === 'contents' ? '' : '\\n';\n    text += apart;\n    const own = node.textContent || '';\n    if (composed(node)) nodesOf(node).forEach((child) => read(child, style.visibility === 'visible'));\n    else if (own.length > limit - text.length) text += own.slice(0, limit - text.length);\n    else text += typeof node.innerText === 'string' ? node.innerText : own;\n    text += apart;\n  };\n  const visible = view.getComputedStyle(el).visibility === 'visible';\n  nodesOf(el).forEach((child) => read(child, visible));\n  return text.slice(0, limit);\n};\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const nodes = el.localName === 'slot' ? el.assignedNodes({ flatten: true }) : (el.shadowRoot || el).childNodes;\n    let text = '';\n    for (const node of nodes) {\n      if (node.nodeType === 3) text += node.data;\n      else if (node.nodeType === 1 && !skipped.test(node.localName)) text += hiddenText(node);\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    const text = !rendered ? hiddenText(el) : composed(el) ? flatText(el, Infinity, true) : el.innerText;\n    return text.replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n})(shadowRoots);\n  const result = new Set();\n  for (const el of found) {\n    for (const part of parts) {\n      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;\n      for (const match of descend(el, part.steps || [])) result.add(match);\n    }\n  }\n  const rootOrder = new Map(roots.map((root, i) => [root, i]));\n  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;\n  return [...result].sort((a, b) =>\n    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)\n  );\n}";
 /**
  * Page-side element lookup shared by the interaction scripts.
  *
@@ -58,7 +62,7 @@ export declare const DEEP_QUERY_JS = "function (selector, parts) {\n  const css
  * built-ins ({@link bindMatches}), otherwise all matches of the selector
  * ({@link DEEP_QUERY_JS}).
  */
-export declare const FIND_ELEMENTS_JS = "function (selector, parts) {\n  if (selector === '__bdg_bound_target__') {\n    const el = window.__bdgTarget;\n    return el && el.isConnected ? [el] : [];\n  }\n  const bound = window.__bdgMatches;\n  if (bound && bound.selector === selector) {\n    const connected = [];\n    for (let i = 0; i < bound.nodes.length; i++) {\n      if (bound.nodes[i] && bound.nodes[i].isConnected) connected[connected.length] = bound.nodes[i];\n    }\n    return connected;\n  }\n  return (function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const roots = [];\n  const visit = (root) => {\n    roots.push(root);\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const shadowRoots = roots.filter((root) => root.host);\n  const { passesAll, descend } = ((shadowRoots) => {\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const walker = el.ownerDocument.createTreeWalker(el, 5, {\n      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)\n    });\n    let text = '';\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      if (node.nodeType === 3) text += node.data;\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n})(shadowRoots);\n  const result = new Set();\n  for (const el of found) {\n    for (const part of parts) {\n      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;\n      for (const match of descend(el, part.steps || [])) result.add(match);\n    }\n  }\n  const rootOrder = new Map(roots.map((root, i) => [root, i]));\n  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;\n  return [...result].sort((a, b) =>\n    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)\n  );\n})(selector, parts);\n}";
+export declare const FIND_ELEMENTS_JS = "function (selector, parts) {\n  if (selector === '__bdg_bound_target__') {\n    const el = window.__bdgTarget;\n    return el && el.isConnected ? [el] : [];\n  }\n  const bound = window.__bdgMatches;\n  if (bound && bound.selector === selector) {\n    const connected = [];\n    for (let i = 0; i < bound.nodes.length; i++) {\n      if (bound.nodes[i] && bound.nodes[i].isConnected) connected[connected.length] = bound.nodes[i];\n    }\n    return connected;\n  }\n  return (function (selector, parts) {\n  const css = parts ? parts.map((part) => part.css).join(', ') : selector;\n  const found = [];\n  const roots = [];\n  const visit = (root) => {\n    roots.push(root);\n    for (const match of root.querySelectorAll(css)) found.push(match);\n    for (const el of root.querySelectorAll('*')) {\n      if (el.shadowRoot) visit(el.shadowRoot);\n      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {\n        let frameDocument = null;\n        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }\n        if (frameDocument) visit(frameDocument);\n      }\n    }\n  };\n  visit(document);\n  if (!parts) return found;\n  const shadowRoots = roots.filter((root) => root.host);\n  const { passesAll, descend } = ((shadowRoots) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const flatText = (el, limit, fields) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const view = el.ownerDocument.defaultView;\n  let text = '';\n  const nodesOf = (node) =>\n    node.localName === 'slot' ? node.assignedNodes({ flatten: true }) : Array.from((node.shadowRoot || node).childNodes);\n  const read = (node, visible) => {\n    if (text.length >= limit) return;\n    if (node.nodeType === 3 && visible) text += node.data.replace(/\\s+/g, ' ');\n    if (node.nodeType !== 1) return;\n    if (/^(input|textarea)$/.test(node.localName)) return;\n    if (!fields && (node.localName === 'select' || node.isContentEditable)) return;\n    const style = view.getComputedStyle(node);\n    if (node.checkVisibility && !node.checkVisibility() && style.display !== 'contents') return;\n    if (node.localName === 'br') text += '\\n';\n    const apart = style.display.startsWith('inline') || style.display === 'contents' ? '' : '\\n';\n    text += apart;\n    const own = node.textContent || '';\n    if (composed(node)) nodesOf(node).forEach((child) => read(child, style.visibility === 'visible'));\n    else if (own.length > limit - text.length) text += own.slice(0, limit - text.length);\n    else text += typeof node.innerText === 'string' ? node.innerText : own;\n    text += apart;\n  };\n  const visible = view.getComputedStyle(el).visibility === 'visible';\n  nodesOf(el).forEach((child) => read(child, visible));\n  return text.slice(0, limit);\n};\n  const skipped = /^(script|style|noscript|template)$/;\n  const hiddenText = (el) => {\n    const nodes = el.localName === 'slot' ? el.assignedNodes({ flatten: true }) : (el.shadowRoot || el).childNodes;\n    let text = '';\n    for (const node of nodes) {\n      if (node.nodeType === 3) text += node.data;\n      else if (node.nodeType === 1 && !skipped.test(node.localName)) text += hiddenText(node);\n    }\n    return text;\n  };\n  const textOf = (el) => {\n    if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;\n    const rendered = typeof el.innerText === 'string' &&\n      (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));\n    const text = !rendered ? hiddenText(el) : composed(el) ? flatText(el, Infinity, true) : el.innerText;\n    return text.replace(/\\s+/g, ' ').trim();\n  };\n  const passes = (el, filter) => {\n    if (filter.kind === 'visible') {\n      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;\n      const rect = el.getBoundingClientRect();\n      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';\n    }\n    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);\n    const text = textOf(el);\n    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);\n  };\n  const passesAll = (el, filters) =>\n    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&\n    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));\n  const isUnder = (scope, node) => {\n    for (let current = node; current; current = current.getRootNode().host) {\n      if (scope === current || scope.contains(current)) return true;\n    }\n    return false;\n  };\n  const stepMatches = (scope, step) => {\n    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];\n    if (step.combinator !== ' ') return matches;\n    for (const root of shadowRoots) {\n      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));\n    }\n    return matches;\n  };\n  const descend = (scope, steps) => {\n    let current = [scope];\n    for (const step of steps) {\n      const next = new Set();\n      for (const el of current) {\n        for (const match of stepMatches(el, step)) {\n          if (passesAll(match, step.filters)) next.add(match);\n        }\n      }\n      current = [...next];\n    }\n    return current;\n  };\n  return { passesAll: passesAll, descend: descend };\n})(shadowRoots);\n  const result = new Set();\n  for (const el of found) {\n    for (const part of parts) {\n      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;\n      for (const match of descend(el, part.steps || [])) result.add(match);\n    }\n  }\n  const rootOrder = new Map(roots.map((root, i) => [root, i]));\n  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;\n  return [...result].sort((a, b) =>\n    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)\n  );\n})(selector, parts);\n}";
 /**
  * Page-side check of what selectors cannot search in the top document:
  * iframes whose document cannot be read (cross-origin) and `<object>`/`<embed>`

package/dist/runtime/dom/targetNode.js

@@ -10,6 +10,7 @@
  */
 import { CommandError } from '../../errors/index.js';
 import { actionBrokenByPageError, actionScriptFailedError, emptySelectorError, indexOutOfRangeError, noNodesFoundError, staleNodeError, } from '../../errors/messages.js';
+import { COMPOSED_JS, FLAT_TEXT_JS } from './elementInfo.js';
 import { ActionScriptError, throwIfInvalidSelector } from './formFillHelpers/shared.js';
 import { frameScopedConnection } from './frameScopedConnection.js';
 import { evaluateInBdgWorld } from '../page/bdgWorld.js';
@@ -102,9 +103,13 @@ const log = createLogger('dom');
  * the text nodes of hidden ones (display or visibility; not those of
  * `<script>`, `<style>` or `<noscript>`), so text filters match hidden
  * elements like Playwright's and `:visible` decides visibility; button inputs
- * use their value. Whitespace is collapsed; filter texts arrive normalized
- * (`has-text` lowercased). `:visible` is checked before the text filters,
- * which read the text.
+ * use their value. Text is read in the flat tree, as `bdg dom query` shows
+ * it: the text a web component's open shadow root renders, slotted content
+ * in place of its slots. A visible component, slot or element holding either
+ * ({@link COMPOSED_JS}) is read with {@link FLAT_TEXT_JS}, including the
+ * selects and editable regions `innerText` reads. Whitespace is collapsed;
+ * filter texts arrive normalized (`has-text` lowercased). `:visible` is
+ * checked before the text filters, which read the text.
  *
  * Steps and `:has()` match CSS relative to an element (`:scope > css`). A
  * descendant step also searches the open shadow roots under the element (the
@@ -112,14 +117,15 @@ const log = createLogger('dom');
  * element's own tree.
  */
 export const FILTER_MATCHING_JS = `(shadowRoots) => {
+  const composed = ${COMPOSED_JS};
+  const flatText = ${FLAT_TEXT_JS};
   const skipped = /^(script|style|noscript|template)$/;
   const hiddenText = (el) => {
-    const walker = el.ownerDocument.createTreeWalker(el, 5, {
-      acceptNode: (node) => (node.nodeType === 1 && skipped.test(node.localName) ? 2 : 1)
-    });
+    const nodes = el.localName === 'slot' ? el.assignedNodes({ flatten: true }) : (el.shadowRoot || el).childNodes;
     let text = '';
-    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    for (const node of nodes) {
       if (node.nodeType === 3) text += node.data;
+      else if (node.nodeType === 1 && !skipped.test(node.localName)) text += hiddenText(node);
     }
     return text;
   };
@@ -127,7 +133,8 @@ export const FILTER_MATCHING_JS = `(shadowRoots) => {
     if (el.localName === 'input' && /^(submit|button|reset)$/i.test(el.type)) return el.value;
     const rendered = typeof el.innerText === 'string' &&
       (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));
-    return (rendered ? el.innerText : hiddenText(el)).replace(/\\s+/g, ' ').trim();
+    const text = !rendered ? hiddenText(el) : composed(el) ? flatText(el, Infinity, true) : el.innerText;
+    return text.replace(/\\s+/g, ' ').trim();
   };
   const passes = (el, filter) => {
     if (filter.kind === 'visible') {

package/dist/telemetry/a11y.d.ts

@@ -1,5 +1,5 @@
 import type { Protocol } from '../connection/typed-cdp.js';
-import type { A11yNode, A11yTree, A11yQueryPattern, A11yQueryResult, NodeRef } from '../types.js';
+import type { A11yNode, A11yTree, A11yQueryPattern, A11yQueryResult, ListedA11yTree, NodeRef } from '../types.js';
 /**
  * Builds accessibility tree from raw CDP nodes.
  *
@@ -14,6 +14,20 @@ import type { A11yNode, A11yTree, A11yQueryPattern, A11yQueryResult, NodeRef } f
  * @throws Error if no root node found
  */
 export declare function buildTreeFromRawNodes(rawNodes: Protocol.Accessibility.AXNode[]): A11yTree;
+/**
+ * The nodes `dom a11y tree` lists, depth-first from the root (then nodes not
+ * under it, such as frame content): the first `limit` (0 = all) no deeper
+ * than `maxDepth`. Noise ({@link isTreeNoise}) is counted as skipped and its
+ * children move up a level, so the budget goes to meaningful nodes; nodes cut
+ * by the limit or depth are counted as omitted. Every node of the tree is
+ * listed, omitted or skipped.
+ *
+ * @param tree - Accessibility tree
+ * @param limit - Nodes to list (0 = all listable ones)
+ * @param maxDepth - Deepest level to list (0 = root only; undefined = all)
+ * @returns Listed nodes with their depth, the tree size, and how many were cut or skipped
+ */
+export declare function listA11yTree(tree: A11yTree, limit: number, maxDepth?: number): ListedA11yTree;
 /**
  * Collects the full accessibility tree from the page via IPC.
  *

package/dist/telemetry/a11y.js

@@ -47,6 +47,89 @@ export function buildTreeFromRawNodes(rawNodes) {
     const root = nodes.get(rootRaw.nodeId);
     return { root, nodes, count: nodes.size };
 }
+/** Roles that only lay out their children and say nothing themselves */
+const LAYOUT_ROLES = new Set([
+    'generic',
+    'none',
+    'presentation',
+    'LayoutTable',
+    'LayoutTableRow',
+    'LayoutTableCell',
+]);
+/**
+ * Whether a node is left out of `dom a11y tree`: text boxes, blank text,
+ * text that repeats its parent's name, and nameless layout wrappers.
+ *
+ * @param node - Accessibility node
+ * @param parentName - Name of the nearest named ancestor
+ * @returns True when the node says nothing of its own
+ */
+function isTreeNoise(node, parentName) {
+    return (node.role === 'InlineTextBox' ||
+        (node.role === 'StaticText' && (node.name === parentName || !node.name?.trim())) ||
+        (LAYOUT_ROLES.has(node.role) && !node.name));
+}
+/**
+ * The nodes `dom a11y tree` lists, depth-first from the root (then nodes not
+ * under it, such as frame content): the first `limit` (0 = all) no deeper
+ * than `maxDepth`. Noise ({@link isTreeNoise}) is counted as skipped and its
+ * children move up a level, so the budget goes to meaningful nodes; nodes cut
+ * by the limit or depth are counted as omitted. Every node of the tree is
+ * listed, omitted or skipped.
+ *
+ * @param tree - Accessibility tree
+ * @param limit - Nodes to list (0 = all listable ones)
+ * @param maxDepth - Deepest level to list (0 = root only; undefined = all)
+ * @returns Listed nodes with their depth, the tree size, and how many were cut or skipped
+ */
+export function listA11yTree(tree, limit, maxDepth) {
+    const nodes = [];
+    const visited = new Set();
+    let omitted = 0;
+    let skipped = 0;
+    const visit = (node, depth, parentName) => {
+        if (visited.has(node.nodeId))
+            return;
+        visited.add(node.nodeId);
+        const listable = !isTreeNoise(node, parentName);
+        if (listable) {
+            const fits = (limit === 0 || nodes.length < limit) && (maxDepth ?? depth) >= depth;
+            if (fits)
+                nodes.push(listedNode(node, depth));
+            else
+                omitted++;
+        }
+        else {
+            skipped++;
+        }
+        for (const childId of node.childIds ?? []) {
+            const child = tree.nodes.get(childId);
+            if (child)
+                visit(child, listable ? depth + 1 : depth, node.name ?? parentName);
+        }
+    };
+    visit(tree.root, 0, undefined);
+    for (const node of tree.nodes.values())
+        visit(node, 0, undefined);
+    return {
+        nodes,
+        count: tree.count,
+        ...(omitted > 0 && { omitted }),
+        ...(skipped > 0 && { skipped }),
+    };
+}
+/**
+ * A node as the tree lists it: its depth instead of child ids (its children
+ * follow it, one level deeper).
+ *
+ * @param node - Accessibility node
+ * @param depth - Its level in the listing
+ * @returns Listed node
+ */
+function listedNode(node, depth) {
+    const { childIds: _childIds, ...rest } = node;
+    return { ...rest, depth };
+}
 /**
  * Ids of a node's children as shown: ignored children are replaced by their
  * own non-ignored descendants; ids missing from the tree are dropped.

package/dist/telemetry/har/builder.js

@@ -2,7 +2,7 @@
  * HAR (HTTP Archive) builder for transforming network telemetry to HAR 1.2 format.
  */
 import { createRequire } from 'node:module';
-import { skippedBodyReason } from '../network.js';
+import { skippedBodyReason } from '../networkRetention.js';
 /**
  * Loads Node builtins on first use: importing `node:http` in an ES module
  * reads all its exports, which loads undici and zlib (about 8 ms of every CLI

package/dist/telemetry/network.d.ts

@@ -1,19 +1,6 @@
 import type { CDPConnection } from '../connection/cdp.js';
 import type { NetworkRequest, WebSocketConnection, CleanupFunction } from '../types.js';
-/**
- * Placeholder stored instead of a response body that was not fetched.
- *
- * @param reason - Why the body was skipped
- * @returns Placeholder text shown by `bdg details`
- */
-export declare function skippedBodyPlaceholder(reason: string): string;
-/**
- * Extract the reason from a skipped-body placeholder.
- *
- * @param body - Stored response body
- * @returns Reason if `body` is a placeholder, otherwise undefined
- */
-export declare function skippedBodyReason(body: string | undefined): string | undefined;
+import { type NetworkEvictions } from './networkRetention.js';
 /**
  * A request that has started but not finished or failed yet.
  */
@@ -41,6 +28,12 @@ export interface NetworkCollectionOptions {
     networkInclude?: string[];
     networkExclude?: string[];
     maxBodySize?: number;
+    /** Finished requests kept at most; past it the oldest are dropped (default {@link MAX_NETWORK_REQUESTS}) */
+    maxRequests?: number;
+    /** Total size of stored response bodies; past it the oldest are evicted (default {@link MAX_TOTAL_BODY_BYTES}) */
+    maxTotalBodyBytes?: number;
+    /** Counters of dropped requests and evicted bodies; otherwise the collector keeps private ones */
+    evictions?: NetworkEvictions | undefined;
     getCurrentNavigationId?: (() => number) | undefined;
 }
 /**
@@ -56,8 +49,12 @@ export interface NetworkCollectionOptions {
  *
  * @remarks
  * - Chrome buffer limits: 50MB total, 10MB per resource, 1MB POST data (with fallback)
- * - Stale requests (incomplete after 60s) are removed from tracking but NOT added to output
- * - Request limit of 10,000 prevents memory issues in long-running sessions
+ * - The newest 10,000 finished requests are kept: past that the oldest finished
+ *   ones are dropped (counted in `evictions.requestsDropped`); requests in flight
+ *   are tracked separately and never dropped mid-flight
+ * - Stored response bodies total at most 100MB: past that the oldest bodies are
+ *   replaced by a placeholder (counted in `evictions.bodiesEvicted`), their
+ *   request metadata stays
  * - Response bodies are automatically skipped for images, fonts, CSS, and source maps (see DEFAULT_SKIP_BODY_PATTERNS)
  * - Response bodies larger than 5MB are skipped with a placeholder message
  * - By default, common tracking/analytics domains are filtered out (use includeAll to disable)