browser-debugger-cli 0.11.0 → 0.13.0

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

@@ -12,8 +12,8 @@ import type { CDPConnection } from '../../connection/cdp.js';
 import { CommandError } from '../../errors/index.js';
 /** Selector placeholder that makes page scripts use the bound node. */
 export declare const BOUND_TARGET_SELECTOR = "__bdg_bound_target__";
-/** Removes the node bound for index-based commands from the window it was stored on */
-export declare const UNBIND_TARGET_SCRIPT = "delete window.__bdgTarget";
+/** Removes the node bound for index-based commands, and matches bound for a selector, from the window they were stored on */
+export declare const UNBIND_TARGET_SCRIPT = "delete window.__bdgTarget; delete window.__bdgMatches";
 /**
  * Page-side matching of filters ({@link SelectorFilter}) and scoped steps
  * ({@link ScopedStep}): called with the open shadow roots of the page, returns
@@ -54,9 +54,11 @@ export declare const DEEP_QUERY_JS = "function (selector, parts) {\n  const css
  * Page-side element lookup shared by the interaction scripts.
  *
  * Returns the bound node (if still in the page) for the placeholder selector,
- * otherwise all matches of the selector ({@link DEEP_QUERY_JS}).
+ * the matches bound for the selector when the page replaced the search
+ * 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  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 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}";
 /**
  * Page-side check of what selectors cannot search in the top document:
  * iframes whose document cannot be read (cross-origin) and `<object>`/`<embed>`
@@ -94,23 +96,34 @@ export interface ScriptTarget {
     index?: number;
     /** Connection for the page scripts (scoped to the element's frame when the top page cannot reach it) */
     cdp: CDPConnection;
