browser-commander 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.28.0
+
+### Minor Changes
+
+- cc2a209: Add portable screenshots, bounded recordings and GIF/APNG/WebP encoding, trace
+  rendering and summaries, full/text DOM links, bounded redacted network/HAR,
+  continuous trace rotation/gzip, and detached reusable browser sessions with idle
+  shutdown. Add early trigger readiness, explicit trigger concurrency, visible
+  counts and configured overlay dismissal. Fix navigation-interrupted waits,
+  Trusted Types capture, Chrome panel restrictions and deterministic tab selection.
+  Close ordinary launched CLI browsers even when their connection supports detach;
+  only explicitly kept-open sessions survive dispatcher cleanup.
+  Add stable viewport capture with native-view CDP, viewport-only engine fallbacks
+  and displayed-window regression coverage; document full-page compositor effects.
+  Preserve readiness timer expiry when the rounded clock still reports budget.
+
 ## 0.27.0
 
 ### Minor Changes

package/README.md

@@ -802,6 +802,10 @@ 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)
+for screenshots, recordings, full/text DOM links, network/HAR, rotation,
+persistent browsers, early trigger readiness and engine capability limits.
+
 `startTrace()` records a session into a schema-versioned bundle any of the three
 languages can read - the manifest, an ordered NDJSON timeline, per-checkpoint
 DOM snapshots and the mutation batches between them:

package/eslint.config.js

@@ -141,6 +141,17 @@ export default [
       'max-lines-per-function': 'off',
     },
   },
