browser-debugger-cli 0.8.0 → 0.9.0

package/dist/runtime/dom/targetNode.js

@@ -9,25 +9,97 @@
  * {@link BOUND_TARGET_SELECTOR}.
  */
 import { CommandError } from '../../errors/index.js';
-import { staleNodeError } from '../../errors/messages.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';
+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 test of one text or visibility filter ({@link SelectorFilter}).
- * Visible means a non-empty box and `visibility: visible`, as in Playwright
- * (`opacity: 0` still counts as visible). Text is the rendered text (`innerText`, `textContent` for elements without
- * it) with whitespace collapsed; filter texts arrive normalized (`has-text`
- * lowercased).
+ * 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.
  */
-const FILTER_MATCHES_JS = `(el, filter) => {
-  if (filter.kind === 'visible') {
-    const rect = el.getBoundingClientRect();
-    return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';
-  }
-  const text = (typeof el.innerText === 'string' ? el.innerText : el.textContent || '').replace(/\\s+/g, ' ').trim();
-  return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);
+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
@@ -35,15 +107,19 @@ const FILTER_MATCHES_JS = `(el, filter) => {
  *
  * 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.
- * Matches of the document come first, then those of each shadow root and
- * frame in document order. Cross-origin iframes are separate processes and
- * cannot be searched. Throws a `SyntaxError` for an invalid selector.
+ * 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);
@@ -56,8 +132,20 @@ export const DEEP_QUERY_JS = `function (selector, parts) {
   };
   visit(document);
   if (!parts) return found;
-  const passes = ${FILTER_MATCHES_JS};
-  return found.filter((el) => parts.some((part) => el.matches(part.css) && part.filters.every((filter) => passes(el, filter))));
+  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.
@@ -72,6 +160,45 @@ export const FIND_ELEMENTS_JS = `function (selector, parts) {
   }
   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
