browserclaw 0.11.4 → 0.11.6

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,
@@ -1894,6 +1895,7 @@ function ensurePageState(page) {
     page.on("dialog", (dialog) => {
       if (state.armIdDialog > 0) return;
       if (state.dialogHandler) {
+        const handler = state.dialogHandler;
         let handled = false;
         const event = {
           type: dialog.type(),
@@ -1908,7 +1910,7 @@ function ensurePageState(page) {
             return dialog.dismiss();
           }
         };
-        Promise.resolve(state.dialogHandler(event)).then(() => {
+        Promise.resolve().then(() => handler(event)).then(() => {
           if (!handled) {
             dialog.dismiss().catch((err) => {
               console.warn(
@@ -2116,7 +2118,9 @@ async function fetchJsonForCdp(url, timeoutMs) {
     const res = await fetch(url, { signal: ctrl.signal });
     if (!res.ok) return null;
     return await res.json();
-  } catch {
+  } catch (err) {
+    if (process.env.DEBUG !== void 0 && process.env.DEBUG !== "")
+      console.warn(`[browserclaw] fetchJsonForCdp ${url} failed: ${err instanceof Error ? err.message : String(err)}`);
     return null;
   } finally {
     clearTimeout(t);
@@ -2324,11 +2328,15 @@ async function disconnectBrowser() {
     for (const p of connectingByCdpUrl.values()) {
       try {
         await p;
-      } catch {
+      } catch (err) {
+        console.warn(
+          `[browserclaw] disconnectBrowser: pending connect failed: ${err instanceof Error ? err.message : String(err)}`
+        );
       }
     }
   }
   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(() => {
@@ -2450,12 +2458,17 @@ var forceDisconnectPlaywrightForTarget = forceDisconnectPlaywrightConnection;
 function getAllPages(browser) {
   return browser.contexts().flatMap((c) => c.pages());
 }
+var pageTargetIdCache = /* @__PURE__ */ new WeakMap();
 async function pageTargetId(page) {
+  const cached = pageTargetIdCache.get(page);
+  if (cached !== void 0) return cached;
   const session = await page.context().newCDPSession(page);
   try {
     const info = await session.send("Target.getTargetInfo");
     const targetInfo = info.targetInfo;
-    return (targetInfo?.targetId ?? "").trim() || null;
+    const id = (targetInfo?.targetId ?? "").trim() || null;
+    if (id !== null) pageTargetIdCache.set(page, id);
+    return id;
   } finally {
     await session.detach().catch(() => {
     });
@@ -2485,17 +2498,19 @@ async function findPageByTargetIdViaTargetList(pages, targetId, cdpUrl) {
 }
 async function findPageByTargetId(browser, targetId, cdpUrl) {
   const pages = getAllPages(browser);
-  let resolvedViaCdp = false;
-  for (const page of pages) {
-    let tid = null;
-    try {
-      tid = await pageTargetId(page);
-      resolvedViaCdp = true;
-    } catch {
-      tid = null;
-    }
-    if (tid !== null && tid !== "" && tid === targetId) return page;
-  }
+  const results = await Promise.all(
+    pages.map(async (page) => {
+      try {
+        const tid = await pageTargetId(page);
+        return { page, tid };
+      } catch {
+        return { page, tid: null };
+      }
+    })
+  );
+  const resolvedViaCdp = results.some(({ tid }) => tid !== null);
+  const matched = results.find(({ tid }) => tid !== null && tid !== "" && tid === targetId);
+  if (matched) return matched.page;
   if (cdpUrl !== void 0 && cdpUrl !== "") {
     try {
       return await findPageByTargetIdViaTargetList(pages, targetId, cdpUrl);
@@ -2551,9 +2566,6 @@ async function getPageForTargetId(opts) {
     );
   }
   if (isBlockedPageRef(opts.cdpUrl, found)) throw new BlockedBrowserTargetError();
-  const foundTargetId = await pageTargetId(found).catch(() => null);
-  if (foundTargetId !== null && foundTargetId !== "" && isBlockedTarget(opts.cdpUrl, foundTargetId))
-    throw new BlockedBrowserTargetError();
   return found;
 }
 async function resolvePageByTargetIdOrThrow(opts) {
@@ -3206,7 +3218,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);
@@ -3221,9 +3233,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;
@@ -3264,7 +3273,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) {
@@ -3441,7 +3449,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) {
@@ -3553,6 +3564,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 {
@@ -4602,14 +4614,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
@@ -4808,7 +4823,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;
@@ -4819,7 +4834,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;
@@ -4897,7 +4912,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) {
@@ -4905,9 +4920,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);
@@ -4988,7 +5003,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,
@@ -5498,7 +5513,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 },
    * ]);
    * ```
@@ -5551,17 +5566,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) {
@@ -6043,7 +6059,7 @@ var CrawlPage = class {
    * await page.setCookie({
    *   name: 'token',
    *   value: 'abc123',
-   *   url: 'https://example.com',
+   *   url: 'https://demo.playwright.dev/todomvc',
    * });
    * ```
    */
@@ -6295,7 +6311,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 });
@@ -6356,7 +6372,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) {
@@ -6387,14 +6403,14 @@ 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',
    * });
    * ```
@@ -6450,7 +6466,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();
    * ```
    */
@@ -6557,6 +6573,7 @@ var BrowserClaw = class _BrowserClaw {
   }
 };
 
+exports.BlockedBrowserTargetError = BlockedBrowserTargetError;
 exports.BrowserClaw = BrowserClaw;
 exports.BrowserTabNotFoundError = BrowserTabNotFoundError;
 exports.CrawlPage = CrawlPage;
@@ -6587,6 +6604,7 @@ exports.resolveBoundedDelayMs = resolveBoundedDelayMs;
 exports.resolveInteractionTimeoutMs = resolveInteractionTimeoutMs;
 exports.resolvePageByTargetIdOrThrow = resolvePageByTargetIdOrThrow;
 exports.resolvePinnedHostnameWithPolicy = resolvePinnedHostnameWithPolicy;
+exports.resolveStrictExistingPathsWithinRoot = resolveStrictExistingPathsWithinRoot;
 exports.resolveStrictExistingUploadPaths = resolveStrictExistingUploadPaths;
 exports.sanitizeUntrustedFileName = sanitizeUntrustedFileName;
 exports.setDialogHandler = setDialogHandler;