browser-debugger-cli 0.7.1 → 0.8.0

package/dist/runtime/dom/formFillHelpers/scroll.js

@@ -0,0 +1,188 @@
+/**
+ * Page scroll operations: scroll element into view, by pixel offset, or to
+ * page boundaries.
+ */
+import { CommandError } from '../../../errors/index.js';
+import { throwIfInvalidSelector, withMultipleMatchesWarning, } from './shared.js';
+import { FIND_ELEMENTS_JS, selectorArgsJS } from '../targetNode.js';
+import { EXIT_CODES } from '../../../utils/exitCodes.js';
+const SCROLL_TO_ELEMENT_SCRIPT = `
+(function(selector, parts, index) {
+  const allMatches = (${FIND_ELEMENTS_JS})(selector, parts);
+  if (allMatches.length === 0) {
+    return { success: false, error: 'No nodes found matching selector: ' + selector };
+  }
+
+  let el;
+  if (typeof index === 'number' && index >= 0) {
+    if (index >= allMatches.length) {
+      return {
+        success: false,
+        reason: 'range',
+        error: 'Index ' + index + ' out of range (found ' + allMatches.length + ' nodes, use 0-' + (allMatches.length - 1) + ')'
+      };
+    }
+    el = allMatches[index];
+  } else {
+    el = allMatches[0];
+  }
+
+  el.scrollIntoView({ behavior: 'instant', block: 'center' });
+
+  const rect = el.getBoundingClientRect();
+  const scrollX = window.scrollX + rect.left + rect.width / 2 - window.innerWidth / 2;
+  const scrollY = window.scrollY + rect.top + rect.height / 2 - window.innerHeight / 2;
+
+  return {
+    success: true,
+    scrollType: 'element',
+    selector: selector,
+    matchCount: allMatches.length,
+    scrolledTo: {
+      x: Math.round(window.scrollX),
+      y: Math.round(window.scrollY)
+    },
+    viewportSize: {
+      width: window.innerWidth,
+      height: window.innerHeight
+    },
+    pageSize: {
+      width: document.documentElement.scrollWidth,
+      height: document.documentElement.scrollHeight
+    }
+  };
+})`;
+const SCROLL_BY_SCRIPT = `
+(function(options) {
+  const beforeX = window.scrollX;
+  const beforeY = window.scrollY;
+
+  if (options.top) {
+    window.scrollTo({ top: 0, behavior: 'instant' });
+  } else if (options.bottom) {
+    window.scrollTo({ top: document.documentElement.scrollHeight, behavior: 'instant' });
+  } else {
+    let deltaX = 0;
+    let deltaY = 0;
+
+    if (options.down) deltaY = options.down;
+    if (options.up) deltaY = -options.up;
+    if (options.right) deltaX = options.right;
+    if (options.left) deltaX = -options.left;
+
+    window.scrollBy({ left: deltaX, top: deltaY, behavior: 'instant' });
+  }
+
+  const afterX = window.scrollX;
+  const afterY = window.scrollY;
+
+  return {
+    success: true,
+    scrollType: options.top || options.bottom ? 'position' : 'offset',
+    scrolledTo: { x: Math.round(afterX), y: Math.round(afterY) },
+    scrolledBy: { x: Math.round(afterX - beforeX), y: Math.round(afterY - beforeY) },
+    viewportSize: {
+      width: window.innerWidth,
+      height: window.innerHeight
+    },
+    pageSize: {
+      width: document.documentElement.scrollWidth,
+      height: document.documentElement.scrollHeight
+    }
+  };
+})`;
+function isScrollResult(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return typeof obj['success'] === 'boolean' && typeof obj['scrollType'] === 'string';
+}
+/**
+ * Scroll the page to an element, by offset, or to a boundary.
+ */
+export async function scrollPage(cdp, selector, options = {}) {
+    try {
+        if (selector) {
+            const indexArg = options.index ?? 'null';
+            const expression = `(${SCROLL_TO_ELEMENT_SCRIPT})(${selectorArgsJS(selector)}, ${indexArg})`;
+            const response = await cdp.send('Runtime.evaluate', {
+                expression,
+                returnByValue: true,
+            });
+            const cdpResponse = response;
+            if (cdpResponse.exceptionDetails) {
+                throwIfInvalidSelector(cdpResponse.exceptionDetails, selector);
+                return {
+                    success: false,
+                    exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+                    scrollType: 'element',
+                    error: `Script execution failed: ${cdpResponse.exceptionDetails.text}`,
+                    suggestion: `Verify element exists: bdg dom query "${selector}"`,
+                };
+            }
+            if (cdpResponse.result?.value && isScrollResult(cdpResponse.result.value)) {
+                return withMultipleMatchesWarning(cdpResponse.result.value, options.index, 'scrolled to the first');
+            }
+            const scriptResult = cdpResponse.result?.value;
+            if (scriptResult?.success === false && scriptResult.error) {
+                const outOfRange = scriptResult.reason === 'range';
+                return {
+                    success: false,
+                    exitCode: outOfRange ? EXIT_CODES.INVALID_ARGUMENTS : EXIT_CODES.RESOURCE_NOT_FOUND,
+                    scrollType: 'element',
+                    error: scriptResult.error,
+                    suggestion: `${outOfRange ? 'Check the matches' : 'Verify element exists'}: bdg dom query "${selector}"`,
+                };
+            }
+            return {
+                success: false,
+                exitCode: EXIT_CODES.SOFTWARE_ERROR,
+                scrollType: 'element',
+                error: 'Unexpected response format',
+            };
+        }
+        const scrollOptions = {
+            down: options.down,
+            up: options.up,
+            left: options.left,
+            right: options.right,
+            top: options.top,
+            bottom: options.bottom,
+        };
+        const expression = `(${SCROLL_BY_SCRIPT})(${JSON.stringify(scrollOptions)})`;
+        const response = await cdp.send('Runtime.evaluate', {
+            expression,
+            returnByValue: true,
+        });
+        const cdpResponse = response;
+        if (cdpResponse.exceptionDetails) {
+            return {
+                success: false,
+                exitCode: EXIT_CODES.SOFTWARE_ERROR,
+                scrollType: 'offset',
+                error: `Script execution failed: ${cdpResponse.exceptionDetails.text}`,
+            };
+        }
+        if (cdpResponse.result?.value && isScrollResult(cdpResponse.result.value)) {
+            return cdpResponse.result.value;
+        }
+        return {
+            success: false,
+            exitCode: EXIT_CODES.SOFTWARE_ERROR,
+            scrollType: 'offset',
+            error: 'Unexpected response format',
+        };
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            exitCode: EXIT_CODES.SOFTWARE_ERROR,
+            scrollType: selector ? 'element' : 'offset',
+            error: `Scroll failed: ${errorMessage}`,
+        };
+    }
+}
+//# sourceMappingURL=scroll.js.map

