browser-commander 0.26.3 → 0.28.0

package/src/core/navigation-manager.js

@@ -1,3 +1,4 @@
+import { removeCallback, subscribeCallbacks } from './subscriptions.js';
 /**
  * NavigationManager - Centralized navigation handling
  *
@@ -10,7 +11,13 @@
 
 import { isNavigationError } from './navigation-safety.js';
 import { TIMING } from './constants.js';
-import { READINESS_STATUS } from './readiness.js';
+import {
+  READINESS_STATUS,
+  createDeadline,
+  runWithinDeadline,
+} from './readiness.js';
+import { createManagedNavigator } from './managed-navigation.js';
+import { navigationPhase as runNavigationPhase } from './navigation-operation.js';
 import { createReadinessWaiter } from './navigation-readiness.js';
 
 async function setManagedContent(options = {}) {
@@ -23,7 +30,7 @@ async function setManagedContent(options = {}) {
     currentUrl,
     triggerNavigationStart,
     updateCurrentUrl,
-    waitForPageReady,
+    waitForReady,
     abandonNavigation,
   } = options;
 
@@ -32,22 +39,35 @@ async function setManagedContent(options = {}) {
   }
 
   log.debug(() => '🚀 Loading in-memory HTML content');
+  const deadline = createDeadline({ timeout, signal: options.signal });
 
   try {
     // Treat document replacement as a controlled navigation so active page
     // triggers stop before the old document is discarded.
-    await triggerNavigationStart({ url: currentUrl, isExternal: false });
-    await page.setContent(html, { waitUntil, timeout });
+    await runNavigationPhase(deadline, () =>
+      triggerNavigationStart({ url: currentUrl, isExternal: false })
+    );
+    await runNavigationPhase(deadline, () =>
+      page.setContent(html, {
+        waitUntil,
+        timeout: Math.max(1, deadline.remainingMs()),
+      })
+    );
 
     // setContent normally preserves the URL, but inline scripts can navigate.
     updateCurrentUrl();
-    await waitForPageReady({ timeout, reason: 'after setContent' });
-    return true;
+    return (
+      await waitForReady({
+        deadline,
+        reason: 'after setContent',
+        checks: options.checks,
+      })
+    ).ready;
   } catch (error) {
     // Do not leave the manager in its loading state when setContent fails, but
     // do not claim the page became ready either - it did not.
     abandonNavigation('setContent failed');
-    if (isNavigationError(error)) {
+    if (error.status || isNavigationError(error)) {
       log.debug(() => '⚠️  Content loading was interrupted, recovering...');
       return false;
     }
@@ -77,6 +97,7 @@ export function createNavigationManager(options = {}) {
   let navigationStartTime = null;
   let navigationPromise = null;
   let navigationResolve = null;
+  const state = { activeOperation: null, lastOutcome: null };
 
   // Session tracking
   let sessionId = 0;
@@ -182,6 +203,10 @@ export function createNavigationManager(options = {}) {
     }
     sessionCleanupCallbacks = [];
 
+    if (details.signal?.aborted) {
+      return;
+    }
+
     // Start new session
     sessionId++;
     isNavigating = true;
@@ -210,12 +235,14 @@ export function createNavigationManager(options = {}) {
 
     // If external navigation, wait for it to complete
     if (isExternal) {
-      await waitForPageReady({ reason: 'external navigation' });
+      await waitForPageReady({
+        reason: 'external navigation',
+        timeout: config.networkIdleTimeout,
+      });
     }
   }
 
   // Track if a readiness wait is currently running to prevent concurrent calls
-  let pageReadyPromise = null;
 
   const { waitForReady } = createReadinessWaiter({
     page,
@@ -230,9 +257,11 @@ export function createNavigationManager(options = {}) {
         log.debug(() => `🔄 Redirect detected: ${url}`);
       }
     },
-    onReady: () => {
+    onReady: (readyOn) => {
       finishNavigationTracking({ ready: true });
-      emitPageReady();
+      if (readyOn === 'networkidle') {
+        emitPageReady();
+      }
     },
     onNotReady: () => finishNavigationTracking({ ready: false }),
   });
@@ -250,22 +279,9 @@ export function createNavigationManager(options = {}) {
   async function waitForPageReady(opts = {}) {
     const { reason = 'page ready' } = opts;
 
-    // Concurrent callers join the in-flight wait instead of racing a second
-    // deadline against the first.
-    if (pageReadyPromise) {
-      log.debug(
-        () => `⏳ Waiting for existing page ready operation (${reason})...`
-      );
-      return pageReadyPromise;
-    }
-
-    pageReadyPromise = waitForReady(opts).then((result) => result.ready);
-
-    try {
-      return await pageReadyPromise;
-    } finally {
-      pageReadyPromise = null;
-    }
+    // Independent policies and deadlines cannot safely share a readiness wait.
+    log.debug(() => `Waiting for page ready (${reason})`);
+    return (await waitForReady(opts)).ready;
   }
 
   /**
@@ -343,36 +359,15 @@ export function createNavigationManager(options = {}) {
    * @param {number} options.timeout - Navigation timeout
    * @returns {Promise<boolean>} - True if navigation succeeded
    */
