browserclaw 0.11.5 → 0.12.0

package/README.md

@@ -15,16 +15,16 @@ The AI-native browser automation library — born from [OpenClaw](https://github
 ```typescript
 import { BrowserClaw } from 'browserclaw';
 
-const browser = await BrowserClaw.launch({ url: 'https://example.com' });
+const browser = await BrowserClaw.launch({ url: 'https://demo.playwright.dev/todomvc' });
 const page = await browser.currentPage();
 
 // Snapshot — the core feature
 const { snapshot, refs } = await page.snapshot();
 // snapshot: AI-readable text tree
-// refs: { "e1": { role: "link", name: "More info" }, "e2": { role: "button", name: "Submit" } }
+// refs: { "e1": { role: "textbox", name: "What needs to be done?" }, "e2": { role: "link", name: "Playwright" } }
 
-await page.click('e1'); // Click by ref
-await page.type('e3', 'hello'); // Type by ref
+await page.type('e1', 'Buy groceries', { submit: true }); // Type by ref
+await page.click('e2'); // Click by ref
 await browser.stop();
 ```
 
@@ -102,20 +102,20 @@ Requires a Chromium-based browser installed on the system (Chrome, Brave, Edge,
 ## How It Works
 
 ```
-┌─────────────┐     snapshot()     ┌─────────────────────────────────┐
-│  Web Page   │ ──────────────►    │  AI-readable text tree          │
-│             │                    │                                 │
-│  [buttons]  │                    │  - heading "Example Domain"     │
-│  [links]    │                    │  - paragraph "This domain..."   │
-│  [inputs]   │                    │  - link "More information" [e1] │
-└─────────────┘                    └──────────────┬──────────────────┘
+┌─────────────┐     snapshot()     ┌──────────────────────────────────────────┐
+│  Web Page   │ ──────────────►    │  AI-readable text tree                   │
+│             │                    │                                          │
+│  [buttons]  │                    │  - heading "todos"                       │
+│  [links]    │                    │  - textbox "What needs to be done?" [e1] │
+│  [inputs]   │                    │  - link "Playwright" [e2]                │
+└─────────────┘                    └──────────────┬───────────────────────────┘
                                                   │
                                           AI reads snapshot,
-                                          decides: click e1
+                                          decides: type in e1
                                                   │
-┌─────────────┐     click('e1')    ┌──────────────▼──────────────────┐
+┌─────────────┐   type('e1',...)   ┌──────────────▼──────────────────┐
 │  Web Page   │ ◄──────────────    │  Ref "e1" resolves to a         │
-│  (navigated)│                    │  Playwright locator — one ref,  │
+│  (updated)  │                    │  Playwright locator — one ref,  │
 │             │                    │  one exact element              │
 └─────────────┘                    └─────────────────────────────────┘
 ```
@@ -133,7 +133,7 @@ Requires a Chromium-based browser installed on the system (Chrome, Brave, Edge,
 ```typescript
 // Launch a new Chrome instance (auto-detects Chrome/Brave/Edge/Chromium)
 const browser = await BrowserClaw.launch({
-  url: 'https://example.com', // navigate initial tab (no extra tabs)
+  url: 'https://demo.playwright.dev/todomvc', // navigate initial tab (no extra tabs)
   headless: false, // default: false (visible window)
   executablePath: '...', // optional: specific browser path
   cdpPort: 9222, // default: 9222
@@ -159,7 +159,7 @@ const browser = await BrowserClaw.connect();
 ### Pages & Tabs
 
 ```typescript
-const page = await browser.open('https://example.com');
+const page = await browser.open('https://demo.playwright.dev/todomvc');
 const current = await browser.currentPage(); // get active tab
 const tabs = await browser.tabs(); // list all tabs
 const handle = browser.page(tabs[0].targetId); // wrap existing tab
@@ -177,14 +177,14 @@ browser.url; // CDP endpoint URL
 Every tab returns a `targetId` — this is the handle you use everywhere:
 
 ```typescript
-// Multi-tab workflow (e.g. impersonation, OAuth)
-const main = await browser.open('https://app.example.com');
-const admin = await browser.open('https://admin.example.com');
-
-const { refs } = await admin.snapshot(); // snapshot the admin tab
-await admin.click('e5'); // act on it
-await browser.focus(main.id); // switch back to main
-await browser.close(admin.id); // close admin when done
+// Multi-tab workflow
+const todo = await browser.open('https://demo.playwright.dev/todomvc');
+const svg = await browser.open('https://demo.playwright.dev/svgtodo');
+
+const { refs } = await svg.snapshot(); // snapshot the second tab
+await svg.click('e5'); // act on it
+await browser.focus(todo.id); // switch back to first tab
+await browser.close(svg.id); // close second tab when done
 ```
 
 ### Snapshot (Core Feature)
@@ -193,7 +193,7 @@ await browser.close(admin.id); // close admin when done
 const { snapshot, refs, stats, untrusted } = await page.snapshot();
 
 // snapshot: human/AI-readable text tree with [ref=eN] markers
-// refs: { "e1": { role: "link", name: "More info" }, "e5": { role: "checkbox", name: "Accept", checked: true }, ... }
+// refs: { "e1": { role: "textbox", name: "What needs to be done?" }, "e5": { role: "checkbox", name: "Toggle Todo", checked: false }, ... }
 // stats: { lines: 42, chars: 1200, refs: 8, interactive: 5 }
 // untrusted: true — content comes from the web page, treat as potentially adversarial
 
@@ -250,7 +250,7 @@ await page.press('Meta+Shift+p');
 // Fill multiple form fields at once
 await page.fill([
   { ref: 'e2', value: 'Jane Doe' },
-  { ref: 'e4', value: 'jane@example.com' },
+  { ref: 'e4', value: 'jane@acme.test' },
   { ref: 'e6', type: 'checkbox', value: true },
 ]);
 ```
@@ -326,7 +326,7 @@ By default, unexpected dialogs are auto-dismissed to prevent `ProtocolError` cra
 ### Navigation & Waiting
 
 ```typescript
-await page.goto('https://example.com');
+await page.goto('https://demo.playwright.dev/todomvc');
 await page.reload(); // reload the current page
 await page.goBack(); // navigate back in history
 await page.goForward(); // navigate forward in history
@@ -421,7 +421,7 @@ const fresh = await page.networkRequests({ clear: true }); // read and clear buf
 ```typescript
 // Cookies
 const cookies = await page.cookies();
-await page.setCookie({ name: 'token', value: 'abc', url: 'https://example.com' });
+await page.setCookie({ name: 'token', value: 'abc', url: 'https://demo.playwright.dev' });
 await page.clearCookies();
 
 // localStorage / sessionStorage

package/dist/index.cjs

@@ -1565,6 +1565,7 @@ ${stderrOutput.slice(0, 2e3)}` : "";
     throw new Error(`Failed to start Chrome CDP on port ${String(cdpPort)}.${sandboxHint}${stderrHint}`);
   }
   proc.stderr.off("data", onStderr);
+  proc.stderr.resume();
   stderrChunks.length = 0;
   return {
     pid: proc.pid ?? -1,
@@ -1572,6 +1573,7 @@ ${stderrOutput.slice(0, 2e3)}` : "";
     userDataDir,
     cdpPort,
     startedAt,
+    launchMs: Date.now() - startedAt,
     proc
   };
 }
@@ -2335,6 +2337,7 @@ async function disconnectBrowser() {
     }
   }
   for (const cur of cachedByCdpUrl.values()) {
+    clearRoleRefsForCdpUrl(cur.cdpUrl);
     if (cur.onDisconnected && typeof cur.browser.off === "function")
       cur.browser.off("disconnected", cur.onDisconnected);
     await cur.browser.close().catch(() => {
@@ -2564,7 +2567,6 @@ async function getPageForTargetId(opts) {
     );
   }
   if (isBlockedPageRef(opts.cdpUrl, found)) throw new BlockedBrowserTargetError();
-  if (isBlockedTarget(opts.cdpUrl, opts.targetId)) throw new BlockedBrowserTargetError();
   return found;
 }
 async function resolvePageByTargetIdOrThrow(opts) {
@@ -3217,7 +3219,7 @@ async function writeViaSiblingTempPath(params) {
   const requestedTargetPath = path.resolve(params.targetPath);
   const targetPath = await promises$1.realpath(path.dirname(requestedTargetPath)).then((realDir) => path.join(realDir, path.basename(requestedTargetPath))).catch(() => requestedTargetPath);
   const relativeTargetPath = path.relative(rootDir, targetPath);
-  if (!relativeTargetPath || relativeTargetPath === ".." || relativeTargetPath.startsWith(`..${path.sep}`) || isAbsolute(relativeTargetPath)) {
+  if (!relativeTargetPath || relativeTargetPath === ".." || relativeTargetPath.startsWith(`..${path.sep}`) || path.isAbsolute(relativeTargetPath)) {
     throw new Error("Target path is outside the allowed root");
   }
   const tempPath = buildSiblingTempPath(targetPath);
@@ -3232,9 +3234,6 @@ async function writeViaSiblingTempPath(params) {
       });
   }
 }
-function isAbsolute(p) {
-  return p.startsWith("/") || /^[a-zA-Z]:/.test(p);
-}
 async function assertBrowserNavigationResultAllowed(opts) {
   const rawUrl = opts.url.trim();
   if (rawUrl === "") return;
@@ -3275,7 +3274,6 @@ async function setCheckedViaEvaluate(locator, checked) {
     else input.checked = desired;
     input.dispatchEvent(new Event("input", { bubbles: true }));
     input.dispatchEvent(new Event("change", { bubbles: true }));
-    input.click();
   }, checked);
 }
 function resolveLocator(page, resolved) {
@@ -3452,7 +3450,10 @@ async function fillFormViaPlaywright(opts) {
       const checked = rawValue === true || rawValue === 1 || rawValue === "1" || rawValue === "true";
       try {
         await locator.setChecked(checked, { timeout, force: true });
-      } catch {
+      } catch (setCheckedErr) {
+        console.warn(
+          `[browserclaw] setChecked fallback for ref "${ref}": ${setCheckedErr instanceof Error ? setCheckedErr.message : String(setCheckedErr)}`
+        );
         try {
           await setCheckedViaEvaluate(locator, checked);
         } catch (err) {
@@ -3564,6 +3565,7 @@ async function armFileUploadViaPlaywright(opts) {
       scopeLabel: `uploads directory (${DEFAULT_UPLOAD_DIR})`
     });
     if (!uploadPathsResult.ok) {
+      console.warn(`[browserclaw] armFileUpload: path validation failed: ${uploadPathsResult.error}`);
       try {
         await page.keyboard.press("Escape");
       } catch {
@@ -4613,14 +4615,17 @@ async function traceStopViaPlaywright(opts) {
   if (!ctxState.traceActive) {
     throw new Error("No active trace. Start a trace before stopping it.");
   }
-  await writeViaSiblingTempPath({
-    rootDir: path.dirname(opts.path),
-    targetPath: opts.path,
-    writeTemp: async (tempPath) => {
-      await context.tracing.stop({ path: tempPath });
-    }
-  });
-  ctxState.traceActive = false;
+  try {
+    await writeViaSiblingTempPath({
+      rootDir: path.dirname(opts.path),
+      targetPath: opts.path,
+      writeTemp: async (tempPath) => {
+        await context.tracing.stop({ path: tempPath });
+      }
+    });
+  } finally {
+    ctxState.traceActive = false;
+  }
 }
 
 // src/snapshot/ref-map.ts
@@ -4819,7 +4824,7 @@ function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
     const isInteractive = INTERACTIVE_ROLES.has(role);
     const isContent = CONTENT_ROLES.has(role);
     const isStructural = STRUCTURAL_ROLES.has(role);
-    if (options.compact === true && isStructural && name === "") continue;
+    if (options.compact === true && isStructural && !name) continue;
     if (!(isInteractive || isContent && name !== "")) {
       result.push(line);
       continue;
@@ -4830,7 +4835,7 @@ function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
     const state = parseStateFromSuffix(suffix);
     refs[ref] = { role, name, nth, ...state };
     let enhanced = `${prefix}${roleRaw}`;
-    if (name !== "") enhanced += ` "${name}"`;
+    if (name) enhanced += ` "${name}"`;
     enhanced += ` [ref=${ref}]`;
     if (nth > 0) enhanced += ` [nth=${String(nth)}]`;
     if (suffix !== "") enhanced += suffix;
@@ -4908,7 +4913,7 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
     }
     const role = roleRaw.toLowerCase();
     const isStructural = STRUCTURAL_ROLES.has(role);
-    if (options.compact === true && isStructural && name === "") continue;
+    if (options.compact === true && isStructural && !name) continue;
     const ref = parseAiSnapshotRef(suffix);
     const state = parseStateFromSuffix(suffix);
     if (ref !== null) {
@@ -4916,9 +4921,9 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
       out.push(line);
     } else if (INTERACTIVE_ROLES.has(role)) {
       const generatedRef = nextGeneratedRef();
-      refs[generatedRef] = { role, ...name !== "" ? { name } : {}, ...state };
+      refs[generatedRef] = { role, ...name ? { name } : {}, ...state };
       let enhanced = `${prefix}${roleRaw}`;
-      if (name !== "") enhanced += ` "${name}"`;
+      if (name) enhanced += ` "${name}"`;
       enhanced += ` [ref=${generatedRef}]`;
       if (suffix.trim() !== "") enhanced += suffix;
       out.push(enhanced);
@@ -4999,7 +5004,7 @@ async function snapshotRole(opts) {
     if (!maybe._snapshotForAI) {
       throw new Error("refs=aria requires Playwright _snapshotForAI support.");
     }
-    const result = await maybe._snapshotForAI({ timeout: 5e3, track: "response" });
+    const result = await maybe._snapshotForAI({ timeout: normalizeTimeoutMs(opts.timeoutMs, 5e3), track: "response" });
     const built2 = buildRoleSnapshotFromAiSnapshot(String(result.full), opts.options);
     storeRoleRefsForTarget({
       page,
@@ -5509,7 +5514,7 @@ var CrawlPage = class {
    * ```ts
    * await page.fill([
    *   { ref: 'e2', type: 'text', value: 'Jane Doe' },
-   *   { ref: 'e4', type: 'text', value: 'jane@example.com' },
+   *   { ref: 'e4', type: 'text', value: 'jane@acme.test' },
    *   { ref: 'e6', type: 'checkbox', value: true },
    * ]);
    * ```
@@ -5562,17 +5567,18 @@ var CrawlPage = class {
     });
   }
   /**
-   * Arm a one-shot dialog handler (alert, confirm, prompt).
+   * Arm a one-shot dialog handler (alert, confirm, prompt). Fire-and-forget:
+   * returns immediately once the arm is registered. The dialog is handled in
+   * the background when it fires.
    *
-   * Returns a promise — store it (don't await), trigger the dialog, then await it.
+   * Call this BEFORE triggering the action that opens the dialog.
    *
    * @param opts - Dialog options (accept/dismiss, prompt text, timeout)
    *
    * @example
    * ```ts
-   * const dialogDone = page.armDialog({ accept: true }); // don't await here
-   * await page.click('e5'); // triggers confirm()
-   * await dialogDone;       // wait for dialog to be handled
+   * await page.armDialog({ accept: true }); // registers the handler, returns immediately
+   * await page.click('e5');                 // triggers confirm() — handled in background
    * ```
    */
   async armDialog(opts) {
@@ -6054,7 +6060,7 @@ var CrawlPage = class {
    * await page.setCookie({
    *   name: 'token',
    *   value: 'abc123',
-   *   url: 'https://example.com',
+   *   url: 'https://demo.playwright.dev/todomvc',
    * });
    * ```
    */
@@ -6306,7 +6312,7 @@ var CrawlPage = class {
    *
    * @example
    * ```ts
-   * await page.goto('https://example.com');
+   * await page.goto('https://demo.playwright.dev/todomvc');
    * const challenge = await page.detectChallenge();
    * if (challenge?.kind === 'cloudflare-js') {
    *   const { resolved } = await page.waitForChallenge({ timeoutMs: 20000 });
@@ -6322,6 +6328,137 @@ var CrawlPage = class {
       pollMs: opts?.pollMs
     });
   }
+  // ── Auth Health ──────────────────────────────────────────────
+  /**
+   * Check whether the current page session appears authenticated.
+   *
+   * Evaluates one or more rules against the page state. All rules must pass
+   * for `authenticated` to be `true`. Returns per-rule details for debugging.
+   *
+   * @param rules - Array of auth check rules (url, cookie, selector, text, textGone, fn)
+   * @returns Authentication status and per-rule check details
+   *
+   * @example
+   * ```ts
+   * // Check by URL and absence of login text
+   * const result = await page.isAuthenticated([
+   *   { url: '/dashboard' },
+   *   { textGone: 'Sign in' },
+   * ]);
+   * if (!result.authenticated) {
+   *   console.log('Auth failed:', result.checks.filter(c => !c.passed));
+   * }
+   *
+   * // Check by cookie presence
+   * const result = await page.isAuthenticated([{ cookie: 'session_id' }]);
+   *
+   * // Check with custom JS function
+   * const result = await page.isAuthenticated([
+   *   { fn: '() => !!document.querySelector("[data-user-id]")' },
+   * ]);
+   * ```
+   */
+  async isAuthenticated(rules) {
+    if (!rules.length) return { authenticated: true, checks: [] };
+    const page = await getRestoredPageForTarget({ cdpUrl: this.cdpUrl, targetId: this.targetId });
+    const checks = [];
+    for (const rule of rules) {
+      if (rule.url !== void 0) {
+        const currentUrl = page.url();
+        const passed = currentUrl.includes(rule.url);
+        checks.push({ rule: "url", passed, detail: passed ? currentUrl : `expected "${rule.url}" in "${currentUrl}"` });
+      }
+      if (rule.cookie !== void 0) {
+        const cookies = await page.context().cookies();
+        const found = cookies.some((c) => c.name === rule.cookie && c.value !== "");
+        checks.push({
+          rule: "cookie",
+          passed: found,
+          detail: found ? `cookie "${rule.cookie}" present` : `cookie "${rule.cookie}" missing or empty`
+        });
+      }
+      if (rule.selector !== void 0) {
+        try {
+          const count = await page.locator(rule.selector).count();
+          const passed = count > 0;
+          checks.push({
+            rule: "selector",
+            passed,
+            detail: passed ? `"${rule.selector}" found (${String(count)})` : `"${rule.selector}" not found`
+          });
+        } catch (err) {
+          console.warn(
+            `[browserclaw] isAuthenticated selector check failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+          checks.push({ rule: "selector", passed: false, detail: `"${rule.selector}" error during evaluation` });
+        }
+      }
+      if (rule.text !== void 0 || rule.textGone !== void 0) {
+        let bodyText = null;
+        try {
+          const raw = await evaluateViaPlaywright({
+            cdpUrl: this.cdpUrl,
+            targetId: this.targetId,
+            fn: '() => { const b = document.body; return b ? b.innerText : ""; }'
+          });
+          bodyText = typeof raw === "string" ? raw : null;
+        } catch (err) {
+          console.warn(
+            `[browserclaw] isAuthenticated body text fetch failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        if (rule.text !== void 0) {
+          if (bodyText === null) {
+            checks.push({ rule: "text", passed: false, detail: `"${rule.text}" error during evaluation` });
+          } else {
+            const passed = bodyText.includes(rule.text);
+            checks.push({
+              rule: "text",
+              passed,
+              detail: passed ? `"${rule.text}" found` : `"${rule.text}" not found in page text`
+            });
+          }
+        }
+        if (rule.textGone !== void 0) {
+          if (bodyText === null) {
+            checks.push({ rule: "textGone", passed: false, detail: `"${rule.textGone}" error during evaluation` });
+          } else {
+            const passed = !bodyText.includes(rule.textGone);
+            checks.push({
+              rule: "textGone",
+              passed,
+              detail: passed ? `"${rule.textGone}" absent (good)` : `"${rule.textGone}" still present`
+            });
+          }
+        }
+      }
+      if (rule.fn !== void 0) {
+        try {
+          const result = await evaluateViaPlaywright({
+            cdpUrl: this.cdpUrl,
+            targetId: this.targetId,
+            fn: rule.fn
+          });
+          const passed = result !== null && result !== void 0 && result !== false && result !== 0 && result !== "";
+          checks.push({
+            rule: "fn",
+            passed,
+            detail: passed ? "function returned truthy" : `function returned ${JSON.stringify(result)}`
+          });
+        } catch (err) {
+          checks.push({
+            rule: "fn",
+            passed: false,
+            detail: `function threw: ${err instanceof Error ? err.message : String(err)}`
+          });
+        }
+      }
+    }
+    return {
+      authenticated: checks.length > 0 && checks.every((c) => c.passed),
+      checks
+    };
+  }
   // ── Playwright Escape Hatches ─────────────────────────────────
   /**
    * Get the underlying Playwright `Page` object for this tab.
@@ -6367,7 +6504,7 @@ var CrawlPage = class {
    *
    * // Use Playwright selectors
    * const input = await page.locator('input[name="email"]');
-   * await input.fill('test@example.com');
+   * await input.fill('test@acme.test');
    * ```
    */
   async locator(selector) {
@@ -6380,9 +6517,11 @@ var BrowserClaw = class _BrowserClaw {
   ssrfPolicy;
   recordVideo;
   chrome;
-  constructor(cdpUrl, chrome, ssrfPolicy, recordVideo) {
+  _telemetry;
+  constructor(cdpUrl, chrome, telemetry, ssrfPolicy, recordVideo) {
     this.cdpUrl = cdpUrl;
     this.chrome = chrome;
+    this._telemetry = telemetry;
     this.ssrfPolicy = ssrfPolicy;
     this.recordVideo = recordVideo;
   }
@@ -6398,26 +6537,34 @@ var BrowserClaw = class _BrowserClaw {
    * @example
    * ```ts
    * // Launch and navigate to a URL
-   * const browser = await BrowserClaw.launch({ url: 'https://example.com' });
+   * const browser = await BrowserClaw.launch({ url: 'https://demo.playwright.dev/todomvc' });
    *
    * // Headless mode
-   * const browser = await BrowserClaw.launch({ url: 'https://example.com', headless: true });
+   * const browser = await BrowserClaw.launch({ url: 'https://demo.playwright.dev/todomvc', headless: true });
    *
    * // Specific browser
    * const browser = await BrowserClaw.launch({
-   *   url: 'https://example.com',
+   *   url: 'https://demo.playwright.dev/todomvc',
    *   executablePath: '/usr/bin/google-chrome',
    * });
    * ```
    */
   static async launch(opts = {}) {
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const chrome = await launchChrome(opts);
     const cdpUrl = `http://127.0.0.1:${String(chrome.cdpPort)}`;
     const ssrfPolicy = opts.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
-    const browser = new _BrowserClaw(cdpUrl, chrome, ssrfPolicy, opts.recordVideo);
+    const telemetry = {
+      launchMs: chrome.launchMs,
+      timestamps: { startedAt, launchedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    };
+    const browser = new _BrowserClaw(cdpUrl, chrome, telemetry, ssrfPolicy, opts.recordVideo);
     if (opts.url !== void 0 && opts.url !== "") {
       const page = await browser.currentPage();
+      const navT0 = Date.now();
       await page.goto(opts.url);
+      telemetry.navMs = Date.now() - navT0;
+      telemetry.timestamps.navigatedAt = (/* @__PURE__ */ new Date()).toISOString();
     }
     return browser;
   }
@@ -6436,6 +6583,8 @@ var BrowserClaw = class _BrowserClaw {
    * ```
    */
   static async connect(cdpUrl, opts) {
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const connectT0 = Date.now();
     let resolvedUrl = cdpUrl;
     if (resolvedUrl === void 0 || resolvedUrl === "") {
       const discovered = await discoverChromeCdpUrl();
@@ -6451,7 +6600,11 @@ var BrowserClaw = class _BrowserClaw {
     }
     await connectBrowser(resolvedUrl, opts?.authToken);
     const ssrfPolicy = opts?.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts?.ssrfPolicy;
-    return new _BrowserClaw(resolvedUrl, null, ssrfPolicy, opts?.recordVideo);
+    const telemetry = {
+      connectMs: Date.now() - connectT0,
+      timestamps: { startedAt, connectedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    };
+    return new _BrowserClaw(resolvedUrl, null, telemetry, ssrfPolicy, opts?.recordVideo);
   }
   /**
    * Open a URL in a new tab and return the page handle.
@@ -6461,7 +6614,7 @@ var BrowserClaw = class _BrowserClaw {
    *
    * @example
    * ```ts
-   * const page = await browser.open('https://example.com');
+   * const page = await browser.open('https://demo.playwright.dev/todomvc');
    * const { snapshot, refs } = await page.snapshot();
    * ```
    */
@@ -6480,7 +6633,12 @@ var BrowserClaw = class _BrowserClaw {
    * @returns CrawlPage for the first/active page
    */
   async currentPage() {
+    const connectT0 = Date.now();
     const { browser } = await connectBrowser(this.cdpUrl);
+    if (this._telemetry.connectMs === void 0) {
+      this._telemetry.connectMs = Date.now() - connectT0;
+      this._telemetry.timestamps.connectedAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
     const pages = getAllPages(browser);
     if (!pages.length) throw new Error("No pages available. Use browser.open(url) to create a tab.");
     const tid = await pageTargetId(pages[0]).catch(() => null);
@@ -6557,15 +6715,61 @@ var BrowserClaw = class _BrowserClaw {
    * If the browser was launched by `BrowserClaw.launch()`, the Chrome process
    * will be terminated. If connected via `BrowserClaw.connect()`, only the
    * Playwright connection is closed.
+   *
+   * @param exitReason - Optional structured reason for stopping (e.g. `'success'`, `'auth_failed'`, `'timeout'`)
    */
-  async stop() {
-    clearRecordingContext(this.cdpUrl);
-    await disconnectBrowser();
-    if (this.chrome) {
-      await stopChrome(this.chrome);
-      this.chrome = null;
+  async stop(exitReason) {
+    this._telemetry.timestamps.stoppedAt = (/* @__PURE__ */ new Date()).toISOString();
+    if (exitReason !== void 0) this._telemetry.exitReason = exitReason;
+    try {
+      clearRecordingContext(this.cdpUrl);
+      await disconnectBrowser();
+      if (this.chrome) {
+        await stopChrome(this.chrome);
+        this.chrome = null;
+      }
+      this._telemetry.cleanupOk = true;
+    } catch (err) {
+      this._telemetry.cleanupOk = false;
+      throw err;
     }
   }
+  /**
+   * Get structured telemetry for this browser session.
+   *
+   * Returns timing data, timestamps, and exit information collected
+   * throughout the session lifecycle. Useful for diagnosing startup
+   * latency, auth failures, and cleanup issues in cron/unattended runs.
+   *
+   * @returns Telemetry envelope with launch/connect/nav timings and exit info
+   *
+   * @example
+   * ```ts
+   * const browser = await BrowserClaw.launch({ url: 'https://example.com' });
+   * const page = await browser.currentPage();
+   *
+   * // ... do work ...
+   *
+   * const auth = await page.isAuthenticated([{ cookie: 'session' }]);
+   * browser.recordAuthResult(auth.authenticated);
+   *
+   * await browser.stop(auth.authenticated ? 'success' : 'auth_failed');
+   * console.log(browser.telemetry());
+   * // { launchMs: 1823, connectMs: 45, navMs: 620, authOk: true,
+   * //   exitReason: 'success', cleanupOk: true, timestamps: { ... } }
+   * ```
+   */
+  telemetry() {
+    return this._telemetry;
+  }
+  /**
+   * Record the result of an authentication check in the telemetry envelope.
+   *
+   * @param ok - Whether authentication was successful
+   */
+  recordAuthResult(ok) {
+    this._telemetry.authOk = ok;
+  }
 };
 
 exports.BlockedBrowserTargetError = BlockedBrowserTargetError;