@ulpi/browse 1.0.6 → 1.3.0

package/skill/references/commands.md

@@ -0,0 +1,482 @@
+# browse — Full Command Reference
+
+Read this file when you need command syntax not covered in the SKILL.md Quick Reference, or need exact flags for a specific command category.
+
+## Quick Reference (all examples)
+
+```bash
+# Navigate to a page
+browse goto https://example.com
+
+# Read cleaned page text
+browse text
+
+# Take a screenshot (saved to .browse/sessions/default/screenshot.png)
+browse screenshot
+
+# Snapshot: accessibility tree with refs
+browse snapshot -i
+
+# Click by ref (after snapshot)
+browse click @e3
+
+# Fill by ref
+browse fill @e4 "test@test.com"
+
+# Double-click, focus, check/uncheck
+browse dblclick @e3
+browse focus @e5
+browse check @e7
+browse uncheck @e7
+
+# Drag and drop
+browse drag @e1 @e2
+
+# Run JavaScript
+browse js "document.title"
+
+# Get all links
+browse links
+
+# Get input value / count elements
+browse value "[id=email]"
+browse count ".search-result"
+
+# Click by CSS selector
+browse click "button.submit"
+
+# Fill a form by CSS selector (use [id=...] instead of # to avoid shell issues)
+browse fill "[id=email]" "test@test.com"
+browse fill "[id=password]" "abc123"
+browse click "button[type=submit]"
+
+# Scroll
+browse scroll up
+browse scroll down
+browse scroll "[id=target]"
+
+# Wait for navigation or network
+browse wait ".loaded"
+browse wait --url "**/dashboard"
+browse wait --network-idle
+
+# iframe targeting
+browse frame "[id=my-iframe]"
+browse text                    # reads from inside the iframe
+browse click @e3               # clicks inside the iframe
+browse frame main              # back to main page
+
+# Highlight an element (visual debugging)
+browse highlight @e5
+
+# Download a file
+browse download @e3 ./file.pdf
+
+# Network mocking
+browse route "**/*.png" block
+browse route "**/api/data" fulfill 200 '{"mock":true}'
+browse route clear
+
+# Offline mode
+browse offline on
+browse offline off
+
+# JSON output mode
+browse --json goto https://example.com
+
+# Security: content boundaries
+browse --content-boundaries text
+
+# Security: domain restriction
+browse --allowed-domains example.com,*.cdn.example.com goto https://example.com
+
+# State persistence
+browse state save mysite
+browse state load mysite
+browse state clean                    # delete states older than 7 days
+browse state clean --older-than 30    # custom threshold
+
+# Cookie management
+browse cookie clear                                      # clear all cookies
+browse cookie set auth token --domain .example.com       # set with options
+browse cookie export ./cookies.json                      # export to file
+browse cookie import ./cookies.json                      # import from file
+
+# Cookie import from real browsers (macOS -- Chrome, Arc, Brave, Edge)
+browse cookie-import --list                              # show installed browsers
+browse cookie-import chrome --domain .example.com        # import cookies for a domain
+browse cookie-import arc --domain .github.com            # import from Arc
+browse cookie-import chrome --profile "Profile 1" --domain .site.com  # specific Chrome profile
+
+# Session auto-persistence (named sessions survive restarts)
+browse --session myapp goto https://app.com/login        # login...
+browse session-close myapp                               # state auto-saved (encrypted if BROWSE_ENCRYPTION_KEY set)
+browse --session myapp goto https://app.com/dashboard    # cookies auto-restored
+
+# Persistent profiles (full browser state, own Chromium)
+browse --profile mysite goto https://app.com       # all state persists automatically
+browse --profile mysite snapshot -i                 # still logged in next time
+browse profile list                                 # list all profiles with size
+browse profile delete old-site                      # remove a profile
+
+# Load state at launch
+browse --state auth.json goto https://app.com            # load cookies before first command
+
+# Auth vault (credentials never visible to LLM)
+browse auth save github https://github.com/login user pass123
+browse auth login github
+
+# HAR recording
+browse har start
+browse goto https://example.com
+browse har stop ./recording.har
+
+# Video recording (watch a .webm of the session)
+browse video start ./videos
+browse goto https://example.com
+browse click @e3
+browse video stop
+
+# Command recording (export replayable scripts)
+browse record start
+browse goto https://example.com
+browse click "a"
+browse fill "[id=search]" "test query"
+browse record stop
+browse record export replay ./recording.json    # replay with: npx @puppeteer/replay ./recording.json
+browse record export browse ./steps.json        # replay with: cat steps.json | browse chain
+
+# Both together (video + replayable script)
+browse video start ./videos
+browse record start
+browse goto https://example.com
+browse snapshot -i
+browse click @e3
+browse fill "[id=email]" "user@test.com"
+browse record stop
+browse video stop
+browse record export replay ./recording.json
+
+# Device emulation
+browse emulate iphone
+browse emulate reset
+
+# Parallel sessions
+browse --session agent-a goto https://site1.com
+browse --session agent-b goto https://site2.com
+
+# Clipboard
+browse clipboard
+browse clipboard write "copied text"
+
+# Find elements semantically
+browse find role button
+browse find text "Submit"
+browse find testid "login-btn"
+
+# Screenshot diff (visual regression)
+browse screenshot-diff baseline.png current.png
+
+# Headed mode (visible browser)
+browse --headed goto https://example.com
+
+# Handoff (human takeover for CAPTCHA/MFA -- see guides.md for protocol)
+browse handoff "stuck on CAPTCHA"
+browse resume
+
+# React debugging
+browse react-devtools enable
+browse react-devtools tree
+browse react-devtools props @e3
+browse react-devtools suspense
+browse react-devtools disable
+
+# Stealth mode (bypasses bot detection)
+browse --runtime rebrowser goto https://example.com
+
+# State list / show
+browse state list
+browse state show mysite
+```
+
+## Navigation
+```
+browse goto <url>         Navigate current tab
+browse back               Go back
+browse forward            Go forward
+browse reload             Reload page
+browse url                Print current URL
+```
+
+## Content extraction
+```
+browse text               Cleaned page text (no scripts/styles)
+browse html [selector]    innerHTML of element, or full page HTML
+browse links              All links as "text -> href"
+browse forms              All forms + fields as JSON
+browse accessibility      Accessibility tree snapshot (ARIA)
+```
+
+## Snapshot (ref-based element selection)
+```
+browse snapshot           Full accessibility tree with @refs
+browse snapshot -i        Interactive elements only -- terse flat list (minimal tokens)
+browse snapshot -i -f     Interactive elements -- full indented tree with props
+browse snapshot -i -V     Interactive elements -- viewport only (skip below-fold)
+browse snapshot -c        Compact (no empty structural elements)
+browse snapshot -C        Cursor-interactive (detect divs with cursor:pointer/onclick/tabindex)
+browse snapshot -d <N>    Limit depth to N levels
+browse snapshot -s <sel>  Scope to CSS selector
+browse snapshot-diff      Compare current vs previous snapshot
+```
+
+After snapshot, use @refs as selectors in any command:
+```
+browse click @e3          Click the element assigned ref @e3
+browse fill @e4 "value"   Fill the input assigned ref @e4
+browse hover @e1          Hover the element assigned ref @e1
+browse html @e2           Get innerHTML of ref @e2
+browse css @e5 "color"    Get computed CSS of ref @e5
+browse attrs @e6          Get attributes of ref @e6
+```
+
+Refs are invalidated on navigation -- run `snapshot` again after `goto`.
+
+## Interaction
+```
+browse click <selector>        Click element (CSS selector or @ref)
+browse click <x>,<y>           Click at page coordinates (e.g. 590,461)
+browse rightclick <selector>   Right-click element (context menu)
+browse dblclick <selector>     Double-click element
+browse fill <selector> <value> Fill input field
+browse select <selector> <val> Select dropdown value
+browse hover <selector>        Hover over element
+browse focus <selector>        Focus element
+browse tap <selector>          Tap element (requires touch context via emulate)
+browse check <selector>        Check checkbox
+browse uncheck <selector>      Uncheck checkbox
+browse drag <src> <tgt>        Drag source to target
+browse type <text>             Type into focused element
+browse press <key>             Press key (Enter, Tab, Escape, etc.)
+browse keydown <key>           Hold key down
+browse keyup <key>             Release key
+browse keyboard inserttext <t> Insert text without key events
+browse scroll [sel|up|down]    Scroll element/viewport/bottom
+browse scrollinto <sel>        Scroll element into view (explicit)
+browse scrollintoview <sel>    Alias for scrollinto
+browse swipe <dir> [px]        Swipe up/down/left/right (touch events)
+browse mouse move <x> <y>     Move mouse to coordinates
+browse mouse down [button]     Press mouse button (left/right/middle)
+browse mouse up [button]       Release mouse button
+browse mouse wheel <dy> [dx]   Scroll wheel
+browse wait <sel>              Wait for element to appear
+browse wait <sel> --state hidden  Wait for element to disappear
+browse wait <ms>               Wait for milliseconds
+browse wait --text "..."       Wait for text to appear in page
+browse wait --fn "expr"        Wait for JavaScript condition
+browse wait --load <state>     Wait for load state
+browse wait --url <pattern>    Wait for URL match
+browse wait --network-idle     Wait for network idle
+browse wait --download                    Wait for download, return temp path
+browse wait --download ./report.pdf       Wait and save to path
+browse wait --download 60000              Custom timeout (ms)
+browse wait --download ./file.pdf 60000   Both path and timeout
+browse set geo <lat> <lng>     Set geolocation
+browse set media <scheme>      Set color scheme (dark/light/no-preference)
+browse header <name>:<value>   Set request header
+browse useragent <string>      Set user agent string
+browse viewport <WxH>          Set viewport size (e.g. 375x812)
+browse upload <sel> <files>    Upload file(s) to a file input
+browse highlight <selector>    Highlight element (visual debugging)
+browse download <sel> [path]   Download file triggered by click
+browse dialog-accept [value]   Set dialogs to auto-accept
+browse dialog-dismiss          Set dialogs to auto-dismiss (default)
+browse emulate <device>        Emulate device (iphone, pixel, etc.)
+browse emulate reset           Reset to desktop (1920x1080)
+browse offline [on|off]        Toggle offline mode
+```
+
+## Cookies
+```
+browse cookie <n>=<v>                  Set cookie (shorthand)
+browse cookie set <n> <v> [--domain d --secure]  Set cookie with options
+browse cookie clear                    Clear all cookies
+browse cookie export <file>            Export cookies to JSON file
+browse cookie import <file>            Import cookies from JSON file
+```
+
+## Network
+```
+browse route <pattern> block           Block matching requests
+browse route <pattern> fulfill <s> [b] Mock with status + body
+browse route clear                     Remove all routes
+```
+
+## Inspection
+```
+browse js <expression>         Run JS, print result
+browse eval <js-file>          Run JS file against page
+browse css <selector> <prop>   Get computed CSS property
+browse attrs <selector>        Get element attributes as JSON
+browse element-state <selector> Element state (visible/enabled/checked/focused)
+browse value <selector>        Get input field value
+browse count <selector>        Count matching elements
+browse box <selector>          Get bounding box as JSON {x, y, width, height}
+browse dialog                  Last dialog info or "(no dialog detected)"
+browse console [--clear]       View/clear console messages
+browse errors [--clear]        View/clear page errors (filtered from console)
+browse network [--clear]       View/clear network requests
+browse cookies                 Dump all cookies as JSON
+browse storage [set <k> <v>]   View/set localStorage
+browse perf                    Page load performance timings
+browse devices [filter]        List available device names
+browse clipboard               Read system clipboard text
+browse clipboard write <text>  Write text to system clipboard
+```
+
+## Visual
+```
+browse screenshot [path]              Viewport screenshot (default: .browse/sessions/{id}/screenshot.png)
+browse screenshot --full [path]       Full-page screenshot (entire scrollable page)
+browse screenshot <sel|@ref> [path]   Screenshot specific element
+browse screenshot --clip x,y,w,h [path]  Screenshot clipped region
+browse screenshot --annotate [path]   Screenshot with numbered badges + legend
+browse pdf [path]                     Save as PDF
+browse responsive [prefix]            Screenshots at mobile/tablet/desktop
+```
+
+## Frames (iframe targeting)
+```
+browse frame <selector>        Target an iframe (subsequent commands run inside it)
+browse frame main              Return to main page
+```
+
+## Find (semantic element locators)
+```
+browse find role <query>              Find elements by ARIA role
+browse find text <query>              Find elements by text content
+browse find label <query>             Find elements by label
+browse find placeholder <query>       Find elements by placeholder
+browse find testid <query>            Find elements by test ID
+browse find alt <query>               Find elements by alt text
+browse find title <query>             Find elements by title attribute
+browse find first <sel>               First matching element
+browse find last <sel>                Last matching element
+browse find nth <n> <sel>             Nth matching element (0-indexed)
+```
+
+## Compare
+```
+browse diff <url1> <url2>             Text diff between two pages
+browse screenshot-diff <base> [curr]  Pixel-diff two PNG screenshots
+```
+
+## Multi-step (chain)
+```
+echo '[["goto","https://example.com"],["snapshot","-i"],["click","@e1"]]' | browse chain
+```
+
+## Tabs
+```
+browse tabs                    List tabs (id, url, title)
+browse tab <id>                Switch to tab
+browse newtab [url]            Open new tab
+browse closetab [id]           Close tab
+```
+
+## Sessions (parallel agents)
+```
+browse --session <id> <cmd>    Run command in named session
+browse sessions                List active sessions
+browse session-close <id>      Close a session
+```
+
+## Profiles
+```
+browse --profile <name> <cmd>             Use persistent browser profile
+browse profile list                       List profiles with disk size
+browse profile delete <name>              Delete a profile
+browse profile clean [--older-than <d>]   Remove old profiles (default: 7 days)
+```
+
+## State persistence
+```
+browse state save [name]       Save cookies + localStorage (all origins)
+browse state load [name]       Restore saved state
+browse state list              List saved states
+browse state show [name]       Show contents of saved state
+browse state clean             Delete states older than 7 days
+browse state clean --older-than N   Custom age threshold (days)
+```
+
+## Cookie import (macOS -- borrow auth from real browsers)
+```
+browse cookie-import --list                         List installed browsers
+browse cookie-import <browser> --domain <d>         Import cookies for a domain
+browse cookie-import <browser> --profile <p> --domain <d>   Specific Chrome profile
+```
+
+## Auth vault
+```
+browse auth save <name> <url> <user> <pass|--password-stdin>   Save credentials (encrypted)
+browse auth login <name>                       Auto-login using saved credentials
+browse auth list                               List saved credentials
+browse auth delete <name>                      Delete credentials
+```
+
+## HAR recording
+```
+browse har start               Start recording network traffic
+browse har stop [path]         Stop and save HAR file
+```
+
+## Video recording
+```
+browse video start [dir]       Start recording video (WebM, compositor-level)
+browse video stop              Stop recording and save video files
+browse video status            Check if recording is active
+```
+
+## Command recording & export
+```
+browse record start                    Start recording commands
+browse record stop                     Stop recording, keep steps for export
+browse record status                   Recording state and step count
+browse record export browse [path]     Export as chain-compatible JSON (replay with browse chain)
+browse record export replay [path]    Export as Chrome DevTools Recorder (Playwright/Puppeteer)
+```
+
+## React DevTools
+```
+browse react-devtools enable           Enable React DevTools (downloads hook, injects, reloads)
+browse react-devtools disable          Disable React DevTools
+browse react-devtools tree             Component tree with indentation
+browse react-devtools props <sel>      Props/state/hooks of component at element
+browse react-devtools suspense         Suspense boundaries + status
+browse react-devtools errors           Error boundaries + caught errors
+browse react-devtools profiler         Render timing per component
+browse react-devtools hydration        Hydration timing (Next.js)
+browse react-devtools renders          What re-rendered since last commit
+browse react-devtools owners <sel>     Parent component chain
+browse react-devtools context <sel>    Context values consumed by component
+```
+
+## Server management
+```
+browse status                  Server health, uptime, session count
+browse instances               List all running browse servers (instance, PID, port, status)
+browse version                 Print CLI version
+browse doctor                  System check (Node, Playwright, Chromium)
+browse upgrade                 Self-update via npm
+browse stop                    Shutdown server
+browse restart                 Kill + restart server
+browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
+```
+
+## Handoff (human takeover)
+```
+browse handoff [reason]        Swap to visible browser for user to solve CAPTCHA/MFA
+browse resume                  Swap back to headless, returns fresh snapshot
+```
+
+See [guides.md](guides.md) for the mandatory handoff protocol.

