Remove benchmark/run.ts from PR

Co-authored-by: ctate <chris@ctate.dev>

.gitignore

@@ -42,3 +42,9 @@ yarn.lock
 
 # opensrc - source code for packages
 opensrc/
+
+# Docs site
+docs/node_modules/
+docs/.next/
+docs/out/
+docs/package-lock.json

docs/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

docs/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

docs/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;

docs/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "docs",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "next": "16.1.1",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "shiki": "^3.21.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.1.1",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

docs/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

docs/src/app/agent-mode/page.tsx

@@ -0,0 +1,72 @@
+import { CodeBlock } from "@/components/code-block";
+
+export default function AgentMode() {
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
+      <div className="prose">
+        <h1>Agent Mode</h1>
+        <p>
+          agent-browser works with any AI coding agent. Use <code>--json</code> for machine-readable output.
+        </p>
+
+        <h2>Compatible agents</h2>
+        <ul>
+          <li>Claude Code</li>
+          <li>Cursor</li>
+          <li>GitHub Copilot</li>
+          <li>OpenAI Codex</li>
+          <li>Google Gemini</li>
+          <li>opencode</li>
+          <li>Any agent that can run shell commands</li>
+        </ul>
+
+        <h2>JSON output</h2>
+        <CodeBlock code={`agent-browser snapshot --json
+# {"success":true,"data":{"snapshot":"...","refs":{...}}}
+
+agent-browser get text @e1 --json
+agent-browser is visible @e2 --json`} />
+
+        <h2>Optimal workflow</h2>
+        <CodeBlock code={`# 1. Navigate and get snapshot
+agent-browser open example.com
+agent-browser snapshot -i --json   # AI parses tree and refs
+
+# 2. AI identifies target refs from snapshot
+# 3. Execute actions using refs
+agent-browser click @e2
+agent-browser fill @e3 "input text"
+
+# 4. Get new snapshot if page changed
+agent-browser snapshot -i --json`} />
+
+        <h2>Integration</h2>
+
+        <h3>Just ask</h3>
+        <p>The simplest approach:</p>
+        <CodeBlock lang="text" code="Use agent-browser to test the login flow. Run agent-browser --help to see available commands." />
+        <p>The <code>--help</code> output is comprehensive.</p>
+
+        <h3>AGENTS.md / CLAUDE.md</h3>
+        <p>For consistent results, add to your instructions file:</p>
+        <CodeBlock lang="markdown" code={`## Browser Automation
+
+Use \`agent-browser\` for web automation. Run \`agent-browser --help\` for all commands.
+
+Core workflow:
+1. \`agent-browser open <url>\` - Navigate to page
+2. \`agent-browser snapshot -i\` - Get interactive elements with refs (@e1, @e2)
+3. \`agent-browser click @e1\` / \`fill @e2 "text"\` - Interact using refs
+4. Re-snapshot after page changes`} />
+
+        <h3>Claude Code skill</h3>
+        <p>For richer context:</p>
+        <CodeBlock code="cp -r node_modules/agent-browser/skills/agent-browser .claude/skills/" />
+        <p>Or download:</p>
+        <CodeBlock code={`mkdir -p .claude/skills/agent-browser
+curl -o .claude/skills/agent-browser/SKILL.md \\
+  https://raw.githubusercontent.com/vercel-labs/agent-browser/main/skills/agent-browser/SKILL.md`} />
+      </div>
+    </div>
+  );
+}

docs/src/app/cdp-mode/page.tsx

