browser-debugger-cli 0.9.0 → 0.10.0

package/README.md

@@ -59,6 +59,9 @@ bdg eval "document.title"          # Run JavaScript in the page (--frame for ifr
 bdg network list --preset errors   # Network requests, console: bdg console
 bdg dom listeners "#save"          # Which event listeners run for an element
 bdg dom layout "#save"             # Where it is, whether it is visible or covered
+bdg dom inspect "#save"            # What it looks like (Figma-like styles), no screenshot
+bdg dom inspect "#save" --why color   # Which CSS rule sets a value, and what it beats
+bdg page emulate --viewport 900x700   # Responsive check mid-session (or --color-scheme)
 bdg dom wait "#result" --visible   # Wait for an element instead of sleeping
 bdg example.com --session agent2 --viewport 1280x800   # A second, independent session
 bdg stop                           # End session
@@ -66,7 +69,7 @@ bdg stop                           # End session
 
 ## Current State
 
-**Raw CDP access is complete.** Every protocol method works now. High-level commands cover the common work: page navigation, DOM queries and interaction (click, fill, hover, keys, forms, shadow DOM and iframes), accessibility tree, screenshots, network requests and HAR export, console messages and event listeners. Actions report what they changed (navigation, new messages, requests, or no visible effect), and several named sessions can run side by side. See the [CLI reference](docs/CLI_REFERENCE.md) for every command, and `bdg --help --json` for the machine-readable version.
+**Raw CDP access is complete.** Every protocol method works now. High-level commands cover the common work: page navigation, DOM queries and interaction (click, fill, hover, keys, forms, shadow DOM and iframes), accessibility tree, screenshots, element styles with the CSS cascade (`dom inspect`: what an element looks like, which rule sets each value, and declarations that have no effect), network requests and HAR export, console messages and event listeners. Actions report what they changed (navigation, new messages, requests, or no visible effect), and several named sessions can run side by side. See the [CLI reference](docs/CLI_REFERENCE.md) for every command, and `bdg --help --json` for the machine-readable version.
 
 ## Agent Discovery Pattern
 

package/dist/commands/dom/a11y.js

@@ -10,6 +10,7 @@
  */
 import { DomElementResolver } from './DomElementResolver.js';
 import { getDomContext, resolveBackendNodeIds } from './helpers/index.js';
+import { withSecretMasked } from './semanticUtils.js';
 import { runCommand, runJsonCommand } from '../shared/CommandRunner.js';
 import { jsonOption } from '../shared/commonOptions.js';
 import { integerOption } from '../shared/validation.js';
@@ -164,7 +165,7 @@ async function handleA11yDescribe(selectorOrIndex, options) {
         if (domNodeId) {
             domContext = await getDomContext({ backendNodeId: domNodeId });
         }
-        return { node, domContext };
+        return { node: withSecretMasked(node, domContext), domContext };
     }
     if (options.json) {
         await runJsonCommand(fetchA11yNodeData);

package/dist/commands/dom/formInteraction.js

@@ -9,7 +9,7 @@
 import { InvalidArgumentError } from 'commander';
 import { runElementCommand } from './helpers/runElementCommand.js';
 import { runCommand } from '../shared/CommandRunner.js';
-import { jsonOption } from '../shared/commonOptions.js';
+import { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } from '../shared/commonOptions.js';
 import { integerOption } from '../shared/validation.js';
 import { CommandError } from '../../errors/index.js';
 import { VIA_LABEL_SUFFIX, conflictingOptionsMessage, indexSourceText, internalError, scrollOptionsError, } from '../../errors/messages.js';
@@ -17,9 +17,11 @@ import { domClick, domFill, domPressKey, domScroll, domSubmit } from '../../ipc/
 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, POINTER_ACTION_DONE, actionStatusLine, dialogConsoleText, newMessageText, pageNavigationText, } from '../../ui/messages/commands.js';