-  async function navigate(opts = {}) {
-    const { url, waitUntil = 'domcontentloaded', timeout = 60000 } = opts;
-
-    if (!url) {
-      throw new Error('url is required in options');
-    }
-
-    log.debug(() => `🚀 Navigating to: ${url}`);
-
-    try {
-      // Trigger navigation start
-      await triggerNavigationStart({ url, isExternal: false });
-
-      // Perform navigation
-      await page.goto(url, { waitUntil, timeout });
-
-      // Update current URL
-      currentUrl = page.url();
-
-      // Wait for page to be fully ready
-      return await waitForPageReady({ timeout, reason: 'after goto' });
-    } catch (error) {
-      if (isNavigationError(error)) {
-        log.debug(() => '⚠️  Navigation was interrupted, recovering...');
-        abandonNavigation('navigation interrupted');
-        return false;
-      }
-      throw error;
-    }
-  }
+  const navigate = createManagedNavigator({
+    page,
+    state,
+    config,
+    waitForReady,
+    triggerNavigationStart,
+    updateCurrentUrl: () => (currentUrl = page.url()),
+    abandonNavigation,
+  });
 
   const setContent = (opts = {}) =>
     setManagedContent({
@@ -382,7 +377,7 @@ export function createNavigationManager(options = {}) {
       currentUrl,
       triggerNavigationStart,
       updateCurrentUrl: () => (currentUrl = page.url()),
-      waitForPageReady,
+      waitForReady,
       abandonNavigation,
     });
 
@@ -399,23 +394,15 @@ export function createNavigationManager(options = {}) {
       return true; // Already ready
     }
 
-    // Create a promise that resolves when navigation completes
     if (!navigationPromise) {
       navigationPromise = new Promise((resolve) => {
         navigationResolve = resolve;
-
-        // Timeout handler
-        setTimeout(() => {
-          if (isNavigating) {
-            log.debug(() => '⚠️  waitForNavigation timeout');
-            abandonNavigation('waitForNavigation timeout');
-            resolve(false);
-          }
-        }, timeout);
       });
     }
-
-    return await navigationPromise;
+    const deadline =
+      opts.deadline ?? createDeadline({ timeout, signal: opts.signal });
+    const outcome = await runWithinDeadline(deadline, () => navigationPromise);
+    return !outcome.timedOut && !outcome.interrupted && outcome.value;
   }
 
   /**
@@ -450,28 +437,21 @@ export function createNavigationManager(options = {}) {
    * Will be called before next navigation
    */
   function onSessionCleanup(callback) {
-    sessionCleanupCallbacks.push(callback);
+    return subscribeCallbacks(sessionCleanupCallbacks, callback);
   }
 
   /**
    * 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);
   }
 
   /**
@@ -486,6 +466,7 @@ export function createNavigationManager(options = {}) {
    * Stop listening for navigation events
    */
   function stopListening() {
+    state.activeOperation?.controller.abort();
     page.off('framenavigated', handleFrameNavigation);
     log.debug(() => '🔌 Navigation manager stopped');
   }
