browser-debugger-cli 0.12.0 → 0.14.0

package/dist/runtime/dom/inspect.js

@@ -8,22 +8,24 @@
  * tree), `dom layout`'s measurement (page position, hidden, covered,
  * offscreen) and, once the nodes are pushed to CDP, `CSS.getComputedStyleForNode`
  * for the element, its layout parent and its `::before`/`::after`,
- * `CSS.getPlatformFontsForNode` for its text and `DOM.getBoxModel`. DOM and
- * CSS are enabled on the first inspect and kept on. Matched rules are not
- * read (no cascade).
+ * `CSS.getPlatformFontsForNode` for its text and `DOM.getBoxModel`. After
+ * those, for the hints, `--rules` and `--why`, the matched rules
+ * (`CSS.getMatchedStylesForNode`, see {@link matchedStyles}). DOM and CSS are
+ * enabled on the first inspect and kept on.
  */
 import { CommandError } from '../../errors/index.js';
 import { operationFailedError, unknownCssPropertyError, whyAllPropertyError, } from '../../errors/messages.js';
 import { throwIfInvalidSelector } from './formFillHelpers/shared.js';
 import { selectedProps } from './inspectAllStyles.js';
 import { buildCascadeFields } from './inspectCascadeModel.js';
-import { buildInspectResult } from './inspectModel.js';
-import { matchedStyles, sourceLabel, trackStyleSheets } from './inspectRules.js';
 import { explainUnsetVariables } from './inspectHints.js';
+import { buildInspectResult } from './inspectModel.js';
+import { HINTS_BUDGET_MS, matchedStyles, RULES_BUDGET_MS, sourceLabel, trackStyleSheets, } from './inspectRules.js';
 import { INSPECT_PAGE_JS, RELATED_NODE_JS, VARIABLE_SETTERS_JS, } from './inspectScripts.js';
 import { DEFAULT_TREE_DEPTH, DEFAULT_TREE_LIMIT } from './inspectTree.js';
 import { inspectLayout } from './layout.js';
 import { DEEP_QUERY_JS, missingElementError, selectorArgsJS } from './targetNode.js';
+import { evaluateInBdgWorld, resolveNodeInBdgWorld } from '../page/bdgWorld.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
@@ -31,10 +33,6 @@ import { findSimilar } from '../../utils/suggestions.js';
 const log = createLogger('dom');
 /** Connections DOM and CSS were enabled on */
 const stylesEnabled = new WeakSet();
