@monoes/monobrowse 1.0.0

package/src/browser/adapters/google.ts

@@ -0,0 +1,20 @@
+// src/browser/adapters/google.ts
+import type { PlatformAdapter, PageInterface } from './index.js';
+
+export const googleAdapter: PlatformAdapter = {
+  platform: 'google',
+  baseURL: 'https://accounts.google.com',
+  reservedPaths: ['/signin', '/oauth', '/o/oauth2'],
+  loginURL: () => 'https://accounts.google.com/signin/v2/identifier',
+  async isLoggedIn(page: PageInterface): Promise<boolean> {
+    const url = await page.url();
+    // Logged in if we're on a Google service page (not the sign-in page)
+    if (url.includes('accounts.google.com/signin')) return false;
+    return page.evaluate<boolean>("!!(document.querySelector('[aria-label*=\"Google Account\"]') || document.querySelector('.gb_A') || document.cookie.includes('SSID'))");
+  },
+  async extractUsername(page: PageInterface): Promise<string> {
+    return page.evaluate<string>(
+      "document.querySelector('[data-email]')?.getAttribute('data-email') ?? document.querySelector('.gb_A.gb_Sa')?.textContent?.trim() ?? ''"
+    );
+  },
+};

package/src/browser/adapters/index.ts

@@ -0,0 +1,33 @@
+// src/browser/adapters/index.ts
+
+export interface PageInterface {
+  evaluate<T>(expression: string): Promise<T>;
+  url(): Promise<string>;
+}
+
+export interface PlatformAdapter {
+  platform: string;
+  baseURL: string;
+  reservedPaths: string[];
+  isLoggedIn(page: PageInterface): Promise<boolean>;
+  loginURL(): string;
+  extractUsername(page: PageInterface): Promise<string>;
+}
+
+import { linkedinAdapter } from './linkedin.js';
+import { instagramAdapter } from './instagram.js';
+import { xAdapter } from './x.js';
+import { geminiAdapter } from './gemini.js';
+
+export const adapters: Map<string, PlatformAdapter> = new Map([
+  ['linkedin', linkedinAdapter],
+  ['instagram', instagramAdapter],
+  ['x', xAdapter],
+  ['gemini', geminiAdapter],
+]);
+
+export function getAdapter(platform: string): PlatformAdapter {
+  const adapter = adapters.get(platform);
+  if (!adapter) throw new Error(`Unknown platform: ${platform}. Supported: ${[...adapters.keys()].join(', ')}`);
+  return adapter;
+}

package/src/browser/adapters/instagram.ts

@@ -0,0 +1,16 @@
+// src/browser/adapters/instagram.ts
+import type { PlatformAdapter, PageInterface } from './index.js';
+
+export const instagramAdapter: PlatformAdapter = {
+  platform: 'instagram',
+  baseURL: 'https://www.instagram.com',
+  reservedPaths: ['/direct', '/explore', '/reels', '/stories'],
+  loginURL: () => 'https://www.instagram.com/accounts/login/',
+  async isLoggedIn(page: PageInterface): Promise<boolean> {
+    return page.evaluate<boolean>('!!document.querySelector(\'svg[aria-label="Home"]\')');
+  },
+  async extractUsername(page: PageInterface): Promise<string> {
+    // Use getAttribute to get the raw path-relative href (not the resolved absolute URL)
+    return page.evaluate<string>("document.querySelector('a[href^=\"/\"]')?.getAttribute('href')?.split('/').filter(Boolean)[0] ?? ''");
+  },
+};

package/src/browser/adapters/linkedin.ts

@@ -0,0 +1,15 @@
+// src/browser/adapters/linkedin.ts
+import type { PlatformAdapter, PageInterface } from './index.js';
+
+export const linkedinAdapter: PlatformAdapter = {
+  platform: 'linkedin',
+  baseURL: 'https://www.linkedin.com',
+  reservedPaths: ['/feed', '/jobs', '/messaging', '/notifications', '/me'],
+  loginURL: () => 'https://www.linkedin.com/login',
+  async isLoggedIn(page: PageInterface): Promise<boolean> {
+    return page.evaluate<boolean>("!!document.querySelector('.global-nav__me-photo')");
+  },
+  async extractUsername(page: PageInterface): Promise<string> {
+    return page.evaluate<string>("document.querySelector('.profile-rail-card__actor-link')?.textContent?.trim() ?? ''");
+  },
+};

package/src/browser/adapters/microsoft.ts

