browser-debugger-cli 0.8.0 → 0.10.0

package/dist/commands/dom/formSummary.js

@@ -0,0 +1,180 @@
+/**
+ * Readiness of a discovered form (`bdg dom form`): which fields are filled,
+ * which required ones are still empty, and which button submits it.
+ */
+import { REQUIRED_FIELD_EMPTY_REASON } from '../../ui/messages/commands.js';
+/**
+ * Button labels that leave or clear a form instead of submitting it (English,
+ * German, French, Spanish, Italian and Polish cancel/back words)
+ */
+const DISMISSIVE_BUTTON_LABEL = /^(cancel|reset|back|go back|previous|prev|close|clear|discard|delete|remove|abbrechen|zurück|annuler|retour|cancelar|volver|annulla|indietro|anuluj|wstecz)\b/iu;
+/**
+ * Fields a user fills as one: the options of a radio or checkbox group (same
+ * name in the same form), or a single field.
+ *
+ * @param fields - Form fields
+ * @returns Groups, in the order their first field appears
+ */
+export function groupFields(fields) {
+    const groups = new Map();
+    for (const field of fields) {
+        const type = (field.inputType ?? field.type).toLowerCase();
+        const choice = (type === 'radio' || type === 'checkbox') && field.name;
+        const key = choice ? `${field.formIndex}:${type}:${field.name}` : `#${field.index}`;
+        groups.set(key, [...(groups.get(key) ?? []), field]);
+    }
+    return [...groups.values()];
+}
+/**
+ * Whether a field has a value (a checked option for radios and checkboxes).
+ *
+ * @param field - Form field
+ * @returns True when filled or checked
+ */
+function isFilled(field) {
+    return field.state === 'filled' || field.state === 'checked';
+}
+/**
+ * Label of a field group: the group's name (legend, radiogroup label, name)
+ * for several options, the field's own label otherwise.
+ *
+ * @param group - Fields of one group (at least one)
+ * @returns Label
+ */
+function groupLabel(group) {
+    const [first] = group;
+    return group.length > 1 ? (first.groupLabel ?? first.label) : first.label;
+}
+/**
+ * What keeps a form from being submitted: required groups left empty,
+ * invalid fields, a disabled submit button.
+ *
+ * @param groups - Field groups of the editable, visible fields
+ * @param buttons - Form buttons
+ * @returns Blockers, required fields first
+ */
+function findBlockers(groups, buttons) {
+    const blockers = [];
+    for (const group of groups) {
+        const first = group[0];
+        if (group.some((field) => field.required) && !group.some(isFilled)) {
+            blockers.push({
+                index: first.index,
+                label: groupLabel(group),
+                reason: REQUIRED_FIELD_EMPTY_REASON,
+                command: first.command,
+            });
+            continue;
+        }
+        const invalid = group.find((field) => !field.validation.valid);
+        if (invalid) {
+            blockers.push({
+                index: invalid.index,
+                label: invalid.label,
+                reason: invalid.validation.message ?? 'Validation failed',
+                command: invalid.command,
+            });
+        }
+    }
+    const submitButton = buttons.find((b) => b.type === 'submit' && b.primary);
+    if (submitButton && !submitButton.enabled) {
+        blockers.push({
+            index: submitButton.index,
+            label: submitButton.label,
+            reason: submitButton.disabledReason ?? 'Submit button is disabled',
+            command: submitButton.command,
+        });
+    }
+    return blockers;
+}
+/**
+ * Summarize a form's state. Only visible, editable fields count, and a radio
+ * or checkbox group counts once (filled when any option is checked; required
+ * when any option is). The form is ready when nothing blocks it and at least
+ * one field is filled (an untouched form is not ready), or it has no fields.
+ *
+ * @param fields - Form fields
+ * @param buttons - Form buttons
+ * @returns Form summary
+ */
+export function calculateSummary(fields, buttons) {
+    const editable = fields.filter((f) => !f.hidden && !f.disabled && !f.readOnly);
+    const groups = groupFields(editable);
+    const filled = groups.filter((group) => group.some(isFilled));
+    const empty = groups.filter((group) => !group.some(isFilled));
+    const required = groups.filter((group) => group.some((field) => field.required));
+    const requiredRemaining = required.filter((group) => !group.some(isFilled)).length;
+    const invalid = groups.filter((group) => group.some((field) => !field.validation.valid)).length;
+    const blockers = findBlockers(groups, buttons);
+    return {
+        totalFields: groups.length,
+        filledFields: filled.length,
+        emptyFields: empty.length,
+        validFields: groups.length - invalid,
+        invalidFields: invalid,
+        requiredTotal: required.length,
+        requiredFilled: required.length - requiredRemaining,
+        requiredRemaining,
+        emptyFieldLabels: empty.map(groupLabel),
+        readyToSubmit: blockers.length === 0 && (filled.length > 0 || groups.length === 0),
+        blockers,
+    };
+}
+/**
+ * The button that submits the form, as a user would pick it. Buttons that
+ * cancel, reset, go back or delete ({@link DISMISSIVE_BUTTON_LABEL}) never
+ * are. Then, in order: a button written as a submit button
+ * (`type="submit"`, `<input type=submit>`); among the form's untyped
+ * `<button>`s (each submits it) one styled as primary, else the last one
+ * (forms put Cancel or Back first); else any button styled as primary.
+ * Buttons outside a form submit nothing, so only their style counts.
+ *
+ * @param buttons - Raw buttons of one form
+ * @returns Index of the primary button, or undefined when there is none
+ */
+export function primaryButtonIndex(buttons) {
+    const candidates = buttons.filter((button) => button.type !== 'reset' && !DISMISSIVE_BUTTON_LABEL.test(button.label.trim()));
+    const formDefaults = candidates.filter((button) => button.formDefault);
+    const primary = candidates.find((button) => button.explicitSubmit) ??
+        formDefaults.find((button) => button.primaryClass) ??
+        formDefaults.at(-1) ??
+        candidates.find((button) => button.primaryClass);
+    return primary?.index;
+}
+/**
+ * Where a form is listed: shown in an open dialog first (what the user is
+ * looking at), then other visible forms, then hidden ones.
+ *
+ * @param form - Raw form
+ * @returns Rank, lower first
+ */
+function visibilityRank(form) {
+    if (form.hidden)
+        return 2;
+    return form.inDialog ? 0 : 1;
+}
+/**
+ * Put forms in listing order (by {@link visibilityRank}, then by relevance)
+ * and number them, their fields and their buttons in that order, so the
+ * first field listed is 0 and `bdg dom fill <index>` / `click <index>` reach
+ * the element listed with that index (the indices are cached in this order).
+ * Within a form, fields come before buttons, both in document order.
+ *
+ * @param forms - Raw forms in document order
+ * @returns Forms in listing order, renumbered (the input is not changed)
+ */
+export function orderForms(forms) {
+    const ordered = forms
+        .map((form, position) => ({ form, position }))
+        .sort((a, b) => visibilityRank(a.form) - visibilityRank(b.form) ||
+        b.form.relevanceScore - a.form.relevanceScore ||
+        a.position - b.position);
+    let next = 0;
+    return ordered.map(({ form }, formIndex) => ({
+        ...form,
+        index: formIndex,
+        fields: form.fields.map((field) => ({ ...field, index: next++, formIndex })),
+        buttons: form.buttons.map((button) => ({ ...button, index: next++ })),
+    }));
+}
+//# sourceMappingURL=formSummary.js.map