+    /** Built-ins the page replaced that the page scripts use (they run in the page's world) */
+    replacedBuiltins?: string[];
+    /** The page replaced the selector search, so the matches were found in bdg's world */
+    boundInBdgWorld?: boolean;
 }
 /**
  * Run an interaction on the element a request targets. Results and errors
  * never show the internal placeholder: a bound node the page scripts could
  * not find is reported as stale (87), and results carry the user's selector.
+ * On a page that replaced the selector search, a result warns that the
+ * element was found in bdg's world; on a page that replaced built-ins the
+ * scripts use, a failure adds that they may be the cause, and a script that
+ * threw is reported as broken by the page (90), naming them.
  *
  * @param cdp - CDP connection
  * @param params - Request with a selector (and optional index) or a backend node id
  * @param work - The interaction, given the script target
  * @returns The interaction's result
- * @throws CommandError (87) when the bound node left the page during the action
+ * @throws CommandError (87) when the bound node left the page during the
+ *   action, (90) when its script threw on a page that replaced built-ins
  */
 export declare function onScriptTarget<T extends {
     selector?: string;
     error?: string;
     suggestion?: string;
     exitCode?: number;
+    warning?: string;
+    replacedBuiltins?: string[];
 }>(cdp: CDPConnection, params: {
     selector?: string;
     index?: number;

package/dist/runtime/dom/targetNode.js

@@ -9,16 +9,86 @@
  * {@link BOUND_TARGET_SELECTOR}.
  */
 import { CommandError } from '../../errors/index.js';
-import { emptySelectorError, indexOutOfRangeError, noNodesFoundError, staleNodeError, } from '../../errors/messages.js';
+import { actionBrokenByPageError, actionScriptFailedError, emptySelectorError, indexOutOfRangeError, noNodesFoundError, staleNodeError, } from '../../errors/messages.js';
+import { ActionScriptError, throwIfInvalidSelector } from './formFillHelpers/shared.js';
 import { frameScopedConnection } from './frameScopedConnection.js';
+import { evaluateInBdgWorld } from '../page/bdgWorld.js';
+import { findReplacedBuiltins } from '../page/replacedBuiltins.js';
 import { createLogger } from '../../ui/logging/index.js';
+import { brokenByReplacedBuiltinsSuggestion, replacedBuiltinsWarning, } from '../../ui/messages/commands.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { parseSelectorFilters, } from '../../utils/selectorFilters.js';
 /** Selector placeholder that makes page scripts use the bound node. */
 export const BOUND_TARGET_SELECTOR = '__bdg_bound_target__';
-/** Removes the node bound for index-based commands from the window it was stored on */
-export const UNBIND_TARGET_SCRIPT = 'delete window.__bdgTarget';
+/** Removes the node bound for index-based commands, and matches bound for a selector, from the window they were stored on */
+export const UNBIND_TARGET_SCRIPT = 'delete window.__bdgTarget; delete window.__bdgMatches';
+/**
+ * Built-ins the selector search ({@link DEEP_QUERY_JS}) cannot do without:
+ * when the page replaced one, the search runs in bdg's world instead.
+ * Helpers that libraries replace with working versions (Prototype.js's
+ * `Array.prototype.map`) are left to {@link SCRIPT_BUILTINS}.
+ */
+const SELECTION_BUILTINS = [
+    'Element.prototype.querySelectorAll',
+    'Element.prototype.querySelector',
+    'Document.prototype.querySelectorAll',
+    'Document.prototype.querySelector',
+    'DocumentFragment.prototype.querySelectorAll',
+    'Element.prototype.matches',
+    'Element.prototype.closest',
+    'Node.prototype.getRootNode',
+    'Node.prototype.compareDocumentPosition',
+    'Node.prototype.contains',
+    'NodeList.prototype[Symbol.iterator]',
+    'Array.prototype[Symbol.iterator]',
+    'Array.prototype.push',
+    'Set',
+    'Map',
+];
+/** Other built-ins the interaction scripts use */
+const SCRIPT_BUILTINS = [
+    'Array.from',
+    'Array.prototype.map',
+    'Array.prototype.filter',
+    'Array.prototype.forEach',
+    'Array.prototype.some',
+    'Array.prototype.find',
+    'Array.prototype.includes',
+    'Object.keys',
+    'Object.assign',
+    'Object.getOwnPropertyDescriptor',
+    'Function.prototype.call',
+    'JSON.stringify',
+    'JSON.parse',
+];
+/** DOM built-ins the interaction scripts act through (anti-bot scripts often make them throw) */
+const DOM_ACTION_BUILTINS = [
+    'Element.prototype.getBoundingClientRect',
+    'Element.prototype.getClientRects',
+    'Element.prototype.scrollIntoView',
+    'window.getComputedStyle',
+    'Document.prototype.elementFromPoint',
+    'Document.prototype.createEvent',
+    'EventTarget.prototype.dispatchEvent',
+    'HTMLElement.prototype.focus',
+    'HTMLElement.prototype.blur',
+    'HTMLElement.prototype.click',
+    'Event',
+    'MouseEvent',
+    'HTMLInputElement.prototype.value',
+    'HTMLTextAreaElement.prototype.value',
+    'HTMLSelectElement.prototype.value',
+];
+/** Matches bound for a selector when the page replaced the selector search built-ins (enough for --index) */
+const MATCH_BIND_LIMIT = 100;
+/** Page-side: stores a node as match `i` of the selector being bound on the top window (runs on the node, in its frame; a cross-origin frame cannot reach the top window and fails) */
+const BIND_MATCH_FUNCTION = `function (selector, i) {
+  const w = window.top;
+  if (!w.__bdgMatches || w.__bdgMatches.selector !== selector) return false;
+  w.__bdgMatches.nodes[i] = this;
+  return true;
+}`;
 const log = createLogger('dom');
 /**
  * Page-side matching of filters ({@link SelectorFilter}) and scoped steps
@@ -151,13 +221,23 @@ export const DEEP_QUERY_JS = `function (selector, parts) {
  * Page-side element lookup shared by the interaction scripts.
  *
  * Returns the bound node (if still in the page) for the placeholder selector,
- * otherwise all matches of the selector ({@link DEEP_QUERY_JS}).
+ * the matches bound for the selector when the page replaced the search
+ * built-ins ({@link bindMatches}), otherwise all matches of the selector
+ * ({@link DEEP_QUERY_JS}).
  */
 export const FIND_ELEMENTS_JS = `function (selector, parts) {
   if (selector === '${BOUND_TARGET_SELECTOR}') {
     const el = window.__bdgTarget;
     return el && el.isConnected ? [el] : [];
   }
+  const bound = window.__bdgMatches;
+  if (bound && bound.selector === selector) {
+    const connected = [];
+    for (let i = 0; i < bound.nodes.length; i++) {
+      if (bound.nodes[i] && bound.nodes[i].isConnected) connected[connected.length] = bound.nodes[i];
+    }
+    return connected;
+  }
   return (${DEEP_QUERY_JS})(selector, parts);
 }`;
 /**
@@ -269,13 +349,124 @@ async function bindTargetNode(cdp, backendNodeId) {
  */
 async function resolveScriptTarget(cdp, params) {
     if (params.backendNodeId === undefined) {
+        const selector = params.selector ?? '';
+        const replaced = await replacedBuiltins(cdp);
+        const searchReplaced = replaced.some((name) => SELECTION_BUILTINS.includes(name));
+        const bound = searchReplaced && (await bindMatches(cdp, selector, params.index ?? 0));
         return {
-            selector: params.selector ?? '',
+            selector,
             ...(params.index !== undefined && { index: params.index }),
             cdp,
+            ...(replaced.length > 0 && { replacedBuiltins: replaced }),
+            ...(bound && { boundInBdgWorld: true }),
         };
     }
-    return { selector: BOUND_TARGET_SELECTOR, cdp: await bindTargetNode(cdp, params.backendNodeId) };
+    const scriptCdp = await bindTargetNode(cdp, params.backendNodeId);
+    const replaced = await replacedBuiltins(scriptCdp);
+    return {
+        selector: BOUND_TARGET_SELECTOR,
+        cdp: scriptCdp,
+        ...(replaced.length > 0 && { replacedBuiltins: replaced }),
+    };
+}
+/**
+ * The built-ins the interaction scripts use that the page replaced.
+ *
+ * @param cdp - CDP connection
+ * @returns Their dotted names (empty when all are the browser's, or the check failed)
+ */
+function replacedBuiltins(cdp) {
+    return findReplacedBuiltins(cdp, [
+        ...SELECTION_BUILTINS,
+        ...SCRIPT_BUILTINS,
+        ...DOM_ACTION_BUILTINS,
+    ]);
+}
+/**
+ * Search the selector in bdg's own world, where the page's replacements do
+ * not apply, and hand the matches (the first {@link MATCH_BIND_LIMIT}, or up
+ * to the index asked for) to the page scripts, which run in the page's world.
+ * When a match cannot be handed over (or the search fails other than on an
+ * invalid selector), nothing is bound and the scripts search themselves.
+ *
+ * @param cdp - CDP connection
+ * @param selector - Selector as the user gave it
+ * @param index - Match the action is for
+ * @returns Whether the matches were bound
+ * @throws CommandError (81) for an invalid selector
+ */
+async function bindMatches(cdp, selector, index) {
+    const objectGroup = `bdg-bind-${Date.now()}`;
+    const limit = Math.max(MATCH_BIND_LIMIT, index + 1);
+    try {
+        const found = await evaluateInBdgWorld(cdp, {
+            expression: `(${DEEP_QUERY_JS})(${selectorArgsJS(selector)}).slice(0, ${limit})`,
+            objectGroup,
+        });
+        if (found.exceptionDetails)
+            throwIfInvalidSelector(found.exceptionDetails, selector);
+        const arrayId = found.result.objectId;
+        if (found.exceptionDetails || !arrayId)
+            return false;
+        const { result } = (await cdp.send('Runtime.getProperties', {
+            objectId: arrayId,
+            ownProperties: true,
+        }));
+        const matches = result
+            .filter((property) => /^\d+$/.test(property.name))
+            .map((property) => ({ i: Number(property.name), objectId: property.value?.objectId }));
+        await cdp.send('Runtime.evaluate', {
+            expression: `window.__bdgMatches = { selector: ${JSON.stringify(selector)}, nodes: [] }`,
+        });
+        const bound = await Promise.all(matches.map(({ i, objectId }) => objectId ? bindMatch(cdp, selector, i, objectId) : Promise.resolve(false)));
+        if (bound.every(Boolean))
+            return true;
+        await cdp.send('Runtime.evaluate', { expression: 'delete window.__bdgMatches' });
+        return false;
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        log.debug(`Matches not bound: ${getErrorMessage(error)}`);
+        return false;
+    }
+    finally {
+        await cdp
+            .send('Runtime.releaseObjectGroup', { objectGroup })
+            .catch((error) => log.debug(`Matches not released: ${getErrorMessage(error)}`));
+    }
+}
+/**
+ * Hand one match from bdg's world to the page's world as match `i`.
+ *
+ * @param cdp - CDP connection
+ * @param selector - Selector the matches are for
+ * @param i - Its position among the matches
+ * @param objectId - The match in bdg's world
+ * @returns Whether it was handed over
+ */
+async function bindMatch(cdp, selector, i, objectId) {
+    try {
+        const { node } = (await cdp.send('DOM.describeNode', {
+            objectId,
+        }));
+        const resolved = (await cdp.send('DOM.resolveNode', {
+            backendNodeId: node.backendNodeId,
+        }));
+        if (!resolved.object.objectId)
+            return false;
+        const stored = (await cdp.send('Runtime.callFunctionOn', {
+            objectId: resolved.object.objectId,
+            functionDeclaration: BIND_MATCH_FUNCTION,
+            arguments: [{ value: selector }, { value: i }],
+            returnByValue: true,
+        }));
+        return stored.result.value === true;
+    }
+    catch (error) {
+        log.debug(`Match ${i} not bound: ${getErrorMessage(error)}`);
+        return false;
+    }
 }
 /**
  * Whether an error is about the bound node: the placeholder only appears in
@@ -291,19 +482,28 @@ function boundNodeMissing(text) {
  * Run an interaction on the element a request targets. Results and errors
  * never show the internal placeholder: a bound node the page scripts could
  * not find is reported as stale (87), and results carry the user's selector.
+ * On a page that replaced the selector search, a result warns that the
+ * element was found in bdg's world; on a page that replaced built-ins the
+ * scripts use, a failure adds that they may be the cause, and a script that
+ * threw is reported as broken by the page (90), naming them.
  *
  * @param cdp - CDP connection
  * @param params - Request with a selector (and optional index) or a backend node id
  * @param work - The interaction, given the script target
  * @returns The interaction's result
- * @throws CommandError (87) when the bound node left the page during the action
+ * @throws CommandError (87) when the bound node left the page during the
+ *   action, (90) when its script threw on a page that replaced built-ins
  */
 export async function onScriptTarget(cdp, params, work) {
     const err = staleNodeError();
     let target;
     try {
         target = await resolveScriptTarget(cdp, params);
-        const result = withUserSelector(await work(target), params.selector);
+        const replaced = target.replacedBuiltins ?? [];
+        const result = withReplacedBuiltins(withUserSelector(await work(target), params.selector), target.boundInBdgWorld ? replaced : []);
+        if (result.error && replaced.length > 0) {
+            return { ...result, suggestion: withBrokenHint(result.suggestion, replaced) };
+        }
         if (!boundNodeMissing(result.error))
             return result;
         return {
@@ -314,6 +514,16 @@ export async function onScriptTarget(cdp, params, work) {
         };
     }
     catch (error) {
+        const replaced = target?.replacedBuiltins ?? [];
+        if (error instanceof ActionScriptError) {
+            throw actionScriptFailure(error, replaced, params.selector ?? '');
+        }
+        if (error instanceof CommandError && replaced.length > 0) {
+            const suggestion = error.metadata['suggestion'];
+            throw new CommandError(error.message, {
+                suggestion: withBrokenHint(typeof suggestion === 'string' ? suggestion : undefined, replaced),
+            }, error.exitCode);
+        }
         if (!(error instanceof CommandError) || !boundNodeMissing(error.message))
             throw error;
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
@@ -323,6 +533,24 @@ export async function onScriptTarget(cdp, params, work) {
             unbindInFrame(target.cdp);
     }
 }
+/**
+ * The error for an action script that threw: on a page that replaced
+ * built-ins the scripts use, that the page broke it (90, naming them);
+ * otherwise what it threw (110), with the user's selector.
+ *
+ * @param error - What the action reported
+ * @param replaced - Built-ins the page replaced
+ * @param selector - Selector the user gave (or the cached query's selector)
+ * @returns Error to throw
+ */
+function actionScriptFailure(error, replaced, selector) {
+    if (replaced.length > 0) {
+        const err = actionBrokenByPageError(error.action, error.exception, replaced);
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_CONFLICT);
+    }
+    const err = actionScriptFailedError(error.action, error.exception, selector);
+    return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
+}
 /**
  * Remove a node bound in a cross-origin frame from that frame's window
  * (through the scoped connection, so the script runs where the bind ran; the
@@ -336,6 +564,38 @@ function unbindInFrame(frameConnection) {
         .send('Runtime.evaluate', { expression: UNBIND_TARGET_SCRIPT })
         .catch((error) => log.debug(`Frame target not unbound: ${getErrorMessage(error)}`));
 }
+/**
+ * A failed action's suggestion with the hint that the page's replaced
+ * built-ins may have broken it.
+ *
+ * @param suggestion - The action's own suggestion
+ * @param replaced - Built-ins the page replaced
+ * @returns Both, the action's first
+ */
+function withBrokenHint(suggestion, replaced) {
+    const hint = brokenByReplacedBuiltinsSuggestion(replaced);
+    return suggestion ? `${suggestion}. ${hint}` : hint;
+}
+/**
+ * Warn that the page replaced built-ins the page scripts use: they run in
+ * the page's world, so the action may misbehave (the element itself was
+ * found in bdg's world). The warning names the first few; `replacedBuiltins`
+ * lists them all.
+ *
+ * @param result - Script result
+ * @param replaced - Built-ins the page replaced
+ * @returns Result with the warning added to any it has
+ */
+function withReplacedBuiltins(result, replaced) {
+    if (!replaced || replaced.length === 0)
+        return result;
+    const warning = replacedBuiltinsWarning(replaced);
+    return {
+        ...result,
+        warning: result.warning ? `${result.warning}; ${warning}` : warning,
+        replacedBuiltins: replaced,
+    };
+}
 /**
  * Report the user's selector instead of the internal placeholder.
  *

package/dist/runtime/dom/wait.js

@@ -15,6 +15,7 @@ import { invalidSelectorError, waitTimeoutError } from '../../errors/messages.js
 import { isContextLostError } from './evalHelpers.js';
 import { DEEP_QUERY_JS, FILTER_MATCHING_JS, selectorArgsJS } from './targetNode.js';
 import { isWaitConditionMet, needsGoneConfirmation, normalizeWaitText, } from './waitCondition.js';
+import { evaluateInBdgWorld } from '../page/bdgWorld.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { delay, raceTimeout } from '../../utils/async.js';
 import { getErrorMessage } from '../../utils/errors.js';
@@ -157,7 +158,7 @@ async function nextSnapshot(cdp, condition, previous, deadline) {
     const selectorArgs = condition.selector === undefined ? 'null, null' : selectorArgsJS(condition.selector);
     const text = condition.text === undefined ? null : normalizeWaitText(condition.text);
     const args = `${selectorArgs}, ${JSON.stringify(text)}, ${JSON.stringify(previous)}, ${Math.min(remaining, WAIT_SLICE_MS)}`;
-    const evaluated = cdp.send('Runtime.evaluate', {
+    const evaluated = evaluateInBdgWorld(cdp, {
         expression: `(${WAIT_SNAPSHOT_JS})(${args})`,
         awaitPromise: true,
         returnByValue: true,

package/dist/runtime/page/bdgWorld.d.ts

@@ -0,0 +1,57 @@
+/**
+ * bdg's own JavaScript world in the page (a CDP isolated world): it shares
+ * the DOM with the page but has its own built-ins, so a page that replaces
+ * `Element.prototype.querySelectorAll`, `JSON.stringify` or
+ * `Array.prototype.map` (polyfills, old frameworks, anti-bot scripts) cannot
+ * change what bdg's page scripts find or return.
+ *
+ * Only the entry points need the world: `Runtime.evaluate` runs in it with
+ * its `contextId`, and `DOM.resolveNode` hands out objects of it with its
+ * `executionContextId`; `Runtime.callFunctionOn` on such an object runs in
+ * the same world. The world belongs to the top frame (same-origin iframes are
+ * reached through it); a node of another frame, a connection without the
+ * Page domain (a frame-scoped one) or a failure to create it fall back to the
+ * main world, as before.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { Protocol } from '../../connection/typed-cdp.js';
+/**
+ * What the world needs of a connection: commands, and events to forget the
+ * world when the page navigates (a sender without events, such as a test
+ * double, runs scripts in the main world)
+ */
+type PageConnection = Pick<CDPConnection, 'send'> & Partial<Pick<CDPConnection, 'on'>>;
+/** Name of bdg's isolated world (shown in DevTools' context selector) */
+export declare const BDG_WORLD_NAME = "bdg";
+/**
+ * `Runtime.evaluate` in bdg's world of the top frame. A call that names its
+ * own context is sent as it is.
+ *
+ * @param cdp - Connection to the page
+ * @param params - Evaluate parameters
+ * @returns Evaluate response
+ */
+export declare function evaluateInBdgWorld(cdp: PageConnection, params: Protocol.Runtime.EvaluateRequest): Promise<Protocol.Runtime.EvaluateResponse>;
+/**
+ * `DOM.resolveNode` into bdg's world of the top frame, so functions called on
+ * the node run there. A node the world cannot use (one of a cross-origin
+ * frame, or one no longer in the page) is resolved in its own frame's main
+ * world, as before.
+ *
+ * @param cdp - Connection to the page
+ * @param params - Resolve parameters
+ * @returns Resolve response
+ */
+export declare function resolveNodeInBdgWorld(cdp: PageConnection, params: Protocol.DOM.ResolveNodeRequest): Promise<Protocol.DOM.ResolveNodeResponse>;
+/**
+ * Send a CDP command for bdg's own scripts: `Runtime.evaluate` and
+ * `DOM.resolveNode` go to bdg's world, other methods as they are.
+ *
+ * @param cdp - Connection to the page
+ * @param method - CDP method
+ * @param params - Its parameters
+ * @returns The command's result
+ */
+export declare function sendForBdgScript(cdp: PageConnection, method: string, params: Record<string, unknown>): Promise<unknown>;
+export {};
+//# sourceMappingURL=bdgWorld.d.ts.map