browser-pilot 0.0.3 → 0.0.4

package/dist/cli.cjs

@@ -3194,15 +3194,6 @@ function parseExecArgs(args) {
 }
 async function execCommand(args, globalOptions) {
   const { actionsJson, options: execOptions } = parseExecArgs(args);
-  let session;
-  if (globalOptions.session) {
-    session = await loadSession(globalOptions.session);
-  } else {
-    session = await getDefaultSession();
-    if (!session) {
-      throw new Error('No session found. Run "bp connect" first.');
-    }
-  }
   if (!actionsJson) {
     throw new Error(
       `No actions provided. Usage: bp exec '{"action":"goto","url":"..."}'
@@ -3218,6 +3209,15 @@ Run 'bp actions' for complete action reference.`
       "Invalid JSON. Actions must be valid JSON.\n\nRun 'bp actions' for complete action reference."
     );
   }
+  let session;
+  if (globalOptions.session) {
+    session = await loadSession(globalOptions.session);
+  } else {
+    session = await getDefaultSession();
+    if (!session) {
+      throw new Error('No session found. Run "bp connect" first.');
+    }
+  }
   const browser = await connect({
     provider: session.provider,
     wsUrl: session.wsUrl,
@@ -3317,67 +3317,62 @@ function getAge(date) {
 
 // src/cli/commands/quickstart.ts
 var QUICKSTART = `
-browser-pilot - CDP-based browser automation for AI agents
-
-Zero production dependencies. Works in Node.js, Bun, and Cloudflare Workers.
-
-RUNNING
-  npx browser-pilot ...     # Node.js projects
-  bunx browser-pilot ...    # Bun projects (faster)
-
-CONNECTING
-  npx browser-pilot connect <wsUrl>     Connect to existing browser
-  npx browser-pilot connect --provider browserbase --api-key <key>
-
-BASIC USAGE (Code)
-  import { Browser } from 'browser-pilot';
-
-  const browser = await Browser.connect({ wsUrl: '...' });
-  const page = await browser.newPage();
-  await page.goto('https://example.com');
-  await page.click('#button');
-  await page.fill('#input', 'text');
-  await browser.close();
-
-KEY PATTERNS
-  Multi-Selector    await page.click(['#primary', '.fallback', 'button']);
-  Smart Waiting     Every action waits for visibility automatically
-  Optional Actions  await page.click('#banner', { optional: true });
-
-BATCH EXECUTION
-  await page.batch([
-    { action: 'goto', url: 'https://example.com' },
-    { action: 'fill', selector: '#email', value: 'test@test.com' },
-    { action: 'submit', selector: 'form' },
-  ]);
-
-SNAPSHOTS (FOR AI AGENTS)
-  const snapshot = await page.snapshot();
-  // Returns accessibility tree with refs: e1, e2, e3...
-  await page.click({ ref: 'e5' });
-
-PROVIDERS
-  BrowserBase     Browser.connect({ provider: 'browserbase', apiKey })
-  Browserless     Browser.connect({ provider: 'browserless', apiKey })
-  Generic         Browser.connect({ wsUrl: 'ws://...' })
+browser-pilot CLI - Quick Start Guide
+
+STEP 1: CONNECT TO A BROWSER
+  bp connect --provider generic --name mysite
+
+  This creates a session. The CLI remembers it for subsequent commands.
+
+STEP 2: NAVIGATE
+  bp exec '{"action":"goto","url":"https://example.com"}'
+
+STEP 3: GET PAGE SNAPSHOT
+  bp snapshot --format text
+
+  Output shows the page as an accessibility tree with element refs:
+    - heading "Welcome" [ref=e1]
+    - button "Sign In" [ref=e2]
+    - textbox "Email" [ref=e3]
+
+STEP 4: INTERACT USING REFS
+  bp exec '{"action":"fill","selector":"ref:e3","value":"test@example.com"}'
+  bp exec '{"action":"click","selector":"ref:e2"}'
+
+STEP 5: BATCH MULTIPLE ACTIONS
+  bp exec '[
+    {"action":"fill","selector":"ref:e3","value":"user@test.com"},
+    {"action":"click","selector":"ref:e2"},
+    {"action":"snapshot"}
+  ]'
+
+FOR AI AGENTS
+  Use -o json for machine-readable output:
+    bp snapshot --format text -o json
+    bp exec '{"action":"click","selector":"ref:e3"}' -o json
+
+TIPS
+  \u2022 Refs (e1, e2...) are stable within a page - prefer them over CSS selectors
+  \u2022 After navigation, take a new snapshot to get updated refs
+  \u2022 Use multi-selectors for resilience: ["ref:e3", "#email", "input[type=email]"]
+  \u2022 Add "optional":true to skip elements that may not exist
+
+SELECTOR PRIORITY
+  1. ref:e5         From snapshot - most reliable
+  2. #id            CSS ID selector
+  3. [data-testid]  Test attributes
+  4. .class         CSS class (less stable)
 
 COMMON ACTIONS
-  page.goto(url)              Navigate to URL
-  page.click(selector)        Click element
-  page.fill(selector, value)  Fill input field
-  page.submit(selector)       Submit form
-  page.select(selector, val)  Select dropdown option
-  page.screenshot()           Capture screenshot
-  page.snapshot()             Get accessibility tree
-
-AGENT INTEGRATION
-  - Use snapshot() to get page state as accessibility tree
-  - Refs (e1, e2...) identify elements without fragile selectors
-  - Multi-selector arrays handle UI variations
-  - optional: true prevents failures on transient elements
-
-Ready to automate!
-Run: npx browser-pilot connect <wsUrl>
+  goto        {"action":"goto","url":"https://..."}
+  click       {"action":"click","selector":"ref:e3"}
+  fill        {"action":"fill","selector":"ref:e3","value":"text"}
+  submit      {"action":"submit","selector":"form"}
+  select      {"action":"select","selector":"ref:e5","value":"option"}
+  snapshot    {"action":"snapshot"}
+  screenshot  {"action":"screenshot"}
+
+Run 'bp actions' for the complete action reference.
 `;
 async function quickstartCommand() {
   console.log(QUICKSTART);
@@ -3553,56 +3548,30 @@ Usage:
   bp <command> [options]
 
 Commands:
-  quickstart  Show getting started guide
-  connect     Create or resume browser session
-  exec        Execute actions on current session
-  snapshot    Get page accessibility snapshot (includes element refs)
-  text        Extract text content from page
+  quickstart  Getting started guide (start here!)
+  connect     Create browser session
+  exec        Execute actions
+  snapshot    Get page with element refs
+  text        Extract text content
   screenshot  Take screenshot
   close       Close session
-  list        List all sessions
-  actions     Show all available actions with examples
+  list        List sessions
+  actions     Complete action reference
 
-Global Options:
-  -s, --session <id>    Session ID to use
-  -o, --output <fmt>    Output format: json | pretty (default: pretty)
-  --trace               Enable execution tracing
-  -h, --help            Show this help message
-
-Exec Options:
-  --dialog <mode>       Auto-handle dialogs: accept | dismiss
-
-Ref Selectors (Recommended for AI Agents):
-  1. Navigate + snapshot: bp exec '[{"action":"goto","url":"..."},{"action":"snapshot"}]'
-     Output shows:        button "Submit" [ref=e4], textbox "Email" [ref=e5]
-  2. Use refs (snapshot cached for same session+URL):
-     bp exec '[{"action":"click","selector":"ref:e4"}]'
-
-  Refs are cached per session+URL after snapshot. Use new snapshot after navigation.
-  Combine with CSS fallbacks:
-    {"selector": ["ref:e4", "#submit", "button[type=submit]"]}
+Options:
+  -s, --session <id>    Session ID
+  -o, --output <fmt>    json | pretty (default: pretty)
+  --trace               Enable debug tracing
+  --dialog <mode>       Handle dialogs: accept | dismiss
+  -h, --help            Show help
 
 Examples:
-  # Connect to browser
   bp connect --provider generic --name dev
+  bp exec '{"action":"goto","url":"https://example.com"}'
+  bp snapshot --format text
+  bp exec '{"action":"click","selector":"ref:e3"}'
 
-  # Navigate and get snapshot with refs
-  bp exec '[{"action":"goto","url":"https://example.com"},{"action":"snapshot"}]'
-
-  # Use refs (snapshot cached for same session+URL)
-  bp exec '[{"action":"fill","selector":"ref:e5","value":"test@example.com"},{"action":"click","selector":"ref:e4"}]'
-
-  # Handle native dialogs (alert/confirm/prompt)
-  bp exec --dialog accept '{"action":"click","selector":"#delete-btn"}'
-
-  # Batch multiple actions (snapshot optional if already cached)
-  bp exec '[
-    {"action":"snapshot"},
-    {"action":"fill","selector":"ref:e5","value":"user@example.com"},
-    {"action":"click","selector":"ref:e4"},
-    {"action":"snapshot"}
-  ]'
-
+Run 'bp quickstart' for CLI workflow guide.
 Run 'bp actions' for complete action reference.
 `;
 function parseGlobalOptions(args) {

package/dist/cli.mjs

@@ -410,15 +410,6 @@ function parseExecArgs(args) {
 }
 async function execCommand(args, globalOptions) {
   const { actionsJson, options: execOptions } = parseExecArgs(args);
-  let session;
-  if (globalOptions.session) {
-    session = await loadSession(globalOptions.session);
-  } else {
-    session = await getDefaultSession();
-    if (!session) {
-      throw new Error('No session found. Run "bp connect" first.');
-    }
-  }
   if (!actionsJson) {
     throw new Error(
       `No actions provided. Usage: bp exec '{"action":"goto","url":"..."}'
@@ -434,6 +425,15 @@ Run 'bp actions' for complete action reference.`
       "Invalid JSON. Actions must be valid JSON.\n\nRun 'bp actions' for complete action reference."
     );
   }
+  let session;
+  if (globalOptions.session) {
+    session = await loadSession(globalOptions.session);
+  } else {
+    session = await getDefaultSession();
+    if (!session) {
+      throw new Error('No session found. Run "bp connect" first.');
+    }
+  }
   const browser = await connect({
     provider: session.provider,
     wsUrl: session.wsUrl,
@@ -533,67 +533,62 @@ function getAge(date) {
 
 // src/cli/commands/quickstart.ts
 var QUICKSTART = `
-browser-pilot - CDP-based browser automation for AI agents
-
-Zero production dependencies. Works in Node.js, Bun, and Cloudflare Workers.
-
-RUNNING
-  npx browser-pilot ...     # Node.js projects
-  bunx browser-pilot ...    # Bun projects (faster)
-
-CONNECTING
-  npx browser-pilot connect <wsUrl>     Connect to existing browser
-  npx browser-pilot connect --provider browserbase --api-key <key>
-
-BASIC USAGE (Code)
-  import { Browser } from 'browser-pilot';
-
-  const browser = await Browser.connect({ wsUrl: '...' });
-  const page = await browser.newPage();
-  await page.goto('https://example.com');
-  await page.click('#button');
-  await page.fill('#input', 'text');
-  await browser.close();
-
-KEY PATTERNS
-  Multi-Selector    await page.click(['#primary', '.fallback', 'button']);
-  Smart Waiting     Every action waits for visibility automatically
-  Optional Actions  await page.click('#banner', { optional: true });
-
-BATCH EXECUTION
-  await page.batch([
-    { action: 'goto', url: 'https://example.com' },
-    { action: 'fill', selector: '#email', value: 'test@test.com' },
-    { action: 'submit', selector: 'form' },
-  ]);
-
-SNAPSHOTS (FOR AI AGENTS)
-  const snapshot = await page.snapshot();
-  // Returns accessibility tree with refs: e1, e2, e3...
-  await page.click({ ref: 'e5' });
-
-PROVIDERS
-  BrowserBase     Browser.connect({ provider: 'browserbase', apiKey })
-  Browserless     Browser.connect({ provider: 'browserless', apiKey })
-  Generic         Browser.connect({ wsUrl: 'ws://...' })
+browser-pilot CLI - Quick Start Guide
+
+STEP 1: CONNECT TO A BROWSER
+  bp connect --provider generic --name mysite
+
+  This creates a session. The CLI remembers it for subsequent commands.
+
+STEP 2: NAVIGATE
+  bp exec '{"action":"goto","url":"https://example.com"}'
+
+STEP 3: GET PAGE SNAPSHOT
+  bp snapshot --format text
+
+  Output shows the page as an accessibility tree with element refs:
+    - heading "Welcome" [ref=e1]
+    - button "Sign In" [ref=e2]
+    - textbox "Email" [ref=e3]
+
+STEP 4: INTERACT USING REFS
+  bp exec '{"action":"fill","selector":"ref:e3","value":"test@example.com"}'
+  bp exec '{"action":"click","selector":"ref:e2"}'
+
+STEP 5: BATCH MULTIPLE ACTIONS
+  bp exec '[
+    {"action":"fill","selector":"ref:e3","value":"user@test.com"},
+    {"action":"click","selector":"ref:e2"},
+    {"action":"snapshot"}
+  ]'
+
+FOR AI AGENTS
+  Use -o json for machine-readable output:
+    bp snapshot --format text -o json
+    bp exec '{"action":"click","selector":"ref:e3"}' -o json
+
+TIPS
+  \u2022 Refs (e1, e2...) are stable within a page - prefer them over CSS selectors
+  \u2022 After navigation, take a new snapshot to get updated refs
+  \u2022 Use multi-selectors for resilience: ["ref:e3", "#email", "input[type=email]"]
+  \u2022 Add "optional":true to skip elements that may not exist
+
+SELECTOR PRIORITY
+  1. ref:e5         From snapshot - most reliable
+  2. #id            CSS ID selector
+  3. [data-testid]  Test attributes
+  4. .class         CSS class (less stable)
 
 COMMON ACTIONS
-  page.goto(url)              Navigate to URL
-  page.click(selector)        Click element
-  page.fill(selector, value)  Fill input field
-  page.submit(selector)       Submit form
-  page.select(selector, val)  Select dropdown option
-  page.screenshot()           Capture screenshot
-  page.snapshot()             Get accessibility tree
-
-AGENT INTEGRATION
-  - Use snapshot() to get page state as accessibility tree
-  - Refs (e1, e2...) identify elements without fragile selectors
-  - Multi-selector arrays handle UI variations
-  - optional: true prevents failures on transient elements
-
-Ready to automate!
-Run: npx browser-pilot connect <wsUrl>
+  goto        {"action":"goto","url":"https://..."}
+  click       {"action":"click","selector":"ref:e3"}
+  fill        {"action":"fill","selector":"ref:e3","value":"text"}
+  submit      {"action":"submit","selector":"form"}
+  select      {"action":"select","selector":"ref:e5","value":"option"}
+  snapshot    {"action":"snapshot"}
+  screenshot  {"action":"screenshot"}
+
+Run 'bp actions' for the complete action reference.
 `;
 async function quickstartCommand() {
   console.log(QUICKSTART);
@@ -769,56 +764,30 @@ Usage:
   bp <command> [options]
 
 Commands:
-  quickstart  Show getting started guide
-  connect     Create or resume browser session
-  exec        Execute actions on current session
-  snapshot    Get page accessibility snapshot (includes element refs)
-  text        Extract text content from page
+  quickstart  Getting started guide (start here!)
+  connect     Create browser session
+  exec        Execute actions
+  snapshot    Get page with element refs
+  text        Extract text content
   screenshot  Take screenshot
   close       Close session
-  list        List all sessions
-  actions     Show all available actions with examples
+  list        List sessions
+  actions     Complete action reference
 
-Global Options:
-  -s, --session <id>    Session ID to use
-  -o, --output <fmt>    Output format: json | pretty (default: pretty)
-  --trace               Enable execution tracing
-  -h, --help            Show this help message
-
-Exec Options:
-  --dialog <mode>       Auto-handle dialogs: accept | dismiss
-
-Ref Selectors (Recommended for AI Agents):
-  1. Navigate + snapshot: bp exec '[{"action":"goto","url":"..."},{"action":"snapshot"}]'
-     Output shows:        button "Submit" [ref=e4], textbox "Email" [ref=e5]
-  2. Use refs (snapshot cached for same session+URL):
-     bp exec '[{"action":"click","selector":"ref:e4"}]'
-
-  Refs are cached per session+URL after snapshot. Use new snapshot after navigation.
-  Combine with CSS fallbacks:
-    {"selector": ["ref:e4", "#submit", "button[type=submit]"]}
+Options:
+  -s, --session <id>    Session ID
+  -o, --output <fmt>    json | pretty (default: pretty)
+  --trace               Enable debug tracing
+  --dialog <mode>       Handle dialogs: accept | dismiss
+  -h, --help            Show help
 
 Examples:
-  # Connect to browser
   bp connect --provider generic --name dev
+  bp exec '{"action":"goto","url":"https://example.com"}'
+  bp snapshot --format text
+  bp exec '{"action":"click","selector":"ref:e3"}'
 
-  # Navigate and get snapshot with refs
-  bp exec '[{"action":"goto","url":"https://example.com"},{"action":"snapshot"}]'
-
-  # Use refs (snapshot cached for same session+URL)
-  bp exec '[{"action":"fill","selector":"ref:e5","value":"test@example.com"},{"action":"click","selector":"ref:e4"}]'
-
-  # Handle native dialogs (alert/confirm/prompt)
-  bp exec --dialog accept '{"action":"click","selector":"#delete-btn"}'
-
-  # Batch multiple actions (snapshot optional if already cached)
-  bp exec '[
-    {"action":"snapshot"},
-    {"action":"fill","selector":"ref:e5","value":"user@example.com"},
-    {"action":"click","selector":"ref:e4"},
-    {"action":"snapshot"}
-  ]'
-
+Run 'bp quickstart' for CLI workflow guide.
 Run 'bp actions' for complete action reference.
 `;
 function parseGlobalOptions(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-pilot",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Lightweight CDP-based browser automation for Node.js, Bun, and Cloudflare Workers",
   "type": "module",
   "main": "./dist/index.cjs",