@@ -500,6 +481,10 @@ export function createNavigationManager(options = {}) {
   return {
     // Navigation
     navigate,
+    cancelNavigation: () => {
+      state.activeOperation?.controller.abort();
+      abandonNavigation('caller stopped navigation');
+    },
     setContent,
     waitForNavigation,
     waitForPageReady,
@@ -507,6 +492,7 @@ export function createNavigationManager(options = {}) {
 
     // State
     isNavigating: () => isNavigating,
+    getLastOutcome: () => state.lastOutcome,
     getCurrentUrl: () => currentUrl,
     getSessionId: () => sessionId,
 

package/src/core/navigation-operation.js

@@ -0,0 +1,25 @@
+import { runWithinDeadline } from './readiness.js';
+
+/** Stable outcome for cancellation or an exhausted operation budget. */
+export class NavigationStoppedError extends Error {
+  constructor(status) {
+    super(
+      status === 'interrupted'
+        ? 'Navigation interrupted'
+        : 'Navigation timed out'
+    );
+    this.name = 'NavigationStoppedError';
+    this.status = status;
+  }
+}
+
+/** Bound every navigation phase by the same deadline and caller signal. */
+export async function navigationPhase(deadline, run) {
+  const result = await runWithinDeadline(deadline, run);
+  if (result.interrupted || result.timedOut) {
+    throw new NavigationStoppedError(
+      result.interrupted ? 'interrupted' : 'timed_out'
+    );
+  }
+  return result.value;
+}

package/src/core/navigation-readiness.js

@@ -12,6 +12,7 @@ import {
   networkIdleFor,
   runReadinessChecks,
   urlStableFor,
+  stableCheck,
 } from './readiness.js';
 
 /**
@@ -97,27 +98,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 ?? checksForReadiness(opts.readyOn, 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(opts.readyOn ?? 'networkidle');
+      }
       log.debug(() => `✅ Page ready after ${outcome.elapsedMs}ms (${reason})`);
     } else {
-      onNotReady();
+      if (notify()) {
+        onNotReady();
+      }
       log.debug(
         () =>
           `⚠️  Page not ready (${reason}): ${outcome.status} after ` +
@@ -131,3 +156,30 @@ export function createReadinessWaiter(options = {}) {
 
   return { waitForReady, getAdapter };
 }
+
+export function checksForReadiness(readyOn = 'networkidle', config) {
+  if (readyOn === 'networkidle') {
+    return defaultReadinessChecks(config);
+  }
+  if (readyOn === 'urlchange') {
+    return [];
+  }
+  if (!['domcontentloaded', 'load'].includes(readyOn)) {
+    throw new RangeError(`Unknown readyOn: ${readyOn}`);
+  }
+  return [
+    stableCheck({
+      name: readyOn,
+      stableForMs: 0,
+      intervalMs: 50,
+      sample: async ({ page }) => {
+        const state = await page.evaluate(() => document.readyState);
+        return {
+          stable:
+            readyOn === 'load' ? state === 'complete' : state !== 'loading',
+          detail: { state },
+        };
+      },
+    }),
+  ];
+}

package/src/core/navigation-safety.js

@@ -8,7 +8,58 @@
  * @param {Error} error - The error to check
  * @returns {boolean} - True if this is a navigation error
  */
+export class NavigationInterruptedError extends Error {
+  constructor(cause) {
+    super('Navigation interrupted the element wait', { cause });
+    this.name = 'NavigationInterruptedError';
+  }
+}
+
+export function waitNavigationState(page, manager) {
+  return { url: page.url?.(), session: manager?.getSessionId?.() };
+}
+
+export function classifyWaitError(error, page, manager, initial) {
+  if (!isTimeoutError(error)) {
+    return error;
+  }
+  try {
+    const current = waitNavigationState(page, manager);
+    if (current.url !== initial.url || current.session !== initial.session) {
+      return new NavigationInterruptedError(error);
+    }
+  } catch {
+    // Keep the original timeout when the page identity is unavailable.
+  }
+  return error;
+}
+
+export function recoverWaitError(
+  caught,
+  options,
+  initial,
+  operation,
+  fallback
+) {
+  const error = classifyWaitError(
+    caught,
+    options.page,
+    options.navigationManager,
+    initial
+  );
+  if (!isNavigationError(error) || options.throwOnNavigation !== false) {
+    throw error;
+  }
+  console.log(
+    `⚠️  Navigation detected during ${operation}, recovering gracefully`
+  );
+  return fallback;
+}
+
 export function isNavigationError(error) {
+  if (error instanceof NavigationInterruptedError) {
+    return true;
+  }
   if (!error || !error.message) {
     return false;
   }

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