browser-debugger-cli 0.12.0 → 0.13.0

package/dist/commands/dom/formInteraction.js

@@ -10,14 +10,15 @@ import { InvalidArgumentError } from 'commander';
 import { runElementCommand } from './helpers/runElementCommand.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } from '../shared/commonOptions.js';
+import { createErrorResult } from '../shared/dataFetcher.js';
 import { integerOption } from '../shared/validation.js';
 import { CommandError } from '../../errors/index.js';
-import { VIA_LABEL_SUFFIX, conflictingOptionsMessage, hoverOffWithTargetError, missingArgumentError, indexSourceText, internalError, scrollOptionsError, } from '../../errors/messages.js';
+import { VIA_LABEL_SUFFIX, conflictingOptionsError, hoverOffWithTargetError, missingArgumentError, indexSourceText, internalError, scrollOptionsError, } from '../../errors/messages.js';
 import { callCDP, domClick, domFill, domPressKey, domScroll, domSubmit } from '../../ipc/client.js';
 import { findUnknownModifiers } from '../../runtime/dom/keyMapping.js';
 import { formatTriggeredRequestLines, formatTriggeredRequestsTitle, } from '../../ui/formatters/triggeredRequests.js';
 import { OutputFormatter } from '../../ui/formatting.js';
-import { CLICK_RESULT_WAIT_HELP, HOVER_OFF_DONE, HOVER_USAGE, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, actionStatusLine, dialogConsoleText, moreMessagesText, newMessageText, pageNavigationText, shownElementText, stillChangingNote, } from '../../ui/messages/commands.js';
+import { CLICK_RESULT_WAIT_HELP, HOVER_OFF_DONE, HOVER_USAGE, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, pointerScrollText, actionStatusLine, dialogConsoleText, moreMessagesText, newMessageText, pageNavigationText, shownElementText, stillChangingNote, } from '../../ui/messages/commands.js';
 import { sessionCommand } from '../../ui/messages/sessionCommand.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /** Help of `--strict` on click and hover */
@@ -288,12 +289,9 @@ async function hoverOff(selectorOrIndex, options) {
     }, options, () => HOVER_OFF_DONE);
 }
 async function runPointerCommand(selectorOrIndex, options, action) {
+    const conflict = conflictingOptionsError('--double', '--right');
     await runCommand(() => options.double && options.right
-        ? Promise.resolve({
-            success: false,
-            error: conflictingOptionsMessage('--double', '--right'),
-            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
-        })
+        ? Promise.resolve(createErrorResult(conflict.message, EXIT_CODES.INVALID_ARGUMENTS, conflict.suggestion))
         : runElementCommand({
             selectorOrIndex,
             index: options.index,
@@ -430,6 +428,9 @@ function formatClickOutput(result) {
         ...selectorRows(result),
         elementRow(result),
         ['Method', result.method === 'dom' ? 'DOM events' : 'mouse events'],
+        ...(result.scrolledBy
+            ? [['Scrolled', pointerScrollText(result.scrolledBy)]]
+            : []),
     ], result, { action: POINTER_ACTION_NOUN[result.action ?? 'click'] }).build();
 }
 /**

package/dist/commands/dom/get.js

@@ -10,7 +10,7 @@ import { getDOMElements, getDomContext, selectMatch, } from './helpers/index.js'
 import { formatSemanticNodeWithContext, resolveNodeWithFallback, } from './semanticUtils.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { CommandError } from '../../errors/index.js';
-import { conflictingOptionsMessage, indexWithIndexOptionError, nodeIdNotFoundError, optionRequiresMessage, } from '../../errors/messages.js';
+import { conflictingOptionsError, indexWithIndexOptionError, nodeIdNotFoundError, optionRequiresError, } from '../../errors/messages.js';
 import { resolveA11yNode } from '../../telemetry/a11y.js';
 import { formatDomGet } from '../../ui/formatters/dom.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
@@ -99,23 +99,23 @@ function matchIndex(options) {
  *
  * @param selectorOrIndex - Selector or index argument
  * @param options - Command options
- * @returns What conflicts, or null
+ * @returns What conflicts and how to fix it, or null
  */
 function getOptionsConflict(selectorOrIndex, options) {
     if (options.nodeId !== undefined && selectorOrIndex !== undefined) {
-        return conflictingOptionsMessage('--node-id', 'a selector or index');
+        return conflictingOptionsError('--node-id', 'a selector or index');
     }
     if (options.full && (options.raw || options.nodeId !== undefined)) {
-        return conflictingOptionsMessage('--full', options.raw ? '--raw' : '--node-id');
+        return conflictingOptionsError('--full', options.raw ? '--raw' : '--node-id');
     }
     if (options.index !== undefined && options.nth !== undefined) {
-        return conflictingOptionsMessage('--index', '--nth');
+        return conflictingOptionsError('--index', '--nth');
     }
     if (options.all && matchIndex(options) !== undefined) {
-        return conflictingOptionsMessage('--all', '--index');
+        return conflictingOptionsError('--all', '--index');
     }
     if (options.all && !options.raw)
-        return optionRequiresMessage('--all', '--raw');
+        return optionRequiresError('--all', '--raw');
     return null;
 }
 /**
@@ -130,7 +130,7 @@ function getOptionsConflict(selectorOrIndex, options) {
 export async function handleDomGet(selectorOrIndex, options) {
     const conflict = getOptionsConflict(selectorOrIndex, options);
     if (conflict) {
-        throw new CommandError(conflict, {}, EXIT_CODES.INVALID_ARGUMENTS);
+        throw new CommandError(conflict.message, { suggestion: conflict.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
     }
     const { nodeId } = options;
     if (nodeId !== undefined) {

package/dist/commands/dom/helpers/index.d.ts

@@ -5,7 +5,7 @@
  * - `query.ts`      — selector → backend node ids (shadow roots, same-origin iframes), DOM.describeNode
  * - `screenshot.ts` — page / element capture, element bounds, scroll helpers
  */
-export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, } from './query.js';
+export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, pageDocumentId, } from './query.js';
 export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
 export type { DomQueryResult, DomGetResult, ScreenshotResult, DomGetOptions, ScreenshotOptions, DomContext, ElementBounds, } from '../../../types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/dom/helpers/index.js

