browser-commander 0.19.0 → 0.21.0

package/src/browser/real-browser.js

@@ -1,259 +1,108 @@
-import { spawn } from 'node:child_process';
-import { constants } from 'node:fs';
-import { access, mkdir, readFile } from 'node:fs/promises';
-import os from 'node:os';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
+import { startProcess } from '../utilities/subprocess.js';
+import {
+  applyAutomationParityArgs,
+  detectAutomationControlledTriggers,
+} from '../fingerprint/automation-parity.js';
+import {
+  prepareSnapshotLaunch,
+  validateAttachOption,
+} from './attach/snapshot-launch.js';
 import { connectBrowser } from './connector.js';
-import { resolveChromeArgs } from './launch-options.js';
+import { migrateProfile } from './migration/index.js';
+import {
+  assertFixedDebuggingPort,
+  classifyDevToolsOwnership,
+  LOOPBACK_HOST,
+  PortRaceError,
+  reserveLoopbackPort,
+  watchDevToolsOutput,
+} from './debugging-port.js';
+import {
+  createTemporaryUserDataDir,
+  prepareUserDataDir,
+  removeUserDataDir,
+} from './profile-directory.js';
+import {
+  assertStringArray,
+  mergeFeatureSwitches,
+  resolveRestrictions,
+} from './restrictions.js';
+import {
+  assertDedicatedUserDataDir,
+  defaultUserDataDir,
+  knownDefaultUserDataDirs,
+  resolveSystemBrowserExecutable,
+} from './system-browser.js';
 
+/**
+ * Switches the launcher owns. Letting a caller pass them would break the
+ * guarantees of this path: DevTools bound to loopback only, a dedicated
+ * profile, and no switch that turns AutomationControlled on (issue #101).
+ */
 const MANAGED_ARGUMENTS = [
   '--remote-debugging-address',
   '--remote-debugging-port',
+  '--remote-debugging-pipe',
   '--user-data-dir',
 ];
 
