@monoes/monobrowse 1.0.0

package/src/browser/pdf.ts

@@ -0,0 +1,41 @@
+import type { CdpClient } from './cdp.js';
+import { writeFile } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+export interface PdfOptions {
+  path?: string;
+  landscape?: boolean;
+  paperWidth?: number;
+  paperHeight?: number;
+  marginTop?: number;
+  marginBottom?: number;
+  marginLeft?: number;
+  marginRight?: number;
+  printBackground?: boolean;
+  scale?: number;
+}
+
+export async function capturePdf(
+  client: CdpClient,
+  sessionId: string,
+  options: PdfOptions = {}
+): Promise<string> {
+  const params: Record<string, unknown> = {
+    landscape: options.landscape ?? false,
+    printBackground: options.printBackground ?? true,
+    scale: options.scale ?? 1,
+  };
+
+  if (options.paperWidth) params.paperWidth = options.paperWidth;
+  if (options.paperHeight) params.paperHeight = options.paperHeight;
+  if (options.marginTop !== undefined) params.marginTop = options.marginTop;
+  if (options.marginBottom !== undefined) params.marginBottom = options.marginBottom;
+  if (options.marginLeft !== undefined) params.marginLeft = options.marginLeft;
+  if (options.marginRight !== undefined) params.marginRight = options.marginRight;
+
+  const result = await client.send<{ data: string }>('Page.printToPDF', params, sessionId);
+  const outputPath = options.path ?? join(tmpdir(), `monomind-pdf-${Date.now()}.pdf`);
+  await writeFile(outputPath, Buffer.from(result.data, 'base64'));
+  return outputPath;
+}

package/src/browser/profiler.ts

@@ -0,0 +1,96 @@
+import type { CdpClient } from './cdp.js';
+import { writeFile } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+export interface ProfilerOptions {
+  path?: string;
+  samplingInterval?: number;
+}
+
+const _sessions = new Set<string>();
+const _heapSessions = new Set<string>();
+
+export async function startCpuProfile(
+  client: CdpClient,
+  sessionId: string,
+  options: ProfilerOptions = {}
+): Promise<void> {
+  if (_sessions.has(sessionId)) {
+    throw new Error('CPU profiler already running for this session');
+  }
+  await client.send('Profiler.enable', {}, sessionId);
+  if (options.samplingInterval !== undefined) {
+    await client.send('Profiler.setSamplingInterval', { interval: options.samplingInterval }, sessionId);
+  }
+  await client.send('Profiler.start', {}, sessionId);
+  _sessions.add(sessionId);
+}
+
+export async function stopCpuProfile(
+  client: CdpClient,
+  sessionId: string,
+  outputPath?: string
+): Promise<string> {
+  if (!_sessions.has(sessionId)) {
+    throw new Error('No active CPU profiler for this session');
+  }
+  let result: { profile: unknown };
+  try {
+    result = await client.send<{ profile: unknown }>('Profiler.stop', {}, sessionId);
+  } finally {
+    _sessions.delete(sessionId);
+  }
+
+  // Disable after capturing the profile so a disable failure doesn't discard valid data
+  await client.send('Profiler.disable', {}, sessionId).catch(() => {});
+
+  const path = outputPath ?? join(tmpdir(), `monomind-profile-${Date.now()}.cpuprofile`);
+  await writeFile(path, JSON.stringify(result!.profile));
+  return path;
+}
+
+export function isProfilingActive(sessionId: string): boolean {
+  return _sessions.has(sessionId);
+}
+
+export async function startHeapSnapshot(
+  client: CdpClient,
+  sessionId: string,
+  outputPath?: string
+): Promise<string> {
+  if (_heapSessions.has(sessionId)) {
+    throw new Error('Heap snapshot already in progress for this session');
+  }
+  _heapSessions.add(sessionId);
+  await client.send('HeapProfiler.enable', {}, sessionId);
+
+  const chunks: string[] = [];
+  const off = client.on('HeapProfiler.addHeapSnapshotChunk', (params, sid) => {
+    if (sid !== sessionId) return;
+    chunks.push(params.chunk as string);
+  });
+
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const timeoutHandle = setTimeout(() => {
+        off2();
+        reject(new Error('Timeout waiting for heap snapshot (120s)'));
+      }, 120_000);
+      const off2 = client.on('HeapProfiler.reportHeapSnapshotProgress', (params, sid) => {
+        if (sid !== sessionId) return;
+        if (params.finished) { clearTimeout(timeoutHandle); off2(); resolve(); }
+      });
+      client.send('HeapProfiler.takeHeapSnapshot', { reportProgress: true }, sessionId)
+        .catch((err) => { clearTimeout(timeoutHandle); off2(); reject(err); });
+    });
+  } finally {
+    off();
+    _heapSessions.delete(sessionId);
+    await client.send('HeapProfiler.disable', {}, sessionId).catch(() => {});
+  }
+
+  const path = outputPath ?? join(tmpdir(), `monomind-heap-${Date.now()}.heapsnapshot`);
+  await writeFile(path, chunks.join(''));
+  return path;
+}

