browser-commander 0.17.2 → 0.18.0

package/.jscpd-baseline.json

@@ -14,7 +14,6 @@
     "0b48b63049c42591": 1,
     "0b8c71391c107a5e": 1,
     "0ba2d165b56db0b3": 1,
-    "0c8a29320e45bdfa": 1,
     "0ca2d9c2f2b44d6c": 1,
     "0caa402c4eae32d8": 1,
     "0fd23be8410c2c95": 1,
@@ -28,7 +27,6 @@
     "16340a16ed52849e": 1,
     "17c26c0db2d35ad1": 1,
     "193b46c0e7f72053": 1,
-    "1ac9fbd87efdb313": 1,
     "1ad4dc7e19a77f68": 1,
     "1c1baf1bc8ea0eae": 1,
     "1cbd39b416a2b94b": 1,
@@ -77,15 +75,12 @@
     "4c3b94caa28045d0": 1,
     "4e090d6bb30e6551": 1,
     "4f3c541b3f3e3f23": 1,
-    "4fe5663c69a426cb": 1,
-    "505d98bd14b63a6c": 1,
     "5085765e1f103f3e": 1,
     "5184c90c9f8406c3": 1,
     "520a28ee2ced56c2": 1,
     "53519ec61a6ba319": 1,
     "53f7e3f3e444a37d": 1,
     "5587ec0cdb7b96e6": 1,
-    "559b5241047cd753": 1,
     "562ebfb882d4aa8f": 1,
     "56b5df15ee61887d": 1,
     "56b7675e4ce57335": 1,
@@ -103,10 +98,10 @@
     "6098544c77ff17a2": 1,
     "60d0c58a01fc8746": 1,
     "61bcadcd8dc9f63e": 1,
-    "63a3b672c8d8b50b": 1,
     "63ff613b1780c67a": 1,
     "642cc89ed49f8a21": 1,
     "6479c3604c153ec4": 1,
+    "6699064d6e8e09ba": 1,
     "66fb97eebd7ff0dc": 1,
     "67a95e428b8fa31c": 1,
     "6880d620e0e67229": 1,
@@ -119,6 +114,7 @@
     "6fa62e2642cc73c3": 1,
     "7009c5e9bd61dbe8": 1,
     "709348ea44394b52": 1,
+    "72705e6a2212d7b2": 1,
     "731fbc5d4188839a": 1,
     "73dbf56d17ab79ed": 1,
     "760d9925f6e3ca85": 1,
@@ -141,28 +137,22 @@
     "8678919f1350f154": 1,
     "86aae81b1aa0d21b": 1,
     "87484a2744e09748": 1,
-    "87514cf1299c9c0e": 1,
     "876d2c8edfc8c40a": 1,
     "8b013ac20e436d76": 1,
     "8c2b1408886c1db1": 1,
-    "8cb9a984bf19a062": 1,
     "8ec18cdbd4a96518": 1,
-    "8ecf2e554a04d2ef": 1,
     "91049efadc65169b": 1,
     "9134185980de8a17": 1,
     "916833bafca4fa63": 1,
     "91a538e4a0c28f25": 1,
-    "929fba5228e9fdac": 1,
     "92ddafa7e65be7eb": 1,
     "94821a4d1b745dfd": 1,
-    "94d89888ac9da9a9": 1,
     "97c5a112fdde7be8": 1,
     "98cc22079feaa004": 1,
     "990d87f21678fa96": 1,
     "9a72b1c2f22156ca": 1,
     "9b6ef4df04562546": 1,
     "9c055dfd90c369bf": 1,
-    "9cb19f1b972e811e": 1,
     "9ee57dcd5e7a6691": 1,
     "9fbb8296259dedbe": 1,
     "a0183465782b0b15": 1,
@@ -175,7 +165,6 @@
     "a78d76908162699e": 1,
     "a9bd4ffef6da5faf": 1,
     "a9d71c2e50f1b832": 1,
-    "abe5a58f2b2cc593": 1,
     "acc95d694eb2f581": 1,
     "ad4469f2e8131535": 1,
     "ad4cfa76daa1b6fc": 1,
@@ -188,7 +177,6 @@
     "b2a0686231220c8a": 1,
     "b35ff46c365dcd18": 1,
     "b41581af204af40e": 1,
-    "b62f3449cde7991d": 1,
     "b71fa5250da28739": 1,
     "b740ecac685a15fe": 1,
     "b8c2d21f2a26f77d": 1,
