browser-debugger-cli 0.8.0 → 0.10.0

package/dist/connection/chromeIdentity.js

@@ -0,0 +1,143 @@
+/**
+ * Identity of the Chrome bdg launched.
+ *
+ * chrome-launcher only waits until something answers on 127.0.0.1:<port>. That
+ * may be another process: when 127.0.0.1:<port> is taken, Chrome listens on
+ * [::1]:<port> instead and the readiness check is answered by the other one.
+ *
+ * Chrome prints `DevTools listening on ws://<host>:<port>/devtools/browser/<id>`
+ * to stderr (chrome-launcher writes it to `chrome-err.log` in the profile).
+ * The browser path is unique per browser, so comparing it with the one
+ * 127.0.0.1:<port> reports tells whether that is the launched Chrome.
+ * (Chrome's `DevToolsActivePort` file holds the same, but Chrome writes it only
+ * for `--remote-debugging-port=0`.)
+ *
+ * A Chrome whose output lacks the line (stderr redirected, a Chromium build
+ * that does not print it) is accepted with a warning when its browser answers
+ * on 127.0.0.1 and nothing listens on [::1]: the port was free on both right
+ * before the launch, and a second listener is how a conflict shows.
+ */
+import { createLogger } from '../ui/logging/index.js';
+import { delay } from '../utils/async.js';
+import { fetchBrowserWsUrl } from '../utils/http.js';
+import { isProcessAlive } from '../utils/process.js';
+import { ChromeLaunchError } from './errors.js';
+import { acceptsConnections } from './portReservation.js';
+import { readStartupLines } from './startupExit.js';
+/** Chrome's stderr line announcing its debugging endpoint */
+const LISTENING_PATTERN = /^DevTools listening on (ws:\/\/\S+)/;
+/** How long to wait for Chrome to announce its endpoint after the port answered */
+const ENDPOINT_WAIT_MS = 10000;
+const ENDPOINT_POLL_MS = 50;
+const log = createLogger('chrome');
+/**
+ * Find the endpoint Chrome announced in its output (the last announcement).
+ *
+ * @param lines - Chrome's output lines
+ * @returns Endpoint, or null if there is no complete announcement
+ */
+export function parseDevToolsListening(lines) {
+    for (const line of [...lines].reverse()) {
+        const match = LISTENING_PATTERN.exec(line.trim());
+        if (!match?.[1])
+            continue;
+        try {
+            const url = new URL(match[1]);
+            const port = Number(url.port);
+            if (!port || !url.pathname.startsWith('/devtools/browser/'))
+                continue;
+            return { host: url.hostname, port, browserPath: url.pathname };
+        }
+        catch (error) {
+            log.debug(`Ignoring malformed DevTools announcement: ${String(error)}`);
+        }
+    }
+    return null;
+}
+/**
+ * Wait for Chrome to announce its endpoint.
+ *
+ * @param logs - Chrome's log positions from before the launch
+ * @param isRunning - Whether Chrome is still running (waiting stops when not)
+ * @param timeoutMs - Longest wait
+ * @returns Endpoint, or null if Chrome exited or announced none in time
+ */
+export async function waitForDevToolsEndpoint(logs, isRunning, timeoutMs = ENDPOINT_WAIT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const endpoint = parseDevToolsListening(readStartupLines(logs));
+        if (endpoint || !isRunning() || Date.now() >= deadline)
+            return endpoint;
+        await delay(ENDPOINT_POLL_MS);
+    }
+}
+/**
+ * Check that the Chrome answering on 127.0.0.1:<port> is the one just
+ * launched, so bdg never drives another session's browser.
+ *
+ * @param options - Chrome's log positions from before the launch, requested
+ *   port (free on 127.0.0.1 and ::1 right before the launch), Chrome's PID and
+ *   longest wait for its announcement
+ * @throws ChromeLaunchError: CHROME_DIED_AFTER_LAUNCH if Chrome exits first;
+ *   PORT_IN_USE if another browser or process answers on the port;
+ *   CHROME_LAUNCH_FAILED if Chrome announced nothing and nothing answers
+ */
+export async function verifyLaunchedChrome(options) {
+    const { logs, port, pid, timeoutMs } = options;
+    const isRunning = () => isProcessAlive(pid);
+    const endpoint = await waitForDevToolsEndpoint(logs, isRunning, timeoutMs);
+    if (!endpoint && !isRunning()) {
+        throw new ChromeLaunchError(`Chrome died immediately after launch (PID: ${pid})`, {
+            issue: { code: 'CHROME_DIED_AFTER_LAUNCH', context: { port, pid } },
+        });
+    }
+    if (!endpoint)
+        return acceptUnannouncedChrome(logs, port);
+    if (endpoint.port !== port) {
+        throw portTakenError(port, `Chrome listens on port ${endpoint.port} instead`);
+    }
+    const answering = await fetchBrowserWsUrl(port, log);
+    if (!answering || new URL(answering).pathname !== endpoint.browserPath) {
+        throw portTakenError(port, `another process answers on 127.0.0.1 (Chrome listens on ${endpoint.host})`);
+    }
+    log.debug(`Chrome on port ${port} is the launched one (${endpoint.browserPath})`);
+}
+/**
+ * Accept a Chrome that did not announce its endpoint, if a browser answers on
+ * 127.0.0.1:<port> and nothing listens on [::1]:<port> (two listeners mean a
+ * conflict).
+ *
+ * @param logs - Chrome's log positions (the stderr log is named in messages)
+ * @param port - Requested port
+ * @throws ChromeLaunchError: PORT_IN_USE for a second listener;
+ *   CHROME_LAUNCH_FAILED if no browser answers
+ */
+async function acceptUnannouncedChrome(logs, port) {
+    const errLog = logs.files[0]?.file ?? 'chrome-err.log';
+    const missing = `Chrome did not print "DevTools listening on" to ${errLog}`;
+    if (!(await fetchBrowserWsUrl(port, log))) {
+        throw new ChromeLaunchError(`${missing}, and no browser answers on port ${port}`, {
+            issue: {
+                code: 'CHROME_LAUNCH_FAILED',
+                context: { port, reason: `${missing}, and no browser answers on port ${port}` },
+            },
+        });
+    }
+    if (await acceptsConnections(port, '::1')) {
+        throw portTakenError(port, `${missing}, and both 127.0.0.1 and [::1] answer`);
+    }
+    log.info(`Warning: ${missing}; using the browser on 127.0.0.1:${port}, which was free before the launch`);
+}
+/**
+ * The error for a port another process answers on.
+ *
+ * @param port - Requested port
+ * @param reason - What was found
+ * @returns Launch error with the PORT_IN_USE issue
+ */
+function portTakenError(port, reason) {
+    return new ChromeLaunchError(`Port ${port} is already in use: ${reason}`, {
+        issue: { code: 'PORT_IN_USE', context: { port, reason } },
+    });
+}
+//# sourceMappingURL=chromeIdentity.js.map

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