@@ -0,0 +1,79 @@
+import { CodeBlock } from "@/components/code-block";
+
+export default function CDPMode() {
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
+      <div className="prose">
+        <h1>CDP Mode</h1>
+        <p>Connect to an existing browser via Chrome DevTools Protocol:</p>
+        <CodeBlock code={`# Connect to Electron app
+agent-browser --cdp 9222 snapshot
+
+# Connect to Chrome with remote debugging
+# (Start Chrome with: google-chrome --remote-debugging-port=9222)
+agent-browser --cdp 9222 open about:blank`} />
+
+        <h2>Use cases</h2>
+        <p>This enables control of:</p>
+        <ul>
+          <li>Electron apps</li>
+          <li>Chrome/Chromium with remote debugging</li>
+          <li>WebView2 applications</li>
+          <li>Any browser exposing a CDP endpoint</li>
+        </ul>
+
+        <h2>Global options</h2>
+        <table>
+          <thead>
+            <tr>
+              <th>Option</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td><code>--session &lt;name&gt;</code></td>
+              <td>Use isolated session</td>
+            </tr>
+            <tr>
+              <td><code>--headers &lt;json&gt;</code></td>
+              <td>HTTP headers scoped to origin</td>
+            </tr>
+            <tr>
+              <td><code>--executable-path</code></td>
+              <td>Custom browser executable</td>
+            </tr>
+            <tr>
+              <td><code>--json</code></td>
+              <td>JSON output for agents</td>
+            </tr>
+            <tr>
+              <td><code>--full, -f</code></td>
+              <td>Full page screenshot</td>
+            </tr>
+            <tr>
+              <td><code>--name, -n</code></td>
+              <td>Locator name filter</td>
+            </tr>
+            <tr>
+              <td><code>--exact</code></td>
+              <td>Exact text match</td>
+            </tr>
+            <tr>
+              <td><code>--headed</code></td>
+              <td>Show browser window</td>
+            </tr>
+            <tr>
+              <td><code>--cdp &lt;port&gt;</code></td>
+              <td>CDP connection port</td>
+            </tr>
+            <tr>
+              <td><code>--debug</code></td>
+              <td>Debug output</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

docs/src/app/commands/page.tsx

@@ -0,0 +1,121 @@
+import { CodeBlock } from "@/components/code-block";
+
+export default function Commands() {
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
+      <div className="prose">
+        <h1>Commands</h1>
+
+        <h2>Core</h2>
+        <CodeBlock code={`agent-browser open <url>              # Navigate (aliases: goto, navigate)
+agent-browser click <sel>             # Click element
+agent-browser dblclick <sel>          # Double-click
+agent-browser fill <sel> <text>       # Clear and fill
+agent-browser type <sel> <text>       # Type into element
+agent-browser press <key>             # Press key (Enter, Tab, Control+a)
+agent-browser hover <sel>             # Hover element
+agent-browser select <sel> <val>      # Select dropdown option
+agent-browser check <sel>             # Check checkbox
+agent-browser uncheck <sel>           # Uncheck checkbox
+agent-browser scroll <dir> [px]       # Scroll (up/down/left/right)
+agent-browser screenshot [path]       # Screenshot (--full for full page)
+agent-browser snapshot                # Accessibility tree with refs
+agent-browser eval <js>               # Run JavaScript
+agent-browser close                   # Close browser`} />
+
+        <h2>Get info</h2>
+        <CodeBlock code={`agent-browser get text <sel>          # Get text content
+agent-browser get html <sel>          # Get innerHTML
+agent-browser get value <sel>         # Get input value
+agent-browser get attr <sel> <attr>   # Get attribute
+agent-browser get title               # Get page title
+agent-browser get url                 # Get current URL
+agent-browser get count <sel>         # Count matching elements
+agent-browser get box <sel>           # Get bounding box`} />
+
+        <h2>Check state</h2>
+        <CodeBlock code={`agent-browser is visible <sel>        # Check if visible
+agent-browser is enabled <sel>        # Check if enabled
+agent-browser is checked <sel>        # Check if checked`} />
+
+        <h2>Find elements</h2>
+        <p>Semantic locators with actions (<code>click</code>, <code>fill</code>, <code>check</code>, <code>hover</code>, <code>text</code>):</p>
+        <CodeBlock code={`agent-browser find role <role> <action> [value]
+agent-browser find text <text> <action>
+agent-browser find label <label> <action> [value]
+agent-browser find placeholder <ph> <action> [value]
+agent-browser find testid <id> <action> [value]
+agent-browser find first <sel> <action> [value]
+agent-browser find nth <n> <sel> <action> [value]`} />
+        <p>Examples:</p>
+        <CodeBlock code={`agent-browser find role button click --name "Submit"
+agent-browser find label "Email" fill "test@test.com"
+agent-browser find first ".item" click`} />
+
+        <h2>Wait</h2>
+        <CodeBlock code={`agent-browser wait <selector>         # Wait for element
+agent-browser wait <ms>               # Wait for time
+agent-browser wait --text "Welcome"   # Wait for text
+agent-browser wait --url "**/dash"    # Wait for URL pattern
+agent-browser wait --load networkidle # Wait for load state
+agent-browser wait --fn "condition"   # Wait for JS condition`} />
+
+        <h2>Mouse</h2>
+        <CodeBlock code={`agent-browser mouse move <x> <y>      # Move mouse
+agent-browser mouse down [button]     # Press button
+agent-browser mouse up [button]       # Release button
+agent-browser mouse wheel <dy> [dx]   # Scroll wheel`} />
+
+        <h2>Settings</h2>
+        <CodeBlock code={`agent-browser set viewport <w> <h>    # Set viewport size
+agent-browser set device <name>       # Emulate device ("iPhone 14")
+agent-browser set geo <lat> <lng>     # Set geolocation
+agent-browser set offline [on|off]    # Toggle offline mode
+agent-browser set headers <json>      # Extra HTTP headers
+agent-browser set credentials <u> <p> # HTTP basic auth
+agent-browser set media [dark|light]  # Emulate color scheme`} />
+
+        <h2>Cookies & storage</h2>
+        <CodeBlock code={`agent-browser cookies                 # Get all cookies
+agent-browser cookies set <name> <val> # Set cookie
+agent-browser cookies clear           # Clear cookies
+
+agent-browser storage local           # Get all localStorage
+agent-browser storage local <key>     # Get specific key
+agent-browser storage local set <k> <v>  # Set value
+agent-browser storage local clear     # Clear all
+
+agent-browser storage session         # Same for sessionStorage`} />
+
+        <h2>Network</h2>
+        <CodeBlock code={`agent-browser network route <url>              # Intercept requests
+agent-browser network route <url> --abort      # Block requests
+agent-browser network route <url> --body <json>  # Mock response
+agent-browser network unroute [url]            # Remove routes
+agent-browser network requests                 # View tracked requests`} />
+
+        <h2>Tabs & frames</h2>
+        <CodeBlock code={`agent-browser tab                     # List tabs
+agent-browser tab new [url]           # New tab
+agent-browser tab <n>                 # Switch to tab
+agent-browser tab close [n]           # Close tab
+agent-browser frame <sel>             # Switch to iframe
+agent-browser frame main              # Back to main frame`} />
+
+        <h2>Debug</h2>
+        <CodeBlock code={`agent-browser trace start [path]      # Start trace
+agent-browser trace stop [path]       # Stop and save trace
+agent-browser console                 # View console messages
+agent-browser errors                  # View page errors
+agent-browser highlight <sel>         # Highlight element
+agent-browser state save <path>       # Save auth state
+agent-browser state load <path>       # Load auth state`} />
+
+        <h2>Navigation</h2>
+        <CodeBlock code={`agent-browser back                    # Go back
+agent-browser forward                 # Go forward
+agent-browser reload                  # Reload page`} />
+      </div>
+    </div>
+  );
+}