package/dist/commands/dom/frames.d.ts

@@ -6,7 +6,8 @@
  */
 import type { DomFramesCommandOptions } from '../shared/optionTypes.js';
 /**
- * Handle `bdg dom frames`.
+ * Handle `bdg dom frames`. The list of a page still loading says it may be
+ * incomplete (`readyState` in the data): its iframes may not exist yet.
  */
 export declare function handleDomFrames(options: DomFramesCommandOptions): Promise<void>;
 //# sourceMappingURL=frames.d.ts.map

package/dist/commands/dom/frames.js

@@ -4,12 +4,14 @@
  * CLI-side handler. Frames are discovered in the daemon via the `dom_frames`
  * IPC command, out-of-process (cross-site) ones included.
  */
+import { documentReadyState } from './helpers/query.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { domFrames } from '../../ipc/client.js';
 import { formatDomFrames } from '../../ui/formatters/dom.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /**
- * Handle `bdg dom frames`.
+ * Handle `bdg dom frames`. The list of a page still loading says it may be
+ * incomplete (`readyState` in the data): its iframes may not exist yet.
  */
 export async function handleDomFrames(options) {
     await runCommand(async () => {
@@ -22,7 +24,20 @@ export async function handleDomFrames(options) {
                 ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
             };
         }
-        return { success: true, data: { frames: response.data.frames } };
+        return { success: true, data: await withReadyState(response.data.frames) };
     }, options, formatDomFrames);
 }
