browser-debugger-cli 0.7.2 → 0.9.0

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

@@ -0,0 +1,27 @@
+/**
+ * Page scroll operations: scroll element into view, by pixel offset, or to
+ * page boundaries.
+ */
+import type { CDPConnection } from '../../../connection/cdp.js';
+import type { ScrollResult } from '../../../ipc/protocol/domTypes.js';
+/**
+ * Scroll options.
+ *
+ * The reported viewport is the layout viewport without scrollbars and the
+ * page size the scrolling element's, as in `bdg dom layout`.
+ */
+export interface ScrollOptions {
+    down?: number;
+    up?: number;
+    left?: number;
+    right?: number;
+    top?: boolean;
+    bottom?: boolean;
+    index?: number;
+}
+export type { ScrollResult } from '../../../ipc/protocol/domTypes.js';
+/**
+ * Scroll the page to an element, by offset, or to a boundary.
+ */
+export declare function scrollPage(cdp: CDPConnection, selector: string | undefined, options?: ScrollOptions): Promise<ScrollResult>;
+//# sourceMappingURL=scroll.d.ts.map

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

@@ -0,0 +1,230 @@
+/**
+ * Page scroll operations: scroll element into view, by pixel offset, or to
+ * page boundaries.
+ */
+import { CommandError } from '../../../errors/index.js';
+import { scrollNoEffectWarning } from '../../../errors/messages.js';
+import { SCROLL_RANGE_JS, VIEWPORT_SIZE_JS, } from '../elementGeometry.js';
+import { ELEMENT_IDENTITY_JS } from '../elementInfo.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' });
+
+  return {
+    success: true,
+    scrollType: 'element',
+    selector: selector,
+    element: (${ELEMENT_IDENTITY_JS})(el),
+    matchCount: allMatches.length,
+    scrolledTo: {
+      x: Math.round(window.scrollX),
+      y: Math.round(window.scrollY)
+    },
+    viewportSize: (${VIEWPORT_SIZE_JS})(window),
+    pageSize: {
+      width: (document.scrollingElement || document.documentElement).scrollWidth,
+      height: (document.scrollingElement || document.documentElement).scrollHeight
+    }
+  };
+})`;
+const SCROLL_BY_SCRIPT = `
+(function(options) {
+  const beforeX = window.scrollX;
+  const beforeY = window.scrollY;
+  const range = (${SCROLL_RANGE_JS})(window);
+
+  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: (${VIEWPORT_SIZE_JS})(window),
+    pageSize: {
+      width: (document.scrollingElement || document.documentElement).scrollWidth,
+      height: (document.scrollingElement || document.documentElement).scrollHeight
+    },
+    rangeBefore: range,
+    readyState: document.readyState
+  };
+})`;
+/**
+ * The direction a page scroll asked for (the options allow one per axis;
+ * only one axis is checked, vertical first).
+ *
+ * @param options - Scroll options
+ * @returns Direction, or undefined when no distance was asked for
+ */
+function requestedDirection(options) {
+    if (options.bottom || (options.down ?? 0) > 0)
+        return 'down';
+    if (options.top || (options.up ?? 0) > 0)
+        return 'up';
+    if ((options.right ?? 0) > 0)
+        return 'right';
+    if ((options.left ?? 0) > 0)
+        return 'left';
+    return undefined;
+}
+/**
+ * Warn when a page scroll moved nothing: the document does not scroll in
+ * that direction, the page was already at its edge, or scrolling is locked;
+ * while the page is still loading, also that it may grow.
+ *
+ * @param result - Page script result
+ * @param options - Scroll options
+ * @returns The scroll result, with `warning` when nothing scrolled
+ */
+function withNoEffectWarning(result, options) {
+    const { rangeBefore, readyState, ...scroll } = result;
+    const direction = requestedDirection(options);
+    const moved = scroll.scrolledBy && (scroll.scrolledBy.x !== 0 || scroll.scrolledBy.y !== 0);
+    if (!direction || moved || !scroll.viewportSize)
+        return scroll;
+    const vertical = direction === 'up' || direction === 'down';
+    const scrollable = vertical
+        ? rangeBefore.up + rangeBefore.down > 0
+        : rangeBefore.left + rangeBefore.right > 0;
+    const warning = scrollNoEffectWarning({
+        direction,
+        reason: !scrollable ? 'too-small' : rangeBefore[direction] <= 0 ? 'at-edge' : 'locked',
+        viewport: vertical ? scroll.viewportSize.height : scroll.viewportSize.width,
+        readyState,
+    });
+    return { ...scroll, warning };
+}
+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 withNoEffectWarning(cdpResponse.result.value, options);
+        }
+        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,60 @@
+/**
+ * Shared internal helpers for form-fill operations: script-error formatting
+ * and JS string escaping.
+ */
+import type { Protocol } from '../../../connection/typed-cdp.js';
+import type { FillResult } from '../../../ipc/protocol/domTypes.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;
+/**
+ * Put a warning first when the filled field's value is not the one given
+ * (see `valueMismatch`). Keeps an existing warning after it.
+ *
+ * @param result - Fill result
+ * @returns The result, with the warning when the value differs
+ */
+export declare function withValueMismatchWarning(result: FillResult): FillResult;
+/**
+ * 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;
+/**
+ * What a page script threw, in one line (`TypeError: Cannot read …` rather
+ * than CDP's bare "Uncaught").
+ *
+ * @param details - Exception details from Runtime.evaluate
+ * @returns First line of the exception's description
+ */
+export declare function exceptionSummary(details: Protocol.Runtime.ExceptionDetails): 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,124 @@
+/**
+ * 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, valueMismatchWarning } 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 };
+}
+/**
+ * Put a warning first when the filled field's value is not the one given
+ * (see `valueMismatch`). Keeps an existing warning after it.
+ *
+ * @param result - Fill result
+ * @returns The result, with the warning when the value differs
+ */
+export function withValueMismatchWarning(result) {
+    if (!result.valueMismatch)
+        return result;
+    const warning = valueMismatchWarning(result.valueMismatch);
+    return { ...result, warning: result.warning ? `${warning}; ${result.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');
+}
+/**
+ * What a page script threw, in one line (`TypeError: Cannot read …` rather
+ * than CDP's bare "Uncaught").
+ *
+ * @param details - Exception details from Runtime.evaluate
+ * @returns First line of the exception's description
+ */
+export function exceptionSummary(details) {
+    const description = details.exception?.description ?? details.text;
+    return description.split('\n')[0] ?? description;
+}
+/**
+ * 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,28 @@
+/**
+ * Post-action network-stability wait.
+ *
+ * Used around fill/click/hover/pressKey/scroll: tracks in-flight requests
+ * from before the action runs (so a request its handler sends synchronously
+ * is seen), then waits until no request has been pending for
+ * ACTION_NETWORK_IDLE_MS, giving up after ACTION_STABILITY_TIMEOUT_MS.
+ */
+import type { CDPConnection } from '../../../connection/cdp.js';
+/**
+ * Run an action and, when it succeeds, wait for the network to settle.
+ *
+ * Requests are tracked from before the action, so one an event handler
+ * starts while the action runs (`onclick = () => fetch(...)`) is waited for.
+ * `Network.enable` is sent without waiting for it: the session's network
+ * collector has already enabled the domain, and Chrome holds the call until
+ * a pending navigation commits, which would otherwise block for as long as
+ * the new page's server takes to answer.
+ *
+ * @param cdp - CDP connection
+ * @param action - Action to run (its result's `success` decides whether to wait)
+ * @param wait - Wait for the network after the action (false for `--no-wait`)
+ * @returns The action's result, once the network is idle or the wait timed out
+ */
+export declare function withActionStability<T extends {
+    success: boolean;
+}>(cdp: CDPConnection, action: () => Promise<T>, wait?: boolean): Promise<T>;
+//# sourceMappingURL=stability.d.ts.map

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

