browser-debugger-cli 0.9.0 → 0.11.0

package/dist/commands/shared/startHelpers.js

@@ -17,14 +17,21 @@ import { getSessionName } from '../../session/paths.js';
 import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
 import { escapeControlChars, joinLines } from '../../ui/formatting.js';
 import { createLogger } from '../../ui/logging/index.js';
-import { startNotices } from '../../ui/messages/session.js';
+import { daemonStillExitingHint, daemonStillExitingSuggestion, startNotices, } from '../../ui/messages/session.js';
 import { noActiveSessionMessage } from '../../ui/messages/sessionCommand.js';
-import { delay } from '../../utils/async.js';
+import { delay, waitUntil } from '../../utils/async.js';
 import { getExitCodeForIPCError } from '../../utils/errorMapping.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
 const log = createLogger('bdg');
+/** How long a failed start waits for the daemons it spawned to exit */
+export const SPAWNED_DAEMON_EXIT_WAIT_MS = 3000;
+const DEFAULT_START_DEPS = {
+    launch: launchDaemon,
+    send: sendStartSessionRequest,
+    exitWaitMs: SPAWNED_DAEMON_EXIT_WAIT_MS,
+};
 /**
  * Start a session via the daemon and report the result.
  *
@@ -38,13 +45,69 @@ const log = createLogger('bdg');
 export async function startSessionViaDaemon(url, options, telemetry) {
     process.once('SIGINT', () => reportStartOutcome(interruptedOutcome('SIGINT'), options));
     process.once('SIGTERM', () => reportStartOutcome(interruptedOutcome('SIGTERM'), options));
-    let outcome = await requestSession(url, options, telemetry);
+    reportStartOutcome(await attemptStart(url, options, telemetry), options);
+}
+/**
+ * Start a session, retrying while the previous session shuts down. After a
+ * failure the daemon reported (or a dropped connection), it waits for every
+ * daemon the attempts spawned to exit ({@link afterSpawnedDaemonExit}).
+ *
+ * @param url - Target URL
+ * @param options - Session options
+ * @param telemetry - Telemetry types
+ * @param deps - How to reach the daemon (tests replace it)
+ * @returns Start outcome, ready to report
+ */
+export async function attemptStart(url, options, telemetry, deps = DEFAULT_START_DEPS) {
+    const spawned = [];
+    const attempt = async () => {
+        const outcome = await requestSession(url, options, telemetry, deps);
+        if (!outcome.ok && outcome.spawned)
+            spawned.push(outcome.spawned);
+        return outcome;
+    };
+    let outcome = await attempt();
     const deadline = Date.now() + SHUTDOWN_WAIT_MS;
     while (isShuttingDown(outcome) && Date.now() < deadline) {
         await delay(SHUTDOWN_POLL_MS);
-        outcome = await requestSession(url, options, telemetry);
+        outcome = await attempt();
+    }
+    return afterSpawnedDaemonExit(outcome, spawned, deps.exitWaitMs);
+}
+/**
+ * Let the daemons a failed start spawned finish exiting before the error is
+ * reported: a daemon removes its session files on the way out, and a command
+ * run right after (`bdg sessions`, another start) would otherwise still see
+ * the session as starting. The wait is bounded; a daemon still running after
+ * it is reported (`details.daemonStillRunning`, `daemonPid`, a suggestion).
+ *
+ * @param outcome - Start outcome
+ * @param spawned - Exiting daemons the attempts spawned
+ * @param waitMs - Milliseconds to wait at most for all of them
+ * @returns The failure (without internal fields), with a hint when a daemon did not exit in time
+ */
+export async function afterSpawnedDaemonExit(outcome, spawned, waitMs) {
+    if (outcome.ok)
+        return outcome;
+    const { spawned: _spawned, daemonExiting: _exiting, ...failure } = outcome;
+    if (spawned.length === 0)
+        return failure;
+    if (await waitUntil(() => spawned.every((daemon) => daemon.hasExited()), waitMs)) {
+        return failure;
     }
-    reportStartOutcome(outcome, options);
+    const running = spawned.filter((daemon) => !daemon.hasExited()).pop();
+    const suggestion = daemonStillExitingSuggestion();
+    const previous = failure.details?.['suggestion'];
+    return {
+        ...failure,
+        human: joinLines(failure.human, `${daemonStillExitingHint(running?.pid, waitMs)}; ${suggestion}`),
+        details: {
+            ...failure.details,
+            daemonStillRunning: true,
+            ...(running?.pid !== undefined && { daemonPid: running.pid }),
+            suggestion: typeof previous === 'string' && previous ? `${previous}; ${suggestion}` : suggestion,
+        },
+    };
 }
 /**
  * The outcome of a start interrupted with Ctrl-C (the daemon notices the
@@ -83,9 +146,10 @@ function isShuttingDown(outcome) {
  * @param telemetry - Telemetry types
  * @returns Start outcome
  */
