browser-debugger-cli 0.8.0 → 0.9.0

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

@@ -6,11 +6,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { CommandError } from '../../../errors/index.js';
 import { fileNotFoundError, uploadDirectoryError, singleFileInputError, fillableElementNotFoundError, clickableElementNotFoundError, clickTargetDetachedError, unexpectedResponseFormatError, operationFailedError, } from '../../../errors/messages.js';
-import { escapeValueForJS, formatScriptExecutionError, throwIfInvalidSelector, withMultipleMatchesWarning, } from './shared.js';
-import { REACT_FILL_SCRIPT, CLICK_ELEMENT_SCRIPT, isFillResult, isClickResult, } from '../reactEventHelpers.js';
-import { FIND_ELEMENTS_JS, selectorArgsJS } from '../targetNode.js';
+import { escapeValueForJS, formatScriptExecutionError, throwIfInvalidSelector, withMultipleMatchesWarning, withValueMismatchWarning, } from './shared.js';
+import { FILL_READ_BACK_SCRIPT, REACT_FILL_SCRIPT, CLICK_ELEMENT_SCRIPT, isFillResult, isClickResult, } from '../reactEventHelpers.js';
+import { FIND_ELEMENTS_JS, LABEL_CONTROL_JS, selectorArgsJS } from '../targetNode.js';
 import { createLogger } from '../../../ui/logging/index.js';
-import { POINTER_ACTION_DONE, domClickFallbackWarning } from '../../../ui/messages/commands.js';
+import { CLICK_NOT_RECEIVED_WARNING, POINTER_ACTION_DONE, domClickFallbackWarning, } from '../../../ui/messages/commands.js';
 import { getErrorMessage } from '../../../utils/errors.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
 const log = createLogger('dom');
@@ -38,7 +38,12 @@ export async function fillElement(cdp, selector, value, options = {}) {
         }
         if (cdpResponse.result?.value && isFillResult(cdpResponse.result.value)) {
             const result = cdpResponse.result.value;
-            return result.fileInput ? await setFileInput(cdp, selector, value, options) : result;
+            if (!result.fileInput)
+                return withValueMismatchWarning(await withReadBack(cdp, result));
+            const uploaded = await setFileInput(cdp, selector, value, options);
+            return uploaded.success && result.elementType
+                ? { ...uploaded, elementType: result.elementType }
+                : uploaded;
         }
         const err = unexpectedResponseFormatError('FillResult');
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
@@ -52,6 +57,52 @@ export async function fillElement(cdp, selector, value, options = {}) {
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SOFTWARE_ERROR);
     }
 }