@@ -0,0 +1,71 @@
+/**
+ * Post-action network-stability wait.
+ *
+ * Used around fill/click/hover/pressKey/scroll: tracks in-flight requests
+ * from before the action runs (so a request its handler sends synchronously
+ * is seen), then waits until no request has been pending for
+ * ACTION_NETWORK_IDLE_MS, giving up after ACTION_STABILITY_TIMEOUT_MS.
+ */
+import { trackInFlightRequests } from '../../../connection/inFlightRequests.js';
+import { createLogger } from '../../../ui/logging/index.js';
+import { delay } from '../../../utils/async.js';
+import { getErrorMessage } from '../../../utils/errors.js';
+const log = createLogger('dom');
+const ACTION_NETWORK_IDLE_MS = 150;
+const ACTION_STABILITY_TIMEOUT_MS = 2000;
+const STABILITY_CHECK_INTERVAL_MS = 50;
+/**
+ * Run an action and, when it succeeds, wait for the network to settle.
+ *
+ * Requests are tracked from before the action, so one an event handler
+ * starts while the action runs (`onclick = () => fetch(...)`) is waited for.
+ * `Network.enable` is sent without waiting for it: the session's network
+ * collector has already enabled the domain, and Chrome holds the call until
+ * a pending navigation commits, which would otherwise block for as long as
+ * the new page's server takes to answer.
+ *
+ * @param cdp - CDP connection
+ * @param action - Action to run (its result's `success` decides whether to wait)
+ * @param wait - Wait for the network after the action (false for `--no-wait`)
+ * @returns The action's result, once the network is idle or the wait timed out
+ */
+export async function withActionStability(cdp, action, wait = true) {
+    if (!wait)
+        return action();
+    void cdp
+        .send('Network.enable')
+        .catch((error) => log.debug(`Network.enable failed: ${getErrorMessage(error)}`));
+    const requests = trackInFlightRequests(cdp);
+    try {
+        const result = await action();
+        if (result.success)
+            await waitForNetworkIdle(requests);
+        return result;
+    }
+    finally {
+        requests.dispose();
+    }
+}
+/**
+ * Wait until no request has been in flight for ACTION_NETWORK_IDLE_MS since
+ * the wait began (a request the action started counts until it ends), or
+ * until ACTION_STABILITY_TIMEOUT_MS passed.
+ *
+ * @param requests - Tracker started before the action
+ */
+async function waitForNetworkIdle(requests) {
+    const waitStart = Date.now();
+    const deadline = waitStart + ACTION_STABILITY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (requests.count === 0) {
+            const idleTime = Date.now() - Math.max(requests.lastActivity, waitStart);
+            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 with ${requests.count} request(s) in flight, proceeding`);
+}
+//# sourceMappingURL=stability.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * Form submission helpers with smart network waiting.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { SubmitResult } from '../../ipc/protocol/domTypes.js';
+import type { PendingRequest } from '../../telemetry/network.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;
+    /** Requests still running in the session (named when the wait times out) */
+    pendingRequests?: () => Iterable<PendingRequest>;
+}
+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