browser-debugger-cli 0.11.0 → 0.13.0

package/dist/commands/peek.js

@@ -8,9 +8,12 @@ import { fetchPreviewOutput, createErrorResult, } from './shared/dataFetcher.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 { CommandError } from '../errors/index.js';
+import { intervalWithoutFollowError } from '../errors/messages.js';
 import { filterByResourceType } from '../telemetry/filters.js';
 import { buildPreviewJsonData, formatPreview, } from '../ui/formatters/preview.js';
 import { followingPreviewMessage, stoppedFollowingPreviewMessage } from '../ui/messages/preview.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
 function parseOptions(options) {
     const lastN = positiveIntRule({
         name: '--last',
@@ -20,7 +23,17 @@ function parseOptions(options) {
         allowZeroForAll: true,
     }).validate(options.last);
     const resourceTypes = resourceTypeRule().validate(options.type);
-    return { lastN, resourceTypes };
+    if (options.interval !== undefined && !options.follow) {
+        const err = intervalWithoutFollowError();
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    const interval = positiveIntRule({
+        name: '--interval',
+        min: 100,
+        max: 60000,
+        default: 1000,
+    }).validate(options.interval);
+    return { lastN, resourceTypes, interval };
 }
 /**
  * Data section selected by `--network` / `--console`, if any.
@@ -75,11 +88,12 @@ function createPreviewOptions(base, resourceTypes, unfilteredCount) {
     }
     return options;
 }
-async function runFollowMode(options, lastN, resourceTypes, baseOptions) {
+async function runFollowMode(options, parsed, baseOptions) {
+    const { lastN, resourceTypes, interval } = parsed;
     const showPreview = async () => {
         const result = await fetchAndFilterPreview(lastN, resourceTypes, peekSection(options));
         if (!result.success) {
-            return followFetchFailure(result, { json: options.json, retryIntervalMs: 1000 });
+            return followFetchFailure(result, { json: options.json, retryIntervalMs: interval });
         }
         noteFollowConnected();
         if (!options.json)
@@ -91,9 +105,51 @@ async function runFollowMode(options, lastN, resourceTypes, baseOptions) {
     await setupFollowMode(showPreview, {
         startMessage: followingPreviewMessage,
         stopMessage: stoppedFollowingPreviewMessage,
-        intervalMs: 1000,
+        intervalMs: interval,
     });
 }
+/**
+ * Parse the options, reporting an invalid one and exiting.
+ *
+ * @param options - Peek options
+ * @returns Parsed options
+ */
+function parsePeekOptions(options) {
+    try {
+        return parseOptions(options);
+    }
+    catch (error) {
+        handleValidationError(error, options.json ?? false);
+    }
+}
+/**
+ * How the preview is shown.
+ *
+ * @param options - Peek options
+ * @param lastN - Items to show
+ * @returns Preview options
+ */
+function previewDisplayOptions(options, lastN) {
+    return {
+        json: options.json,
+        network: options.network,
+        console: options.console,
+        last: lastN,
+        verbose: options.verbose,
+        follow: options.follow,
+    };
+}
+/**
+ * Watch the session data (`peek --follow`, and the deprecated `tail`).
+ *
+ * @param options - Peek options (follow implied)
+ */
+export async function followPreview(options) {
+    const following = { ...options, follow: true };
+    showBothSectionsWhenBothRequested(following);
+    const parsed = parsePeekOptions(following);
+    await runFollowMode(following, parsed, previewDisplayOptions(following, parsed.lastN));
+}
 export function registerPeekCommand(program) {
     program
         .command('peek')
@@ -103,6 +159,7 @@ export function registerPeekCommand(program) {
         .option('-n, --network', 'Show only network requests', false)
         .option('-c, --console', 'Show only console messages', false)
         .option('-f, --follow', 'Watch for updates (like tail -f)', false)
+        .option('--interval <ms>', 'Refresh interval of --follow in ms, 100-60000 (default: 1000)')
         .option('--last <count>', 'Show last N items, 0 for all', '10')
         .option('--type <types>', 'Filter network requests by resource type (comma-separated: Document,XHR,Fetch,etc.)')
         .action(async (options) => {
@@ -110,26 +167,11 @@ export function registerPeekCommand(program) {
         if (options.network && !options.json) {
             console.error('Note: "bdg peek --network" is deprecated. Use "bdg network list" for enhanced filtering.');
         }
-        let lastN;
-        let resourceTypes;
-        try {
-            const parsed = parseOptions(options);
-            lastN = parsed.lastN;
-            resourceTypes = parsed.resourceTypes;
-        }
-        catch (error) {
-            handleValidationError(error, options.json ?? false);
-        }
-        const baseOptions = {
-            json: options.json,
-            network: options.network,
-            console: options.console,
-            last: lastN,
-            verbose: options.verbose,
-            follow: options.follow,
-        };
+        const parsed = parsePeekOptions(options);
+        const { lastN, resourceTypes } = parsed;
+        const baseOptions = previewDisplayOptions(options, lastN);
         if (options.follow) {
-            await runFollowMode(options, lastN, resourceTypes, baseOptions);
+            await runFollowMode(options, parsed, baseOptions);
             return;
         }
         await runCommand(async () => {

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

@@ -28,8 +28,11 @@ export declare function noteFollowConnected(): void;
  * Handle daemon connection errors with consistent formatting and behavior.
  *
  * Outside follow mode the command exits. In follow mode, a session that never
- * answered exits too (there is nothing to follow, exit 83); a session that
- * goes away is reported once and retried until a new one starts.
+ * answered exits too (there is nothing to follow, exit 83), and so does one
+ * that ends while followed (no session any more, exit 83), so a follower
+ * running in the background finds out. Other failures (a busy page, a
+ * timeout) are retried: reported once in text, and on every failed refresh
+ * in JSON, one object per line.
  *
  * @param error - Error message to display
  * @param options - Error handling options

package/dist/commands/shared/daemonErrorHandler.js

@@ -4,7 +4,7 @@
 import { sessionUnavailableSuggestion } from '../../errors/messages.js';
 import { genericError } from '../../errors/messages.js';
 import { OutputBuilder } from '../../ui/OutputBuilder.js';
-import { connectionLostRetryMessage, connectionLostStopHintMessage, } from '../../ui/messages/preview.js';
+import { connectionLostRetryMessage, connectionLostStopHintMessage, followedSessionEndedMessage, } from '../../ui/messages/preview.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /** Follow-mode state: whether a session ever answered, and whether its loss was reported */
 const followState = { connected: false, lossReported: false };
@@ -20,8 +20,11 @@ export function noteFollowConnected() {
  * Handle daemon connection errors with consistent formatting and behavior.
  *
  * Outside follow mode the command exits. In follow mode, a session that never
- * answered exits too (there is nothing to follow, exit 83); a session that
- * goes away is reported once and retried until a new one starts.
+ * answered exits too (there is nothing to follow, exit 83), and so does one
+ * that ends while followed (no session any more, exit 83), so a follower
+ * running in the background finds out. Other failures (a busy page, a
+ * timeout) are retried: reported once in text, and on every failed refresh
+ * in JSON, one object per line.
  *
  * @param error - Error message to display
  * @param options - Error handling options
@@ -29,22 +32,30 @@ export function noteFollowConnected() {
  */
 export function handleDaemonConnectionError(error, options) {
     const { json = false, follow = false, retryIntervalMs = 1000, exitCode = EXIT_CODES.RESOURCE_NOT_FOUND, } = options;
-    const exits = !follow || !followState.connected;
-    if (exits || !followState.lossReported) {
+    const sessionGone = exitCode === EXIT_CODES.RESOURCE_NOT_FOUND;
+    const exits = !follow || !followState.connected || sessionGone;
+    const message = follow && followState.connected && sessionGone ? followedSessionEndedMessage() : error;
+    if (exits || json || !followState.lossReported) {
         if (json) {
             const suggestion = exits ? sessionUnavailableSuggestion(exitCode) : undefined;
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(error, { exitCode, ...(suggestion && { suggestion }) }), null, 2));
+            const envelope = OutputBuilder.buildJsonError(message, {
+                exitCode,
+                ...(suggestion && { suggestion }),
+            });
+            console.log(follow ? JSON.stringify(envelope) : JSON.stringify(envelope, null, 2));
         }
         else {
-            console.error(genericError(error));
+            console.error(genericError(message));
         }
     }
     if (exits)
         return { shouldExit: true, exitCode };
     if (!followState.lossReported) {
         const retryMessage = retryIntervalMs >= 1000 ? `${retryIntervalMs / 1000}s` : `${retryIntervalMs}ms`;
-        console.error(connectionLostRetryMessage(new Date().toISOString(), retryMessage));
-        console.error(connectionLostStopHintMessage());
+        if (!json) {
+            console.error(connectionLostRetryMessage(new Date().toISOString(), retryMessage));
+            console.error(connectionLostStopHintMessage());
+        }
         followState.lossReported = true;
     }
     return { shouldExit: false };

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

@@ -47,18 +47,26 @@ export declare function fetchPreviewData(query?: PreviewQuery): Promise<FetchRes
  * Fetch all captured network requests from daemon.
  *
  * @param withHeaders - Include request/response headers (needed by header filters)
- * @returns Requests or a fetch error
+ * @returns Requests, and when the page crashed (while it is not loaded
+ *   again), or a fetch error
  */
-export declare function fetchNetworkRequests(withHeaders?: boolean): Promise<FetchResult<NetworkRequest[]>>;
+export declare function fetchNetworkRequests(withHeaders?: boolean): Promise<FetchResult<{
+    requests: NetworkRequest[];
+    pageCrashedAt: number | undefined;
+}>>;
 /**
  * Fetch all console messages from daemon.
  *
- * @returns Messages (with their session-wide index) and the navigation id of
- *   the page currently loaded
+ * @returns Messages (with their session-wide index), the navigation id of
+ *   the page currently loaded, how many of the oldest messages the session
+ *   dropped at its limit and when the page crashed (while it is not loaded
+ *   again)
  */
 export declare function fetchConsoleMessages(): Promise<FetchResult<{
     messages: ConsoleMessage[];
     currentNavigationId: number | undefined;
+    dropped: number;
+    pageCrashedAt: number | undefined;
 }>>;
 interface ErrorResult {
     success: false;

package/dist/commands/shared/dataFetcher.js

@@ -90,19 +90,25 @@ export async function fetchPreviewData(query = {}) {
  * Fetch all captured network requests from daemon.
  *
  * @param withHeaders - Include request/response headers (needed by header filters)
- * @returns Requests or a fetch error
+ * @returns Requests, and when the page crashed (while it is not loaded
+ *   again), or a fetch error
  */
 export async function fetchNetworkRequests(withHeaders = false) {
     const result = await fetchPreviewData({ lastN: 0, only: 'network', withHeaders });
     if (!result.success)
         return result;
-    return { success: true, data: result.data.network };
+    return {
+        success: true,
+        data: { requests: result.data.network, pageCrashedAt: result.data.output.pageCrashedAt },
+    };
 }
 /**
  * Fetch all console messages from daemon.
  *
- * @returns Messages (with their session-wide index) and the navigation id of
- *   the page currently loaded
+ * @returns Messages (with their session-wide index), the navigation id of
+ *   the page currently loaded, how many of the oldest messages the session
+ *   dropped at its limit and when the page crashed (while it is not loaded
+ *   again)
  */
 export async function fetchConsoleMessages() {
     const result = await fetchPreviewData({ lastN: 0, only: 'console' });
@@ -113,6 +119,8 @@ export async function fetchConsoleMessages() {
         data: {
             messages: result.data.console,
             currentNavigationId: result.data.output.currentNavigationId,
+            dropped: result.data.output.totals?.consoleDropped ?? 0,
+            pageCrashedAt: result.data.output.pageCrashedAt,
         },
     };
 }

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

@@ -23,6 +23,14 @@ export declare function followFetchFailure(failure: {
     json?: boolean | undefined;
     retryIntervalMs: number;
 }): FollowPoll;
+/**
+ * Report each page crash of a stream once: a page loaded again that crashes
+ * again is a new crash.
+ *
+ * @returns Function taking the crash time a refresh fetched, returning it
+ *   when that crash was not reported yet
+ */
+export declare function newPageCrashes(): (crashedAt: number | undefined) => number | undefined;
 /**
  * Options for configuring follow mode behavior.
  */
@@ -42,7 +50,7 @@ export interface FollowModeOptions {
  * - Initial display of start message
  * - First refresh call (awaited)
  * - Periodic interval-based refresh
- * - SIGINT handler for graceful shutdown
+ * - SIGINT/SIGTERM handlers that stop with 130/143, as shells expect
  * - Stopping with the exit code a refresh returns (e.g. the session is gone)
  *
  * @param refreshFn - Async function to call on each refresh cycle

package/dist/commands/shared/followMode.js

@@ -27,6 +27,22 @@ export function followFetchFailure(failure, options) {
         ? { exitCode: result.exitCode ?? EXIT_CODES.RESOURCE_NOT_FOUND }
         : undefined;
 }
+/**
+ * Report each page crash of a stream once: a page loaded again that crashes
+ * again is a new crash.
+ *
+ * @returns Function taking the crash time a refresh fetched, returning it
+ *   when that crash was not reported yet
+ */
+export function newPageCrashes() {
+    let reported;
+    return (crashedAt) => {
+        if (crashedAt === undefined || crashedAt === reported)
+            return undefined;
+        reported = crashedAt;
+        return crashedAt;
+    };
+}
 /**
  * Sets up follow mode with periodic refresh and graceful shutdown.
  *
@@ -35,7 +51,7 @@ export function followFetchFailure(failure, options) {
  * - Initial display of start message
  * - First refresh call (awaited)
  * - Periodic interval-based refresh
- * - SIGINT handler for graceful shutdown
+ * - SIGINT/SIGTERM handlers that stop with 130/143, as shells expect
  * - Stopping with the exit code a refresh returns (e.g. the session is gone)
  *
  * @param refreshFn - Async function to call on each refresh cycle
@@ -71,10 +87,12 @@ export async function setupFollowMode(refreshFn, options) {
             console.error(genericError(getErrorMessage(error)));
         });
     }, intervalMs);
-    process.on('SIGINT', () => {
+    const stop = (exitCode) => {
         clearInterval(intervalId);
         console.error(stopMessage());
-        process.exit(EXIT_CODES.SUCCESS);
-    });
+        process.exit(exitCode);
+    };
+    process.on('SIGINT', () => stop(EXIT_CODES.INTERRUPTED));
+    process.on('SIGTERM', () => stop(EXIT_CODES.TERMINATED));
 }
 //# sourceMappingURL=followMode.js.map

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

@@ -93,8 +93,10 @@ export interface ScreenshotOptions {
     fullPage?: boolean;
     /** CSS selector for element capture */
     selector?: string;
-    /** Cached element index (0-based) from previous query */
+    /** Cached element index (0-based) from previous query, or with `selector`, which of its matches */
     index?: number;
+    /** Extra space (CSS px) around an element capture */
+    padding?: number;
     /** Continuous capture mode to directory */
     follow?: boolean;
     /** Capture interval in ms for follow mode (string from CLI) */
@@ -140,7 +142,10 @@ export type DetailsCommandOptions = BaseOptions & {
     id: string;
 };
 /** Options for DOM query command */
-export type DomQueryCommandOptions = BaseOptions;
+export type DomQueryCommandOptions = BaseOptions & {
+    /** Matches listed (0 = all); default 50, or 1000 with --json */
+    limit?: number;
+};
 /** Options for DOM get command */
 export type DomGetCommandOptions = BaseOptions & RawOptions & SelectionOptions & {
     /** All of the element's text instead of its first 500 characters (semantic output) */
@@ -373,6 +378,8 @@ export interface PeekCommandOptions extends BaseOptions, PreviewDisplayOptions {
     last?: string;
     /** Filter network requests by resource type (comma-separated) */
     type?: string;
+    /** Refresh interval of --follow in ms (string from CLI, default: 1000) */
+    interval?: string;
 }
 /**
  * Options for tail command.

package/dist/commands/shared/outputFile.js

@@ -7,6 +7,7 @@ import * as path from 'path';
 import { CommandError } from '../../errors/index.js';
 import { emptyOutputPathError, outputFileError } from '../../errors/messages.js';
 import { AtomicFileWriter } from '../../utils/atomicFile.js';
+import { makeDirectory } from '../../utils/directories.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /** What went wrong with a path, by error code */
 const PATH_PROBLEMS = {
@@ -19,6 +20,10 @@ const PATH_PROBLEMS = {
     ENAMETOOLONG: { reason: 'the name is too long', exitCode: EXIT_CODES.INVALID_ARGUMENTS },
     ENOENT: { reason: 'the directory cannot be created', exitCode: EXIT_CODES.INVALID_ARGUMENTS },
     ENOSPC: { reason: 'no space left on the device', exitCode: EXIT_CODES.SESSION_FILE_ERROR },
+    EPSEUDOFS: {
+        reason: 'it is on a pseudo-filesystem (/proc, /sys)',
+        exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+    },
 };
 /**
  * A file-system error as a user-facing error about the given path.
@@ -64,7 +69,7 @@ export async function writeOutputFile(filePath, data, extension) {
     assertFilePath(filePath, extension);
     const absolutePath = path.resolve(filePath);
     try {
-        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+        makeDirectory(path.dirname(absolutePath));
         if (typeof data === 'string')
             await AtomicFileWriter.writeAsync(absolutePath, data);
         else

package/dist/commands/start.d.ts

@@ -26,6 +26,8 @@ export interface CollectorOptions {
     chromeFlags?: string;
     /** Viewport size, e.g. `1280x800`. */
     viewport?: string;
+    /** Emulate a phone (`--mobile`) */
+    mobile?: boolean;
     /** `prefers-color-scheme` to emulate: light or dark. */
     colorScheme?: string;
 }
@@ -53,6 +55,17 @@ export declare function extractUserDataDirFromFlags(flags: string[]): {
  * @returns The modified Command instance with all telemetry options applied
  */
 export declare function applyCollectorOptions(command: Command): Command;
+/** Viewport of `--mobile` without `--viewport` (a common phone, CSS px) */
+export declare const MOBILE_VIEWPORT: ViewportSize;
+/**
+ * The viewport to emulate from `--viewport` and `--mobile`.
+ *
+ * @param viewport - `--viewport` value
+ * @param mobile - `--mobile` was given
+ * @returns Viewport (a phone's with `--mobile`), or undefined for neither
+ * @throws CommandError (81) for an invalid size
+ */
+export declare function requestedViewport(viewport: string | undefined, mobile: boolean | undefined): ViewportSize | undefined;
 /**
  * Parse a `--viewport` value: width and height in CSS px joined by `x`
  * (`1280x800`; `X`, `×` and `,` work too).
@@ -71,15 +84,17 @@ export declare function parseViewport(value: string): ViewportSize;
  */
 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
- * arguments.
+ * Reject a mistyped command before Commander reads it as a start URL with
+ * extra arguments (`too many arguments`): a subcommand typed without its
+ * group (`bdg query x` for `bdg dom query x`), or a word close to a command
+ * followed by more words (`bdg netwrk list`). A single word is left to the
+ * start command, which checks it the same way.
  *
  * @param program - Root command with all commands registered
  * @param argv - Process arguments
- * @throws CommandError (81) naming the full command
+ * @throws CommandError (81) naming the command meant
  */
-export declare function assertNotGroupSubcommand(program: Command, argv: string[]): void;
+export declare function assertNotMistypedCommand(program: Command, argv: string[]): void;
 /**
  * Register the start command
  *

package/dist/commands/start.js

@@ -9,19 +9,12 @@ import { PORT_OPTION_DESCRIPTION } from '../constants.js';
 import { CommandError } from '../errors/index.js';
 import { chromeWsUrlConflictError, externalChromeUnreachableError, invalidChromeFlagError, notDevToolsEndpointError, invalidColorSchemeError, invalidUserDataDirError, invalidViewportError, missingStartUrlError, unknownCommandError, } from '../errors/messages.js';
 import { startCommandHelpMessage } from '../ui/messages/commands.js';
+import { directoryProblem } from '../utils/directories.js';
+import { hasDisplay } from '../utils/display.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { probeDevToolsEndpoint } from '../utils/http.js';
 import { findSimilar } from '../utils/suggestions.js';
 import { devToolsHttpEndpoint, validateChromeWsUrl, validateUrl } from '../utils/url.js';
-/**
- * Check if a display server (X11 or Wayland) is available.
- * Used to determine default headless mode.
- */
-function hasDisplay() {
-    const display = process.env['DISPLAY'];
-    const wayland = process.env['WAYLAND_DISPLAY'];
-    return (display !== undefined && display !== '') || (wayland !== undefined && wayland !== '');
-}
 /**
  * Expand a leading `~/` in a path to the user's home directory.
  * Chrome itself does not expand `~`, so bdg normalizes it for users.
@@ -74,14 +67,31 @@ export function applyCollectorOptions(command) {
         .option('-a, --all', 'Include all data: no tracking/analytics filtering, and capture every response body (incl. binary)', false)
         .option('-m, --max-body-size <megabytes>', 'Maximum response body size in MB', '5')
         .addOption(new Option('--compact', 'No effect; kept for compatibility').hideHelp())
-        .option('--headless', 'Run Chrome without a window (default unless DISPLAY or WAYLAND_DISPLAY is set)', defaultHeadless)
+        .option('--headless', 'Run Chrome without a window (default without a display: Linux without DISPLAY or WAYLAND_DISPLAY, macOS over SSH or in CI)', defaultHeadless)
         .option('--no-headless', 'Show browser window')
         .option('--chrome-ws-url <url>', 'Connect to an existing Chrome: its DevTools port (9222, host:port, http://host:port), or a WebSocket URL: browser (ws://host:port/devtools/browser/<id>, uses the first tab) or page (.../devtools/page/<id>)')
         .option('-q, --quiet', 'Quiet mode - minimal output for AI agents', false)
         .addOption(jsonOption())
         .option('--chrome-flags <flags>', 'Custom Chrome flags (space-separated, e.g., --chrome-flags="--ignore-certificate-errors --disable-web-security")')
         .option('--viewport <WxH>', 'Viewport size in CSS px for the whole session, e.g. 1280x800 (default: 1920x1080 window)')
-        .option('--color-scheme <scheme>', 'Emulate prefers-color-scheme for the session: light or dark (default: the system setting)');
+        .option('--color-scheme <scheme>', 'Emulate prefers-color-scheme for the session: light or dark (default: the system setting)')
+        .option('--mobile', `Emulate a phone for the session: mobile viewport (${MOBILE_VIEWPORT.width}x${MOBILE_VIEWPORT.height} unless --viewport), touch, mobile user agent`);
+}
+/** Viewport of `--mobile` without `--viewport` (a common phone, CSS px) */
+export const MOBILE_VIEWPORT = { width: 390, height: 844 };
+/**
+ * The viewport to emulate from `--viewport` and `--mobile`.
+ *
+ * @param viewport - `--viewport` value
+ * @param mobile - `--mobile` was given
+ * @returns Viewport (a phone's with `--mobile`), or undefined for neither
+ * @throws CommandError (81) for an invalid size
+ */
+export function requestedViewport(viewport, mobile) {
+    const size = viewport !== undefined ? parseViewport(viewport) : undefined;
+    if (!mobile)
+        return size;
+    return { ...(size ?? MOBILE_VIEWPORT), mobile: true };
 }
 /** Largest viewport side accepted by `--viewport` (CSS px) */
 const MAX_VIEWPORT_SIDE = 10000;
@@ -157,12 +167,14 @@ function buildSessionOptions(options) {
         quiet: options.quiet ?? false,
         json: options.json ?? false,
         chromeFlags,
-        viewport: options.viewport !== undefined ? parseViewport(options.viewport) : undefined,
+        viewport: requestedViewport(options.viewport, options.mobile),
         colorScheme: options.colorScheme !== undefined ? parseColorScheme(options.colorScheme) : undefined,
     };
 }
 /** Telemetry collected by every session. */
 const SESSION_TELEMETRY = ['dom', 'network', 'console'];
+/** A word that cannot be a URL: no dot, colon or slash */
+const BARE_WORD = /^[a-z][a-z0-9_-]*$/i;
 /** Flags users type as commands (`bdg version`). */
 const FLAG_WORDS = { version: '--version', help: '--help' };
 /**
@@ -177,29 +189,59 @@ const FLAG_WORDS = { version: '--version', help: '--help' };
  * @throws CommandError (81) for a bare word other than `localhost`
  */
 function assertNotCommandTypo(arg, commandNames) {
-    if (!/^[a-z][a-z0-9_-]*$/i.test(arg) || arg.toLowerCase() === 'localhost')
+    if (!BARE_WORD.test(arg) || arg.toLowerCase() === 'localhost')
         return;
     const flag = FLAG_WORDS[arg.toLowerCase()];
     const err = unknownCommandError(arg, flag ? [flag] : findSimilar(arg, commandNames));
     throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
- * 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
- * arguments.
+ * The words of the command line that are not options or option values of
+ * the root command (`bdg --session a netwrk list` gives `netwrk`, `list`).
+ *
+ * @param program - Root command
+ * @param args - Arguments after the executable and script
+ * @returns Positional words, in order
+ */
+function positionalWords(program, args) {
+    const words = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? '';
+        if (!arg.startsWith('-')) {
+            words.push(arg);
+            continue;
+        }
+        const option = program.options.find((o) => o.long === arg || o.short === arg);
+        if (option && (option.required || option.optional))
+            i++;
+    }
+    return words;
+}
+/**
+ * Reject a mistyped command before Commander reads it as a start URL with
+ * extra arguments (`too many arguments`): a subcommand typed without its
+ * group (`bdg query x` for `bdg dom query x`), or a word close to a command
+ * followed by more words (`bdg netwrk list`). A single word is left to the
+ * start command, which checks it the same way.
  *
  * @param program - Root command with all commands registered
  * @param argv - Process arguments
- * @throws CommandError (81) naming the full command
+ * @throws CommandError (81) naming the command meant
  */
-export function assertNotGroupSubcommand(program, argv) {
-    const [first] = argv.slice(2).filter((arg) => !arg.startsWith('-'));
-    if (first === undefined || program.commands.some((command) => command.name() === first))
+export function assertNotMistypedCommand(program, argv) {
+    const [first, ...rest] = positionalWords(program, argv.slice(2));
+    const commandNames = program.commands.map((command) => command.name());
+    if (first === undefined || commandNames.includes(first))
         return;
     const group = program.commands.find((command) => command.commands.some((sub) => sub.name() === first));
-    if (!group)
+    const similar = group
+        ? [`${group.name()} ${first}`]
+        : rest.length > 0 && BARE_WORD.test(first)
+            ? findSimilar(first, commandNames)
+            : [];
+    if (similar.length === 0)
         return;
-    const err = unknownCommandError(first, [`${group.name()} ${first}`]);
+    const err = unknownCommandError(first, similar);
     throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
@@ -230,7 +272,10 @@ function validateStartInput(url, options, program) {
             ...(process.env['BDG_CHROME_FLAGS']?.split(' ') ?? []),
             ...(options.chromeFlags?.split(' ') ?? []),
         ]);
-    return { url, sessionOptions: buildSessionOptions(options) };
+    const sessionOptions = buildSessionOptions(options);
+    if (sessionOptions.userDataDir !== undefined)
+        assertUsableProfile(sessionOptions.userDataDir);
+    return { url, sessionOptions };
 }
 /**
  * Register the start command
@@ -329,6 +374,22 @@ function assertUserDataDir(value) {
     const err = invalidUserDataDirError(value, reason);
     throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
+/**
+ * Check that Chrome can create and write its profile directory (given with
+ * `-u` or in `--chrome-flags`), before a daemon is spawned: a profile under
+ * `/proc` spun the daemon at full CPU and wedged the session.
+ *
+ * @param dir - Profile directory, `~/` expanded
+ * @throws CommandError (81) for a path that cannot hold a directory, (82)
+ *   when its nearest existing directory is not writable
+ */
+function assertUsableProfile(dir) {
+    const problem = directoryProblem(dir);
+    if (!problem)
+        return;
+    const err = invalidUserDataDirError(dir, problem.reason);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, problem.denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.INVALID_ARGUMENTS);
+}
 /**
  * Options given that only apply to a Chrome bdg launches. `--headless` has a
  * default, so it counts only when given on the command line.