browser-debugger-cli 0.14.0 → 0.16.0

package/dist/connection/launcher/flagsBuilder.d.ts

@@ -56,5 +56,51 @@ export declare function needsNoSandbox(): boolean;
  * @returns True if running in Docker, false otherwise
  */
 export declare function isDocker(): boolean;
+/**
+ * Remove `HEADLESS` from this process's environment.
+ *
+ * chrome-launcher adds a bare `--headless` whenever the launching process has
+ * a non-empty `HEADLESS` variable (even `0` or `false`), whatever its
+ * `envVars` option says, which would make `--no-headless` launch headless.
+ * The daemon calls this before it launches Chrome.
+ *
+ * @param env - Environment to clean (defaults to `process.env`)
+ */
+export declare function dropLauncherHeadlessEnv(env?: NodeJS.ProcessEnv): void;
+/**
+ * Build Chrome flags array from launch options.
+ *
+ * Uses chrome-launcher default flags as base (unless ignoreDefaultFlags is true)
+ * and layers bdg-specific overrides on top. Headless mode uses the new headless
+ * implementation for better compatibility.
+ *
+ * When running in Docker, automatically adds GPU-disabling flags to work around
+ * graphics limitations in containerized environments.
+ *
+ * Custom flags are passed via the chromeFlags option. The BDG_CHROME_FLAGS env var
+ * is parsed by the CLI and merged into chromeFlags before reaching this function.
+ * Feature lists from all sources end up in one `--disable-features` (and one
+ * `--enable-features`) flag, and each flag appears once.
+ *
+ * @param options - Launch options containing flag preferences
+ * @returns Array of Chrome command-line flags
+ *
+ * @example
+ * ```typescript
+ * // Standard flags
+ * const flags = buildChromeFlags({ port: 9222 });
+ *
+ * // Headless with custom flags
+ * const flags = buildChromeFlags({
+ *   port: 9222,
+ *   headless: true,
+ *   chromeFlags: ['--window-size=1920,1080']
+ * });
+ *
+ * // Docker environment (auto-detects)
+ * const flags = buildChromeFlags({ port: 9222 });
+ * // Includes --disable-gpu, --no-sandbox if in Docker
+ * ```
+ */
 export declare function buildChromeFlags(options: FlagsBuilderOptions): string[];
 //# sourceMappingURL=flagsBuilder.d.ts.map

package/dist/connection/launcher/flagsBuilder.js

@@ -68,6 +68,103 @@ export function isDocker() {
         return false;
     }
 }
+const DISABLE_FEATURES = '--disable-features=';
+const ENABLE_FEATURES = '--enable-features=';
+/**
+ * Flags that bdg merges into one: Chrome reads only the last occurrence of
+ * these comma-separated feature lists, and chrome-launcher's defaults, bdg and
+ * users all pass them. `--disable-blink-features`/`--enable-blink-features`
+ * are not merged (neither bdg nor the defaults pass them), nor is `--js-flags`
+ * (space-separated V8 flags, not a feature list).
+ */
+const FEATURE_LIST_FLAGS = [DISABLE_FEATURES, ENABLE_FEATURES];
+/**
+ * Bare name of a feature-list entry, without a `<Trial` or `:params` suffix.
+ *
+ * @param entry - Entry such as `Foo<Trial` or `Foo:param/1`
+ * @returns Feature name
+ */
+function featureName(entry) {
+    return entry.split(/[<:]/)[0] ?? entry;
+}
+/**
+ * Remove disabled features that are also enabled.
+ *
+ * Chrome lets `--disable-features` win over `--enable-features`, so without
+ * this a user's `--enable-features=MediaRouter` could not re-enable a feature
+ * chrome-launcher disables by default.
+ *
+ * @param features - Merged values per feature-list flag (changed in place)
+ */
+function dropReEnabledFeatures(features) {
+    const enabled = new Set([...(features.get(ENABLE_FEATURES) ?? [])].map(featureName));
+    const disabled = features.get(DISABLE_FEATURES);
+    disabled?.forEach((entry) => {
+        if (enabled.has(featureName(entry)))
+            disabled.delete(entry);
+    });
+}
+/**
+ * Merge every `--disable-features=` (and `--enable-features=`) flag into one
+ * and drop repeated flags.
+ *
+ * Chrome applies only the last occurrence of a feature-list flag, so bdg's or
+ * the user's list would otherwise switch chrome-launcher's defaults back on.
+ * The merged flag keeps the first one's position; its values keep their order
+ * without repeats, and an enabled feature is never also disabled. Only
+ * entries starting with `-` are deduplicated, so positional arguments such as
+ * URLs are passed as given.
+ *
+ * @param flags - Chrome flags in launch order
+ * @returns Flags with at most one flag per feature list and no repeated flags
+ */
+function mergeFeatureFlags(flags) {
+    const features = new Map();
+    const merged = [];
+    for (const flag of flags) {
+        const prefix = FEATURE_LIST_FLAGS.find((p) => flag.startsWith(p));
+        if (prefix) {
+            if (!features.has(prefix))
+                merged.push(prefix);
+            const values = flag.slice(prefix.length).split(',').filter(Boolean);
+            features.set(prefix, new Set([...(features.get(prefix) ?? []), ...values]));
+        }
+        else if (!flag.startsWith('-') || !merged.includes(flag)) {
+            merged.push(flag);
+        }
+    }
+    dropReEnabledFeatures(features);
+    return merged.flatMap((flag) => {
+        const values = features.get(flag);
+        if (!values)
+            return [flag];
+        return values.size > 0 ? [flag + [...values].join(',')] : [];
+    });
+}
+/**
+ * Remove `HEADLESS` from this process's environment.
+ *
+ * chrome-launcher adds a bare `--headless` whenever the launching process has
+ * a non-empty `HEADLESS` variable (even `0` or `false`), whatever its
+ * `envVars` option says, which would make `--no-headless` launch headless.
+ * The daemon calls this before it launches Chrome.
+ *
+ * @param env - Environment to clean (defaults to `process.env`)
+ */
+export function dropLauncherHeadlessEnv(env = process.env) {
+    delete env['HEADLESS'];
+}
+/**
+ * chrome-launcher's default flags (plus its Linux sandbox flag). bdg passes
+ * them itself and tells chrome-launcher to skip its own copy, so each flag
+ * appears once; chrome-launcher adds `--remote-debugging-port`.
+ *
+ * @returns Default flags
+ */
+function defaultFlags() {
+    const flags = chromeLauncher.Launcher.defaultFlags();
+    return process.platform === 'linux' ? [...flags, '--disable-setuid-sandbox'] : flags;
+}
 /**
  * Build Chrome flags array from launch options.
  *
@@ -80,6 +177,8 @@ export function isDocker() {
  *
  * Custom flags are passed via the chromeFlags option. The BDG_CHROME_FLAGS env var
  * is parsed by the CLI and merged into chromeFlags before reaching this function.
+ * Feature lists from all sources end up in one `--disable-features` (and one
+ * `--enable-features`) flag, and each flag appears once.
  *
  * @param options - Launch options containing flag preferences
  * @returns Array of Chrome command-line flags
@@ -101,17 +200,6 @@ export function isDocker() {
  * // Includes --disable-gpu, --no-sandbox if in Docker
  * ```
  */
