@ulpi/browse 0.5.0 → 0.6.0

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@ulpi/browse",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/ulpi-io/browse"
   },
   "dependencies": {
+    "@lightpanda/browser": "^1.2.0",
     "@ulpi/browse": "^0.3.0",
     "diff": "^7.0.0",
-    "playwright": "^1.58.2"
+    "playwright": "^1.58.2",
+    "playwright-core": "^1.58.2"
   },
   "bin": {
     "browse": "bin/browse.ts"
@@ -52,5 +54,8 @@
   "devDependencies": {
     "@types/node": "^25.5.0",
     "typescript": "^5.9.3"
+  },
+  "optionalDependencies": {
+    "rebrowser-playwright": "^1.52.0"
   }
 }

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browse
-version: 2.3.0
+version: 2.4.0
 description: |
   Fast web browsing for AI coding agents via persistent headless Chromium daemon. Navigate to any URL,
   read page content, click elements, fill forms, run JavaScript, take screenshots,
@@ -89,6 +89,8 @@ If the file is missing or does not contain browse permission rules in `permissio
 - Always call `browse` as a bare command (it's on PATH via global install).
 - Do NOT use shell variables like `B=...` or full paths — they break Claude Code's permission matching.
 - NEVER use `#` in CSS selectors — use `[id=foo]` instead of `#foo`. The `#` character breaks Claude Code's permission matching and triggers approval prompts.
+- After `goto`, always run `browse wait --network-idle` before reading content or taking screenshots. Pages with dynamic content, SPAs, and lazy-loaded assets need time to fully render.
+- Screenshots MUST be saved to `.browse/sessions/default/` (or `.browse/sessions/<session-id>/` when using `--session`). Use descriptive filenames like `browse screenshot .browse/sessions/default/homepage.png`. NEVER save screenshots to `/tmp` or any other location.
 - The browser persists between calls — cookies, tabs, and state carry over.
 - The server auto-starts on first command. No manual setup needed.
 - Use `--session <id>` for parallel agent isolation. Each session gets its own tabs, refs, cookies.
@@ -105,8 +107,8 @@ browse goto https://example.com
 # Read cleaned page text
 browse text
 
-# Take a screenshot (then Read the image)
-browse screenshot .browse/sessions/default/screenshot.png
+# Take a screenshot (then Read the image — saved to .browse/sessions/default/screenshot.png)
+browse screenshot
 
 # Snapshot: accessibility tree with refs
 browse snapshot -i
@@ -226,6 +228,10 @@ browse screenshot-diff baseline.png current.png
 # Headed mode (visible browser)
 browse --headed goto https://example.com
 
+# Stealth mode (bypasses bot detection)
+# Requires: bun add rebrowser-playwright && npx rebrowser-playwright install chromium
+browse --runtime rebrowser goto https://example.com
+
 # State list / show
 browse state list
 browse state show mysite
