browser-commander 0.27.0 → 0.29.0

package/src/cli/args.js

@@ -33,6 +33,11 @@ const BROWSER_OPTIONS = Object.freeze({
   'first-run': FLAG,
   'driver-path': STRING,
   bidi: FLAG,
+  'remote-debugging-port': STRING,
+  'idle-timeout-ms': STRING,
+  'adopt-existing': FLAG,
+  'close-new-tabs': FLAG,
+  'no-defaults': FLAG,
 });
 
 /** Options accepted by every page command. */
@@ -41,8 +46,40 @@ const PAGE_OPTIONS = Object.freeze({
   'cdp-endpoint': STRING,
   'server-url': STRING,
   url: STRING,
+  'target-id': STRING,
+  'single-tab': FLAG,
 });
 
+const CAPTURE_OPTIONS = {
+  format: STRING,
+  quality: STRING,
+  fps: STRING,
+  scale: STRING,
+  loop: STRING,
+  palette: STRING,
+  dither: FLAG,
+  optimize: FLAG,
+  ffmpeg: STRING,
+  size: STRING,
+};
+const SCREENSHOT_OPTIONS = {
+  ...PAGE_OPTIONS,
+  'full-page': FLAG,
+  'stable-viewport': FLAG,
+  selector: STRING,
+  clip: STRING,
+  format: STRING,
+  quality: STRING,
+  scale: STRING,
+  'omit-background': FLAG,
+  animations: STRING,
+  caret: STRING,
+  'hide-scrollbars': FLAG,
+  'hide-caret': FLAG,
+  'disable-animations': FLAG,
+  'wait-for-fonts': FLAG,
+};
+
 /**
  * Every command: its positional argument names and its options.
  * Two-word commands (`trace start`) are keyed by both words.
@@ -66,12 +103,36 @@ export const COMMANDS = Object.freeze({
   eval: { positionals: ['expression'], options: PAGE_OPTIONS },
   screenshot: {
     positionals: ['path'],
-    options: { ...PAGE_OPTIONS, 'full-page': FLAG },
+    options: SCREENSHOT_OPTIONS,
   },
   pdf: { positionals: ['path'], options: PAGE_OPTIONS },
   'trace start': { positionals: [], options: { ...PAGE_OPTIONS, out: STRING } },
   'trace stop': { positionals: [], options: { out: STRING } },
   'trace view': { positionals: ['dir'], options: { out: STRING } },
+  'trace summarize': {
+    positionals: ['dir'],
+    options: { from: STRING, to: STRING, grep: STRING },
+  },
+  'trace render': {
+    positionals: ['dir'],
+    options: { ...CAPTURE_OPTIONS, out: STRING, from: STRING, to: STRING },
+  },
+  'record start': {
+    positionals: [],
+    options: {
+      ...PAGE_OPTIONS,
+      ...CAPTURE_OPTIONS,
+      out: STRING,
+      'max-frames': STRING,
+      'max-bytes': STRING,
+      'max-duration-ms': STRING,
+    },
+  },
+  'record stop': { positionals: [], options: { out: STRING } },
+  gif: {
+    positionals: [],
+    options: { ...CAPTURE_OPTIONS, frame: STRINGS, out: STRING },
+  },
   'cookies import': {
     positionals: [],
     options: {
@@ -255,6 +316,13 @@ export function launchParams(options) {
     firstRun: options.firstRun,
     driverPath: options.driverPath,
     bidi: options.bidi,
+    keepOpen: options.keepOpen,
+    remoteDebuggingPort: integerOption(
+      options,
+      'remoteDebuggingPort',
+      'launch'
+    ),
+    idleTimeoutMs: integerOption(options, 'idleTimeoutMs', 'launch'),
   };
   return Object.fromEntries(
     Object.entries(params).filter(([, value]) => value !== undefined)

package/src/cli/commands.js

@@ -22,6 +22,110 @@ import { createDispatcher } from './dispatcher.js';
 import { DEFAULT_DEPENDENCIES } from './modules.js';
 import { runScript } from './script.js';
 import { serveStdio } from './serve.js';
+import { encodeAnimation } from '../capture/index.js';
+import { renderTrace, summarizeTrace } from '../traces/render.js';
+
+function mediaOptions(options) {
+  const result = { ...options };
+  for (const key of [
+    'quality',
+    'fps',
+    'loop',
+    'palette',
+    'maxFrames',
+    'maxBytes',
+    'maxDurationMs',
+  ]) {
+    if (options[key] !== undefined) {
+      result[key] = Number(options[key]);
+    }
+  }
+  if (
+    options.scale !== undefined &&
+    !['css', 'device'].includes(options.scale)
+  ) {
+    result.scale = Number(options.scale);
+  }
+  for (const key of ['clip', 'size']) {
+    if (options[key]) {
+      try {
+        result[key] = JSON.parse(options[key]);
+      } catch {
+        throw new UsageError(`${key} must be a JSON object`);
+      }
+    }
+  }
+  return result;
+}
+
+async function gif(parsed) {
+  const target = path.resolve(requireOption(parsed.options, 'out', 'gif'));
+  const bytes = await encodeAnimation(parsed.options.frame ?? [], {
+    ...mediaOptions(parsed.options),
+    path: target,
+  });
+  return done({ path: target, bytes: bytes.length });
+}
+async function traceSummarize(parsed) {
+  return done(await summarizeTrace(parsed.args.dir, parsed.options));
+}
+async function traceRender(parsed) {
+  const target = path.resolve(
+    requireOption(parsed.options, 'out', 'trace render')
+  );
+  const options = { ...mediaOptions(parsed.options), path: target };
+  let browser;
+  try {
+    if (
+      ['webm', 'mp4', 'mov'].includes(
+        options.format ?? path.extname(target).slice(1)
+      ) &&
+      !options.ffmpeg
+    ) {
+      const { chromium } = await import('playwright');
+      browser = await chromium.launch({ headless: true });
+      options.page = await browser.newPage();
+    }
+    const bytes = await renderTrace(parsed.args.dir, options);
+    return done({ path: target, bytes: bytes.length });
+  } finally {
+    await browser?.close();
+  }
+}
+function recordStart(parsed, io) {
+  const target = path.resolve(
+    requireOption(parsed.options, 'out', 'record start')
+  );
+  const marker = `${target}.stop`;
+  return withPageSession(parsed, io, async (session, dispatcher) => {
+    await rm(marker, { force: true });
+    await dispatcher.dispatch('record.start', {
+      session,
+      ...mediaOptions(parsed.options),
+      format: parsed.options.format ?? path.extname(target).slice(1),
+      path: target,
+    });
+    let stopped = false;
+    try {
+      io.print({ recording: target });
+      await waitForStop({
+        signals: io.signals,
+        extra: [markerAppears(marker, () => stopped)],
+      });
+      return done(await dispatcher.dispatch('record.stop', { session }));
+    } finally {
+      stopped = true;
+      await rm(marker, { force: true });
+    }
+  });
+}
+async function recordStop(parsed) {
+  const target = path.resolve(
+    requireOption(parsed.options, 'out', 'record stop')
+  );
+  await writeFile(`${target}.stop`, '', { mode: 0o600 });
+  return done({ recording: target, stopRequested: true });
+}
 
 /** Where `trace stop` asks a running `trace start` to finish. */
 export const TRACE_STOP_MARKER = '.stop';
