browser-commander 0.26.3 → 0.28.0

package/src/browser/launcher.js

@@ -1,7 +1,13 @@
 import { access } from 'node:fs/promises';
+import { launchFailure } from './launch-diagnostics.js';
+import {
+  installSessionPersistence,
+  sessionPersistencePath,
+} from './session-persistence.js';
 
 import { assertSupportedEngine } from './connector.js';
 import { emulateMedia } from './media.js';
+import { reserveLoopbackPort } from './debugging-port.js';
 import {
   buildPlaywrightLaunchOptions,
   buildPuppeteerLaunchOptions,
@@ -9,6 +15,7 @@ import {
 } from './launch-options.js';
 import {
   createTemporaryUserDataDir,
+  configureUserDataDir,
   removeUserDataDir,
 } from './profile-directory.js';
 import { launchRealBrowser } from './real-browser.js';
@@ -163,6 +170,7 @@ async function launchWithEngine(options, dependencies) {
     extraArgs,
     ignoreDefaultArgs,
     restrictions,
+    disableFeatures: options.disableFeatures,
   });
   const restrictionEnv = resolveRestrictions(restrictions).env;
   const childEnv =
@@ -172,6 +180,13 @@ async function launchWithEngine(options, dependencies) {
   const temporaryProfile = !requestedUserDataDir;
   const userDataDir =
     requestedUserDataDir ?? (await createTemporaryUserDataDir());
+  await configureUserDataDir(userDataDir, {
+    preferences: {
+      ...resolveRestrictions(restrictions).preferences,
+      ...options.preferences,
+    },
+    localState: options.localState,
+  });
   const engineModule = await (
     dependencies.loadEngineModule ?? loadEngine[engine]
   )();
@@ -302,6 +317,16 @@ export async function launchBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  if (options.keepOpen) {
+    const { connectOrLaunch } = await import('./persistent-session.js');
+    return connectOrLaunch({
+      ...options,
+      userDataDir: options.userDataDir ?? (await createTemporaryUserDataDir()),
+      remoteDebuggingPort:
+        options.remoteDebuggingPort ?? (await reserveLoopbackPort()),
+    });
+  }
+  sessionPersistencePath(options);
   if (isSafariChannel(options.channel ?? options.browser)) {
     validateLaunchMode({
       engine: options.engine ?? 'playwright',
@@ -310,7 +335,13 @@ export async function launchBrowserWithDependencies(
     });
     return await launchSafari(options, dependencies);
   }
-  return await launchNonSafariBrowser(options, dependencies);
+  const result = await launchNonSafariBrowser(options, dependencies);
+  try {
+    return await installSessionPersistence(result, options);
+  } catch (error) {
+    await result.close();
+    throw error;
+  }
 }
 
 async function launchNonSafariBrowser(options, dependencies) {
@@ -343,7 +374,13 @@ async function launchNonSafariBrowser(options, dependencies) {
     }
   }
   // Validate arguments before anything is started or written to disk.
-  resolveChromeArgs({ args, extraArgs, ignoreDefaultArgs, restrictions });
+  resolveChromeArgs({
+    args,
+    extraArgs,
+    ignoreDefaultArgs,
+    restrictions,
+    disableFeatures: options.disableFeatures,
+  });
   const resolvedStorageState = await loadStorageState(storageState);
 
   if (verbose) {
@@ -361,13 +398,21 @@ async function launchNonSafariBrowser(options, dependencies) {
     automationParity,
     storageState: resolvedStorageState,
   };
-  const launched =
-    launch === 'engine'
-      ? await launchWithEngine(
-          { ...common, ignoreDefaultArgs, colorScheme },
-          dependencies
-        )
-      : await launchReal(common, dependencies);
+  let launched;
+  try {
+    launched =
+      launch === 'engine'
+        ? await launchWithEngine(
+            { ...common, ignoreDefaultArgs, colorScheme },
+            dependencies
+          )
+        : await launchReal(common, dependencies);
+  } catch (error) {
+    throw launchFailure(error, {
+      ...common,
+      phase: launch === 'engine' ? 'engine_launch' : 'launch',
+    });
+  }
   const { browser, page } = launched;
   if (verbose) {
     console.log(`✅ Browser launched with ${engine} engine`);

package/src/browser/migration/sqlite-snapshot.js

@@ -3,9 +3,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { pathExists } from './fs-utils.js';
 
-import BetterSqlite3 from 'better-sqlite3';
-
-import { openSqliteDatabase } from '../browser-cookie-database.js';
+import {
+  openSqliteDatabase,
+  backupSqliteDatabase,
+} from '../browser-cookie-database.js';
 
 /**
  * Read a Chromium SQLite database (History, Top Sites, Login Data, Web Data)
@@ -40,36 +41,13 @@ export async function withDatabaseSnapshot({ sourcePath, read }) {
   try {
     // The backup API needs to open the source. It opens read-only, so nothing
     // is written to the user's real database.
-    let source;
     try {
-      source = new BetterSqlite3(sourcePath, {
-        readonly: true,
-        fileMustExist: true,
-        timeout: 1000,
-      });
-      // Detect an exclusive lock before better-sqlite3's initial zero-page
-      // transfer can mistake SQLITE_BUSY for an empty completed backup.
-      source.pragma('schema_version');
-      let remaining = Infinity;
-      let lastProgress = Date.now();
-      await source.backup(snapshotPath, {
-        progress: ({ remainingPages }) => {
-          if (remainingPages < remaining) {
-            lastProgress = Date.now();
-          } else if (Date.now() - lastProgress >= 1000) {
-            throw new Error('SQLite backup made no progress');
-          }
-          remaining = remainingPages;
-          return 256;
-        },
-      });
+      await backupSqliteDatabase(sourcePath, snapshotPath);
     } catch (cause) {
       throw new Error(
         `Consistent SQLite snapshot unavailable for ${sourcePath}; close the source browser and retry, or supply a consistent read-only snapshot. ${cause.message}`,
         { cause }
       );
-    } finally {
-      source?.close();
     }
     return await read(snapshotPath);
   } finally {

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;