browser-commander 0.28.0 → 0.29.0

package/.jscpd-baseline.json

@@ -1,10 +1,8 @@
 {
   "version": 1,
   "fingerprints": {
-    "00504cdec3a262ed": 1,
     "00d381dd611ae8ac": 1,
     "029a62ef1f48e856": 1,
-    "02fc9852e9ba4c49": 1,
     "038170e72e0af1f5": 1,
     "0413f601c8911a92": 1,
     "04b28d01d0bb47dc": 1,
@@ -14,22 +12,18 @@
     "08e28c7706cdddd6": 1,
     "090a69d9528e4cdb": 1,
     "09694dc8fb9d683c": 1,
-    "0a3459aad03492bb": 1,
     "0ae281facb3c28dd": 1,
-    "0b48b63049c42591": 1,
     "0b8c71391c107a5e": 1,
     "0ba2d165b56db0b3": 1,
     "0ca2d9c2f2b44d6c": 1,
     "0caa402c4eae32d8": 1,
     "0fd23be8410c2c95": 1,
     "0fe4f3b5e5e939b3": 1,
-    "126a1cfe8f2264ce": 1,
     "1273365073edd790": 1,
     "13c4b58d3ea0719b": 1,
     "14beedf656e57fba": 1,
     "150c8efe188ac225": 1,
     "16340a16ed52849e": 1,
-    "17c26c0db2d35ad1": 1,
     "19ff70fc80fad524": 1,
     "1a9f0f0f68ed445c": 1,
     "1ad4dc7e19a77f68": 1,
@@ -42,7 +36,6 @@
     "22755b35701c5bb6": 1,
     "2296c06fa00da254": 1,
     "229b903386b17538": 1,
-    "22ab9a1ca6316d24": 1,
     "22cbd954358d25f8": 1,
     "230bfe57cfda164d": 1,
     "2357ae472525f6bf": 1,
@@ -51,6 +44,7 @@
     "266b9cb95f783cdf": 1,
     "26bb09996580437c": 1,
     "26ebb2e251c9a39e": 1,
+    "282eb8d84bbe54a4": 1,
     "29edfb9e08094991": 1,
     "2a78ee4b05679c8d": 1,
     "2b1a759e2cfd21a2": 1,
@@ -65,7 +59,6 @@
     "33357ce94e07cc4b": 1,
     "35cf2769645f3234": 1,
     "37bd4114d0089f49": 1,
-    "39cf8134a7fdaa31": 1,
     "3adca52a3f04837c": 1,
     "3c1017def7b3216c": 1,
     "3c5cb4b62d3739e3": 1,
@@ -79,7 +72,6 @@
     "441570d51d6f70a4": 1,
     "457c71f32f53833d": 1,
     "4715a17d690865ee": 1,
-    "47dc143be0bd8be5": 1,
     "4b0d3cc5c27227e7": 1,
     "4c3b94caa28045d0": 1,
     "4d1ff99bb19f5685": 1,
@@ -107,16 +99,15 @@
     "5ba2f3218754f04c": 1,
     "60052da86e7bb241": 1,
     "608e1dd27138ec6f": 1,
-    "60a3149247760d9b": 1,
     "60d0c58a01fc8746": 1,
     "61ae5da6cc003836": 1,
     "61bcadcd8dc9f63e": 1,
     "63ff613b1780c67a": 1,
     "642cc89ed49f8a21": 1,
     "6479c3604c153ec4": 1,
+    "65ce52f8afd6a952": 1,
     "66fb97eebd7ff0dc": 1,
     "67a95e428b8fa31c": 1,
-    "67c309590c5d69a1": 1,
     "6880d620e0e67229": 1,
     "69d50e6f6a5f2ee9": 1,
     "6a7ed9ad3fc00a39": 1,
@@ -153,6 +144,7 @@
     "86aae81b1aa0d21b": 1,
     "87484a2744e09748": 1,
     "8c2b1408886c1db1": 1,
+    "8d24ce7d6e8f6795": 1,
     "8e55579a412bc058": 1,
     "8ec18cdbd4a96518": 1,
     "901317bc4d7d30d0": 1,
@@ -178,10 +170,8 @@
     "a6ad7ab6c05656dc": 1,
     "a6ffab1aacd00af6": 1,
     "a71a4b720d466e32": 1,
-    "a71fab6edf38c846": 1,
     "a78d76908162699e": 1,
     "a9bd4ffef6da5faf": 1,
-    "ac3fe4ef966e0209": 1,
     "acc95d694eb2f581": 1,
     "ad4cfa76daa1b6fc": 1,
     "ad50b48938af8aef": 1,
@@ -203,7 +193,6 @@
     "bb5b0c8d22c9667a": 1,
     "bc9115be3a462930": 1,
     "bd0ae42c13d5b4f9": 1,
-    "bd17b166d89cb709": 1,
     "bdb8ca169be36b80": 1,
     "bdcd11c2bfb5fde0": 1,
     "be0900fb3e87164e": 1,
@@ -235,8 +224,6 @@
     "d6fa9884eee815f0": 1,
     "d86bafb915488255": 1,
     "da2c10a66acdb52f": 1,
-    "dabb9fc09638e178": 1,
-    "dcc616702e5b0cb4": 1,
     "de0bf2317c53d427": 1,
     "de1b481bfe8c3e58": 1,
     "df2dc922f40485e7": 1,
@@ -256,7 +243,6 @@
     "eb9a70c2a21094ff": 1,
     "ebe03c5f8c2f5147": 1,
     "ee19c8b9b332ee98": 1,
-    "ef6b9112e659147b": 1,
     "f07f979f8c2706e8": 1,
     "f38f72095a67c95e": 1,
     "f40ba84763547f41": 1,
@@ -265,7 +251,6 @@
     "f4bfa7e503443cd1": 1,
     "f6678d6748e9c902": 1,
     "f67a07a611f39cb2": 1,
-    "f762b61eef0af530": 1,
     "f7b1f9d699bcd580": 1,
     "f81e07af5d3a1c3c": 1,
     "f904844f89cab699": 1,
@@ -275,6 +260,7 @@
     "fb4a079a529a6285": 1,
     "fc0d7bde0033411d": 1,
     "fccfd8b004c12dd4": 1,
-    "fe859df9f97c75d4": 1
+    "fe859df9f97c75d4": 1,
+    "ff3b6c3e0b8bf33b": 1
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.29.0
+
+### Minor Changes
+
+- 4939956: Harden trace privacy and bounded mutation capture; rotate continuous bundles before writes and retain segments by default. Fix CDP selection cleanup and zero-page reconnect, add persistent profile adoption, idle heartbeats and tab enforcement, preserve queued trigger starts during stop, and make overlay dismissal report failures safely. Export trace rendering/summary tools and document the 0.28 trigger migration and packaged guides.
+
 ## 0.28.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,7 @@
 
 A universal browser automation library for JavaScript/TypeScript that supports Playwright, Puppeteer, and Selenium with a unified API. The key focus is on **stoppable page triggers** - ensuring automation logic is properly mounted/unmounted during page navigation.
 
-See [engine support and native/CLI defaults](../docs/engine-support.md) for the
+See [engine support and native/CLI defaults](https://github.com/link-foundation/browser-commander/blob/main/docs/engine-support.md) for the
 cross-language API matrix and Selenium examples.
 
 ## Installation
@@ -119,7 +119,7 @@ const { browser, page } = await launchBrowser({
 ```
 
 Every switch Browser Commander used to add on its own is available as a named
-[launch restriction](../docs/feature-parity.md#launch-command-line-and-opt-in-restrictions);
+[launch restriction](https://github.com/link-foundation/browser-commander/blob/main/docs/feature-parity.md#launch-command-line-and-opt-in-restrictions);
 `restrictions: ['legacy-defaults']` restores the old `CHROME_ARGS`. Pass
 `launch: 'engine'` to use Playwright's `launchPersistentContext()` or
 `puppeteer.launch()` instead; the engine then adds its own switches, and
@@ -379,6 +379,10 @@ commander.pageTrigger({
 });
 ```
 
+For trace budgets/privacy, persistent session adoption and heartbeats, CDP
+`noDefaults`, overlay reporting, and the `readyOn`/`concurrency` trigger migration,
+see [trace and session hardening](https://github.com/link-foundation/browser-commander/blob/f5e426d6933c681189c4989bac182a1558d8edb8/docs/trace-session-hardening.md).
+
 ## API Reference
 
 ### launchBrowser(options)
@@ -520,7 +524,7 @@ headless. `connectWebDriver({ serverUrl, capabilities })` opens a session on a
 server that is already running (a Selenium Grid, a cloud provider); pass
 `capabilities: { webSocketUrl: true }` for BiDi. Media emulation, fingerprint
 overrides and managed downloads need CDP and throw on this engine; see
-[docs/feature-parity.md](../docs/feature-parity.md#webdriver-engine).
+[docs/feature-parity.md](https://github.com/link-foundation/browser-commander/blob/main/docs/feature-parity.md#webdriver-engine).
 
 ### listBrowserProfiles(options)
 
@@ -686,6 +690,8 @@ const commander = makeBrowserCommander({
   verbose: false, // Enable debug logging
   enableNetworkTracking: true, // Track HTTP requests
   enableNavigationManager: true, // Enable navigation events
+  overlays: [{ selector: '.consent-close', timeout: 1000 }],
+  onOverlayDismiss: (report) => console.log(report.selector, report.status),
 });
 ```
 
@@ -693,10 +699,14 @@ const commander = makeBrowserCommander({
 
 ```javascript
 const unregister = commander.pageTrigger({
-  name: 'trigger-name',                    // For debugging
-  condition: (ctx) => boolean,             // When to run (receives {url, commander})
-  action: async (ctx) => void,             // What to do
-  priority: 0,                             // Higher runs first
+  name: 'application-ready',
+  readyOn: 'domcontentloaded', // Default: networkidle
+  concurrency: 'queue', // Default: skip; also restart
+  condition: ({ url }) => url.includes('/application'),
+  action: async (ctx) => {
+    ctx.checkStopped();
+  },
+  priority: 0, // Higher runs first
 });
 ```
 
@@ -802,7 +812,7 @@ failed or cancelled download raises the failure rather than returning a path.
 
 ### Portable Traces
 
-See [capture, debugging and reusable sessions](../docs/capture-and-debugging.md)
+See [capture, debugging and reusable sessions](https://github.com/link-foundation/browser-commander/blob/main/docs/capture-and-debugging.md)
 for screenshots, recordings, full/text DOM links, network/HAR, rotation,
 persistent browsers, early trigger readiness and engine capability limits.
 
@@ -1028,7 +1038,7 @@ This is the **official extensibility mechanism** while awaiting browser-commande
 
 ## Command Line
 
-The package installs a `browser-commander` command. The Rust and Python packages ship the same command, and the contract all three follow is [docs/cli-and-bridge.md](../docs/cli-and-bridge.md). Every command prints exactly one JSON document to stdout. The exit code is `0` on success and `1` on error. `doctor` exits `2` when it finds an unlisted difference, and a usage error exits `64`.
+The package installs a `browser-commander` command. The Rust and Python packages ship the same command, and the contract all three follow is [docs/cli-and-bridge.md](https://github.com/link-foundation/browser-commander/blob/main/docs/cli-and-bridge.md). Every command prints exactly one JSON document to stdout. The exit code is `0` on success and `1` on error. `doctor` exits `2` when it finds an unlisted difference, and a usage error exits `64`.
 
 ```bash
 npx browser-commander version
@@ -1068,4 +1078,4 @@ See [src/ARCHITECTURE.md](src/ARCHITECTURE.md) for detailed architecture documen
 
 [UNLICENSE](../LICENSE)
 
-See [navigation budgets, launch diagnostics, reusable helpers and sessions](../docs/navigation-launch-and-sessions.md) for the shared API contracts and engine limitations.
+See [navigation budgets, launch diagnostics, reusable helpers and sessions](https://github.com/link-foundation/browser-commander/blob/main/docs/navigation-launch-and-sessions.md) for the shared API contracts and engine limitations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {

package/src/browser/browser-profile-files.js

@@ -10,13 +10,16 @@ export function localStatePathForProfile(profileDir) {
 }
 
 /** Resolve existing ancestors even when the target profile does not exist. */
-export function physicalPath(value) {
+export function physicalPath(value, resolve = realpathSync) {
   let existing = path.resolve(value);
   const suffix = [];
   while (true) {
     try {
-      return path.join(realpathSync(existing), ...suffix.reverse());
+      return path.join(resolve(existing), ...suffix.reverse());
     } catch (error) {
+      if (['EPERM', 'EACCES'].includes(error.code)) {
+        return path.resolve(value);
+      }
       if (!['ENOENT', 'ENOTDIR'].includes(error.code)) {
         throw error;
       }

package/src/browser/connector.js

@@ -45,11 +45,17 @@ async function connectSelenium(options, dependencies) {
         ...options,
         debuggerAddress: new URL(options.cdpEndpoint).host,
       });
-  await selectWebDriverTab(connected.driver, options);
+  try {
+    await selectWebDriverTab(connected.driver, options);
+  } catch (error) {
+    await ignoreCleanup(() => connected.close());
+    throw error;
+  }
   return {
     ...connected,
     browser: connected.driver,
     disconnect: connected.close,
+    detach: connected.close,
   };
 }
 
@@ -60,11 +66,14 @@ async function selectWebDriverTab(driver, options) {
   const original = await driver.getWindowHandle();
   const handles = await driver.getAllWindowHandles();
   let selected = original;
-  if (options.targetId || options.url) {
+  const matchers = urlMatchers(options);
+  if (options.targetId || matchers.length) {
     selected = null;
+    const tabs = [];
     for (const handle of handles) {
       if (
         options.targetId &&
+        !options.fallback &&
         handle !== options.targetId &&
         handle !== `CDwindow-${options.targetId}`
       ) {
@@ -72,22 +81,26 @@ async function selectWebDriverTab(driver, options) {
       }
       await driver.switchTo().window(handle);
       const url = await driver.getCurrentUrl();
-      if (
-        options.url &&
-        !(typeof options.url === 'function'
-          ? options.url(url)
-          : options.url instanceof RegExp
-            ? options.url.test(url)
-            : url === options.url)
-      ) {
-        continue;
-      }
-      selected = handle;
-      break;
+      tabs.push({ handle, url });
     }
+    selected = matchers.length
+      ? matchers
+          .map(
+            (matcher) =>
+              tabs.find((tab) => matchesUrl(matcher, tab.url))?.handle
+          )
+          .find(Boolean)
+      : tabs.find(
+          (tab) =>
+            tab.handle === options.targetId ||
+            tab.handle === `CDwindow-${options.targetId}`
+        )?.handle;
     if (!selected) {
-      await driver.switchTo().window(original);
-      throw new Error('No tab matches the requested targetId or URL');
+      if (!options.fallback) {
+        await driver.switchTo().window(original);
+        throw new Error('No tab matches the requested targetId or URL');
+      }
+      selected = handles.includes(original) ? original : handles[0];
     }
   }
   if (options.singleTab) {
@@ -108,8 +121,13 @@ function addDefinedOptions(options, values) {
   return options;
 }
 
-function buildPlaywrightConnectOptions({ slowMo, timeout, headers }) {
-  return addDefinedOptions({}, { slowMo, timeout, headers });
+function buildPlaywrightConnectOptions({
+  slowMo,
+  timeout,
+  headers,
+  noDefaults,
+}) {
+  return addDefinedOptions({}, { slowMo, timeout, headers, noDefaults });
 }
 
 function buildPuppeteerConnectOptions({
@@ -130,6 +148,55 @@ function buildPuppeteerConnectOptions({
   );
 }
 
+export function matchesUrl(matcher, url) {
+  if (matcher instanceof RegExp) {
+    matcher.lastIndex = 0;
+    return matcher.test(url);
+  }
+  return typeof matcher === 'function' ? matcher(url) : matcher === url;
+}
+
+function urlMatchers(options) {
+  return (
+    options.urlMatchers ??
+    (Array.isArray(options.url)
+      ? options.url
+      : options.url
+        ? [options.url]
+        : [])
+  );
+}
+
+async function ignoreCleanup(cleanup) {
+  try {
+    await cleanup();
+  } catch {
+    /* Preserve the connection failure. */
+  }
+}
+
+function requestedPage(pages, targets, options) {
+  const matchers = urlMatchers(options);
+  if (!options.targetId && !matchers.length) {
+    return undefined;
+  }
+  const candidates = options.targetId
+    ? pages.filter((page) => targets.get(page) === options.targetId)
+    : pages;
+  const eligible = candidates.length || !options.fallback ? candidates : pages;
+  const selected = matchers.length
+    ? matchers
+        .map((matcher) =>
+          eligible.find((page) => matchesUrl(matcher, page.url()))
+        )
+        .find(Boolean)
+    : candidates[0];
+  if (!selected && !options.fallback) {
+    throw new RangeError('No tab matches the requested targetId/URL');
+  }
+  return selected;
+}
+
 async function prepareStorageState({ storageState, seedCookies }) {
   if (seedCookies !== undefined && !Array.isArray(seedCookies)) {
     throw new TypeError('seedCookies must be an array');
@@ -180,30 +247,10 @@ export async function pickForegroundPage(pages, options = {}) {
       // Non-Chromium engines do not expose CDP. Explicit URL matching still
       // works there, and normal visibility is not affected by this emulation.
     } finally {
-      await session?.detach?.().catch(() => {});
-    }
-  }
-  let selected;
-  if (options.targetId || options.url) {
-    selected = pages.find((page) => {
-      if (options.targetId && targets.get(page) !== options.targetId) {
-        return false;
-      }
-      const url = page.url();
-      const matcher = options.url;
-      if (matcher instanceof RegExp) {
-        matcher.lastIndex = 0;
-        return matcher.test(url);
-      }
-      if (typeof matcher === 'function') {
-        return matcher(url);
-      }
-      return !matcher || matcher === url;
-    });
-    if (!selected) {
-      throw new RangeError('No tab matches the requested targetId/URL');
+      await ignoreCleanup(() => session?.detach?.());
     }
   }
+  let selected = requestedPage(pages, targets, options);
   if (!selected) {
     for (const page of pages) {
       if (typeof page?.evaluate !== 'function') {
@@ -232,20 +279,38 @@ export async function pickForegroundPage(pages, options = {}) {
 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 settings = buildPlaywrightConnectOptions(options);
+  let browser;
+  try {
+    browser = await chromium.connectOverCDP(endpoint, settings);
+  } catch (error) {
+    if (
+      settings.noDefaults !== undefined ||
+      !/Browser\.setDownloadBehavior/.test(error.message) ||
+      !/Browser context management is not supported/.test(error.message)
+    ) {
+      throw error;
+    }
+    browser = await chromium.connectOverCDP(endpoint, {
+      ...settings,
+      noDefaults: true,
+    });
   }
-  const page =
-    (await pickForegroundPage(context.pages(), options)) ??
-    (await context.newPage());
+  try {
+    const context = browser.contexts()[0];
+    if (!context) {
+      throw new Error('Connected Playwright browser has no default context');
+    }
+    const page =
+      (await pickForegroundPage(context.pages(), options)) ??
+      (await context.newPage());
 
-  await restorePlaywrightStorageState({ context, storageState });
-  return { browser, page, detach: browser.close?.bind(browser) };
+    await restorePlaywrightStorageState({ context, storageState });
+    return { browser, page, detach: browser.close?.bind(browser) };
+  } catch (error) {
+    await ignoreCleanup(() => browser.close?.());
+    throw error;
+  }
 }
 
 async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
@@ -254,12 +319,17 @@ async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
   const browser = await puppeteer.connect(
     buildPuppeteerConnectOptions(options)
   );
-  const page =
-    (await pickForegroundPage(await browser.pages(), options)) ??
-    (await browser.newPage());
+  try {
+    const page =
+      (await pickForegroundPage(await browser.pages(), options)) ??
+      (await browser.newPage());
 
-  await restorePuppeteerStorageState({ page, storageState });
-  return { browser, page, detach: browser.disconnect?.bind(browser) };
+    await restorePuppeteerStorageState({ page, storageState });
+    return { browser, page, detach: browser.disconnect?.bind(browser) };
+  } catch (error) {
+    await ignoreCleanup(() => browser.disconnect?.());
+    throw error;
+  }
 }
 
 /**
@@ -313,7 +383,7 @@ export async function connectBrowserWithDependencies(
       });
       return { ...result, downloads };
     } catch (error) {
-      await result.close();
+      await ignoreCleanup(() => result.close());
       throw error;
     }
   }
@@ -346,14 +416,19 @@ export async function connectBrowserWithDependencies(
 
   // An attached browser gets the same managed lifecycle as a launched one:
   // the manager is built from the browser and page, not from how we got them.
-  const downloads = await attachDownloads({
-    engine,
-    browser: result.browser,
-    page: result.page,
-    downloads: normalizedOptions.downloads,
-  });
+  try {
+    const downloads = await attachDownloads({
+      engine,
+      browser: result.browser,
+      page: result.page,
+      downloads: normalizedOptions.downloads,
+    });
 
-  return { ...result, downloads };
+    return { ...result, downloads };
+  } catch (error) {
+    await ignoreCleanup(() => result.detach?.());
+    throw error;
+  }
 }
 
 export { buildPlaywrightConnectOptions, buildPuppeteerConnectOptions };