browser-pilot 0.0.7 → 0.0.8

package/dist/cli.cjs

@@ -209,6 +209,18 @@ EXAMPLES
     {"action":"click","selector":"#delete-btn"},
     {"action":"wait","selector":"#success-message","waitFor":"visible"}
   ]'
+
+DEBUGGING
+  When actions fail, use these diagnostic tools:
+
+  bp diagnose '#selector'               # Why can't this be found?
+  bp diagnose '#selector' --json        # Machine-readable output
+  bp snapshot --diff prev.json          # What changed on the page?
+  bp snapshot --inspect                 # Visual ref labels on page
+  bp list -s <id> --log-tail 10         # Recent command history
+
+  Failure hints are included in error output when element not found.
+  Use --json output for detailed hints with alternative selectors.
 `;
 async function actionsCommand() {
   console.log(ACTIONS_HELP);
@@ -219,20 +231,20 @@ var import_node_os = require("os");
 var import_node_path = require("path");
 var SESSION_DIR = (0, import_node_path.join)((0, import_node_os.homedir)(), ".browser-pilot", "sessions");
 async function ensureSessionDir() {
-  const fs = await import("fs/promises");
-  await fs.mkdir(SESSION_DIR, { recursive: true });
+  const fs3 = await import("fs/promises");
+  await fs3.mkdir(SESSION_DIR, { recursive: true });
 }
 async function saveSession(session) {
   await ensureSessionDir();
-  const fs = await import("fs/promises");
+  const fs3 = await import("fs/promises");
   const filePath = (0, import_node_path.join)(SESSION_DIR, `${session.id}.json`);
-  await fs.writeFile(filePath, JSON.stringify(session, null, 2));
+  await fs3.writeFile(filePath, JSON.stringify(session, null, 2));
 }
 async function loadSession(id) {
-  const fs = await import("fs/promises");
+  const fs3 = await import("fs/promises");
   const filePath = (0, import_node_path.join)(SESSION_DIR, `${id}.json`);
   try {
-    const content = await fs.readFile(filePath, "utf-8");
+    const content = await fs3.readFile(filePath, "utf-8");
     return JSON.parse(content);
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -254,10 +266,10 @@ async function updateSession(id, updates) {
   return updated;
 }
 async function deleteSession(id) {
-  const fs = await import("fs/promises");
+  const fs3 = await import("fs/promises");
   const filePath = (0, import_node_path.join)(SESSION_DIR, `${id}.json`);
   try {
-    await fs.unlink(filePath);
+    await fs3.unlink(filePath);
   } catch (error) {
     if (error.code !== "ENOENT") {
       throw error;
@@ -266,14 +278,14 @@ async function deleteSession(id) {
 }
 async function listSessions() {
   await ensureSessionDir();
-  const fs = await import("fs/promises");
+  const fs3 = await import("fs/promises");
   try {
-    const files = await fs.readdir(SESSION_DIR);
+    const files = await fs3.readdir(SESSION_DIR);
     const sessions = [];
     for (const file of files) {
       if (file.endsWith(".json")) {
         try {
-          const content = await fs.readFile((0, import_node_path.join)(SESSION_DIR, file), "utf-8");
+          const content = await fs3.readFile((0, import_node_path.join)(SESSION_DIR, file), "utf-8");
           sessions.push(JSON.parse(content));
         } catch {
         }
@@ -350,6 +362,25 @@ async function cleanCommand(args, globalOptions) {
   );
 }
 
+// src/browser/types.ts
+var ElementNotFoundError = class extends Error {
+  selectors;
+  hints;
+  constructor(selectors, hints) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    super(`Element not found: ${selectorList.join(", ")}`);
+    this.name = "ElementNotFoundError";
+    this.selectors = selectorList;
+    this.hints = hints;
+  }
+};
+var TimeoutError = class extends Error {
+  constructor(message = "Operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+
 // src/actions/executor.ts
 var DEFAULT_TIMEOUT = 3e4;
 var BatchExecutor = class {
@@ -381,13 +412,15 @@ var BatchExecutor = class {
         });
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
+        const hints = error instanceof ElementNotFoundError ? error.hints : void 0;
         results.push({
           index: i,
           action: step.action,
           selector: step.selector,
           success: false,
           durationMs: Date.now() - stepStart,
-          error: errorMessage
+          error: errorMessage,
+          hints
         });
         if (onFail === "stop" && !step.optional) {
           return {
@@ -522,7 +555,7 @@ var BatchExecutor = class {
       case "wait": {
         if (!step.selector && !step.waitFor) {
           const delay = step.timeout ?? 1e3;
-          await new Promise((resolve) => setTimeout(resolve, delay));
+          await new Promise((resolve2) => setTimeout(resolve2, delay));
           return {};
         }
         if (step.waitFor === "navigation") {
@@ -583,10 +616,12 @@ var BatchExecutor = class {
     }
   }
   /**
-   * Get the first selector if multiple were provided
-   * (actual used selector tracking would need to be implemented in Page)
+   * Get the actual selector that matched the element.
+   * Uses the last matched selector tracked by Page, falls back to first selector if unavailable.
    */
   getUsedSelector(selector) {
+    const matched = this.page.getLastMatchedSelector();
+    if (matched) return matched;
     return Array.isArray(selector) ? selector[0] : selector;
   }
 };
@@ -612,7 +647,7 @@ var CDPError = class extends Error {
 // src/cdp/transport.ts
 function createTransport(wsUrl, options = {}) {
   const { timeout = 3e4 } = options;
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const timeoutId = setTimeout(() => {
       reject(new Error(`WebSocket connection timeout after ${timeout}ms`));
     }, timeout);
@@ -657,7 +692,7 @@ function createTransport(wsUrl, options = {}) {
           errorHandlers.push(handler);
         }
       };
-      resolve(transport);
+      resolve2(transport);
     });
     ws.addEventListener("message", (event) => {
       const data = typeof event.data === "string" ? event.data : String(event.data);
@@ -781,13 +816,13 @@ async function createCDPClient(wsUrl, options = {}) {
       if (debug) {
         console.log("[CDP] -->", message.slice(0, 500));
       }
-      return new Promise((resolve, reject) => {
+      return new Promise((resolve2, reject) => {
         const timer = setTimeout(() => {
           pending.delete(id);
           reject(new Error(`CDP command ${method} timed out after ${timeout}ms`));
         }, timeout);
         pending.set(id, {
-          resolve,
+          resolve: resolve2,
           reject,
           method,
           timer
@@ -1285,7 +1320,7 @@ async function isElementAttached(cdp, selector, contextId) {
   return result.result.value === true;
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 async function waitForAnyElement(cdp, selectors, options = {}) {
   const { state = "visible", timeout = 3e4, pollInterval = 100, contextId } = options;
@@ -1332,14 +1367,14 @@ async function waitForNavigation(cdp, options = {}) {
   } catch {
     startUrl = "";
   }
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     let resolved = false;
     const cleanup = [];
     const done = (success) => {
       if (resolved) return;
       resolved = true;
       for (const fn of cleanup) fn();
-      resolve({ success, waitedMs: Date.now() - startTime });
+      resolve2({ success, waitedMs: Date.now() - startTime });
     };
     const timer = setTimeout(() => done(false), timeout);
     cleanup.push(() => clearTimeout(timer));
@@ -1380,19 +1415,19 @@ async function waitForNetworkIdle(cdp, options = {}) {
   const { timeout = 3e4, idleTime = 500 } = options;
   const startTime = Date.now();
   await cdp.send("Network.enable");
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     let inFlight = 0;
     let idleTimer = null;
     const timeoutTimer = setTimeout(() => {
       cleanup();
-      resolve({ success: false, waitedMs: Date.now() - startTime });
+      resolve2({ success: false, waitedMs: Date.now() - startTime });
     }, timeout);
     const checkIdle = () => {
       if (inFlight === 0) {
         if (idleTimer) clearTimeout(idleTimer);
         idleTimer = setTimeout(() => {
           cleanup();
-          resolve({ success: true, waitedMs: Date.now() - startTime });
+          resolve2({ success: true, waitedMs: Date.now() - startTime });
         }, idleTime);
       }
     };
@@ -1421,27 +1456,256 @@ async function waitForNetworkIdle(cdp, options = {}) {
   });
 }
 
-// src/browser/types.ts
-var ElementNotFoundError = class extends Error {
-  selectors;
-  constructor(selectors) {
-    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
-    super(`Element not found: ${selectorList.join(", ")}`);
-    this.name = "ElementNotFoundError";
-    this.selectors = selectorList;
+// src/browser/fuzzy-match.ts
+function jaroWinkler(a, b) {
+  if (a.length === 0 && b.length === 0) return 0;
+  if (a.length === 0 || b.length === 0) return 0;
+  if (a === b) return 1;
+  const s1 = a.toLowerCase();
+  const s2 = b.toLowerCase();
+  const matchWindow = Math.max(0, Math.floor(Math.max(s1.length, s2.length) / 2) - 1);
+  const s1Matches = new Array(s1.length).fill(false);
+  const s2Matches = new Array(s2.length).fill(false);
+  let matches = 0;
+  let transpositions = 0;
+  for (let i = 0; i < s1.length; i++) {
+    const start = Math.max(0, i - matchWindow);
+    const end = Math.min(i + matchWindow + 1, s2.length);
+    for (let j = start; j < end; j++) {
+      if (s2Matches[j] || s1[i] !== s2[j]) continue;
+      s1Matches[i] = true;
+      s2Matches[j] = true;
+      matches++;
+      break;
+    }
+  }
+  if (matches === 0) return 0;
+  let k = 0;
+  for (let i = 0; i < s1.length; i++) {
+    if (!s1Matches[i]) continue;
+    while (!s2Matches[k]) k++;
+    if (s1[i] !== s2[k]) transpositions++;
+    k++;
+  }
+  const jaro = (matches / s1.length + matches / s2.length + (matches - transpositions / 2) / matches) / 3;
+  let prefix = 0;
+  for (let i = 0; i < Math.min(4, Math.min(s1.length, s2.length)); i++) {
+    if (s1[i] === s2[i]) {
+      prefix++;
+    } else {
+      break;
+    }
   }
-};
-var TimeoutError = class extends Error {
-  constructor(message = "Operation timed out") {
-    super(message);
-    this.name = "TimeoutError";
+  const WINKLER_SCALING = 0.1;
+  return jaro + prefix * WINKLER_SCALING * (1 - jaro);
+}
+function stringSimilarity(a, b) {
+  if (a.length === 0 || b.length === 0) return 0;
+  const lowerA = a.toLowerCase();
+  const lowerB = b.toLowerCase();
+  if (lowerA === lowerB) return 1;
+  const jw = jaroWinkler(a, b);
+  let containsBonus = 0;
+  if (lowerB.includes(lowerA)) {
+    containsBonus = 0.2;
+  } else if (lowerA.includes(lowerB)) {
+    containsBonus = 0.1;
+  }
+  return Math.min(1, jw + containsBonus);
+}
+function scoreElement(query, element) {
+  const lowerQuery = query.toLowerCase();
+  const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
+  let nameScore = 0;
+  if (element.name) {
+    const lowerName = element.name.toLowerCase();
+    if (lowerName === lowerQuery) {
+      nameScore = 1;
+    } else if (lowerName.includes(lowerQuery)) {
+      nameScore = 0.8;
+    } else if (words.length > 0) {
+      const matchedWords = words.filter((w) => lowerName.includes(w));
+      nameScore = matchedWords.length / words.length * 0.7;
+    } else {
+      nameScore = stringSimilarity(query, element.name) * 0.6;
+    }
+  }
+  let roleScore = 0;
+  const lowerRole = element.role.toLowerCase();
+  if (lowerRole === lowerQuery || lowerQuery.includes(lowerRole)) {
+    roleScore = 0.3;
+  } else if (words.some((w) => lowerRole.includes(w))) {
+    roleScore = 0.2;
   }
+  let selectorScore = 0;
+  const lowerSelector = element.selector.toLowerCase();
+  if (words.some((w) => lowerSelector.includes(w))) {
+    selectorScore = 0.2;
+  }
+  const totalScore = nameScore * 0.6 + roleScore * 0.25 + selectorScore * 0.15;
+  return totalScore;
+}
+function explainMatch(query, element, score) {
+  const reasons = [];
+  const lowerQuery = query.toLowerCase();
+  const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
+  if (element.name) {
+    const lowerName = element.name.toLowerCase();
+    if (lowerName === lowerQuery) {
+      reasons.push("exact name match");
+    } else if (lowerName.includes(lowerQuery)) {
+      reasons.push("name contains query");
+    } else if (words.some((w) => lowerName.includes(w))) {
+      const matchedWords = words.filter((w) => lowerName.includes(w));
+      reasons.push(`name contains: ${matchedWords.join(", ")}`);
+    } else if (stringSimilarity(query, element.name) > 0.5) {
+      reasons.push("similar name");
+    }
+  }
+  const lowerRole = element.role.toLowerCase();
+  if (lowerRole === lowerQuery || words.some((w) => w === lowerRole)) {
+    reasons.push(`role: ${element.role}`);
+  }
+  if (words.some((w) => element.selector.toLowerCase().includes(w))) {
+    reasons.push("selector match");
+  }
+  if (reasons.length === 0) {
+    reasons.push(`fuzzy match (score: ${score.toFixed(2)})`);
+  }
+  return reasons.join(", ");
+}
+function fuzzyMatchElements(query, elements, maxResults = 5) {
+  if (!query || query.length === 0) {
+    return [];
+  }
+  const THRESHOLD = 0.3;
+  const scored = elements.map((element) => ({
+    element,
+    score: scoreElement(query, element)
+  }));
+  return scored.filter((s) => s.score >= THRESHOLD).sort((a, b) => b.score - a.score).slice(0, maxResults).map((s) => ({
+    element: s.element,
+    score: s.score,
+    matchReason: explainMatch(query, s.element, s.score)
+  }));
+}
+
+// src/browser/hint-generator.ts
+var ACTION_ROLE_MAP = {
+  click: ["button", "link", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "option"],
+  fill: ["textbox", "searchbox", "textarea"],
+  type: ["textbox", "searchbox", "textarea"],
+  submit: ["button", "form"],
+  select: ["combobox", "listbox", "option"],
+  check: ["checkbox", "radio", "switch"],
+  uncheck: ["checkbox", "switch"],
+  focus: [],
+  // Any focusable element
+  hover: [],
+  // Any element
+  clear: ["textbox", "searchbox", "textarea"]
 };
+function extractIntent(selectors) {
+  const patterns = [];
+  let text = "";
+  for (const selector of selectors) {
+    if (selector.startsWith("ref:")) {
+      continue;
+    }
+    const idMatch = selector.match(/#([a-zA-Z0-9_-]+)/);
+    if (idMatch) {
+      patterns.push(idMatch[1]);
+    }
+    const ariaMatch = selector.match(/\[aria-label=["']([^"']+)["']\]/);
+    if (ariaMatch) {
+      patterns.push(ariaMatch[1]);
+    }
+    const testidMatch = selector.match(/\[data-testid=["']([^"']+)["']\]/);
+    if (testidMatch) {
+      patterns.push(testidMatch[1]);
+    }
+    const classMatch = selector.match(/\.([a-zA-Z0-9_-]+)/);
+    if (classMatch) {
+      patterns.push(classMatch[1]);
+    }
+  }
+  patterns.sort((a, b) => b.length - a.length);
+  text = patterns[0] ?? selectors[0] ?? "";
+  return { text, patterns };
+}
+function getHintType(selector) {
+  if (selector.startsWith("ref:")) return "ref";
+  if (selector.includes("data-testid")) return "testid";
+  if (selector.includes("aria-label")) return "aria";
+  if (selector.startsWith("#")) return "id";
+  return "css";
+}
+function getConfidence(score) {
+  if (score >= 0.8) return "high";
+  if (score >= 0.5) return "medium";
+  return "low";
+}
+function diversifyHints(candidates, maxHints) {
+  const hints = [];
+  const usedTypes = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    if (hints.length >= maxHints) break;
+    const refSelector = `ref:${candidate.element.ref}`;
+    const hintType = getHintType(refSelector);
+    if (!usedTypes.has(hintType)) {
+      hints.push({
+        selector: refSelector,
+        reason: candidate.matchReason,
+        confidence: getConfidence(candidate.score),
+        element: {
+          ref: candidate.element.ref,
+          role: candidate.element.role,
+          name: candidate.element.name,
+          disabled: candidate.element.disabled
+        }
+      });
+      usedTypes.add(hintType);
+    } else if (hints.length < maxHints) {
+      hints.push({
+        selector: refSelector,
+        reason: candidate.matchReason,
+        confidence: getConfidence(candidate.score),
+        element: {
+          ref: candidate.element.ref,
+          role: candidate.element.role,
+          name: candidate.element.name,
+          disabled: candidate.element.disabled
+        }
+      });
+    }
+  }
+  return hints;
+}
+async function generateHints(page, failedSelectors, actionType, maxHints = 3) {
+  let snapshot;
+  try {
+    snapshot = await page.snapshot();
+  } catch {
+    return [];
+  }
+  const intent = extractIntent(failedSelectors);
+  const roleFilter = ACTION_ROLE_MAP[actionType] ?? [];
+  let candidates = snapshot.interactiveElements;
+  if (roleFilter.length > 0) {
+    candidates = candidates.filter((el) => roleFilter.includes(el.role));
+  }
+  const matches = fuzzyMatchElements(intent.text, candidates, maxHints * 2);
+  if (matches.length === 0) {
+    return [];
+  }
+  return diversifyHints(matches, maxHints);
+}
 
 // src/browser/page.ts
 var DEFAULT_TIMEOUT2 = 3e4;
 var Page = class {
   cdp;
+  _targetId;
   rootNodeId = null;
   batchExecutor;
   emulationState = {};
@@ -1460,10 +1724,19 @@ var Page = class {
   frameExecutionContexts = /* @__PURE__ */ new Map();
   /** Current frame's execution context ID (null = main frame default) */
   currentFrameContextId = null;
-  constructor(cdp) {
+  /** Last matched selector from findElement (for selectorUsed tracking) */
+  _lastMatchedSelector;
+  constructor(cdp, targetId) {
     this.cdp = cdp;
+    this._targetId = targetId;
     this.batchExecutor = new BatchExecutor(this);
   }
+  /**
+   * Get the CDP target ID for this page
+   */
+  get targetId() {
+    return this._targetId;
+  }
   /**
    * Get the underlying CDP client for advanced operations.
    * Use with caution - prefer high-level Page methods when possible.
@@ -1471,6 +1744,13 @@ var Page = class {
   get cdpClient() {
     return this.cdp;
   }
+  /**
+   * Get the last matched selector from findElement (for selectorUsed tracking).
+   * Returns undefined if no selector has been matched yet.
+   */
+  getLastMatchedSelector() {
+    return this._lastMatchedSelector;
+  }
   /**
    * Initialize the page (enable required CDP domains)
    */
@@ -1590,7 +1870,9 @@ var Page = class {
       const element = await this.findElement(selector, options);
       if (!element) {
         if (options.optional) return false;
-        throw new ElementNotFoundError(selector);
+        const selectorList = Array.isArray(selector) ? selector : [selector];
+        const hints = await generateHints(this, selectorList, "click");
+        throw new ElementNotFoundError(selector, hints);
       }
       await this.scrollIntoView(element.nodeId);
       const submitResult = await this.evaluateInFrame(
@@ -1626,7 +1908,9 @@ var Page = class {
       const element = await this.findElement(selector, options);
       if (!element) {
         if (options.optional) return false;
-        throw new ElementNotFoundError(selector);
+        const selectorList = Array.isArray(selector) ? selector : [selector];
+        const hints = await generateHints(this, selectorList, "fill");
+        throw new ElementNotFoundError(selector, hints);
       }
       await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
       if (clear) {
@@ -1704,7 +1988,9 @@ var Page = class {
     const element = await this.findElement(selector, options);
     if (!element) {
       if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+      const selectorList = Array.isArray(selector) ? selector : [selector];
+      const hints = await generateHints(this, selectorList, "select");
+      throw new ElementNotFoundError(selector, hints);
     }
     const values = Array.isArray(value) ? value : [value];
     await this.cdp.send("Runtime.evaluate", {
@@ -1765,7 +2051,9 @@ var Page = class {
     const element = await this.findElement(selector, options);
     if (!element) {
       if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+      const selectorList = Array.isArray(selector) ? selector : [selector];
+      const hints = await generateHints(this, selectorList, "check");
+      throw new ElementNotFoundError(selector, hints);
     }
     const result = await this.cdp.send("Runtime.evaluate", {
       expression: `(() => {
@@ -1785,7 +2073,9 @@ var Page = class {
     const element = await this.findElement(selector, options);
     if (!element) {
       if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+      const selectorList = Array.isArray(selector) ? selector : [selector];
+      const hints = await generateHints(this, selectorList, "uncheck");
+      throw new ElementNotFoundError(selector, hints);
     }
     const result = await this.cdp.send("Runtime.evaluate", {
       expression: `(() => {
@@ -1805,13 +2095,40 @@ var Page = class {
    * - 'auto' (default): Attempt to detect navigation for 1 second, then assume client-side handling
    * - true: Wait for full navigation (traditional forms)
    * - false: Return immediately (AJAX forms where you'll wait for something else)
+   *
+   * When targeting a <form> element directly, uses form.requestSubmit() which fires
+   * the submit event and triggers HTML5 validation.
    */
   async submit(selector, options = {}) {
     const { method = "enter+click", waitForNavigation: shouldWait = "auto" } = options;
     const element = await this.findElement(selector, options);
     if (!element) {
       if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+      const selectorList = Array.isArray(selector) ? selector : [selector];
+      const hints = await generateHints(this, selectorList, "submit");
+      throw new ElementNotFoundError(selector, hints);
+    }
+    const isFormElement = await this.evaluateInFrame(
+      `(() => {
+        const el = document.querySelector(${JSON.stringify(element.selector)});
+        return el instanceof HTMLFormElement;
+      })()`
+    );
+    if (isFormElement.result.value) {
+      await this.evaluateInFrame(
+        `(() => {
+          const form = document.querySelector(${JSON.stringify(element.selector)});
+          if (form && form instanceof HTMLFormElement) {
+            form.requestSubmit();
+          }
+        })()`
+      );
+      if (shouldWait === true) {
+        await this.waitForNavigation({ timeout: options.timeout ?? DEFAULT_TIMEOUT2 });
+      } else if (shouldWait === "auto") {
+        await Promise.race([this.waitForNavigation({ timeout: 1e3, optional: true }), sleep2(500)]);
+      }
+      return true;
     }
     await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
     if (method.includes("enter")) {
@@ -1882,7 +2199,9 @@ var Page = class {
     const element = await this.findElement(selector, options);
     if (!element) {
       if (options.optional) return false;
-      throw new ElementNotFoundError(selector);
+      const selectorList = Array.isArray(selector) ? selector : [selector];
+      const hints = await generateHints(this, selectorList, "focus");
+      throw new ElementNotFoundError(selector, hints);
     }
     await this.cdp.send("DOM.focus", { nodeId: element.nodeId });
     return true;
@@ -1895,7 +2214,9 @@ var Page = class {
       const element = await this.findElement(selector, options);
       if (!element) {
         if (options.optional) return false;
-        throw new ElementNotFoundError(selector);
+        const selectorList = Array.isArray(selector) ? selector : [selector];
+        const hints = await generateHints(this, selectorList, "hover");
+        throw new ElementNotFoundError(selector, hints);
       }
       await this.scrollIntoView(element.nodeId);
       const box = await this.getBoxModel(element.nodeId);
@@ -1966,7 +2287,7 @@ var Page = class {
       const deadline = Date.now() + timeout;
       let contextId = this.frameExecutionContexts.get(frameId);
       while (!contextId && Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
         contextId = this.frameExecutionContexts.get(frameId);
       }
       if (contextId) {
@@ -2145,7 +2466,7 @@ var Page = class {
       behavior: "allowAndName",
       eventsEnabled: true
     });
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       let downloadGuid;
       let suggestedFilename;
       let resolved = false;
@@ -2169,7 +2490,7 @@ var Page = class {
               return new ArrayBuffer(0);
             }
           };
-          resolve(download);
+          resolve2(download);
         } else if (params["guid"] === downloadGuid && params["state"] === "canceled") {
           resolved = true;
           cleanup();
@@ -2850,6 +3171,7 @@ var Page = class {
   async findElement(selectors, options = {}) {
     const { timeout = DEFAULT_TIMEOUT2 } = options;
     const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    this._lastMatchedSelector = void 0;
     for (const selector of selectorList) {
       if (selector.startsWith("ref:")) {
         const ref = selector.slice(4);
@@ -2866,6 +3188,7 @@ var Page = class {
             }
           );
           if (pushResult.nodeIds?.[0]) {
+            this._lastMatchedSelector = selector;
             return {
               nodeId: pushResult.nodeIds[0],
               backendNodeId,
@@ -2899,6 +3222,7 @@ var Page = class {
         "DOM.describeNode",
         { nodeId: queryResult.nodeId }
       );
+      this._lastMatchedSelector = result.selector;
       return {
         nodeId: queryResult.nodeId,
         backendNodeId: describeResult2.node.backendNodeId,
@@ -2926,6 +3250,7 @@ var Page = class {
       "DOM.describeNode",
       { nodeId: nodeResult.nodeId }
     );
+    this._lastMatchedSelector = result.selector;
     return {
       nodeId: nodeResult.nodeId,
       backendNodeId: describeResult.node.backendNodeId,
@@ -3004,7 +3329,7 @@ var Page = class {
   }
 };
 function sleep2(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
 // src/browser/browser.ts
@@ -3032,14 +3357,24 @@ var Browser = class _Browser {
    * Get or create a page by name
    * If no name is provided, returns the first available page or creates a new one
    */
-  async page(name) {
+  async page(name, options) {
     const pageName = name ?? "default";
     const cached = this.pages.get(pageName);
     if (cached) return cached;
     const targets = await this.cdp.send("Target.getTargets");
     const pageTargets = targets.targetInfos.filter((t) => t.type === "page");
     let targetId;
-    if (pageTargets.length > 0) {
+    if (options?.targetId) {
+      const targetExists = pageTargets.some((t) => t.targetId === options.targetId);
+      if (targetExists) {
+        targetId = options.targetId;
+      } else {
+        console.warn(`[browser-pilot] Target ${options.targetId} no longer exists, falling back`);
+        targetId = pageTargets.length > 0 ? pageTargets[0].targetId : (await this.cdp.send("Target.createTarget", {
+          url: "about:blank"
+        })).targetId;
+      }
+    } else if (pageTargets.length > 0) {
       targetId = pageTargets[0].targetId;
     } else {
       const result = await this.cdp.send("Target.createTarget", {
@@ -3048,7 +3383,7 @@ var Browser = class _Browser {
       targetId = result.targetId;
     }
     await this.cdp.attachToTarget(targetId);
-    const page = new Page(this.cdp);
+    const page = new Page(this.cdp, targetId);
     await page.init();
     this.pages.set(pageName, page);
     return page;
@@ -3061,7 +3396,7 @@ var Browser = class _Browser {
       url
     });
     await this.cdp.attachToTarget(result.targetId);
-    const page = new Page(this.cdp);
+    const page = new Page(this.cdp, result.targetId);
     await page.init();
     const name = `page-${this.pages.size + 1}`;
     this.pages.set(name, page);
@@ -3182,6 +3517,8 @@ function parseConnectArgs(args) {
       options.apiKey = args[++i];
     } else if (arg === "--project-id") {
       options.projectId = args[++i];
+    } else if (arg === "--export-log") {
+      options.exportLog = args[++i];
     }
   }
   return options;
@@ -3230,6 +3567,8 @@ async function connectCommand(args, globalOptions) {
     provider,
     wsUrl: browser.wsUrl,
     providerSessionId: browser.sessionId,
+    targetId: page.targetId,
+    exportLog: options.exportLog,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
     lastActivity: (/* @__PURE__ */ new Date()).toISOString(),
     currentUrl,
@@ -3249,6 +3588,808 @@ async function connectCommand(args, globalOptions) {
   );
 }
 
+// src/browser/selector-generator.ts
+function escapeAttrValue(value) {
+  return value.replace(/"/g, '\\"').replace(/'/g, "\\'");
+}
+function extractTestId(selector) {
+  const patterns = [
+    /\[data-testid=["']([^"']+)["']\]/,
+    /\[data-test-id=["']([^"']+)["']\]/,
+    /\[data-test=["']([^"']+)["']\]/
+  ];
+  for (const pattern of patterns) {
+    const match = selector.match(pattern);
+    if (match) {
+      return match[1] ?? null;
+    }
+  }
+  return null;
+}
+function extractId(selector) {
+  const match = selector.match(/#([a-zA-Z][a-zA-Z0-9_-]*)/);
+  return match ? match[1] ?? null : null;
+}
+function generateRoleSelector(element) {
+  if (!element.role || !element.name) {
+    return null;
+  }
+  const escapedName = escapeAttrValue(element.name);
+  return `[role="${element.role}"][aria-label="${escapedName}"]`;
+}
+function simplifyCssPath(selector) {
+  if (selector.startsWith("#") || selector.startsWith(".") || selector.startsWith("[")) {
+    return selector;
+  }
+  const parts = selector.split(/\s+/);
+  const lastPart = parts[parts.length - 1];
+  if (lastPart && (lastPart.startsWith("#") || lastPart.includes("[") || lastPart.includes("."))) {
+    return lastPart;
+  }
+  return selector;
+}
+function generateSelectors(element, _snapshot) {
+  const selectors = [];
+  if (element.ref) {
+    selectors.push({
+      selector: `ref:${element.ref}`,
+      type: "ref"
+    });
+  }
+  const testId = extractTestId(element.selector);
+  if (testId) {
+    selectors.push({
+      selector: `[data-testid="${escapeAttrValue(testId)}"]`,
+      type: "testid"
+    });
+  }
+  if (element.name) {
+    selectors.push({
+      selector: `[aria-label="${escapeAttrValue(element.name)}"]`,
+      type: "aria-label"
+    });
+  }
+  const id = extractId(element.selector);
+  if (id) {
+    selectors.push({
+      selector: `#${id}`,
+      type: "id"
+    });
+  }
+  const roleSelector = generateRoleSelector(element);
+  if (roleSelector) {
+    selectors.push({
+      selector: roleSelector,
+      type: "role-name"
+    });
+  }
+  const cssPath = simplifyCssPath(element.selector);
+  if (cssPath && !selectors.some((s) => s.selector === cssPath)) {
+    selectors.push({
+      selector: cssPath,
+      type: "css"
+    });
+  }
+  return selectors;
+}
+function generateSelectorStrings(element, snapshot) {
+  return generateSelectors(element, snapshot).map((s) => s.selector);
+}
+
+// src/browser/visibility.ts
+var VISIBILITY_STATE_SCRIPT = `
+function getVisibilityState(selector) {
+  ${DEEP_QUERY_SCRIPT}
+  const el = deepQuery(selector);
+  if (!el) {
+    return null;
+  }
+
+  const style = getComputedStyle(el);
+  const rect = el.getBoundingClientRect();
+
+  const display = style.display;
+  const visibility = style.visibility;
+  const opacity = parseFloat(style.opacity);
+  const width = rect.width;
+  const height = rect.height;
+
+  // Check if in viewport
+  const inViewport = (
+    rect.top < window.innerHeight &&
+    rect.bottom > 0 &&
+    rect.left < window.innerWidth &&
+    rect.right > 0
+  );
+
+  // Collect reasons for invisibility
+  const reasons = [];
+  if (display === 'none') {
+    reasons.push('display: none');
+  }
+  if (visibility === 'hidden') {
+    reasons.push('visibility: hidden');
+  }
+  if (opacity === 0) {
+    reasons.push('opacity: 0');
+  }
+  if (width === 0 && height === 0) {
+    reasons.push('zero dimensions');
+  } else if (width === 0) {
+    reasons.push('zero width');
+  } else if (height === 0) {
+    reasons.push('zero height');
+  }
+  if (!inViewport && width > 0 && height > 0) {
+    reasons.push('outside viewport');
+  }
+
+  const visible = reasons.length === 0;
+
+  return {
+    visible,
+    display,
+    visibility,
+    opacity,
+    width,
+    height,
+    inViewport,
+    reasons
+  };
+}
+`;
+var COVERING_ELEMENT_SCRIPT = `
+function detectCoveringElement(selector) {
+  ${DEEP_QUERY_SCRIPT}
+  const el = deepQuery(selector);
+  if (!el) {
+    return { error: 'Element not found' };
+  }
+
+  const rect = el.getBoundingClientRect();
+
+  // Check center point
+  const centerX = rect.left + rect.width / 2;
+  const centerY = rect.top + rect.height / 2;
+
+  // Get element at center point
+  const topEl = document.elementFromPoint(centerX, centerY);
+
+  if (!topEl) {
+    return { covered: false };
+  }
+
+  // Check if the target element is the top element or contains it
+  if (topEl === el || el.contains(topEl)) {
+    return { covered: false };
+  }
+
+  // Element is covered - get info about covering element
+  const style = getComputedStyle(topEl);
+  return {
+    covered: true,
+    coveringElement: {
+      tagName: topEl.tagName.toLowerCase(),
+      id: topEl.id || undefined,
+      className: topEl.className || undefined,
+      zIndex: style.zIndex === 'auto' ? undefined : parseInt(style.zIndex, 10)
+    }
+  };
+}
+`;
+var VISIBILITY_BY_NODE_SCRIPT = `
+function getVisibilityStateByNode(nodeId) {
+  // This script expects nodeId to be resolved to an element via CDP
+  // It's called after Runtime.callFunctionOn with the target element
+  const el = this;
+  if (!el) {
+    return null;
+  }
+
+  const style = getComputedStyle(el);
+  const rect = el.getBoundingClientRect();
+
+  const display = style.display;
+  const visibility = style.visibility;
+  const opacity = parseFloat(style.opacity);
+  const width = rect.width;
+  const height = rect.height;
+
+  const inViewport = (
+    rect.top < window.innerHeight &&
+    rect.bottom > 0 &&
+    rect.left < window.innerWidth &&
+    rect.right > 0
+  );
+
+  const reasons = [];
+  if (display === 'none') reasons.push('display: none');
+  if (visibility === 'hidden') reasons.push('visibility: hidden');
+  if (opacity === 0) reasons.push('opacity: 0');
+  if (width === 0 && height === 0) reasons.push('zero dimensions');
+  else if (width === 0) reasons.push('zero width');
+  else if (height === 0) reasons.push('zero height');
+  if (!inViewport && width > 0 && height > 0) reasons.push('outside viewport');
+
+  return {
+    visible: reasons.length === 0,
+    display,
+    visibility,
+    opacity,
+    width,
+    height,
+    inViewport,
+    reasons
+  };
+}
+`;
+var COVERING_BY_NODE_SCRIPT = `
+function detectCoveringByNode() {
+  const el = this;
+  if (!el) {
+    return { error: 'Element not found' };
+  }
+
+  const rect = el.getBoundingClientRect();
+  const centerX = rect.left + rect.width / 2;
+  const centerY = rect.top + rect.height / 2;
+
+  const topEl = document.elementFromPoint(centerX, centerY);
+
+  if (!topEl) {
+    return { covered: false };
+  }
+
+  if (topEl === el || el.contains(topEl)) {
+    return { covered: false };
+  }
+
+  const style = getComputedStyle(topEl);
+  return {
+    covered: true,
+    coveringElement: {
+      tagName: topEl.tagName.toLowerCase(),
+      id: topEl.id || undefined,
+      className: topEl.className || undefined,
+      zIndex: style.zIndex === 'auto' ? undefined : parseInt(style.zIndex, 10)
+    }
+  };
+}
+`;
+async function getVisibilityState(cdp, nodeId) {
+  const resolveResult = await cdp.send("DOM.resolveNode", {
+    nodeId
+  });
+  if (!resolveResult.object?.objectId) {
+    return null;
+  }
+  const objectId = resolveResult.object.objectId;
+  const result = await cdp.send(
+    "Runtime.callFunctionOn",
+    {
+      objectId,
+      functionDeclaration: VISIBILITY_BY_NODE_SCRIPT,
+      returnByValue: true
+    }
+  );
+  return result.result.value;
+}
+async function detectCoveringElement(cdp, nodeId) {
+  const resolveResult = await cdp.send("DOM.resolveNode", {
+    nodeId
+  });
+  if (!resolveResult.object?.objectId) {
+    return null;
+  }
+  const objectId = resolveResult.object.objectId;
+  const result = await cdp.send("Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: COVERING_BY_NODE_SCRIPT,
+    returnByValue: true
+  });
+  const value = result.result.value;
+  if (value.error || !value.covered) {
+    return null;
+  }
+  return value.coveringElement ?? null;
+}
+
+// src/browser/diagnose.ts
+function isFuzzyQuery(selector) {
+  if (selector.startsWith("ref:")) return false;
+  if (/^[#.[]/.test(selector)) return false;
+  if (/\[.*\]/.test(selector)) return false;
+  if (/\s/.test(selector) && !/\s*[>+~]\s*/.test(selector)) return true;
+  if (!/[#.[\]>+~:=]/.test(selector)) return true;
+  return false;
+}
+async function tryExactMatch(page, selector) {
+  const cdp = page.cdpClient;
+  if (selector.startsWith("ref:")) {
+    const ref = selector.slice(4);
+    const refMap = page.exportRefMap();
+    const backendNodeId = refMap[ref];
+    if (!backendNodeId) {
+      return { found: false };
+    }
+    try {
+      await cdp.send("DOM.getDocument");
+      const pushResult = await cdp.send(
+        "DOM.pushNodesByBackendIdsToFrontend",
+        {
+          backendNodeIds: [backendNodeId]
+        }
+      );
+      if (pushResult.nodeIds?.[0]) {
+        return {
+          found: true,
+          nodeId: pushResult.nodeIds[0],
+          backendNodeId,
+          selectorUsed: selector
+        };
+      }
+    } catch {
+      return { found: false };
+    }
+  }
+  try {
+    const doc = await cdp.send("DOM.getDocument");
+    const rootNodeId = doc.root.nodeId;
+    const result = await cdp.send("DOM.querySelector", {
+      nodeId: rootNodeId,
+      selector
+    });
+    if (result.nodeId && result.nodeId !== 0) {
+      const describe = await cdp.send("DOM.describeNode", {
+        nodeId: result.nodeId
+      });
+      return {
+        found: true,
+        nodeId: result.nodeId,
+        backendNodeId: describe.node.backendNodeId,
+        selectorUsed: selector
+      };
+    }
+  } catch {
+  }
+  return { found: false };
+}
+async function getElementAttributes(page, nodeId) {
+  const cdp = page.cdpClient;
+  const attributes = {};
+  try {
+    const result = await cdp.send("DOM.getAttributes", {
+      nodeId
+    });
+    for (let i = 0; i < result.attributes.length; i += 2) {
+      const name = result.attributes[i];
+      const value = result.attributes[i + 1];
+      if (name && value !== void 0) {
+        attributes[name] = value;
+      }
+    }
+  } catch {
+  }
+  return attributes;
+}
+async function diagnoseElement(page, selector, options = {}) {
+  const { maxCandidates = 5, includeHidden = false } = options;
+  const cdp = page.cdpClient;
+  const snapshot = await page.snapshot();
+  const fuzzy = isFuzzyQuery(selector);
+  if (!fuzzy) {
+    const match = await tryExactMatch(page, selector);
+    if (match.found && match.nodeId && match.backendNodeId) {
+      const visibility = await getVisibilityState(cdp, match.nodeId) ?? {
+        visible: false,
+        display: "unknown",
+        visibility: "unknown",
+        opacity: 1,
+        width: 0,
+        height: 0,
+        inViewport: false,
+        reasons: ["Could not determine visibility"]
+      };
+      const covering = await detectCoveringElement(cdp, match.nodeId);
+      const attributes = await getElementAttributes(page, match.nodeId);
+      const refMap = page.exportRefMap();
+      let ref = "";
+      for (const [r, bid] of Object.entries(refMap)) {
+        if (bid === match.backendNodeId) {
+          ref = r;
+          break;
+        }
+      }
+      const interactiveEl = snapshot.interactiveElements.find((el) => el.ref === ref);
+      const disabled = attributes["disabled"] !== void 0 || interactiveEl?.disabled === true;
+      const readonly = attributes["readonly"] !== void 0;
+      const covered = covering !== null;
+      const clickable = visibility.visible && !disabled && !covered;
+      let reason;
+      if (!clickable) {
+        const reasons = [];
+        if (!visibility.visible) reasons.push("not visible");
+        if (disabled) reasons.push("disabled");
+        if (covered) reasons.push("covered by another element");
+        reason = reasons.join(", ");
+      }
+      const element = interactiveEl ?? {
+        ref,
+        role: "generic",
+        name: "",
+        selector: match.selectorUsed ?? selector,
+        disabled
+      };
+      const suggestedSelectors = generateSelectorStrings(element, snapshot);
+      return {
+        matched: true,
+        selector: match.selectorUsed ?? selector,
+        ref,
+        element: {
+          role: element.role,
+          name: element.name,
+          nodeId: match.nodeId,
+          backendNodeId: match.backendNodeId
+        },
+        visibility,
+        interactivity: {
+          disabled,
+          readonly,
+          covered,
+          coveringElement: covering ?? void 0,
+          clickable,
+          reason
+        },
+        attributes,
+        suggestedSelectors
+      };
+    }
+  }
+  let candidates = snapshot.interactiveElements;
+  if (!includeHidden) {
+    candidates = candidates.filter((el) => !el.disabled);
+  }
+  const matches = fuzzyMatchElements(selector, candidates, maxCandidates);
+  return {
+    matched: false,
+    query: selector,
+    candidates: matches.map((m) => ({
+      score: m.score,
+      ref: m.element.ref,
+      selector: m.element.selector,
+      role: m.element.role,
+      name: m.element.name,
+      visible: true,
+      // We assume visible since they're interactive
+      disabled: m.element.disabled ?? false,
+      matchReason: m.matchReason
+    }))
+  };
+}
+
+// src/cli/commands/diagnose.ts
+var DIAGNOSE_HELP = `
+bp diagnose - Debug element selection and find alternatives
+
+Usage:
+  bp diagnose <selector>           Diagnose specific selector
+  bp diagnose "<fuzzy query>"      Fuzzy search for elements
+
+Examples:
+  bp diagnose "#login-btn"         Full diagnostics for element
+  bp diagnose "submit"             Find elements matching "submit"
+  bp diagnose "ref:e4"             Diagnose by element ref
+
+Options:
+  --json              Output as JSON
+  --max <n>           Max candidates for fuzzy match (default: 5)
+  -s, --session <id>  Use specific session
+  --help              Show this help
+
+Output (exact match):
+  - Visibility: display, opacity, in viewport
+  - Interactivity: disabled, covered by overlay
+  - Alternative selectors
+
+Output (fuzzy match):
+  - Top N candidates ranked by similarity
+  - Role, name, visibility for each
+`;
+function parseDiagnoseArgs(args) {
+  const options = {};
+  let selector;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--max") {
+      options.maxCandidates = parseInt(args[++i] ?? "5", 10);
+    } else if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (!arg.startsWith("-")) {
+      selector = arg;
+    }
+  }
+  return { selector, options };
+}
+function formatExactResult(result) {
+  const lines = [];
+  lines.push(`\u2713 Element Found: ${result.selector}`);
+  lines.push(`  Ref: ${result.ref}`);
+  lines.push(`  Role: ${result.element.role}`);
+  if (result.element.name) {
+    lines.push(`  Name: "${result.element.name}"`);
+  }
+  lines.push("");
+  lines.push("Visibility:");
+  lines.push(`  Visible: ${result.visibility.visible ? "\u2713 Yes" : "\u2717 No"}`);
+  if (!result.visibility.visible && result.visibility.reasons.length > 0) {
+    lines.push(`  Reasons: ${result.visibility.reasons.join(", ")}`);
+  }
+  lines.push(`  Display: ${result.visibility.display}`);
+  lines.push(`  Opacity: ${result.visibility.opacity}`);
+  lines.push(`  Size: ${result.visibility.width}x${result.visibility.height}`);
+  lines.push(`  In Viewport: ${result.visibility.inViewport ? "Yes" : "No"}`);
+  lines.push("");
+  lines.push("Interactivity:");
+  lines.push(`  Clickable: ${result.interactivity.clickable ? "\u2713 Yes" : "\u2717 No"}`);
+  if (!result.interactivity.clickable && result.interactivity.reason) {
+    lines.push(`  Reason: ${result.interactivity.reason}`);
+  }
+  lines.push(`  Disabled: ${result.interactivity.disabled ? "Yes" : "No"}`);
+  lines.push(`  Readonly: ${result.interactivity.readonly ? "Yes" : "No"}`);
+  lines.push(`  Covered: ${result.interactivity.covered ? "Yes" : "No"}`);
+  if (result.interactivity.coveringElement) {
+    const ce = result.interactivity.coveringElement;
+    lines.push(`  Covering Element: <${ce.tagName}${ce.id ? ` id="${ce.id}"` : ""}>`);
+  }
+  lines.push("");
+  if (result.suggestedSelectors.length > 0) {
+    lines.push("Alternative Selectors:");
+    for (const sel of result.suggestedSelectors) {
+      lines.push(`  - ${sel}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatFuzzyResult(result) {
+  const lines = [];
+  lines.push(`\u2717 No exact match for: "${result.query}"`);
+  lines.push("");
+  if (result.candidates.length === 0) {
+    lines.push("No similar elements found.");
+    return lines.join("\n");
+  }
+  lines.push(`Found ${result.candidates.length} similar elements:`);
+  lines.push("");
+  for (let i = 0; i < result.candidates.length; i++) {
+    const c = result.candidates[i];
+    const score = (c.score * 100).toFixed(0);
+    lines.push(`${i + 1}. [${c.ref}] ${c.role} "${c.name || "(no name)"}" (${score}% match)`);
+    lines.push(`   Selector: ${c.selector}`);
+    lines.push(`   Reason: ${c.matchReason}`);
+    if (c.disabled) {
+      lines.push(`   \u26A0 Disabled`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+async function diagnoseCommand(args, globalOptions) {
+  const { selector, options } = parseDiagnoseArgs(args);
+  if (options.help || !selector) {
+    console.log(DIAGNOSE_HELP);
+    return;
+  }
+  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,
+    debug: globalOptions.trace
+  });
+  try {
+    const page = await browser.page(void 0, { targetId: session.targetId });
+    const result = await diagnoseElement(page, selector, {
+      maxCandidates: options.maxCandidates
+    });
+    const snapshot = await page.snapshot();
+    await updateSession(session.id, {
+      currentUrl: snapshot.url,
+      metadata: {
+        refCache: {
+          url: snapshot.url,
+          savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          refMap: page.exportRefMap()
+        }
+      }
+    });
+    if (globalOptions.output === "json") {
+      output(result, "json");
+    } else {
+      if (result.matched) {
+        console.log(formatExactResult(result));
+      } else {
+        console.log(formatFuzzyResult(result));
+      }
+    }
+  } finally {
+    await browser.disconnect();
+  }
+}
+
+// src/cli/session-logger.ts
+var fs = __toESM(require("fs"), 1);
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+var SESSION_DIR2 = (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".browser-pilot", "sessions");
+var SessionLogger = class {
+  logPath;
+  exportLogPath = null;
+  seq = 0;
+  constructor(sessionId, exportLogPath) {
+    const sessionDir = (0, import_node_path2.join)(SESSION_DIR2, sessionId);
+    this.logPath = (0, import_node_path2.join)(sessionDir, "log.jsonl");
+    if (!fs.existsSync(sessionDir)) {
+      fs.mkdirSync(sessionDir, { recursive: true });
+    }
+    if (exportLogPath) {
+      this.exportLogPath = (0, import_node_path2.resolve)(exportLogPath);
+      const exportDir = (0, import_node_path2.dirname)(this.exportLogPath);
+      if (!fs.existsSync(exportDir)) {
+        fs.mkdirSync(exportDir, { recursive: true });
+      }
+    }
+    if (fs.existsSync(this.logPath)) {
+      this.seq = this.countEntries();
+    }
+  }
+  /**
+   * Log a raw entry (writes to both core and export logs)
+   */
+  log(entry) {
+    const fullEntry = {
+      seq: ++this.seq,
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      ...entry
+    };
+    const line = `${JSON.stringify(fullEntry)}
+`;
+    fs.appendFileSync(this.logPath, line, "utf-8");
+    if (this.exportLogPath) {
+      try {
+        fs.appendFileSync(this.exportLogPath, line, "utf-8");
+      } catch (err) {
+        console.warn(`[browser-pilot] Failed to write to export log: ${err}`);
+      }
+    }
+  }
+  /**
+   * Get the export log path (if configured)
+   */
+  getExportLogPath() {
+    return this.exportLogPath;
+  }
+  /**
+   * Log a command execution
+   */
+  logCommand(cmd, args, result, durationMs) {
+    this.log({
+      type: "command",
+      cmd,
+      args,
+      status: result.success ? "success" : "failed",
+      durationMs,
+      error: result.error,
+      hints: result.hints
+    });
+  }
+  /**
+   * Log an error
+   */
+  logError(error, context) {
+    this.log({
+      type: "error",
+      error: error.message,
+      args: context
+    });
+  }
+  /**
+   * Get the log file path
+   */
+  getLogPath() {
+    return this.logPath;
+  }
+  /**
+   * Get log statistics
+   */
+  getLogStats() {
+    if (!fs.existsSync(this.logPath)) {
+      return { entries: 0, size: 0 };
+    }
+    const stat = fs.statSync(this.logPath);
+    const entries = this.countEntries();
+    let first;
+    let last;
+    if (entries > 0) {
+      const lines = fs.readFileSync(this.logPath, "utf-8").trim().split("\n");
+      const firstEntry = this.parseLine(lines[0]);
+      const lastEntry = this.parseLine(lines[lines.length - 1]);
+      first = firstEntry?.ts;
+      last = lastEntry?.ts;
+    }
+    return {
+      entries,
+      size: stat.size,
+      first,
+      last
+    };
+  }
+  /**
+   * Get the last n log entries
+   */
+  tailLog(n) {
+    if (!fs.existsSync(this.logPath)) {
+      return [];
+    }
+    const content = fs.readFileSync(this.logPath, "utf-8").trim();
+    if (!content) {
+      return [];
+    }
+    const lines = content.split("\n");
+    const startIndex = Math.max(0, lines.length - n);
+    const result = [];
+    for (let i = startIndex; i < lines.length; i++) {
+      const entry = this.parseLine(lines[i]);
+      if (entry) {
+        result.push(entry);
+      }
+    }
+    return result;
+  }
+  /**
+   * Count entries in the log file
+   */
+  countEntries() {
+    if (!fs.existsSync(this.logPath)) {
+      return 0;
+    }
+    const content = fs.readFileSync(this.logPath, "utf-8").trim();
+    if (!content) {
+      return 0;
+    }
+    return content.split("\n").length;
+  }
+  /**
+   * Parse a single log line
+   */
+  parseLine(line) {
+    if (!line) {
+      return null;
+    }
+    try {
+      return JSON.parse(line);
+    } catch {
+      return null;
+    }
+  }
+};
+var loggerCache = /* @__PURE__ */ new Map();
+function getSessionLogger(sessionId, exportLogPath) {
+  const cacheKey = exportLogPath ? `${sessionId}:${exportLogPath}` : sessionId;
+  let logger = loggerCache.get(cacheKey);
+  if (!logger) {
+    logger = new SessionLogger(sessionId, exportLogPath);
+    loggerCache.set(cacheKey, logger);
+  }
+  return logger;
+}
+
 // src/cli/commands/exec.ts
 async function validateSession(session) {
   try {
@@ -3313,13 +4454,14 @@ Run 'bp actions' for complete action reference.`
 Session file has been cleaned up. Run "bp connect" to create a new session.`
     );
   }
+  const logger = getSessionLogger(session.id, session.exportLog);
   const browser = await connect({
     provider: session.provider,
     wsUrl: session.wsUrl,
     debug: globalOptions.trace
   });
   try {
-    const page = addBatchToPage(await browser.page());
+    const page = addBatchToPage(await browser.page(void 0, { targetId: session.targetId }));
     const currentUrlForCache = await page.url();
     const refCache = session.metadata?.refCache;
     if (refCache && refCache.url === currentUrlForCache) {
@@ -3335,7 +4477,30 @@ Session file has been cleaned up. Run "bp connect" to create a new session.`
       });
     }
     const steps = Array.isArray(actions) ? actions : [actions];
+    const urlBefore = await page.url();
     const result = await page.batch(steps);
+    const urlAfter = await page.url();
+    for (const stepResult of result.steps) {
+      logger.logCommand(
+        stepResult.action,
+        { selector: stepResult.selectorUsed },
+        {
+          success: stepResult.success,
+          error: stepResult.error,
+          hints: stepResult.hints
+        },
+        stepResult.durationMs
+      );
+    }
+    logger.log({
+      type: "event",
+      cmd: "batch",
+      args: { stepCount: steps.length },
+      status: result.success ? "success" : "failed",
+      durationMs: result.totalDurationMs,
+      urlBefore,
+      urlAfter
+    });
     const currentUrl = await page.url();
     const hasSnapshot = steps.some((step) => step.action === "snapshot");
     if (hasSnapshot) {
@@ -3376,7 +4541,101 @@ Session file has been cleaned up. Run "bp connect" to create a new session.`
 }
 
 // src/cli/commands/list.ts
-async function listCommand(_args, globalOptions) {
+function parseListArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--log-path") {
+      options.logPath = true;
+    } else if (arg === "--log-tail") {
+      const next = args[i + 1];
+      if (next && !next.startsWith("-")) {
+        options.logTail = parseInt(next, 10);
+        i++;
+      } else {
+        options.logTail = 20;
+      }
+    } else if (arg === "--info") {
+      options.info = true;
+    }
+  }
+  return options;
+}
+function formatLogEntry(entry) {
+  const time = new Date(entry.ts).toLocaleTimeString();
+  const status = entry.status === "failed" ? "\u2717" : entry.status === "success" ? "\u2713" : "\u25CB";
+  if (entry.type === "command") {
+    const dur = entry.durationMs ? `(${entry.durationMs}ms)` : "";
+    return `${time} ${status} ${entry.cmd} ${dur}`;
+  }
+  if (entry.type === "error") {
+    return `${time} \u2717 ERROR: ${entry.error}`;
+  }
+  return `${time} ${entry.type}: ${entry.cmd || ""}`;
+}
+async function listCommand(args, globalOptions) {
+  const listOptions = parseListArgs(args);
+  if (listOptions.logPath || listOptions.logTail !== void 0 || listOptions.info) {
+    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 or specify with -s.');
+    }
+    const logger = getSessionLogger(session.id);
+    if (listOptions.logPath) {
+      console.log(logger.getLogPath());
+      return;
+    }
+    if (listOptions.logTail !== void 0) {
+      const entries = logger.tailLog(listOptions.logTail);
+      if (globalOptions.output === "json") {
+        output(entries, "json");
+        return;
+      }
+      if (entries.length === 0) {
+        console.log("No log entries.");
+        return;
+      }
+      console.log(`Last ${entries.length} log entries for session ${session.id}:
+`);
+      for (const entry of entries) {
+        console.log(`  ${formatLogEntry(entry)}`);
+      }
+      return;
+    }
+    if (listOptions.info) {
+      const stats = logger.getLogStats();
+      if (globalOptions.output === "json") {
+        output({ session, logStats: stats }, "json");
+        return;
+      }
+      console.log(`Session: ${session.id}
+`);
+      console.log(`  Provider: ${session.provider}`);
+      console.log(`  Created: ${new Date(session.createdAt).toLocaleString()}`);
+      console.log(`  Last activity: ${new Date(session.lastActivity).toLocaleString()}`);
+      console.log(`  URL: ${session.currentUrl}`);
+      if (session.exportLog) {
+        console.log(`  Export log: ${session.exportLog}`);
+      }
+      console.log("");
+      console.log("Log Stats:");
+      console.log(`  Path: ${logger.getLogPath()}`);
+      console.log(`  Entries: ${stats.entries}`);
+      console.log(`  Size: ${formatBytes(stats.size)}`);
+      if (stats.first) {
+        console.log(`  First: ${new Date(stats.first).toLocaleString()}`);
+      }
+      if (stats.last) {
+        console.log(`  Last: ${new Date(stats.last).toLocaleString()}`);
+      }
+      return;
+    }
+  }
   const sessions = await listSessions();
   if (globalOptions.output === "json") {
     output(sessions, "json");
@@ -3397,6 +4656,11 @@ async function listCommand(_args, globalOptions) {
     console.log("");
   }
 }
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
 function getAge(date) {
   const now = Date.now();
   const diff = now - date.getTime();
@@ -3442,9 +4706,9 @@ STEP 5: BATCH MULTIPLE ACTIONS
   ]'
 
 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
+  Use --json for machine-readable output:
+    bp snapshot --format text --json
+    bp exec '{"action":"click","selector":"ref:e3"}' --json
 
 TIPS
   \u2022 Refs (e1, e2...) are stable within a page - prefer them over CSS selectors
@@ -3476,6 +4740,31 @@ RECORDING (FOR HUMANS)
 
   Great for creating initial automation scripts that AI agents can refine.
 
+DEBUGGING
+  When element selection fails, use these tools to diagnose:
+
+  1. Diagnose a selector:
+     bp diagnose '#submit-button' -s mysite
+
+     Shows exact matches, fuzzy matches, visibility issues, and suggestions.
+
+  2. Compare page states:
+     bp snapshot > before.json
+     # ... perform actions ...
+     bp snapshot --diff before.json
+
+     Shows what changed: added/removed/modified elements.
+
+  3. Visual inspection:
+     bp snapshot --inspect
+
+     Injects visual ref labels onto the page. Use --keep to leave them visible.
+
+  4. Session logs:
+     bp list -s mysite --log-tail 10
+
+     Shows last N commands with timing and any errors.
+
 Run 'bp actions' for the complete action reference.
 `;
 async function quickstartCommand() {
@@ -4433,8 +5722,8 @@ async function recordCommand(args, globalOptions) {
     stopping = true;
     try {
       const recording = await recorder.stop();
-      const fs = await import("fs/promises");
-      await fs.writeFile(outputFile, JSON.stringify(recording, null, 2));
+      const fs3 = await import("fs/promises");
+      await fs3.writeFile(outputFile, JSON.stringify(recording, null, 2));
       const currentUrl = await page.url();
       await updateSession(session.id, { currentUrl });
       await browser.disconnect();
@@ -4502,7 +5791,7 @@ async function screenshotCommand(args, globalOptions) {
     debug: globalOptions.trace
   });
   try {
-    const page = await browser.page();
+    const page = await browser.page(void 0, { targetId: session.targetId });
     const screenshotData = await page.screenshot({
       format: options.format ?? "png",
       quality: options.quality,
@@ -4532,6 +5821,256 @@ async function screenshotCommand(args, globalOptions) {
   }
 }
 
+// src/cli/commands/snapshot.ts
+var fs2 = __toESM(require("fs"), 1);
+
+// src/browser/overlay.ts
+var OVERLAY_SCRIPT = `(function() {
+  // Check for existing DOM elements (handles cross-CLI reconnection)
+  let style = document.getElementById('__bp-overlay-styles');
+  let container = document.getElementById('__bp-overlay-container');
+
+  // Clear existing labels before updating
+  if (container) {
+    container.innerHTML = '';
+  }
+  document.querySelectorAll('[data-bp-ref]').forEach(el => el.removeAttribute('data-bp-ref'));
+
+  // Create infrastructure only if it doesn't exist
+  if (!style) {
+    style = document.createElement('style');
+    style.id = '__bp-overlay-styles';
+    style.textContent = \`
+      [data-bp-ref] {
+        outline: 2px dashed rgba(229, 57, 53, 0.6) !important;
+        outline-offset: 2px !important;
+      }
+      .__bp-ref-label {
+        position: absolute;
+        background: #e53935;
+        color: white;
+        padding: 1px 4px;
+        font-size: 10px;
+        font-family: monospace;
+        font-weight: bold;
+        z-index: 10000;
+        pointer-events: none;
+        border-radius: 2px;
+        line-height: 1.2;
+      }
+    \`;
+    document.head.appendChild(style);
+  }
+
+  if (!container) {
+    container = document.createElement('div');
+    container.id = '__bp-overlay-container';
+    container.style.cssText = 'position:absolute;top:0;left:0;pointer-events:none;z-index:10000;';
+    document.body.appendChild(container);
+  }
+
+  // Always redefine to ensure correct container reference
+  window.__bpAddLabel = function(ref, rect) {
+    const label = document.createElement('div');
+    label.className = '__bp-ref-label';
+    label.textContent = ref;
+    label.style.left = (rect.left + window.scrollX) + 'px';
+    label.style.top = (rect.top + window.scrollY - 16) + 'px';
+    container.appendChild(label);
+  };
+
+  window.__bpRemoveOverlay = function() {
+    const c = document.getElementById('__bp-overlay-container');
+    const s = document.getElementById('__bp-overlay-styles');
+    if (c) c.remove();
+    if (s) s.remove();
+    document.querySelectorAll('[data-bp-ref]').forEach(el => el.removeAttribute('data-bp-ref'));
+    delete window.__bpOverlayInstalled;
+    delete window.__bpAddLabel;
+    delete window.__bpRemoveOverlay;
+  };
+
+  window.__bpOverlayInstalled = true;
+})();`;
+var REMOVE_OVERLAY_SCRIPT = `(function() {
+  if (window.__bpRemoveOverlay) {
+    window.__bpRemoveOverlay();
+  }
+})();`;
+var ADD_REF_SCRIPT = `function(ref) {
+  this.setAttribute('data-bp-ref', ref);
+  const rect = this.getBoundingClientRect();
+  if (window.__bpAddLabel) {
+    window.__bpAddLabel(ref, {
+      left: rect.left,
+      top: rect.top,
+      width: rect.width,
+      height: rect.height
+    });
+  }
+  return true;
+}`;
+async function injectRefOverlay(page, snapshot) {
+  await page.evaluate(OVERLAY_SCRIPT);
+  const refMap = page.exportRefMap();
+  const cdp = page.cdpClient;
+  for (const element of snapshot.interactiveElements) {
+    const backendNodeId = refMap[element.ref];
+    if (backendNodeId === void 0) {
+      continue;
+    }
+    try {
+      const resolveResult = await cdp.send("DOM.resolveNode", {
+        backendNodeId
+      });
+      if (!resolveResult.object?.objectId) {
+        continue;
+      }
+      await cdp.send("Runtime.callFunctionOn", {
+        objectId: resolveResult.object.objectId,
+        functionDeclaration: ADD_REF_SCRIPT,
+        arguments: [{ value: element.ref }],
+        returnByValue: true
+      });
+    } catch {
+    }
+  }
+}
+async function removeRefOverlay(page) {
+  await page.evaluate(REMOVE_OVERLAY_SCRIPT);
+}
+
+// src/browser/snapshot-diff.ts
+function getElementKey(node, path) {
+  const name = node.name ?? "";
+  return `${node.role}::${name}::${path.join("/")}`;
+}
+function flattenTree(nodes, path = []) {
+  const result = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i];
+    const currentPath = [...path, String(i)];
+    const key = getElementKey(node, currentPath);
+    result.push({ node, key, path: currentPath });
+    if (node.children) {
+      result.push(...flattenTree(node.children, currentPath));
+    }
+  }
+  return result;
+}
+function compareNodes(before, after) {
+  const changedFields = [];
+  if (before.role !== after.role) {
+    changedFields.push("role");
+  }
+  if (before.name !== after.name) {
+    changedFields.push("name");
+  }
+  if (before.value !== after.value) {
+    changedFields.push("value");
+  }
+  if (before.disabled !== after.disabled) {
+    changedFields.push("disabled");
+  }
+  if (before.checked !== after.checked) {
+    changedFields.push("checked");
+  }
+  return changedFields;
+}
+function diffSnapshots(before, after) {
+  const beforeFlat = flattenTree(before.accessibilityTree);
+  const afterFlat = flattenTree(after.accessibilityTree);
+  const beforeMap = new Map(beforeFlat.map((item) => [item.key, item]));
+  const afterMap = new Map(afterFlat.map((item) => [item.key, item]));
+  const added = [];
+  const removed = [];
+  const changed = [];
+  let unchanged = 0;
+  for (const afterItem of afterFlat) {
+    const beforeItem = beforeMap.get(afterItem.key);
+    if (!beforeItem) {
+      added.push(afterItem.node);
+    } else {
+      const changedFields = compareNodes(beforeItem.node, afterItem.node);
+      if (changedFields.length > 0) {
+        changed.push({
+          key: afterItem.key,
+          before: beforeItem.node,
+          after: afterItem.node,
+          changedFields
+        });
+      } else {
+        unchanged++;
+      }
+    }
+  }
+  for (const beforeItem of beforeFlat) {
+    if (!afterMap.has(beforeItem.key)) {
+      removed.push(beforeItem.node);
+    }
+  }
+  return {
+    metadata: {
+      before: {
+        url: before.url,
+        timestamp: before.timestamp,
+        title: before.title
+      },
+      after: {
+        url: after.url,
+        timestamp: after.timestamp,
+        title: after.title
+      },
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    summary: {
+      added: added.length,
+      removed: removed.length,
+      changed: changed.length,
+      unchanged
+    },
+    changes: {
+      added,
+      removed,
+      changed
+    }
+  };
+}
+function formatDiffPretty(diff) {
+  const lines = [];
+  lines.push(`Snapshot Diff: ${diff.metadata.after.url}`);
+  lines.push(`  Before: ${diff.metadata.before.timestamp}`);
+  lines.push(`  After:  ${diff.metadata.after.timestamp}`);
+  lines.push("");
+  if (diff.summary.added === 0 && diff.summary.removed === 0 && diff.summary.changed === 0) {
+    lines.push("No changes detected.");
+    return lines.join("\n");
+  }
+  lines.push("Changes:");
+  for (const node of diff.changes.added) {
+    const name = node.name ? ` "${node.name}"` : "";
+    lines.push(`  + [${node.ref}] ${node.role}${name} (new)`);
+  }
+  for (const item of diff.changes.changed) {
+    const name = item.after.name ? ` "${item.after.name}"` : "";
+    const fieldChanges = item.changedFields.map((field) => {
+      const beforeVal = item.before[field];
+      const afterVal = item.after[field];
+      return `${field}: ${JSON.stringify(beforeVal)} \u2192 ${JSON.stringify(afterVal)}`;
+    }).join(", ");
+    lines.push(`  ~ [${item.after.ref}] ${item.after.role}${name} ${fieldChanges}`);
+  }
+  for (const node of diff.changes.removed) {
+    const name = node.name ? ` "${node.name}"` : "";
+    lines.push(`  - [${node.ref}] ${node.role}${name} (removed)`);
+  }
+  lines.push("");
+  lines.push(
+    `Summary: +${diff.summary.added} added, -${diff.summary.removed} removed, ~${diff.summary.changed} changed`
+  );
+  return lines.join("\n");
+}
+
 // src/cli/commands/snapshot.ts
 function parseSnapshotArgs(args) {
   const options = {};
@@ -4539,10 +6078,19 @@ function parseSnapshotArgs(args) {
     const arg = args[i];
     if (arg === "--format" || arg === "-f") {
       options.format = args[++i];
+    } else if (arg === "--diff" || arg === "-d") {
+      options.diffFile = args[++i];
+    } else if (arg === "--inspect") {
+      options.inspect = true;
+    } else if (arg === "--keep") {
+      options.keep = true;
     }
   }
   return options;
 }
+function sleep3(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
 async function snapshotCommand(args, globalOptions) {
   const options = parseSnapshotArgs(args);
   let session;
@@ -4560,7 +6108,7 @@ async function snapshotCommand(args, globalOptions) {
     debug: globalOptions.trace
   });
   try {
-    const page = await browser.page();
+    const page = await browser.page(void 0, { targetId: session.targetId });
     const snapshot = await page.snapshot();
     await updateSession(session.id, {
       currentUrl: snapshot.url,
@@ -4572,6 +6120,34 @@ async function snapshotCommand(args, globalOptions) {
         }
       }
     });
+    if (options.diffFile) {
+      if (!fs2.existsSync(options.diffFile)) {
+        throw new Error(`Diff file not found: ${options.diffFile}`);
+      }
+      const beforeContent = fs2.readFileSync(options.diffFile, "utf-8");
+      const beforeSnapshot = JSON.parse(beforeContent);
+      const diff = diffSnapshots(beforeSnapshot, snapshot);
+      if (globalOptions.output === "json") {
+        output(diff, "json");
+      } else {
+        console.log(formatDiffPretty(diff));
+      }
+      return;
+    }
+    if (options.inspect) {
+      await injectRefOverlay(page, snapshot);
+      console.log("Overlay injected. Element refs are now visible on the page.");
+      if (options.keep) {
+        console.log(
+          "Overlay will remain visible. Use removeRefOverlay() or refresh the page to remove."
+        );
+      } else {
+        console.log("Overlay will be removed in 10 seconds...");
+        await sleep3(1e4);
+        await removeRefOverlay(page);
+        console.log("Overlay removed.");
+      }
+    }
     switch (options.format) {
       case "interactive":
         output(snapshot.interactiveElements, globalOptions.output);
@@ -4616,7 +6192,7 @@ async function textCommand(args, globalOptions) {
     debug: globalOptions.trace
   });
   try {
-    const page = await browser.page();
+    const page = await browser.page(void 0, { targetId: session.targetId });
     const text = await page.text(options.selector);
     const currentUrl = await page.url();
     await updateSession(session.id, { currentUrl });
@@ -4643,27 +6219,29 @@ Commands:
   exec        Execute actions
   record      Record browser actions to JSON
   snapshot    Get page with element refs
+  diagnose    Debug element selection issues
   text        Extract text content
   screenshot  Take screenshot
   close       Close session
-  list        List sessions
+  list        List sessions (--log-path, --log-tail, --info)
   clean       Clean up old sessions
   actions     Complete action reference
 
 Options:
   -s, --session <id>    Session ID
   -o, --output <fmt>    json | pretty (default: pretty)
+  --json                Alias for -o json
   --trace               Enable debug tracing
   --dialog <mode>       Handle dialogs: accept | dismiss
   -h, --help            Show help
 
 Examples:
   bp connect --provider generic --name dev
+  bp connect -s test --export-log ./logs/test.jsonl
   bp exec '{"action":"goto","url":"https://example.com"}'
   bp snapshot --format text
+  bp list --json                   # JSON output
   bp exec '{"action":"click","selector":"ref:e3"}'
-  bp record                        # Record from local browser
-  bp record -s -f login.json       # Record from latest session
 
 Run 'bp quickstart' for CLI workflow guide.
 Run 'bp actions' for complete action reference.
@@ -4679,6 +6257,10 @@ function parseGlobalOptions(args) {
       options.session = args[++i];
     } else if (arg === "-o" || arg === "--output") {
       options.output = args[++i];
+    } else if (arg === "--json") {
+      options.output = "json";
+    } else if (arg === "--pretty") {
+      options.output = "pretty";
     } else if (arg === "--trace") {
       options.trace = true;
     } else if (arg === "-h" || arg === "--help") {
@@ -4698,7 +6280,7 @@ function output(data, format = "pretty") {
     } else if (typeof data === "object" && data !== null) {
       const { truncated } = prettyPrint(data);
       if (truncated) {
-        console.log("\n(Output truncated. Use -o json for full data)");
+        console.log("\n(Output truncated. Use --json for full data)");
       }
     } else {
       console.log(data);
@@ -4748,6 +6330,9 @@ async function main() {
       case "snapshot":
         await snapshotCommand(remaining, options);
         break;
+      case "diagnose":
+        await diagnoseCommand(remaining, options);
+        break;
       case "text":
         await textCommand(remaining, options);
         break;