browser-commander 0.22.0 → 0.24.0

package/examples/react-test-app/package.json

@@ -9,11 +9,11 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
   },
   "devDependencies": {
-    "@vitejs/plugin-react": "^4.2.0",
-    "vite": "^5.0.0"
+    "@vitejs/plugin-react": "^6.1.2",
+    "vite": "^8.3.2"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "browser-commander",
-  "version": "0.22.0",
-  "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
+  "version": "0.24.0",
+  "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {
     "browser-commander": "bin/browser-commander.js"
@@ -61,12 +61,12 @@
   },
   "homepage": "https://github.com/link-foundation/browser-commander#readme",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "peerDependencies": {
-    "playwright": ">=1.40.0",
-    "puppeteer": ">=21.0.0",
-    "selenium-webdriver": ">=4.20.0"
+    "playwright": ">=1.63.0",
+    "puppeteer": ">=25.12.0",
+    "selenium-webdriver": ">=4.50.0"
   },
   "peerDependenciesMeta": {
     "playwright": {
@@ -81,24 +81,24 @@
   },
   "dependencies": {
     "better-sqlite3": "^13.0.3",
-    "command-stream": "^1.2.0",
-    "links-notation": "^0.20.0",
+    "command-stream": "^1.4.0",
+    "links-notation": "^0.22.0",
     "log-lazy": "^1.0.4",
     "test-anywhere": "^0.9.1"
   },
   "devDependencies": {
-    "@changesets/cli": "^3.0.2",
+    "@changesets/cli": "^3.0.3",
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.10.0",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
-    "jscpd": "^5.1.2",
-    "jsdoc": "^4.0.4",
-    "playwright": "^1.62.1",
-    "prettier": "^3.9.6",
-    "puppeteer": "^25.10.0",
-    "selenium-webdriver": "^4.49.0",
-    "typescript": "^5.9.3",
+    "jscpd": "^5.4.0",
+    "jsdoc": "^4.0.5",
+    "playwright": "^1.63.0",
+    "prettier": "^3.9.9",
+    "puppeteer": "^25.12.0",
+    "selenium-webdriver": "^4.50.0",
+    "typescript": "^7.0.2",
     "yaml": "^2.9.1"
   },
   "allowScripts": {

package/src/browser/browser-cookies.js

@@ -33,6 +33,11 @@ import {
   resolveSourceBrowser,
 } from './browser-profiles.js';
 import { resolveDefaultBrowser } from './default-browser.js';
+import {
+  countSafariCookies,
+  parseSafariCookies,
+  readSafariCookieFile,
+} from './safari-cookies.js';
 
 const CHROME_EPOCH_OFFSET_SECONDS = 11_644_473_600n;
 const MICROSECONDS_PER_SECOND = 1_000_000n;
@@ -319,6 +324,14 @@ export async function readBrowserCookiesWithDependencies(
     return cachedCookies;
   }
 
+  if (browserFamily(browser) === 'safari') {
+    const cookies = parseSafariCookies(
+      await readSafariCookieFile(cookiePath, { environment }),
+      options.domainFilter
+    );
+    await writeCookieResultCache({ cache, identity, cookies, now });
+    return cookies;
+  }
   const database = await openCookieDatabase(cookiePath);
   let cookies;
   try {
@@ -426,8 +439,15 @@ export async function listCookieSources({
     let error;
     let database;
     try {
-      database = await openCookieDatabase(cookiePath);
-      counts = countCookiesByDomain(database, family, domains);
+      if (family === 'safari') {
+        counts = countSafariCookies(
+          await readSafariCookieFile(cookiePath, { environment }),
+          domains
+        );
+      } else {
+        database = await openCookieDatabase(cookiePath);
+        counts = countCookiesByDomain(database, family, domains);
+      }
     } catch (openError) {
       error = openError.message;
     } finally {
@@ -514,12 +534,24 @@ export async function resolveImportSource({
     environment,
     runCommand,
   });
-  const holders = (
-    await listCookieSources({ domains, platform, homeDir, environment })
-  ).filter((source) => !source.error);
+  const listedSources = await listCookieSources({
+    domains,
+    platform,
+    homeDir,
+    environment,
+  });
+  const holders = listedSources.filter((source) => !source.error);
   const fromDefault = holders.filter(
     (source) => source.browser === systemDefault
   );
+  const unreadableDefault = listedSources.find(
+    (source) => source.browser === systemDefault && source.error
+  );
+  if (fromDefault.length === 0 && unreadableDefault) {
+    throw new Error(
+      `Could not inspect the default browser (${systemDefault}): ${unreadableDefault.error}`
+    );
+  }
   const candidates = fromDefault.length > 0 ? fromDefault : holders;
   if (candidates.length === 0) {
     if (!systemDefault) {

package/src/browser/browser-profiles.js

@@ -10,6 +10,7 @@ import {
   resolveBrowserRoots,
 } from './browser-sources.js';
 import { resolveDefaultBrowser } from './default-browser.js';
+import { findSafariCookieFile } from './safari-cookies.js';
 
 /**
  * Keywords that select the operating-system default browser instead of a named
@@ -112,6 +113,9 @@ function chromiumCookiePaths(profilePath, pathApi = path) {
 
 export async function findCookieDatabase(browser, profilePath, platform) {
   const pathApi = platformPath(platform ?? process.platform);
+  if (browserFamily(browser) === 'safari') {
+    return findSafariCookieFile(profilePath);
+  }
   if (browserFamily(browser) === 'firefox') {
     const candidate = pathApi.join(profilePath, 'cookies.sqlite');
     return (await pathExists(candidate)) ? candidate : null;
@@ -274,6 +278,20 @@ async function listProfilesForBrowser(browser, platform, homeDir, environment) {
   const family = browserFamily(browser);
   const profiles = [];
   for (const root of roots) {
+    if (family === 'safari') {
+      if (await findSafariCookieFile(root)) {
+        return [
+          {
+            browser,
+            name: 'Default',
+            displayName: 'Default',
+            path: root,
+            isDefault: true,
+          },
+        ];
+      }
+      continue;
+    }
     profiles.push(
       ...(family === 'firefox'
         ? await listFirefoxProfiles(browser, root, platform)

package/src/browser/browser-sources.json

@@ -394,6 +394,36 @@
         "darwin": ["org.floorp.Floorp"],
         "linux": ["floorp.desktop"]
       }
+    },
+    {
+      "id": "safari",
+      "family": "safari",
+      "aliases": ["apple-safari"],
+      "singleProfile": true,
+      "roots": {
+        "darwin": [
+          "{home}/Library/Containers/com.apple.Safari/Data/Library",
+          "{home}/Library"
+        ]
+      },
+      "default": {
+        "darwin": ["com.apple.safari"]
+      }
+    },
+    {
+      "id": "safari-technology-preview",
+      "family": "safari",
+      "aliases": ["safari-tp", "safari-preview"],
+      "singleProfile": true,
+      "roots": {
+        "darwin": [
+          "{home}/Library/Containers/com.apple.SafariTechnologyPreview/Data/Library",
+          "{home}/Library/Safari Technology Preview"
+        ]
+      },
+      "default": {
+        "darwin": ["com.apple.safaritechnologypreview"]
+      }
     }
   ]
 }

package/src/browser/connector.js

@@ -1,8 +1,10 @@
 import { attachDownloads } from '../downloads/attach.js';
+import { connectWebDriver, launchWebDriver } from './webdriver.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
   restorePuppeteerStorageState,
+  restoreWebDriverStorageState,
 } from './storage-state.js';
 
 /**
@@ -11,9 +13,9 @@ import {
  * @param {string} engine
  */
 export function assertSupportedEngine(engine) {
-  if (!['playwright', 'puppeteer'].includes(engine)) {
+  if (!['playwright', 'puppeteer', 'selenium'].includes(engine)) {
     throw new Error(
-      `Invalid engine: ${engine}. Expected 'playwright' or 'puppeteer'`
+      `Invalid engine: ${engine}. Expected 'playwright', 'puppeteer' or 'selenium'`
     );
   }
 }
@@ -28,6 +30,28 @@ function validateConnectionOptions({ engine, cdpEndpoint, wsEndpoint }) {
   }
 }
 
+async function connectSelenium(options, dependencies) {
+  if (Boolean(options.serverUrl) === Boolean(options.cdpEndpoint)) {
+    throw new Error(
+      'selenium requires exactly one of serverUrl or cdpEndpoint'
+    );
+  }
+  if (options.wsEndpoint) {
+    throw new Error('selenium requires an HTTP cdpEndpoint or serverUrl');
+  }
+  const connected = options.serverUrl
+    ? await (dependencies.connectWebDriver ?? connectWebDriver)(options)
+    : await (dependencies.launchWebDriver ?? launchWebDriver)({
+        ...options,
+        debuggerAddress: new URL(options.cdpEndpoint).host,
+      });
+  return {
+    ...connected,
+    browser: connected.driver,
+    disconnect: connected.close,
+  };
+}
+
 function addDefinedOptions(options, values) {
   for (const [key, value] of Object.entries(values)) {
     if (value !== undefined) {
@@ -135,10 +159,12 @@ async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
 }
 
 /**
- * Attach to an already-running Chromium-family browser over CDP.
+ * Attach over CDP or create a native session on a WebDriver server.
  *
  * @param {Object} options - Connection options
- * @param {'playwright'|'puppeteer'} [options.engine='playwright'] - Automation engine
+ * @param {'playwright'|'puppeteer'|'selenium'} [options.engine='playwright'] - Automation engine
+ * @param {string} [options.serverUrl] - Selenium Grid or WebDriver server URL
+ * @param {Object} [options.capabilities] - Native WebDriver capabilities
  * @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
@@ -171,6 +197,22 @@ export async function connectBrowserWithDependencies(
     verbose: false,
     ...options,
   };
+  if (normalizedOptions.engine === 'selenium') {
+    assertSupportedEngine(normalizedOptions.engine);
+    const storageState = await prepareStorageState(normalizedOptions);
+    const result = await connectSelenium(normalizedOptions, dependencies);
+    try {
+      await restoreWebDriverStorageState({ page: result.page, storageState });
+      const downloads = await attachDownloads({
+        ...normalizedOptions,
+        ...result,
+      });
+      return { ...result, downloads };
+    } catch (error) {
+      await result.close();
+      throw error;
+    }
+  }
   validateConnectionOptions(normalizedOptions);
 
   const storageState = await prepareStorageState(normalizedOptions);

package/src/browser/launcher.js

@@ -16,10 +16,12 @@ import { resolveRestrictions } from './restrictions.js';
 import { resolveSystemBrowserExecutable } from './system-browser.js';
 import { applyFingerprint } from '../fingerprint/apply.js';
 import { attachDownloads } from '../downloads/attach.js';
+import { launchWebDriver } from './webdriver.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
   restorePuppeteerStorageState,
+  restoreWebDriverStorageState,
 } from './storage-state.js';
 
 /** How `launchBrowser` starts the browser (issue #103). */
@@ -131,6 +133,13 @@ async function launchReal(options, dependencies) {
 }
 
 async function launchWithEngine(options, dependencies) {
+  if (options.engine === 'selenium') {
+    const launched = await (dependencies.launchWebDriver ?? launchWebDriver)({
+      ...options,
+      args: [...options.args, ...options.extraArgs],
+    });
+    return { ...launched, browser: launched.driver };
+  }
   const {
     engine,
     userDataDir: requestedUserDataDir,
@@ -261,7 +270,7 @@ async function unfocusAddressBar(page, verbose, settleMs = 500) {
  * limitations.json (`engine-launch-switches`).
  *
  * @param {Object} options - Configuration options
- * @param {string} [options.engine='playwright'] - Browser automation engine: 'playwright' or 'puppeteer'
+ * @param {string} [options.engine='playwright'] - Browser automation engine: 'playwright', 'puppeteer' or 'selenium'
  * @param {'real'|'engine'} [options.launch='real'] - Who starts the browser: Browser Commander (a hand-started command line) or the automation engine
  * @param {string} [options.userDataDir] - Persistent profile directory. When omitted a fresh temporary profile is created and deleted on close.
  * @param {boolean} [options.headless=false] - Run in headless mode
@@ -309,6 +318,16 @@ export async function launchBrowserWithDependencies(
     ...rest
   } = options;
   validateLaunchMode({ engine, launch, attach: rest.attach });
+  if (engine === 'selenium') {
+    if (colorScheme !== undefined || fingerprint !== undefined || downloads) {
+      throw new Error(
+        'selenium does not support CDP emulation, fingerprint overrides or managed downloads (webdriver-no-cdp-emulation)'
+      );
+    }
+    if (launch === 'real' && rest.browser === 'firefox') {
+      throw new Error("selenium Firefox requires launch: 'engine'");
+    }
+  }
   // Validate arguments before anything is started or written to disk.
   resolveChromeArgs({ args, extraArgs, ignoreDefaultArgs, restrictions });
   const resolvedStorageState = await loadStorageState(storageState);
@@ -341,6 +360,12 @@ export async function launchBrowserWithDependencies(
   }
 
   try {
+    if (engine === 'selenium' && launch === 'engine') {
+      await restoreWebDriverStorageState({
+        page,
+        storageState: resolvedStorageState,
+      });
+    }
     // A Playwright-launched context applies colorScheme itself; an attached
     // browser and Puppeteer need page-level emulation.
     const emulateColorScheme =

package/src/browser/migration/index.js

@@ -114,6 +114,34 @@ function mergeReport(report, className, fragment) {
   report.warnings.push(...(fragment.warnings ?? []));
 }
 
+function reportSafariClasses(report, selected) {
+  for (const type of ALL_DATA_CLASSES.filter(
+    (name) => name !== 'cookies' && selected.has(name)
+  )) {
+    report.skipped.push({
+      type,
+      item: report.source.browser,
+      reason:
+        type === 'passwords'
+          ? 'safari-password-export-required'
+          : 'safari-class-not-supported',
+      detail:
+        type === 'passwords'
+          ? 'Safari passwords live in the Keychain. Export Passwords from Safari or the Passwords app to CSV; CSV import is tracked separately and is not supported yet.'
+          : 'Safari currently supports cookie import only; this data class has not been translated.',
+    });
+  }
+  if (report.cookies.length > 0) {
+    report.warnings.push({
+      type: 'cookies',
+      item: report.source.browser,
+      reason: 'safari-samesite-unavailable',
+      detail:
+        'Cookies.binarycookies does not store SameSite; imported cookies use Lax.',
+    });
+  }
+}
+
 async function resolvePasswordKeys({
   keys,
   browser,
@@ -234,6 +262,11 @@ export async function migrateProfile({
     }
   }
 
+  if (browserFamily(browser) === 'safari') {
+    reportSafariClasses(report, selected);
+    return report;
+  }
+
   if (selected.has('bookmarks')) {
     mergeReport(
       report,

package/src/browser/real-browser.js

@@ -259,6 +259,10 @@ async function waitForExit(browserProcess, timeout) {
 }
 
 async function requestBrowserClose({ engine, browser, originalClose }) {
+  if (engine === 'selenium') {
+    await originalClose();
+    return;
+  }
   if (engine === 'puppeteer') {
     // A connected Puppeteer Browser sends Browser.close and waits for it.
     await originalClose.call(browser);
@@ -278,8 +282,9 @@ function createCloser({
   userDataDir,
   temporaryProfile,
   closeTimeout,
+  closeConnection,
 }) {
-  const originalClose = browser?.close;
+  const originalClose = closeConnection ?? browser?.close;
   let closing;
   const close = () => {
     closing ??= (async () => {
@@ -298,7 +303,7 @@ function createCloser({
     })();
     return closing;
   };
-  if (browser && originalClose) {
+  if (browser && originalClose && engine !== 'selenium') {
     // `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;
@@ -670,6 +675,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
       userDataDir,
       temporaryProfile,
       closeTimeout,
+      closeConnection: engine === 'selenium' ? connection.close : undefined,
     });
     return {
       ...connection,

package/src/browser/safari-cookies.js

@@ -0,0 +1,173 @@
+/** Read Safari's unencrypted, mixed-endian Cookies.binarycookies store.
+ * Format: https://github.com/libyal/dtformats/blob/main/documentation/Safari%20Cookies.asciidoc
+ * No SameSite attribute is stored in this format; use Lax and report that loss.
+ */
+import { readFile as readFileBytes, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { TextDecoder } from 'node:util';
+
+const APPLE_EPOCH = 978_307_200;
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+function invalid(detail) {
+  throw new Error(`Invalid Safari binarycookies: ${detail}`);
+}
+
+function bounded(data, offset, size) {
+  if (offset < 0 || size < 0 || offset + size > data.length) {
+    invalid('truncated or out-of-range data');
+  }
+  return data.subarray(offset, offset + size);
+}
+
+function uint(data, offset, bigEndian = false) {
+  const bytes = bounded(data, offset, 4);
+  return bigEndian ? bytes.readUInt32BE() : bytes.readUInt32LE();
+}
+
+function string(record, field) {
+  const offset = uint(record, field);
+  if (offset < 56 || offset >= record.length) {
+    invalid('string offset');
+  }
+  const end = record.indexOf(0, offset);
+  if (end < 0) {
+    invalid('unterminated string');
+  }
+  try {
+    return utf8.decode(record.subarray(offset, end));
+  } catch {
+    return invalid('invalid UTF-8');
+  }
+}
+
+/** Validate all structural offsets before walking records; counts are bounded
+ * by the file size, so forged counts cannot cause unbounded allocations.
+ */
+function* records(data) {
+  if (bounded(data, 0, 4).toString('ascii') !== 'cook') {
+    invalid('file signature');
+  }
+  const pages = uint(data, 4, true);
+  bounded(data, 8, pages * 4);
+  let pageStart = 8 + pages * 4;
+  for (let index = 0; index < pages; index += 1) {
+    const page = bounded(data, pageStart, uint(data, 8 + index * 4, true));
+    pageStart += page.length;
+    if (uint(page, 0) !== 0x00010000) {
+      invalid('page signature');
+    }
+    const count = uint(page, 4);
+    const headerSize = 8 + count * 4;
+    bounded(page, 0, headerSize);
+    let previousEnd = headerSize;
+    for (let cookie = 0; cookie < count; cookie += 1) {
+      const start = uint(page, 8 + cookie * 4);
+      if (start < previousEnd) {
+        invalid('overlapping record');
+      }
+      const size = uint(page, start);
+      if (size < 56) {
+        invalid('short record');
+      }
+      const record = bounded(page, start, size);
+      previousEnd = start + size;
+      yield record;
+    }
+  }
+  // Safari may append a checksum and a plist trailer. They are not cookies.
+}
+
+/** Decode cookies in automation shape, using the existing substring filter. */
+export function parseSafariCookies(data, domainFilter) {
+  const cookies = [];
+  for (const record of records(data)) {
+    const domain = string(record, 16);
+    if (
+      domainFilter &&
+      !domain.toLowerCase().includes(domainFilter.toLowerCase())
+    ) {
+      continue;
+    }
+    const expiry = record.readDoubleLE(40) + APPLE_EPOCH;
+    if (
+      !Number.isFinite(expiry) ||
+      Math.abs(expiry) > Number.MAX_SAFE_INTEGER
+    ) {
+      invalid('expiry');
+    }
+    const flags = uint(record, 8);
+    cookies.push({
+      name: string(record, 20),
+      value: string(record, 28),
+      domain,
+      path: string(record, 24) || '/',
+      expires: Math.floor(expiry),
+      httpOnly: Boolean(flags & 4),
+      secure: Boolean(flags & 1),
+      sameSite: 'Lax',
+    });
+  }
+  return cookies;
+}
+
+/** Counts decode only domain strings. Names and values are never decoded. */
+export function countSafariCookies(data, domains) {
+  const byDomain = domains?.length
+    ? Object.fromEntries(domains.map((domain) => [domain, 0]))
+    : null;
+  let total = 0;
+  for (const record of records(data)) {
+    const host = string(record, 16).toLowerCase();
+    total += 1;
+    for (const domain of Object.keys(byDomain ?? {})) {
+      if (host.includes(domain.toLowerCase())) {
+        byDomain[domain] += 1;
+      }
+    }
+  }
+  return { total, byDomain };
+}
+
+/** A protected path is still a source: preserve it for an actionable read error. */
+export async function findSafariCookieFile(profileDir, statFile = stat) {
+  for (const candidate of [
+    path.join(profileDir, 'Cookies', 'Cookies.binarycookies'),
+    path.join(profileDir, 'Cookies.binarycookies'),
+  ]) {
+    try {
+      if ((await statFile(candidate)).isFile()) {
+        return candidate;
+      }
+    } catch (error) {
+      if (['EPERM', 'EACCES'].includes(error.code)) {
+        return candidate;
+      }
+      if (!['ENOENT', 'ENOTDIR'].includes(error.code)) {
+        throw error;
+      }
+    }
+  }
+  return null;
+}
+
+export async function readSafariCookieFile(
+  filePath,
+  { environment = process.env, readFile = readFileBytes } = {}
+) {
+  try {
+    return await readFile(filePath);
+  } catch (error) {
+    if (!['EPERM', 'EACCES'].includes(error.code)) {
+      throw error;
+    }
+    const app =
+      environment.__CFBundleIdentifier ||
+      environment.TERM_PROGRAM ||
+      process.execPath;
+    throw new Error(
+      `Safari cookie access denied (${error.code}) at ${filePath}. Grant Full Disk Access to ${app}, the app running Browser Commander, then retry: x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles`,
+      { cause: error }
+    );
+  }
+}

package/src/browser/storage-state.js

@@ -30,6 +30,33 @@ function restoreOriginLocalStorage(origins) {
   }
 }
 
+/** Restore classic WebDriver cookies; origin preload scripts require BiDi. */
+export async function restoreWebDriverStorageState({ page, storageState }) {
+  if (!storageState) {
+    return;
+  }
+  const origins = storageState.origins ?? [];
+  if (origins.length) {
+    await page.evaluateOnNewDocument(restoreOriginLocalStorage, origins);
+    await page.evaluate(restoreOriginLocalStorage, origins);
+  }
+  const originalUrl = page.url();
+  const cookies = storageState.cookies ?? [];
+  try {
+    for (const cookie of cookies) {
+      const origin = cookie.url
+        ? new URL(cookie.url).origin
+        : `${cookie.secure ? 'https' : 'http'}://${cookie.domain.replace(/^\./u, '')}`;
+      await page.goto(origin);
+      await page.setCookie(cookie);
+    }
+  } finally {
+    if (cookies.length) {
+      await page.goto(originalUrl);
+    }
+  }
+}
+
 /**
  * Apply Playwright-compatible storage state to a Puppeteer page.
  * @param {Object} options - Restore options