browser-commander 0.27.0 → 0.29.0

package/src/capture/recording.js

@@ -0,0 +1,136 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { screenshot } from './screenshot.js';
+import {
+  encodeAnimation,
+  decodePng,
+  encodePng,
+  resizeFrame,
+} from './encoding.js';
+import { encodeVideo } from './video.js';
+import { UnsupportedCaptureError } from './errors.js';
+
+/** A bounded, sequential screenshot recorder, usable on attached sessions. */
+export async function startRecording(options = {}) {
+  options = { ...options, path: options.path ?? options.output };
+  const {
+    fps = 10,
+    maxFrames = 1000,
+    maxBytes = 64 * 1024 * 1024,
+    maxDurationMs = 60_000,
+    format = 'webm',
+  } = options;
+  if (
+    !Number.isFinite(fps) ||
+    fps < 1 ||
+    fps > 60 ||
+    !Number.isSafeInteger(maxFrames) ||
+    maxFrames < 1 ||
+    maxFrames > 1000 ||
+    !Number.isFinite(maxDurationMs) ||
+    maxDurationMs <= 0 ||
+    !Number.isSafeInteger(maxBytes) ||
+    maxBytes < 1
+  ) {
+    throw new RangeError('invalid recording bounds');
+  }
+  if (
+    !['frames', 'gif', 'apng', 'webp', 'webm', 'mp4', 'mov'].includes(format)
+  ) {
+    throw new UnsupportedCaptureError(format, options.engine);
+  }
+  if (['webm', 'mp4', 'mov'].includes(format) && !options.ffmpeg) {
+    const supported = await options.page.evaluate(
+      (format) =>
+        globalThis.MediaRecorder?.isTypeSupported(
+          { webm: 'video/webm', mp4: 'video/mp4' }[format] ?? ''
+        ) ?? false,
+      format
+    );
+    if (!supported) {
+      throw new UnsupportedCaptureError(
+        format,
+        options.engine ?? 'MediaRecorder'
+      );
+    }
+  }
+  const frames = [];
+  const controller = new AbortController();
+  let bytes = 0,
+    failure,
+    stopping,
+    truncated = false;
+  const started = performance.now();
+  const grab = async () => {
+    let data = await screenshot({
+      page: options.page,
+      engine: options.engine,
+      ...(options.screenshot ?? {}),
+      format: 'png',
+    });
+    if (options.size) {
+      data = encodePng(resizeFrame(decodePng(data), 1, options.size));
+    }
+    if (bytes + data.length > maxBytes) {
+      truncated = true;
+      return false;
+    }
+    frames.push(data);
+    bytes += data.length;
+    return true;
+  };
+  if (!(await grab())) {
+    throw new RangeError('The first recording frame exceeds maxBytes');
+  }
+  const task = (async () => {
+    while (!controller.signal.aborted) {
+      try {
+        await delay(Math.max(1, 1000 / fps), undefined, {
+          signal: controller.signal,
+        });
+      } catch {
+        break;
+      }
+      if (
+        frames.length >= maxFrames ||
+        performance.now() - started >= maxDurationMs
+      ) {
+        truncated = true;
+        break;
+      }
+      try {
+        if (!(await grab())) {
+          break;
+        }
+      } catch (error) {
+        failure = error;
+        break;
+      }
+    }
+  })();
+  const stop = (stopOptions = {}) => {
+    stopping ??= (async () => {
+      controller.abort();
+      await task;
+      if (failure) {
+        throw failure;
+      }
+      const encoding = { ...options, format, ...stopOptions, fps };
+      const data =
+        encoding.format === 'frames'
+          ? null
+          : ['gif', 'apng', 'webp'].includes(encoding.format)
+            ? await encodeAnimation(frames, encoding)
+            : await encodeVideo(frames, encoding);
+      return {
+        frames,
+        bytes: data,
+        path: encoding.path ?? null,
+        format: encoding.format,
+        fps,
+        truncated,
+      };
+    })();
+    return stopping;
+  };
+  return { stop, frames, fps };
+}

package/src/capture/screenshot.js