@@ -0,0 +1,19 @@
+// src/browser/adapters/microsoft.ts
+import type { PlatformAdapter, PageInterface } from './index.js';
+
+export const microsoftAdapter: PlatformAdapter = {
+  platform: 'microsoft',
+  baseURL: 'https://login.microsoftonline.com',
+  reservedPaths: ['/oauth2', '/common/oauth2', '/kmsi'],
+  loginURL: () => 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=common&response_type=code&scope=openid+profile+email',
+  async isLoggedIn(page: PageInterface): Promise<boolean> {
+    const url = await page.url();
+    if (url.includes('login.microsoftonline.com') || url.includes('login.microsoft.com')) return false;
+    return page.evaluate<boolean>("!!(document.querySelector('[data-tid=\"user-email\"]') || document.querySelector('.mectrl_currentAccount') || document.cookie.includes('ESTSAUTH'))");
+  },
+  async extractUsername(page: PageInterface): Promise<string> {
+    return page.evaluate<string>(
+      "document.querySelector('[data-tid=\"user-email\"]')?.textContent?.trim() ?? document.querySelector('.mectrl_headerEmail')?.textContent?.trim() ?? ''"
+    );
+  },
+};

package/src/browser/adapters/x.ts

@@ -0,0 +1,15 @@
+// src/browser/adapters/x.ts
+import type { PlatformAdapter, PageInterface } from './index.js';
+
+export const xAdapter: PlatformAdapter = {
+  platform: 'x',
+  baseURL: 'https://x.com',
+  reservedPaths: ['/home', '/explore', '/notifications', '/messages'],
+  loginURL: () => 'https://x.com/i/flow/login',
+  async isLoggedIn(page: PageInterface): Promise<boolean> {
+    return page.evaluate<boolean>('!!document.querySelector(\'[data-testid="SideNav_AccountSwitcher_Button"]\')');
+  },
+  async extractUsername(page: PageInterface): Promise<string> {
+    return page.evaluate<string>("document.querySelector('[data-testid=\"SideNav_AccountSwitcher_Button\"] span')?.textContent?.trim() ?? ''");
+  },
+};

package/src/browser/batch.ts

@@ -0,0 +1,4 @@
+export interface BatchCommand {
+  command: string;
+  args: string[];
+}

package/src/browser/browser.ts

