@ulpi/browse 1.0.6 → 1.3.0

package/README.md

@@ -10,7 +10,7 @@ Headless browser CLI for AI coding agents. Persistent Chromium daemon via Playwr
 npm install -g @ulpi/browse
 ```
 
-Requires Node.js 18+. Chromium is installed automatically via Playwright on first `npm install`.
+Requires Node.js 18+. Chromium is installed automatically via Playwright on first `npm install`. If [Bun](https://bun.sh) is installed, browse automatically uses it for ~2x faster command execution.
 
 ### Project Installation (local dependency)
 
@@ -143,6 +143,7 @@ browse wait --text "Welcome"   # Wait for text to appear in page
 browse wait --fn "js expr"     # Wait for JavaScript condition
 browse wait --load <state>     # Wait for load state (load/domcontentloaded/networkidle)
 browse wait --network-idle     # Wait for network idle
+browse wait --download [path]  # Wait for download to complete
 ```
 
 ### Snapshot
@@ -300,8 +301,47 @@ browse record stop             # Stop recording
 browse record status           # Check recording status
 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)
+browse record export replay --selectors css,aria [path]  # Filter selector types in export
 ```
 
+### React DevTools
+
+```bash
+browse react-devtools enable           # Enable (downloads hook on first use)
+browse react-devtools tree             # Component tree
+browse react-devtools props <sel>      # Props/state of component
+browse react-devtools suspense         # Suspense boundary status
+browse react-devtools errors           # Error boundaries
+browse react-devtools profiler         # Render timing
+browse react-devtools hydration        # Hydration timing
+browse react-devtools renders          # What re-rendered
+browse react-devtools owners <sel>     # Parent component chain
+browse react-devtools context <sel>    # Context values
+browse react-devtools disable          # Disable
+```
+
+### Handoff (Human Takeover)
+
+```bash
+browse handoff [reason]        # Swap to Chrome for CAPTCHA/MFA/OAuth (falls back to Chromium)
+browse handoff --chromium      # Force Playwright Chromium instead of Chrome
+browse resume                  # Swap back to headless, returns fresh snapshot
+```
+
+Handoff defaults to your system Chrome (bypasses Turnstile and bot detection). Falls back to Playwright Chromium if Chrome is not installed. Agent asks permission first via AskUserQuestion, then hands off. Server auto-suggests handoff after 3 consecutive failures.
+
+### Cloud Providers
+
+```bash
+browse provider save browserbase <api-key>     # Save API key (encrypted)
+browse provider save browserless <token>       # Save token (encrypted)
+browse --provider browserbase goto https://...  # Use cloud browser
+browse provider list                           # List saved providers
+browse provider delete <name>                  # Remove saved key
+```
+
+API keys are encrypted at rest in `.browse/providers/` — never visible to agents.
+
 ### State & Auth
 
 ```bash
@@ -315,6 +355,10 @@ browse auth save <name> <url> <user> --password-stdin  # Password from stdin
 browse auth login <name>       # Auto-login with saved credential
 browse auth list               # List saved credentials
 browse auth delete <name>      # Delete credential
+
+browse cookie-import --list                            # List browsers with cookies
+browse cookie-import chrome [--domain .example.com]    # Import cookies from Chrome
+browse cookie-import chrome --profile "Profile 1"      # Specific browser profile
 ```
 
 ### Multi-Step (Chaining)
@@ -330,6 +374,7 @@ echo '[["goto","https://example.com"],["snapshot","-i"],["text"]]' | browse chai
 ```bash
 browse status                  # Server health report
 browse instances               # List all running browse servers
+browse version                 # Print CLI version
 browse doctor                  # System check (Node, Playwright, Chromium)
 browse upgrade                 # Self-update via npm
 browse stop                    # Stop server
@@ -503,6 +548,61 @@ Core workflow:
 Use browse to test the login flow. Run browse --help to see available commands.
 ```
 
+## MCP Server Mode
+
+Run browse as an [MCP](https://modelcontextprotocol.io/) server for editors that support the Model Context Protocol.
+
+```bash
+browse --mcp
+```
+
+Use `--json` alongside `--mcp` for structured responses (`{success, data, command}`).
+
+> **Note:** Requires `npm install @modelcontextprotocol/sdk` alongside browse.
+
+### Cursor
+
+`.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "browse": {
+      "command": "browse",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "browse": {
+      "command": "browse",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+```json
+{
+  "mcpServers": {
+    "browse": {
+      "command": "browse",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
 ## Options
 
 | Flag | Description |
@@ -514,6 +614,11 @@ Use browse to test the login flow. Run browse --help to see available commands.
 | `--allowed-domains <d,d>` | Block navigation/resources outside allowlist |
 | `--max-output <n>` | Truncate output to N characters |
 | `--headed` | Show browser window (not headless) |
+| `--chrome` | Launch system Chrome (uses real browser, bypasses bot detection) |
+| `--cdp <port>` | Connect to Chrome on a specific debugging port |
+| `--connect` | Auto-discover and connect to a running Chrome instance |
+| `--provider <name>` | Cloud browser provider (browserless, browserbase) |
+| `--runtime <name>` | Browser runtime: playwright (default), rebrowser (stealth), lightpanda, chrome |
 
 ## Environment Variables
 
@@ -540,7 +645,9 @@ Use browse to test the login flow. Run browse --help to see available commands.
 | `BROWSE_CONFIRM_ACTIONS` | (none) | Commands requiring confirmation |
 | `BROWSE_ENCRYPTION_KEY` | auto-generated | 64-char hex AES key for credential vault |
 | `BROWSE_AUTH_PASSWORD` | (none) | Password for `auth save` (alt to `--password-stdin`) |
-| `BROWSE_RUNTIME` | playwright | Browser runtime (playwright, rebrowser, lightpanda) |
+| `BROWSE_RUNTIME` | playwright | Browser runtime (playwright, rebrowser, lightpanda, chrome) |
+| `BROWSE_CHROME` | (none) | Set to `1` to use system Chrome |
+| `BROWSE_CHROME_PATH` | auto-detected | Override Chrome executable path |
 
 ## Architecture