@@ -5,6 +5,6 @@
  * - `query.ts`      — selector → backend node ids (shadow roots, same-origin iframes), DOM.describeNode
  * - `screenshot.ts` — page / element capture, element bounds, scroll helpers
  */
-export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, } from './query.js';
+export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, pageDocumentId, } from './query.js';
 export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
 //# sourceMappingURL=index.js.map

package/dist/commands/dom/helpers/query.d.ts

@@ -38,13 +38,26 @@ export declare function noMatchContext(selector: string): Promise<NoMatchContext
  * @returns The state, or undefined when the page did not answer
  */
 export declare function documentReadyState(): Promise<string | undefined>;
+/** Matches whose viewport position `dom query` reports (measuring is not free) */
+export declare const VIEWPORT_HINT_LIMIT = 100;
 /**
- * Query elements by selector for `bdg dom query`.
+ * Matches `dom query` describes and caches for use by index at least, beyond
+ * those it lists: describing costs a round trip per element, so a page with
+ * 50000 matches is not described whole unless `--limit 0` asks for it.
+ */
+export declare const QUERY_CACHE_LIMIT = 1000;
+/**
+ * Query elements by selector for `bdg dom query`: all matches are counted,
+ * and the first `limit` (at least {@link QUERY_CACHE_LIMIT}, so indices past
+ * the listed ones still work) are described in one page-side pass plus one
+ * `DOM.describeNode` each for their backend node id.
  *
  * @param selector - CSS selector
- * @returns Matches with backend node ids, tags, classes and text previews
+ * @param limit - Matches the caller lists (0 = all, so all are described)
+ * @returns The match count, and the described matches with backend node
+ *   ids, tags, key attributes, classes and text previews
  */
-export declare function queryDOMElements(selector: string): Promise<DomQueryResult>;
+export declare function queryDOMElements(selector: string, limit?: number): Promise<DomQueryResult>;
 /**
  * Get DOM context (tag, classes, key attributes, text preview) for a node: a one-line
  * preview, and up to {@link ELEMENT_TEXT_LENGTH} characters of text when it
@@ -102,4 +115,15 @@ export declare function resolveBackendNodeIds(selectors: string[]): Promise<(num
  * @throws CommandError (87) when the element is gone
  */
 export declare function assertNodeAttached(backendNodeId: number, source?: IndexSource): Promise<void>;