+/**
+ * The frames, with the page's `readyState` while it is still loading (one
+ * page evaluation).
+ *
+ * @param frames - Frames of the page
+ * @returns Frames, and `readyState` unless the page has loaded (or did not answer)
+ */
+async function withReadyState(frames) {
+    const readyState = await documentReadyState();
+    return readyState === undefined || readyState === 'complete'
+        ? { frames }
+        : { frames, readyState };
+}
 //# sourceMappingURL=frames.js.map

package/dist/commands/dom/get.d.ts

@@ -6,14 +6,15 @@
  * - Raw: full HTML, attributes, and classes
  */
 import type { DomGetCommandOptions } from '../shared/optionTypes.js';
+/** What `bdg dom get` reads without a selector */
+export declare const DOM_GET_DEFAULT_SELECTOR = "body";
 /**
- * Handle `bdg dom get [selectorOrIndex] [--node-id <id>]`.
+ * Handle `bdg dom get [selectorOrIndex] [--index <n>] [--node-id <id>]`.
  *
- * `--node-id` reads that node directly (raw output); otherwise dispatches to
- * the selector or index handler based on whether the argument parses as a
- * numeric index.
+ * `--node-id` reads that node directly (raw output); otherwise reads a cached
+ * index or a selector's match (`body` without an argument).
  *
- * @param selectorOrIndex - CSS selector or cached index (optional with --node-id)
+ * @param selectorOrIndex - CSS selector or cached index (default: body)
  * @param options - Command options
  */
 export declare function handleDomGet(selectorOrIndex: string | undefined, options: DomGetCommandOptions): Promise<void>;

package/dist/commands/dom/get.js

@@ -6,86 +6,93 @@
  * - Raw: full HTML, attributes, and classes
  */
 import { DomElementResolver } from './DomElementResolver.js';