@@ -0,0 +1,222 @@
+import { writeCapture } from './files.js';
+import path from 'node:path';
+import webp from 'webp-wasm';
+import { decodePng, encodePng, resizeFrame } from './encoding.js';
+import { UnsupportedCaptureError } from './errors.js';
+import { captureStableViewport, validateStableViewport } from './viewport.js';
+
+/**
+ * @typedef {Object} ScreenshotOptions
+ * @property {string} [path]
+ * @property {boolean} [fullPage]
+ * @property {boolean} [stableViewport] Capture only the existing view without visual styling.
+ * @property {string} [selector]
+ * @property {Object} [element]
+ * @property {{x:number,y:number,width:number,height:number}} [clip]
+ * @property {string} [format] png, jpeg or webp
+ * @property {number} [quality]
+ * @property {string} [scale] css or device
+ * @property {boolean} [omitBackground]
+ * @property {string} [animations] allow or disabled
+ * @property {string} [caret] hide or initial
+ * @property {boolean} [hideScrollbars]
+ * @property {boolean} [hideCaret]
+ * @property {boolean} [disableAnimations]
+ * @property {boolean} [waitForFonts]
+ */
+export async function screenshot(options = {}) {
+  const {
+    page,
+    engine = 'playwright',
+    selector,
+    element,
+    clip,
+    fullPage = false,
+    scale = 'device',
+    quality,
+    path: output,
+  } = options;
+  if (
+    !['playwright', 'puppeteer', 'selenium', 'chromiumoxide'].includes(
+      engine
+    ) ||
+    typeof page?.screenshot !== 'function'
+  ) {
+    throw new UnsupportedCaptureError('screenshot', engine);
+  }
+  const { format, animations, caret } = validateScreenshot(options);
+  const native = {
+    type: format === 'webp' ? 'png' : format,
+    fullPage,
+    ...(clip ? { clip } : {}),
+    ...(format === 'jpeg' && quality !== undefined ? { quality } : {}),
+  };
+  if (options.omitBackground) {
+    if (engine === 'selenium') {
+      throw new UnsupportedCaptureError('omitBackground', engine);
+    }
+    native.omitBackground = true;
+  }
+  const css = captureStyle(options, animations, caret);
+  if (options.waitForFonts) {
+    await page.evaluate(() => document.fonts.ready.then(() => true));
+  }
+  if (options.stableViewport) {
+    if (engine === 'playwright') {
+      native.scale = scale;
+      native.caret = 'initial';
+    }
+    const captured = await captureStableViewport(page, engine, native);
+    return finishScreenshot(captured.bytes, {
+      page,
+      engine: captured.engine,
+      scale,
+      format,
+      quality,
+      output,
+    });
+  }
+  let styleId;
+  if (engine === 'playwright') {
+    Object.assign(native, {
+      scale,
+      animations,
+      caret: 'initial',
+      ...(css ? { style: css } : {}),
+    });
+  } else if (css) {
+    styleId = await page.evaluate((css) => {
+      const style = document.createElement('style');
+      style.id = `browser-commander-capture-${Math.random().toString(36).slice(2)}`;
+      style.textContent = css;
+      document.documentElement.appendChild(style);
+      return style.id;
+    }, css);
+  }
+  let target = page;
+  try {
+    if (selector || element) {
+      target =
+        element ??
+        (engine === 'playwright'
+          ? page.locator(selector).first()
+          : await page.$(selector));
+      if (!target) {
+        throw new Error(`No element matches ${selector}`);
+      }
+      if (typeof target.screenshot !== 'function') {
+        throw new UnsupportedCaptureError('element screenshot', engine);
+      }
+      delete native.fullPage;
+    }
+    return await finishScreenshot(
+      Buffer.from(await target.screenshot(native)),
+      { page, engine, scale, format, quality, output }
+    );
+  } finally {
+    if (styleId) {
+      await page.evaluate(
+        (id) => document.getElementById(id)?.remove(),
+        styleId
+      );
+    }
+  }
+}
+
+async function finishScreenshot(
+  bytes,
+  { page, engine, scale, format, quality, output }
+) {
+  if (scale === 'css' && engine !== 'playwright') {
+    if (format === 'jpeg') {
+      throw new UnsupportedCaptureError('JPEG CSS scale', engine);
+    }
+    const ratio = await page.evaluate(() => window.devicePixelRatio);
+    if (ratio !== 1) {
+      bytes = encodePng(resizeFrame(decodePng(bytes), 1 / ratio));
+    }
+  }
+  if (format === 'webp') {
+    bytes = await webp.encode(decodePng(bytes), { quality: quality ?? 75 });
+  }
+  return writeCapture(bytes, output);
+}
+
+function validateScreenshot(options) {
+  const engine = options.engine ?? 'playwright';
+  const {
+    path: output,
+    quality,
+    scale = 'device',
+    selector,
+    element,
+    clip,
+    fullPage,
+  } = options;
+  const extension = output ? path.extname(output).slice(1).toLowerCase() : '';
+  const format =
+    options.format ??
+    options.type ??
+    (extension === 'jpg'
+      ? 'jpeg'
+      : ['png', 'jpeg', 'webp'].includes(extension)
+        ? extension
+        : 'png');
+  if (!['png', 'jpeg', 'webp'].includes(format)) {
+    throw new UnsupportedCaptureError(format, engine);
+  }
+  if (
+    quality !== undefined &&
+    (!Number.isInteger(quality) ||
+      quality < 0 ||
+      quality > 100 ||
+      format === 'png')
+  ) {
+    throw new RangeError('quality must be an integer 0–100 for JPEG/WebP');
+  }
+  if (!['css', 'device'].includes(scale)) {
+    throw new RangeError('scale must be css or device');
+  }
+  if ([selector || element, clip, fullPage].filter(Boolean).length > 1) {
+    throw new RangeError(
+      'selector/element, clip and fullPage are mutually exclusive'
+    );
+  }
+  if (
+    clip &&
+    (!['x', 'y', 'width', 'height'].every((key) =>
+      Number.isFinite(clip[key])
+    ) ||
+      clip.x < 0 ||
+      clip.y < 0 ||
+      clip.width <= 0 ||
+      clip.height <= 0)
+  ) {
+    throw new RangeError(
+      'clip must have nonnegative coordinates and positive dimensions'
+    );
+  }
+  const animations =
+    options.animations ?? (options.disableAnimations ? 'disabled' : 'allow');
+  const caret = options.caret ?? (options.hideCaret ? 'hide' : 'initial');
+  validateStableViewport(options, animations, caret);
+  if (
+    !['allow', 'disabled'].includes(animations) ||
+    !['hide', 'initial'].includes(caret)
+  ) {
+    throw new RangeError('invalid animations/caret option');
+  }
+  return { format, animations, caret };
+}
+
+function captureStyle(options, animations, caret) {
+  return [
+    options.hideScrollbars
+      ? '*::-webkit-scrollbar{display:none!important}*{scrollbar-width:none!important}'
+      : '',
+    caret === 'hide' ? '*{caret-color:transparent!important}' : '',
+    animations === 'disabled'
+      ? '*,*::before,*::after{animation:none!important;transition:none!important}'
+      : '',
+  ].join('');
+}