docs/src/app/globals.css

@@ -0,0 +1,182 @@
+@import "tailwindcss";
+
+:root {
+  --background: #000000;
+  --foreground: #ededed;
+  --muted: #888888;
+  --border: #222222;
+  --accent: #ededed;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-muted: var(--muted);
+  --color-border: var(--border);
+  --color-accent: var(--accent);
+  --font-sans: var(--font-geist);
+  --font-mono: var(--font-geist-mono);
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: var(--font-geist), system-ui, sans-serif;
+}
+
+/* Scrollbar */
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #333;
+  border-radius: 3px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #444;
+}
+
+/* Code blocks */
+pre {
+  background: #111 !important;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 0.875rem;
+  overflow-x: auto;
+  font-family: var(--font-geist-mono), monospace;
+  font-size: 0.8125rem;
+  line-height: 1.7;
+}
+
+.code-block pre {
+  margin: 0;
+}
+
+.code-block {
+  margin-bottom: 1.25rem;
+}
+
+@media (max-width: 640px) {
+  pre {
+    font-size: 0.75rem;
+    padding: 0.75rem;
+  }
+}
+
+code {
+  font-family: var(--font-geist-mono), monospace;
+}
+
+:not(pre) > code {
+  background: #1a1a1a;
+  padding: 0.125rem 0.375rem;
+  border-radius: 3px;
+  font-size: 0.875em;
+}
+
+/* Prose */
+.prose {
+  max-width: 100%;
+}
+
+.prose h1 {
+  font-size: 1.5rem;
+  font-weight: 500;
+  letter-spacing: -0.02em;
+  margin-bottom: 0.5rem;
+  color: #fff;
+}
+
+@media (min-width: 640px) {
+  .prose h1 {
+    font-size: 1.75rem;
+  }
+}
+
+.prose h2 {
+  font-size: 0.875rem;
+  font-weight: 500;
+  letter-spacing: 0;
+  text-transform: uppercase;
+  color: var(--muted);
+  margin-top: 3rem;
+  margin-bottom: 1rem;
+}
+
+.prose h3 {
+  font-size: 0.875rem;
+  font-weight: 500;
+  margin-top: 2rem;
+  margin-bottom: 0.75rem;
+  color: #ccc;
+}
+
+.prose p {
+  margin-bottom: 1.25rem;
+  line-height: 1.7;
+  color: var(--muted);
+  font-size: 0.9375rem;
+}
+
+.prose ul, .prose ol {
+  margin-bottom: 1.25rem;
+  padding-left: 1.25rem;
+}
+
+.prose li {
+  margin-bottom: 0.5rem;
+  color: var(--muted);
+  font-size: 0.9375rem;
+  line-height: 1.6;
+}
+
+.prose li strong {
+  color: #ccc;
+  font-weight: 500;
+}
+
+.prose a {
+  color: var(--foreground);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.prose a:hover {
+  color: #fff;
+}
+
+.prose table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1.5rem 0;
+  font-size: 0.8125rem;
+}
+
+.prose th, .prose td {
+  text-align: left;
+  padding: 0.625rem 0.875rem;
+  border-bottom: 1px solid var(--border);
+}
+
+.prose th {
+  font-weight: 500;
+  color: var(--muted);
+  text-transform: uppercase;
+  font-size: 0.75rem;
+  letter-spacing: 0.025em;
+}
+
+.prose td {
+  color: var(--muted);
+}
+
+.prose td code {
+  color: var(--foreground);
+}

