browser-commander 0.26.3 → 0.28.0

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

@@ -1,3 +1,5 @@
+import { subscribeCallbacks } from './subscriptions.js';
+
 /**
  * PageTriggerManager - Manages stoppable page triggers with proper lifecycle
  *
@@ -168,7 +170,8 @@ export function createPageTriggerManager(options = {}) {
   }
 
   // Registered triggers
-  const triggers = [];
+  const triggers = [],
+    subscriptions = [];
 
   // Current action state
   let currentTrigger = null;
@@ -176,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
@@ -189,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');
@@ -203,6 +224,8 @@ export function createPageTriggerManager(options = {}) {
       action,
       name,
       priority,
+      readyOn,
+      concurrency,
     };
 
     triggers.push(triggerConfig);
@@ -232,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) {
@@ -276,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`
@@ -287,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;
@@ -310,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
@@ -323,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}`);
 
@@ -436,18 +481,19 @@ export function createPageTriggerManager(options = {}) {
      */
     const cleanupCallbacks = [];
     function onCleanup(callback) {
-      cleanupCallbacks.push(callback);
-      abortSignal.addEventListener(
-        'abort',
-        async () => {
-          try {
-            await callback();
-          } catch (e) {
-            log.debug(() => `⚠️  Cleanup error: ${e.message}`);
-          }
-        },
-        { once: true }
-      );
+      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
@@ -507,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');
   }
@@ -544,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,
@@ -564,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

