browser-commander 0.27.0 → 0.29.0

package/src/elements/selectors.js

@@ -1,5 +1,9 @@
-import { isNavigationError } from '../core/navigation-safety.js';
-import { createPlaywrightLocator } from './locators.js';
+import {
+  isNavigationError,
+  waitNavigationState,
+  recoverWaitError,
+} from '../core/navigation-safety.js';
+import { createPlaywrightLocator, requireSelector } from './locators.js';
 
 /**
  * Query single element
@@ -9,67 +13,38 @@ import { createPlaywrightLocator } from './locators.js';
  * @param {string} options.selector - CSS selector
  * @returns {Promise<Object|null>} - Element handle or null
  */
-export async function querySelector(options = {}) {
-  const { page, engine, selector } = options;
-
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+export function querySelector(options = {}) {
+  return queryElements(options, true);
+}
 
-  try {
-    if (engine === 'playwright') {
-      const locator = createPlaywrightLocator({ page, selector }).first();
-      const count = await locator.count();
-      return count > 0 ? locator : null;
-    } else {
-      return await page.$(selector);
-    }
-  } catch (error) {
-    if (isNavigationError(error)) {
-      console.log(
-        '⚠️  Navigation detected during querySelector, returning null'
-      );
-      return null;
-    }
-    throw error;
-  }
+/** Return every matching element with the same navigation recovery as querySelector. */
+export function querySelectorAll(options = {}) {
+  return queryElements(options, false);
 }
 
-/**
- * Query all elements
- * @param {Object} options - Configuration options
- * @param {Object} options.page - Browser page object
- * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
- * @param {string} options.selector - CSS selector
- * @returns {Promise<Array>} - Array of element handles
- */
-export async function querySelectorAll(options = {}) {
+async function queryElements(options, single) {
+  requireSelector(options.selector);
   const { page, engine, selector } = options;
-
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
-
   try {
-    if (engine === 'playwright') {
-      const locator = createPlaywrightLocator({ page, selector });
-      const count = await locator.count();
-      const elements = [];
-      for (let i = 0; i < count; i++) {
-        elements.push(locator.nth(i));
-      }
-      return elements;
-    } else {
-      return await page.$$(selector);
+    if (engine !== 'playwright') {
+      return single ? await page.$(selector) : await page.$$(selector);
     }
+    const matching = createPlaywrightLocator({ page, selector });
+    const locator = single ? matching.first() : matching;
+    const total = await locator.count();
+    return single
+      ? total > 0
+        ? locator
+        : null
+      : Array.from({ length: total }, (_, index) => locator.nth(index));
   } catch (error) {
-    if (isNavigationError(error)) {
-      console.log(
-        '⚠️  Navigation detected during querySelectorAll, returning empty array'
-      );
-      return [];
+    if (!isNavigationError(error)) {
+      throw error;
     }
-    throw error;
+    console.log(
+      `⚠️  Navigation detected during ${single ? 'querySelector' : 'querySelectorAll'}, recovering gracefully`
+    );
+    return single ? null : [];
   }
 }
 
@@ -175,9 +150,7 @@ function parsePlaywrightTextSelector(selector) {
 export async function normalizeSelector(options = {}) {
   const { page, engine, selector } = options;
 
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(selector);
 
   // DEFENSIVE: Validate selector type - must be string or Puppeteer text selector object
   // Arrays and other invalid types should be rejected to prevent downstream querySelectorAll errors
@@ -360,19 +333,11 @@ export function withTextSelectorSupport(fn, engine, page) {
  * @returns {Promise<boolean>} - True if selector found, false on navigation
  */
 export async function waitForSelector(options = {}) {
-  const {
-    page,
-    engine,
-    selector,
-    visible = true,
-    timeout = 5000,
-    throwOnNavigation = true,
-  } = options;
-
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  const { page, engine, selector, visible = true, timeout = 5000 } = options;
+
+  requireSelector(selector);
 
+  const initial = waitNavigationState(page, options.navigationManager);
   try {
     if (engine === 'playwright') {
       const locator = createPlaywrightLocator({ page, selector });
@@ -384,16 +349,7 @@ export async function waitForSelector(options = {}) {
       await page.waitForSelector(selector, { visible, timeout });
     }
     return true;
-  } catch (error) {
-    if (isNavigationError(error)) {
-      console.log(
-        '⚠️  Navigation detected during waitForSelector, recovering gracefully'
-      );
-      if (throwOnNavigation) {
-        throw error;
-      }
-      return false;
-    }
-    throw error;
+  } catch (caught) {
+    return recoverWaitError(caught, options, initial, 'waitForSelector', false);
   }
 }

package/src/elements/visibility.js

@@ -1,6 +1,6 @@
 import { TIMING } from '../core/constants.js';
 import { isNavigationError } from '../core/navigation-safety.js';
-import { getLocatorOrElement } from './locators.js';
+import { getLocatorOrElement, requireSelector } from './locators.js';
 
 /**
  * Check if element is visible
@@ -13,9 +13,7 @@ import { getLocatorOrElement } from './locators.js';
 export async function isVisible(options = {}) {
   const { page, engine, selector } = options;
 
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(selector);
 
   try {
     if (engine === 'playwright') {
@@ -62,9 +60,7 @@ export async function isVisible(options = {}) {
 export async function isEnabled(options = {}) {
   const { page, engine, selector, disabledClasses = ['disabled'] } = options;
 
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(selector);
 
   try {
     if (engine === 'playwright') {
@@ -119,9 +115,7 @@ export async function isEnabled(options = {}) {
 export async function count(options = {}) {
   const { page, engine, selector } = options;
 
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(selector);
 
   try {
     // Handle Puppeteer text selectors
@@ -150,9 +144,37 @@ export async function count(options = {}) {
     }
 
     if (engine === 'playwright') {
+      if (options.visible) {
+        return await page
+          .locator(selector)
+          .evaluateAll(
+            (elements) =>
+              elements.filter(
+                (element) =>
+                  element.getClientRects().length > 0 &&
+                  element.checkVisibility({ visibilityProperty: true })
+              ).length
+          );
+      }
       return await page.locator(selector).count();
     } else {
       const elements = await page.$$(selector);
+      if (options.visible) {
+        let visible = 0;
+        for (const element of elements) {
+          if (
+            await page.evaluate(
+              (element) =>
+                element.getClientRects().length > 0 &&
+                element.checkVisibility({ visibilityProperty: true }),
+              element
+            )
+          ) {
+            visible += 1;
+          }
+        }
+        return visible;
+      }
       return elements.length;
     }
   } catch (error) {

package/src/factory.js

@@ -22,7 +22,7 @@ import {
 } from './core/page-trigger-manager.js';
 import { createBoundFunctions } from './bindings.js';
 import { attachDownloads } from './downloads/attach.js';
-import { startTrace } from './traces/recorder.js';
+import { attachCommanderFeatures } from './core/commander-features.js';
 import { createCdpSession } from './browser/cdp-session.js';
 
 /**
@@ -66,7 +66,7 @@ export function makeBrowserCommander(options = {}) {
       page,
       engine,
       log,
-      idleTimeout: 30000, // Wait 30 seconds without requests before considering network idle
+      idleTimeout: options.networkIdleForMs ?? 30000, // Wait 30 seconds without requests before considering network idle
     });
     networkTracker.startTracking();
   }
@@ -92,6 +92,7 @@ export function makeBrowserCommander(options = {}) {
       log,
       networkTracker,
     });
+    navigationManager.configure(navigationOptions(options));
     navigationManager.startListening();
 
     // Create PageSession factory
@@ -159,7 +160,6 @@ export function makeBrowserCommander(options = {}) {
 
     // All bound functions
     ...boundFunctions,
-
     // Managed downloads (issue #88). Present once a manager is attached,
     // either by passing the one launchBrowser() returned or by calling
     // configureDownloads() on an existing commander.
@@ -192,15 +192,6 @@ export function makeBrowserCommander(options = {}) {
      */
     createCdpSession: () => createCdpSession(page, { engine }),
 
-    /**
-     * Start recording a privacy-aware trace of this session (issue #87).
-     *
-     * @param {Object} [traceOptions] - {output, mode, screenshots, dom, events, privacy, limits}
-     * @returns {Promise<Object>} The running trace: {checkpoint, event, stop}
-     */
-    startTrace: (traceOptions = {}) =>
-      startTrace({ commander, page, log, ...traceOptions }),
-
     // Lifecycle
     destroy,
 
@@ -295,5 +286,15 @@ export function makeBrowserCommander(options = {}) {
     pageTriggerManager.initialize(commander);
   }
 
+  attachCommanderFeatures(commander, options, makeBrowserCommander);
   return commander;
 }
+
+function navigationOptions(options) {
+  return {
+    ...(options.navigationManager ?? {}),
+    ...(options.networkIdleTimeout === undefined
+      ? {}
+      : { networkIdleTimeout: options.networkIdleTimeout }),
+  };
+}

package/src/index.js

@@ -18,3 +18,7 @@ export {
 
 // Re-export all public APIs from exports module
 export * from './exports.js';
+export * from './capture/index.js';
+export { connectOrLaunch } from './browser/persistent-session.js';
+
+export { renderTrace, summarizeTrace } from './traces/render.js';

package/src/interactions/click.js

@@ -31,6 +31,25 @@ function isInterrupted(error) {
   return isNavigationError(error) || isActionStoppedError(error);
 }
 
+function waitInterruptedByNavigation({
+  error,
+  page,
+  navigationManager,
+  startUrl,
+  startSessionId,
+  preparationFinished,
+}) {
+  const timedOut =
+    error.name === 'TimeoutError' ||
+    error.name === 'NavigationInterruptedError' ||
+    /timeout|timed out/i.test(error.message);
+  const navigationChanged =
+    page.url() !== startUrl ||
+    (startSessionId !== undefined &&
+      navigationManager?.getSessionId?.() !== startSessionId);
+  return timedOut && navigationChanged && !preparationFinished;
+}
+
 /**
  * Read the target element's observable state under the click's own budget.
  *
@@ -975,6 +994,7 @@ export async function clickButton(options = {}) {
 
   const startUrl = page.url();
   const startSessionId = navigationManager?.getSessionId?.();
+  let preparationFinished = false;
 
   try {
     const prepareResult = await prepareElement({
@@ -1012,6 +1032,7 @@ export async function clickButton(options = {}) {
       });
     }
 
+    preparationFinished = true;
     const clickResult = await clickElement({
       page,
       engine,
@@ -1055,6 +1076,29 @@ export async function clickButton(options = {}) {
       actionId,
     });
   } catch (error) {
+    if (
+      waitInterruptedByNavigation({
+        error,
+        page,
+        navigationManager,
+        startUrl,
+        startSessionId,
+        preparationFinished,
+      })
+    ) {
+      return makeClickResult({
+        status: CLICK_STATUS.INTERRUPTED,
+        dispatched: false,
+        effect: CLICK_EFFECT.NOT_OBSERVED,
+        navigated: true,
+        reason: 'navigation interrupted the element wait before the click',
+        evidence: [
+          evidence('interrupted', { message: error.message, phase: 'prepare' }),
+        ],
+        elapsedMs: elapsed(),
+        actionId,
+      });
+    }
     if (isInterrupted(error)) {
       log.debug(
         () =>

package/src/interactions/overlays.js

@@ -0,0 +1,73 @@
+import { withDeadline } from '../traces/deadline.js';
+import { isVisible } from '../elements/visibility.js';
+
+async function dismissVisible({ page, engine, selector, timeout = 1000 }) {
+  if (engine === 'playwright') {
+    const matches = page.locator(selector);
+    for (let index = 0; index < (await matches.count()); index++) {
+      const target = matches.nth(index);
+      if (await target.isVisible()) {
+        await target.click({ timeout });
+        return 'dismissed';
+      }
+    }
+    return 'absent';
+  }
+  const matches = await page.$$(selector);
+  try {
+    for (const target of matches) {
+      if (await isVisible({ page, engine, selector: target })) {
+        await target.click({ timeout });
+        return 'dismissed';
+      }
+    }
+    return 'absent';
+  } finally {
+    await Promise.allSettled(
+      matches.map(async (target) => await target.dispose?.())
+    );
+  }
+}
+
+/** Dismiss caller-named overlays; a failed dismissal never blocks an action. */
+export async function dismissOverlays({
+  page,
+  engine,
+  overlays = [],
+  onDismiss,
+}) {
+  if (!Array.isArray(overlays)) {
+    throw new TypeError('overlays must be an array');
+  }
+  const reports = [];
+  for (const item of overlays) {
+    const options = typeof item === 'string' ? { selector: item } : item;
+    if (!options?.selector) {
+      throw new TypeError('overlay requires selector');
+    }
+    const report = { selector: options.selector, status: 'absent' };
+    try {
+      report.status = await withDeadline(
+        dismissVisible({ page, engine, ...options }),
+        options.timeout || 1000,
+        `overlay ${options.selector}`
+      );
+    } catch (error) {
+      report.status = 'error';
+      report.error = error;
+    }
+    reports.push(report);
+    for (const callback of [options.onDismiss, onDismiss]) {
+      try {
+        await withDeadline(
+          Promise.resolve(callback?.(report)),
+          options.timeout || 1000,
+          'overlay report'
+        );
+      } catch {
+        // Reporting must not interrupt the caller's requested interaction.
+      }
+    }
+  }
+  return reports;
+}

package/src/traces/bundle.js

@@ -43,6 +43,7 @@ export async function openTraceBundle(options = {}) {
     now = () => Date.now(),
     monotonic = () => performance.now(),
     onEvent = null,
+    nextSequence = null,
   } = options;
 
   if (typeof output !== 'string' || output === '') {
@@ -70,6 +71,9 @@ export async function openTraceBundle(options = {}) {
   let dropped = 0;
   const counts = { checkpoints: 0, events: 0, mutationBatches: 0 };
   const problems = [];
+  let mutationIndex = null;
+  let mutationBytes = 0;
+  let mutationTruncated = false;
 
   /** Close the timeline exactly once, after every queued append. */
   function closeEvents() {
@@ -117,11 +121,13 @@ export async function openTraceBundle(options = {}) {
    * @returns {Promise<Object|null>} The event as written
    */
   async function appendEvent(event, { retry = true } = {}) {
+    const number = nextSequence?.() ?? ++sequence;
     const record = {
-      sequence: ++sequence,
+      sequence: number,
       at: new Date(now()).toISOString(),
       monotonicMs: Math.round(monotonic()),
       ...event,
+      ...(nextSequence ? { sequence: number } : {}),
     };
     const line = `${JSON.stringify(record)}\n`;
     const bytes = Buffer.byteLength(line);
@@ -181,10 +187,17 @@ export async function openTraceBundle(options = {}) {
    * @param {string|Buffer} contents - What to write
    * @returns {Promise<Object|null>} `{member, bytes}` or null when dropped
    */
-  async function writeMember(member, contents) {
+  async function writeMember(member, contents, { append = false } = {}) {
     const data = Buffer.isBuffer(contents) ? contents : Buffer.from(contents);
+    const target = path.join(root, member);
+    const previous = append
+      ? await fs.stat(target).then(
+          (value) => value.size,
+          () => 0
+        )
+      : 0;
 
-    if (!fits(data.length)) {
+    if (!fits(data.length) || previous + data.length > maxResourceBytes) {
       await drop({
         reason: TRACE_DROP_REASON.SIZE_LIMIT,
         member,
@@ -193,13 +206,15 @@ export async function openTraceBundle(options = {}) {
       return null;
     }
 
-    const target = path.join(root, member);
     try {
       await fs.mkdir(path.dirname(target), {
         recursive: true,
         mode: TRACE_DIRECTORY_MODE,
       });
-      await fs.writeFile(target, data, { mode: TRACE_FILE_MODE });
+      await fs.writeFile(target, data, {
+        mode: TRACE_FILE_MODE,
+        flag: append ? 'a' : 'w',
+      });
       written += data.length;
       return { member, bytes: data.length };
     } catch (error) {
@@ -266,10 +281,39 @@ export async function openTraceBundle(options = {}) {
       return null;
     }
     const member = `${TRACE_FILES.MUTATIONS_DIR}/${sequenceName(index)}.ndjson`;
-    const body = `${batches.map((batch) => JSON.stringify(batch)).join('\n')}\n`;
-    const result = await writeMember(member, body);
+    if (mutationIndex !== index) {
+      mutationIndex = index;
+      mutationBytes = 0;
+      mutationTruncated = false;
+    }
+    if (mutationTruncated) {
+      return null;
+    }
+    const ceiling = Math.min(
+      limits.maxMutationBytes ?? 4 * 1024 * 1024,
+      maxResourceBytes
+    );
+    const lines = [];
+    for (const batch of batches) {
+      const line = `${JSON.stringify(batch)}\n`;
+      if (mutationBytes + Buffer.byteLength(line) + 256 > ceiling) {
+        mutationTruncated = true;
+        const marker = `${JSON.stringify({ records: [{ kind: 'truncated', reason: 'mutation interval size limit' }] })}\n`;
+        if (mutationBytes + Buffer.byteLength(marker) <= ceiling) {
+          lines.push(marker);
+        }
+        break;
+      }
+      lines.push(line);
+      mutationBytes += Buffer.byteLength(line);
+    }
+    if (!lines.length) {
+      return null;
+    }
+    const body = lines.join('');
+    const result = await writeMember(member, body, { append: true });
     if (result) {
-      counts.mutationBatches += batches.length;
+      counts.mutationBatches += lines.length;
     }
     return result ? result.member : null;
   }
@@ -310,6 +354,9 @@ export async function openTraceBundle(options = {}) {
     get bytesWritten() {
       return written;
     },
+    get mutationTruncated() {
+      return mutationTruncated;
+    },
     appendEvent,
     writeMember,
     writeCheckpoint,

package/src/traces/checkpoints.js

@@ -0,0 +1,103 @@
+import { captureSnapshotInPage } from './page-capture.js';
+import { withDeadline } from './deadline.js';
+import { redactText, redactValue, redactUrl, REDACTED } from './redaction.js';
+import { TRACE_EVENT, TRACE_DROP_REASON } from './schema.js';
+export function createCheckpointRecorder({
+  isStopped,
+  captureState,
+  mutations,
+  evaluateInPage,
+  privacyOptions,
+  domOptions,
+  links,
+  limits,
+  captureTimeoutMs,
+  bundle,
+  screenshot,
+  checkpoints,
+  record,
+}) {
+  /**
+   * Capture a named checkpoint.
+   *
+   * @param {string} name - What this moment is
+   * @param {Object} [checkpointOptions] - `{actor, reason, screenshots}`
+   * @returns {Promise<Object|null>} `{index, name, members}`
+   */
+  async function checkpoint(name, checkpointOptions = {}) {
+    if (isStopped()) {
+      throw new Error('this trace has already been stopped');
+    }
+
+    const { actor = 'automation', reason = 'checkpoint' } = checkpointOptions;
+    const index = ++captureState.index;
+
+    // Mutations are drained first so the batches belong to the interval that
+    // ended here, not to the one that starts now.
+    await mutations.drain(index - 1 > 0 ? index - 1 : 0);
+
+    let captured = null;
+    try {
+      captured = await withDeadline(
+        evaluateInPage(captureSnapshotInPage, {
+          redactSelectors: privacyOptions.redactSelectors,
+          redactAttributes: privacyOptions.redactAttributes,
+          useDefaults: privacyOptions.useDefaults,
+          redacted: REDACTED,
+          html: domOptions.html,
+          liveControlState: domOptions.liveControlState,
+          openShadowRoots: domOptions.openShadowRoots,
+          ignoreSelectors: domOptions.ignoreSelectors ?? [],
+          captureText: links?.dom === 'text',
+          maxHtmlBytes: limits.maxHtmlBytes ?? 4 * 1024 * 1024,
+        }),
+        captureTimeoutMs,
+        'trace checkpoint capture'
+      );
+    } catch (error) {
+      await bundle.drop({
+        reason: /closed/i.test(error.message)
+          ? TRACE_DROP_REASON.PAGE_CLOSED
+          : TRACE_DROP_REASON.CAPTURE_FAILED,
+        member: `checkpoints/${index}`,
+        detail: error.message,
+      });
+    }
+
+    const shot = await screenshot(reason);
+    const state = captured?.state
+      ? redactValue(captured.state, privacyOptions)
+      : null;
+
+    const members = await bundle.writeCheckpoint({
+      index,
+      html: redactText(captured?.html, privacyOptions, {
+        kind: 'dom',
+        name: 'html',
+      }),
+      state: state ? { ...state, name, actor, reason } : undefined,
+      screenshot: shot ?? undefined,
+    });
+
+    const entry = {
+      index,
+      name,
+      actor,
+      reason,
+      url: state ? redactUrl(state.url, privacyOptions) : null,
+      truncated: Boolean(captured?.truncated),
+      members,
+    };
+    checkpoints.push(entry);
+    await record(TRACE_EVENT.CHECKPOINT, entry);
+
+    // The init script covers every document created from here on; this covers
+    // a frame that was attached without one, which is cheap because installing
+    // over a recorder that is already observing does nothing.
+    await mutations.install();
+
+    return entry;
+  }
+
+  return checkpoint;
+}