-const CHANNEL_EXECUTABLE_NAMES = {
-  brave: ['brave-browser', 'brave-browser-stable', 'brave'],
-  chrome: ['google-chrome', 'google-chrome-stable', 'chrome'],
-  'chrome-beta': ['google-chrome-beta'],
-  'chrome-canary': ['google-chrome-canary'],
-  'chrome-dev': ['google-chrome-unstable'],
-  chromium: ['chromium', 'chromium-browser'],
-  msedge: ['microsoft-edge', 'microsoft-edge-stable', 'msedge'],
-  'msedge-beta': ['microsoft-edge-beta'],
-  'msedge-canary': ['microsoft-edge-canary'],
-  'msedge-dev': ['microsoft-edge-dev'],
-};
-
-function platformPath(platform) {
-  return platform === 'win32' ? path.win32 : path;
-}
-
-function defaultUserDataDir(channel, homeDir = os.homedir()) {
-  const directoryName = channel.replace(/[^a-z0-9_.-]/gi, '-');
-  return path.join(
-    homeDir,
-    '.browser-commander',
-    'real-browser',
-    directoryName
-  );
-}
-
-function knownDefaultUserDataDirs({
-  platform = process.platform,
-  homeDir = os.homedir(),
-  environment = process.env,
-} = {}) {
-  const pathApi = platformPath(platform);
-  if (platform === 'darwin') {
-    const applicationSupport = pathApi.join(
-      homeDir,
-      'Library',
-      'Application Support'
-    );
-    return [
-      pathApi.join(applicationSupport, 'Google', 'Chrome'),
-      pathApi.join(applicationSupport, 'Google', 'Chrome Beta'),
-      pathApi.join(applicationSupport, 'Google', 'Chrome Canary'),
-      pathApi.join(applicationSupport, 'Google', 'Chrome Dev'),
-      pathApi.join(applicationSupport, 'Chromium'),
-      pathApi.join(applicationSupport, 'BraveSoftware', 'Brave-Browser'),
-      pathApi.join(applicationSupport, 'BraveSoftware', 'Brave-Browser-Beta'),
-      pathApi.join(
-        applicationSupport,
-        'BraveSoftware',
-        'Brave-Browser-Nightly'
-      ),
-      pathApi.join(applicationSupport, 'Microsoft Edge'),
-      pathApi.join(applicationSupport, 'Microsoft Edge Beta'),
-      pathApi.join(applicationSupport, 'Microsoft Edge Canary'),
-      pathApi.join(applicationSupport, 'Microsoft Edge Dev'),
-    ];
-  }
-  if (platform === 'win32') {
-    const localAppData =
-      environment.LOCALAPPDATA ?? pathApi.join(homeDir, 'AppData', 'Local');
-    return [
-      pathApi.join(localAppData, 'Google', 'Chrome', 'User Data'),
-      pathApi.join(localAppData, 'Google', 'Chrome Beta', 'User Data'),
-      pathApi.join(localAppData, 'Google', 'Chrome Dev', 'User Data'),
-      pathApi.join(localAppData, 'Google', 'Chrome SxS', 'User Data'),
-      pathApi.join(localAppData, 'Chromium', 'User Data'),
-      pathApi.join(localAppData, 'BraveSoftware', 'Brave-Browser', 'User Data'),
-      pathApi.join(
-        localAppData,
-        'BraveSoftware',
-        'Brave-Browser-Beta',
-        'User Data'
-      ),
-      pathApi.join(
-        localAppData,
-        'BraveSoftware',
-        'Brave-Browser-Nightly',
-        'User Data'
-      ),
-      pathApi.join(localAppData, 'Microsoft', 'Edge', 'User Data'),
-      pathApi.join(localAppData, 'Microsoft', 'Edge Beta', 'User Data'),
-      pathApi.join(localAppData, 'Microsoft', 'Edge Dev', 'User Data'),
-      pathApi.join(localAppData, 'Microsoft', 'Edge SxS', 'User Data'),
-    ];
-  }
-  return [
-    pathApi.join(homeDir, '.config', 'google-chrome'),
-    pathApi.join(homeDir, '.config', 'google-chrome-beta'),
-    pathApi.join(homeDir, '.config', 'google-chrome-unstable'),
-    pathApi.join(homeDir, '.config', 'chromium'),
-    pathApi.join(homeDir, '.config', 'BraveSoftware', 'Brave-Browser'),
-    pathApi.join(homeDir, '.config', 'BraveSoftware', 'Brave-Browser-Beta'),
-    pathApi.join(homeDir, '.config', 'BraveSoftware', 'Brave-Browser-Nightly'),
-    pathApi.join(homeDir, '.config', 'microsoft-edge'),
-    pathApi.join(homeDir, '.config', 'microsoft-edge-beta'),
-    pathApi.join(homeDir, '.config', 'microsoft-edge-dev'),
-  ];
-}
-
-/** Ensure Chrome is not asked to expose the user's default profile over CDP. */
-export function assertDedicatedUserDataDir(userDataDir, platformOptions = {}) {
-  if (!userDataDir) {
-    throw new Error('launchAndConnectRealBrowser requires a userDataDir');
-  }
-  const platform = platformOptions.platform ?? process.platform;
-  const pathApi = platformPath(platform);
-  const normalize = (value) => {
-    const resolved = pathApi.resolve(value).replace(/[\\/]+$/, '');
-    return platform === 'win32' ? resolved.toLowerCase() : resolved;
-  };
-  const requested = normalize(userDataDir);
-  const isDefault = knownDefaultUserDataDirs(platformOptions).some(
-    (directory) => normalize(directory) === requested
-  );
-  if (isDefault) {
-    throw new Error(
-      'launchAndConnectRealBrowser requires a dedicated userDataDir, not a browser default profile'
-    );
-  }
-}
-
-function browserInstallCandidates({
-  channel,
-  platform = process.platform,
-  environment = process.env,
-}) {
-  const candidates = [];
-  const names = CHANNEL_EXECUTABLE_NAMES[channel];
-  if (!names) {
-    throw new Error(
-      `Unknown browser channel: ${channel}. Expected one of ${Object.keys(CHANNEL_EXECUTABLE_NAMES).join(', ')}`
-    );
-  }
-
-  if (platform === 'darwin') {
-    const applications = {
-      brave: 'Brave Browser.app/Contents/MacOS/Brave Browser',
-      chrome: 'Google Chrome.app/Contents/MacOS/Google Chrome',
-      'chrome-beta': 'Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta',
-      'chrome-canary':
-        'Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
-      'chrome-dev': 'Google Chrome Dev.app/Contents/MacOS/Google Chrome Dev',
-      chromium: 'Chromium.app/Contents/MacOS/Chromium',
-      msedge: 'Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
-      'msedge-beta':
-        'Microsoft Edge Beta.app/Contents/MacOS/Microsoft Edge Beta',
-      'msedge-canary':
-        'Microsoft Edge Canary.app/Contents/MacOS/Microsoft Edge Canary',
-      'msedge-dev': 'Microsoft Edge Dev.app/Contents/MacOS/Microsoft Edge Dev',
-    };
-    candidates.push(path.join('/Applications', applications[channel]));
-  } else if (platform === 'win32') {
-    const roots = [
-      environment.PROGRAMFILES,
-      environment['PROGRAMFILES(X86)'],
-      environment.LOCALAPPDATA,
-    ].filter(Boolean);
-    const relativePaths = {
-      brave: ['BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'],
-      chrome: ['Google', 'Chrome', 'Application', 'chrome.exe'],
-      'chrome-beta': ['Google', 'Chrome Beta', 'Application', 'chrome.exe'],
-      'chrome-canary': ['Google', 'Chrome SxS', 'Application', 'chrome.exe'],
-      'chrome-dev': ['Google', 'Chrome Dev', 'Application', 'chrome.exe'],
-      chromium: ['Chromium', 'Application', 'chrome.exe'],
-      msedge: ['Microsoft', 'Edge', 'Application', 'msedge.exe'],
-      'msedge-beta': ['Microsoft', 'Edge Beta', 'Application', 'msedge.exe'],
-      'msedge-canary': ['Microsoft', 'Edge SxS', 'Application', 'msedge.exe'],
-      'msedge-dev': ['Microsoft', 'Edge Dev', 'Application', 'msedge.exe'],
-    };
-    for (const root of roots) {
-      candidates.push(path.win32.join(root, ...relativePaths[channel]));
-    }
-  } else {
-    for (const name of names) {
-      candidates.push(`/usr/bin/${name}`, `/usr/local/bin/${name}`);
-    }
-    if (channel === 'chrome') {
-      candidates.push('/opt/google/chrome/google-chrome');
-    }
-  }
-
-  const pathApi = platformPath(platform);
-  const delimiter = platform === 'win32' ? ';' : path.delimiter;
-  for (const directory of (environment.PATH ?? '').split(delimiter)) {
-    if (!directory) {
-      continue;
-    }
-    for (const name of names) {
-      candidates.push(
-        pathApi.join(directory, platform === 'win32' ? `${name}.exe` : name)
-      );
-    }
-  }
-  return [...new Set(candidates)];
-}
-
-/** Resolve a genuine installed Chrome-family browser executable. */
-export async function resolveSystemBrowserExecutable({
-  channel = 'chrome',
-  executablePath,
-  platform = process.platform,
-  environment = process.env,
-} = {}) {
-  const candidates = executablePath
-    ? [path.resolve(executablePath)]
-    : browserInstallCandidates({ channel, platform, environment });
-  for (const candidate of candidates) {
-    try {
-      await access(candidate, constants.X_OK);
-      return candidate;
-    } catch {
-      // Continue through known locations and PATH entries.
-    }
-  }
-  throw new Error(
-    executablePath
-      ? `Browser executable is not accessible: ${executablePath}`
-      : `Could not find an installed ${channel} browser; provide executablePath`
-  );
-}
+/**
+ * The page a real launch opens when the caller passes no start URL.
+ *
+ * With no URL at all a browser opens its start pages instead: Chrome the New
+ * Tab page, Edge the MSN New Tab page and edge://welcome-new-profile, whose
+ * flow closes the window - and so ends the browser - a few seconds after the
+ * launch. Playwright and Puppeteer open about:blank for the same reason. The
+ * URL is not a switch, and a page cannot see how its tab was first opened.
+ */
+const START_URL = 'about:blank';
 