@@ -0,0 +1,265 @@
+import { spawn, execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { CdpClient, fetchTargets, fetchNewTarget } from './cdp.js';
+import type { BrowserConfig, CdpTarget } from './types.js';
+import { CHROME_EXECUTABLES } from './types.js';
+import { enableConsoleCapture, setupConsoleCapture } from './console-log.js';
+import { setupDialogAutoHandling } from './dialog.js';
+
+const DEFAULT_PORT = 9222;
+const LAUNCH_TIMEOUT = 10_000;
+const POLL_INTERVAL = 200;
+
+function findChrome(executablePath?: string): string {
+  if (executablePath) {
+    if (existsSync(executablePath)) return executablePath;
+    throw new Error(`Chrome executable not found: ${executablePath}`);
+  }
+  for (const candidate of CHROME_EXECUTABLES) {
+    if (existsSync(candidate)) return candidate;
+  }
+  // Try PATH
+  try {
+    const result = execSync('which google-chrome chromium-browser chromium 2>/dev/null', { encoding: 'utf8' }).trim();
+    const first = result.split('\n')[0];
+    if (first) return first;
+  } catch {
+    // ignore
+  }
+  throw new Error(
+    'Chrome/Chromium not found. Install Google Chrome or pass executablePath in BrowserConfig.'
+  );
+}
+
+export async function isPortOpen(port: number): Promise<boolean> {
+  try {
+    await fetchTargets(port);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function launchBrowser(config: BrowserConfig = {}): Promise<number> {
+  const rawPort = config.port ?? DEFAULT_PORT;
+  // Validate port is in a safe range for localhost CDP debugging
+  if (!Number.isInteger(rawPort) || rawPort < 1024 || rawPort > 65535) {
+    throw new Error(`Invalid port: ${rawPort}. Must be an integer between 1024 and 65535.`);
+  }
+  const port = rawPort;
+
+  if (await isPortOpen(port)) {
+    return port;
+  }
+
+  const chromePath = findChrome(config.executablePath);
+  const userDataDir = config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}`);
+
+  const defaultArgs = [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${userDataDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-background-networking',
+    '--disable-client-side-phishing-detection',
+    '--disable-default-apps',
+    '--disable-extensions',
+    '--disable-hang-monitor',
+    '--disable-popup-blocking',
+    '--disable-prompt-on-repost',
+    '--disable-sync',
+    '--disable-translate',
+    '--metrics-recording-only',
+    '--safebrowsing-disable-auto-update',
+    '--password-store=basic',
+    '--use-mock-keychain',
+  ];
+
+  if (config.headless !== false) {
+    defaultArgs.push('--headless=new');
+  }
+
+  // Cap caller-supplied args to prevent memory exhaustion via huge argument arrays
+  const callerArgs = (config.args ?? []).slice(0, 50);
+  const args = [...defaultArgs, ...callerArgs];
+  const child = spawn(chromePath, args, {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+
+  const deadline = Date.now() + LAUNCH_TIMEOUT;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL);
+    if (await isPortOpen(port)) return port;
+  }
+
+  throw new Error(`Chrome failed to start on port ${port} within ${LAUNCH_TIMEOUT}ms`);
+}
+
+export async function enableSessionDomains(client: CdpClient, sessionId: string): Promise<void> {
+  await Promise.all([
+    client.send('Page.enable', {}, sessionId),
+    client.send('Runtime.enable', {}, sessionId),
+    client.send('Network.enable', {}, sessionId),
+    client.send('DOM.enable', {}, sessionId),
+    client.send('Accessibility.enable', {}, sessionId),
+  ]);
+  setupConsoleCapture(client, sessionId);
+  await enableConsoleCapture(client, sessionId);
+  setupDialogAutoHandling(client, sessionId);
+}
+
+export async function connectToTarget(port: number, targetId?: string): Promise<{ client: CdpClient; target: CdpTarget; sessionId: string }> {
+  const targets = await fetchTargets(port);
+  const pageTargets = targets.filter((t) => t.type === 'page');
+
+  let target: CdpTarget;
+  if (targetId) {
+    const found = pageTargets.find((t) => t.id === targetId);
+    if (!found) throw new Error(`Target ${targetId} not found`);
+    target = found;
+  } else if (pageTargets.length > 0) {
+    target = pageTargets[0];
+  } else {
+    target = await fetchNewTarget(port, 'about:blank');
+  }
+
+  const wsUrl = target.webSocketDebuggerUrl ?? `ws://127.0.0.1:${port}/devtools/page/${target.id}`;
+  const client = new CdpClient();
+  await client.connect(wsUrl);
+
+  const { sessionId } = await client.send<{ sessionId: string }>('Target.attachToTarget', {
+    targetId: target.id,
+    flatten: true,
+  });
+
+  await enableSessionDomains(client, sessionId);
+  return { client, target, sessionId };
+}
+
+export async function openUrl(client: CdpClient, sessionId: string, url: string): Promise<void> {
+  // Cap to 2 MB to prevent OOM in CDP message serializer (e.g. data: URI attacks)
+  if (url.length > 2_097_152) throw new Error('URL exceeds 2 MB limit');
+  await client.send('Page.navigate', { url }, sessionId);
+  await waitForNetworkIdle(client, sessionId, 500, 30_000);
+}
+
+export async function waitForLoad(
+  client: CdpClient,
+  sessionId: string,
+  condition: 'load' | 'networkidle' | 'domcontentloaded' = 'load',
+  timeout = 30_000
+): Promise<void> {
+  if (condition === 'load' || condition === 'domcontentloaded') {
+    // Guard against race where the page loads before the listener is registered
+    const readyExpr = condition === 'load' ? 'document.readyState === "complete"' : 'document.readyState !== "loading"';
+    const readyCheck = await client.send<{ result: { value?: boolean } }>('Runtime.evaluate', {
+      expression: readyExpr, returnByValue: true,
+    }, sessionId).catch(() => ({ result: { value: false } }));
+    if (readyCheck.result?.value) return;
+
+    const event = condition === 'load' ? 'Page.loadEventFired' : 'Page.domContentEventFired';
+    const [eventPromise, cancelOnce] = client.onceWithOff(event, sessionId);
+    let timedOut = false;
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const timeoutPromise = new Promise<void>((resolve) => {
+      timeoutHandle = setTimeout(() => { timedOut = true; resolve(); }, timeout);
+    });
+    try {
+      await Promise.race([eventPromise, timeoutPromise]);
+      if (timedOut) throw new Error(`Timeout waiting for ${condition}`);
+    } finally {
+      cancelOnce();
+      clearTimeout(timeoutHandle);
+    }
+    return;
+  }
+
+  // networkidle: no network requests for 500ms
+  await waitForNetworkIdle(client, sessionId, 500, timeout);
+}
+
+async function waitForNetworkIdle(
+  client: CdpClient,
+  sessionId: string,
+  idleMs: number,
+  timeout: number
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let pending = 0;
+    const inflight = new Set<string>();
+    let idleTimer: ReturnType<typeof setTimeout> | null = null;
+    const killTimer = setTimeout(() => {
+      cleanup();
+      reject(new Error('Timeout waiting for networkidle'));
+    }, timeout);
+
+    const cleanup = () => {
+      if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+      clearTimeout(killTimer);
+      offReq(); offResp(); offFail(); offCache(); offResp2();
+    };
+
+    const settle = () => {
+      cleanup();
+      resolve();
+    };
+
+    const check = () => {
+      if (pending === 0) {
+        if (idleTimer) clearTimeout(idleTimer);
+        idleTimer = setTimeout(settle, idleMs);
+      } else {
+        if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+      }
+    };
+
+    const offReq = client.on('Network.requestWillBeSent', (params, sid) => {
+      if (sid !== sessionId) return;
+      const id = params.requestId as string;
+      if (!inflight.has(id)) { inflight.add(id); pending++; check(); }
+    });
+
+    const decrement = (params: Record<string, unknown>, sid?: string) => {
+      if (sid !== sessionId) return;
+      const id = params.requestId as string;
+      if (inflight.delete(id)) { pending = Math.max(0, pending - 1); check(); }
+    };
+
+    const offResp  = client.on('Network.loadingFinished',        decrement);
+    const offFail  = client.on('Network.loadingFailed',          decrement);
+    const offCache = client.on('Network.requestServedFromCache', decrement);
+    // Guard against requests that never fire loadingFinished/loadingFailed (e.g. data: URLs)
+    // Skip 3xx redirect responses — the request continues under the same requestId
+    const offResp2 = client.on('Network.responseReceived', (params, sid) => {
+      const p = params as { requestId: string; response: { status: number } };
+      if (p.response.status >= 300 && p.response.status < 400) return;
+      decrement(params, sid);
+    });
+
+    check();
+  });
+}
+
+export async function getCurrentUrl(client: CdpClient, sessionId: string): Promise<string> {
+  const result = await client.send<{ result: { value: string } }>('Runtime.evaluate', {
+    expression: 'location.href',
+    returnByValue: true,
+  }, sessionId);
+  return result.result?.value ?? '';
+}
+
+export async function getCurrentTitle(client: CdpClient, sessionId: string): Promise<string> {
+  const result = await client.send<{ result: { value: string } }>('Runtime.evaluate', {
+    expression: 'document.title',
+    returnByValue: true,
+  }, sessionId);
+  return result.result?.value ?? '';
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/browser/cdp.ts

@@ -0,0 +1,156 @@
+import { WebSocket } from 'ws';
+import type { CdpCommand, CdpResponse, CdpTarget } from './types.js';
+
+export class CdpClient {
+  private ws: WebSocket | null = null;
+  private pendingCommands = new Map<number, { resolve: (r: CdpResponse) => void; reject: (e: Error) => void }>();
+  private eventListeners = new Map<string, Set<(params: Record<string, unknown>, sessionId?: string) => void>>();
+  private nextId = 1;
+  private connected = false;
+
+  async connect(wsUrl: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(wsUrl);
+
+      this.ws.on('open', () => {
+        this.connected = true;
+        resolve();
+      });
+
+      this.ws.on('error', (err) => {
+        if (!this.connected) {
+          reject(err);
+        } else {
+          // Post-connect: flush all pending commands — 'close' may not fire on all platforms
+          this.connected = false;
+          for (const { reject: r } of this.pendingCommands.values()) r(err);
+          this.pendingCommands.clear();
+        }
+      });
+
+      this.ws.on('close', () => {
+        this.connected = false;
+        for (const { reject: r } of this.pendingCommands.values()) {
+          r(new Error('CDP connection closed'));
+        }
+        this.pendingCommands.clear();
+      });
+
+      this.ws.on('message', (data) => {
+        try {
+          const msg: CdpResponse = JSON.parse(data.toString());
+          if (msg.id !== undefined && this.pendingCommands.has(msg.id)) {
+            const handler = this.pendingCommands.get(msg.id)!;
+            this.pendingCommands.delete(msg.id);
+            if (msg.error) {
+              handler.reject(new Error(`CDP error ${msg.error.code}: ${msg.error.message}`));
+            } else {
+              handler.resolve(msg);
+            }
+          } else if (msg.method) {
+            const listeners = this.eventListeners.get(msg.method);
+            if (listeners) {
+              for (const fn of listeners) {
+                try { fn(msg.params ?? {}, msg.sessionId); } catch { /* isolate per-listener errors */ }
+              }
+            }
+          }
+        } catch {
+          // ignore malformed messages
+        }
+      });
+    });
+  }
+
+  send<T = Record<string, unknown>>(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<T> {
+    return new Promise((resolve, reject) => {
+      if (!this.ws || !this.connected) {
+        reject(new Error('CDP not connected'));
+        return;
+      }
+      // Cap in-flight commands to prevent unbounded Map growth
+      if (this.pendingCommands.size >= 1000) {
+        reject(new Error('CDP command queue full (>1000 in-flight commands)'));
+        return;
+      }
+      const id = this.nextId++;
+      const cmd: CdpCommand = { id, method, params };
+      if (sessionId) cmd.sessionId = sessionId;
+      this.pendingCommands.set(id, {
+        resolve: (r) => resolve((r.result ?? {}) as T),
+        reject,
+      });
+      this.ws.send(JSON.stringify(cmd), (err) => {
+        if (err) {
+          this.pendingCommands.delete(id);
+          reject(err);
+        }
+      });
+    });
+  }
+
+  on(event: string, fn: (params: Record<string, unknown>, sessionId?: string) => void): () => void {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, new Set());
+    }
+    const listeners = this.eventListeners.get(event)!;
+    // Cap listeners per event to prevent unbounded Set growth
+    if (listeners.size >= 100) {
+      throw new Error(`CDP event listener limit reached for event: ${event}`);
+    }
+    listeners.add(fn);
+    return () => this.eventListeners.get(event)?.delete(fn);
+  }
+
+  once(event: string, sessionId?: string): Promise<Record<string, unknown>> {
+    const [promise] = this.onceWithOff(event, sessionId);
+    return promise;
+  }
+
+  onceWithOff(event: string, sessionId?: string): [Promise<Record<string, unknown>>, () => void] {
+    let off: () => void = () => {};
+    const promise = new Promise<Record<string, unknown>>((resolve) => {
+      off = this.on(event, (params, sid) => {
+        if (sessionId !== undefined && sid !== sessionId) return;
+        off();
+        resolve(params);
+      });
+    });
+    return [promise, () => off()];
+  }
+
+  close(): void {
+    this.connected = false;
+    for (const { reject: r } of this.pendingCommands.values()) r(new Error('CDP connection closed'));
+    this.pendingCommands.clear();
+    this.ws?.close();
+    this.ws = null;
+    this.eventListeners.clear();
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+}
+
+const CDP_RESPONSE_SIZE_LIMIT = 10 * 1024 * 1024; // 10 MB
+
+async function readCdpJson(res: Response): Promise<unknown> {
+  const text = await res.text();
+  if (text.length > CDP_RESPONSE_SIZE_LIMIT) {
+    throw new Error(`CDP response too large: ${text.length} bytes`);
+  }
+  return JSON.parse(text);
+}
+
+export async function fetchTargets(port: number): Promise<CdpTarget[]> {
+  const res = await fetch(`http://127.0.0.1:${port}/json/list`);
+  if (!res.ok) throw new Error(`Failed to fetch targets: ${res.statusText}`);
+  return readCdpJson(res) as Promise<CdpTarget[]>;
+}
+
+export async function fetchNewTarget(port: number, url: string): Promise<CdpTarget> {
+  const res = await fetch(`http://127.0.0.1:${port}/json/new?${url}`);
+  if (!res.ok) throw new Error(`Failed to create target: ${res.statusText}`);
+  return readCdpJson(res) as Promise<CdpTarget>;
+}