@@ -209,6 +197,7 @@
     "c415ffcd004d6518": 1,
     "c461a83b51eb7740": 1,
     "c9cf3c28bed33a5b": 1,
+    "cab590a1d04b5a05": 1,
     "cbd444e9a6a9072e": 1,
     "cd49f39b43d14635": 1,
     "cebff7d1cc87f646": 1,
@@ -221,7 +210,6 @@
     "d1a4a8e6a523b752": 1,
     "d1e5c2961267399a": 1,
     "d2ed3d02dd6a2d8c": 1,
-    "d4eec99f58906a63": 1,
     "d6157a86fea41907": 1,
     "d6fa9884eee815f0": 1,
     "d86bafb915488255": 1,
@@ -239,7 +227,6 @@
     "ea1195048ded896c": 1,
     "ea88711c5deb1fe5": 1,
     "eb9a70c2a21094ff": 1,
-    "ebd08637a2d7bcf3": 1,
     "ebe03c5f8c2f5147": 1,
     "ee19c8b9b332ee98": 1,
     "eeca0ccf8d821f21": 1,
@@ -253,11 +240,11 @@
     "f4bfa7e503443cd1": 1,
     "f6678d6748e9c902": 1,
     "f67a07a611f39cb2": 1,
+    "f7b1f9d699bcd580": 1,
     "f911821aa7dda47f": 1,
     "f97bf515bfd95829": 1,
     "fae844842fba705b": 1,
     "faf76ec43b2dbbaa": 1,
-    "fb3a2e9ace145907": 1,
     "fc6ed7d760c98f51": 1,
     "fccfd8b004c12dd4": 1,
     "fe859df9f97c75d4": 1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.18.0
+
+### Minor Changes
+
+- 0915dd8: Add managed downloads, portable traces and truthful click results.
+
+  `downloads` is now accepted by `launchBrowser()`, `connectBrowser()` and
+  `launchRealBrowser()`, and by `commander.configureDownloads()` on a browser you
+  already have. The manager owns the file rather than the page: `capture()` starts
+  listening before the action runs so a fast download cannot be missed, a caller
+  can choose the saved name and have a bare UUID given the extension its content
+  proves, and the file is still there after the context and the browser are gone.
+  Failed and cancelled downloads report the failure instead of a path, and
+  `browser-commander/tests` keeps captured files in the run's artifact directory.
+
+  `startTrace()` records a session into a schema-versioned bundle - an ordered
+  NDJSON timeline, named checkpoints with full HTML, live control state and frame
+  metadata, and the DOM mutation batches between them - which `readTrace()`,
+  `diffControlState()` and the offline `writeTraceViewer()` read back with scripts
+  and network disabled. Redaction runs before anything is written, a truncated or
+  interrupted run still produces a readable partial trace, and
+  `browser-commander/tests` supports `trace: 'retain-on-failure'` in place of its
+  own artifact mechanism.
+
+  `clickElement()` now reports what was observed: `status` is `succeeded`,
+  `failed`, `timed_out`, `interrupted` or `unverified`, `effect` is `confirmed`,
+  `not-observed` or `contradicted`, and `evidence` carries the reason for both.
+  The `clicked` and `verified` booleans remain and are derived conservatively, so
+  a click that changed nothing is no longer reported as verified. `waitForReady()`
+  composes URL, network, DOM, image and custom checks under one deadline and
+  returns the same per-check evidence. `noAutoScroll` is deprecated in favour of
+  the `scroll` axis; `scroll: 'none'` now fails with a `ScrollConstraintError` on
+  engines that cannot click without scrolling instead of scrolling anyway.
+
 ## 0.17.2
 
 ### Patch Changes

package/README.md

