browser-debugger-cli 0.7.2 → 0.9.0

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

@@ -0,0 +1,131 @@
+/**
+ * Bind interaction scripts to an exact DOM node.
+ *
+ * Indices from `bdg dom query` / `bdg dom form` refer to one specific node
+ * (by backend node id). Re-running the selector at action time would hit a
+ * different element after the DOM changed, so the node itself is handed to
+ * the page scripts: it is resolved through CDP and stored on `window`, and the
+ * scripts' element lookup ({@link FIND_ELEMENTS_JS}) returns it for
+ * {@link BOUND_TARGET_SELECTOR}.
+ */
+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";
+/**
+ * Page-side matching of filters ({@link SelectorFilter}) and scoped steps
+ * ({@link ScopedStep}): called with the open shadow roots of the page, returns
+ * `{ passesAll, descend }`.
+ *
+ * Visible means rendered (`checkVisibility()`: not inside a closed
+ * `<details>` or under `content-visibility: hidden`), a non-empty box and
+ * `visibility: visible`, as in Playwright (`opacity: 0` still counts as
+ * visible). Text is the rendered text (`innerText`) of visible elements and
+ * 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.
+ *
+ * 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}";
+/**
+ * Page-side selector search that also reaches into open shadow roots and
+ * same-origin iframes (recursively), like a user sees the page.
+ *
+ * Takes the selector and, when it has text or visibility filters, its parts
+ * from {@link parseSelectorFilters}: their CSS runs as one selector list and
+ * a match is kept when it passes the filters of a part it matches; a part
+ * with scoped steps contributes the steps' matches under it instead (each
+ * element once). Matches come in document order: those of the document
+ * first, then those of each shadow root and frame in the order they are
+ * 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}";
+/**
+ * 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}).
+ */
+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}";
+/**
+ * Page-side check of what selectors cannot search in the top document:
+ * iframes whose document cannot be read (cross-origin) and `<object>`/`<embed>`
+ * elements. Cheap: no frame is entered.
+ */
+export declare const UNSEARCHED_CONTENT_JS = "(() => {\n  const frames = Array.from(document.querySelectorAll('iframe, frame'));\n  const unreadable = (frame) => {\n    try { return !frame.contentDocument; } catch (e) { return true; }\n  };\n  return { crossOriginFrames: frames.some(unreadable), embeds: !!document.querySelector('object, embed') };\n})()";
+/**
+ * Page-side ids (`kind` "id") or classes (`kind` "class") in the top
+ * document, from the first {@link NAME_SCAN_LIMIT} elements that have one.
+ *
+ * @param kind - Which names to read
+ * @returns Expression evaluating to the distinct names
+ */
+export declare function pageNamesJS(kind: 'id' | 'class'): string;
+/**
+ * Page-side: the form control a `<label>` stands for (`label.control`: its
+ * `for` target or the control inside it), or null for other elements and
+ * labels without one. Fill, click and key presses act on that control, like
+ * Playwright.
+ */
+export declare const LABEL_CONTROL_JS = "(el) => (el && el.localName === 'label' ? el.control : null)";
+/**
+ * Arguments for {@link DEEP_QUERY_JS} / {@link FIND_ELEMENTS_JS} and the page
+ * scripts built on them: the selector as a JS string literal and its parts
+ * (`null` for plain CSS, which runs unchanged).
+ *
+ * @param selector - Selector as the user gave it (or the bound-node placeholder)
+ * @returns JS source of the two arguments, e.g. `"li:visible", [{...}]`
+ * @throws CommandError (81) for an empty selector or a misplaced or malformed filter
+ */
+export declare function selectorArgsJS(selector: string): string;
+/** Selector and index the page scripts should use, and the connection to run them on. */
+export interface ScriptTarget {
+    selector: string;
+    index?: number;
+    /** Connection for the page scripts (scoped to the element's frame when the top page cannot reach it) */
+    cdp: CDPConnection;
+}
+/**
+ * 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.
+ *
+ * @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
+ */
+export declare function onScriptTarget<T extends {
+    selector?: string;
+    error?: string;
+    suggestion?: string;
+    exitCode?: number;
+}>(cdp: CDPConnection, params: {
+    selector?: string;
+    index?: number;
+    backendNodeId?: number;
+}, work: (target: ScriptTarget) => Promise<T>): Promise<T>;
+/**
+ * Error for an element a command could not find.
+ *
+ * @param target - Selector (and index) or backend node id the command was given
+ * @param matchCount - Elements the selector matched
+ * @returns Stale (87), out of range (81) or not found (83) error
+ */
+export declare function missingElementError(target: {
+    selector: string;
+    index?: number;
+    backendNodeId?: number;
+}, matchCount: number): CommandError;
+//# sourceMappingURL=targetNode.d.ts.map

