browser-commander 0.27.0 → 0.29.0

package/src/browser/session-adoption.js

@@ -0,0 +1,96 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { runCommand } from '../utilities/subprocess.js';
+
+/** Match both the dedicated profile and fixed port before adopting ownership. */
+export function matchesSessionProcess(args, options) {
+  if (
+    args.filter((arg) => arg.startsWith('--user-data-dir=')).length !== 1 ||
+    args.filter((arg) => arg.startsWith('--remote-debugging-port=')).length !==
+      1
+  ) {
+    return false;
+  }
+  const profile = args
+    .find((arg) => arg.startsWith('--user-data-dir='))
+    ?.slice(16);
+  const port = args
+    .find((arg) => arg.startsWith('--remote-debugging-port='))
+    ?.slice(24);
+  return (
+    /^(?:google[ -]chrome(?:[ -](?:for testing|stable|beta|unstable|canary|dev))?|chrome|chromium(?:-browser)?|brave(?: browser)?|microsoft edge|msedge)(?:\.exe)?$/i.test(
+      path.basename(args[0] ?? '')
+    ) &&
+    Boolean(profile) &&
+    path.resolve(profile) === path.resolve(options.userDataDir) &&
+    Number(port) === options.remoteDebuggingPort &&
+    !args.some((arg) => arg.startsWith('--type='))
+  );
+}
+export async function findSessionProcess(options) {
+  if (process.platform === 'linux') {
+    for (const name of await fs.readdir('/proc')) {
+      if (!/^\d+$/.test(name)) {
+        continue;
+      }
+      const args = await fs.readFile(`/proc/${name}/cmdline`, 'utf8').then(
+        (text) => text.split('\0'),
+        () => []
+      );
+      if (matchesSessionProcess(args, options)) {
+        return Number(name);
+      }
+    }
+  } else if (process.platform === 'darwin') {
+    const { stdout } = await runCommand('ps', ['-axo', 'pid=,command=']);
+    for (const line of stdout.split('\n')) {
+      const match = line.match(/^\s*(\d+)\s+(.+)$/);
+      if (!match) {
+        continue;
+      }
+      const args = processArguments(match[2]);
+      if (matchesSessionProcess(args, options)) {
+        return Number(match[1]);
+      }
+    }
+  } else if (process.platform === 'win32') {
+    const { stdout } = await runCommand('powershell.exe', [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      'Get-CimInstance Win32_Process | Where-Object { $_.Name -match "^(chrome|chromium|brave|msedge)\\.exe$" } | Select-Object ProcessId,ExecutablePath,CommandLine | ConvertTo-Json -Compress',
+    ]);
+    const records = JSON.parse(stdout || '[]');
+    for (const record of Array.isArray(records) ? records : [records]) {
+      const args = processArguments(record.CommandLine ?? '');
+      args[0] = record.ExecutablePath ?? args[0];
+      if (matchesSessionProcess(args, options)) {
+        return record.ProcessId;
+      }
+    }
+  }
+  throw new Error(
+    'Cannot verify the running browser profile and port for adoption'
+  );
+}
+
+/** Process listings omit argv boundaries; only accept unambiguous managed switches. */
+export function processArguments(command) {
+  if (
+    command.match(/--user-data-dir=/g)?.length !== 1 ||
+    command.match(/--remote-debugging-port=/g)?.length !== 1
+  ) {
+    return [];
+  }
+  const executable = command.match(/^"([^"\n]+)"|^(.*?)(?=\s--)/);
+  const profile = command.match(
+    /--user-data-dir=(?:"([^"\n]+)"|'([^'\n]+)'|(.+?))(?=\s--|$)/
+  );
+  const port = command.match(/--remote-debugging-port=(\d+)(?=\s|$)/);
+  return [
+    executable?.[1] ?? executable?.[2] ?? '',
+    `--user-data-dir=${profile?.[1] ?? profile?.[2] ?? profile?.[3] ?? ''}`,
+    `--remote-debugging-port=${port?.[1] ?? ''}`,
+    ...(command.includes('--type=') ? ['--type=child'] : []),
+  ];
+}