-/** Build the protected command line used for a real browser CDP process. */
+/**
+ * Build the command line for a real browser.
+ *
+ * By default it is exactly what a person would type to allow a debugger:
+ * `--user-data-dir=<dir> --remote-debugging-port=<port> about:blank` (issue
+ * #103), and a start URL among the custom `args` replaces `about:blank`. The
+ * fixed port keeps `navigator.webdriver` false without any extra switch
+ * (issue #101). Everything else is opt-in: `headless`, named `restrictions`
+ * and custom `args`.
+ *
+ * Chrome's DevTools server binds to loopback by default, so no
+ * `--remote-debugging-address` is passed; the switch stays managed so custom
+ * arguments cannot expose DevTools on another interface.
+ *
+ * `--headless` is not an AutomationControlled trigger (a hand-started headless
+ * Chrome reports `navigator.webdriver === false`), so a headless launch gets
+ * no off switch either. Only when a custom argument is a trigger is the off
+ * switch added, unless `automationParity` is false.
+ *
+ * @param {Object} options
+ * @param {string} options.userDataDir - Dedicated profile directory
+ * @param {number} options.remoteDebuggingPort - Fixed loopback port, 1-65535
+ * @param {boolean} [options.headless=false]
+ * @param {string[]} [options.restrictions] - Names from launch-restrictions.json
+ * @param {string[]} [options.args] - Additional switches
+ * @param {string[]} [options.extraArgs] - Additional switches appended after args
+ * @param {boolean} [options.automationParity=true]
+ * @returns {string[]}
+ */
 export function buildRealBrowserArgs({
   userDataDir,
-  remoteDebuggingPort = 0,
+  remoteDebuggingPort,
   headless = false,
+  restrictions = [],
   args = [],
   extraArgs = [],
-  ignoreDefaultArgs = [],
+  automationParity = true,
 }) {
-  if (
-    !Number.isInteger(remoteDebuggingPort) ||
-    remoteDebuggingPort < 0 ||
-    remoteDebuggingPort > 65_535
-  ) {
-    throw new RangeError(
-      'remoteDebuggingPort must be an integer from 0 to 65535'
-    );
-  }
-  const customArgs = [...args, ...extraArgs];
+  assertFixedDebuggingPort(remoteDebuggingPort);
+  const customArgs = [
+    ...assertStringArray(args, 'args'),
+    ...assertStringArray(extraArgs, 'extraArgs'),
+  ];
   const conflictingArgument = customArgs.find((argument) =>
     MANAGED_ARGUMENTS.some(
       (managed) => argument === managed || argument.startsWith(`${managed}=`)
@@ -265,16 +114,23 @@ export function buildRealBrowserArgs({
     );
   }
 
-  const defaultArgs = resolveChromeArgs({ ignoreDefaultArgs }).args;
-
-  return [
-    '--remote-debugging-address=127.0.0.1',
-    `--remote-debugging-port=${remoteDebuggingPort}`,
+  let browserArgs = mergeFeatureSwitches([
     `--user-data-dir=${userDataDir}`,
-    ...defaultArgs,
+    `--remote-debugging-port=${remoteDebuggingPort}`,
     ...(headless ? ['--headless=new'] : []),
+    ...resolveRestrictions(restrictions).args,
     ...customArgs,
-  ];
+  ]);
+  if (
+    automationParity &&
+    detectAutomationControlledTriggers(browserArgs).length > 0
+  ) {
+    browserArgs = applyAutomationParityArgs(browserArgs);
+  }
+  if (browserArgs.every((argument) => argument.startsWith('-'))) {
+    browserArgs.push(START_URL);
+  }
+  return browserArgs;
 }
 
 async function fetchCdpVersion(endpoint, fetchImplementation, timeout) {
@@ -285,85 +141,198 @@ async function fetchCdpVersion(endpoint, fetchImplementation, timeout) {
       signal: controller.signal,
     });
     if (!response.ok) {
-      return false;
+      return null;
     }
     const version = await response.json();
-    return Boolean(version.webSocketDebuggerUrl);
+    return version.webSocketDebuggerUrl ? version : null;
   } finally {
     clearTimeout(timer);
   }
 }
 
