browser-commander 0.26.2 → 0.27.0

package/src/browser/session-cookies.js

@@ -0,0 +1,78 @@
+import { matchesDomains } from './migration/domains.js';
+import { restoreWebDriverStorageState } from './storage-state.js';
+
+/** Normalize cookie shape without turning session cookies into expired cookies. */
+export function normalizeSessionCookies(cookies, engine) {
+  if (!Array.isArray(cookies)) {
+    throw new TypeError('cookies must be an array');
+  }
+  return cookies.map(({ expires, ...cookie }) => ({
+    ...cookie,
+    ...(cookie.sameSite
+      ? {
+          sameSite:
+            cookie.sameSite[0].toUpperCase() +
+            cookie.sameSite.slice(1).toLowerCase(),
+        }
+      : {}),
+    ...(Number.isFinite(expires) && expires > 0
+      ? { expires }
+      : engine === 'playwright' && expires !== undefined
+        ? { expires: -1 }
+        : {}),
+  }));
+}
+
+/** Add cookies to the current context, including cookies for other origins. */
+export async function setCookies({ page, engine, cookies } = {}) {
+  const normalized = normalizeSessionCookies(cookies, engine);
+  if (engine === 'playwright') {
+    return page.context().addCookies(normalized);
+  }
+  if (engine === 'selenium' && !(await page.bidi?.())) {
+    return restoreWebDriverStorageState({
+      page,
+      storageState: { cookies: normalized, origins: [] },
+    });
+  }
+  const context = page.browserContext?.();
+  if (typeof context?.setCookie === 'function') {
+    return context.setCookie(...normalized);
+  }
+  if (typeof page.browser?.().setCookie === 'function') {
+    return page.browser().setCookie(...normalized);
+  }
+  return page.setCookie(...normalized);
+}
+
+/** Clear the context or only cookies whose domain matches the requested site. */
+export async function clearCookies({ page, engine, domain } = {}) {
+  if (engine === 'playwright' && !domain) {
+    return page.context().clearCookies();
+  }
+  const context =
+    engine === 'playwright' ? page.context() : page.browserContext?.();
+  const cookies =
+    engine === 'playwright'
+      ? await context.cookies()
+      : typeof context?.cookies === 'function'
+        ? await context.cookies()
+        : await page.cookies();
+  const selected = cookies.filter(
+    (cookie) => !domain || matchesDomains(cookie.domain, [domain])
+  );
+  if (engine === 'playwright') {
+    for (const cookie of selected) {
+      await context.clearCookies({
+        name: cookie.name,
+        domain: cookie.domain,
+        path: cookie.path,
+      });
+    }
+  } else if (typeof context?.deleteCookie === 'function') {
+    await context.deleteCookie(...selected);
+  } else {
+    await page.deleteCookie(...selected);
+  }
+  return selected.length;
+}

package/src/browser/session-persistence.js

@@ -0,0 +1,72 @@
+import path from 'node:path';
+import { access } from 'node:fs/promises';
+import { assertDedicatedUserDataDir } from './system-browser.js';
+import {
+  saveStorageState,
+  writeRestrictedState,
+  loadStorageState,
+  restorePlaywrightStorageState,
+  restorePuppeteerStorageState,
+  restoreWebDriverStorageState,
+} from './storage-state.js';
+
+const installed = Symbol('sessionPersistence');
+export function sessionPersistencePath(options) {
+  if (!options.persistSessionCookies) {
+    return null;
+  }
+  if (!options.userDataDir || options.attach) {
+    throw new TypeError(
+      'persistSessionCookies requires an explicit dedicated userDataDir'
+    );
+  }
+  assertDedicatedUserDataDir(options.userDataDir);
+  return typeof options.persistSessionCookies === 'string'
+    ? options.persistSessionCookies
+    : path.join(options.userDataDir, 'browser-commander-session.json');
+}
+export async function installSessionPersistence(result, options) {
+  const file = sessionPersistencePath(options);
+  if (!file || result[installed]) {
+    return result;
+  }
+  const engine = options.engine ?? 'playwright';
+  if (
+    await access(file).then(
+      () => true,
+      () => false
+    )
+  ) {
+    const storageState = await loadStorageState(file);
+    if (engine === 'playwright') {
+      await restorePlaywrightStorageState({
+        context: result.page.context(),
+        storageState,
+      });
+    } else if (engine === 'puppeteer') {
+      await restorePuppeteerStorageState({ page: result.page, storageState });
+    } else {
+      await restoreWebDriverStorageState({ page: result.page, storageState });
+    }
+  }
+  const close = result.close;
+  let closing;
+  const persistAndClose = () =>
+    (closing ??= (async () => {
+      try {
+        const state = await saveStorageState(result.page);
+        await writeRestrictedState(file, {
+          cookies: state.cookies.filter((cookie) => !(cookie.expires > 0)),
+          origins: [],
+        });
+      } finally {
+        await close();
+      }
+    })());
+  result.close = persistAndClose;
+  if (typeof result.browser?.close === 'function') {
+    result.browser.close = persistAndClose;
+  }
+  result[installed] = true;
+  return result;
+}

