browser-debugger-cli 0.12.0 → 0.14.0

package/dist/commands/dom/form.js

@@ -5,11 +5,12 @@
  * validation state, and suggested commands for agent consumption.
  */
 import { calculateSummary, orderForms, primaryButtonIndex } from './formSummary.js';
-import { resolveBackendNodeIds } from './helpers/index.js';
+import { pageDocumentId, resolveBackendNodeIds } from './helpers/index.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { jsonOption } from '../shared/commonOptions.js';
 import { noFormsFoundError, formInIframeError } from '../../errors/messages.js';
 import { domFormDiscover } from '../../ipc/client.js';
+import { MASKED_VALUE } from '../../runtime/dom/elementInfo.js';
 import { FORM_DISCOVERY_CACHE_SELECTOR, QueryCacheManager } from '../../session/QueryCacheManager.js';
 import { formatFormDiscovery } from '../../ui/formatters/form.js';
 import { createLogger } from '../../ui/logging/index.js';
@@ -84,16 +85,14 @@ function buildFieldState(raw) {
     return 'empty';
 }
 /**
- * Build masked value for password fields.
+ * The masked value of a sensitive field (the page script never sends its
+ * real value).
  *
  * @param raw - Raw field data
  * @returns Masked value string
  */
 function buildMaskedValue(raw) {
-    if (raw.inputType === 'password' && typeof raw.value === 'string' && raw.value.length > 0) {
-        return '•'.repeat(Math.min(raw.value.length, 8));
-    }
-    return undefined;
+    return raw.value === MASKED_VALUE ? MASKED_VALUE : undefined;
 }
 /**
  * Build interaction warning for non-native fields.
@@ -244,8 +243,9 @@ function transformForm(raw) {
  * the selector later.
  *
  * @param forms - Discovered forms
+ * @param document - Identity of the page document they were found in, read before discovery
  */
-async function cacheFormElements(forms) {
+async function cacheFormElements(forms, document) {
     const elements = forms.flatMap((form) => [...form.fields, ...form.buttons]);
     const backendNodeIds = await resolveBackendNodeIds(elements.map((el) => el.selector)).catch((error) => {
         log.debug(`Form fields not cached by node: ${getErrorMessage(error)}`);
@@ -259,7 +259,7 @@ async function cacheFormElements(forms) {
             nodeId: backendNodeIds[i] ?? 0,
             selector: el.selector,
         })),
-    });
+    }, document);
     log.debug(`Cached ${elements.length} form elements`);
 }
 /**
@@ -269,6 +269,7 @@ async function cacheFormElements(forms) {
  */
 async function handleFormCommand(options) {
     await runCommand(async () => {
+        const document = await pageDocumentId();
         const response = await domFormDiscover();
         if (response.status === 'error' || !response.data) {
             return {
@@ -311,7 +312,7 @@ async function handleFormCommand(options) {
         const allForms = orderForms(rawData.forms).map(transformForm);
         const forms = options.all ? allForms : [allForms[0]];
         // Cache ALL forms so global indices work with bdg dom fill/click
-        await cacheFormElements(allForms);
+        await cacheFormElements(allForms, document);
         const result = {
             formCount: rawData.forms.length,
             selectedForm: 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 */
@@ -57,7 +58,7 @@ export function registerFormInteractionCommands(program) {
         .command('fill')
         .description('Fill a form field with a value (React-compatible, waits for stability)')
         .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
-        .argument('<value>', 'Value to fill (file inputs: paths separated by commas, "" clears)')
+        .argument('<value>', 'Value to fill (file inputs: local file paths, separated by commas, that are uploaded to the page; "" clears)')
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .option('--no-blur', 'Do not blur after filling (keeps focus on element)')
         .option('--no-wait', 'Skip waiting for network stability after fill')
@@ -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

@@ -9,12 +9,14 @@ import { DomElementResolver } from './DomElementResolver.js';
 import { getDOMElements, getDomContext, selectMatch, } from './helpers/index.js';
 import { formatSemanticNodeWithContext, resolveNodeWithFallback, } from './semanticUtils.js';
 import { runCommand } from '../shared/CommandRunner.js';
+import { MAX_VALUE_LENGTH } from '../../constants.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';
 import { filterDefined } from '../../utils/objects.js';
+import { capLength } from '../../utils/strings.js';
 /** What `bdg dom get` reads without a selector */
 export const DOM_GET_DEFAULT_SELECTOR = 'body';
 /**
@@ -58,7 +60,7 @@ async function semanticElement(backendNodeId, full) {
  * Raw view: the element(s) with attributes and outer HTML.
  *
  * @param selectorOrIndex - CSS selector or cached index
- * @param options - Command options (`--all`, `--index`)
+ * @param options - Command options (`--all`, `--index`, `--full`)
  */
 async function handleRawGet(selectorOrIndex, options) {
     await runCommand(async () => {
@@ -70,8 +72,27 @@ async function handleRawGet(selectorOrIndex, options) {
                 all: options.all,
                 nth: matchIndex(options),
             });
-        return { success: true, data: await getDOMElements(getOptions) };
-    }, options, formatDomGet);
+        return { success: true, data: rawGetData(await getDOMElements(getOptions), options) };
+    }, options, (data) => formatDomGet(data, { full: options.full }));
+}
+/**
+ * Raw elements for the output: in JSON each outer HTML is cut to
+ * {@link MAX_VALUE_LENGTH} characters with `truncatedFrom`, unless `--full`
+ * (human output is cut when formatted).
+ *
+ * @param result - Elements read
+ * @param options - `--json`, `--full`
+ * @returns Elements to output
+ */
+function rawGetData(result, options) {
+    if (!options.json || options.full)
+        return result;
+    return {
+        nodes: result.nodes.map((node) => {
+            const { text, truncatedFrom } = capLength(node.outerHTML ?? '', MAX_VALUE_LENGTH);
+            return truncatedFrom === undefined ? node : { ...node, outerHTML: text, truncatedFrom };
+        }),
+    };
 }
 /**
  * Semantic view of the target.
@@ -99,23 +120,20 @@ 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');
-    }
-    if (options.full && (options.raw || options.nodeId !== undefined)) {
-        return conflictingOptionsMessage('--full', options.raw ? '--raw' : '--node-id');
+        return conflictingOptionsError('--node-id', 'a selector or index');
     }
     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,11 +148,11 @@ 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) {
-        await runCommand(async () => ({ success: true, data: await getDOMElements({ nodeId }) }), options, formatDomGet);
+        await runCommand(async () => ({ success: true, data: rawGetData(await getDOMElements({ nodeId }), options) }), options, (data) => formatDomGet(data, { full: options.full }));
         return;
     }
     const target = selectorOrIndex ?? DOM_GET_DEFAULT_SELECTOR;

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