browser-pilot 0.0.1 → 0.0.3

package/README.md

@@ -171,6 +171,8 @@ await page.click(['ref:e4', '#submit', 'button[type=submit]']);
 ```
 
 Refs are stable until page navigation. Always take a fresh snapshot after navigating.
+CLI note: refs are cached per session+URL after a snapshot, so you can reuse them across CLI calls
+until navigation changes the URL.
 
 ## Page API
 
@@ -343,6 +345,7 @@ bp snapshot -s my-session --format text
 # 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"}'
 

package/dist/actions.d.cts

@@ -1,5 +1,5 @@
-import { P as Page, S as Step, B as BatchOptions, b as BatchResult } from './types-Cs89wle0.cjs';
-export { A as ActionType, c as StepResult } from './types-Cs89wle0.cjs';
+import { P as Page, S as Step, B as BatchOptions, b as BatchResult } from './types-C6m0bT04.cjs';
+export { A as ActionType, c as StepResult } from './types-C6m0bT04.cjs';
 import './client-7Nqka5MV.cjs';
 
 /**

package/dist/actions.d.ts

@@ -1,5 +1,5 @@
-import { P as Page, S as Step, B as BatchOptions, b as BatchResult } from './types-DL_-3BZk.js';
-export { A as ActionType, c as StepResult } from './types-DL_-3BZk.js';
+import { P as Page, S as Step, B as BatchOptions, b as BatchResult } from './types-BJv2dzu0.js';
+export { A as ActionType, c as StepResult } from './types-BJv2dzu0.js';
 import './client-7Nqka5MV.js';
 
 /**

package/dist/browser.cjs

@@ -1608,10 +1608,14 @@ var Page = class {
     this.currentFrame = frameKey;
     this.rootNodeId = descResult.node.contentDocument.nodeId;
     if (descResult.node.frameId) {
-      let contextId = this.frameExecutionContexts.get(descResult.node.frameId);
-      if (!contextId) {
-        await new Promise((resolve) => setTimeout(resolve, 50));
-        contextId = this.frameExecutionContexts.get(descResult.node.frameId);
+      const frameId = descResult.node.frameId;
+      const { timeout = DEFAULT_TIMEOUT2 } = options;
+      const pollInterval = 50;
+      const deadline = Date.now() + timeout;
+      let contextId = this.frameExecutionContexts.get(frameId);
+      while (!contextId && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        contextId = this.frameExecutionContexts.get(frameId);
       }
       if (contextId) {
         this.currentFrameContextId = contextId;
@@ -1947,6 +1951,27 @@ var Page = class {
       text
     };
   }
+  /**
+   * Export the current ref map for cross-exec reuse (CLI).
+   */
+  exportRefMap() {
+    const map = {};
+    for (const [ref, backendNodeId] of this.refMap.entries()) {
+      map[ref] = backendNodeId;
+    }
+    return map;
+  }
+  /**
+   * Import a ref map previously captured from a snapshot.
+   */
+  importRefMap(refMap) {
+    this.refMap.clear();
+    for (const [ref, backendNodeId] of Object.entries(refMap)) {
+      if (typeof backendNodeId === "number") {
+        this.refMap.set(ref, backendNodeId);
+      }
+    }
+  }
   // ============ Batch Execution ============
   /**
    * Execute a batch of steps

package/dist/browser.d.cts

@@ -1,7 +1,7 @@
 import { C as CDPClient } from './client-7Nqka5MV.cjs';
 import { C as ConnectOptions } from './types-D_uDqh0Z.cjs';
-import { P as Page } from './types-Cs89wle0.cjs';
-export { d as ActionOptions, e as ActionResult, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, h as CustomSelectConfig, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, F as FileInput, o as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, p as NetworkIdleOptions, q as PageError, r as PageSnapshot, s as SnapshotNode, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-Cs89wle0.cjs';
+import { P as Page } from './types-C6m0bT04.cjs';
+export { d as ActionOptions, e as ActionResult, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, h as CustomSelectConfig, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, F as FileInput, o as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, p as NetworkIdleOptions, q as PageError, r as PageSnapshot, s as SnapshotNode, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-C6m0bT04.cjs';
 
 /**
  * Browser class - manages CDP connection and pages

package/dist/browser.d.ts

@@ -1,7 +1,7 @@
 import { C as CDPClient } from './client-7Nqka5MV.js';
 import { C as ConnectOptions } from './types-D_uDqh0Z.js';
-import { P as Page } from './types-DL_-3BZk.js';
-export { d as ActionOptions, e as ActionResult, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, h as CustomSelectConfig, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, F as FileInput, o as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, p as NetworkIdleOptions, q as PageError, r as PageSnapshot, s as SnapshotNode, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-DL_-3BZk.js';
+import { P as Page } from './types-BJv2dzu0.js';
+export { d as ActionOptions, e as ActionResult, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, h as CustomSelectConfig, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, F as FileInput, o as FillOptions, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, p as NetworkIdleOptions, q as PageError, r as PageSnapshot, s as SnapshotNode, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions } from './types-BJv2dzu0.js';
 
 /**
  * Browser class - manages CDP connection and pages

package/dist/browser.mjs

@@ -5,7 +5,7 @@ import {
   Page,
   TimeoutError,
   connect
-} from "./chunk-FI55U7JS.mjs";
+} from "./chunk-CWSTSVWO.mjs";
 import "./chunk-BCOZUKWS.mjs";
 import "./chunk-R3PS4PCM.mjs";
 import "./chunk-YEHK2XY3.mjs";

package/dist/{chunk-FI55U7JS.mjs → chunk-CWSTSVWO.mjs}

@@ -946,10 +946,14 @@ var Page = class {
     this.currentFrame = frameKey;
     this.rootNodeId = descResult.node.contentDocument.nodeId;
     if (descResult.node.frameId) {
-      let contextId = this.frameExecutionContexts.get(descResult.node.frameId);
-      if (!contextId) {
-        await new Promise((resolve) => setTimeout(resolve, 50));
-        contextId = this.frameExecutionContexts.get(descResult.node.frameId);
+      const frameId = descResult.node.frameId;
+      const { timeout = DEFAULT_TIMEOUT } = options;
+      const pollInterval = 50;
+      const deadline = Date.now() + timeout;
+      let contextId = this.frameExecutionContexts.get(frameId);
+      while (!contextId && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        contextId = this.frameExecutionContexts.get(frameId);
       }
       if (contextId) {
         this.currentFrameContextId = contextId;
@@ -1285,6 +1289,27 @@ var Page = class {
       text
     };
   }
+  /**
+   * Export the current ref map for cross-exec reuse (CLI).
+   */
+  exportRefMap() {
+    const map = {};
+    for (const [ref, backendNodeId] of this.refMap.entries()) {
+      map[ref] = backendNodeId;
+    }
+    return map;
+  }
+  /**
+   * Import a ref map previously captured from a snapshot.
+   */
+  importRefMap(refMap) {
+    this.refMap.clear();
+    for (const [ref, backendNodeId] of Object.entries(refMap)) {
+      if (typeof backendNodeId === "number") {
+        this.refMap.set(ref, backendNodeId);
+      }
+    }
+  }
   // ============ Batch Execution ============
   /**
    * Execute a batch of steps

package/dist/cli.cjs

@@ -150,6 +150,7 @@ REF SELECTORS (from snapshot)
     bp exec '{"action":"click","selector":"ref:e4"}'
 
   Refs are stable until navigation. Prefix with "ref:" to use.
+  CLI caches refs per session+URL after snapshot, so they can be reused across exec calls.
   Example: {"action":"fill","selector":"ref:e23","value":"hello"}
 
 MULTI-SELECTOR PATTERN
@@ -1801,10 +1802,14 @@ var Page = class {
     this.currentFrame = frameKey;
     this.rootNodeId = descResult.node.contentDocument.nodeId;
     if (descResult.node.frameId) {
-      let contextId = this.frameExecutionContexts.get(descResult.node.frameId);
-      if (!contextId) {
-        await new Promise((resolve) => setTimeout(resolve, 50));
-        contextId = this.frameExecutionContexts.get(descResult.node.frameId);
+      const frameId = descResult.node.frameId;
+      const { timeout = DEFAULT_TIMEOUT2 } = options;
+      const pollInterval = 50;
+      const deadline = Date.now() + timeout;
+      let contextId = this.frameExecutionContexts.get(frameId);
+      while (!contextId && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        contextId = this.frameExecutionContexts.get(frameId);
       }
       if (contextId) {
         this.currentFrameContextId = contextId;
@@ -2140,6 +2145,27 @@ var Page = class {
       text
     };
   }
+  /**
+   * Export the current ref map for cross-exec reuse (CLI).
+   */
+  exportRefMap() {
+    const map = {};
+    for (const [ref, backendNodeId] of this.refMap.entries()) {
+      map[ref] = backendNodeId;
+    }
+    return map;
+  }
+  /**
+   * Import a ref map previously captured from a snapshot.
+   */
+  importRefMap(refMap) {
+    this.refMap.clear();
+    for (const [ref, backendNodeId] of Object.entries(refMap)) {
+      if (typeof backendNodeId === "number") {
+        this.refMap.set(ref, backendNodeId);
+      }
+    }
+  }
   // ============ Batch Execution ============
   /**
    * Execute a batch of steps
@@ -2977,9 +3003,11 @@ async function loadSession(id) {
 }
 async function updateSession(id, updates) {
   const session = await loadSession(id);
+  const mergedMetadata = updates.metadata !== void 0 ? { ...session.metadata ?? {}, ...updates.metadata ?? {} } : session.metadata;
   const updated = {
     ...session,
     ...updates,
+    metadata: mergedMetadata,
     lastActivity: (/* @__PURE__ */ new Date()).toISOString()
   };
   await saveSession(updated);
@@ -3197,6 +3225,11 @@ Run 'bp actions' for complete action reference.`
   });
   try {
     const page = addBatchToPage(await browser.page());
+    const currentUrlForCache = await page.url();
+    const refCache = session.metadata?.refCache;
+    if (refCache && refCache.url === currentUrlForCache) {
+      page.importRefMap(refCache.refMap);
+    }
     if (execOptions.dialog) {
       await page.onDialog(async (dialog) => {
         if (execOptions.dialog === "accept") {
@@ -3209,7 +3242,21 @@ Run 'bp actions' for complete action reference.`
     const steps = Array.isArray(actions) ? actions : [actions];
     const result = await page.batch(steps);
     const currentUrl = await page.url();
-    await updateSession(session.id, { currentUrl });
+    const hasSnapshot = steps.some((step) => step.action === "snapshot");
+    if (hasSnapshot) {
+      await updateSession(session.id, {
+        currentUrl,
+        metadata: {
+          refCache: {
+            url: currentUrl,
+            savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            refMap: page.exportRefMap()
+          }
+        }
+      });
+    } else {
+      await updateSession(session.id, { currentUrl });
+    }
     output(
       {
         success: result.success,
@@ -3268,6 +3315,74 @@ function getAge(date) {
   return `${days}d ago`;
 }
 
+// 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://...' })
+
+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>
+`;
+async function quickstartCommand() {
+  console.log(QUICKSTART);
+}
+
 // src/cli/commands/screenshot.ts
 function parseScreenshotArgs(args) {
   const options = {};
@@ -3362,7 +3477,16 @@ async function snapshotCommand(args, globalOptions) {
   try {
     const page = await browser.page();
     const snapshot = await page.snapshot();
-    await updateSession(session.id, { currentUrl: snapshot.url });
+    await updateSession(session.id, {
+      currentUrl: snapshot.url,
+      metadata: {
+        refCache: {
+          url: snapshot.url,
+          savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          refMap: page.exportRefMap()
+        }
+      }
+    });
     switch (options.format) {
       case "interactive":
         output(snapshot.interactiveElements, globalOptions.output);
@@ -3429,6 +3553,7 @@ 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)
@@ -3448,11 +3573,13 @@ Exec Options:
   --dialog <mode>       Auto-handle dialogs: accept | dismiss
 
 Ref Selectors (Recommended for AI Agents):
-  1. Take snapshot:     bp snapshot --format text
-     Output shows:      button "Submit" [ref=e4], textbox "Email" [ref=e5]
-  2. Use ref directly:  bp exec '{"action":"click","selector":"ref:e4"}'
+  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 stable until navigation. Combine with CSS fallbacks:
+  Refs are cached per session+URL after snapshot. Use new snapshot after navigation.
+  Combine with CSS fallbacks:
     {"selector": ["ref:e4", "#submit", "button[type=submit]"]}
 
 Examples:
@@ -3460,18 +3587,17 @@ Examples:
   bp connect --provider generic --name dev
 
   # Navigate and get snapshot with refs
-  bp exec '{"action":"goto","url":"https://example.com"}'
-  bp snapshot --format text
+  bp exec '[{"action":"goto","url":"https://example.com"},{"action":"snapshot"}]'
 
-  # Use ref from snapshot (most reliable)
-  bp exec '{"action":"click","selector":"ref:e4"}'
-  bp exec '{"action":"fill","selector":"ref:e5","value":"test@example.com"}'
+  # 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
+  # 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"}
@@ -3540,6 +3666,9 @@ async function main() {
   }
   try {
     switch (command) {
+      case "quickstart":
+        await quickstartCommand();
+        break;
       case "connect":
         await connectCommand(remaining, options);
         break;

package/dist/cli.d.cts

@@ -7,6 +7,7 @@
  *   2. bp exec '{"selector":"ref:e4",...}'  → Use refs for reliable targeting
  *
  * Commands:
+ *   quickstart  Getting started guide
  *   connect     Create browser session
  *   exec        Execute actions (supports --dialog accept|dismiss)
  *   snapshot    Get page snapshot with element refs
@@ -16,7 +17,7 @@
  *   list        List sessions
  *   actions     Complete action reference
  *
- * Run 'bp actions' for full action DSL documentation.
+ * Run 'bp quickstart' for getting started guide.
  */
 declare function output(data: unknown, format?: 'json' | 'pretty'): void;
 

package/dist/cli.d.ts

@@ -7,6 +7,7 @@
  *   2. bp exec '{"selector":"ref:e4",...}'  → Use refs for reliable targeting
  *
  * Commands:
+ *   quickstart  Getting started guide
  *   connect     Create browser session
  *   exec        Execute actions (supports --dialog accept|dismiss)
  *   snapshot    Get page snapshot with element refs
@@ -16,7 +17,7 @@
  *   list        List sessions
  *   actions     Complete action reference
  *
- * Run 'bp actions' for full action DSL documentation.
+ * Run 'bp quickstart' for getting started guide.
  */
 declare function output(data: unknown, format?: 'json' | 'pretty'): void;
 

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import "./chunk-ZIQA4JOT.mjs";
 import {
   connect
-} from "./chunk-FI55U7JS.mjs";
+} from "./chunk-CWSTSVWO.mjs";
 import "./chunk-BCOZUKWS.mjs";
 import {
   getBrowserWebSocketUrl
@@ -126,6 +126,7 @@ REF SELECTORS (from snapshot)
     bp exec '{"action":"click","selector":"ref:e4"}'
 
   Refs are stable until navigation. Prefix with "ref:" to use.
+  CLI caches refs per session+URL after snapshot, so they can be reused across exec calls.
   Example: {"action":"fill","selector":"ref:e23","value":"hello"}
 
 MULTI-SELECTOR PATTERN
@@ -218,9 +219,11 @@ async function loadSession(id) {
 }
 async function updateSession(id, updates) {
   const session = await loadSession(id);
+  const mergedMetadata = updates.metadata !== void 0 ? { ...session.metadata ?? {}, ...updates.metadata ?? {} } : session.metadata;
   const updated = {
     ...session,
     ...updates,
+    metadata: mergedMetadata,
     lastActivity: (/* @__PURE__ */ new Date()).toISOString()
   };
   await saveSession(updated);
@@ -438,6 +441,11 @@ Run 'bp actions' for complete action reference.`
   });
   try {
     const page = addBatchToPage(await browser.page());
+    const currentUrlForCache = await page.url();
+    const refCache = session.metadata?.refCache;
+    if (refCache && refCache.url === currentUrlForCache) {
+      page.importRefMap(refCache.refMap);
+    }
     if (execOptions.dialog) {
       await page.onDialog(async (dialog) => {
         if (execOptions.dialog === "accept") {
@@ -450,7 +458,21 @@ Run 'bp actions' for complete action reference.`
     const steps = Array.isArray(actions) ? actions : [actions];
     const result = await page.batch(steps);
     const currentUrl = await page.url();
-    await updateSession(session.id, { currentUrl });
+    const hasSnapshot = steps.some((step) => step.action === "snapshot");
+    if (hasSnapshot) {
+      await updateSession(session.id, {
+        currentUrl,
+        metadata: {
+          refCache: {
+            url: currentUrl,
+            savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            refMap: page.exportRefMap()
+          }
+        }
+      });
+    } else {
+      await updateSession(session.id, { currentUrl });
+    }
     output(
       {
         success: result.success,
@@ -509,6 +531,74 @@ function getAge(date) {
   return `${days}d ago`;
 }
 
+// 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://...' })
+
+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>
+`;
+async function quickstartCommand() {
+  console.log(QUICKSTART);
+}
+
 // src/cli/commands/screenshot.ts
 function parseScreenshotArgs(args) {
   const options = {};
@@ -603,7 +693,16 @@ async function snapshotCommand(args, globalOptions) {
   try {
     const page = await browser.page();
     const snapshot = await page.snapshot();
-    await updateSession(session.id, { currentUrl: snapshot.url });
+    await updateSession(session.id, {
+      currentUrl: snapshot.url,
+      metadata: {
+        refCache: {
+          url: snapshot.url,
+          savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          refMap: page.exportRefMap()
+        }
+      }
+    });
     switch (options.format) {
       case "interactive":
         output(snapshot.interactiveElements, globalOptions.output);
@@ -670,6 +769,7 @@ 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)
@@ -689,11 +789,13 @@ Exec Options:
   --dialog <mode>       Auto-handle dialogs: accept | dismiss
 
 Ref Selectors (Recommended for AI Agents):
-  1. Take snapshot:     bp snapshot --format text
-     Output shows:      button "Submit" [ref=e4], textbox "Email" [ref=e5]
-  2. Use ref directly:  bp exec '{"action":"click","selector":"ref:e4"}'
+  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 stable until navigation. Combine with CSS fallbacks:
+  Refs are cached per session+URL after snapshot. Use new snapshot after navigation.
+  Combine with CSS fallbacks:
     {"selector": ["ref:e4", "#submit", "button[type=submit]"]}
 
 Examples:
@@ -701,18 +803,17 @@ Examples:
   bp connect --provider generic --name dev
 
   # Navigate and get snapshot with refs
-  bp exec '{"action":"goto","url":"https://example.com"}'
-  bp snapshot --format text
+  bp exec '[{"action":"goto","url":"https://example.com"},{"action":"snapshot"}]'
 
-  # Use ref from snapshot (most reliable)
-  bp exec '{"action":"click","selector":"ref:e4"}'
-  bp exec '{"action":"fill","selector":"ref:e5","value":"test@example.com"}'
+  # 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
+  # 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"}
@@ -781,6 +882,9 @@ async function main() {
   }
   try {
     switch (command) {
+      case "quickstart":
+        await quickstartCommand();
+        break;
       case "connect":
         await connectCommand(remaining, options);
         break;

package/dist/index.cjs

@@ -1678,10 +1678,14 @@ var Page = class {
     this.currentFrame = frameKey;
     this.rootNodeId = descResult.node.contentDocument.nodeId;
     if (descResult.node.frameId) {
-      let contextId = this.frameExecutionContexts.get(descResult.node.frameId);
-      if (!contextId) {
-        await new Promise((resolve) => setTimeout(resolve, 50));
-        contextId = this.frameExecutionContexts.get(descResult.node.frameId);
+      const frameId = descResult.node.frameId;
+      const { timeout = DEFAULT_TIMEOUT2 } = options;
+      const pollInterval = 50;
+      const deadline = Date.now() + timeout;
+      let contextId = this.frameExecutionContexts.get(frameId);
+      while (!contextId && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        contextId = this.frameExecutionContexts.get(frameId);
       }
       if (contextId) {
         this.currentFrameContextId = contextId;
@@ -2017,6 +2021,27 @@ var Page = class {
       text
     };
   }
+  /**
+   * Export the current ref map for cross-exec reuse (CLI).
+   */
+  exportRefMap() {
+    const map = {};
+    for (const [ref, backendNodeId] of this.refMap.entries()) {
+      map[ref] = backendNodeId;
+    }
+    return map;
+  }
+  /**
+   * Import a ref map previously captured from a snapshot.
+   */
+  importRefMap(refMap) {
+    this.refMap.clear();
+    for (const [ref, backendNodeId] of Object.entries(refMap)) {
+      if (typeof backendNodeId === "number") {
+        this.refMap.set(ref, backendNodeId);
+      }
+    }
+  }
   // ============ Batch Execution ============
   /**
    * Execute a batch of steps

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 export { BatchExecutor, addBatchToPage } from './actions.cjs';
-import { R as RequestPattern, a as RequestHandler } from './types-Cs89wle0.cjs';
-export { d as ActionOptions, e as ActionResult, A as ActionType, B as BatchOptions, b as BatchResult, Q as ClearCookiesOptions, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, z as ContinueRequestOptions, X as Cookie, h as CustomSelectConfig, Y as DeleteCookieOptions, w as DeviceDescriptor, x as DeviceName, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, H as FailRequestOptions, F as FileInput, o as FillOptions, J as FulfillRequestOptions, G as GeolocationOptions, I as InteractiveElement, K as InterceptedRequest, N as NavigationError, p as NetworkIdleOptions, P as Page, q as PageError, r as PageSnapshot, L as RequestActions, M as ResourceType, O as RouteOptions, Z as SetCookieOptions, s as SnapshotNode, S as Step, c as StepResult, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions, _ as WaitOptions, $ as WaitResult, a0 as WaitState, y as devices, a1 as waitForAnyElement, a2 as waitForElement, a3 as waitForNavigation, a4 as waitForNetworkIdle } from './types-Cs89wle0.cjs';
+import { R as RequestPattern, a as RequestHandler } from './types-C6m0bT04.cjs';
+export { d as ActionOptions, e as ActionResult, A as ActionType, B as BatchOptions, b as BatchResult, Q as ClearCookiesOptions, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, z as ContinueRequestOptions, X as Cookie, h as CustomSelectConfig, Y as DeleteCookieOptions, w as DeviceDescriptor, x as DeviceName, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, H as FailRequestOptions, F as FileInput, o as FillOptions, J as FulfillRequestOptions, G as GeolocationOptions, I as InteractiveElement, K as InterceptedRequest, N as NavigationError, p as NetworkIdleOptions, P as Page, q as PageError, r as PageSnapshot, L as RequestActions, M as ResourceType, O as RouteOptions, Z as SetCookieOptions, s as SnapshotNode, S as Step, c as StepResult, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions, _ as WaitOptions, $ as WaitResult, a0 as WaitState, y as devices, a1 as waitForAnyElement, a2 as waitForElement, a3 as waitForNavigation, a4 as waitForNetworkIdle } from './types-C6m0bT04.cjs';
 export { Browser, BrowserOptions, connect } from './browser.cjs';
 import { C as CDPClient } from './client-7Nqka5MV.cjs';
 export { a as CDPClientOptions, c as createCDPClient } from './client-7Nqka5MV.cjs';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { BatchExecutor, addBatchToPage } from './actions.js';
-import { R as RequestPattern, a as RequestHandler } from './types-DL_-3BZk.js';
-export { d as ActionOptions, e as ActionResult, A as ActionType, B as BatchOptions, b as BatchResult, Q as ClearCookiesOptions, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, z as ContinueRequestOptions, X as Cookie, h as CustomSelectConfig, Y as DeleteCookieOptions, w as DeviceDescriptor, x as DeviceName, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, H as FailRequestOptions, F as FileInput, o as FillOptions, J as FulfillRequestOptions, G as GeolocationOptions, I as InteractiveElement, K as InterceptedRequest, N as NavigationError, p as NetworkIdleOptions, P as Page, q as PageError, r as PageSnapshot, L as RequestActions, M as ResourceType, O as RouteOptions, Z as SetCookieOptions, s as SnapshotNode, S as Step, c as StepResult, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions, _ as WaitOptions, $ as WaitResult, a0 as WaitState, y as devices, a1 as waitForAnyElement, a2 as waitForElement, a3 as waitForNavigation, a4 as waitForNetworkIdle } from './types-DL_-3BZk.js';
+import { R as RequestPattern, a as RequestHandler } from './types-BJv2dzu0.js';
+export { d as ActionOptions, e as ActionResult, A as ActionType, B as BatchOptions, b as BatchResult, Q as ClearCookiesOptions, C as ConsoleHandler, f as ConsoleMessage, g as ConsoleMessageType, z as ContinueRequestOptions, X as Cookie, h as CustomSelectConfig, Y as DeleteCookieOptions, w as DeviceDescriptor, x as DeviceName, D as Dialog, i as DialogHandler, j as DialogType, k as Download, E as ElementInfo, l as ElementNotFoundError, m as EmulationState, n as ErrorHandler, H as FailRequestOptions, F as FileInput, o as FillOptions, J as FulfillRequestOptions, G as GeolocationOptions, I as InteractiveElement, K as InterceptedRequest, N as NavigationError, p as NetworkIdleOptions, P as Page, q as PageError, r as PageSnapshot, L as RequestActions, M as ResourceType, O as RouteOptions, Z as SetCookieOptions, s as SnapshotNode, S as Step, c as StepResult, t as SubmitOptions, T as TimeoutError, u as TypeOptions, U as UserAgentMetadata, v as UserAgentOptions, V as ViewportOptions, W as WaitForOptions, _ as WaitOptions, $ as WaitResult, a0 as WaitState, y as devices, a1 as waitForAnyElement, a2 as waitForElement, a3 as waitForNavigation, a4 as waitForNetworkIdle } from './types-BJv2dzu0.js';
 export { Browser, BrowserOptions, connect } from './browser.js';
 import { C as CDPClient } from './client-7Nqka5MV.js';
 export { a as CDPClientOptions, c as createCDPClient } from './client-7Nqka5MV.js';

package/dist/index.mjs

@@ -17,7 +17,7 @@ import {
   waitForElement,
   waitForNavigation,
   waitForNetworkIdle
-} from "./chunk-FI55U7JS.mjs";
+} from "./chunk-CWSTSVWO.mjs";
 import {
   CDPError,
   createCDPClient

package/dist/{types-DL_-3BZk.d.ts → types-BJv2dzu0.d.ts}

@@ -626,6 +626,14 @@ declare class Page {
      * Get an accessibility tree snapshot of the page
      */
     snapshot(): Promise<PageSnapshot>;
+    /**
+     * Export the current ref map for cross-exec reuse (CLI).
+     */
+    exportRefMap(): Record<string, number>;
+    /**
+     * Import a ref map previously captured from a snapshot.
+     */
+    importRefMap(refMap: Record<string, number>): void;
     /**
      * Execute a batch of steps
      */

package/dist/{types-Cs89wle0.d.cts → types-C6m0bT04.d.cts}

@@ -626,6 +626,14 @@ declare class Page {
      * Get an accessibility tree snapshot of the page
      */
     snapshot(): Promise<PageSnapshot>;
+    /**
+     * Export the current ref map for cross-exec reuse (CLI).
+     */
+    exportRefMap(): Record<string, number>;
+    /**
+     * Import a ref map previously captured from a snapshot.
+     */
+    importRefMap(refMap: Record<string, number>): void;
     /**
      * Execute a batch of steps
      */

package/package.json

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