package/src/browser/console-log.ts

@@ -0,0 +1,120 @@
+import type { CdpClient } from './cdp.js';
+
+export interface ConsoleMessage {
+  type: 'log' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
+  text: string;
+  timestamp: number;
+  url?: string;
+  lineNumber?: number;
+}
+
+export interface PageError {
+  text: string;
+  url?: string;
+  lineNumber?: number;
+  columnNumber?: number;
+  timestamp: number;
+}
+
+const _consoleMessages = new Map<string, ConsoleMessage[]>();
+const _pageErrors = new Map<string, PageError[]>();
+const _consoleListeners = new Map<string, Array<() => void>>();
+
+function messagesFor(sessionId: string): ConsoleMessage[] {
+  if (!_consoleMessages.has(sessionId)) _consoleMessages.set(sessionId, []);
+  return _consoleMessages.get(sessionId)!;
+}
+
+function errorsFor(sessionId: string): PageError[] {
+  if (!_pageErrors.has(sessionId)) _pageErrors.set(sessionId, []);
+  return _pageErrors.get(sessionId)!;
+}
+
+export function setupConsoleCapture(client: CdpClient, sessionId: string): void {
+  // Remove stale listeners from any prior connection on this sessionId
+  const prevOffs = _consoleListeners.get(sessionId);
+  if (prevOffs) { for (const off of prevOffs) off(); _consoleListeners.delete(sessionId); }
+
+  _consoleMessages.set(sessionId, []);
+  _pageErrors.set(sessionId, []);
+
+  const off1 = client.on('Runtime.consoleAPICalled', (params, sid) => {
+    if (sid !== sessionId) return;
+    const args = (params.args as Array<{ value?: unknown; description?: string }>) ?? [];
+    const text = args.map((a) => a.description ?? String(a.value ?? '')).join(' ');
+    const rawType = (params.type as string) === 'warning' ? 'warn' : (params.type as string);
+    messagesFor(sessionId).push({
+      type: (rawType as ConsoleMessage['type']) ?? 'log',
+      text,
+      timestamp: Date.now(),
+    });
+  });
+
+  const off2 = client.on('Log.entryAdded', (params, sid) => {
+    if (sid !== sessionId) return;
+    const entry = params.entry as { level?: string; text?: string; url?: string; lineNumber?: number };
+    // CDP uses 'warning' but ConsoleMessage type uses 'warn'
+    const rawLevel = entry.level === 'warning' ? 'warn' : entry.level;
+    messagesFor(sessionId).push({
+      type: (rawLevel as ConsoleMessage['type']) ?? 'log',
+      text: entry.text ?? '',
+      timestamp: Date.now(),
+      url: entry.url,
+      lineNumber: entry.lineNumber,
+    });
+  });
+
+  const off3 = client.on('Runtime.exceptionThrown', (params, sid) => {
+    if (sid !== sessionId) return;
+    const detail = params.exceptionDetails as {
+      text?: string;
+      url?: string;
+      lineNumber?: number;
+      columnNumber?: number;
+      exception?: { description?: string; value?: unknown };
+    };
+    const message = detail.exception?.description ?? detail.text ?? 'Unknown error';
+    errorsFor(sessionId).push({
+      text: message,
+      url: detail.url,
+      lineNumber: detail.lineNumber,
+      columnNumber: detail.columnNumber,
+      timestamp: Date.now(),
+    });
+  });
+
+  _consoleListeners.set(sessionId, [off1, off2, off3]);
+}
+
+export async function enableConsoleCapture(client: CdpClient, sessionId: string): Promise<void> {
+  await client.send('Runtime.enable', {}, sessionId);
+  await client.send('Log.enable', {}, sessionId);
+}
+
+export function getConsoleMessages(sessionId?: string): ConsoleMessage[] {
+  if (sessionId) return [...(messagesFor(sessionId))];
+  // Fallback: return all messages across all sessions (legacy callers)
+  return [..._consoleMessages.values()].flat();
+}
+
+export function clearConsoleMessages(sessionId?: string): void {
+  if (sessionId) { _consoleMessages.set(sessionId, []); return; }
+  _consoleMessages.clear();
+}
+
+export function getPageErrors(sessionId?: string): PageError[] {
+  if (sessionId) return [...(errorsFor(sessionId))];
+  return [..._pageErrors.values()].flat();
+}
+
+export function clearPageErrors(sessionId?: string): void {
+  if (sessionId) { _pageErrors.set(sessionId, []); return; }
+  _pageErrors.clear();
+}
+
+export function teardownConsoleCapture(sessionId: string): void {
+  const offs = _consoleListeners.get(sessionId);
+  if (offs) { for (const off of offs) off(); _consoleListeners.delete(sessionId); }
+  _consoleMessages.delete(sessionId);
+  _pageErrors.delete(sessionId);
+}