-/**
- * chrome-launcher's default flags (plus its Linux sandbox flag). bdg passes
- * them itself and tells chrome-launcher to skip its own copy, so each flag
- * appears once; chrome-launcher adds `--remote-debugging-port`.
- *
- * @returns Default flags
- */
-function defaultFlags() {
-    const flags = chromeLauncher.Launcher.defaultFlags();
-    return process.platform === 'linux' ? [...flags, '--disable-setuid-sandbox'] : flags;
-}
 export function buildChromeFlags(options) {
     const baseFlags = options.ignoreDefaultFlags ? [] : defaultFlags();
     const bdgFlags = [
@@ -120,18 +208,14 @@ export function buildChromeFlags(options) {
     ];
     const dockerFlags = isDocker() ? DOCKER_CHROME_FLAGS : [];
     const sandboxFlags = needsNoSandbox() ? ['--no-sandbox'] : [];
-    // Custom flags from CLI option (env var BDG_CHROME_FLAGS is parsed by CLI and passed here)
     const customFlags = options.chromeFlags ?? [];
-    if (options.headless) {
-        return [
-            HEADLESS_FLAG,
-            ...baseFlags,
-            ...bdgFlags,
-            ...dockerFlags,
-            ...sandboxFlags,
-            ...customFlags,
-        ];
-    }
-    return [...baseFlags, ...bdgFlags, ...dockerFlags, ...sandboxFlags, ...customFlags];
+    return mergeFeatureFlags([
+        ...(options.headless ? [HEADLESS_FLAG] : []),
+        ...baseFlags,
+        ...bdgFlags,
+        ...dockerFlags,
+        ...sandboxFlags,
+        ...customFlags,
+    ]);
 }
 //# sourceMappingURL=flagsBuilder.js.map

package/dist/connection/launcher.d.ts

@@ -1,10 +1,11 @@
 import type { LaunchedChrome, Logger } from './types.js';
 import type { Options as ChromeLaunchOptions } from 'chrome-launcher';
+import { ChromeLaunchError } from './errors.js';
 /**
  * Options that control how Chrome is launched for CDP sessions.
  * Extended to support chrome-launcher advanced features.
  */
-export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'connectionPollInterval' | 'maxConnectionRetries' | 'portStrictMode' | 'envVars' | 'handleSIGINT' | 'ignoreDefaultFlags' | 'chromeFlags' | 'chromePath'> {
+export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'connectionPollInterval' | 'maxConnectionRetries' | 'portStrictMode' | 'envVars' | 'ignoreDefaultFlags' | 'chromeFlags' | 'chromePath'> {
     /** Remote debugging port (defaults to 9222 when omitted) */
     port?: number;
     /**
@@ -29,6 +30,11 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
     chromePath?: string;
     /** bdg session directory: recorded as a marker flag on the Chrome command line, and holds the default profile */
     sessionDir?: string | undefined;
+    /**
+     * Ends the launch when aborted (the session was stopped): bdg stops waiting
+     * and kills Chrome as soon as chrome-launcher has spawned it
+     */
+    signal?: AbortSignal | undefined;
 }
 /**
  * Launch Chrome with remote debugging enabled using chrome-launcher.
@@ -42,7 +48,7 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
  *
  * @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
@@ -50,6 +56,32 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
  * Uses chrome-launcher for cross-platform Chrome detection and launching.
  */
 export declare function launchChrome(options?: LaunchOptions): Promise<LaunchedChrome>;
+/**
+ * State of the launch when chrome-launcher rejected.
+ */
+interface LaunchFailureContext {
+    /** Debugging port */
+    port: number;
+    /** Chrome's PID (0 if it was not spawned) */
+    pid: number;
+    /** Whether Chrome was still running when chrome-launcher rejected */
+    chromeAlive: boolean;
+    /** How long chrome-launcher waited for the port to open */
+    readyBudgetMs: number;
+}
+/**
+ * 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 declare function launchFailedError(error: unknown, { port, pid, chromeAlive, readyBudgetMs }: LaunchFailureContext): ChromeLaunchError;
 /**
  * Preferences for the launched profile: bdg's defaults (no translate prompt,
  * no password manager or leak check, whose bubbles capture input) for
@@ -65,4 +97,5 @@ export declare function launchChrome(options?: LaunchOptions): Promise<LaunchedC
  * @throws ChromeLaunchError if prefs file cannot be read or parsed, or prefs are not JSON
  */
 export declare function resolveChromePrefs(options: LaunchOptions): Record<string, unknown>;
+export {};
 //# sourceMappingURL=launcher.d.ts.map

package/dist/connection/launcher.js

@@ -2,12 +2,14 @@ import * as fs from 'fs';
 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, DEFAULT_CHROME_HANDLE_SIGINT, } from '../constants.js';
+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.
  *
@@ -224,7 +312,6 @@ function buildChromeOptions(options) {
     const chromePathOverride = resolveChromeBinary(options);
     return {
         logLevel: options.logLevel ?? DEFAULT_CHROME_LOG_LEVEL,
-        handleSIGINT: options.handleSIGINT ?? DEFAULT_CHROME_HANDLE_SIGINT,
         ignoreDefaultFlags: true,
         chromeFlags: buildChromeFlags(options),
         userDataDir,

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

@@ -12,10 +12,6 @@ export declare const DEFAULT_CDP_PORT = 9222;
  * Default Chrome launcher log level for quiet operation
  */
 export declare const DEFAULT_CHROME_LOG_LEVEL = "silent";
-/**
- * Default SIGINT handling - bdg handles signals, not chrome-launcher
- */
-export declare const DEFAULT_CHROME_HANDLE_SIGINT = false;
 /**
  * Persistent Chrome profile directory path (relative to user home)
  */
@@ -90,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;
@@ -124,6 +120,8 @@ export declare const CHROME_NETWORK_BUFFER_PER_RESOURCE: number;
 export declare const CHROME_POST_DATA_LIMIT: number;
 /** Matches `dom query` and `dom a11y query` list with `--json` and no `--limit` */
 export declare const QUERY_JSON_LIST_LIMIT = 100;
+/** Elements of an array result `dom eval --json` lists (the rest are counted as omitted) */
+export declare const EVAL_JSON_ARRAY_LIMIT = 100;
 /** Matches `dom layout` measures per command (the rest are counted as omitted) */
 export declare const LAYOUT_ELEMENT_LIMIT = 100;
 /**

package/dist/constants.js

@@ -15,10 +15,6 @@ export const DEFAULT_CDP_PORT = 9222;
  * Default Chrome launcher log level for quiet operation
  */
 export const DEFAULT_CHROME_LOG_LEVEL = 'silent';
-/**
- * Default SIGINT handling - bdg handles signals, not chrome-launcher
- */
-export const DEFAULT_CHROME_HANDLE_SIGINT = false;
 /**
  * Persistent Chrome profile directory path (relative to user home)
  */
@@ -122,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;
@@ -165,6 +161,8 @@ export const CHROME_POST_DATA_LIMIT = 1 * 1024 * 1024; // 1MB
 // ============================================================================
 /** Matches `dom query` and `dom a11y query` list with `--json` and no `--limit` */
 export const QUERY_JSON_LIST_LIMIT = 100;
+/** Elements of an array result `dom eval --json` lists (the rest are counted as omitted) */
+export const EVAL_JSON_ARRAY_LIMIT = 100;
 /** Matches `dom layout` measures per command (the rest are counted as omitted) */
 export const LAYOUT_ELEMENT_LIMIT = 100;
 /**

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':