browserclaw 0.9.7 → 0.10.1

package/dist/index.d.cts

@@ -184,6 +184,8 @@ interface LaunchOptions {
     profileColor?: string;
     /** Additional Chrome command-line arguments (e.g. `['--start-maximized']`). */
     chromeArgs?: string[];
+    /** Ignore HTTPS certificate errors (e.g. expired local dev certs). Default: `false` */
+    ignoreHTTPSErrors?: boolean;
     /**
      * SSRF policy controlling which URLs navigation is allowed to reach.
      * Defaults to trusted-network mode (private/internal addresses allowed).
@@ -249,6 +251,10 @@ interface RoleRefInfo {
     name?: string;
     /** Disambiguation index when multiple elements share the same role + name */
     nth?: number;
+    /** Whether the element is disabled (from `[disabled]` or `aria-disabled`) */
+    disabled?: boolean;
+    /** Whether a checkbox/radio/switch is checked */
+    checked?: boolean | 'mixed';
 }
 /** Map of ref IDs (e.g. `'e1'`, `'e2'`) to their element information. */
 type RoleRefs = Record<string, RoleRefInfo>;
@@ -375,6 +381,8 @@ interface ClickOptions {
     delayMs?: number;
     /** Timeout in milliseconds. Default: `8000` */
     timeoutMs?: number;
+    /** Force click even if element is hidden or covered. Dispatches the event regardless of visibility. */
+    force?: boolean;
 }
 /** Options for type actions. */
 interface TypeOptions {
@@ -402,8 +410,8 @@ interface WaitOptions {
     url?: string;
     /** Wait for a specific page load state */
     loadState?: 'load' | 'domcontentloaded' | 'networkidle';
-    /** Wait until a JavaScript function returns truthy (evaluated in browser context) */
-    fn?: string;
+    /** Wait until a JavaScript function returns truthy (evaluated in browser context). Accepts a string or a serializable function. */
+    fn?: string | (() => unknown);
     /** Timeout for each condition in milliseconds. Default: `20000` */
     timeoutMs?: number;
 }
@@ -774,6 +782,7 @@ declare class CrawlPage {
      * ```
      */
     clickByRole(role: string, name?: string, opts?: {
+        index?: number;
         button?: 'left' | 'right' | 'middle';
         modifiers?: ('Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift')[];
         timeoutMs?: number;

package/dist/index.d.ts

@@ -184,6 +184,8 @@ interface LaunchOptions {
     profileColor?: string;
     /** Additional Chrome command-line arguments (e.g. `['--start-maximized']`). */
     chromeArgs?: string[];
+    /** Ignore HTTPS certificate errors (e.g. expired local dev certs). Default: `false` */
+    ignoreHTTPSErrors?: boolean;
     /**
      * SSRF policy controlling which URLs navigation is allowed to reach.
      * Defaults to trusted-network mode (private/internal addresses allowed).
@@ -249,6 +251,10 @@ interface RoleRefInfo {
     name?: string;
     /** Disambiguation index when multiple elements share the same role + name */
     nth?: number;
+    /** Whether the element is disabled (from `[disabled]` or `aria-disabled`) */
+    disabled?: boolean;
+    /** Whether a checkbox/radio/switch is checked */
+    checked?: boolean | 'mixed';
 }
 /** Map of ref IDs (e.g. `'e1'`, `'e2'`) to their element information. */
 type RoleRefs = Record<string, RoleRefInfo>;
@@ -375,6 +381,8 @@ interface ClickOptions {
     delayMs?: number;
     /** Timeout in milliseconds. Default: `8000` */
     timeoutMs?: number;
+    /** Force click even if element is hidden or covered. Dispatches the event regardless of visibility. */
+    force?: boolean;
 }
 /** Options for type actions. */
 interface TypeOptions {
@@ -402,8 +410,8 @@ interface WaitOptions {
     url?: string;
     /** Wait for a specific page load state */
     loadState?: 'load' | 'domcontentloaded' | 'networkidle';
-    /** Wait until a JavaScript function returns truthy (evaluated in browser context) */
-    fn?: string;
+    /** Wait until a JavaScript function returns truthy (evaluated in browser context). Accepts a string or a serializable function. */
+    fn?: string | (() => unknown);
     /** Timeout for each condition in milliseconds. Default: `20000` */
     timeoutMs?: number;
 }
@@ -774,6 +782,7 @@ declare class CrawlPage {
      * ```
      */
     clickByRole(role: string, name?: string, opts?: {
+        index?: number;
         button?: 'left' | 'right' | 'middle';
         modifiers?: ('Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift')[];
         timeoutMs?: number;

package/dist/index.js

@@ -1396,6 +1396,9 @@ async function launchChrome(opts = {}) {
     if (opts.noSandbox === true) {
       args.push("--no-sandbox", "--disable-setuid-sandbox");
     }
+    if (opts.ignoreHTTPSErrors === true) {
+      args.push("--ignore-certificate-errors");
+    }
     if (process.platform === "linux") args.push("--disable-dev-shm-usage");
     const extraArgs = Array.isArray(opts.chromeArgs) ? opts.chromeArgs.filter((a) => typeof a === "string" && a.trim().length > 0) : [];
     if (extraArgs.length) args.push(...extraArgs);
@@ -2364,7 +2367,14 @@ function toAIFriendlyError(error, selector) {
       `Element "${selector}" is not interactable (hidden or covered). Try scrolling it into view, closing overlays, or re-snapshotting.`
     );
   }
-  return error instanceof Error ? error : new Error(message);
+  const timeoutMatch = /Timeout (\d+)ms exceeded/.exec(message);
+  if (timeoutMatch) {
+    return new Error(
+      `Element "${selector}" timed out after ${timeoutMatch[1]}ms \u2014 element may be hidden or not interactable. Run a new snapshot to see current page elements.`
+    );
+  }
+  const cleaned = message.replace(/locator\([^)]*\)\./g, "").replace(/waiting for locator\([^)]*\)/g, "").trim();
+  return new Error(cleaned || message);
 }
 function normalizeTimeoutMs(timeoutMs, fallback, maxMs = 12e4) {
   return Math.max(500, Math.min(maxMs, timeoutMs ?? fallback));
@@ -3062,6 +3072,7 @@ function requiresInspectableBrowserNavigationRedirects(ssrfPolicy) {
 
 // src/actions/interaction.ts
 var MAX_CLICK_DELAY_MS = 5e3;
+var DEFAULT_SCROLL_TIMEOUT_MS = 2e4;
 var CHECKABLE_ROLES = /* @__PURE__ */ new Set(["menuitemcheckbox", "menuitemradio", "checkbox", "switch"]);
 function resolveLocator(page, resolved) {
   if (resolved.ref !== void 0 && resolved.ref !== "") return refLocator(page, resolved.ref);
@@ -3096,8 +3107,9 @@ async function pressAndHoldViaCdp(opts) {
 async function clickByTextViaPlaywright(opts) {
   const page = await getRestoredPageForTarget(opts);
   const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
+  const locator = page.getByText(opts.text, { exact: opts.exact }).and(page.locator(":visible")).or(page.getByTitle(opts.text, { exact: opts.exact })).first();
   try {
-    await page.getByText(opts.text, { exact: opts.exact }).click({ timeout, button: opts.button, modifiers: opts.modifiers });
+    await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
   } catch (err) {
     throw toAIFriendlyError(err, `text="${opts.text}"`);
   }
@@ -3105,13 +3117,12 @@ async function clickByTextViaPlaywright(opts) {
 async function clickByRoleViaPlaywright(opts) {
   const page = await getRestoredPageForTarget(opts);
   const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
+  const label = `role=${opts.role}${opts.name !== void 0 && opts.name !== "" ? ` name="${opts.name}"` : ""}`;
+  const locator = page.getByRole(opts.role, { name: opts.name }).nth(opts.index ?? 0);
   try {
-    await page.getByRole(opts.role, { name: opts.name }).click({ timeout, button: opts.button, modifiers: opts.modifiers });
+    await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
   } catch (err) {
-    throw toAIFriendlyError(
-      err,
-      `role=${opts.role}${opts.name !== void 0 && opts.name !== "" ? ` name="${opts.name}"` : ""}`
-    );
+    throw toAIFriendlyError(err, label);
   }
 }
 async function clickViaPlaywright(opts) {
@@ -3132,7 +3143,7 @@ async function clickViaPlaywright(opts) {
   try {
     const delayMs = resolveBoundedDelayMs(opts.delayMs, "click delayMs", MAX_CLICK_DELAY_MS);
     if (delayMs > 0) {
-      await locator.hover({ timeout });
+      await locator.hover({ timeout, force: opts.force });
       await new Promise((resolve2) => setTimeout(resolve2, delayMs));
     }
     let ariaCheckedBefore;
@@ -3140,9 +3151,9 @@ async function clickViaPlaywright(opts) {
       ariaCheckedBefore = await locator.getAttribute("aria-checked", { timeout }).catch(() => void 0);
     }
     if (opts.doubleClick === true) {
-      await locator.dblclick({ timeout, button: opts.button, modifiers: opts.modifiers });
+      await locator.dblclick({ timeout, button: opts.button, modifiers: opts.modifiers, force: opts.force });
     } else {
-      await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
+      await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers, force: opts.force });
     }
     if (checkableRole && opts.doubleClick !== true && ariaCheckedBefore !== void 0) {
       const POLL_INTERVAL_MS = 50;
@@ -3236,7 +3247,7 @@ async function fillFormViaPlaywright(opts) {
     if (type === "checkbox" || type === "radio") {
       const checked = rawValue === true || rawValue === 1 || rawValue === "1" || rawValue === "true";
       try {
-        await locator.setChecked(checked, { timeout });
+        await locator.setChecked(checked, { timeout, force: true });
       } catch (err) {
         throw toAIFriendlyError(err, ref);
       }
@@ -3255,7 +3266,13 @@ async function scrollIntoViewViaPlaywright(opts) {
   const label = resolved.ref ?? resolved.selector ?? "";
   const locator = resolveLocator(page, resolved);
   try {
-    await locator.scrollIntoViewIfNeeded({ timeout: normalizeTimeoutMs(opts.timeoutMs, 2e4) });
+    await locator.waitFor({
+      state: "attached",
+      timeout: normalizeTimeoutMs(opts.timeoutMs, DEFAULT_SCROLL_TIMEOUT_MS)
+    });
+    await locator.evaluate((el) => {
+      el.scrollIntoView({ block: "center", behavior: "instant" });
+    });
   } catch (err) {
     throw toAIFriendlyError(err, label);
   }
@@ -3531,9 +3548,13 @@ async function waitForViaPlaywright(opts) {
   if (opts.loadState !== void 0) {
     await page.waitForLoadState(opts.loadState, { timeout });
   }
-  if (opts.fn !== void 0 && opts.fn !== "") {
-    const fn = opts.fn.trim();
-    if (fn !== "") await page.waitForFunction(fn, void 0, { timeout });
+  if (opts.fn !== void 0) {
+    if (typeof opts.fn === "function") {
+      await page.waitForFunction(opts.fn, { timeout });
+    } else {
+      const fn = opts.fn.trim();
+      if (fn !== "") await page.waitForFunction(fn, void 0, { timeout });
+    }
   }
 }
 
@@ -4243,6 +4264,13 @@ async function traceStopViaPlaywright(opts) {
 }
 
 // src/snapshot/ref-map.ts
+function parseStateFromSuffix(suffix) {
+  const state = {};
+  if (/\[disabled\]/i.test(suffix)) state.disabled = true;
+  if (/\[checked\s*=\s*"?mixed"?\]/i.test(suffix)) state.checked = "mixed";
+  else if (/\[checked\]/i.test(suffix)) state.checked = true;
+  return state;
+}
 var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
   "button",
   "link",
@@ -4401,7 +4429,8 @@ function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
       const ref = nextRef();
       const nth = tracker.getNextIndex(role, name);
       tracker.trackRef(role, name, ref);
-      refs[ref] = { role, name, nth };
+      const state = parseStateFromSuffix(suffix);
+      refs[ref] = { role, name, nth, ...state };
       let enhanced = `${prefix}${roleRaw}`;
       if (name !== void 0 && name !== "") enhanced += ` "${name}"`;
       enhanced += ` [ref=${ref}]`;
@@ -4438,7 +4467,8 @@ function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
     const ref = nextRef();
     const nth = tracker.getNextIndex(role, name);
     tracker.trackRef(role, name, ref);
-    refs[ref] = { role, name, nth };
+    const state = parseStateFromSuffix(suffix);
+    refs[ref] = { role, name, nth, ...state };
     let enhanced = `${prefix}${roleRaw}`;
     if (name !== "") enhanced += ` "${name}"`;
     enhanced += ` [ref=${ref}]`;
@@ -4476,12 +4506,13 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
       if (!INTERACTIVE_ROLES.has(role)) continue;
       const ref = parseAiSnapshotRef(suffix);
       const prefix = /^(\s*-\s*)/.exec(line)?.[1] ?? "";
+      const state = parseStateFromSuffix(suffix);
       if (ref !== null) {
-        refs[ref] = { role, ...name !== void 0 && name !== "" ? { name } : {} };
+        refs[ref] = { role, ...name !== void 0 && name !== "" ? { name } : {}, ...state };
         out2.push(`${prefix}${roleRaw}${name !== void 0 && name !== "" ? ` "${name}"` : ""}${suffix}`);
       } else {
         const generatedRef = nextInteractiveRef();
-        refs[generatedRef] = { role, ...name !== void 0 && name !== "" ? { name } : {} };
+        refs[generatedRef] = { role, ...name !== void 0 && name !== "" ? { name } : {}, ...state };
         let enhanced = `${prefix}${roleRaw}`;
         if (name !== void 0 && name !== "") enhanced += ` "${name}"`;
         enhanced += ` [ref=${generatedRef}]`;
@@ -4519,12 +4550,13 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
     const isStructural = STRUCTURAL_ROLES.has(role);
     if (options.compact === true && isStructural && name === "") continue;
     const ref = parseAiSnapshotRef(suffix);
+    const state = parseStateFromSuffix(suffix);
     if (ref !== null) {
-      refs[ref] = { role, ...name !== "" ? { name } : {} };
+      refs[ref] = { role, ...name !== "" ? { name } : {}, ...state };
       out.push(line);
     } else if (INTERACTIVE_ROLES.has(role)) {
       const generatedRef = nextGeneratedRef();
-      refs[generatedRef] = { role, ...name !== "" ? { name } : {} };
+      refs[generatedRef] = { role, ...name !== "" ? { name } : {}, ...state };
       let enhanced = `${prefix}${roleRaw}`;
       if (name !== "") enhanced += ` "${name}"`;
       enhanced += ` [ref=${generatedRef}]`;
@@ -4890,7 +4922,8 @@ var CrawlPage = class {
       button: opts?.button,
       modifiers: opts?.modifiers,
       delayMs: opts?.delayMs,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      force: opts?.force
     });
   }
   /**
@@ -4916,7 +4949,8 @@ var CrawlPage = class {
       button: opts?.button,
       modifiers: opts?.modifiers,
       delayMs: opts?.delayMs,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      force: opts?.force
     });
   }
   /**
@@ -5019,6 +5053,7 @@ var CrawlPage = class {
       targetId: this.targetId,
       role,
       name,
+      index: opts?.index,
       button: opts?.button,
       modifiers: opts?.modifiers,
       timeoutMs: opts?.timeoutMs