package/src/browser/record.ts

@@ -0,0 +1,92 @@
+import type { CdpClient } from './cdp.js';
+import { writeFile } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+export interface RecordOptions {
+  path?: string;
+  format?: 'jpeg' | 'png' | 'webp';
+  quality?: number;
+  everyNthFrame?: number;
+  maxWidth?: number;
+  maxHeight?: number;
+}
+
+export interface RecordingState {
+  frames: string[];
+  offScreencast: (() => void) | null;
+}
+
+const _sessions = new Map<string, RecordingState>();
+
+export async function startRecording(
+  client: CdpClient,
+  sessionId: string,
+  options: RecordOptions = {}
+): Promise<void> {
+  if (_sessions.has(sessionId)) {
+    throw new Error('Recording already in progress for this session');
+  }
+
+  const state: RecordingState = { frames: [], offScreencast: null };
+  _sessions.set(sessionId, state);
+
+  state.offScreencast = client.on('Page.screencastFrame', async (params, sid) => {
+    if (sid !== sessionId) return;
+    const { data, sessionId: frameSessionId } = params as { data: string; sessionId: number };
+    state.frames.push(data);
+    await client.send('Page.screencastFrameAck', { sessionId: frameSessionId }, sessionId).catch(() => {});
+  });
+
+  try {
+    await client.send('Page.startScreencast', {
+      format: options.format ?? 'jpeg',
+      quality: options.quality ?? 80,
+      everyNthFrame: options.everyNthFrame ?? 1,
+      ...(options.maxWidth ? { maxWidth: options.maxWidth } : {}),
+      ...(options.maxHeight ? { maxHeight: options.maxHeight } : {}),
+    }, sessionId);
+  } catch (err) {
+    state.offScreencast?.();
+    _sessions.delete(sessionId);
+    throw err;
+  }
+}
+
+export async function stopRecording(
+  client: CdpClient,
+  sessionId: string,
+  outputPath?: string
+): Promise<string> {
+  const state = _sessions.get(sessionId);
+  if (!state) throw new Error('No active recording for this session');
+
+  try {
+    await client.send('Page.stopScreencast', {}, sessionId);
+  } finally {
+    state.offScreencast?.();
+    _sessions.delete(sessionId);
+  }
+
+  const path = outputPath ?? join(tmpdir(), `monomind-screencast-${Date.now()}.frames.json`);
+  await writeFile(path, JSON.stringify({ frameCount: state.frames.length, frames: state.frames }));
+  return path;
+}
+
+export function getRecordingStatus(sessionId: string): { recording: boolean; frames: number } {
+  const state = _sessions.get(sessionId);
+  return { recording: !!state, frames: state?.frames.length ?? 0 };
+}
+
+export async function saveFrameAsPng(
+  client: CdpClient,
+  sessionId: string,
+  frameIndex: number,
+  outputPath: string
+): Promise<void> {
+  const state = _sessions.get(sessionId);
+  if (!state || frameIndex >= state.frames.length) {
+    throw new Error(`Frame ${frameIndex} not available`);
+  }
+  await writeFile(outputPath, Buffer.from(state.frames[frameIndex], 'base64'));
+}

