browser-pilot 0.0.11 → 0.0.13

package/README.md

@@ -33,6 +33,7 @@ await browser.close();
 | Bun CDP connection bugs | Custom CDP client that works everywhere |
 | Single-selector API (fragile) | Multi-selector by default: `['#primary', '.fallback']` |
 | No action batching (high latency) | Batch DSL: one call for entire sequences |
+| No inline assertions (extra API calls to verify) | Built-in assertions: verify state within the same batch |
 | No AI-optimized snapshots | Built-in accessibility tree extraction |
 | No audio I/O for voice agents | Mic injection + output capture + Whisper transcription |
 
@@ -131,6 +132,25 @@ console.log(result.totalDurationMs); // total execution time
 console.log(result.steps[5].result); // snapshot from step 5
 ```
 
+Assertion steps verify expected state within the same batch — no extra round trips. Available: `assertVisible`, `assertExists`, `assertText`, `assertUrl`, `assertValue`.
+
+```typescript
+const result = await page.batch([
+  { action: 'goto', url: 'https://example.com/login' },
+  { action: 'fill', selector: '#email', value: 'user@example.com' },
+  { action: 'fill', selector: '#password', value: 'secret' },
+  { action: 'submit', selector: '#login-btn' },
+  { action: 'assertUrl', expect: '/dashboard' },
+  { action: 'assertVisible', selector: '.welcome-message' },
+]);
+```
+
+Any step supports `retry` and `retryDelay` for flaky or async content:
+
+```typescript
+{ action: 'assertVisible', selector: '.async-content', retry: 3, retryDelay: 1000 }
+```
+
 ### AI-Optimized Snapshots
 
 Get the page state in a format perfect for LLMs:
@@ -147,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
@@ -159,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');
@@ -363,13 +383,19 @@ 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"}'
 
@@ -380,6 +406,16 @@ bp listen ws -m "*voice*"  # monitor WebSocket traffic
 bp list                    # list all sessions
 bp close -s my-session     # close session
 bp actions                 # show complete action reference
+bp run workflow.json       # run a workflow file
+
+# Actions with inline assertions (no extra bp eval needed)
+bp exec '[
+  {"action":"goto","url":"https://example.com/login"},
+  {"action":"fill","selector":"#email","value":"user@example.com"},
+  {"action":"submit","selector":"form"},
+  {"action":"assertUrl","expect":"/dashboard"},
+  {"action":"assertText","expect":"Welcome"}
+]'
 ```
 
 ### CLI for AI Agents
@@ -393,7 +429,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 '[
@@ -572,7 +608,7 @@ const browserTool = {
         items: {
           type: 'object',
           properties: {
-            action: { enum: ['goto', 'click', 'fill', 'submit', 'snapshot'] },
+            action: { enum: ['goto', 'click', 'fill', 'submit', 'snapshot', 'assertVisible', 'assertExists', 'assertText', 'assertUrl', 'assertValue'] },
             selector: { type: ['string', 'array'] },
             value: { type: 'string' },
             url: { type: 'string' },