@ulpi/browse 1.1.1 → 1.3.1

package/README.md

@@ -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,6 +301,7 @@ 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
@@ -321,11 +323,24 @@ browse react-devtools disable          # Disable
 ### Handoff (Human Takeover)
 
 ```bash
-browse handoff [reason]        # Swap to visible browser for CAPTCHA/MFA/OAuth
+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
 ```
 
-Agent asks permission first via AskUserQuestion, then hands off. Server auto-suggests handoff after 3 consecutive failures.
+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
 
@@ -340,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)
@@ -529,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 |
@@ -540,9 +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 |
-| `--runtime <name>` | Browser runtime: playwright (default), rebrowser (stealth), lightpanda |
+| `--provider <name>` | Cloud browser provider (browserless, browserbase) |
+| `--runtime <name>` | Browser runtime: playwright (default), rebrowser (stealth), lightpanda, chrome |
 
 ## Environment Variables
 
@@ -569,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