browser-debugger-cli 0.8.0 → 0.9.0

package/dist/commands/page.d.ts

@@ -1,5 +1,6 @@
 /**
- * `bdg page navigate|reload|back|forward` — move the session's page.
+ * `bdg page navigate|reload|back|forward` — move the session's page;
+ * `bdg page info` — where it is.
  */
 import type { Command } from 'commander';
 /**

package/dist/commands/page.js

@@ -1,12 +1,13 @@
 /**
- * `bdg page navigate|reload|back|forward` — move the session's page.
+ * `bdg page navigate|reload|back|forward` — move the session's page;
+ * `bdg page info` — where it is.
  */
-import { runCommand } from './shared/CommandRunner.js';
+import { noActiveSessionError, runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
 import { javascriptNavigationError } from '../errors/messages.js';
-import { pageNavigate } from '../ipc/client.js';
+import { getStatus, pageNavigate } from '../ipc/client.js';
 import { OutputFormatter } from '../ui/formatting.js';
-import { PAGE_ACTION_DESCRIPTIONS, PAGE_ACTION_DONE } from '../ui/messages/commands.js';
+import { PAGE_ACTION_DESCRIPTIONS, PAGE_ACTION_DONE, PAGE_INFO_DESCRIPTION, pageLoadingWarning, } from '../ui/messages/commands.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { validateUrl } from '../utils/url.js';
 /**
@@ -27,6 +28,8 @@ function formatPageResult(result) {
     ], 8);
     if (result.warning)
         fmt.text(`⚠ ${result.warning}`);
+    if (result.loading)
+        fmt.text(`⚠ ${pageLoadingWarning(result.loading)}`);
     return fmt.build();
 }
 /**
@@ -85,6 +88,32 @@ async function runPageAction(action, options, url) {
         return { success: true, data: response.data };
     }, options, formatPageResult);
 }
+/**
+ * `bdg page info`: URL and title of the session page.
+ *
+ * @param options - Command options
+ */
+async function showPageInfo(options) {
+    await runCommand(async () => {
+        const response = await getStatus();
+        if (response.status === 'error') {
+            return {
+                success: false,
+                error: response.error ?? 'Failed to read the page',
+                exitCode: EXIT_CODES.SOFTWARE_ERROR,
+            };
+        }
+        const page = response.data?.sessionPid ? response.data.pageState : undefined;
+        if (!page)
+            throw noActiveSessionError();
+        return { success: true, data: { url: page.url, title: page.title } };
+    }, options, (page) => new OutputFormatter()
+        .keyValueList([
+        ['URL', page.url],
+        ['Title', page.title],
+    ], 8)
+        .build());
+}
 /**
  * Register the `page` command group.
  *
@@ -93,7 +122,14 @@ async function runPageAction(action, options, url) {
 export function registerPageCommands(program) {
     const page = program
         .command('page')
-        .description('Navigate the session page: navigate <url>, reload, back, forward');
+        .description('The session page: info (URL and title), navigate <url>, reload, back, forward');
+    page
+        .command('info')
+        .description(PAGE_INFO_DESCRIPTION)
+        .addOption(jsonOption())
+        .action(async (options) => {
+        await showPageInfo(options);
+    });
     const withCommon = (command) => command
         .option('--no-wait', 'Return without waiting for the page to load')
         .addOption(jsonOption());

package/dist/commands/peek.js

@@ -3,9 +3,9 @@
  */
 import { runCommand } from './shared/CommandRunner.js';
 import { jsonOption, showBothSectionsWhenBothRequested } from './shared/commonOptions.js';
-import { handleDaemonConnectionError, noteFollowConnected, } from './shared/daemonErrorHandler.js';
+import { noteFollowConnected } from './shared/daemonErrorHandler.js';
 import { fetchPreviewOutput, createErrorResult, } from './shared/dataFetcher.js';
-import { setupFollowMode } from './shared/followMode.js';
+import { followFetchFailure, setupFollowMode, } from './shared/followMode.js';
 import { handleValidationError } from './shared/handleValidationError.js';
 import { MAX_LAST_ITEMS, positiveIntRule, resourceTypeRule } from './shared/validation.js';
 import { filterByResourceType } from '../telemetry/filters.js';
@@ -79,21 +79,14 @@ async function runFollowMode(options, lastN, resourceTypes, baseOptions) {
     const showPreview = async () => {
         const result = await fetchAndFilterPreview(lastN, resourceTypes, peekSection(options));
         if (!result.success) {
-            const errorResult = handleDaemonConnectionError(result.error, {
-                json: options.json,
-                follow: true,
-                retryIntervalMs: 1000,
-                exitCode: result.exitCode,
-            });
-            if (errorResult.shouldExit)
-                process.exit(errorResult.exitCode);
-            return;
+            return followFetchFailure(result, { json: options.json, retryIntervalMs: 1000 });
         }
         noteFollowConnected();
         if (!options.json)
             console.clear();
         const previewOptions = createPreviewOptions(baseOptions, resourceTypes, result.data.unfilteredNetworkCount);
         console.log(formatPreview(result.data.output, previewOptions));
+        return undefined;
     };
     await setupFollowMode(showPreview, {
         startMessage: followingPreviewMessage,

package/dist/commands/sessions.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from 'commander';
+/**
+ * Register the sessions command (lists running default and named sessions).
+ *
+ * @param program - Commander.js Command instance to register commands on
+ */
+export declare function registerSessionsCommand(program: Command): void;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/commands/sessions.js

@@ -0,0 +1,19 @@
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { listRunningSessions } from '../session/sessionList.js';
+import { formatSessionList } from '../ui/formatters/sessions.js';
+/**
+ * Register the sessions command (lists running default and named sessions).
+ *
+ * @param program - Commander.js Command instance to register commands on
+ */
+export function registerSessionsCommand(program) {
+    program
+        .command('sessions')
+        .description('List sessions (default and named) with their state, URL, port and PID, including crashed ones to clean up')
+        .addOption(jsonOption())
+        .action(async (options) => {
+        await runCommand(async () => ({ success: true, data: { sessions: await listRunningSessions() } }), options, formatSessionList);
+    });
+}
+//# sourceMappingURL=sessions.js.map

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/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 */
@@ -218,13 +227,35 @@ 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 `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 +305,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.js

@@ -8,15 +8,17 @@ 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 { noActiveSessionMessage } from '../../ui/messages/sessionCommand.js';
 import { delay } from '../../utils/async.js';
 import { getExitCodeForIPCError } from '../../utils/errorMapping.js';
 import { getErrorMessage } from '../../utils/errors.js';
@@ -111,6 +113,8 @@ 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);
@@ -139,7 +143,7 @@ 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,
@@ -189,7 +193,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 +246,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 +265,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,13 @@ 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[];
 export declare function resourceTypeRule(): ValidationRule<Protocol.Network.ResourceType[]>;
 //# sourceMappingURL=validation.d.ts.map

package/dist/commands/shared/validation.js

@@ -145,16 +145,17 @@ export function consoleLevelOption(value) {
 }
 /**
  * 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 function eventTypesOption(value) {
+export function eventTypesOption(value, previous = []) {
     const types = parseCommaSeparated(value);
     if (types.length > 0)
-        return types;
+        return [...new Set([...previous, ...types])];
     throw new InvalidArgumentError('Give at least one event type, e.g. click or click,keydown.');
 }
 function parseCommaSeparated(value) {

package/dist/commands/start.d.ts

@@ -1,4 +1,34 @@
 import { type Command } from 'commander';
+import type { ColorScheme, ViewportSize } from '../types.js';
+/**
+ * Parsed command-line flags shared by the start subcommands.
+ */
+export interface CollectorOptions {
+    /** Chrome debugging port as provided by the user. */
+    port: string;
+    /** Optional auto-stop timeout (seconds, string form). */
+    timeout?: string;
+    /** Custom Chrome profile directory path. */
+    userDataDir?: string;
+    /** When true, disables default filtering of noisy data. */
+    all?: boolean;
+    /** Maximum response body size in megabytes (default: 5MB). */
+    maxBodySize?: string;
+    /** Launch Chrome in headless mode. Default: true if no display, false if display available. */
+    headless?: boolean;
+    /** WebSocket URL for connecting to existing Chrome instance (skips Chrome launch). */
+    chromeWsUrl?: string;
+    /** Quiet mode - suppress verbose landing page output for AI agents. */
+    quiet?: boolean;
+    /** Print the result as a JSON envelope. */
+    json?: boolean;
+    /** Custom Chrome flags (space-separated string). */
+    chromeFlags?: string;
+    /** Viewport size, e.g. `1280x800`. */
+    viewport?: string;
+    /** `prefers-color-scheme` to emulate: light or dark. */
+    colorScheme?: string;
+}
 /**
  * Expand a leading `~/` in a path to the user's home directory.
  * Chrome itself does not expand `~`, so bdg normalizes it for users.
@@ -16,6 +46,30 @@ export declare function extractUserDataDirFromFlags(flags: string[]): {
     userDataDir: string | undefined;
     rest: string[];
 };
+/**
+ * Apply shared telemetry options to a command
+ *
+ * @param command - Commander.js Command instance to apply options to
+ * @returns The modified Command instance with all telemetry options applied
+ */
+export declare function applyCollectorOptions(command: Command): Command;
+/**
+ * Parse a `--viewport` value: width and height in CSS px joined by `x`
+ * (`1280x800`; `X`, `×` and `,` work too).
+ *
+ * @param value - Option value
+ * @returns Viewport size
+ * @throws CommandError (81) for anything else, or a side outside 1-10000
+ */
+export declare function parseViewport(value: string): ViewportSize;
+/**
+ * Parse a `--color-scheme` value (case-insensitive).
+ *
+ * @param value - Option value
+ * @returns The scheme
+ * @throws CommandError (81) for another value, suggesting the closest one
+ */
+export declare function parseColorScheme(value: string): ColorScheme;
 /**
  * Reject a subcommand typed without its group (`bdg query x` for
  * `bdg dom query x`) before Commander reads it as a start URL with extra
@@ -33,4 +87,13 @@ export declare function assertNotGroupSubcommand(program: Command, argv: string[
  * @returns void
  */
 export declare function registerStartCommands(program: Command): void;
+/**
+ * Options given that only apply to a Chrome bdg launches. `--headless` has a
+ * default, so it counts only when given on the command line.
+ *
+ * @param options - Parsed options
+ * @param program - Command the options were parsed by
+ * @returns The conflicting flags, e.g. ["--port", "--headless"]
+ */
+export declare function launchOptionConflicts(options: CollectorOptions, program: Command): string[];
 //# sourceMappingURL=start.d.ts.map