browser-debugger-cli 0.8.0 → 0.10.0

package/dist/constants.js

@@ -64,8 +64,12 @@ export const DOCKER_CHROME_FLAGS = [
 ];
 /**
  * BDG-specific Chrome preferences for automation
- * These preferences are automatically merged with user preferences when launching Chrome
- * User preferences take precedence over these defaults
+ * Written into the launched profile's Default/Preferences (dotted names become nested paths)
+ * before every launch, so persistent profiles get them too. User preferences take precedence.
+ *
+ * The password manager and its leak check are off: after a login their bubble
+ * (e.g. "Change your password") captures all input in headless Chrome, so
+ * later clicks silently never reach the page.
  *
  * Note: Crash/restore popup suppression is handled by Chrome flags (--disable-session-crashed-bubble, --disable-infobars)
  * which are more reliable than preference-based approaches.
@@ -75,6 +79,9 @@ export const BDG_CHROME_PREFS = {
     'translate.enabled': false, // Disable Google Translate popup
     translate_site_blacklist: ['*'], // Block translate for all sites
     'profile.exit_type': 'Normal', // Trick Chrome into thinking it shut down correctly
+    credentials_enable_service: false, // No "Save password?" bubble
+    'profile.password_manager_enabled': false, // Password manager off
+    'profile.password_manager_leak_detection': false, // No "Change your password" breach dialog
 };
 // ============================================================================
 // DATA COLLECTION LIMITS

package/dist/daemon/SessionController.js

@@ -9,20 +9,36 @@ import { CDPConnectionError, CDPProtocolError, ChromeLaunchError, ConnectionErro
 import { Session, StartCancelledError } from './session/Session.js';
 import { detectTargetMismatch } from './session/targetMismatch.js';
 import { CommandError } from '../errors/index.js';
-import { LAUNCHED_CHROME_DESCRIPTION, cdpRequestRejectedError, sessionEndedDuringCommandError, } from '../errors/messages.js';
+import { LAUNCHED_CHROME_DESCRIPTION, cdpRequestRejectedError, sessionAlreadyRunningMessage, sessionEndedDuringCommandError, sessionUnavailableSuggestion, } from '../errors/messages.js';
 import { IPCErrorCode, } from '../ipc/index.js';
 import { clearLastSessionEnd, writeLastSessionEnd } from '../session/lastSession.js';
 import { createLogger } from '../ui/logging/index.js';
 import { formatChromeIssue } from '../ui/messages/chrome.js';
+import { noActiveSessionMessage } from '../ui/messages/sessionCommand.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { filterDefined } from '../utils/objects.js';
 const log = createLogger('daemon');
-const NO_SESSION_ERROR = 'No active session';
 /** Error for requests that need the session while `bdg <url>` is still starting it */
 const STARTING_ERROR = 'The session is still starting';
 const COMMAND_TIMEOUT_MS = 30000;
 const QUERY_TIMEOUT_MS = 5000;