+/** How long reading a filled value back may take before it is skipped */
+const READ_BACK_TIMEOUT_MS = 1000;
+/**
+ * Add the read-back of a successful fill ({@link FILL_READ_BACK_SCRIPT}):
+ * `valueMismatch` when the field's value is not the one given. The fill
+ * stands without it when the read-back fails, takes longer than
+ * {@link READ_BACK_TIMEOUT_MS} or finds nothing (a change handler navigated
+ * or replaced the page).
+ *
+ * @param cdp - CDP connection
+ * @param result - Fill result
+ * @returns The result, with `valueMismatch` when the value differs
+ */
+async function withReadBack(cdp, result) {
+    if (!result.success)
+        return result;
+    let timer;
+    const timedOut = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), READ_BACK_TIMEOUT_MS);
+    });
+    const readBack = cdp
+        .send('Runtime.evaluate', {
+        expression: FILL_READ_BACK_SCRIPT,
+        returnByValue: true,
+        awaitPromise: true,
+    })
+        .then((response) => response.result?.value)
+        .catch((error) => {
+        log.debug(`Filled value not read back: ${getErrorMessage(error)}`);
+        return undefined;
+    });
+    const mismatch = await Promise.race([readBack, timedOut]).finally(() => clearTimeout(timer));
+    return isValueMismatch(mismatch) ? { ...result, valueMismatch: mismatch } : result;
+}
+/**
+ * Whether a read-back value is a mismatch.
+ *
+ * @param value - Value from {@link FILL_READ_BACK_SCRIPT}
+ * @returns True for `{ expected, actual }`
+ */
+function isValueMismatch(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return typeof obj['expected'] === 'string' && typeof obj['actual'] === 'string';
+}
 /** Empties a file input as a user removing the selection would (with events). */
 const CLEAR_FILE_INPUT_FUNCTION = `function () {
   this.value = '';
@@ -125,7 +176,7 @@ async function setFileInput(cdp, selector, value, options) {
         return problem;
     try {
         const located = (await cdp.send('Runtime.evaluate', {
-            expression: `(${FIND_ELEMENTS_JS})(${selectorArgsJS(selector)})[${options.index ?? 0}]`,
+            expression: `((el) => (${LABEL_CONTROL_JS})(el) || el)((${FIND_ELEMENTS_JS})(${selectorArgsJS(selector)})[${options.index ?? 0}])`,
             objectGroup: UPLOAD_OBJECT_GROUP,
         }));
         if (located.exceptionDetails)
@@ -213,6 +264,67 @@ export function mouseEvents(action, x, y) {
     ];
     return action === 'double' ? [moved, ...press(1), ...press(2)] : [moved, ...press(1)];
 }
+/**
+ * Page script that stops the press probe installed by CLICK_ELEMENT_SCRIPT
+ * and evaluates to whether the mouse press reached the target.
+ */
+const PRESS_PROBE_READ_SCRIPT = `(() => {
+  const probe = window.__bdgPressProbe;
+  delete window.__bdgPressProbe;
+  if (!probe) return true;
+  probe.stop();
+  return probe.reached;
+})()`;
+/**
+ * Whether the mouse press just dispatched reached the target element.
+ *
+ * Any doubt (no probe, evaluation failure) counts as reached, so only a
+ * press that the page provably never saw is reported.
+ *
+ * @param cdp - CDP connection
+ * @returns False only when the target received no pointerdown/mousedown
+ */
+export async function pressReachedTarget(cdp) {
+    try {
+        const response = (await cdp.send('Runtime.evaluate', {
+            expression: PRESS_PROBE_READ_SCRIPT,
+            returnByValue: true,
+        }));
+        return response.result?.value !== false;
+    }
+    catch (error) {
+        log.debug(`Press probe not read: ${getErrorMessage(error)}`);
+        return true;
+    }
+}
+/**
+ * Dispatch real mouse events for an action, checking after the first press
+ * that the target received it. If dispatching fails first, the press probe
+ * is still removed from the page.
+ *
+ * @param cdp - CDP connection
+ * @param action - What to do
+ * @param x - Page x
+ * @param y - Page y
+ * @returns False if the press never reached the target
+ */
+async function dispatchMouseAction(cdp, action, x, y) {
+    let reached;
+    try {
+        for (const event of mouseEvents(action, x, y)) {
+            await cdp.send('Input.dispatchMouseEvent', event);
+            if (event['type'] === 'mousePressed' && reached === undefined) {
+                reached = await pressReachedTarget(cdp);
+            }
+        }
+    }
+    catch (error) {
+        if (reached === undefined)
+            await pressReachedTarget(cdp);
+        throw error;
+    }
+    return reached ?? true;
+}
 /**
  * Drop the located element from the page without waiting: right after a
  * click on a link, evaluation waits until the new page commits (seconds for a
@@ -244,11 +356,14 @@ async function performClick(cdp, located, action) {
     if (!result.success)
         return result;
     if (hittable && x !== undefined && y !== undefined) {
-        for (const event of mouseEvents(action, x, y)) {
-            await cdp.send('Input.dispatchMouseEvent', event);
-        }
+        const reached = await dispatchMouseAction(cdp, action, x, y);
         releaseClickTarget(cdp);
-        return withMultipleMatchesWarning({ ...result, action, method: 'mouse' }, result.selectedIndex, `${POINTER_ACTION_DONE[action].toLowerCase()} the first visible one`);
+        return withMultipleMatchesWarning({
+            ...result,
+            action,
+            method: 'mouse',
+            ...(!reached && { warning: CLICK_NOT_RECEIVED_WARNING }),
+        }, result.selectedIndex, `${POINTER_ACTION_DONE[action].toLowerCase()} the first visible one`);
     }
     const response = (await cdp.send('Runtime.evaluate', {
         expression: domFallbackScript(action),

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

@@ -4,7 +4,7 @@
  * - `fill.ts`      — fillElement, clickElement
  * - `pressKey.ts`  — pressKeyElement + types
  * - `scroll.ts`    — scrollPage + types
- * - `stability.ts` — waitForActionStability
+ * - `stability.ts` — withActionStability
  * - `shared.ts`    — internal script/error helpers
  *
  * Callers keep importing from `@/commands/dom/formFillHelpers.js` which
@@ -13,5 +13,5 @@
 export { fillElement, clickElement } from './fill.js';
 export { pressKeyElement, type PressKeyOptions, type PressKeyResult, } from './pressKey.js';
 export { scrollPage, type ScrollOptions, type ScrollResult, } from './scroll.js';
-export { waitForActionStability } from './stability.js';
+export { withActionStability } from './stability.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -4,7 +4,7 @@
  * - `fill.ts`      — fillElement, clickElement
  * - `pressKey.ts`  — pressKeyElement + types
  * - `scroll.ts`    — scrollPage + types
- * - `stability.ts` — waitForActionStability
+ * - `stability.ts` — withActionStability
  * - `shared.ts`    — internal script/error helpers
  *
  * Callers keep importing from `@/commands/dom/formFillHelpers.js` which
@@ -13,5 +13,5 @@
 export { fillElement, clickElement } from './fill.js';
 export { pressKeyElement, } from './pressKey.js';
 export { scrollPage, } from './scroll.js';
-export { waitForActionStability } from './stability.js';
+export { withActionStability } from './stability.js';
 //# sourceMappingURL=index.js.map

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

@@ -4,10 +4,11 @@
  * that CDP skips (keypress / input / change / submit).
  */
 import { CommandError } from '../../../errors/index.js';
-import { keyPressFailedError, operationFailedError, unknownKeyError } from '../../../errors/messages.js';
+import { VIA_LABEL_SUFFIX, keyPressFailedError, operationFailedError, unknownKeyError, } from '../../../errors/messages.js';
+import { ELEMENT_IDENTITY_JS } from '../elementInfo.js';
 import { throwIfInvalidSelector, withMultipleMatchesWarning, } from './shared.js';
 import { describeModifiers, getKeyDefinition, impliesShift, MODIFIER_FLAGS, parseModifiers, similarKeyNames, shortcutCommands, } from '../keyMapping.js';
-import { FIND_ELEMENTS_JS, selectorArgsJS } from '../targetNode.js';
+import { FIND_ELEMENTS_JS, LABEL_CONTROL_JS, selectorArgsJS } from '../targetNode.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
 const FOCUS_ELEMENT_SCRIPT = `
 (function(selector, parts, index) {
@@ -29,6 +30,9 @@ const FOCUS_ELEMENT_SCRIPT = `
   } else {
     el = allMatches[0];
   }
+  const labelControl = (${LABEL_CONTROL_JS})(el);
+  const viaLabel = labelControl ? ${JSON.stringify(VIA_LABEL_SUFFIX)} : '';
+  if (labelControl) el = labelControl;
 
   const pageLevel = el === document.body || el === document.documentElement;
   if (!pageLevel) {
@@ -61,7 +65,13 @@ const FOCUS_ELEMENT_SCRIPT = `
     }
   }
 