package/src/capture/video.js

@@ -0,0 +1,186 @@
+import { writeCapture } from './files.js';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { runCommand } from '../utilities/subprocess.js';
+import { decodePng } from './encoding.js';
+import { UnsupportedCaptureError } from './errors.js';
+
+/** Optional binary backend; never inferred from PATH or invoked by default. */
+export async function encodeVideo(frames, options = {}) {
+  if (!Array.isArray(frames) || frames.length < 1 || frames.length > 1000) {
+    throw new RangeError('video requires 1–1000 frames');
+  }
+  if (
+    !Number.isFinite(options.fps ?? 10) ||
+    (options.fps ?? 10) < 1 ||
+    (options.fps ?? 10) > 60
+  ) {
+    throw new RangeError('fps must be 1–60');
+  }
+  if (
+    options.quality !== undefined &&
+    (!Number.isInteger(options.quality) ||
+      options.quality < 0 ||
+      options.quality > 100)
+  ) {
+    throw new RangeError('quality must be 0–100');
+  }
+  if (frames.reduce((sum, frame) => sum + frame.length, 0) > 64 * 1024 * 1024) {
+    throw new RangeError('video frames exceed 64 MiB');
+  }
+  for (const frame of frames) {
+    decodePng(frame);
+  }
+  if (!options.ffmpeg) {
+    if (!options.page?.evaluate) {
+      throw new UnsupportedCaptureError(
+        options.format ?? 'webm',
+        'video encoder (provide a page or set ffmpeg explicitly)'
+      );
+    }
+    const result = await options.page.evaluate(encodeVideoInPage, {
+      frames: frames.map((frame) => frame.toString('base64')),
+      format: options.format ?? 'webm',
+      fps: options.fps ?? 10,
+      quality: options.quality,
+      size: options.size,
+    });
+    if (result.unsupported) {
+      throw new UnsupportedCaptureError(
+        options.format ?? 'webm',
+        options.engine ?? 'MediaRecorder'
+      );
+    }
+    const bytes = Buffer.from(result.data);
+    return writeCapture(bytes, options.path);
+  }
+  return encodeFfmpeg(frames, options);
+}
+
+async function encodeFfmpeg(frames, options) {
+  const directory = await fs.mkdtemp(
+    path.join(os.tmpdir(), 'commander-video-')
+  );
+  try {
+    for (let i = 0; i < frames.length; i++) {
+      await fs.writeFile(
+        path.join(directory, `${String(i).padStart(6, '0')}.png`),
+        frames[i]
+      );
+    }
+    const output = path.join(directory, `output.${options.format ?? 'webm'}`);
+    const codec = { mp4: 'libx264', webm: 'libvpx-vp9', mov: 'libx264' }[
+      options.format ?? 'webm'
+    ];
+    if (!codec) {
+      throw new UnsupportedCaptureError(options.format, 'ffmpeg');
+    }
+    const args = [
+      '-y',
+      '-framerate',
+      String(options.fps ?? 10),
+      '-i',
+      path.join(directory, '%06d.png'),
+      '-c:v',
+      codec,
+      '-pix_fmt',
+      'yuv420p',
+      '-crf',
+      String(Math.round(51 * (1 - (options.quality ?? 75) / 100))),
+      ...(options.size
+        ? ['-vf', `scale=${options.size.width}:${options.size.height}`]
+        : []),
+      output,
+    ];
+    try {
+      await runCommand(
+        options.ffmpeg === true ? 'ffmpeg' : options.ffmpeg,
+        args
+      );
+    } catch (cause) {
+      throw new UnsupportedCaptureError('ffmpeg', 'video encoder', cause);
+    }
+    const bytes = await fs.readFile(output);
+    return writeCapture(bytes, options.path);
+  } finally {
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+}
+
+/** Browser-native encoding on a detached canvas; no live DOM markers. */
+export async function encodeVideoInPage({
+  frames,
+  format,
+  fps,
+  quality,
+  size,
+}) {
+  const mimeType = { webm: 'video/webm', mp4: 'video/mp4' }[format];
+  if (!mimeType || !globalThis.MediaRecorder?.isTypeSupported(mimeType)) {
+    return { unsupported: true };
+  }
+  const image = new globalThis.Image();
+  image.src = `data:image/png;base64,${frames[0]}`;
+  await image.decode();
+  const canvas = document.createElement('canvas');
+  canvas.width = size?.width ?? image.width;
+  canvas.height = size?.height ?? image.height;
+  if (
+    !Number.isInteger(canvas.width) ||
+    canvas.width < 1 ||
+    !Number.isInteger(canvas.height) ||
+    canvas.height < 1 ||
+    canvas.width * canvas.height > 16_777_216
+  ) {
+    throw new RangeError('video canvas exceeds 16 megapixels');
+  }
+  const context = canvas.getContext('2d');
+  const stream = canvas.captureStream(fps);
+  const chunks = [];
+  let encodedBytes = 0;
+  const recorder = new globalThis.MediaRecorder(stream, {
+    mimeType,
+    videoBitsPerSecond: Math.max(
+      100_000,
+      Math.round((quality ?? 75) * 100_000)
+    ),
+  });
+  const done = new Promise((resolve, reject) => {
+    recorder.ondataavailable = (event) => {
+      encodedBytes += event.data.size;
+      if (encodedBytes > 64 * 1024 * 1024) {
+        reject(new RangeError('encoded video exceeds 64 MiB'));
+      } else {
+        chunks.push(event.data);
+      }
+    };
+    recorder.onerror = (event) =>
+      reject(event.error ?? new Error('Video encoding failed'));
+    recorder.onstop = resolve;
+  });
+  // Keep early codec failures handled while frames are still being decoded.
+  done.catch(() => {});
+  try {
+    recorder.start();
+    for (const bytes of frames) {
+      image.src = `data:image/png;base64,${bytes}`;
+      await image.decode();
+      context.clearRect(0, 0, canvas.width, canvas.height);
+      context.drawImage(image, 0, 0, canvas.width, canvas.height);
+      await new Promise((resolve) => setTimeout(resolve, 1000 / fps));
+    }
+    recorder.stop();
+    await done;
+    return {
+      data: Array.from(
+        new Uint8Array(await new Blob(chunks, { type: mimeType }).arrayBuffer())
+      ),
+    };
+  } finally {
+    if (recorder.state !== 'inactive') {
+      recorder.stop();
+    }
+    stream.getTracks().forEach((track) => track.stop());
+  }
+}

package/src/capture/viewport.js

@@ -0,0 +1,68 @@
+import { createCdpSession } from '../browser/cdp-session.js';
+
+export function validateStableViewport(options, animations, caret) {
+  const changes = [
+    options.selector,
+    options.element,
+    options.clip,
+    options.fullPage,
+    options.omitBackground,
+    options.hideScrollbars,
+    animations !== 'allow',
+    caret !== 'initial',
+  ];
+  if (options.stableViewport && changes.some(Boolean)) {
+    throw new RangeError(
+      'stableViewport requires the unmodified viewport: no region, background or visual styling options'
+    );
+  }
+}
+
+/** Capture the existing view; never scroll, resize, activate, or capture beyond it. */
+export async function captureStableViewport(page, engine, native) {
+  // Native-view capture bypasses emulated pixel density. Keep the engine's viewport path.
+  const viewport =
+    engine === 'playwright' ? page.viewportSize?.() : page.viewport?.();
+  if (viewport) {
+    return { bytes: Buffer.from(await page.screenshot(native)), engine };
+  }
+  let session;
+  if (
+    (engine === 'playwright' && typeof page.context === 'function') ||
+    (engine === 'puppeteer' &&
+      (typeof page.createCDPSession === 'function' ||
+        typeof page.target === 'function'))
+  ) {
+    try {
+      session = await createCdpSession(page, { engine });
+    } catch (error) {
+      if (
+        error.name !== 'UnsupportedOperation' &&
+        !/only supported by Chromium|CDP.*not supported|CDP.*unsupported|CDP support is required|does not support CDP/i.test(
+          error.message
+        )
+      ) {
+        throw error;
+      }
+    }
+  }
+  if (session) {
+    try {
+      const { data } = await session.send('Page.captureScreenshot', {
+        format: native.type,
+        fromSurface: false,
+        captureBeyondViewport: false,
+        ...(native.quality === undefined ? {} : { quality: native.quality }),
+      });
+      return { bytes: Buffer.from(data, 'base64'), engine: 'cdp' };
+    } catch (error) {
+      // Some headless builds cannot capture a native view. Preserve every other error.
+      if (!/Unable to capture screenshot/i.test(error.message)) {
+        throw error;
+      }
+    } finally {
+      await session.detach();
+    }
+  }
+  return { bytes: Buffer.from(await page.screenshot(native)), engine };
+}

package/src/capture/worker.js

@@ -0,0 +1,22 @@
+/** Companion codec worker for Rust. Uses the same bounded portable encoders. */
+import { encodeAnimation, encodeVideo } from './index.js';
+let input = '';
+for await (const chunk of process.stdin) {
+  input += chunk;
+  if (input.length > 96 * 1024 * 1024) {
+    throw new RangeError('codec input exceeds 96 MiB');
+  }
+}
+try {
+  const { frames, options } = JSON.parse(input);
+  const data = frames.map((frame) => Buffer.from(frame, 'base64'));
+  const result = ['webm', 'mp4', 'mov'].includes(options.format)
+    ? await encodeVideo(data, options)
+    : await encodeAnimation(data, options);
+  process.stdout.write(JSON.stringify({ data: result.toString('base64') }));
+} catch (error) {
+  process.stdout.write(
+    JSON.stringify({ error: { code: error.code, message: error.message } })
+  );
+  process.exitCode = 1;
+}