browser-commander 0.26.3 → 0.28.0

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,8 @@ 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.serverUrl ? { serverUrl: options.serverUrl } : {}),
             ...(options.driverPath ? { driverPath: options.driverPath } : {}),
             ...(options.bidi !== undefined ? { bidi: options.bidi } : {}),
@@ -145,7 +251,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 +448,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,9 @@ async function connectSession(state, params) {
   const connected = await state.dependencies.connectBrowser({
     engine,
     ...endpoint,
+    ...(params.targetId ? { targetId: params.targetId } : {}),
+    ...(params.urlMatcher ? { url: params.urlMatcher } : {}),
+    ...(params.singleTab !== undefined ? { singleTab: params.singleTab } : {}),
     ...(params.driverPath ? { driverPath: params.driverPath } : {}),
     ...(params.bidi !== undefined ? { bidi: params.bidi } : {}),
   });
@@ -111,12 +118,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 +375,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,9 @@ const LAUNCH_PASSTHROUGH = Object.freeze([
   'driverPath',
   'bidi',
   'seedCookies',
+  'disableFeatures',
+  'keepOpen',
+  'idleTimeoutMs',
 ]);
 
 /** Validate an engine name, defaulting to Playwright. */
@@ -121,20 +124,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 +212,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,105 @@
+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 });
+  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/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;
+}