browser-commander 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.13.0
+
+### Minor Changes
+
+- 46d0049: Add CDP attachment through `connectBrowser()` for Playwright and Puppeteer, plus `launchAndConnectRealBrowser()` for starting an installed Chrome-family browser with a dedicated automation profile.
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -106,6 +106,41 @@ const { browser, page } = await launchBrowser({
 });
 ```
 
+Attach to a Chrome-family browser that is already listening for CDP connections:
+
+```javascript
+import { connectBrowser, makeBrowserCommander } from 'browser-commander';
+
+const { browser, page } = await connectBrowser({
+  engine: 'playwright', // or 'puppeteer'
+  cdpEndpoint: 'http://127.0.0.1:9222',
+});
+const commander = makeBrowserCommander({ page });
+```
+
+`launchAndConnectRealBrowser()` can find and start a genuine installed Chrome,
+Edge, Brave, or Chromium with a loopback CDP endpoint and then attach to it. It
+always uses a dedicated profile; Chrome 136 and newer do not honor remote
+debugging switches for the default profile. See the
+[Chrome remote-debugging security change](https://developer.chrome.com/blog/remote-debugging-port).
+
+```javascript
+import { launchAndConnectRealBrowser } from 'browser-commander';
+
+const connection = await launchAndConnectRealBrowser({
+  engine: 'puppeteer',
+  channel: 'chrome',
+  userDataDir: '/tmp/my-automation-profile',
+  seedCookies: [
+    { name: 'session', value: 'saved', url: 'https://example.com' },
+  ],
+});
+await connection.browser.close();
+```
+
+Cookie seeding copies only cookies you explicitly provide; the helper does not
+read, decrypt, or expose cookies from a browser's default profile.
+
 Reuse a saved authenticated session by passing Playwright-compatible storage
 state as a JSON file path or object. Cookies and localStorage are restored for
 both engines:
@@ -303,6 +338,38 @@ The `storageState` option accepts a Playwright-compatible JSON path or object.
 Each engine restores its cookies and origin-specific localStorage before
 navigation, including when Playwright uses a persistent context.
 
+### connectBrowser(options)
+
+Connect to an existing Chrome-family browser over an HTTP or WebSocket CDP
+endpoint. Exactly one of `cdpEndpoint` and `wsEndpoint` is required. The raw
+`browser` and `page` work with both the underlying engine API and
+`makeBrowserCommander({ page })`.
+
+```javascript
+const { browser, page } = await connectBrowser({
+  engine: 'playwright',
+  wsEndpoint: 'ws://127.0.0.1:9222/devtools/browser/<id>',
+  timeout: 30_000,
+  seedCookies: [
+    { name: 'session', value: 'saved', url: 'https://example.com' },
+  ],
+});
+```
+
+Playwright accepts `timeout` and Puppeteer accepts `protocolTimeout`.
+`storageState` can also seed Playwright-compatible cookies and localStorage.
+
+### launchAndConnectRealBrowser(options)
+
+Start an installed browser and connect through `connectBrowser()`. Use
+`channel` (`chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`,
+`msedge-beta`, `msedge-dev`, `msedge-canary`, `brave`, or `chromium`) or an
+explicit `executablePath`. The helper defaults to
+a managed directory under `~/.browser-commander/real-browser/`, rejects known
+default browser-profile paths, protects its remote-debugging arguments, and
+returns the spawned `browserProcess`, resolved `cdpEndpoint`, executable path,
+and profile path alongside `{ browser, page }`.
+
 ### saveStorageState(page, filePath)
 
 Save the current cookies and localStorage in Playwright's portable storage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",

package/src/browser/connector.js

@@ -0,0 +1,163 @@
+import {
+  loadStorageState,
+  restorePlaywrightStorageState,
+  restorePuppeteerStorageState,
+} from './storage-state.js';
+
+function validateConnectionOptions({ engine, cdpEndpoint, wsEndpoint }) {
+  if (!['playwright', 'puppeteer'].includes(engine)) {
+    throw new Error(
+      `Invalid engine: ${engine}. Expected 'playwright' or 'puppeteer'`
+    );
+  }
+
+  if (Boolean(cdpEndpoint) === Boolean(wsEndpoint)) {
+    throw new Error(
+      'connectBrowser requires exactly one of cdpEndpoint or wsEndpoint'
+    );
+  }
+}
+
+function addDefinedOptions(options, values) {
+  for (const [key, value] of Object.entries(values)) {
+    if (value !== undefined) {
+      options[key] = value;
+    }
+  }
+  return options;
+}
+
+function buildPlaywrightConnectOptions({ slowMo, timeout, headers }) {
+  return addDefinedOptions({}, { slowMo, timeout, headers });
+}
+
+function buildPuppeteerConnectOptions({
+  cdpEndpoint,
+  wsEndpoint,
+  slowMo,
+  protocolTimeout,
+  headers,
+}) {
+  return addDefinedOptions(
+    {
+      ...(cdpEndpoint
+        ? { browserURL: cdpEndpoint }
+        : { browserWSEndpoint: wsEndpoint }),
+      defaultViewport: null,
+    },
+    { slowMo, protocolTimeout, headers }
+  );
+}
+
+async function prepareStorageState({ storageState, seedCookies }) {
+  if (seedCookies !== undefined && !Array.isArray(seedCookies)) {
+    throw new TypeError('seedCookies must be an array');
+  }
+
+  const resolvedStorageState = await loadStorageState(storageState);
+  if (!resolvedStorageState && seedCookies === undefined) {
+    return undefined;
+  }
+
+  return {
+    ...(resolvedStorageState ?? {}),
+    cookies: [...(resolvedStorageState?.cookies ?? []), ...(seedCookies ?? [])],
+  };
+}
+
+async function connectPlaywright({ options, loadPlaywright, storageState }) {
+  const { chromium } = await loadPlaywright();
+  const endpoint = options.cdpEndpoint ?? options.wsEndpoint;
+  const browser = await chromium.connectOverCDP(
+    endpoint,
+    buildPlaywrightConnectOptions(options)
+  );
+  const context = browser.contexts()[0];
+  if (!context) {
+    throw new Error('Connected Playwright browser has no default context');
+  }
+  const page = context.pages()[0] ?? (await context.newPage());
+
+  await restorePlaywrightStorageState({ context, storageState });
+  return { browser, page };
+}
+
+async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
+  const puppeteerModule = await loadPuppeteer();
+  const puppeteer = puppeteerModule.default ?? puppeteerModule;
+  const browser = await puppeteer.connect(
+    buildPuppeteerConnectOptions(options)
+  );
+  const pages = await browser.pages();
+  const page = pages[0] ?? (await browser.newPage());
+
+  await restorePuppeteerStorageState({ page, storageState });
+  return { browser, page };
+}
+
+/**
+ * Attach to an already-running Chromium-family browser over CDP.
+ *
+ * @param {Object} options - Connection options
+ * @param {'playwright'|'puppeteer'} [options.engine='playwright'] - Automation engine
+ * @param {string} [options.cdpEndpoint] - HTTP DevTools endpoint, such as http://127.0.0.1:9222
+ * @param {string} [options.wsEndpoint] - DevTools browser WebSocket endpoint
+ * @param {number} [options.slowMo] - Delay engine operations by this many milliseconds
+ * @param {number} [options.timeout] - Playwright connection timeout in milliseconds
+ * @param {number} [options.protocolTimeout] - Puppeteer CDP call timeout in milliseconds
+ * @param {Object<string,string>} [options.headers] - Additional connection headers
+ * @param {Object[]|string|Object} [options.storageState] - Playwright-compatible state path or object
+ * @param {Object[]} [options.seedCookies] - Cookies to seed after connecting
+ * @param {boolean} [options.verbose=false] - Enable connection logging
+ * @returns {Promise<{browser: Object, page: Object}>} Raw browser and page handles
+ */
+export async function connectBrowser(options = {}) {
+  return await connectBrowserWithDependencies(options);
+}
+
+/**
+ * Dependency-injected implementation used by the public connector and tests.
+ *
+ * @param {Object} options - See {@link connectBrowser}
+ * @param {Object} dependencies - Optional engine module loaders
+ * @returns {Promise<{browser: Object, page: Object}>} Raw browser and page handles
+ */
+export async function connectBrowserWithDependencies(
+  options = {},
+  dependencies = {}
+) {
+  const normalizedOptions = {
+    engine: 'playwright',
+    verbose: false,
+    ...options,
+  };
+  validateConnectionOptions(normalizedOptions);
+
+  const storageState = await prepareStorageState(normalizedOptions);
+  const { engine, verbose } = normalizedOptions;
+  if (verbose) {
+    console.log(`Connecting to browser with ${engine} engine...`);
+  }
+
+  const result =
+    engine === 'playwright'
+      ? await connectPlaywright({
+          options: normalizedOptions,
+          loadPlaywright:
+            dependencies.loadPlaywright ?? (() => import('playwright')),
+          storageState,
+        })
+      : await connectPuppeteer({
+          options: normalizedOptions,
+          loadPuppeteer:
+            dependencies.loadPuppeteer ?? (() => import('puppeteer')),
+          storageState,
+        });
+
+  if (verbose) {
+    console.log(`Connected to browser with ${engine} engine`);
+  }
+  return result;
+}
+
+export { buildPlaywrightConnectOptions, buildPuppeteerConnectOptions };

package/src/browser/real-browser.js

@@ -0,0 +1,439 @@
+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 path from 'node:path';
+
+import { connectBrowser } from './connector.js';
+
+const MANAGED_ARGUMENTS = [
+  '--remote-debugging-address',
+  '--remote-debugging-port',
+  '--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`
+  );
+}
+
+/** Build the protected command line used for a real browser CDP process. */
+export function buildRealBrowserArgs({
+  userDataDir,
+  remoteDebuggingPort = 0,
+  headless = false,
+  args = [],
+}) {
+  if (
+    !Number.isInteger(remoteDebuggingPort) ||
+    remoteDebuggingPort < 0 ||
+    remoteDebuggingPort > 65_535
+  ) {
+    throw new RangeError(
+      'remoteDebuggingPort must be an integer from 0 to 65535'
+    );
+  }
+  const conflictingArgument = args.find((argument) =>
+    MANAGED_ARGUMENTS.some(
+      (managed) => argument === managed || argument.startsWith(`${managed}=`)
+    )
+  );
+  if (conflictingArgument) {
+    throw new Error(
+      `${conflictingArgument} is managed by launchAndConnectRealBrowser`
+    );
+  }
+
+  return [
+    '--remote-debugging-address=127.0.0.1',
+    `--remote-debugging-port=${remoteDebuggingPort}`,
+    `--user-data-dir=${userDataDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    ...(headless ? ['--headless=new'] : []),
+    ...args,
+  ];
+}
+
+async function fetchCdpVersion(endpoint, fetchImplementation, timeout) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.min(timeout, 500));
+  try {
+    const response = await fetchImplementation(`${endpoint}/json/version`, {
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      return false;
+    }
+    const version = await response.json();
+    return Boolean(version.webSocketDebuggerUrl);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Wait until Chrome publishes a usable DevTools endpoint. */
+export async function waitForCdpEndpoint({
+  remoteDebuggingPort,
+  userDataDir,
+  browserProcess,
+  timeout = 30_000,
+  fetchImplementation = globalThis.fetch,
+}) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    if (browserProcess.exitCode !== null) {
+      throw new Error(
+        `Browser exited before its DevTools endpoint was ready (exit ${browserProcess.exitCode})`
+      );
+    }
+
+    let port = remoteDebuggingPort;
+    if (port === 0) {
+      try {
+        const activePort = await readFile(
+          path.join(userDataDir, 'DevToolsActivePort'),
+          'utf8'
+        );
+        port = Number.parseInt(activePort.split(/\r?\n/, 1)[0], 10);
+      } catch {
+        port = 0;
+      }
+    }
+
+    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;
+        }
+      } catch {
+        // Chrome may have allocated the port before /json/version is ready.
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(
+    `Timed out after ${timeout}ms waiting for the DevTools endpoint`
+  );
+}
+
+/**
+ * Spawn a genuine installed Chrome-family browser with an isolated profile,
+ * wait for its loopback CDP endpoint, and attach through {@link connectBrowser}.
+ *
+ * @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 {boolean} [options.headless=false] - Run the installed browser headlessly
+ * @param {string[]} [options.args] - Additional browser arguments
+ * @param {number} [options.startupTimeout=30000] - CDP readiness timeout in milliseconds
+ * @param {Object[]} [options.seedCookies] - Cookies to seed after connecting
+ * @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
+ */
+export async function launchAndConnectRealBrowser(options = {}) {
+  return await launchAndConnectRealBrowserWithDependencies(options);
+}
+
+/** Dependency-injected implementation used by the public helper and tests. */
+export async function launchAndConnectRealBrowserWithDependencies(
+  options = {},
+  dependencies = {}
+) {
+  const {
+    engine = 'playwright',
+    channel = 'chrome',
+    executablePath: requestedExecutablePath,
+    userDataDir = defaultUserDataDir(channel),
+    remoteDebuggingPort = 0,
+    headless = false,
+    args = [],
+    startupTimeout = 30_000,
+    verbose = false,
+    cdpEndpoint,
+    wsEndpoint,
+    ...connectionOptions
+  } = options;
+  if (cdpEndpoint || wsEndpoint) {
+    throw new Error(
+      'launchAndConnectRealBrowser creates its own endpoint; use connectBrowser to attach to an existing endpoint'
+    );
+  }
+
+  assertDedicatedUserDataDir(userDataDir);
+  await mkdir(userDataDir, { recursive: true });
+  const resolveExecutable =
+    dependencies.resolveExecutable ?? resolveSystemBrowserExecutable;
+  const resolvedExecutablePath = await resolveExecutable({
+    channel,
+    executablePath: requestedExecutablePath,
+  });
+  const browserArgs = buildRealBrowserArgs({
+    userDataDir,
+    remoteDebuggingPort,
+    headless,
+    args,
+  });
+  const spawnBrowser = dependencies.spawnBrowser ?? spawn;
+  const browserProcess = spawnBrowser(resolvedExecutablePath, browserArgs, {
+    stdio: verbose ? 'inherit' : 'ignore',
+  });
+
+  try {
+    const waitForEndpoint = dependencies.waitForEndpoint ?? waitForCdpEndpoint;
+    const resolvedCdpEndpoint = await waitForEndpoint({
+      remoteDebuggingPort,
+      userDataDir,
+      browserProcess,
+      timeout: startupTimeout,
+    });
+    const connect = dependencies.connect ?? connectBrowser;
+    const connection = await connect({
+      engine,
+      cdpEndpoint: resolvedCdpEndpoint,
+      ...connectionOptions,
+      verbose,
+    });
+    return {
+      ...connection,
+      browserProcess,
+      cdpEndpoint: resolvedCdpEndpoint,
+      executablePath: resolvedExecutablePath,
+      userDataDir,
+    };
+  } catch (error) {
+    if (browserProcess.exitCode === null) {
+      browserProcess.kill();
+    }
+    throw error;
+  }
+}
+
+export { defaultUserDataDir, knownDefaultUserDataDirs };

package/src/exports.js

@@ -42,6 +42,8 @@ export {
 } from './core/page-trigger-manager.js';
 
 // Re-export browser management
+export { connectBrowser } from './browser/connector.js';
+export { launchAndConnectRealBrowser } from './browser/real-browser.js';
 export { launchBrowser } from './browser/launcher.js';
 export { saveStorageState } from './browser/storage-state.js';
 export { emulateMedia } from './browser/media.js';

package/tests/unit/browser/connector.test.js

@@ -0,0 +1,129 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import {
+  connectBrowser,
+  connectBrowserWithDependencies,
+} from '../../../src/browser/connector.js';
+import { connectBrowser as publicConnectBrowser } from '../../../src/index.js';
+
+describe('connectBrowser', () => {
+  it('is exported from the package API', () => {
+    assert.equal(publicConnectBrowser, connectBrowser);
+  });
+
+  it('attaches Playwright over an HTTP CDP endpoint and reuses its first page', async () => {
+    const calls = [];
+    const page = { id: 'playwright-page' };
+    const context = {
+      pages: () => [page],
+      addCookies: async (cookies) => calls.push(['cookies', cookies]),
+    };
+    const browser = { contexts: () => [context] };
+    const chromium = {
+      connectOverCDP: async (endpoint, options) => {
+        calls.push(['connect', endpoint, options]);
+        return browser;
+      },
+    };
+    const seedCookies = [
+      { name: 'SID', value: 'saved', domain: '.example.com', path: '/' },
+    ];
+
+    const result = await connectBrowserWithDependencies(
+      {
+        engine: 'playwright',
+        cdpEndpoint: 'http://127.0.0.1:9222',
+        slowMo: 25,
+        timeout: 5_000,
+        seedCookies,
+      },
+      { loadPlaywright: async () => ({ chromium }) }
+    );
+
+    assert.equal(result.browser, browser);
+    assert.equal(result.page, page);
+    assert.deepEqual(calls, [
+      ['connect', 'http://127.0.0.1:9222', { slowMo: 25, timeout: 5_000 }],
+      ['cookies', seedCookies],
+    ]);
+  });
+
+  it('maps a WebSocket endpoint to Puppeteer and creates a page when needed', async () => {
+    const calls = [];
+    const page = {
+      id: 'new-puppeteer-page',
+      setCookie: async (...cookies) => calls.push(['cookies', cookies]),
+    };
+    const browser = {
+      pages: async () => [],
+      newPage: async () => {
+        calls.push(['newPage']);
+        return page;
+      },
+    };
+    const puppeteer = {
+      connect: async (options) => {
+        calls.push(['connect', options]);
+        return browser;
+      },
+    };
+    const seedCookies = [
+      { name: 'session', value: 'saved', domain: '.example.com', path: '/' },
+    ];
+
+    const result = await connectBrowserWithDependencies(
+      {
+        engine: 'puppeteer',
+        wsEndpoint: 'ws://127.0.0.1:9222/devtools/browser/id',
+        slowMo: 10,
+        protocolTimeout: 30_000,
+        seedCookies,
+      },
+      { loadPuppeteer: async () => ({ default: puppeteer }) }
+    );
+
+    assert.equal(result.browser, browser);
+    assert.equal(result.page, page);
+    assert.deepEqual(calls, [
+      [
+        'connect',
+        {
+          browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/id',
+          defaultViewport: null,
+          slowMo: 10,
+          protocolTimeout: 30_000,
+        },
+      ],
+      ['newPage'],
+      ['cookies', seedCookies],
+    ]);
+  });
+
+  it('requires exactly one endpoint and a supported engine', async () => {
+    await assert.rejects(
+      () => connectBrowserWithDependencies({ engine: 'playwright' }, {}),
+      /exactly one of cdpEndpoint or wsEndpoint/
+    );
+    await assert.rejects(
+      () =>
+        connectBrowserWithDependencies(
+          {
+            engine: 'playwright',
+            cdpEndpoint: 'http://127.0.0.1:9222',
+            wsEndpoint: 'ws://127.0.0.1:9222/devtools/browser/id',
+          },
+          {}
+        ),
+      /exactly one of cdpEndpoint or wsEndpoint/
+    );
+    await assert.rejects(
+      () =>
+        connectBrowserWithDependencies(
+          { engine: 'invalid', cdpEndpoint: 'http://127.0.0.1:9222' },
+          {}
+        ),
+      /Invalid engine: invalid/
+    );
+  });
+});

package/tests/unit/browser/real-browser.test.js

@@ -0,0 +1,165 @@
+import assert from 'node:assert';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, it } from 'node:test';
+
+import {
+  assertDedicatedUserDataDir,
+  buildRealBrowserArgs,
+  launchAndConnectRealBrowser,
+  launchAndConnectRealBrowserWithDependencies,
+} from '../../../src/browser/real-browser.js';
+import { launchAndConnectRealBrowser as publicHelper } from '../../../src/index.js';
+
+describe('launchAndConnectRealBrowser', () => {
+  let temporaryDirectory;
+
+  afterEach(async () => {
+    if (temporaryDirectory) {
+      await rm(temporaryDirectory, { recursive: true, force: true });
+      temporaryDirectory = undefined;
+    }
+  });
+
+  it('is exported from the package API', () => {
+    assert.equal(publicHelper, launchAndConnectRealBrowser);
+  });
+
+  it('builds a loopback-only CDP command with a dedicated profile', () => {
+    const args = buildRealBrowserArgs({
+      userDataDir: '/tmp/browser-commander-dedicated',
+      remoteDebuggingPort: 9333,
+      headless: true,
+      args: ['--lang=en-US'],
+    });
+
+    assert.deepEqual(args, [
+      '--remote-debugging-address=127.0.0.1',
+      '--remote-debugging-port=9333',
+      '--user-data-dir=/tmp/browser-commander-dedicated',
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--headless=new',
+      '--lang=en-US',
+    ]);
+  });
+
+  it('rejects custom arguments that could bypass protected CDP settings', () => {
+    for (const argument of [
+      '--remote-debugging-address=0.0.0.0',
+      '--remote-debugging-port=9222',
+      '--user-data-dir=/tmp/other',
+    ]) {
+      assert.throws(
+        () =>
+          buildRealBrowserArgs({
+            userDataDir: '/tmp/browser-commander-dedicated',
+            remoteDebuggingPort: 0,
+            args: [argument],
+          }),
+        /managed by launchAndConnectRealBrowser/
+      );
+    }
+  });
+
+  it('rejects Chrome default user-data directories', () => {
+    for (const profile of ['google-chrome', 'google-chrome-beta']) {
+      assert.throws(
+        () =>
+          assertDedicatedUserDataDir(
+            path.join(os.homedir(), '.config', profile),
+            {
+              platform: 'linux',
+              homeDir: os.homedir(),
+              environment: {},
+            }
+          ),
+        /dedicated userDataDir/
+      );
+    }
+  });
+
+  it('spawns, waits, connects, and returns process metadata', async () => {
+    temporaryDirectory = await mkdtemp(
+      path.join(os.tmpdir(), 'browser-commander-real-browser-test-')
+    );
+    const calls = [];
+    const browserProcess = { exitCode: null, kill: () => calls.push(['kill']) };
+    const browser = { id: 'browser' };
+    const page = { id: 'page' };
+
+    const result = await launchAndConnectRealBrowserWithDependencies(
+      {
+        engine: 'puppeteer',
+        channel: 'chrome',
+        userDataDir: temporaryDirectory,
+        remoteDebuggingPort: 0,
+        seedCookies: [{ name: 'SID', value: 'saved' }],
+      },
+      {
+        resolveExecutable: async () => '/opt/google/chrome',
+        spawnBrowser: (executablePath, args) => {
+          calls.push(['spawn', executablePath, args]);
+          return browserProcess;
+        },
+        waitForEndpoint: async (options) => {
+          calls.push(['wait', options.remoteDebuggingPort]);
+          return 'http://127.0.0.1:9444';
+        },
+        connect: async (options) => {
+          calls.push(['connect', options]);
+          return { browser, page };
+        },
+      }
+    );
+
+    assert.equal(result.browser, browser);
+    assert.equal(result.page, page);
+    assert.equal(result.browserProcess, browserProcess);
+    assert.equal(result.cdpEndpoint, 'http://127.0.0.1:9444');
+    assert.equal(result.executablePath, '/opt/google/chrome');
+    assert.equal(result.userDataDir, temporaryDirectory);
+    assert.deepEqual(calls[1], ['wait', 0]);
+    assert.deepEqual(calls[2], [
+      'connect',
+      {
+        engine: 'puppeteer',
+        cdpEndpoint: 'http://127.0.0.1:9444',
+        seedCookies: [{ name: 'SID', value: 'saved' }],
+        verbose: false,
+      },
+    ]);
+  });
+
+  it('terminates the spawned browser when connection fails', async () => {
+    temporaryDirectory = await mkdtemp(
+      path.join(os.tmpdir(), 'browser-commander-real-browser-test-')
+    );
+    let killed = false;
+    const browserProcess = {
+      exitCode: null,
+      kill: () => {
+        killed = true;
+      },
+    };
+
+    await assert.rejects(
+      () =>
+        launchAndConnectRealBrowserWithDependencies(
+          { userDataDir: temporaryDirectory },
+          {
+            resolveExecutable: async () => '/opt/google/chrome',
+            spawnBrowser: () => browserProcess,
+            waitForEndpoint: async () => 'http://127.0.0.1:9222',
+            connect: async () => {
+              throw new Error('connection failed');
+            },
+          }
+        ),
+      /connection failed/
+    );
+
+    assert.equal(killed, true);
+  });
+});