@@ -599,6 +599,90 @@ await keyDown({ page, engine: 'playwright', key: 'Control' });
 await keyUp({ page, engine: 'playwright', key: 'Control' });
 ```
 
+### Managed Downloads
+
+A download that only exists while the browser is open is not a download. Ask for
+`downloads` at any entry point - `launchBrowser()`, `connectBrowser()`,
+`launchRealBrowser()` or `commander.configureDownloads()` - and the manager owns
+the file from then on:
+
+```javascript
+const { commander, downloads } = await launchBrowser({
+  downloads: { directory: '/tmp/reports', conflict: 'rename' },
+});
+
+// capture() starts listening before the action runs, so a download that
+// finishes in 5ms cannot slip past the registration.
+const artifact = await downloads.capture({
+  action: () => commander.clickButton({ selector: '#export' }),
+  filename: 'q3-report.pdf', // the page's UUID name gets the caller's name
+  timeout: 30000,
+});
+
+console.log(artifact.path, artifact.bytes, artifact.checksum);
+
+await commander.destroy();
+// The file is still there: it outlives the page, the context and the browser.
+```
+
+`downloads.on(DOWNLOAD_EVENT.COMPLETED, ...)` observes every download in the
+session, including one a person started by hand in a visible browser, and each
+download is reported exactly once whether it was captured or merely observed. A
+failed or cancelled download raises the failure rather than returning a path.
+
+### Portable Traces
+
+`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:
+
+```javascript
+import { startTrace, readTrace, writeTraceViewer } from 'browser-commander';
+
+const trace = await startTrace({
+  commander,
+  output: '/tmp/traces/checkout',
+  mode: 'continuous', // keeps DOM mutations between checkpoints
+  privacy: { redact: [/password/i, /token/i] },
+});
+
+await commander.goto({ url: 'https://example.com/checkout' });
+await trace.checkpoint('cart');
+await commander.clickButton({ selector: '#pay' });
+await trace.checkpoint('paid');
+
+const { path } = await trace.stop();
+const bundle = await readTrace(path);
+await writeTraceViewer(bundle, '/tmp/traces/checkout/viewer.html');
+```
+
+Redaction runs before anything reaches disk, and a run cut short by a closed
+page or a size limit still leaves a readable partial trace. The viewer seeks,
+diffs and replays the captured DOM with scripts and network disabled.
+
+### Truthful Click Results
+
+`clickElement()` reports what was observed, not what was attempted:
+
+```javascript
+const result = await clickElement({
+  page,
+  engine,
+  locatorOrElement: '#submit',
+});
+
+result.status; // 'succeeded' | 'failed' | 'timed_out' | 'interrupted' | 'unverified'
+result.effect; // 'confirmed' | 'not-observed' | 'contradicted'
+result.evidence; // why status and effect say what they say
+result.clicked; // still here: whether the click reached the element
+result.verified; // still here, now derived from effect === 'confirmed'
+```
+
+The `scroll` axis (`auto`, `preserve`, `none`) replaces the deprecated
+`noAutoScroll` flag. `scroll: 'none'` never scrolls: on an engine that cannot
+deliver a click without scrolling it throws `ScrollConstraintError` naming the
+alternatives, rather than scrolling the page and reporting success.
+
 ### commander.destroy()
 
 ```javascript

package/eslint.config.js

@@ -22,6 +22,7 @@ export default [
         __filename: 'readonly',
         // Node.js 18+ globals
         fetch: 'readonly',
+        performance: 'readonly',
         // Web/Node.js shared globals
         setTimeout: 'readonly',
         clearTimeout: 'readonly',
@@ -50,6 +51,10 @@ export default [
         // Chrome verbatim rather than executed by Node).
         document: 'readonly',
         window: 'readonly',
+        location: 'readonly',
+        MutationObserver: 'readonly',
+        DOMParser: 'readonly',
+        Node: 'readonly',
         navigator: 'readonly',
         Navigator: 'readonly',
         screen: 'readonly',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",
@@ -16,6 +16,9 @@
     "test:e2e:playwright": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/playwright.e2e.test.js",
     "test:e2e:puppeteer": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/puppeteer.e2e.test.js",
     "test:e2e:parity": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/fingerprint-parity.e2e.test.js",
+    "test:e2e:click-readiness": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/click-readiness.e2e.test.js",
+    "test:e2e:downloads": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/downloads.e2e.test.js",
+    "test:e2e:traces": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/traces.e2e.test.js",
     "test:all": "npm run test:unit && npm run test:e2e",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",

package/src/bindings.js

@@ -11,6 +11,7 @@ import {
   setContent,
   waitForNavigation,
   waitForPageReady,
+  waitForReady,
   waitAfterAction,
 } from './browser/navigation.js';
 import { emulateMedia } from './browser/media.js';
@@ -137,6 +138,15 @@ export function createBoundFunctions(options = {}) {
       log,
       wait: waitBound,
     });
+  const waitForReadyBound = (opts) =>
+    waitForReady({
+      ...opts,
+      page,
+      engine,
+      navigationManager,
+      networkTracker,
+      log,
+    });
   const waitAfterActionBound = (opts) =>
     waitAfterAction({
       ...opts,
@@ -199,7 +209,8 @@ export function createBoundFunctions(options = {}) {
     scrollIntoViewIfNeeded({ ...opts, page, engine, wait: waitBound, log });
 
   // Bound click - now navigation-aware
-  const clickElementBound = (opts) => clickElement({ ...opts, engine, log });
+  const clickElementBound = (opts) =>
+    clickElement({ ...opts, page, engine, log });
   const clickButtonBound = (opts) =>
     clickButton({
       ...opts,
@@ -323,6 +334,7 @@ export function createBoundFunctions(options = {}) {
     getUrl: getUrlBound,
     waitForNavigation: waitForNavigationBound,
     waitForPageReady: waitForPageReadyBound,
+    waitForReady: waitForReadyBound,
     waitAfterAction: waitAfterActionBound,
     getAttribute: getAttributeWrapped,
     isVisible: isVisibleWrapped,

package/src/browser/connector.js

@@ -1,3 +1,4 @@
+import { attachDownloads } from '../downloads/attach.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
@@ -109,7 +110,8 @@ async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
  * @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
+ * @param {boolean|Object} [options.downloads] - Manage downloads: true for defaults, or {directory, persist, conflict}
+ * @returns {Promise<{browser: Object, page: Object, downloads: Object|null}>} Raw handles and the download manager when one was requested
  */
 export async function connectBrowser(options = {}) {
   return await connectBrowserWithDependencies(options);
@@ -120,7 +122,7 @@ export async function connectBrowser(options = {}) {
  *
  * @param {Object} options - See {@link connectBrowser}
  * @param {Object} dependencies - Optional engine module loaders
- * @returns {Promise<{browser: Object, page: Object}>} Raw browser and page handles
+ * @returns {Promise<{browser: Object, page: Object, downloads: Object|null}>} Raw handles and the download manager when one was requested
  */
 export async function connectBrowserWithDependencies(
   options = {},
@@ -157,7 +159,17 @@ export async function connectBrowserWithDependencies(
   if (verbose) {
     console.log(`Connected to browser with ${engine} engine`);
   }
-  return result;
+
+  // 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,
+  });
+
+  return { ...result, downloads };
 }
 
 export { buildPlaywrightConnectOptions, buildPuppeteerConnectOptions };

package/src/browser/launcher.js

@@ -8,6 +8,7 @@ import {
   resolveChromeArgs,
 } from './launch-options.js';
 import { applyFingerprint } from '../fingerprint/apply.js';
+import { attachDownloads } from '../downloads/attach.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
@@ -31,7 +32,8 @@ import {
  * @param {string|Object} [options.storageState] - Playwright-compatible storage state path or object
  * @param {Object} [options.fingerprint] - Environment fields to present to pages, such as userAgent, timezone, locale, hardwareConcurrency or screen. Applied over CDP after launch; see src/fingerprint/profile.js for the full field list and presets.js for ready-made profiles.
  * @param {boolean} [options.automationParity=true] - Keep the command line indistinguishable from a hand-started Chrome. Turning this off restores the pre-parity switches and makes navigator.webdriver true.
- * @returns {Promise<Object>} - Object with browser and page
+ * @param {boolean|Object} [options.downloads] - Manage downloads: true for defaults, or {directory, persist, conflict}. The directory may be an absolute path, 'user-downloads' or 'temporary'.
+ * @returns {Promise<{browser: Object, page: Object, downloads: Object|null}>} - Browser, page and the download manager when one was requested
  */
 export async function launchBrowser(options = {}) {
   const {
@@ -49,6 +51,7 @@ export async function launchBrowser(options = {}) {
     storageState,
     fingerprint,
     automationParity = true,
+    downloads,
   } = options;
 
   const resolvedChromeArgs = resolveChromeArgs({
@@ -169,5 +172,14 @@ export async function launchBrowser(options = {}) {
     }
   }
 
-  return { browser, page };
+  // Downloads are armed before the caller can navigate: a download triggered
+  // by the first page load still lands in the managed directory.
+  const downloadManager = await attachDownloads({
+    engine,
+    browser,
+    page,
+    downloads,
+  });
+
+  return { browser, page, downloads: downloadManager };
 }

package/src/browser/navigation.js

@@ -8,6 +8,13 @@
 import { TIMING } from '../core/constants.js';
 import { isNavigationError } from '../core/navigation-safety.js';
 import { isActionStoppedError } from '../core/page-trigger-manager.js';
+import {
+  READINESS_STATUS,
+  createDeadline,
+  networkIdleFor,
+  runReadinessChecks,
+  urlStableFor,
+} from '../core/readiness.js';
 
 /**
  * Default verification function for navigation operations.
@@ -492,6 +499,62 @@ export async function waitForPageReady(options = {}) {
   return true;
 }
 
+/**
+ * Wait for the page to be ready and return structured evidence.
+ *
+ * Unlike {@link waitForPageReady}, which answers with a single boolean, this
+ * reports which checks passed, which failed, which were skipped and which never
+ * got to run before the shared deadline expired.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Browser page object
+ * @param {string} [options.engine] - Engine type
+ * @param {Object} [options.navigationManager] - NavigationManager instance
+ * @param {Object} [options.networkTracker] - NetworkTracker instance
+ * @param {Function} [options.log] - Logger instance
+ * @param {number} [options.timeout=30000] - Total budget in milliseconds
+ * @param {string} [options.reason='page ready'] - Reason for waiting
+ * @param {Array} [options.checks] - Composable readiness checks
+ * @returns {Promise<Object>} Structured readiness result
+ */
+export async function waitForReady(options = {}) {
+  const {
+    page,
+    engine,
+    navigationManager,
+    networkTracker,
+    log = { debug: () => {} },
+    timeout = 30000,
+    reason = 'page ready',
+    checks,
+  } = options;
+
+  if (navigationManager?.waitForReady) {
+    return navigationManager.waitForReady({ timeout, reason, checks });
+  }
+
+  const deadline = createDeadline({ timeout });
+  const result = await runReadinessChecks({
+    checks: checks ?? [urlStableFor(), networkIdleFor()],
+    deadline,
+    context: {
+      page,
+      engine,
+      log,
+      networkTracker,
+      getAdapter: async () => {
+        const { createEngineAdapter } =
+          await import('../core/engine-adapter.js');
+        return createEngineAdapter(page, engine);
+      },
+    },
+  });
+
+  return { ...result, reason, url: page?.url?.() ?? null };
+}
+
+export { READINESS_STATUS };
+
 /**
  * Wait for any ongoing navigation and network requests to complete.
  * Use this after actions that might trigger navigation (like clicks).

package/src/core/dialog-manager.js

@@ -28,6 +28,12 @@ export function createDialogManager(options = {}) {
   // User-registered dialog handlers
   const handlers = [];
 
+  // Passive observers. They are told about every dialog and are never
+  // responsible for answering one, so watching dialogs - which is what a
+  // trace recorder does - cannot leave a page waiting forever for an answer
+  // nobody was going to give.
+  const observers = [];
+
   // Whether we are currently listening to the page's dialog event
   let isListening = false;
 
@@ -45,6 +51,14 @@ export function createDialogManager(options = {}) {
 
     log.debug(() => `💬 Dialog event: type="${type}", message="${message}"`);
 
+    for (const observer of observers) {
+      try {
+        await observer(dialog);
+      } catch (e) {
+        log.debug(() => `⚠️  Error in dialog observer: ${e.message}`);
+      }
+    }
+
     if (handlers.length === 0) {
       log.debug(
         () =>
@@ -121,6 +135,36 @@ export function createDialogManager(options = {}) {
     log.debug(() => '🔌 All dialog handlers cleared');
   }
 
+  /**
+   * Watch dialogs without taking responsibility for answering them
+   * @param {Function} observer - Async function receiving the dialog object
+   * @returns {Function} - Removes this observer again
+   */
+  function observeDialogs(observer) {
+    if (typeof observer !== 'function') {
+      throw new Error('Dialog observer must be a function');
+    }
+    observers.push(observer);
+    log.debug(
+      () => `👁  Dialog observer registered (total: ${observers.length})`
+    );
+    return () => unobserveDialogs(observer);
+  }
+
+  /**
+   * Remove a dialog observer
+   * @param {Function} observer - The observer to remove
+   */
+  function unobserveDialogs(observer) {
+    const index = observers.indexOf(observer);
+    if (index !== -1) {
+      observers.splice(index, 1);
+      log.debug(
+        () => `👁  Dialog observer removed (remaining: ${observers.length})`
+      );
+    }
+  }
+
   /**
    * Start listening for dialog events on the page
    */
@@ -151,6 +195,10 @@ export function createDialogManager(options = {}) {
     offDialog,
     clearDialogHandlers,
 
+    // Passive observation (issue #87)
+    observeDialogs,
+    unobserveDialogs,
+
     // Lifecycle
     startListening,
     stopListening,