browser-debugger-cli 0.15.0 → 0.16.0

package/dist/connection/launcher.js

@@ -3,11 +3,13 @@ import * as os from 'os';
 import * as path from 'path';
 import * as chromeLauncher from 'chrome-launcher';
 import { BDG_CHROME_PREFS, DEFAULT_CDP_PORT, CHROME_PROFILE_DIR, DEFAULT_CHROME_LOG_LEVEL, } from '../constants.js';
+import { chromePortNotOpenedMessage } from '../ui/messages/chrome.js';
+import { delay } from '../utils/async.js';
 import { makeDirectory } from '../utils/directories.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { filterDefined } from '../utils/objects.js';
 import { isProcessAlive } from '../utils/process.js';
-import { verifyLaunchedChrome } from './chromeIdentity.js';
+import { launchAbortedError, throwIfLaunchAborted, verifyLaunchedChrome, } from './chromeIdentity.js';
 import { ChromeLaunchError } from './errors.js';
 import { resolveChromeBinary } from './launcher/binaryResolver.js';
 import { buildChromeFlags } from './launcher/flagsBuilder.js';
@@ -27,6 +29,8 @@ import { markStartupLogs, watchStartupExit } from './startupExit.js';
 const CHROME_READY_POLL_MS = 50;
 /** Checks before giving up: 25 s in all, as with chrome-launcher's defaults */
 const CHROME_READY_POLL_ATTEMPTS = 500;
