lightpanda (#646)

* lightpanda

* lightpanda benchmarks

* improvements

* fixes

* improvements

docs/src/app/configuration/page.mdx

@@ -80,6 +80,7 @@ Every CLI flag can be set in the config file using its camelCase equivalent:
     <tr><td><code>actionPolicy</code></td><td><code>--action-policy</code></td><td>string</td></tr>
     <tr><td><code>confirmActions</code></td><td><code>--confirm-actions</code></td><td>string</td></tr>
     <tr><td><code>confirmInteractive</code></td><td><code>--confirm-interactive</code></td><td>boolean</td></tr>
+    <tr><td><code>engine</code></td><td><code>--engine</code></td><td>string (<code>chrome</code>, <code>lightpanda</code>)</td></tr>
     <tr><td><code>native</code></td><td><code>--native</code></td><td>boolean (experimental)</td></tr>
     <tr><td><code>headers</code></td><td><code>--headers</code></td><td>string (JSON)</td></tr>
   </tbody>
@@ -187,6 +188,7 @@ These environment variables configure additional daemon and runtime behavior:
     <tr><td><code>AGENT_BROWSER_ACTION_POLICY</code></td><td>Path to action policy JSON file.</td><td>(none)</td></tr>
     <tr><td><code>AGENT_BROWSER_CONFIRM_ACTIONS</code></td><td>Comma-separated action categories requiring confirmation.</td><td>(none)</td></tr>
     <tr><td><code>AGENT_BROWSER_CONFIRM_INTERACTIVE</code></td><td>Enable interactive confirmation prompts (auto-denies if stdin is not a TTY).</td><td>(disabled)</td></tr>
+    <tr><td><code>AGENT_BROWSER_ENGINE</code></td><td>Browser engine to use: <code>chrome</code> (default), <code>lightpanda</code>. Implies <code>--native</code>.</td><td><code>chrome</code></td></tr>
     <tr><td><code>AGENT_BROWSER_NATIVE</code></td><td>Use the experimental native Rust daemon instead of Node.js/Playwright.</td><td>(disabled)</td></tr>
   </tbody>
 </table>

docs/src/app/engines/chrome/page.mdx

@@ -0,0 +1,105 @@
+import { pageMetadata } from "@/lib/page-metadata"
+
+export const metadata = pageMetadata("engines/chrome")
+
+# Chrome
+
+Chrome (and Chromium) is the default browser engine. agent-browser discovers, launches, and manages the Chrome process automatically via the Chrome DevTools Protocol (CDP).
+
+## Binary Discovery
+
+When no `--executable-path` is provided, agent-browser searches for Chrome in this order:
+
+<table>
+  <thead>
+    <tr><th>Platform</th><th>Locations checked</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>macOS</td>
+      <td>
+        <code>/Applications/Google Chrome.app</code>,
+        <code>/Applications/Google Chrome Canary.app</code>,
+        <code>/Applications/Chromium.app</code>,
+        Playwright Chromium cache
+      </td>
+    </tr>
+    <tr>
+      <td>Linux</td>
+      <td>
+        <code>google-chrome</code>,
+        <code>google-chrome-stable</code>,
+        <code>chromium-browser</code>,
+        <code>chromium</code> in PATH,
+        Playwright Chromium cache
+      </td>
+    </tr>
+    <tr>
+      <td>Windows</td>
+      <td>
+        <code>%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe</code>,
+        <code>C:\Program Files\Google\Chrome\Application\chrome.exe</code>,
+        <code>C:\Program Files (x86)\...\chrome.exe</code>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+If Chrome is not found, run `agent-browser install` to download Chromium via Playwright.
+
+## Usage
+
+Chrome is the default engine -- no `--engine` flag is needed:
+
+```bash
+agent-browser open example.com
+```
+
+To be explicit:
+
+```bash
+agent-browser --engine chrome open example.com
+```
+
+## Custom Binary
+
+Point to any Chromium-based browser with `--executable-path`:
+
+```bash
+agent-browser --executable-path /path/to/chromium open example.com
+```
+
+Or via environment variable:
+
+```bash
+export AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium
+agent-browser open example.com
+```
+
+## Chrome-Specific Features
+
+These features are available only with Chrome:
+
+<table>
+  <thead>
+    <tr><th>Feature</th><th>Flag</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>Browser extensions</td><td><code>--extension &lt;path&gt;</code></td></tr>
+    <tr><td>Persistent profiles</td><td><code>--profile &lt;path&gt;</code></td></tr>
+    <tr><td>Storage state</td><td><code>--state &lt;path&gt;</code></td></tr>
+    <tr><td>File URL access</td><td><code>--allow-file-access</code></td></tr>
+    <tr><td>Headed mode</td><td><code>--headed</code></td></tr>
+    <tr><td>Custom launch args</td><td><code>--args &lt;args&gt;</code></td></tr>
+  </tbody>
+</table>
+
+## Containers and CI
+
+In Docker, CI runners, or other sandboxed environments, Chrome's user namespace sandbox may need to be disabled:
+
+```bash
+agent-browser --args "--no-sandbox" open example.com
+```
+
+agent-browser automatically adds `--no-sandbox` when it detects a container environment (Docker, Podman, running as root).

docs/src/app/engines/lightpanda/page.mdx

@@ -0,0 +1,97 @@
+import { pageMetadata } from "@/lib/page-metadata"
+
+export const metadata = pageMetadata("engines/lightpanda")
+
+# Lightpanda
+
+[Lightpanda](https://lightpanda.io/) is a headless browser engine built from scratch in Zig for machines. It starts instantly, uses 10x less memory than Chrome, and executes 10x faster.
+
+agent-browser manages Lightpanda the same way it manages Chrome -- spawning the process, connecting via CDP, and shutting it down. All downstream commands (snapshot, click, fill, screenshot, etc.) work through the same CDP protocol path.
+
+## Installation
+
+Install the Lightpanda binary before using it with agent-browser:
+
+<table>
+  <thead>
+    <tr><th>Platform</th><th>Command</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>macOS (Apple Silicon)</td>
+      <td><code>curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && chmod a+x ./lightpanda</code></td>
+    </tr>
+    <tr>
+      <td>Linux (x86_64)</td>
+      <td><code>curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && chmod a+x ./lightpanda</code></td>
+    </tr>
+  </tbody>
+</table>
+
+Move the binary somewhere in your `PATH` (e.g. `/usr/local/bin/lightpanda` or `~/.local/bin/lightpanda`).
+
+See the [Lightpanda installation docs](https://lightpanda.io/docs/open-source/installation) for more options.
+
+## Usage
+
+Use the `--engine` flag to select Lightpanda:
+
+```bash
+agent-browser --engine lightpanda open example.com
+agent-browser --engine lightpanda snapshot
+agent-browser --engine lightpanda screenshot
+```
+
+Or set it as the default via environment variable:
+
+```bash
+export AGENT_BROWSER_ENGINE=lightpanda
+agent-browser open example.com
+```
+
+Or in your `agent-browser.json` config:
+
+```json
+{
+  "engine": "lightpanda"
+}
+```
+
+## Custom Binary Path
+
+If the `lightpanda` binary is not in your `PATH`, use `--executable-path`:
+
+```bash
+agent-browser --engine lightpanda --executable-path /path/to/lightpanda open example.com
+```
+
+## Differences from Chrome
+
+Lightpanda is a purpose-built headless engine. Some Chrome-specific features are not available:
+
+<table>
+  <thead>
+    <tr><th>Feature</th><th>Status</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>Extensions (<code>--extension</code>)</td><td>Not supported</td></tr>
+    <tr><td>Persistent profiles (<code>--profile</code>)</td><td>Not supported</td></tr>
+    <tr><td>Storage state (<code>--state</code>)</td><td>Not supported</td></tr>
+    <tr><td>File access (<code>--allow-file-access</code>)</td><td>Not supported</td></tr>
+    <tr><td>Headed mode (<code>--headed</code>)</td><td>Not applicable (headless only)</td></tr>
+    <tr><td>Screenshots</td><td>Depends on Lightpanda CDP support</td></tr>
+  </tbody>
+</table>
+
+agent-browser returns a clear error if you combine `--engine lightpanda` with unsupported flags.
+
+## When to Use Lightpanda
+
+Lightpanda is a good fit for:
+
+- Fast web scraping and data extraction
+- AI agent workflows where speed and low memory matter
+- CI/CD environments with constrained resources
+- High-volume parallel automation
+
+Use Chrome when you need full browser fidelity, extensions, or persistent profiles.

docs/src/lib/docs-navigation.ts

@@ -40,6 +40,13 @@ export const navigation: NavSection[] = [
       { name: "Native Mode (Experimental)", href: "/native-mode" },
     ],
   },
+  {
+    title: "Engines",
+    items: [
+      { name: "Chrome", href: "/engines/chrome" },
+      { name: "Lightpanda", href: "/engines/lightpanda" },
+    ],
+  },
   {
     title: null,
     items: [{ name: "Changelog", href: "/changelog" }],

docs/src/lib/page-titles.ts

@@ -14,6 +14,8 @@ export const PAGE_TITLES: Record<string, string> = {
   profiler: "Profiler",
   ios: "iOS Simulator",
   security: "Security",
+  "engines/chrome": "Chrome",
+  "engines/lightpanda": "Lightpanda",
   "native-mode": "Native Mode (Experimental)",
   changelog: "Changelog",
 };