package/src/browser/session-watchdog.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import {
+  probeSession,
+  closeRemoteBrowser,
+  acquireLease,
+} from './persistent-session.js';
+const [, , file, token] = process.argv;
+const read = () =>
+  fs
+    .readFile(file, 'utf8')
+    .then(JSON.parse)
+    .catch(() => null);
+while (true) {
+  const session = await read();
+  if (session?.token !== token) {
+    break;
+  }
+  await new Promise((resolve) =>
+    setTimeout(
+      resolve,
+      Math.min(30_000, Math.max(100, session.idleTimeoutMs / 10))
+    )
+  );
+  const current = await read();
+  if (current?.token !== token) {
+    break;
+  }
+  if (Date.now() - current.lastActive < current.idleTimeoutMs) {
+    continue;
+  }
+  let release;
+  try {
+    release = await acquireLease(`${file}.lock`);
+  } catch {
+    continue;
+  }
+  try {
+    const version = await probeSession(
+      `http://127.0.0.1:${current.remoteDebuggingPort}`
+    );
+    const latest = await read();
+    if (latest?.token !== token) {
+      break;
+    }
+    if (Date.now() - latest.lastActive < latest.idleTimeoutMs) {
+      continue;
+    }
+    if (!version) {
+      try {
+        process.kill(current.pid, 0);
+        continue;
+      } catch (error) {
+        if (error.code !== 'ESRCH') {
+          continue;
+        }
+      }
+    } else if (version.webSocketDebuggerUrl === current.webSocketDebuggerUrl) {
+      try {
+        await closeRemoteBrowser(version.webSocketDebuggerUrl);
+      } catch {
+        continue;
+      }
+    }
+    if ((await read())?.token === token) {
+      await fs.rm(file, { force: true });
+    }
+    break;
+  } finally {
+    await release();
+  }
+}

package/src/browser/session-worker.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { connectBrowser } from './connector.js';
+import {
+  connectOrLaunch,
+  SESSION_METADATA,
+  closeOwnedSession,
+  writeSessionMetadata,
+  acquireLease,
+} from './persistent-session.js';
+let input = '';
+for await (const chunk of process.stdin) {
+  input += chunk;
+  if (input.length > 1024 * 1024) {
+    throw new RangeError('session options exceed 1 MiB');
+  }
+}
+const options = JSON.parse(input);
+const file = path.join(path.resolve(options.userDataDir), SESSION_METADATA);
+if (options.operation) {
+  const release = await acquireLease(`${file}.lock`);
+  try {
+    let metadata;
+    try {
+      metadata = JSON.parse(await fs.readFile(file, 'utf8'));
+    } catch (error) {
+      if (
+        error.code === 'ENOENT' &&
+        ['close', 'touch'].includes(options.operation)
+      ) {
+        process.stdout.write('{}');
+        process.exitCode = 0;
+      } else {
+        throw error;
+      }
+    }
+    if (metadata) {
+      if (metadata.token !== options.token) {
+        throw new Error('Persistent session ownership changed');
+      }
+      if (options.operation === 'close') {
+        await closeOwnedSession(file, metadata);
+      } else if (options.operation === 'touch') {
+        metadata.lastActive = Date.now();
+        if (options.targetId) {
+          metadata.targetId = options.targetId;
+        }
+        await writeSessionMetadata(file, metadata);
+        if (options.closeNewTabs) {
+          const connection = await connectBrowser({
+            cdpEndpoint: `http://127.0.0.1:${metadata.remoteDebuggingPort}`,
+            targetId: metadata.targetId,
+            singleTab: true,
+            noDefaults: true,
+          });
+          await connection.detach();
+        }
+      } else {
+        throw new TypeError('Unknown session operation');
+      }
+      process.stdout.write('{}');
+    }
+  } finally {
+    await release();
+  }
+} else {
+  const session = await connectOrLaunch(options);
+  await session.detach();
+  const metadata = JSON.parse(await fs.readFile(file, 'utf8'));
+  process.stdout.write(
+    JSON.stringify({
+      cdpEndpoint: session.cdpEndpoint,
+      userDataDir: session.userDataDir,
+      remoteDebuggingPort: session.remoteDebuggingPort,
+      reused: session.reused,
+      token: metadata.token,
+      targetId: metadata.targetId,
+      idleTimeoutMs: metadata.idleTimeoutMs,
+      adopted: session.adopted,
+    })
+  );
+}

package/src/browser/webdriver.js

