browser-commander 0.27.0 → 0.29.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,26 @@ 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();
+  let pendingStart = null;
+  let destroyed = false;
+
+  function drainPending() {
+    if (destroyed || isActionRunning || isStopping || !pendingStart) {
+      return;
+    }
+    const pending = pendingStart;
+    pendingStart = null;
+    if (
+      triggers.includes(pending.trigger) &&
+      (!pending.commander.page?.url ||
+        pending.commander.page.url() === pending.url)
+    ) {
+      void startAction(pending.url, pending.commander, pending.readyOn);
+    }
+  }
 
   /**
    * Register a page trigger
@@ -191,7 +210,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', 'queue'].includes(concurrency)) {
+      throw new RangeError(`Unknown trigger concurrency: ${concurrency}`);
+    }
 
     if (typeof condition !== 'function') {
       throw new Error('condition must be a function');
@@ -205,6 +241,8 @@ export function createPageTriggerManager(options = {}) {
       action,
       name,
       priority,
+      readyOn,
+      concurrency,
     };
 
     triggers.push(triggerConfig);
@@ -221,6 +259,9 @@ export function createPageTriggerManager(options = {}) {
       const index = triggers.indexOf(triggerConfig);
       if (index !== -1) {
         triggers.splice(index, 1);
+        if (pendingStart?.trigger === triggerConfig) {
+          pendingStart = null;
+        }
         log.debug(() => `📋 Unregistered page trigger: "${name}"`);
       }
     };
@@ -234,7 +275,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) {
@@ -277,9 +318,10 @@ export function createPageTriggerManager(options = {}) {
     }
 
     // Wait for action to finish (with timeout)
-    const timeoutMs = 10000; // 10 second max wait
+    const timeoutMs = options.stopGraceMs ?? 10000;
+    let stopTimer;
     const timeoutPromise = new Promise((resolve) => {
-      setTimeout(() => {
+      stopTimer = setTimeout(() => {
         log.debug(
           () =>
             `⚠️  Action "${currentTrigger?.name}" did not stop gracefully within ${timeoutMs}ms`
@@ -289,6 +331,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;
@@ -305,6 +357,7 @@ export function createPageTriggerManager(options = {}) {
     }
 
     log.debug(() => '✅ Action stopped');
+    drainPending();
   }
 
   /**
@@ -312,11 +365,15 @@ 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') {
+    if (destroyed) {
+      return Promise.resolve();
+    }
     // Create context for condition checking
     const conditionCtx = {
       url,
       commander,
+      readyOn,
     };
 
     // Find matching trigger
@@ -325,6 +382,20 @@ export function createPageTriggerManager(options = {}) {
       log.debug(() => `📋 No trigger registered for: ${url}`);
       return Promise.resolve();
     }
+    if (isActionRunning) {
+      if (
+        matchingTrigger.concurrency === 'skip' &&
+        !isStopping &&
+        !currentAbortController?.signal.aborted
+      ) {
+        return Promise.resolve();
+      }
+      // One latest start bounds memory while preserving readiness during stop.
+      pendingStart = { url, commander, readyOn, trigger: matchingTrigger };
+      return matchingTrigger.concurrency === 'restart'
+        ? stopCurrentAction()
+        : Promise.resolve();
+    }
 
     log.debug(() => `🚀 Starting action "${matchingTrigger.name}" for: ${url}`);
 
@@ -334,12 +405,15 @@ export function createPageTriggerManager(options = {}) {
     isActionRunning = true;
 
     // Create action context
-    const context = createActionContext({
-      url,
-      abortSignal: currentAbortController.signal,
-      commander,
-      triggerName: matchingTrigger.name,
-    });
+    const context = createActionContext(
+      {
+        url,
+        abortSignal: currentAbortController.signal,
+        commander,
+        triggerName: matchingTrigger.name,
+      },
+      log
+    );
 
     // Run action
     actionPromise = (async () => {
@@ -368,6 +442,7 @@ export function createPageTriggerManager(options = {}) {
           isActionRunning = false;
           currentTrigger = null;
           currentAbortController = null;
+          globalThis.queueMicrotask(drainPending);
         }
       }
     })();
@@ -380,166 +455,44 @@ export function createPageTriggerManager(options = {}) {
    * @param {Object} options
    * @returns {Object} - Action context
    */
