browser-debugger-cli 0.8.0 → 0.10.0

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

@@ -9,19 +9,23 @@
  * bdg invocations. Selectors are matched in the page, including open shadow
  * roots and same-origin iframes, like a user sees the page.
  */
+import { keyAttributes } from './keyAttributes.js';
 import { CommandError } from '../../../errors/index.js';
-import { noNodesFoundError, indexOutOfRangeError, eitherArgumentRequiredError, invalidSelectorError, nodeIdNotFoundError, staleNodeError, } from '../../../errors/messages.js';
+import { noNodesFoundError, indexOutOfRangeError, eitherArgumentRequiredError, invalidSelectorError, nodeIdNotFoundError, operationFailedError, similarSelectorsLine, staleNodeError, } from '../../../errors/messages.js';
 import { callCDP } from '../../../ipc/client.js';
-import { DEEP_QUERY_JS, selectorArgsJS } from '../../../runtime/dom/targetNode.js';
-import { resolveA11yNode } from '../../../telemetry/a11y.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 { 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';
 import { ConcurrencyLimiter } from '../../../utils/concurrency.js';
+import { getErrorMessage } from '../../../utils/errors.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
+import { leadingCompounds, parseSelectorFilters, withoutVisibleFilters, } from '../../../utils/selectorFilters.js';
+import { findSimilarNames, parseSingleNameSelector } from '../../../utils/suggestions.js';
 const log = createLogger('dom');
 /** Maximum concurrent CDP calls to avoid overwhelming the connection. */
 const CDP_CONCURRENCY_LIMIT = 10;
