add release script

0.4.1
sync version
2026-01-12 00:35:18 -06:00 · 2026-01-12 00:33:29 -06:00 · 2026-01-12 00:32:20 -06:00 · 2026-01-12 00:29:53 -06:00 · 2026-01-12 00:29:45 -06:00 · 2026-01-12 00:06:34 -06:00
18 changed files with 2435 additions and 256 deletions
@@ -0,0 +1,85 @@
+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 }}
@@ -0,0 +1 @@
+pnpm lint-staged
@@ -403,6 +403,50 @@ The daemon starts automatically on first command and persists between commands f
 | Linux x64 | ✅ Native Rust | Node.js |
 | Windows | - | 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/browsing-web .claude/skills/
+```
+
+Or download:
+
+```bash
+mkdir -p .claude/skills/browsing-web
+curl -o .claude/skills/browsing-web/SKILL.md \
+  https://raw.githubusercontent.com/vercel-labs/agent-browser/main/skills/browsing-web/SKILL.md
+```
+
 ## License

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

 [[package]]
 name = "agent-browser"
-version = "0.4.0"
+version = "0.4.1"
 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.1"
 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
@@ -6,14 +6,93 @@ 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};

+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);
@@ -31,14 +110,29 @@ 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())
-            );
-            eprintln!("\x1b[2mRun: agent-browser --help\x1b[0m");
+        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
+                );
+            } else {
+                eprintln!("\x1b[31m{}\x1b[0m", e.format());
+            }
            exit(1);
        }
    };
@@ -215,6 +215,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)
@@ -1,25 +1,30 @@
 {
  "name": "agent-browser",
-  "version": "0.4.0",
+  "version": "0.4.1",
  "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: browsing-web
+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
 */
@@ -383,12 +424,16 @@ async function handleNavigate(
 async function handleClick(command: ClickCommand, browser: BrowserManager): Promise<Response> {
  // Support both refs (@e1) and regular selectors
  const locator = browser.getLocator(command.selector);
-  
-  await locator.click({
-    button: command.button,
-    clickCount: command.clickCount,
-    delay: command.delay,
-  });
+
+  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,13 +441,17 @@ async function handleClick(command: ClickCommand, browser: BrowserManager): Prom
 async function handleType(command: TypeCommand, browser: BrowserManager): Promise<Response> {
  const locator = browser.getLocator(command.selector);

-  if (command.clear) {
-    await locator.fill('');
-  }
+  try {
+    if (command.clear) {
+      await locator.fill('');
+    }

-  await locator.pressSequentially(command.text, {
-    delay: command.delay,
-  });
+    await locator.pressSequentially(command.text, {
+      delay: command.delay,
+    });
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }

  return successResponse(command.id, { typed: true });
 }
@@ -449,7 +498,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 +605,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];

-  await locator.selectOption(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);
-  await locator.hover();
+  try {
+    await locator.hover();
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }

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

 async function handleFill(command: FillCommand, browser: BrowserManager): Promise<Response> {
  const locator = browser.getLocator(command.selector);
-  await locator.fill(command.value);
+  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);
-  await locator.check();
+  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);
-  await locator.uncheck();
+  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];
-  await locator.setInputFiles(files);
+  try {
+    await locator.setInputFiles(files);
+  } catch (error) {
+    throw toAIFriendlyError(error, command.selector);
+  }
  return successResponse(command.id, { uploaded: files });
 }

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

@@ -791,7 +878,15 @@ async function handleCookiesSet(
 ): Promise<Response> {
  const page = browser.getPage();
  const context = page.context();
-  await context.addCookies(command.cookies);
+  // Auto-fill URL for cookies that don't have domain/path/url set
+  const pageUrl = page.url();
+  const cookies = command.cookies.map((cookie) => {
+    if (!cookie.url && !cookie.domain && !cookie.path) {
+      return { ...cookie, url: pageUrl };
+    }
+    return cookie;
+  });
+  await context.addCookies(cookies);
  return successResponse(command.id, { set: true });
 }

@@ -120,6 +120,30 @@ describe('BrowserManager', () => {
      expect(testCookie?.value).toBe('value');
    });

+    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: '/' },
+      ]);
+      const cookies = await context.cookies();
+      const testCookie = cookies.find((c) => c.name === 'domainCookie');
+      expect(testCookie?.value).toBe('domainValue');
+    });
+
+    it('should set multiple cookies at once', async () => {
+      const page = browser.getPage();
+      const context = page.context();
+      await context.clearCookies();
+      await context.addCookies([
+        { name: 'cookie1', value: 'value1', url: 'https://example.com' },
+        { name: 'cookie2', value: 'value2', url: 'https://example.com' },
+      ]);
+      const cookies = await context.cookies();
+      expect(cookies.find((c) => c.name === 'cookie1')?.value).toBe('value1');
+      expect(cookies.find((c) => c.name === 'cookie2')?.value).toBe('value2');
+    });
+
    it('should clear cookies', async () => {
      const page = browser.getPage();
      const context = page.context();
@@ -129,20 +153,83 @@ describe('BrowserManager', () => {
    });
  });

-  describe('storage via evaluate', () => {
-    it('should set and get localStorage', async () => {
+  describe('localStorage operations', () => {
+    it('should set and get localStorage item', async () => {
      const page = browser.getPage();
+      await page.goto('https://example.com');
      await page.evaluate(() => localStorage.setItem('testKey', 'testValue'));
      const value = await page.evaluate(() => localStorage.getItem('testKey'));
      expect(value).toBe('testValue');
    });

+    it('should get all localStorage items', async () => {
+      const page = browser.getPage();
+      await page.evaluate(() => {
+        localStorage.clear();
+        localStorage.setItem('key1', 'value1');
+        localStorage.setItem('key2', 'value2');
+      });
+      const storage = await page.evaluate(() => {
+        const items: Record<string, string> = {};
+        for (let i = 0; i < localStorage.length; i++) {
+          const key = localStorage.key(i);
+          if (key) items[key] = localStorage.getItem(key) || '';
+        }
+        return items;
+      });
+      expect(storage.key1).toBe('value1');
+      expect(storage.key2).toBe('value2');
+    });
+
    it('should clear localStorage', async () => {
      const page = browser.getPage();
      await page.evaluate(() => localStorage.clear());
      const value = await page.evaluate(() => localStorage.getItem('testKey'));
      expect(value).toBeNull();
    });
+
+    it('should return null for non-existent key', async () => {
+      const page = browser.getPage();
+      await page.evaluate(() => localStorage.clear());
+      const value = await page.evaluate(() => localStorage.getItem('nonexistent'));
+      expect(value).toBeNull();
+    });
+  });
+
+  describe('sessionStorage operations', () => {
+    it('should set and get sessionStorage item', async () => {
+      const page = browser.getPage();
+      await page.goto('https://example.com');
+      await page.evaluate(() => sessionStorage.setItem('sessionKey', 'sessionValue'));
+      const value = await page.evaluate(() => sessionStorage.getItem('sessionKey'));
+      expect(value).toBe('sessionValue');
+    });
+
+    it('should get all sessionStorage items', async () => {
+      const page = browser.getPage();
+      await page.evaluate(() => {
+        sessionStorage.clear();
+        sessionStorage.setItem('skey1', 'svalue1');
+        sessionStorage.setItem('skey2', 'svalue2');
+      });
+      const storage = await page.evaluate(() => {
+        const items: Record<string, string> = {};
+        for (let i = 0; i < sessionStorage.length; i++) {
+          const key = sessionStorage.key(i);
+          if (key) items[key] = sessionStorage.getItem(key) || '';
+        }
+        return items;
+      });
+      expect(storage.skey1).toBe('svalue1');
+      expect(storage.skey2).toBe('svalue2');
+    });
+
+    it('should clear sessionStorage', async () => {
+      const page = browser.getPage();
+      await page.evaluate(() => sessionStorage.clear());
+      const value = await page.evaluate(() => sessionStorage.getItem('sessionKey'));
+      expect(value).toBeNull();
+    });
  });

  describe('viewport', () => {
@@ -94,13 +94,21 @@ export class BrowserManager {
    if (!refData) return null;

    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;
  }

  /**
@@ -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) };
@@ -112,9 +112,22 @@ describe('parseCommand', () => {
    it('should parse cookies_get', () => {
      const result = parseCommand(cmd({ id: '1', action: 'cookies_get' }));
      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.command.action).toBe('cookies_get');
+      }
    });

-    it('should parse cookies_set', () => {
+    it('should parse cookies_get with urls filter', () => {
+      const result = parseCommand(
+        cmd({ id: '1', action: 'cookies_get', urls: ['https://example.com'] })
+      );
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.command.urls).toEqual(['https://example.com']);
+      }
+    });
+
+    it('should parse cookies_set with minimal cookie', () => {
      const result = parseCommand(
        cmd({
          id: '1',
@@ -123,18 +136,129 @@ describe('parseCommand', () => {
        })
      );
      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.command.action).toBe('cookies_set');
+        expect(result.command.cookies).toHaveLength(1);
+        expect(result.command.cookies[0].name).toBe('session');
+        expect(result.command.cookies[0].value).toBe('abc123');
+      }
+    });
+
+    it('should parse cookies_set with full cookie options', () => {
+      const result = parseCommand(
+        cmd({
+          id: '1',
+          action: 'cookies_set',
+          cookies: [
+            {
+              name: 'auth',
+              value: 'token123',
+              domain: 'example.com',
+              path: '/',
+              expires: Date.now() / 1000 + 3600,
+              httpOnly: true,
+              secure: true,
+              sameSite: 'Strict',
+            },
+          ],
+        })
+      );
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.command.cookies[0].httpOnly).toBe(true);
+        expect(result.command.cookies[0].secure).toBe(true);
+        expect(result.command.cookies[0].sameSite).toBe('Strict');
+      }
+    });
+
+    it('should parse cookies_set with multiple cookies', () => {
+      const result = parseCommand(
+        cmd({
+          id: '1',
+          action: 'cookies_set',
+          cookies: [
+            { name: 'cookie1', value: 'value1' },
+            { name: 'cookie2', value: 'value2' },
+          ],
+        })
+      );
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.command.cookies).toHaveLength(2);
+      }
+    });
+
+    it('should reject cookies_set without cookies array', () => {
+      const result = parseCommand(cmd({ id: '1', action: 'cookies_set' }));
+      expect(result.success).toBe(false);
+    });
+
+    it('should accept cookies_set with empty cookies array', () => {
+      // Empty array is technically valid (no-op)
+      const result = parseCommand(cmd({ id: '1', action: 'cookies_set', cookies: [] }));
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject cookies_set with cookie missing name', () => {
+      const result = parseCommand(
+        cmd({ id: '1', action: 'cookies_set', cookies: [{ value: 'test' }] })
+      );
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject cookies_set with cookie missing value', () => {
+      const result = parseCommand(
+        cmd({ id: '1', action: 'cookies_set', cookies: [{ name: 'test' }] })
+      );
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject cookies_set with invalid sameSite value', () => {
+      const result = parseCommand(
+        cmd({
+          id: '1',
+          action: 'cookies_set',
+          cookies: [{ name: 'test', value: 'val', sameSite: 'Invalid' }],
+        })
+      );
+      expect(result.success).toBe(false);
    });

    it('should parse cookies_clear', () => {
      const result = parseCommand(cmd({ id: '1', action: 'cookies_clear' }));
      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.command.action).toBe('cookies_clear');
+      }
    });
  });

  describe('storage', () => {
-    it('should parse storage_get', () => {
+    it('should parse storage_get for localStorage', () => {
      const result = parseCommand(cmd({ id: '1', action: 'storage_get', type: 'local' }));
      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.command.action).toBe('storage_get');
+        expect(result.command.type).toBe('local');
+      }
+    });
+
+    it('should parse storage_get for sessionStorage', () => {
+      const result = parseCommand(cmd({ id: '1', action: 'storage_get', type: 'session' }));
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.command.type).toBe('session');
+      }
+    });
+
+    it('should parse storage_get with specific key', () => {
+      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');
+      }
    });

    it('should parse storage_set', () => {
@@ -148,6 +272,59 @@ describe('parseCommand', () => {
        })
      );
      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.command.action).toBe('storage_set');
+        expect(result.command.key).toBe('test');
+        expect(result.command.value).toBe('value');
+      }
+    });
+
+    it('should reject storage_set without key', () => {
+      const result = parseCommand(
+        cmd({
+          id: '1',
+          action: 'storage_set',
+          type: 'local',
+          value: 'value',
+        })
+      );
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject storage_set without value', () => {
+      const result = parseCommand(
+        cmd({
+          id: '1',
+          action: 'storage_set',
+          type: 'local',
+          key: 'test',
+        })
+      );
+      expect(result.success).toBe(false);
+    });
+
+    it('should parse storage_clear for localStorage', () => {
+      const result = parseCommand(cmd({ id: '1', action: 'storage_clear', type: 'local' }));
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.command.action).toBe('storage_clear');
+        expect(result.command.type).toBe('local');
+      }
+    });
+
+    it('should parse storage_clear for sessionStorage', () => {
+      const result = parseCommand(cmd({ id: '1', action: 'storage_clear', type: 'session' }));
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject storage_get without type', () => {
+      const result = parseCommand(cmd({ id: '1', action: 'storage_get' }));
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject storage_get with invalid type', () => {
+      const result = parseCommand(cmd({ id: '1', action: 'storage_get', type: 'invalid' }));
+      expect(result.success).toBe(false);
    });
  });

@@ -251,14 +428,16 @@ describe('parseCommand', () => {
    });

    it('should parse snapshot with all options', () => {
-      const result = parseCommand(cmd({
-        id: '1',
-        action: 'snapshot',
-        interactive: true,
-        compact: true,
-        maxDepth: 5,
-        selector: '.content',
-      }));
+      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);
@@ -312,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);
    });

@@ -346,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);
    });

@@ -397,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,49 +163,109 @@ 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) {
    for (const line of lines) {
      const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
      if (!match) continue;
-      
+
      const [, , role, name, suffix] = match;
      const roleLower = role.toLowerCase();
-      
+
      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;
@@ -302,27 +386,27 @@ function processLine(
 function compactTree(tree: string): string {
  const lines = tree.split('\n');
  const result: string[] = [];
-  
+
  // Simple pass: keep lines that have content or refs
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
-    
+
    // Always keep lines with refs
    if (line.includes('[ref=')) {
      result.push(line);
      continue;
    }
-    
+
    // Keep lines with text content (after :)
    if (line.includes(':') && !line.endsWith(':')) {
      result.push(line);
      continue;
    }
-    
+
    // Check if this structural element has children with refs
    const currentIndent = getIndentLevel(line);
    let hasRelevantChildren = false;
-    
+
    for (let j = i + 1; j < lines.length; j++) {
      const childIndent = getIndentLevel(lines[j]);
      if (childIndent <= currentIndent) break;
@@ -331,12 +415,12 @@ function compactTree(tree: string): string {
        break;
      }
    }
-    
+
    if (hasRelevantChildren) {
      result.push(line);
    }
  }
-  
+
  return result.join('\n');
 }

@@ -359,17 +443,18 @@ 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,
    chars: tree.length,
Author	SHA1	Message	Date
Chris Tate	e8fcc3574c	add release script	2026-01-12 00:35:18 -06:00
Chris Tate	dd10ca7e01	0.4.1	2026-01-12 00:33:29 -06:00
Chris Tate	15149bf54d	sync version	2026-01-12 00:32:20 -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
Chris Tate	9f7d7d6447	fix cookies/storage (#10 )	2026-01-11 23:27:49 -06:00