browser-pilot 0.0.3 → 0.0.5

package/dist/cli.mjs

@@ -2,14 +2,14 @@
 import "./chunk-ZIQA4JOT.mjs";
 import {
   connect
-} from "./chunk-CWSTSVWO.mjs";
+} from "./chunk-NP56KSAN.mjs";
 import "./chunk-BCOZUKWS.mjs";
 import {
   getBrowserWebSocketUrl
 } from "./chunk-R3PS4PCM.mjs";
 import {
   addBatchToPage
-} from "./chunk-YEHK2XY3.mjs";
+} from "./chunk-6RB3GKQP.mjs";
 
 // src/cli/commands/actions.ts
 var ACTIONS_HELP = `
@@ -272,6 +272,60 @@ async function getDefaultSession() {
   return sessions[0] ?? null;
 }
 
+// src/cli/commands/clean.ts
+function parseCleanArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--max-age") {
+      const value = args[++i];
+      options.maxAge = parseInt(value ?? "24", 10);
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--all") {
+      options.all = true;
+    }
+  }
+  return options;
+}
+async function cleanCommand(args, globalOptions) {
+  const options = parseCleanArgs(args);
+  const maxAgeMs = (options.maxAge ?? 24) * 60 * 60 * 1e3;
+  const now = Date.now();
+  const sessions = await listSessions();
+  const stale = sessions.filter((s) => {
+    if (options.all) return true;
+    const age = now - new Date(s.lastActivity).getTime();
+    return age > maxAgeMs;
+  });
+  if (stale.length === 0) {
+    output({ message: "No stale sessions found", cleaned: 0 }, globalOptions.output);
+    return;
+  }
+  if (options.dryRun) {
+    output(
+      {
+        message: `Would clean ${stale.length} session(s)`,
+        sessions: stale.map((s) => s.id),
+        dryRun: true
+      },
+      globalOptions.output
+    );
+    return;
+  }
+  for (const session of stale) {
+    await deleteSession(session.id);
+  }
+  output(
+    {
+      message: `Cleaned ${stale.length} session(s)`,
+      cleaned: stale.length,
+      sessions: stale.map((s) => s.id)
+    },
+    globalOptions.output
+  );
+}
+
 // src/cli/commands/close.ts
 async function closeCommand(args, globalOptions) {
   let session;
@@ -390,6 +444,17 @@ async function connectCommand(args, globalOptions) {
 }
 
 // src/cli/commands/exec.ts
+async function validateSession(session) {
+  try {
+    const wsUrl = new URL(session.wsUrl);
+    const protocol = wsUrl.protocol === "wss:" ? "https:" : "http:";
+    const httpUrl = `${protocol}//${wsUrl.host}/json/version`;
+    const response = await fetch(httpUrl, { signal: AbortSignal.timeout(3e3) });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
 function parseExecArgs(args) {
   const options = {};
   let actionsJson;
@@ -410,15 +475,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 +490,23 @@ 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 isValid = await validateSession(session);
+  if (!isValid) {
+    await deleteSession(session.id);
+    throw new Error(
+      `Session "${session.id}" is no longer valid (browser may have closed).
+Session file has been cleaned up. Run "bp connect" to create a new session.`
+    );
+  }
   const browser = await connect({
     provider: session.provider,
     wsUrl: session.wsUrl,
@@ -533,67 +606,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 +837,31 @@ 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
-
-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"}]'
+  list        List sessions
+  clean       Clean up old sessions
+  actions     Complete action reference
 
-  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) {
@@ -849,7 +892,10 @@ function output(data, format = "pretty") {
     if (typeof data === "string") {
       console.log(data);
     } else if (typeof data === "object" && data !== null) {
-      prettyPrint(data);
+      const { truncated } = prettyPrint(data);
+      if (truncated) {
+        console.log("\n(Output truncated. Use -o json for full data)");
+      }
     } else {
       console.log(data);
     }
@@ -857,16 +903,20 @@ function output(data, format = "pretty") {
 }
 function prettyPrint(obj, indent = 0) {
   const prefix = "  ".repeat(indent);
+  let truncated = false;
   for (const [key, value] of Object.entries(obj)) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
       console.log(`${prefix}${key}:`);
-      prettyPrint(value, indent + 1);
+      const result = prettyPrint(value, indent + 1);
+      if (result.truncated) truncated = true;
     } else if (Array.isArray(value)) {
       console.log(`${prefix}${key}: [${value.length} items]`);
+      truncated = true;
     } else {
       console.log(`${prefix}${key}: ${value}`);
     }
   }
+  return { truncated };
 }
 async function main() {
   const args = process.argv.slice(2);
@@ -906,6 +956,9 @@ async function main() {
       case "list":
         await listCommand(remaining, options);
         break;
+      case "clean":
+        await cleanCommand(remaining, options);
+        break;
       case "actions":
         await actionsCommand();
         break;

package/dist/index.cjs

@@ -134,7 +134,8 @@ var BatchExecutor = class {
         await this.page.fill(step.selector, step.value, {
           timeout,
           optional,
-          clear: step.clear ?? true
+          clear: step.clear ?? true,
+          blur: step.blur
         });
         return { selectorUsed: this.getUsedSelector(step.selector) };
       }
@@ -1353,7 +1354,7 @@ var Page = class {
    * Fill an input field (clears first by default)
    */
   async fill(selector, value, options = {}) {
-    const { clear = true } = options;
+    const { clear = true, blur = false } = options;
     return this.withStaleNodeRetry(async () => {
       const element = await this.findElement(selector, options);
       if (!element) {
@@ -1367,7 +1368,11 @@ var Page = class {
             const el = document.querySelector(${JSON.stringify(element.selector)});
             if (el) {
               el.value = '';
-              el.dispatchEvent(new Event('input', { bubbles: true }));
+              el.dispatchEvent(new InputEvent('input', {
+                bubbles: true,
+                cancelable: true,
+                inputType: 'deleteContent'
+              }));
             }
           })()`
         );
@@ -1377,11 +1382,21 @@ var Page = class {
         `(() => {
           const el = document.querySelector(${JSON.stringify(element.selector)});
           if (el) {
-            el.dispatchEvent(new Event('input', { bubbles: true }));
+            el.dispatchEvent(new InputEvent('input', {
+              bubbles: true,
+              cancelable: true,
+              inputType: 'insertText',
+              data: ${JSON.stringify(value)}
+            }));
             el.dispatchEvent(new Event('change', { bubbles: true }));
           }
         })()`
       );
+      if (blur) {
+        await this.evaluateInFrame(
+          `document.querySelector(${JSON.stringify(element.selector)})?.blur()`
+        );
+      }
       return true;
     });
   }

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 export { BatchExecutor, addBatchToPage } from './actions.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';
+import { R as RequestPattern, a as RequestHandler } from './types-DQhA8uQZ.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-DQhA8uQZ.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-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';
+import { R as RequestPattern, a as RequestHandler } from './types-DKz34hii.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-DKz34hii.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-CWSTSVWO.mjs";
+} from "./chunk-NP56KSAN.mjs";
 import {
   CDPError,
   createCDPClient
@@ -33,7 +33,7 @@ import {
 import {
   BatchExecutor,
   addBatchToPage
-} from "./chunk-YEHK2XY3.mjs";
+} from "./chunk-6RB3GKQP.mjs";
 export {
   BatchExecutor,
   Browser,

package/dist/{types-BJv2dzu0.d.ts → types-DKz34hii.d.ts}

@@ -68,6 +68,8 @@ interface ActionOptions {
 interface FillOptions extends ActionOptions {
     /** Clear existing content before filling */
     clear?: boolean;
+    /** Trigger blur after filling (useful for React/Vue frameworks that update on blur) */
+    blur?: boolean;
 }
 interface TypeOptions extends ActionOptions {
     /** Delay between keystrokes in ms */
@@ -866,6 +868,8 @@ interface Step {
     method?: 'enter' | 'click' | 'enter+click';
     /** Clear input before filling */
     clear?: boolean;
+    /** Trigger blur after filling (for React/Vue frameworks) */
+    blur?: boolean;
     /** Delay between keystrokes for type action */
     delay?: number;
     /** Wait for navigation after click action completes */

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

@@ -68,6 +68,8 @@ interface ActionOptions {
 interface FillOptions extends ActionOptions {
     /** Clear existing content before filling */
     clear?: boolean;
+    /** Trigger blur after filling (useful for React/Vue frameworks that update on blur) */
+    blur?: boolean;
 }
 interface TypeOptions extends ActionOptions {
     /** Delay between keystrokes in ms */
@@ -866,6 +868,8 @@ interface Step {
     method?: 'enter' | 'click' | 'enter+click';
     /** Clear input before filling */
     clear?: boolean;
+    /** Trigger blur after filling (for React/Vue frameworks) */
+    blur?: boolean;
     /** Delay between keystrokes for type action */
     delay?: number;
     /** Wait for navigation after click action completes */

package/package.json

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