browser-debugger-cli 0.8.0 → 0.9.0

package/dist/daemon/launcher.js

@@ -12,7 +12,7 @@ import { join } from 'path';
 import { DaemonStartupError, SessionDirError } from './errors.js';
 import { sessionDirIsFileError, sessionDirNotWritableError, socketPathTooLongError, } from '../errors/messages.js';
 import { isDaemonAlive } from '../session/daemonSocket.js';
-import { ensureSessionDir, getSessionDir, getSessionFilePath } from '../session/paths.js';
+import { MAX_DAEMON_SOCKET_PATH_BYTES, ensureSessionDir, getSessionDir, getSessionFilePath, } from '../session/paths.js';
 import { createLogger } from '../ui/logging/index.js';
 import { delay } from '../utils/async.js';
 import { getErrorMessage } from '../utils/errors.js';
@@ -52,13 +52,12 @@ export async function launchDaemon() {
     daemon.unref();
     await waitForDaemonReady(() => exited);
 }
-/** Longest Unix socket path (sun_path is 104 bytes on macOS, 108 on Linux, NUL included) */
-const MAX_SOCKET_PATH = process.platform === 'darwin' ? 103 : 107;
 /**
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file or a too-long path, (82) when not writable
+ * @throws SessionDirError (103) for a file, (81) for a too-long path like a
+ *   named session's, (82) when not writable
  */
 export function assertUsableSessionDir() {
     const dir = getSessionDir();
@@ -68,8 +67,8 @@ export function assertUsableSessionDir() {
     if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory())
         fail(sessionDirIsFileError(dir));
     const socketPath = getSessionFilePath('DAEMON_SOCKET');
-    if (Buffer.byteLength(socketPath) > MAX_SOCKET_PATH) {
-        fail(socketPathTooLongError(socketPath, MAX_SOCKET_PATH));
+    if (Buffer.byteLength(socketPath) > MAX_DAEMON_SOCKET_PATH_BYTES) {
+        fail(socketPathTooLongError(socketPath, MAX_DAEMON_SOCKET_PATH_BYTES), EXIT_CODES.INVALID_ARGUMENTS);
     }
     try {
         ensureSessionDir();

package/dist/daemon/server/SocketServer.js

@@ -2,11 +2,10 @@ import { linkSync, lstatSync, unlinkSync } from 'fs';
 import { createServer } from 'net';
 import { DaemonError } from '../errors.js';
 import { probeDaemonSocket } from '../../session/daemonSocket.js';
+import { MAX_SOCKET_PATH_BYTES } from '../../session/paths.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
-/** Unix socket path limit (sun_path is 104 bytes on macOS incl. NUL; 108 on Linux). */
-const MAX_SOCKET_PATH_BYTES = 103;
 /** Error code thrown when another daemon already owns the socket path. */
 export const DAEMON_ALREADY_RUNNING_CODE = 'DAEMON_ALREADY_RUNNING';
 /**

package/dist/daemon/session/Session.d.ts

@@ -6,6 +6,7 @@
  * separate worker process: the daemon process *is* the session.
  */
 import type { CommandName, CommandSchemas } from '../../ipc/index.js';
+import type { PageLoadingState } from '../../ipc/protocol/commands.js';
 import type { SessionOptions } from '../../ipc/session/lifecycle.js';
 import type { StatusResponseData } from '../../ipc/session/queries.js';
 /** Why a session ended. */
@@ -18,6 +19,8 @@ export interface SessionInfo {
     targetTitle?: string;
     /** HTTP status of the page's main document, when known */
     documentStatus?: number;
+    /** The page had not finished loading when the readiness wait ended */
+    loading?: PageLoadingState;
 }
 /** Session metadata as reported in status responses. */
 export type SessionStatusMetadata = NonNullable<StatusResponseData['sessionMetadata']>;
@@ -50,6 +53,7 @@ export declare class Session {
     private readonly launchAbort;
     private started;
     private documentRequestId;
+    private loading;
     private constructor();
     /**
      * Validate the request and create a session that has not been launched yet.
@@ -115,6 +119,15 @@ export declare class Session {
      * Acquire Chrome, CDP and collectors, checking for a concurrent stop after each step.
      */
     private acquireResources;
+    /**
+     * Choose the port and launch Chrome on it.
+     *
+     * A Chrome left by this session's crashed daemon is reaped first, so the
+     * session gets its remembered port back. If another process took an
+     * automatically chosen port before Chrome could listen on it, another port
+     * is chosen (the taken one now answers, so it is skipped).
+     */
+    private launchOwnChrome;
     /**
      * End the session after its page connection was lost. A launched Chrome
      * still running a moment later means the tab was closed (e.g.

package/dist/daemon/session/Session.js

@@ -5,6 +5,7 @@
  * telemetry collectors and executes session commands directly. There is no
  * separate worker process: the daemon process *is* the session.
  */
+import { ChromeLaunchError } from '../../connection/errors.js';
 import { TelemetryStore } from './TelemetryStore.js';
 import { connectCDP, navigateToTarget } from './cdpSetup.js';
 import { externalChromePort, findPageTarget, setupChromeConnection, } from './chromeConnection.js';
@@ -12,6 +13,8 @@ import { startTelemetryCollectors } from './collectors.js';
 import { createCommandRegistry } from './commandRegistry.js';
 import { teardownSession } from './teardown.js';
 import { CommandError } from '../../errors/index.js';
+import { applySessionEmulation } from '../../runtime/page/emulation.js';
+import { readPageLoadingState } from '../../runtime/page/loadingState.js';
 import { reapOrphanedChrome, removeSessionFiles } from '../../session/cleanup/staleSession.js';
 import { writeSessionMetadata } from '../../session/metadata.js';
 import { getSessionPort } from '../../session/port.js';
@@ -25,6 +28,17 @@ import { validateUrl } from '../../utils/url.js';
 const log = createLogger('session');
 /** How long Chrome gets to exit after the page connection drops, before the end is called a closed tab */
 const CRASH_SETTLE_MS = 500;
+/** Ports tried when automatically chosen ports turn out to be taken */
+const PORT_ATTEMPTS = 3;
+/**
+ * Whether a launch failed because another process holds the port.
+ *
+ * @param error - Launch error
+ * @returns True for a PORT_IN_USE launch error
+ */
+function isPortConflict(error) {
+    return error instanceof ChromeLaunchError && error.issue?.code === 'PORT_IN_USE';
+}
 /**
  * A launch that failed because the session was stopped while starting.
  */
@@ -56,6 +70,7 @@ export class Session {
     launchAbort = new AbortController();
     started = false;
     documentRequestId;
+    loading;
     constructor(config, onEnded) {
         this.config = config;
         this.onEnded = onEnded;
@@ -134,6 +149,7 @@ export class Session {
             targetUrl: target?.url ?? this.config.url,
             ...(target?.title && { targetTitle: target.title }),
             ...(documentStatus !== undefined && { documentStatus }),
+            ...(this.loading && { loading: this.loading }),
         };
     }
     /**
@@ -153,6 +169,8 @@ export class Session {
                 autoStopAt: this.autoStopAt,
                 targetId: target?.id,
                 webSocketDebuggerUrl: target?.webSocketDebuggerUrl,
+                viewport: this.config.viewport,
+                colorScheme: this.config.colorScheme,
             }),
         };
     }
@@ -194,15 +212,14 @@ export class Session {
     async acquireResources() {
         this.store.resetSessionStart();
         const { chromeWsUrl } = this.config;
-        const port = chromeWsUrl
-            ? externalChromePort(chromeWsUrl)
-            : await getSessionPort(this.config.port || undefined);
-        this.config = { ...this.config, port };
-        this.throwIfStopping();
-        if (!this.config.chromeWsUrl) {
-            await reapOrphanedChrome();
+        if (chromeWsUrl) {
+            this.config = { ...this.config, port: externalChromePort(chromeWsUrl) };
+            this.throwIfStopping();
+            this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify);
+        }
+        else {
+            await this.launchOwnChrome();
         }
-        this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify);
         this.throwIfStopping();
         if (this.chrome) {
             await findPageTarget(this.config, this.store, log);
@@ -213,10 +230,40 @@ export class Session {
             signal: this.launchAbort.signal,
         });
         this.throwIfStopping();
+        await applySessionEmulation(this.cdp, this.config);
+        this.throwIfStopping();
         this.cleanupFunctions = await startTelemetryCollectors(this.cdp, this.config, this.store, log);
         this.throwIfStopping();
         this.documentRequestId = await navigateToTarget(this.cdp, this.config, this.store, this.chrome, log);
         this.throwIfStopping();
+        this.loading = await readPageLoadingState(this.cdp, this.store.pendingNetworkRequests.values());
+        this.throwIfStopping();
+    }
+    /**
+     * Choose the port and launch Chrome on it.
+     *
+     * A Chrome left by this session's crashed daemon is reaped first, so the
+     * session gets its remembered port back. If another process took an
+     * automatically chosen port before Chrome could listen on it, another port
+     * is chosen (the taken one now answers, so it is skipped).
+     */
+    async launchOwnChrome() {
+        await reapOrphanedChrome();
+        const explicitPort = this.config.port || undefined;
+        for (let attempt = 1;; attempt++) {
+            this.config = { ...this.config, port: await getSessionPort(explicitPort) };
+            this.throwIfStopping();
+            try {
+                this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify);
+                return;
+            }
+            catch (error) {
+                const retry = !explicitPort && attempt < PORT_ATTEMPTS && isPortConflict(error);
+                if (!retry)
+                    throw error;
+                log.info(`Port ${this.config.port} was taken by another process; choosing another`);
+            }
+        }
     }
     /**
      * End the session after its page connection was lost. A launched Chrome
@@ -282,6 +329,8 @@ function buildConfig(url, port, options) {
             maxBodySize: options.maxBodySize,
             chromeWsUrl: options.chromeWsUrl,
             chromeFlags: options.chromeFlags,
+            viewport: options.viewport,
+            colorScheme: options.colorScheme,
         }),
     };
 }

package/dist/daemon/session/chromeConnection.d.ts

@@ -22,6 +22,15 @@ export declare function setupChromeConnection(config: SessionConfig, telemetrySt
  * @returns Port in the URL, or the protocol default
  */
 export declare function externalChromePort(wsUrl: string): number;
+/**
+ * Chrome flags of a launched Chrome: with `--viewport`, a window of that size
+ * first (so tabs the page opens get it too), then the user's own flags, which
+ * win over it.
+ *
+ * @param config - Session configuration
+ * @returns Flags, or undefined without any
+ */
+export declare function windowSizeFlags(config: SessionConfig): string[] | undefined;
 /**
  * Find the page target of a Chrome that bdg launched.
  *

package/dist/daemon/session/chromeConnection.js

@@ -9,11 +9,12 @@ import { launchChrome } from '../../connection/launcher.js';
 import { HTTP_LOCALHOST } from '../../constants.js';
 import { ConfigError } from '../errors.js';
 import { CommandError } from '../../errors/index.js';
-import { externalBrowserIdMismatchError, externalChromeUnreachableError, externalPageNotFoundError, } from '../../errors/messages.js';
+import { chromeInUseBySessionError, externalBrowserIdMismatchError, externalChromeUnreachableError, externalPageNotFoundError, notDevToolsEndpointError, } from '../../errors/messages.js';
 import { writeChromePid } from '../../session/chrome.js';
+import { findConflictingOwner } from '../../session/chromeOwners.js';
 import { getSessionDir } from '../../session/paths.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
-import { createPageTarget, fetchBrowserWsUrl, fetchCDPTargets } from '../../utils/http.js';
+import { createPageTarget, fetchCDPTargets, probeDevToolsEndpoint } from '../../utils/http.js';
 import { filterDefined } from '../../utils/objects.js';
 /**
  * Setup Chrome connection - either launch new instance or connect to existing.
@@ -71,23 +72,30 @@ async function resolveExternalTarget(wsUrl, config, log) {
     const { hostname, pathname, protocol, port } = new URL(wsUrl);
     const http = { host: hostname, secure: protocol === 'wss:' };
     const endpoint = `${http.secure ? 'https' : 'http'}://${hostname}:${config.port}`;
-    const browserWsUrl = await fetchBrowserWsUrl(config.port, log, http);
-    if (!browserWsUrl)
-        fail(externalChromeUnreachableError(endpoint, http.secure), EXIT_CODES.CDP_CONNECTION_FAILURE);
+    const probe = await probeDevToolsEndpoint(config.port, log, http);
+    if (probe.kind !== 'devtools') {
+        const err = probe.kind === 'not-devtools'
+            ? notDevToolsEndpointError(endpoint)
+            : externalChromeUnreachableError(endpoint, http.secure);
+        fail(err, EXIT_CODES.CDP_CONNECTION_FAILURE);
+    }
+    const browserWsUrl = probe.wsUrl;
     const targets = await fetchCDPTargets(config.port, log, http);
     const targetId = pathname.split('/').pop() ?? '';
     if (!pathname.startsWith(BROWSER_WS_PATH)) {
         const known = targets.find((t) => t.id === targetId);
         if (!known)
             fail(externalPageNotFoundError(targetId, endpoint), EXIT_CODES.RESOURCE_NOT_FOUND);
+        await assertNotOwned(targets, known.id, endpoint);
         return { ...known, webSocketDebuggerUrl: wsUrl };
     }
     if (new URL(browserWsUrl).pathname !== pathname) {
         const actual = withEndpoint(browserWsUrl, protocol, hostname, port);
         fail(externalBrowserIdMismatchError(endpoint, actual), EXIT_CODES.RESOURCE_NOT_FOUND);
     }
-    const page = targets.find((t) => t.type === 'page') ??
-        (await createPageTarget(hostname, config.port, log, http));
+    const firstPage = targets.find((t) => t.type === 'page');
+    await assertNotOwned(targets, firstPage?.id ?? '', endpoint);
+    const page = firstPage ?? (await createPageTarget(hostname, config.port, log, http));
     if (!page)
         fail(externalChromeUnreachableError(endpoint, http.secure), EXIT_CODES.CDP_CONNECTION_FAILURE);
     log.info(`Attaching to page ${page.url} of the external Chrome`);
@@ -96,6 +104,21 @@ async function resolveExternalTarget(wsUrl, config, log) {
         webSocketDebuggerUrl: withEndpoint(page.webSocketDebuggerUrl, protocol, hostname, port),
     };
 }
+/**
+ * Refuse to attach when another running bdg session launched this Chrome or
+ * drives the tab this session would use: taking it over would mix both
+ * sessions' telemetry and let one end the other.
+ *
+ * @param targets - Every target of the Chrome
+ * @param targetId - Tab this session would drive ('' for a tab still to be opened)
+ * @param endpoint - e.g. http://127.0.0.1:9222
+ * @throws CommandError (90) naming the other session
+ */
+async function assertNotOwned(targets, targetId, endpoint) {
+    const owner = await findConflictingOwner(targets.map((t) => t.id), targetId);
+    if (owner)
+        fail(chromeInUseBySessionError(endpoint, owner), EXIT_CODES.RESOURCE_CONFLICT);
+}
 /**
  * A DevTools WebSocket URL from Chrome, reached the way the user's URL is
  * (Chrome reports its own host, e.g. 127.0.0.1, even behind a proxy).
@@ -123,6 +146,20 @@ function withEndpoint(url, protocol, hostname, port) {
 function fail(err, exitCode) {
     throw new CommandError(err.message, { suggestion: err.suggestion }, exitCode);
 }
+/**
+ * Chrome flags of a launched Chrome: with `--viewport`, a window of that size
+ * first (so tabs the page opens get it too), then the user's own flags, which
+ * win over it.
+ *
+ * @param config - Session configuration
+ * @returns Flags, or undefined without any
+ */
+export function windowSizeFlags(config) {
+    if (!config.viewport)
+        return config.chromeFlags;
+    const { width, height } = config.viewport;
+    return [`--window-size=${width},${height}`, ...(config.chromeFlags ?? [])];
+}
 /**
  * Launch a new Chrome instance and record its PID for crash cleanup.
  */
@@ -134,7 +171,7 @@ async function setupLaunchedChrome(config, log) {
         ...filterDefined({
             userDataDir: config.userDataDir,
             headless: config.headless,
-            chromeFlags: config.chromeFlags,
+            chromeFlags: windowSizeFlags(config),
         }),
     });
     log.info(`Chrome launched (PID ${chrome.pid})`);

package/dist/daemon/session/commandRegistry.js

@@ -1,16 +1,24 @@
 import { CDPConnectionError } from '../../connection/errors.js';
 import { PatternDetector } from '../patternDetector.js';
 import { createInteractionRunner } from './interactions.js';
+import { withTriggeredRequestCount } from './triggeredRequests.js';
 import { CommandError } from '../../errors/index.js';
+import { formDiscoveryFailedError } from '../../errors/messages.js';
 import { evaluateScript, withBusyPageRecovery } from '../../runtime/dom/evalHelpers.js';
 import { inspectEventListeners } from '../../runtime/dom/eventListeners.js';
 import { FORM_DISCOVERY_SCRIPT, isRawFormData } from '../../runtime/dom/formDiscovery.js';
-import { fillElement, clickElement, pressKeyElement, scrollPage, waitForActionStability, } from '../../runtime/dom/formFillHelpers/index.js';
+import { fillElement, clickElement, pressKeyElement, scrollPage, withActionStability, } from '../../runtime/dom/formFillHelpers/index.js';
+import { exceptionSummary } from '../../runtime/dom/formFillHelpers/shared.js';
 import { submitForm } from '../../runtime/dom/formSubmitHelpers.js';
 import { evaluateInFrame, listFrames } from '../../runtime/dom/frames.js';
-import { resolveScriptTarget, withUserSelector } from '../../runtime/dom/targetNode.js';
+import { inspectLayout } from '../../runtime/dom/layout.js';
+import { onScriptTarget } from '../../runtime/dom/targetNode.js';
+import { waitForCondition } from '../../runtime/dom/wait.js';
+import { pageAppearance } from '../../runtime/page/emulation.js';
+import { readDocumentReadyState } from '../../runtime/page/loadingState.js';
 import { navigatePage } from '../../runtime/page/navigation.js';
 import { skippedBodyReason } from '../../telemetry/network.js';
+import { sessionCommand } from '../../ui/messages/sessionCommand.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
 import { VERSION } from '../../utils/version.js';
@@ -169,7 +177,7 @@ function findNetworkRequestOrThrow(store, id) {
         store.pendingNetworkRequests.get(id)?.request ??
         (webSocket && webSocketAsRequest(webSocket));
     if (!request) {
-        throw new CommandError(`Network request not found: ${id}`, { suggestion: 'List request ids with: bdg network list' }, EXIT_CODES.RESOURCE_NOT_FOUND);
+        throw new CommandError(`Network request not found: ${id}`, { suggestion: `List request ids with: ${sessionCommand('bdg network list')}` }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
     return request;
 }
@@ -183,13 +191,13 @@ function findNetworkRequestOrThrow(store, id) {
  */
 function findConsoleMessageOrThrow(messages, indexStr) {
     if (!/^\d+$/.test(indexStr)) {
-        throw new CommandError(`Invalid console message index: ${indexStr}`, { suggestion: 'Use a 0-based index from: bdg console --list' }, EXIT_CODES.INVALID_ARGUMENTS);
+        throw new CommandError(`Invalid console message index: ${indexStr}`, { suggestion: `Use a 0-based index from: ${sessionCommand('bdg console --list')}` }, EXIT_CODES.INVALID_ARGUMENTS);
     }
     const index = parseInt(indexStr, 10);
     if (index >= messages.length) {
         throw new CommandError(messages.length === 0
             ? `Console message not found at index: ${indexStr} (no messages captured yet)`
-            : `Console message not found at index: ${indexStr} (available: 0-${messages.length - 1})`, { suggestion: 'List messages with: bdg console --list' }, EXIT_CODES.RESOURCE_NOT_FOUND);
+            : `Console message not found at index: ${indexStr} (available: 0-${messages.length - 1})`, { suggestion: `List messages with: ${sessionCommand('bdg console --list')}` }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
     const message = messages[index];
     if (!message) {
@@ -304,7 +312,7 @@ export function createCommandRegistry(store) {
             }
             return Promise.reject(new Error(`Unknown itemType: ${String(params.itemType)}. Expected 'network' or 'console'.`));
         },
-        session_status: async (_cdp, _params) => {
+        session_status: async (cdp, _params) => {
             const duration = Date.now() - store.sessionStartTime;
             const lastNetworkRequest = store.networkRequests[store.networkRequests.length - 1];
             const lastConsoleMessage = store.consoleMessages[store.consoleMessages.length - 1];
@@ -314,6 +322,7 @@ export function createCommandRegistry(store) {
                 target: {
                     url: store.targetInfo?.url ?? '',
                     title: store.targetInfo?.title ?? '',
+                    ...(await pageAppearance(cdp)),
                 },
                 activeTelemetry: store.activeTelemetry,
                 activity: filterDefined({
@@ -324,7 +333,7 @@ export function createCommandRegistry(store) {
                 }),
                 navigationId: store.getCurrentNavigationId?.() ?? 0,
             };
-            return Promise.resolve(result);
+            return result;
         },
         session_har_data: async (_cdp, _params) => {
             return Promise.resolve({
@@ -342,6 +351,10 @@ export function createCommandRegistry(store) {
             return Promise.resolve({
                 url: targetRequest.url,
                 requestId: targetRequest.requestId,
+                method: targetRequest.method,
+                ...(targetRequest.status !== undefined && { status: targetRequest.status }),
+                ...(targetRequest.statusText && { statusText: targetRequest.statusText }),
+                ...(targetRequest.errorText && { errorText: targetRequest.errorText }),
                 requestHeaders,
                 responseHeaders,
             });
@@ -365,66 +378,40 @@ export function createCommandRegistry(store) {
             ? evaluateScript(cdp, params.script)
             : evaluateInFrame(cdp, pageWebSocketUrl(store), params.script, params.frame),
         dom_frames: async (cdp) => ({ frames: await listFrames(cdp, pageWebSocketUrl(store)) }),
-        dom_fill: async (cdp, params) => interact(cdp, async () => {
-            const target = await resolveScriptTarget(cdp, params);
-            const fillOptions = filterDefined({
-                index: target.index,
-                blur: params.blur,
-                cwd: params.cwd,
-            });
-            const result = withUserSelector(await fillElement(cdp, target.selector, params.value, fillOptions), params.selector);
-            if (result.success && params.wait !== false)
-                await waitForActionStability(cdp);
-            return result;
+        dom_fill: async (cdp, params) => interact(cdp, async () => onScriptTarget(cdp, params, (target) => withActionStability(cdp, () => fillElement(target.cdp, target.selector, params.value, filterDefined({ index: target.index, blur: params.blur, cwd: params.cwd })), params.wait !== false))),
+        dom_click: async (cdp, params) => interact(cdp, async () => onScriptTarget(cdp, params, (target) => withActionStability(cdp, () => clickElement(target.cdp, target.selector, filterDefined({ index: target.index, action: params.action })), params.wait !== false)), {
+            detectNoEffect: params.wait !== false && params.action !== 'hover' && params.action !== 'right',
         }),
-        dom_click: async (cdp, params) => interact(cdp, async () => {
-            const target = await resolveScriptTarget(cdp, params);
-            const clickOptions = filterDefined({ index: target.index, action: params.action });
-            const result = withUserSelector(await clickElement(cdp, target.selector, clickOptions), params.selector);
-            if (result.success && params.wait !== false)
-                await waitForActionStability(cdp);
-            return result;
-        }),
-        dom_submit: async (cdp, params) => interact(cdp, async () => {
-            const target = await resolveScriptTarget(cdp, params);
-            const submitOptions = filterDefined({
+        dom_submit: async (cdp, params) => withTriggeredRequestCount(await interact(cdp, async () => onScriptTarget(cdp, params, (target) => submitForm(target.cdp, target.selector, {
+            ...filterDefined({
                 index: target.index,
                 waitNavigation: params.waitNavigation,
                 waitNetwork: params.waitNetwork,
                 timeout: params.timeout,
-            });
-            return withUserSelector(await submitForm(cdp, target.selector, submitOptions), params.selector);
-        }),
-        dom_press_key: async (cdp, params) => interact(cdp, async () => {
-            const target = await resolveScriptTarget(cdp, params);
-            const pressKeyOptions = filterDefined({
-                index: target.index,
-                times: params.times,
-                modifiers: params.modifiers,
-            });
-            const result = withUserSelector(await pressKeyElement(cdp, target.selector, params.key, pressKeyOptions), params.selector);
-            if (result.success && params.wait !== false)
-                await waitForActionStability(cdp);
-            return result;
-        }),
-        dom_scroll: async (cdp, params) => interact(cdp, async () => {
-            const target = await resolveScriptTarget(cdp, params);
-            const scrollOptions = filterDefined({
-                index: target.index,
-                down: params.down,
-                up: params.up,
-                left: params.left,
-                right: params.right,
-                top: params.top,
-                bottom: params.bottom,
-            });
-            const result = withUserSelector(await scrollPage(cdp, target.selector || undefined, scrollOptions), params.selector);
-            if (result.success && params.wait !== false)
-                await waitForActionStability(cdp);
-            return result;
-        }),
+            }),
+            pendingRequests: () => store.pendingNetworkRequests.values(),
+        })), { detectNoEffect: params.waitNetwork !== 0 || params.waitNavigation === true })),
+        dom_press_key: async (cdp, params) => interact(cdp, async () => onScriptTarget(cdp, params, (target) => withActionStability(cdp, () => pressKeyElement(target.cdp, target.selector, params.key, filterDefined({
+            index: target.index,
+            times: params.times,
+            modifiers: params.modifiers,
+        })), params.wait !== false))),
+        dom_scroll: async (cdp, params) => interact(cdp, async () => onScriptTarget(cdp, params, (target) => withActionStability(cdp, () => scrollPage(target.cdp, target.selector || undefined, filterDefined({
+            index: target.index,
+            down: params.down,
+            up: params.up,
+            left: params.left,
+            right: params.right,
+            top: params.top,
+            bottom: params.bottom,
+        })), params.wait !== false))),
         dom_listeners: async (cdp, params) => withBusyPageRecovery(cdp, inspectEventListeners(cdp, params)),
-        page_navigate: async (cdp, params) => interact(cdp, () => navigatePage(cdp, params.action, filterDefined({ url: params.url, wait: params.wait }))),
+        dom_layout: async (cdp, params) => withBusyPageRecovery(cdp, inspectLayout(cdp, params)),
+        dom_wait: async (cdp, params) => waitForCondition(cdp, params),
+        page_navigate: async (cdp, params) => interact(cdp, () => navigatePage(cdp, params.action, {
+            ...filterDefined({ url: params.url, wait: params.wait }),
+            pendingRequests: () => store.pendingNetworkRequests.values(),
+        }), { reportRequests: false, reportEffects: false }),
         dom_form_discover: async (cdp) => {
             const response = await withBusyPageRecovery(cdp, cdp.send('Runtime.evaluate', {
                 expression: FORM_DISCOVERY_SCRIPT,
@@ -432,7 +419,10 @@ export function createCommandRegistry(store) {
             }));
             const cdpResponse = response;
             if (cdpResponse.exceptionDetails) {
-                throw new Error(`Form discovery failed: ${cdpResponse.exceptionDetails.text}`);
+                const readyState = await readDocumentReadyState(cdp);
+                const loading = readyState !== undefined && readyState !== 'complete';
+                const err = formDiscoveryFailedError(exceptionSummary(cdpResponse.exceptionDetails), readyState);
+                throw new CommandError(err.message, { suggestion: err.suggestion }, loading ? EXIT_CODES.RESOURCE_NOT_FOUND : EXIT_CODES.SOFTWARE_ERROR);
             }
             const rawData = cdpResponse.result?.value;
             if (!isRawFormData(rawData)) {

package/dist/daemon/session/interactions.d.ts

@@ -1,14 +1,36 @@
 /**
  * Running page interactions (fill, click, submit, pressKey, scroll) one at a
- * time, reporting the dialogs they caused.
+ * time, reporting the dialogs, network requests and page changes they caused.
  */
 import type { TelemetryStore } from './TelemetryStore.js';
 import type { CDPConnection } from '../../connection/cdp.js';
-import type { DialogInfo } from '../../ipc/protocol/domTypes.js';
-/** Runs one interaction after the previous one finished */
-export type InteractionRunner = <T extends object>(cdp: CDPConnection, action: () => Promise<T>) => Promise<T & {
+import type { ActionEffects, DialogInfo, TriggeredRequest } from '../../ipc/protocol/domTypes.js';
+/** What an interaction caused besides its own result */
+interface InteractionReport extends ActionEffects {
     dialogs?: DialogInfo[];
-}>;
+    triggeredRequests?: TriggeredRequest[];
+    triggeredRequestsOmitted?: number;
+}
+/** How an interaction is reported */
+export interface InteractionOptions {
+    /**
+     * List the network requests it triggered (default true; off for page
+     * navigation, whose requests are the whole page load)
+     */
+    reportRequests?: boolean;
+    /**
+     * Report navigation and new messages (default true; off for page
+     * navigation, which reports its own page)
+     */
+    reportEffects?: boolean;
+    /**
+     * Say when it had no visible effect (`effect: "none"`): only for actions
+     * whose effect shows in the DOM (click, submit) and that waited for it
+     */
+    detectNoEffect?: boolean;
+}
+/** Runs one interaction after the previous one finished */
+export type InteractionRunner = <T extends object>(cdp: CDPConnection, action: () => Promise<T>, options?: InteractionOptions) => Promise<T & InteractionReport>;
 /**
  * Create the runner for a session's interactions.
  *
@@ -16,12 +38,16 @@ export type InteractionRunner = <T extends object>(cdp: CDPConnection, action: (
  * commands would interleave keystrokes into each other's field, so they are
  * queued. After each one, the bound target (`window.__bdgTarget`) is removed
  * from the page (without waiting: during a pending navigation that takes until
- * the new page commits), and the dialogs it opened are added to its result.
- * Dialogs are attributed by time: one opened by a page timer or a navigation
- * started earlier is reported by whichever interaction is running then.
+ * the new page commits), and the dialogs it opened, what it changed on the
+ * page (see {@link watchActionEffects}) and the network requests it
+ * triggered (see {@link watchTriggeredRequests}) are added to its result.
+ * They are attributed by time: a dialog or request started by a page timer
+ * or a navigation started earlier is reported by whichever interaction is
+ * running then.
  *
- * @param store - Session store recording accepted dialogs
+ * @param store - Session store recording accepted dialogs and network requests
  * @returns Interaction runner
  */
 export declare function createInteractionRunner(store: TelemetryStore): InteractionRunner;
+export {};
 //# sourceMappingURL=interactions.d.ts.map