+  {
+    // Browser init scripts are serialized as one self-contained function.
+    // Keep its DOM/redaction helpers inside the payload.
+    files: ['src/traces/page-capture.js'],
+    rules: {
+      'max-lines-per-function': [
+        'warn',
+        { max: 350, skipBlankLines: true, skipComments: true },
+      ],
+    },
+  },
   {
     // Test files have different requirements
     files: ['tests/**/*.js', '**/*.test.js'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {
@@ -83,10 +83,13 @@
     "bplist-parser": "^0.5.0",
     "command-stream": "^1.4.0",
     "csv-parse": "^7.0.3",
+    "gifenc": "^1.0.3",
     "links-notation": "^0.23.0",
     "log-lazy": "^1.0.4",
     "plist": "^5.0.0",
-    "test-anywhere": "^0.9.1"
+    "test-anywhere": "^0.9.1",
+    "upng-js": "^2.1.0",
+    "webp-wasm": "^1.0.6"
   },
   "devDependencies": {
     "@changesets/cli": "^3.0.3",

package/src/browser/connector.js

@@ -45,6 +45,7 @@ async function connectSelenium(options, dependencies) {
         ...options,
         debuggerAddress: new URL(options.cdpEndpoint).host,
       });
+  await selectWebDriverTab(connected.driver, options);
   return {
     ...connected,
     browser: connected.driver,
@@ -52,6 +53,52 @@ async function connectSelenium(options, dependencies) {
   };
 }
 
+async function selectWebDriverTab(driver, options) {
+  if (!driver?.getAllWindowHandles) {
+    return;
+  }
+  const original = await driver.getWindowHandle();
+  const handles = await driver.getAllWindowHandles();
+  let selected = original;
+  if (options.targetId || options.url) {
+    selected = null;
+    for (const handle of handles) {
+      if (
+        options.targetId &&
+        handle !== options.targetId &&
+        handle !== `CDwindow-${options.targetId}`
+      ) {
+        continue;
+      }
+      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;
+    }
+    if (!selected) {
+      await driver.switchTo().window(original);
+      throw new Error('No tab matches the requested targetId or URL');
+    }
+  }
+  if (options.singleTab) {
+    for (const handle of handles.filter((handle) => handle !== selected)) {
+      await driver.switchTo().window(handle);
+      await driver.close();
+    }
+  }
+  await driver.switchTo().window(selected);
+}
+
 function addDefinedOptions(options, values) {
   for (const [key, value] of Object.entries(values)) {
     if (value !== undefined) {
@@ -111,19 +158,75 @@ async function prepareStorageState({ storageState, seedCookies }) {
  * @param {Object[]} pages - Engine page handles
  * @returns {Promise<Object|undefined>}
  */
-export async function pickForegroundPage(pages) {
+export async function pickForegroundPage(pages, options = {}) {
+  const targets = new Map();
+  // Playwright emulates focus on every attached tab. Remove the emulation
+  // before observing visibility; DevTools target order has no active-tab flag.
   for (const page of pages) {
-    if (typeof page?.evaluate !== 'function') {
-      continue;
+    let session;
+    try {
+      session =
+        (await page.context?.().newCDPSession?.(page)) ??
+        (await page.target?.().createCDPSession?.());
+      if (!session) {
+        continue;
+      }
+      const { targetInfo } = await session.send('Target.getTargetInfo');
+      targets.set(page, targetInfo.targetId);
+      await session.send('Emulation.setFocusEmulationEnabled', {
+        enabled: false,
+      });
+    } catch {
+      // 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');
     }
-    const state = await page
-      .evaluate(() => document.visibilityState)
-      .catch(() => null);
-    if (state === 'visible') {
-      return page;
+  }
+  if (!selected) {
+    for (const page of pages) {
+      if (typeof page?.evaluate !== 'function') {
+        continue;
+      }
+      const state = await page
+        .evaluate(() => document.visibilityState)
+        .catch(() => null);
+      if (state === 'visible') {
+        selected = page;
+        break;
+      }
+    }
+  }
+  selected ??= pages[0];
+  if (options.singleTab && selected) {
+    for (const page of pages) {
+      if (page !== selected) {
+        await page.close();
+      }
     }
   }
-  return pages[0];
+  return selected;
 }
 
 async function connectPlaywright({ options, loadPlaywright, storageState }) {
@@ -138,10 +241,11 @@ async function connectPlaywright({ options, loadPlaywright, storageState }) {
     throw new Error('Connected Playwright browser has no default context');
   }
   const page =
-    (await pickForegroundPage(context.pages())) ?? (await context.newPage());
+    (await pickForegroundPage(context.pages(), options)) ??
+    (await context.newPage());
 
   await restorePlaywrightStorageState({ context, storageState });
-  return { browser, page };
+  return { browser, page, detach: browser.close?.bind(browser) };
 }
 
 async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
@@ -151,11 +255,11 @@ async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
     buildPuppeteerConnectOptions(options)
   );
   const page =
-    (await pickForegroundPage(await browser.pages())) ??
+    (await pickForegroundPage(await browser.pages(), options)) ??
     (await browser.newPage());
 
   await restorePuppeteerStorageState({ page, storageState });
-  return { browser, page };
+  return { browser, page, detach: browser.disconnect?.bind(browser) };
 }
 
 /**

package/src/browser/launch-options.js

@@ -26,6 +26,7 @@ export function resolveChromeArgs({
   extraArgs = [],
   ignoreDefaultArgs = [],
   restrictions = [],
+  disableFeatures = [],
 } = {}) {
   assertStringArray(args, 'args');
   assertStringArray(extraArgs, 'extraArgs');
@@ -41,7 +42,7 @@ export function resolveChromeArgs({
 
   return {
     args: mergeFeatureSwitches([
-      ...resolveRestrictions(restrictions).args,
+      ...resolveRestrictions(restrictions, { disableFeatures }).args,
       ...args,
       ...extraArgs,
     ]),

package/src/browser/launch-restrictions.json

@@ -17,7 +17,8 @@
         "--disable-session-crashed-bubble",
         "--hide-crash-restore-bubble",
         "--disable-crash-restore"
-      ]
+      ],
+      "disableFeatures": ["SessionRestoreInfobar"]
     },
     {
       "id": "no-infobars",
@@ -60,7 +61,12 @@
     {
       "id": "no-translate",
       "description": "Disable the Translate feature and its bubble.",
-      "disableFeatures": ["Translate"]
+      "disableFeatures": ["Translate"],
+      "preferences": {
+        "translate": {
+          "enabled": false
+        }
+      }
     },
     {
       "id": "no-component-update",
@@ -124,6 +130,24 @@
       "id": "start-maximized",
       "description": "Start with a maximized window.",
       "args": ["--start-maximized"]
+    },
+    {
+      "id": "no-save-bubbles",
+      "description": "Suppress password and payment-card saving bubbles and browser promos.",
+      "disableFeatures": [
+        "AutofillSaveCardUi",
+        "ChromeWhatsNewUI",
+        "PromotionalTabs"
+      ],
+      "preferences": {
+        "credentials_enable_service": false,
+        "profile": {
+          "password_manager_enabled": false
+        },
+        "autofill": {
+          "credit_card_enabled": false
+        }
+      }
     }
   ],
   "presets": {
@@ -142,6 +166,13 @@
       "no-default-browser-check",
       "no-google-services",
       "no-translate"
+    ],
+    "quiet-ui": [
+      "no-first-run",
+      "no-default-browser-check",
+      "no-crash-restore",
+      "no-translate",
+      "no-save-bubbles"
     ]
   }
 }

package/src/browser/launcher.js

@@ -7,6 +7,7 @@ import {
 
 import { assertSupportedEngine } from './connector.js';
 import { emulateMedia } from './media.js';
+import { reserveLoopbackPort } from './debugging-port.js';
 import {
   buildPlaywrightLaunchOptions,
   buildPuppeteerLaunchOptions,
@@ -14,6 +15,7 @@ import {
 } from './launch-options.js';
 import {
   createTemporaryUserDataDir,
+  configureUserDataDir,
   removeUserDataDir,
 } from './profile-directory.js';
 import { launchRealBrowser } from './real-browser.js';
@@ -168,6 +170,7 @@ async function launchWithEngine(options, dependencies) {
     extraArgs,
     ignoreDefaultArgs,
     restrictions,
+    disableFeatures: options.disableFeatures,
   });
   const restrictionEnv = resolveRestrictions(restrictions).env;
   const childEnv =
@@ -177,6 +180,13 @@ async function launchWithEngine(options, dependencies) {
   const temporaryProfile = !requestedUserDataDir;
   const userDataDir =
     requestedUserDataDir ?? (await createTemporaryUserDataDir());
+  await configureUserDataDir(userDataDir, {
+    preferences: {
+      ...resolveRestrictions(restrictions).preferences,
+      ...options.preferences,
+    },
+    localState: options.localState,
+  });
   const engineModule = await (
     dependencies.loadEngineModule ?? loadEngine[engine]
   )();
@@ -307,6 +317,15 @@ export async function launchBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  if (options.keepOpen) {
+    const { connectOrLaunch } = await import('./persistent-session.js');
+    return connectOrLaunch({
+      ...options,
+      userDataDir: options.userDataDir ?? (await createTemporaryUserDataDir()),
+      remoteDebuggingPort:
+        options.remoteDebuggingPort ?? (await reserveLoopbackPort()),
+    });
+  }
   sessionPersistencePath(options);
   if (isSafariChannel(options.channel ?? options.browser)) {
     validateLaunchMode({
@@ -355,7 +374,13 @@ async function launchNonSafariBrowser(options, dependencies) {
     }
   }
   // Validate arguments before anything is started or written to disk.
-  resolveChromeArgs({ args, extraArgs, ignoreDefaultArgs, restrictions });
+  resolveChromeArgs({
+    args,
+    extraArgs,
+    ignoreDefaultArgs,
+    restrictions,
+    disableFeatures: options.disableFeatures,
+  });
   const resolvedStorageState = await loadStorageState(storageState);
 
   if (verbose) {