browser-debugger-cli 0.8.0 → 0.9.0

package/dist/commands/dom/formInteraction.js

@@ -7,17 +7,18 @@
  * subscriptions for network-stability waits) on behalf of the CLI.
  */
 import { InvalidArgumentError } from 'commander';
-import { DomElementResolver } from './DomElementResolver.js';
 import { runElementCommand } from './helpers/runElementCommand.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { jsonOption } from '../shared/commonOptions.js';
 import { integerOption } from '../shared/validation.js';
 import { CommandError } from '../../errors/index.js';
-import { conflictingOptionsMessage, internalError, scrollOptionsError } from '../../errors/messages.js';
+import { VIA_LABEL_SUFFIX, conflictingOptionsMessage, indexSourceText, internalError, scrollOptionsError, } from '../../errors/messages.js';
 import { domClick, domFill, domPressKey, domScroll, domSubmit } from '../../ipc/client.js';
 import { findUnknownModifiers } from '../../runtime/dom/keyMapping.js';
+import { formatTriggeredRequestLines, formatTriggeredRequestsTitle, } from '../../ui/formatters/triggeredRequests.js';
 import { OutputFormatter } from '../../ui/formatting.js';
-import { POINTER_ACTION_DONE, dialogConsoleText } from '../../ui/messages/commands.js';
+import { CLICK_RESULT_WAIT_HELP, POINTER_ACTION_DONE, actionStatusLine, dialogConsoleText, newMessageText, pageNavigationText, } from '../../ui/messages/commands.js';
+import { sessionCommand } from '../../ui/messages/sessionCommand.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /**
  * Commander parser for `--modifiers`: rejects unknown names instead of
@@ -71,6 +72,7 @@ export function registerFormInteractionCommands(program) {
                 wait: options.wait !== false,
             }),
             call: domFill,
+            command: 'fill',
             action: 'fill element',
             failureSuggestion: 'Verify the selector matches a fillable element (input, textarea, select)',
         }), options, formatFillOutput);