package/src/browser/screenshot.ts

@@ -0,0 +1,67 @@
+import type { CdpClient } from './cdp.js';
+import { writeFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { tmpdir } from 'os';
+
+export interface ScreenshotOptions {
+  path?: string;
+  fullPage?: boolean;
+  quality?: number;
+  format?: 'jpeg' | 'png' | 'webp';
+  annotate?: boolean;
+}
+
+export async function captureScreenshot(
+  client: CdpClient,
+  sessionId: string,
+  options: ScreenshotOptions = {}
+): Promise<{ path: string; dataUrl: string }> {
+  const format = options.format ?? 'png';
+  const params: Record<string, unknown> = { format };
+
+  if (format === 'jpeg' || format === 'webp') {
+    params.quality = options.quality ?? 80;
+  }
+
+  if (options.fullPage) {
+    const dims = await client.send<{ result: { value: string } }>('Runtime.evaluate', {
+      expression: 'JSON.stringify({w: document.documentElement.scrollWidth, h: document.documentElement.scrollHeight})',
+      returnByValue: true,
+    }, sessionId);
+    const { w, h } = JSON.parse(dims.result?.value ?? '{"w":1280,"h":720}');
+    params.clip = { x: 0, y: 0, width: w, height: h, scale: 1 };
+    params.captureBeyondViewport = true;
+  }
+
+  const result = await client.send<{ data: string }>('Page.captureScreenshot', params, sessionId);
+  const data = result.data;
+  const dataUrl = `data:image/${format};base64,${data}`;
+
+  const outputPath = options.path ?? join(tmpdir(), `monomind-screenshot-${Date.now()}.${format}`);
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, Buffer.from(data, 'base64'));
+
+  return { path: outputPath, dataUrl };
+}
+
+export async function setViewport(
+  client: CdpClient,
+  sessionId: string,
+  width: number,
+  height: number
+): Promise<void> {
+  await client.send('Emulation.setDeviceMetricsOverride', {
+    width,
+    height,
+    deviceScaleFactor: 1,
+    mobile: false,
+  }, sessionId);
+}
+
+export async function setUserAgent(
+  client: CdpClient,
+  sessionId: string,
+  userAgent: string
+): Promise<void> {
+  await client.send('Emulation.setUserAgentOverride', { userAgent }, sessionId);
+}

package/src/browser/session.ts