docs/src/app/installation/page.tsx

@@ -0,0 +1,58 @@
+import { CodeBlock } from "@/components/code-block";
+
+export default function Installation() {
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
+      <div className="prose">
+        <h1>Installation</h1>
+
+        <h2>npm (recommended)</h2>
+        <CodeBlock code={`npm install -g agent-browser
+agent-browser install  # Download Chromium`} />
+
+        <h2>From source</h2>
+        <CodeBlock code={`git clone https://github.com/vercel-labs/agent-browser
+cd agent-browser
+pnpm install
+pnpm build
+pnpm build:native
+./bin/agent-browser install
+pnpm link --global`} />
+
+        <h2>Linux dependencies</h2>
+        <p>On Linux, install system dependencies:</p>
+        <CodeBlock code={`agent-browser install --with-deps
+# or manually: npx playwright install-deps chromium`} />
+
+        <h2>Custom browser</h2>
+        <p>
+          Use a custom browser executable instead of bundled Chromium:
+        </p>
+        <ul>
+          <li><strong>Serverless</strong> - Use <code>@sparticuz/chromium</code> (~50MB vs ~684MB)</li>
+          <li><strong>System browser</strong> - Use existing Chrome installation</li>
+          <li><strong>Custom builds</strong> - Use modified browser builds</li>
+        </ul>
+
+        <CodeBlock code={`# Via flag
+agent-browser --executable-path /path/to/chromium open example.com
+
+# Via environment variable
+AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com`} />
+
+        <h3>Serverless example</h3>
+        <CodeBlock lang="typescript" code={`import chromium from '@sparticuz/chromium';
+import { BrowserManager } from 'agent-browser';
+
+export async function handler() {
+  const browser = new BrowserManager();
+  await browser.launch({
+    executablePath: await chromium.executablePath(),
+    headless: true,
+  });
+  // ... use browser
+}`} />
+      </div>
+    </div>
+  );
+}

docs/src/app/layout.tsx