@@ -277,6 +283,7 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 ### Interaction
 ```
 browse click <selector>        Click element (CSS selector or @ref)
+browse click <x>,<y>           Click at page coordinates (e.g. 590,461)
 browse dblclick <selector>     Double-click element
 browse fill <selector> <value> Fill input field
 browse select <selector> <val> Select dropdown value
@@ -426,6 +433,7 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 | `--content-boundaries` | Wrap page content in nonce-delimited markers (prompt injection defense) |
 | `--allowed-domains <d,d>` | Block navigation/resources outside allowlist |
 | `--headed` | Run browser in headed (visible) mode |
+| `--runtime <name>` | Browser engine: playwright (default), rebrowser (stealth) |
 
 ## Speed Rules
 
@@ -450,7 +458,7 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 | Check if element exists | `count ".thing"` |
 | Get input value | `value "[id=email]"` |
 | Extract specific data | `js "document.querySelector('.price').textContent"` |
-| Visual check | `screenshot .browse/sessions/default/x.png` then Read the image |
+| Visual check | `screenshot` then `Read .browse/sessions/default/screenshot.png` |
 | Fill and submit form | `snapshot -i` → `fill @e4 "val"` → `click @e5` |
 | Check/uncheck boxes | `check @e7` / `uncheck @e7` |
 | Check CSS | `css "selector" "property"` or `css @e3 "property"` |
@@ -479,6 +487,7 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 | Visual regression | `screenshot-diff baseline.png` |
 | Debug with DevTools | `inspect` (set BROWSE_DEBUG_PORT first) |
 | See the browser | `browse --headed goto <url>` |
+| Bypass bot detection | `--runtime rebrowser goto <url>` |
 
 ## Architecture
 
@@ -497,3 +506,4 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 - AI-friendly error messages: Playwright errors rewritten to actionable hints
 - CDP remote connection: `BROWSE_CDP_URL` to connect to existing Chrome
 - Policy enforcement: `browse-policy.json` for allow/deny/confirm rules
+- Two browser engines: playwright (default) and rebrowser (stealth, bypasses bot detection)

package/src/browser-manager.ts

@@ -7,7 +7,8 @@
  *   We do NOT try to self-heal — don't hide failure.
  */
 
-import { chromium, devices as playwrightDevices, type Browser, type BrowserContext, type Page, type Locator, type Frame, type FrameLocator, type Request as PlaywrightRequest } from 'playwright';
+import { devices as playwrightDevices, type Browser, type BrowserContext, type Page, type Locator, type Frame, type FrameLocator, type Request as PlaywrightRequest } from 'playwright';
+import { getRuntime } from './runtime';
 import { SessionBuffers, type LogEntry, type NetworkEntry } from './buffers';
 import type { HarRecording } from './har';
 import type { DomainFilter } from './domain-filter';
@@ -202,8 +203,9 @@ export class BrowserManager {
    * Launch a new Chromium browser (single-session / multi-process mode).
    * This instance owns the browser and will close it on close().
    */
-  async launch(onCrash?: () => void) {
-    this.browser = await chromium.launch({ headless: true });
+  async launch(onCrash?: () => void, runtimeName?: string) {
+    const runtime = await getRuntime(runtimeName);
+    this.browser = await runtime.chromium.launch({ headless: true });
     this.ownsBrowser = true;
 
     // Chromium crash → notify caller (server uses this to exit; tests ignore it)

package/src/bun.d.ts

@@ -14,9 +14,23 @@ declare module 'bun' {
 
   export function spawn(cmd: string[], options?: {
     stdio?: Array<'ignore' | 'pipe' | 'inherit'>;
+    stdout?: 'pipe' | 'ignore' | 'inherit';
+    stderr?: 'pipe' | 'ignore' | 'inherit';
+    stdin?: 'pipe' | 'ignore' | 'inherit';
     env?: Record<string, string | undefined>;
   }): BunSubprocess;
 
+  export function listen(options: {
+    hostname: string;
+    port: number;
+    socket: {
+      data: (...args: any[]) => void;
+      open?: (...args: any[]) => void;
+      close?: (...args: any[]) => void;
+      error?: (...args: any[]) => void;
+    };
+  }): BunTCPServer;
+
   export function sleep(ms: number): Promise<void>;
 
   export const stdin: { text(): Promise<string> };
@@ -26,10 +40,18 @@ declare module 'bun' {
     stop(): void;
   }
 
+  interface BunTCPServer {
+    port: number;
+    stop(): void;
+  }
+
   interface BunSubprocess {
     pid: number;
+    exitCode: number | null;
     stderr: ReadableStream<Uint8Array> | null;
     stdout: ReadableStream<Uint8Array> | null;
+    exited: Promise<number>;
+    kill(signal?: number): void;
     unref(): void;
   }
 }
@@ -37,6 +59,7 @@ declare module 'bun' {
 declare var Bun: {
   serve: typeof import('bun').serve;
   spawn: typeof import('bun').spawn;
+  listen: typeof import('bun').listen;
   sleep: typeof import('bun').sleep;
   stdin: typeof import('bun').stdin;
 };

package/src/cli.ts

@@ -20,6 +20,7 @@ const cliFlags = {
   contentBoundaries: false,
   allowedDomains: '' as string,
   headed: false,
+  runtime: '' as string,
 };
 
 const BROWSE_PORT = parseInt(process.env.BROWSE_PORT || '0', 10);
@@ -252,7 +253,7 @@ async function startServer(): Promise<ServerState> {
       : ['bun', 'run', SERVER_SCRIPT];
     const proc = Bun.spawn(spawnCmd, {
       stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env, __BROWSE_SERVER_MODE: '1', BROWSE_LOCAL_DIR: LOCAL_DIR, BROWSE_INSTANCE, ...(cliFlags.headed ? { BROWSE_HEADED: '1' } : {}) },
+      env: { ...process.env, __BROWSE_SERVER_MODE: '1', BROWSE_LOCAL_DIR: LOCAL_DIR, BROWSE_INSTANCE, ...(cliFlags.headed ? { BROWSE_HEADED: '1' } : {}), ...(cliFlags.runtime ? { BROWSE_RUNTIME: cliFlags.runtime } : {}) },
     });
 
     // Don't hold the CLI open
@@ -511,7 +512,7 @@ export async function main() {
     for (let i = 0; i < a.length; i++) {
       if (!a[i].startsWith('-')) return i;
       // Skip flag values for known value-flags
-      if (a[i] === '--session' || a[i] === '--allowed-domains') i++;
+      if (a[i] === '--session' || a[i] === '--allowed-domains' || a[i] === '--runtime') i++;
     }
     return a.length;
   }
@@ -569,11 +570,25 @@ export async function main() {
   }
   headed = headed || process.env.BROWSE_HEADED === '1';
 
+  // Extract --runtime flag (only before command)
+  let runtimeName: string | undefined;
+  const runtimeIdx = args.indexOf('--runtime');
+  if (runtimeIdx !== -1 && runtimeIdx < findCommandIndex(args)) {
+    runtimeName = args[runtimeIdx + 1];
+    if (!runtimeName || runtimeName.startsWith('-')) {
+      console.error('Usage: browse --runtime <name> <command> [args...]');
+      process.exit(1);
+    }
+    args.splice(runtimeIdx, 2);
+  }
+  runtimeName = runtimeName || process.env.BROWSE_RUNTIME || config.runtime || undefined;
+
   // Set global flags for sendCommand()
   cliFlags.json = jsonMode;
   cliFlags.contentBoundaries = contentBoundaries;
   cliFlags.allowedDomains = allowedDomains || '';
   cliFlags.headed = headed;
+  cliFlags.runtime = runtimeName || '';
 
   // ─── Local commands (no server needed) ─────────────────────
   if (args[0] === 'instances') {
@@ -630,6 +645,7 @@ Options:
   --content-boundaries     Wrap page content in nonce-delimited markers
   --allowed-domains <d,d>  Block navigation/resources outside allowlist
   --headed                 Run browser in headed (visible) mode
+  --runtime <name>         Browser runtime (playwright, rebrowser, lightpanda)
 
 Snapshot flags:
   -i            Interactive elements only (buttons, links, inputs)

package/src/commands/write.ts

@@ -73,7 +73,16 @@ export async function handleWriteCommand(
 
     case 'click': {
       const selector = args[0];
-      if (!selector) throw new Error('Usage: browse click <selector>');
+      if (!selector) throw new Error('Usage: browse click <selector|x,y>');
+      // Coordinate click: "590,461" or "590, 461"
+      const coordMatch = selector.match(/^(\d+)\s*,\s*(\d+)$/);
+      if (coordMatch) {
+        const x = parseInt(coordMatch[1], 10);
+        const y = parseInt(coordMatch[2], 10);
+        await page.mouse.click(x, y);
+        await page.waitForLoadState('domcontentloaded').catch(() => {});
+        return `Clicked at (${x}, ${y}) → now at ${page.url()}`;
+      }
       const resolved = bm.resolveRef(selector);
       if ('locator' in resolved) {
         await resolved.locator.click({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });

package/src/config.ts

@@ -14,6 +14,7 @@ export interface BrowseConfig {
   idleTimeout?: number;
   viewport?: string;
   device?: string;
+  runtime?: string;
 }
 
 /**

package/src/rebrowser.d.ts

@@ -0,0 +1,7 @@
+/**
+ * rebrowser-playwright is a drop-in fork of playwright with stealth patches.
+ * Re-export playwright's types so tsc passes without the package installed.
+ */
+declare module 'rebrowser-playwright' {
+  export * from 'playwright';
+}

package/src/runtime.ts

@@ -0,0 +1,161 @@
+/**
+ * Browser runtime provider registry
+ *
+ * Abstracts the browser engine so playwright, rebrowser, etc. are swappable at runtime.
+ * Each runtime is loaded lazily via dynamic import -- only the selected runtime is loaded.
+ *
+ * Two kinds of runtime:
+ *   Library runtimes (playwright, rebrowser) -- return a BrowserType for launch()/connectOverCDP()
+ *   Process runtimes (lightpanda) -- spawn a binary, wait for CDP, connect Playwright to it
+ *     These set `browser` (pre-connected) and `close` (cleanup spawned process).
+ */
+
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+import { execSync } from 'child_process';
+import { join } from 'path';
+import type { Browser, BrowserType } from 'playwright';
+
+export interface BrowserRuntime {
+  name: string;
+  chromium: BrowserType;
+  /** Pre-connected browser (for process runtimes like lightpanda). */
+  browser?: Browser;
+  /** Cleanup function -- kills spawned process, if any. */
+  close?: () => Promise<void>;
+}
+
+type RuntimeLoader = () => Promise<BrowserRuntime>;
+
+/**
+ * Find the lightpanda binary on this machine.
+ * Checks PATH via `which`, then well-known install locations.
+ * Returns the absolute path or null if not found.
+ */
+export function findLightpanda(): string | null {
+  // Check PATH
+  try {
+    const result = execSync('which lightpanda', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    if (result) return result;
+  } catch {
+    // not on PATH
+  }
+
+  // Check well-known install locations
+  const home = homedir();
+  const candidates = [
+    join(home, '.lightpanda', 'lightpanda'),
+    join(home, '.local', 'bin', 'lightpanda'),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+const registry: Record<string, RuntimeLoader> = {
+  playwright: async () => {
+    const pw = await import('playwright');
+    return { name: 'playwright', chromium: pw.chromium };
+  },
+
+  rebrowser: async () => {
+    try {
+      const pw = await import('rebrowser-playwright');
+      return { name: 'rebrowser', chromium: pw.chromium };
+    } catch {
+      throw new Error(
+        'rebrowser-playwright not installed. Run: bun add rebrowser-playwright'
+      );
+    }
+  },
+
+  lightpanda: async () => {
+    const binaryPath = findLightpanda();
+    if (!binaryPath) {
+      throw new Error(
+        'Lightpanda not found. Install: https://lightpanda.io/docs/open-source/installation'
+      );
+    }
+
+    // Find a free port
+    const server = Bun.listen({
+      hostname: '127.0.0.1',
+      port: 0,
+      socket: {
+        data() {},
+        open() {},
+        close() {},
+        error() {},
+      },
+    });
+    const port = server.port;
+    server.stop();
+
+    // Spawn lightpanda with 1-week session timeout (documented maximum)
+    const child = Bun.spawn(
+      [binaryPath, 'serve', '--host', '127.0.0.1', '--port', String(port), '--timeout', '604800'],
+      { stdout: 'pipe', stderr: 'pipe' }
+    );
+
+    // Poll for CDP ready (10s timeout, 100ms interval)
+    const deadline = Date.now() + 10_000;
+    let wsUrl: string | undefined;
+
+    while (Date.now() < deadline) {
+      // Check if process exited early
+      if (child.exitCode !== null) {
+        const stderr = await new Response(child.stderr).text().catch(() => '');
+        throw new Error(
+          `Lightpanda exited before CDP became ready (exit code: ${child.exitCode})` +
+          (stderr ? `\nstderr: ${stderr.slice(0, 2000)}` : '')
+        );
+      }
+
+      try {
+        const res = await fetch(`http://127.0.0.1:${port}/json/version`);
+        if (res.ok) {
+          const data = await res.json() as { webSocketDebuggerUrl?: string };
+          wsUrl = data.webSocketDebuggerUrl;
+          break;
+        }
+      } catch {
+        // Not ready yet
+      }
+      await new Promise(r => setTimeout(r, 100));
+    }
+
+    if (!wsUrl) {
+      child.kill();
+      throw new Error(
+        `Lightpanda failed to start on port ${port} within 10 seconds`
+      );
+    }
+
+    // Bun's WebSocket client sends "Connection: keep-alive" instead of
+    // "Connection: Upgrade", breaking the WebSocket handshake with Lightpanda.
+    // Playwright's connectOverCDP relies on the bundled ws package which Bun
+    // intercepts. This is a known Bun issue (oven-sh/bun#9911).
+    // Until Bun fixes WebSocket upgrades, lightpanda cannot be used.
+    child.kill();
+    throw new Error(
+      'Lightpanda runtime is not yet supported under Bun.\n' +
+      'Bun\'s WebSocket client breaks the HTTP upgrade handshake required by connectOverCDP (oven-sh/bun#9911).\n' +
+      'This affects all CDP-based connections. Use --runtime playwright or --runtime rebrowser instead.'
+    );
+  },
+};
+
+export const AVAILABLE_RUNTIMES: string[] = Object.keys(registry);
+
+export async function getRuntime(name?: string): Promise<BrowserRuntime> {
+  const key = name ?? 'playwright';
+  const loader = registry[key];
+  if (!loader) {
+    throw new Error(
+      `Unknown runtime: ${key}. Available: ${AVAILABLE_RUNTIMES.join(', ')}`
+    );
+  }
+  return loader();
+}

