Merge main into ctate/custom-headers

support serverless environments (#29 )
* add --executable-path * tests * test vercel * fixes
2026-01-12 11:57:43 -06:00 · 2026-01-12 11:41:25 -06:00 · 2026-01-12 11:40:52 -06:00 · 2026-01-12 11:26:45 -06:00 · 2026-01-12 11:22:46 -06:00 · 2026-01-12 10:52:31 -06:00
24 changed files with 3661 additions and 299 deletions
@@ -0,0 +1,188 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  typescript:
+    name: TypeScript (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Format check
+        run: pnpm format:check
+
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Run tests
+        run: pnpm test
+
+  rust:
+    name: Rust (${{ matrix.os }} - ${{ matrix.target }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: macos-latest
+            target: aarch64-apple-darwin
+          - os: macos-latest
+            target: x86_64-apple-darwin
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Cache Cargo dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            cli/target/
+          key: ${{ runner.os }}-cargo-${{ matrix.target }}-${{ hashFiles('cli/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-${{ matrix.target }}-
+
+      - name: Build release binary
+        run: cargo build --release --manifest-path cli/Cargo.toml --target ${{ matrix.target }}
+
+      - name: Run Rust tests
+        run: cargo test --manifest-path cli/Cargo.toml --target ${{ matrix.target }}
+
+  windows-integration:
+    name: Windows Integration Test
+    runs-on: windows-latest
+    needs: rust
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: x86_64-pc-windows-msvc
+
+      - name: Cache Cargo dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            cli/target/
+          key: windows-cargo-x86_64-pc-windows-msvc-${{ hashFiles('cli/Cargo.lock') }}
+          restore-keys: |
+            windows-cargo-x86_64-pc-windows-msvc-
+
+      - name: Build Rust CLI
+        run: cargo build --release --manifest-path cli/Cargo.toml --target x86_64-pc-windows-msvc
+
+      - name: Install npm dependencies
+        run: pnpm install
+
+      - name: Build TypeScript
+        run: pnpm build
+
+      - name: Copy CLI binary to bin directory
+        run: |
+          Copy-Item cli/target/x86_64-pc-windows-msvc/release/agent-browser.exe bin/agent-browser-win32-x64.exe
+
+      - name: Test agent-browser install command
+        run: |
+          $env:PATH = "$pwd\bin;$env:PATH"
+          bin/agent-browser-win32-x64.exe install
+        shell: pwsh
+
+      - name: Verify Chromium was installed
+        run: |
+          $playwrightPath = "$env:LOCALAPPDATA\ms-playwright"
+          if (Test-Path $playwrightPath) {
+            Write-Host "Playwright browsers installed at: $playwrightPath"
+            Get-ChildItem $playwrightPath -Recurse -Depth 2 | Select-Object -First 20
+          } else {
+            Write-Error "Playwright browsers not found!"
+            exit 1
+          }
+        shell: pwsh
+
+  serverless-chromium:
+    name: Serverless Chromium (@sparticuz/chromium)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Install @sparticuz/chromium
+        run: pnpm add -D @sparticuz/chromium
+
+      - name: Build TypeScript
+        run: pnpm build
+
+      - name: Run serverless integration test
+        run: pnpm exec vitest run test/serverless.test.ts
@@ -0,0 +1 @@
+pnpm lint-staged
@@ -55,13 +55,13 @@ agent-browser find role button click --name "Submit"
 ### Core Commands

 ```bash
-agent-browser open <url>              # Navigate to URL
+agent-browser open <url>              # Navigate to URL (aliases: goto, navigate)
 agent-browser click <sel>             # Click element
 agent-browser dblclick <sel>          # Double-click element
 agent-browser focus <sel>             # Focus element
 agent-browser type <sel> <text>       # Type into element
 agent-browser fill <sel> <text>       # Clear and fill
-agent-browser press <key>             # Press key (Enter, Tab, Control+a)
+agent-browser press <key>             # Press key (Enter, Tab, Control+a) (alias: key)
 agent-browser keydown <key>           # Hold key down
 agent-browser keyup <key>             # Release key
 agent-browser hover <sel>             # Hover element
@@ -69,14 +69,14 @@ 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 scrollintoview <sel>    # Scroll element into view
+agent-browser scrollintoview <sel>    # Scroll element into view (alias: scrollinto)
 agent-browser drag <src> <tgt>        # Drag and drop
 agent-browser upload <sel> <files>    # Upload files
 agent-browser screenshot [path]       # Take screenshot (--full for full page)
 agent-browser pdf <path>              # Save as PDF
 agent-browser snapshot                # Accessibility tree with refs (best for AI)
 agent-browser eval <js>               # Run JavaScript
-agent-browser close                   # Close browser
+agent-browser close                   # Close browser (aliases: quit, exit)
 ```

 ### Get Info
@@ -129,9 +129,9 @@ agent-browser find nth 2 "a" text
 ### Wait

 ```bash
-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 <selector>         # Wait for element to be visible
+agent-browser wait <ms>               # Wait for time (milliseconds)
+agent-browser wait --text "Welcome"   # Wait for text to appear
 agent-browser wait --url "**/dash"    # Wait for URL pattern
 agent-browser wait --load networkidle # Wait for load state
 agent-browser wait --fn "window.ready === true"  # Wait for JS condition
@@ -253,6 +253,10 @@ 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
@@ -289,6 +293,8 @@ agent-browser snapshot -i -c -d 5         # Combine options
 | Option | Description |
 |--------|-------------|
 | `--session <name>` | Use isolated session (or `AGENT_BROWSER_SESSION` env) |
+| `--headers <json>` | Set HTTP headers scoped to the URL's origin |
+| `--executable-path <path>` | Custom browser executable (or `AGENT_BROWSER_EXECUTABLE_PATH` env) |
 | `--json` | JSON output (for agents) |
 | `--full, -f` | Full page screenshot |
 | `--name, -n` | Locator name filter |
@@ -383,6 +389,74 @@ agent-browser open example.com --headed

 This opens a visible browser window instead of running headless.

+## Authenticated Sessions
+
+Use `--headers` to set HTTP headers for a specific origin, enabling authentication without login flows:
+
+```bash
+# Headers are 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 are NOT sent (safe!)
+agent-browser open other-site.com
+```
+
+This is useful for:
+- **Skipping login flows** - Authenticate via headers instead of UI
+- **Switching users** - Start new sessions with different auth tokens
+- **API testing** - Access protected endpoints directly
+- **Security** - Headers are scoped to the origin, not leaked to other domains
+
+To set headers for multiple origins, use `--headers` with each `open` command:
+
+```bash
+agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
+agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'
+```
+
+For global headers (all domains), use `set headers`:
+
+```bash
+agent-browser set headers '{"X-Custom-Header": "value"}'
+```
+
+## Custom Browser Executable
+
+Use a custom browser executable instead of the bundled Chromium. This is useful for:
+- **Serverless deployment**: Use lightweight Chromium builds like `@sparticuz/chromium` (~50MB vs ~684MB)
+- **System browsers**: Use an existing Chrome/Chromium installation
+- **Custom builds**: Use modified browser builds
+
+### CLI Usage
+
+```bash
+# 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
+```
+
+### Serverless Example (Vercel/AWS Lambda)
+
+```typescript
+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
+}
+```
+
 ## Architecture

 agent-browser uses a client-daemon architecture:
@@ -393,15 +467,61 @@ agent-browser uses a client-daemon architecture:

 The daemon starts automatically on first command and persists between commands for fast subsequent operations.

+**Browser Engine:** Uses Chromium by default. The daemon also supports Firefox and WebKit via the Playwright protocol.
+
 ## Platforms

 | Platform | Binary | Fallback |
 |----------|--------|----------|
-| macOS ARM64 | ✅ Native Rust | Node.js |
-| macOS x64 | ✅ Native Rust | Node.js |
-| Linux ARM64 | ✅ Native Rust | Node.js |
-| Linux x64 | ✅ Native Rust | Node.js |
-| Windows | - | Node.js |
+| macOS ARM64 | Native Rust | Node.js |
+| macOS x64 | Native Rust | Node.js |
+| Linux ARM64 | Native Rust | Node.js |
+| Linux x64 | Native Rust | Node.js |
+| Windows x64 | Native Rust | Node.js |
+
+## Usage with AI Agents
+
+### Just ask the agent
+
+The simplest approach - just tell your agent to use it:
+
+```
+Use agent-browser to test the login flow. Run agent-browser --help to see available commands.
+```
+
+The `--help` output is comprehensive and most agents can figure it out from there.
+
+### AGENTS.md / CLAUDE.md
+
+For more consistent results, add to your project or global instructions file:
+
+```markdown
+## 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
+```
+
+### Claude Code Skill
+
+For Claude Code, a [skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) provides richer context:
+
+```bash
+cp -r node_modules/agent-browser/skills/agent-browser .claude/skills/
+```
+
+Or download:
+
+```bash
+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
+```

 ## License

@@ -4,11 +4,12 @@ version = 4

 [[package]]
 name = "agent-browser"
-version = "0.4.0"
+version = "0.4.3"
 dependencies = [
 "libc",
 "serde",
 "serde_json",
+ "windows-sys",
 ]

 [[package]]
@@ -107,6 +108,79 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"

+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
 [[package]]
 name = "zmij"
 version = "1.0.12"
@@ -1,6 +1,6 @@
 [package]
 name = "agent-browser"
-version = "0.4.0"
+version = "0.4.3"
 edition = "2021"
 description = "Fast browser automation CLI for AI agents"
 license = "Apache-2.0"
@@ -12,6 +12,9 @@ serde_json = "1.0"
 [target.'cfg(unix)'.dependencies]
 libc = "0.2"

+[target.'cfg(windows)'.dependencies]
+windows-sys = { version = "0.52", features = ["Win32_System_Threading", "Win32_Foundation"] }
+
 [profile.release]
 opt-level = 3
 lto = true
@@ -153,9 +153,15 @@ fn daemon_ready(session: &str) -> bool {
    }
 }

-pub fn ensure_daemon(session: &str, headed: bool) -> Result<(), String> {
+/// Result of ensure_daemon indicating whether a new daemon was started
+pub struct DaemonResult {
+    /// True if we connected to an existing daemon, false if we started a new one
+    pub already_running: bool,
+}
+
+pub fn ensure_daemon(session: &str, headed: bool, executable_path: Option<&str>) -> Result<DaemonResult, String> {
    if is_daemon_running(session) && daemon_ready(session) {
-        return Ok(());
+        return Ok(DaemonResult { already_running: true });
    }

    let exe_path = env::current_exe().map_err(|e| e.to_string())?;
@@ -186,6 +192,10 @@ pub fn ensure_daemon(session: &str, headed: bool) -> Result<(), String> {
            cmd.env("AGENT_BROWSER_HEADED", "1");
        }

+        if let Some(path) = executable_path {
+            cmd.env("AGENT_BROWSER_EXECUTABLE_PATH", path);
+        }
+
        // Create new process group and session to fully detach
        unsafe {
            cmd.pre_exec(|| {
@@ -206,8 +216,13 @@ pub fn ensure_daemon(session: &str, headed: bool) -> Result<(), String> {
    {
        use std::os::windows::process::CommandExt;
        
-        let mut cmd = Command::new("node");
-        cmd.arg(daemon_path)
+        // On Windows, use cmd.exe to run node to ensure proper PATH resolution.
+        // This handles cases where node.exe isn't directly in PATH but node.cmd is.
+        // Pass the entire command as a single string to /c to handle paths with spaces.
+        let cmd_string = format!("node \"{}\"", daemon_path.display());
+        let mut cmd = Command::new("cmd");
+        cmd.arg("/c")
+            .arg(&cmd_string)
            .env("AGENT_BROWSER_DAEMON", "1")
            .env("AGENT_BROWSER_SESSION", session);

@@ -215,6 +230,10 @@ pub fn ensure_daemon(session: &str, headed: bool) -> Result<(), String> {
            cmd.env("AGENT_BROWSER_HEADED", "1");
        }

+        if let Some(path) = executable_path {
+            cmd.env("AGENT_BROWSER_EXECUTABLE_PATH", path);
+        }
+
        // CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS
        const CREATE_NEW_PROCESS_GROUP: u32 = 0x00000200;
        const DETACHED_PROCESS: u32 = 0x00000008;
@@ -229,7 +248,7 @@ pub fn ensure_daemon(session: &str, headed: bool) -> Result<(), String> {

    for _ in 0..50 {
        if daemon_ready(session) {
-            return Ok(());
+            return Ok(DaemonResult { already_running: false });
        }
        thread::sleep(Duration::from_millis(100));
    }
@@ -6,6 +6,8 @@ pub struct Flags {
    pub headed: bool,
    pub debug: bool,
    pub session: String,
+    pub headers: Option<String>,
+    pub executable_path: Option<String>,
 }

 pub fn parse_flags(args: &[String]) -> Flags {
@@ -15,6 +17,8 @@ pub fn parse_flags(args: &[String]) -> Flags {
        headed: false,
        debug: false,
        session: env::var("AGENT_BROWSER_SESSION").unwrap_or_else(|_| "default".to_string()),
+        headers: None,
+        executable_path: env::var("AGENT_BROWSER_EXECUTABLE_PATH").ok(),
    };

    let mut i = 0;
@@ -30,6 +34,18 @@ pub fn parse_flags(args: &[String]) -> Flags {
                    i += 1;
                }
            }
+            "--headers" => {
+                if let Some(h) = args.get(i + 1) {
+                    flags.headers = Some(h.clone());
+                    i += 1;
+                }
+            }
+            "--executable-path" => {
+                if let Some(s) = args.get(i + 1) {
+                    flags.executable_path = Some(s.clone());
+                    i += 1;
+                }
+            }
            _ => {}
        }
        i += 1;
@@ -43,13 +59,15 @@ pub fn clean_args(args: &[String]) -> Vec<String> {

    // Global flags that should be stripped from command args
    const GLOBAL_FLAGS: &[&str] = &["--json", "--full", "--headed", "--debug"];
+    // Global flags that take a value (need to skip the next arg too)
+    const GLOBAL_FLAGS_WITH_VALUE: &[&str] = &["--session", "--headers", "--executable-path"];

    for arg in args.iter() {
        if skip_next {
            skip_next = false;
            continue;
        }
-        if arg == "--session" {
+        if GLOBAL_FLAGS_WITH_VALUE.contains(&arg.as_str()) {
            skip_next = true;
            continue;
        }
@@ -61,3 +79,111 @@ pub fn clean_args(args: &[String]) -> Vec<String> {
    }
    result
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn args(s: &str) -> Vec<String> {
+        s.split_whitespace().map(String::from).collect()
+    }
+
+    #[test]
+    fn test_parse_headers_flag() {
+        let flags = parse_flags(&args(r#"open example.com --headers {"Auth":"token"}"#));
+        assert_eq!(flags.headers, Some(r#"{"Auth":"token"}"#.to_string()));
+    }
+
+    #[test]
+    fn test_parse_headers_flag_with_spaces() {
+        // Headers JSON is passed as a single quoted argument in shell
+        let input: Vec<String> = vec![
+            "open".to_string(),
+            "example.com".to_string(),
+            "--headers".to_string(),
+            r#"{"Authorization": "Bearer token"}"#.to_string(),
+        ];
+        let flags = parse_flags(&input);
+        assert_eq!(flags.headers, Some(r#"{"Authorization": "Bearer token"}"#.to_string()));
+    }
+
+    #[test]
+    fn test_parse_no_headers_flag() {
+        let flags = parse_flags(&args("open example.com"));
+        assert!(flags.headers.is_none());
+    }
+
+    #[test]
+    fn test_clean_args_removes_headers() {
+        let input: Vec<String> = vec![
+            "open".to_string(),
+            "example.com".to_string(),
+            "--headers".to_string(),
+            r#"{"Auth":"token"}"#.to_string(),
+        ];
+        let clean = clean_args(&input);
+        assert_eq!(clean, vec!["open", "example.com"]);
+    }
+
+    #[test]
+    fn test_clean_args_removes_headers_at_start() {
+        let input: Vec<String> = vec![
+            "--headers".to_string(),
+            r#"{"Auth":"token"}"#.to_string(),
+            "open".to_string(),
+            "example.com".to_string(),
+        ];
+        let clean = clean_args(&input);
+        assert_eq!(clean, vec!["open", "example.com"]);
+    }
+
+    #[test]
+    fn test_headers_with_other_flags() {
+        let input: Vec<String> = vec![
+            "open".to_string(),
+            "example.com".to_string(),
+            "--headers".to_string(),
+            r#"{"Auth":"token"}"#.to_string(),
+            "--json".to_string(),
+            "--headed".to_string(),
+        ];
+        let flags = parse_flags(&input);
+        assert_eq!(flags.headers, Some(r#"{"Auth":"token"}"#.to_string()));
+        assert!(flags.json);
+        assert!(flags.headed);
+        
+        let clean = clean_args(&input);
+        assert_eq!(clean, vec!["open", "example.com"]);
+    }
+
+    #[test]
+    fn test_parse_executable_path_flag() {
+        let flags = parse_flags(&args("--executable-path /path/to/chromium open example.com"));
+        assert_eq!(flags.executable_path, Some("/path/to/chromium".to_string()));
+    }
+
+    #[test]
+    fn test_parse_executable_path_flag_no_value() {
+        let flags = parse_flags(&args("--executable-path"));
+        assert_eq!(flags.executable_path, None);
+    }
+
+    #[test]
+    fn test_clean_args_removes_executable_path() {
+        let cleaned = clean_args(&args("--executable-path /path/to/chromium open example.com"));
+        assert_eq!(cleaned, vec!["open", "example.com"]);
+    }
+
+    #[test]
+    fn test_clean_args_removes_executable_path_with_other_flags() {
+        let cleaned = clean_args(&args("--json --executable-path /path/to/chromium --headed open example.com"));
+        assert_eq!(cleaned, vec!["open", "example.com"]);
+    }
+
+    #[test]
+    fn test_parse_flags_with_session_and_executable_path() {
+        let flags = parse_flags(&args("--session test --executable-path /custom/chrome open example.com"));
+        assert_eq!(flags.session, "test");
+        assert_eq!(flags.executable_path, Some("/custom/chrome".to_string()));
+    }
+}
@@ -128,6 +128,16 @@ pub fn run_install(with_deps: bool) {
    }

    println!("\x1b[36mInstalling Chromium browser...\x1b[0m");
+    
+    // On Windows, we need to use cmd.exe to run npx because npx is actually npx.cmd
+    // and Command::new() doesn't resolve .cmd files the way the shell does.
+    // Pass the entire command as a single string to /c to handle paths with spaces.
+    #[cfg(windows)]
+    let status = Command::new("cmd")
+        .args(["/c", "npx playwright install chromium"])
+        .status();
+    
+    #[cfg(not(windows))]
    let status = Command::new("npx")
        .args(["playwright", "install", "chromium"])
        .status();
@@ -6,20 +6,111 @@ mod output;

 use serde_json::json;
 use std::env;
+use std::fs;
 use std::process::exit;

-use commands::{gen_id, parse_command};
+#[cfg(unix)]
+use libc;
+
+#[cfg(windows)]
+use windows_sys::Win32::Foundation::CloseHandle;
+#[cfg(windows)]
+use windows_sys::Win32::System::Threading::{OpenProcess, PROCESS_QUERY_LIMITED_INFORMATION};
+
+use commands::{gen_id, parse_command, ParseError};
 use connection::{ensure_daemon, send_command};
 use flags::{clean_args, parse_flags};
 use install::run_install;
-use output::{print_help, print_response};
+use output::{print_command_help, print_help, print_response};
+
+fn run_session(args: &[String], session: &str, json_mode: bool) {
+    let subcommand = args.get(1).map(|s| s.as_str());
+
+    match subcommand {
+        Some("list") => {
+            let tmp = env::temp_dir();
+            let mut sessions: Vec<String> = Vec::new();
+
+            if let Ok(entries) = fs::read_dir(&tmp) {
+                for entry in entries.flatten() {
+                    let name = entry.file_name().to_string_lossy().to_string();
+                    // Look for socket files (Unix) or pid files
+                    if name.starts_with("agent-browser-") && name.ends_with(".pid") {
+                        let session_name = name
+                            .strip_prefix("agent-browser-")
+                            .and_then(|s| s.strip_suffix(".pid"))
+                            .unwrap_or("");
+                        if !session_name.is_empty() {
+                            // Check if session is actually running
+                            let pid_path = tmp.join(&name);
+                            if let Ok(pid_str) = fs::read_to_string(&pid_path) {
+                                if let Ok(pid) = pid_str.trim().parse::<u32>() {
+                                    #[cfg(unix)]
+                                    let running = unsafe { libc::kill(pid as i32, 0) == 0 };
+                                    #[cfg(windows)]
+                                    let running = unsafe {
+                                        let handle = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid);
+                                        if handle != 0 {
+                                            CloseHandle(handle);
+                                            true
+                                        } else {
+                                            false
+                                        }
+                                    };
+                                    if running {
+                                        sessions.push(session_name.to_string());
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+
+            if json_mode {
+                println!(
+                    r#"{{"success":true,"data":{{"sessions":{}}}}}"#,
+                    serde_json::to_string(&sessions).unwrap_or_default()
+                );
+            } else if sessions.is_empty() {
+                println!("No active sessions");
+            } else {
+                println!("Active sessions:");
+                for s in &sessions {
+                    let marker = if s == session { "→" } else { " " };
+                    println!("{} {}", marker, s);
+                }
+            }
+        }
+        None | Some(_) => {
+            // Just show current session
+            if json_mode {
+                println!(r#"{{"success":true,"data":{{"session":"{}"}}}}"#, session);
+            } else {
+                println!("{}", session);
+            }
+        }
+    }
+}

 fn main() {
    let args: Vec<String> = env::args().skip(1).collect();
    let flags = parse_flags(&args);
    let clean = clean_args(&args);

-    if clean.is_empty() || args.iter().any(|a| a == "--help" || a == "-h") {
+    let has_help = args.iter().any(|a| a == "--help" || a == "-h");
+
+    if clean.is_empty() {
+        print_help();
+        return;
+    }
+
+    if has_help {
+        if let Some(cmd) = clean.get(0) {
+            if print_command_help(cmd) {
+                return;
+            }
+        }
        print_help();
        return;
    }
@@ -31,19 +122,36 @@ fn main() {
        return;
    }

+    // Handle session separately (doesn't need daemon)
+    if clean.get(0).map(|s| s.as_str()) == Some("session") {
+        run_session(&clean, &flags.session, flags.json);
+        return;
+    }
+
    let cmd = match parse_command(&clean, &flags) {
-        Some(c) => c,
-        None => {
-            eprintln!(
-                "\x1b[31mUnknown command:\x1b[0m {}",
-                clean.get(0).unwrap_or(&String::new())
+        Ok(c) => c,
+        Err(e) => {
+            if flags.json {
+                let error_type = match &e {
+                    ParseError::UnknownCommand { .. } => "unknown_command",
+                    ParseError::UnknownSubcommand { .. } => "unknown_subcommand",
+                    ParseError::MissingArguments { .. } => "missing_arguments",
+                };
+                println!(
+                    r#"{{"success":false,"error":"{}","type":"{}"}}"#,
+                    e.format().replace('\n', " "),
+                    error_type
                );
-            eprintln!("\x1b[2mRun: agent-browser --help\x1b[0m");
+            } else {
+                eprintln!("\x1b[31m{}\x1b[0m", e.format());
+            }
            exit(1);
        }
    };

-    if let Err(e) = ensure_daemon(&flags.session, flags.headed) {
+    let daemon_result = match ensure_daemon(&flags.session, flags.headed, flags.executable_path.as_deref()) {
+        Ok(result) => result,
+        Err(e) => {
            if flags.json {
                println!(r#"{{"success":false,"error":"{}"}}"#, e);
            } else {
@@ -51,6 +159,14 @@ fn main() {
            }
            exit(1);
        }
+    };
+
+    // Warn if executable_path was specified but daemon was already running
+    if daemon_result.already_running && flags.executable_path.is_some() {
+        if !flags.json {
+            eprintln!("\x1b[33m⚠\x1b[0m --executable-path ignored: daemon already running. Use 'agent-browser close' first to restart with new path.");
+        }
+    }

    // If --headed flag is set, send launch command first to switch to headed mode
    if flags.headed {
@@ -145,6 +145,964 @@ pub fn print_response(resp: &Response, json_mode: bool) {
    }
 }

+/// Print command-specific help. Returns true if help was printed, false if command unknown.
+pub fn print_command_help(command: &str) -> bool {
+    let help = match command {
+        // === Navigation ===
+        "open" | "goto" | "navigate" => r##"
+agent-browser open - Navigate to a URL
+
+Usage: agent-browser open <url>
+
+Navigates the browser to the specified URL. If no protocol is provided,
+https:// is automatically prepended.
+
+Aliases: goto, navigate
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+  --headers <json>     Set HTTP headers (scoped to this origin)
+  --headed             Show browser window
+
+Examples:
+  agent-browser open example.com
+  agent-browser open https://github.com
+  agent-browser open localhost:3000
+  agent-browser open api.example.com --headers '{"Authorization": "Bearer token"}'
+    # ^ Headers only sent to api.example.com, not other domains
+"##,
+        "back" => r##"
+agent-browser back - Navigate back in history
+
+Usage: agent-browser back
+
+Goes back one page in the browser history, equivalent to clicking
+the browser's back button.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser back
+"##,
+        "forward" => r##"
+agent-browser forward - Navigate forward in history
+
+Usage: agent-browser forward
+
+Goes forward one page in the browser history, equivalent to clicking
+the browser's forward button.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser forward
+"##,
+        "reload" => r##"
+agent-browser reload - Reload the current page
+
+Usage: agent-browser reload
+
+Reloads the current page, equivalent to pressing F5 or clicking
+the browser's reload button.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser reload
+"##,
+
+        // === Core Actions ===
+        "click" => r##"
+agent-browser click - Click an element
+
+Usage: agent-browser click <selector>
+
+Clicks on the specified element. The selector can be a CSS selector,
+XPath, or an element reference from snapshot (e.g., @e1).
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser click "#submit-button"
+  agent-browser click @e1
+  agent-browser click "button.primary"
+  agent-browser click "//button[@type='submit']"
+"##,
+        "dblclick" => r##"
+agent-browser dblclick - Double-click an element
+
+Usage: agent-browser dblclick <selector>
+
+Double-clicks on the specified element. Useful for text selection
+or triggering double-click handlers.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser dblclick "#editable-text"
+  agent-browser dblclick @e5
+"##,
+        "fill" => r##"
+agent-browser fill - Clear and fill an input field
+
+Usage: agent-browser fill <selector> <text>
+
+Clears the input field and fills it with the specified text.
+This replaces any existing content in the field.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser fill "#email" "user@example.com"
+  agent-browser fill @e3 "Hello World"
+  agent-browser fill "input[name='search']" "query"
+"##,
+        "type" => r##"
+agent-browser type - Type text into an element
+
+Usage: agent-browser type <selector> <text>
+
+Types text into the specified element character by character.
+Unlike fill, this does not clear existing content first.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser type "#search" "hello"
+  agent-browser type @e2 "additional text"
+"##,
+        "hover" => r##"
+agent-browser hover - Hover over an element
+
+Usage: agent-browser hover <selector>
+
+Moves the mouse to hover over the specified element. Useful for
+triggering hover states or dropdown menus.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser hover "#dropdown-trigger"
+  agent-browser hover @e4
+"##,
+        "focus" => r##"
+agent-browser focus - Focus an element
+
+Usage: agent-browser focus <selector>
+
+Sets keyboard focus to the specified element.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser focus "#input-field"
+  agent-browser focus @e2
+"##,
+        "check" => r##"
+agent-browser check - Check a checkbox
+
+Usage: agent-browser check <selector>
+
+Checks a checkbox element. If already checked, no action is taken.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser check "#terms-checkbox"
+  agent-browser check @e7
+"##,
+        "uncheck" => r##"
+agent-browser uncheck - Uncheck a checkbox
+
+Usage: agent-browser uncheck <selector>
+
+Unchecks a checkbox element. If already unchecked, no action is taken.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser uncheck "#newsletter-opt-in"
+  agent-browser uncheck @e8
+"##,
+        "select" => r##"
+agent-browser select - Select a dropdown option
+
+Usage: agent-browser select <selector> <value>
+
+Selects an option in a <select> dropdown by its value attribute.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser select "#country" "US"
+  agent-browser select @e5 "option2"
+"##,
+        "drag" => r##"
+agent-browser drag - Drag and drop
+
+Usage: agent-browser drag <source> <target>
+
+Drags an element from source to target location.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser drag "#draggable" "#drop-zone"
+  agent-browser drag @e1 @e2
+"##,
+        "upload" => r##"
+agent-browser upload - Upload files
+
+Usage: agent-browser upload <selector> <files...>
+
+Uploads one or more files to a file input element.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser upload "#file-input" ./document.pdf
+  agent-browser upload @e3 ./image1.png ./image2.png
+"##,
+
+        // === Keyboard ===
+        "press" | "key" => r##"
+agent-browser press - Press a key or key combination
+
+Usage: agent-browser press <key>
+
+Presses a key or key combination. Supports special keys and modifiers.
+
+Aliases: key
+
+Special Keys:
+  Enter, Tab, Escape, Backspace, Delete, Space
+  ArrowUp, ArrowDown, ArrowLeft, ArrowRight
+  Home, End, PageUp, PageDown
+  F1-F12
+
+Modifiers (combine with +):
+  Control, Alt, Shift, Meta
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser press Enter
+  agent-browser press Tab
+  agent-browser press Control+a
+  agent-browser press Control+Shift+s
+  agent-browser press Escape
+"##,
+        "keydown" => r##"
+agent-browser keydown - Press a key down (without release)
+
+Usage: agent-browser keydown <key>
+
+Presses a key down without releasing it. Use keyup to release.
+Useful for holding modifier keys.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser keydown Shift
+  agent-browser keydown Control
+"##,
+        "keyup" => r##"
+agent-browser keyup - Release a key
+
+Usage: agent-browser keyup <key>
+
+Releases a key that was pressed with keydown.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser keyup Shift
+  agent-browser keyup Control
+"##,
+
+        // === Scroll ===
+        "scroll" => r##"
+agent-browser scroll - Scroll the page
+
+Usage: agent-browser scroll [direction] [amount]
+
+Scrolls the page in the specified direction.
+
+Arguments:
+  direction            up, down, left, right (default: down)
+  amount               Pixels to scroll (default: 300)
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser scroll
+  agent-browser scroll down 500
+  agent-browser scroll up 200
+  agent-browser scroll left 100
+"##,
+        "scrollintoview" | "scrollinto" => r##"
+agent-browser scrollintoview - Scroll element into view
+
+Usage: agent-browser scrollintoview <selector>
+
+Scrolls the page until the specified element is visible in the viewport.
+
+Aliases: scrollinto
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser scrollintoview "#footer"
+  agent-browser scrollintoview @e15
+"##,
+
+        // === Wait ===
+        "wait" => r##"
+agent-browser wait - Wait for condition
+
+Usage: agent-browser wait <selector|ms|option>
+
+Waits for an element to appear, a timeout, or other conditions.
+
+Modes:
+  <selector>           Wait for element to appear
+  <ms>                 Wait for specified milliseconds
+  --url <pattern>      Wait for URL to match pattern
+  --load <state>       Wait for load state (load, domcontentloaded, networkidle)
+  --fn <expression>    Wait for JavaScript expression to be truthy
+  --text <text>        Wait for text to appear on page
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser wait "#loading-spinner"
+  agent-browser wait 2000
+  agent-browser wait --url "**/dashboard"
+  agent-browser wait --load networkidle
+  agent-browser wait --fn "window.appReady === true"
+  agent-browser wait --text "Welcome back"
+"##,
+
+        // === Screenshot/PDF ===
+        "screenshot" => r##"
+agent-browser screenshot - Take a screenshot
+
+Usage: agent-browser screenshot [path]
+
+Captures a screenshot of the current page. If no path is provided,
+outputs base64-encoded image data.
+
+Options:
+  --full, -f           Capture full page (not just viewport)
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser screenshot
+  agent-browser screenshot ./screenshot.png
+  agent-browser screenshot --full ./full-page.png
+"##,
+        "pdf" => r##"
+agent-browser pdf - Save page as PDF
+
+Usage: agent-browser pdf <path>
+
+Saves the current page as a PDF file.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser pdf ./page.pdf
+  agent-browser pdf ~/Documents/report.pdf
+"##,
+
+        // === Snapshot ===
+        "snapshot" => r##"
+agent-browser snapshot - Get accessibility tree snapshot
+
+Usage: agent-browser snapshot [options]
+
+Returns an accessibility tree representation of the page with element
+references (like @e1, @e2) that can be used in subsequent commands.
+Designed for AI agents to understand page structure.
+
+Options:
+  -i, --interactive    Only include interactive elements
+  -c, --compact        Remove empty structural elements
+  -d, --depth <n>      Limit tree depth
+  -s, --selector <sel> Scope snapshot to CSS selector
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser snapshot
+  agent-browser snapshot -i
+  agent-browser snapshot --compact --depth 5
+  agent-browser snapshot -s "#main-content"
+"##,
+
+        // === Eval ===
+        "eval" => r##"
+agent-browser eval - Execute JavaScript
+
+Usage: agent-browser eval <script>
+
+Executes JavaScript code in the browser context and returns the result.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser eval "document.title"
+  agent-browser eval "window.location.href"
+  agent-browser eval "document.querySelectorAll('a').length"
+"##,
+
+        // === Close ===
+        "close" | "quit" | "exit" => r##"
+agent-browser close - Close the browser
+
+Usage: agent-browser close
+
+Closes the browser instance for the current session.
+
+Aliases: quit, exit
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser close
+  agent-browser close --session mysession
+"##,
+
+        // === Get ===
+        "get" => r##"
+agent-browser get - Retrieve information from elements or page
+
+Usage: agent-browser get <subcommand> [args]
+
+Retrieves various types of information from elements or the page.
+
+Subcommands:
+  text <selector>            Get text content of element
+  html <selector>            Get inner HTML of element
+  value <selector>           Get value of input element
+  attr <selector> <name>     Get attribute value
+  title                      Get page title
+  url                        Get current URL
+  count <selector>           Count matching elements
+  box <selector>             Get bounding box (x, y, width, height)
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser get text @e1
+  agent-browser get html "#content"
+  agent-browser get value "#email-input"
+  agent-browser get attr "#link" href
+  agent-browser get title
+  agent-browser get url
+  agent-browser get count "li.item"
+  agent-browser get box "#header"
+"##,
+
+        // === Is ===
+        "is" => r##"
+agent-browser is - Check element state
+
+Usage: agent-browser is <subcommand> <selector>
+
+Checks the state of an element and returns true/false.
+
+Subcommands:
+  visible <selector>   Check if element is visible
+  enabled <selector>   Check if element is enabled (not disabled)
+  checked <selector>   Check if checkbox/radio is checked
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser is visible "#modal"
+  agent-browser is enabled "#submit-btn"
+  agent-browser is checked "#agree-checkbox"
+"##,
+
+        // === Find ===
+        "find" => r##"
+agent-browser find - Find and interact with elements by locator
+
+Usage: agent-browser find <locator> <value> [action] [text]
+
+Finds elements using semantic locators and optionally performs an action.
+
+Locators:
+  role <role>              Find by ARIA role (--name <n>, --exact)
+  text <text>              Find by text content (--exact)
+  label <label>            Find by associated label (--exact)
+  placeholder <text>       Find by placeholder text (--exact)
+  alt <text>               Find by alt text (--exact)
+  title <text>             Find by title attribute (--exact)
+  testid <id>              Find by data-testid attribute
+  first <selector>         First matching element
+  last <selector>          Last matching element
+  nth <index> <selector>   Nth matching element (0-based)
+
+Actions (default: click):
+  click, fill, type, hover, focus, check, uncheck
+
+Options:
+  --name <name>        Filter role by accessible name
+  --exact              Require exact text match
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser find role button click --name Submit
+  agent-browser find text "Sign In" click
+  agent-browser find label "Email" fill "user@example.com"
+  agent-browser find placeholder "Search..." type "query"
+  agent-browser find testid "login-form" click
+  agent-browser find first "li.item" click
+  agent-browser find nth 2 ".card" hover
+"##,
+
+        // === Mouse ===
+        "mouse" => r##"
+agent-browser mouse - Low-level mouse operations
+
+Usage: agent-browser mouse <subcommand> [args]
+
+Performs low-level mouse operations for precise control.
+
+Subcommands:
+  move <x> <y>         Move mouse to coordinates
+  down [button]        Press mouse button (left, right, middle)
+  up [button]          Release mouse button
+  wheel <dy> [dx]      Scroll mouse wheel
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser mouse move 100 200
+  agent-browser mouse down
+  agent-browser mouse up
+  agent-browser mouse down right
+  agent-browser mouse wheel 100
+  agent-browser mouse wheel -50 0
+"##,
+
+        // === Set ===
+        "set" => r##"
+agent-browser set - Configure browser settings
+
+Usage: agent-browser set <setting> [args]
+
+Configures various browser settings and emulation options.
+
+Settings:
+  viewport <w> <h>           Set viewport size
+  device <name>              Emulate device (e.g., "iPhone 12")
+  geo <lat> <lng>            Set geolocation
+  offline [on|off]           Toggle offline mode
+  headers <json>             Set extra HTTP headers
+  credentials <user> <pass>  Set HTTP authentication
+  media [dark|light]         Set color scheme preference
+        [reduced-motion]     Enable reduced motion
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser set viewport 1920 1080
+  agent-browser set device "iPhone 12"
+  agent-browser set geo 37.7749 -122.4194
+  agent-browser set offline on
+  agent-browser set headers '{"X-Custom": "value"}'
+  agent-browser set credentials admin secret123
+  agent-browser set media dark
+  agent-browser set media light reduced-motion
+"##,
+
+        // === Network ===
+        "network" => r##"
+agent-browser network - Network interception and monitoring
+
+Usage: agent-browser network <subcommand> [args]
+
+Intercept, mock, or monitor network requests.
+
+Subcommands:
+  route <url> [options]      Intercept requests matching URL pattern
+    --abort                  Abort matching requests
+    --body <json>            Respond with custom body
+  unroute [url]              Remove route (all if no URL)
+  requests [options]         List captured requests
+    --clear                  Clear request log
+    --filter <pattern>       Filter by URL pattern
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser network route "**/api/*" --abort
+  agent-browser network route "**/data.json" --body '{"mock": true}'
+  agent-browser network unroute
+  agent-browser network requests
+  agent-browser network requests --filter "api"
+  agent-browser network requests --clear
+"##,
+
+        // === Storage ===
+        "storage" => r##"
+agent-browser storage - Manage web storage
+
+Usage: agent-browser storage <type> [operation] [key] [value]
+
+Manage localStorage and sessionStorage.
+
+Types:
+  local                localStorage
+  session              sessionStorage
+
+Operations:
+  get [key]            Get all storage or specific key
+  set <key> <value>    Set a key-value pair
+  clear                Clear all storage
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser storage local
+  agent-browser storage local get authToken
+  agent-browser storage local set theme "dark"
+  agent-browser storage local clear
+  agent-browser storage session get userId
+"##,
+
+        // === Cookies ===
+        "cookies" => r##"
+agent-browser cookies - Manage browser cookies
+
+Usage: agent-browser cookies [operation] [args]
+
+Manage browser cookies for the current context.
+
+Operations:
+  get                  Get all cookies (default)
+  set <name> <value>   Set a cookie
+  clear                Clear all cookies
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser cookies
+  agent-browser cookies get
+  agent-browser cookies set session_id "abc123"
+  agent-browser cookies clear
+"##,
+
+        // === Tabs ===
+        "tab" => r##"
+agent-browser tab - Manage browser tabs
+
+Usage: agent-browser tab [operation] [args]
+
+Manage browser tabs in the current window.
+
+Operations:
+  list                 List all tabs (default)
+  new [url]            Open new tab
+  close [index]        Close tab (current if no index)
+  <index>              Switch to tab by index
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser tab
+  agent-browser tab list
+  agent-browser tab new
+  agent-browser tab new https://example.com
+  agent-browser tab 2
+  agent-browser tab close
+  agent-browser tab close 1
+"##,
+
+        // === Window ===
+        "window" => r##"
+agent-browser window - Manage browser windows
+
+Usage: agent-browser window <operation>
+
+Manage browser windows.
+
+Operations:
+  new                  Open new browser window
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser window new
+"##,
+
+        // === Frame ===
+        "frame" => r##"
+agent-browser frame - Switch frame context
+
+Usage: agent-browser frame <selector|main>
+
+Switch to an iframe or back to the main frame.
+
+Arguments:
+  <selector>           CSS selector for iframe
+  main                 Switch back to main frame
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser frame "#embed-iframe"
+  agent-browser frame "iframe[name='content']"
+  agent-browser frame main
+"##,
+
+        // === Dialog ===
+        "dialog" => r##"
+agent-browser dialog - Handle browser dialogs
+
+Usage: agent-browser dialog <response> [text]
+
+Respond to browser dialogs (alert, confirm, prompt).
+
+Operations:
+  accept [text]        Accept dialog, optionally with prompt text
+  dismiss              Dismiss/cancel dialog
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser dialog accept
+  agent-browser dialog accept "my input"
+  agent-browser dialog dismiss
+"##,
+
+        // === Trace ===
+        "trace" => r##"
+agent-browser trace - Record execution trace
+
+Usage: agent-browser trace <operation> [path]
+
+Record a trace for debugging with Playwright Trace Viewer.
+
+Operations:
+  start [path]         Start recording trace
+  stop [path]          Stop recording and save trace
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser trace start
+  agent-browser trace start ./my-trace
+  agent-browser trace stop
+  agent-browser trace stop ./debug-trace.zip
+"##,
+
+        // === Console/Errors ===
+        "console" => r##"
+agent-browser console - View console logs
+
+Usage: agent-browser console [--clear]
+
+View browser console output (log, warn, error, info).
+
+Options:
+  --clear              Clear console log buffer
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser console
+  agent-browser console --clear
+"##,
+        "errors" => r##"
+agent-browser errors - View page errors
+
+Usage: agent-browser errors [--clear]
+
+View JavaScript errors and uncaught exceptions.
+
+Options:
+  --clear              Clear error buffer
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser errors
+  agent-browser errors --clear
+"##,
+
+        // === Highlight ===
+        "highlight" => r##"
+agent-browser highlight - Highlight an element
+
+Usage: agent-browser highlight <selector>
+
+Visually highlights an element on the page for debugging.
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser highlight "#target-element"
+  agent-browser highlight @e5
+"##,
+
+        // === State ===
+        "state" => r##"
+agent-browser state - Save/load browser state
+
+Usage: agent-browser state <operation> <path>
+
+Save or restore browser state (cookies, localStorage, sessionStorage).
+
+Operations:
+  save <path>          Save current state to file
+  load <path>          Load state from file
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser state save ./auth-state.json
+  agent-browser state load ./auth-state.json
+"##,
+
+        // === Session ===
+        "session" => r##"
+agent-browser session - Manage sessions
+
+Usage: agent-browser session [operation]
+
+Manage isolated browser sessions. Each session has its own browser
+instance with separate cookies, storage, and state.
+
+Operations:
+  (none)               Show current session name
+  list                 List all active sessions
+
+Environment:
+  AGENT_BROWSER_SESSION    Default session name
+
+Global Options:
+  --json               Output as JSON
+  --session <name>     Use specific session
+
+Examples:
+  agent-browser session
+  agent-browser session list
+  agent-browser --session test open example.com
+"##,
+
+        // === Install ===
+        "install" => r##"
+agent-browser install - Install browser binaries
+
+Usage: agent-browser install [--with-deps]
+
+Downloads and installs browser binaries required for automation.
+
+Options:
+  -d, --with-deps      Also install system dependencies (Linux only)
+
+Examples:
+  agent-browser install
+  agent-browser install --with-deps
+"##,
+
+        _ => return false,
+    };
+    println!("{}", help.trim());
+    true
+}
+
 pub fn print_help() {
    println!(
        r#"
@@ -215,6 +1173,10 @@ Debug:
  errors [--clear]           View page errors
  highlight <sel>            Highlight element

+Sessions:
+  session                    Show current session name
+  session list               List active sessions
+
 Setup:
  install                    Install browser binaries
  install --with-deps        Also install system dependencies (Linux)
@@ -227,6 +1189,8 @@ Snapshot Options:

 Options:
  --session <name>           Isolated session (or AGENT_BROWSER_SESSION env)
+  --headers <json>           HTTP headers scoped to URL's origin (for auth)
+  --executable-path <path>   Custom browser executable (or AGENT_BROWSER_EXECUTABLE_PATH)
  --json                     JSON output
  --full, -f                 Full page screenshot
  --headed                   Show browser window (not headless)
@@ -1,25 +1,30 @@
 {
  "name": "agent-browser",
-  "version": "0.4.0",
+  "version": "0.4.3",
  "description": "Headless browser automation CLI for AI agents",
  "type": "module",
  "main": "dist/daemon.js",
  "files": [
    "dist",
    "bin",
-    "scripts"
+    "scripts",
+    "skills"
  ],
  "bin": {
    "agent-browser": "./bin/agent-browser"
  },
  "scripts": {
+    "prepare": "husky",
+    "version:sync": "node scripts/sync-version.js",
+    "version": "npm run version:sync && git add cli/Cargo.toml",
    "build": "tsc",
-    "build:native": "cargo build --release --manifest-path cli/Cargo.toml && node scripts/copy-native.js",
-    "build:linux": "docker compose -f docker/docker-compose.yml run --rm build-linux",
-    "build:macos": "(cargo build --release --manifest-path cli/Cargo.toml --target aarch64-apple-darwin & cargo build --release --manifest-path cli/Cargo.toml --target x86_64-apple-darwin & wait) && cp cli/target/aarch64-apple-darwin/release/agent-browser bin/agent-browser-darwin-arm64 && cp cli/target/x86_64-apple-darwin/release/agent-browser bin/agent-browser-darwin-x64",
-    "build:windows": "docker compose -f docker/docker-compose.yml run --rm build-windows",
-    "build:all-platforms": "(npm run build:linux & npm run build:windows & wait) && npm run build:macos",
+    "build:native": "npm run version:sync && cargo build --release --manifest-path cli/Cargo.toml && node scripts/copy-native.js",
+    "build:linux": "npm run version:sync && docker compose -f docker/docker-compose.yml run --rm build-linux",
+    "build:macos": "npm run version:sync && (cargo build --release --manifest-path cli/Cargo.toml --target aarch64-apple-darwin & cargo build --release --manifest-path cli/Cargo.toml --target x86_64-apple-darwin & wait) && cp cli/target/aarch64-apple-darwin/release/agent-browser bin/agent-browser-darwin-arm64 && cp cli/target/x86_64-apple-darwin/release/agent-browser bin/agent-browser-darwin-x64",
+    "build:windows": "npm run version:sync && docker compose -f docker/docker-compose.yml run --rm build-windows",
+    "build:all-platforms": "npm run version:sync && (npm run build:linux & npm run build:windows & wait) && npm run build:macos",
    "build:docker": "docker build -t agent-browser-builder -f docker/Dockerfile.build .",
+    "release": "npm run version:sync && npm run build && npm run build:all-platforms && npm publish",
    "start": "node dist/daemon.js",
    "dev": "tsx src/daemon.ts",
    "typecheck": "tsc --noEmit",
@@ -52,10 +57,15 @@
  },
  "devDependencies": {
    "@types/node": "^20.10.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.2.11",
    "playwright": "^1.57.0",
    "prettier": "^3.7.4",
    "tsx": "^4.6.0",
    "typescript": "^5.3.0",
    "vitest": "^4.0.16"
+  },
+  "lint-staged": {
+    "src/**/*.ts": "prettier --write"
  }
 }
@@ -18,6 +18,12 @@ importers:
      '@types/node':
        specifier: ^20.10.0
        version: 20.19.28
+      husky:
+        specifier: ^9.1.7
+        version: 9.1.7
+      lint-staged:
+        specifier: ^15.2.11
+        version: 15.5.2
      playwright:
        specifier: ^1.57.0
        version: 1.57.0
@@ -32,7 +38,7 @@ importers:
        version: 5.9.3
      vitest:
        specifier: ^4.0.16
-        version: 4.0.16(@types/node@20.19.28)(tsx@4.21.0)
+        version: 4.0.16(@types/node@20.19.28)(tsx@4.21.0)(yaml@2.8.2)

 packages:

@@ -364,14 +370,69 @@ packages:
  '@vitest/utils@4.0.16':
    resolution: {integrity: sha512-h8z9yYhV3e1LEfaQ3zdypIrnAg/9hguReGZoS7Gl0aBG5xgA410zBqECqmaF/+RkTggRsfnzc1XaAHA6bmUufA==}

+  ansi-escapes@7.2.0:
+    resolution: {integrity: sha512-g6LhBsl+GBPRWGWsBtutpzBYuIIdBkLEvad5C/va/74Db018+5TZiyA26cZJAr3Rft5lprVqOIPxf5Vid6tqAw==}
+    engines: {node: '>=18'}
+
+  ansi-regex@6.2.2:
+    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
+    engines: {node: '>=12'}
+
+  ansi-styles@6.2.3:
+    resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
+    engines: {node: '>=12'}
+
  assertion-error@2.0.1:
    resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
    engines: {node: '>=12'}

+  braces@3.0.3:
+    resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
+    engines: {node: '>=8'}
+
  chai@6.2.2:
    resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
    engines: {node: '>=18'}

+  chalk@5.6.2:
+    resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
+    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
+  cli-cursor@5.0.0:
+    resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
+    engines: {node: '>=18'}
+
+  cli-truncate@4.0.0:
+    resolution: {integrity: sha512-nPdaFdQ0h/GEigbPClz11D0v/ZJEwxmeVZGeMo3Z5StPtUTkA9o1lD6QwoirYiSDzbcwn2XcjwmCp68W1IS4TA==}
+    engines: {node: '>=18'}
+
+  colorette@2.0.20:
+    resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==}
+
+  commander@13.1.0:
+    resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
+    engines: {node: '>=18'}
+
+  cross-spawn@7.0.6:
+    resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
+    engines: {node: '>= 8'}
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  emoji-regex@10.6.0:
+    resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==}
+
+  environment@1.1.0:
+    resolution: {integrity: sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==}
+    engines: {node: '>=18'}
+
  es-module-lexer@1.7.0:
    resolution: {integrity: sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==}

@@ -383,6 +444,13 @@ packages:
  estree-walker@3.0.3:
    resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}

+  eventemitter3@5.0.1:
+    resolution: {integrity: sha512-GWkBvjiSZK87ELrYOSESUYeVIc9mvLLf/nXalMOS5dYrgZq9o5OVkbZAVM06CVxYsCwH9BDZFPlQTlPA1j4ahA==}
+
+  execa@8.0.1:
+    resolution: {integrity: sha512-VyhnebXciFV2DESc+p6B+y0LjSm0krU4OgJN44qFAhBY0TJ+1V61tYD2+wHusZ6F9n5K+vl8k0sTy7PEfV4qpg==}
+    engines: {node: '>=16.17'}
+
  expect-type@1.3.0:
    resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==}
    engines: {node: '>=12.0.0'}
@@ -396,6 +464,10 @@ packages:
      picomatch:
        optional: true

+  fill-range@7.1.1:
+    resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==}
+    engines: {node: '>=8'}
+
  fsevents@2.3.2:
    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -406,30 +478,130 @@ packages:
    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
    os: [darwin]

+  get-east-asian-width@1.4.0:
+    resolution: {integrity: sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q==}
+    engines: {node: '>=18'}
+
+  get-stream@8.0.1:
+    resolution: {integrity: sha512-VaUJspBffn/LMCJVoMvSAdmscJyS1auj5Zulnn5UoYcY531UWmdwhRWkcGKnGU93m5HSXP9LP2usOryrBtQowA==}
+    engines: {node: '>=16'}
+
  get-tsconfig@4.13.0:
    resolution: {integrity: sha512-1VKTZJCwBrvbd+Wn3AOgQP/2Av+TfTCOlE4AcRJE72W1ksZXbAx8PPBR9RzgTeSPzlPMHrbANMH3LbltH73wxQ==}

+  human-signals@5.0.0:
+    resolution: {integrity: sha512-AXcZb6vzzrFAUE61HnN4mpLqd/cSIwNQjtNWR0euPm6y0iqx3G4gOXaIDdtdDwZmhwe82LA6+zinmW4UBWVePQ==}
+    engines: {node: '>=16.17.0'}
+
+  husky@9.1.7:
+    resolution: {integrity: sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  is-fullwidth-code-point@4.0.0:
+    resolution: {integrity: sha512-O4L094N2/dZ7xqVdrXhh9r1KODPJpFms8B5sGdJLPy664AgvXsreZUyCQQNItZRDlYug4xStLjNp/sz3HvBowQ==}
+    engines: {node: '>=12'}
+
+  is-fullwidth-code-point@5.1.0:
+    resolution: {integrity: sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==}
+    engines: {node: '>=18'}
+
+  is-number@7.0.0:
+    resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==}
+    engines: {node: '>=0.12.0'}
+
+  is-stream@3.0.0:
+    resolution: {integrity: sha512-LnQR4bZ9IADDRSkvpqMGvt/tEJWclzklNgSw48V5EAaAeDd6qGvN8ei6k5p0tvxSR171VmGyHuTiAOfxAbr8kA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  isexe@2.0.0:
+    resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
+
+  lilconfig@3.1.3:
+    resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==}
+    engines: {node: '>=14'}
+
+  lint-staged@15.5.2:
+    resolution: {integrity: sha512-YUSOLq9VeRNAo/CTaVmhGDKG+LBtA8KF1X4K5+ykMSwWST1vDxJRB2kv2COgLb1fvpCo+A/y9A0G0znNVmdx4w==}
+    engines: {node: '>=18.12.0'}
+    hasBin: true
+
+  listr2@8.3.3:
+    resolution: {integrity: sha512-LWzX2KsqcB1wqQ4AHgYb4RsDXauQiqhjLk+6hjbaeHG4zpjjVAB6wC/gz6X0l+Du1cN3pUB5ZlrvTbhGSNnUQQ==}
+    engines: {node: '>=18.0.0'}
+
+  log-update@6.1.0:
+    resolution: {integrity: sha512-9ie8ItPR6tjY5uYJh8K/Zrv/RMZ5VOlOWvtZdEHYSTFKZfIBPQa9tOAEeAWhd+AnIneLJ22w5fjOYtoutpWq5w==}
+    engines: {node: '>=18'}
+
  magic-string@0.30.21:
    resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}

+  merge-stream@2.0.0:
+    resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==}
+
+  micromatch@4.0.8:
+    resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
+    engines: {node: '>=8.6'}
+
+  mimic-fn@4.0.0:
+    resolution: {integrity: sha512-vqiC06CuhBTUdZH+RYl8sFrL096vA45Ok5ISO6sE/Mr1jRbGH4Csnhi8f3wKVl7x8mO4Au7Ir9D3Oyv1VYMFJw==}
+    engines: {node: '>=12'}
+
+  mimic-function@5.0.1:
+    resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
+    engines: {node: '>=18'}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
  nanoid@3.3.11:
    resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==}
    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
    hasBin: true

+  npm-run-path@5.3.0:
+    resolution: {integrity: sha512-ppwTtiJZq0O/ai0z7yfudtBpWIoxM8yE6nHi1X47eFR2EWORqfbu6CnPlNsjeN683eT0qG6H/Pyf9fCcvjnnnQ==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
  obug@2.1.1:
    resolution: {integrity: sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==}

+  onetime@6.0.0:
+    resolution: {integrity: sha512-1FlR+gjXK7X+AsAHso35MnyN5KqGwJRi/31ft6x0M194ht7S+rWAvd7PHss9xSKMzE0asv1pyIHaJYq+BbacAQ==}
+    engines: {node: '>=12'}
+
+  onetime@7.0.0:
+    resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
+    engines: {node: '>=18'}
+
+  path-key@3.1.1:
+    resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
+    engines: {node: '>=8'}
+
+  path-key@4.0.0:
+    resolution: {integrity: sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==}
+    engines: {node: '>=12'}
+
  pathe@2.0.3:
    resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}

  picocolors@1.1.1:
    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}

+  picomatch@2.3.1:
+    resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==}
+    engines: {node: '>=8.6'}
+
  picomatch@4.0.3:
    resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==}
    engines: {node: '>=12'}

+  pidtree@0.6.0:
+    resolution: {integrity: sha512-eG2dWTVw5bzqGRztnHExczNxt5VGsE6OwTeCG3fdUf9KBsZzO3R5OIIIzWR+iZA0NtZ+RDVdaoE2dK1cn6jH4g==}
+    engines: {node: '>=0.10'}
+    hasBin: true
+
  playwright-core@1.57.0:
    resolution: {integrity: sha512-agTcKlMw/mjBWOnD6kFZttAAGHgi/Nw0CZ2o6JqWSbMlI219lAFLZZCyqByTsvVAJq5XA5H8cA6PrvBRpBWEuQ==}
    engines: {node: '>=18'}
@@ -452,14 +624,41 @@ packages:
  resolve-pkg-maps@1.0.0:
    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}

+  restore-cursor@5.1.0:
+    resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
+    engines: {node: '>=18'}
+
+  rfdc@1.4.1:
+    resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==}
+
  rollup@4.55.1:
    resolution: {integrity: sha512-wDv/Ht1BNHB4upNbK74s9usvl7hObDnvVzknxqY/E/O3X6rW1U1rV1aENEfJ54eFZDTNo7zv1f5N4edCluH7+A==}
    engines: {node: '>=18.0.0', npm: '>=8.0.0'}
    hasBin: true

+  shebang-command@2.0.0:
+    resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
+    engines: {node: '>=8'}
+
+  shebang-regex@3.0.0:
+    resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
+    engines: {node: '>=8'}
+
  siginfo@2.0.0:
    resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}

+  signal-exit@4.1.0:
+    resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
+    engines: {node: '>=14'}
+
+  slice-ansi@5.0.0:
+    resolution: {integrity: sha512-FC+lgizVPfie0kkhqUScwRu1O/lF6NOgJmlCgK+/LYxDCTk8sGelYaHDhFcDN+Sn3Cv+3VSa4Byeo+IMCzpMgQ==}
+    engines: {node: '>=12'}
+
+  slice-ansi@7.1.2:
+    resolution: {integrity: sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w==}
+    engines: {node: '>=18'}
+
  source-map-js@1.2.1:
    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
    engines: {node: '>=0.10.0'}
@@ -470,6 +669,22 @@ packages:
  std-env@3.10.0:
    resolution: {integrity: sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==}

+  string-argv@0.3.2:
+    resolution: {integrity: sha512-aqD2Q0144Z+/RqG52NeHEkZauTAUWJO8c6yTftGJKO3Tja5tUgIfmIl6kExvhtxSDP7fXB6DvzkfMpCd/F3G+Q==}
+    engines: {node: '>=0.6.19'}
+
+  string-width@7.2.0:
+    resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==}
+    engines: {node: '>=18'}
+
+  strip-ansi@7.1.2:
+    resolution: {integrity: sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==}
+    engines: {node: '>=12'}
+
+  strip-final-newline@3.0.0:
+    resolution: {integrity: sha512-dOESqjYr96iWYylGObzd39EuNTa5VJxyvVAEm5Jnh7KGo75V43Hk1odPQkNDyXNmUR6k+gEiDVXnjB8HJ3crXw==}
+    engines: {node: '>=12'}
+
  tinybench@2.9.0:
    resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}

@@ -485,6 +700,10 @@ packages:
    resolution: {integrity: sha512-PSkbLUoxOFRzJYjjxHJt9xro7D+iilgMX/C9lawzVuYiIdcihh9DXmVibBe8lmcFrRi/VzlPjBxbN7rH24q8/Q==}
    engines: {node: '>=14.0.0'}

+  to-regex-range@5.0.1:
+    resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==}
+    engines: {node: '>=8.0'}
+
  tsx@4.21.0:
    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
    engines: {node: '>=18.0.0'}
@@ -572,11 +791,25 @@ packages:
      jsdom:
        optional: true

+  which@2.0.2:
+    resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
+    engines: {node: '>= 8'}
+    hasBin: true
+
  why-is-node-running@2.3.0:
    resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==}
    engines: {node: '>=8'}
    hasBin: true

+  wrap-ansi@9.0.2:
+    resolution: {integrity: sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==}
+    engines: {node: '>=18'}
+
+  yaml@2.8.2:
+    resolution: {integrity: sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
  zod@3.25.76:
    resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}

@@ -761,13 +994,13 @@ snapshots:
      chai: 6.2.2
      tinyrainbow: 3.0.3

-  '@vitest/mocker@4.0.16(vite@7.3.1(@types/node@20.19.28)(tsx@4.21.0))':
+  '@vitest/mocker@4.0.16(vite@7.3.1(@types/node@20.19.28)(tsx@4.21.0)(yaml@2.8.2))':
    dependencies:
      '@vitest/spy': 4.0.16
      estree-walker: 3.0.3
      magic-string: 0.30.21
    optionalDependencies:
-      vite: 7.3.1(@types/node@20.19.28)(tsx@4.21.0)
+      vite: 7.3.1(@types/node@20.19.28)(tsx@4.21.0)(yaml@2.8.2)

  '@vitest/pretty-format@4.0.16':
    dependencies:
@@ -791,10 +1024,51 @@ snapshots:
      '@vitest/pretty-format': 4.0.16
      tinyrainbow: 3.0.3

+  ansi-escapes@7.2.0:
+    dependencies:
+      environment: 1.1.0
+
+  ansi-regex@6.2.2: {}
+
+  ansi-styles@6.2.3: {}
+
  assertion-error@2.0.1: {}

+  braces@3.0.3:
+    dependencies:
+      fill-range: 7.1.1
+
  chai@6.2.2: {}

+  chalk@5.6.2: {}
+
+  cli-cursor@5.0.0:
+    dependencies:
+      restore-cursor: 5.1.0
+
+  cli-truncate@4.0.0:
+    dependencies:
+      slice-ansi: 5.0.0
+      string-width: 7.2.0
+
+  colorette@2.0.20: {}
+
+  commander@13.1.0: {}
+
+  cross-spawn@7.0.6:
+    dependencies:
+      path-key: 3.1.1
+      shebang-command: 2.0.0
+      which: 2.0.2
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  emoji-regex@10.6.0: {}
+
+  environment@1.1.0: {}
+
  es-module-lexer@1.7.0: {}

  esbuild@0.27.2:
@@ -830,36 +1104,141 @@ snapshots:
    dependencies:
      '@types/estree': 1.0.8

+  eventemitter3@5.0.1: {}
+
+  execa@8.0.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      get-stream: 8.0.1
+      human-signals: 5.0.0
+      is-stream: 3.0.0
+      merge-stream: 2.0.0
+      npm-run-path: 5.3.0
+      onetime: 6.0.0
+      signal-exit: 4.1.0
+      strip-final-newline: 3.0.0
+
  expect-type@1.3.0: {}

  fdir@6.5.0(picomatch@4.0.3):
    optionalDependencies:
      picomatch: 4.0.3

+  fill-range@7.1.1:
+    dependencies:
+      to-regex-range: 5.0.1
+
  fsevents@2.3.2:
    optional: true

  fsevents@2.3.3:
    optional: true

+  get-east-asian-width@1.4.0: {}
+
+  get-stream@8.0.1: {}
+
  get-tsconfig@4.13.0:
    dependencies:
      resolve-pkg-maps: 1.0.0

+  human-signals@5.0.0: {}
+
+  husky@9.1.7: {}
+
+  is-fullwidth-code-point@4.0.0: {}
+
+  is-fullwidth-code-point@5.1.0:
+    dependencies:
+      get-east-asian-width: 1.4.0
+
+  is-number@7.0.0: {}
+
+  is-stream@3.0.0: {}
+
+  isexe@2.0.0: {}
+
+  lilconfig@3.1.3: {}
+
+  lint-staged@15.5.2:
+    dependencies:
+      chalk: 5.6.2
+      commander: 13.1.0
+      debug: 4.4.3
+      execa: 8.0.1
+      lilconfig: 3.1.3
+      listr2: 8.3.3
+      micromatch: 4.0.8
+      pidtree: 0.6.0
+      string-argv: 0.3.2
+      yaml: 2.8.2
+    transitivePeerDependencies:
+      - supports-color
+
+  listr2@8.3.3:
+    dependencies:
+      cli-truncate: 4.0.0
+      colorette: 2.0.20
+      eventemitter3: 5.0.1
+      log-update: 6.1.0
+      rfdc: 1.4.1
+      wrap-ansi: 9.0.2
+
+  log-update@6.1.0:
+    dependencies:
+      ansi-escapes: 7.2.0
+      cli-cursor: 5.0.0
+      slice-ansi: 7.1.2
+      strip-ansi: 7.1.2
+      wrap-ansi: 9.0.2
+
  magic-string@0.30.21:
    dependencies:
      '@jridgewell/sourcemap-codec': 1.5.5

+  merge-stream@2.0.0: {}
+
+  micromatch@4.0.8:
+    dependencies:
+      braces: 3.0.3
+      picomatch: 2.3.1
+
+  mimic-fn@4.0.0: {}
+
+  mimic-function@5.0.1: {}
+
+  ms@2.1.3: {}
+
  nanoid@3.3.11: {}

+  npm-run-path@5.3.0:
+    dependencies:
+      path-key: 4.0.0
+
  obug@2.1.1: {}

+  onetime@6.0.0:
+    dependencies:
+      mimic-fn: 4.0.0
+
+  onetime@7.0.0:
+    dependencies:
+      mimic-function: 5.0.1
+
+  path-key@3.1.1: {}
+
+  path-key@4.0.0: {}
+
  pathe@2.0.3: {}

  picocolors@1.1.1: {}

+  picomatch@2.3.1: {}
+
  picomatch@4.0.3: {}

+  pidtree@0.6.0: {}
+
  playwright-core@1.57.0: {}

  playwright@1.57.0:
@@ -878,6 +1257,13 @@ snapshots:

  resolve-pkg-maps@1.0.0: {}

+  restore-cursor@5.1.0:
+    dependencies:
+      onetime: 7.0.0
+      signal-exit: 4.1.0
+
+  rfdc@1.4.1: {}
+
  rollup@4.55.1:
    dependencies:
      '@types/estree': 1.0.8
@@ -909,14 +1295,46 @@ snapshots:
      '@rollup/rollup-win32-x64-msvc': 4.55.1
      fsevents: 2.3.3

+  shebang-command@2.0.0:
+    dependencies:
+      shebang-regex: 3.0.0
+
+  shebang-regex@3.0.0: {}
+
  siginfo@2.0.0: {}

+  signal-exit@4.1.0: {}
+
+  slice-ansi@5.0.0:
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 4.0.0
+
+  slice-ansi@7.1.2:
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
  source-map-js@1.2.1: {}

  stackback@0.0.2: {}

  std-env@3.10.0: {}

+  string-argv@0.3.2: {}
+
+  string-width@7.2.0:
+    dependencies:
+      emoji-regex: 10.6.0
+      get-east-asian-width: 1.4.0
+      strip-ansi: 7.1.2
+
+  strip-ansi@7.1.2:
+    dependencies:
+      ansi-regex: 6.2.2
+
+  strip-final-newline@3.0.0: {}
+
  tinybench@2.9.0: {}

  tinyexec@1.0.2: {}
@@ -928,6 +1346,10 @@ snapshots:

  tinyrainbow@3.0.3: {}

+  to-regex-range@5.0.1:
+    dependencies:
+      is-number: 7.0.0
+
  tsx@4.21.0:
    dependencies:
      esbuild: 0.27.2
@@ -939,7 +1361,7 @@ snapshots:

  undici-types@6.21.0: {}

-  vite@7.3.1(@types/node@20.19.28)(tsx@4.21.0):
+  vite@7.3.1(@types/node@20.19.28)(tsx@4.21.0)(yaml@2.8.2):
    dependencies:
      esbuild: 0.27.2
      fdir: 6.5.0(picomatch@4.0.3)
@@ -951,11 +1373,12 @@ snapshots:
      '@types/node': 20.19.28
      fsevents: 2.3.3
      tsx: 4.21.0
+      yaml: 2.8.2

-  vitest@4.0.16(@types/node@20.19.28)(tsx@4.21.0):
+  vitest@4.0.16(@types/node@20.19.28)(tsx@4.21.0)(yaml@2.8.2):
    dependencies:
      '@vitest/expect': 4.0.16
-      '@vitest/mocker': 4.0.16(vite@7.3.1(@types/node@20.19.28)(tsx@4.21.0))
+      '@vitest/mocker': 4.0.16(vite@7.3.1(@types/node@20.19.28)(tsx@4.21.0)(yaml@2.8.2))
      '@vitest/pretty-format': 4.0.16
      '@vitest/runner': 4.0.16
      '@vitest/snapshot': 4.0.16
@@ -972,7 +1395,7 @@ snapshots:
      tinyexec: 1.0.2
      tinyglobby: 0.2.15
      tinyrainbow: 3.0.3
-      vite: 7.3.1(@types/node@20.19.28)(tsx@4.21.0)
+      vite: 7.3.1(@types/node@20.19.28)(tsx@4.21.0)(yaml@2.8.2)
      why-is-node-running: 2.3.0
    optionalDependencies:
      '@types/node': 20.19.28
@@ -989,9 +1412,21 @@ snapshots:
      - tsx
      - yaml

+  which@2.0.2:
+    dependencies:
+      isexe: 2.0.0
+
  why-is-node-running@2.3.0:
    dependencies:
      siginfo: 2.0.0
      stackback: 0.0.2

+  wrap-ansi@9.0.2:
+    dependencies:
+      ansi-styles: 6.2.3
+      string-width: 7.2.0
+      strip-ansi: 7.1.2
+
+  yaml@2.8.2: {}
+
  zod@3.25.76: {}
@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+/**
+ * Syncs the version from package.json to all other config files.
+ * Run this script before building or releasing.
+ */
+
+import { readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, "..");
+
+// Read version from package.json (single source of truth)
+const packageJson = JSON.parse(
+  readFileSync(join(rootDir, "package.json"), "utf-8")
+);
+const version = packageJson.version;
+
+console.log(`Syncing version ${version} to all config files...`);
+
+// Update Cargo.toml
+const cargoTomlPath = join(rootDir, "cli/Cargo.toml");
+let cargoToml = readFileSync(cargoTomlPath, "utf-8");
+const cargoVersionRegex = /^version\s*=\s*"[^"]*"/m;
+const newCargoVersion = `version = "${version}"`;
+
+if (cargoVersionRegex.test(cargoToml)) {
+  const oldMatch = cargoToml.match(cargoVersionRegex)?.[0];
+  if (oldMatch !== newCargoVersion) {
+    cargoToml = cargoToml.replace(cargoVersionRegex, newCargoVersion);
+    writeFileSync(cargoTomlPath, cargoToml);
+    console.log(`  Updated cli/Cargo.toml: ${oldMatch} -> ${newCargoVersion}`);
+  } else {
+    console.log(`  cli/Cargo.toml already up to date`);
+  }
+} else {
+  console.error("  Could not find version field in cli/Cargo.toml");
+  process.exit(1);
+}
+
+console.log("Version sync complete.");
@@ -0,0 +1,143 @@
+---
+name: agent-browser
+description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
+---
+
+# Browser Automation with agent-browser
+
+## Quick start
+
+```bash
+agent-browser open <url>        # Navigate to page
+agent-browser snapshot -i       # Get interactive elements with refs
+agent-browser click @e1         # Click element by ref
+agent-browser fill @e2 "text"   # Fill input by ref
+agent-browser close             # Close browser
+```
+
+## Core workflow
+
+1. Navigate: `agent-browser open <url>`
+2. Snapshot: `agent-browser snapshot -i` (returns elements with refs like `@e1`, `@e2`)
+3. Interact using refs from the snapshot
+4. Re-snapshot after navigation or significant DOM changes
+
+## Commands
+
+### Navigation
+```bash
+agent-browser open <url>      # Navigate to URL
+agent-browser back            # Go back
+agent-browser forward         # Go forward  
+agent-browser reload          # Reload page
+agent-browser close           # Close browser
+```
+
+### Snapshot (page analysis)
+```bash
+agent-browser snapshot        # Full accessibility tree
+agent-browser snapshot -i     # Interactive elements only (recommended)
+agent-browser snapshot -c     # Compact output
+agent-browser snapshot -d 3   # Limit depth to 3
+```
+
+### Interactions (use @refs from snapshot)
+```bash
+agent-browser click @e1           # Click
+agent-browser dblclick @e1        # Double-click
+agent-browser fill @e2 "text"     # Clear and type
+agent-browser type @e2 "text"     # Type without clearing
+agent-browser press Enter         # Press key
+agent-browser press Control+a     # Key combination
+agent-browser hover @e1           # Hover
+agent-browser check @e1           # Check checkbox
+agent-browser uncheck @e1         # Uncheck checkbox
+agent-browser select @e1 "value"  # Select dropdown
+agent-browser scroll down 500     # Scroll page
+agent-browser scrollintoview @e1  # Scroll element into view
+```
+
+### Get information
+```bash
+agent-browser get text @e1        # Get element text
+agent-browser get value @e1       # Get input value
+agent-browser get title           # Get page title
+agent-browser get url             # Get current URL
+```
+
+### Screenshots
+```bash
+agent-browser screenshot          # Screenshot to stdout
+agent-browser screenshot path.png # Save to file
+agent-browser screenshot --full   # Full page
+```
+
+### Wait
+```bash
+agent-browser wait @e1                     # Wait for element
+agent-browser wait 2000                    # Wait milliseconds
+agent-browser wait --text "Success"        # Wait for text
+agent-browser wait --load networkidle      # Wait for network idle
+```
+
+### Semantic locators (alternative to refs)
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+```
+
+## Example: Form submission
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Submit" [ref=e3]
+
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i  # Check result
+```
+
+## Example: Authentication with saved state
+
+```bash
+# Login once
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "username"
+agent-browser fill @e2 "password"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json
+
+# Later sessions: load saved state
+agent-browser state load auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+## Sessions (parallel browsers)
+
+```bash
+agent-browser --session test1 open site-a.com
+agent-browser --session test2 open site-b.com
+agent-browser session list
+```
+
+## JSON output (for parsing)
+
+Add `--json` for machine-readable output:
+```bash
+agent-browser snapshot -i --json
+agent-browser get text @e1 --json
+```
+
+## Debugging
+
+```bash
+agent-browser open example.com --headed  # Show browser window
+agent-browser console                    # View console messages
+agent-browser errors                     # View page errors
+```
@@ -111,6 +111,47 @@ interface SnapshotData {
  refs?: Record<string, { role: string; name?: string }>;
 }

+/**
+ * Convert Playwright errors to AI-friendly messages
+ */
+function toAIFriendlyError(error: unknown, selector: string): Error {
+  const message = error instanceof Error ? error.message : String(error);
+
+  // Handle strict mode violation (multiple elements match)
+  if (message.includes('strict mode violation')) {
+    // Extract count if available
+    const countMatch = message.match(/resolved to (\d+) elements/);
+    const count = countMatch ? countMatch[1] : 'multiple';
+
+    return new Error(
+      `Selector "${selector}" matched ${count} elements. ` +
+        `Run 'snapshot' to get updated refs, or use a more specific CSS selector.`
+    );
+  }
+
+  // Handle element not found
+  if (
+    message.includes('waiting for') &&
+    (message.includes('to be visible') || message.includes('Timeout'))
+  ) {
+    return new Error(
+      `Element "${selector}" not found or not visible. ` +
+        `Run 'snapshot' to see current page elements.`
+    );
+  }
+
+  // Handle element not interactable
+  if (message.includes('intercepts pointer events') || message.includes('not visible')) {
+    return new Error(
+      `Element "${selector}" is not interactable (may be hidden or covered). ` +
+        `Try scrolling it into view or check if a modal/overlay is blocking it.`
+    );
+  }
+
+  // Return original error for unknown cases
+  return error instanceof Error ? error : new Error(message);
+}
+
 /**
 * Execute a command and return a response
 */
@@ -370,6 +411,12 @@ async function handleNavigate(
  browser: BrowserManager
 ): Promise<Response<NavigateData>> {
  const page = browser.getPage();
+
+  // If headers are provided, set up scoped headers for this origin
+  if (command.headers && Object.keys(command.headers).length > 0) {
+    await browser.setScopedHeaders(command.url, command.headers);
+  }
+
  await page.goto(command.url, {
    waitUntil: command.waitUntil ?? 'load',
  });
@@ -384,11 +431,15 @@ async function handleClick(command: ClickCommand, browser: BrowserManager): Prom
  // Support both refs (@e1) and regular selectors
  const locator = browser.getLocator(command.selector);

+  try {
    await locator.click({
      button: command.button,
      clickCount: command.clickCount,
      delay: command.delay,
    });
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }

  return successResponse(command.id, { clicked: true });
 }
@@ -396,6 +447,7 @@ async function handleClick(command: ClickCommand, browser: BrowserManager): Prom
 async function handleType(command: TypeCommand, browser: BrowserManager): Promise<Response> {
  const locator = browser.getLocator(command.selector);

+  try {
    if (command.clear) {
      await locator.fill('');
    }
@@ -403,6 +455,9 @@ async function handleType(command: TypeCommand, browser: BrowserManager): Promis
    await locator.pressSequentially(command.text, {
      delay: command.delay,
    });
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }

  return successResponse(command.id, { typed: true });
 }
@@ -449,7 +504,13 @@ async function handleScreenshot(
 }

 async function handleSnapshot(
-  command: Command & { action: 'snapshot'; interactive?: boolean; maxDepth?: number; compact?: boolean; selector?: string },
+  command: Command & {
+    action: 'snapshot';
+    interactive?: boolean;
+    maxDepth?: number;
+    compact?: boolean;
+    selector?: string;
+  },
  browser: BrowserManager
 ): Promise<Response<SnapshotData>> {
  // Use enhanced snapshot with refs and optional filtering
@@ -550,14 +611,22 @@ async function handleSelect(command: SelectCommand, browser: BrowserManager): Pr
  const locator = browser.getLocator(command.selector);
  const values = Array.isArray(command.values) ? command.values : [command.values];

+  try {
    await locator.selectOption(values);
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }

  return successResponse(command.id, { selected: values });
 }

 async function handleHover(command: HoverCommand, browser: BrowserManager): Promise<Response> {
  const locator = browser.getLocator(command.selector);
+  try {
    await locator.hover();
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }

  return successResponse(command.id, { hovered: true });
 }
@@ -637,26 +706,42 @@ async function handleWindowNew(

 async function handleFill(command: FillCommand, browser: BrowserManager): Promise<Response> {
  const locator = browser.getLocator(command.selector);
+  try {
    await locator.fill(command.value);
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }
  return successResponse(command.id, { filled: true });
 }

 async function handleCheck(command: CheckCommand, browser: BrowserManager): Promise<Response> {
  const locator = browser.getLocator(command.selector);
+  try {
    await locator.check();
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }
  return successResponse(command.id, { checked: true });
 }

 async function handleUncheck(command: UncheckCommand, browser: BrowserManager): Promise<Response> {
  const locator = browser.getLocator(command.selector);
+  try {
    await locator.uncheck();
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }
  return successResponse(command.id, { unchecked: true });
 }

 async function handleUpload(command: UploadCommand, browser: BrowserManager): Promise<Response> {
  const locator = browser.getLocator(command.selector);
  const files = Array.isArray(command.files) ? command.files : [command.files];
+  try {
    await locator.setInputFiles(files);
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }
  return successResponse(command.id, { uploaded: files });
 }

@@ -665,13 +750,21 @@ async function handleDoubleClick(
  browser: BrowserManager
 ): Promise<Response> {
  const locator = browser.getLocator(command.selector);
+  try {
    await locator.dblclick();
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }
  return successResponse(command.id, { clicked: true });
 }

 async function handleFocus(command: FocusCommand, browser: BrowserManager): Promise<Response> {
  const locator = browser.getLocator(command.selector);
+  try {
    await locator.focus();
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }
  return successResponse(command.id, { focused: true });
 }

@@ -22,6 +22,16 @@ describe('BrowserManager', () => {
      const page = browser.getPage();
      expect(page).toBeDefined();
    });
+
+    it('should reject invalid executablePath', async () => {
+      const testBrowser = new BrowserManager();
+      await expect(
+        testBrowser.launch({
+          headless: true,
+          executablePath: '/nonexistent/path/to/chromium',
+        })
+      ).rejects.toThrow();
+    });
  });

  describe('navigation', () => {
@@ -123,7 +133,9 @@ describe('BrowserManager', () => {
    it('should set cookie with domain', async () => {
      const page = browser.getPage();
      const context = page.context();
-      await context.addCookies([{ name: 'domainCookie', value: 'domainValue', domain: 'example.com', path: '/' }]);
+      await context.addCookies([
+        { name: 'domainCookie', value: 'domainValue', domain: 'example.com', path: '/' },
+      ]);
      const cookies = await context.cookies();
      const testCookie = cookies.find((c) => c.name === 'domainCookie');
      expect(testCookie?.value).toBe('domainValue');
@@ -292,4 +304,59 @@ describe('BrowserManager', () => {
      expect(h1).toBe('Example Domain');
    });
  });
+
+  describe('scoped headers', () => {
+    it('should register route for scoped headers', async () => {
+      // Test that setScopedHeaders doesn't throw and completes successfully
+      await browser.clearScopedHeaders();
+      await expect(
+        browser.setScopedHeaders('https://example.com', { 'X-Test': 'value' })
+      ).resolves.not.toThrow();
+      await browser.clearScopedHeaders();
+    });
+
+    it('should handle full URL origin', async () => {
+      await browser.clearScopedHeaders();
+      await expect(
+        browser.setScopedHeaders('https://api.example.com/path', { Authorization: 'Bearer token' })
+      ).resolves.not.toThrow();
+      await browser.clearScopedHeaders();
+    });
+
+    it('should handle hostname-only origin', async () => {
+      await browser.clearScopedHeaders();
+      await expect(
+        browser.setScopedHeaders('example.com', { 'X-Custom': 'value' })
+      ).resolves.not.toThrow();
+      await browser.clearScopedHeaders();
+    });
+
+    it('should clear scoped headers for specific origin', async () => {
+      await browser.clearScopedHeaders();
+      await browser.setScopedHeaders('https://example.com', { 'X-Test': 'value' });
+      await expect(browser.clearScopedHeaders('https://example.com')).resolves.not.toThrow();
+    });
+
+    it('should clear all scoped headers', async () => {
+      await browser.setScopedHeaders('https://example.com', { 'X-Test-1': 'value1' });
+      await browser.setScopedHeaders('https://example.org', { 'X-Test-2': 'value2' });
+      await expect(browser.clearScopedHeaders()).resolves.not.toThrow();
+    });
+
+    it('should replace headers when called twice for same origin', async () => {
+      await browser.clearScopedHeaders();
+      await browser.setScopedHeaders('https://example.com', { 'X-First': 'first' });
+      // Second call should replace, not add
+      await expect(
+        browser.setScopedHeaders('https://example.com', { 'X-Second': 'second' })
+      ).resolves.not.toThrow();
+      await browser.clearScopedHeaders();
+    });
+
+    it('should handle clearing non-existent origin gracefully', async () => {
+      await browser.clearScopedHeaders();
+      // Should not throw when clearing headers that were never set
+      await expect(browser.clearScopedHeaders('https://never-set.com')).resolves.not.toThrow();
+    });
+  });
 });
@@ -51,6 +51,7 @@ export class BrowserManager {
  private isRecordingHar: boolean = false;
  private refMap: RefMap = {};
  private lastSnapshot: string = '';
+  private scopedHeaderRoutes: Map<string, (route: Route) => Promise<void>> = new Map();

  /**
   * Check if browser is launched
@@ -95,12 +96,20 @@ export class BrowserManager {

    const page = this.getPage();

-    // Parse the selector and create locator
+    // Build locator with exact: true to avoid substring matches
+    let locator: Locator;
    if (refData.name) {
-      return page.getByRole(refData.role as any, { name: refData.name });
+      locator = page.getByRole(refData.role as any, { name: refData.name, exact: true });
    } else {
-      return page.getByRole(refData.role as any);
+      locator = page.getByRole(refData.role as any);
    }
+
+    // If an nth index is stored (for disambiguation), use it
+    if (refData.nth !== undefined) {
+      locator = locator.nth(refData.nth);
+    }
+
+    return locator;
  }

  /**
@@ -431,7 +440,7 @@ export class BrowserManager {
  }

  /**
-   * Set extra HTTP headers
+   * Set extra HTTP headers (global - all requests)
   */
  async setExtraHeaders(headers: Record<string, string>): Promise<void> {
    const context = this.contexts[0];
@@ -440,6 +449,76 @@ export class BrowserManager {
    }
  }

+  /**
+   * Set scoped HTTP headers (only for requests matching the origin)
+   * Uses route interception to add headers only to matching requests
+   */
+  async setScopedHeaders(origin: string, headers: Record<string, string>): Promise<void> {
+    const page = this.getPage();
+
+    // Build URL pattern from origin (e.g., "api.example.com" -> "**://api.example.com/**")
+    // Handle both full URLs and just hostnames
+    let urlPattern: string;
+    try {
+      const url = new URL(origin.startsWith('http') ? origin : `https://${origin}`);
+      // Match any protocol, the host, and any path
+      urlPattern = `**://${url.host}/**`;
+    } catch {
+      // If parsing fails, treat as hostname pattern
+      urlPattern = `**://${origin}/**`;
+    }
+
+    // Remove existing route for this origin if any
+    const existingHandler = this.scopedHeaderRoutes.get(urlPattern);
+    if (existingHandler) {
+      await page.unroute(urlPattern, existingHandler);
+    }
+
+    // Create handler that adds headers to matching requests
+    const handler = async (route: Route) => {
+      const requestHeaders = route.request().headers();
+      await route.continue({
+        headers: {
+          ...requestHeaders,
+          ...headers,
+        },
+      });
+    };
+
+    // Store and register the route
+    this.scopedHeaderRoutes.set(urlPattern, handler);
+    await page.route(urlPattern, handler);
+  }
+
+  /**
+   * Clear scoped headers for an origin (or all if no origin specified)
+   */
+  async clearScopedHeaders(origin?: string): Promise<void> {
+    const page = this.getPage();
+
+    if (origin) {
+      let urlPattern: string;
+      try {
+        const url = new URL(origin.startsWith('http') ? origin : `https://${origin}`);
+        urlPattern = `**://${url.host}/**`;
+      } catch {
+        urlPattern = `**://${origin}/**`;
+      }
+
+      const handler = this.scopedHeaderRoutes.get(urlPattern);
+      if (handler) {
+        await page.unroute(urlPattern, handler);
+        this.scopedHeaderRoutes.delete(urlPattern);
+      }
+    } else {
+      // Clear all scoped header routes
+      for (const [pattern, handler] of this.scopedHeaderRoutes) {
+        await page.unroute(pattern, handler);
+      }
+      this.scopedHeaderRoutes.clear();
+    }
+  }
+
  /**
   * Start tracing
   */
@@ -512,11 +591,13 @@ export class BrowserManager {
    // Launch browser
    this.browser = await launcher.launch({
      headless: options.headless ?? true,
+      executablePath: options.executablePath,
    });

-    // Create context with viewport
+    // Create context with viewport and optional headers
    const context = await this.browser.newContext({
      viewport: options.viewport ?? { width: 1280, height: 720 },
+      extraHTTPHeaders: options.headers,
    });

    // Set default timeout to 10 seconds (Playwright default is 30s)
@@ -33,7 +33,7 @@ export function getSession(): string {
 function getPortForSession(session: string): number {
  let hash = 0;
  for (let i = 0; i < session.length; i++) {
-    hash = ((hash << 5) - hash) + session.charCodeAt(i);
+    hash = (hash << 5) - hash + session.charCodeAt(i);
    hash |= 0;
  }
  // Port range 49152-65535 (dynamic/private ports)
@@ -90,7 +90,9 @@ export function isDaemonRunning(session?: string): boolean {
 * Get connection info for the current session
 * Returns { type: 'unix', path: string } or { type: 'tcp', port: number }
 */
-export function getConnectionInfo(session?: string): { type: 'unix'; path: string } | { type: 'tcp'; port: number } {
+export function getConnectionInfo(
+  session?: string
+): { type: 'unix'; path: string } | { type: 'tcp'; port: number } {
  const sess = session ?? currentSession;
  if (isWindows) {
    return { type: 'tcp', port: getPortForSession(sess) };
@@ -156,7 +158,12 @@ export async function startDaemon(): Promise<void> {
            parseResult.command.action !== 'launch' &&
            parseResult.command.action !== 'close'
          ) {
-            await browser.launch({ id: 'auto', action: 'launch', headless: true });
+            await browser.launch({
+              id: 'auto',
+              action: 'launch',
+              headless: true,
+              executablePath: process.env.AGENT_BROWSER_EXECUTABLE_PATH,
+            });
          }

          // Handle close command specially
@@ -252,7 +252,9 @@ describe('parseCommand', () => {
    });

    it('should parse storage_get with specific key', () => {
-      const result = parseCommand(cmd({ id: '1', action: 'storage_get', type: 'local', key: 'mykey' }));
+      const result = parseCommand(
+        cmd({ id: '1', action: 'storage_get', type: 'local', key: 'mykey' })
+      );
      expect(result.success).toBe(true);
      if (result.success) {
        expect(result.command.key).toBe('mykey');
@@ -426,14 +428,16 @@ describe('parseCommand', () => {
    });

    it('should parse snapshot with all options', () => {
-      const result = parseCommand(cmd({
+      const result = parseCommand(
+        cmd({
          id: '1',
          action: 'snapshot',
          interactive: true,
          compact: true,
          maxDepth: 5,
          selector: '.content',
-      }));
+        })
+      );
      expect(result.success).toBe(true);
      if (result.success) {
        expect(result.command.interactive).toBe(true);
@@ -487,7 +491,9 @@ describe('parseCommand', () => {

  describe('scroll', () => {
    it('should parse scroll command', () => {
-      const result = parseCommand(cmd({ id: '1', action: 'scroll', direction: 'down', amount: 300 }));
+      const result = parseCommand(
+        cmd({ id: '1', action: 'scroll', direction: 'down', amount: 300 })
+      );
      expect(result.success).toBe(true);
    });

@@ -521,7 +527,9 @@ describe('parseCommand', () => {
    });

    it('should parse geolocation', () => {
-      const result = parseCommand(cmd({ id: '1', action: 'geolocation', latitude: 37.7749, longitude: -122.4194 }));
+      const result = parseCommand(
+        cmd({ id: '1', action: 'geolocation', latitude: 37.7749, longitude: -122.4194 })
+      );
      expect(result.success).toBe(true);
    });

@@ -572,7 +580,9 @@ describe('parseCommand', () => {
    });

    it('should parse dialog accept with prompt text', () => {
-      const result = parseCommand(cmd({ id: '1', action: 'dialog', response: 'accept', promptText: 'hello' }));
+      const result = parseCommand(
+        cmd({ id: '1', action: 'dialog', response: 'accept', promptText: 'hello' })
+      );
      expect(result.success).toBe(true);
      if (result.success) {
        expect(result.command.promptText).toBe('hello');
@@ -24,6 +24,8 @@ export interface RefMap {
    selector: string;
    role: string;
    name?: string;
+    /** Index for disambiguation when multiple elements have same role+name */
+    nth?: number;
  };
 }

@@ -129,7 +131,7 @@ const STRUCTURAL_ROLES = new Set([
 function buildSelector(role: string, name?: string): string {
  if (name) {
    const escapedName = name.replace(/"/g, '\\"');
-    return `getByRole('${role}', { name: "${escapedName}" })`;
+    return `getByRole('${role}', { name: "${escapedName}", exact: true })`;
  }
  return `getByRole('${role}')`;
 }
@@ -161,12 +163,60 @@ export async function getEnhancedSnapshot(
  return { tree: enhancedTree, refs };
 }

+/**
+ * Track role+name combinations to detect duplicates
+ */
+interface RoleNameTracker {
+  counts: Map<string, number>;
+  /** Maps role+name key to array of ref IDs that use it */
+  refsByKey: Map<string, string[]>;
+  getKey(role: string, name?: string): string;
+  getNextIndex(role: string, name?: string): number;
+  trackRef(role: string, name: string | undefined, ref: string): void;
+  /** Get all role+name keys that have duplicates */
+  getDuplicateKeys(): Set<string>;
+}
+
+function createRoleNameTracker(): RoleNameTracker {
+  const counts = new Map<string, number>();
+  const refsByKey = new Map<string, string[]>();
+  return {
+    counts,
+    refsByKey,
+    getKey(role: string, name?: string): string {
+      return `${role}:${name ?? ''}`;
+    },
+    getNextIndex(role: string, name?: string): number {
+      const key = this.getKey(role, name);
+      const current = counts.get(key) ?? 0;
+      counts.set(key, current + 1);
+      return current;
+    },
+    trackRef(role: string, name: string | undefined, ref: string): void {
+      const key = this.getKey(role, name);
+      const refs = refsByKey.get(key) ?? [];
+      refs.push(ref);
+      refsByKey.set(key, refs);
+    },
+    getDuplicateKeys(): Set<string> {
+      const duplicates = new Set<string>();
+      for (const [key, refs] of refsByKey) {
+        if (refs.length > 1) {
+          duplicates.add(key);
+        }
+      }
+      return duplicates;
+    },
+  };
+}
+
 /**
 * Process ARIA snapshot: add refs and apply filters
 */
 function processAriaTree(ariaTree: string, refs: RefMap, options: SnapshotOptions): string {
  const lines = ariaTree.split('\n');
  const result: string[] = [];
+  const tracker = createRoleNameTracker();

  // For interactive-only mode, we collect just interactive elements
  if (options.interactive) {
@@ -179,31 +229,43 @@ function processAriaTree(ariaTree: string, refs: RefMap, options: SnapshotOption

      if (INTERACTIVE_ROLES.has(roleLower)) {
        const ref = nextRef();
+        const nth = tracker.getNextIndex(roleLower, name);
+        tracker.trackRef(roleLower, name, ref);
        refs[ref] = {
          selector: buildSelector(roleLower, name),
          role: roleLower,
          name,
+          nth, // Always store nth, we'll use it for duplicates
        };

        let enhanced = `- ${role}`;
        if (name) enhanced += ` "${name}"`;
        enhanced += ` [ref=${ref}]`;
+        // Only show nth in output if it's > 0 (for readability)
+        if (nth > 0) enhanced += ` [nth=${nth}]`;
        if (suffix && suffix.includes('[')) enhanced += suffix;

        result.push(enhanced);
      }
    }
+
+    // Post-process: remove nth from refs that don't have duplicates
+    removeNthFromNonDuplicates(refs, tracker);
+
    return result.join('\n') || '(no interactive elements)';
  }

  // Normal processing with depth/compact filters
  for (const line of lines) {
-    const processed = processLine(line, refs, options);
+    const processed = processLine(line, refs, options, tracker);
    if (processed !== null) {
      result.push(processed);
    }
  }

+  // Post-process: remove nth from refs that don't have duplicates
+  removeNthFromNonDuplicates(refs, tracker);
+
  // If compact mode, remove empty structural elements
  if (options.compact) {
    return compactTree(result.join('\n'));
@@ -212,6 +274,22 @@ function processAriaTree(ariaTree: string, refs: RefMap, options: SnapshotOption
  return result.join('\n');
 }

+/**
+ * Remove nth from refs that ended up not having duplicates
+ * This keeps single-element locators simple (no unnecessary .nth(0))
+ */
+function removeNthFromNonDuplicates(refs: RefMap, tracker: RoleNameTracker): void {
+  const duplicateKeys = tracker.getDuplicateKeys();
+
+  for (const [ref, data] of Object.entries(refs)) {
+    const key = tracker.getKey(data.role, data.name);
+    if (!duplicateKeys.has(key)) {
+      // Not a duplicate, remove nth to keep locator simple
+      delete refs[ref].nth;
+    }
+  }
+}
+
 /**
 * Get indentation level (number of spaces / 2)
 */
@@ -226,7 +304,8 @@ function getIndentLevel(line: string): number {
 function processLine(
  line: string,
  refs: RefMap,
-  options: SnapshotOptions
+  options: SnapshotOptions,
+  tracker: RoleNameTracker
 ): string | null {
  const depth = getIndentLevel(line);

@@ -277,17 +356,22 @@ function processLine(

  if (shouldHaveRef) {
    const ref = nextRef();
+    const nth = tracker.getNextIndex(roleLower, name);
+    tracker.trackRef(roleLower, name, ref);

    refs[ref] = {
      selector: buildSelector(roleLower, name),
      role: roleLower,
      name,
+      nth, // Always store nth, we'll clean up non-duplicates later
    };

    // Build enhanced line with ref
    let enhanced = `${prefix}${role}`;
    if (name) enhanced += ` "${name}"`;
    enhanced += ` [ref=${ref}]`;
+    // Only show nth in output if it's > 0 (for readability)
+    if (nth > 0) enhanced += ` [nth=${nth}]`;
    if (suffix) enhanced += suffix;

    return enhanced;
@@ -359,16 +443,17 @@ export function parseRef(arg: string): string | null {
 /**
 * Get snapshot statistics
 */
-export function getSnapshotStats(tree: string, refs: RefMap): {
+export function getSnapshotStats(
+  tree: string,
+  refs: RefMap
+): {
  lines: number;
  chars: number;
  tokens: number;
  refs: number;
  interactive: number;
 } {
-  const interactive = Object.values(refs).filter(r => 
-    INTERACTIVE_ROLES.has(r.role)
-  ).length;
+  const interactive = Object.values(refs).filter((r) => INTERACTIVE_ROLES.has(r.role)).length;

  return {
    lines: tree.split('\n').length,
@@ -12,12 +12,15 @@ export interface LaunchCommand extends BaseCommand {
  headless?: boolean;
  viewport?: { width: number; height: number };
  browser?: 'chromium' | 'firefox' | 'webkit';
+  headers?: Record<string, string>;
+  executablePath?: string;
 }

 export interface NavigateCommand extends BaseCommand {
  action: 'navigate';
  url: string;
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+  headers?: Record<string, string>;
 }

 export interface ClickCommand extends BaseCommand {
@@ -0,0 +1,85 @@
+/**
+ * Integration test for @sparticuz/chromium compatibility
+ * This tests the executablePath option with a serverless-optimized Chromium build
+ *
+ * Note: @sparticuz/chromium only works on Linux (designed for AWS Lambda).
+ * This test will skip on non-Linux platforms.
+ */
+import { describe, it, expect, afterAll } from 'vitest';
+import { BrowserManager } from '../src/browser.js';
+import * as os from 'os';
+
+const isLinux = os.platform() === 'linux';
+
+// Only run if @sparticuz/chromium is available AND we're on Linux
+const canRunTest = await (async () => {
+  if (!isLinux) {
+    console.log('Skipping @sparticuz/chromium test: only runs on Linux');
+    return false;
+  }
+  try {
+    await import('@sparticuz/chromium');
+    return true;
+  } catch {
+    console.log('Skipping @sparticuz/chromium test: package not installed');
+    return false;
+  }
+})();
+
+describe.skipIf(!canRunTest)('Serverless Chromium Integration', () => {
+  let browser: BrowserManager;
+  let chromiumPath: string;
+
+  it('should get executable path from @sparticuz/chromium', async () => {
+    const chromium = await import('@sparticuz/chromium');
+    chromiumPath = await chromium.default.executablePath();
+    expect(chromiumPath).toBeTruthy();
+    expect(typeof chromiumPath).toBe('string');
+    console.log('Chromium executable path:', chromiumPath);
+  });
+
+  it('should launch browser with custom executablePath', async () => {
+    const chromium = await import('@sparticuz/chromium');
+    chromiumPath = await chromium.default.executablePath();
+
+    browser = new BrowserManager();
+    await browser.launch({
+      headless: true,
+      executablePath: chromiumPath,
+    });
+
+    expect(browser.isLaunched()).toBe(true);
+  });
+
+  it('should navigate to a page', async () => {
+    const page = browser.getPage();
+    await page.goto('https://example.com');
+    expect(page.url()).toBe('https://example.com/');
+  });
+
+  it('should get page title', async () => {
+    const page = browser.getPage();
+    const title = await page.title();
+    expect(title).toBe('Example Domain');
+  });
+
+  it('should take snapshot with refs', async () => {
+    const { tree, refs } = await browser.getSnapshot();
+    expect(tree).toContain('Example Domain');
+    expect(typeof refs).toBe('object');
+    expect(Object.keys(refs).length).toBeGreaterThan(0);
+  });
+
+  it('should take screenshot', async () => {
+    const page = browser.getPage();
+    const buffer = await page.screenshot();
+    expect(buffer).toBeInstanceOf(Buffer);
+    expect(buffer.length).toBeGreaterThan(0);
+  });
+
+  afterAll(async () => {
+    if (browser?.isLaunched()) {
+      await browser.close();
+    }
+  });
+});
@@ -3,7 +3,7 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
  test: {
    globals: true,
-    include: ['src/**/*.test.ts'],
+    include: ['src/**/*.test.ts', 'test/**/*.test.ts'],
    testTimeout: 30000,
  },
 });
Author	SHA1	Message	Date
Chris Tate	068fc74a9c	Merge main into ctate/custom-headers	2026-01-12 11:57:43 -06:00
Chris Tate	4f6fd8ec5c	support serverless environments (#29 ) * add --executable-path * tests * test vercel * fixes	2026-01-12 11:41:25 -06:00
Chris Tate	4e5ff20078	better parsing	2026-01-12 11:40:52 -06:00
Chris Tate	03e266ee38	add tests	2026-01-12 11:26:45 -06:00
Chris Tate	8c412197ad	add custom headers via --headers	2026-01-12 11:22:46 -06:00
Chris Tate	3cd0ab468f	add sub --help flag (#27 )	2026-01-12 10:52:31 -06:00
Chris Tate	a4fcc1c198	fix windows bug (#26 ) * fix windows bug * test windows * address feedback	2026-01-12 10:33:21 -06:00
Chris Tate	574037080c	0.4.3 (#20 )	2026-01-12 01:24:48 -06:00
Chris Tate	278466764b	fix readme + add missing wait flags (#19 ) * fix inaccuracies * fix wait * address feedback	2026-01-12 01:22:10 -06:00
Chris Tate	f2878c750d	fix typo (#18 ) * fix skill name * 0.4.2	2026-01-12 00:58:07 -06:00
Chris Tate	bc0b99c374	0.4.1 (#17 ) * sync version * 0.4.1 * add release script	2026-01-12 00:43:52 -06:00
Chris Tate	a0802b1863	fix locator issues (#14 ) * fix locator issues * address feedback	2026-01-12 00:29:53 -06:00
Chris Tate	403a7e5d56	usage with agents (#15 )	2026-01-12 00:29:45 -06:00
Chris Tate	277febad63	fix session cmd (#13 ) * fix session cmd * address feedback	2026-01-12 00:06:34 -06:00
Chris Tate	5a7c7440c0	add ci action (#12 ) * add ci action * pre-commit hook * format	2026-01-12 00:02:38 -06:00
Chris Tate	24881c7327	better ax/dx (#11 )	2026-01-11 23:48:07 -06:00