@@ -326,6 +326,7 @@ export function buildBrowserOptions({
   remoteDebuggingPort,
   headless,
   restrictions,
+  disableFeatures,
   args,
   automationParity,
   bidi,
@@ -358,6 +359,7 @@ export function buildBrowserOptions({
       remoteDebuggingPort,
       headless,
       restrictions,
+      disableFeatures,
       args,
       automationParity,
     });
@@ -556,6 +558,7 @@ async function launchWebDriverOnce(options, dependencies) {
     bidi = false,
     args = [],
     restrictions = [],
+    disableFeatures = [],
     automationParity = true,
     env,
     startupTimeout = 30_000,
@@ -627,6 +630,7 @@ async function launchWebDriverOnce(options, dependencies) {
         browser === 'chrome' ? await reservePort() : undefined,
       headless,
       restrictions,
+      disableFeatures,
       args,
       automationParity,
       bidi,

package/src/capture/encoding.js

@@ -0,0 +1,327 @@
+import { writeCapture } from './files.js';
+import fs from 'node:fs/promises';
+import { deflateSync } from 'node:zlib';
+import UPNG from 'upng-js';
+import webp from 'webp-wasm';
+import gifenc from 'gifenc';
+import { UnsupportedCaptureError } from './errors.js';
+const { GIFEncoder, quantize, applyPalette } = gifenc;
+
+export function resizeFrame(frame, scale = 1, size) {
+  const width = size?.width ?? Math.max(1, Math.round(frame.width * scale));
+  const height = size?.height ?? Math.max(1, Math.round(frame.height * scale));
+  if (
+    !Number.isSafeInteger(width) ||
+    !Number.isSafeInteger(height) ||
+    width < 1 ||
+    height < 1 ||
+    width * height > 16_777_216
+  ) {
+    throw new RangeError(
+      'capture dimensions must be positive integers within 16 megapixels'
+    );
+  }
+  const data = new Uint8Array(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const source =
+        (Math.min(frame.height - 1, Math.floor((y * frame.height) / height)) *
+          frame.width +
+          Math.min(frame.width - 1, Math.floor((x * frame.width) / width))) *
+        4;
+      data.set(frame.data.subarray(source, source + 4), (y * width + x) * 4);
+    }
+  }
+  return { width, height, data };
+}
+export function decodePng(bytes) {
+  const data = Buffer.from(bytes);
+  if (
+    data.length < 33 ||
+    !data.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+  ) {
+    throw new RangeError('frame must be a PNG');
+  }
+  const pixels = data.readUInt32BE(16) * data.readUInt32BE(20);
+  if (pixels < 1 || pixels > 16_777_216) {
+    throw new RangeError('PNG exceeds 16 megapixels');
+  }
+  const decoded = UPNG.decode(
+    data.buffer.slice(data.byteOffset, data.byteOffset + data.length)
+  );
+  return {
+    width: decoded.width,
+    height: decoded.height,
+    data: new Uint8Array(UPNG.toRGBA8(decoded)[0]),
+  };
+}
+export function encodePng(frame) {
+  return Buffer.from(
+    UPNG.encode(
+      [
+        frame.data.buffer.slice(
+          frame.data.byteOffset,
+          frame.data.byteOffset + frame.data.length
+        ),
+      ],
+      frame.width,
+      frame.height,
+      0,
+      undefined,
+      true
+    )
+  );
+}
+
+function chunk(tag, data) {
+  const header = Buffer.alloc(8);
+  header.write(tag);
+  header.writeUInt32LE(data.length, 4);
+  return Buffer.concat([
+    header,
+    data,
+    ...(data.length % 2 ? [Buffer.alloc(1)] : []),
+  ]);
+}
+function write24(buffer, value, offset) {
+  buffer.writeUIntLE(value, offset, 3);
+}
+async function animatedWebp(frames, { fps, quality = 75, loop = 0 }) {
+  const { width, height } = frames[0];
+  const extended = Buffer.alloc(10);
+  extended[0] = 0x12;
+  write24(extended, width - 1, 4);
+  write24(extended, height - 1, 7);
+  const animation = Buffer.alloc(6);
+  animation.writeUInt16LE(loop, 4);
+  const chunks = [chunk('VP8X', extended), chunk('ANIM', animation)];
+  for (const frame of frames) {
+    const encoded = await webp.encode(frame, { quality });
+    const imageChunks = [];
+    for (let offset = 12; offset < encoded.length;) {
+      const length = encoded.readUInt32LE(offset + 4);
+      const tag = encoded.subarray(offset, offset + 4).toString();
+      if (['ALPH', 'VP8 ', 'VP8L'].includes(tag)) {
+        imageChunks.push(
+          encoded.subarray(offset, offset + 8 + length + (length % 2))
+        );
+      }
+      offset += 8 + length + (length % 2);
+    }
+    const header = Buffer.alloc(16);
+    write24(header, width - 1, 6);
+    write24(header, height - 1, 9);
+    write24(header, Math.round(1000 / fps), 12);
+    header[15] = 2;
+    chunks.push(chunk('ANMF', Buffer.concat([header, ...imageChunks])));
+  }
+  const payload = Buffer.concat([Buffer.from('WEBP'), ...chunks]);
+  const header = Buffer.alloc(8);
+  header.write('RIFF');
+  header.writeUInt32LE(payload.length, 4);
+  return Buffer.concat([header, payload]);
+}
+
+function pngChunk(tag, data) {
+  const bytes = Buffer.alloc(data.length + 12);
+  bytes.writeUInt32BE(data.length);
+  bytes.write(tag, 4);
+  data.copy(bytes, 8);
+  bytes.writeUInt32BE(
+    UPNG.crc.crc(bytes, 4, data.length + 4) >>> 0,
+    data.length + 8
+  );
+  return bytes;
+}
+function animatedPng(frames, fps, loop, optimize) {
+  const { width, height } = frames[0];
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  const animation = Buffer.alloc(8);
+  animation.writeUInt32BE(frames.length);
+  animation.writeUInt32BE(loop, 4);
+  const chunks = [
+    Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    pngChunk('IHDR', ihdr),
+    pngChunk('acTL', animation),
+  ];
+  let sequence = 0;
+  for (const [index, frame] of frames.entries()) {
+    const control = Buffer.alloc(26);
+    control.writeUInt32BE(sequence++);
+    control.writeUInt32BE(width, 4);
+    control.writeUInt32BE(height, 8);
+    control.writeUInt16BE(Math.round(1000 / fps), 20);
+    control.writeUInt16BE(1000, 22);
+    chunks.push(pngChunk('fcTL', control));
+    const scanlines = Buffer.alloc(height * (width * 4 + 1));
+    for (let y = 0; y < height; y++) {
+      scanlines.set(
+        frame.data.subarray(y * width * 4, (y + 1) * width * 4),
+        y * (width * 4 + 1) + 1
+      );
+    }
+    const compressed = deflateSync(scanlines, { level: optimize ? 9 : 1 });
+    if (index === 0) {
+      chunks.push(pngChunk('IDAT', compressed));
+    } else {
+      const number = Buffer.alloc(4);
+      number.writeUInt32BE(sequence++);
+      chunks.push(pngChunk('fdAT', Buffer.concat([number, compressed])));
+    }
+  }
+  chunks.push(pngChunk('IEND', Buffer.alloc(0)));
+  return Buffer.concat(chunks);
+}
+function ditherPalette(frame, palette) {
+  const data = Float32Array.from(frame.data);
+  const pixels = new Uint8Array(frame.width * frame.height);
+  const transparent = palette.findIndex((color) => color[3] === 0);
+  const add = (x, y, channel, error, weight) => {
+    if (x >= 0 && x < frame.width && y < frame.height) {
+      data[(y * frame.width + x) * 4 + channel] += error * weight;
+    }
+  };
+  for (let y = 0; y < frame.height; y++) {
+    for (let x = 0; x < frame.width; x++) {
+      const offset = (y * frame.width + x) * 4;
+      if (data[offset + 3] < 128 && transparent >= 0) {
+        pixels[y * frame.width + x] = transparent;
+        continue;
+      }
+      let best = 0,
+        distance = Infinity;
+      for (let i = 0; i < palette.length; i++) {
+        if (i === transparent) {
+          continue;
+        }
+        const delta = palette[i]
+          .slice(0, 3)
+          .reduce((sum, value, c) => sum + (data[offset + c] - value) ** 2, 0);
+        if (delta < distance) {
+          distance = delta;
+          best = i;
+        }
+      }
+      pixels[y * frame.width + x] = best;
+      for (let c = 0; c < 3; c++) {
+        const error = data[offset + c] - palette[best][c];
+        add(x + 1, y, c, error, 7 / 16);
+        add(x - 1, y + 1, c, error, 3 / 16);
+        add(x, y + 1, c, error, 5 / 16);
+        add(x + 1, y + 1, c, error, 1 / 16);
+      }
+    }
+  }
+  return pixels;
+}
+
+/** Portable GIF/APNG/WebP animation from PNG bytes or paths. */
+export async function encodeAnimation(input, options = {}) {
+  const {
+    format = 'gif',
+    fps = 10,
+    scale = 1,
+    loop = 0,
+    palette = 256,
+    dither = false,
+    optimize = true,
+    path: output,
+  } = options;
+  validateAnimation(input, { fps, scale, loop, dither, format });
+  const frames = [];
+  let decodedBytes = 0;
+  for (const value of input) {
+    const png = typeof value === 'string' ? await fs.readFile(value) : value;
+    const data = Buffer.from(png);
+    if (data.length < 33) {
+      throw new RangeError('frame must be a PNG');
+    }
+    const sourceBytes = data.readUInt32BE(16) * data.readUInt32BE(20) * 4;
+    const targetBytes = options.size
+      ? options.size.width * options.size.height * 4
+      : sourceBytes * Math.max(1, scale * scale);
+    if (decodedBytes + sourceBytes + targetBytes > 256 * 1024 * 1024) {
+      throw new RangeError('decoded animation exceeds 256 MiB');
+    }
+    const frame = resizeFrame(decodePng(data), scale, options.size);
+    decodedBytes += frame.data.length;
+    frames.push(frame);
+  }
+  const { width, height } = frames[0];
+  if (
+    frames.some((frame) => frame.width !== width || frame.height !== height)
+  ) {
+    throw new RangeError('animation frames must have equal dimensions');
+  }
+  if (frames.length * width * height * 4 > 256 * 1024 * 1024) {
+    throw new RangeError('decoded animation exceeds 256 MiB');
+  }
+  let bytes;
+  if (format === 'gif') {
+    bytes = encodeGif(frames, { width, height, palette, dither, fps, loop });
+  } else if (format === 'apng') {
+    bytes = animatedPng(frames, fps, loop, optimize);
+  } else if (format === 'webp') {
+    bytes = await animatedWebp(frames, { ...options, fps, loop });
+  } else {
+    throw new UnsupportedCaptureError(format, 'animation encoder');
+  }
+  if (bytes.length > 64 * 1024 * 1024) {
+    throw new RangeError('encoded animation exceeds 64 MiB');
+  }
+  return writeCapture(bytes, output);
+}
+
+function validateAnimation(input, { fps, scale, loop, dither, format }) {
+  if (
+    !Number.isFinite(fps) ||
+    fps < 1 ||
+    fps > 60 ||
+    !Number.isFinite(scale) ||
+    scale <= 0 ||
+    scale > 8
+  ) {
+    throw new RangeError('fps must be 1–60 and scale must be >0 and <=8');
+  }
+  if (!Number.isInteger(loop) || loop < 0 || loop > 65535) {
+    throw new RangeError('loop must be 0–65535');
+  }
+  if (dither && format !== 'gif') {
+    throw new UnsupportedCaptureError('dither', format);
+  }
+  if (!Array.isArray(input) || input.length === 0 || input.length > 1000) {
+    throw new RangeError('animation requires 1–1000 frames');
+  }
+}
+function encodeGif(frames, { width, height, palette, dither, fps, loop }) {
+  if (
+    !Array.isArray(palette) &&
+    (!Number.isInteger(palette) || palette < 2 || palette > 256)
+  ) {
+    throw new RangeError('palette must be 2–256 colors or a palette array');
+  }
+  const gif = GIFEncoder();
+  for (const frame of frames) {
+    const colors = Array.isArray(palette)
+      ? palette
+      : quantize(frame.data, palette, { format: 'rgba4444' });
+    const pixels = dither
+      ? ditherPalette(frame, colors)
+      : applyPalette(frame.data, colors, 'rgba4444');
+    const transparentIndex = colors.findIndex((color) => color[3] === 0);
+    gif.writeFrame(pixels, width, height, {
+      palette: colors,
+      delay: 1000 / fps,
+      repeat: loop,
+      dispose: 2,
+      transparent: transparentIndex >= 0,
+      transparentIndex: Math.max(0, transparentIndex),
+    });
+  }
+  gif.finish();
+  return Buffer.from(gif.bytes());
+}

package/src/capture/errors.js

@@ -0,0 +1,12 @@
+/** A requested capture capability is unavailable on this engine or codec. */
+export class UnsupportedCaptureError extends Error {
+  constructor(capability, engine, cause) {
+    super(`Capture capability "${capability}" is unavailable on ${engine}`, {
+      cause,
+    });
+    this.name = 'UnsupportedCaptureError';
+    this.code = 'UNSUPPORTED_CAPTURE';
+    this.capability = capability;
+    this.engine = engine;
+  }
+}

package/src/capture/files.js

@@ -0,0 +1,9 @@
+import fs from 'node:fs/promises';
+
+/** Return capture bytes and optionally persist them with private permissions. */
+export async function writeCapture(bytes, output) {
+  if (output) {
+    await fs.writeFile(output, bytes, { mode: 0o600 });
+  }
+  return bytes;
+}

package/src/capture/index.js

@@ -0,0 +1,5 @@
+export { UnsupportedCaptureError } from './errors.js';
+export { screenshot } from './screenshot.js';
+export { encodeAnimation } from './encoding.js';
+export { startRecording } from './recording.js';
+export { encodeVideo } from './video.js';