+import { CLICK_RESULT_WAIT_HELP, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, actionStatusLine, dialogConsoleText, 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 */
+const STRICT_OPTION_HELP = 'Fail (exit 90) instead of using DOM events when a real mouse cannot reach the element (covered, hidden, zero-size)';
 /**
  * Commander parser for `--modifiers`: rejects unknown names instead of
  * silently pressing the bare key.
@@ -54,7 +56,7 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('fill')
         .description('Fill a form field with a value (React-compatible, waits for stability)')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .argument('<value>', 'Value to fill (file inputs: paths separated by commas, "" 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)')
@@ -80,10 +82,11 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('click')
         .description('Click an element and wait for stability (accepts selector or index)')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .option('--double', 'Double-click')
         .option('--right', 'Right-click (opens the context menu)')
+        .option('--strict', STRICT_OPTION_HELP)
         .option('--no-wait', 'Skip waiting for network stability after click')
         .addOption(jsonOption())
         .addHelpText('after', CLICK_RESULT_WAIT_HELP)
@@ -94,8 +97,9 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('hover')
         .description('Move the mouse over an element (shows hover menus and tooltips)')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
+        .option('--strict', STRICT_OPTION_HELP)
         .option('--no-wait', 'Skip waiting for network stability after hovering')
         .addOption(jsonOption())
         .action(async (selectorOrIndex, options) => {
@@ -104,7 +108,7 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('submit')
         .description('Submit a form by clicking submit button and waiting for completion')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .option('--wait-navigation', 'Wait for page navigation after submit')
         .option('--wait-network <ms>', 'Wait for network idle after submit (milliseconds)', integerOption(0), 1000)
@@ -132,7 +136,7 @@ export function registerFormInteractionCommands(program) {
     domCommand
         .command('pressKey')
         .description('Press a key on an element (for Enter-to-submit, keyboard navigation)')
-        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .argument('<key>', 'Key to press (Enter, Tab, Escape, Space, ArrowUp, etc.)')
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .option('--times <n>', 'Press key multiple times (default: 1)', integerOption(1, 1000))
@@ -270,6 +274,7 @@ async function runPointerCommand(selectorOrIndex, options, action) {
                 ...target,
                 wait: options.wait !== false,
                 ...(action !== 'click' && { action }),
+                ...(options.strict && { strict: true }),
             }),
             call: domClick,
             command: action === 'hover' ? 'hover' : 'click',
@@ -279,34 +284,40 @@ async function runPointerCommand(selectorOrIndex, options, action) {
 }
 /**
  * Build an action's output: the status line ("✓ Element Clicked",
- * "⚠ Element Clicked (with warnings)" with the warning right below it, or
- * "⚠ Element Clicked (no visible effect: …)"), the details, what changed on
- * the page (`Page:` navigation, `New text:` messages), then the network
- * requests it triggered and the dialogs it caused. No request list is shown
- * when there were none (JSON has an empty `triggeredRequests` then).
+ * "⚠ Element Clicked (with warnings)" with the warning right below it,
+ * "⚠ Element Clicked (page still changing)" with what it was still working
+ * on, or "⚠ Element Clicked (no visible effect: …)"), the details, what
+ * changed on the page (`Page:` navigation, `New text:` messages, `Shown:`
+ * elements), then the network requests it triggered and the dialogs it
+ * caused. No request list is shown when there were none (JSON has an empty
+ * `triggeredRequests` then).
  *
  * @param done - What was done, e.g. "Element Clicked"
  * @param details - Label/value rows
  * @param result - Action result
- * @param keyWidth - Width of the labels
+ * @param options - Width of the labels; what the action is called in notes (e.g. "click")
  * @returns Output being built (more can be appended)
  */
-function formatActionOutput(done, details, result, keyWidth = 15) {
+function formatActionOutput(done, details, result, options = {}) {
+    const keyWidth = options.keyWidth ?? 15;
     const fmt = new OutputFormatter();
-    fmt.text(actionStatusLine(done, result.warning !== undefined, result.effect === 'none'));
+    const stillChanging = result.settled === false && result.pending !== undefined;
+    fmt.text(actionStatusLine(done, {
+        warned: result.warning !== undefined,
+        noEffect: result.effect === 'none',
+        stillChanging,
+    }));
     if (result.warning)
         fmt.text(`⚠ Warning: ${result.warning}`);
+    if (stillChanging && result.pending) {
+        fmt.text(`⚠ ${stillChangingNote(options.action ?? 'action', result.pending)}`);
+    }
     fmt.blank();
     fmt.keyValueList(details, keyWidth);
     if (result.navigation)
         fmt.keyValue('Page', pageNavigationText(result.navigation), keyWidth);
-    (result.messages ?? []).forEach((message, index) => {
-        const text = newMessageText(message);
-        if (index === 0)
-            fmt.keyValue('New text', text, keyWidth);
-        else
-            fmt.text(' '.repeat(keyWidth) + text);
-    });
+    listRows(fmt, 'New text', (result.messages ?? []).map(newMessageText), keyWidth);
+    listRows(fmt, 'Shown', (result.shown ?? []).map(shownElementText), keyWidth);
     const omitted = result.triggeredRequestsOmitted;
     const requests = formatTriggeredRequestLines(result.triggeredRequests ?? [], omitted);
     if (requests.length > 0) {
@@ -320,6 +331,23 @@ function formatActionOutput(done, details, result, keyWidth = 15) {
     }
     return fmt;
 }
+/**
+ * Rows of a list under one label: the label on the first row, the rest
+ * indented below it.
+ *
+ * @param fmt - Output being built
+ * @param label - Label, e.g. "New text"
+ * @param texts - One text per row
+ * @param keyWidth - Width of the labels
+ */
+function listRows(fmt, label, texts, keyWidth) {
+    texts.forEach((text, index) => {
+        if (index === 0)
+            fmt.keyValue(label, text, keyWidth);
+        else
+            fmt.text(' '.repeat(keyWidth) + text);
+    });
+}
 /**
  * Row naming the element an action hit, e.g.
  * `Element: input.toggle in div.view "Write report"` (just its tag when the
@@ -372,7 +400,7 @@ function formatClickOutput(result) {
         ...selectorRows(result),
         elementRow(result),
         ['Method', result.method === 'dom' ? 'DOM events' : 'mouse events'],
-    ], result).build();
+    ], result, { action: POINTER_ACTION_NOUN[result.action ?? 'click'] }).build();
 }
 /**
  * Format submit command output for human-readable display.
@@ -391,7 +419,10 @@ function formatSubmitOutput(result) {
         details.push(['Navigation', 'yes']);
     if (result.waitTimeMs !== undefined)
         details.push(['Wait Time', `${result.waitTimeMs}ms`]);
-    const fmt = formatActionOutput('Form Submitted', details, result, 20);
+    const fmt = formatActionOutput('Form Submitted', details, result, {
+        keyWidth: 20,
+        action: 'submit',
+    });
     fmt.hints('Next steps:', [
         `${sessionCommand('bdg network list --last 10').padEnd(32)} Check network requests`,
         `${sessionCommand('bdg console --last 5').padEnd(32)} Check console messages`,
@@ -412,7 +443,7 @@ function formatPressKeyOutput(result) {
         details.push(['Times', result.times.toString()]);
     if (result.modifiers?.length)
         details.push(['Modifiers', result.modifiers.join('+')]);
-    return formatActionOutput('Key Pressed', details, result).build();
+    return formatActionOutput('Key Pressed', details, result, { action: 'key press' }).build();
 }
 /**
  * Format scroll command output for human-readable display.

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

@@ -0,0 +1,20 @@
+/**
+ * The attributes that identify an element by its type (an image's `src`, a
+ * link's `href`, a field's name and value), shown by `dom query`, `dom get`
+ * and `dom a11y describe`.
+ */
+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
+ * (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.
+ *
+ * @param tag - Lower-case tag name
+ * @param attributes - Element attributes
+ * @param state - Live state read in the page (`ELEMENT_STATE_JS`)
+ * @returns Key attributes, or undefined for an element type without any
+ */
+export declare function keyAttributes(tag: string, attributes: Record<string, string>, state?: ElementState): KeyAttributes | undefined;
+//# sourceMappingURL=keyAttributes.d.ts.map

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

@@ -0,0 +1,54 @@
+/**
+ * The attributes that identify an element by its type (an image's `src`, a
+ * link's `href`, a field's name and value), shown by `dom query`, `dom get`
+ * and `dom a11y describe`.
+ */
+import { MASKED_VALUE } from '../../../runtime/dom/elementInfo.js';
+/** Attributes read for each element type (live state is added for form controls) */
+const ATTRIBUTES_BY_TAG = {
+    img: ['src', 'alt'],
+    a: ['href'],
+    input: ['name', 'placeholder'],
+    textarea: ['name', 'placeholder'],
+    button: ['name'],
+    select: ['name'],
+    iframe: ['src'],
+    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
+ * (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.
+ *
+ * @param tag - Lower-case tag name
+ * @param attributes - Element attributes
+ * @param state - Live state read in the page (`ELEMENT_STATE_JS`)
+ * @returns Key attributes, or undefined for an element type without any
+ */
+export function keyAttributes(tag, attributes, state = {}) {
+    const names = ATTRIBUTES_BY_TAG[tag];
+    if (!names)
+        return undefined;
+    const result = {};
+    const type = state.type ?? attributes['type'];
+    if (type)
+        result['type'] = type;
+    for (const name of names) {
+        const value = attributes[name];
+        if (value)
+            result[name] = value;
+    }
+    if (type === 'hidden')
+        return result;
+    const secret = state.sensitive === true || type === 'password';
+    if (state.value)
+        result['value'] = secret ? MASKED_VALUE : state.value;
+    if (state.checked !== undefined)
+        result['checked'] = state.checked;
+    if (state.selected)
+        result['selected'] = secret ? MASKED_VALUE : state.selected;
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+//# sourceMappingURL=keyAttributes.js.map

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

@@ -46,7 +46,7 @@ export declare function documentReadyState(): Promise<string | undefined>;
  */
 export declare function queryDOMElements(selector: string): Promise<DomQueryResult>;
 /**
- * Get DOM context (tag, classes, text preview) for a node: a one-line
+ * 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`).
  *

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

@@ -9,18 +9,19 @@
  * 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, operationFailedError, similarSelectorsLine, staleNodeError, } from '../../../errors/messages.js';
 import { callCDP } from '../../../ipc/client.js';
 import { ELEMENT_GEOMETRY_JS, VIEWPORT_SIZE_JS, classifyViewportPosition, } from '../../../runtime/dom/elementGeometry.js';
-import { ELEMENT_CONTEXT_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, } 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 { parseSelectorFilters, withoutVisibleFilters } from '../../../utils/selectorFilters.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. */
@@ -113,6 +114,34 @@ async function withSelection(selector, use) {
 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
@@ -131,9 +160,11 @@ export async function noMatchContext(selector) {
         ? `(() => { 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} })`,
+            expression: `({ hidden: ${hidden}, readyState: document.readyState, unsearched: ${UNSEARCHED_CONTENT_JS}, names: ${names}, shadowHost: ${shadowHost} })`,
             returnByValue: true,
         });
         const { result } = (evaluated.data?.result ?? {});
@@ -151,6 +182,8 @@ export async function noMatchContext(selector) {
                 },
             }),
             ...(similar && { similar }),
+            ...(typeof value.shadowHost === 'number' &&
+                compounds[value.shadowHost] && { shadowHost: compounds[value.shadowHost] }),
         };
     }
     catch (error) {
@@ -182,7 +215,8 @@ export async function documentReadyState() {
 const VIEWPORT_HINT_LIMIT = 100;
 /**
  * Where each element of a page-side array lives (an iframe and/or a shadow
- * root), its text and, for the first {@link VIEWPORT_HINT_LIMIT}, its position
+ * 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.
  */
@@ -190,9 +224,10 @@ const ELEMENT_DETAILS_FUNCTION = `function () {
   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), geometry: index < ${VIEWPORT_HINT_LIMIT} ? geometryOf(el) : null };
+      return { context: contextOf(el), text: textOf(el), state: stateOf(el), geometry: index < ${VIEWPORT_HINT_LIMIT} ? geometryOf(el) : null };
     } catch (e) {
       return {};
     }
@@ -219,6 +254,7 @@ async function elementsWithDetails(arrayObjectId) {
                 backendNodeId,
                 context: details?.context ?? '',
                 text: details?.text ?? '',
+                state: details?.state ?? {},
                 ...viewportHint(details?.geometry, viewport),
             },
         ];
@@ -334,18 +370,21 @@ export async function queryDOMElements(selector) {
         log.debug(`Querying ${elements.length} elements with selector: ${selector}`);
     }
     const nodes = await mapConcurrently(elements, async (element, index) => {
-        const { backendNodeId, context, text, inViewport, clippedBy } = element;
+        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(),
+            tag,
             ...identifyingAttributes(attributes, desc.nodeName),
+            ...(keys && { attributes: keys }),
             ...(classes && { classes }),
             ...(preview && { preview }),
             ...(context && { context }),
@@ -372,36 +411,39 @@ function identifyingAttributes(attributes, nodeName) {
     };
 }
 /**
- * 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
  * @param full - Read all of a large container's text, not just its start
- * @returns Element text, or empty when the node cannot be read
+ * @returns Element text and state, empty when the node cannot be read
  */
-async function elementText(ref, full) {
+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 (full) { return (${ELEMENT_TEXT_JS})(this, full); }`,
+            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: a one-line
+ * 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`).
  *
@@ -417,13 +459,18 @@ export async function getDomContext(ref, options = {}) {
         return null;
     }
     const full = options.full === true;
-    const classes = unpackAttributes(desc.attributes)['class']?.split(/\s+/).filter(Boolean);
-    const text = await elementText(ref, full);
+    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))),

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

@@ -6,7 +6,7 @@
  */
 import { DomElementResolver } from '../DomElementResolver.js';
 import { noMatchContext } from './query.js';
-import { otherIndexSourceNote, staleNodeError, unreachableElementsNote, withLoadingHint, } from '../../../errors/messages.js';
+import { otherIndexSourceNote, staleNodeError, shadowBoundaryLine, unreachableElementsNote, withLoadingHint, } from '../../../errors/messages.js';
 import { joinLines } from '../../../ui/formatting.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
 /**
@@ -110,7 +110,8 @@ function failedResultFailure(result, options) {
 }
 /**
  * Add what the page says to a "not found" failure (one page evaluation, on
- * this failure path only, {@link noMatchContext}): similar ids or classes,
+ * this failure path only, {@link noMatchContext}): similar ids or classes, a
+ * shadow host the selector tries to cross,
  * the places selectors do not search (for a page script that found nothing)
  * and the still-loading hint while the page loads.
  *
@@ -124,7 +125,7 @@ async function withNotFoundContext(failure, selector, searched) {
         return failure;
     const context = await noMatchContext(selector);
     const note = searched ? unreachableElementsNote(selector, context.unsearched) : '';
-    const suggestion = withLoadingHint(joinLines(context.similar, failure.errorContext?.suggestion, note ? note : undefined), context.readyState, selector);
+    const suggestion = withLoadingHint(joinLines(context.similar, context.shadowHost && shadowBoundaryLine(context.shadowHost), failure.errorContext?.suggestion, note ? note : undefined), context.readyState, selector);
     return suggestion ? { ...failure, errorContext: { suggestion } } : failure;
 }
 //# sourceMappingURL=runElementCommand.js.map