nothumanallowed 9.5.2 → 9.6.0

package/src/services/browser-engine.mjs

@@ -1,1240 +0,0 @@
-/**
- * NHA Browser Engine — Chrome DevTools Protocol (CDP) client.
- *
- * Controls Chrome/Chromium headless via the CDP WebSocket protocol.
- * Zero npm dependencies — pure Node.js 22.
- *
- * Capabilities:
- * - Launch Chrome headless (auto-detect path per OS)
- * - Navigate to URLs (with SSRF protection)
- * - Screenshot (full page or viewport, returns base64 PNG)
- * - Click elements by CSS selector or coordinates
- * - Type text into focused elements or selectors
- * - Fill forms (set input values via JS)
- * - Extract page text or HTML
- * - Execute arbitrary JavaScript in page context
- * - Wait for elements or navigation
- * - Cookie & localStorage management
- *
- * Architecture:
- * - Single persistent browser instance (lazy-launched)
- * - WebSocket connection to CDP (ws:// on localhost)
- * - JSON-RPC over WebSocket per CDP spec
- * - Graceful cleanup on process exit
- */
-
-import { spawn } from 'child_process';
-import { createConnection } from 'net';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-import dns from 'dns/promises';
-import net from 'net';
-import crypto from 'crypto';
-
-// ── Constants ────────────────────────────────────────────────────────────────
-
-const CDP_PORT = 9222;
-const LAUNCH_TIMEOUT_MS = 15000;
-const COMMAND_TIMEOUT_MS = 30000;
-const NAV_TIMEOUT_MS = 30000;
-const SCREENSHOT_TIMEOUT_MS = 15000;
-const MAX_OUTPUT_CHARS = 12000;
-
-// ── SSRF Protection (reused from web-tools.mjs pattern) ─────────────────────
-
-const PRIVATE_RANGES = [
-  { start: '10.0.0.0', end: '10.255.255.255' },
-  { start: '172.16.0.0', end: '172.31.255.255' },
-  { start: '192.168.0.0', end: '192.168.255.255' },
-  { start: '127.0.0.0', end: '127.255.255.255' },
-  { start: '169.254.0.0', end: '169.254.255.255' },
-  { start: '0.0.0.0', end: '0.255.255.255' },
-];
-
-function ipToLong(ip) {
-  const parts = ip.split('.').map(Number);
-  return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
-}
-
-function isPrivateIp(ip) {
-  if (!net.isIPv4(ip)) return false;
-  const long = ipToLong(ip);
-  for (const range of PRIVATE_RANGES) {
-    if (long >= ipToLong(range.start) && long <= ipToLong(range.end)) return true;
-  }
-  return false;
-}
-
-async function isSafeUrl(urlStr) {
-  let parsed;
-  try {
-    parsed = new URL(urlStr);
-  } catch {
-    return { safe: false, reason: 'Invalid URL' };
-  }
-
-  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
-    return { safe: false, reason: `Blocked protocol: ${parsed.protocol}` };
-  }
-
-  const hostname = parsed.hostname.toLowerCase();
-  if (
-    hostname === 'localhost' ||
-    hostname === '0.0.0.0' ||
-    hostname === '[::1]' ||
-    hostname === '::1' ||
-    /^0x[0-9a-f]+$/i.test(hostname) ||
-    /^\d+$/.test(hostname)
-  ) {
-    return { safe: false, reason: 'Blocked: localhost/internal' };
-  }
-
-  try {
-    const addresses = await dns.resolve4(hostname);
-    for (const addr of addresses) {
-      if (isPrivateIp(addr)) {
-        return { safe: false, reason: `Blocked: ${hostname} resolves to private IP ${addr}` };
-      }
-    }
-  } catch {
-    return { safe: false, reason: `DNS resolution failed for ${hostname}` };
-  }
-
-  return { safe: true };
-}
-
-// ── Chrome Path Detection ───────────────────────────────────────────────────
-
-function findChromePath() {
-  const platform = os.platform();
-
-  const candidates = {
-    darwin: [
-      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-      '/Applications/Chromium.app/Contents/MacOS/Chromium',
-      '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
-      '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
-      '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
-    ],
-    linux: [
-      '/usr/bin/google-chrome',
-      '/usr/bin/google-chrome-stable',
-      '/usr/bin/chromium',
-      '/usr/bin/chromium-browser',
-      '/snap/bin/chromium',
-      '/usr/bin/brave-browser',
-      '/usr/bin/microsoft-edge',
-    ],
-    win32: [
-      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
-      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
-      `${os.homedir()}\\AppData\\Local\\Google\\Chrome\\Application\\chrome.exe`,
-      'C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe',
-      'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
-    ],
-  };
-
-  const paths = candidates[platform] || candidates.linux;
-  for (const p of paths) {
-    try {
-      if (fs.existsSync(p)) return p;
-    } catch { /* skip */ }
-  }
-
-  return null;
-}
-
-// ── CDP WebSocket Client ────────────────────────────────────────────────────
-
-/**
- * Minimal WebSocket client for CDP.
- * Implements just enough of RFC 6455 to communicate with Chrome.
- * Handles text frames only (CDP is JSON text).
- */
-class CDPWebSocket {
-  constructor() {
-    this._socket = null;
-    this._callbacks = new Map();
-    this._events = new Map();
-    this._buffer = Buffer.alloc(0);
-    this._connected = false;
-    this._nextId = 1;
-  }
-
-  /**
-   * Connect to CDP WebSocket endpoint.
-   * @param {string} wsUrl - e.g. ws://127.0.0.1:9222/devtools/page/ABC123
-   * @returns {Promise<void>}
-   */
-  connect(wsUrl) {
-    return new Promise((resolve, reject) => {
-      const parsed = new URL(wsUrl);
-      const host = parsed.hostname;
-      const port = parseInt(parsed.port, 10);
-      const pathname = parsed.pathname + (parsed.search || '');
-
-      this._socket = createConnection({ host, port }, () => {
-        // Send WebSocket upgrade request
-        const key = crypto.randomBytes(16).toString('base64');
-        const request = [
-          `GET ${pathname} HTTP/1.1`,
-          `Host: ${host}:${port}`,
-          'Upgrade: websocket',
-          'Connection: Upgrade',
-          `Sec-WebSocket-Key: ${key}`,
-          'Sec-WebSocket-Version: 13',
-          '',
-          '',
-        ].join('\r\n');
-
-        this._socket.write(request);
-      });
-
-      let handshakeDone = false;
-
-      this._socket.on('data', (data) => {
-        if (!handshakeDone) {
-          // Check for HTTP 101 Switching Protocols
-          const str = data.toString();
-          if (str.includes('101')) {
-            handshakeDone = true;
-            this._connected = true;
-            // Find end of HTTP headers
-            const headerEnd = data.indexOf('\r\n\r\n');
-            if (headerEnd !== -1 && headerEnd + 4 < data.length) {
-              // Process remaining data as WebSocket frames
-              this._processData(data.subarray(headerEnd + 4));
-            }
-            resolve();
-          } else {
-            reject(new Error(`WebSocket handshake failed: ${str.slice(0, 200)}`));
-          }
-          return;
-        }
-
-        this._processData(data);
-      });
-
-      this._socket.on('error', (err) => {
-        if (!handshakeDone) reject(err);
-      });
-
-      this._socket.on('close', () => {
-        this._connected = false;
-      });
-
-      setTimeout(() => {
-        if (!handshakeDone) reject(new Error('WebSocket connection timeout'));
-      }, 10000);
-    });
-  }
-
-  /**
-   * Process incoming WebSocket data — accumulate and parse frames.
-   */
-  _processData(data) {
-    this._buffer = Buffer.concat([this._buffer, data]);
-    this._parseFrames();
-  }
-
-  /**
-   * Parse WebSocket frames from buffer.
-   * CDP only sends text frames (opcode 0x1) with no masking (server→client).
-   */
-  _parseFrames() {
-    while (this._buffer.length >= 2) {
-      const firstByte = this._buffer[0];
-      const secondByte = this._buffer[1];
-      const opcode = firstByte & 0x0f;
-      const masked = (secondByte & 0x80) !== 0;
-      let payloadLen = secondByte & 0x7f;
-      let offset = 2;
-
-      if (payloadLen === 126) {
-        if (this._buffer.length < 4) return; // Need more data
-        payloadLen = this._buffer.readUInt16BE(2);
-        offset = 4;
-      } else if (payloadLen === 127) {
-        if (this._buffer.length < 10) return;
-        // Read as BigInt and convert (CDP payloads shouldn't exceed 2^53)
-        payloadLen = Number(this._buffer.readBigUInt64BE(2));
-        offset = 10;
-      }
-
-      if (masked) offset += 4; // Skip mask key (shouldn't happen for server→client)
-
-      const totalLen = offset + payloadLen;
-      if (this._buffer.length < totalLen) return; // Need more data
-
-      const payload = this._buffer.subarray(offset, totalLen);
-      this._buffer = this._buffer.subarray(totalLen);
-
-      // Handle text frame (opcode 1) — CDP JSON messages
-      if (opcode === 0x01) {
-        const text = payload.toString('utf-8');
-        try {
-          const msg = JSON.parse(text);
-          this._handleMessage(msg);
-        } catch { /* ignore malformed JSON */ }
-      }
-      // opcode 0x08 = close
-      else if (opcode === 0x08) {
-        this.close();
-      }
-      // opcode 0x09 = ping → send pong
-      else if (opcode === 0x09) {
-        this._sendFrame(0x0a, payload);
-      }
-    }
-  }
-
-  /**
-   * Handle a parsed CDP message — route to callbacks or event listeners.
-   */
-  _handleMessage(msg) {
-    // Response to a command
-    if (msg.id !== undefined && this._callbacks.has(msg.id)) {
-      const { resolve, reject } = this._callbacks.get(msg.id);
-      this._callbacks.delete(msg.id);
-      if (msg.error) {
-        reject(new Error(`CDP error: ${msg.error.message} (code ${msg.error.code})`));
-      } else {
-        resolve(msg.result || {});
-      }
-    }
-    // Event
-    else if (msg.method) {
-      const listeners = this._events.get(msg.method) || [];
-      for (const fn of listeners) {
-        try { fn(msg.params); } catch { /* ignore listener errors */ }
-      }
-    }
-  }
-
-  /**
-   * Send a WebSocket text frame (client→server, masked per RFC 6455).
-   */
-  _sendFrame(opcode, payload) {
-    if (!this._connected || !this._socket) return;
-
-    const payloadBuf = typeof payload === 'string' ? Buffer.from(payload, 'utf-8') : payload;
-    const len = payloadBuf.length;
-
-    // Client frames MUST be masked
-    const mask = crypto.randomBytes(4);
-    let header;
-
-    if (len < 126) {
-      header = Buffer.alloc(6);
-      header[0] = 0x80 | opcode; // FIN + opcode
-      header[1] = 0x80 | len;    // MASK + length
-      mask.copy(header, 2);
-    } else if (len < 65536) {
-      header = Buffer.alloc(8);
-      header[0] = 0x80 | opcode;
-      header[1] = 0x80 | 126;
-      header.writeUInt16BE(len, 2);
-      mask.copy(header, 4);
-    } else {
-      header = Buffer.alloc(14);
-      header[0] = 0x80 | opcode;
-      header[1] = 0x80 | 127;
-      header.writeBigUInt64BE(BigInt(len), 2);
-      mask.copy(header, 10);
-    }
-
-    // Apply mask to payload
-    const masked = Buffer.alloc(len);
-    for (let i = 0; i < len; i++) {
-      masked[i] = payloadBuf[i] ^ mask[i % 4];
-    }
-
-    this._socket.write(Buffer.concat([header, masked]));
-  }
-
-  /**
-   * Send a CDP command and wait for response.
-   * @param {string} method - CDP method (e.g. "Page.navigate")
-   * @param {object} params - CDP params
-   * @param {number} timeout - Timeout in ms
-   * @returns {Promise<object>}
-   */
-  send(method, params = {}, timeout = COMMAND_TIMEOUT_MS) {
-    return new Promise((resolve, reject) => {
-      const id = this._nextId++;
-      const timer = setTimeout(() => {
-        this._callbacks.delete(id);
-        reject(new Error(`CDP command timeout: ${method} (${timeout}ms)`));
-      }, timeout);
-
-      this._callbacks.set(id, {
-        resolve: (result) => { clearTimeout(timer); resolve(result); },
-        reject: (err) => { clearTimeout(timer); reject(err); },
-      });
-
-      this._sendFrame(0x01, JSON.stringify({ id, method, params }));
-    });
-  }
-
-  /**
-   * Register an event listener.
-   */
-  on(event, fn) {
-    if (!this._events.has(event)) this._events.set(event, []);
-    this._events.get(event).push(fn);
-  }
-
-  /**
-   * Remove all listeners for an event.
-   */
-  off(event) {
-    this._events.delete(event);
-  }
-
-  /**
-   * Wait for a specific event, with timeout.
-   */
-  waitForEvent(event, timeout = NAV_TIMEOUT_MS) {
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.off(event);
-        reject(new Error(`Timeout waiting for ${event}`));
-      }, timeout);
-
-      this.on(event, (params) => {
-        clearTimeout(timer);
-        this.off(event);
-        resolve(params);
-      });
-    });
-  }
-
-  /**
-   * Close the WebSocket connection.
-   */
-  close() {
-    this._connected = false;
-    if (this._socket) {
-      try {
-        this._sendFrame(0x08, Buffer.alloc(0));
-        this._socket.end();
-      } catch { /* best effort */ }
-      this._socket = null;
-    }
-    // Reject all pending callbacks
-    for (const [id, { reject }] of this._callbacks) {
-      reject(new Error('WebSocket closed'));
-    }
-    this._callbacks.clear();
-  }
-
-  get connected() {
-    return this._connected;
-  }
-}
-
-// ── Browser Instance Manager ────────────────────────────────────────────────
-
-/** @type {{ process: import('child_process').ChildProcess, ws: CDPWebSocket, wsUrl: string, userDataDir: string } | null} */
-let _browser = null;
-
-/**
- * Find a free port for CDP.
- */
-function findFreePort() {
-  return new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.listen(0, '127.0.0.1', () => {
-      const port = server.address().port;
-      server.close(() => resolve(port));
-    });
-    server.on('error', reject);
-  });
-}
-
-/**
- * Wait for CDP to become available.
- * Uses Chrome's stderr to get the browser WS URL, then creates a page target.
- * Falls back to polling /json endpoint.
- */
-async function waitForCDP(port, stderrPromise, timeoutMs = LAUNCH_TIMEOUT_MS) {
-  const start = Date.now();
-
-  // Wait for Chrome to print its DevTools WS URL
-  let browserWsUrl;
-  try {
-    browserWsUrl = await Promise.race([
-      stderrPromise,
-      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 8000)),
-    ]);
-  } catch { /* continue to polling */ }
-
-  // Extract actual port from wsUrl (may differ from requested port)
-  const actualPort = browserWsUrl
-    ? parseInt(new URL(browserWsUrl).port, 10) || port
-    : port;
-
-  // Poll /json to find or create a page target
-  while (Date.now() - start < timeoutMs) {
-    try {
-      const res = await fetch(`http://127.0.0.1:${actualPort}/json`, {
-        signal: AbortSignal.timeout(3000),
-      });
-      if (res.ok) {
-        const targets = await res.json();
-        // Look for an existing page target
-        const page = targets.find(t => t.type === 'page');
-        if (page && page.webSocketDebuggerUrl) {
-          return page.webSocketDebuggerUrl;
-        }
-
-        // No page target — create one via /json/new
-        try {
-          const newRes = await fetch(`http://127.0.0.1:${actualPort}/json/new?about:blank`, {
-            method: 'PUT',
-            signal: AbortSignal.timeout(3000),
-          });
-          if (newRes.ok) {
-            const newPage = await newRes.json();
-            if (newPage.webSocketDebuggerUrl) {
-              return newPage.webSocketDebuggerUrl;
-            }
-          }
-        } catch { /* /json/new might not work, keep polling */ }
-      }
-    } catch { /* not ready yet */ }
-    await new Promise(r => setTimeout(r, 300));
-  }
-  throw new Error(`Chrome CDP not available after ${timeoutMs}ms. Is Chrome installed?`);
-}
-
-/**
- * Launch Chrome headless and connect via CDP.
- * Returns the browser instance or throws.
- */
-async function launchBrowser() {
-  if (_browser && _browser.ws.connected) return _browser;
-
-  const chromePath = findChromePath();
-  if (!chromePath) {
-    throw new Error(
-      'Chrome/Chromium not found. Install Chrome or set CHROME_PATH environment variable.\n' +
-      'Checked paths:\n' +
-      '  macOS: /Applications/Google Chrome.app\n' +
-      '  Linux: /usr/bin/google-chrome, /usr/bin/chromium\n' +
-      '  Windows: C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
-    );
-  }
-
-  const userDataDir = path.join(os.tmpdir(), `nha-browser-${Date.now()}`);
-  fs.mkdirSync(userDataDir, { recursive: true });
-
-  const port = await findFreePort();
-
-  // Realistic user agent to avoid bot detection on major sites
-  const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
-
-  const chromeArgs = [
-    `--remote-debugging-port=${port}`,
-    '--headless=new',
-    `--user-data-dir=${userDataDir}`,
-    `--user-agent=${UA}`,
-    '--no-first-run',
-    '--no-default-browser-check',
-    '--disable-blink-features=AutomationControlled',
-    '--disable-background-networking',
-    '--disable-background-timer-throttling',
-    '--disable-backgrounding-occluded-windows',
-    '--disable-breakpad',
-    '--disable-component-update',
-    '--disable-default-apps',
-    '--disable-dev-shm-usage',
-    '--disable-extensions',
-    '--disable-hang-monitor',
-    '--disable-ipc-flooding-protection',
-    '--disable-popup-blocking',
-    '--disable-prompt-on-repost',
-    '--disable-renderer-backgrounding',
-    '--disable-sync',
-    '--disable-translate',
-    '--metrics-recording-only',
-    '--safebrowsing-disable-auto-update',
-    '--window-size=1920,1080',
-    'about:blank',
-  ];
-
-  const useChromePath = process.env.CHROME_PATH || chromePath;
-
-  const proc = spawn(useChromePath, chromeArgs, {
-    stdio: ['ignore', 'pipe', 'pipe'],
-    detached: false,
-  });
-
-  // Capture stderr for debugging + extract DevTools WS URL
-  let stderrBuf = '';
-  const stderrWsPromise = new Promise((resolve) => {
-    proc.stderr.on('data', (d) => {
-      stderrBuf += d.toString();
-      // Chrome prints: "DevTools listening on ws://127.0.0.1:PORT/devtools/browser/UUID"
-      const wsMatch = stderrBuf.match(/DevTools listening on (ws:\/\/\S+)/);
-      if (wsMatch) resolve(wsMatch[1]);
-    });
-  });
-
-  proc.on('error', (err) => {
-    throw new Error(`Failed to launch Chrome: ${err.message}`);
-  });
-
-  // Wait for CDP to be ready
-  let wsUrl;
-  try {
-    wsUrl = await waitForCDP(port, stderrWsPromise);
-  } catch (err) {
-    proc.kill('SIGTERM');
-    // Wait for Chrome to fully exit before cleaning up
-    await new Promise(r => setTimeout(r, 1000));
-    try { fs.rmSync(userDataDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 }); } catch {}
-    throw new Error(`${err.message}\nChrome stderr: ${stderrBuf.slice(0, 500)}`);
-  }
-
-  // Connect WebSocket
-  const ws = new CDPWebSocket();
-  await ws.connect(wsUrl);
-
-  // Enable required CDP domains
-  await ws.send('Page.enable');
-  await ws.send('Runtime.enable');
-  await ws.send('Network.enable');
-  await ws.send('DOM.enable');
-
-  // Anti-detection: remove navigator.webdriver flag and other headless indicators
-  await ws.send('Page.addScriptToEvaluateOnNewDocument', {
-    source: `
-      Object.defineProperty(navigator, 'webdriver', { get: () => false });
-      Object.defineProperty(navigator, 'languages', { get: () => ['it-IT', 'it', 'en-US', 'en'] });
-      Object.defineProperty(navigator, 'plugins', { get: () => [1, 2, 3, 4, 5] });
-      window.chrome = { runtime: {} };
-    `,
-  });
-
-  _browser = { process: proc, ws, wsUrl, userDataDir, port };
-
-  // Cleanup on process exit
-  const cleanup = () => {
-    if (_browser) {
-      try { _browser.ws.close(); } catch {}
-      try { _browser.process.kill('SIGTERM'); } catch {}
-      try { fs.rmSync(_browser.userDataDir, { recursive: true, force: true }); } catch {}
-      _browser = null;
-    }
-  };
-
-  process.on('exit', cleanup);
-  process.on('SIGINT', cleanup);
-  process.on('SIGTERM', cleanup);
-
-  return _browser;
-}
-
-/**
- * Get the active browser, launching if needed.
- */
-async function getBrowser() {
-  if (_browser && _browser.ws.connected) return _browser;
-  return launchBrowser();
-}
-
-// ── Public API ──────────────────────────────────────────────────────────────
-
-/**
- * Open a URL in the browser.
- * SSRF-protected — blocks private IPs, localhost, non-HTTP protocols.
- *
- * @param {string} url - URL to navigate to
- * @param {object} [options]
- * @param {number} [options.timeout] - Navigation timeout in ms (default 30s)
- * @param {boolean} [options.waitForLoad] - Wait for page load event (default true)
- * @returns {Promise<{ title: string, url: string, status: number }>}
- */
-export async function browserOpen(url, options = {}) {
-  // SSRF check
-  const check = await isSafeUrl(url);
-  if (!check.safe) {
-    return { error: true, message: `SSRF blocked: ${check.reason}` };
-  }
-
-  const browser = await getBrowser();
-  const timeout = options.timeout || NAV_TIMEOUT_MS;
-  const waitForLoad = options.waitForLoad !== false;
-
-  // Navigate
-  const navResult = await browser.ws.send('Page.navigate', { url }, timeout);
-
-  if (navResult.errorText) {
-    return { error: true, message: `Navigation error: ${navResult.errorText}` };
-  }
-
-  // Wait for load
-  if (waitForLoad) {
-    try {
-      await browser.ws.waitForEvent('Page.loadEventFired', timeout);
-    } catch {
-      // Page may not fire load event (e.g. streaming pages), continue anyway
-    }
-    // Small delay for JS rendering
-    await new Promise(r => setTimeout(r, 500));
-  }
-
-  // Get page info
-  const titleResult = await browser.ws.send('Runtime.evaluate', {
-    expression: 'document.title',
-    returnByValue: true,
-  });
-
-  const urlResult = await browser.ws.send('Runtime.evaluate', {
-    expression: 'window.location.href',
-    returnByValue: true,
-  });
-
-  // Check final URL for SSRF (after redirects)
-  const finalUrl = urlResult.result?.value || url;
-  if (finalUrl !== url) {
-    const finalCheck = await isSafeUrl(finalUrl);
-    if (!finalCheck.safe) {
-      // Navigate away from the blocked page
-      await browser.ws.send('Page.navigate', { url: 'about:blank' });
-      return { error: true, message: `Redirect blocked: ${finalCheck.reason}` };
-    }
-  }
-
-  return {
-    error: false,
-    title: titleResult.result?.value || '',
-    url: finalUrl,
-  };
-}
-
-/**
- * Take a screenshot of the current page.
- *
- * @param {object} [options]
- * @param {boolean} [options.fullPage] - Capture full scrollable page (default false)
- * @param {'png'|'jpeg'|'webp'} [options.format] - Image format (default 'png')
- * @param {number} [options.quality] - JPEG/WebP quality 0-100 (default 80)
- * @param {string} [options.saveTo] - Save to file path (otherwise returns base64)
- * @returns {Promise<{ base64: string, width: number, height: number, savedTo?: string }>}
- */
-export async function browserScreenshot(options = {}) {
-  const browser = await getBrowser();
-  const format = options.format || 'png';
-  const quality = format === 'png' ? undefined : (options.quality || 80);
-
-  const params = {
-    format,
-    ...(quality !== undefined && { quality }),
-  };
-
-  if (options.fullPage) {
-    // Get full page dimensions
-    const metrics = await browser.ws.send('Page.getLayoutMetrics');
-    const { width, height } = metrics.contentSize || metrics.cssContentSize || { width: 1920, height: 1080 };
-
-    // Set viewport to full page size (capped)
-    const cappedHeight = Math.min(height, 16384); // Chrome limit
-    await browser.ws.send('Emulation.setDeviceMetricsOverride', {
-      width: Math.ceil(width),
-      height: Math.ceil(cappedHeight),
-      deviceScaleFactor: 1,
-      mobile: false,
-    });
-
-    params.clip = { x: 0, y: 0, width: Math.ceil(width), height: Math.ceil(cappedHeight), scale: 1 };
-  }
-
-  const result = await browser.ws.send('Page.captureScreenshot', params, SCREENSHOT_TIMEOUT_MS);
-
-  // Reset viewport if we changed it
-  if (options.fullPage) {
-    await browser.ws.send('Emulation.clearDeviceMetricsOverride');
-  }
-
-  const base64 = result.data;
-
-  if (options.saveTo) {
-    const absPath = path.resolve(options.saveTo);
-    fs.writeFileSync(absPath, Buffer.from(base64, 'base64'));
-    return { error: false, base64, savedTo: absPath, size: base64.length };
-  }
-
-  return { error: false, base64, size: base64.length };
-}
-
-/**
- * Click an element by CSS selector, visible text, or coordinates.
- *
- * @param {object} target
- * @param {string} [target.selector] - CSS selector to click
- * @param {string} [target.text] - Visible text of a button/link/element to click (case-insensitive partial match)
- * @param {number} [target.x] - X coordinate
- * @param {number} [target.y] - Y coordinate
- * @returns {Promise<{ clicked: boolean, selector?: string }>}
- */
-export async function browserClick(target) {
-  const browser = await getBrowser();
-
-  let x, y;
-  let label = '';
-
-  if (target.text) {
-    // Find element by visible text — searches buttons, links, and all clickable elements
-    const searchText = target.text;
-    const result = await browser.ws.send('Runtime.evaluate', {
-      expression: `(() => {
-        const searchText = ${JSON.stringify(searchText)}.toLowerCase();
-        // Search in priority order: buttons, links, then any visible element
-        const candidates = [
-          ...document.querySelectorAll('button, [role="button"], input[type="submit"], input[type="button"]'),
-          ...document.querySelectorAll('a'),
-          ...document.querySelectorAll('[onclick], [tabindex]'),
-        ];
-        for (const el of candidates) {
-          const text = (el.textContent || el.value || el.getAttribute('aria-label') || '').trim();
-          if (text.toLowerCase().includes(searchText) && el.offsetHeight > 0 && el.offsetWidth > 0) {
-            const rect = el.getBoundingClientRect();
-            if (rect.width > 0 && rect.height > 0) {
-              return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2, tag: el.tagName, text: text.slice(0, 60) };
-            }
-          }
-        }
-        return null;
-      })()`,
-      returnByValue: true,
-    });
-
-    const info = result.result?.value;
-    if (!info) {
-      return { error: true, message: `No clickable element found with text "${searchText}". Try browser_extract to see visible buttons.` };
-    }
-
-    x = Math.round(info.x);
-    y = Math.round(info.y);
-    label = `"${info.text}" (${info.tag})`;
-  } else if (target.selector) {
-    // Find element by CSS selector and get its center point
-    const result = await browser.ws.send('Runtime.evaluate', {
-      expression: `(() => {
-        const el = document.querySelector(${JSON.stringify(target.selector)});
-        if (!el) return null;
-        const rect = el.getBoundingClientRect();
-        return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2, tag: el.tagName, text: el.textContent?.slice(0, 50) };
-      })()`,
-      returnByValue: true,
-      awaitPromise: false,
-    });
-
-    const info = result.result?.value;
-    if (!info) {
-      return { error: true, message: `Element not found: ${target.selector}` };
-    }
-
-    x = Math.round(info.x);
-    y = Math.round(info.y);
-    label = target.selector;
-  } else if (target.x !== undefined && target.y !== undefined) {
-    x = target.x;
-    y = target.y;
-    label = `(${x}, ${y})`;
-  } else {
-    return { error: true, message: 'Provide text, CSS selector, or x/y coordinates' };
-  }
-
-  // Dispatch mouse events: move → down → up (simulates real click)
-  await browser.ws.send('Input.dispatchMouseEvent', {
-    type: 'mouseMoved', x, y,
-  });
-  await browser.ws.send('Input.dispatchMouseEvent', {
-    type: 'mousePressed', x, y, button: 'left', clickCount: 1,
-  });
-  await browser.ws.send('Input.dispatchMouseEvent', {
-    type: 'mouseReleased', x, y, button: 'left', clickCount: 1,
-  });
-
-  // Wait for any navigation or JS handlers triggered by the click
-  await new Promise(r => setTimeout(r, 500));
-
-  // Check if the click triggered a navigation — wait for it
-  try {
-    const navCheck = await browser.ws.send('Runtime.evaluate', {
-      expression: 'document.readyState',
-      returnByValue: true,
-    });
-    if (navCheck.result?.value === 'loading') {
-      // Page is navigating — wait for load
-      try {
-        await browser.ws.waitForEvent('Page.loadEventFired', 10000);
-        await new Promise(r => setTimeout(r, 500));
-      } catch { /* timeout ok */ }
-    }
-  } catch { /* evaluation failed during navigation, that's fine */ }
-
-  return { error: false, clicked: true, x, y, selector: label || target.selector || `(${x}, ${y})` };
-}
-
-/**
- * Type text into the currently focused element or a specific selector.
- *
- * @param {object} params
- * @param {string} params.text - Text to type
- * @param {string} [params.selector] - CSS selector to focus first
- * @param {boolean} [params.clear] - Clear existing content before typing (default false)
- * @param {number} [params.delay] - Delay between keystrokes in ms (default 0 = instant)
- * @returns {Promise<{ typed: boolean, length: number }>}
- */
-export async function browserType(params) {
-  const browser = await getBrowser();
-
-  if (params.selector) {
-    // Click the element first to focus it
-    const clickResult = await browserClick({ selector: params.selector });
-    if (clickResult.error) return clickResult;
-    await new Promise(r => setTimeout(r, 100));
-  }
-
-  if (params.clear) {
-    // Select all and delete
-    await browser.ws.send('Input.dispatchKeyEvent', {
-      type: 'keyDown', key: 'a', code: 'KeyA',
-      modifiers: os.platform() === 'darwin' ? 4 : 2, // Meta (Mac) or Ctrl
-    });
-    await browser.ws.send('Input.dispatchKeyEvent', {
-      type: 'keyUp', key: 'a', code: 'KeyA',
-    });
-    await browser.ws.send('Input.dispatchKeyEvent', {
-      type: 'keyDown', key: 'Backspace', code: 'Backspace',
-    });
-    await browser.ws.send('Input.dispatchKeyEvent', {
-      type: 'keyUp', key: 'Backspace', code: 'Backspace',
-    });
-    await new Promise(r => setTimeout(r, 50));
-  }
-
-  const text = params.text || '';
-  const delay = params.delay || 0;
-
-  if (delay > 0) {
-    // Type character by character with delay
-    for (const char of text) {
-      await browser.ws.send('Input.dispatchKeyEvent', {
-        type: 'keyDown', text: char, key: char,
-        unmodifiedText: char,
-      });
-      await browser.ws.send('Input.dispatchKeyEvent', {
-        type: 'keyUp', key: char,
-      });
-      if (delay > 0) await new Promise(r => setTimeout(r, delay));
-    }
-  } else {
-    // Insert text all at once (faster)
-    await browser.ws.send('Input.insertText', { text });
-  }
-
-  return { error: false, typed: true, length: text.length, selector: params.selector || '(focused)' };
-}
-
-/**
- * Extract text content or HTML from the current page.
- *
- * @param {object} [options]
- * @param {string} [options.selector] - CSS selector to extract from (default: body)
- * @param {'text'|'html'|'value'|'attribute'} [options.mode] - Extraction mode (default 'text')
- * @param {string} [options.attribute] - Attribute name when mode='attribute'
- * @param {boolean} [options.all] - Extract from all matching elements (default false)
- * @returns {Promise<{ content: string, length: number }>}
- */
-export async function browserExtract(options = {}) {
-  const browser = await getBrowser();
-  const selector = options.selector || 'body';
-  const mode = options.mode || 'text';
-
-  let expression;
-
-  if (options.all) {
-    expression = `(() => {
-      const els = document.querySelectorAll(${JSON.stringify(selector)});
-      if (els.length === 0) return null;
-      return Array.from(els).map((el, i) => {
-        ${mode === 'html' ? 'return el.innerHTML;' : ''}
-        ${mode === 'value' ? 'return el.value || el.textContent;' : ''}
-        ${mode === 'attribute' ? `return el.getAttribute(${JSON.stringify(options.attribute || '')});` : ''}
-        ${mode === 'text' ? 'return el.textContent;' : ''}
-      }).filter(Boolean).join('\\n---\\n');
-    })()`;
-  } else {
-    expression = `(() => {
-      const el = document.querySelector(${JSON.stringify(selector)});
-      if (!el) return null;
-      ${mode === 'html' ? 'return el.innerHTML;' : ''}
-      ${mode === 'value' ? 'return el.value || el.textContent;' : ''}
-      ${mode === 'attribute' ? `return el.getAttribute(${JSON.stringify(options.attribute || '')});` : ''}
-      ${mode === 'text' ? 'return el.textContent;' : ''}
-    })()`;
-  }
-
-  const result = await browser.ws.send('Runtime.evaluate', {
-    expression,
-    returnByValue: true,
-  });
-
-  const content = result.result?.value;
-  if (content === null || content === undefined) {
-    return { error: true, message: `Element not found: ${selector}` };
-  }
-
-  // Trim and cap output
-  let trimmed = typeof content === 'string'
-    ? content.replace(/\s+/g, ' ').trim()
-    : String(content);
-
-  if (trimmed.length > MAX_OUTPUT_CHARS) {
-    trimmed = trimmed.slice(0, MAX_OUTPUT_CHARS) + '\n\n[... truncated at 12000 chars]';
-  }
-
-  return { error: false, content: trimmed, length: trimmed.length, selector };
-}
-
-/**
- * Execute arbitrary JavaScript in the page context.
- *
- * @param {string} code - JavaScript code to execute
- * @param {object} [options]
- * @param {boolean} [options.awaitPromise] - Await promise result (default true)
- * @returns {Promise<{ result: any, type: string }>}
- */
-export async function browserEval(code, options = {}) {
-  const browser = await getBrowser();
-
-  // Auto-wrap object literals: {key: val} → ({key: val}) to avoid block/label ambiguity
-  let expression = code.trim();
-  if (expression.startsWith('{') && !expression.startsWith('{(')) {
-    expression = `(${expression})`;
-  }
-
-  let result = await browser.ws.send('Runtime.evaluate', {
-    expression,
-    returnByValue: true,
-    awaitPromise: options.awaitPromise !== false,
-    generatePreview: true,
-  }, COMMAND_TIMEOUT_MS);
-
-  // If SyntaxError, retry with IIFE wrapper
-  if (result.exceptionDetails?.exception?.description?.includes('SyntaxError')) {
-    result = await browser.ws.send('Runtime.evaluate', {
-      expression: `(() => { return (${code.trim()}); })()`,
-      returnByValue: true,
-      awaitPromise: options.awaitPromise !== false,
-      generatePreview: true,
-    }, COMMAND_TIMEOUT_MS);
-  }
-
-  if (result.exceptionDetails) {
-    const errMsg = result.exceptionDetails.exception?.description
-      || result.exceptionDetails.text
-      || 'Unknown JS error';
-    return { error: true, message: `JS error: ${errMsg}` };
-  }
-
-  const value = result.result?.value;
-  const type = result.result?.type;
-
-  let display;
-  if (type === 'undefined') {
-    display = 'undefined';
-  } else if (value === null) {
-    display = 'null';
-  } else if (typeof value === 'object') {
-    try {
-      display = JSON.stringify(value, null, 2);
-    } catch {
-      display = String(value);
-    }
-  } else {
-    display = String(value);
-  }
-
-  if (display.length > MAX_OUTPUT_CHARS) {
-    display = display.slice(0, MAX_OUTPUT_CHARS) + '\n\n[... truncated]';
-  }
-
-  return { error: false, result: display, type: type || 'unknown' };
-}
-
-/**
- * Wait for an element to appear on the page.
- *
- * @param {string} selector - CSS selector to wait for
- * @param {object} [options]
- * @param {number} [options.timeout] - Max wait time in ms (default 10000)
- * @param {boolean} [options.visible] - Wait for element to be visible (default true)
- * @returns {Promise<{ found: boolean }>}
- */
-export async function browserWaitFor(selector, options = {}) {
-  const browser = await getBrowser();
-  const timeout = options.timeout || 10000;
-  const visible = options.visible !== false;
-
-  const start = Date.now();
-  while (Date.now() - start < timeout) {
-    const check = await browser.ws.send('Runtime.evaluate', {
-      expression: `(() => {
-        const el = document.querySelector(${JSON.stringify(selector)});
-        if (!el) return false;
-        ${visible ? `
-        const style = window.getComputedStyle(el);
-        if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') return false;
-        const rect = el.getBoundingClientRect();
-        if (rect.width === 0 || rect.height === 0) return false;
-        ` : ''}
-        return true;
-      })()`,
-      returnByValue: true,
-    });
-
-    if (check.result?.value === true) {
-      return { error: false, found: true, selector, elapsed: Date.now() - start };
-    }
-
-    await new Promise(r => setTimeout(r, 200));
-  }
-
-  return { error: true, message: `Element "${selector}" not found after ${timeout}ms` };
-}
-
-/**
- * Get the current page URL and title.
- */
-export async function browserInfo() {
-  const browser = await getBrowser();
-
-  const result = await browser.ws.send('Runtime.evaluate', {
-    expression: `({ url: window.location.href, title: document.title, readyState: document.readyState })`,
-    returnByValue: true,
-  });
-
-  return {
-    error: false,
-    url: result.result?.value?.url || 'about:blank',
-    title: result.result?.value?.title || '',
-    readyState: result.result?.value?.readyState || 'unknown',
-  };
-}
-
-/**
- * Close the browser instance.
- */
-export async function browserClose() {
-  if (!_browser) return { error: false, message: 'No browser running' };
-
-  try { _browser.ws.close(); } catch {}
-  try { _browser.process.kill('SIGTERM'); } catch {}
-  try { fs.rmSync(_browser.userDataDir, { recursive: true, force: true }); } catch {}
-  _browser = null;
-
-  return { error: false, message: 'Browser closed' };
-}
-
-/**
- * Press a keyboard key (Enter, Tab, Escape, ArrowDown, etc.)
- *
- * @param {string} key - Key name (e.g. 'Enter', 'Tab', 'Escape')
- * @param {object} [options]
- * @param {boolean} [options.ctrl] - Hold Ctrl/Meta
- * @param {boolean} [options.shift] - Hold Shift
- * @param {boolean} [options.alt] - Hold Alt
- * @returns {Promise<{ pressed: boolean }>}
- */
-export async function browserKeyPress(key, options = {}) {
-  const browser = await getBrowser();
-
-  let modifiers = 0;
-  if (options.alt) modifiers |= 1;
-  if (options.ctrl) modifiers |= 2;
-  if (os.platform() === 'darwin' && options.ctrl) modifiers |= 4; // Meta on Mac
-  if (options.shift) modifiers |= 8;
-
-  // Map common key names to CDP key codes
-  const keyMap = {
-    'Enter': { key: 'Enter', code: 'Enter' },
-    'Tab': { key: 'Tab', code: 'Tab' },
-    'Escape': { key: 'Escape', code: 'Escape' },
-    'Backspace': { key: 'Backspace', code: 'Backspace' },
-    'Delete': { key: 'Delete', code: 'Delete' },
-    'ArrowUp': { key: 'ArrowUp', code: 'ArrowUp' },
-    'ArrowDown': { key: 'ArrowDown', code: 'ArrowDown' },
-    'ArrowLeft': { key: 'ArrowLeft', code: 'ArrowLeft' },
-    'ArrowRight': { key: 'ArrowRight', code: 'ArrowRight' },
-    'Space': { key: ' ', code: 'Space' },
-  };
-
-  const mapped = keyMap[key] || { key, code: `Key${key.toUpperCase()}` };
-
-  await browser.ws.send('Input.dispatchKeyEvent', {
-    type: 'keyDown',
-    key: mapped.key,
-    code: mapped.code,
-    modifiers,
-  });
-  await browser.ws.send('Input.dispatchKeyEvent', {
-    type: 'keyUp',
-    key: mapped.key,
-    code: mapped.code,
-    modifiers,
-  });
-
-  return { error: false, pressed: true, key };
-}
-
-/**
- * Scroll the page.
- *
- * @param {object} [options]
- * @param {'up'|'down'|'top'|'bottom'} [options.direction] - Scroll direction (default 'down')
- * @param {number} [options.amount] - Pixels to scroll (default 500)
- * @returns {Promise<{ scrolled: boolean }>}
- */
-export async function browserScroll(options = {}) {
-  const browser = await getBrowser();
-  const direction = options.direction || 'down';
-  const amount = options.amount || 500;
-
-  let expression;
-  switch (direction) {
-    case 'top':
-      expression = 'window.scrollTo(0, 0)';
-      break;
-    case 'bottom':
-      expression = 'window.scrollTo(0, document.body.scrollHeight)';
-      break;
-    case 'up':
-      expression = `window.scrollBy(0, -${amount})`;
-      break;
-    case 'down':
-    default:
-      expression = `window.scrollBy(0, ${amount})`;
-      break;
-  }
-
-  await browser.ws.send('Runtime.evaluate', {
-    expression: `${expression}; ({ scrollY: window.scrollY, scrollHeight: document.body.scrollHeight })`,
-    returnByValue: true,
-  });
-
-  return { error: false, scrolled: true, direction };
-}
-
-/**
- * Check if browser is currently running.
- */
-export function isBrowserRunning() {
-  return _browser !== null && _browser.ws.connected;
-}