@ulpi/browse 0.4.0 → 0.6.0

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@ulpi/browse",
-  "version": "0.4.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,19 +1,19 @@
 ---
 name: browse
-version: 2.0.0
+version: 2.4.0
 description: |
-  Fast web browsing for Claude Code via persistent headless Chromium daemon. Navigate to any URL,
+  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,
   inspect CSS/DOM, capture console/network logs, and more. ~100ms per command after
-  first call. Use when you need to check a website, verify a deployment, read docs,
-  or interact with any web page. No MCP, no Chrome extension — just fast CLI.
+  first call. Works with Claude Code, Cursor, Cline, Windsurf, and any agent that can run Bash.
+  No MCP, no Chrome extension — just fast CLI.
 allowed-tools:
   - Bash
   - Read
 
 ---
 
-# browse: Persistent Browser for Claude Code
+# browse: Persistent Browser for AI Coding Agents
 
 Persistent headless Chromium daemon. First call auto-starts the server (~3s).
 Every subsequent call: ~100-200ms. Auto-shuts down after 30 min idle.
@@ -74,7 +74,7 @@ If the file is missing or does not contain browse permission rules in `permissio
 "Bash(browse newtab:*)", "Bash(browse closetab:*)",
 "Bash(browse frame:*)",
 "Bash(browse sessions:*)", "Bash(browse session-close:*)",
-"Bash(browse state:*)", "Bash(browse auth:*)", "Bash(browse har:*)",
+"Bash(browse state:*)", "Bash(browse auth:*)", "Bash(browse har:*)", "Bash(browse video:*)",
 "Bash(browse route:*)", "Bash(browse offline:*)",
 "Bash(browse status:*)", "Bash(browse stop:*)", "Bash(browse restart:*)",
 "Bash(browse cookie:*)", "Bash(browse header:*)",
@@ -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
@@ -197,6 +199,12 @@ browse har start
 browse goto https://example.com
 browse har stop ./recording.har
 
+# Video recording
+browse video start ./videos
+browse goto https://example.com
+browse click @e3
+browse video stop
+
 # Device emulation
 browse emulate iphone
 browse emulate reset
@@ -220,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
@@ -271,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
@@ -325,7 +338,8 @@ browse clipboard write <text>  Write text to system clipboard
 
 ### Visual
 ```
-browse screenshot [path]              Screenshot (default: .browse/sessions/{id}/screenshot.png)
+browse screenshot [path]              Viewport screenshot (default: .browse/sessions/{id}/screenshot.png)
+browse screenshot --full [path]       Full-page screenshot (entire scrollable page)
 browse screenshot --annotate [path]   Screenshot with numbered badges + legend
 browse pdf [path]                     Save as PDF
 browse responsive [prefix]            Screenshots at mobile/tablet/desktop
@@ -394,6 +408,13 @@ browse har start               Start recording network traffic
 browse har stop [path]         Stop and save HAR file
 ```
 
+### Video recording
+```
+browse video start [dir]       Start recording video (WebM, compositor-level)
+browse video stop              Stop recording and save video files
+browse video status            Check if recording is active
+```
+
 ### Server management
 ```
 browse status                  Server health, uptime, session count
@@ -412,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
 
@@ -436,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"` |
@@ -454,6 +476,7 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 | Save/restore session | `state save mysite` / `state load mysite` |
 | Auto-login | `auth save gh https://github.com/login user pass` → `auth login gh` |
 | Record network | `har start` → browse around → `har stop ./out.har` |
+| Record video | `video start ./vids` → browse around → `video stop` |
 | Parallel agents | `--session agent-a <cmd>` / `--session agent-b <cmd>` |
 | Multi-step flow | `echo '[...]' \| browse chain` |
 | Secure browsing | `--allowed-domains example.com goto https://example.com` |
@@ -464,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
 
@@ -482,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') {
@@ -605,7 +620,7 @@ Inspection:     js <expr> | eval <file> | css <sel> <prop> | attrs <sel>
                 element-state <sel> | console [--clear] | network [--clear]
                 cookies | storage [set <k> <v>] | perf
                 value <sel> | count <sel> | clipboard [write <text>]
