browser-debugger-cli 0.8.0 → 0.10.0

package/dist/commands/shared/CommandRunner.js

@@ -4,7 +4,7 @@ import { daemonNotRunningError, unknownError, genericError, commandTimedOutError
 import { IPCEarlyCloseError, IPCTimeoutError } from '../../ipc/transport/IPCError.js';
 import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
 import { escapeControlChars } from '../../ui/formatting.js';
-import { STOP_MESSAGES } from '../../ui/messages/session.js';
+import { noActiveSessionMessage, startSessionSuggestion } from '../../ui/messages/sessionCommand.js';
 import { getErrorExitCode, getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /**
@@ -13,7 +13,7 @@ import { EXIT_CODES } from '../../utils/exitCodes.js';
  * @returns Command error (exit 83) with how to start one
  */
 export function noActiveSessionError() {
-    return new CommandError(STOP_MESSAGES.DAEMON_NOT_RUNNING, { suggestion: 'Start a session with: bdg <url>' }, EXIT_CODES.RESOURCE_NOT_FOUND);
+    return new CommandError(noActiveSessionMessage(), { suggestion: startSessionSuggestion() }, EXIT_CODES.RESOURCE_NOT_FOUND);
 }
 /**
  * Execute an async function and output JSON result with proper error handling.
@@ -168,8 +168,8 @@ export async function runCommand(handler, options, formatter) {
         const errorMessage = getErrorMessage(error);
         if (isDaemonConnectionError(error)) {
             if (options.json) {
-                console.log(JSON.stringify(OutputBuilder.buildJsonError(STOP_MESSAGES.DAEMON_NOT_RUNNING, {
-                    suggestion: 'Start a session with: bdg <url>',
+                console.log(JSON.stringify(OutputBuilder.buildJsonError(noActiveSessionMessage(), {
+                    suggestion: startSessionSuggestion(),
                     exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                 }), null, 2));
             }

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

@@ -30,4 +30,8 @@ export declare function showBothSectionsWhenBothRequested(options: {
     network?: boolean;
     console?: boolean;
 }): void;
+/** Help of a `<selectorOrIndex>` argument */
+export declare const SELECTOR_OR_INDEX_ARGUMENT = "CSS selector (searches open shadow roots and same-origin iframes) or numeric index from query results (0-based)";
+/** Help text after `dom query`'s options: what selectors search and what they cannot */
+export declare const SELECTOR_SCOPE_HELP = "\nSelectors search the page, open shadow roots and same-origin iframes (nested ones\nincluded). They cannot reach into closed shadow roots or cross-origin iframes:\nuse bdg dom eval --frame <frame> for those (see bdg dom frames).";
 //# sourceMappingURL=commonOptions.d.ts.map

package/dist/commands/shared/commonOptions.js

@@ -34,4 +34,13 @@ export function showBothSectionsWhenBothRequested(options) {
         options.console = false;
     }
 }
+/** Where selectors search, for the help of commands that take one */
+const SELECTOR_SCOPE = 'searches open shadow roots and same-origin iframes';
+/** Help of a `<selectorOrIndex>` argument */
+export const SELECTOR_OR_INDEX_ARGUMENT = `CSS selector (${SELECTOR_SCOPE}) or numeric index from query results (0-based)`;
+/** Help text after `dom query`'s options: what selectors search and what they cannot */
+export const SELECTOR_SCOPE_HELP = `
+Selectors search the page, open shadow roots and same-origin iframes (nested ones
+included). They cannot reach into closed shadow roots or cross-origin iframes:
+use bdg dom eval --frame <frame> for those (see bdg dom frames).`;
 //# sourceMappingURL=commonOptions.js.map

package/dist/commands/shared/dataFetcher.js

@@ -7,7 +7,7 @@ import { validateIPCResponse } from '../../ipc/index.js';
 import { IPCConnectionError, IPCEarlyCloseError, IPCTimeoutError, } from '../../ipc/transport/IPCError.js';
 import { isConnectionError } from '../../ipc/utils/errors.js';
 import { createLogger } from '../../ui/logging/index.js';
-import { STOP_MESSAGES } from '../../ui/messages/session.js';
+import { noActiveSessionMessage } from '../../ui/messages/sessionCommand.js';
 import { getExitCodeForConnectionError } from '../../utils/errorMapping.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
@@ -42,7 +42,7 @@ export async function fetchPreviewOutput(query = {}) {
         log.debug(`Daemon unreachable: ${getErrorMessage(error)}`);
         return {
             success: false,
-            error: STOP_MESSAGES.DAEMON_NOT_RUNNING,
+            error: noActiveSessionMessage(),
             exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
         };
     }

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

@@ -4,6 +4,25 @@
  * Provides a unified pattern for commands that continuously poll
  * and display updates (like tail -f behavior).
  */
+/** What a refresh asks for: nothing to keep following, or the exit code to stop with */
+export type FollowPoll = {
+    exitCode: number;
+} | undefined;
+/**
+ * Report a failed fetch in follow mode: a lost connection is reported and
+ * retried while the session was seen before, otherwise follow mode stops.
+ *
+ * @param failure - The fetch's error and exit code
+ * @param options - JSON output and the retry interval shown
+ * @returns The exit code to stop with, or undefined to keep following
+ */
+export declare function followFetchFailure(failure: {
+    error: string;
+    exitCode?: number | undefined;
+}, options: {
+    json?: boolean | undefined;
+    retryIntervalMs: number;
+}): FollowPoll;
 /**
  * Options for configuring follow mode behavior.
  */
@@ -24,6 +43,7 @@ export interface FollowModeOptions {
  * - First refresh call (awaited)
  * - Periodic interval-based refresh
  * - SIGINT handler for graceful shutdown
+ * - Stopping with the exit code a refresh returns (e.g. the session is gone)
  *
  * @param refreshFn - Async function to call on each refresh cycle
  * @param options - Configuration options for follow mode
@@ -43,5 +63,5 @@ export interface FollowModeOptions {
  * );
  * ```
  */
-export declare function setupFollowMode(refreshFn: () => Promise<void>, options: FollowModeOptions): Promise<void>;
+export declare function setupFollowMode(refreshFn: () => Promise<FollowPoll>, options: FollowModeOptions): Promise<void>;
 //# sourceMappingURL=followMode.d.ts.map

package/dist/commands/shared/followMode.js

@@ -4,9 +4,29 @@
  * Provides a unified pattern for commands that continuously poll
  * and display updates (like tail -f behavior).
  */
+import { handleDaemonConnectionError } from './daemonErrorHandler.js';
 import { genericError } from '../../errors/messages.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+/**
+ * Report a failed fetch in follow mode: a lost connection is reported and
+ * retried while the session was seen before, otherwise follow mode stops.
+ *
+ * @param failure - The fetch's error and exit code
+ * @param options - JSON output and the retry interval shown
+ * @returns The exit code to stop with, or undefined to keep following
+ */
+export function followFetchFailure(failure, options) {
+    const result = handleDaemonConnectionError(failure.error, {
+        json: options.json,
+        follow: true,
+        retryIntervalMs: options.retryIntervalMs,
+        exitCode: failure.exitCode,
+    });
+    return result.shouldExit
+        ? { exitCode: result.exitCode ?? EXIT_CODES.RESOURCE_NOT_FOUND }
+        : undefined;
+}
 /**
  * Sets up follow mode with periodic refresh and graceful shutdown.
  *
@@ -16,6 +36,7 @@ import { EXIT_CODES } from '../../utils/exitCodes.js';
  * - First refresh call (awaited)
  * - Periodic interval-based refresh
  * - SIGINT handler for graceful shutdown
+ * - Stopping with the exit code a refresh returns (e.g. the session is gone)
  *
  * @param refreshFn - Async function to call on each refresh cycle
  * @param options - Configuration options for follow mode
@@ -37,10 +58,16 @@ import { EXIT_CODES } from '../../utils/exitCodes.js';
  */
 export async function setupFollowMode(refreshFn, options) {
     const { startMessage, stopMessage, intervalMs = 1000 } = options;
+    const stopIfAsked = (poll) => {
+        if (poll)
+            process.exit(poll.exitCode);
+    };
     console.error(startMessage());
-    await refreshFn();
+    stopIfAsked(await refreshFn());
     const intervalId = setInterval(() => {
-        refreshFn().catch((error) => {
+        refreshFn()
+            .then(stopIfAsked)
+            .catch((error) => {
             console.error(genericError(getErrorMessage(error)));
         });
     }, intervalMs);

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

@@ -4,8 +4,8 @@
  *
  * For `CommandError`, emits either a JSON envelope (when `json=true`) or
  * a human-readable message + suggestion, then exits with the error's own
- * exit code. For anything else, prints the message and exits with
- * `INVALID_ARGUMENTS`.
+ * exit code. For anything else, prints the message (as an envelope with
+ * `--json`) and exits with `INVALID_ARGUMENTS`.
  *
  * @param error - Error thrown from validation code
  * @param json - Whether the caller is in `--json` output mode

package/dist/commands/shared/handleValidationError.js

@@ -9,8 +9,8 @@ import { EXIT_CODES } from '../../utils/exitCodes.js';
  *
  * For `CommandError`, emits either a JSON envelope (when `json=true`) or
  * a human-readable message + suggestion, then exits with the error's own
- * exit code. For anything else, prints the message and exits with
- * `INVALID_ARGUMENTS`.
+ * exit code. For anything else, prints the message (as an envelope with
+ * `--json`) and exits with `INVALID_ARGUMENTS`.
  *
  * @param error - Error thrown from validation code
  * @param json - Whether the caller is in `--json` output mode
@@ -33,7 +33,16 @@ export function handleValidationError(error, json) {
         }
         process.exit(error.exitCode);
     }
-    console.error(genericError(error instanceof Error ? error.message : String(error)));
+    const message = error instanceof Error ? error.message : String(error);
+    if (json) {
+        const envelope = OutputBuilder.buildJsonError(message, {
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+        });
+        console.log(JSON.stringify(envelope, null, 2));
+    }
+    else {
+        console.error(genericError(message));
+    }
     process.exit(EXIT_CODES.INVALID_ARGUMENTS);
 }
 //# sourceMappingURL=handleValidationError.js.map

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

@@ -25,6 +25,8 @@ export interface BaseOptions {
     json?: boolean;
     /** Hide tips and hints (`-q`, accepted by every command) */
     quiet?: boolean;
+    /** Named session to act on (`--session`, accepted by every command) */
+    session?: string;
 }
 /**
  * Options for commands with verbose output.
@@ -58,6 +60,8 @@ export interface CleanupOptions {
     removeOutput?: boolean;
     /** Aggressive cleanup - kill all Chrome processes */
     aggressive?: boolean;
+    /** Also delete the named session's directory (profile, logs, port) */
+    purge?: boolean;
 }
 /**
  * Options for commands with raw output mode.
@@ -138,12 +142,17 @@ export type DetailsCommandOptions = BaseOptions & {
 /** Options for DOM query command */
 export type DomQueryCommandOptions = BaseOptions;
 /** Options for DOM get command */
-export type DomGetCommandOptions = BaseOptions & RawOptions & SelectionOptions;
+export type DomGetCommandOptions = BaseOptions & RawOptions & SelectionOptions & {
+    /** All of the element's text instead of its first 500 characters (semantic output) */
+    full?: boolean;
+    /** Which match of the selector (0-based); `--nth` is its alias */
+    index?: number;
+};
 /** Options for DOM screenshot command */
 export type DomScreenshotCommandOptions = BaseOptions & ScreenshotOptions;
 /** Options for DOM eval command */
 export interface DomEvalCommandOptions extends BaseOptions {
-    /** Iframe to evaluate in: index, name/id attribute, or part of the URL */
+    /** Iframe to evaluate in: index, name/id attribute, or part of the name, id or URL */
     frame?: string;
 }
 /** Options for DOM frames command */
@@ -174,6 +183,8 @@ export interface ClickCommandOptions extends BaseOptions, IndexOptions {
     double?: boolean;
     /** Right-click */
     right?: boolean;
+    /** Refuse instead of falling back to DOM events when the mouse can't reach the element */
+    strict?: boolean;
 }
 /**
  * Options for submit command.
@@ -218,13 +229,54 @@ export interface ScrollCommandOptions extends BaseOptions, IndexOptions {
  * Options for `dom listeners`.
  */
 export interface ListenersCommandOptions extends BaseOptions, IndexOptions {
-    /** Only these event types (from --type, comma-separated) */
+    /** Only these event types (from --type, comma-separated, repeatable) */
     type?: string[];
+    /** List every listener of framework roots */
+    all?: boolean;
+}
+/**
+ * Options for `dom layout`.
+ */
+export type LayoutCommandOptions = BaseOptions & IndexOptions;
+/**
+ * Options for `dom inspect`.
+ */
+export interface InspectCommandOptions extends BaseOptions, IndexOptions {
+    /** Child tree depth (0 for none) */
+    tree?: number;
+    /** Child tree rows at most */
+    treeLimit?: number;
+    /** Every non-default property instead of the groups */
+    all?: boolean;
+    /** Only these properties */
+    props?: string[];
+    /** Which declaration sets each shown property */
+    rules?: boolean;
+    /** Every declaration of this property */
+    why?: string;
+    /** `--no-hints` sets false */
+    hints?: boolean;
+}
+/** Options for `bdg dom wait` */
+export interface WaitCommandOptions extends BaseOptions {
+    /** Text a match must contain */
+    text?: string;
+    /** Wait for the matches to be gone */
+    gone?: boolean;
+    /** Only count visible matches */
+    visible?: boolean;
+    /** Wait for document.readyState to be complete */
+    load?: boolean;
+    /** Give up after this many milliseconds */
+    timeout: number;
 }
 /** Options for A11y tree command */
 export type A11yTreeCommandOptions = BaseOptions;
 /** Options for A11y query command */
-export type A11yQueryCommandOptions = BaseOptions;
+export interface A11yQueryCommandOptions extends BaseOptions {
+    /** Matches to list (0 = all) */
+    limit?: number;
+}
 /** Options for A11y describe command */
 export type A11yDescribeCommandOptions = BaseOptions;
 /** Options for CDP command */
@@ -274,9 +326,13 @@ export interface SessionStartOptions {
     json?: boolean | undefined;
     /** Custom Chrome flags (e.g., ['--ignore-certificate-errors']) */
     chromeFlags: string[] | undefined;
+    /** Viewport size to emulate (`--viewport`) */
+    viewport?: ViewportSize | undefined;
+    /** `prefers-color-scheme` to emulate (`--color-scheme`) */
+    colorScheme?: ColorScheme | undefined;
 }
 export type { ConsoleLevel } from '../../types.js';
-import type { ConsoleLevel } from '../../types.js';
+import type { ColorScheme, ConsoleLevel, ViewportSize } from '../../types.js';
 /**
  * Options for console command.
  * Supports smart summary (default), list view (--list), and streaming (--follow).

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

@@ -5,7 +5,48 @@
  * Handles IPC communication with daemon to start browser sessions.
  */
 import type { SessionStartOptions } from './optionTypes.js';
+import { type SpawnedDaemon } from '../../daemon/launcher.js';
+import { startSession as sendStartSessionRequest } from '../../ipc/client.js';
+import { IPCErrorCode, type StartSessionResponseData } from '../../ipc/index.js';
 import type { TelemetryType } from '../../types.js';
+/**
+ * Outcome of a start attempt, printed by {@link reportStartOutcome}.
+ */
+export type StartOutcome = {
+    ok: true;
+    data: StartSessionResponseData;
+} | {
+    ok: false;
+    /** Message for `--json` (no "Error:" prefix) */
+    error: string;
+    /** Full human-readable message */
+    human: string;
+    exitCode: number;
+    /** Daemon's error code (internal: not printed) */
+    errorCode?: IPCErrorCode | undefined;
+    /** Extra fields of the JSON error envelope */
+    details?: Record<string, unknown>;
+    /** The daemon went away mid-request (e.g. the previous session was ending) */
+    retryable?: boolean;
+    /**
+     * The daemon reported the failure or dropped the connection, so it is
+     * exiting (a daemon this start spawned is then waited for)
+     */
+    daemonExiting?: boolean;
+    /** The daemon this attempt spawned, when it is exiting */
+    spawned?: SpawnedDaemon;
+};
+/** How long a failed start waits for the daemons it spawned to exit */
+export declare const SPAWNED_DAEMON_EXIT_WAIT_MS = 3000;
+/** What a start uses to reach the daemon (replaced in tests) */
+export interface StartDeps {
+    /** Spawns the daemon if none runs ({@link launchDaemon}) */
+    launch: () => Promise<SpawnedDaemon | undefined>;
+    /** Sends `start_session_request` */
+    send: typeof sendStartSessionRequest;
+    /** How long a failed start waits for the daemons it spawned to exit */
+    exitWaitMs: number;
+}
 /**
  * Start a session via the daemon and report the result.
  *
@@ -17,4 +58,29 @@ import type { TelemetryType } from '../../types.js';
  * @param telemetry - Array of telemetry types to enable
  */
 export declare function startSessionViaDaemon(url: string, options: SessionStartOptions, telemetry: TelemetryType[]): Promise<never>;
+/**
+ * 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 declare function attemptStart(url: string, options: SessionStartOptions, telemetry: TelemetryType[], deps?: StartDeps): Promise<StartOutcome>;
+/**
+ * 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 declare function afterSpawnedDaemonExit(outcome: StartOutcome, spawned: SpawnedDaemon[], waitMs: number): Promise<StartOutcome>;
 //# sourceMappingURL=startHelpers.d.ts.map

package/dist/commands/shared/startHelpers.js

@@ -8,21 +8,30 @@ import { timeoutError } from './CommandRunner.js';
 import { landingPage } from './landingPage.js';
 import { DaemonError, SessionDirError } from '../../daemon/errors.js';
 import { launchDaemon } from '../../daemon/launcher.js';
-import { LAUNCHED_CHROME_DESCRIPTION, sessionAlreadyRunningError, ALREADY_RUNNING_SUGGESTION, sessionTargetMismatchError, daemonNotRunningError, invalidResponseError, genericError, } from '../../errors/messages.js';
+import { LAUNCHED_CHROME_DESCRIPTION, sessionAlreadyRunningError, alreadyRunningSuggestion, sessionTargetMismatchError, daemonNotRunningError, invalidResponseError, genericError, } from '../../errors/messages.js';
 import { startSession as sendStartSessionRequest } from '../../ipc/client.js';
 import { IPCErrorCode, } from '../../ipc/index.js';
 import { IPCTimeoutError } from '../../ipc/transport/index.js';
 import { isConnectionError } from '../../ipc/utils/errors.js';
+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 { delay } from '../../utils/async.js';
+import { daemonStillExitingHint, daemonStillExitingSuggestion, startNotices, } from '../../ui/messages/session.js';
+import { noActiveSessionMessage } from '../../ui/messages/sessionCommand.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.
  *
@@ -36,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
@@ -81,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) {
@@ -99,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,
@@ -111,9 +192,12 @@ async function requestSession(url, options, telemetry) {
             headless: options.headless,
             chromeWsUrl: options.chromeWsUrl,
             chromeFlags: options.chromeFlags,
+            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 {
@@ -139,10 +223,11 @@ async function requestSession(url, options, telemetry) {
         if (isConnectionError(error)) {
             return {
                 ok: false,
-                error: 'No active session (daemon not running)',
+                error: `${noActiveSessionMessage()} (daemon not running)`,
                 human: daemonNotRunningError({ suggestStatus: true, suggestRetry: true }),
                 exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                 retryable: true,
+                daemonExiting: true,
             };
         }
         const message = getErrorMessage(error);
@@ -189,7 +274,7 @@ function describeStartFailure(response, options) {
             human: sessionAlreadyRunningError(pid, duration ? duration * 1000 : 0, targetUrl),
             exitCode,
             errorCode: response.errorCode,
-            details: { ...details, suggestion: ALREADY_RUNNING_SUGGESTION },
+            details: { ...details, suggestion: alreadyRunningSuggestion() },
         };
     }
     if (response.errorCode === IPCErrorCode.SESSION_TARGET_MISMATCH) {
@@ -242,11 +327,14 @@ function reportStartOutcome(outcome, options) {
     }
     const { data } = outcome;
     const autoStopAt = options.timeout !== undefined ? new Date(Date.now() + options.timeout * 1000) : undefined;
+    const session = getSessionName() ?? undefined;
     if (options.json) {
         const result = {
+            ...(session && { session }),
             targetUrl: data.targetUrl,
             ...(data.targetTitle !== undefined && { targetTitle: data.targetTitle }),
             ...(data.documentStatus !== undefined && { documentStatus: data.documentStatus }),
+            ...(data.loading && { loading: data.loading }),
             port: data.port,
             ...(data.chromePid > 0 ? { chromePid: data.chromePid } : { externalChrome: true }),
             daemonPid: data.daemonPid,
@@ -258,7 +346,9 @@ function reportStartOutcome(outcome, options) {
         const page = {
             url: data.targetUrl,
             ...(data.documentStatus !== undefined && { documentStatus: data.documentStatus }),
+            ...(data.loading && { loading: data.loading }),
             ...(autoStopAt && { autoStopAt }),
+            ...(session && { session }),
         };
         const text = options.quiet
             ? [`Session started: ${data.targetUrl}`, ...startNotices(page)].join('\n')

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

@@ -49,12 +49,24 @@ export declare function screenshotFormatOption(value: string): 'png' | 'jpeg';
 export declare function consoleLevelOption(value: string): ConsoleLevel;
 /**
  * Commander parser for `dom listeners --type`: comma-separated event types
- * (case-sensitive, like `addEventListener`).
+ * (case-sensitive, like `addEventListener`); repeated options add up.
  *
  * @param value - Raw option value, e.g. "click,keydown"
+ * @param previous - Types from earlier `--type` options
  * @returns Event types
  * @throws InvalidArgumentError (exit 81) when no type is given
  */
-export declare function eventTypesOption(value: string): string[];
+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