browser-commander 0.27.0 → 0.28.0

package/src/core/page-trigger-manager.js

@@ -170,7 +170,8 @@ export function createPageTriggerManager(options = {}) {
   }
 
   // Registered triggers
-  const triggers = [];
+  const triggers = [],
+    subscriptions = [];
 
   // Current action state
   let currentTrigger = null;
@@ -178,8 +179,9 @@ export function createPageTriggerManager(options = {}) {
   let actionPromise = null;
   let actionStopPromise = null;
   let actionStopResolve = null;
-  let isActionRunning = false;
-  let isStopping = false;
+  let isActionRunning = false,
+    isStopping = false;
+  let startQueue = Promise.resolve();
 
   /**
    * Register a page trigger
@@ -191,7 +193,24 @@ export function createPageTriggerManager(options = {}) {
    * @returns {Function} - Unregister function
    */
   function pageTrigger(config) {
-    const { condition, action, name = 'unnamed', priority = 0 } = config;
+    const {
+      condition,
+      action,
+      name = 'unnamed',
+      priority = 0,
+      readyOn = 'networkidle',
+      concurrency = 'skip',
+    } = config;
+    if (
+      !['urlchange', 'domcontentloaded', 'load', 'networkidle'].includes(
+        readyOn
+      )
+    ) {
+      throw new RangeError(`Unknown trigger readyOn: ${readyOn}`);
+    }
+    if (!['skip', 'restart'].includes(concurrency)) {
+      throw new RangeError(`Unknown trigger concurrency: ${concurrency}`);
+    }
 
     if (typeof condition !== 'function') {
       throw new Error('condition must be a function');
@@ -205,6 +224,8 @@ export function createPageTriggerManager(options = {}) {
       action,
       name,
       priority,
+      readyOn,
+      concurrency,
     };
 
     triggers.push(triggerConfig);
@@ -234,7 +255,7 @@ export function createPageTriggerManager(options = {}) {
   function findMatchingTrigger(ctx) {
     for (const config of triggers) {
       try {
-        if (config.condition(ctx)) {
+        if (config.readyOn === ctx.readyOn && config.condition(ctx)) {
           return config;
         }
       } catch (e) {
@@ -278,8 +299,9 @@ export function createPageTriggerManager(options = {}) {
 
     // Wait for action to finish (with timeout)
     const timeoutMs = 10000; // 10 second max wait
+    let stopTimer;
     const timeoutPromise = new Promise((resolve) => {
-      setTimeout(() => {
+      stopTimer = setTimeout(() => {
         log.debug(
           () =>
             `⚠️  Action "${currentTrigger?.name}" did not stop gracefully within ${timeoutMs}ms`
@@ -289,6 +311,16 @@ export function createPageTriggerManager(options = {}) {
     });
 
     await Promise.race([actionPromise, timeoutPromise]);
+    clearTimeout(stopTimer);
+    // An action can ignore cancellation. Keep it in flight until it settles,
+    // so a second form handler can never race it after the grace period.
+    if (isActionRunning) {
+      isStopping = false;
+      actionStopResolve?.();
+      actionStopPromise = null;
+      actionStopResolve = null;
+      return;
+    }
 
     // Cleanup
     isActionRunning = false;
@@ -312,11 +344,12 @@ export function createPageTriggerManager(options = {}) {
    * @param {string} url - URL to start action for
    * @param {Object} commander - BrowserCommander instance
    */
-  function startAction(url, commander) {
+  function startAction(url, commander, readyOn = 'networkidle') {
     // Create context for condition checking
     const conditionCtx = {
       url,
       commander,
+      readyOn,
     };
 
     // Find matching trigger
@@ -325,6 +358,16 @@ export function createPageTriggerManager(options = {}) {
       log.debug(() => `📋 No trigger registered for: ${url}`);
       return Promise.resolve();
     }
+    if (isActionRunning) {
+      if (matchingTrigger.concurrency === 'skip') {
+        return Promise.resolve();
+      }
+      return stopCurrentAction().then(() => {
+        if (!isActionRunning) {
+          return startAction(url, commander, readyOn);
+        }
+      });
+    }
 
     log.debug(() => `🚀 Starting action "${matchingTrigger.name}" for: ${url}`);
 
@@ -510,36 +553,32 @@ export function createPageTriggerManager(options = {}) {
   /**
    * Handle page ready - start matching action
    */
-  async function onPageReady({ url }, commander) {
-    await startAction(url, commander);
-  }
-
   /**
    * Check if an action is currently running
    */
-  function isRunning() {
-    return isActionRunning;
-  }
+  const isRunning = () => isActionRunning;
 
   /**
    * Get current trigger name
    */
-  function getCurrentTriggerName() {
-    return currentTrigger?.name || null;
-  }
+  const getCurrentTriggerName = () => currentTrigger?.name || null;
 
   /**
    * Initialize - connect to navigation manager
    * @param {Object} commander - BrowserCommander instance
    */
   function initialize(commander) {
-    // Stop action before navigation starts
-    navigationManager.on('onBeforeNavigate', onNavigationStart);
-
-    // Start action when page is ready
-    navigationManager.on('onPageReady', (event) =>
-      onPageReady(event, commander)
-    );
+    subscribeReadiness({
+      commander,
+      navigationManager,
+      subscriptions,
+      onNavigationStart,
+      enqueue: (url, readyOn) => {
+        startQueue = startQueue.then(() =>
+          startAction(url, commander, readyOn)
+        );
+      },
+    });
 
     log.debug(() => '📋 PageTriggerManager initialized');
   }
@@ -547,12 +586,13 @@ export function createPageTriggerManager(options = {}) {
   /**
    * Cleanup
    */
-  async function destroy() {
-    await stopCurrentAction();
-    triggers.length = 0;
-    navigationManager.off('onBeforeNavigate', onNavigationStart);
-    log.debug(() => '📋 PageTriggerManager destroyed');
-  }
+  const destroy = createTriggerDestroy({
+    subscriptions,
+    getQueue: () => startQueue,
+    stopCurrentAction,
+    triggers,
+    log,
+  });
 
   return {
     pageTrigger,
@@ -567,3 +607,48 @@ export function createPageTriggerManager(options = {}) {
     isActionStoppedError,
   };
 }
+
+function subscribeReadiness({
+  commander,
+  navigationManager,
+  subscriptions,
+  onNavigationStart,
+  enqueue,
+}) {
+  function subscribe(source, event, listener) {
+    source?.on?.(event, listener);
+    subscriptions.push(() => source?.off?.(event, listener));
+  }
+  subscribe(navigationManager, 'onBeforeNavigate', onNavigationStart);
+  subscribe(navigationManager, 'onPageReady', (event) =>
+    enqueue(event.url, 'networkidle')
+  );
+  // onNavigationStart happens after old actions have been stopped. Using
+  // onUrlChange here would start an action that cleanup immediately aborts.
+  subscribe(navigationManager, 'onNavigationStart', (event) =>
+    enqueue(event.url, 'urlchange')
+  );
+  for (const readyOn of ['domcontentloaded', 'load']) {
+    subscribe(commander.page, readyOn, () =>
+      enqueue(commander.page.url(), readyOn)
+    );
+  }
+}
+
+function createTriggerDestroy({
+  subscriptions,
+  getQueue,
+  stopCurrentAction,
+  triggers,
+  log,
+}) {
+  return async () => {
+    for (const unsubscribe of subscriptions.splice(0)) {
+      unsubscribe();
+    }
+    await getQueue();
+    await stopCurrentAction();
+    triggers.length = 0;
+    log.debug(() => '📋 PageTriggerManager destroyed');
+  };
+}

package/src/core/readiness.js

@@ -464,9 +464,14 @@ export async function runReadinessChecks(options = {}) {
   const skipped = [];
   const pending = [];
   const evidence = [];
+  let deadlineReached = false;
 
   for (const [index, check] of checks.entries()) {
-    if (deadline.signal?.aborted || (deadline.expired() && failed.length > 0)) {
+    if (
+      deadlineReached ||
+      deadline.signal?.aborted ||
+      (deadline.expired() && failed.length > 0)
+    ) {
       pending.push(...checks.slice(index).map((entry) => entry.name));
       break;
     }
@@ -477,6 +482,9 @@ export async function runReadinessChecks(options = {}) {
       const bounded = await runWithinDeadline(deadline, () =>
         check.run({ ...context, deadline })
       );
+      // Timer callbacks and the rounded monotonic clock can disagree briefly.
+      // Once expiry ends a wait, another clock sample must not undo it.
+      deadlineReached ||= bounded.timedOut;
       outcome =
         bounded.timedOut || bounded.interrupted
           ? {
@@ -513,7 +521,7 @@ export async function runReadinessChecks(options = {}) {
 
   const interrupted = Boolean(deadline.signal?.aborted);
   const ready = !interrupted && failed.length === 0 && pending.length === 0;
-  const timedOut = !ready && deadline.expired();
+  const timedOut = !ready && (deadlineReached || deadline.expired());
 
   return {
     status: interrupted

package/src/elements/locators.js

@@ -1,5 +1,8 @@
 import { TIMING } from '../core/constants.js';
-import { isNavigationError } from '../core/navigation-safety.js';
+import {
+  waitNavigationState,
+  recoverWaitError,
+} from '../core/navigation-safety.js';
 
 /**
  * Helper to create Playwright locator from selector string
@@ -9,12 +12,16 @@ import { isNavigationError } from '../core/navigation-safety.js';
  * @param {string} options.selector - CSS selector
  * @returns {Object} - Playwright locator
  */
-export function createPlaywrightLocator(options = {}) {
-  const { page, selector } = options;
-
+export function requireSelector(selector) {
   if (!selector) {
     throw new Error('selector is required in options');
   }
+}
+
+export function createPlaywrightLocator(options = {}) {
+  const { page, selector } = options;
+
+  requireSelector(selector);
   // Check if selector has :nth-of-type(n) pattern
   const nthOfTypeMatch = selector.match(/^(.+):nth-of-type\((\d+)\)$/);
 
@@ -42,9 +49,7 @@ export async function getLocatorOrElement(options = {}) {
     throw new TypeError('index must be a non-negative integer');
   }
 
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(selector);
   if (typeof selector !== 'string') {
     return selector; // Already a locator/element
   }
@@ -73,18 +78,12 @@ export async function getLocatorOrElement(options = {}) {
  * @throws {Error} - If element not found or not visible within timeout (unless navigation error and throwOnNavigation is false)
  */
 export async function waitForLocatorOrElement(options = {}) {
-  const {
-    page,
-    engine,
-    selector,
-    timeout = TIMING.DEFAULT_TIMEOUT,
-    throwOnNavigation = true,
-  } = options;
-
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(options.selector);
+  const { page, engine, selector } = options;
+  const timeout =
+    options.timeout === undefined ? TIMING.DEFAULT_TIMEOUT : options.timeout;
 
+  const initial = waitNavigationState(page, options.navigationManager);
   try {
     if (engine === 'playwright') {
       const locator = await getLocatorOrElement(options);
@@ -125,17 +124,14 @@ export async function waitForLocatorOrElement(options = {}) {
       }
       return element;
     }
-  } catch (error) {
-    if (isNavigationError(error)) {
-      console.log(
-        '⚠️  Navigation detected during waitForLocatorOrElement, recovering gracefully'
-      );
-      if (throwOnNavigation) {
-        throw error;
-      }
-      return null;
-    }
-    throw error;
+  } catch (caught) {
+    return recoverWaitError(
+      caught,
+      options,
+      initial,
+      'waitForLocatorOrElement',
+      null
+    );
   }
 }
 
@@ -179,9 +175,7 @@ export async function waitForVisible(options = {}) {
 export function locator(options = {}) {
   const { page, engine, selector } = options;
 
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(selector);
 
   if (engine === 'playwright') {
     return createPlaywrightLocator({ page, selector });

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,5 @@ 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';