browser-pilot 0.0.2 → 0.0.4

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);
@@ -3166,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":"..."}'
@@ -3190,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,
@@ -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,69 @@ function getAge(date) {
   return `${days}d ago`;
 }
 
+// src/cli/commands/quickstart.ts
+var QUICKSTART = `
+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
+  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);
+}
+
 // src/cli/commands/screenshot.ts
 function parseScreenshotArgs(args) {
   const options = {};
@@ -3362,7 +3472,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,54 +3548,30 @@ Usage:
   bp <command> [options]
 
 Commands:
-  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. 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"}'
-
-  Refs are stable until 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
-
-  # Navigate and get snapshot with refs
   bp exec '{"action":"goto","url":"https://example.com"}'
   bp snapshot --format text
+  bp exec '{"action":"click","selector":"ref:e3"}'
 
-  # Use ref from snapshot (most reliable)
-  bp exec '{"action":"click","selector":"ref:e4"}'
-  bp exec '{"action":"fill","selector":"ref:e5","value":"test@example.com"}'
-
-  # Handle native dialogs (alert/confirm/prompt)
-  bp exec --dialog accept '{"action":"click","selector":"#delete-btn"}'
-
-  # Batch multiple actions
-  bp exec '[
-    {"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) {
@@ -3540,6 +3635,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);
@@ -407,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":"..."}'
@@ -431,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,
@@ -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,69 @@ function getAge(date) {
   return `${days}d ago`;
 }
 
+// src/cli/commands/quickstart.ts
+var QUICKSTART = `
+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
+  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);
+}
+
 // src/cli/commands/screenshot.ts
 function parseScreenshotArgs(args) {
   const options = {};
@@ -603,7 +688,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,54 +764,30 @@ Usage:
   bp <command> [options]
 
 Commands:
-  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
-
-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. 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"}'
+  list        List sessions
+  actions     Complete action reference
 
-  Refs are stable until 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
-
-  # Navigate and get snapshot with refs
   bp exec '{"action":"goto","url":"https://example.com"}'
   bp snapshot --format text
+  bp exec '{"action":"click","selector":"ref:e3"}'
 
-  # Use ref from snapshot (most reliable)
-  bp exec '{"action":"click","selector":"ref:e4"}'
-  bp exec '{"action":"fill","selector":"ref:e5","value":"test@example.com"}'
-
-  # Handle native dialogs (alert/confirm/prompt)
-  bp exec --dialog accept '{"action":"click","selector":"#delete-btn"}'
-
-  # Batch multiple actions
-  bp exec '[
-    {"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) {
@@ -781,6 +851,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.2",
+  "version": "0.0.4",
   "description": "Lightweight CDP-based browser automation for Node.js, Bun, and Cloudflare Workers",
   "type": "module",
   "main": "./dist/index.cjs",