browser-commander 0.26.3 → 0.27.0

package/src/browser/navigation.js

@@ -5,6 +5,7 @@
  * the NavigationManager for backwards compatibility.
  */
 
+import { navigationPhase } from '../core/navigation-operation.js';
 import { TIMING } from '../core/constants.js';
 import { isNavigationError } from '../core/navigation-safety.js';
 import { isActionStoppedError } from '../core/page-trigger-manager.js';
@@ -13,6 +14,8 @@ import {
   createDeadline,
   networkIdleFor,
   runReadinessChecks,
+  runWithinDeadline,
+  sleepWithinDeadline,
   urlStableFor,
 } from '../core/readiness.js';
 
@@ -102,17 +105,30 @@ export async function verifyNavigation(options = {}) {
     log = { debug: () => {} },
   } = options;
 
-  const startTime = Date.now();
+  const deadline =
+    options.deadline ?? createDeadline({ timeout, signal: options.signal });
+  const verificationEnd = performance.now() + timeout;
+  const budget = {
+    ...deadline,
+    remainingMs: () =>
+      Math.max(
+        0,
+        Math.min(deadline.remainingMs(), verificationEnd - performance.now())
+      ),
+    expired: () => deadline.expired() || performance.now() >= verificationEnd,
+  };
   let attempts = 0;
   let lastResult = { verified: false, actualUrl: '', reason: '' };
 