+/** How often an aborted launch checks whether chrome-launcher has spawned Chrome yet */
+const SPAWN_POLL_MS = 10;
 const defaultLogger = {
     info: (msg) => console.error(msg),
     debug: () => { }, // No-op by default
@@ -43,7 +47,7 @@ const defaultLogger = {
  *
  * @param options - Launch configuration options
  * @returns LaunchedChrome instance with PID and kill method
- * @throws ChromeLaunchError if Chrome fails to launch, process dies immediately, or CDP doesn't become available
+ * @throws ChromeLaunchError if Chrome fails to launch, process dies immediately, CDP doesn't become available, or `options.signal` aborts
  * @throws Error if user data directory cannot be created
  *
  * @remarks
@@ -79,13 +83,14 @@ export async function launchChrome(options = {}) {
     logger.debug(`User data directory: ${userDataDir}`);
     applyProfilePreferences(userDataDir, options, logger);
     const chromeOptions = buildChromeOptions({ ...options, port });
+    throwIfLaunchAborted(options.signal);
     const launcher = new chromeLauncher.Launcher(chromeOptions);
     const logs = markStartupLogs(userDataDir);
     const startup = watchStartupExit(() => launcher.chromeProcess, logs, userDataDir);
     try {
         const launchStart = Date.now();
         logger.info('Waiting for Chrome to be ready...');
-        await Promise.race([launcher.launch(), startup.exited]);
+        await launchUnlessAborted(launcher, startup.exited, options.signal);
         startup.stop();
         const launchDurationMs = Date.now() - launchStart;
         logger.info(`✓ Chrome ready (${launchDurationMs}ms)`);
@@ -101,7 +106,7 @@ export async function launchChrome(options = {}) {
                 },
             });
         }
-        await verifyLaunchedChrome({ logs, port, pid: chromeProcessPid });
+        await verifyLaunchedChrome({ logs, port, pid: chromeProcessPid, signal: options.signal });
         logger.info(`Chrome launched successfully (PID: ${chromeProcessPid}, ${launchDurationMs}ms)`);
         return {
             pid: chromeProcessPid,
@@ -117,20 +122,103 @@ export async function launchChrome(options = {}) {
     }
     catch (error) {
         startup.stop();
+        const pid = launcher.chromeProcess?.pid ?? 0;
+        const chromeAlive = pid > 0 && isProcessAlive(pid);
         launcher.kill();
         launcher.destroyTmp();
         if (error instanceof ChromeLaunchError) {
             throw error;
         }
-        throw new ChromeLaunchError(`Failed to launch Chrome: ${getErrorMessage(error)}`, {
-            ...(error instanceof Error && { cause: error }),
-            issue: {
-                code: 'CHROME_LAUNCH_FAILED',
-                context: { port, reason: getErrorMessage(error) },
-            },
+        throw launchFailedError(error, {
+            port,
+            pid,
+            chromeAlive,
+            readyBudgetMs: readyBudgetMs(chromeOptions),
         });
     }
 }
+/**
+ * The error for a launch chrome-launcher rejected.
+ *
+ * A refused connection while Chrome is still running means Chrome did not
+ * open its port within the readiness budget (a slow start, e.g. the first
+ * one on a cold machine): the port was free right before the launch and
+ * nothing answers on it, so it is not a conflict, and Chrome did not crash.
+ *
+ * @param error - chrome-launcher's rejection
+ * @param context - Port, Chrome's PID and liveness, and the readiness budget
+ * @returns CHROME_PORT_NOT_OPENED for a slow start, else CHROME_LAUNCH_FAILED
+ */
+export function launchFailedError(error, { port, pid, chromeAlive, readyBudgetMs }) {
+    const cause = error instanceof Error ? { cause: error } : {};
+    if (chromeAlive && isConnectionRefused(error)) {
+        return new ChromeLaunchError(chromePortNotOpenedMessage(pid, port, readyBudgetMs), {
+            ...cause,
+            issue: { code: 'CHROME_PORT_NOT_OPENED', context: { port, pid, waitedMs: readyBudgetMs } },
+        });
+    }
+    return new ChromeLaunchError(`Failed to launch Chrome: ${getErrorMessage(error)}`, {
+        ...cause,
+        issue: { code: 'CHROME_LAUNCH_FAILED', context: { port, reason: getErrorMessage(error) } },
+    });
+}
+/**
+ * Whether an error is a refused TCP connection.
+ *
+ * @param error - Error to check
+ * @returns True for ECONNREFUSED
+ */
+function isConnectionRefused(error) {
+    return error?.code === 'ECONNREFUSED';
+}
+/**
+ * How long chrome-launcher waits for Chrome's debugging port to open.
+ *
+ * @param chromeOptions - chrome-launcher options
+ * @returns Poll interval times the number of polls
+ */
+function readyBudgetMs(chromeOptions) {
+    return ((chromeOptions.connectionPollInterval ?? CHROME_READY_POLL_MS) *
+        (chromeOptions.maxConnectionRetries ?? CHROME_READY_POLL_ATTEMPTS));
+}
+/**
+ * Run chrome-launcher's launch (spawn Chrome, wait for its port to open),
+ * ending early when Chrome exits or `signal` aborts.
+ *
+ * chrome-launcher cannot be cancelled: after an abort its port poller keeps
+ * running, bdg just stops waiting for it. An abort can arrive before
+ * chrome-launcher has spawned Chrome (it first checks whether the port
+ * answers), so this waits until Chrome is spawned or the launch has ended
+ * without one; the caller's kill then reaches that Chrome.
+ *
+ * @param launcher - chrome-launcher instance, not launched yet
+ * @param exited - Rejects when Chrome exits during startup
+ * @param signal - The launch's abort signal
+ * @throws ChromeLaunchError if `signal` aborts (before or during the launch)
+ * @throws Error from chrome-launcher or `exited`
+ */
+async function launchUnlessAborted(launcher, exited, signal) {
+    throwIfLaunchAborted(signal);
+    let settled = false;
+    const launching = launcher.launch().finally(() => {
+        settled = true;
+    });
+    let onAbort = () => { };
+    const aborted = new Promise((resolve) => {
+        onAbort = () => resolve('aborted');
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+        if ((await Promise.race([launching, exited, aborted])) !== 'aborted')
+            return;
+    }
+    finally {
+        signal?.removeEventListener('abort', onAbort);
+    }
+    while (!launcher.chromeProcess && !settled)
+        await delay(SPAWN_POLL_MS);
+    throw launchAbortedError();
+}
 /**
  * Get the default persistent user-data-dir path.
  *

package/dist/connection/typed-cdp.d.ts

@@ -18,9 +18,10 @@ import type { Protocol } from 'devtools-protocol/types/protocol.js';
  * Extract parameter type from a CDP command.
  *
  * If command has no parameters, returns empty object type.
- * If command has single parameter array, returns first element.
+ * If command has a single parameter (required, or optional when all its
+ * fields are), returns its type.
  */
-type CommandParams<T extends keyof ProtocolMapping.Commands> = ProtocolMapping.Commands[T]['paramsType'] extends [infer P] ? P : ProtocolMapping.Commands[T]['paramsType'] extends [] ? Record<string, never> : never;
+type CommandParams<T extends keyof ProtocolMapping.Commands> = ProtocolMapping.Commands[T]['paramsType'] extends [] ? Record<string, never> : ProtocolMapping.Commands[T]['paramsType'] extends [(infer P)?] ? NonNullable<P> : never;
 /**
  * Extract return type from a CDP command.
  */

package/dist/constants.d.ts

@@ -86,7 +86,7 @@ export declare const OBJECT_EXPANSION_FAILURE_THRESHOLD = 5;
  */
 export declare const MAX_RESPONSE_SIZE: number;
 /**
- * Total size of the response bodies a session keeps (100MB)
+ * Total size of the request and response bodies a session keeps (100MB)
  * Past this the oldest bodies are replaced by a placeholder; their requests stay
  */
 export declare const MAX_TOTAL_BODY_BYTES: number;

package/dist/constants.js

@@ -118,7 +118,7 @@ export const OBJECT_EXPANSION_FAILURE_THRESHOLD = 5;
  */
 export const MAX_RESPONSE_SIZE = 5 * 1024 * 1024; // 5MB
 /**
- * Total size of the response bodies a session keeps (100MB)
+ * Total size of the request and response bodies a session keeps (100MB)
  * Past this the oldest bodies are replaced by a placeholder; their requests stay
  */
 export const MAX_TOTAL_BODY_BYTES = 100 * 1024 * 1024;

package/dist/daemon/SessionController.d.ts

@@ -41,7 +41,8 @@ export declare class SessionController {
     stopActiveSession(): Promise<boolean>;
     /**
      * Error fields for a request that needs the session when there is none:
-     * still starting (85), or none at all.
+     * still starting (85), or none at all (also while an abandoned start is
+     * torn down).
      *
      * @returns Error message, plus exit code and suggestion while starting
      */
@@ -78,15 +79,19 @@ export declare class SessionController {
      * Execute a session command (dom_*, cdp_call, session_details, ...).
      *
      * @param request - Command request
+     * @param abandoned - Aborted when the requesting client disconnects
      * @returns Command response, forwarding exit code and suggestion on failure
      */
-    command(request: ClientRequestUnion): Promise<unknown>;
+    command(request: ClientRequestUnion, abandoned?: AbortSignal): Promise<unknown>;
     /**
      * Start a session, or report the one already running.
      *
-     * A start whose client disconnects (Ctrl-C) is abandoned: the session is
-     * stopped, whether it is still launching or has just started, since nobody
-     * learns that it exists.
+     * A start whose client disconnects (Ctrl-C, or a client killed without a
+     * clean disconnect) is abandoned: the session is stopped, whether it is
+     * still launching or has just started, since nobody learns that it exists.
+     * From then on the daemon reports itself shutting down (a new start gets
+     * the retryable `SESSION_SHUTTING_DOWN`, status shows the session ending),
+     * not starting, while Chrome is torn down.
      *
      * @param request - Start session request
      * @param abandoned - Aborted when the requesting client disconnects

package/dist/daemon/SessionController.js

@@ -149,12 +149,13 @@ export class SessionController {
     }
     /**
      * Error fields for a request that needs the session when there is none:
-     * still starting (85), or none at all.
+     * still starting (85), or none at all (also while an abandoned start is
+     * torn down).
      *
      * @returns Error message, plus exit code and suggestion while starting
      */
     noSessionError() {
-        if (!this.launching)
+        if (!this.launching || this.closing)
             return { error: noActiveSessionMessage() };
         return {
             error: STARTING_ERROR,
@@ -190,7 +191,7 @@ export class SessionController {
         };
         const base = { type: 'status_response', sessionId: request.sessionId };
         if (!this.session || this.session.stopRequested()) {
-            if (this.launching) {
+            if (this.launching && !this.closing) {
                 data.starting = { url: this.launching.url, since: this.launching.since };
             }
             if (this.session || this.closing)
@@ -250,6 +251,7 @@ export class SessionController {
                         },
                         currentNavigationId: data.currentNavigationId,
                         ...(data.pageCrashedAt !== undefined && { pageCrashedAt: data.pageCrashedAt }),
+                        ...(data.downloads && { downloads: data.downloads }),
                         partial: true,
                     },
                 },
@@ -282,9 +284,10 @@ export class SessionController {
      * Execute a session command (dom_*, cdp_call, session_details, ...).
      *
      * @param request - Command request
+     * @param abandoned - Aborted when the requesting client disconnects
      * @returns Command response, forwarding exit code and suggestion on failure
      */
-    async command(request) {
+    async command(request, abandoned) {
         const name = request.type.slice(0, -'_request'.length);
         const base = { type: `${name}_response`, sessionId: request.sessionId };
         if (!this.session) {
@@ -293,7 +296,7 @@ export class SessionController {
         const { sessionId: _sessionId, type: _type, ...params } = request;
         try {
             const execute = this.session.execute.bind(this.session);
-            const data = await withTimeout(execute(name, params), commandTimeoutMs(name, params), 'Command');
+            const data = await withTimeout(execute(name, params, abandoned), commandTimeoutMs(name, params), 'Command');
             return { ...base, status: 'ok', data };
         }
         catch (error) {
@@ -303,9 +306,12 @@ export class SessionController {
     /**
      * Start a session, or report the one already running.
      *
-     * A start whose client disconnects (Ctrl-C) is abandoned: the session is
-     * stopped, whether it is still launching or has just started, since nobody
-     * learns that it exists.
+     * A start whose client disconnects (Ctrl-C, or a client killed without a
+     * clean disconnect) is abandoned: the session is stopped, whether it is
+     * still launching or has just started, since nobody learns that it exists.
+     * From then on the daemon reports itself shutting down (a new start gets
+     * the retryable `SESSION_SHUTTING_DOWN`, status shows the session ending),
+     * not starting, while Chrome is torn down.
      *
      * @param request - Start session request
      * @param abandoned - Aborted when the requesting client disconnects
@@ -330,6 +336,7 @@ export class SessionController {
         this.launching = launching;
         const stopAbandoned = () => {
             log.info('Client disconnected during start; stopping the session');
+            this.closing = true;
             void launching.session?.stop('normal');
         };
         abandoned?.addEventListener('abort', stopAbandoned, { once: true });

package/dist/daemon/ipcServer.js

@@ -196,7 +196,7 @@ export class IPCServer {
      */
     async route(message, disconnected) {
         if (isCommandRequest(message.type)) {
-            return this.controller.command(message);
+            return this.controller.command(message, disconnected);
         }
         switch (message.type) {
             case 'handshake_request':

package/dist/daemon/launcher.d.ts

@@ -11,6 +11,11 @@ export interface SpawnedDaemon {
     pid: number | undefined;
     /** Whether it has exited (from the child process's exit event) */
     hasExited: () => boolean;
+    /**
+     * Tell it to shut down (SIGTERM, unless it has exited): it ends what it
+     * hosts and exits. For a start interrupted before its request was sent.
+     */
+    stop: () => void;
 }
 /**
  * Ensure a daemon is running, spawning one if needed.

package/dist/daemon/launcher.js

@@ -58,7 +58,14 @@ export async function launchDaemon() {
     });
     daemon.unref();
     await waitForDaemonReady(() => exited);
-    return { pid: daemon.pid, hasExited: () => exited };
+    return {
+        pid: daemon.pid,
+        hasExited: () => exited,
+        stop: () => {
+            if (!exited)
+                daemon.kill('SIGTERM');
+        },
+    };
 }
 /** How long a daemon that lost its socket gets to end its session before it is killed */
 const UNREACHABLE_DAEMON_EXIT_MS = 8000;

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

@@ -39,6 +39,7 @@ export declare class Session {
     private readonly onEnded;
     private readonly store;
     private readonly registry;
+    private readonly captures;
     private readonly notify;
     private chrome;
     private cdp;
@@ -85,12 +86,15 @@ export declare class Session {
      * {@link CRASH_SAFE_CDP} methods); others fail with exit 107 instead of
      * waiting for a page that cannot answer. Commands that may change the page
      * drop `dom inspect`'s kept matched rules ({@link withMatchedStylesReset}).
+     * Page commands run once a screenshot running before them has put the
+     * page's emulation back ({@link CaptureGate}).
      *
      * @param name - Command name
      * @param params - Command parameters
+     * @param abandoned - Aborted when the requesting client disconnects
      * @returns Command result
      */
-    execute<K extends CommandName>(name: K, params: CommandSchemas[K]['requestSchema']): Promise<CommandSchemas[K]['responseSchema']>;
+    execute<K extends CommandName>(name: K, params: CommandSchemas[K]['requestSchema'], abandoned?: AbortSignal): Promise<CommandSchemas[K]['responseSchema']>;
     /**
      * Summary of this session for start responses.
      *

package/dist/daemon/session/Session.js

@@ -7,6 +7,7 @@
  */
 import { ChromeLaunchError } from '../../connection/errors.js';
 import { TelemetryStore } from './TelemetryStore.js';
+import { CaptureGate, TELEMETRY_READS } from './captureGate.js';
 import { connectCDP, navigateToTarget } from './cdpSetup.js';
 import { externalChromePort, findPageTarget, setupChromeConnection, } from './chromeConnection.js';
 import { startTelemetryCollectors } from './collectors.js';
@@ -40,11 +41,7 @@ const PORT_ATTEMPTS = 3;
  * send raw CDP. Every other command needs the page and fails at once.
  */
 const RUN_ON_CRASHED_PAGE = new Set([
-    'session_peek',
-    'session_details',
-    'session_status',
-    'session_har_data',
-    'session_network_headers',
+    ...TELEMETRY_READS,
     'page_navigate',
     'cdp_call',
 ]);
@@ -83,6 +80,7 @@ export class Session {
         get: () => filterDefined({ viewport: this.config.viewport, colorScheme: this.config.colorScheme }),
         set: (emulation) => this.setEmulation(emulation),
     });
+    captures = new CaptureGate();
     notify = (notice) => log.info(formatChromeNotice(notice));
     chrome = null;
     cdp = null;
@@ -155,12 +153,15 @@ export class Session {
      * {@link CRASH_SAFE_CDP} methods); others fail with exit 107 instead of
      * waiting for a page that cannot answer. Commands that may change the page
      * drop `dom inspect`'s kept matched rules ({@link withMatchedStylesReset}).
+     * Page commands run once a screenshot running before them has put the
+     * page's emulation back ({@link CaptureGate}).
      *
      * @param name - Command name
      * @param params - Command parameters
+     * @param abandoned - Aborted when the requesting client disconnects
      * @returns Command result
      */
-    execute(name, params) {
+    execute(name, params, abandoned) {
         if (!this.cdp || !this.started || this.stopping) {
             return Promise.reject(new Error('No active session'));
         }
@@ -176,7 +177,7 @@ export class Session {
         }
         const handler = this.registry[name];
         const cdp = this.cdp;
-        return withMatchedStylesReset(cdp, name, () => handler(cdp, params));
+        return this.captures.run(name, () => withMatchedStylesReset(cdp, name, () => handler(cdp, params, abandoned)));
     }
     /**
      * Summary of this session for start responses.
@@ -315,7 +316,7 @@ export class Session {
             this.config = { ...this.config, port: await getSessionPort(explicitPort) };
             this.throwIfStopping();
             try {
-                this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify);
+                this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify, this.launchAbort.signal);
                 return;
             }
             catch (error) {

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

@@ -1,4 +1,5 @@
 import type { DialogInfo } from '../../ipc/protocol/domTypes.js';
+import type { TrackedDownload } from '../../telemetry/downloads.js';
 import type { NavigationEvent } from '../../telemetry/navigation.js';
 import type { PendingRequest } from '../../telemetry/network.js';
 import type { NetworkEvictions } from '../../telemetry/networkRetention.js';
@@ -23,6 +24,10 @@ export declare class TelemetryStore {
     readonly websocketConnections: WebSocketConnection[];
     /** JavaScript dialogs accepted during the session */
     readonly dialogs: DialogInfo[];
+    /** Downloads that began during the session, oldest first, updated as they progress */
+    readonly downloads: TrackedDownload[];
+    /** Set while downloads do not go where bdg meant them to (refused, or not redirected) */
+    downloadsWarning: string | undefined;
     activeTelemetry: TelemetryType[];
     /** When the page's renderer crashed (epoch ms); undefined while the page is alive */
     pageCrashedAt: number | undefined;

package/dist/daemon/session/TelemetryStore.js

@@ -20,6 +20,10 @@ export class TelemetryStore {
     websocketConnections = [];
     /** JavaScript dialogs accepted during the session */
     dialogs = [];
+    /** Downloads that began during the session, oldest first, updated as they progress */
+    downloads = [];
+    /** Set while downloads do not go where bdg meant them to (refused, or not redirected) */
+    downloadsWarning = undefined;
     activeTelemetry = [];
     /** When the page's renderer crashed (epoch ms); undefined while the page is alive */
     pageCrashedAt;

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

@@ -0,0 +1,59 @@
+/**
+ * A screenshot changes the page's emulation for its capture (pixel ratio,
+ * touch, viewport, scrollbars) and puts it back once the capture ended. Its
+ * client may be gone long before that: interrupted (Ctrl-C), killed, or timed
+ * out by the daemon's command timeout. Page commands therefore run only once
+ * the captures before them are done, restore included, so no command, from
+ * any client, sees the capture's emulation. Commands that read only the
+ * telemetry run at once. The wait counts toward the command's own timeout
+ * (30 s), like any time the command takes.
+ */
+import type { CommandName } from '../../ipc/index.js';
+/** Commands that read only what the session collected, never the page */
+export declare const TELEMETRY_READS: readonly CommandName[];
+/**
+ * How long a page command waits for a capture before it runs anyway. A
+ * capture of a very tall page takes a few seconds; one that never ends (CDP
+ * calls have no timeout) must not stall the session. A capture waits for the
+ * one before it without this limit (bounded by its command timeout): run
+ * during it, it would record that capture's emulation as the page's own and
+ * put that back.
+ */
+export declare const CAPTURE_WAIT_MS = 15000;
+/**
+ * Orders page commands after the captures before them.
+ */
+export declare class CaptureGate {
+    private readonly waitMs;
+    private capture;
+    /**
+     * @param waitMs - How long a command waits for a capture at most
+     */
+    constructor(waitMs?: number);
+    /**
+     * Run a command: at once when it reads only the telemetry, else once the
+     * capture running before it has ended (or, unless it is a capture itself,
+     * {@link waitMs} passed). A
+     * capture is waited for by the commands after it until it ends, however it
+     * ends.
+     *
+     * @param name - Command name
+     * @param command - The command
+     * @returns Its result
+     */
+    run<T>(name: CommandName, command: () => Promise<T>): Promise<T>;
+    /**
+     * Wait for the running capture, if any: until it ends for a capture, else
+     * at most {@link waitMs}.
+     *
+     * @param isCapture - Whether the waiting command is a capture
+     */
+    private captureEnded;
+    /**
+     * Make a capture the one later commands wait for.
+     *
+     * @param result - The capture's result
+     */
+    private track;
+}
+//# sourceMappingURL=captureGate.d.ts.map

package/dist/daemon/session/captureGate.js

@@ -0,0 +1,96 @@
+/**
+ * A screenshot changes the page's emulation for its capture (pixel ratio,
+ * touch, viewport, scrollbars) and puts it back once the capture ended. Its
+ * client may be gone long before that: interrupted (Ctrl-C), killed, or timed
+ * out by the daemon's command timeout. Page commands therefore run only once
+ * the captures before them are done, restore included, so no command, from
+ * any client, sees the capture's emulation. Commands that read only the
+ * telemetry run at once. The wait counts toward the command's own timeout
+ * (30 s), like any time the command takes.
+ */
+import { settledWithin } from '../../runtime/dom/evalHelpers.js';
+import { createLogger } from '../../ui/logging/index.js';
+const log = createLogger('session');
+/** Commands that read only what the session collected, never the page */
+export const TELEMETRY_READS = [
+    'session_peek',
+    'session_details',
+    'session_status',
+    'session_har_data',
+    'session_network_headers',
+];
+const IGNORES_CAPTURE = new Set(TELEMETRY_READS);
+/**
+ * How long a page command waits for a capture before it runs anyway. A
+ * capture of a very tall page takes a few seconds; one that never ends (CDP
+ * calls have no timeout) must not stall the session. A capture waits for the
+ * one before it without this limit (bounded by its command timeout): run
+ * during it, it would record that capture's emulation as the page's own and
+ * put that back.
+ */
+export const CAPTURE_WAIT_MS = 15_000;
+/** Command that changes the page's emulation until it ends */
+const CAPTURE_COMMAND = 'dom_screenshot';
+/**
+ * Orders page commands after the captures before them.
+ */
+export class CaptureGate {
+    waitMs;
+    capture;
+    /**
+     * @param waitMs - How long a command waits for a capture at most
+     */
+    constructor(waitMs = CAPTURE_WAIT_MS) {
+        this.waitMs = waitMs;
+    }
+    /**
+     * Run a command: at once when it reads only the telemetry, else once the
+     * capture running before it has ended (or, unless it is a capture itself,
+     * {@link waitMs} passed). A
+     * capture is waited for by the commands after it until it ends, however it
+     * ends.
+     *
+     * @param name - Command name
+     * @param command - The command
+     * @returns Its result
+     */
+    run(name, command) {
+        if (IGNORES_CAPTURE.has(name))
+            return command();
+        const isCapture = name === CAPTURE_COMMAND;
+        const result = this.captureEnded(isCapture).then(command);
+        if (isCapture)
+            this.track(result);
+        return result;
+    }
+    /**
+     * Wait for the running capture, if any: until it ends for a capture, else
+     * at most {@link waitMs}.
+     *
+     * @param isCapture - Whether the waiting command is a capture
+     */
+    async captureEnded(isCapture) {
+        const capture = this.capture;
+        if (!capture)
+            return;
+        if (isCapture)
+            return capture;
+        const ended = await settledWithin(capture, this.waitMs);
+        if (!ended.settled)
+            log.info(`Capture still running after ${this.waitMs} ms; not waiting`);
+    }
+    /**
+     * Make a capture the one later commands wait for.
+     *
+     * @param result - The capture's result
+     */
+    track(result) {
+        const ended = result.then(() => undefined, () => undefined);
+        this.capture = ended;
+        void ended.then(() => {
+            if (this.capture === ended)
+                this.capture = undefined;
+        });
+    }
+}
+//# sourceMappingURL=captureGate.js.map

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

@@ -12,9 +12,24 @@ import type { Logger } from '../../ui/logging/index.js';
 /**
  * Setup Chrome connection - either launch new instance or connect to existing.
  *
+ * @param config - Session configuration
+ * @param telemetryStore - Store receiving the target info
+ * @param log - Logger
+ * @param notify - Receives notices about an external Chrome
+ * @param signal - Ends a launch at once when aborted (the session was stopped)
  * @returns Launched Chrome instance (null if connecting to external Chrome)
  */
-export declare function setupChromeConnection(config: SessionConfig, telemetryStore: TelemetryStore, log: Logger, notify: NoticeSink<ChromeNoticeCode>): Promise<LaunchedChrome | null>;
+export declare function setupChromeConnection(config: SessionConfig, telemetryStore: TelemetryStore, log: Logger, notify: NoticeSink<ChromeNoticeCode>, signal?: AbortSignal): Promise<LaunchedChrome | null>;
+/**
+ * Browser-level DevTools WebSocket URL of the session's Chrome: a launched
+ * Chrome's, or for `--chrome-ws-url` the URL itself when it is browser-level,
+ * else the one Chrome reports, reached the way the user's URL is.
+ *
+ * @param config - Session configuration (port resolved)
+ * @param log - Logger
+ * @returns The URL, or null when Chrome does not answer `/json/version`
+ */
+export declare function browserWebSocketUrl(config: SessionConfig, log: Logger): Promise<string | null>;
 /**
  * Debugging port of an external Chrome, taken from its WebSocket URL.
  *