package/src/browser/storage-state.js

@@ -1,4 +1,6 @@
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile, writeFile, rename, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { normalizeSessionCookies } from './session-cookies.js';
 
 /**
  * Load a Playwright-compatible storage state from a JSON path or object.
@@ -91,7 +93,9 @@ export async function restorePuppeteerStorageState({ page, storageState }) {
 
   const cookies = storageState.cookies ?? [];
   if (cookies.length > 0) {
-    await page.setCookie(...cookies);
+    const context = page.browserContext?.();
+    const target = typeof context?.setCookie === 'function' ? context : page;
+    await target.setCookie(...normalizeSessionCookies(cookies, 'puppeteer'));
   }
 
   const origins = storageState.origins ?? [];
@@ -115,7 +119,7 @@ export async function restorePlaywrightStorageState({ context, storageState }) {
 
   const cookies = storageState.cookies ?? [];
   if (cookies.length > 0) {
-    await context.addCookies(cookies);
+    await context.addCookies(normalizeSessionCookies(cookies, 'playwright'));
   }
 
   const origins = storageState.origins ?? [];
@@ -137,7 +141,11 @@ function readCurrentLocalStorage() {
 }
 
 async function collectPuppeteerStorageState(page) {
-  const cookies = await page.cookies();
+  const context = page.browserContext?.();
+  const cookies =
+    typeof context?.cookies === 'function'
+      ? await context.cookies()
+      : await page.cookies();
   const pageUrl = page.url();
   const origin = new URL(pageUrl).origin;
   const origins = [];
@@ -161,7 +169,11 @@ async function collectPuppeteerStorageState(page) {
 export async function saveStorageState(page, filePath) {
   const context = typeof page.context === 'function' ? page.context() : null;
   if (typeof context?.storageState === 'function') {
-    return context.storageState(filePath ? { path: filePath } : undefined);
+    const state = await context.storageState();
+    if (filePath) {
+      await writeRestrictedState(filePath, state);
+    }
+    return state;
   }
 
   if (
@@ -174,7 +186,21 @@ export async function saveStorageState(page, filePath) {
 
   const storageState = await collectPuppeteerStorageState(page);
   if (filePath) {
-    await writeFile(filePath, `${JSON.stringify(storageState, null, 2)}\n`);
+    await writeRestrictedState(filePath, storageState);
   }
   return storageState;
 }
+
+/** Replace state atomically with an owner-only file, without following a destination symlink. */
+export async function writeRestrictedState(filePath, state) {
+  const temporary = `${filePath}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, {
+      mode: 0o600,
+      flag: 'wx',
+    });
+    await rename(temporary, filePath);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}

package/src/browser/system-browser.js

@@ -2,7 +2,7 @@ import { constants } from 'node:fs';
 import { physicalPath } from './browser-profile-files.js';
 import {
   BROWSER_SOURCES,
-  resolveBrowserRoots,
+  resolveBrowserProtectionRoots,
   resolveBrowserExecutables,
 } from './browser-sources.js';
 import { access } from 'node:fs/promises';
@@ -46,7 +46,7 @@ export function knownDefaultUserDataDirs({
   environment = process.env,
 } = {}) {
   return BROWSER_SOURCES.flatMap((browser) =>
-    resolveBrowserRoots(browser.id, {
+    resolveBrowserProtectionRoots(browser.id, {
       platform,
       homeDir,
       environment,

package/src/core/dialog-manager.js

@@ -111,6 +111,13 @@ export function createDialogManager(options = {}) {
     }
     handlers.push(handler);
     log.debug(() => `🔌 Dialog handler registered (total: ${handlers.length})`);
+    let removed = false;
+    return () => {
+      if (!removed) {
+        removed = true;
+        offDialog(handler);
+      }
+    };
   }
 
   /**

package/src/core/managed-navigation.js

@@ -0,0 +1,101 @@
+import { createDeadline, urlStableFor, networkIdleFor } from './readiness.js';
+import { navigationPhase } from './navigation-operation.js';
+import { isNavigationError } from './navigation-safety.js';
+
+/** Own a controlled navigation's deadline, policy and cancellation lifecycle. */
+export function createManagedNavigator({
+  page,
+  state,
+  config,
+  waitForReady,
+  triggerNavigationStart,
+  updateCurrentUrl,
+  abandonNavigation,
+}) {
+  async function navigate(opts = {}) {
+    const { url, waitUntil = 'domcontentloaded', timeout = 60000 } = opts;
+    if (!url) {
+      throw new Error('url is required in options');
+    }
+    state.activeOperation?.controller.abort();
+    const controller = new AbortController();
+    const signal = opts.signal
+      ? AbortSignal.any([opts.signal, controller.signal])
+      : controller.signal;
+    const deadline = opts.deadline ?? createDeadline({ timeout, signal });
+    // Keep a caller-provided deadline's clock, adding operation cancellation.
+    const budget = { ...deadline, signal };
+    const operation = { controller };
+    state.activeOperation = operation;
+    const stable = () =>
+      urlStableFor({
+        stableForMs:
+          opts.checkInterval === undefined
+            ? config.redirectStabilizationTime
+            : opts.checkInterval,
+        intervalMs: opts.checkInterval ?? 200,
+        consecutiveSamples: opts.stableChecks ?? 1,
+      });
+    try {
+      if (opts.waitForStableUrlBefore === true) {
+        const before = await waitForReady({
+          checks: [stable()],
+          deadline: budget,
+          reason: 'before goto',
+          observeOnly: true,
+        });
+        if (!before.ready) {
+          state.lastOutcome = before;
+          return opts.returnOutcome ? before : false;
+        }
+      }
+      await navigationPhase(budget, () =>
+        triggerNavigationStart({ url, isExternal: false, signal })
+      );
+      await navigationPhase(budget, () =>
+        page.goto(url, {
+          waitUntil,
+          timeout: Math.max(1, budget.remainingMs()),
+        })
+      );
+      updateCurrentUrl();
+      const checks = opts.checks ?? [
+        ...(opts.waitForStableUrlAfter === false ? [] : [stable()]),
+        ...(opts.waitForNetworkIdle === false ? [] : [networkIdleFor()]),
+      ];
+      state.lastOutcome = await waitForReady({
+        deadline: budget,
+        checks,
+        reason: 'after goto',
+        shouldNotify: () => state.activeOperation === operation,
+      });
+      return opts.returnOutcome ? state.lastOutcome : state.lastOutcome.ready;
+    } catch (error) {
+      if (
+        error.status ||
+        isNavigationError(error) ||
+        error.name === 'TimeoutError'
+      ) {
+        const status =
+          error.status ??
+          (error.name === 'TimeoutError' ? 'timed_out' : 'interrupted');
+        state.lastOutcome = {
+          ready: false,
+          status,
+          reason: error.message,
+          elapsedMs: budget.elapsedMs(),
+        };
+        return opts.returnOutcome ? state.lastOutcome : false;
+      }
+      throw error;
+    } finally {
+      controller.abort();
+      if (state.activeOperation === operation) {
+        state.activeOperation = null;
+        abandonNavigation('operation finished');
+      }
+    }
+  }
+
+  return navigate;
+}

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,
@@ -250,22 +277,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 +357,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 +375,7 @@ export function createNavigationManager(options = {}) {
       currentUrl,
       triggerNavigationStart,
       updateCurrentUrl: () => (currentUrl = page.url()),
-      waitForPageReady,
+      waitForReady,
       abandonNavigation,
     });
 
@@ -399,23 +392,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 +435,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 +464,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 +479,10 @@ export function createNavigationManager(options = {}) {
   return {
     // Navigation
     navigate,
+    cancelNavigation: () => {
+      state.activeOperation?.controller.abort();
+      abandonNavigation('caller stopped navigation');
+    },
     setContent,
     waitForNavigation,
     waitForPageReady,
@@ -507,6 +490,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;
+}