@@ -0,0 +1,40 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+import { Sidebar } from "@/components/sidebar";
+
+const geist = Geist({
+  variable: "--font-geist",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "agent-browser",
+  description: "Headless browser automation CLI for AI agents",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en" className="dark">
+      <body
+        className={`${geist.variable} ${geistMono.variable} antialiased bg-zinc-950 text-zinc-100`}
+      >
+        <div className="flex min-h-screen">
+          <Sidebar />
+          <main className="flex-1 overflow-auto pt-14 lg:pt-0">
+            {children}
+          </main>
+        </div>
+      </body>
+    </html>
+  );
+}

docs/src/app/page.tsx

@@ -0,0 +1,69 @@
+import { CodeBlock } from "@/components/code-block";
+
+export default function Home() {
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
+      <div className="prose">
+        <h1>agent-browser</h1>
+        <p>
+          Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallback.
+        </p>
+
+        <CodeBlock code="npm install -g agent-browser" />
+
+        <h2>Features</h2>
+        <ul>
+          <li><strong>Universal</strong> - Works with any AI agent: Claude Code, Cursor, Codex, Copilot, Gemini, opencode, and more</li>
+          <li><strong>AI-first</strong> - Snapshot returns accessibility tree with refs for deterministic element selection</li>
+          <li><strong>Fast</strong> - Native Rust CLI for instant command parsing</li>
+          <li><strong>Complete</strong> - 50+ commands for navigation, forms, screenshots, network, storage</li>
+          <li><strong>Sessions</strong> - Multiple isolated browser instances with separate auth</li>
+          <li><strong>Cross-platform</strong> - macOS, Linux, Windows with native binaries</li>
+          <li><strong>Serverless</strong> - Custom executable path for lightweight Chromium builds</li>
+        </ul>
+
+        <h2>Example</h2>
+        <CodeBlock code={`# Navigate and get snapshot
+agent-browser open example.com
+agent-browser snapshot -i
+
+# Output:
+# - heading "Example Domain" [ref=e1]
+# - link "More information..." [ref=e2]
+
+# Interact using refs
+agent-browser click @e2
+agent-browser screenshot page.png
+agent-browser close`} />
+
+        <h2>Why refs?</h2>
+        <p>
+          The <code>snapshot</code> command returns an accessibility tree where each element 
+          has a unique ref like <code>@e1</code>, <code>@e2</code>. This provides:
+        </p>
+        <ul>
+          <li><strong>Deterministic</strong> - Ref points to exact element from snapshot</li>
+          <li><strong>Fast</strong> - No DOM re-query needed</li>
+          <li><strong>AI-friendly</strong> - LLMs can reliably parse and use refs</li>
+        </ul>
+
+        <h2>Architecture</h2>
+        <p>
+          Client-daemon architecture for optimal performance:
+        </p>
+        <ol>
+          <li><strong>Rust CLI</strong> - Parses commands, communicates with daemon</li>
+          <li><strong>Node.js Daemon</strong> - Manages Playwright browser instance</li>
+        </ol>
+        <p>
+          Daemon starts automatically and persists between commands.
+        </p>
+
+        <h2>Platforms</h2>
+        <p>
+          Native Rust binaries for macOS (ARM64, x64), Linux (ARM64, x64), and Windows (x64).
+        </p>
+      </div>
+    </div>
+  );
+}

docs/src/app/quick-start/page.tsx

@@ -0,0 +1,50 @@
+import { CodeBlock } from "@/components/code-block";
+
+export default function QuickStart() {
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
+      <div className="prose">
+        <h1>Quick Start</h1>
+
+        <h2>Basic workflow</h2>
+        <CodeBlock code={`agent-browser open example.com
+agent-browser snapshot                    # Get accessibility tree with refs
+agent-browser click @e2                   # Click by ref from snapshot
+agent-browser fill @e3 "test@example.com" # Fill by ref
+agent-browser get text @e1                # Get text by ref
+agent-browser screenshot page.png
+agent-browser close`} />
+
+        <h2>Traditional selectors</h2>
+        <p>CSS selectors and semantic locators also supported:</p>
+        <CodeBlock code={`agent-browser click "#submit"
+agent-browser fill "#email" "test@example.com"
+agent-browser find role button click --name "Submit"`} />
+
+        <h2>AI workflow</h2>
+        <p>Optimal workflow for AI agents:</p>
+        <CodeBlock code={`# 1. Navigate and get snapshot
+agent-browser open example.com
+agent-browser snapshot -i --json   # AI parses tree and refs
+
+# 2. AI identifies target refs from snapshot
+# 3. Execute actions using refs
+agent-browser click @e2
+agent-browser fill @e3 "input text"
+
+# 4. Get new snapshot if page changed
+agent-browser snapshot -i --json`} />
+
+        <h2>Headed mode</h2>
+        <p>Show browser window for debugging:</p>
+        <CodeBlock code="agent-browser open example.com --headed" />
+
+        <h2>JSON output</h2>
+        <p>Use <code>--json</code> for machine-readable output:</p>
+        <CodeBlock code={`agent-browser snapshot --json
+agent-browser get text @e1 --json
+agent-browser is visible @e2 --json`} />
+      </div>
+    </div>
+  );
+}