@@ -0,0 +1,47 @@
+/**
+ * Chrome profile preferences writer.
+ *
+ * Chrome reads `<user-data-dir>/Default/Preferences` as nested JSON and looks
+ * preferences up by path (`profile.password_manager_enabled` is
+ * `{"profile": {"password_manager_enabled": ...}}`). bdg's preferences use
+ * dotted names, so they are expanded into that structure and deep-merged into
+ * the existing file: persistent profiles reused across sessions get them too,
+ * and everything else Chrome stored there is kept.
+ */
+import type { Logger } from '../types.js';
+/** JSON object as stored in the Preferences file */
+type PrefsObject = Record<string, unknown>;
+/**
+ * Merge preferences into an existing Preferences object.
+ *
+ * Dotted names become nested paths, and a literal dotted top-level key (as
+ * earlier bdg versions wrote, which Chrome ignored) is removed.
+ *
+ * @param existing - Current Preferences content
+ * @param prefs - Preferences to apply, dotted or nested
+ * @returns Merged Preferences (a new object; `existing` is not modified)
+ */
+export declare function mergePreferences(existing: PrefsObject, prefs: PrefsObject): PrefsObject;
+/**
+ * Whether a running Chrome has the profile open, judged by its
+ * `SingletonLock` symlink (`<host>-<pid>`, macOS and Linux).
+ *
+ * @param userDataDir - Chrome user data directory
+ * @returns True if the lock names a live process on this host
+ */
+export declare function profileInUse(userDataDir: string): boolean;
+/**
+ * Apply preferences to the default profile in a Chrome user data directory.
+ *
+ * Failures are logged (visible in daemon.log), not thrown: Chrome still
+ * starts, only without them. An unreadable Preferences file and a profile
+ * that a running Chrome has open are left alone, and the file is not
+ * rewritten when nothing changes.
+ *
+ * @param userDataDir - Chrome user data directory
+ * @param prefs - Preferences to apply, dotted or nested
+ * @param logger - Logger for failures
+ */
+export declare function writeProfilePreferences(userDataDir: string, prefs: PrefsObject, logger: Logger): void;
+export {};
+//# sourceMappingURL=profilePreferences.d.ts.map