+/**
+ * Identity of the page's current document: its time origin, which every
+ * document load gets anew. Cached backend node ids belong to one document; a
+ * page loaded in a new renderer process reuses the same ids for other
+ * elements, so an index of an older document must not be used.
+ *
+ * @returns The identity, or undefined when the page cannot be asked
+ * @throws CommandError when the page is busy (102) or crashed (107), as the
+ *   command itself would
+ */
+export declare function pageDocumentId(): Promise<string | undefined>;
 //# sourceMappingURL=query.d.ts.map

package/dist/commands/dom/helpers/query.js

@@ -12,9 +12,9 @@
 import { keyAttributes } from './keyAttributes.js';
 import { CommandError } from '../../../errors/index.js';
 import { noNodesFoundError, indexOutOfRangeError, eitherArgumentRequiredError, invalidSelectorError, nodeIdNotFoundError, operationFailedError, similarSelectorsLine, staleNodeError, } from '../../../errors/messages.js';
-import { callCDP } from '../../../ipc/client.js';
+import { callBdgScript, callCDP } from '../../../ipc/client.js';
 import { ELEMENT_GEOMETRY_JS, VIEWPORT_SIZE_JS, classifyViewportPosition, } from '../../../runtime/dom/elementGeometry.js';
-import { ELEMENT_CONTEXT_JS, ELEMENT_STATE_JS, ELEMENT_TEXT_JS, ELEMENT_TEXT_LENGTH, textPreview, } from '../../../runtime/dom/elementInfo.js';
+import { ELEMENT_CONTEXT_JS, ELEMENT_STATE_JS, ELEMENT_TEXT_JS, ELEMENT_TEXT_LENGTH, textPreview, isLabelClass, } from '../../../runtime/dom/elementInfo.js';
 import { DEEP_QUERY_JS, UNSEARCHED_CONTENT_JS, pageNamesJS, selectorArgsJS, } from '../../../runtime/dom/targetNode.js';
 import { createLogger } from '../../../ui/logging/index.js';
 import { sessionCommand } from '../../../ui/messages/sessionCommand.js';
