browser-debugger-cli 0.11.0 → 0.13.0

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/keyAttributes.d.ts

@@ -5,8 +5,9 @@
  */
 import type { ElementState, KeyAttributes } from '../../../types.js';
 /**
- * The key attributes of an element: the identifying attributes of its type
- * that are set (empty ones left out) and the live state of a form control
+ * The key attributes of an element: its shadow `part` name (how a page's CSS
+ * reaches it with `::part()`), the identifying attributes of its type that
+ * are set (empty ones left out) and the live state of a form control
  * (type, current value, checked, selected options). Values arrive masked
  * from the page (`ELEMENT_STATE_JS`); a hidden input's value is never read,
  * and a sensitive field's value is masked here again in case it was not.

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

@@ -16,8 +16,9 @@ const ATTRIBUTES_BY_TAG = {
     form: ['action', 'method'],
 };
 /**
- * The key attributes of an element: the identifying attributes of its type
- * that are set (empty ones left out) and the live state of a form control
+ * The key attributes of an element: its shadow `part` name (how a page's CSS
+ * reaches it with `::part()`), the identifying attributes of its type that
+ * are set (empty ones left out) and the live state of a form control
  * (type, current value, checked, selected options). Values arrive masked
  * from the page (`ELEMENT_STATE_JS`); a hidden input's value is never read,
  * and a sensitive field's value is masked here again in case it was not.
@@ -29,9 +30,10 @@ const ATTRIBUTES_BY_TAG = {
  */
 export function keyAttributes(tag, attributes, state = {}) {
     const names = ATTRIBUTES_BY_TAG[tag];
+    const part = attributes['part'];
     if (!names)
-        return undefined;
-    const result = {};
+        return part ? { part } : undefined;
+    const result = part ? { part } : {};
     const type = state.type ?? attributes['type'];
     if (type)
         result['type'] = type;

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.d.ts

@@ -29,5 +29,6 @@ export declare function captureElementScreenshot(outputPath: string, ref: NodeRe
     format?: 'png' | 'jpeg';
     quality?: number;
     noResize?: boolean;
+    padding?: number;
 }): Promise<ScreenshotResult>;
 //# sourceMappingURL=screenshot.d.ts.map