browser-pilot 0.0.12 → 0.0.14

package/README.md

@@ -167,10 +167,10 @@ console.log(snapshot.interactiveElements);
 
 // Text representation for LLMs
 console.log(snapshot.text);
-// - main [ref=e1]
-//   - heading "Welcome" [ref=e2]
-//   - button "Get Started" [ref=e3]
-//   - textbox [ref=e4] placeholder="Email"
+// - main ref:e1
+//   - heading "Welcome" ref:e2
+//   - button "Get Started" ref:e3
+//   - textbox ref:e4 placeholder="Email"
 ```
 
 ### Ref-Based Selectors
@@ -179,7 +179,7 @@ After taking a snapshot, use element refs directly as selectors:
 
 ```typescript
 const snapshot = await page.snapshot();
-// Output shows: button "Submit" [ref=e4]
+// Output shows: button "Submit" ref:e4
 
 // Click using the ref - no fragile CSS needed
 await page.click('ref:e4');
@@ -373,6 +373,8 @@ The CLI provides session persistence for interactive workflows:
 # Connect to a browser
 bp connect --provider browserbase --name my-session
 bp connect --provider generic  # auto-discovers local Chrome
+bp connect --no-daemon          # skip daemon (direct WebSocket only)
+bp connect --daemon-idle 30     # custom idle timeout (minutes)
 
 # Execute actions
 bp exec -s my-session '{"action":"goto","url":"https://example.com"}'
@@ -383,25 +385,38 @@ bp exec -s my-session '[
 
 # Get page state (note the refs in output)
 bp snapshot -s my-session --format text
-# Output: button "Submit" [ref=e4], textbox "Email" [ref=e5], ...
+# Output: button "Submit" ref:e4, textbox "Email" ref:e5, ...
 
 # Use refs from snapshot for reliable targeting
 # Refs are cached per session+URL after snapshot
 bp exec -s my-session '{"action":"click","selector":"ref:e4"}'
 bp exec -s my-session '{"action":"fill","selector":"ref:e5","value":"test@example.com"}'
 
+# Quick discovery commands
+bp page -s my-session          # URL, title, headings, forms, interactive controls
+bp forms -s my-session         # Structured form metadata only
+bp targets -s my-session       # Browser tabs with targetIds
+bp connect --new-tab --url https://example.com --name fresh
+
 # Handle native dialogs (alert/confirm/prompt)
 bp exec --dialog accept '{"action":"click","selector":"#delete-btn"}'
+bp exec --record '[{"action":"click","selector":"#checkout"},{"action":"assertText","expect":"Thanks"}]'
 
 # Other commands
 bp text -s my-session --selector ".main-content"
 bp screenshot -s my-session --output page.png
 bp listen ws -m "*voice*"  # monitor WebSocket traffic
 bp list                    # list all sessions
+bp clean --max-size 500MB  # trim old sessions by disk usage
 bp close -s my-session     # close session
 bp actions                 # show complete action reference
 bp run workflow.json       # run a workflow file
 
+# Daemon management
+bp daemon status           # check daemon health
+bp daemon stop             # stop daemon for default session
+bp daemon logs             # view daemon log
+
 # Actions with inline assertions (no extra bp eval needed)
 bp exec '[
   {"action":"goto","url":"https://example.com/login"},
@@ -423,7 +438,7 @@ The CLI is designed for AI agent tool calls. The recommended workflow:
 ```bash
 # Step 1: Get page state with refs
 bp snapshot --format text
-# Output shows: button "Add to Cart" [ref=e12], textbox "Search" [ref=e5]
+# Output shows: button "Add to Cart" ref:e12, textbox "Search" ref:e5
 
 # Step 2: Use refs to interact (stable, no CSS guessing)
 bp exec '[
@@ -528,10 +543,32 @@ The output format is compatible with `page.batch()`:
 ```
 
 **Notes:**