@@ -92,7 +92,7 @@ async function selectAll(selector) {
 async function withSelection(selector, use) {
     await callCDP('DOM.enable', {});
     const objectGroup = `bdg-query-${process.pid}-${++queryCount}`;
-    const evaluated = await callCDP('Runtime.evaluate', {
+    const evaluated = await callBdgScript('Runtime.evaluate', {
         expression: `(${DEEP_QUERY_JS})(${selectorArgsJS(selector)})`,
         objectGroup,
     });
@@ -163,7 +163,7 @@ export async function noMatchContext(selector) {
     const compounds = leadingCompounds(selector);
     const shadowHost = compounds.length > 0 ? shadowHostJS(compounds) : '-1';
     try {
-        const evaluated = await callCDP('Runtime.evaluate', {
+        const evaluated = await callBdgScript('Runtime.evaluate', {
             expression: `({ hidden: ${hidden}, readyState: document.readyState, unsearched: ${UNSEARCHED_CONTENT_JS}, names: ${names}, shadowHost: ${shadowHost} })`,
             returnByValue: true,
         });
@@ -199,7 +199,7 @@ export async function noMatchContext(selector) {
  */
 export async function documentReadyState() {
     try {
-        const evaluated = await callCDP('Runtime.evaluate', {
+        const evaluated = await callBdgScript('Runtime.evaluate', {
             expression: 'document.readyState',
             returnByValue: true,
         });
@@ -212,46 +212,63 @@ export async function documentReadyState() {
     }
 }
 /** Matches whose viewport position `dom query` reports (measuring is not free) */
-const VIEWPORT_HINT_LIMIT = 100;
+export const VIEWPORT_HINT_LIMIT = 100;
 /**
- * Where each element of a page-side array lives (an iframe and/or a shadow
- * root), its text, its form control state ({@link ELEMENT_STATE_JS}) and, for
- * the first {@link VIEWPORT_HINT_LIMIT}, its position
- * relative to the viewport, plus the viewport size. An element that cannot be
- * read gets empty details instead of failing the whole query.
+ * Matches `dom query` describes and caches for use by index at least, beyond
+ * those it lists: describing costs a round trip per element, so a page with
+ * 50000 matches is not described whole unless `--limit 0` asks for it.
  */
-const ELEMENT_DETAILS_FUNCTION = `function () {
+export const QUERY_CACHE_LIMIT = 1000;
+/**
+ * For the first `count` elements of a page-side array: the tag and
+ * attributes, where it lives (an iframe and/or a shadow root), its text, its
+ * form control state ({@link ELEMENT_STATE_JS}) and, for the first
+ * {@link VIEWPORT_HINT_LIMIT}, its position relative to the viewport; plus
+ * the viewport size and how many elements the array has. An element that
+ * cannot be read gets empty details instead of failing the whole query.
+ */
+const ELEMENT_DETAILS_FUNCTION = `function (count) {
   const contextOf = ${ELEMENT_CONTEXT_JS};
   const textOf = ${ELEMENT_TEXT_JS};
   const geometryOf = ${ELEMENT_GEOMETRY_JS};
   const stateOf = ${ELEMENT_STATE_JS};
   const read = (el, index) => {
     try {
-      return { context: contextOf(el), text: textOf(el), state: stateOf(el), geometry: index < ${VIEWPORT_HINT_LIMIT} ? geometryOf(el) : null };
+      const attributes = [];
+      for (const attribute of Array.from(el.attributes || [])) attributes.push(attribute.name, attribute.value);
+      return { tag: el.nodeName, attributes: attributes, context: contextOf(el), text: textOf(el), state: stateOf(el), geometry: index < ${VIEWPORT_HINT_LIMIT} ? geometryOf(el) : null };
     } catch (e) {
       return {};
     }
   };
-  return { viewport: (${VIEWPORT_SIZE_JS})(window), elements: Array.from(this, read) };
+  return { total: this.length, viewport: (${VIEWPORT_SIZE_JS})(window), elements: Array.from(Array.prototype.slice.call(this, 0, count), read) };
 }`;
+/** Page-side: the first `count` elements of the array, as a new array */
+const SLICE_FUNCTION = `function (count) { return Array.prototype.slice.call(this, 0, count); }`;
 /**
- * Backend node ids of the elements in a page-side array, each with where it
- * lives (empty for the main document), its text and its viewport position.
+ * The first `count` elements of a page-side array with their backend node
+ * ids, tag and attributes, where each lives (empty for the main document),
+ * its text and its viewport position, and how many elements the array has.
  *
  * @param arrayObjectId - Remote object id of the array
- * @returns Elements in array order (ones that cannot be described are left out)
+ * @param count - Elements to describe (0 = all)
+ * @returns Elements in array order (ones that cannot be described are left
+ *   out) and the array's length
  * @throws CommandError (91) when the page could not describe the matches
  */
-async function elementsWithDetails(arrayObjectId) {
-    const { viewport, elements = [] } = await readPageDetails(arrayObjectId);
-    const ids = await elementBackendNodeIds(arrayObjectId);
-    return ids.flatMap((backendNodeId, index) => {
+async function elementsWithDetails(arrayObjectId, count) {
+    const limit = count === 0 ? Number.MAX_SAFE_INTEGER : count;
+    const { total = 0, viewport, elements = [] } = await readPageDetails(arrayObjectId, limit);
+    const ids = await elementBackendNodeIds(total > limit ? await sliceArray(arrayObjectId, limit) : arrayObjectId);
+    const described = ids.flatMap((backendNodeId, index) => {
         if (backendNodeId === undefined)
             return [];
         const details = elements[index];
         return [
             {
                 backendNodeId,
+                tag: details?.tag ?? '',
+                attributes: details?.attributes ?? [],
                 context: details?.context ?? '',
                 text: details?.text ?? '',
                 state: details?.state ?? {},
@@ -259,18 +276,44 @@ async function elementsWithDetails(arrayObjectId) {
             },
         ];
     });
+    return { total, elements: described };
+}
+/**
+ * A page-side array of the first elements of another (in the same object
+ * group), so only those are described.
+ *
+ * @param arrayObjectId - Remote object id of the array
+ * @param count - Elements to keep
+ * @returns Remote object id of the shorter array
+ * @throws CommandError (91) when the page could not slice it
+ */
+async function sliceArray(arrayObjectId, count) {
+    const response = await callCDP('Runtime.callFunctionOn', {
+        objectId: arrayObjectId,
+        functionDeclaration: SLICE_FUNCTION,
+        arguments: [{ value: count }],
+    });
+    const objectId = response.data?.result
+        ?.result?.objectId;
+    if (!objectId) {
+        const err = operationFailedError('describe the matches', response.error ?? 'no result');
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SCRIPT_ERROR);
+    }
+    return objectId;
 }
 /**
  * Run {@link ELEMENT_DETAILS_FUNCTION} on a page-side array.
  *
  * @param arrayObjectId - Remote object id of the array
- * @returns Details of each element and the viewport size
+ * @param count - Elements to describe, from the start
+ * @returns Details of those elements, the array's length and the viewport size
  * @throws CommandError (91) when the script failed
  */
-async function readPageDetails(arrayObjectId) {
+async function readPageDetails(arrayObjectId, count) {
     const response = await callCDP('Runtime.callFunctionOn', {
         objectId: arrayObjectId,
         functionDeclaration: ELEMENT_DETAILS_FUNCTION,
+        arguments: [{ value: count }],
         returnByValue: true,
     });
     const result = response.data?.result;
@@ -359,40 +402,49 @@ function mapConcurrently(items, mapper) {
     return Promise.all(items.map((item, index) => limiter.run(() => mapper(item, index))));
 }
 /**
- * Query elements by selector for `bdg dom query`.
+ * Query elements by selector for `bdg dom query`: all matches are counted,
+ * and the first `limit` (at least {@link QUERY_CACHE_LIMIT}, so indices past
+ * the listed ones still work) are described in one page-side pass plus one
+ * `DOM.describeNode` each for their backend node id.
  *
  * @param selector - CSS selector
- * @returns Matches with backend node ids, tags, classes and text previews
+ * @param limit - Matches the caller lists (0 = all, so all are described)
+ * @returns The match count, and the described matches with backend node
+ *   ids, tags, key attributes, classes and text previews
  */
-export async function queryDOMElements(selector) {
-    const elements = await withSelection(selector, elementsWithDetails);
-    if (elements.length > 20) {
-        log.debug(`Querying ${elements.length} elements with selector: ${selector}`);
-    }
-    const nodes = await mapConcurrently(elements, async (element, index) => {
-        const { backendNodeId, context, text, state, inViewport, clippedBy } = element;
-        const desc = await describeNode({ backendNodeId });
-        if (!desc)
-            return { index, nodeId: 0 };
-        const attributes = unpackAttributes(desc.attributes);
-        const classes = attributes['class']?.split(/\s+/).filter(Boolean);
-        const preview = textPreview(text);
-        const tag = desc.nodeName.toLowerCase();
-        const keys = keyAttributes(tag, attributes, state);
-        return {
-            index,
-            nodeId: desc.backendNodeId,
-            tag,
-            ...identifyingAttributes(attributes, desc.nodeName),
-            ...(keys && { attributes: keys }),
-            ...(classes && { classes }),
-            ...(preview && { preview }),
-            ...(context && { context }),
-            ...(inViewport && { inViewport }),
-            ...(clippedBy && { clippedBy }),
-        };
-    });
-    return { selector, count: nodes.length, nodes };
+export async function queryDOMElements(selector, limit = 0) {
+    const described = limit === 0 ? 0 : Math.max(limit, QUERY_CACHE_LIMIT);
+    const { total, elements } = await withSelection(selector, (arrayObjectId) => elementsWithDetails(arrayObjectId, described));
+    if (total > 20)
+        log.debug(`Queried ${total} elements with selector: ${selector}`);
+    return { selector, count: total, nodes: elements.map(queryNode) };
+}
+/**
+ * One described match as `dom query` reports it.
+ *
+ * @param element - Match with its page-side details
+ * @param index - Its position among the matches
+ * @returns Query node
+ */
+function queryNode(element, index) {
+    const { backendNodeId, context, text, state, inViewport, clippedBy } = element;
+    const attributes = unpackAttributes(element.attributes);
+    const classes = attributes['class']?.split(/\s+/).filter(Boolean);
+    const preview = textPreview(text);
+    const tag = element.tag.toLowerCase();
+    const keys = keyAttributes(tag, attributes, state);
+    return {
+        index,
+        nodeId: backendNodeId,
+        tag,
+        ...identifyingAttributes(attributes, element.tag),
+        ...(keys && { attributes: keys }),
+        ...(classes && { classes }),
+        ...(preview && { preview }),
+        ...(context && { context }),
+        ...(inViewport && { inViewport }),
+        ...(clippedBy && { clippedBy }),
+    };
 }
 /**
  * The attributes that tell similar elements apart (form fields especially).
@@ -420,7 +472,7 @@ function identifyingAttributes(attributes, nodeName) {
  */
 async function elementTextAndState(ref, full) {
     const objectGroup = `bdg-text-${process.pid}-${++queryCount}`;
-    const resolved = await callCDP('DOM.resolveNode', { ...ref, objectGroup });
+    const resolved = await callBdgScript('DOM.resolveNode', { ...ref, objectGroup });
     const objectId = resolved.data?.result?.object
         .objectId;
     if (!objectId)
@@ -478,33 +530,40 @@ export async function getDomContext(ref, options = {}) {
 }
 /** Child elements named for an element without text */
 const CHILDREN_LISTED = 5;
+/** Children that show nothing themselves, left out of the listing */
+const UNSHOWN_CHILD = /^(SCRIPT|STYLE|LINK|TEMPLATE)$/;
 /**
  * The child elements of an element (for one without text: a body holding
- * only an iframe, an empty app root).
+ * only an iframe, an empty app root). A web component is described by its
+ * shadow root's children, which is what it shows (an icon button named
+ * there); scripts, styles and templates are left out.
  *
  * @param ref - Node reference
- * @returns The first {@link CHILDREN_LISTED} as `tag#id.class` and how many there are
+ * @returns The first {@link CHILDREN_LISTED} as `tag#id.class "label"`, how many there are, and whether they are in its shadow root
  */
 async function childElements(ref) {
-    const response = await callCDP('DOM.describeNode', { ...ref, depth: 1 });
+    const response = await callCDP('DOM.describeNode', { ...ref, depth: 2, pierce: true });
     const node = response.data?.result?.node;
-    const elements = (node?.children ?? []).filter((child) => child.nodeType === 1);
+    const shadowRoot = node?.shadowRoots?.find((root) => root.shadowRootType !== 'user-agent');
+    const elements = ((shadowRoot ?? node)?.children ?? []).filter((child) => child.nodeType === 1 && !UNSHOWN_CHILD.test(child.nodeName));
     return {
         children: elements.slice(0, CHILDREN_LISTED).map(childLabel),
         childCount: elements.length,
+        ...(shadowRoot && { shadowChildren: true }),
     };
 }
 /**
- * A child element in a few characters.
+ * A child element in a few characters, with its aria-label when it has one.
  *
  * @param node - Child node
- * @returns e.g. `iframe#app.full`
+ * @returns e.g. `iframe#app.full`, `button.icon "Close"`
  */
 function childLabel(node) {
     const attributes = unpackAttributes(node.attributes);
     const id = attributes['id'] ? `#${attributes['id']}` : '';
-    const classes = (attributes['class'] ?? '').split(/\s+/).filter(Boolean).slice(0, 2);
-    return `${node.nodeName.toLowerCase()}${id}${classes.map((name) => `.${name}`).join('')}`;
+    const classes = (attributes['class'] ?? '').split(/\s+/).filter(isLabelClass).slice(0, 2);
+    const label = attributes['aria-label']?.trim();
+    return `${node.nodeName.toLowerCase()}${id}${classes.map((name) => `.${name}`).join('')}${label ? ` "${label}"` : ''}`;
 }
 /**
  * All matches of a selector.
@@ -629,7 +688,10 @@ export async function resolveBackendNodeIds(selectors) {
  * @throws CommandError (87) when the element is gone
  */
 export async function assertNodeAttached(backendNodeId, source) {
-    const resolved = await callCDP('DOM.resolveNode', { backendNodeId, objectGroup: 'bdg-check' });
+    const resolved = await callBdgScript('DOM.resolveNode', {
+        backendNodeId,
+        objectGroup: 'bdg-check',
+    });
     const objectId = resolved.data?.result?.object
         .objectId;
     let attached = false;
@@ -648,4 +710,30 @@ export async function assertNodeAttached(backendNodeId, source) {
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
     }
 }
+/**
+ * Identity of the page's current document: its time origin, which every
+ * document load gets anew. Cached backend node ids belong to one document; a
+ * page loaded in a new renderer process reuses the same ids for other
+ * elements, so an index of an older document must not be used.
+ *
+ * @returns The identity, or undefined when the page cannot be asked
+ * @throws CommandError when the page is busy (102) or crashed (107), as the
+ *   command itself would
+ */
+export async function pageDocumentId() {
+    try {
+        const evaluated = await callBdgScript('Runtime.evaluate', {
+            expression: 'String(performance.timeOrigin)',
+            returnByValue: true,
+        });
+        const { result } = (evaluated.data?.result ?? {});
+        return typeof result?.value === 'string' ? result.value : undefined;
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        log.debug(`Page document not identified: ${getErrorMessage(error)}`);
+        return undefined;
+    }
+}
 //# sourceMappingURL=query.js.map

package/dist/commands/dom/helpers/screenshot.js

@@ -9,7 +9,7 @@ import { writeOutputFile } from '../../shared/outputFile.js';
 import { CDPConnectionError } from '../../../connection/errors.js';
 import { CommandError } from '../../../errors/index.js';
 import { noNodesFoundError, elementNotVisibleError, elementZeroDimensionsError, } from '../../../errors/messages.js';
-import { callCDP } from '../../../ipc/client.js';
+import { callBdgScript, callCDP } from '../../../ipc/client.js';
 import { DEEP_QUERY_JS, selectorArgsJS } from '../../../runtime/dom/targetNode.js';
 import { viewportOverride } from '../../../runtime/page/emulation.js';
 import { readSessionMetadata } from '../../../session/metadata.js';
@@ -26,7 +26,7 @@ const STABILITY_CHECK_INTERVAL_MS = 50;
  */
 async function waitForPostScrollStability() {
     const deadline = Date.now() + POST_SCROLL_MAX_WAIT_MS;
-    await callCDP('Runtime.evaluate', {
+    await callBdgScript('Runtime.evaluate', {
         expression: `
       (() => {
         window.__bdg_scrollStability = {
@@ -66,7 +66,7 @@ async function waitForPostScrollStability() {
     });
     try {
         while (Date.now() < deadline) {
-            const checkResult = await callCDP('Runtime.evaluate', {
+            const checkResult = await callBdgScript('Runtime.evaluate', {
                 expression: `
           (() => {
             const state = window.__bdg_scrollStability;
@@ -91,7 +91,7 @@ async function waitForPostScrollStability() {
         log.debug('Post-scroll stability timeout, proceeding anyway');
     }
     finally {
-        await callCDP('Runtime.evaluate', {
+        await callBdgScript('Runtime.evaluate', {
             expression: `
         (() => {
           const state = window.__bdg_scrollStability;
@@ -111,7 +111,7 @@ async function waitForPostScrollStability() {
  * position so it can be restored afterwards.
  */
 async function scrollToElement(selector) {
-    const result = await callCDP('Runtime.evaluate', {
+    const result = await callBdgScript('Runtime.evaluate', {
         expression: `
       (() => {
         const el = (${DEEP_QUERY_JS})(${selectorArgsJS(selector)})[0];
@@ -133,7 +133,7 @@ async function scrollToElement(selector) {
     return { x: value.originalX ?? 0, y: value.originalY ?? 0 };
 }
 async function restoreScrollPosition(position) {
-    await callCDP('Runtime.evaluate', {
+    await callBdgScript('Runtime.evaluate', {
         expression: `window.scrollTo(${position.x}, ${position.y})`,
         returnByValue: true,
     });
@@ -147,7 +147,7 @@ async function restoreScrollPosition(position) {
  * @returns Width and height in CSS px
  */
 async function windowSize(viewport) {
-    const response = await callCDP('Runtime.evaluate', {
+    const response = await callBdgScript('Runtime.evaluate', {
         expression: '[window.innerWidth, window.innerHeight]',
         returnByValue: true,
     });
@@ -245,7 +245,7 @@ export async function capturePageScreenshot(outputPath, options = {}) {
     if (options.scroll) {
         originalScrollPosition = await scrollToElement(options.scroll);
     }
-    const dprResponse = await callCDP('Runtime.evaluate', {
+    const dprResponse = await callBdgScript('Runtime.evaluate', {
         expression: 'window.devicePixelRatio',
         returnByValue: true,
     });
@@ -266,7 +266,7 @@ export async function capturePageScreenshot(outputPath, options = {}) {
     const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, viewport);
     if (devicePixelRatio !== 1) {
         if (options.scroll) {
-            await callCDP('Runtime.evaluate', {
+            await callBdgScript('Runtime.evaluate', {
                 expression: `(${DEEP_QUERY_JS})(${selectorArgsJS(options.scroll)})[0]?.scrollIntoView({ block: 'center', behavior: 'instant' })`,
                 returnByValue: true,
             });
@@ -461,7 +461,7 @@ async function measureInView(ref, padding) {
     const scrolledFrom = await scrollPosition();
     const dx = bounds.x + bounds.width / 2 - view.width / 2;
     const dy = bounds.y + bounds.height / 2 - view.height / 2;
-    await callCDP('Runtime.evaluate', { expression: `window.scrollBy(${dx}, ${dy})` });
+    await callBdgScript('Runtime.evaluate', { expression: `window.scrollBy(${dx}, ${dy})` });
     try {
         box = await getElementBounds(ref);
         bounds = await captureArea(ref, box, padding);
@@ -501,7 +501,7 @@ async function restoreViewport() {
  * @returns Scroll offsets in CSS px
  */
 async function scrollPosition() {
-    const response = await callCDP('Runtime.evaluate', {
+    const response = await callBdgScript('Runtime.evaluate', {
         expression: '[window.scrollX, window.scrollY]',
         returnByValue: true,
     });
@@ -544,7 +544,7 @@ async function captureArea(ref, bounds, padding) {
 async function paintedArea(ref, bounds) {
     const objectGroup = `bdg-shot-${process.pid}`;
     try {
-        const resolved = await callCDP('DOM.resolveNode', { ...ref, objectGroup });
+        const resolved = await callBdgScript('DOM.resolveNode', { ...ref, objectGroup });
         const objectId = resolved.data?.result?.object
             .objectId;
         if (!objectId)
@@ -586,7 +586,7 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
     const format = options.format ?? 'png';
     const quality = format === 'jpeg' ? (options.quality ?? 90) : undefined;
     const noResize = options.noResize ?? false;
-    const dprResponse = await callCDP('Runtime.evaluate', {
+    const dprResponse = await callBdgScript('Runtime.evaluate', {
         expression: 'window.devicePixelRatio',
         returnByValue: true,
     });

package/dist/commands/dom/index.js

@@ -17,15 +17,16 @@
  */
 import { Option } from 'commander';
 import { registerA11yCommands } from './a11y.js';
+import { registerAuditCommand } from './audit.js';
 import { handleDomEval } from './eval.js';
 import { registerFormCommand } from './form.js';
 import { handleDomFrames } from './frames.js';
 import { DOM_GET_DEFAULT_SELECTOR, handleDomGet } from './get.js';
+import { QUERY_CACHE_LIMIT } from './helpers/query.js';
 import { registerInspectCommand } from './inspect.js';
-import { registerAuditCommand } from './audit.js';
 import { registerLayoutCommand } from './layout.js';
 import { registerListenersCommand } from './listeners.js';
-import { handleDomQuery } from './query.js';
+import { handleDomQuery, QUERY_LIST_LIMIT } from './query.js';
 import { handleDomScreenshot } from './screenshot.js';
 import { registerWaitCommand } from './wait.js';
 import { SELECTOR_OR_INDEX_ARGUMENT, SELECTOR_SCOPE_HELP, } from '../shared/commonOptions.js';
@@ -49,6 +50,7 @@ export function registerDomCommands(program) {
         .command('query')
         .description('Find elements by CSS selector')
         .argument('<selector>', 'CSS selector (e.g., ".error", "#app", "button")')
+        .option('--limit <n>', `Matches to list (default: ${QUERY_LIST_LIMIT}, ${QUERY_CACHE_LIMIT} with --json; 0 = all); the first ${QUERY_CACHE_LIMIT} (or more with a higher limit) are indexed`, integerOption(0))
         .option('-j, --json', 'Output as JSON')
         .addHelpText('after', SELECTOR_SCOPE_HELP)
         .action(async (selector, options) => {