package/dist/runtime/dom/targetNode.js

@@ -0,0 +1,370 @@
+/**
+ * Bind interaction scripts to an exact DOM node.
+ *
+ * Indices from `bdg dom query` / `bdg dom form` refer to one specific node
+ * (by backend node id). Re-running the selector at action time would hit a
+ * different element after the DOM changed, so the node itself is handed to
+ * the page scripts: it is resolved through CDP and stored on `window`, and the
+ * scripts' element lookup ({@link FIND_ELEMENTS_JS}) returns it for
+ * {@link BOUND_TARGET_SELECTOR}.
+ */
+import { CommandError } from '../../errors/index.js';
+import { emptySelectorError, indexOutOfRangeError, noNodesFoundError, staleNodeError, } from '../../errors/messages.js';
+import { frameScopedConnection } from './frameScopedConnection.js';
+import { createLogger } from '../../ui/logging/index.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';
+const log = createLogger('dom');
+/**
+ * Page-side matching of filters ({@link SelectorFilter}) and scoped steps
+ * ({@link ScopedStep}): called with the open shadow roots of the page, returns
+ * `{ passesAll, descend }`.
+ *
+ * Visible means rendered (`checkVisibility()`: not inside a closed
+ * `<details>` or under `content-visibility: hidden`), a non-empty box and
+ * `visibility: visible`, as in Playwright (`opacity: 0` still counts as
+ * visible). Text is the rendered text (`innerText`) of visible elements and
+ * 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.
+ *
+ * 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 const FILTER_MATCHING_JS = `(shadowRoots) => {
+  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)
+    });
+    let text = '';
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+      if (node.nodeType === 3) text += node.data;
+    }
+    return text;
+  };
+  const textOf = (el) => {
+    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 passes = (el, filter) => {
+    if (filter.kind === 'visible') {
+      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;
+      const rect = el.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';
+    }
+    if (filter.kind === 'has') return filter.selectors.some((chain) => descend(el, chain).length > 0);
+    const text = textOf(el);
+    return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);
+  };
+  const passesAll = (el, filters) =>
+    filters.every((filter) => filter.kind !== 'visible' || passes(el, filter)) &&
+    filters.every((filter) => filter.kind === 'visible' || passes(el, filter));
+  const isUnder = (scope, node) => {
+    for (let current = node; current; current = current.getRootNode().host) {
+      if (scope === current || scope.contains(current)) return true;
+    }
+    return false;
+  };
+  const stepMatches = (scope, step) => {
+    const matches = [...scope.querySelectorAll(':scope ' + step.combinator + ' ' + step.css)];
+    if (step.combinator !== ' ') return matches;
+    for (const root of shadowRoots) {
+      if (isUnder(scope, root.host)) matches.push(...root.querySelectorAll(step.css));
+    }
+    return matches;
+  };
+  const descend = (scope, steps) => {
+    let current = [scope];
+    for (const step of steps) {
+      const next = new Set();
+      for (const el of current) {
+        for (const match of stepMatches(el, step)) {
+          if (passesAll(match, step.filters)) next.add(match);
+        }
+      }
+      current = [...next];
+    }
+    return current;
+  };
+  return { passesAll: passesAll, descend: descend };
+}`;
+/**
+ * Page-side selector search that also reaches into open shadow roots and
+ * same-origin iframes (recursively), like a user sees the page.
+ *
+ * Takes the selector and, when it has text or visibility filters, its parts
+ * from {@link parseSelectorFilters}: their CSS runs as one selector list and
+ * a match is kept when it passes the filters of a part it matches; a part
+ * with scoped steps contributes the steps' matches under it instead (each
+ * element once). Matches come in document order: those of the document
+ * first, then those of each shadow root and frame in the order they are
+ * reached. Cross-origin iframes are separate processes and cannot be
+ * searched. Throws a `SyntaxError` for an invalid selector.
+ */
+export const DEEP_QUERY_JS = `function (selector, parts) {
+  const css = parts ? parts.map((part) => part.css).join(', ') : selector;
+  const found = [];
+  const roots = [];
+  const visit = (root) => {
+    roots.push(root);
+    for (const match of root.querySelectorAll(css)) found.push(match);
+    for (const el of root.querySelectorAll('*')) {
+      if (el.shadowRoot) visit(el.shadowRoot);
+      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {
+        let frameDocument = null;
+        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }
+        if (frameDocument) visit(frameDocument);
+      }
+    }
+  };
+  visit(document);
+  if (!parts) return found;
+  const shadowRoots = roots.filter((root) => root.host);
+  const { passesAll, descend } = (${FILTER_MATCHING_JS})(shadowRoots);
+  const result = new Set();
+  for (const el of found) {
+    for (const part of parts) {
+      if (!el.matches(part.css) || !passesAll(el, part.filters)) continue;
+      for (const match of descend(el, part.steps || [])) result.add(match);
+    }
+  }
+  const rootOrder = new Map(roots.map((root, i) => [root, i]));
+  const rootIndex = (el) => rootOrder.get(el.getRootNode()) ?? roots.length;
+  return [...result].sort((a, b) =>
+    rootIndex(a) - rootIndex(b) || (a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1)
+  );
+}`;
+/**
+ * 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}).
+ */
+export const FIND_ELEMENTS_JS = `function (selector, parts) {
+  if (selector === '${BOUND_TARGET_SELECTOR}') {
+    const el = window.__bdgTarget;
+    return el && el.isConnected ? [el] : [];
+  }
+  return (${DEEP_QUERY_JS})(selector, parts);
+}`;
+/**
+ * Page-side check of what selectors cannot search in the top document:
+ * iframes whose document cannot be read (cross-origin) and `<object>`/`<embed>`
+ * elements. Cheap: no frame is entered.
+ */
+export const UNSEARCHED_CONTENT_JS = `(() => {
+  const frames = Array.from(document.querySelectorAll('iframe, frame'));
+  const unreadable = (frame) => {
+    try { return !frame.contentDocument; } catch (e) { return true; }
+  };
+  return { crossOriginFrames: frames.some(unreadable), embeds: !!document.querySelector('object, embed') };
+})()`;
+/** Elements whose ids or classes are read for "did you mean" (bounds the work on huge pages) */
+const NAME_SCAN_LIMIT = 5000;
+/**
+ * Page-side ids (`kind` "id") or classes (`kind` "class") in the top
+ * document, from the first {@link NAME_SCAN_LIMIT} elements that have one.
+ *
+ * @param kind - Which names to read
+ * @returns Expression evaluating to the distinct names
+ */
+export function pageNamesJS(kind) {
+    return `(() => {
+  const names = new Set();
+  const elements = document.querySelectorAll('[${kind}]');
+  for (let i = 0; i < elements.length && i < ${NAME_SCAN_LIMIT}; i++) {
+    const el = elements[i];
+    ${kind === 'id' ? 'if (el.id) names.add(el.id);' : 'for (const name of el.classList) names.add(name);'}
+  }
+  return Array.from(names);
+})()`;
+}
+/**
+ * Page-side: the form control a `<label>` stands for (`label.control`: its
+ * `for` target or the control inside it), or null for other elements and
+ * labels without one. Fill, click and key presses act on that control, like
+ * Playwright.
+ */
+export const LABEL_CONTROL_JS = `(el) => (el && el.localName === 'label' ? el.control : null)`;
+/**
+ * Arguments for {@link DEEP_QUERY_JS} / {@link FIND_ELEMENTS_JS} and the page
+ * scripts built on them: the selector as a JS string literal and its parts
+ * (`null` for plain CSS, which runs unchanged).
+ *
+ * @param selector - Selector as the user gave it (or the bound-node placeholder)
+ * @returns JS source of the two arguments, e.g. `"li:visible", [{...}]`
+ * @throws CommandError (81) for an empty selector or a misplaced or malformed filter
+ */
+export function selectorArgsJS(selector) {
+    if (selector.trim() === '') {
+        const err = emptySelectorError();
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    return `${JSON.stringify(selector)}, ${JSON.stringify(parseSelectorFilters(selector))}`;
+}
+/**
+ * Store the node for the page scripts. It runs in the node's own frame, while
+ * the scripts run in the top page, so the node goes on the top window, which
+ * same-origin frames can reach. A cross-origin frame cannot write to the top
+ * window: the node then goes on its own window (`"frame"`) and the scripts
+ * run in that frame ({@link frameScopedConnection}).
+ */
+const BIND_FUNCTION = `function () {
+  if (!this.isConnected) return false;
+  try { window.top.__bdgTarget = this; return 'top'; } catch (e) { window.__bdgTarget = this; return 'frame'; }
+}`;
+/**
+ * Make the node with `backendNodeId` the target of the next page script.
+ *
+ * @param cdp - CDP connection
+ * @param backendNodeId - Backend node id from the query cache
+ * @returns Connection for the page scripts: the session's, or one running them
+ *   in the node's frame when that frame is cross-origin
+ * @throws CommandError (exit 87) when the node no longer exists in the page
+ */
+async function bindTargetNode(cdp, backendNodeId) {
+    const err = staleNodeError();
+    const stale = new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
+    let objectId;
+    try {
+        const resolved = (await cdp.send('DOM.resolveNode', { backendNodeId }));
+        objectId = resolved.object?.objectId;
+    }
+    catch {
+        throw stale;
+    }
+    if (!objectId)
+        throw stale;
+    const bound = (await cdp.send('Runtime.callFunctionOn', {
+        objectId,
+        functionDeclaration: BIND_FUNCTION,
+        returnByValue: true,
+    }));
+    const scope = bound.result?.value;
+    if (scope === 'frame')
+        return frameScopedConnection(cdp, objectId);
+    if (scope !== 'top')
+        throw stale;
+    return cdp;
+}
+/**
+ * Resolve what a page script should target for an interaction request.
+ *
+ * @param cdp - CDP connection
+ * @param params - Request with a selector (and optional index) or a backend node id
+ * @returns Selector/index for the page script and the connection to run it on
+ */
+async function resolveScriptTarget(cdp, params) {
+    if (params.backendNodeId === undefined) {
+        return {
+            selector: params.selector ?? '',
+            ...(params.index !== undefined && { index: params.index }),
+            cdp,
+        };
+    }
+    return { selector: BOUND_TARGET_SELECTOR, cdp: await bindTargetNode(cdp, params.backendNodeId) };
+}
+/**
+ * Whether an error is about the bound node: the placeholder only appears in
+ * "not found" messages, which for a bound node mean it left the page.
+ *
+ * @param text - Error message
+ * @returns True when the bound node was not found
+ */
+function boundNodeMissing(text) {
+    return text?.includes(BOUND_TARGET_SELECTOR) === true;
+}
+/**
+ * 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.
+ *
+ * @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
+ */
+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);
+        if (!boundNodeMissing(result.error))
+            return result;
+        return {
+            ...result,
+            error: err.message,
+            suggestion: err.suggestion,
+            exitCode: EXIT_CODES.STALE_CACHE,
+        };
+    }
+    catch (error) {
+        if (!(error instanceof CommandError) || !boundNodeMissing(error.message))
+            throw error;
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
+    }
+    finally {
+        if (target && target.cdp !== cdp)
+            unbindInFrame(target.cdp);
+    }
+}
+/**
+ * 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
+ * session removes the one bound on the top window after every interaction).
+ * Not waited for.
+ *
+ * @param frameConnection - Connection scoped to the node's frame
+ */
+function unbindInFrame(frameConnection) {
+    void frameConnection
+        .send('Runtime.evaluate', { expression: UNBIND_TARGET_SCRIPT })
+        .catch((error) => log.debug(`Frame target not unbound: ${getErrorMessage(error)}`));
+}
+/**
+ * Report the user's selector instead of the internal placeholder.
+ *
+ * @param result - Script result
+ * @param selector - Selector the user gave (or the cached query's selector)
+ * @returns Result with the placeholder replaced
+ */
+function withUserSelector(result, selector) {
+    if (result.selector !== BOUND_TARGET_SELECTOR)
+        return result;
+    return { ...result, ...(selector !== undefined && { selector }) };
+}
+/**
+ * Error for an element a command could not find.
+ *
+ * @param target - Selector (and index) or backend node id the command was given
+ * @param matchCount - Elements the selector matched
+ * @returns Stale (87), out of range (81) or not found (83) error
+ */
+export function missingElementError(target, matchCount) {
+    if (target.backendNodeId !== undefined) {
+        const err = staleNodeError();
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
+    }
+    if (matchCount > 0) {
+        const err = indexOutOfRangeError(target.index ?? 0, matchCount - 1);
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    const err = noNodesFoundError(target.selector);
+    return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+}
+//# sourceMappingURL=targetNode.js.map

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

@@ -0,0 +1,25 @@
+/**
+ * `bdg dom wait`: wait in the page until elements appear, become visible,
+ * contain a text or are gone, and/or the page has loaded.
+ *
+ * The page watches itself (a MutationObserver plus a short poll for style
+ * and frame changes the observer cannot see) and answers as soon as what it
+ * shows changes; the condition is decided here ({@link isWaitConditionMet}).
+ * Each page call lasts at most {@link WAIT_SLICE_MS}, so a navigation during
+ * the wait (the page's context is destroyed) only costs a retry on the new
+ * document. `--gone` is confirmed by a second snapshot of the same settled
+ * document, so the empty document right after a navigation does not count.
+ */
+import type { DomWaitCommand, DomWaitData } from '../../ipc/protocol/commands.js';
+import type { CDPSender } from '../../telemetry/objectExpander.js';
+/**
+ * Wait until the page meets the condition.
+ *
+ * @param cdp - CDP connection
+ * @param params - Condition and timeout
+ * @returns What the page showed when it was met, and how long it took
+ * @throws CommandError (81) for an invalid selector, (102) when the timeout passed;
+ *   CDP errors other than a lost page context (a closed connection) as they are
+ */
+export declare function waitForCondition(cdp: CDPSender, params: DomWaitCommand): Promise<DomWaitData>;
+//# sourceMappingURL=wait.d.ts.map