@@ -80,6 +184,11 @@ async function withPageSession(parsed, io, work, { skipUrl = false } = {}) {
         ? await dispatcher.dispatch('session.connect', {
             cdpEndpoint: options.cdpEndpoint,
             engine: options.engine,
+            targetId: options.targetId,
+            singleTab: options.singleTab,
+            ...(options.noDefaults !== undefined
+              ? { noDefaults: options.noDefaults }
+              : {}),
             ...(options.serverUrl ? { serverUrl: options.serverUrl } : {}),
             ...(options.driverPath ? { driverPath: options.driverPath } : {}),
             ...(options.bidi !== undefined ? { bidi: options.bidi } : {}),
@@ -145,7 +254,7 @@ async function launch(parsed, io) {
       args: session.args,
       ...(opened.attach ? { attach: opened.attach } : {}),
     };
-    if (!parsed.options.keepOpen) {
+    if (!parsed.options.keepOpen || session.persistent) {
       return done(document);
     }
     io.print(document);
@@ -342,13 +451,18 @@ export const COMMAND_HANDLERS = Object.freeze({
     expression: args.expression,
   })),
   screenshot: pageCommand('page.screenshot', ({ args, options }) => ({
+    ...mediaOptions(options),
     path: args.path,
-    fullPage: options.fullPage === true,
   })),
   pdf: pageCommand('page.pdf', ({ args }) => ({ path: args.path })),
   'trace start': traceStart,
   'trace stop': traceStop,
   'trace view': traceView,
+  'trace summarize': traceSummarize,
+  'trace render': traceRender,
+  'record start': recordStart,
+  'record stop': recordStop,
+  gif,
   'cookies import': pageCommand('cookies.import', ({ options }) => ({
     from: requireOption(options, 'from', 'cookies import'),
     profile: options.profile,

package/src/cli/high-level-methods.js

@@ -7,6 +7,10 @@
  * dispatcher state built by `createDispatcher()`.
  */
 import path from 'node:path';
+import {
+  screenshot as captureScreenshot,
+  startRecording,
+} from '../capture/index.js';
 
 import { invalidParams, requireString } from './rpc-error.js';
 import {
@@ -24,7 +28,7 @@ async function launchSession(state, params) {
   const options = buildLaunchOptions(params);
   const launched = await state.dependencies.launchBrowser(options);
   const session = state.sessions.add(
-    sessionFromLaunch(options.engine, launched)
+    sessionFromLaunch(options.engine, launched, options)
   );
   return {
     session,
@@ -48,6 +52,16 @@ async function connectSession(state, params) {
   const connected = await state.dependencies.connectBrowser({
     engine,
     ...endpoint,
+    ...(params.targetId ? { targetId: params.targetId } : {}),
+    ...(params.urlMatcher ? { url: params.urlMatcher } : {}),
+    ...(params.noDefaults !== undefined
+      ? { noDefaults: params.noDefaults }
+      : {}),
+    ...(params.urlMatchers !== undefined
+      ? { urlMatchers: params.urlMatchers }
+      : {}),
+    ...(params.fallback !== undefined ? { fallback: params.fallback } : {}),
+    ...(params.singleTab !== undefined ? { singleTab: params.singleTab } : {}),
     ...(params.driverPath ? { driverPath: params.driverPath } : {}),
     ...(params.bidi !== undefined ? { bidi: params.bidi } : {}),
   });
@@ -111,12 +125,40 @@ async function capture(params, write) {
 }
 
 function screenshot(state, params) {
-  const { page } = sessionOf(state, params);
+  const { page, engine } = sessionOf(state, params);
   return capture(params, (options) =>
-    page.screenshot({ ...options, fullPage: params.fullPage === true })
+    captureScreenshot({ ...params, ...options, page, engine })
   );
 }
 
+async function recordStart(state, params) {
+  const session = sessionOf(state, params);
+  if (session.recording) {
+    throw invalidParams('A recording is already active');
+  }
+  session.recording = await startRecording({
+    ...params,
+    page: session.page,
+    engine: session.engine,
+  });
+  return { recording: true };
+}
+async function recordStop(state, params) {
+  const session = sessionOf(state, params);
+  if (!session.recording) {
+    throw invalidParams('No recording is active');
+  }
+  const recording = session.recording;
+  session.recording = null;
+  const result = await recording.stop(params);
+  return {
+    path: result.path,
+    bytes: result.bytes?.length ?? 0,
+    frames: result.frames.length,
+    truncated: result.truncated,
+  };
+}
+
 function pdf(state, params) {
   const { page } = sessionOf(state, params);
   return capture(params, (options) => page.pdf(options));
@@ -340,6 +382,8 @@ export const HIGH_LEVEL_METHODS = Object.freeze({
   'page.pdf': pdf,
   'trace.start': traceStart,
   'trace.stop': traceStop,
+  'record.start': recordStart,
+  'record.stop': recordStop,
   'cookies.import': importCookies,
   'cookies.sources': cookieSources,
   'profile.migrate': migrateProfile,

package/src/cli/sessions.js

@@ -44,6 +44,12 @@ const LAUNCH_PASSTHROUGH = Object.freeze([
   'driverPath',
   'bidi',
   'seedCookies',
+  'disableFeatures',
+  'keepOpen',
+  'idleTimeoutMs',
+  'adoptExisting',
+  'closeNewTabs',
+  'noDefaults',
 ]);
 
 /** Validate an engine name, defaulting to Playwright. */
@@ -121,20 +127,24 @@ export function buildLaunchOptions(params = {}) {
  * CDP-connected `Browser` as `connectedBrowser`; the engine launch returns a
  * persistent context whose `browser()` is null. Puppeteer returns a Browser.
  */
-export function sessionFromLaunch(engine, launched) {
+export function sessionFromLaunch(engine, launched, { keepOpen = false } = {}) {
   engine = launched.engine ?? engine;
   const playwright = engine === 'playwright';
   const handle = launched.browser;
+  const persistent = keepOpen && Boolean(launched.detach);
   return {
     engine,
     browser: playwright
       ? (launched.connectedBrowser ?? handle?.browser?.() ?? null)
       : handle,
-    context: playwright ? handle : (handle?.defaultBrowserContext?.() ?? null),
+    context: playwright
+      ? (launched.page?.context?.() ?? handle)
+      : (handle?.defaultBrowserContext?.() ?? null),
     page: launched.page,
     driver: launched.driver ?? (engine === 'selenium' ? handle : null),
     args: launched.args ?? [],
-    close: () => launched.close(),
+    close: () => (persistent ? launched.detach() : launched.close()),
+    persistent,
     connected: false,
   };
 }
@@ -205,6 +215,7 @@ export class SessionTable {
       this.latest = [...this.sessions.keys()].at(-1) ?? null;
     }
     await session.trace?.stop?.().catch(() => {});
+    await session.recording?.stop?.().catch(() => {});
     await session.close();
   }
 

package/src/core/commander-features.js

@@ -0,0 +1,110 @@
+import { startTrace } from '../traces/recorder.js';
+import { touchSessionPage } from '../browser/persistent-session.js';
+import { dismissOverlays } from '../interactions/overlays.js';
+import {
+  screenshot,
+  startRecording,
+  encodeAnimation,
+} from '../capture/index.js';
+
+const INTERACTIONS = new Set([
+  'clickButton',
+  'clickElement',
+  'fillTextArea',
+  'check',
+  'pressKey',
+]);
+
+/** Bind capture, persistence and opt-in debugging to the commander lifecycle. */
+export function attachCommanderFeatures(commander, options, recreate) {
+  const { page, engine } = commander;
+  const managed = new Set();
+  function track(item) {
+    const stop = item.stop.bind(item);
+    let stopping;
+    item.stop = (...args) => {
+      stopping ??= Promise.resolve()
+        .then(() => stop(...args))
+        .finally(() => managed.delete(item));
+      return stopping;
+    };
+    managed.add(item);
+    return item;
+  }
+  commander.screenshot = (captureOptions = {}) =>
+    screenshot({ ...options.capture, ...captureOptions, page, engine });
+  commander.startRecording = async (recordingOptions = {}) =>
+    track(await startRecording({ ...recordingOptions, page, engine }));
+  commander.gif = (frames, animationOptions = {}) =>
+    encodeAnimation(frames, { ...animationOptions, format: 'gif' });
+  commander.dismissOverlays = (overlays = options.overlays) =>
+    dismissOverlays({
+      page,
+      engine,
+      overlays,
+      onDismiss: options.onOverlayDismiss,
+    });
+  commander.startTrace = async (traceOptions = {}) =>
+    track(await startTrace({ commander, page, ...traceOptions }));
+  const output =
+    options.debug?.output ??
+    options.output ??
+    process.env.BROWSER_COMMANDER_TRACE;
+  let debug;
+  const ensureDebug = async () => {
+    if (!output || (!options.debug && !process.env.BROWSER_COMMANDER_TRACE)) {
+      return;
+    }
+    debug ??= commander.startTrace({
+      output,
+      mode: 'continuous',
+      network: { har: true },
+      links: { output: `${output}.links`, dom: 'text' },
+      checkpointOnNavigation: true,
+    });
+    await debug;
+  };
+  for (const name of [...INTERACTIONS, 'goto', 'evaluate', 'count']) {
+    const method = commander[name];
+    if (!method) {
+      continue;
+    }
+    commander[name] = async (...args) => {
+      touchSessionPage(page);
+      await ensureDebug();
+      if (INTERACTIONS.has(name)) {
+        await commander.dismissOverlays();
+      }
+      return method(...args);
+    };
+  }
+  const destroy = commander.destroy;
+  commander.destroy = async () => {
+    try {
+      if (debug) {
+        await debug;
+      }
+      await Promise.all([...managed].map((item) => item.stop()));
+    } finally {
+      await destroy();
+    }
+  };
+  commander.reusePage = async (selection = {}) => {
+    if (!options.session?.reusePage) {
+      throw new Error('reusePage requires a persistent session');
+    }
+    const selected = await options.session.reusePage(selection);
+    if (selected !== page) {
+      await commander.destroy();
+      Object.assign(
+        commander,
+        recreate({ ...options, page: selected, downloads: null })
+      );
+    }
+    touchSessionPage(selected);
+    return selected;
+  };
+  if (options.debug || process.env.BROWSER_COMMANDER_TRACE) {
+    commander.ready = ensureDebug();
+  }
+}

package/src/core/constants.js

@@ -15,6 +15,7 @@ export const CHROME_ARGS = [
   '--no-first-run',
   '--no-default-browser-check',
   '--disable-crash-restore',
+  '--disable-features=SessionRestoreInfobar',
 ];
 
 /**

package/src/core/navigation-manager.js

@@ -257,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 }),
   });

package/src/core/navigation-readiness.js

@@ -12,6 +12,7 @@ import {
   networkIdleFor,
   runReadinessChecks,
   urlStableFor,
+  stableCheck,
 } from './readiness.js';
 
 /**
@@ -113,7 +114,7 @@ export function createReadinessWaiter(options = {}) {
     let result;
     try {
       result = await runReadinessChecks({
-        checks: checks ?? defaultReadinessChecks(config),
+        checks: checks ?? checksForReadiness(opts.readyOn, config),
         deadline,
         context: {
           page,
@@ -135,7 +136,7 @@ export function createReadinessWaiter(options = {}) {
 
     if (outcome.ready) {
       if (notify()) {
-        onReady();
+        onReady(opts.readyOn ?? 'networkidle');
       }
       log.debug(() => `✅ Page ready after ${outcome.elapsedMs}ms (${reason})`);
     } else {
@@ -155,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,12 +8,64 @@
  * @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;
   }
 
   const navigationErrorPatterns = [
+    'net::ERR_ABORTED',
     'Execution context was destroyed',
     'detached Frame',
     'Target closed',