browser-commander 0.26.3 → 0.27.0

package/src/core/navigation-readiness.js

@@ -97,27 +97,51 @@ export function createReadinessWaiter(options = {}) {
 
     log.debug(() => `⏳ Waiting for page ready (${reason})...`);
 
-    const deadline = createDeadline({ timeout });
-    const result = await runReadinessChecks({
-      checks: checks ?? defaultReadinessChecks(config),
-      deadline,
-      context: {
-        page,
-        engine,
-        log,
-        networkTracker,
-        getAdapter,
-        onUrlSample,
-      },
-    });
-
+    const controller = new AbortController();
+    const parentSignal = opts.deadline?.signal ?? opts.signal;
+    const signal = parentSignal
+      ? AbortSignal.any([parentSignal, controller.signal])
+      : controller.signal;
+    const deadline = {
+      ...(opts.deadline ?? createDeadline({ timeout })),
+      signal,
+    };
+    const notify = () =>
+      !opts.observeOnly &&
+      !parentSignal?.aborted &&
+      (opts.shouldNotify?.() ?? true);
+    let result;
+    try {
+      result = await runReadinessChecks({
+        checks: checks ?? defaultReadinessChecks(config),
+        deadline,
+        context: {
+          page,
+          engine,
+          log,
+          networkTracker,
+          getAdapter,
+          onUrlSample: (url) => {
+            if (notify()) {
+              onUrlSample?.(url);
+            }
+          },
+        },
+      });
+    } finally {
+      controller.abort();
+    }
     const outcome = { ...result, reason, ...getState() };
 
     if (outcome.ready) {
-      onReady();
+      if (notify()) {
+        onReady();
+      }
       log.debug(() => `✅ Page ready after ${outcome.elapsedMs}ms (${reason})`);
     } else {
-      onNotReady();
+      if (notify()) {
+        onNotReady();
+      }
       log.debug(
         () =>
           `⚠️  Page not ready (${reason}): ${outcome.status} after ` +

package/src/core/network-tracker.js

@@ -1,3 +1,4 @@
+import { removeCallback, subscribeCallbacks } from './subscriptions.js';
 /**
  * NetworkTracker - Track all HTTP requests and wait for network idle
  *
@@ -206,101 +207,54 @@ export function createNetworkTracker(options = {}) {
    * @param {number} options.idleTime - Time network must be idle (default: idleTimeout)
    * @returns {Promise<boolean>} - True if idle, false if timeout
    */
-  async function waitForNetworkIdle(opts = {}) {
-    const { timeout = 30000, idleTime = idleTimeout } = opts;
-
-    const currentNavId = navigationId;
-
-    // If already idle, wait for idle time
-    if (pendingRequests.size === 0) {
-      await new Promise((r) => setTimeout(r, idleTime));
-
-      // Check if still idle and no navigation happened
-      if (pendingRequests.size === 0 && navigationId === currentNavId) {
-        return true;
-      }
+  function waitForNetworkIdle(opts = {}) {
+    const { timeout = 30000, idleTime = idleTimeout, signal } = opts;
+    if (signal?.aborted || timeout <= 0) {
+      return false;
     }
-
+    const currentNavId = navigationId;
+    const started = performance.now();
+    let quietSince = pendingRequests.size === 0 ? started : null;
     return new Promise((resolve) => {
-      let resolved = false;
-      let checkTimer = null;
-      let timeoutTimer = null;
-
-      const cleanup = () => {
-        if (checkTimer) {
-          clearInterval(checkTimer);
-        }
-        if (timeoutTimer) {
-          clearTimeout(timeoutTimer);
-        }
-        resolved = true;
+      let timer;
+      const finish = (value) => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        resolve(value);
       };
-
-      // Timeout handler
-      timeoutTimer = setTimeout(() => {
-        if (!resolved) {
-          cleanup();
-          log.debug(
-            () =>
-              `⚠️  Network idle timeout after ${timeout}ms (${pendingRequests.size} pending)`
-          );
-
-          // Log stuck requests
-          if (pendingRequests.size > 0) {
-            const stuckRequests = [];
-            for (const [key, req] of pendingRequests) {
-              const startTime = requestStartTimes.get(key);
-              const duration = Date.now() - startTime;
-              const url = typeof req.url === 'function' ? req.url() : req.url;
-              stuckRequests.push(
-                `  ${url.substring(0, 60)}... (${duration}ms)`
-              );
-            }
-            log.debug(() => `⚠️  Stuck requests:\n${stuckRequests.join('\n')}`);
-          }
-
-          resolve(false);
-        }
-      }, timeout);
-
-      // Check periodically for idle state
-      checkTimer = setInterval(async () => {
-        if (resolved) {
-          return;
-        }
-
-        // Check for navigation change (abort wait)
-        if (navigationId !== currentNavId) {
-          cleanup();
-          resolve(false);
+      const onAbort = () => finish(false);
+      const sample = () => {
+        const now = performance.now();
+        if (
+          signal?.aborted ||
+          navigationId !== currentNavId ||
+          now - started >= timeout
+        ) {
+          finish(false);
           return;
         }
-
-        // Check for timed out requests and remove them
-        const now = Date.now();
-        for (const [key, startTime] of requestStartTimes) {
-          if (now - startTime > requestTimeout) {
-            log.debug(() => `⚠️  Request timed out, removing: ${key}`);
+        for (const [key, requestStart] of requestStartTimes) {
+          if (Date.now() - requestStart > requestTimeout) {
             pendingRequests.delete(key);
             requestStartTimes.delete(key);
           }
         }
-
-        // Check if idle
         if (pendingRequests.size === 0) {
-          // Wait for idle time to confirm
-          await new Promise((r) => setTimeout(r, idleTime));
-
-          if (
-            !resolved &&
-            pendingRequests.size === 0 &&
-            navigationId === currentNavId
-          ) {
-            cleanup();
-            resolve(true);
+          quietSince ??= now;
+          if (now - quietSince >= idleTime) {
+            finish(true);
+            return;
           }
+        } else {
+          quietSince = null;
         }
-      }, 100);
+        timer = setTimeout(
+          sample,
+          Math.max(1, Math.min(25, timeout - (now - started)))
+        );
+      };
+      signal?.addEventListener('abort', onAbort, { once: true });
+      sample();
     });
   }
 
@@ -327,21 +281,14 @@ export function createNetworkTracker(options = {}) {
    * Add event listener
    */
   function on(event, callback) {
-    if (listeners[event]) {
-      listeners[event].push(callback);
-    }
+    return subscribeCallbacks(listeners[event], callback);
   }
 
   /**
    * Remove event listener
    */
   function off(event, callback) {
-    if (listeners[event]) {
-      const index = listeners[event].indexOf(callback);
-      if (index !== -1) {
-        listeners[event].splice(index, 1);
-      }
-    }
+    removeCallback(listeners[event], callback);
   }
 
   /**

package/src/core/page-session.js

@@ -1,3 +1,4 @@
+import { subscribeCallbacks } from './subscriptions.js';
 /**
  * PageSession - Abstraction for page lifecycle management
  *
@@ -151,9 +152,9 @@ export function createPageSessionFactory(options = {}) {
         log.debug(
           () => `⚠️  Cannot register cleanup on inactive session "${name}"`
         );
-        return;
+        return () => {};
       }
-      cleanupCallbacks.push(callback);
+      return subscribeCallbacks(cleanupCallbacks, callback);
     }
 
     /**

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

@@ -1,3 +1,5 @@
+import { subscribeCallbacks } from './subscriptions.js';
+
 /**
  * PageTriggerManager - Manages stoppable page triggers with proper lifecycle
  *
@@ -436,18 +438,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

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 }),
       });
 
@@ -428,7 +466,7 @@ export async function runReadinessChecks(options = {}) {
   const evidence = [];
 
   for (const [index, check] of checks.entries()) {
-    if (deadline.expired() && failed.length > 0) {
+    if (deadline.signal?.aborted || (deadline.expired() && failed.length > 0)) {
       pending.push(...checks.slice(index).map((entry) => entry.name));
       break;
     }
@@ -436,7 +474,20 @@ 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 })
+      );
+      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 +511,18 @@ export async function runReadinessChecks(options = {}) {
     }
   }
 
-  const ready = failed.length === 0 && pending.length === 0;
+  const interrupted = Boolean(deadline.signal?.aborted);
+  const ready = !interrupted && failed.length === 0 && pending.length === 0;
   const timedOut = !ready && 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

@@ -37,7 +37,10 @@ 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;
+  const { page, engine, selector, index } = options;
+  if (index !== undefined && (!Number.isInteger(index) || index < 0)) {
+    throw new TypeError('index must be a non-negative integer');
+  }
 
   if (!selector) {
     throw new Error('selector is required in options');
@@ -47,10 +50,13 @@ export async function getLocatorOrElement(options = {}) {
   }
 
   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);
   }
 }
 
@@ -81,15 +87,39 @@ export async function waitForLocatorOrElement(options = {}) {
 
   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}`);
       }