docs/src/app/selectors/page.tsx

@@ -0,0 +1,53 @@
+import { CodeBlock } from "@/components/code-block";
+
+export default function Selectors() {
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
+      <div className="prose">
+        <h1>Selectors</h1>
+
+        <h2>Refs (recommended)</h2>
+        <p>
+          Refs provide deterministic element selection from snapshots. Best for AI agents.
+        </p>
+        <CodeBlock code={`# 1. Get snapshot with refs
+agent-browser snapshot
+# Output:
+# - heading "Example Domain" [ref=e1] [level=1]
+# - button "Submit" [ref=e2]
+# - textbox "Email" [ref=e3]
+# - link "Learn more" [ref=e4]
+
+# 2. Use refs to interact
+agent-browser click @e2                   # Click the button
+agent-browser fill @e3 "test@example.com" # Fill the textbox
+agent-browser get text @e1                # Get heading text
+agent-browser hover @e4                   # Hover the link`} />
+
+        <h3>Why refs?</h3>
+        <ul>
+          <li><strong>Deterministic</strong> - Ref points to exact element from snapshot</li>
+          <li><strong>Fast</strong> - No DOM re-query needed</li>
+          <li><strong>AI-friendly</strong> - LLMs can reliably parse and use refs</li>
+        </ul>
+
+        <h2>CSS selectors</h2>
+        <CodeBlock code={`agent-browser click "#id"
+agent-browser click ".class"
+agent-browser click "div > button"
+agent-browser click "[data-testid='submit']"`} />
+
+        <h2>Text & XPath</h2>
+        <CodeBlock code={`agent-browser click "text=Submit"
+agent-browser click "xpath=//button[@type='submit']"`} />
+
+        <h2>Semantic locators</h2>
+        <p>Find elements by role, label, or other semantic properties:</p>
+        <CodeBlock code={`agent-browser find role button click --name "Submit"
+agent-browser find label "Email" fill "test@test.com"
+agent-browser find placeholder "Search..." fill "query"
+agent-browser find testid "submit-btn" click`} />
+      </div>
+    </div>
+  );
+}

docs/src/app/sessions/page.tsx

@@ -0,0 +1,66 @@
+import { CodeBlock } from "@/components/code-block";
+
+export default function Sessions() {
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
+      <div className="prose">
+        <h1>Sessions</h1>
+        <p>Run multiple isolated browser instances:</p>
+        <CodeBlock code={`# Different sessions
+agent-browser --session agent1 open site-a.com
+agent-browser --session agent2 open site-b.com
+
+# Or via environment variable
+AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"
+
+# List active sessions
+agent-browser session list
+# Output:
+# Active sessions:
+# -> default
+#    agent1
+
+# Show current session
+agent-browser session`} />
+
+        <h2>Session isolation</h2>
+        <p>Each session has its own:</p>
+        <ul>
+          <li>Browser instance</li>
+          <li>Cookies and storage</li>
+          <li>Navigation history</li>
+          <li>Authentication state</li>
+        </ul>
+
+        <h2>Authenticated sessions</h2>
+        <p>
+          Use <code>--headers</code> to set HTTP headers for a specific origin:
+        </p>
+        <CodeBlock code={`# Headers scoped to api.example.com only
+agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'
+
+# Requests to api.example.com include the auth header
+agent-browser snapshot -i --json
+agent-browser click @e2
+
+# Navigate to another domain - headers NOT sent
+agent-browser open other-site.com`} />
+        <p>Useful for:</p>
+        <ul>
+          <li><strong>Skipping login flows</strong> - Authenticate via headers</li>
+          <li><strong>Switching users</strong> - Different auth tokens per session</li>
+          <li><strong>API testing</strong> - Access protected endpoints</li>
+          <li><strong>Security</strong> - Headers scoped to origin, not leaked</li>
+        </ul>
+
+        <h2>Multiple origins</h2>
+        <CodeBlock code={`agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
+agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'`} />
+
+        <h2>Global headers</h2>
+        <p>For headers on all domains:</p>
+        <CodeBlock code={`agent-browser set headers '{"X-Custom-Header": "value"}'`} />
+      </div>
+    </div>
+  );
+}