-  function createActionContext(options) {
-    const { url, abortSignal, commander, triggerName } = options;
-
-    /**
-     * Check if stopped and throw if so
-     */
-    function checkStopped() {
-      if (abortSignal.aborted) {
-        throw new ActionStoppedError(`Action "${triggerName}" stopped`);
-      }
-    }
-
-    /**
-     * Wrap async function to check abort before and after
-     */
-    function wrapAsync(fn) {
-      return async (...args) => {
-        checkStopped();
-        const result = await fn(...args);
-        checkStopped();
-        return result;
-      };
-    }
-
-    /**
-     * Create abort-aware loop helper
-     * Use this instead of for/while loops for stoppability
-     */
-    async function forEach(items, callback) {
-      for (let i = 0; i < items.length; i++) {
-        checkStopped();
-        await callback(items[i], i, items);
-      }
-    }
-
-    /**
-     * Wait with abort support
-     */
-    async function wait(ms) {
-      checkStopped();
-      await new Promise((resolve, reject) => {
-        const timeout = setTimeout(resolve, ms);
-        abortSignal.addEventListener(
-          'abort',
-          () => {
-            clearTimeout(timeout);
-            reject(new ActionStoppedError());
-          },
-          { once: true }
-        );
-      });
-    }
-
-    /**
-     * Register cleanup callback (called when action stops)
-     */
-    const cleanupCallbacks = [];
-    function onCleanup(callback) {
-      const unsubscribe = subscribeCallbacks(cleanupCallbacks, callback);
-      const onAbort = async () => {
-        try {
-          await callback();
-        } catch (e) {
-          log.debug(() => `⚠️  Cleanup error: ${e.message}`);
-        }
-      };
-      abortSignal.addEventListener('abort', onAbort, { once: true });
-      return () => {
-        abortSignal.removeEventListener('abort', onAbort);
-        unsubscribe();
-      };
-    }
-
-    // Wrap all commander methods to be abort-aware
-    const wrappedCommander = {};
-    for (const [key, value] of Object.entries(commander)) {
-      if (
-        typeof value === 'function' &&
-        key !== 'destroy' &&
-        key !== 'pageTrigger'
-      ) {
-        wrappedCommander[key] = wrapAsync(value);
-      } else {
-        wrappedCommander[key] = value;
-      }
-    }
-
-    return {
-      // URL this action is running for
-      url,
-
-      // Abort signal - use with fetch() or custom abort logic
-      abortSignal,
-
-      // Check if action should stop
-      isStopped: () => abortSignal.aborted,
-
-      // Throw if stopped - call this in loops
-      checkStopped,
-
-      // Abort-aware iteration helper
-      forEach,
-
-      // Abort-aware wait
-      wait,
-
-      // Register cleanup callback
-      onCleanup,
-
-      // Wrapped commander - all methods throw ActionStoppedError if stopped
-      commander: wrappedCommander,
-
-      // Original commander (use carefully)
-      rawCommander: commander,
-
-      // Trigger name for debugging
-      triggerName,
-    };
-  }
 
   /**
    * Handle navigation start - stop current action first
    */
   async function onNavigationStart() {
+    pendingStart = null;
     await stopCurrentAction();
   }
 
   /**
    * 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 +500,18 @@ export function createPageTriggerManager(options = {}) {
   /**
    * Cleanup
    */
-  async function destroy() {
-    await stopCurrentAction();
-    triggers.length = 0;
-    navigationManager.off('onBeforeNavigate', onNavigationStart);
-    log.debug(() => '📋 PageTriggerManager destroyed');
-  }
+  const cleanup = createTriggerDestroy({
+    subscriptions,
+    getQueue: () => startQueue,
+    stopCurrentAction,
+    triggers,
+    log,
+  });
+  const destroy = async () => {
+    destroyed = true;
+    pendingStart = null;
+    await cleanup();
+  };
 
   return {
     pageTrigger,
@@ -567,3 +526,168 @@ 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');
+  };
+}
+
+function createActionContext(options, log) {
+  const { url, abortSignal, commander, triggerName } = options;
+
+  /**
+   * Check if stopped and throw if so
+   */
+  function checkStopped() {
+    if (abortSignal.aborted) {
+      throw new ActionStoppedError(`Action "${triggerName}" stopped`);
+    }
+  }
+
+  /**
+   * Wrap async function to check abort before and after
+   */
+  function wrapAsync(fn) {
+    return async (...args) => {
+      checkStopped();
+      const result = await fn(...args);
+      checkStopped();
+      return result;
+    };
+  }
+
+  /**
+   * Create abort-aware loop helper
+   * Use this instead of for/while loops for stoppability
+   */
+  async function forEach(items, callback) {
+    for (let i = 0; i < items.length; i++) {
+      checkStopped();
+      await callback(items[i], i, items);
+    }
+  }
+
+  /**
+   * Wait with abort support
+   */
+  async function wait(ms) {
+    checkStopped();
+    await new Promise((resolve, reject) => {
+      const timeout = setTimeout(resolve, ms);
+      abortSignal.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(timeout);
+          reject(new ActionStoppedError());
+        },
+        { once: true }
+      );
+    });
+  }
+
+  /**
+   * Register cleanup callback (called when action stops)
+   */
+  const cleanupCallbacks = [];
+  function onCleanup(callback) {
+    const unsubscribe = subscribeCallbacks(cleanupCallbacks, callback);
+    const onAbort = async () => {
+      try {
+        await callback();
+      } catch (e) {
+        log.debug(() => `⚠️  Cleanup error: ${e.message}`);
+      }
+    };
+    abortSignal.addEventListener('abort', onAbort, { once: true });
+    return () => {
+      abortSignal.removeEventListener('abort', onAbort);
+      unsubscribe();
+    };
+  }
+
+  // Wrap all commander methods to be abort-aware
+  const wrappedCommander = {};
+  for (const [key, value] of Object.entries(commander)) {
+    if (
+      typeof value === 'function' &&
+      key !== 'destroy' &&
+      key !== 'pageTrigger'
+    ) {
+      wrappedCommander[key] = wrapAsync(value);
+    } else {
+      wrappedCommander[key] = value;
+    }
+  }
+
+  return {
+    // URL this action is running for
+    url,
+
+    // Abort signal - use with fetch() or custom abort logic
+    abortSignal,
+
+    // Check if action should stop
+    isStopped: () => abortSignal.aborted,
+
+    // Throw if stopped - call this in loops
+    checkStopped,
+
+    // Abort-aware iteration helper
+    forEach,
+
+    // Abort-aware wait
+    wait,
+
+    // Register cleanup callback
+    onCleanup,
+
+    // Wrapped commander - all methods throw ActionStoppedError if stopped
+    commander: wrappedCommander,
+
+    // Original commander (use carefully)
+    rawCommander: commander,
+
+    // Trigger name for debugging
+    triggerName,
+  };
+}

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 });