@monostate/node-scraper 2.1.0 → 2.2.0

package/README.md

@@ -79,6 +79,80 @@ await bulkScrapeStream(urls, {
 
 See [BULK_SCRAPING.md](./BULK_SCRAPING.md) for full documentation.
 
+### Browser sessions
+
+Persistent browser sessions with real-time control. Three modes:
+
+```javascript
+import { createSession } from '@monostate/node-scraper';
+
+// Headless (default) — LightPanda with Chrome fallback
+const session = await createSession({ mode: 'auto' });
+await session.goto('https://example.com');
+const content = await session.extractContent();
+const state = await session.getPageState({ includeScreenshot: true });
+await session.close();
+
+// Visual — Chrome with headless:false for dev/debug
+const visual = await createSession({ mode: 'visual' });
+await visual.goto('https://example.com');
+await visual.screenshot(); // real Chrome rendering
+await visual.close();
+```
+
+Session methods: `goto`, `click`, `type`, `scroll`, `hover`, `select`, `pressKey`, `goBack`, `goForward`, `screenshot`, `extractContent`, `getPageState`, `waitFor`, `evaluate`, `getCookies`, `setCookies`.
+
+### Computer use (coordinate-based browser control)
+
+For AI agents that navigate by pixel coordinates -- useful for anti-bot sites, dynamic UIs, or anything that can't be scraped with selectors.
+
+```javascript
+import { createSession, LocalProvider } from '@monostate/node-scraper';
+
+// LocalProvider runs Xvfb + Chrome + xdotool (Linux only)
+const session = await createSession({
+  mode: 'computer-use',
+  provider: new LocalProvider({ screenWidth: 1280, screenHeight: 800, enableVnc: true }),
+});
+
+await session.goto('https://example.com');
+
+// Coordinate-based actions (delegated to provider)
+await session.clickAt(640, 400);
+await session.typeText('hello world');
+await session.mouseMove(100, 200);
+await session.drag(10, 20, 300, 400);
+await session.scrollAt(640, 400, 'down', 5);
+const pos = await session.getCursorPosition();
+const size = await session.getScreenSize();
+
+// Selector-based actions still work (via Puppeteer CDP)
+await session.click('#submit');
+await session.type('#search', 'query');
+
+// VNC streaming URL (if provider supports it)
+console.log(session.getVncUrl());
+
+await session.close();
+```
+
+#### Custom providers
+
+Implement `ComputerUseProvider` to connect any VM/container backend:
+
+```javascript
+import { ComputerUseProvider } from '@monostate/node-scraper';
+
+class MyProvider extends ComputerUseProvider {
+  async start() {
+    // Provision VM, return { cdpUrl, vncUrl, screenSize }
+  }
+  async mouseClick(x, y, button) { /* ... */ }
+  async screenshot() { /* ... */ }
+  async stop() { /* cleanup */ }
+}
+```
+
 ### AI-powered Q&A
 
 Ask questions about any website using OpenRouter, OpenAI, or local fallback:

package/browser-session.js

@@ -12,15 +12,16 @@ const FALLBACK_REASONS = {
 export class BrowserSession {
   /**
    * @param {object} options
-   * @param {'headless'|'visual'|'auto'} options.mode - 'headless' (LightPanda), 'visual' (Chrome), 'auto' (LP with Chrome fallback)
+   * @param {'headless'|'visual'|'auto'|'computer-use'} options.mode - 'headless' (LightPanda), 'visual' (Chrome visible), 'auto' (LP with Chrome fallback), 'computer-use' (provider with Xvfb+VNC)
    * @param {number} options.timeout - Navigation timeout in ms (default: 15000)
    * @param {string} options.userAgent - Custom user agent
    * @param {string} options.lightpandaPath - Path to LightPanda binary
    * @param {boolean} options.verbose - Enable logging
+   * @param {import('./computer-use-provider.js').ComputerUseProvider} options.provider - Required for computer-use mode
    */
   constructor(options = {}) {
     this.mode = options.mode || 'auto';
-    this.activeBackend = null; // 'lightpanda' | 'chrome'
+    this.activeBackend = null; // 'lightpanda' | 'chrome' | 'computer-use'
     this.timeout = options.timeout || 15000;
     this.userAgent = options.userAgent || 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36';
     this.lightpandaPath = options.lightpandaPath;
@@ -33,6 +34,10 @@ export class BrowserSession {
     this._connected = false;
     this._fallbackCount = 0;
 
+    // Computer-use provider (Xvfb + Chrome + xdotool + optional VNC)
+    this.provider = options.provider || null;
+    this._providerInfo = null;
+
     this.history = []; // action log for debugging
   }
 
@@ -41,8 +46,10 @@ export class BrowserSession {
   async connect() {
     if (this._connected) return this;
 
-    if (this.mode === 'visual') {
-      await this._connectChrome();
+    if (this.mode === 'computer-use') {
+      await this._connectViaProvider();
+    } else if (this.mode === 'visual') {
+      await this._connectChromeVisual();
     } else {
       // 'headless' or 'auto' — start with LightPanda
       try {
@@ -86,6 +93,45 @@ export class BrowserSession {
     this._log('Connected to Chrome');
   }
 
+  async _connectChromeVisual() {
+    const puppeteer = await this._getPuppeteer();
+    this.browser = await puppeteer.launch({
+      headless: false,
+      args: [
+        '--no-sandbox',
+        '--disable-setuid-sandbox',
+        '--disable-dev-shm-usage',
+        '--window-size=1280,800',
+      ],
+    });
+    this.page = await this.browser.newPage();
+    await this.page.setUserAgent(this.userAgent);
+    await this.page.setViewport({ width: 1280, height: 800 });
+    this.activeBackend = 'chrome';
+    this._log('Connected to Chrome (visual, headless:false)');
+  }
+
+  async _connectViaProvider() {
+    if (!this.provider) {
+      throw new Error('computer-use mode requires a provider. Pass { provider: new LocalProvider() }');
+    }
+    this._providerInfo = await this.provider.start();
+
+    const puppeteer = await this._getPuppeteer();
+    this.browser = await puppeteer.connect({
+      browserWSEndpoint: this._providerInfo.cdpUrl,
+    });
+
+    const pages = await this.browser.pages();
+    this.page = pages[0] || await this.browser.newPage();
+    await this.page.setViewport({
+      width: this._providerInfo.screenSize.width,
+      height: this._providerInfo.screenSize.height,
+    });
+    this.activeBackend = 'computer-use';
+    this._log('Connected via ComputerUseProvider');
+  }
+
   // ── Navigation ──────────────────────────────────────────────
 
   async goto(url) {
@@ -383,6 +429,15 @@ export class BrowserSession {
       case 'screenshot': return this.screenshot(action);
       case 'extractContent': return this.extractContent();
       case 'waitFor': return this.waitFor(action.selector, action.timeout);
+      // Coordinate-based actions (computer-use mode)
+      case 'mouseMove': return this.mouseMove(action.x, action.y);
+      case 'clickAt': return this.clickAt(action.x, action.y, action.button);
+      case 'doubleClickAt': return this.doubleClickAt(action.x, action.y, action.button);
+      case 'drag': return this.drag(action.startX, action.startY, action.endX, action.endY);
+      case 'scrollAt': return this.scrollAt(action.x, action.y, action.direction, action.amount);
+      case 'typeText': return this.typeText(action.text);
+      case 'getCursorPosition': return this.getCursorPosition();
+      case 'getScreenSize': return this.getScreenSize();
       default: throw new Error(`Unknown action type: ${action.type}`);
     }
   }
@@ -416,6 +471,78 @@ export class BrowserSession {
     }
   }
 
+  // ── Coordinate-based actions (computer-use mode) ────────────
+
+  _ensureProvider() {
+    if (!this.provider || this.activeBackend !== 'computer-use') {
+      throw new Error('Coordinate-based actions require computer-use mode with a provider');
+    }
+  }
+
+  async mouseMove(x, y) {
+    this._ensureConnected();
+    this._ensureProvider();
+    const result = await this.provider.mouseMove(x, y);
+    this._logAction('mouseMove', { x, y });
+    return result;
+  }
+
+  async clickAt(x, y, button = 'left') {
+    this._ensureConnected();
+    this._ensureProvider();
+    const result = await this.provider.mouseClick(x, y, button);
+    this._logAction('clickAt', { x, y, button });
+    return result;
+  }
+
+  async doubleClickAt(x, y, button = 'left') {
+    this._ensureConnected();
+    this._ensureProvider();
+    const result = await this.provider.mouseDoubleClick(x, y, button);
+    this._logAction('doubleClickAt', { x, y, button });
+    return result;
+  }
+
+  async drag(startX, startY, endX, endY) {
+    this._ensureConnected();
+    this._ensureProvider();
+    const result = await this.provider.mouseDrag(startX, startY, endX, endY);
+    this._logAction('drag', { startX, startY, endX, endY });
+    return result;
+  }
+
+  async scrollAt(x, y, direction = 'down', amount = 3) {
+    this._ensureConnected();
+    this._ensureProvider();
+    const result = await this.provider.scroll(x, y, direction, amount);
+    this._logAction('scrollAt', { x, y, direction, amount });
+    return result;
+  }
+
+  async typeText(text) {
+    this._ensureConnected();
+    this._ensureProvider();
+    const result = await this.provider.typeText(text);
+    this._logAction('typeText', { text: text.substring(0, 20) + (text.length > 20 ? '...' : '') });
+    return result;
+  }
+
+  async getCursorPosition() {
+    this._ensureConnected();
+    this._ensureProvider();
+    return this.provider.getCursorPosition();
+  }
+
+  async getScreenSize() {
+    this._ensureConnected();
+    this._ensureProvider();
+    return this.provider.getScreenSize();
+  }
+
+  getVncUrl() {
+    return this._providerInfo?.vncUrl || null;
+  }
+
   // ── Fallback ────────────────────────────────────────────────
 
   async _fallbackToChrome(reason) {
@@ -487,8 +614,15 @@ export class BrowserSession {
       if (this.context) await this.context.close();
     } catch { /* ignore */ }
 
-    if (this.activeBackend === 'lightpanda' && this.browser) {
+    if (this.activeBackend === 'computer-use') {
+      // Provider mode: disconnect from CDP, then stop the provider
+      try { if (this.browser) await this.browser.disconnect(); } catch { /* ignore */ }
+      try { if (this.provider) await this.provider.stop(); } catch { /* ignore */ }
+    } else if (this.activeBackend === 'lightpanda' && this.browser) {
       try { await this.browser.disconnect(); } catch { /* ignore */ }
+    } else if (this.mode === 'visual' && this.browser && !this._chromeBrowser) {
+      // Visual mode: launched directly, not from pool — close the browser process
+      try { await this.browser.close(); } catch { /* ignore */ }
     }
 
     if (this._chromeBrowser) {

package/computer-use-provider.js

@@ -0,0 +1,168 @@
+/**
+ * Abstract base class for computer-use providers.
+ *
+ * A provider manages a display server (e.g. Xvfb), a browser (Chrome),
+ * and optionally a VNC server. It exposes coordinate-based actions
+ * (mouse, keyboard) and screenshots for AI computer-use agents.
+ *
+ * Open-source implementations:
+ *   - LocalProvider: spawns Xvfb + Chrome + xdotool on the local machine
+ *
+ * To build your own provider (Docker, Kubernetes, cloud VMs, etc.),
+ * extend this class and implement all methods.
+ *
+ * @example
+ * import { ComputerUseProvider } from '@monostate/node-scraper';
+ *
+ * class MyCloudProvider extends ComputerUseProvider {
+ *   async start() {
+ *     // spin up a VM, return CDP URL
+ *     return { cdpUrl: 'ws://...', vncUrl: 'https://...', screenSize: { width: 1280, height: 800 } };
+ *   }
+ *   // ... implement all other methods ...
+ * }
+ */
+
+/**
+ * @typedef {Object} ProviderInfo
+ * @property {string} cdpUrl - WebSocket URL for Chrome DevTools Protocol (ws://...)
+ * @property {string|null} vncUrl - noVNC URL for live browser view (null if unavailable)
+ * @property {{width: number, height: number}} screenSize - Virtual display dimensions
+ */
+
+/**
+ * @typedef {Object} CoordinateActionResult
+ * @property {boolean} success
+ * @property {string} [screenshot] - base64 data URL of screenshot after action (optional)
+ * @property {string} [error] - error message if failed
+ */
+
+export class ComputerUseProvider {
+  /**
+   * Start the environment: display server, browser, VNC, etc.
+   * @returns {Promise<ProviderInfo>}
+   */
+  async start() {
+    throw new Error('ComputerUseProvider.start() not implemented');
+  }
+
+  /**
+   * Stop the environment and release all resources.
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    throw new Error('ComputerUseProvider.stop() not implemented');
+  }
+
+  /**
+   * Capture a screenshot of the full virtual display.
+   * @returns {Promise<{screenshot: string}>} base64 data URL (data:image/png;base64,...)
+   */
+  async screenshot() {
+    throw new Error('ComputerUseProvider.screenshot() not implemented');
+  }
+
+  // ── Coordinate-based actions ──────────────────────────────
+
+  /**
+   * Move the mouse cursor to (x, y).
+   * @param {number} x
+   * @param {number} y
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async mouseMove(x, y) {
+    throw new Error('ComputerUseProvider.mouseMove() not implemented');
+  }
+
+  /**
+   * Click at (x, y).
+   * @param {number} x
+   * @param {number} y
+   * @param {'left'|'right'|'middle'} [button='left']
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async mouseClick(x, y, button = 'left') {
+    throw new Error('ComputerUseProvider.mouseClick() not implemented');
+  }
+
+  /**
+   * Double-click at (x, y).
+   * @param {number} x
+   * @param {number} y
+   * @param {'left'|'right'|'middle'} [button='left']
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async mouseDoubleClick(x, y, button = 'left') {
+    throw new Error('ComputerUseProvider.mouseDoubleClick() not implemented');
+  }
+
+  /**
+   * Drag from (startX, startY) to (endX, endY).
+   * @param {number} startX
+   * @param {number} startY
+   * @param {number} endX
+   * @param {number} endY
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async mouseDrag(startX, startY, endX, endY) {
+    throw new Error('ComputerUseProvider.mouseDrag() not implemented');
+  }
+
+  /**
+   * Scroll at (x, y) in a direction.
+   * @param {number} x
+   * @param {number} y
+   * @param {'up'|'down'} direction
+   * @param {number} [amount=3] - number of scroll steps
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async scroll(x, y, direction, amount = 3) {
+    throw new Error('ComputerUseProvider.scroll() not implemented');
+  }
+
+  /**
+   * Press a key or key combination (e.g. 'Return', 'ctrl+c', 'alt+Tab').
+   * @param {string} key - xdotool-compatible key name
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async pressKey(key) {
+    throw new Error('ComputerUseProvider.pressKey() not implemented');
+  }
+
+  /**
+   * Type text character by character.
+   * @param {string} text
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async typeText(text) {
+    throw new Error('ComputerUseProvider.typeText() not implemented');
+  }
+
+  /**
+   * Wait for a duration.
+   * @param {number} ms - milliseconds to wait
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async wait(ms) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+    return { success: true };
+  }
+
+  /**
+   * Get the current cursor position.
+   * @returns {Promise<{x: number, y: number}>}
+   */
+  async getCursorPosition() {
+    throw new Error('ComputerUseProvider.getCursorPosition() not implemented');
+  }
+
+  /**
+   * Get the virtual display dimensions.
+   * @returns {Promise<{width: number, height: number}>}
+   */
+  async getScreenSize() {
+    throw new Error('ComputerUseProvider.getScreenSize() not implemented');
+  }
+}
+
+export default ComputerUseProvider;

package/index.d.ts

@@ -455,14 +455,57 @@ export function bulkScrape(urls: string[], options?: BulkScrapeOptions): Promise
  */
 export function bulkScrapeStream(urls: string[], options: BulkScrapeStreamOptions): Promise<BulkScrapeStreamStats>;
 
+// ── Computer Use Provider ─────────────────────────────────────
+
+export interface ProviderInfo {
+  cdpUrl: string;
+  vncUrl: string | null;
+  screenSize: { width: number; height: number };
+}
+
+export interface CoordinateActionResult {
+  success: boolean;
+  screenshot?: string | null;
+  error?: string | null;
+}
+
+export declare class ComputerUseProvider {
+  start(): Promise<ProviderInfo>;
+  stop(): Promise<void>;
+  screenshot(): Promise<{ screenshot: string }>;
+  mouseMove(x: number, y: number): Promise<CoordinateActionResult>;
+  mouseClick(x: number, y: number, button?: 'left' | 'right' | 'middle'): Promise<CoordinateActionResult>;
+  mouseDoubleClick(x: number, y: number, button?: 'left' | 'right' | 'middle'): Promise<CoordinateActionResult>;
+  mouseDrag(startX: number, startY: number, endX: number, endY: number): Promise<CoordinateActionResult>;
+  scroll(x: number, y: number, direction: 'up' | 'down', amount?: number): Promise<CoordinateActionResult>;
+  pressKey(key: string): Promise<CoordinateActionResult>;
+  typeText(text: string): Promise<CoordinateActionResult>;
+  wait(ms: number): Promise<CoordinateActionResult>;
+  getCursorPosition(): Promise<{ x: number; y: number }>;
+  getScreenSize(): Promise<{ width: number; height: number }>;
+}
+
+export interface LocalProviderOptions {
+  screenWidth?: number;
+  screenHeight?: number;
+  enableVnc?: boolean;
+  chromePath?: string;
+  chromeArgs?: string[];
+}
+
+export declare class LocalProvider extends ComputerUseProvider {
+  constructor(options?: LocalProviderOptions);
+}
+
 // ── Browser Session ───────────────────────────────────────────
 
 export interface BrowserSessionOptions {
-  mode?: 'headless' | 'visual' | 'auto';
+  mode?: 'headless' | 'visual' | 'auto' | 'computer-use';
   timeout?: number;
   userAgent?: string;
   lightpandaPath?: string;
   verbose?: boolean;
+  provider?: ComputerUseProvider;
 }
 
 export interface PageState {
@@ -480,7 +523,7 @@ export interface PageState {
     value?: string;
   }>;
   screenshot?: string;
-  backend: 'lightpanda' | 'chrome';
+  backend: 'lightpanda' | 'chrome' | 'computer-use';
   sessionHistory: Array<{ type: string; timestamp: number; backend: string }>;
 }
 
@@ -492,7 +535,7 @@ export interface ActionResult {
 }
 
 export interface BrowserAction {
-  type: 'goto' | 'click' | 'type' | 'scroll' | 'hover' | 'select' | 'pressKey' | 'goBack' | 'goForward' | 'screenshot' | 'extractContent' | 'waitFor';
+  type: 'goto' | 'click' | 'type' | 'scroll' | 'hover' | 'select' | 'pressKey' | 'goBack' | 'goForward' | 'screenshot' | 'extractContent' | 'waitFor' | 'mouseMove' | 'clickAt' | 'doubleClickAt' | 'drag' | 'scrollAt' | 'typeText' | 'getCursorPosition' | 'getScreenSize';
   url?: string;
   selector?: string;
   text?: string;
@@ -508,13 +551,21 @@ export interface BrowserAction {
   fullPage?: boolean;
   type_?: 'png' | 'jpeg' | 'webp';
   includeScreenshot?: boolean;
+  /** Coordinate-based action fields */
+  x?: number;
+  y?: number;
+  button?: 'left' | 'right' | 'middle';
+  startX?: number;
+  startY?: number;
+  endX?: number;
+  endY?: number;
 }
 
 export declare class BrowserSession {
   constructor(options?: BrowserSessionOptions);
 
-  readonly activeBackend: 'lightpanda' | 'chrome' | null;
-  readonly mode: 'headless' | 'visual' | 'auto';
+  readonly activeBackend: 'lightpanda' | 'chrome' | 'computer-use' | null;
+  readonly mode: 'headless' | 'visual' | 'auto' | 'computer-use';
 
   connect(): Promise<BrowserSession>;
   goto(url: string): Promise<ActionResult>;
@@ -535,8 +586,19 @@ export declare class BrowserSession {
   getCookies(): Promise<any[]>;
   setCookies(cookies: any[]): Promise<void>;
   getHistory(): Array<{ type: string; timestamp: number; backend: string }>;
-  getBackend(): 'lightpanda' | 'chrome' | null;
+  getBackend(): 'lightpanda' | 'chrome' | 'computer-use' | null;
   close(): Promise<void>;
+
+  /** Coordinate-based actions (computer-use mode only) */
+  mouseMove(x: number, y: number): Promise<CoordinateActionResult>;
+  clickAt(x: number, y: number, button?: 'left' | 'right' | 'middle'): Promise<CoordinateActionResult>;
+  doubleClickAt(x: number, y: number, button?: 'left' | 'right' | 'middle'): Promise<CoordinateActionResult>;
+  drag(startX: number, startY: number, endX: number, endY: number): Promise<CoordinateActionResult>;
+  scrollAt(x: number, y: number, direction: 'up' | 'down', amount?: number): Promise<CoordinateActionResult>;
+  typeText(text: string): Promise<CoordinateActionResult>;
+  getCursorPosition(): Promise<{ x: number; y: number }>;
+  getScreenSize(): Promise<{ width: number; height: number }>;
+  getVncUrl(): string | null;
 }
 
 export function createSession(options?: BrowserSessionOptions): Promise<BrowserSession>;

package/index.js

@@ -1798,5 +1798,7 @@ export async function bulkScrapeStream(urls, options = {}) {
 // Browser session exports
 export { BrowserSession, createSession } from './browser-session.js';
 export { default as LightPandaServer, getLightPandaServer, stopLightPandaServer } from './lightpanda-server.js';
+export { ComputerUseProvider } from './computer-use-provider.js';
+export { LocalProvider } from './providers/local-provider.js';
 
 export default BNCASmartScraper;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monostate/node-scraper",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Intelligent web scraping with AI Q&A, PDF support and multi-level fallback system - 11x faster than traditional scrapers",
   "type": "module",
   "main": "index.js",
@@ -17,6 +17,8 @@
     "browser-pool.js",
     "browser-session.js",
     "lightpanda-server.js",
+    "computer-use-provider.js",
+    "providers/",
     "README.md",
     "BULK_SCRAPING.md",
     "package.json",

package/providers/local-provider.js

@@ -0,0 +1,322 @@
+/**
+ * LocalProvider — runs Xvfb + Chrome + xdotool on the local machine.
+ *
+ * Requires Linux with: xvfb, xdotool, chromium/google-chrome
+ * Optional: x11vnc, noVNC (for VNC streaming)
+ *
+ * @example
+ * import { createSession, LocalProvider } from '@monostate/node-scraper';
+ *
+ * const session = await createSession({
+ *   mode: 'computer-use',
+ *   provider: new LocalProvider({ screenWidth: 1280, screenHeight: 800 }),
+ * });
+ * await session.goto('https://example.com');
+ * await session.clickAt(640, 400);
+ * await session.close();
+ */
+
+import { ComputerUseProvider } from '../computer-use-provider.js';
+import { spawn, execFile } from 'child_process';
+import { createServer } from 'net';
+
+function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.listen(0, '127.0.0.1', () => {
+      const port = srv.address().port;
+      srv.close(() => resolve(port));
+    });
+    srv.on('error', reject);
+  });
+}
+
+function waitForProcess(proc, readyCheck, timeoutMs = 10000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('Process startup timed out')), timeoutMs);
+    const check = setInterval(async () => {
+      try {
+        if (await readyCheck()) {
+          clearTimeout(timer);
+          clearInterval(check);
+          resolve();
+        }
+      } catch { /* still starting */ }
+    }, 200);
+    proc.on('error', (err) => {
+      clearTimeout(timer);
+      clearInterval(check);
+      reject(err);
+    });
+    proc.on('exit', (code) => {
+      if (code !== 0 && code !== null) {
+        clearTimeout(timer);
+        clearInterval(check);
+        reject(new Error(`Process exited with code ${code}`));
+      }
+    });
+  });
+}
+
+function execAsync(cmd, args, env) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { env, timeout: 10000 }, (err, stdout, stderr) => {
+      if (err) reject(err);
+      else resolve({ stdout: stdout.trim(), stderr: stderr.trim() });
+    });
+  });
+}
+
+export class LocalProvider extends ComputerUseProvider {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.screenWidth=1280]
+   * @param {number} [options.screenHeight=800]
+   * @param {boolean} [options.enableVnc=false]
+   * @param {string} [options.chromePath] - Path to Chrome/Chromium binary (auto-detected)
+   * @param {string[]} [options.chromeArgs] - Additional Chrome launch args
+   */
+  constructor(options = {}) {
+    super();
+    this.screenWidth = options.screenWidth || 1280;
+    this.screenHeight = options.screenHeight || 800;
+    this.enableVnc = options.enableVnc ?? false;
+    this.chromePath = options.chromePath || null;
+    this.chromeArgs = options.chromeArgs || [];
+
+    this._display = null;
+    this._displayNum = null;
+    this._cdpPort = null;
+    this._vncPort = null;
+    this._xvfbProc = null;
+    this._chromeProc = null;
+    this._vncProc = null;
+    this._env = null;
+    this._cdpWsUrl = null;
+  }
+
+  async start() {
+    if (process.platform !== 'linux') {
+      throw new Error(
+        'LocalProvider requires Linux (Xvfb + xdotool). ' +
+        'On macOS/Windows, use Docker or a remote provider.'
+      );
+    }
+
+    // Find free ports
+    this._cdpPort = await findFreePort();
+    this._displayNum = 10 + Math.floor(Math.random() * 90); // :10-:99
+    this._display = `:${this._displayNum}`;
+
+    this._env = {
+      ...process.env,
+      DISPLAY: this._display,
+      DBUS_SESSION_BUS_ADDRESS: '/dev/null',
+    };
+
+    // 1. Start Xvfb
+    this._xvfbProc = spawn('Xvfb', [
+      this._display,
+      '-screen', '0', `${this.screenWidth}x${this.screenHeight}x24`,
+      '-ac',
+    ], { stdio: 'pipe', env: this._env });
+
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    // 2. Find Chrome binary
+    const chromePath = this.chromePath || await this._findChrome();
+
+    // 3. Start Chrome
+    const chromeArgs = [
+      '--no-sandbox',
+      '--disable-setuid-sandbox',
+      '--disable-dev-shm-usage',
+      '--disable-gpu',
+      `--remote-debugging-port=${this._cdpPort}`,
+      '--remote-debugging-address=127.0.0.1',
+      `--window-size=${this.screenWidth},${this.screenHeight}`,
+      '--disable-features=dbus',
+      '--disable-sync',
+      '--disable-extensions',
+      '--disable-component-update',
+      '--no-first-run',
+      '--user-data-dir=/tmp/chrome-local-provider-' + this._displayNum,
+      ...this.chromeArgs,
+      'about:blank',
+    ];
+
+    this._chromeProc = spawn(chromePath, chromeArgs, {
+      stdio: 'pipe',
+      env: this._env,
+    });
+
+    // Wait for CDP to be ready
+    await waitForProcess(this._chromeProc, async () => {
+      const res = await fetch(`http://127.0.0.1:${this._cdpPort}/json/version`);
+      return res.ok;
+    }, 15000);
+
+    // Get the CDP WebSocket URL
+    const versionRes = await fetch(`http://127.0.0.1:${this._cdpPort}/json/version`);
+    const versionData = await versionRes.json();
+    this._cdpWsUrl = versionData.webSocketDebuggerUrl;
+
+    // 4. Optionally start VNC
+    let vncUrl = null;
+    if (this.enableVnc) {
+      try {
+        this._vncPort = await findFreePort();
+        this._vncProc = spawn('x11vnc', [
+          '-display', this._display,
+          '-rfbport', String(this._vncPort),
+          '-shared', '-nopw', '-forever',
+        ], { stdio: 'pipe', env: this._env });
+        await new Promise(resolve => setTimeout(resolve, 500));
+        vncUrl = `vnc://127.0.0.1:${this._vncPort}`;
+      } catch {
+        // VNC is optional — don't fail if x11vnc is not installed
+      }
+    }
+
+    return {
+      cdpUrl: this._cdpWsUrl,
+      vncUrl,
+      screenSize: { width: this.screenWidth, height: this.screenHeight },
+    };
+  }
+
+  async stop() {
+    for (const proc of [this._vncProc, this._chromeProc, this._xvfbProc]) {
+      if (proc && !proc.killed) {
+        try { proc.kill('SIGTERM'); } catch { /* ignore */ }
+      }
+    }
+    this._vncProc = null;
+    this._chromeProc = null;
+    this._xvfbProc = null;
+  }
+
+  async screenshot() {
+    // Use CDP Page.captureScreenshot
+    const pagesRes = await fetch(`http://127.0.0.1:${this._cdpPort}/json`);
+    const pages = await pagesRes.json();
+    const page = pages[0];
+    if (!page) throw new Error('No open pages for screenshot');
+
+    const wsUrl = page.webSocketDebuggerUrl;
+    const { default: WebSocket } = await import('ws');
+
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(wsUrl);
+      ws.on('open', () => {
+        ws.send(JSON.stringify({ id: 1, method: 'Page.captureScreenshot', params: { format: 'png' } }));
+      });
+      ws.on('message', (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.id === 1) {
+          ws.close();
+          if (msg.error) {
+            reject(new Error(msg.error.message));
+          } else {
+            resolve({ screenshot: `data:image/png;base64,${msg.result.data}` });
+          }
+        }
+      });
+      ws.on('error', reject);
+      setTimeout(() => { ws.close(); reject(new Error('Screenshot timed out')); }, 10000);
+    });
+  }
+
+  // ── Coordinate-based actions via xdotool ──────────────────
+
+  async mouseMove(x, y) {
+    await this._xdotool(['mousemove', '--', String(Math.round(x)), String(Math.round(y))]);
+    return { success: true };
+  }
+
+  async mouseClick(x, y, button = 'left') {
+    const btn = { left: '1', right: '3', middle: '2' }[button] || '1';
+    await this._xdotool(['mousemove', '--', String(Math.round(x)), String(Math.round(y))]);
+    await this._xdotool(['click', btn]);
+    return { success: true };
+  }
+
+  async mouseDoubleClick(x, y, button = 'left') {
+    const btn = { left: '1', right: '3', middle: '2' }[button] || '1';
+    await this._xdotool(['mousemove', '--', String(Math.round(x)), String(Math.round(y))]);
+    await this._xdotool(['click', '--repeat', '2', '--delay', '50', btn]);
+    return { success: true };
+  }
+
+  async mouseDrag(startX, startY, endX, endY) {
+    await this._xdotool([
+      'mousemove', '--', String(Math.round(startX)), String(Math.round(startY)),
+    ]);
+    await this._xdotool(['mousedown', '1']);
+    await this._xdotool([
+      'mousemove', '--', String(Math.round(endX)), String(Math.round(endY)),
+    ]);
+    await this._xdotool(['mouseup', '1']);
+    return { success: true };
+  }
+
+  async scroll(x, y, direction, amount = 3) {
+    await this._xdotool(['mousemove', '--', String(Math.round(x)), String(Math.round(y))]);
+    const btn = direction === 'up' ? '4' : '5';
+    await this._xdotool(['click', '--repeat', String(amount), '--delay', '50', btn]);
+    return { success: true };
+  }
+
+  async pressKey(key) {
+    await this._xdotool(['key', key]);
+    return { success: true };
+  }
+
+  async typeText(text) {
+    // Type in chunks to avoid buffer issues
+    const CHUNK = 50;
+    for (let i = 0; i < text.length; i += CHUNK) {
+      const chunk = text.substring(i, i + CHUNK);
+      await this._xdotool(['type', '--delay', '12', '--clearmodifiers', chunk]);
+    }
+    return { success: true };
+  }
+
+  async getCursorPosition() {
+    const { stdout } = await this._xdotool(['getmouselocation', '--shell']);
+    const x = parseInt(stdout.match(/X=(\d+)/)?.[1] || '0', 10);
+    const y = parseInt(stdout.match(/Y=(\d+)/)?.[1] || '0', 10);
+    return { x, y };
+  }
+
+  async getScreenSize() {
+    return { width: this.screenWidth, height: this.screenHeight };
+  }
+
+  // ── Internal helpers ──────────────────────────────────────
+
+  async _xdotool(args) {
+    return execAsync('xdotool', args, this._env);
+  }
+
+  async _findChrome() {
+    const candidates = [
+      'chromium-browser',
+      'chromium',
+      'google-chrome',
+      'google-chrome-stable',
+    ];
+    for (const name of candidates) {
+      try {
+        const { stdout } = await execAsync('which', [name], this._env);
+        if (stdout) return stdout;
+      } catch { /* not found */ }
+    }
+    throw new Error(
+      'Chrome/Chromium not found. Install with: apt-get install chromium ' +
+      'or pass chromePath option.'
+    );
+  }
+}
+
+export default LocalProvider;