+/** Time a `dom wait` gets beyond its own --timeout to report the timeout itself */
+const WAIT_COMMAND_MARGIN_MS = 5000;
+/**
+ * How long a session command may run: `dom wait` runs for its own
+ * --timeout, everything else gets {@link COMMAND_TIMEOUT_MS}.
+ *
+ * @param name - Command name
+ * @param params - Command parameters
+ * @returns Timeout in milliseconds
+ */
+function commandTimeoutMs(name, params) {
+    if (name !== 'dom_wait')
+        return COMMAND_TIMEOUT_MS;
+    const { timeout } = params;
+    return Math.max(COMMAND_TIMEOUT_MS, (timeout ?? 0) + WAIT_COMMAND_MARGIN_MS);
+}
 /**
  * Run a promise with a timeout, clearing the timer either way.
  *
@@ -139,11 +155,11 @@ export class SessionController {
      */
     noSessionError() {
         if (!this.launching)
-            return { error: NO_SESSION_ERROR };
+            return { error: noActiveSessionMessage() };
         return {
             error: STARTING_ERROR,
             exitCode: EXIT_CODES.RESOURCE_BUSY,
-            suggestion: 'Wait until "bdg <url>" returns, then retry',
+            suggestion: sessionUnavailableSuggestion(EXIT_CODES.RESOURCE_BUSY),
         };
     }
     /**
@@ -270,7 +286,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), COMMAND_TIMEOUT_MS, 'Command');
+            const data = await withTimeout(execute(name, params), commandTimeoutMs(name, params), 'Command');
             return { ...base, status: 'ok', data };
         }
         catch (error) {
@@ -367,7 +383,7 @@ export class SessionController {
             return {
                 ...base,
                 status: 'error',
-                message: 'No active session found',
+                message: noActiveSessionMessage(),
                 errorCode: IPCErrorCode.NO_SESSION,
             };
         }
@@ -430,7 +446,7 @@ export class SessionController {
             };
         }
         return {
-            message: `Session already running (PID ${process.pid}). Stop it first with: bdg stop`,
+            message: sessionAlreadyRunningMessage(process.pid),
             errorCode: IPCErrorCode.SESSION_ALREADY_RUNNING,
             existingSession: { ...existingSession, targetUrl },
         };

package/dist/daemon/errors.d.ts

@@ -54,7 +54,7 @@ export declare class SessionDirError extends DaemonError {
     /**
      * @param message - What is wrong with the directory
      * @param suggestion - How to fix it
-     * @param exitCode - 82 for permissions, 103 otherwise
+     * @param exitCode - 82 for permissions, 81 for a too-long path, 103 otherwise
      */
     constructor(message: string, suggestion: string, exitCode?: number);
 }

package/dist/daemon/errors.js