package/dist/connection/launcher/profilePreferences.js

@@ -0,0 +1,151 @@
+/**
+ * Chrome profile preferences writer.
+ *
+ * Chrome reads `<user-data-dir>/Default/Preferences` as nested JSON and looks
+ * preferences up by path (`profile.password_manager_enabled` is
+ * `{"profile": {"password_manager_enabled": ...}}`). bdg's preferences use
+ * dotted names, so they are expanded into that structure and deep-merged into
+ * the existing file: persistent profiles reused across sessions get them too,
+ * and everything else Chrome stored there is kept.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { chromePrefsNotAppliedMessage } from '../../ui/messages/chrome.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { isProcessAlive } from '../../utils/process.js';
+/**
+ * Whether a value is a plain JSON object (not an array or null).
+ *
+ * @param value - Value to check
+ * @returns True for objects that can be merged into
+ */
+function isPrefsObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Set a preference at a nested path, merging objects with what is there.
+ *
+ * @param target - Preferences object to modify
+ * @param keys - Path segments, e.g. `['profile', 'exit_type']`
+ * @param value - Value to set
+ */
+function setAtPath(target, keys, value) {
+    const [key, ...rest] = keys;
+    if (key === undefined)
+        return;
+    const current = target[key];
+    if (rest.length > 0) {
+        const child = isPrefsObject(current) ? current : {};
+        target[key] = child;
+        setAtPath(child, rest, value);
+        return;
+    }
+    if (isPrefsObject(current) && isPrefsObject(value)) {
+        for (const [childKey, childValue] of Object.entries(value)) {
+            setAtPath(current, [childKey], childValue);
+        }
+        return;
+    }
+    target[key] = value;
+}
+/**
+ * Merge preferences into an existing Preferences object.
+ *
+ * Dotted names become nested paths, and a literal dotted top-level key (as
+ * earlier bdg versions wrote, which Chrome ignored) is removed.
+ *
+ * @param existing - Current Preferences content
+ * @param prefs - Preferences to apply, dotted or nested
+ * @returns Merged Preferences (a new object; `existing` is not modified)
+ */
+export function mergePreferences(existing, prefs) {
+    const merged = structuredClone(existing);
+    for (const [name, value] of Object.entries(prefs)) {
+        if (name.includes('.'))
+            delete merged[name];
+        setAtPath(merged, name.split('.'), value);
+    }
+    return merged;
+}
+/**
+ * Read the profile's Preferences file.
+ *
+ * @param file - Preferences file path
+ * @returns Its content, `{}` if missing
+ * @throws Error if it is not valid JSON or not a JSON object
+ */
+function readPreferencesFile(file) {
+    if (!fs.existsSync(file))
+        return {};
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!isPrefsObject(parsed))
+        throw new Error('not a JSON object');
+    return parsed;
+}
+/**
+ * Whether a running Chrome has the profile open, judged by its
+ * `SingletonLock` symlink (`<host>-<pid>`, macOS and Linux).
+ *
+ * @param userDataDir - Chrome user data directory
+ * @returns True if the lock names a live process on this host
+ */
+export function profileInUse(userDataDir) {
+    let target;
+    try {
+        target = fs.readlinkSync(path.join(userDataDir, 'SingletonLock'));
+    }
+    catch {
+        return false;
+    }
+    const separator = target.lastIndexOf('-');
+    const pid = Number(target.slice(separator + 1));
+    return (target.slice(0, separator) === os.hostname() && Number.isInteger(pid) && isProcessAlive(pid));
+}
+/**
+ * Replace a file atomically: write a temporary file next to it, then rename.
+ *
+ * @param file - File to replace
+ * @param content - New content
+ */
+function writeFileAtomic(file, content) {
+    const temp = `${file}.bdg-${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(temp, content, 'utf8');
+        fs.renameSync(temp, file);
+    }
+    finally {
+        fs.rmSync(temp, { force: true });
+    }
+}
+/**
+ * Apply preferences to the default profile in a Chrome user data directory.
+ *
+ * Failures are logged (visible in daemon.log), not thrown: Chrome still
+ * starts, only without them. An unreadable Preferences file and a profile
+ * that a running Chrome has open are left alone, and the file is not
+ * rewritten when nothing changes.
+ *
+ * @param userDataDir - Chrome user data directory
+ * @param prefs - Preferences to apply, dotted or nested
+ * @param logger - Logger for failures
+ */
+export function writeProfilePreferences(userDataDir, prefs, logger) {
+    const file = path.join(userDataDir, 'Default', 'Preferences');
+    if (profileInUse(userDataDir)) {
+        logger.info(chromePrefsNotAppliedMessage(file, 'the profile is in use by a running Chrome'));
+        return;
+    }
+    try {
+        const existing = readPreferencesFile(file);
+        const content = JSON.stringify(mergePreferences(existing, prefs));
+        if (content === JSON.stringify(existing))
+            return;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        writeFileAtomic(file, content);
+    }
+    catch (error) {
+        logger.info(chromePrefsNotAppliedMessage(file, getErrorMessage(error)));
+    }
+}
+//# sourceMappingURL=profilePreferences.js.map

package/dist/connection/launcher.d.ts

@@ -7,7 +7,11 @@ import type { Options as ChromeLaunchOptions } from 'chrome-launcher';
 export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'connectionPollInterval' | 'maxConnectionRetries' | 'portStrictMode' | 'envVars' | 'handleSIGINT' | 'ignoreDefaultFlags' | 'chromeFlags' | 'chromePath'> {
     /** Remote debugging port (defaults to 9222 when omitted) */
     port?: number;
-    /** Directory for Chrome profile data. Falls back to persistent ~/.bdg/chrome-profile directory */
+    /**
+     * Directory for Chrome profile data, chosen by the user: bdg's default
+     * preferences are not written into it. Falls back to the bdg-managed
+     * persistent profile in the session directory (~/.bdg/chrome-profile)
+     */
     userDataDir?: string | undefined;
     /** Base directory for creating user data dir (defaults to OS temp dir, injectable for testing) */
     baseDir?: string | undefined;
@@ -23,7 +27,7 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
     prefsFile?: string | undefined;
     /** Override Chrome binary detection with an explicit path */
     chromePath?: string;
-    /** bdg session directory, recorded as a marker flag on the Chrome command line */
+    /** bdg session directory: recorded as a marker flag on the Chrome command line, and holds the default profile */
     sessionDir?: string | undefined;
 }
 /**
@@ -46,4 +50,19 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
  * Uses chrome-launcher for cross-platform Chrome detection and launching.
  */
 export declare function launchChrome(options?: LaunchOptions): Promise<LaunchedChrome>;
+/**
+ * Preferences for the launched profile: bdg's defaults (no translate prompt,
+ * no password manager or leak check, whose bubbles capture input) for
+ * profiles bdg manages, with the caller's preferences on top. A profile the
+ * user chose (`--user-data-dir`) gets only preferences the caller passed.
+ *
+ * File-based preferences take precedence over inline preferences because
+ * files allow for complex, reusable configurations that can be version
+ * controlled and shared across team members or CI environments.
+ *
+ * @param options - Launch options containing prefs or prefsFile
+ * @returns Merged preferences (empty when there is nothing to apply)
+ * @throws ChromeLaunchError if prefs file cannot be read or parsed, or prefs are not JSON
+ */
+export declare function resolveChromePrefs(options: LaunchOptions): Record<string, unknown>;
 //# sourceMappingURL=launcher.d.ts.map

package/dist/connection/launcher.js

@@ -6,10 +6,12 @@ import { BDG_CHROME_PREFS, DEFAULT_CDP_PORT, CHROME_PROFILE_DIR, DEFAULT_CHROME_
 import { getErrorMessage } from '../utils/errors.js';
 import { filterDefined } from '../utils/objects.js';
 import { isProcessAlive } from '../utils/process.js';
+import { verifyLaunchedChrome } from './chromeIdentity.js';
 import { ChromeLaunchError } from './errors.js';
 import { resolveChromeBinary } from './launcher/binaryResolver.js';
 import { buildChromeFlags } from './launcher/flagsBuilder.js';
 import { loadChromePrefs, ensureJSONCompatiblePrefs } from './launcher/preferencesLoader.js';
+import { writeProfilePreferences } from './launcher/profilePreferences.js';
 import { reservePort } from './portReservation.js';
 import { markStartupLogs, watchStartupExit } from './startupExit.js';
 /**
@@ -57,7 +59,7 @@ export async function launchChrome(options = {}) {
     }
     const reservation = await reservePort(port);
     reservation.release();
-    const userDataDir = options.userDataDir ?? getPersistentUserDataDir(options.baseDir);
+    const userDataDir = options.userDataDir ?? getPersistentUserDataDir(options.baseDir ?? options.sessionDir);
     if (!fs.existsSync(userDataDir)) {
         try {
             fs.mkdirSync(userDataDir, { recursive: true });
@@ -74,9 +76,11 @@ export async function launchChrome(options = {}) {
     }
     logger.info(`Launching Chrome on port ${port}...`);
     logger.debug(`User data directory: ${userDataDir}`);
-    const chromeOptions = buildChromeOptions(options);
+    applyProfilePreferences(userDataDir, options, logger);
+    const chromeOptions = buildChromeOptions({ ...options, port });
     const launcher = new chromeLauncher.Launcher(chromeOptions);
-    const startup = watchStartupExit(() => launcher.chromeProcess, markStartupLogs(userDataDir), userDataDir);
+    const logs = markStartupLogs(userDataDir);
+    const startup = watchStartupExit(() => launcher.chromeProcess, logs, userDataDir);
     try {
         const launchStart = Date.now();
         logger.info('Waiting for Chrome to be ready...');
@@ -96,10 +100,11 @@ export async function launchChrome(options = {}) {
                 },
             });
         }
+        await verifyLaunchedChrome({ logs, port, pid: chromeProcessPid });
         logger.info(`Chrome launched successfully (PID: ${chromeProcessPid}, ${launchDurationMs}ms)`);
         return {
             pid: chromeProcessPid,
-            port: launcher.port ?? port,
+            port,
             userDataDir: launcher.userDataDir,
             kill: async () => {
                 return Promise.resolve().then(() => {
@@ -128,7 +133,9 @@ export async function launchChrome(options = {}) {
 /**
  * Get the default persistent user-data-dir path.
  *
- * Uses the session directory ($BDG_SESSION_DIR) to store Chrome profile data,
+ * Uses the session directory (`~/.bdg`, `$BDG_SESSION_DIR`, or
+ * `<base>/sessions/<name>` for a named session, passed as `sessionDir`) to
+ * store Chrome profile data,
  * ensuring each session has its own isolated Chrome profile. This prevents
  * SingletonLock conflicts when multiple agents run concurrently.
  *
@@ -136,7 +143,7 @@ export async function launchChrome(options = {}) {
  * For shared login state across sessions, use --user-data-dir to specify a
  * shared location explicitly.
  *
- * @param baseDir - Optional base directory (defaults to session dir). Allows injection for testing or custom locations.
+ * @param baseDir - Optional base directory (defaults to `~/.bdg` or `$BDG_SESSION_DIR`). Allows injection for testing or custom locations.
  * @returns Absolute path to session-isolated user-data-dir
  * @throws Error if user data directory cannot be created due to permission issues
  */
@@ -168,32 +175,52 @@ function getPersistentUserDataDir(baseDir) {
     return userDataDir;
 }
 /**
- * Load Chrome preferences from options.
+ * Preferences for the launched profile: bdg's defaults (no translate prompt,
+ * no password manager or leak check, whose bubbles capture input) for
+ * profiles bdg manages, with the caller's preferences on top. A profile the
+ * user chose (`--user-data-dir`) gets only preferences the caller passed.
  *
  * File-based preferences take precedence over inline preferences because
  * files allow for complex, reusable configurations that can be version
  * controlled and shared across team members or CI environments.
  *
  * @param options - Launch options containing prefs or prefsFile
- * @returns Chrome preferences object or undefined if no preferences specified
- * @throws ChromeLaunchError if prefs file cannot be read, parsed, or doesn't exist
+ * @returns Merged preferences (empty when there is nothing to apply)
+ * @throws ChromeLaunchError if prefs file cannot be read or parsed, or prefs are not JSON
  */
+export function resolveChromePrefs(options) {
+    const defaults = options.userDataDir === undefined ? BDG_CHROME_PREFS : {};
+    const prefs = { ...defaults, ...loadChromePrefs(options) };
+    ensureJSONCompatiblePrefs(prefs);
+    return prefs;
+}
+/**
+ * Write the launch preferences into the profile, if there are any.
+ *
+ * @param userDataDir - Chrome user data directory
+ * @param options - Launch options
+ * @param logger - Logger for failures
+ * @throws ChromeLaunchError if prefs file cannot be read or parsed, or prefs are not JSON
+ */
+function applyProfilePreferences(userDataDir, options, logger) {
+    const prefs = resolveChromePrefs(options);
+    if (Object.keys(prefs).length > 0)
+        writeProfilePreferences(userDataDir, prefs, logger);
+}
 /**
  * Build chrome-launcher options from bdg launch options.
  *
  * Maps LaunchOptions to chrome-launcher API format using a clean utility approach
- * that filters out undefined values automatically. User preferences override bdg
- * defaults to allow customization while maintaining sensible base configuration.
+ * that filters out undefined values automatically. Preferences are not passed:
+ * chrome-launcher would replace whole nested sections of an existing profile's
+ * Preferences, so `writeProfilePreferences` merges them instead.
  *
  * @param options - bdg launch options to convert
  * @returns chrome-launcher compatible options object
- * @throws ChromeLaunchError if preference loading fails
  */
 function buildChromeOptions(options) {
-    const userPrefs = loadChromePrefs(options);
-    const userDataDir = options.userDataDir ?? getPersistentUserDataDir(options.baseDir);
+    const userDataDir = options.userDataDir ?? getPersistentUserDataDir(options.baseDir ?? options.sessionDir);
     const chromePathOverride = resolveChromeBinary(options);
-    const mergedPrefs = userPrefs ? { ...BDG_CHROME_PREFS, ...userPrefs } : BDG_CHROME_PREFS;
     return {
         logLevel: options.logLevel ?? DEFAULT_CHROME_LOG_LEVEL,
         handleSIGINT: options.handleSIGINT ?? DEFAULT_CHROME_HANDLE_SIGINT,
@@ -206,7 +233,6 @@ function buildChromeOptions(options) {
             connectionPollInterval: options.connectionPollInterval ?? CHROME_READY_POLL_MS,
             maxConnectionRetries: options.maxConnectionRetries ?? CHROME_READY_POLL_ATTEMPTS,
             portStrictMode: options.portStrictMode,
-            prefs: ensureJSONCompatiblePrefs(mergedPrefs),
             envVars: options.envVars,
             chromePath: chromePathOverride,
         }),

package/dist/connection/portReservation.d.ts

@@ -12,14 +12,24 @@ export interface PortReservation {
     release: () => void;
 }
 /**
- * Whether something already accepts connections on 127.0.0.1:port. A
- * listener on all interfaces (`0.0.0.0`/`::`) does not stop bdg from binding
- * 127.0.0.1 on macOS, but Chrome would then fail to listen, so it is checked
- * by connecting.
+ * Whether something already accepts connections on host:port.
  *
  * @param port - Port to check
+ * @param host - Address to connect to
  * @returns True if a connection was accepted
  */
+export declare function acceptsConnections(port: number, host: string): Promise<boolean>;
+/**
+ * Whether something already accepts connections on the port, on 127.0.0.1 or
+ * ::1. A listener on all interfaces (`0.0.0.0`/`::`) does not stop bdg from
+ * binding 127.0.0.1 on macOS, but Chrome would then fail to listen; a Chrome
+ * on [::1] (one that found 127.0.0.1 taken) does not stop it either, but a
+ * second Chrome would be reached through the first one's port. Both are found
+ * by connecting.
+ *
+ * @param port - Port to check
+ * @returns True if a connection was accepted on either address
+ */
 export declare function isPortAnswering(port: number): Promise<boolean>;
 /**
  * Atomically reserve a port to prevent race conditions during Chrome launch.

package/dist/connection/portReservation.js

@@ -8,18 +8,18 @@ import * as net from 'net';
 import { ChromeLaunchError } from './errors.js';
 /** How long a connection attempt may take when checking a port */
 const CONNECT_CHECK_MS = 500;
+/** Loopback addresses Chrome may listen on (it falls back to IPv6 when IPv4 is taken) */
+const LOOPBACK_HOSTS = ['127.0.0.1', '::1'];
 /**
- * Whether something already accepts connections on 127.0.0.1:port. A
- * listener on all interfaces (`0.0.0.0`/`::`) does not stop bdg from binding
- * 127.0.0.1 on macOS, but Chrome would then fail to listen, so it is checked
- * by connecting.
+ * Whether something already accepts connections on host:port.
  *
  * @param port - Port to check
+ * @param host - Address to connect to
  * @returns True if a connection was accepted
  */
-export function isPortAnswering(port) {
+export function acceptsConnections(port, host) {
     return new Promise((resolve) => {
-        const socket = net.connect({ port, host: '127.0.0.1' });
+        const socket = net.connect({ port, host });
         const finish = (answering) => {
             socket.destroy();
             resolve(answering);
@@ -29,6 +29,21 @@ export function isPortAnswering(port) {
         socket.once('error', () => finish(false));
     });
 }
+/**
+ * Whether something already accepts connections on the port, on 127.0.0.1 or
+ * ::1. A listener on all interfaces (`0.0.0.0`/`::`) does not stop bdg from
+ * binding 127.0.0.1 on macOS, but Chrome would then fail to listen; a Chrome
+ * on [::1] (one that found 127.0.0.1 taken) does not stop it either, but a
+ * second Chrome would be reached through the first one's port. Both are found
+ * by connecting.
+ *
+ * @param port - Port to check
+ * @returns True if a connection was accepted on either address
+ */
+export async function isPortAnswering(port) {
+    const answers = await Promise.all(LOOPBACK_HOSTS.map((host) => acceptsConnections(port, host)));
+    return answers.some(Boolean);
+}
 /**
  * The error for a port another process uses.
  *

package/dist/connection/startupExit.d.ts

@@ -22,6 +22,14 @@ export interface StartupLogs {
  * @returns Log positions
  */
 export declare function markStartupLogs(userDataDir: string): StartupLogs;
+/**
+ * Chrome's output (stderr, then stdout) since {@link markStartupLogs}. The
+ * marked offsets are byte sizes, so the files are cut before decoding.
+ *
+ * @param logs - Log positions
+ * @returns Output lines
+ */
+export declare function readStartupLines(logs: StartupLogs): string[];
 /**
  * Reject when the launched Chrome exits before it is ready.
  *

package/dist/connection/startupExit.js

@@ -31,18 +31,27 @@ export function markStartupLogs(userDataDir) {
     };
 }
 /**
- * Chrome's output since {@link markStartupLogs}, last lines first trimmed.
+ * Chrome's output (stderr, then stdout) since {@link markStartupLogs}. The
+ * marked offsets are byte sizes, so the files are cut before decoding.
  *
  * @param logs - Log positions
- * @returns Up to {@link OUTPUT_LINES} non-empty lines
+ * @returns Output lines
  */
-function readStartupOutput(logs) {
-    const lines = logs.files.flatMap(({ file, offset }) => {
+export function readStartupLines(logs) {
+    return logs.files.flatMap(({ file, offset }) => {
         if (!fs.existsSync(file))
             return [];
-        return fs.readFileSync(file, 'utf8').slice(offset).split('\n');
+        return fs.readFileSync(file).subarray(offset).toString('utf8').split('\n');
     });
-    return lines
+}
+/**
+ * Chrome's output since {@link markStartupLogs}, last lines first trimmed.
+ *
+ * @param logs - Log positions
+ * @returns Up to {@link OUTPUT_LINES} non-empty lines
+ */
+function readStartupOutput(logs) {
+    return readStartupLines(logs)
         .map((line) => line.trim())
         .filter(Boolean)
         .slice(-OUTPUT_LINES);

package/dist/constants.d.ts

@@ -46,8 +46,12 @@ export declare const BDG_CHROME_FLAGS: string[];
 export declare const DOCKER_CHROME_FLAGS: string[];
 /**
  * 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.