browser-debugger-cli 0.8.0 → 0.10.0

package/dist/commands/dom/formInteraction.js

@@ -7,18 +7,21 @@
  * 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 { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } 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, 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.
@@ -53,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)')
@@ -71,6 +74,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);
@@ -78,12 +82,14 @@ 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)
         .action(async (selectorOrIndex, options) => {
         const action = options.double ? 'double' : options.right ? 'right' : 'click';
         await runPointerCommand(selectorOrIndex, options, action);
@@ -91,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) => {
@@ -101,12 +108,13 @@ 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)
         .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 +128,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);
@@ -127,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))
@@ -146,6 +155,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 +174,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.
@@ -266,89 +274,159 @@ 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',
             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,
+ * "⚠ 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 fmt - Output being built
+ * @param done - What was done, e.g. "Element Clicked"
+ * @param details - Label/value rows
  * @param result - Action result
+ * @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 appendNotices(fmt, result) {
-    if (result.warning) {
-        fmt.blank();
+function formatActionOutput(done, details, result, options = {}) {
+    const keyWidth = options.keyWidth ?? 15;
+    const fmt = new OutputFormatter();
+    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);
+    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) {
+        fmt
+            .blank()
+            .section(formatTriggeredRequestsTitle(result.triggeredRequests ?? [], omitted), requests);
     }
     for (const dialog of result.dialogs ?? []) {
         fmt.blank();
         fmt.text(`Dialog: ${dialogConsoleText(dialog)}`);
     }
+    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
+ * 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, { action: POINTER_ACTION_NOUN[result.action ?? 'click'] }).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, {
+        keyWidth: 20,
+        action: 'submit',
+    });
     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 +434,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, { action: 'key press' }).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