browser-commander 0.20.0 → 0.21.0

package/src/downloads/attach.js

@@ -47,6 +47,12 @@ export function attachDownloads({ engine, browser, page, downloads, log }) {
   if (!managerOptions) {
     return null;
   }
+  if (engine === 'selenium') {
+    throw new Error(
+      'Managed downloads are not available with the selenium engine: they ' +
+        'are driven by CDP download events (see the webdriver-no-cdp-emulation limitation)'
+    );
+  }
 
   return createDownloadManager({
     engine,

package/src/elements/selectors.js

@@ -302,9 +302,10 @@ export function withTextSelectorSupport(fn, engine, page) {
   return async (options = {}) => {
     let { selector } = options;
 
-    // Normalize Puppeteer text selectors (object format)
+    // Normalize Puppeteer-style text selectors (object format; Puppeteer and
+    // selenium)
     if (
-      engine === 'puppeteer' &&
+      engine !== 'playwright' &&
       typeof selector === 'object' &&
       selector._isPuppeteerTextSelector
     ) {

package/src/elements/visibility.js

@@ -149,6 +149,10 @@ export async function count(options = {}) {
       );
       return result;
     }
+    if (engine === 'selenium' && selector?._isPuppeteerTextSelector) {
+      // The WebDriverPage facade evaluates like a Puppeteer page (issue #104).
+      return await count({ ...options, engine: 'puppeteer' });
+    }
 
     if (engine === 'playwright') {
       return await page.locator(selector).count();

package/src/exports.js

@@ -27,9 +27,24 @@ export {
   EngineAdapter,
   PlaywrightAdapter,
   PuppeteerAdapter,
+  SeleniumAdapter,
   createEngineAdapter,
 } from './core/engine-adapter.js';
 
+// Selenium / WebDriver engine (issue #104)
+export {
+  WebDriverPage,
+  WebDriverTimeoutError,
+  createWebDriverPage,
+  isWebDriver,
+} from './core/webdriver-page.js';
+export {
+  launchWebDriver,
+  connectWebDriver,
+  resolveWebDriverExecutable,
+  CHROMEDRIVER_DEFAULT_SWITCHES,
+} from './browser/webdriver.js';
+
 // Page trigger system
 export {
   createPageTriggerManager,
@@ -51,7 +66,49 @@ export {
   launchAndConnectRealBrowser,
   launchRealBrowser,
 } from './browser/real-browser.js';
-export { launchBrowser } from './browser/launcher.js';
+export {
+  classifyDifferences,
+  compareCommandLines,
+  measureParity,
+  parseSwitches,
+  readBrowserVersionPage,
+} from './browser/parity.js';
+export {
+  openInUserBrowser,
+  buildOpenCommand,
+  validateOpenUrl,
+} from './browser/open-in-user-browser.js';
+export { migrateProfile, ALL_DATA_CLASSES } from './browser/migration/index.js';
+export {
+  attachUserBrowser,
+  attachViaExtension,
+  ATTACH_MODES,
+  DEFAULT_RELAY_PORT,
+  describeAttachDifferences,
+  EXTENSION_DIRECTORY,
+  RELAY_PATH,
+  snapshotUserDataDir,
+} from './browser/attach/index.js';
+export {
+  launchBrowser,
+  LAUNCH_MODES,
+  resolveLaunchExecutable,
+} from './browser/launcher.js';
+export {
+  LAUNCH_RESTRICTIONS,
+  LAUNCH_RESTRICTION_PRESETS,
+  resolveRestrictions,
+  mergeFeatureSwitches,
+} from './browser/restrictions.js';
+export {
+  createTemporaryUserDataDir,
+  prepareUserDataDir,
+  removeUserDataDir,
+} from './browser/profile-directory.js';
+export {
+  PortRaceError,
+  reserveLoopbackPort,
+} from './browser/debugging-port.js';
 export { saveStorageState } from './browser/storage-state.js';
 export { emulateMedia } from './browser/media.js';
 export {
@@ -187,7 +244,9 @@ export {
   buildFingerprintInitScript,
   buildInitScriptConfig,
 } from './fingerprint/init-script.js';
-export { applyFingerprint, createCdpSession } from './fingerprint/apply.js';
+export { applyFingerprint } from './fingerprint/apply.js';
+// Raw CDP with one surface for both engines (issue #104).
+export { createCdpSession, wrapCdpSession } from './browser/cdp-session.js';
 export {
   FINGERPRINT_PRESET_NAMES,
   createFingerprintPreset,

package/src/factory.js

@@ -6,6 +6,7 @@
 
 import { createLogger } from './core/logger.js';
 import { detectEngine } from './core/engine-detection.js';
+import { WebDriverPage } from './core/webdriver-page.js';
 import { createNetworkTracker } from './core/network-tracker.js';
 import { createNavigationManager } from './core/navigation-manager.js';
 import { createPageSessionFactory } from './core/page-session.js';
@@ -22,11 +23,12 @@ import {
 import { createBoundFunctions } from './bindings.js';
 import { attachDownloads } from './downloads/attach.js';
 import { startTrace } from './traces/recorder.js';
+import { createCdpSession } from './browser/cdp-session.js';
 
 /**
  * Create a browser commander instance for a specific page
  * @param {Object} options - Configuration options
- * @param {Object} options.page - Playwright or Puppeteer page object
+ * @param {Object} options.page - Playwright or Puppeteer page object, or a selenium-webdriver WebDriver (or the WebDriverPage launchWebDriver() returns)
  * @param {boolean} options.verbose - Enable verbose logging
  * @param {boolean} options.enableNetworkTracking - Enable network request tracking (default: true)
  * @param {boolean} options.enableNavigationManager - Enable navigation manager (default: true)
@@ -35,7 +37,7 @@ import { startTrace } from './traces/recorder.js';
  */
 export function makeBrowserCommander(options = {}) {
   const {
-    page,
+    page: providedPage,
     verbose = false,
     enableNetworkTracking = true,
     enableNavigationManager = true,
@@ -43,11 +45,17 @@ export function makeBrowserCommander(options = {}) {
     downloads = null,
   } = options;
 
-  if (!page) {
+  if (!providedPage) {
     throw new Error('page is required in options');
   }
 
-  const engine = detectEngine(page);
+  const engine = detectEngine(providedPage);
+  // A bare selenium-webdriver WebDriver is wrapped in the page facade the
+  // helpers speak to (issue #104); launchWebDriver() already returns one.
+  const page =
+    engine === 'selenium' && !providedPage.isWebDriverPage
+      ? new WebDriverPage(providedPage)
+      : providedPage;
   const log = createLogger({ verbose });
 
   // Create NetworkTracker if enabled
@@ -177,6 +185,13 @@ export function makeBrowserCommander(options = {}) {
       return commander.downloads;
     },
 
+    /**
+     * Open a raw CDP session for this commander's page (issue #104).
+     *
+     * @returns {Promise<Object>} {send, on, once, off, detach, session, engine}
+     */
+    createCdpSession: () => createCdpSession(page, { engine }),
+
     /**
      * Start recording a privacy-aware trace of this session (issue #87).
      *

package/src/fingerprint/apply.js

@@ -14,6 +14,12 @@ import { resolveFingerprintProfile } from './profile.js';
 
 /** Open a CDP session for a page, whichever engine owns it. */
 export function createCdpSession({ browser, page, engine }) {
+  if (engine === 'selenium') {
+    throw new Error(
+      'Fingerprint profiles need a CDP session, which the selenium engine does ' +
+        'not have (see the webdriver-no-cdp-emulation limitation)'
+    );
+  }
   if (engine === 'puppeteer') {
     if (typeof page.createCDPSession === 'function') {
       return page.createCDPSession();

package/src/fingerprint/automation-parity.js

@@ -16,6 +16,13 @@
  * the browser. A specific port number is left alone on purpose, since that is
  * what a human attaching a debugger passes.
  *
+ * `kHeadless` is in that table but is not a trigger in practice: the renderer
+ * never sees the switch in today's headless mode. A hand-started Chrome 153
+ * with `--headless`, `--headless=new` or `--headless=old` and nothing else
+ * reports `navigator.webdriver === false`
+ * (experiments/issue-103/headless-webdriver.mjs), so a headless launch needs
+ * no off switch to match it, and adding one would be a difference of its own.
+ *
  * https://chromium.googlesource.com/chromium/src/+/refs/heads/main/content/child/runtime_features.cc
  */
 
@@ -30,11 +37,6 @@ export const AUTOMATION_CONTROLLED_TRIGGERS = Object.freeze([
     reason:
       'Mapped onto AutomationControlled in content/child/runtime_features.cc; also shows the "controlled by automated test software" infobar.',
   }),
-  Object.freeze({
-    switch: '--headless',
-    reason:
-      'Mapped onto AutomationControlled in content/child/runtime_features.cc; covers --headless and --headless=new alike.',
-  }),
   Object.freeze({
     switch: '--remote-debugging-pipe',
     reason:
@@ -59,9 +61,6 @@ function isTrigger(argument, trigger) {
       Number(argument.slice('--remote-debugging-port='.length)) === 0
     );
   }
-  if (trigger.switch === '--headless') {
-    return switchName(argument) === '--headless';
-  }
   return switchName(argument) === trigger.switch;
 }
 

package/src/fingerprint/limitations.js

@@ -8,7 +8,7 @@
  * `docs/case-studies/issue-79/analysis-artifacts/`.
  *
  * The catalogue itself lives in `limitations.json`, because Python and Rust
- * publish the same eleven entries and a hand-copied paragraph of prose drifts
+ * publish the same sixteen entries and a hand-copied paragraph of prose drifts
  * as easily as a hand-copied patch. This module owns the JSON; the copies are
  * checked byte for byte by `scripts/check-shared-fingerprint-assets.sh`.
  *

package/src/fingerprint/limitations.json

@@ -4,10 +4,19 @@
     "surface": "navigator.webdriver",
     "severity": "high",
     "evidence": "measured",
-    "detail": "navigator.webdriver is the AutomationControlled Blink runtime feature. Chrome enables it for --enable-automation, --headless, --remote-debugging-pipe and an ephemeral --remote-debugging-port=0, and the only way to turn it back off is the launch switch --disable-blink-features=AutomationControlled. Emulation.setAutomationOverride({enabled:false}) is accepted over CDP but leaves navigator.webdriver true, in the same document and after navigation, so a browser somebody else already launched cannot be corrected from the protocol side.",
-    "workaround": "Launch the browser through this library, which passes the switch. When attaching to a browser somebody else started, apply the profile with the webdriver patch option, which installs a JavaScript getter instead: that is weaker, because it does not reach workers or a renderer that starts before the patch is installed.",
+    "detail": "navigator.webdriver is the AutomationControlled Blink runtime feature. Chrome enables it for --enable-automation, --remote-debugging-pipe and an ephemeral --remote-debugging-port=0, and the only way to turn it back off is the launch switch --disable-blink-features=AutomationControlled. A fixed non-zero --remote-debugging-port does not enable it, and neither does --headless in any of its forms (measured with Chrome 153, experiments/issue-103/headless-webdriver.mjs). Emulation.setAutomationOverride({enabled:false}) is accepted over CDP but leaves navigator.webdriver true, in the same document and after navigation, so a browser somebody else already launched cannot be corrected from the protocol side.",
+    "workaround": "Launch the browser through this library: the default real launch starts it on a fixed port, so the feature is never enabled, and launch: 'engine' passes the off switch. When attaching to a browser somebody else started, apply the profile with the webdriver patch option, which installs a JavaScript getter instead: that is weaker, because it does not reach workers or a renderer that starts before the patch is installed.",
     "reference": "content/child/runtime_features.cc; analysis-artifacts/remote-debugging-isolation.json"
   },
+  {
+    "id": "engine-launch-switches",
+    "surface": "Browser UI and chrome://version command line",
+    "severity": "medium",
+    "evidence": "measured",
+    "detail": "With launch: 'engine' the browser is started by Playwright or Puppeteer, which add their own switches (--enable-automation, --remote-debugging-pipe or port 0, --disable-extensions, --disable-sync and more; see chrome://version). Browser Commander removes --enable-automation and adds --disable-blink-features=AutomationControlled so navigator.webdriver stays false, but Chrome answers that switch with the \"You are using an unsupported command-line flag\" infobar, and the remaining engine switches change which browser features exist.",
+    "workaround": "Use the default launch: 'real', which starts the browser with only --user-data-dir and a fixed --remote-debugging-port, and opt into individual restrictions by name when they are wanted.",
+    "reference": "js/tests/e2e/fingerprint-parity.e2e.test.js; experiments/issue-105/"
+  },
   {
     "id": "no-cdp-device-memory-override",
     "surface": "navigator.deviceMemory",
@@ -92,5 +101,39 @@
     "detail": "A worker has its own Navigator, and overrides set on the page session only partly reach it. Measured in a dedicated worker: userAgent, timezone and locale follow the profile, but platform, language, languages, hardwareConcurrency and deviceMemory all report the real host values, and no JavaScript patch is present because Page.addScriptToEvaluateOnNewDocument runs in documents only. Full worker parity is reachable over raw CDP -- replaying the Emulation commands on the worker session fixes languages and hardwareConcurrency, and evaluating the init script during the waitForDebuggerOnStart pause fixes the rest -- but that needs a sessionId, which neither engine accepts: Playwright newCDPSession takes only Page or Frame, and Puppeteer worker sessions are internal to its TargetManager.",
     "workaround": "Avoid workloads that read the fingerprint from a worker, or drive Chrome over a raw CDP connection and replay the commands the CDP override builder returns on each attached worker session.",
     "reference": "analysis-artifacts/worker-visibility.json"
+  },
+  {
+    "id": "webdriver-driver-launch-switches",
+    "surface": "navigator.webdriver and the browser command line under chromedriver",
+    "severity": "medium",
+    "evidence": "measured",
+    "detail": "chromedriver starts Chrome with twenty switches of its own. Two of them turn navigator.webdriver on by themselves: --enable-automation, and --remote-debugging-port=0 (any debugging port chosen by the browser). With chromedriver's defaults navigator.webdriver is true; excluding --enable-automation alone still leaves it true; excluding every default switch and giving Chrome a fixed debugging port makes it false, headful and headless, with and without BiDi. launchWebDriver() does exactly that, so its command line is the same as a real-browser launch. A driver started by someone else -- a Selenium Grid node, a cloud provider, connectWebDriver() -- keeps whatever switches it was given, and --disable-blink-features=AutomationControlled, the usual workaround, shows an unsupported-flag infobar.",
+    "workaround": "Launch the driver with launchWebDriver(), or pass the same excludeSwitches and a fixed --remote-debugging-port in the capabilities given to connectWebDriver().",
+    "reference": "experiments/issue-104/webdriver-automation-flags.mjs"
+  },
+  {
+    "id": "webdriver-no-cdp-emulation",
+    "surface": "Fingerprint profiles, media emulation and managed downloads on the selenium engine",
+    "severity": "medium",
+    "evidence": "documented",
+    "detail": "Fingerprint profiles, emulateMedia and managed downloads are built on Chrome DevTools Protocol commands and events (Emulation.*, Page.addScriptToEvaluateOnNewDocument with a CDP session, Browser.setDownloadBehavior). A WebDriver session exposes no CDP session through the W3C protocol, and WebDriver BiDi has no equivalent of most Emulation commands yet, so on the selenium engine these operations throw instead of silently doing nothing.",
+    "workaround": "Use the playwright or puppeteer engine for fingerprint profiles, media emulation and managed downloads, or set the equivalent browser preferences in the capabilities."
+  },
+  {
+    "id": "webdriver-classic-has-no-events",
+    "surface": "Console, page error, dialog, request and navigation events on the selenium engine",
+    "severity": "low",
+    "evidence": "documented",
+    "detail": "Classic WebDriver is request/response only: a session cannot be told about console messages, uncaught errors, dialogs, network requests or navigations it did not start. Those events, preload scripts and full-page or clipped screenshots come from WebDriver BiDi, which a session has only when it was created with the webSocketUrl capability. Without it the operations that need events throw an error naming the missing capability.",
+    "workaround": "Launch with bidi: true, or add webSocketUrl: true to the capabilities given to connectWebDriver()."
+  },
+  {
+    "id": "webdriver-print-options",
+    "surface": "pdf() options on the selenium engine",
+    "severity": "low",
+    "evidence": "documented",
+    "detail": "WebDriver Print Page takes orientation, scale, background, page size, margins, shrink-to-fit and page ranges only. Header and footer templates, preferCSSPageSize, tagged and outlined PDFs and omitBackground have no WebDriver equivalent; pdf() rejects them rather than producing a different document than the one asked for. Page and margin sizes are converted to centimetres.",
+    "workaround": "Leave the unsupported options out, or produce the PDF with the playwright or puppeteer engine.",
+    "reference": "https://w3c.github.io/webdriver/#print-page"
   }
 ]

package/src/parity/harness.js

@@ -0,0 +1,303 @@
+/**
+ * Parity harness: capture the environment probe from a browser that nothing is
+ * automating, then from a browser Browser Commander drives, and diff the two.
+ *
+ * The reference capture never speaks CDP. The browser is started as a plain
+ * child process pointed at a local page; the page runs the probe and POSTs the
+ * JSON report back. That is the only way to get a baseline that is genuinely
+ * "a real browser" rather than "a browser we are already driving". Automated
+ * captures are delivered the same way, so a difference in the diff is a
+ * difference in the browser rather than in how the probe was invoked.
+ */
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+
+import { startProcess } from '../utilities/subprocess.js';
+import {
+  createTemporaryUserDataDir,
+  removeUserDataDir,
+} from '../browser/profile-directory.js';
+
+/** Read the environment probe shipped with the package. */
+export function readProbeSource() {
+  return readFile(new URL('./probe.js', import.meta.url), 'utf8');
+}
+
+export function probeExpression(source) {
+  return `(${source})()`;
+}
+
+function probePage(probeSource, token) {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>probe</title></head>
+<body><p id="status">running</p>
+<script>
+${probeExpression(probeSource)}
+  .then((report) => fetch('/report/${token}', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(report),
+  }))
+  .then(() => { document.getElementById('status').textContent = 'done'; })
+  .catch((error) => fetch('/report/${token}', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ fatal: String(error && error.stack || error) }),
+  }));
+</script></body></html>`;
+}
+
+/** Serve the probe page and collect reports POSTed back by page scripts. */
+export async function startProbeServer(probeSource) {
+  const reports = new Map();
+  const waiters = new Map();
+  // The Accept-Language and Sec-CH-UA-* headers are part of the fingerprint and
+  // are only observable from the server side, so record them per token.
+  const requestHeaders = new Map();
+
+  const receiveReport = (token, request, response) => {
+    const chunks = [];
+    request.on('data', (chunk) => chunks.push(chunk));
+    request.on('end', () => {
+      const report = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      reports.set(token, report);
+      waiters.get(token)?.(report);
+      waiters.delete(token);
+      response.writeHead(204);
+      response.end();
+    });
+  };
+
+  const server = createServer((request, response) => {
+    const url = new URL(request.url, 'http://127.0.0.1');
+    if (request.method === 'GET' && url.pathname.startsWith('/probe/')) {
+      const token = url.pathname.slice('/probe/'.length);
+      requestHeaders.set(token, { ...request.headers });
+      response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      response.end(probePage(probeSource, token));
+      return;
+    }
+    if (request.method === 'POST' && url.pathname.startsWith('/report/')) {
+      receiveReport(url.pathname.slice('/report/'.length), request, response);
+      return;
+    }
+    response.writeHead(404);
+    response.end();
+  });
+
+  const port = await new Promise((resolve) =>
+    server.listen(0, '127.0.0.1', () => resolve(server.address().port))
+  );
+
+  return {
+    port,
+    url: (token) => `http://127.0.0.1:${port}/probe/${token}`,
+    headersFor: (token) => requestHeaders.get(token) || null,
+    waitForReport(token, timeoutMs = 60000) {
+      if (reports.has(token)) {
+        return Promise.resolve(reports.get(token));
+      }
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(
+          () => reject(new Error(`timed out waiting for report ${token}`)),
+          timeoutMs
+        );
+        waiters.set(token, (report) => {
+          clearTimeout(timer);
+          resolve(report);
+        });
+      });
+    },
+    async close() {
+      server.closeAllConnections?.();
+      await new Promise((resolve) => server.close(resolve));
+    },
+  };
+}
+
+/**
+ * The command line of a hand-started reference browser: a dedicated profile,
+ * headless when asked, and the page to open. Nothing else, so the reference is
+ * exactly what a person types.
+ *
+ * @param {Object} options
+ * @param {string} options.userDataDir
+ * @param {string} options.url
+ * @param {boolean} [options.headless=false]
+ * @param {string[]} [options.extraArgs]
+ * @returns {string[]}
+ */
+export function buildReferenceArgs({
+  userDataDir,
+  url,
+  headless = false,
+  extraArgs = [],
+}) {
+  return [
+    `--user-data-dir=${userDataDir}`,
+    ...(headless ? ['--headless=new'] : []),
+    ...extraArgs,
+    url,
+  ];
+}
+
+const STDERR_TAIL_BYTES = 4000;
+
+/** Keep the last few kilobytes a process wrote, for error messages. */
+function collectTail(channel) {
+  let tail = '';
+  channel?.on?.('data', (chunk) => {
+    tail = (tail + String(chunk)).slice(-STDERR_TAIL_BYTES);
+  });
+  return () => tail.trim();
+}
+
+function withOutput(error, output) {
+  if (output) {
+    error.message += `\nbrowser stderr:\n${output}`;
+  }
+  return error;
+}
+
+/**
+ * Reject as soon as the reference browser exits without having reported, so a
+ * browser that cannot start (a missing sandbox, a bad switch) fails with its
+ * own exit code and stderr instead of a silent report timeout. A clean exit
+ * never settles: a launcher script may hand off to a browser that keeps
+ * running and still reports.
+ */
+async function exitedBeforeReport(child, executablePath, stderr) {
+  const code = await child.exited;
+  if (code === 0) {
+    return new Promise(() => {});
+  }
+  throw withOutput(
+    new Error(
+      `reference browser ${executablePath} exited with code ${code} before reporting`
+    ),
+    stderr()
+  );
+}
+
+/**
+ * Start the browser as an ordinary user would - no CDP, no automation
+ * switches - and collect the probe report its page POSTs back.
+ *
+ * The profile is prepared exactly like the launcher's temporary profile: the
+ * `First Run` sentinel and the "What's new" milestone in `Local State` keep
+ * the first-run UI and a second tab from opening.
+ *
+ * @returns {Promise<Object>} The probe report with `commandLine` attached
+ */
+async function captureReferenceAttempt({
+  executablePath = process.env.CHROME_PATH || 'google-chrome',
+  server,
+  token,
+  extraArgs = [],
+  headless = false,
+  timeoutMs = 60000,
+  start = startProcess,
+}) {
+  const userDataDir = await createTemporaryUserDataDir();
+  const args = buildReferenceArgs({
+    userDataDir,
+    url: server.url(token),
+    headless,
+    extraArgs,
+  });
+  const child = start(executablePath, args, { killGrace: 3000 });
+  const stderr = collectTail(child.stderr);
+  try {
+    const report = await Promise.race([
+      server.waitForReport(token, timeoutMs).catch((error) => {
+        throw withOutput(error, stderr());
+      }),
+      exitedBeforeReport(child, executablePath, stderr),
+    ]);
+    Object.defineProperty(report, 'commandLine', {
+      value: args,
+      enumerable: false,
+    });
+    return report;
+  } finally {
+    child.kill('SIGTERM');
+    await child.exited;
+    await removeUserDataDir(userDataDir);
+  }
+}
+
+/**
+ * Edge can keep running after its network service crashes during startup,
+ * leaving the probe page unable to POST. Retry only that observed transient
+ * startup failure; a separate profile and token keep late first-attempt
+ * reports from being mistaken for the retry's report.
+ */
+export async function captureReferenceReport(options) {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      return await captureReferenceAttempt({
+        ...options,
+        token:
+          attempt === 0 ? options.token : `${options.token}-retry-${attempt}`,
+      });
+    } catch (error) {
+      if (
+        attempt === 0 &&
+        error.message.startsWith('timed out waiting for report ') &&
+        error.message.includes(
+          'Network service crashed or was terminated, restarting service.'
+        )
+      ) {
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+const IGNORED_PATHS = [
+  // Window geometry depends on the window manager and on how each engine sizes
+  // the first window; it is user-configurable, not an automation artifact.
+  /^window\.(innerWidth|innerHeight|outerWidth|outerHeight|screenX|screenY|screenLeft|screenTop)$/u,
+  /^viewportRelation\./u,
+  /^document\.(referrer|hasFocus|bodyClientHeightIsPositive)$/u,
+  /^probeErrors\./u,
+  // NetworkInformation.downlink is a rolling bandwidth estimate: two captures
+  // from the same real browser disagree, so it carries no automation signal.
+  /^connection\.(downlink|rtt)$/u,
+];
+
+function isIgnored(pathString, extraIgnores) {
+  return (
+    IGNORED_PATHS.some((pattern) => pattern.test(pathString)) ||
+    extraIgnores.some((pattern) => pattern.test(pathString))
+  );
+}
+
+function isPlainRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Deep diff producing dotted paths, so failures name the exact leaked field. */
+export function diffReports(reference, candidate, { ignore = [] } = {}) {
+  const differences = [];
+
+  const walk = (left, right, trail) => {
+    if (isIgnored(trail, ignore)) {
+      return;
+    }
+    if (isPlainRecord(left) && isPlainRecord(right)) {
+      const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+      for (const key of [...keys].sort()) {
+        walk(left[key], right[key], trail ? `${trail}.${key}` : key);
+      }
+      return;
+    }
+    if (JSON.stringify(left) !== JSON.stringify(right)) {
+      differences.push({ path: trail, reference: left, candidate: right });
+    }
+  };
+
+  walk(reference, candidate, '');
+  return differences;
+}