-  return { success: true, selector: selector, elementType: el.tagName.toLowerCase(), matchCount: allMatches.length };
+  return {
+    success: true,
+    selector: selector,
+    element: (${ELEMENT_IDENTITY_JS})(el),
+    elementType: el.tagName.toLowerCase() + viaLabel,
+    matchCount: allMatches.length
+  };
 })`;
 /** Exit codes and suggestions for focus failures, by reason. */
 const FOCUS_FAILURES = {
@@ -135,6 +145,7 @@ export async function pressKeyElement(cdp, selector, keyName, options = {}) {
             key: keyName,
             times,
             ...(modifierFlags > 0 && { modifiers: describeModifiers(modifierFlags) }),
+            ...(focusResult.element !== undefined && { element: focusResult.element }),
             elementType: focusResult.elementType,
             ...(focusResult.matchCount !== undefined && { matchCount: focusResult.matchCount }),
         }, options.index, 'pressed the key on the first');

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

@@ -6,6 +6,9 @@ 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;

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

@@ -3,6 +3,9 @@
  * 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';
@@ -29,26 +32,20 @@ const SCROLL_TO_ELEMENT_SCRIPT = `
 
   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,
+    element: (${ELEMENT_IDENTITY_JS})(el),
     matchCount: allMatches.length,
     scrolledTo: {
       x: Math.round(window.scrollX),
       y: Math.round(window.scrollY)
     },