package/skill/references/guides.md

@@ -0,0 +1,178 @@
+# browse — Operational Guides
+
+Read this file when you need the handoff protocol, optimization tips, or help choosing which command to use.
+
+## Handoff Protocol (MANDATORY)
+
+Read this section when you hit CAPTCHA, MFA, OAuth, or any blocker after 2-3 failed attempts. The server auto-suggests handoff after 3 consecutive failures (look for HINT in error messages).
+
+When the browser hits a blocker you can't solve, you MUST follow this exact 3-step protocol. Do NOT skip any step.
+
+### Step 1 — Ask permission (REQUIRED before handoff)
+
+Use `AskUserQuestion` (or your platform's equivalent interactive prompt tool) to ask
+the user before opening the browser. Do NOT just print text and proceed — you MUST
+wait for an explicit response.
+
+```
+AskUserQuestion:
+  question: "I'm stuck on a CAPTCHA at [URL]. Can I open a visible browser so you can solve it?"
+  options:
+    - label: "Yes, open browser"
+      description: "Opens a visible Chrome window with your current session"
+    - label: "No, try something else"
+      description: "I'll try cookie-import, auth login, or a different approach"
+```
+
+If your platform does not have `AskUserQuestion`, ask the user via text and wait for
+their response before proceeding. Do NOT run handoff without explicit user confirmation.
+
+If the user says no, try `cookie-import`, `auth login`, or a different approach.
+
+### Step 2 — Handoff + wait for user (REQUIRED)
+
+Run the handoff command, then use `AskUserQuestion` (or equivalent) to wait for the
+user to finish:
+
+```bash
+browse handoff "Stuck on CAPTCHA at login page"
+```
+
+Then immediately prompt the user:
+
+```
+AskUserQuestion:
+  question: "Browser is open. Please solve the CAPTCHA, then click Done."
+  options:
+    - label: "Done"
+      description: "I've solved it, return to headless mode"
+    - label: "Cancel"
+      description: "Close the browser, try something else"
+```
+
+Do NOT proceed or do any other work while waiting. The user is interacting with the
+visible browser — wait for their response.
+
+### Step 3 — Resume
+
+After the user responds:
+
+```bash
+browse resume
+# Returns fresh snapshot — continue working with it
+```
+
+If "Done" — continue with the fresh snapshot from resume.
+If "Cancel" — resume anyway (closes headed browser), then try alternative approach.
+
+### When to Handoff
+- CAPTCHA or bot detection blocking progress
+- Multi-factor authentication requiring a physical device
+- OAuth popup that redirects to a third-party login
+- Any blocker after 2-3 failed attempts at the same step
+- The server auto-suggests handoff after 3 consecutive failures (look for HINT in error messages)
+
+### When NOT to Handoff
+- Normal navigation/interaction failures — retry or try a different selector
+- Pages that just need more time to load — use `wait` commands
+- Cookie/auth issues — try `cookie-import` or `auth login` first
+
+### Handoff Rules
+- NEVER run `browse handoff` without asking the user first (Step 1)
+- NEVER proceed without waiting for the user to finish (Step 2)
+- ALWAYS tell the user what they need to do in the visible browser
+- ALWAYS run `browse resume` after the user is done
+
+## Speed Rules
+
+Read this section to optimize your command usage and minimize token consumption.
+
+1. **Navigate once, query many times.** `goto` loads the page; then `text`, `js`, `css`, `screenshot` all run against the loaded page instantly.
+2. **Use `snapshot -i` for interaction.** Get refs for all interactive elements, then click/fill by ref. No need to guess CSS selectors.
+3. **Use `snapshot -C` for SPAs.** Catches cursor:pointer divs and onclick handlers that ARIA misses.
+4. **Use `js` for precision.** `js "document.querySelector('.price').textContent"` is faster than parsing full page text.
+5. **Use `links` to survey.** Faster than `text` when you just need navigation structure.
+6. **Use `chain` for multi-step flows.** Avoids CLI overhead per step.
+7. **Use `responsive` for layout checks.** One command = 3 viewport screenshots.
+8. **Use `--session` for parallel work.** Multiple agents can browse simultaneously without interference.
+9. **Use `value`/`count` instead of `js`.** Purpose-built commands are cleaner than `js "document.querySelector(...).value"`.
+10. **Use `frame` for iframes.** Don't try to reach into iframes with CSS — use `frame [id=x]` first.
+
+## When to Use What
+
+Read this section when you're unsure which command to use for a task.
+
+| Task | Commands |
+|------|----------|
+| Read a page | `goto <url>` then `text` |
+| Interact with elements | `snapshot -i` then `click @e3` |
+| Find hidden clickables | `snapshot -i -C` then `click @e15` |
+| Check if element exists | `count ".thing"` |
+| Get input value | `value "[id=email]"` |
+| Extract specific data | `js "document.querySelector('.price').textContent"` |
+| Visual check | `screenshot` then `Read .browse/sessions/default/screenshot.png` |
+| Fill and submit form | `snapshot -i` then `fill @e4 "val"` then `click @e5` |
+| Check/uncheck boxes | `check @e7` / `uncheck @e7` |
+| Check CSS | `css "selector" "property"` or `css @e3 "property"` |
+| Inspect DOM | `html "selector"` or `attrs @e3` |
+| Debug console errors | `console` |
+| Check network requests | `network` |
+| Mock API responses | `route "**/api/*" fulfill 200 '{"data":[]}'` |
+| Block ads/trackers | `route "**/*.doubleclick.net/*" block` |
+| Test offline behavior | `offline on` then test then `offline off` |
+| Interact in iframe | `frame "[id=payment]"` then `fill @e2 "4242..."` then `frame main` |
+| Check local dev | `goto http://127.0.0.1:3000` |
+| Compare two pages | `diff <url1> <url2>` |
+| Mobile layout check | `responsive .browse/sessions/default/resp` |
+| Test on mobile device | `emulate iphone` then `goto <url>` then `screenshot` |
+| Save/restore session | `state save mysite` / `state load mysite` |
+| Auto-login | `auth save gh https://github.com/login user pass` then `auth login gh` |
+| Record network | `har start` then browse then `har stop ./out.har` |
+| Record video | `video start ./vids` then browse then `video stop` |
+| Export automation script | `record start` then browse then `record export replay ./recording.json` |
+| Parallel agents | `--session agent-a <cmd>` / `--session agent-b <cmd>` |
+| Multi-step flow | `echo '[...]' \| browse chain` |
+| Secure browsing | `--allowed-domains example.com goto https://example.com` |
+| Scroll through results | `scroll down` then `text` then `scroll down` then `text` |
+| Drag and drop | `drag @e1 @e2` |
+| Read/write clipboard | `clipboard` / `clipboard write "text"` |
+| Find by accessibility | `find role button` / `find text "Submit"` |
+| Visual regression | `screenshot-diff baseline.png` |
+| Debug with DevTools | `inspect` (set BROWSE_DEBUG_PORT first) |
+| Get element position | `box @e3` |
+| Check page errors | `errors` |
+| Right-click context menu | `rightclick @e3` |
+| Test mobile gestures | `emulate iphone` then `tap @e1` / `swipe down` |
+| Set dark mode | `set media dark` |
+| Test geolocation | `set geo 37.7 -122.4` then verify in page |
+| Export/import cookies | `cookie export ./cookies.json` / `cookie import ./cookies.json` |
+| Limit output size | `--max-output 5000 text` |
+| See the browser | `browse --headed goto <url>` |
+| CAPTCHA / MFA blocker | `handoff "reason"` then user solves then `resume` (see Handoff Protocol above) |
+| Debug React components | `react-devtools enable` then `tree` then `props @e3` |
+| Debug hydration issues | `react-devtools enable` then `hydration` |
+| Find suspense blockers | `react-devtools enable` then `suspense` |
+| Bypass bot detection | `--runtime rebrowser goto <url>` |
+| Persistent login state | `--profile mysite` then browse then close then reopen (still logged in) |
+| Cloud browser (CI/CD) | `provider save browserbase <key>` then `--provider browserbase goto <url>` |
+
+## Architecture
+
+Read this section to understand the system design.
+
+- Persistent Chromium daemon on localhost (port 9400-10400)
+- Bearer token auth per session
+- One server per project directory — `--session` handles agent isolation
+- Session multiplexing: multiple agents share one Chromium via isolated BrowserContexts
+- For separate servers: set `BROWSE_INSTANCE` env var (e.g., fault isolation between teams)
+- `browse instances` — discover all running servers (PID, port, status, session count)
+- Project-local state: `.browse/` directory at project root (auto-created, self-gitignored)
+  - `sessions/{id}/` — per-session screenshots, logs, PDFs
+  - `states/{name}.json` — saved browser state (cookies + localStorage)
+  - `browse-server.json` — server PID, port, auth token
+- Auto-shutdown when all sessions idle past 30 min
+- Chromium crash — server exits — auto-restarts on next command
+- AI-friendly error messages: Playwright errors rewritten to actionable hints
+- CDP remote connection: `BROWSE_CDP_URL` to connect to existing Chrome
+- Policy enforcement: `browse-policy.json` for allow/deny/confirm rules
+- Two browser engines: playwright (default) and rebrowser (stealth, bypasses bot detection)