package/src/server.ts

@@ -9,7 +9,8 @@
  *   Auto-shutdown when all sessions idle past BROWSE_IDLE_TIMEOUT (default 30 min)
  */
 
-import { chromium, type Browser } from 'playwright';
+import type { Browser } from 'playwright';
+import { getRuntime, type BrowserRuntime } from './runtime';
 import { SessionManager, type Session } from './session-manager';
 import { handleReadCommand } from './commands/read';
 import { handleWriteCommand } from './commands/write';
@@ -99,6 +100,7 @@ function flushSessionBuffers(session: Session, final: boolean) {
 // ─── Server ────────────────────────────────────────────────────
 let sessionManager: SessionManager;
 let browser: Browser;
+let activeRuntime: BrowserRuntime | undefined;
 let isShuttingDown = false;
 let isRemoteBrowser = false;
 const policyChecker = new PolicyChecker();
@@ -326,6 +328,9 @@ async function shutdown() {
     await browser.close().catch(() => {});
   }
 
+  // Clean up runtime resources (e.g. lightpanda child process)
+  await activeRuntime?.close?.().catch(() => {});
+
   // Only remove state file if it still belongs to this server instance.
   try {
     const currentState = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
@@ -365,13 +370,27 @@ const sessionCleanupInterval = setInterval(async () => {
 async function start() {
   const port = await findPort();
 
+  // Resolve browser runtime (playwright, rebrowser, etc.)
+  const runtimeName = process.env.BROWSE_RUNTIME;
+  const runtime = await getRuntime(runtimeName);
+  activeRuntime = runtime;
+  console.log(`[browse] Runtime: ${runtime.name}`);
+
   // Launch or connect to browser
   const cdpUrl = process.env.BROWSE_CDP_URL;
   if (cdpUrl) {
     // Connect to remote Chrome via CDP
-    browser = await chromium.connectOverCDP(cdpUrl);
+    browser = await runtime.chromium.connectOverCDP(cdpUrl);
     isRemoteBrowser = true;
     console.log(`[browse] Connected to remote Chrome via CDP: ${cdpUrl}`);
+  } else if (runtime.browser) {
+    // Process runtime (e.g. lightpanda) -- browser already connected
+    browser = runtime.browser;
+    browser.on('disconnected', () => {
+      if (isShuttingDown) return;
+      console.error('[browse] Browser disconnected. Shutting down.');
+      shutdown();
+    });
   } else {
     // Launch local Chromium
     const launchOptions: Record<string, any> = { headless: process.env.BROWSE_HEADED !== '1' };
@@ -385,7 +404,7 @@ async function start() {
         launchOptions.proxy.bypass = process.env.BROWSE_PROXY_BYPASS;
       }
     }
-    browser = await chromium.launch(launchOptions);
+    browser = await runtime.chromium.launch(launchOptions);
 
     // Chromium crash → clean shutdown (only for owned browser)
     browser.on('disconnected', () => {