-/** Wait until Chrome publishes a usable DevTools endpoint. */
+async function readDevToolsActivePort(userDataDir) {
+  try {
+    const content = await readFile(
+      path.join(userDataDir, 'DevToolsActivePort'),
+      'utf8'
+    );
+    const [port, browserPath] = content.split(/\r?\n/);
+    return { port: Number.parseInt(port, 10), browserPath };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Wait until the browser we spawned publishes its DevTools endpoint on the
+ * reserved port, and prove that the endpoint belongs to it.
+ *
+ * Proof comes from the browser's own stderr (`DevTools listening on
+ * ws://127.0.0.1:<port>/devtools/browser/<id>`), whose browser id must match
+ * the `webSocketDebuggerUrl` served on the port. Chrome writes
+ * `DevToolsActivePort` only for port 0, so the file is accepted as proof when
+ * present (for callers that bring their own spawn) but never required.
+ *
+ * @throws {PortRaceError} When another process holds the port
+ */
 export async function waitForCdpEndpoint({
   remoteDebuggingPort,
   userDataDir,
   browserProcess,
+  devToolsOutput = watchDevToolsOutput(browserProcess?.stderr),
   timeout = 30_000,
   fetchImplementation = globalThis.fetch,
 }) {
+  const port = assertFixedDebuggingPort(remoteDebuggingPort);
+  const endpoint = `http://${LOOPBACK_HOST}:${port}`;
   const deadline = Date.now() + timeout;
   while (Date.now() < deadline) {
+    const output = devToolsOutput.state();
+    let ownership = devToolsOutput.available
+      ? classifyDevToolsOwnership(output, port)
+      : 'unknown';
+    if (ownership === 'race') {
+      throw new PortRaceError(port, output.listening?.url ?? 'bind failed');
+    }
     if (browserProcess.exitCode !== null) {
       throw new Error(
         `Browser exited before its DevTools endpoint was ready (exit ${browserProcess.exitCode})`
       );
     }
+    if (ownership !== 'owned') {
+      const activePort = await readDevToolsActivePort(userDataDir);
+      if (activePort?.port === port) {
+        ownership = 'owned';
+      }
+    }
 
-    let port = remoteDebuggingPort;
-    if (port === 0) {
+    if (ownership === 'owned') {
+      let version = null;
       try {
-        const activePort = await readFile(
-          path.join(userDataDir, 'DevToolsActivePort'),
-          'utf8'
+        version = await fetchCdpVersion(
+          endpoint,
+          fetchImplementation,
+          Math.max(1, deadline - Date.now())
         );
-        port = Number.parseInt(activePort.split(/\r?\n/, 1)[0], 10);
       } catch {
-        port = 0;
+        // The HTTP handler can lag the listening line by a moment.
       }
-    }
-
-    if (port > 0) {
-      const endpoint = `http://127.0.0.1:${port}`;
-      try {
-        if (
-          await fetchCdpVersion(
-            endpoint,
-            fetchImplementation,
-            Math.max(1, deadline - Date.now())
-          )
-        ) {
-          return endpoint;
+      if (version) {
+        const expected = output.listening?.url;
+        if (expected && version.webSocketDebuggerUrl !== expected) {
+          throw new PortRaceError(
+            port,
+            `port serves ${version.webSocketDebuggerUrl}, browser announced ${expected}`
+          );
         }
-      } catch {
-        // Chrome may have allocated the port before /json/version is ready.
+        return endpoint;
       }
     }
     await new Promise((resolve) => setTimeout(resolve, 100));
   }
   throw new Error(
-    `Timed out after ${timeout}ms waiting for the DevTools endpoint`
+    `Timed out after ${timeout}ms waiting for the DevTools endpoint on port ${port}`
   );
 }
 
+function spawnWithStartProcess(executablePath, args, { env, verbose }) {
+  return startProcess(executablePath, args, { env, forwardOutput: verbose });
+}
+
+async function waitForExit(browserProcess, timeout) {
+  if (browserProcess.exitCode !== null) {
+    return true;
+  }
+  if (typeof browserProcess.once !== 'function') {
+    return false;
+  }
+  let timer;
+  const exited = await Promise.race([
+    new Promise((resolve) => browserProcess.once('exit', () => resolve(true))),
+    new Promise((resolve) => {
+      timer = setTimeout(() => resolve(false), timeout);
+    }),
+  ]);
+  clearTimeout(timer);
+  return exited;
+}
+
+async function requestBrowserClose({ engine, browser, originalClose }) {
+  if (engine === 'puppeteer') {
+    // A connected Puppeteer Browser sends Browser.close and waits for it.
+    await originalClose.call(browser);
+    return;
+  }
+  // Playwright's close() only disconnects from a connectOverCDP browser, so
+  // ask Chrome itself to shut down, then drop the connection.
+  const session = await browser.newBrowserCDPSession();
+  await session.send('Browser.close').catch(() => {});
+  await originalClose.call(browser).catch(() => {});
+}
+
+function createCloser({
+  engine,
+  browser,
+  browserProcess,
+  userDataDir,
+  temporaryProfile,
+  closeTimeout,
+}) {
+  const originalClose = browser?.close;
+  let closing;
+  const close = () => {
+    closing ??= (async () => {
+      if (browserProcess.exitCode === null && originalClose) {
+        await requestBrowserClose({ engine, browser, originalClose }).catch(
+          () => {}
+        );
+      }
+      if (!(await waitForExit(browserProcess, closeTimeout))) {
+        browserProcess.kill();
+        await waitForExit(browserProcess, closeTimeout);
+      }
+      if (temporaryProfile) {
+        await removeUserDataDir(userDataDir);
+      }
+    })();
+    return closing;
+  };
+  if (browser && originalClose) {
+    // `browser.close()` means "close the browser" for every caller, so it
+    // shuts the spawned process down and deletes a temporary profile too.
+    browser.close = close;
+  }
+  return close;
+}
+
 /**
- * Spawn a genuine installed Chrome-family browser with an isolated profile,
+ * Spawn a genuine installed Chrome-family browser with a dedicated profile,
  * wait for its loopback CDP endpoint, and attach through {@link connectBrowser}.
  *
+ * The command line is `--user-data-dir=<dir> --remote-debugging-port=<port>`
+ * and nothing else unless asked for, so the session is as close to a
+ * hand-started browser as CDP allows and `navigator.webdriver` is false.
+ *
  * @param {Object} options - Launch and connection options
  * @param {'playwright'|'puppeteer'} [options.engine='playwright'] - Automation engine
  * @param {string} [options.channel='chrome'] - Installed Chrome-family channel
  * @param {string} [options.executablePath] - Explicit installed browser executable
- * @param {string} [options.userDataDir] - Dedicated non-default browser profile
- * @param {number} [options.remoteDebuggingPort=0] - Loopback CDP port; zero lets Chrome choose
+ * @param {string} [options.userDataDir] - Persistent dedicated profile. When omitted a fresh temporary profile is created and deleted on close.
+ * @param {number} [options.remoteDebuggingPort] - Fixed loopback CDP port. When omitted a free port is reserved (and re-reserved on a port race). Zero is refused because it sets navigator.webdriver.
+ * @param {number} [options.portAttempts=3] - Launch attempts when a reserved port is lost to a race
  * @param {boolean} [options.headless=false] - Run the installed browser headlessly
+ * @param {string[]} [options.restrictions] - Opt-in restrictions from launch-restrictions.json, such as 'no-extensions'
  * @param {string[]} [options.args] - Additional browser arguments
- * @param {string[]} [options.extraArgs] - Additional browser arguments appended after legacy args
- * @param {boolean|string[]} [options.ignoreDefaultArgs] - Browser Commander defaults to omit, or true for all
+ * @param {string[]} [options.extraArgs] - Additional browser arguments appended after args
+ * @param {Object<string,string>} [options.env] - Extra environment for the browser process only
+ * @param {boolean} [options.automationParity=true] - Add the AutomationControlled off switch when a custom argument turns the feature on
  * @param {number} [options.startupTimeout=30000] - CDP readiness timeout in milliseconds
+ * @param {number} [options.closeTimeout=5000] - How long close() waits before killing the process
  * @param {Object[]} [options.seedCookies] - Cookies to seed after connecting
+ * @param {{browser: string, profile: (string|undefined), userDataDir: (string|undefined), include: (Array<string>|undefined), domains: (Array<string>|undefined)}} [options.migrateFrom] - Migrate a real browser profile into the dedicated profile before launch; on-disk data is written before the browser starts and cookies are seeded over CDP after connecting
+ * @param {{mode: 'snapshot', browser: (string|undefined), profile: (string|undefined), userDataDir: (string|undefined)}} [options.attach] - Launch on a read-only snapshot of a real profile (issue #102, addendum): `snapshotUserDataDir()` copies it into a temporary user data directory, which is deleted on close. `browser` defaults to the channel's browser and `profile` to Default. Mutually exclusive with `migrateFrom` and `userDataDir`.
  * @param {boolean} [options.verbose=false] - Show browser and connection logs
- * @returns {Promise<{browser: Object, page: Object, browserProcess: Object, cdpEndpoint: string, executablePath: string, userDataDir: string}>} Connected handles and process metadata
+ * @returns {Promise<{browser: Object, page: Object, downloads: (Object|null), close: function(): Promise<void>, browserProcess: Object, cdpEndpoint: string, remoteDebuggingPort: number, executablePath: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>, migration: (Object|undefined), attach: ({mode: 'snapshot', snapshot: Object, differences: Array<{aspect: string, description: string}>}|undefined)}>} Connected handles and process metadata (with a `migration` report when `migrateFrom` was given and an `attach` entry when `attach` was given)
  */
 export async function launchAndConnectRealBrowser(options = {}) {
   return await launchAndConnectRealBrowserWithDependencies(options);
@@ -378,7 +347,175 @@ export async function launchAndConnectRealBrowser(options = {}) {
  */
 export const launchRealBrowser = launchAndConnectRealBrowser;
 
+async function spawnOnFreePort({
+  requestedPort,
+  portAttempts,
+  executablePath,
+  argOptions,
+  env,
+  verbose,
+  userDataDir,
+  startupTimeout,
+  dependencies,
+}) {
+  const reservePort = dependencies.reservePort ?? reserveLoopbackPort;
+  const spawnBrowser = dependencies.spawnBrowser ?? spawnWithStartProcess;
+  const waitForEndpoint = dependencies.waitForEndpoint ?? waitForCdpEndpoint;
+  const attempts = requestedPort === undefined ? portAttempts : 1;
+  for (let attempt = 1; ; attempt++) {
+    const port = requestedPort ?? (await reservePort());
+    const browserArgs = buildRealBrowserArgs({
+      ...argOptions,
+      userDataDir,
+      remoteDebuggingPort: port,
+    });
+    const browserProcess = spawnBrowser(executablePath, browserArgs, {
+      env,
+      verbose,
+    });
+    try {
+      const cdpEndpoint = await waitForEndpoint({
+        remoteDebuggingPort: port,
+        userDataDir,
+        browserProcess,
+        timeout: startupTimeout,
+      });
+      return { browserProcess, cdpEndpoint, port, browserArgs };
+    } catch (error) {
+      if (browserProcess.exitCode === null) {
+        browserProcess.kill();
+      }
+      if (!(error instanceof PortRaceError) || attempt >= attempts) {
+        throw error;
+      }
+      if (verbose) {
+        console.log(`${error.message}; retrying with a new port`);
+      }
+      await waitForExit(browserProcess, 5_000);
+    }
+  }
+}
+
+/** Reject a launch request before anything touches the disk. */
+function validateLaunchRequest({
+  argOptions,
+  userDataDir,
+  remoteDebuggingPort,
+  endpoint,
+  attach,
+  migrateFrom,
+}) {
+  if (endpoint) {
+    throw new Error(
+      'launchAndConnectRealBrowser creates its own endpoint; use connectBrowser to attach to an existing endpoint'
+    );
+  }
+  validateAttachOption({
+    attach,
+    migrateFrom,
+    userDataDir,
+    customArgs: [argOptions.args, argOptions.extraArgs].flatMap((list) =>
+      Array.isArray(list) ? list : []
+    ),
+  });
+  if (remoteDebuggingPort !== undefined) {
+    assertFixedDebuggingPort(remoteDebuggingPort);
+  }
+  buildRealBrowserArgs({
+    ...argOptions,
+    userDataDir: userDataDir ?? 'validation',
+    remoteDebuggingPort: remoteDebuggingPort ?? 1,
+  });
+  if (userDataDir) {
+    assertDedicatedUserDataDir(userDataDir);
+  }
+}
+
+/**
+ * Environment for the browser process. Restriction environment (for example
+ * no-google-services) goes to the browser only; this process's environment is
+ * never modified.
+ */
+function browserEnvironment(restrictions, env) {
+  const restrictionEnv = resolveRestrictions(restrictions).env;
+  return env || Object.keys(restrictionEnv).length > 0
+    ? { ...process.env, ...restrictionEnv, ...env }
+    : undefined;
+}
+
+/**
+ * Create the profile the browser starts with: a snapshot of a real profile
+ * for `attach`, a fresh temporary one, or the caller's dedicated one. A
+ * snapshot is a temporary profile too and is deleted on close. The snapshot's
+ * `--profile-directory` switch is put before the custom `args`.
+ */
+async function prepareProfile({
+  attach,
+  channel,
+  requestedUserDataDir,
+  argOptions,
+  snapshot,
+}) {
+  if (attach) {
+    const snapshotLaunch = await prepareSnapshotLaunch({
+      attach,
+      channel,
+      restrictions: argOptions.restrictions,
+      customArgs: [...argOptions.args, ...argOptions.extraArgs],
+      snapshot,
+    });
+    argOptions.args = [...snapshotLaunch.args, ...argOptions.args];
+    return { userDataDir: snapshotLaunch.userDataDir, snapshotLaunch };
+  }
+  return {
+    userDataDir: requestedUserDataDir
+      ? await prepareUserDataDir(requestedUserDataDir)
+      : await createTemporaryUserDataDir(),
+  };
+}
+
 /** Dependency-injected implementation used by the public helper and tests. */
+/**
+ * Migrate a real browser profile into the dedicated profile before launch.
+ *
+ * On-disk data classes (bookmarks, history, passwords, preferences,
+ * extensions) must be in place before the browser starts, so this runs before
+ * the process is spawned. Cookies are returned instead of written because a
+ * running Chromium re-derives its own encryption; the caller seeds them over
+ * CDP after connecting. On failure a freshly created temporary profile is
+ * removed before the error propagates.
+ *
+ * @returns {Promise<{migration: (Object|undefined), migratedCookies: Array<Object>}>}
+ */
+async function runPreLaunchMigration({
+  migrateFrom,
+  userDataDir,
+  channel,
+  temporaryProfile,
+  migrate,
+}) {
+  if (!migrateFrom) {
+    return { migration: undefined, migratedCookies: [] };
+  }
+  const { include, domains, ...from } = migrateFrom;
+  try {
+    const report = await migrate({
+      from,
+      to: path.join(userDataDir, 'Default'),
+      include,
+      domains,
+      targetBrowser: channel,
+    });
+    const { cookies, ...migration } = report;
+    return { migration, migratedCookies: cookies ?? [] };
+  } catch (error) {
+    if (temporaryProfile) {
+      await removeUserDataDir(userDataDir);
+    }
+    throw error;
+  }
+}
+
 export async function launchAndConnectRealBrowserWithDependencies(
   options = {},
   dependencies = {}
@@ -387,73 +524,143 @@ export async function launchAndConnectRealBrowserWithDependencies(
     engine = 'playwright',
     channel = 'chrome',
     executablePath: requestedExecutablePath,
-    userDataDir = defaultUserDataDir(channel),
-    remoteDebuggingPort = 0,
+    userDataDir: requestedUserDataDir,
+    remoteDebuggingPort,
+    portAttempts = 3,
     headless = false,
+    restrictions = [],
     args = [],
     extraArgs = [],
-    ignoreDefaultArgs = [],
+    ignoreDefaultArgs: _ignoredLegacyDefaults,
+    env,
+    automationParity = true,
     startupTimeout = 30_000,
+    closeTimeout = 5_000,
     verbose = false,
     cdpEndpoint,
     wsEndpoint,
+    migrateFrom,
+    attach,
     ...connectionOptions
   } = options;
-  if (cdpEndpoint || wsEndpoint) {
-    throw new Error(
-      'launchAndConnectRealBrowser creates its own endpoint; use connectBrowser to attach to an existing endpoint'
-    );
-  }
+  const argOptions = {
+    headless,
+    restrictions,
+    args,
+    extraArgs,
+    automationParity,
+  };
+  validateLaunchRequest({
+    argOptions,
+    userDataDir: requestedUserDataDir,
+    remoteDebuggingPort,
+    endpoint: cdpEndpoint || wsEndpoint,
+    attach,
+    migrateFrom,
+  });
 
-  assertDedicatedUserDataDir(userDataDir);
-  await mkdir(userDataDir, { recursive: true });
   const resolveExecutable =
     dependencies.resolveExecutable ?? resolveSystemBrowserExecutable;
-  const resolvedExecutablePath = await resolveExecutable({
+  const executablePath = await resolveExecutable({
     channel,
     executablePath: requestedExecutablePath,
   });
-  const browserArgs = buildRealBrowserArgs({
-    userDataDir,
-    remoteDebuggingPort,
-    headless,
-    args,
-    extraArgs,
-    ignoreDefaultArgs,
+
+  const temporaryProfile = !requestedUserDataDir;
+  const { userDataDir, snapshotLaunch } = await prepareProfile({
+    attach,
+    channel,
+    requestedUserDataDir,
+    argOptions,
+    snapshot: dependencies.snapshotUserDataDir,
   });
-  const spawnBrowser = dependencies.spawnBrowser ?? spawn;
-  const browserProcess = spawnBrowser(resolvedExecutablePath, browserArgs, {
-    stdio: verbose ? 'inherit' : 'ignore',
+  const childEnv = browserEnvironment(restrictions, env);
+
+  const { migration, migratedCookies } = await runPreLaunchMigration({
+    migrateFrom,
+    userDataDir,
+    channel,
+    temporaryProfile,
+    migrate: dependencies.migrateProfile ?? migrateProfile,
   });
 
+  let launched;
   try {
-    const waitForEndpoint = dependencies.waitForEndpoint ?? waitForCdpEndpoint;
-    const resolvedCdpEndpoint = await waitForEndpoint({
-      remoteDebuggingPort,
+    launched = await spawnOnFreePort({
+      requestedPort: remoteDebuggingPort,
+      portAttempts,
+      executablePath,
+      argOptions,
+      env: childEnv,
+      verbose,
       userDataDir,
-      browserProcess,
-      timeout: startupTimeout,
+      startupTimeout,
+      dependencies,
     });
+  } catch (error) {
+    if (temporaryProfile) {
+      await removeUserDataDir(userDataDir);
+    }
+    throw error;
+  }
+  const { browserProcess, cdpEndpoint: resolvedCdpEndpoint } = launched;
+  if (temporaryProfile) {
+    // The profile goes away with the browser, also when the user closes the
+    // window instead of the caller calling close().
+    browserProcess.once?.('exit', () => {
+      removeUserDataDir(userDataDir).catch(() => {});
+    });
+  }
+
+  try {
     const connect = dependencies.connect ?? connectBrowser;
+    const seedCookies =
+      migratedCookies.length > 0
+        ? [...(connectionOptions.seedCookies ?? []), ...migratedCookies]
+        : connectionOptions.seedCookies;
     const connection = await connect({
       engine,
       cdpEndpoint: resolvedCdpEndpoint,
       ...connectionOptions,
+      seedCookies,
       verbose,
     });
+    const close = createCloser({
+      engine,
+      browser: connection.browser,
+      browserProcess,
+      userDataDir,
+      temporaryProfile,
+      closeTimeout,
+    });
     return {
       ...connection,
+      close,
       browserProcess,
       cdpEndpoint: resolvedCdpEndpoint,
-      executablePath: resolvedExecutablePath,
+      remoteDebuggingPort: launched.port,
+      executablePath,
       userDataDir,
+      temporaryProfile,
+      args: launched.browserArgs,
+      ...(migration ? { migration } : {}),
+      ...(snapshotLaunch ? { attach: snapshotLaunch.attach } : {}),
     };
   } catch (error) {
     if (browserProcess.exitCode === null) {
       browserProcess.kill();
     }
+    await waitForExit(browserProcess, closeTimeout);
+    if (temporaryProfile) {
+      await removeUserDataDir(userDataDir);
+    }
     throw error;
   }
 }
 
-export { defaultUserDataDir, knownDefaultUserDataDirs };
+export {
+  assertDedicatedUserDataDir,
+  defaultUserDataDir,
+  knownDefaultUserDataDirs,
+  resolveSystemBrowserExecutable,
+};