-- Password fields are automatically redacted as `[REDACTED]`
+- Sensitive fields are automatically redacted as `[REDACTED]` based on input settings such as `type="password"`, `type="hidden"`, and secret/autofill hints like `autocomplete="one-time-code"` or `cc-number`
 - Selectors are multi-selector arrays ordered by reliability (data attributes > IDs > CSS paths)
 - Edit the JSON to adjust selectors or add `optional: true` flags
 
+### Screenshot Trail During Replay
+
+Capture a lightweight visual trail while replaying steps. Enable recording at the session level so all `bp exec` calls are captured automatically:
+
+```bash
+# Enable recording for the entire session
+bp connect --provider generic --name my-session --record
+
+# All exec calls now produce screenshots — frames accumulate in one manifest
+bp exec -s my-session '[
+  {"action":"goto","url":"https://example.com/login"},
+  {"action":"fill","selector":"#email","value":"user@example.com"},
+  {"action":"submit","selector":"form"}
+]'
+bp exec -s my-session '{"action":"assertUrl","expect":"/dashboard"}'
+
+# Or enable recording on a single exec call
+bp exec --record '[{"action":"click","selector":"#checkout"}]'
+```
+
+This writes `recording.json` plus a `screenshots/` directory in the session directory. Sensitive field values are redacted in both the manifest and the screenshot overlays. See the [Action Recording Guide](./docs/guides/action-recording.md) for options like `--record-format`, `--record-quality`, and `--no-highlights`.
+
 ## Examples
 
 ### Login Flow with Error Handling
@@ -567,8 +604,32 @@ await page.fill('.dropdown-search', 'United');
 await page.click('.dropdown-option:has-text("United States")');
 ```
 
+### WebSocket Daemon
+
+By default, `bp connect` spawns a lightweight background daemon that holds the CDP WebSocket open. Subsequent CLI commands connect via Unix socket (~5-15ms) instead of re-establishing WebSocket (~280-1030ms per command).
+
+```bash
+# Daemon spawns automatically on connect
+bp connect --provider generic --name dev
+
+# Subsequent commands use the fast daemon path
+bp exec -s dev '{"action":"snapshot"}'  # ~5-15ms overhead instead of ~280ms
+
+# Manage the daemon
+bp daemon status           # check health, PID, uptime
+bp daemon stop             # stop daemon
+bp daemon logs             # view daemon log
+
+# Disable daemon for direct WebSocket
+bp connect --no-daemon
+```
+
+The daemon is transparent — if it dies or becomes stale, CLI commands fall back to direct WebSocket silently. Each session gets its own daemon with a 60-minute idle timeout.
+
 ### Cloudflare Workers
 
+> Note: Cloudflare Workers' Node-compat runtime can expose parts of `node:net` with compatibility flags, but browser-pilot's daemon fast-path is intentionally CLI/Node-specific (Unix domain sockets + local background process). In Workers, use the normal direct WebSocket path shown below.
+
 ```typescript
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
@@ -650,9 +711,9 @@ enableTracing({ output: 'console' });
 browser-pilot is designed for AI agents. Two resources for agent setup:
 
 - **[llms.txt](./docs/llms.txt)** - Abbreviated reference for LLM context windows
-- **[Claude Code Skill](./docs/skill/SKILL.md)** - Full skill for Claude Code agents
+- **[Claude Code Skill](./docs/automating-browsers/SKILL.md)** - Full skill for Claude Code agents
 
-To use with Claude Code, copy `docs/skill/` to your project or reference it in your agent's context.
+To use with Claude Code, copy `docs/automating-browsers/` to your project or reference it in your agent's context.
 
 ## Documentation
 
@@ -660,6 +721,7 @@ See the [docs](./docs) folder for detailed documentation:
 
 - [Getting Started](./docs/getting-started.md)
 - [Providers](./docs/providers.md)
+- [Action Recording](./docs/guides/action-recording.md)
 - [Multi-Selector Guide](./docs/guides/multi-selector.md)
 - [Batch Actions](./docs/guides/batch-actions.md)
 - [Snapshots](./docs/guides/snapshots.md)