-  while (Date.now() - startTime < timeout) {
+  while (!budget.expired() && !budget.signal?.aborted) {
     attempts++;
-    lastResult = await verifyFn({
-      page,
-      expectedUrl,
-      startUrl,
-    });
+    const probe = await runWithinDeadline(budget, () =>
+      verifyFn({ page, expectedUrl, startUrl })
+    );
+    if (probe.timedOut || probe.interrupted) {
+      break;
+    }
+    lastResult = probe.value;
 
     if (lastResult.verified) {
       log.debug(
@@ -128,7 +144,7 @@ export async function verifyNavigation(options = {}) {
     }
 
     // Wait before next retry
-    await new Promise((resolve) => setTimeout(resolve, retryInterval));
+    await sleepWithinDeadline(retryInterval, budget);
   }
 
   log.debug(
@@ -158,7 +174,7 @@ export async function waitForUrlStabilization(options = {}) {
   const {
     page,
     log,
-    wait,
+    wait: _wait,
     navigationManager,
     stableChecks = 3,
     checkInterval = 1000,
@@ -168,25 +184,29 @@ export async function waitForUrlStabilization(options = {}) {
 
   // If NavigationManager is available, delegate to it
   if (navigationManager) {
-    return navigationManager.waitForPageReady({ timeout, reason });
+    return navigationManager.waitForPageReady({ ...options, timeout, reason });
   }
 
   // Legacy polling-based approach
   log.debug(() => `⏳ Waiting for URL to stabilize (${reason})...`);
   let stableCount = 0;
   let lastUrl = page.url();
-  const startTime = Date.now();
+  const deadline =
+    options.deadline ?? createDeadline({ timeout, signal: options.signal });
 
   while (stableCount < stableChecks) {
     // Check timeout
-    if (Date.now() - startTime > timeout) {
+    if (deadline.expired() || deadline.signal?.aborted) {
       log.debug(
         () => `⚠️  URL stabilization timeout after ${timeout}ms (${reason})`
       );
       return false;
     }
 
-    await wait({ ms: checkInterval, reason: 'checking URL stability' });
+    await sleepWithinDeadline(checkInterval, deadline);
+    if (deadline.expired() || deadline.signal?.aborted) {
+      return false;
+    }
     const currentUrl = page.url();
 
     if (currentUrl === lastUrl) {
@@ -209,6 +229,70 @@ export async function waitForUrlStabilization(options = {}) {
   return true;
 }
 
+async function legacyGotoReadiness(options, deadline) {
+  const {
+    page,
+    url,
+    waitForUrlStabilization: stabilizeFn,
+    waitUntil,
+    waitForStableUrlBefore,
+    waitForStableUrlAfter,
+    waitForNetworkIdle,
+    stableChecks,
+    checkInterval,
+    checks,
+  } = options;
+  if (waitForStableUrlBefore && stabilizeFn) {
+    await navigationPhase(deadline, () =>
+      stabilizeFn({
+        stableChecks,
+        checkInterval,
+        timeout: deadline.remainingMs(),
+        deadline,
+        reason: 'before navigation',
+      })
+    );
+  }
+  await navigationPhase(deadline, () =>
+    page.goto(url, {
+      waitUntil,
+      timeout: Math.max(1, deadline.remainingMs()),
+    })
+  );
+  const readiness = checks ?? [
+    ...(waitForStableUrlAfter
+      ? [
+          urlStableFor({
+            intervalMs: checkInterval,
+            stableForMs: checkInterval,
+            consecutiveSamples: stableChecks,
+          }),
+        ]
+      : []),
+    ...(waitForNetworkIdle ? [networkIdleFor()] : []),
+  ];
+  return runReadinessChecks({
+    checks: readiness,
+    deadline,
+    context: { page, networkTracker: options.networkTracker },
+  });
+}
+
+function navigationFailureStatus(error, signal) {
+  if (signal?.aborted) {
+    return 'interrupted';
+  }
+  if (error.status) {
+    return error.status;
+  }
+  if (error.name === 'TimeoutError') {
+    return 'timed_out';
+  }
+  return isNavigationError(error) || isActionStoppedError(error)
+    ? 'interrupted'
+    : null;
+}
+
 /**
  * Navigate to URL with full wait for page ready
  * @param {Object} options - Configuration options
@@ -232,14 +316,13 @@ export async function waitForUrlStabilization(options = {}) {
 export async function goto(options = {}) {
   const {
     page,
-    waitForUrlStabilization: stabilizeFn,
     navigationManager,
     log = { debug: () => {} },
     url,
     waitUntil = 'domcontentloaded',
     waitForStableUrlBefore = true,
     waitForStableUrlAfter = true,
-    waitForNetworkIdle: _waitForNetworkIdle = true,
+    waitForNetworkIdle = true,
     stableChecks = 3,
     checkInterval = 1000,
     timeout = 240000,
@@ -252,103 +335,95 @@ export async function goto(options = {}) {
     throw new Error('url is required in options');
   }
 
+  const { signal, checks } = options;
+  const deadline = options.deadline ?? createDeadline({ timeout, signal });
   const startUrl = page.url();
-
-  // If NavigationManager is available, use it for full navigation handling
-  if (navigationManager) {
-    try {
-      const navigated = await navigationManager.navigate({
-        url,
-        waitUntil,
-        timeout,
-      });
-
-      // Verify navigation if requested
-      if (verify && navigated) {
-        const verificationResult = await verifyNavigation({
+  try {
+    let outcome;
+    if (navigationManager) {
+      const result = await navigationPhase(deadline, () =>
+        navigationManager.navigate({
+          url,
+          waitUntil,
+          timeout,
+          deadline,
+          signal,
+          checks,
+          waitForStableUrlBefore,
+          waitForStableUrlAfter,
+          waitForNetworkIdle,
+          stableChecks,
+          checkInterval,
+          returnOutcome: true,
+        })
+      );
+      outcome =
+        typeof result === 'boolean'
+          ? { ready: result, status: result ? 'ready' : 'failed' }
+          : result;
+    } else {
+      outcome = await legacyGotoReadiness(
+        {
+          ...options,
+          waitUntil,
+          waitForStableUrlBefore,
+          waitForStableUrlAfter,
+          waitForNetworkIdle,
+          stableChecks,
+          checkInterval,
+        },
+        deadline
+      );
+    }
+    if (!outcome.ready) {
+      return {
+        navigated: false,
+        verified: false,
+        actualUrl: page.url(),
+        status: outcome.status,
+        readiness: outcome,
+      };
+    }
+    if (verify) {
+      const verified = await navigationPhase(deadline, () =>
+        verifyNavigation({
           page,
           expectedUrl: url,
           startUrl,
           verifyFn,
-          timeout: verificationTimeout,
+          timeout: Math.min(verificationTimeout, deadline.remainingMs()),
           log,
-        });
-
-        return {
-          navigated: true,
-          verified: verificationResult.verified,
-          actualUrl: verificationResult.actualUrl,
-          reason: verificationResult.reason,
-        };
-      }
-
-      return { navigated, verified: navigated, actualUrl: page.url() };
-    } catch (error) {
-      if (isNavigationError(error) || isActionStoppedError(error)) {
-        // Navigation was stopped by page trigger or navigation error
-        // This is not a failure - it means another action took over
-        return {
-          navigated: false,
-          verified: false,
-          reason: 'navigation stopped/interrupted',
-        };
-      }
-      throw error;
-    }
-  }
-
-  // Legacy approach without NavigationManager
-  try {
-    // Wait for URL to stabilize BEFORE navigation (to avoid interrupting natural redirects)
-    if (waitForStableUrlBefore && stabilizeFn) {
-      await stabilizeFn({
-        stableChecks,
-        checkInterval,
-        reason: 'before navigation',
-      });
-    }
-
-    // Navigate to the URL
-    await page.goto(url, { waitUntil, timeout });
-
-    // Wait for URL to stabilize AFTER navigation (to ensure all redirects are complete)
-    if (waitForStableUrlAfter && stabilizeFn) {
-      await stabilizeFn({
-        stableChecks,
-        checkInterval,
-        reason: 'after navigation',
-      });
-    }
-
-    // Verify navigation if requested
-    if (verify) {
-      const verificationResult = await verifyNavigation({
-        page,
-        expectedUrl: url,
-        startUrl,
-        verifyFn,
-        timeout: verificationTimeout,
-        log,
-      });
-
+          deadline: {
+            ...deadline,
+            remainingMs: () =>
+              Math.min(verificationTimeout, deadline.remainingMs()),
+          },
+        })
+      );
       return {
         navigated: true,
-        verified: verificationResult.verified,
-        actualUrl: verificationResult.actualUrl,
-        reason: verificationResult.reason,
+        ...verified,
+        status: verified.verified ? 'ready' : 'failed',
+        readiness: outcome,
       };
     }
-
-    return { navigated: true, verified: true, actualUrl: page.url() };
+    return {
+      navigated: true,
+      verified: true,
+      actualUrl: page.url(),
+      status: 'ready',
+      readiness: outcome,
+    };
   } catch (error) {
-    if (isNavigationError(error) || isActionStoppedError(error)) {
-      console.log(
-        '⚠️  Navigation was interrupted/stopped, recovering gracefully'
-      );
+    const status = navigationFailureStatus(error, signal);
+    if (status) {
+      navigationManager?.cancelNavigation?.();
       return {
         navigated: false,
         verified: false,
-        reason: 'navigation interrupted/stopped',
+        actualUrl: page.url(),
+        status,
+        reason: error.message,
       };
     }
     throw error;

package/src/browser/real-browser.js

@@ -1,3 +1,8 @@
+import { launchFailure, redactLaunchEvidence } from './launch-diagnostics.js';
+import {
+  installSessionPersistence,
+  sessionPersistencePath,
+} from './session-persistence.js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { findBrowserSource } from './browser-sources.js';
@@ -187,56 +192,66 @@ export async function waitForCdpEndpoint({
   timeout = 30_000,
   fetchImplementation = globalThis.fetch,
 }) {
-  const port = assertFixedDebuggingPort(remoteDebuggingPort);
-  const endpoint = `http://${LOOPBACK_HOST}:${port}`;
-  const deadline = Date.now() + timeout;
-  while (Date.now() < deadline) {
-    const output = devToolsOutput.state();
-    let ownership = devToolsOutput.available
-      ? classifyDevToolsOwnership(output, port)
-      : 'unknown';
-    if (ownership === 'race') {
-      throw new PortRaceError(port, output.listening?.url ?? 'bind failed');
-    }
-    if (browserProcess.exitCode !== null) {
-      throw new Error(
-        `Browser exited before its DevTools endpoint was ready (exit ${browserProcess.exitCode})`
-      );
-    }
-    if (ownership !== 'owned') {
-      const activePort = await readDevToolsActivePort(userDataDir);
-      if (activePort?.port === port) {
-        ownership = 'owned';
+  try {
+    const port = assertFixedDebuggingPort(remoteDebuggingPort);
+    const endpoint = `http://${LOOPBACK_HOST}:${port}`;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const output = devToolsOutput.state();
+      let ownership = devToolsOutput.available
+        ? classifyDevToolsOwnership(output, port)
+        : 'unknown';
+      if (ownership === 'race') {
+        throw new PortRaceError(port, output.listening?.url ?? 'bind failed');
       }
-    }
-
-    if (ownership === 'owned') {
-      let version = null;
-      try {
-        version = await fetchCdpVersion(
-          endpoint,
-          fetchImplementation,
-          Math.max(1, deadline - Date.now())
+      if (browserProcess.exitCode !== null) {
+        throw (
+          browserProcess.spawnError ??
+          Object.assign(
+            new Error(
+              `Browser exited before its DevTools endpoint was ready (exit ${browserProcess.exitCode})`
+            ),
+            { stderrTail: browserProcess.stderrTail }
+          )
         );
-      } catch {
-        // The HTTP handler can lag the listening line by a moment.
       }
-      if (version) {
-        const expected = output.listening?.url;
-        if (expected && version.webSocketDebuggerUrl !== expected) {
-          throw new PortRaceError(
-            port,
-            `port serves ${version.webSocketDebuggerUrl}, browser announced ${expected}`
+      if (ownership !== 'owned') {
+        const activePort = await readDevToolsActivePort(userDataDir);
+        if (activePort?.port === port) {
+          ownership = 'owned';
+        }
+      }
+
+      if (ownership === 'owned') {
+        let version = null;
+        try {
+          version = await fetchCdpVersion(
+            endpoint,
+            fetchImplementation,
+            Math.max(1, deadline - Date.now())
           );
+        } catch {
+          // The HTTP handler can lag the listening line by a moment.
+        }
+        if (version) {
+          const expected = output.listening?.url;
+          if (expected && version.webSocketDebuggerUrl !== expected) {
+            throw new PortRaceError(
+              port,
+              `port serves ${version.webSocketDebuggerUrl}, browser announced ${expected}`
+            );
+          }
+          return endpoint;
         }
-        return endpoint;
       }
+      await new Promise((resolve) => setTimeout(resolve, 100));
     }
-    await new Promise((resolve) => setTimeout(resolve, 100));
+    throw new Error(
+      `Timed out after ${timeout}ms waiting for the DevTools endpoint on port ${port}`
+    );
+  } finally {
+    devToolsOutput.dispose?.();
   }
-  throw new Error(
-    `Timed out after ${timeout}ms waiting for the DevTools endpoint on port ${port}`
-  );
 }
 
 function spawnWithStartProcess(executablePath, args, { env, verbose }) {
@@ -251,13 +266,19 @@ async function waitForExit(browserProcess, timeout) {
     return false;
   }
   let timer;
+  const onExit = () => resolveExit(true);
+  let resolveExit;
   const exited = await Promise.race([
-    new Promise((resolve) => browserProcess.once('exit', () => resolve(true))),
+    new Promise((resolve) => {
+      resolveExit = resolve;
+      browserProcess.once('exit', onExit);
+    }),
     new Promise((resolve) => {
       timer = setTimeout(() => resolve(false), timeout);
     }),
   ]);
   clearTimeout(timer);
+  browserProcess.removeListener?.('exit', onExit);
   return exited;
 }
 
@@ -369,6 +390,7 @@ async function spawnOnFreePort({
   userDataDir,
   startupTimeout,
   dependencies,
+  diagnostics,
 }) {
   const reservePort = dependencies.reservePort ?? reserveLoopbackPort;
   const spawnBrowser = dependencies.spawnBrowser ?? spawnWithStartProcess;
@@ -381,10 +403,20 @@ async function spawnOnFreePort({
       userDataDir,
       remoteDebuggingPort: port,
     });
-    const browserProcess = spawnBrowser(executablePath, browserArgs, {
-      env,
-      verbose,
-    });
+    let browserProcess;
+    try {
+      browserProcess = await spawnBrowser(executablePath, browserArgs, {
+        env,
+        verbose: false,
+      });
+    } catch (error) {
+      throw launchFailure(error, {
+        ...diagnostics,
+        phase: 'spawn',
+        executablePath,
+        userDataDir,
+      });
+    }
     try {
       const cdpEndpoint = await waitForEndpoint({
         remoteDebuggingPort: port,
@@ -397,13 +429,24 @@ async function spawnOnFreePort({
       if (browserProcess.exitCode === null) {
         browserProcess.kill();
       }
+      await waitForExit(browserProcess, 5_000);
       if (!(error instanceof PortRaceError) || attempt >= attempts) {
-        throw error;
+        throw launchFailure(error, {
+          ...diagnostics,
+          phase: 'endpoint',
+          browserProcess,
+          executablePath,
+          userDataDir,
+        });
       }
       if (verbose) {
-        console.log(`${error.message}; retrying with a new port`);
+        console.log(
+          redactLaunchEvidence(
+            `${error.message}; retrying with a new port`,
+            diagnostics?.diagnosticRedactor
+          )
+        );
       }
-      await waitForExit(browserProcess, 5_000);
     }
   }
 }
@@ -565,6 +608,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  sessionPersistencePath(options);
   if (isSafariChannel(options.channel ?? options.browser)) {
     return launchSafari(options, dependencies);
   }
@@ -614,10 +658,22 @@ export async function launchAndConnectRealBrowserWithDependencies(
 
   const resolveExecutable =
     dependencies.resolveExecutable ?? resolveSystemBrowserExecutable;
-  const executablePath = await resolveExecutable({
-    channel,
-    executablePath: requestedExecutablePath,
-  });
+  const launchChannel = attach?.browser ?? channel;
+  const executablePath = await Promise.resolve()
+    .then(() =>
+      resolveExecutable({
+        channel: launchChannel,
+        executablePath: requestedExecutablePath,
+      })
+    )
+    .catch((error) => {
+      throw launchFailure(error, {
+        ...options,
+        phase: 'discovery',
+        engine,
+        executablePath: requestedExecutablePath,
+      });
+    });
 
   const temporaryProfile = !requestedUserDataDir;
   const { userDataDir, snapshotLaunch } = await prepareProfile({
@@ -661,6 +717,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
       userDataDir,
       startupTimeout,
       dependencies,
+      diagnostics: { engine, diagnosticRedactor: options.diagnosticRedactor },
     })
   );
   const { browserProcess, cdpEndpoint: resolvedCdpEndpoint } = launched;
@@ -694,19 +751,22 @@ export async function launchAndConnectRealBrowserWithDependencies(
       closeTimeout,
       closeConnection: engine === 'selenium' ? connection.close : undefined,
     });
-    return {
-      ...connection,
-      close,
-      browserProcess,
-      cdpEndpoint: resolvedCdpEndpoint,
-      remoteDebuggingPort: launched.port,
-      executablePath,
-      userDataDir,
-      temporaryProfile,
-      args: launched.browserArgs,
-      ...(migration ? { migration } : {}),
-      ...(snapshotLaunch ? { attach: snapshotLaunch.attach } : {}),
-    };
+    return await installSessionPersistence(
+      {
+        ...connection,
+        close,
+        browserProcess,
+        cdpEndpoint: resolvedCdpEndpoint,
+        remoteDebuggingPort: launched.port,
+        executablePath,
+        userDataDir,
+        temporaryProfile,
+        args: launched.browserArgs,
+        ...(migration ? { migration } : {}),
+        ...(snapshotLaunch ? { attach: snapshotLaunch.attach } : {}),
+      },
+      options
+    );
   } catch (error) {
     if (browserProcess.exitCode === null) {
       browserProcess.kill();
@@ -715,7 +775,14 @@ export async function launchAndConnectRealBrowserWithDependencies(
     if (temporaryProfile) {
       await removeUserDataDir(userDataDir);
     }
-    throw error;
+    throw launchFailure(error, {
+      ...options,
+      phase: 'connect',
+      engine,
+      browserProcess,
+      executablePath,
+      userDataDir,
+    });
   }
 }