-async function requestSession(url, options, telemetry) {
+async function requestSession(url, options, telemetry, deps) {
+    let spawned;
     try {
-        await launchDaemon();
+        spawned = await deps.launch();
     }
     catch (error) {
         if (error instanceof SessionDirError) {
@@ -101,9 +165,24 @@ async function requestSession(url, options, telemetry) {
         const exitCode = error instanceof DaemonError ? error.exitCode : EXIT_CODES.SOFTWARE_ERROR;
         return { ok: false, error: message, human: genericError(message), exitCode };
     }
+    const outcome = await sendStart(url, options, telemetry, deps.send);
+    return !outcome.ok && outcome.daemonExiting && spawned ? { ...outcome, spawned } : outcome;
+}
+/**
+ * Ask the running daemon to start a session.
+ *
+ * @param url - Target URL
+ * @param options - Session options
+ * @param telemetry - Telemetry types
+ * @param send - Sends the request
+ * @returns Start outcome; `daemonExiting` for a failure the daemon reported
+ *   or a dropped connection, not for a timeout or an unexpected error (the
+ *   daemon may still be starting the session then)
+ */
+async function sendStart(url, options, telemetry, send) {
     try {
         log.debug('Connecting to daemon...');
-        const response = await sendStartSessionRequest(url, filterDefined({
+        const response = await send(url, filterDefined({
             port: options.port,
             timeout: options.timeout,
             telemetry: telemetry.length > 0 ? telemetry : undefined,
@@ -116,8 +195,9 @@ async function requestSession(url, options, telemetry) {
             viewport: options.viewport,
             colorScheme: options.colorScheme,
         }));
-        if (response.status === 'error')
-            return describeStartFailure(response, options);
+        if (response.status === 'error') {
+            return { ...describeStartFailure(response, options), daemonExiting: true };
+        }
         if (!response.data) {
             const message = 'Invalid response from daemon: missing data';
             return {
@@ -147,6 +227,7 @@ async function requestSession(url, options, telemetry) {
                 human: daemonNotRunningError({ suggestStatus: true, suggestRetry: true }),
                 exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                 retryable: true,
+                daemonExiting: true,
             };
         }
         const message = getErrorMessage(error);

package/dist/commands/shared/validation.d.ts

@@ -57,5 +57,16 @@ export declare function consoleLevelOption(value: string): ConsoleLevel;
  * @throws InvalidArgumentError (exit 81) when no type is given
  */
 export declare function eventTypesOption(value: string, previous?: string[]): string[];
+/**
+ * Commander parser for `dom inspect --props`: comma-separated CSS property
+ * names, lowercased except custom properties (`--brand`), which are
+ * case-sensitive; repeated options add up.
+ *
+ * @param value - Raw option value, e.g. "padding-top,color"
+ * @param previous - Names from earlier `--props` options
+ * @returns Property names
+ * @throws InvalidArgumentError (exit 81) when no name is given
+ */
+export declare function cssPropertiesOption(value: string, previous?: string[]): string[];
 export declare function resourceTypeRule(): ValidationRule<Protocol.Network.ResourceType[]>;
 //# sourceMappingURL=validation.d.ts.map

package/dist/commands/shared/validation.js

@@ -158,6 +158,22 @@ export function eventTypesOption(value, previous = []) {
         return [...new Set([...previous, ...types])];
     throw new InvalidArgumentError('Give at least one event type, e.g. click or click,keydown.');
 }
+/**
+ * Commander parser for `dom inspect --props`: comma-separated CSS property
+ * names, lowercased except custom properties (`--brand`), which are
+ * case-sensitive; repeated options add up.
+ *
+ * @param value - Raw option value, e.g. "padding-top,color"
+ * @param previous - Names from earlier `--props` options
+ * @returns Property names
+ * @throws InvalidArgumentError (exit 81) when no name is given
+ */
+export function cssPropertiesOption(value, previous = []) {
+    const names = parseCommaSeparated(value).map((name) => name.startsWith('--') ? name : name.toLowerCase());
+    if (names.length > 0)
+        return [...new Set([...previous, ...names])];
+    throw new InvalidArgumentError('Give at least one CSS property, e.g. color or padding-top,color.');
+}
 function parseCommaSeparated(value) {
     return value
         .split(',')

package/dist/commands.js

@@ -4,6 +4,7 @@ import { registerConsoleCommand } from './commands/console.js';
 import { registerDetailsCommand } from './commands/details.js';
 import { registerFormInteractionCommands } from './commands/dom/formInteraction.js';
 import { registerDomCommands } from './commands/dom/index.js';
+import { registerInstallSkillCommand } from './commands/installSkill.js';
 import { registerNetworkCommands } from './commands/network/index.js';
 import { registerPageCommands } from './commands/page.js';
 import { registerPeekCommand } from './commands/peek.js';
@@ -44,5 +45,7 @@ export const commandRegistry = [
     registerNetworkCommands,
     addCommandGroup('Console Commands:'),
     registerConsoleCommand,
+    addCommandGroup('Agent Setup:'),
+    registerInstallSkillCommand,
 ];
 //# sourceMappingURL=commands.js.map

package/dist/daemon/launcher.d.ts

@@ -6,13 +6,20 @@
  * SocketServer), so concurrent launches are safe: a losing daemon exits and
  * the CLI talks to the winner.
  */
+/** A daemon this process spawned */
+export interface SpawnedDaemon {
+    pid: number | undefined;
+    /** Whether it has exited (from the child process's exit event) */
+    hasExited: () => boolean;
+}
 /**
  * Ensure a daemon is running, spawning one if needed.
  *
+ * @returns The daemon it spawned, or undefined when one was already running
  * @throws DaemonStartupError if the daemon script is missing or the daemon
  *   does not accept connections in time
  */
-export declare function launchDaemon(): Promise<void>;
+export declare function launchDaemon(): Promise<SpawnedDaemon | undefined>;
 /**
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).

package/dist/daemon/launcher.js

@@ -24,13 +24,14 @@ const DAEMON_READY_POLL_MS = 20;
 /**
  * Ensure a daemon is running, spawning one if needed.
  *
+ * @returns The daemon it spawned, or undefined when one was already running
  * @throws DaemonStartupError if the daemon script is missing or the daemon
  *   does not accept connections in time
  */
 export async function launchDaemon() {
     if (await isDaemonAlive()) {
         log.debug('Daemon already running');
-        return;
+        return undefined;
     }
     if (!fs.existsSync(DAEMON_SCRIPT_PATH)) {
         throw new DaemonStartupError(`Daemon script not found at ${DAEMON_SCRIPT_PATH}. Did you run 'npm run build'?`, 'DAEMON_SCRIPT_NOT_FOUND');
@@ -51,6 +52,7 @@ export async function launchDaemon() {
     });
     daemon.unref();
     await waitForDaemonReady(() => exited);
+    return { pid: daemon.pid, hasExited: () => exited };
 }
 /**
  * Check that the session directory can hold the daemon's files before

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

@@ -99,6 +99,13 @@ export declare class Session {
      * @returns Session metadata
      */
     metadata(): SessionStatusMetadata;
+    /**
+     * Record a page emulation changed mid-session, so screenshots restore it
+     * and `bdg status` reports it.
+     *
+     * @param emulation - Viewport and color scheme now emulated
+     */
+    private setEmulation;
     /**
      * Whether stop() has been called.
      *

package/dist/daemon/session/Session.js

@@ -21,6 +21,7 @@ import { getSessionPort } from '../../session/port.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { formatChromeNotice } from '../../ui/messages/chrome.js';
 import { delay } from '../../utils/async.js';
+import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
 import { isProcessAlive } from '../../utils/process.js';
@@ -55,7 +56,10 @@ export class Session {
     config;
     onEnded;
     store = new TelemetryStore();
-    registry = createCommandRegistry(this.store);
+    registry = createCommandRegistry(this.store, {
+        get: () => filterDefined({ viewport: this.config.viewport, colorScheme: this.config.colorScheme }),
+        set: (emulation) => this.setEmulation(emulation),
+    });
     notify = (notice) => log.info(formatChromeNotice(notice));
     chrome = null;
     cdp = null;
@@ -174,6 +178,24 @@ export class Session {
             }),
         };
     }
+    /**
+     * Record a page emulation changed mid-session, so screenshots restore it
+     * and `bdg status` reports it.
+     *
+     * @param emulation - Viewport and color scheme now emulated
+     */
+    setEmulation(emulation) {
+        const { viewport: _viewport, colorScheme: _colorScheme, ...rest } = this.config;
+        this.config = { ...rest, ...emulation };
+        if (!this.started)
+            return;
+        try {
+            writeSessionMetadata(this.metadata());
+        }
+        catch (error) {
+            log.debug(`Session metadata not updated: ${getErrorMessage(error)}`);
+        }
+    }
     /**
      * Whether stop() has been called.
      *

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

@@ -1,10 +1,23 @@
 import type { TelemetryStore } from './TelemetryStore.js';
 import type { CDPConnection } from '../../connection/cdp.js';
 import type { CommandName, CommandSchemas } from '../../ipc/index.js';
+import { type SessionEmulation } from '../../runtime/page/emulation.js';
 type Handler<K extends CommandName> = (cdp: CDPConnection, params: CommandSchemas[K]['requestSchema']) => Promise<CommandSchemas[K]['responseSchema']>;
 export type CommandRegistry = {
     [K in CommandName]: Handler<K>;
 };
-export declare function createCommandRegistry(store: TelemetryStore): CommandRegistry;
+/** The session's page emulation, which `page emulate` reads and changes */
+export interface EmulationState {
+    get: () => SessionEmulation;
+    set: (emulation: SessionEmulation) => void;
+}
+/**
+ * The handlers of the session commands.
+ *
+ * @param store - Telemetry of the session
+ * @param emulation - The session's page emulation
+ * @returns Command registry
+ */
+export declare function createCommandRegistry(store: TelemetryStore, emulation: EmulationState): CommandRegistry;
 export {};
 //# sourceMappingURL=commandRegistry.d.ts.map

package/dist/daemon/session/commandRegistry.js

@@ -1,9 +1,9 @@
-import { CDPConnectionError } from '../../connection/errors.js';
+import { CDPConnectionError, CDPProtocolError } 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 { cdpCallError, 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';
@@ -11,10 +11,11 @@ import { fillElement, clickElement, pressKeyElement, scrollPage, withActionStabi
 import { exceptionSummary } from '../../runtime/dom/formFillHelpers/shared.js';
 import { submitForm } from '../../runtime/dom/formSubmitHelpers.js';
 import { evaluateInFrame, listFrames } from '../../runtime/dom/frames.js';
+import { inspectElement } from '../../runtime/dom/inspect.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 { emulatePage, 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';
@@ -62,6 +63,8 @@ function mapNetworkRequestToPreview(req, withHeaders = false) {
     return filterDefined({
         requestId: req.requestId,
         timestamp: req.timestamp,
+        sentTime: req.sentTime,
+        navigationId: req.navigationId,
         method: req.method,
         url: req.url,
         status: req.status,
@@ -260,9 +263,45 @@ function pageWebSocketUrl(store) {
         throw new CDPConnectionError('No page target');
     return url;
 }
-export function createCommandRegistry(store) {
+/** Chrome's "server error" code, used for failures on the page's state (a missing node, a bad id…) */
+const CDP_SERVER_ERROR = -32000;
+/**
+ * A `bdg cdp` failure that is the caller's: wrong parameters (81), or an
+ * id of a node, target or frame that does not exist (83). Other failures
+ * (internal errors, a detached page) stay software errors.
+ *
+ * @param method - CDP method
+ * @param error - What the call threw
+ * @returns The error to report, or undefined to keep the original
+ */
+function callerError(method, error) {
+    if (!(error instanceof CDPProtocolError))
+        return undefined;
+    const err = cdpCallError(method, error.message);
+    if (error.isRequestError()) {
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    if (error.code === CDP_SERVER_ERROR && err.notFound) {
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    if (error.code === CDP_SERVER_ERROR &&
+        /must be specified|invalid|expected|missing/i.test(error.message)) {
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    return undefined;
+}
+/**
+ * The handlers of the session commands.
+ *
+ * @param store - Telemetry of the session
+ * @param emulation - The session's page emulation
+ * @returns Command registry
+ */
+export function createCommandRegistry(store, emulation) {
     const patternDetector = new PatternDetector();
     const interact = createInteractionRunner(store);
+    /** Frame id behind each index of the last `dom frames` listing */
+    let listedFrameIds;
     return {
         session_peek: async (_cdp, params) => {
             const lastN = calculateLastN(params.lastN);
@@ -360,7 +399,9 @@ export function createCommandRegistry(store) {
             });
         },
         cdp_call: async (cdp, params) => {
-            const result = await withBusyPageRecovery(cdp, cdp.send(params.method, params.params ?? {}));
+            const result = await withBusyPageRecovery(cdp, cdp.send(params.method, params.params ?? {}).catch((error) => {
+                throw callerError(params.method, error) ?? error;
+            }));
             const detectionResult = patternDetector.trackCommand(params.method);
             let hint;
             if (detectionResult.shouldShow && detectionResult.pattern) {
@@ -376,11 +417,21 @@ export function createCommandRegistry(store) {
         },
         dom_eval: async (cdp, params) => params.frame === undefined
             ? evaluateScript(cdp, params.script)
-            : evaluateInFrame(cdp, pageWebSocketUrl(store), params.script, params.frame),
-        dom_frames: async (cdp) => ({ frames: await listFrames(cdp, pageWebSocketUrl(store)) }),
+            : evaluateInFrame(cdp, pageWebSocketUrl(store), params.script, params.frame, listedFrameIds),
+        dom_frames: async (cdp) => {
+            const { frames, frameIds } = await listFrames(cdp, pageWebSocketUrl(store));
+            listedFrameIds = frameIds;
+            return { frames };
+        },
         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)), {
+        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,
+            strict: params.strict,
+        })), params.wait !== false)), {
             detectNoEffect: params.wait !== false && params.action !== 'hover' && params.action !== 'right',
+            reportShown: params.action === 'hover',
+            detectUnsettled: params.wait !== false && params.action !== 'hover',
         }),
         dom_submit: async (cdp, params) => withTriggeredRequestCount(await interact(cdp, async () => onScriptTarget(cdp, params, (target) => submitForm(target.cdp, target.selector, {
             ...filterDefined({
@@ -395,7 +446,7 @@ export function createCommandRegistry(store) {
             index: target.index,
             times: params.times,
             modifiers: params.modifiers,
-        })), params.wait !== false))),
+        })), params.wait !== false)), { reportShown: true, detectUnsettled: 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,
@@ -407,11 +458,16 @@ export function createCommandRegistry(store) {
         })), params.wait !== false))),
         dom_listeners: async (cdp, params) => withBusyPageRecovery(cdp, inspectEventListeners(cdp, params)),
         dom_layout: async (cdp, params) => withBusyPageRecovery(cdp, inspectLayout(cdp, params)),
+        dom_inspect: async (cdp, params) => withBusyPageRecovery(cdp, inspectElement(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 }),
+        page_emulate: async (cdp, params) => {
+            const emulated = await emulatePage(cdp, emulation.get(), params, emulation.set);
+            return { emulated, ...(await pageAppearance(cdp)) };
+        },
         dom_form_discover: async (cdp) => {
             const response = await withBusyPageRecovery(cdp, cdp.send('Runtime.evaluate', {
                 expression: FORM_DISCOVERY_SCRIPT,

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

@@ -1,6 +1,7 @@
 /**
  * Running page interactions (fill, click, submit, pressKey, scroll) one at a
- * time, reporting the dialogs, network requests and page changes they caused.
+ * time, reporting the dialogs, network requests and page changes they caused,
+ * and whether the page was still changing when they returned.
  */
 import type { TelemetryStore } from './TelemetryStore.js';
 import type { CDPConnection } from '../../connection/cdp.js';
@@ -28,6 +29,17 @@ export interface InteractionOptions {
      * whose effect shows in the DOM (click, submit) and that waited for it
      */
     detectNoEffect?: boolean;
+    /**
+     * List the elements it showed (`shown`): for hover and key presses, whose
+     * effect is often a menu, tooltip or new item rather than a message
+     */
+    reportShown?: boolean;
+    /**
+     * Say when the page was still changing as it returned (`settled: false`
+     * with `pending`): for actions that start app transitions (click, key
+     * press) and waited for the network
+     */
+    detectUnsettled?: 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>;
@@ -40,10 +52,11 @@ export type InteractionRunner = <T extends object>(cdp: CDPConnection, action: (
  * from the page (without waiting: during a pending navigation that takes until
  * 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.
+ * triggered (see {@link watchTriggeredRequests}) are added to its result,
+ * and, when asked, what the page was still working on (see
+ * {@link pendingChanges}). 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 and network requests
  * @returns Interaction runner

package/dist/daemon/session/interactions.js

@@ -1,8 +1,9 @@
 /**
  * Running page interactions (fill, click, submit, pressKey, scroll) one at a
- * time, reporting the dialogs, network requests and page changes they caused.
+ * time, reporting the dialogs, network requests and page changes they caused,
+ * and whether the page was still changing when they returned.
  */
-import { watchActionEffects } from '../../runtime/dom/actionEffects.js';
+import { pendingChanges, watchActionEffects } from '../../runtime/dom/actionEffects.js';
 import { UNBIND_TARGET_SCRIPT } from '../../runtime/dom/targetNode.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
@@ -26,10 +27,11 @@ function succeeded(result) {
  * from the page (without waiting: during a pending navigation that takes until
  * 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.
+ * triggered (see {@link watchTriggeredRequests}) are added to its result,
+ * and, when asked, what the page was still working on (see
+ * {@link pendingChanges}). 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 and network requests
  * @returns Interaction runner
@@ -44,17 +46,25 @@ export function createInteractionRunner(store) {
             try {
                 const result = await action();
                 const dialogs = store.dialogs.slice(firstDialog);
-                const changes = succeeded(result)
-                    ? await effects?.collect({
-                        dialogs: dialogs.length,
-                        detectNoEffect: options.detectNoEffect === true,
-                    })
+                if (!succeeded(result))
+                    return { ...result, ...(dialogs.length > 0 && { dialogs }) };
+                const collected = await effects?.collect({
+                    dialogs: dialogs.length,
+                    detectNoEffect: options.detectNoEffect === true,
+                    reportShown: options.reportShown === true,
+                    detectUnsettled: options.detectUnsettled === true,
+                });
+                const { work, ...changes } = collected ?? {};
+                const requests = collectRequests?.();
+                const pending = options.detectUnsettled && work
+                    ? pendingChanges(work, requests?.triggeredRequests)
                     : undefined;
                 return {
                     ...result,
                     ...(dialogs.length > 0 && { dialogs }),
                     ...changes,
-                    ...(succeeded(result) && collectRequests?.()),
+                    ...(pending && { settled: false, pending }),
+                    ...requests,
                 };
             }
             finally {