@@ -0,0 +1,118 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import type { SessionState, CdpCookie } from './types.js';
+import type { CdpClient } from './cdp.js';
+import { getCookies, setCookies, getLocalStorage, setLocalStorage, getSessionStorage, setSessionStorage } from './network.js';
+
+const SESSION_DIR = join(homedir(), '.monomind', 'browser-sessions');
+
+function validateSessionName(name: string): void {
+  if (!name || /[/\\\x00]/.test(name) || name === '..' || name === '.' || name.startsWith('..')) {
+    throw new Error(`Invalid session name: ${JSON.stringify(name)}`);
+  }
+}
+
+function validateFilePath(filePath: string): void {
+  if (!filePath || filePath.includes('\x00')) {
+    throw new Error(`Invalid file path: ${JSON.stringify(filePath)}`);
+  }
+  if (filePath.includes('/../') || filePath.startsWith('../') || filePath.endsWith('/..') || filePath.includes('\\')) {
+    throw new Error(`Invalid file path (traversal not allowed): ${JSON.stringify(filePath)}`);
+  }
+}
+
+export async function saveSession(
+  client: CdpClient,
+  sessionId: string,
+  targetId: string,
+  name: string,
+  url: string,
+  title: string
+): Promise<string> {
+  validateSessionName(name);
+  await mkdir(SESSION_DIR, { recursive: true });
+
+  const cookies = await getCookies(client, sessionId);
+  const localStorage = await getLocalStorage(client, sessionId);
+  const sessionStorage = await getSessionStorage(client, sessionId);
+
+  const state: SessionState = { targetId, sessionId, url, title, cookies, localStorage, sessionStorage };
+  const filePath = join(SESSION_DIR, `${name}.json`);
+  await writeFile(filePath, JSON.stringify(state, null, 2));
+  return filePath;
+}
+
+export async function loadSession(
+  client: CdpClient,
+  sessionId: string,
+  name: string
+): Promise<SessionState> {
+  validateSessionName(name);
+  const filePath = join(SESSION_DIR, `${name}.json`);
+  const raw = await readFile(filePath, 'utf8').catch((err: NodeJS.ErrnoException) => {
+    if (err.code === 'ENOENT') throw new Error(`Session not found: ${name}`);
+    throw err;
+  });
+  const state: SessionState = JSON.parse(raw);
+  if (!Array.isArray(state.cookies)) throw new Error(`Invalid session file: cookies is not an array`);
+
+  await setCookies(client, sessionId, state.cookies);
+  if (state.localStorage) {
+    if (typeof state.localStorage !== 'object' || Array.isArray(state.localStorage)) throw new Error('Invalid session file: localStorage is not a plain object');
+    await setLocalStorage(client, sessionId, state.localStorage);
+  }
+  if (state.sessionStorage) {
+    if (typeof state.sessionStorage !== 'object' || Array.isArray(state.sessionStorage)) throw new Error('Invalid session file: sessionStorage is not a plain object');
+    await setSessionStorage(client, sessionId, state.sessionStorage);
+  }
+
+  return state;
+}
+
+export async function saveStateFile(
+  client: CdpClient,
+  sessionId: string,
+  targetId: string,
+  filePath: string,
+  url: string,
+  title: string
+): Promise<void> {
+  validateFilePath(filePath);
+  await mkdir(dirname(filePath), { recursive: true });
+  const cookies = await getCookies(client, sessionId);
+  const localStorage = await getLocalStorage(client, sessionId);
+  const sessionStorage = await getSessionStorage(client, sessionId);
+  const state: SessionState = { targetId, sessionId, url, title, cookies, localStorage, sessionStorage };
+  await writeFile(filePath, JSON.stringify(state, null, 2));
+}
+
+export async function loadStateFile(
+  client: CdpClient,
+  sessionId: string,
+  filePath: string
+): Promise<SessionState> {
+  validateFilePath(filePath);
+  const raw = await readFile(filePath, 'utf8');
+  const state: SessionState = JSON.parse(raw);
+  if (!Array.isArray(state.cookies)) throw new Error(`Invalid state file: cookies is not an array`);
+  await setCookies(client, sessionId, state.cookies);
+  if (state.localStorage) {
+    if (typeof state.localStorage !== 'object' || Array.isArray(state.localStorage)) throw new Error('Invalid state file: localStorage is not a plain object');
+    await setLocalStorage(client, sessionId, state.localStorage);
+  }
+  if (state.sessionStorage) {
+    if (typeof state.sessionStorage !== 'object' || Array.isArray(state.sessionStorage)) throw new Error('Invalid state file: sessionStorage is not a plain object');
+    await setSessionStorage(client, sessionId, state.sessionStorage);
+  }
+  return state;
+}
+
+export async function listSessions(): Promise<string[]> {
+  const { readdir } = await import('fs/promises');
+  const files = await readdir(SESSION_DIR).catch((err: NodeJS.ErrnoException) => {
+    if (err.code === 'ENOENT') return [] as string[];
+    throw err;
+  });
+  return files.filter((f) => f.endsWith('.json')).map((f) => f.replace(/\.json$/, ''));
+}

package/src/browser/snapshot.ts