docs/src/app/snapshots/page.tsx

@@ -0,0 +1,71 @@
+import { CodeBlock } from "@/components/code-block";
+
+export default function Snapshots() {
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
+      <div className="prose">
+        <h1>Snapshots</h1>
+        <p>
+          The <code>snapshot</code> command returns the accessibility tree with refs for AI-friendly interaction.
+        </p>
+
+        <h2>Options</h2>
+        <p>Filter output to reduce size:</p>
+        <CodeBlock code={`agent-browser snapshot                    # Full accessibility tree
+agent-browser snapshot -i                 # Interactive elements only
+agent-browser snapshot -c                 # Compact (remove empty elements)
+agent-browser snapshot -d 3               # Limit depth to 3 levels
+agent-browser snapshot -s "#main"         # Scope to CSS selector
+agent-browser snapshot -i -c -d 5         # Combine options`} />
+
+        <table>
+          <thead>
+            <tr>
+              <th>Option</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td><code>-i, --interactive</code></td>
+              <td>Only interactive elements (buttons, links, inputs)</td>
+            </tr>
+            <tr>
+              <td><code>-c, --compact</code></td>
+              <td>Remove empty structural elements</td>
+            </tr>
+            <tr>
+              <td><code>-d, --depth</code></td>
+              <td>Limit tree depth</td>
+            </tr>
+            <tr>
+              <td><code>-s, --selector</code></td>
+              <td>Scope to CSS selector</td>
+            </tr>
+          </tbody>
+        </table>
+
+        <h2>Output format</h2>
+        <CodeBlock code={`agent-browser snapshot
+# Output:
+# - heading "Example Domain" [ref=e1] [level=1]
+# - button "Submit" [ref=e2]
+# - textbox "Email" [ref=e3]
+# - link "Learn more" [ref=e4]`} />
+
+        <h2>JSON output</h2>
+        <p>Use <code>--json</code> for machine-readable output:</p>
+        <CodeBlock code={`agent-browser snapshot --json
+# {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}`} />
+
+        <h2>Best practices</h2>
+        <ol>
+          <li>Use <code>-i</code> to reduce output to actionable elements</li>
+          <li>Use <code>--json</code> for structured parsing</li>
+          <li>Re-snapshot after page changes to get updated refs</li>
+          <li>Scope with <code>-s</code> for specific page sections</li>
+        </ol>
+      </div>
+    </div>
+  );
+}

docs/src/components/code-block.tsx

@@ -0,0 +1,22 @@
+import { codeToHtml } from "shiki";
+import { CopyButton } from "./copy-button";
+
+interface CodeBlockProps {
+  code: string;
+  lang?: string;
+}
+
+export async function CodeBlock({ code, lang = "bash" }: CodeBlockProps) {
+  const trimmedCode = code.trim();
+  const html = await codeToHtml(trimmedCode, {
+    lang,
+    theme: "github-dark-default",
+  });
+
+  return (
+    <div className="code-block relative group">
+      <CopyButton code={trimmedCode} />
+      <div dangerouslySetInnerHTML={{ __html: html }} />
+    </div>
+  );
+}