-import { getDOMElements, getDomContext, resolveA11yNodeForSelector, } from './helpers/index.js';
-import { formatSemanticNodeWithContext, queryDomContextBySelector, resolveNodeWithFallback, } from './semanticUtils.js';
+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 { elementAtIndexNotFoundError, conflictingOptionsMessage, optionRequiresMessage, missingArgumentError, noNodesFoundError, } from '../../errors/messages.js';
+import { conflictingOptionsMessage, indexWithIndexOptionError, nodeIdNotFoundError, optionRequiresMessage, } 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';
-async function handleIndexGetRaw(index, options) {
-    const resolver = DomElementResolver.getInstance();
-    await runCommand(async () => {
-        const targetNode = await resolver.getNodeIdForIndex(index);
-        const getOptions = filterDefined({ nodeId: targetNode.nodeId });
-        const result = await getDOMElements(getOptions);
-        return { success: true, data: result };
-    }, options, formatDomGet);
-}
-async function handleIndexGetSemantic(index, options) {
+/** What `bdg dom get` reads without a selector */
+export const DOM_GET_DEFAULT_SELECTOR = 'body';
+/**
+ * The element to read: a cached index or a selector match.
+ *
+ * @param selectorOrIndex - CSS selector or cached index
+ * @param index - Which match of the selector (0-based)
+ * @returns Backend node id
+ * @throws CommandError (83) no match, (81) index out of range, (87) stale cached index
+ */
+async function targetNodeId(selectorOrIndex, index) {
     const resolver = DomElementResolver.getInstance();
-    await runCommand(async () => {
-        const targetNode = await resolver.getNodeIdForIndex(index);
-        const ref = { backendNodeId: targetNode.nodeId };
-        const [a11yNode, domContext] = await Promise.all([resolveA11yNode(ref), getDomContext(ref)]);
-        const node = resolveNodeWithFallback(a11yNode, domContext, targetNode.nodeId);
-        if (!node) {
-            const err = elementAtIndexNotFoundError(index, 'cached query');
-            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
-        }
-        return { success: true, data: { node, domContext } };
-    }, options, formatSemanticNodeWithContext);
-}
-async function handleIndexGet(index, options) {
-    if (options.raw) {
-        await handleIndexGetRaw(index, options);
+    if (resolver.isNumericIndex(selectorOrIndex)) {
+        return (await resolver.getNodeIdForIndex(Number(selectorOrIndex))).nodeId;
     }
-    else {
-        await handleIndexGetSemantic(index, options);
+    return selectMatch(selectorOrIndex, index ?? 0);
+}
+/**
+ * Semantic view of one element: its accessibility node (or one inferred from
+ * the DOM) and its DOM context.
+ *
+ * @param backendNodeId - The element
+ * @param full - All of its text instead of the first 500 characters
+ * @returns Node and context
+ * @throws CommandError (83) when the element is gone
+ */
+async function semanticElement(backendNodeId, full) {
+    const ref = { backendNodeId };
+    const [a11yNode, domContext] = await Promise.all([
+        resolveA11yNode(ref),
+        getDomContext(ref, { full }),
+    ]);
+    const node = resolveNodeWithFallback(a11yNode, domContext, backendNodeId);
+    if (!node) {
+        const err = nodeIdNotFoundError(backendNodeId);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
+    return { node, domContext };
 }
-async function handleSelectorGetRaw(selector, options) {
+/**
+ * Raw view: the element(s) with attributes and outer HTML.
+ *
+ * @param selectorOrIndex - CSS selector or cached index
+ * @param options - Command options (`--all`, `--index`)
+ */
+async function handleRawGet(selectorOrIndex, options) {
     await runCommand(async () => {
-        const getOptions = filterDefined({
-            selector,
-            all: options.all,
-            nth: options.nth,
-        });
-        const result = await getDOMElements(getOptions);
-        return { success: true, data: result };
+        const resolver = DomElementResolver.getInstance();
+        const getOptions = resolver.isNumericIndex(selectorOrIndex)
+            ? { nodeId: (await resolver.getNodeIdForIndex(Number(selectorOrIndex))).nodeId }
+            : filterDefined({
+                selector: selectorOrIndex,
+                all: options.all,
+                nth: matchIndex(options),
+            });
+        return { success: true, data: await getDOMElements(getOptions) };
     }, options, formatDomGet);
 }
-async function handleSelectorGetSemantic(selector, options) {
+/**
+ * Semantic view of the target.
+ *
+ * @param selectorOrIndex - CSS selector or cached index
+ * @param options - Command options (`--index`, `--full`)
+ */
+async function handleSemanticGet(selectorOrIndex, options) {
     await runCommand(async () => {
-        const a11yNode = await resolveA11yNodeForSelector(selector);
-        let domContext = null;
-        let nodeId;
-        if (a11yNode?.backendDOMNodeId) {
-            nodeId = a11yNode.backendDOMNodeId;
-            domContext = await getDomContext({ backendNodeId: nodeId });
-        }
-        else if (!a11yNode) {
-            const queryResult = await queryDomContextBySelector(selector);
-            nodeId = queryResult.nodeId;
-            domContext = queryResult.domContext;
-        }
-        const node = resolveNodeWithFallback(a11yNode, domContext, nodeId);
-        if (!node) {
-            const err = noNodesFoundError(selector);
-            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
-        }
-        return { success: true, data: { node, domContext } };
+        const backendNodeId = await targetNodeId(selectorOrIndex, matchIndex(options));
+        return { success: true, data: await semanticElement(backendNodeId, options.full === true) };
     }, options, formatSemanticNodeWithContext);
 }
-async function handleSelectorGet(selector, options) {
-    if (options.raw) {
-        await handleSelectorGetRaw(selector, options);
-    }
-    else {
-        await handleSelectorGetSemantic(selector, options);
-    }
+/**
+ * Which match of the selector to read: `--index`, or its alias `--nth`.
+ *
+ * @param options - Command options
+ * @returns 0-based index, undefined for the first match
+ */
+function matchIndex(options) {
+    return options.index ?? options.nth;
 }
 /**
  * Options of `dom get` that cannot be combined (one would be ignored).
@@ -98,22 +105,26 @@ function getOptionsConflict(selectorOrIndex, options) {
     if (options.nodeId !== undefined && selectorOrIndex !== undefined) {
         return conflictingOptionsMessage('--node-id', 'a selector or index');
     }
-    if (options.all && options.nth !== undefined) {
-        return conflictingOptionsMessage('--all', '--nth');
+    if (options.full && (options.raw || options.nodeId !== undefined)) {
+        return conflictingOptionsMessage('--full', options.raw ? '--raw' : '--node-id');
     }
-    if (!options.raw && (options.all || options.nth !== undefined)) {
-        return optionRequiresMessage(options.all ? '--all' : '--nth', '--raw');
+    if (options.index !== undefined && options.nth !== undefined) {
+        return conflictingOptionsMessage('--index', '--nth');
     }
+    if (options.all && matchIndex(options) !== undefined) {
+        return conflictingOptionsMessage('--all', '--index');
+    }
+    if (options.all && !options.raw)
+        return optionRequiresMessage('--all', '--raw');
     return null;
 }
 /**
- * Handle `bdg dom get [selectorOrIndex] [--node-id <id>]`.
+ * Handle `bdg dom get [selectorOrIndex] [--index <n>] [--node-id <id>]`.
  *
- * `--node-id` reads that node directly (raw output); otherwise dispatches to
- * the selector or index handler based on whether the argument parses as a
- * numeric index.
+ * `--node-id` reads that node directly (raw output); otherwise reads a cached
+ * index or a selector's match (`body` without an argument).
  *
- * @param selectorOrIndex - CSS selector or cached index (optional with --node-id)
+ * @param selectorOrIndex - CSS selector or cached index (default: body)
  * @param options - Command options
  */
 export async function handleDomGet(selectorOrIndex, options) {
@@ -126,16 +137,15 @@ export async function handleDomGet(selectorOrIndex, options) {
         await runCommand(async () => ({ success: true, data: await getDOMElements({ nodeId }) }), options, formatDomGet);
         return;
     }
-    if (selectorOrIndex === undefined) {
-        const err = missingArgumentError('bdg dom get <selector|index> or bdg dom get --node-id <id>');
+    const target = selectorOrIndex ?? DOM_GET_DEFAULT_SELECTOR;
+    if (DomElementResolver.getInstance().isNumericIndex(target) &&
+        matchIndex(options) !== undefined) {
+        const err = indexWithIndexOptionError(target, 'get');
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
     }
-    const isNumericIndex = /^\d+$/.test(selectorOrIndex);
-    if (isNumericIndex) {
-        await handleIndexGet(parseInt(selectorOrIndex, 10), options);
-    }
-    else {
-        await handleSelectorGet(selectorOrIndex, options);
-    }
+    if (options.raw)
+        await handleRawGet(target, options);
+    else
+        await handleSemanticGet(target, options);
 }
 //# sourceMappingURL=get.js.map

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 { queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, resolveA11yNodeForSelector, assertNodeAttached, } from './query.js';
+export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, } 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 { queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, resolveA11yNodeForSelector, assertNodeAttached, } from './query.js';
+export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, } from './query.js';
 export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
 //# sourceMappingURL=index.js.map

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

@@ -9,15 +9,35 @@
  * bdg invocations. Selectors are matched in the page, including open shadow
  * roots and same-origin iframes, like a user sees the page.
  */
-import type { A11yNode, DomQueryResult, DomGetResult, DomGetOptions, DomContext, NodeRef } from '../../../types.js';
+import { type ErrorWithSuggestion, type NoMatchContext } from '../../../errors/messages.js';
+import type { DomQueryResult, DomGetResult, DomGetOptions, DomContext, IndexSource, NodeRef } from '../../../types.js';
 /**
- * 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).
+ * 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 text - Element text as the page renders it
- * @returns Collapsed text, truncated to {@link PREVIEW_LENGTH} characters
+ * @param selector - Selector as given
+ * @returns Message and suggestion
  */
-export declare function textPreview(text: string): string;
+export declare function noMatchesError(selector: string): Promise<ErrorWithSuggestion>;
+/**
+ * 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 declare function noMatchContext(selector: string): Promise<NoMatchContext>;
+/**
+ * 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 declare function documentReadyState(): Promise<string | undefined>;
 /**
  * Query elements by selector for `bdg dom query`.
  *
@@ -26,12 +46,26 @@ export declare function textPreview(text: string): string;
  */
 export declare function queryDOMElements(selector: string): Promise<DomQueryResult>;
 /**
- * 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 declare function getDomContext(ref: NodeRef): Promise<DomContext | null>;
+export declare function getDomContext(ref: NodeRef, options?: {
+    full?: boolean;
+}): Promise<DomContext | null>;
+/**
+ * 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 declare function selectMatch(selector: string, index?: number): Promise<number>;
 /**
  * Get full details (attributes, outer HTML) for `bdg dom get --raw`.
  *
@@ -55,13 +89,6 @@ export declare function resolveSelector(selector: string): Promise<NodeRef>;
  * @returns Backend node id per selector, or undefined when it matches nothing
  */
 export declare function resolveBackendNodeIds(selectors: string[]): Promise<(number | undefined)[]>;
-/**
- * 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 declare function resolveA11yNodeForSelector(selector: string): Promise<A11yNode | null>;
 /**
  * Check that a cached element is still part of the current page.
  *
@@ -71,8 +98,8 @@ export declare function resolveA11yNodeForSelector(selector: string): Promise<A1
  * 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 declare function assertNodeAttached(backendNodeId: number, index?: number): Promise<void>;
+export declare function assertNodeAttached(backendNodeId: number, source?: IndexSource): Promise<void>;
 //# sourceMappingURL=query.d.ts.map