@@ -0,0 +1,248 @@
+import type { CdpClient } from './cdp.js';
+import type { ElementRef, SnapshotOptions, SnapshotResult } from './types.js';
+import { INTERACTIVE_ROLES } from './types.js';
+import { getCurrentUrl, getCurrentTitle } from './browser.js';
+
+interface AXNode {
+  nodeId: number;
+  role?: { value: string };
+  name?: { value: string };
+  description?: { value: string };
+  value?: { value: string };
+  properties?: Array<{ name: string; value: { value: unknown } }>;
+  backendDOMNodeId?: number;
+  parentId?: number;
+  childIds?: number[];
+  ignored?: boolean;
+  ignoredReasons?: unknown[];
+}
+
+export async function captureSnapshot(
+  client: CdpClient,
+  sessionId: string,
+  options: SnapshotOptions = {}
+): Promise<SnapshotResult> {
+  const { interactiveOnly = false, compact = false, maxDepth, selector } = options;
+
+  // If a selector scope is requested, resolve it to a backendDOMNodeId and use getPartialAXTree
+  let nodes: AXNode[];
+  if (selector) {
+    const doc = await client.send<{ root: { nodeId: number } }>('DOM.getDocument', {}, sessionId);
+    const found = await client.send<{ nodeId: number }>(
+      'DOM.querySelector',
+      { nodeId: doc.root.nodeId, selector },
+      sessionId
+    ).catch(() => ({ nodeId: 0 }));
+
+    if (found.nodeId) {
+      const partial = await client.send<{ nodes: AXNode[] }>(
+        'Accessibility.getPartialAXTree',
+        { nodeId: found.nodeId, fetchRelatives: false },
+        sessionId
+      ).catch(async () => client.send<{ nodes: AXNode[] }>('Accessibility.getFullAXTree', {}, sessionId));
+      nodes = partial.nodes;
+    } else {
+      const full = await client.send<{ nodes: AXNode[] }>('Accessibility.getFullAXTree', {}, sessionId);
+      nodes = full.nodes;
+    }
+  } else {
+    const full = await client.send<{ nodes: AXNode[] }>('Accessibility.getFullAXTree', {}, sessionId);
+    nodes = full.nodes;
+  }
+
+  const url = await getCurrentUrl(client, sessionId);
+  const title = await getCurrentTitle(client, sessionId);
+
+  const refs = new Map<string, ElementRef>();
+  const nodeMap = new Map<number, AXNode>();
+  for (const node of nodes) nodeMap.set(node.nodeId, node);
+
+  let refCounter = 1;
+  const lines: string[] = [];
+
+  const processNode = (node: AXNode, depth: number) => {
+    // Transparent/structural nodes don't consume depth budget — check before maxDepth
+    if (node.ignored) {
+      if (node.childIds) {
+        for (const childId of node.childIds) {
+          const child = nodeMap.get(childId);
+          if (child) processNode(child, depth);
+        }
+      }
+      return;
+    }
+
+    const role = node.role?.value ?? 'generic';
+
+    if (role === 'none' || role === 'generic' || role === 'inlineTextBox') {
+      if (node.childIds) {
+        for (const childId of node.childIds) {
+          const child = nodeMap.get(childId);
+          if (child) processNode(child, depth);
+        }
+      }
+      return;
+    }
+
+    // Only enforce maxDepth for real rendered roles
+    if (maxDepth !== undefined && depth > maxDepth) return;
+
+    const name = node.name?.value ?? '';
+    const description = node.description?.value;
+
+    const isInteractive = INTERACTIVE_ROLES.has(role.toLowerCase());
+
+    if (interactiveOnly && !isInteractive) {
+      if (node.childIds) {
+        for (const childId of node.childIds) {
+          const child = nodeMap.get(childId);
+          if (child) processNode(child, depth);
+        }
+      }
+      return;
+    }
+
+    const props = extractProperties(node);
+    const refKey = `e${refCounter++}`;
+    const elemRef: ElementRef = {
+      ref: refKey,
+      role,
+      name,
+      description,
+      placeholder: props.placeholder,
+      value: props.value,
+      disabled: props.disabled,
+      checked: props.checked,
+      expanded: props.expanded,
+      nodeId: node.nodeId,
+      backendDOMNodeId: node.backendDOMNodeId,
+    };
+    refs.set(refKey, elemRef);
+
+    const indent = compact ? '' : '  '.repeat(depth);
+    const attrParts: string[] = [`ref=${refKey}`];
+    if (props.value !== undefined) attrParts.push(`value="${props.value}"`);
+    if (props.disabled) attrParts.push('disabled');
+    if (props.checked !== undefined) attrParts.push(`checked=${props.checked}`);
+    if (props.expanded !== undefined) attrParts.push(`expanded=${props.expanded}`);
+    if (props.placeholder) attrParts.push(`placeholder="${props.placeholder}"`);
+    if (props.required) attrParts.push('required');
+
+    const nameStr = name ? ` "${name}"` : '';
+    const descStr = description && !compact ? ` (${description})` : '';
+    const attrsStr = ` [${attrParts.join(', ')}]`;
+
+    lines.push(`${indent}${role}${nameStr}${descStr}${attrsStr}`);
+
+    if (node.childIds) {
+      for (const childId of node.childIds) {
+        const child = nodeMap.get(childId);
+        if (child) processNode(child, depth + 1);
+      }
+    }
+  };
+
+  // Find root nodes — for partial trees parentId may point outside the set; use filter to handle forests
+  const ids = new Set(nodes.map((n) => n.nodeId));
+  const roots = nodes.filter((n) => n.parentId === undefined || !ids.has(n.parentId));
+  for (const root of roots) processNode(root, 0);
+
+  return { text: lines.join('\n'), refs, url, title };
+}
+
+function extractProperties(node: AXNode): {
+  value?: string;
+  disabled?: boolean;
+  checked?: boolean;
+  expanded?: boolean;
+  placeholder?: string;
+  required?: boolean;
+} {
+  const result: ReturnType<typeof extractProperties> = {};
+  if (!node.properties) return result;
+
+  for (const prop of node.properties) {
+    switch (prop.name) {
+      case 'value':
+        if (prop.value.value != null) result.value = String(prop.value.value);
+        break;
+      case 'disabled':
+        result.disabled = Boolean(prop.value.value);
+        break;
+      case 'checked':
+        result.checked = prop.value.value === 'true' || prop.value.value === true;
+        break;
+      case 'expanded':
+        result.expanded = prop.value.value === 'true' || prop.value.value === true;
+        break;
+      case 'placeholder':
+        result.placeholder = String(prop.value.value ?? '');
+        break;
+      case 'required':
+        result.required = Boolean(prop.value.value);
+        break;
+    }
+  }
+
+  if (node.value?.value !== undefined && result.value === undefined) {
+    result.value = String(node.value.value);
+  }
+
+  return result;
+}
+
+export async function resolveRef(
+  client: CdpClient,
+  sessionId: string,
+  refs: Map<string, ElementRef>,
+  refKey: string
+): Promise<ElementRef> {
+  const ref = refs.get(refKey);
+  if (!ref) throw new Error(`Element ref @${refKey} not found. Run snapshot first.`);
+  return ref;
+}
+
+export async function getObjectIdForRef(
+  client: CdpClient,
+  sessionId: string,
+  ref: ElementRef
+): Promise<string | null> {
+  if (!ref.backendDOMNodeId) return null;
+
+  const result = await client.send<{ object: { objectId?: string } }>(
+    'DOM.resolveNode',
+    { backendNodeId: ref.backendDOMNodeId },
+    sessionId
+  );
+  return result.object?.objectId ?? null;
+}
+
+export async function getElementBox(
+  client: CdpClient,
+  sessionId: string,
+  ref: ElementRef
+): Promise<{ x: number; y: number; width: number; height: number } | null> {
+  if (!ref.backendDOMNodeId) return null;
+
+  try {
+    const result = await client.send<{
+      model: {
+        content: number[];
+        border: number[];
+        margin: number[];
+        padding: number[];
+        width: number;
+        height: number;
+      };
+    }>('DOM.getBoxModel', { backendNodeId: ref.backendDOMNodeId }, sessionId);
+
+    const content = result.model?.content;
+    if (!content || content.length < 8) return null;
+
+    const x = (content[0] + content[2] + content[4] + content[6]) / 4;
+    const y = (content[1] + content[3] + content[5] + content[7]) / 4;
+    return { x, y, width: result.model.width, height: result.model.height };
+  } catch {
+    return null;
+  }
+}