-    viewportSize: {
-      width: window.innerWidth,
-      height: window.innerHeight
-    },
+    viewportSize: (${VIEWPORT_SIZE_JS})(window),
     pageSize: {
-      width: document.documentElement.scrollWidth,
-      height: document.documentElement.scrollHeight
+      width: (document.scrollingElement || document.documentElement).scrollWidth,
+      height: (document.scrollingElement || document.documentElement).scrollHeight
     }
   };
 })`;
@@ -56,6 +53,7 @@ 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' });
@@ -81,16 +79,60 @@ const SCROLL_BY_SCRIPT = `
     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
-    },
+    viewportSize: (${VIEWPORT_SIZE_JS})(window),
     pageSize: {
-      width: document.documentElement.scrollWidth,
-      height: document.documentElement.scrollHeight
-    }
+      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;
@@ -164,7 +206,7 @@ export async function scrollPage(cdp, selector, options = {}) {
             };
         }
         if (cdpResponse.result?.value && isScrollResult(cdpResponse.result.value)) {
-            return cdpResponse.result.value;
+            return withNoEffectWarning(cdpResponse.result.value, options);
         }
         return {
             success: false,

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

@@ -3,6 +3,7 @@
  * 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.
  */
@@ -20,6 +21,14 @@ 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.
  */
@@ -30,6 +39,14 @@ export declare function escapeValueForJS(value: string): string;
  * 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

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

@@ -4,7 +4,7 @@
  */
 import { CommandError } from '../../../errors/index.js';
 import { invalidSelectorError } from '../../../errors/messages.js';
-import { multipleMatchesWarning } from '../../../ui/messages/commands.js';
+import { multipleMatchesWarning, valueMismatchWarning } from '../../../ui/messages/commands.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
 import { detectSelectorQuoteDamage } from '../../../utils/shellDetection.js';
 /**
@@ -29,6 +29,19 @@ export function withMultipleMatchesWarning(result, index, action) {
     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.
  */
@@ -81,6 +94,17 @@ export function formatScriptExecutionError(exceptionDetails, selector, operation
     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

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

@@ -1,14 +1,28 @@
 /**
  * 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.
+ * 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';
 /**
- * Wait for the network to settle after an action. Returns when idle for
- * the threshold or after the timeout.
+ * 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 waitForActionStability(cdp: CDPConnection): Promise<void>;
+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

@@ -1,40 +1,71 @@
 /**
  * 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.
+ * 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;
 /**
- * Wait for the network to settle after an action. Returns when idle for
- * the threshold or after the timeout.
+ * 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 waitForActionStability(cdp) {
-    const deadline = Date.now() + ACTION_STABILITY_TIMEOUT_MS;
-    await cdp.send('Network.enable');
+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 {
-        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');
+        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

@@ -3,6 +3,7 @@
  */
 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.
  */
@@ -15,6 +16,8 @@ export interface SubmitOptions {
     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';
 /**