-Visual:         screenshot [path] | pdf [path] | responsive [prefix]
+Visual:         screenshot [path] [--full] [--annotate] | pdf [path] | responsive [prefix]
 Snapshot:       snapshot [-i] [-c] [-C] [-d N] [-s sel]
 Find:           find role|text|label|placeholder|testid <query> [name]
 Compare:        diff <url1> <url2> | screenshot-diff <baseline> [current]
@@ -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/meta.ts

@@ -218,7 +218,8 @@ export async function handleMetaCommand(
     case 'screenshot': {
       const page = bm.getPage();
       const annotate = args.includes('--annotate');
-      const filteredArgs = args.filter(a => a !== '--annotate');
+      const isFullPage = args.includes('--full');
+      const filteredArgs = args.filter(a => a !== '--annotate' && a !== '--full');
       const screenshotPath = filteredArgs[0] || (currentSession ? `${currentSession.outputDir}/screenshot.png` : `${LOCAL_DIR}/browse-screenshot.png`);
 
       if (annotate) {
@@ -278,7 +279,7 @@ export async function handleMetaCommand(
             document.body.appendChild(container);
           }, badges);
 
-          await page.screenshot({ path: screenshotPath, fullPage: true });
+          await page.screenshot({ path: screenshotPath, fullPage: isFullPage });
         } finally {
           await page.evaluate(() => {
             document.getElementById('__browse_annotate__')?.remove();
@@ -288,7 +289,7 @@ export async function handleMetaCommand(
         return `Screenshot saved: ${screenshotPath}\n\nLegend:\n${legend.join('\n')}`;
       }
 
-      await page.screenshot({ path: screenshotPath, fullPage: true });
+      await page.screenshot({ path: screenshotPath, fullPage: isFullPage });
       return `Screenshot saved: ${screenshotPath}`;
     }
 
@@ -481,14 +482,16 @@ export async function handleMetaCommand(
 
     // ─── Screenshot Diff ──────────────────────────────
     case 'screenshot-diff': {
-      const baseline = args[0];
-      if (!baseline) throw new Error('Usage: browse screenshot-diff <baseline> [current] [--threshold 0.1]');
+      const isFullPageDiff = args.includes('--full');
+      const diffArgs = args.filter(a => a !== '--full');
+      const baseline = diffArgs[0];
+      if (!baseline) throw new Error('Usage: browse screenshot-diff <baseline> [current] [--threshold 0.1] [--full]');
       if (!fs.existsSync(baseline)) throw new Error(`Baseline file not found: ${baseline}`);
 
       let thresholdPct = 0.1;
-      const threshIdx = args.indexOf('--threshold');
-      if (threshIdx !== -1 && args[threshIdx + 1]) {
-        thresholdPct = parseFloat(args[threshIdx + 1]);
+      const threshIdx = diffArgs.indexOf('--threshold');
+      if (threshIdx !== -1 && diffArgs[threshIdx + 1]) {
+        thresholdPct = parseFloat(diffArgs[threshIdx + 1]);
       }
 
       const baselineBuffer = fs.readFileSync(baseline);
@@ -496,16 +499,16 @@ export async function handleMetaCommand(
       // Find optional current image path: any non-flag arg after baseline
       let currentBuffer: Buffer;
       let currentPath: string | undefined;
-      for (let i = 1; i < args.length; i++) {
-        if (args[i] === '--threshold') { i++; continue; }
-        if (!args[i].startsWith('--')) { currentPath = args[i]; break; }
+      for (let i = 1; i < diffArgs.length; i++) {
+        if (diffArgs[i] === '--threshold') { i++; continue; }
+        if (!diffArgs[i].startsWith('--')) { currentPath = diffArgs[i]; break; }
       }
       if (currentPath) {
         if (!fs.existsSync(currentPath)) throw new Error(`Current screenshot not found: ${currentPath}`);
         currentBuffer = fs.readFileSync(currentPath);
       } else {
         const page = bm.getPage();
-        currentBuffer = await page.screenshot({ fullPage: true }) as Buffer;
+        currentBuffer = await page.screenshot({ fullPage: isFullPageDiff }) as Buffer;
       }
 
       const { compareScreenshots } = await import('../png-compare');

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', () => {