@@ -69,7 +69,7 @@ export class SessionDirError extends DaemonError {
     /**
      * @param message - What is wrong with the directory
      * @param suggestion - How to fix it
-     * @param exitCode - 82 for permissions, 103 otherwise
+     * @param exitCode - 82 for permissions, 81 for a too-long path, 103 otherwise
      */
     constructor(message, suggestion, exitCode = EXIT_CODES.SESSION_FILE_ERROR) {
         super(message, 'SESSION_DIR_UNUSABLE', exitCode);

package/dist/daemon/launcher.d.ts

@@ -6,18 +6,26 @@
  * SocketServer), so concurrent launches are safe: a losing daemon exits and
  * the CLI talks to the winner.
  */
+/** A daemon this process spawned */
+export interface SpawnedDaemon {
+    pid: number | undefined;
+    /** Whether it has exited (from the child process's exit event) */
+    hasExited: () => boolean;
+}
 /**
  * Ensure a daemon is running, spawning one if needed.
  *
+ * @returns The daemon it spawned, or undefined when one was already running
  * @throws DaemonStartupError if the daemon script is missing or the daemon
  *   does not accept connections in time
  */
-export declare function launchDaemon(): Promise<void>;
+export declare function launchDaemon(): Promise<SpawnedDaemon | undefined>;
 /**
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file or a too-long path, (82) when not writable
+ * @throws SessionDirError (103) for a file, (81) for a too-long path like a
+ *   named session's, (82) when not writable
  */
 export declare function assertUsableSessionDir(): void;
 //# sourceMappingURL=launcher.d.ts.map

package/dist/daemon/launcher.js

@@ -12,7 +12,7 @@ import { join } from 'path';
 import { DaemonStartupError, SessionDirError } from './errors.js';
 import { sessionDirIsFileError, sessionDirNotWritableError, socketPathTooLongError, } from '../errors/messages.js';
 import { isDaemonAlive } from '../session/daemonSocket.js';
-import { ensureSessionDir, getSessionDir, getSessionFilePath } from '../session/paths.js';
+import { MAX_DAEMON_SOCKET_PATH_BYTES, ensureSessionDir, getSessionDir, getSessionFilePath, } from '../session/paths.js';
 import { createLogger } from '../ui/logging/index.js';
 import { delay } from '../utils/async.js';
 import { getErrorMessage } from '../utils/errors.js';
@@ -24,13 +24,14 @@ const DAEMON_READY_POLL_MS = 20;
 /**
  * Ensure a daemon is running, spawning one if needed.
  *
+ * @returns The daemon it spawned, or undefined when one was already running
  * @throws DaemonStartupError if the daemon script is missing or the daemon
  *   does not accept connections in time
  */
 export async function launchDaemon() {
     if (await isDaemonAlive()) {
         log.debug('Daemon already running');
-        return;
+        return undefined;
     }
     if (!fs.existsSync(DAEMON_SCRIPT_PATH)) {
         throw new DaemonStartupError(`Daemon script not found at ${DAEMON_SCRIPT_PATH}. Did you run 'npm run build'?`, 'DAEMON_SCRIPT_NOT_FOUND');
@@ -51,14 +52,14 @@ export async function launchDaemon() {
     });
     daemon.unref();
     await waitForDaemonReady(() => exited);
+    return { pid: daemon.pid, hasExited: () => exited };
 }
-/** Longest Unix socket path (sun_path is 104 bytes on macOS, 108 on Linux, NUL included) */
-const MAX_SOCKET_PATH = process.platform === 'darwin' ? 103 : 107;
 /**
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file or a too-long path, (82) when not writable
+ * @throws SessionDirError (103) for a file, (81) for a too-long path like a
+ *   named session's, (82) when not writable
  */
 export function assertUsableSessionDir() {
     const dir = getSessionDir();
@@ -68,8 +69,8 @@ export function assertUsableSessionDir() {
     if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory())
         fail(sessionDirIsFileError(dir));
     const socketPath = getSessionFilePath('DAEMON_SOCKET');
-    if (Buffer.byteLength(socketPath) > MAX_SOCKET_PATH) {
-        fail(socketPathTooLongError(socketPath, MAX_SOCKET_PATH));
+    if (Buffer.byteLength(socketPath) > MAX_DAEMON_SOCKET_PATH_BYTES) {
+        fail(socketPathTooLongError(socketPath, MAX_DAEMON_SOCKET_PATH_BYTES), EXIT_CODES.INVALID_ARGUMENTS);
     }
     try {
         ensureSessionDir();

package/dist/daemon/server/SocketServer.js

@@ -2,11 +2,10 @@ import { linkSync, lstatSync, unlinkSync } from 'fs';
 import { createServer } from 'net';
 import { DaemonError } from '../errors.js';
 import { probeDaemonSocket } from '../../session/daemonSocket.js';
+import { MAX_SOCKET_PATH_BYTES } from '../../session/paths.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
-/** Unix socket path limit (sun_path is 104 bytes on macOS incl. NUL; 108 on Linux). */
-const MAX_SOCKET_PATH_BYTES = 103;
 /** Error code thrown when another daemon already owns the socket path. */
 export const DAEMON_ALREADY_RUNNING_CODE = 'DAEMON_ALREADY_RUNNING';
 /**

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

@@ -6,6 +6,7 @@
  * separate worker process: the daemon process *is* the session.
  */
 import type { CommandName, CommandSchemas } from '../../ipc/index.js';
+import type { PageLoadingState } from '../../ipc/protocol/commands.js';
 import type { SessionOptions } from '../../ipc/session/lifecycle.js';
 import type { StatusResponseData } from '../../ipc/session/queries.js';
 /** Why a session ended. */
@@ -18,6 +19,8 @@ export interface SessionInfo {
     targetTitle?: string;
     /** HTTP status of the page's main document, when known */
     documentStatus?: number;
+    /** The page had not finished loading when the readiness wait ended */
+    loading?: PageLoadingState;
 }
 /** Session metadata as reported in status responses. */
 export type SessionStatusMetadata = NonNullable<StatusResponseData['sessionMetadata']>;
@@ -50,6 +53,7 @@ export declare class Session {
     private readonly launchAbort;
     private started;
     private documentRequestId;
+    private loading;
     private constructor();
     /**
      * Validate the request and create a session that has not been launched yet.
@@ -95,6 +99,13 @@ export declare class Session {
      * @returns Session metadata
      */
     metadata(): SessionStatusMetadata;
+    /**
+     * Record a page emulation changed mid-session, so screenshots restore it
+     * and `bdg status` reports it.
+     *
+     * @param emulation - Viewport and color scheme now emulated
+     */
+    private setEmulation;
     /**
      * Whether stop() has been called.
      *
@@ -115,6 +126,15 @@ export declare class Session {
      * Acquire Chrome, CDP and collectors, checking for a concurrent stop after each step.
      */
     private acquireResources;
+    /**
+     * Choose the port and launch Chrome on it.
+     *
+     * A Chrome left by this session's crashed daemon is reaped first, so the
+     * session gets its remembered port back. If another process took an
+     * automatically chosen port before Chrome could listen on it, another port
+     * is chosen (the taken one now answers, so it is skipped).
+     */
+    private launchOwnChrome;
     /**
      * End the session after its page connection was lost. A launched Chrome
      * still running a moment later means the tab was closed (e.g.

package/dist/daemon/session/Session.js

@@ -5,6 +5,7 @@
  * telemetry collectors and executes session commands directly. There is no
  * separate worker process: the daemon process *is* the session.
  */
+import { ChromeLaunchError } from '../../connection/errors.js';
 import { TelemetryStore } from './TelemetryStore.js';
 import { connectCDP, navigateToTarget } from './cdpSetup.js';
 import { externalChromePort, findPageTarget, setupChromeConnection, } from './chromeConnection.js';
@@ -12,12 +13,15 @@ import { startTelemetryCollectors } from './collectors.js';
 import { createCommandRegistry } from './commandRegistry.js';
 import { teardownSession } from './teardown.js';
 import { CommandError } from '../../errors/index.js';
+import { applySessionEmulation } from '../../runtime/page/emulation.js';
+import { readPageLoadingState } from '../../runtime/page/loadingState.js';
 import { reapOrphanedChrome, removeSessionFiles } from '../../session/cleanup/staleSession.js';
 import { writeSessionMetadata } from '../../session/metadata.js';
 import { getSessionPort } from '../../session/port.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { formatChromeNotice } from '../../ui/messages/chrome.js';
 import { delay } from '../../utils/async.js';
+import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
 import { isProcessAlive } from '../../utils/process.js';
@@ -25,6 +29,17 @@ import { validateUrl } from '../../utils/url.js';
 const log = createLogger('session');
 /** How long Chrome gets to exit after the page connection drops, before the end is called a closed tab */
 const CRASH_SETTLE_MS = 500;
+/** Ports tried when automatically chosen ports turn out to be taken */
+const PORT_ATTEMPTS = 3;
+/**
+ * Whether a launch failed because another process holds the port.
+ *
+ * @param error - Launch error
+ * @returns True for a PORT_IN_USE launch error
+ */
+function isPortConflict(error) {
+    return error instanceof ChromeLaunchError && error.issue?.code === 'PORT_IN_USE';
+}
 /**
  * A launch that failed because the session was stopped while starting.
  */
@@ -41,7 +56,10 @@ export class Session {
     config;
     onEnded;
     store = new TelemetryStore();
-    registry = createCommandRegistry(this.store);
+    registry = createCommandRegistry(this.store, {
+        get: () => filterDefined({ viewport: this.config.viewport, colorScheme: this.config.colorScheme }),
+        set: (emulation) => this.setEmulation(emulation),
+    });
     notify = (notice) => log.info(formatChromeNotice(notice));
     chrome = null;
     cdp = null;
@@ -56,6 +74,7 @@ export class Session {
     launchAbort = new AbortController();
     started = false;
     documentRequestId;
+    loading;
     constructor(config, onEnded) {
         this.config = config;
         this.onEnded = onEnded;
@@ -134,6 +153,7 @@ export class Session {
             targetUrl: target?.url ?? this.config.url,
             ...(target?.title && { targetTitle: target.title }),
             ...(documentStatus !== undefined && { documentStatus }),
+            ...(this.loading && { loading: this.loading }),
         };
     }
     /**
@@ -153,9 +173,29 @@ export class Session {
                 autoStopAt: this.autoStopAt,
                 targetId: target?.id,
                 webSocketDebuggerUrl: target?.webSocketDebuggerUrl,
+                viewport: this.config.viewport,
+                colorScheme: this.config.colorScheme,
             }),
         };
     }
+    /**
+     * Record a page emulation changed mid-session, so screenshots restore it
+     * and `bdg status` reports it.
+     *
+     * @param emulation - Viewport and color scheme now emulated
+     */
+    setEmulation(emulation) {
+        const { viewport: _viewport, colorScheme: _colorScheme, ...rest } = this.config;
+        this.config = { ...rest, ...emulation };
+        if (!this.started)
+            return;
+        try {
+            writeSessionMetadata(this.metadata());
+        }
+        catch (error) {
+            log.debug(`Session metadata not updated: ${getErrorMessage(error)}`);
+        }
+    }
     /**
      * Whether stop() has been called.
      *
@@ -194,15 +234,14 @@ export class Session {
     async acquireResources() {
         this.store.resetSessionStart();
         const { chromeWsUrl } = this.config;
-        const port = chromeWsUrl
-            ? externalChromePort(chromeWsUrl)
-            : await getSessionPort(this.config.port || undefined);
-        this.config = { ...this.config, port };
-        this.throwIfStopping();
-        if (!this.config.chromeWsUrl) {
-            await reapOrphanedChrome();
+        if (chromeWsUrl) {
+            this.config = { ...this.config, port: externalChromePort(chromeWsUrl) };
+            this.throwIfStopping();
+            this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify);
+        }
+        else {
+            await this.launchOwnChrome();
         }
-        this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify);
         this.throwIfStopping();
         if (this.chrome) {
             await findPageTarget(this.config, this.store, log);
@@ -213,10 +252,40 @@ export class Session {
             signal: this.launchAbort.signal,
         });
         this.throwIfStopping();
+        await applySessionEmulation(this.cdp, this.config);
+        this.throwIfStopping();
         this.cleanupFunctions = await startTelemetryCollectors(this.cdp, this.config, this.store, log);
         this.throwIfStopping();
         this.documentRequestId = await navigateToTarget(this.cdp, this.config, this.store, this.chrome, log);
         this.throwIfStopping();
+        this.loading = await readPageLoadingState(this.cdp, this.store.pendingNetworkRequests.values());
+        this.throwIfStopping();
+    }
+    /**
+     * Choose the port and launch Chrome on it.
+     *
+     * A Chrome left by this session's crashed daemon is reaped first, so the
+     * session gets its remembered port back. If another process took an
+     * automatically chosen port before Chrome could listen on it, another port
+     * is chosen (the taken one now answers, so it is skipped).
+     */
+    async launchOwnChrome() {
+        await reapOrphanedChrome();
+        const explicitPort = this.config.port || undefined;
+        for (let attempt = 1;; attempt++) {
+            this.config = { ...this.config, port: await getSessionPort(explicitPort) };
+            this.throwIfStopping();
+            try {
+                this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify);
+                return;
+            }
+            catch (error) {
+                const retry = !explicitPort && attempt < PORT_ATTEMPTS && isPortConflict(error);
+                if (!retry)
+                    throw error;
+                log.info(`Port ${this.config.port} was taken by another process; choosing another`);
+            }
+        }
     }
     /**
      * End the session after its page connection was lost. A launched Chrome
@@ -282,6 +351,8 @@ function buildConfig(url, port, options) {
             maxBodySize: options.maxBodySize,
             chromeWsUrl: options.chromeWsUrl,
             chromeFlags: options.chromeFlags,
+            viewport: options.viewport,
+            colorScheme: options.colorScheme,
         }),
     };
 }

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

@@ -22,6 +22,15 @@ export declare function setupChromeConnection(config: SessionConfig, telemetrySt
  * @returns Port in the URL, or the protocol default
  */
 export declare function externalChromePort(wsUrl: string): number;
+/**
+ * Chrome flags of a launched Chrome: with `--viewport`, a window of that size
+ * first (so tabs the page opens get it too), then the user's own flags, which
+ * win over it.
+ *
+ * @param config - Session configuration
+ * @returns Flags, or undefined without any
+ */
+export declare function windowSizeFlags(config: SessionConfig): string[] | undefined;
 /**
  * Find the page target of a Chrome that bdg launched.
  *

package/dist/daemon/session/chromeConnection.js

@@ -9,11 +9,12 @@ import { launchChrome } from '../../connection/launcher.js';
 import { HTTP_LOCALHOST } from '../../constants.js';
 import { ConfigError } from '../errors.js';
 import { CommandError } from '../../errors/index.js';
-import { externalBrowserIdMismatchError, externalChromeUnreachableError, externalPageNotFoundError, } from '../../errors/messages.js';
+import { chromeInUseBySessionError, externalBrowserIdMismatchError, externalChromeUnreachableError, externalPageNotFoundError, notDevToolsEndpointError, } from '../../errors/messages.js';
 import { writeChromePid } from '../../session/chrome.js';
+import { findConflictingOwner } from '../../session/chromeOwners.js';
 import { getSessionDir } from '../../session/paths.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
-import { createPageTarget, fetchBrowserWsUrl, fetchCDPTargets } from '../../utils/http.js';
+import { createPageTarget, fetchCDPTargets, probeDevToolsEndpoint } from '../../utils/http.js';
 import { filterDefined } from '../../utils/objects.js';
 /**
  * Setup Chrome connection - either launch new instance or connect to existing.
@@ -71,23 +72,30 @@ async function resolveExternalTarget(wsUrl, config, log) {
     const { hostname, pathname, protocol, port } = new URL(wsUrl);
     const http = { host: hostname, secure: protocol === 'wss:' };
     const endpoint = `${http.secure ? 'https' : 'http'}://${hostname}:${config.port}`;
-    const browserWsUrl = await fetchBrowserWsUrl(config.port, log, http);
-    if (!browserWsUrl)
-        fail(externalChromeUnreachableError(endpoint, http.secure), EXIT_CODES.CDP_CONNECTION_FAILURE);
+    const probe = await probeDevToolsEndpoint(config.port, log, http);
+    if (probe.kind !== 'devtools') {
+        const err = probe.kind === 'not-devtools'
+            ? notDevToolsEndpointError(endpoint)
+            : externalChromeUnreachableError(endpoint, http.secure);
+        fail(err, EXIT_CODES.CDP_CONNECTION_FAILURE);
+    }
+    const browserWsUrl = probe.wsUrl;
     const targets = await fetchCDPTargets(config.port, log, http);
     const targetId = pathname.split('/').pop() ?? '';
     if (!pathname.startsWith(BROWSER_WS_PATH)) {
         const known = targets.find((t) => t.id === targetId);
         if (!known)
             fail(externalPageNotFoundError(targetId, endpoint), EXIT_CODES.RESOURCE_NOT_FOUND);
+        await assertNotOwned(targets, known.id, endpoint);
         return { ...known, webSocketDebuggerUrl: wsUrl };
     }
     if (new URL(browserWsUrl).pathname !== pathname) {
         const actual = withEndpoint(browserWsUrl, protocol, hostname, port);
         fail(externalBrowserIdMismatchError(endpoint, actual), EXIT_CODES.RESOURCE_NOT_FOUND);
     }
-    const page = targets.find((t) => t.type === 'page') ??
-        (await createPageTarget(hostname, config.port, log, http));
+    const firstPage = targets.find((t) => t.type === 'page');
+    await assertNotOwned(targets, firstPage?.id ?? '', endpoint);
+    const page = firstPage ?? (await createPageTarget(hostname, config.port, log, http));
     if (!page)
         fail(externalChromeUnreachableError(endpoint, http.secure), EXIT_CODES.CDP_CONNECTION_FAILURE);
     log.info(`Attaching to page ${page.url} of the external Chrome`);
@@ -96,6 +104,21 @@ async function resolveExternalTarget(wsUrl, config, log) {
         webSocketDebuggerUrl: withEndpoint(page.webSocketDebuggerUrl, protocol, hostname, port),
     };
 }
+/**
+ * Refuse to attach when another running bdg session launched this Chrome or
+ * drives the tab this session would use: taking it over would mix both
+ * sessions' telemetry and let one end the other.
+ *
+ * @param targets - Every target of the Chrome
+ * @param targetId - Tab this session would drive ('' for a tab still to be opened)
+ * @param endpoint - e.g. http://127.0.0.1:9222
+ * @throws CommandError (90) naming the other session
+ */
+async function assertNotOwned(targets, targetId, endpoint) {
+    const owner = await findConflictingOwner(targets.map((t) => t.id), targetId);
+    if (owner)
+        fail(chromeInUseBySessionError(endpoint, owner), EXIT_CODES.RESOURCE_CONFLICT);
+}
 /**
  * A DevTools WebSocket URL from Chrome, reached the way the user's URL is
  * (Chrome reports its own host, e.g. 127.0.0.1, even behind a proxy).
@@ -123,6 +146,20 @@ function withEndpoint(url, protocol, hostname, port) {
 function fail(err, exitCode) {
     throw new CommandError(err.message, { suggestion: err.suggestion }, exitCode);
 }
+/**
+ * Chrome flags of a launched Chrome: with `--viewport`, a window of that size
+ * first (so tabs the page opens get it too), then the user's own flags, which
+ * win over it.
+ *
+ * @param config - Session configuration
+ * @returns Flags, or undefined without any
+ */
+export function windowSizeFlags(config) {
+    if (!config.viewport)
+        return config.chromeFlags;
+    const { width, height } = config.viewport;
+    return [`--window-size=${width},${height}`, ...(config.chromeFlags ?? [])];
+}
 /**
  * Launch a new Chrome instance and record its PID for crash cleanup.
  */
@@ -134,7 +171,7 @@ async function setupLaunchedChrome(config, log) {
         ...filterDefined({
             userDataDir: config.userDataDir,
             headless: config.headless,
-            chromeFlags: config.chromeFlags,
+            chromeFlags: windowSizeFlags(config),
         }),
     });
     log.info(`Chrome launched (PID ${chrome.pid})`);

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

@@ -1,10 +1,23 @@
 import type { TelemetryStore } from './TelemetryStore.js';
 import type { CDPConnection } from '../../connection/cdp.js';
 import type { CommandName, CommandSchemas } from '../../ipc/index.js';
+import { type SessionEmulation } from '../../runtime/page/emulation.js';
 type Handler<K extends CommandName> = (cdp: CDPConnection, params: CommandSchemas[K]['requestSchema']) => Promise<CommandSchemas[K]['responseSchema']>;
 export type CommandRegistry = {
     [K in CommandName]: Handler<K>;
 };
-export declare function createCommandRegistry(store: TelemetryStore): CommandRegistry;
+/** The session's page emulation, which `page emulate` reads and changes */
+export interface EmulationState {
+    get: () => SessionEmulation;
+    set: (emulation: SessionEmulation) => void;
+}
+/**
+ * The handlers of the session commands.
+ *
+ * @param store - Telemetry of the session
+ * @param emulation - The session's page emulation
+ * @returns Command registry
+ */
+export declare function createCommandRegistry(store: TelemetryStore, emulation: EmulationState): CommandRegistry;
 export {};
 //# sourceMappingURL=commandRegistry.d.ts.map