package/dist/runtime/dom/formFillHelpers/shared.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared internal helpers for form-fill operations: script-error formatting
+ * and JS string escaping.
+ */
+import type { Protocol } from '../../../connection/typed-cdp.js';
+/**
+ * Escape a CSS selector for embedding in a single-quoted JS string.
+ */
+export declare function escapeSelectorForJS(selector: string): string;
+/**
+ * Add a warning when the selector matched several elements and no index was
+ * given, so the caller knows which one was used. Keeps an existing warning.
+ *
+ * @param result - Action result with the number of matches
+ * @param index - The --index given, if any
+ * @param action - What was done, e.g. "scrolled to the first"
+ * @returns The result, with a warning when applicable
+ */
+export declare function withMultipleMatchesWarning<T extends {
+    matchCount?: number | undefined;
+    warning?: string | undefined;
+}>(result: T, index: number | undefined, action: string): T;
+/**
+ * Escape a value for embedding in a single-quoted JS string.
+ */
+export declare function escapeValueForJS(value: string): string;
+/**
+ * Format a CDP exception into a user-friendly error with troubleshooting
+ * hints. Detects shell-quote-damaged selectors and recommends the
+ * query-then-act pattern.
+ */
+export declare function formatScriptExecutionError(exceptionDetails: Protocol.Runtime.ExceptionDetails, selector: string, operationType?: 'fill' | 'click', expression?: string): string;
+/**
+ * Throw a user error when a page script failed because the CSS selector is
+ * invalid (the browser's `querySelectorAll` rejected it), instead of reporting
+ * a script failure.
+ *
+ * @param details - Exception details from Runtime.evaluate
+ * @param selector - Selector the user gave
+ * @throws CommandError (81) for an invalid selector
+ */
+export declare function throwIfInvalidSelector(details: Protocol.Runtime.ExceptionDetails, selector: string): void;
+//# sourceMappingURL=shared.d.ts.map