@@ -84,6 +86,7 @@ export function registerFormInteractionCommands(program) {
         .option('--right', 'Right-click (opens the context menu)')
         .option('--no-wait', 'Skip waiting for network stability after click')
         .addOption(jsonOption())
+        .addHelpText('after', CLICK_RESULT_WAIT_HELP)
         .action(async (selectorOrIndex, options) => {
         const action = options.double ? 'double' : options.right ? 'right' : 'click';
         await runPointerCommand(selectorOrIndex, options, action);
@@ -107,6 +110,7 @@ export function registerFormInteractionCommands(program) {
         .option('--wait-network <ms>', 'Wait for network idle after submit (milliseconds)', integerOption(0), 1000)
         .option('--timeout <ms>', 'Maximum time to wait (milliseconds)', integerOption(1), 10000)
         .addOption(jsonOption())
+        .addHelpText('after', CLICK_RESULT_WAIT_HELP)
         .action(async (selectorOrIndex, options) => {
         await runCommand(() => runElementCommand({
             selectorOrIndex,
@@ -120,6 +124,7 @@ export function registerFormInteractionCommands(program) {
                 timeout: options.timeout,
             }),
             call: domSubmit,
+            command: 'submit',
             action: 'submit form',
             failureSuggestion: 'Verify the selector matches a form or submit button',
         }), options, formatSubmitOutput);
@@ -146,6 +151,7 @@ export function registerFormInteractionCommands(program) {
                 wait: options.wait !== false,
             }),
             call: domPressKey,
+            command: 'pressKey',
             action: 'press key',
             failureSuggestion: 'Verify the selector matches a focusable element',
         }), options, formatPressKeyOutput);
@@ -164,64 +170,62 @@ export function registerFormInteractionCommands(program) {
         .option('--no-wait', 'Skip waiting for lazy-loaded content after scroll')
         .addOption(jsonOption())
         .action(async (selector, options) => {
-        await runCommand(async () => {
-            const problem = scrollOptionsProblem(selector, options);
-            if (problem) {
-                const err = scrollOptionsError(problem);
-                return {
-                    success: false,
-                    error: err.message,
-                    exitCode: EXIT_CODES.INVALID_ARGUMENTS,
-                    errorContext: { suggestion: err.suggestion },
-                };
-            }
-            const target = selector
-                ? await DomElementResolver.getInstance().resolve(selector, options.index)
-                : undefined;
-            if (target && !target.success) {
-                return {
-                    success: false,
-                    error: target.error,
-                    exitCode: target.exitCode,
-                    ...(target.suggestion && { errorContext: { suggestion: target.suggestion } }),
-                };
-            }
-            const response = await domScroll({
-                ...(target && { selector: target.selector }),
-                ...(target?.index !== undefined && { index: target.index }),
-                ...(target?.backendNodeId !== undefined && { backendNodeId: target.backendNodeId }),
-                ...(options.down !== undefined && { down: options.down }),
-                ...(options.up !== undefined && { up: options.up }),
-                ...(options.left !== undefined && { left: options.left }),
-                ...(options.right !== undefined && { right: options.right }),
-                ...(options.top !== undefined && { top: options.top }),
-                ...(options.bottom !== undefined && { bottom: options.bottom }),
-                wait: options.wait !== false,
-            });
-            if (response.status === 'error' || !response.data) {
-                return {
-                    success: false,
-                    error: response.error ?? 'Failed to scroll',
-                    exitCode: response.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
-                    ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
-                };
-            }
-            const result = response.data;
-            if (!result.success) {
-                return {
-                    success: false,
-                    error: result.error ?? 'Failed to scroll',
-                    exitCode: result.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
-                    errorContext: {
-                        suggestion: result.suggestion ?? 'Verify the selector exists on the page',
-                    },
-                };
-            }
-            const { success: _success, ...data } = result;
-            return { success: true, data };
-        }, options, formatScrollOutput);
+        await runCommand(() => runScroll(selector, options), options, formatScrollOutput);
     });
 }
+/**
+ * Scroll to an element (selector or cached index) or by offsets/to an edge.
+ *
+ * @param selector - Selector or index argument, if any
+ * @param options - Scroll options
+ * @returns Command result
+ */
+async function runScroll(selector, options) {
+    const problem = scrollOptionsProblem(selector, options);
+    if (problem) {
+        const err = scrollOptionsError(problem);
+        return {
+            success: false,
+            error: err.message,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            errorContext: { suggestion: err.suggestion },
+        };
+    }
+    const request = {
+        ...(options.down !== undefined && { down: options.down }),
+        ...(options.up !== undefined && { up: options.up }),
+        ...(options.left !== undefined && { left: options.left }),
+        ...(options.right !== undefined && { right: options.right }),
+        ...(options.top !== undefined && { top: options.top }),
+        ...(options.bottom !== undefined && { bottom: options.bottom }),
+        wait: options.wait !== false,
+    };
+    if (selector) {
+        return runElementCommand({
+            selectorOrIndex: selector,
+            index: options.index,
+            buildRequest: (target) => ({ ...target, ...request }),
+            call: domScroll,
+            command: 'scroll',
+            action: 'scroll',
+            failureSuggestion: 'Verify the selector exists on the page',
+        });
+    }
+    const response = await domScroll(request);
+    const result = response.data;
+    if (response.status === 'error' || !result?.success) {
+        return {
+            success: false,
+            error: result?.error ?? response.error ?? 'Failed to scroll',
+            exitCode: result?.exitCode ?? response.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
+            ...((result?.suggestion ?? response.suggestion) && {
+                errorContext: { suggestion: result?.suggestion ?? response.suggestion ?? '' },
+            }),
+        };
+    }
+    const { success: _success, ...data } = result;
+    return { success: true, data };
+}
 /**
  * The first rule `bdg dom scroll` options break, if any: one target (an
  * element, or offsets/edges), and no opposite directions.
@@ -268,87 +272,130 @@ async function runPointerCommand(selectorOrIndex, options, action) {
                 ...(action !== 'click' && { action }),
             }),
             call: domClick,
+            command: action === 'hover' ? 'hover' : 'click',
             action: action === 'hover' ? 'hover element' : 'click element',
             failureSuggestion: 'Verify the selector matches a clickable element',
         }), options, formatClickOutput);
 }
 /**
- * Add an action's warning and the dialogs it caused to the output.
+ * 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).
  *
- * @param fmt - Output being built
+ * @param done - What was done, e.g. "Element Clicked"
+ * @param details - Label/value rows
  * @param result - Action result
+ * @param keyWidth - Width of the labels
+ * @returns Output being built (more can be appended)
  */
-function appendNotices(fmt, result) {
-    if (result.warning) {
-        fmt.blank();
+function formatActionOutput(done, details, result, keyWidth = 15) {
+    const fmt = new OutputFormatter();
+    fmt.text(actionStatusLine(done, result.warning !== undefined, result.effect === 'none'));
+    if (result.warning)
         fmt.text(`⚠ Warning: ${result.warning}`);
+    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);
+    });
+    const omitted = result.triggeredRequestsOmitted;
+    const requests = formatTriggeredRequestLines(result.triggeredRequests ?? [], omitted);
+    if (requests.length > 0) {
+        fmt
+            .blank()
+            .section(formatTriggeredRequestsTitle(result.triggeredRequests ?? [], omitted), requests);
     }
     for (const dialog of result.dialogs ?? []) {
         fmt.blank();
         fmt.text(`Dialog: ${dialogConsoleText(dialog)}`);
     }
+    return fmt;
+}
+/**
+ * Row naming the element an action hit, e.g.
+ * `Element: input.toggle in div.view "Write report"` (just its tag when the
+ * page could not describe it), with the list a numeric index refers to
+ * (`(index 0 of the last dom query "h3")`).
+ *
+ * @param result - Action result
+ * @returns Label/value row
+ */
+function elementRow(result) {
+    const source = result.indexSource ? ` (${indexSourceText(result.indexSource)})` : '';
+    if (result.element === undefined) {
+        return ['Element Type', `${result.elementType ?? 'unknown'}${source}`];
+    }
+    const viaLabel = result.elementType?.endsWith(VIA_LABEL_SUFFIX) ? VIA_LABEL_SUFFIX : '';
+    return ['Element', `${result.element}${viaLabel}${source}`];
+}
+/**
+ * Selector row of an action's output; none for an index into a11y query
+ * results, whose "selector" is the a11y pattern (the element row names it).
+ *
+ * @param result - Action result
+ * @returns The row, or none
+ */
+function selectorRows(result) {
+    if (result.indexSource?.command === 'dom a11y query')
+        return [];
+    return [['Selector', result.selector ?? 'unknown']];
 }
 /**
  * Format fill command output for human-readable display.
  */
 function formatFillOutput(result) {
-    const fmt = new OutputFormatter();
-    fmt.text('✓ Element Filled');
-    fmt.blank();
-    const details = [
-        ['Selector', result.selector ?? 'unknown'],
-        ['Element Type', result.elementType ?? 'unknown'],
-    ];
+    const details = [...selectorRows(result), elementRow(result)];
     if (result.inputType)
         details.push(['Input Type', result.inputType]);
     if (result.checked !== undefined) {
         details.push(['Checked', result.checked ? 'true' : 'false']);
     }
-    else if (result.value) {
-        details.push(['Value', result.value]);
+    else if (result.value !== undefined) {
+        details.push(['Value', result.value === '' ? '(empty)' : result.value]);
     }
-    fmt.keyValueList(details, 15);
-    appendNotices(fmt, result);
-    return fmt.build();
+    return formatActionOutput('Element Filled', details, result).build();
 }
 /**
  * Format click command output for human-readable display.
  */
 function formatClickOutput(result) {
-    const fmt = new OutputFormatter();
-    fmt.text(`✓ Element ${POINTER_ACTION_DONE[result.action ?? 'click']}`);
-    fmt.blank();
-    fmt.keyValueList([
-        ['Selector', result.selector ?? 'unknown'],
-        ['Element Type', result.elementType ?? 'unknown'],
+    return formatActionOutput(`Element ${POINTER_ACTION_DONE[result.action ?? 'click']}`, [
+        ...selectorRows(result),
+        elementRow(result),
         ['Method', result.method === 'dom' ? 'DOM events' : 'mouse events'],
-    ], 15);
-    appendNotices(fmt, result);
-    return fmt.build();
+    ], result).build();
 }
 /**
  * Format submit command output for human-readable display.
  */
 function formatSubmitOutput(result) {
-    const fmt = new OutputFormatter();
-    fmt.text('✓ Form Submitted');
-    fmt.blank();
     const details = [
-        ['Selector', result.selector ?? 'unknown'],
+        ...selectorRows(result),
+        ...(result.element !== undefined ? [elementRow(result)] : []),
         ['Submit Button', result.clicked ? 'used' : 'none'],
     ];
     if (result.networkRequests !== undefined)
         details.push(['Network Requests', result.networkRequests.toString()]);
-    if (result.navigationOccurred !== undefined)
-        details.push(['Navigation', result.navigationOccurred ? 'yes' : 'no']);
+    if (result.navigationOccurred === false)
+        details.push(['Navigation', 'no']);
+    if (result.navigationOccurred && !result.navigation)
+        details.push(['Navigation', 'yes']);
     if (result.waitTimeMs !== undefined)
         details.push(['Wait Time', `${result.waitTimeMs}ms`]);
-    fmt.keyValueList(details, 20);
-    appendNotices(fmt, result);
+    const fmt = formatActionOutput('Form Submitted', details, result, 20);
     fmt.hints('Next steps:', [
-        'bdg network list --last 10      Check network requests',
-        'bdg console --last 5             Check console messages',
-        'bdg status                       Check session state',
+        `${sessionCommand('bdg network list --last 10').padEnd(32)} Check network requests`,
+        `${sessionCommand('bdg console --last 5').padEnd(32)} Check console messages`,
+        `${sessionCommand('bdg status').padEnd(32)} Check session state`,
     ]);
     return fmt.build();
 }
@@ -356,42 +403,34 @@ function formatSubmitOutput(result) {
  * Format pressKey command output for human-readable display.
  */
 function formatPressKeyOutput(result) {
-    const fmt = new OutputFormatter();
-    fmt.text('✓ Key Pressed');
-    fmt.blank();
     const details = [
         ['Key', result.key ?? 'unknown'],
-        ['Selector', result.selector ?? 'unknown'],
-        ['Element Type', result.elementType ?? 'unknown'],
+        ...selectorRows(result),
+        elementRow(result),
     ];
     if (result.times && result.times > 1)
         details.push(['Times', result.times.toString()]);
     if (result.modifiers?.length)
         details.push(['Modifiers', result.modifiers.join('+')]);
-    fmt.keyValueList(details, 15);
-    appendNotices(fmt, result);
-    return fmt.build();
+    return formatActionOutput('Key Pressed', details, result).build();
 }
 /**
  * Format scroll command output for human-readable display.
  */
 function formatScrollOutput(result) {
-    const fmt = new OutputFormatter();
-    fmt.text('✓ Page Scrolled');
-    fmt.blank();
     const details = [['Scroll Type', result.scrollType]];
     if (result.selector)
-        details.push(['Selector', result.selector]);
+        details.push(...selectorRows(result));
+    if (result.element)
+        details.push(elementRow(result));
     if (result.scrolledTo)
         details.push(['Position', `(${result.scrolledTo.x}, ${result.scrolledTo.y})`]);
     if (result.scrolledBy && (result.scrolledBy.x !== 0 || result.scrolledBy.y !== 0))
         details.push(['Scrolled By', `(${result.scrolledBy.x}, ${result.scrolledBy.y})`]);
     if (result.viewportSize)
-        details.push(['Viewport', `${result.viewportSize.width}x${result.viewportSize.height}`]);
+        details.push(['Viewport', `${result.viewportSize.width}×${result.viewportSize.height}`]);
     if (result.pageSize)
-        details.push(['Page Size', `${result.pageSize.width}x${result.pageSize.height}`]);
-    fmt.keyValueList(details, 15);
-    appendNotices(fmt, result);
-    return fmt.build();
+        details.push(['Page Size', `${result.pageSize.width}×${result.pageSize.height}`]);
+    return formatActionOutput('Page Scrolled', details, result).build();
 }
 //# sourceMappingURL=formInteraction.js.map

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

@@ -0,0 +1,49 @@
+/**
+ * Readiness of a discovered form (`bdg dom form`): which fields are filled,
+ * which required ones are still empty, and which button submits it.
+ */
+import type { FormButton, FormField, FormSummary, RawButton, RawForm } from '../../runtime/dom/formTypes.js';
+/**
+ * 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 declare function groupFields(fields: FormField[]): FormField[][];
+/**
+ * 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 declare function calculateSummary(fields: FormField[], buttons: FormButton[]): FormSummary;
+/**
+ * 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 declare function primaryButtonIndex(buttons: RawButton[]): number | undefined;
+/**
+ * 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 declare function orderForms(forms: RawForm[]): RawForm[];
+//# sourceMappingURL=formSummary.d.ts.map

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