@@ -14,6 +14,7 @@ export const READINESS_STATUS = Object.freeze({
   READY: 'ready',
   TIMED_OUT: 'timed_out',
   FAILED: 'failed',
+  INTERRUPTED: 'interrupted',
 });
 
 /**
@@ -57,7 +58,7 @@ export function isLongLivedRequest(
  * @returns {{startedAt: number, timeoutMs: number, elapsedMs: Function, remainingMs: Function, expired: Function}} Deadline handle
  */
 export function createDeadline(options = {}) {
-  const { timeout, now = () => performance.now() } = options;
+  const { timeout, now = () => performance.now(), signal } = options;
 
   if (!Number.isFinite(timeout) || timeout < 0) {
     throw new TypeError('createDeadline requires a non-negative timeout');
@@ -72,6 +73,7 @@ export function createDeadline(options = {}) {
   const remainingMs = () => Math.max(0, Math.round(timeout - elapsed()));
 
   return {
+    signal,
     startedAt,
     timeoutMs: timeout,
     elapsedMs: () => Math.round(elapsed()),
@@ -92,7 +94,22 @@ export async function sleepWithinDeadline(ms, deadline) {
   if (capped <= 0) {
     return;
   }
-  await new Promise((resolve) => setTimeout(resolve, capped));
+  await runWithinDeadline(
+    deadline,
+    () =>
+      new Promise((resolve) => {
+        const timer = setTimeout(done, capped);
+        function done() {
+          clearTimeout(timer);
+          deadline.signal?.removeEventListener('abort', done);
+          resolve();
+        }
+        deadline.signal?.addEventListener('abort', done, { once: true });
+        if (deadline.signal?.aborted) {
+          done();
+        }
+      })
+  );
 }
 
 /** Marker resolved by the expiry timer in {@link runWithinDeadline}. */
@@ -110,7 +127,14 @@ const DEADLINE_REACHED = Symbol('deadline-reached');
  * @param {Function} run - Zero-argument function returning a promise
  * @returns {Promise<{timedOut: boolean, value: *}>} Outcome, or expiry
  */
-export async function runWithinDeadline(deadline, run) {
+export async function runWithinDeadline(
+  deadline,
+  run,
+  signal = deadline?.signal
+) {
+  if (signal?.aborted) {
+    return { timedOut: false, interrupted: true };
+  }
   if (!deadline) {
     return { timedOut: false, value: await run() };
   }
@@ -127,18 +151,31 @@ export async function runWithinDeadline(deadline, run) {
   Promise.resolve(operation).catch(() => {});
 
   let timer;
+  let onAbort;
   const expiry = new Promise((resolve) => {
     timer = setTimeout(() => resolve(DEADLINE_REACHED), remaining);
   });
+  const interrupted = Symbol('interrupted');
+  const cancellation = new Promise((resolve) => {
+    onAbort = () => resolve(interrupted);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+    }
+  });
 
   try {
-    const outcome = await Promise.race([operation, expiry]);
+    const outcome = await Promise.race([operation, expiry, cancellation]);
+    if (outcome === interrupted) {
+      return { timedOut: false, interrupted: true };
+    }
     if (outcome === DEADLINE_REACHED) {
       return { timedOut: true, value: undefined };
     }
     return { timedOut: false, value: outcome };
   } finally {
     clearTimeout(timer);
+    signal?.removeEventListener('abort', onAbort);
   }
 }
 
@@ -196,7 +233,7 @@ export function stableCheck(options = {}) {
       let streak = 0;
       let lastDetail = {};
 
-      while (!deadline.expired()) {
+      while (!deadline.expired() && !deadline.signal?.aborted) {
         const { stable, detail } = normalizeSampleResult(await sample(context));
         lastDetail = detail;
 
@@ -285,6 +322,7 @@ export function networkIdleFor(options = {}) {
 
       const idle = await networkTracker.waitForNetworkIdle({
         timeout,
+        signal: deadline.signal,
         ...(idleForMs === undefined ? {} : { idleTime: idleForMs }),
       });
 
@@ -426,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.expired() && failed.length > 0) {
+    if (
+      deadlineReached ||
+      deadline.signal?.aborted ||
+      (deadline.expired() && failed.length > 0)
+    ) {
       pending.push(...checks.slice(index).map((entry) => entry.name));
       break;
     }
@@ -436,7 +479,23 @@ export async function runReadinessChecks(options = {}) {
     const startedAtMs = deadline.elapsedMs();
     let outcome;
     try {
-      outcome = await check.run({ ...context, deadline });
+      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
+          ? {
+              satisfied: false,
+              detail: {
+                reason: bounded.interrupted
+                  ? 'interrupted'
+                  : 'deadline reached',
+              },
+            }
+          : bounded.value;
     } catch (error) {
       outcome = { satisfied: false, detail: { error: error.message } };
     }
@@ -460,15 +519,18 @@ export async function runReadinessChecks(options = {}) {
     }
   }
 
-  const ready = failed.length === 0 && pending.length === 0;
-  const timedOut = !ready && deadline.expired();
+  const interrupted = Boolean(deadline.signal?.aborted);
+  const ready = !interrupted && failed.length === 0 && pending.length === 0;
+  const timedOut = !ready && (deadlineReached || deadline.expired());
 
   return {
-    status: ready
-      ? READINESS_STATUS.READY
-      : timedOut
-        ? READINESS_STATUS.TIMED_OUT
-        : READINESS_STATUS.FAILED,
+    status: interrupted
+      ? READINESS_STATUS.INTERRUPTED
+      : ready
+        ? READINESS_STATUS.READY
+        : timedOut
+          ? READINESS_STATUS.TIMED_OUT
+          : READINESS_STATUS.FAILED,
     ready,
     checks: { satisfied, failed, skipped, pending },
     evidence,

package/src/core/subscriptions.js

@@ -0,0 +1,20 @@
+/** Register a callback and return a remover that can safely be called again. */
+export function subscribeCallbacks(callbacks, callback) {
+  callbacks?.push(callback);
+  let removed = false;
+  return () => {
+    if (removed) {
+      return;
+    }
+    removed = true;
+    removeCallback(callbacks, callback);
+  };
+}
+
+/** Remove one matching callback, retaining other registrations. */
+export function removeCallback(callbacks, callback) {
+  const index = callbacks?.indexOf(callback) ?? -1;
+  if (index !== -1) {
+    callbacks.splice(index, 1);
+  }
+}

package/src/core/webdriver-page.js

@@ -695,18 +695,56 @@ export class WebDriverPage extends EventEmitter {
   // ==========================================================================
 
   async cookies() {
+    if (await this.bidi()) {
+      const state = await this.bidiCommand('storage.getCookies');
+      return state.cookies.map((cookie) => ({
+        ...cookie,
+        value: cookie.value.value,
+        expires: cookie.expiry ?? -1,
+        sameSite: cookie.sameSite?.replace(/^./u, (letter) =>
+          letter.toUpperCase()
+        ),
+      }));
+    }
     const cookies = await this.driver.manage().getCookies();
     return cookies.map(fromWebDriverCookie);
   }
 
   async setCookie(...cookies) {
     for (const cookie of cookies) {
+      if (await this.bidi()) {
+        const { expires, url, ...value } = cookie;
+        await this.bidiCommand('storage.setCookie', {
+          cookie: {
+            ...value,
+            domain:
+              cookie.domain ?? new URL(url ?? (await this.syncUrl())).hostname,
+            ...(url
+              ? { secure: cookie.secure ?? new URL(url).protocol === 'https:' }
+              : {}),
+            value: { type: 'string', value: cookie.value },
+            sameSite: cookie.sameSite?.toLowerCase() ?? 'lax',
+            ...(expires > 0 ? { expiry: expires } : {}),
+          },
+        });
+        continue;
+      }
       await this.driver.manage().addCookie(toWebDriverCookie(cookie));
     }
   }
 
   async deleteCookie(...cookies) {
     for (const cookie of cookies) {
+      if (await this.bidi()) {
+        await this.bidiCommand('storage.deleteCookies', {
+          filter: {
+            name: cookie.name,
+            domain: cookie.domain,
+            path: cookie.path,
+          },
+        });
+        continue;
+      }
       await this.driver.manage().deleteCookie(cookie.name);
     }
   }

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+)\)$/);
 
@@ -37,20 +44,24 @@ export function createPlaywrightLocator(options = {}) {
  * @returns {Promise<Object|null>} - Locator for Playwright, Element for Puppeteer (can be null)
  */
 export async function getLocatorOrElement(options = {}) {
-  const { page, engine, selector } = options;
-
-  if (!selector) {
-    throw new Error('selector is required in options');
+  const { page, engine, selector, index } = options;
+  if (index !== undefined && (!Number.isInteger(index) || index < 0)) {
+    throw new TypeError('index must be a non-negative integer');
   }
+
+  requireSelector(selector);
   if (typeof selector !== 'string') {
     return selector; // Already a locator/element
   }
 
   if (engine === 'playwright') {
-    return createPlaywrightLocator({ page, selector });
+    const locator = createPlaywrightLocator({ page, selector });
+    return index === undefined ? locator : locator.nth(index);
   } else {
     // For Puppeteer, return element (can be null if doesn't exist)
-    return await page.$(selector);
+    return index === undefined
+      ? await page.$(selector)
+      : ((await page.$$(selector))[index] ?? null);
   }
 }
 
@@ -67,45 +78,60 @@ 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({ page, engine, selector });
+      const locator = await getLocatorOrElement(options);
       // Use .first() to handle multiple matches (Playwright strict mode)
       const firstLocator = locator.first();
       await firstLocator.waitFor({ state: 'visible', timeout });
       return firstLocator;
     } else {
+      if (typeof selector !== 'string') {
+        await waitForVisible({ engine, locatorOrElement: selector, timeout });
+        return selector;
+      }
+      if (options.index !== undefined && typeof selector === 'string') {
+        if (!Number.isInteger(options.index) || options.index < 0) {
+          throw new TypeError('index must be a non-negative integer');
+        }
+        await page.waitForFunction(
+          (sel, index) => {
+            const element = document.querySelectorAll(sel)[index];
+            return (
+              element &&
+              element.getBoundingClientRect().width > 0 &&
+              element.getBoundingClientRect().height > 0 &&
+              window.getComputedStyle(element).visibility !== 'hidden'
+            );
+          },
+          { timeout },
+          selector,
+          options.index
+        );
+        return getLocatorOrElement(options);
+      }
       // Puppeteer: wait for selector to be visible (returns first match by default)
       await page.waitForSelector(selector, { visible: true, timeout });
-      const element = await page.$(selector);
+      const element = await getLocatorOrElement(options);
       if (!element) {
         throw new Error(`Element not found after waiting: ${selector}`);
       }
       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
+    );
   }
 }
 
@@ -149,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 });