browser-debugger-cli 0.12.0 → 0.14.0

package/dist/runtime/dom/targetNode.js

@@ -9,16 +9,87 @@
  * {@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 { 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';
+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
@@ -32,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
@@ -42,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;
   };
@@ -57,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') {
@@ -151,13 +228,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 +356,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 +489,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 +521,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 +540,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 +571,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

package/dist/runtime/page/bdgWorld.js

@@ -0,0 +1,180 @@
+/**
+ * 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 { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+const log = createLogger('cdp');
+/** Name of bdg's isolated world (shown in DevTools' context selector) */
+export const BDG_WORLD_NAME = 'bdg';
+/** Errors of a context that is gone (navigation, reload) */
+const CONTEXT_GONE = /Cannot find context with specified id|Execution context was destroyed/;
+/** The world's context id per connection, until the page navigates */
+const worlds = new WeakMap();
+/**
+ * The execution context id of bdg's world in the top frame, created on first
+ * use and forgotten when the top frame navigates or its contexts are cleared.
+ *
+ * @param cdp - Connection to the page
+ * @returns Context id, or null when no world can be made on this connection
+ */
+function worldContext(cdp) {
+    const known = worlds.get(cdp);
+    if (known)
+        return known;
+    const created = createWorld(cdp);
+    worlds.set(cdp, created);
+    return created;
+}
+/**
+ * Create the world in the top frame and forget it when the page changes.
+ *
+ * @param cdp - Connection to the page
+ * @returns Context id, or null when it cannot be created
+ */
+async function createWorld(cdp) {
+    const { on } = cdp;
+    if (!on)
+        return null;
+    try {
+        const { frameTree } = (await cdp.send('Page.getFrameTree'));
+        const { executionContextId } = (await cdp.send('Page.createIsolatedWorld', {
+            frameId: frameTree.frame.id,
+            worldName: BDG_WORLD_NAME,
+            grantUniveralAccess: false,
+        }));
+        const forget = () => {
+            if (worlds.get(cdp) === created)
+                worlds.delete(cdp);
+            stopNavigated();
+            stopCleared();
+        };
+        const created = worlds.get(cdp);
+        const stopNavigated = on.call(cdp, 'Page.frameNavigated', (params) => {
+            if (params.frame.parentId === undefined)
+                forget();
+        });
+        const stopCleared = on.call(cdp, 'Runtime.executionContextsCleared', forget);
+        return executionContextId;
+    }
+    catch (error) {
+        log.debug(`bdg's isolated world not available: ${getErrorMessage(error)}`);
+        worlds.delete(cdp);
+        return null;
+    }
+}
+/**
+ * Send a command with the world's context, once more with a new world when
+ * the context is gone, and in the main world when there is none.
+ *
+ * @param cdp - Connection to the page
+ * @param method - CDP method
+ * @param params - Its parameters
+ * @param withContext - The parameters with the world's context id
+ * @returns The command's result
+ */
+async function sendInWorld(cdp, method, params, withContext) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const contextId = await worldContext(cdp);
+        if (contextId === null)
+            break;
+        try {
+            return await cdp.send(method, withContext(contextId));
+        }
+        catch (error) {
+            if (!CONTEXT_GONE.test(getErrorMessage(error)))
+                throw error;
+            worlds.delete(cdp);
+        }
+    }
+    return cdp.send(method, params);
+}
+/**
+ * `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 async function evaluateInBdgWorld(cdp, params) {
+    if (params.contextId !== undefined || params.uniqueContextId !== undefined) {
+        return (await cdp.send('Runtime.evaluate', { ...params }));
+    }
+    return (await sendInWorld(cdp, 'Runtime.evaluate', { ...params }, (contextId) => ({
+        ...params,
+        contextId,
+    })));
+}
+/**
+ * `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 async function resolveNodeInBdgWorld(cdp, params) {
+    if (params.executionContextId !== undefined) {
+        return (await cdp.send('DOM.resolveNode', { ...params }));
+    }
+    try {
+        const resolved = (await sendInWorld(cdp, 'DOM.resolveNode', { ...params }, (executionContextId) => ({ ...params, executionContextId })));
+        if (await usableInWorld(cdp, resolved.object.objectId))
+            return resolved;
+    }
+    catch (error) {
+        log.debug(`Node resolved in the page's world: ${getErrorMessage(error)}`);
+    }
+    return (await cdp.send('DOM.resolveNode', { ...params }));
+}
+/**
+ * Whether a node resolved into bdg's world can be used there: a node of a
+ * cross-origin frame resolves, but every access to it throws.
+ *
+ * @param cdp - Connection to the page
+ * @param objectId - The node in bdg's world
+ * @returns True when it can be read
+ */
+async function usableInWorld(cdp, objectId) {
+    if (!objectId)
+        return false;
+    const probe = (await cdp.send('Runtime.callFunctionOn', {
+        objectId,
+        functionDeclaration: 'function () { try { return this.isConnected === true; } catch (e) { return false; } }',
+        returnByValue: true,
+    }));
+    return probe.result.value === true;
+}
+/**
+ * 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 function sendForBdgScript(cdp, method, params) {
+    if (method === 'Runtime.evaluate') {
+        return evaluateInBdgWorld(cdp, params);
+    }
+    if (method === 'DOM.resolveNode') {
+        return resolveNodeInBdgWorld(cdp, params);
+    }
+    return cdp.send(method, params);
+}
+//# sourceMappingURL=bdgWorld.js.map