package/dist/runtime/dom/formFillHelpers/shared.js

@@ -0,0 +1,100 @@
+/**
+ * Shared internal helpers for form-fill operations: script-error formatting
+ * and JS string escaping.
+ */
+import { CommandError } from '../../../errors/index.js';
+import { invalidSelectorError } from '../../../errors/messages.js';
+import { multipleMatchesWarning } from '../../../ui/messages/commands.js';
+import { EXIT_CODES } from '../../../utils/exitCodes.js';
+import { detectSelectorQuoteDamage } from '../../../utils/shellDetection.js';
+/**
+ * Escape a CSS selector for embedding in a single-quoted JS string.
+ */
+export function escapeSelectorForJS(selector) {
+    return JSON.stringify(selector).slice(1, -1).replace(/'/g, "\\'");
+}
+/**
+ * Add a warning when the selector matched several elements and no index was
+ * given, so the caller knows which one was used. Keeps an existing warning.
+ *
+ * @param result - Action result with the number of matches
+ * @param index - The --index given, if any
+ * @param action - What was done, e.g. "scrolled to the first"
+ * @returns The result, with a warning when applicable
+ */
+export function withMultipleMatchesWarning(result, index, action) {
+    const count = result.matchCount ?? 0;
+    if (index !== undefined || count <= 1)
+        return result;
+    const warning = multipleMatchesWarning(count, action);
+    return { ...result, warning: result.warning ? `${result.warning}; ${warning}` : warning };
+}
+/**
+ * Escape a value for embedding in a single-quoted JS string.
+ */
+export function escapeValueForJS(value) {
+    return JSON.stringify(value).slice(1, -1).replace(/'/g, "\\'");
+}
+/**
+ * Format a CDP exception into a user-friendly error with troubleshooting
+ * hints. Detects shell-quote-damaged selectors and recommends the
+ * query-then-act pattern.
+ */
+export function formatScriptExecutionError(exceptionDetails, selector, operationType = 'fill', expression) {
+    const errorText = exceptionDetails.text || 'Unknown error';
+    const location = exceptionDetails.lineNumber !== undefined && exceptionDetails.columnNumber !== undefined
+        ? ` at line ${exceptionDetails.lineNumber + 1}, column ${exceptionDetails.columnNumber + 1}`
+        : '';
+    const lines = [];
+    lines.push(`Script execution failed: ${errorText}${location}`);
+    if (expression) {
+        const truncated = expression.length > 150 ? expression.slice(0, 150) + '...' : expression;
+        lines.push('');
+        lines.push(`Expression received: ${truncated}`);
+        const selectorCheck = detectSelectorQuoteDamage(selector);
+        if (selectorCheck.damaged) {
+            lines.push('');
+            lines.push('Shell quote damage detected in selector:');
+            if (selectorCheck.details) {
+                lines.push(`  ${selectorCheck.details}`);
+            }
+            lines.push('');
+            lines.push('Try using the two-step pattern:');
+            lines.push(`  1. bdg dom query '${selector}'`);
+            lines.push(`  2. bdg dom ${operationType} 0${operationType === 'fill' ? ' "value"' : ''}`);
+            return lines.join('\n');
+        }
+    }
+    const troubleshootingSteps = operationType === 'fill'
+        ? [
+            `1. Verify element exists: bdg dom query "${selector}"`,
+            '2. Check element is visible and not disabled',
+            `3. Try direct eval: bdg dom eval "document.querySelector('${escapeSelectorForJS(selector)}').value = 'your-value'"`,
+        ]
+        : [
+            `1. Verify element exists: bdg dom query "${selector}"`,
+            '2. Check element is visible and clickable',
+            `3. Try direct eval: bdg dom eval "document.querySelector('${escapeSelectorForJS(selector)}').click()"`,
+        ];
+    lines.push('');
+    lines.push('Troubleshooting:');
+    lines.push(`  ${troubleshootingSteps.join('\n  ')}`);
+    return lines.join('\n');
+}
+/**
+ * Throw a user error when a page script failed because the CSS selector is
+ * invalid (the browser's `querySelectorAll` rejected it), instead of reporting
+ * a script failure.
+ *
+ * @param details - Exception details from Runtime.evaluate
+ * @param selector - Selector the user gave
+ * @throws CommandError (81) for an invalid selector
+ */
+export function throwIfInvalidSelector(details, selector) {
+    const description = details.exception?.description ?? details.text;
+    if (!/Failed to execute '\w+' on '\w+': .* is not a valid selector/.test(description))
+        return;
+    const err = invalidSelectorError(selector);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+//# sourceMappingURL=shared.js.map

package/dist/runtime/dom/formFillHelpers/stability.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Post-action network-stability wait.
+ *
+ * Lightweight check used after fill/click/pressKey/scroll: subscribes to
+ * CDP network events, waits until no request has been pending for
+ * ACTION_NETWORK_IDLE_MS, times out at ACTION_STABILITY_TIMEOUT_MS.
+ */
+import type { CDPConnection } from '../../../connection/cdp.js';
+/**
+ * Wait for the network to settle after an action. Returns when idle for
+ * the threshold or after the timeout.
+ */
+export declare function waitForActionStability(cdp: CDPConnection): Promise<void>;
+//# sourceMappingURL=stability.d.ts.map

package/dist/runtime/dom/formFillHelpers/stability.js

@@ -0,0 +1,40 @@
+/**
+ * Post-action network-stability wait.
+ *
+ * Lightweight check used after fill/click/pressKey/scroll: subscribes to
+ * CDP network events, waits until no request has been pending for
+ * ACTION_NETWORK_IDLE_MS, times out at ACTION_STABILITY_TIMEOUT_MS.
+ */
+import { trackInFlightRequests } from '../../../connection/inFlightRequests.js';
+import { createLogger } from '../../../ui/logging/index.js';
+import { delay } from '../../../utils/async.js';
+const log = createLogger('dom');
+const ACTION_NETWORK_IDLE_MS = 150;
+const ACTION_STABILITY_TIMEOUT_MS = 2000;
+const STABILITY_CHECK_INTERVAL_MS = 50;
+/**
+ * Wait for the network to settle after an action. Returns when idle for
+ * the threshold or after the timeout.
+ */
+export async function waitForActionStability(cdp) {
+    const deadline = Date.now() + ACTION_STABILITY_TIMEOUT_MS;
+    await cdp.send('Network.enable');
+    const requests = trackInFlightRequests(cdp);
+    try {
+        while (Date.now() < deadline) {
+            if (requests.count === 0) {
+                const idleTime = Date.now() - requests.lastActivity;
+                if (idleTime >= ACTION_NETWORK_IDLE_MS) {
+                    log.debug(`Network stable after ${idleTime}ms idle`);
+                    return;
+                }
+            }
+            await delay(STABILITY_CHECK_INTERVAL_MS);
+        }
+        log.debug('Stability timeout reached, proceeding');
+    }
+    finally {
+        requests.dispose();
+    }
+}
+//# sourceMappingURL=stability.js.map

package/dist/runtime/dom/formSubmitHelpers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Form submission helpers with smart network waiting.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { SubmitResult } from '../../ipc/protocol/domTypes.js';
+/**
+ * Options for submitting a form.
+ */
+export interface SubmitOptions {
+    /** Element index if selector matches multiple (0-based) */
+    index?: number;
+    /** Wait for page navigation after submit (default: false) */
+    waitNavigation?: boolean;
+    /** Wait for network idle after submit in milliseconds (default: 1000) */
+    waitNetwork?: number;
+    /** Maximum time to wait in milliseconds (default: 10000) */
+    timeout?: number;
+}
+export type { SubmitResult } from '../../ipc/protocol/domTypes.js';
+/**
+ * Submit a form and wait for the result.
+ *
+ * @param cdp - CDP connection
+ * @param selector - Form or submit button selector (or bound-node placeholder)
+ * @param options - Submit options
+ * @returns Submit result
+ */
+export declare function submitForm(cdp: CDPConnection, selector: string, options?: SubmitOptions): Promise<SubmitResult>;
+//# sourceMappingURL=formSubmitHelpers.d.ts.map

package/dist/runtime/dom/formSubmitHelpers.js

@@ -0,0 +1,252 @@
+/**
+ * Form submission helpers with smart network waiting.
+ */
+import { CDPTimeoutError } from '../../connection/errors.js';
+import { trackInFlightRequests } from '../../connection/inFlightRequests.js';
+import { submitTimeoutError } from '../../errors/messages.js';
+import { throwIfInvalidSelector } from './formFillHelpers/shared.js';
+import { FIND_ELEMENTS_JS, selectorArgsJS } from './targetNode.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { clickElement } from './formFillHelpers/index.js';
+/**
+ * Page script deciding how to submit the target.
+ *
+ * A `<form>` is submitted with `requestSubmit()` (what pressing a submit
+ * button does); a submit button or other element inside a form is clicked
+ * with real mouse events by the caller. Fails, like a browser would refuse,
+ * when the form has invalid fields, and for elements that are neither a form
+ * nor a button.
+ */
+const PREPARE_SUBMIT_SCRIPT = `
+(function(selector, parts, index) {
+  const matches = (${FIND_ELEMENTS_JS})(selector, parts);
+  if (matches.length === 0) {
+    return { action: 'fail', reason: 'not-found', error: 'Element not found: ' + selector };
+  }
+  const el = typeof index === 'number' ? matches[index] : matches[0];
+  if (!el) {
+    return {
+      action: 'fail',
+      reason: 'range',
+      error: 'Index ' + index + ' out of range (found ' + matches.length + ' elements)'
+    };
+  }
+  const isForm = el.tagName === 'FORM';
+  const isButton = el.matches('button, input[type=submit], input[type=image], [role=button]');
+  const isSubmitter = el.matches('button:not([type]), button[type=submit], input[type=submit], input[type=image]');
+  const form = isForm ? el : el.form || el.closest('form');
+  if (!isForm && !isButton) {
+    return {
+      action: 'fail',
+      reason: 'not-submittable',
+      error: 'Element is neither a form nor a submit button: <' + el.tagName.toLowerCase() + '>'
+    };
+  }
+  const submitters = isForm
+    ? Array.from(el.elements).filter((f) =>
+        f.matches('button:not([type]), button[type=submit], input[type=submit], input[type=image]')
+      )
+    : [];
+  if (submitters.length > 0 && submitters.every((f) => f.matches(':disabled'))) {
+    // A user could not submit: Enter does nothing while the default button is disabled
+    return { action: 'fail', reason: 'disabled', error: 'The form\\'s submit button is disabled' };
+  }
+  if ((isForm || isSubmitter) && form && !form.noValidate && !el.formNoValidate && !form.checkValidity()) {
+    const invalid = Array.from(form.elements)
+      .filter((f) => f.willValidate && !f.checkValidity())
+      .map((f) => (f.name || f.id || f.tagName.toLowerCase()) + ': ' + f.validationMessage);
+    return { action: 'fail', reason: 'invalid', error: 'Form has invalid fields - ' + invalid.join('; ') };
+  }
+  if (isForm) {
+    // Like pressing Enter: the form's default button is the submitter, so its
+    // name=value is sent too
+    const submitter = submitters.find((f) => !f.matches(':disabled'));
+    if (submitter) el.requestSubmit(submitter);
+    else el.requestSubmit();
+    return { action: 'submitted', clicked: Boolean(submitter) };
+  }
+  return { action: 'click' };
+})`;
+const FAILURE_EXIT_CODES = {
+    'not-found': EXIT_CODES.RESOURCE_NOT_FOUND,
+    range: EXIT_CODES.INVALID_ARGUMENTS,
+    'not-submittable': EXIT_CODES.INVALID_ARGUMENTS,
+    invalid: EXIT_CODES.INVALID_ARGUMENTS,
+    disabled: EXIT_CODES.INVALID_ARGUMENTS,
+};
+const FAILURE_SUGGESTIONS = {
+    'not-found': 'Verify the selector matches a form or submit button',
+    range: 'Use an --index within the number of matches',
+    'not-submittable': 'Target the <form> or its submit button, or use "bdg dom click" for other elements',
+    invalid: 'Fill the listed fields first (see "bdg dom form" for their state)',
+    disabled: 'Complete the steps that enable the button first (see "bdg dom form" for its state)',
+};
+/**
+ * Watches navigation and network activity from before a submission is
+ * triggered, so fast navigations are not missed.
+ */
+class SubmissionWatcher {
+    navigated = false;
+    onChange = null;
+    requests;
+    disposers = [];
+    /**
+     * @param cdp - CDP connection
+     */
+    constructor(cdp) {
+        this.requests = trackInFlightRequests(cdp, () => this.onChange?.());
+        this.disposers.push(this.requests.dispose);
+        this.disposers.push(cdp.on('Page.frameNavigated', (params) => {
+            if (params.frame.parentId !== undefined)
+                return;
+            this.navigated = true;
+            this.onChange?.();
+        }));
+    }
+    /** Whether the main frame navigated since watching began. */
+    get navigationOccurred() {
+        return this.navigated;
+    }
+    /** Requests started since watching began. */
+    get networkRequests() {
+        return this.requests.started;
+    }
+    /**
+     * Wait until the network is idle for `waitNetwork` ms and, if requested,
+     * the main frame navigated.
+     *
+     * @param options - Wait conditions
+     * @returns Resolves when done
+     * @throws CDPTimeoutError after `timeout` ms
+     */
+    wait(options) {
+        const { waitNavigation, waitNetwork, timeout } = options;
+        return new Promise((resolve, reject) => {
+            let idle = null;
+            const finish = () => {
+                clearTimeout(deadline);
+                if (idle)
+                    clearTimeout(idle);
+                this.onChange = null;
+            };
+            const deadline = setTimeout(() => {
+                finish();
+                reject(new CDPTimeoutError('Wait for completion timed out', new Error(`${timeout}ms`)));
+            }, timeout);
+            const check = () => {
+                const networkIdle = waitNetwork === 0 || this.requests.count === 0;
+                if (networkIdle && (!waitNavigation || this.navigated)) {
+                    finish();
+                    resolve();
+                }
+            };
+            const schedule = () => {
+                if (idle)
+                    clearTimeout(idle);
+                idle = null;
+                if (waitNetwork === 0)
+                    check();
+                else if (this.requests.count === 0)
+                    idle = setTimeout(check, waitNetwork);
+            };
+            this.onChange = schedule;
+            schedule();
+        });
+    }
+    /** Stop watching. */
+    dispose() {
+        this.disposers.forEach((dispose) => dispose());
+    }
+}
+/**
+ * Submit the target: `requestSubmit()` for a form, a real click otherwise.
+ *
+ * @param cdp - CDP connection
+ * @param selector - Selector (or bound-node placeholder)
+ * @param index - Optional 0-based index among matches
+ * @returns Failure result, or whether a submit button was used
+ */
+async function triggerSubmit(cdp, selector, index) {
+    const response = (await cdp.send('Runtime.evaluate', {
+        expression: `(${PREPARE_SUBMIT_SCRIPT})(${selectorArgsJS(selector)}, ${index ?? 'null'})`,
+        returnByValue: true,
+        userGesture: true,
+    }));
+    if (response.exceptionDetails)
+        throwIfInvalidSelector(response.exceptionDetails, selector);
+    const prepared = response.result?.value;
+    if (!prepared || prepared.action === 'fail') {
+        const reason = prepared?.reason ?? 'not-found';
+        const failure = {
+            success: false,
+            error: prepared?.error ?? 'Could not submit',
+            selector,
+            clicked: false,
+            exitCode: FAILURE_EXIT_CODES[reason],
+            suggestion: FAILURE_SUGGESTIONS[reason],
+        };
+        return { failure };
+    }
+    if (prepared.action === 'submitted')
+        return { clicked: prepared.clicked === true };
+    const click = await clickElement(cdp, selector, index !== undefined ? { index } : {});
+    if (click.success)
+        return { clicked: true };
+    const failure = {
+        success: false,
+        error: click.error ?? 'Click failed',
+        selector,
+        clicked: false,
+        ...(click.exitCode !== undefined && { exitCode: click.exitCode }),
+        ...(click.suggestion !== undefined && { suggestion: click.suggestion }),
+    };
+    return { failure };
+}
+/**
+ * Submit a form and wait for the result.
+ *
+ * @param cdp - CDP connection
+ * @param selector - Form or submit button selector (or bound-node placeholder)
+ * @param options - Submit options
+ * @returns Submit result
+ */
+export async function submitForm(cdp, selector, options = {}) {
+    const { index, waitNavigation = false, waitNetwork = 1000, timeout = 10000 } = options;
+    const startTime = Date.now();
+    const watcher = new SubmissionWatcher(cdp);
+    try {
+        const triggered = await triggerSubmit(cdp, selector, index);
+        if ('failure' in triggered)
+            return triggered.failure;
+        if (waitNetwork > 0 || waitNavigation) {
+            await watcher.wait({ waitNavigation, waitNetwork, timeout });
+        }
+        return {
+            success: true,
+            selector,
+            clicked: triggered.clicked,
+            networkRequests: watcher.networkRequests,
+            navigationOccurred: watcher.navigationOccurred,
+            waitTimeMs: Date.now() - startTime,
+        };
+    }
+    catch (error) {
+        if (!(error instanceof CDPTimeoutError))
+            throw error;
+        const err = submitTimeoutError(timeout, waitNavigation);
+        return {
+            success: false,
+            error: err.message,
+            selector,
+            clicked: true,
+            navigationOccurred: watcher.navigationOccurred,
+            waitTimeMs: Date.now() - startTime,
+            exitCode: EXIT_CODES.CDP_TIMEOUT,
+            suggestion: err.suggestion,
+        };
+    }
+    finally {
+        watcher.dispose();
+    }
+}
+//# sourceMappingURL=formSubmitHelpers.js.map

package/dist/runtime/dom/formTypes.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for form discovery command.
+ *
+ * Re-exports shared types from types.js and defines command-specific types.
+ */
+export type { FieldValidation, FieldOption, FormFieldType, FieldState, FormField, FormButton, FormBlocker, FormSummary, FormStep, DiscoveredForm, FormDiscoveryResult, } from '../../types.js';
+export type { RawFormData, RawForm, RawField, RawButton } from '../../ipc/protocol/domTypes.js';
+//# sourceMappingURL=formTypes.d.ts.map