@ulpi/browse 0.1.0

package/BENCHMARKS.md

@@ -0,0 +1,222 @@
+# Benchmarks: @ulpi/browse vs @playwright/mcp
+
+Measured 2026-03-15. Same machine, same Chromium, same pages.
+
+## What Gets Dumped Into the AI Context
+
+**@playwright/mcp**: Every `browser_navigate`, `browser_click`, or `browser_type` returns the **full accessibility snapshot** — automatically, whether you need it or not.
+
+**@ulpi/browse**: `goto` returns a one-liner (`"Navigated to ... (200)"`). The agent **chooses** what to request: `text`, `snapshot -i`, `links`, `forms`, etc.
+
+## Per-Page Token Cost
+
+| Site | Page | @playwright/mcp navigate | browse snapshot -i | Ratio |
+|------|------|-------------------------:|-------------------:|------:|
+| mumzworld.com | Homepage | ~51,151 | ~15,072 | **3x** |
+| mumzworld.com | Search | ~13,860 | ~3,614 | **4x** |
+| mumzworld.com | PDP | ~10,071 | ~3,084 | **3x** |
+| amazon.com | Homepage | ~10,431 | ~2,150 | **5x** |
+| amazon.com | Search | ~19,458 | ~3,644 | **5x** |
+| ebay.com | Homepage | ~4,641 | ~1,557 | **3x** |
+| ebay.com | Search | ~35,929 | ~7,088 | **5x** |
+| ebay.com | PDP | ~1,294 | ~678 | **2x** |
+| nike.com | Homepage | ~2,495 | ~816 | **3x** |
+| nike.com | Search | ~7,998 | ~2,678 | **3x** |
+| nike.com | PDP | ~3,034 | ~989 | **3x** |
+| **TOTAL** | **11 pages** | **~160,362** | **~41,370** | **4x** |
+
+`browse goto` alone costs ~10-25 tokens per navigation (one-liner confirmation). The agent requests a snapshot only when it needs to see the page.
+
+## 10-Step Agent Session
+
+A typical flow: navigate, snapshot, click, snapshot, fill, click, snapshot, check result.
+
+| | @playwright/mcp | @ulpi/browse |
+|---|---:|---:|
+| Tokens per navigate/click/type | ~14,578 (auto-dumped) | ~15 (one-liner) |
+| 10 actions total | ~145,780 | ~11,388 (3 snapshots + 7 actions) |
+| Context consumed (200K window) | 73% | 6% |
+
+## Raw Data
+
+### mumzworld.com
+
+#### Homepage
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 199.8 KB | ~51,151 | Full snapshot auto-dumped |
+| Playwright page.content() | 3.50 MB | ~917,905 | Raw HTML |
+| browse goto | 44 B | ~11 | One-liner |
+| browse text | 19.4 KB | ~4,971 | Clean visible text |
+| browse snapshot | 159.5 KB | ~40,844 | Full tree + @refs |
+| **browse snapshot -i** | **58.9 KB** | **~15,072** | **Interactive + @refs** |
+| browse links | 62.2 KB | ~15,913 | Text → URL |
+| browse forms | 213 B | ~53 | Structured JSON |
+
+#### Search
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 54.1 KB | ~13,860 | Full snapshot auto-dumped |
+| Playwright page.content() | 1.08 MB | ~283,764 | Raw HTML |
+| browse goto | 66 B | ~17 | One-liner |
+| browse text | 6.6 KB | ~1,687 | Clean visible text |
+| browse snapshot | 49.2 KB | ~12,585 | Full tree + @refs |
+| **browse snapshot -i** | **14.1 KB** | **~3,614** | **Interactive + @refs** |
+| browse links | 14.0 KB | ~3,587 | Text → URL |
+| browse forms | 305 B | ~76 | Structured JSON |
+
+#### PDP
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 39.3 KB | ~10,071 | Full snapshot auto-dumped |
+| Playwright page.content() | 1.48 MB | ~387,614 | Raw HTML |
+| browse goto | 101 B | ~25 | One-liner |
+| browse text | 6.9 KB | ~1,767 | Clean visible text |
+| browse snapshot | 33.2 KB | ~8,508 | Full tree + @refs |
+| **browse snapshot -i** | **12.0 KB** | **~3,084** | **Interactive + @refs** |
+| browse links | 12.5 KB | ~3,203 | Text → URL |
+| browse forms | 545 B | ~136 | Structured JSON |
+
+### amazon.com
+
+#### Homepage
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 40.7 KB | ~10,431 | Full snapshot auto-dumped |
+| Playwright page.content() | 584.2 KB | ~149,544 | Raw HTML |
+| browse goto | 41 B | ~10 | One-liner |
+| browse text | 4.7 KB | ~1,192 | Clean visible text |
+| browse snapshot | 19.6 KB | ~5,008 | Full tree + @refs |
+| **browse snapshot -i** | **8.4 KB** | **~2,150** | **Interactive + @refs** |
+| browse links | 38.5 KB | ~9,853 | Text → URL |
+| browse forms | 4.2 KB | ~1,075 | Structured JSON |
+
+#### Search
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 76.0 KB | ~19,458 | Full snapshot auto-dumped |
+| Playwright page.content() | 673.5 KB | ~172,417 | Raw HTML |
+| browse goto | 59 B | ~15 | One-liner |
+| browse text | 8.1 KB | ~2,069 | Clean visible text |
+| browse snapshot | 29.1 KB | ~7,446 | Full tree + @refs |
+| **browse snapshot -i** | **14.2 KB** | **~3,644** | **Interactive + @refs** |
+| browse links | 49.7 KB | ~12,712 | Text → URL |
+| browse forms | 5.4 KB | ~1,377 | Structured JSON |
+
+### ebay.com
+
+#### Homepage
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 18.1 KB | ~4,641 | Full snapshot auto-dumped |
+| Playwright page.content() | 1.70 MB | ~445,637 | Raw HTML |
+| browse goto | 39 B | ~10 | One-liner |
+| browse text | 4.9 KB | ~1,245 | Clean visible text |
+| browse snapshot | 10.6 KB | ~2,715 | Full tree + @refs |
+| **browse snapshot -i** | **6.1 KB** | **~1,557** | **Interactive + @refs** |
+| browse links | 29.4 KB | ~7,533 | Text → URL |
+| browse forms | 3.9 KB | ~1,006 | Structured JSON |
+
+#### Search
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 140.3 KB | ~35,929 | Full snapshot auto-dumped |
+| Playwright page.content() | 1.26 MB | ~331,247 | Raw HTML |
+| browse goto | 69 B | ~17 | One-liner |
+| browse text | 17.7 KB | ~4,526 | Clean visible text |
+| browse snapshot | 57.6 KB | ~14,750 | Full tree + @refs |
+| **browse snapshot -i** | **27.7 KB** | **~7,088** | **Interactive + @refs** |
+| browse links | 61.9 KB | ~15,851 | Text → URL |
+| browse forms | 4.4 KB | ~1,124 | Structured JSON |
+
+#### PDP
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 5.1 KB | ~1,294 | Full snapshot auto-dumped |
+| Playwright page.content() | 1.07 MB | ~279,725 | Raw HTML |
+| browse goto | 56 B | ~14 | One-liner |
+| browse text | 1.2 KB | ~315 | Clean visible text |
+| browse snapshot | 3.5 KB | ~889 | Full tree + @refs |
+| **browse snapshot -i** | **2.6 KB** | **~678** | **Interactive + @refs** |
+| browse links | 7.6 KB | ~1,934 | Text → URL |
+| browse forms | 3.9 KB | ~1,006 | Structured JSON |
+
+### nike.com
+
+#### Homepage
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 9.7 KB | ~2,495 | Full snapshot auto-dumped |
+| Playwright page.content() | 700.4 KB | ~179,315 | Raw HTML |
+| browse goto | 39 B | ~10 | One-liner |
+| browse text | 2.4 KB | ~607 | Clean visible text |
+| browse snapshot | 5.1 KB | ~1,315 | Full tree + @refs |
+| **browse snapshot -i** | **3.2 KB** | **~816** | **Interactive + @refs** |
+| browse links | 30.2 KB | ~7,744 | Text → URL |
+| browse forms | 1.3 KB | ~341 | Structured JSON |
+
+#### Search
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 31.2 KB | ~7,998 | Full snapshot auto-dumped |
+| Playwright page.content() | 1.08 MB | ~282,582 | Raw HTML |
+| browse goto | 57 B | ~14 | One-liner |
+| browse text | 5.9 KB | ~1,502 | Clean visible text |
+| browse snapshot | 16.2 KB | ~4,152 | Full tree + @refs |
+| **browse snapshot -i** | **10.5 KB** | **~2,678** | **Interactive + @refs** |
+| browse links | 26.6 KB | ~6,798 | Text → URL |
+| browse forms | 291 B | ~73 | Structured JSON |
+
+#### PDP
+
+| Approach | Size | ~Tokens | Notes |
+|----------|-----:|--------:|-------|
+| @playwright/mcp navigate | 11.9 KB | ~3,034 | Full snapshot auto-dumped |
+| Playwright page.content() | 972.4 KB | ~248,945 | Raw HTML |
+| browse goto | 81 B | ~20 | One-liner |
+| browse text | 5.1 KB | ~1,313 | Clean visible text |
+| browse snapshot | 9.0 KB | ~2,314 | Full tree + @refs |
+| **browse snapshot -i** | **3.9 KB** | **~989** | **Interactive + @refs** |
+| browse links | 24.2 KB | ~6,205 | Text → URL |
+| browse forms | 283 B | ~71 | Structured JSON |
+
+## Architectural Differences
+
+| | @playwright/mcp | @ulpi/browse |
+|---|---|---|
+| **Navigate response** | Full snapshot (~5-50K tokens) | One-liner (~15 tokens) |
+| **Click/type response** | Full snapshot (~5-50K tokens) | One-liner (~15 tokens) |
+| **Agent controls output** | No — always gets full dump | Yes — requests what it needs |
+| **Interactive-only filter** | No | `snapshot -i` |
+| **Cursor-interactive detection** | No | `snapshot -C` (cursor:pointer, onclick, tabindex) |
+| **Clean text extraction** | No | `text` command |
+| **Form discovery** | No | `forms` command |
+| **Link extraction** | No | `links` command |
+| **Network/console logs** | console_messages only | `network` + `console` |
+| **Performance timing** | No | `perf` command |
+| **Cookies/storage** | No | `cookies` + `storage` |
+| **Snapshot diff** | No | `snapshot-diff` |
+| **Page text diff** | No | `diff <url1> <url2>` |
+| **Responsive screenshots** | No | `responsive` (3 viewports) |
+| **Persistent daemon** | No — new browser per session | Yes — ~100ms per command |
+| **Crash recovery** | No | Auto-restart with safe retry |
+| **Total commands** | ~15 tools | 40+ commands |
+
+## Methodology
+
+- Token estimates: ~4 chars per token (standard approximation)
+- @playwright/mcp: simulated by calling `ariaSnapshot()` after navigation (identical to what the MCP server does internally)
+- All pages loaded with `waitUntil: domcontentloaded` + 2.5s settle
+- Pages returning < 200 bytes excluded (bot detection)
+- Measured 2026-03-15, Playwright 1.58.2, Chromium headless
+- Rerun: `bun run benchmark.ts`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ciprian Hacman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,324 @@
+# @ulpi/browse
+
+**The headless browser CLI built for AI agents — not humans.**
+
+When AI agents browse the web, the bottleneck isn't Chromium — it's **what gets dumped into the context window**. [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) sends the full accessibility snapshot on every navigate, click, and keystroke. On a real e-commerce page, that's **~16,000 tokens per action** — automatically, whether the agent needs it or not.
+
+Ten actions and you've burned **146K tokens — 73% of a 200K context window** — just on browser output. That leaves almost nothing for the agent to actually think.
+
+`@ulpi/browse` flips this. Navigation returns 11 tokens. Clicks return 15 tokens. The agent requests a page snapshot **only when it needs one** — and can filter to interactive elements only, cutting another 2-6x.
+
+**Same 10 actions: ~11K tokens. 6% of context. 13x less than @playwright/mcp.**
+
+## Benchmarks (Measured)
+
+Tested on 4 e-commerce sites (mumzworld, amazon, ebay, nike) across homepage, search results, and product detail pages ([raw data](BENCHMARKS.md)):
+
+| Site | Page | @playwright/mcp navigate | browse snapshot -i | Reduction |
+|------|------|-------------------------:|-------------------:|----------:|
+| mumzworld.com | Homepage | ~51,151 | ~15,072 | **3x** |
+| mumzworld.com | Search | ~13,860 | ~3,614 | **4x** |
+| mumzworld.com | PDP | ~10,071 | ~3,084 | **3x** |
+| amazon.com | Homepage | ~10,431 | ~2,150 | **5x** |
+| amazon.com | Search | ~19,458 | ~3,644 | **5x** |
+| ebay.com | Homepage | ~4,641 | ~1,557 | **3x** |
+| ebay.com | Search | ~35,929 | ~7,088 | **5x** |
+| ebay.com | PDP | ~1,294 | ~678 | **2x** |
+| nike.com | Homepage | ~2,495 | ~816 | **3x** |
+| nike.com | Search | ~7,998 | ~2,678 | **3x** |
+| nike.com | PDP | ~3,034 | ~989 | **3x** |
+| **TOTAL** | **11 pages** | **~160,362** | **~41,370** | **4x** |
+
+And that's the per-snapshot comparison. The real gap is architectural — @playwright/mcp dumps a snapshot on every action (navigate, click, type). `browse` only returns ~15 tokens per action:
+
+| | @playwright/mcp | @ulpi/browse |
+|---|---:|---:|
+| Tokens on `navigate` | ~14,578 (auto-dumped) | **~11** (one-liner) |
+| Tokens on `click` | ~14,578 (auto-dumped) | **~15** (one-liner) |
+| 10-action session | ~145,780 | **~11,388** |
+| Context consumed (200K) | **73%** | **6%** |
+
+The agent decides when to see the page. Most actions don't need a snapshot.
+
+Rerun: `bun run benchmark`
+
+## Why It's Faster
+
+### 1. You Control What Enters the Context
+
+```
+@playwright/mcp browser_navigate → 51,150 tokens (full snapshot, every time)
+
+browse goto    →     11 tokens  ("Navigated to https://... (200)")
+browse text    →  4,970 tokens  (clean visible text, when you need it)
+browse snap -i → 15,072 tokens  (interactive elements + refs, when you need it)
+```
+
+You pick the right view for the task. Reading prices? Use `text`. Need to click something? Use `snapshot -i`. Just navigating? `goto` is enough.
+
+### 2. Ref-Based Interaction — No Selector Construction
+
+After `snapshot`, every element gets a ref (`@e1`, `@e2`, ...) backed by a Playwright Locator. The agent doesn't waste tokens constructing CSS selectors:
+
+```bash
+$ browse snapshot -i
+@e1 [button] "Help 24/7"
+@e2 [link] "Mumzworld"
+  @e3 [searchbox]
+@e4 [link] "Sign In"
+@e5 [link] "Cart"
+
+$ browse fill @e3 "strollers"
+Filled @e3
+
+$ browse press Enter
+Pressed Enter
+```
+
+### 3. Cursor-Interactive Detection — What ARIA Misses
+
+Modern SPAs use `<div onclick>`, `cursor: pointer`, `tabindex`, and `data-action` for interactivity. These are **invisible** to accessibility trees — both @playwright/mcp and raw `ariaSnapshot()` miss them.
+
+```bash
+$ browse snapshot -i -C
+@e1 [button] "Submit"
+@e2 [textbox] "Email"
+
+[cursor-interactive]
+@e3 [div.card] "Add to cart" (cursor:pointer)
+@e4 [span.close] "Close dialog" (onclick)
+@e5 [div.menu] "Open Menu" (data-action)
+```
+
+Every detected element gets a ref. `browse click @e3` just works.
+
+### 4. 40+ Purpose-Built Commands vs Generic Tools
+
+@playwright/mcp has ~15 tools. For anything beyond navigate/click/type, you write JavaScript via `browser_evaluate`. `browse` has purpose-built commands that return structured, minimal output:
+
+| Need | @playwright/mcp | browse |
+|------|----------------|--------|
+| Page text | `browser_evaluate` + custom JS | `text` |
+| Form fields | `browser_evaluate` + custom JS | `forms` → structured JSON |
+| All links | `browser_evaluate` + custom JS | `links` → `Text → URL` |
+| Network log | Not available | `network` |
+| Cookies | Not available | `cookies` |
+| Performance | Not available | `perf` |
+| Page diff | Not available | `diff <url1> <url2>` |
+| Snapshot diff | Not available | `snapshot-diff` |
+| Responsive screenshots | Not available | `responsive` |
+| Device emulation | Not available | `emulate iphone` |
+
+### 5. Persistent Daemon — 100ms Commands
+
+```
+First command:       ~2s  (server + Chromium startup, once)
+Every command after: ~100-200ms  (HTTP to localhost)
+```
+
+@playwright/mcp starts a new browser per MCP session. `browse` keeps the server running across commands with auto-shutdown after 30 min idle. Crash recovery is built in — the CLI detects a dead server and restarts transparently.
+
+### 6. Multi-Agent Sessions — Parallel Browsing on One Chromium
+
+Run multiple AI agents in parallel, each with its own isolated browser session, sharing a single Chromium process. Each session gets its own tabs, refs, cookies, localStorage, and console/network buffers — zero cross-talk.
+
+```bash
+# Agent A researches strollers on mumzworld
+browse --session agent-a goto https://www.mumzworld.com
+browse --session agent-a snapshot -i
+browse --session agent-a fill @e3 "strollers"
+browse --session agent-a press Enter
+
+# Agent B checks competitor pricing on amazon — simultaneously
+browse --session agent-b goto https://www.amazon.com
+browse --session agent-b snapshot -i
+browse --session agent-b fill @e6 "baby stroller"
+browse --session agent-b press Enter
+
+# Or set once via env var
+export BROWSE_SESSION=agent-a
+browse text    # runs in agent-a's session
+```
+
+Under the hood, each session is a separate Playwright `BrowserContext` on the shared Chromium — same isolation model as browser profiles (separate cookies, storage, cache). One process, no extra memory for multiple Chromium instances.
+
+```
+browse --session <id> <command>
+          │
+    Persistent server (one Chromium process)
+          │
+    SessionManager
+    ├── "default"  → BrowserContext → tabs, refs, cookies, buffers
+    ├── "agent-a"  → BrowserContext → tabs, refs, cookies, buffers
+    └── "agent-b"  → BrowserContext → tabs, refs, cookies, buffers
+```
+
+**Session management:**
+```bash
+browse sessions                # list active sessions with tab counts
+browse session-close agent-a   # close a session (frees its tabs/context)
+browse status                  # shows total session count
+```
+
+Sessions auto-close after the idle timeout (default 30 min). The server shuts down when all sessions are idle. Without `--session`, everything runs in a `"default"` session — fully backward compatible.
+
+For full process isolation (separate Chromium instances), use `BROWSE_PORT` to run independent servers.
+
+## Install
+
+```bash
+bun install -g @ulpi/browse
+```
+
+Requires [Bun](https://bun.sh). Chromium is installed automatically via Playwright.
+
+### Claude Code Skill (optional)
+
+Install the browse skill into your project so Claude Code uses it automatically:
+
+```bash
+browse install-skill
+```
+
+This copies the skill definition to `.claude/skills/browse/SKILL.md` and adds all browse commands to `.claude/settings.json` permissions — no more approval prompts.
+
+## Real-World Example: E-Commerce Flow
+
+Agent browses mumzworld.com — search, find a product, add to cart, checkout:
+
+```bash
+browse goto https://www.mumzworld.com
+browse snapshot -i                    # find searchbox → @e3
+browse fill @e3 "strollers"
+browse press Enter
+
+browse text                           # scan prices in results
+browse goto "https://www.mumzworld.com/en/doona-infant-car-seat..."
+
+browse snapshot -i                    # find Add to Cart → @e54
+browse click @e54
+
+browse snapshot -i -s "[role=dialog]" # scope to cart modal
+browse click @e3                      # "View Cart"
+
+browse snapshot -i                    # find Checkout → @e52
+browse click @e52
+```
+
+**12 steps. ~24K tokens total.** With @playwright/mcp: **~240K tokens** for the same flow (every action dumps a full snapshot).
+
+## Command Reference
+
+### Navigation
+`goto <url>` | `back` | `forward` | `reload` | `url`
+
+### Content Extraction
+`text` | `html [sel]` | `links` | `forms` | `accessibility`
+
+### Interaction
+`click <sel>` | `fill <sel> <val>` | `select <sel> <val>` | `hover <sel>` | `type <text>` | `press <key>` | `scroll [sel]` | `wait <sel>` | `viewport <WxH>`
+
+### Snapshot & Refs
+```
+snapshot [-i] [-c] [-C] [-d N] [-s sel]
+  -i    Interactive elements only (buttons, links, inputs)
+  -c    Compact — remove empty structural nodes
+  -C    Cursor-interactive — detect hidden clickable elements
+  -d N  Limit tree depth
+  -s    Scope to CSS selector
+```
+After snapshot, use `@e1`, `@e2`... as selectors in any command.
+
+### Snapshot Diff
+`snapshot-diff` — compare current page against last snapshot.
+
+### Device Emulation
+`emulate <device>` | `emulate reset` | `devices [filter]`
+
+100+ devices: iPhone 12-17, Pixel 5-7, iPad, Galaxy, and all Playwright built-ins.
+
+### Inspection
+`js <expr>` | `eval <file>` | `css <sel> <prop>` | `attrs <sel>` | `state <sel>` | `console [--clear]` | `network [--clear]` | `cookies` | `storage [set <k> <v>]` | `perf`
+
+### Visual
+`screenshot [path]` | `screenshot --annotate` | `pdf [path]` | `responsive [prefix]`
+
+### Compare
+`diff <url1> <url2>` — text diff between two pages.
+
+### Multi-Step
+```bash
+echo '[["goto","https://example.com"],["text"]]' | browse chain
+```
+
+### Tabs
+`tabs` | `tab <id>` | `newtab [url]` | `closetab [id]`
+
+### Sessions
+`sessions` | `session-close <id>`
+
+### Server Control
+`status` | `cookie <n>=<v>` | `header <n>:<v>` | `useragent <str>` | `stop` | `restart`
+
+## Architecture
+
+```
+browse [--session <id>] <command>
+          │
+          ▼
+    CLI (thin HTTP client)
+    X-Browse-Session: <id>
+          │
+          ▼
+    Persistent server (localhost, auto-started)
+          │
+    SessionManager
+    ├── Session "default" → BrowserContext + tabs + refs + buffers
+    ├── Session "agent-a" → BrowserContext + tabs + refs + buffers
+    └── Session "agent-b" → BrowserContext + tabs + refs + buffers
+          │
+          ▼
+    Chromium (Playwright, headless, shared)
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BROWSE_PORT` | auto 9400-10400 | Fixed server port |
+| `BROWSE_SESSION` | (none) | Default session ID for all commands |
+| `BROWSE_IDLE_TIMEOUT` | 1800000 (30m) | Idle shutdown in ms |
+| `BROWSE_LOCAL_DIR` | `.browse/` or `/tmp` | State/log directory |
+
+## Acknowledgments
+
+Inspired by and originally derived from the `/browse` skill in [gstack](https://github.com/garrytan/gstack) by Garry Tan. The core architecture — persistent Chromium daemon, thin CLI client, ref-based element selection via ARIA snapshots — comes from gstack.
+
+### Added beyond gstack
+
+**New commands:**
+- `emulate` / `devices` — device emulation with 100+ devices (iPhone, Pixel, iPad, custom descriptors)
+- `snapshot -C` — cursor-interactive detection (cursor:pointer, onclick, tabindex, data-action)
+- `snapshot-diff` — before/after comparison with ref-number stripping
+- `dialog` / `dialog-accept` / `dialog-dismiss` — dialog handling with prompt value support
+- `state` — element state inspection (visible, enabled, checked, focused, bounding box)
+- `upload` — file upload to input elements
+- `sessions` / `session-close` — multi-agent session multiplexing
+- `screenshot --annotate` — numbered badge overlay with legend
+
+**Architectural improvements:**
+- Session multiplexing — multiple agents share one Chromium via isolated BrowserContexts
+- Per-tab ref scoping — refs belong to the tab that created them, cross-tab usage throws clear error
+- Per-tab snapshot baselines — `snapshot-diff` compares the correct baseline after tab switches
+- Safe retry classification — read commands auto-retry after crash, write commands don't (prevents double form submissions)
+- Concurrency-safe server spawning — file lock with stale detection prevents race conditions
+- Network correlation via WeakMap — accurate request/response pairing even with duplicate URLs
+- Content-Length based sizing — avoids reading response bodies into memory
+- TreeWalker text extraction — `text` command never triggers MutationObservers
+- Tab creation rollback — failed `newTab(url)` closes the page instead of leaving orphan tabs
+- Context recreation with rollback — `emulate`/`useragent` preserve cookies and all tab URLs, rollback on failure
+- Crash callback — server flushes buffers and cleans state file before exit
+
+## License
+
+MIT

package/bin/browse.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/cli';

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ulpi/browse",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ulpi-io/browse"
+  },
+  "dependencies": {
+    "diff": "^7.0.0",
+    "playwright": "^1.58.2"
+  },
+  "bin": {
+    "browse": "bin/browse.ts"
+  },
+  "description": "Fast headless browser CLI — persistent Chromium daemon via Playwright.",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skill/",
+    "LICENSE",
+    "README.md",
+    "BENCHMARKS.md"
+  ],
+  "keywords": [
+    "browser",
+    "automation",
+    "playwright",
+    "headless",
+    "cli",
+    "ai-agent",
+    "claude"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "bun build --compile src/cli.ts --outfile dist/browse",
+    "dev": "bun run src/cli.ts",
+    "server": "bun run src/server.ts",
+    "test": "bun test",
+    "start": "bun run src/server.ts",
+    "postinstall": "bunx playwright install chromium",
+    "benchmark": "bun run benchmark.ts"
+  }
+}