-/** Length of the text preview shown for queried elements. */
-const PREVIEW_LENGTH = 80;
 /**
  * Convert CDP's flat attribute list to a record.
  *
@@ -63,33 +67,6 @@ async function getOuterHTML(ref) {
     const response = await callCDP('DOM.getOuterHTML', ref);
     return response.data?.result?.outerHTML;
 }
-/**
- * Page-side text of an element as a user sees it: `innerText` for a rendered
- * element (CSS-hidden parts left out, inline elements not split apart), none
- * for an element that is not rendered, `textContent` for SVG and other
- * elements without `innerText` and for `display: contents` wrappers (no box
- * of their own, but their children are shown).
- */
-const ELEMENT_TEXT_JS = `(el) => {
-  if (typeof el.innerText !== 'string') return el.textContent || '';
-  if (!el.checkVisibility || el.checkVisibility()) return el.innerText;
-  const boxless = el.ownerDocument.defaultView.getComputedStyle(el).display === 'contents';
-  return boxless ? el.textContent || '' : '';
-}`;
-/**
- * Short text preview of an element's text: whitespace collapsed, cut on a
- * whole character (an emoji is never split, which would make JSON invalid).
- *
- * @param text - Element text as the page renders it
- * @returns Collapsed text, truncated to {@link PREVIEW_LENGTH} characters
- */
-export function textPreview(text) {
-    const collapsed = text.replace(/\s+/g, ' ').trim();
-    const characters = Array.from(collapsed);
-    return characters.length > PREVIEW_LENGTH
-        ? characters.slice(0, PREVIEW_LENGTH).join('') + '...'
-        : collapsed;
-}
 /** Counter giving each query its own object group (queries may run concurrently) */
 let queryCount = 0;
 /**
@@ -126,53 +103,203 @@ async function withSelection(selector, use) {
         await callCDP('Runtime.releaseObjectGroup', { objectGroup });
     }
 }
-/** Where each element of a page-side array lives (an iframe and/or a shadow root), and its text */
+/**
+ * The "no nodes" error for a selector that matched nothing. One more page
+ * evaluation, on this failure path only, tells what the page says about it
+ * ({@link noMatchContext}).
+ *
+ * @param selector - Selector as given
+ * @returns Message and suggestion
+ */
+export async function noMatchesError(selector) {
+    return noNodesFoundError(selector, await noMatchContext(selector));
+}
+/**
+ * Page-side index of the first leading compound that matches a shadow host
+ * (an element with an open shadow root, anywhere a selector reaches) while
+ * the selector after it finds something: then the selector only failed by
+ * crossing into the shadow root.
+ *
+ * @param compounds - Leading compounds of the selector
+ * @returns Expression evaluating to the index, or -1
+ */
+function shadowHostJS(compounds) {
+    const plain = compounds
+        .slice(0, MAX_HOST_COMPOUNDS)
+        .map((entry) => [withoutFilters(entry.compound), withoutFilters(entry.rest)]);
+    return `${JSON.stringify(plain)}.findIndex(([host, rest]) => { try { const deep = ${DEEP_QUERY_JS}; return deep(host, null).some((el) => el.shadowRoot) && deep(rest, null).length > 0; } catch (e) { return false; } })`;
+}
+/** Leading compounds checked for a shadow host (each check walks the page) */
+const MAX_HOST_COMPOUNDS = 4;
+/**
+ * A selector without bdg's filters (`:visible`, `:has-text()`, `:text-is()`),
+ * which plain CSS does not know.
+ *
+ * @param selector - Selector
+ * @returns Plain CSS
+ */
+function withoutFilters(selector) {
+    return (selector.replace(/:visible\b|:(has-text|text-is)\((?:"[^"]*"|'[^']*'|[^)"'])*\)/g, '').trim() ||
+        '*');
+}
+/**
+ * What the page says about a selector that matched nothing, in one
+ * evaluation: whether it is still loading, how many elements match with the
+ * selector's `:visible` filters removed, whether it has cross-origin iframes
+ * or embeds (which selectors do not search), and for a selector that is a
+ * single id or class, the similar ids or classes on the page.
+ *
+ * @param selector - Selector as given
+ * @returns Context for {@link noNodesFoundError} (empty when the page did not answer)
+ */
+export async function noMatchContext(selector) {
+    const parts = parseSelectorFilters(selector);
+    const unfiltered = parts && withoutVisibleFilters(parts);
+    const single = parseSingleNameSelector(selector);
+    const hidden = unfiltered
+        ? `(() => { try { return (${DEEP_QUERY_JS})(${JSON.stringify(selector)}, ${JSON.stringify(unfiltered)}).length; } catch (e) { return 0; } })()`
+        : '0';
+    const names = single ? pageNamesJS(single.kind) : '[]';
+    const compounds = leadingCompounds(selector);
+    const shadowHost = compounds.length > 0 ? shadowHostJS(compounds) : '-1';
+    try {
+        const evaluated = await callCDP('Runtime.evaluate', {
+            expression: `({ hidden: ${hidden}, readyState: document.readyState, unsearched: ${UNSEARCHED_CONTENT_JS}, names: ${names}, shadowHost: ${shadowHost} })`,
+            returnByValue: true,
+        });
+        const { result } = (evaluated.data?.result ?? {});
+        const value = (result?.value ?? {});
+        const similar = single && Array.isArray(value.names)
+            ? similarSelectorsLine(single.kind, findSimilarNames(single.name, value.names.filter((n) => typeof n === 'string')))
+            : '';
+        return {
+            hidden: typeof value.hidden === 'number' ? value.hidden : 0,
+            ...(typeof value.readyState === 'string' && { readyState: value.readyState }),
+            ...(value.unsearched && {
+                unsearched: {
+                    crossOriginFrames: value.unsearched.crossOriginFrames === true,
+                    embeds: value.unsearched.embeds === true,
+                },
+            }),
+            ...(similar && { similar }),
+            ...(typeof value.shadowHost === 'number' &&
+                compounds[value.shadowHost] && { shadowHost: compounds[value.shadowHost] }),
+        };
+    }
+    catch (error) {
+        log.debug(`Could not read the page after no match: ${getErrorMessage(error)}`);
+        return {};
+    }
+}
+/**
+ * The page's `document.readyState`, read for a failure that may come from a
+ * page still loading.
+ *
+ * @returns The state, or undefined when the page did not answer
+ */
+export async function documentReadyState() {
+    try {
+        const evaluated = await callCDP('Runtime.evaluate', {
+            expression: 'document.readyState',
+            returnByValue: true,
+        });
+        const { result } = (evaluated.data?.result ?? {});
+        return typeof result?.value === 'string' ? result.value : undefined;
+    }
+    catch (error) {
+        log.debug(`Could not read document.readyState: ${getErrorMessage(error)}`);
+        return undefined;
+    }
+}
+/** Matches whose viewport position `dom query` reports (measuring is not free) */
+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.
+ */
 const ELEMENT_DETAILS_FUNCTION = `function () {
-  const describe = (node) => node.tagName.toLowerCase() + (node.id ? '#' + node.id : '');
+  const contextOf = ${ELEMENT_CONTEXT_JS};
   const textOf = ${ELEMENT_TEXT_JS};
-  return Array.from(this, (el) => {
-    const parts = [];
-    for (let doc = el.ownerDocument; doc && doc.defaultView && doc.defaultView.frameElement; ) {
-      const frame = doc.defaultView.frameElement;
-      parts.unshift(describe(frame));
-      doc = frame.ownerDocument;
+  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 };
+    } catch (e) {
+      return {};
     }
-    const root = el.getRootNode();
-    if (root.host) parts.push('shadow root of <' + describe(root.host) + '>');
-    return { context: parts.join(' > '), text: textOf(el) };
-  });
+  };
+  return { viewport: (${VIEWPORT_SIZE_JS})(window), elements: Array.from(this, read) };
 }`;
 /**
  * Backend node ids of the elements in a page-side array, each with where it
- * lives (empty for the main document) and its text.
+ * lives (empty for the main document), its text and its viewport position.
  *
  * @param arrayObjectId - Remote object id of the array
  * @returns Elements in array order (ones that cannot be described are left out)
+ * @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) => {
+        if (backendNodeId === undefined)
+            return [];
+        const details = elements[index];
+        return [
+            {
+                backendNodeId,
+                context: details?.context ?? '',
+                text: details?.text ?? '',
+                state: details?.state ?? {},
+                ...viewportHint(details?.geometry, viewport),
+            },
+        ];
+    });
+}
+/**
+ * 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
+ * @throws CommandError (91) when the script failed
+ */
+async function readPageDetails(arrayObjectId) {
     const response = await callCDP('Runtime.callFunctionOn', {
         objectId: arrayObjectId,
         functionDeclaration: ELEMENT_DETAILS_FUNCTION,
         returnByValue: true,
     });
-    const value = response.data?.result?.result
-        ?.value;
-    const details = (Array.isArray(value) ? value : []);
-    const ids = await elementBackendNodeIds(arrayObjectId);
-    return ids.flatMap((backendNodeId, index) => backendNodeId === undefined
-        ? []
-        : [
-            {
-                backendNodeId,
-                context: details[index]?.context ?? '',
-                text: details[index]?.text ?? '',
-            },
-        ]);
+    const result = response.data?.result;
+    if (response.status === 'error' || result?.exceptionDetails) {
+        const detail = result?.exceptionDetails?.exception?.description ?? response.error ?? 'no result';
+        const err = operationFailedError('describe the matches', detail.split('\n')[0] ?? detail);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SCRIPT_ERROR);
+    }
+    return (result?.result?.value ?? {});
+}
+/**
+ * Viewport position of a measured element for `dom query`.
+ *
+ * @param geometry - Page-side measurements (none beyond the hint limit)
+ * @param viewport - Viewport size
+ * @returns `inViewport` (and `clippedBy`), or nothing when not measured
+ */
+function viewportHint(geometry, viewport) {
+    if (!geometry || !viewport)
+        return {};
+    const { inViewport, clippedBy } = classifyViewportPosition(geometry, viewport);
+    return { inViewport, ...(clippedBy && { clippedBy }) };
 }
 /**
  * The page-side array of a selector query, or the error explaining why there
  * is none: a selector the browser rejects (a `SyntaxError` DOMException) is the
- * user's (81); anything else (no session, a page navigating away) is not.
+ * user's (81; the browser's message is left out for selectors with filters,
+ * as it quotes the CSS bdg rewrote them to); anything else (no session, a
+ * page navigating away) is not.
  *
  * @param selector - CSS selector
  * @param evaluated - `Runtime.evaluate` response
@@ -184,7 +311,7 @@ function selectionObjectId(selector, evaluated) {
         {});
     const description = exceptionDetails?.exception?.description;
     if (description?.startsWith('SyntaxError')) {
-        const detail = description.split('\n')[0];
+        const detail = parseSelectorFilters(selector) ? undefined : description.split('\n')[0];
         const err = invalidSelectorError(selector, detail);
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
     }
@@ -242,21 +369,27 @@ export async function queryDOMElements(selector) {
     if (elements.length > 20) {
         log.debug(`Querying ${elements.length} elements with selector: ${selector}`);
     }
-    const nodes = await mapConcurrently(elements, async ({ backendNodeId, context, text }, index) => {
+    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: desc.nodeName.toLowerCase(),
-            ...identifyingAttributes(attributes),
+            tag,
+            ...identifyingAttributes(attributes, desc.nodeName),
+            ...(keys && { attributes: keys }),
             ...(classes && { classes }),
             ...(preview && { preview }),
             ...(context && { context }),
+            ...(inViewport && { inViewport }),
+            ...(clippedBy && { clippedBy }),
         };
     });
     return { selector, count: nodes.length, nodes };
@@ -265,63 +398,144 @@ export async function queryDOMElements(selector) {
  * The attributes that tell similar elements apart (form fields especially).
  *
  * @param attributes - Element attributes
- * @returns id, name and type when present
+ * @param nodeName - Element name (`OPTION`s also report their `value`)
+ * @returns id, name and type (and an option's value) when present
  */
-function identifyingAttributes(attributes) {
+function identifyingAttributes(attributes, nodeName) {
+    const value = nodeName === 'OPTION' ? attributes['value'] : undefined;
     return {
         ...(attributes['id'] && { id: attributes['id'] }),
         ...(attributes['name'] && { name: attributes['name'] }),
         ...(attributes['type'] && { type: attributes['type'] }),
+        ...(value !== undefined && { value }),
     };
 }
 /**
- * The text of one element as the page renders it ({@link ELEMENT_TEXT_JS}).
+ * The text of one element as the page renders it ({@link ELEMENT_TEXT_JS})
+ * and its form control state ({@link ELEMENT_STATE_JS}).
  *
  * @param ref - Node reference
- * @returns Element text, or empty when the node cannot be read
+ * @param full - Read all of a large container's text, not just its start
+ * @returns Element text and state, empty when the node cannot be read
  */
-async function elementText(ref) {
+async function elementTextAndState(ref, full) {
     const objectGroup = `bdg-text-${process.pid}-${++queryCount}`;
     const resolved = await callCDP('DOM.resolveNode', { ...ref, objectGroup });
     const objectId = resolved.data?.result?.object
         .objectId;
     if (!objectId)
-        return '';
+        return { text: '', state: {} };
     try {
         const response = await callCDP('Runtime.callFunctionOn', {
             objectId,
-            functionDeclaration: `function () { return (${ELEMENT_TEXT_JS})(this); }`,
+            functionDeclaration: `function (full) { return { text: (${ELEMENT_TEXT_JS})(this, full), state: (${ELEMENT_STATE_JS})(this) }; }`,
+            arguments: [{ value: full }],
             returnByValue: true,
         });
-        const value = response.data?.result?.result
-            ?.value;
-        return typeof value === 'string' ? value : '';
+        const value = response.data?.result?.result?.value;
+        return {
+            text: typeof value?.text === 'string' ? value.text : '',
+            state: value?.state ?? {},
+        };
     }
     finally {
         await callCDP('Runtime.releaseObjectGroup', { objectGroup });
     }
 }
 /**
- * Get DOM context (tag, classes, text preview) for a node.
+ * 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
+ * is longer (all of it with `full`).
  *
  * @param ref - Node reference
+ * @param options - `full`: the whole text instead of its first 500 characters
  * @returns DOM context, or null if the node does not exist
  */
-export async function getDomContext(ref) {
+export async function getDomContext(ref, options = {}) {
     await callCDP('DOM.enable', {});
     const desc = await describeNode(ref);
     if (!desc) {
         log.debug(`No DOM context for ${JSON.stringify(ref)}`);
         return null;
     }
-    const classes = unpackAttributes(desc.attributes)['class']?.split(/\s+/).filter(Boolean);
-    const preview = textPreview(await elementText(ref));
+    const full = options.full === true;
+    const attributes = unpackAttributes(desc.attributes);
+    const classes = attributes['class']?.split(/\s+/).filter(Boolean);
+    const { text, state } = await elementTextAndState(ref, full);
+    const preview = textPreview(text);
+    const longer = textPreview(text, full ? Number.POSITIVE_INFINITY : ELEMENT_TEXT_LENGTH);
+    const tag = desc.nodeName.toLowerCase();
+    const keys = keyAttributes(tag, attributes, state);
     return {
-        tag: desc.nodeName.toLowerCase(),
+        tag,
         ...(classes && classes.length > 0 && { classes }),
+        ...(keys && { attributes: keys }),
+        ...(state.sensitive && { sensitive: true }),
         ...(preview && { preview }),
+        ...(longer !== preview && { text: longer }),
+        ...(!preview && (await childElements(ref))),
+    };
+}
+/** Child elements named for an element without text */
+const CHILDREN_LISTED = 5;
+/**
+ * The child elements of an element (for one without text: a body holding
+ * only an iframe, an empty app root).
+ *
+ * @param ref - Node reference
+ * @returns The first {@link CHILDREN_LISTED} as `tag#id.class` and how many there are
+ */
+async function childElements(ref) {
+    const response = await callCDP('DOM.describeNode', { ...ref, depth: 1 });
+    const node = response.data?.result?.node;
+    const elements = (node?.children ?? []).filter((child) => child.nodeType === 1);
+    return {
+        children: elements.slice(0, CHILDREN_LISTED).map(childLabel),
+        childCount: elements.length,
     };
 }
+/**
+ * A child element in a few characters.
+ *
+ * @param node - Child node
+ * @returns e.g. `iframe#app.full`
+ */
+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('')}`;
+}
+/**
+ * All matches of a selector.
+ *
+ * @param selector - CSS selector
+ * @returns Backend node ids of the matches (at least one)
+ * @throws CommandError (83) when nothing matches
+ */
+async function selectMatches(selector) {
+    const backendNodeIds = await selectAll(selector);
+    if (backendNodeIds.length > 0)
+        return backendNodeIds;
+    const err = await noMatchesError(selector);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+}
+/**
+ * One match of a selector.
+ *
+ * @param selector - CSS selector
+ * @param index - Which match (0-based)
+ * @returns Its backend node id
+ * @throws CommandError (83) when nothing matches, (81) for an index beyond the matches
+ */
+export async function selectMatch(selector, index = 0) {
+    const backendNodeIds = await selectMatches(selector);
+    const backendNodeId = backendNodeIds[index];
+    if (backendNodeId !== undefined)
+        return backendNodeId;
+    const err = indexOutOfRangeError(index, backendNodeIds.length - 1);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
 /**
  * Pick the nodes `dom get --raw` should report for a selector.
  *
@@ -330,20 +544,10 @@ export async function getDomContext(ref) {
  * @returns Node references to describe
  */
 async function selectForGet(selector, options) {
-    const backendNodeIds = await selectAll(selector);
-    if (backendNodeIds.length === 0) {
-        const err = noNodesFoundError(selector);
-        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
-    }
-    if (options.all)
-        return backendNodeIds.map((backendNodeId) => ({ backendNodeId }));
-    const position = options.nth ?? 0;
-    const backendNodeId = backendNodeIds[position];
-    if (backendNodeId === undefined) {
-        const err = indexOutOfRangeError(position, backendNodeIds.length - 1);
-        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    if (options.all) {
+        return (await selectMatches(selector)).map((backendNodeId) => ({ backendNodeId }));
     }
-    return [{ backendNodeId }];
+    return [{ backendNodeId: await selectMatch(selector, options.nth ?? 0) }];
 }
 /**
  * Get full details (attributes, outer HTML) for `bdg dom get --raw`.
@@ -366,7 +570,7 @@ export async function getDOMElements(options) {
         refs = await selectForGet(options.selector, options);
     }
     else {
-        const err = eitherArgumentRequiredError('selector', 'nodeId', 'bdg dom get <selector> or bdg dom get --node-id <id>');
+        const err = eitherArgumentRequiredError('selector', 'nodeId', `${sessionCommand('bdg dom get <selector>')} or ${sessionCommand('bdg dom get --node-id <id>')}`);
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
     }
     const nodes = await mapConcurrently(refs, async (ref) => {
@@ -398,7 +602,7 @@ export async function getDOMElements(options) {
 export async function resolveSelector(selector) {
     const backendNodeId = (await selectAll(selector))[0];
     if (backendNodeId === undefined) {
-        const err = noNodesFoundError(selector);
+        const err = await noMatchesError(selector);
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
     return { backendNodeId };
@@ -412,16 +616,6 @@ export async function resolveSelector(selector) {
 export async function resolveBackendNodeIds(selectors) {
     return mapConcurrently(selectors, async (selector) => (await selectAll(selector))[0]);
 }
-/**
- * Accessibility node of the first element matching a selector.
- *
- * @param selector - CSS selector
- * @returns A11y node, or null when nothing matches or the node is not exposed
- */
-export async function resolveA11yNodeForSelector(selector) {
-    const [backendNodeId] = await resolveBackendNodeIds([selector]);
-    return backendNodeId === undefined ? null : resolveA11yNode({ backendNodeId });
-}
 /**
  * Check that a cached element is still part of the current page.
  *
@@ -431,10 +625,10 @@ export async function resolveA11yNodeForSelector(selector) {
  * false for removed elements.
  *
  * @param backendNodeId - Backend node id from the query cache
- * @param index - Index the user gave, for the error message
+ * @param source - Index the user gave and the list it refers to, for the error message
  * @throws CommandError (87) when the element is gone
  */
-export async function assertNodeAttached(backendNodeId, index) {
+export async function assertNodeAttached(backendNodeId, source) {
     const resolved = await callCDP('DOM.resolveNode', { backendNodeId, objectGroup: 'bdg-check' });
     const objectId = resolved.data?.result?.object
         .objectId;
@@ -450,7 +644,7 @@ export async function assertNodeAttached(backendNodeId, index) {
         await callCDP('Runtime.releaseObjectGroup', { objectGroup: 'bdg-check' });
     }
     if (!attached) {
-        const err = staleNodeError(index);
+        const err = staleNodeError(source?.index, source);
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
     }
 }

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

@@ -4,6 +4,7 @@
  * Captures the common flow: resolve selector/index → call IPC → normalize errors.
  * Keeps individual command handlers focused on option wiring and output formatting.
  */
+import type { IndexSource } from '../../../types.js';
 interface IpcResponse<T> {
     status: string;
     data?: T;
@@ -16,6 +17,8 @@ interface ResultPayload {
     error?: string | undefined;
     suggestion?: string | undefined;
     exitCode?: number | undefined;
+    /** The element is not one the command acts on (fill, submit) */
+    unsuitableElement?: boolean | undefined;
 }
 interface CommandResult<T> {
     success: boolean;
@@ -42,6 +45,8 @@ export interface ElementCommandOptions<Req, Res extends ResultPayload> {
     }) => Req;
     /** Invoke the IPC client function. */
     call: (req: Req) => Promise<IpcResponse<Res>>;
+    /** `bdg dom` subcommand being run, e.g. "fill" (for suggestions). */
+    command: string;
     /** Operation label used in fallback error messages (e.g. "fill element"). */
     action: string;
     /** Fallback suggestion when the result reports failure without one. */
@@ -49,8 +54,11 @@ export interface ElementCommandOptions<Req, Res extends ResultPayload> {
 }
 /**
  * Resolve an element target, invoke the IPC call, and normalize failures
- * into the structured `CommandRunner` result shape.
+ * into the structured `CommandRunner` result shape. A numeric index names the
+ * list it refers to (`indexSource` in the data, and in errors).
  */
-export declare function runElementCommand<Req, Res extends ResultPayload>(options: ElementCommandOptions<Req, Res>): Promise<CommandResult<Omit<Res, 'success'>>>;
+export declare function runElementCommand<Req, Res extends ResultPayload>(options: ElementCommandOptions<Req, Res>): Promise<CommandResult<Omit<Res, 'success'> & {
+    indexSource?: IndexSource;
+}>>;
 export {};
 //# sourceMappingURL=runElementCommand.d.ts.map