docs/src/components/copy-button.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import { useState } from "react";
+
+interface CopyButtonProps {
+  code: string;
+}
+
+export function CopyButton({ code }: CopyButtonProps) {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch (error) {
+      console.error("Failed to copy to clipboard:", error);
+      // Optionally, you could set an error state or show a toast notification here
+    }
+  };
+
+  return (
+    <button
+      onClick={handleCopy}
+      className="absolute top-2 right-2 p-1.5 rounded text-[#666] hover:text-[#999] hover:bg-[#333] opacity-0 group-hover:opacity-100 transition-all"
+      aria-label="Copy code"
+    >
+      {copied ? (
+        <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M5 13l4 4L19 7" />
+        </svg>
+      ) : (
+        <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+        </svg>
+      )}
+    </button>
+  );
+}

docs/src/components/sidebar.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { useState, useEffect } from "react";
+
+const navigation = [
+  { name: "Introduction", href: "/" },
+  { name: "Installation", href: "/installation" },
+  { name: "Quick Start", href: "/quick-start" },
+  { name: "Commands", href: "/commands" },
+  { name: "Selectors", href: "/selectors" },
+  { name: "Sessions", href: "/sessions" },
+  { name: "Snapshots", href: "/snapshots" },
+  { name: "Agent Mode", href: "/agent-mode" },
+  { name: "CDP Mode", href: "/cdp-mode" },
+];
+
+export function Sidebar() {
+  const pathname = usePathname();
+  const [isOpen, setIsOpen] = useState(false);
+
+  useEffect(() => {
+    setIsOpen(false);
+  }, [pathname]);
+
+  useEffect(() => {
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setIsOpen(false);
+    };
+    document.addEventListener("keydown", handleEscape);
+    return () => document.removeEventListener("keydown", handleEscape);
+  }, []);
+
+  return (
+    <>
+      {/* Mobile header */}
+      <header className="lg:hidden fixed top-0 left-0 right-0 z-50 bg-black/90 backdrop-blur-sm border-b border-[#222] px-4 py-3">
+        <div className="flex items-center justify-between">
+          <Link href="/" className="text-sm font-medium">
+            agent-browser
+          </Link>
+          <button
+            onClick={() => setIsOpen(!isOpen)}
+            className="p-2 -mr-2 text-[#888] hover:text-white transition-colors"
+            aria-label="Toggle menu"
+          >
+            {isOpen ? (
+              <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M6 18L18 6M6 6l12 12" />
+              </svg>
+            ) : (
+              <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M4 6h16M4 12h16M4 18h16" />
+              </svg>
+            )}
+          </button>
+        </div>
+      </header>
+
+      {/* Mobile overlay */}
+      {isOpen && (
+        <div
+          className="lg:hidden fixed inset-0 z-40 bg-black/80"
+          onClick={() => setIsOpen(false)}
+        />
+      )}
+
+      {/* Sidebar */}
+      <aside
+        className={`
+          fixed lg:sticky top-0 left-0 z-50 lg:z-auto
+          w-56 lg:w-48 h-screen
+          bg-black border-r border-[#222]
+          transform transition-transform duration-150 ease-out
+          ${isOpen ? "translate-x-0" : "-translate-x-full lg:translate-x-0"}
+          pt-14 lg:pt-0
+        `}
+      >
+        <div className="h-full overflow-y-auto p-5">
+          {/* Desktop header */}
+          <div className="mb-8 hidden lg:block">
+            <Link href="/" className="text-sm font-medium">
+              agent-browser
+            </Link>
+          </div>
+
+          <nav className="space-y-0.5">
+            {navigation.map((item) => {
+              const isActive = pathname === item.href;
+
+              return (
+                <Link
+                  key={item.name}
+                  href={item.href}
+                  className={`block px-2 py-1.5 text-[13px] transition-colors ${
+                    isActive
+                      ? "text-white"
+                      : "text-[#666] hover:text-[#999]"
+                  }`}
+                >
+                  {item.name}
+                </Link>
+              );
+            })}
+          </nav>
+
+          <div className="mt-8 pt-4 border-t border-[#222] space-y-0.5">
+            <a
+              href="https://github.com/vercel-labs/agent-browser"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="block px-2 py-1.5 text-[13px] text-[#666] hover:text-[#999] transition-colors"
+            >
+              GitHub
+            </a>
+            <a
+              href="https://www.npmjs.com/package/agent-browser"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="block px-2 py-1.5 text-[13px] text-[#666] hover:text-[#999] transition-colors"
+            >
+              npm
+            </a>
+          </div>
+        </div>
+      </aside>
+    </>
+  );
+}

docs/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}