-/** Time allowed for the matched rules behind the default hints (large stylesheets take longer) */
-const HINTS_BUDGET_MS = 1000;
-/** Time allowed for them with --rules or --why */
-const RULES_BUDGET_MS = 5000;
 /** Distinguishes the object groups of concurrent calls */
 let groupCounter = 0;
 /**
@@ -170,7 +168,7 @@ function expandCustomPropertyPatterns(names, style) {
  *
  * @param cdp - CDP connection (stylesheet headers for the source labels)
  * @param sources - What was read
- * @returns Cascade fields, or `cascade: 'timeout' | 'failed'` when the rules were not read
+ * @returns Cascade fields, or `cascade: 'timeout' | 'failed' | 'skipped'` when the rules were not read
  */
 function cascadeFields(cdp, sources) {
     if (!sources.matched)
@@ -248,9 +246,7 @@ function pickedHow(params, count, index) {
  * @returns Remote object id, or undefined when the node left the page
  */
 async function resolveCachedNode(cdp, backendNodeId, objectGroup) {
-    const resolved = (await cdp
-        .send('DOM.resolveNode', { backendNodeId, objectGroup })
-        .catch((error) => {
+    const resolved = (await resolveNodeInBdgWorld(cdp, { backendNodeId, objectGroup }).catch((error) => {
         log.debug(`Node ${backendNodeId} not resolved: ${getErrorMessage(error)}`);
         return {};
     }));
@@ -270,10 +266,10 @@ async function resolveCachedNode(cdp, backendNodeId, objectGroup) {
  * @throws CommandError (81) invalid selector, (91) page script failure
  */
 async function querySelector(cdp, selector, objectGroup) {
-    const response = (await cdp.send('Runtime.evaluate', {
+    const response = await evaluateInBdgWorld(cdp, {
         expression: `(${DEEP_QUERY_JS})(${selectorArgsJS(selector)})`,
         objectGroup,
-    }));
+    });
     if (response.exceptionDetails || !response.result.objectId) {
         if (response.exceptionDetails)
             throwIfInvalidSelector(response.exceptionDetails, selector);
@@ -306,7 +302,10 @@ async function callOn(cdp, objectId, functionDeclaration, args) {
 }
 /**
  * Read everything about the element: the page-side walk, `dom layout`'s
- * measurement and the CDP styles, fonts and box.
+ * measurement and the CDP styles, fonts and box, then the matched rules.
+ * Chrome answers one request at a time and the rules can take seconds on
+ * CSS-heavy pages, so they are asked for last: the other reads do not wait
+ * behind them, only their own budget does.
  *
  * @param cdp - CDP connection
  * @param objectId - The element
@@ -316,14 +315,16 @@ async function callOn(cdp, objectId, functionDeclaration, args) {
  */
 async function readSources(cdp, objectId, params, objectGroup) {
     const related = await relatedNodes(cdp, objectId, objectGroup);
-    const [raw, measured, styles] = await Promise.all([
+    const [raw, measured, { nodeId, ...styles }] = await Promise.all([
         readPage(cdp, objectId, params),
         measure(cdp, params.selector, related.node),
-        readStyles(cdp, related, params),
+        readStyles(cdp, related),
     ]);
+    const matched = await readMatched(cdp, nodeId, params);
     return {
         raw,
         ...styles,
+        ...(matched && { matched }),
         fonts: raw.textHolder ? styles.fonts.textHolder : styles.fonts.node,
         ...measured,
         ...(params.rules && { rules: true }),
@@ -459,20 +460,19 @@ async function nodeIdLookup(cdp, related) {
 }
 /**
  * Computed styles of the element, its parent and pseudo-elements, the
- * platform fonts of its text and its border box size.
+ * platform fonts of its text, its border box size and its node id.
  *
  * @param cdp - CDP connection
  * @param related - Backend node ids
  * @returns CDP styles
  */
-async function readStyles(cdp, related, params) {
+async function readStyles(cdp, related) {
     await enableStyleDomains(cdp);
     const nodeIdOf = await nodeIdLookup(cdp, related);
     const optionalStyle = (backendNodeId) => backendNodeId === undefined
         ? Promise.resolve(undefined)
         : computedStyle(cdp, nodeIdOf(backendNodeId));
-    const [matched, style, parentStyle, holderStyle, nodeFonts, holderFonts, size, pseudo] = await Promise.all([
-        readMatched(cdp, nodeIdOf(related.node), params),
+    const [style, parentStyle, holderStyle, nodeFonts, holderFonts, size, pseudo] = await Promise.all([
         computedStyle(cdp, nodeIdOf(related.node)),
         optionalStyle(related.parent),
         optionalStyle(related.textHolder),
@@ -488,26 +488,39 @@ async function readStyles(cdp, related, params) {
         pseudo,
         fonts: { node: nodeFonts, textHolder: holderFonts },
         ...(size && { size }),
-        ...(matched && { matched }),
+        nodeId: nodeIdOf(related.node),
     };
 }
 /**
- * The element's matched rules, when hints, `--rules` or `--why` need them:
- * within {@link HINTS_BUDGET_MS} for the default hints (skipped on very
- * large stylesheets), {@link RULES_BUDGET_MS} when asked for explicitly.
+ * How a request reads the element's matched rules, when hints, `--rules` or
+ * `--why` need them: within {@link HINTS_BUDGET_MS} for the default hints,
+ * not waited for at all on a document marked slow; within
+ * {@link RULES_BUDGET_MS} when asked for explicitly.
+ *
+ * @param params - Request
+ * @returns Budget and whether to skip on a slow document, or undefined when not needed
+ */
+export function matchedStylesRead(params) {
+    if (params.rules === true || params.why !== undefined) {
+        return { budgetMs: RULES_BUDGET_MS, skipWhenSlow: false };
+    }
+    if (params.hints === false || params.props !== undefined || params.all === true)
+        return undefined;
+    return { budgetMs: HINTS_BUDGET_MS, skipWhenSlow: true };
+}
+/**
+ * The element's matched rules, read as {@link matchedStylesRead} says.
  *
  * @param cdp - CDP connection
  * @param nodeId - Node id of the element
  * @param params - Request
- * @returns Matched styles, `timeout`, or undefined when not needed (or no node id)
+ * @returns Matched styles or why they are missing, or undefined when not needed (or no node id)
  */
 async function readMatched(cdp, nodeId, params) {
-    const explicit = params.rules === true || params.why !== undefined;
-    const skipped = !explicit && (params.hints === false || params.props !== undefined || params.all === true);
-    if (nodeId === undefined || skipped) {
+    const read = matchedStylesRead(params);
+    if (nodeId === undefined || !read)
         return undefined;
-    }
-    return matchedStyles(cdp, nodeId, explicit ? RULES_BUDGET_MS : HINTS_BUDGET_MS);
+    return matchedStyles(cdp, nodeId, read.budgetMs, { skipWhenSlow: read.skipWhenSlow });
 }
 /**
  * A pseudo-element's computed styles and size.

package/dist/runtime/dom/inspectAllStyles.js

@@ -170,6 +170,7 @@ const PREFIXED_KEPT = new Set([
     '-webkit-line-clamp',
     '-webkit-text-stroke-width',
     '-webkit-text-security',
+    '-webkit-text-fill-color',
 ]);
 /** SVG paint and geometry properties (noise on HTML elements) */
 const SVG_ONLY = /^(fill|fill-opacity|fill-rule|stroke|stroke-.*|stop-.*|flood-.*|lighting-color|marker-.*|clip-rule|color-interpolation.*|color-rendering|shape-rendering|text-anchor|dominant-baseline|alignment-baseline|baseline-shift|vector-effect|buffered-rendering|paint-order|mask-type)$/;

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

@@ -4,9 +4,9 @@
  * checked against authored declarations only (never the browser's own
  * styles), and `var()` references to custom properties that are not set.
  */
+import type { InspectHint } from '../../ipc/protocol/inspectTypes.js';
 import type { Declaration, Resolution } from './inspectCascade.js';
 import type { StyleMap } from './inspectLayoutModel.js';
-import type { InspectHint } from '../../ipc/protocol/inspectTypes.js';
 import type { VariableSetter } from './inspectScripts.js';
 /** A declaration that has no effect */
 export interface CssHint {

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

@@ -5,11 +5,11 @@
  * tree. Pure: every input is plain data, so the rules are tested without a
  * browser.
  */
-import type { Protocol } from '../../connection/typed-cdp.js';
 import type { ElementLayout } from '../../ipc/protocol/domTypes.js';
 import type { InspectResult, InspectVisibility } from '../../ipc/protocol/inspectTypes.js';
 import { type StyleMap } from './inspectLayoutModel.js';
 import { type PlatformFont, type PseudoSource } from './inspectPaintModel.js';
+import type { MatchedStyles } from './inspectRules.js';
 import type { RawInspect } from './inspectScripts.js';
 /** What one inspect read */
 export interface InspectSources {
@@ -29,8 +29,8 @@ export interface InspectSources {
     /** The element as `dom layout` measures it */
     layout?: ElementLayout;
     colorScheme?: 'light' | 'dark';
-    /** Matched rules for the cascade fields; `timeout` or `failed` when they were not read */
-    matched?: Protocol.CSS.GetMatchedStylesForNodeResponse | 'timeout' | 'failed';
+    /** Matched rules for the cascade fields; `timeout`, `failed` or `skipped` when they were not read */
+    matched?: MatchedStyles;
     /** `--rules` was asked for */
     rules?: boolean;
     /** `--why` property */
@@ -52,7 +52,8 @@ export interface InspectRequest {
     propValues?: InspectResult['props'];
 }
 /**
- * The element's label: tag, id and the first classes, with a count of the rest.
+ * The element's label: tag, id and the first classes ({@link isLabelClass}),
+ * with a count of the rest.
  *
  * @param raw - Tag, id and classes
  * @returns e.g. `a.z-1.max-sm:hidden(+11)`, `input#user-name`

package/dist/runtime/dom/inspectModel.js

@@ -5,6 +5,7 @@
  * tree. Pure: every input is plain data, so the rules are tested without a
  * browser.
  */
+import { isLabelClass } from './elementInfo.js';
 import { allStyles } from './inspectAllStyles.js';
 import { buildBox, buildLayout } from './inspectLayoutModel.js';
 import { buildEffects, buildFills, buildSvgPaint, buildFx, buildOutline, buildPseudo, buildRadius, buildState, buildStrokes, buildText, effectiveBackground, } from './inspectPaintModel.js';
@@ -14,17 +15,19 @@ import { normalizeCssValue, round1 } from '../../utils/cssValues.js';
 /** Classes shown in the label (the rest are counted) */
 const LABEL_CLASSES = 2;
 /**
- * The element's label: tag, id and the first classes, with a count of the rest.
+ * The element's label: tag, id and the first classes ({@link isLabelClass}),
+ * with a count of the rest.
  *
  * @param raw - Tag, id and classes
  * @returns e.g. `a.z-1.max-sm:hidden(+11)`, `input#user-name`
  */
 export function elementLabel(raw) {
-    const shown = raw.classes
+    const classes = raw.classes.filter(isLabelClass);
+    const shown = classes
         .slice(0, LABEL_CLASSES)
         .map((name) => `.${name}`)
         .join('');
-    const more = raw.classes.length - LABEL_CLASSES;
+    const more = classes.length - LABEL_CLASSES;
     return `${raw.tag}${raw.id ? `#${raw.id}` : ''}${shown}${more > 0 ? `(+${more})` : ''}`;
 }
 /**
@@ -48,6 +51,7 @@ export function visibilityOf(layout, rendered) {
         ...(offscreen && { offscreen }),
         ...(layout.coveredBy && { coveredBy: layout.coveredBy }),
         ...(layout.coverTransparent && { coverTransparent: true }),
+        ...(layout.masked && { masked: layout.masked }),
     };
 }
 /**

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

@@ -46,6 +46,8 @@ export declare function effectiveBackground(backgrounds: readonly RawBackground[
     inherited: boolean;
     overImage: boolean;
 };
+/** Why a contrast over a background image or gradient is approximate (its pixels are unknown) */
+export declare const OVER_IMAGE_RISK = "background image or gradient behind";
 /**
  * Contrast of the text color with the background behind it, both painted
  * as the browser composites them ({@link paintOver}), with what makes the

package/dist/runtime/dom/inspectPaintModel.js

@@ -128,6 +128,8 @@ export function effectiveBackground(backgrounds, canvasDark) {
         overImage: painted.overImage,
     };
 }
+/** Why a contrast over a background image or gradient is approximate (its pixels are unknown) */
+export const OVER_IMAGE_RISK = 'background image or gradient behind';
 /**
  * Contrast of the text color with the background behind it, both painted
  * as the browser composites them ({@link paintOver}), with what makes the
@@ -146,7 +148,7 @@ export function textContrast(style, raw) {
     const ratio = Math.floor(contrastRatio(painted.text, painted.background) * 100) / 100;
     const size = pxNumber(style['font-size']) ?? 16;
     const weight = Number(style['font-weight'] ?? 400);
-    const approximate = raw.paintRisks ?? [];
+    const approximate = [...(raw.paintRisks ?? []), ...(painted.overImage ? [OVER_IMAGE_RISK] : [])];
     return {
         ratio,
         level: contrastLevel(ratio, size, weight),

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

@@ -22,16 +22,42 @@ export declare function trackStyleSheets(cdp: CDPConnection): void;
  * @returns Headers
  */
 export declare function styleSheetHeaders(cdp: CDPConnection): Iterable<Protocol.CSS.CSSStyleSheetHeader>;
+/** Time allowed for the matched rules behind the default hints; a read within it clears the slow mark */
+export declare const HINTS_BUDGET_MS = 1000;
+/** Time allowed for them with --rules or --why */
+export declare const RULES_BUDGET_MS = 5000;
+/** Matched styles of an element, or why they are missing */
+export type MatchedStyles = Protocol.CSS.GetMatchedStylesForNodeResponse | 'timeout' | 'failed' | 'skipped';
+/**
+ * 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 declare function resetMatchedStyles(cdp: CDPConnection): void;
 /**
  * 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 declare function matchedStyles(cdp: CDPConnection, nodeId: number, budgetMs: number): Promise<Protocol.CSS.GetMatchedStylesForNodeResponse | 'timeout' | 'failed'>;
+export declare function matchedStyles(cdp: CDPConnection, nodeId: number, budgetMs: number, options?: {
+    skipWhenSlow?: boolean;
+}): Promise<MatchedStyles>;
 /**
  * Where a declaration comes from, for people: the selector and the file
  * with its line (and column, for single-line minified files), or what kind

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.