@@ -79,29 +206,36 @@ export const FIND_ELEMENTS_JS = `function (selector, parts) {
  *
  * @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 a misplaced or malformed filter
+ * @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 (always
- * reachable for the same-origin frames bdg can target).
+ * 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 () {
-  let host = window;
-  try { host = window.top; host.__bdgTarget = this; } catch (e) { host = window; host.__bdgTarget = this; }
-  return this.isConnected;
+  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
  */
-export async function bindTargetNode(cdp, backendNodeId) {
+async function bindTargetNode(cdp, backendNodeId) {
     const err = staleNodeError();
     const stale = new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
     let objectId;
@@ -119,25 +253,88 @@ export async function bindTargetNode(cdp, backendNodeId) {
         functionDeclaration: BIND_FUNCTION,
         returnByValue: true,
     }));
-    if (bound.result?.value !== 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
+ * @returns Selector/index for the page script and the connection to run it on
  */
-export async function resolveScriptTarget(cdp, params) {
+async function resolveScriptTarget(cdp, params) {
     if (params.backendNodeId === undefined) {
         return {
             selector: params.selector ?? '',
             ...(params.index !== undefined && { index: params.index }),
+            cdp,
         };
     }
-    await bindTargetNode(cdp, params.backendNodeId);
-    return { selector: BOUND_TARGET_SELECTOR };
+    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.
@@ -146,9 +343,28 @@ export async function resolveScriptTarget(cdp, params) {
  * @param selector - Selector the user gave (or the cached query's selector)
  * @returns Result with the placeholder replaced
  */
-export function withUserSelector(result, selector) {
+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

package/dist/runtime/dom/wait.js

@@ -0,0 +1,199 @@
+/**
+ * `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 { CommandError } from '../../errors/index.js';
+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 { createLogger } from '../../ui/logging/index.js';
+import { delay, raceTimeout } from '../../utils/async.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { filterDefined } from '../../utils/objects.js';
+import { parseSelectorFilters } from '../../utils/selectorFilters.js';
+const log = createLogger('dom');
+/** Longest a single page call waits for a change */
+const WAIT_SLICE_MS = 2000;
+/** Pause before asking a page that could not answer (navigating) again */
+const RETRY_DELAY_MS = 100;
+/** Pause before the snapshot that confirms elements are gone */
+const GONE_CONFIRM_DELAY_MS = 50;
+/**
+ * Page-side: report what the page shows (matches, text matches, visible
+ * ones, readyState) as soon as it differs from `previous` (at once when
+ * `previous` is null), or after `sliceMs` without a change.
+ */
+const WAIT_SNAPSHOT_JS = `async function (selector, parts, text, previous, sliceMs) {
+  const { passesAll } = (${FILTER_MATCHING_JS})([]);
+  const textFilter = text === null ? [] : [{ kind: 'has-text', text: text }];
+  const visibleFilter = [{ kind: 'visible' }];
+  const snapshot = () => {
+    const matches = selector === null ? [] : (${DEEP_QUERY_JS})(selector, parts);
+    const withText = matches.filter((el) => passesAll(el, textFilter));
+    return {
+      count: matches.length,
+      textCount: withText.length,
+      visibleCount: withText.filter((el) => passesAll(el, visibleFilter)).length,
+      readyState: document.readyState,
+      documentId: performance.timeOrigin
+    };
+  };
+  const changed = (s) => previous === null || s.count !== previous.count ||
+    s.textCount !== previous.textCount || s.visibleCount !== previous.visibleCount ||
+    s.readyState !== previous.readyState || s.documentId !== previous.documentId;
+  let current = snapshot();
+  if (changed(current)) return current;
+  return await new Promise((resolve) => {
+    let scheduled = null;
+    const observer = new MutationObserver(() => { if (scheduled === null) scheduled = setTimeout(check, 16); });
+    const poll = setInterval(check, 100);
+    const slice = setTimeout(finish, sliceMs);
+    function check() {
+      scheduled = null;
+      current = snapshot();
+      if (changed(current)) finish();
+    }
+    function finish() {
+      observer.disconnect();
+      clearInterval(poll);
+      clearTimeout(slice);
+      clearTimeout(scheduled);
+      document.removeEventListener('readystatechange', check);
+      resolve(current);
+    }
+    observer.observe(document, { childList: true, subtree: true, attributes: true, characterData: true });
+    document.addEventListener('readystatechange', check);
+  });
+}`;
+/**
+ * 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 async function waitForCondition(cdp, params) {
+    const condition = waitConditionOf(params);
+    const started = Date.now();
+    const deadline = started + params.timeout;
+    let last;
+    let confirming = false;
+    while (Date.now() < deadline) {
+        const snapshot = await nextSnapshot(cdp, condition, confirming ? null : (last ?? null), deadline);
+        if (!snapshot) {
+            confirming = false;
+            await delay(RETRY_DELAY_MS);
+            continue;
+        }
+        if (isWaitConditionMet(snapshot, condition, last)) {
+            return {
+                ...condition,
+                elapsedMs: Date.now() - started,
+                ...snapshotData(snapshot, condition),
+            };
+        }
+        last = snapshot;
+        confirming = needsGoneConfirmation(snapshot, condition);
+        if (confirming)
+            await delay(GONE_CONFIRM_DELAY_MS);
+    }
+    const err = waitTimeoutError(condition, last, params.timeout);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.CDP_TIMEOUT);
+}
+/**
+ * The condition of a request (options that are off left out).
+ *
+ * @param params - Request
+ * @returns Condition
+ */
+function waitConditionOf(params) {
+    return {
+        ...filterDefined({ selector: params.selector, text: params.text }),
+        ...(params.gone && { gone: true }),
+        ...(params.visible && { visible: true }),
+        ...(params.load && { load: true }),
+    };
+}
+/**
+ * The snapshot as reported: `textCount` only when a text was given.
+ *
+ * @param snapshot - What the page showed
+ * @param condition - What was waited for
+ * @returns Snapshot fields of the result
+ */
+function snapshotData(snapshot, condition) {
+    return {
+        count: snapshot.count,
+        ...(condition.text !== undefined && { textCount: snapshot.textCount }),
+        visibleCount: snapshot.visibleCount,
+        readyState: snapshot.readyState,
+    };
+}
+/**
+ * Ask the page for its next snapshot.
+ *
+ * @param cdp - CDP connection
+ * @param condition - What is waited for
+ * @param previous - Last snapshot (null for the first call)
+ * @param deadline - When the wait ends (epoch ms)
+ * @returns The snapshot, or undefined when the page could not answer (its context was lost
+ *   to a navigation, or the time ran out)
+ * @throws CommandError (81) for an invalid selector; other CDP errors (a closed connection) as they are
+ */
+async function nextSnapshot(cdp, condition, previous, deadline) {
+    const remaining = deadline - Date.now();
+    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', {
+        expression: `(${WAIT_SNAPSHOT_JS})(${args})`,
+        awaitPromise: true,
+        returnByValue: true,
+    });
+    evaluated.catch(() => undefined);
+    const response = await raceTimeout(evaluated, remaining).catch((error) => {
+        if (!isContextLostError(error))
+            throw error;
+        log.debug(`dom wait: page context lost (${getErrorMessage(error)}), retrying`);
+        return undefined;
+    });
+    if (!response)
+        return undefined;
+    if (response.exceptionDetails)
+        return pageException(response.exceptionDetails, condition);
+    return response.result.value;
+}
+/**
+ * Handle an exception of the page script: an invalid selector is the
+ * user's; anything else (a document being replaced) is retried.
+ *
+ * @param details - Exception details
+ * @param condition - What is waited for
+ * @returns undefined (retry)
+ * @throws CommandError (81) for an invalid selector
+ */
+function pageException(details, condition) {
+    const description = details.exception?.description ?? details.text;
+    if (condition.selector !== undefined && description.startsWith('SyntaxError')) {
+        const detail = parseSelectorFilters(condition.selector)
+            ? undefined
+            : description.split('\n')[0];
+        const err = invalidSelectorError(condition.selector, detail);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    log.debug(`dom wait: page script failed (${description.split('\n')[0]}), retrying`);
+    return undefined;
+}
+//# sourceMappingURL=wait.js.map

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

@@ -0,0 +1,71 @@
+/**
+ * What `bdg dom wait` waits for, and whether what the page shows meets it.
+ *
+ * The page reports a {@link WaitSnapshot} whenever it changes; the condition
+ * is decided here, in one place.
+ */
+/** What to wait for */
+export interface WaitCondition {
+    /** Selector (filters like :has-text and :visible allowed); absent when only waiting for the load */
+    selector?: string;
+    /** Text one of the matches must contain (case-insensitive, whitespace collapsed) */
+    text?: string;
+    /** Wait for the (visible, with `visible`) matches to be gone */
+    gone?: boolean;
+    /** Only count visible matches */
+    visible?: boolean;
+    /** Also wait for `document.readyState` to be `complete` */
+    load?: boolean;
+}
+/** What the page shows at one moment */
+export interface WaitSnapshot {
+    /** Elements matching the selector */
+    count: number;
+    /** Of those, the ones containing the text (all of them without a text) */
+    textCount: number;
+    /** Of the text matches, the visible ones */
+    visibleCount: number;
+    /** `document.readyState` */
+    readyState: string;
+    /** The document's identity (`performance.timeOrigin`): a new document after a navigation has another */
+    documentId: number;
+}
+/**
+ * The text as the page compares it: whitespace collapsed, lower case (like `:has-text`).
+ *
+ * @param text - Text as given
+ * @returns Normalized text
+ */
+export declare function normalizeWaitText(text: string): string;
+/**
+ * The matches the condition counts: visible ones with `visible`, else those
+ * containing the text (all matches without a text).
+ *
+ * @param snapshot - What the page shows
+ * @param condition - What is waited for
+ * @returns Number of counted matches
+ */
+export declare function countedMatches(snapshot: WaitSnapshot, condition: WaitCondition): number;
+/**
+ * Whether the page shows what is waited for.
+ *
+ * Elements are gone only when two consecutive snapshots of the same
+ * document, neither of it still `loading`, show none: right after a
+ * navigation commits, the new document is empty for a moment.
+ *
+ * @param snapshot - What the page shows
+ * @param condition - What is waited for
+ * @param previous - The snapshot before it, if any
+ * @returns True when the elements are there (or gone with `gone`) and, with `load`, the page loaded
+ */
+export declare function isWaitConditionMet(snapshot: WaitSnapshot, condition: WaitCondition, previous?: WaitSnapshot): boolean;
+/**
+ * Whether a `--gone` wait should confirm this snapshot with another one: it
+ * shows no (counted) matches in a document past `loading`.
+ *
+ * @param snapshot - What the page shows
+ * @param condition - What is waited for
+ * @returns True when one more snapshot of the same document may meet the condition
+ */
+export declare function needsGoneConfirmation(snapshot: WaitSnapshot, condition: WaitCondition): boolean;
+//# sourceMappingURL=waitCondition.d.ts.map