@browserbasehq/stagehand 2.5.3 → 2.5.5

package/dist/index.js

@@ -473,6 +473,7 @@ __export(index_exports, {
   ZodSchemaValidationError: () => ZodSchemaValidationError,
   connectToMCPServer: () => connectToMCPServer,
   defaultExtractSchema: () => defaultExtractSchema,
+  getAccessibilityTree: () => getAccessibilityTree,
   pageTextSchema: () => pageTextSchema
 });
 module.exports = __toCommonJS(index_exports);
@@ -493,7 +494,7 @@ var StagehandFunctionName = /* @__PURE__ */ ((StagehandFunctionName2) => {
 })(StagehandFunctionName || {});
 
 // lib/version.ts
-var STAGEHAND_VERSION = "2.5.3";
+var STAGEHAND_VERSION = "2.5.5";
 
 // types/stagehandErrors.ts
 var StagehandError = class extends Error {
@@ -514,6 +515,7 @@ If you need help, please open a Github issue or reach out to us on Slack: https:
 Full error:
 ${error.message}`
       );
+      this.causedBy = error;
     }
   }
 };
@@ -2607,6 +2609,115 @@ var PUA_START = 57344;
 var PUA_END = 63743;
 var NBSP_CHARS = /* @__PURE__ */ new Set([160, 8239, 8199, 65279]);
 var WORLD_NAME = "stagehand-world";
+var DOM_DEPTH_ATTEMPTS = [-1, 256, 128, 64, 32, 16, 8, 4, 2, 1];
+var DESCRIBE_DEPTH_ATTEMPTS = [-1, 64, 32, 16, 8, 4, 2, 1];
+function isCborStackError(message) {
+  return message.includes("CBOR: stack limit exceeded");
+}
+function shouldExpandNode(node) {
+  var _a15, _b, _c;
+  const declaredChildren = (_a15 = node.childNodeCount) != null ? _a15 : 0;
+  const realizedChildren = (_c = (_b = node.children) == null ? void 0 : _b.length) != null ? _c : 0;
+  return declaredChildren > realizedChildren;
+}
+function mergeDomNodes(target, source) {
+  var _a15, _b, _c, _d;
+  target.childNodeCount = (_a15 = source.childNodeCount) != null ? _a15 : target.childNodeCount;
+  target.children = (_b = source.children) != null ? _b : target.children;
+  target.shadowRoots = (_c = source.shadowRoots) != null ? _c : target.shadowRoots;
+  target.contentDocument = (_d = source.contentDocument) != null ? _d : target.contentDocument;
+}
+function collectDomTraversalTargets(node) {
+  const targets = [];
+  if (node.children) targets.push(...node.children);
+  if (node.shadowRoots) targets.push(...node.shadowRoots);
+  if (node.contentDocument) targets.push(node.contentDocument);
+  return targets;
+}
+function hydrateDomTree(session, root) {
+  return __async(this, null, function* () {
+    var _a15, _b;
+    const stack = [root];
+    const expandedNodeIds = /* @__PURE__ */ new Set();
+    const expandedBackendIds = /* @__PURE__ */ new Set();
+    let describeCalls = 0;
+    while (stack.length) {
+      const node = stack.pop();
+      const nodeId = typeof node.nodeId === "number" && node.nodeId > 0 ? node.nodeId : void 0;
+      const backendId = typeof node.backendNodeId === "number" && node.backendNodeId > 0 ? node.backendNodeId : void 0;
+      const seenByNode = nodeId ? expandedNodeIds.has(nodeId) : false;
+      const seenByBackend = !nodeId && backendId ? expandedBackendIds.has(backendId) : false;
+      if (seenByNode || seenByBackend) continue;
+      if (nodeId) expandedNodeIds.add(nodeId);
+      else if (backendId) expandedBackendIds.add(backendId);
+      const needsExpansion = shouldExpandNode(node);
+      if (needsExpansion && (nodeId || backendId)) {
+        const describeParamsBase = nodeId ? { nodeId } : { backendNodeId: backendId };
+        let expanded = false;
+        for (const depth of DESCRIBE_DEPTH_ATTEMPTS) {
+          try {
+            const described = yield session.send("DOM.describeNode", __spreadProps(__spreadValues({}, describeParamsBase), {
+              depth,
+              pierce: true
+            }));
+            mergeDomNodes(node, described.node);
+            if (!nodeId && described.node.nodeId && described.node.nodeId > 0) {
+              node.nodeId = described.node.nodeId;
+              expandedNodeIds.add(described.node.nodeId);
+            }
+            describeCalls++;
+            expanded = true;
+            break;
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (isCborStackError(message)) {
+              continue;
+            }
+            const identifier = (_a15 = nodeId != null ? nodeId : backendId) != null ? _a15 : "unknown";
+            throw new StagehandDomProcessError(
+              `Failed to expand DOM node ${identifier}: ${String(err)}`
+            );
+          }
+        }
+        if (!expanded) {
+          const identifier = (_b = nodeId != null ? nodeId : backendId) != null ? _b : "unknown";
+          throw new StagehandDomProcessError(
+            `Unable to expand DOM node ${identifier} after describeNode depth retries`
+          );
+        }
+      }
+      for (const child of collectDomTraversalTargets(node)) {
+        stack.push(child);
+      }
+    }
+    return describeCalls;
+  });
+}
+function getDomTreeWithFallback(session) {
+  return __async(this, null, function* () {
+    let lastCborMessage = "";
+    for (const depth of DOM_DEPTH_ATTEMPTS) {
+      try {
+        const params = { depth, pierce: true };
+        const { root } = yield session.send("DOM.getDocument", params);
+        if (depth !== -1) {
+          yield hydrateDomTree(session, root);
+        }
+        return root;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (isCborStackError(message)) {
+          lastCborMessage = message;
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw new StagehandDomProcessError(
+      lastCborMessage ? `CDP DOM.getDocument failed after adaptive depth retries: ${lastCborMessage}` : "CDP DOM.getDocument failed after adaptive depth retries."
+    );
+  });
+}
 function cleanText(input) {
   let out = "";
   let prevWasSpace = false;
@@ -2664,10 +2775,7 @@ function buildBackendIdMaps(experimental, sp, targetFrame) {
       session === (yield sp.getCDPClient()) ? void 0 : targetFrame
     );
     try {
-      const { root } = yield session.send("DOM.getDocument", {
-        depth: -1,
-        pierce: true
-      });
+      const root = yield getDomTreeWithFallback(session);
       let startNode = root;
       let rootFid = targetFrame && (yield getCDPFrameId(sp, targetFrame));
       if (targetFrame && targetFrame !== sp.page.mainFrame() && session === (yield sp.getCDPClient())) {
@@ -2689,8 +2797,10 @@ function buildBackendIdMaps(experimental, sp, targetFrame) {
             if (n.contentDocument && locate(n.contentDocument)) return true;
             return false;
           } else {
-            if (n.backendNodeId === backendNodeId)
-              return iframeNode = n, true;
+            if (n.backendNodeId === backendNodeId) {
+              iframeNode = n;
+              return true;
+            }
             return ((_d2 = (_c2 = n.children) == null ? void 0 : _c2.some(locate)) != null ? _d2 : false) || (n.contentDocument ? locate(n.contentDocument) : false);
           }
         };
@@ -2702,17 +2812,25 @@ function buildBackendIdMaps(experimental, sp, targetFrame) {
       }
       const tagNameMap = {};
       const xpathMap = {};
+      const scrollableBackendIds = /* @__PURE__ */ new Set();
       const stack = [{ node: startNode, path: "", fid: rootFid }];
       const seen = /* @__PURE__ */ new Set();
       const joinStep = (base, step) => base.endsWith("//") ? `${base}${step}` : `${base}/${step}`;
       while (stack.length) {
         const { node, path: path4, fid } = stack.pop();
         if (!node.backendNodeId) continue;
+        const backendId = node.backendNodeId;
         const enc = sp.encodeWithFrameId(fid, node.backendNodeId);
         if (seen.has(enc)) continue;
         seen.add(enc);
         tagNameMap[enc] = lc(String(node.nodeName));
         xpathMap[enc] = path4;
+        if (node.isScrollable === true) {
+          scrollableBackendIds.add(backendId);
+        }
+        if (lc(String(node.nodeName)) === "html") {
+          scrollableBackendIds.add(backendId);
+        }
         if (lc(node.nodeName) === "iframe" && node.contentDocument) {
           const childFid = (_b = node.contentDocument.frameId) != null ? _b : fid;
           stack.push({ node: node.contentDocument, path: "", fid: childFid });
@@ -2753,7 +2871,7 @@ function buildBackendIdMaps(experimental, sp, targetFrame) {
           }
         }
       }
-      return { tagNameMap, xpathMap };
+      return { tagNameMap, xpathMap, scrollableBackendIds };
     } finally {
       yield sp.disableCDP(
         "DOM",
@@ -2885,11 +3003,7 @@ function getCDPFrameId(sp, frame) {
 }
 function getAccessibilityTree(experimental, stagehandPage, logger, selector, targetFrame) {
   return __async(this, null, function* () {
-    const { tagNameMap, xpathMap } = yield buildBackendIdMaps(
-      experimental,
-      stagehandPage,
-      targetFrame
-    );
+    const { tagNameMap, xpathMap, scrollableBackendIds } = yield buildBackendIdMaps(experimental, stagehandPage, targetFrame);
     yield stagehandPage.enableCDP("Accessibility", targetFrame);
     try {
       let params = {};
@@ -2916,10 +3030,6 @@ function getAccessibilityTree(experimental, stagehandPage, logger, selector, tar
         }
       }
       const { nodes: fullNodes } = yield stagehandPage.sendCDP("Accessibility.getFullAXTree", params, sessionFrame);
-      const scrollableIds = yield findScrollableElementIds(
-        stagehandPage,
-        targetFrame
-      );
       let nodes = fullNodes;
       if (selector) {
         nodes = yield filterAXTreeByXPath(
@@ -2931,7 +3041,7 @@ function getAccessibilityTree(experimental, stagehandPage, logger, selector, tar
       }
       const start = Date.now();
       const tree = yield buildHierarchicalTree(
-        decorateRoles(nodes, scrollableIds),
+        decorateRoles(nodes, scrollableBackendIds),
         tagNameMap,
         logger,
         xpathMap
@@ -2980,16 +3090,16 @@ function filterAXTreeByXPath(page, full, xpath, targetFrame) {
 }
 function decorateRoles(nodes, scrollables) {
   return nodes.map((n) => {
-    var _a15, _b, _c, _d, _e;
+    var _a15, _b, _c, _d, _e, _f;
     let role = (_b = (_a15 = n.role) == null ? void 0 : _a15.value) != null ? _b : "";
-    if (scrollables.has(n.backendDOMNodeId)) {
+    if (((_c = n.role) == null ? void 0 : _c.value) !== "RootWebArea" && scrollables.has(n.backendDOMNodeId)) {
       role = role && role !== "generic" && role !== "none" ? `scrollable, ${role}` : "scrollable";
     }
     return {
       role,
-      name: (_c = n.name) == null ? void 0 : _c.value,
-      description: (_d = n.description) == null ? void 0 : _d.value,
-      value: (_e = n.value) == null ? void 0 : _e.value,
+      name: (_d = n.name) == null ? void 0 : _d.value,
+      description: (_e = n.description) == null ? void 0 : _e.value,
+      value: (_f = n.value) == null ? void 0 : _f.value,
       nodeId: n.nodeId,
       backendDOMNodeId: n.backendDOMNodeId,
       parentId: n.parentId,
@@ -3219,27 +3329,6 @@ function getAccessibilityTreeWithFrames(experimental, stagehandPage, logger, roo
     return { combinedTree, combinedXpathMap, combinedUrlMap };
   });
 }
-function findScrollableElementIds(stagehandPage, targetFrame) {
-  return __async(this, null, function* () {
-    const xpaths = targetFrame ? yield targetFrame.evaluate(() => window.getScrollableElementXpaths()) : yield stagehandPage.page.evaluate(
-      () => window.getScrollableElementXpaths()
-    );
-    const backendIds = /* @__PURE__ */ new Set();
-    for (const xpath of xpaths) {
-      if (!xpath) continue;
-      const objectId = yield resolveObjectIdForXPath(
-        stagehandPage,
-        xpath,
-        targetFrame
-      );
-      if (objectId) {
-        const { node } = yield stagehandPage.sendCDP("DOM.describeNode", { objectId }, targetFrame);
-        if (node == null ? void 0 : node.backendNodeId) backendIds.add(node.backendNodeId);
-      }
-    }
-    return backendIds;
-  });
-}
 function resolveObjectIdForXPath(page, xpath, targetFrame) {
   return __async(this, null, function* () {
     const contextId = yield getFrameExecutionContextId(page, targetFrame);
@@ -3788,9 +3877,6 @@ var StagehandResponseParseError = class extends StagehandAPIError {
   }
 };
 
-// lib/dom/build/scriptContent.ts
-var scriptContent = '(() => {\n  // lib/dom/elementCheckUtils.ts\n  function isElementNode(node) {\n    return node.nodeType === Node.ELEMENT_NODE;\n  }\n  function isTextNode(node) {\n    return node.nodeType === Node.TEXT_NODE && Boolean(node.textContent?.trim());\n  }\n\n  // lib/dom/xpathUtils.ts\n  function getParentElement(node) {\n    return isElementNode(node) ? node.parentElement : node.parentNode;\n  }\n  function getCombinations(attributes, size) {\n    const results = [];\n    function helper(start, combo) {\n      if (combo.length === size) {\n        results.push([...combo]);\n        return;\n      }\n      for (let i = start; i < attributes.length; i++) {\n        combo.push(attributes[i]);\n        helper(i + 1, combo);\n        combo.pop();\n      }\n    }\n    helper(0, []);\n    return results;\n  }\n  function isXPathFirstResultElement(xpath, target) {\n    try {\n      const result = document.evaluate(\n        xpath,\n        document.documentElement,\n        null,\n        XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n        null\n      );\n      return result.snapshotItem(0) === target;\n    } catch (error) {\n      console.warn(`Invalid XPath expression: ${xpath}`, error);\n      return false;\n    }\n  }\n  function escapeXPathString(value) {\n    if (value.includes("\'")) {\n      if (value.includes(\'"\')) {\n        return "concat(" + value.split(/(\'+)/).map((part) => {\n          if (part === "\'") {\n            return `"\'"`;\n          } else if (part.startsWith("\'") && part.endsWith("\'")) {\n            return `"${part}"`;\n          } else {\n            return `\'${part}\'`;\n          }\n        }).join(",") + ")";\n      } else {\n        return `"${value}"`;\n      }\n    } else {\n      return `\'${value}\'`;\n    }\n  }\n  async function generateXPathsForElement(element) {\n    if (!element) return [];\n    const [complexXPath, standardXPath, idBasedXPath] = await Promise.all([\n      generateComplexXPath(element),\n      generateStandardXPath(element),\n      generatedIdBasedXPath(element)\n    ]);\n    return [standardXPath, ...idBasedXPath ? [idBasedXPath] : [], complexXPath];\n  }\n  async function generateComplexXPath(element) {\n    const parts = [];\n    let currentElement = element;\n    while (currentElement && (isTextNode(currentElement) || isElementNode(currentElement))) {\n      if (isElementNode(currentElement)) {\n        const el = currentElement;\n        let selector = el.tagName.toLowerCase();\n        const attributePriority = [\n          "data-qa",\n          "data-component",\n          "data-role",\n          "role",\n          "aria-role",\n          "type",\n          "name",\n          "aria-label",\n          "placeholder",\n          "title",\n          "alt"\n        ];\n        const attributes = attributePriority.map((attr) => {\n          let value = el.getAttribute(attr);\n          if (attr === "href-full" && value) {\n            value = el.getAttribute("href");\n          }\n          return value ? { attr: attr === "href-full" ? "href" : attr, value } : null;\n        }).filter((attr) => attr !== null);\n        let uniqueSelector = "";\n        for (let i = 1; i <= attributes.length; i++) {\n          const combinations = getCombinations(attributes, i);\n          for (const combo of combinations) {\n            const conditions = combo.map((a) => `@${a.attr}=${escapeXPathString(a.value)}`).join(" and ");\n            const xpath2 = `//${selector}[${conditions}]`;\n            if (isXPathFirstResultElement(xpath2, el)) {\n              uniqueSelector = xpath2;\n              break;\n            }\n          }\n          if (uniqueSelector) break;\n        }\n        if (uniqueSelector) {\n          parts.unshift(uniqueSelector.replace("//", ""));\n          break;\n        } else {\n          const parent = getParentElement(el);\n          if (parent) {\n            const siblings = Array.from(parent.children).filter(\n              (sibling) => sibling.tagName === el.tagName\n            );\n            const index = siblings.indexOf(el) + 1;\n            selector += siblings.length > 1 ? `[${index}]` : "";\n          }\n          parts.unshift(selector);\n        }\n      }\n      currentElement = getParentElement(currentElement);\n    }\n    const xpath = "//" + parts.join("/");\n    return xpath;\n  }\n  async function generateStandardXPath(element) {\n    const parts = [];\n    while (element && (isTextNode(element) || isElementNode(element))) {\n      let index = 0;\n      let hasSameTypeSiblings = false;\n      const siblings = element.parentElement ? Array.from(element.parentElement.childNodes) : [];\n      for (let i = 0; i < siblings.length; i++) {\n        const sibling = siblings[i];\n        if (sibling.nodeType === element.nodeType && sibling.nodeName === element.nodeName) {\n          index = index + 1;\n          hasSameTypeSiblings = true;\n          if (sibling.isSameNode(element)) {\n            break;\n          }\n        }\n      }\n      if (element.nodeName !== "#text") {\n        const tagName = element.nodeName.toLowerCase();\n        const pathIndex = hasSameTypeSiblings ? `[${index}]` : "";\n        parts.unshift(`${tagName}${pathIndex}`);\n      }\n      element = element.parentElement;\n    }\n    return parts.length ? `/${parts.join("/")}` : "";\n  }\n  async function generatedIdBasedXPath(element) {\n    if (isElementNode(element) && element.id) {\n      return `//*[@id=\'${element.id}\']`;\n    }\n    return null;\n  }\n\n  // types/stagehandErrors.ts\n  var StagehandError = class extends Error {\n    constructor(message) {\n      super(message);\n      this.name = this.constructor.name;\n    }\n  };\n  var StagehandDomProcessError = class extends StagehandError {\n    constructor(message) {\n      super(`Error Processing Dom: ${message}`);\n    }\n  };\n\n  // lib/dom/utils.ts\n  function canElementScroll(elem) {\n    if (typeof elem.scrollTo !== "function") {\n      console.warn("canElementScroll: .scrollTo is not a function.");\n      return false;\n    }\n    try {\n      const originalTop = elem.scrollTop;\n      elem.scrollTo({\n        top: originalTop + 100,\n        left: 0,\n        behavior: "instant"\n      });\n      if (elem.scrollTop === originalTop) {\n        throw new StagehandDomProcessError("scrollTop did not change");\n      }\n      elem.scrollTo({\n        top: originalTop,\n        left: 0,\n        behavior: "instant"\n      });\n      return true;\n    } catch (error) {\n      console.warn("canElementScroll error:", error.message || error);\n      return false;\n    }\n  }\n  function getNodeFromXpath(xpath) {\n    return document.evaluate(\n      xpath,\n      document.documentElement,\n      null,\n      XPathResult.FIRST_ORDERED_NODE_TYPE,\n      null\n    ).singleNodeValue;\n  }\n  function waitForElementScrollEnd(element, idleMs = 100) {\n    return new Promise((resolve) => {\n      let scrollEndTimer;\n      const handleScroll = () => {\n        clearTimeout(scrollEndTimer);\n        scrollEndTimer = window.setTimeout(() => {\n          element.removeEventListener("scroll", handleScroll);\n          resolve();\n        }, idleMs);\n      };\n      element.addEventListener("scroll", handleScroll, { passive: true });\n      handleScroll();\n    });\n  }\n\n  // lib/dom/process.ts\n  function getScrollableElements(topN) {\n    const docEl = document.documentElement;\n    const scrollableElements = [docEl];\n    const allElements = document.querySelectorAll("*");\n    for (const elem of allElements) {\n      const style = window.getComputedStyle(elem);\n      const overflowY = style.overflowY;\n      const isPotentiallyScrollable = overflowY === "auto" || overflowY === "scroll" || overflowY === "overlay";\n      if (isPotentiallyScrollable) {\n        const candidateScrollDiff = elem.scrollHeight - elem.clientHeight;\n        if (candidateScrollDiff > 0 && canElementScroll(elem)) {\n          scrollableElements.push(elem);\n        }\n      }\n    }\n    scrollableElements.sort((a, b) => b.scrollHeight - a.scrollHeight);\n    if (topN !== void 0) {\n      return scrollableElements.slice(0, topN);\n    }\n    return scrollableElements;\n  }\n  async function getScrollableElementXpaths(topN) {\n    const scrollableElems = getScrollableElements(topN);\n    const xpaths = [];\n    for (const elem of scrollableElems) {\n      const allXPaths = await generateXPathsForElement(elem);\n      const firstXPath = allXPaths?.[0] || "";\n      xpaths.push(firstXPath);\n    }\n    return xpaths;\n  }\n  (() => {\n    const closedRoots = /* @__PURE__ */ new WeakMap();\n    const nativeAttachShadow = Element.prototype.attachShadow;\n    Element.prototype.attachShadow = function(init) {\n      const root = nativeAttachShadow.call(this, init);\n      if (init.mode === "closed") closedRoots.set(this, root);\n      return root;\n    };\n    const backdoor = {\n      getClosedRoot: (host) => closedRoots.get(host),\n      queryClosed: (host, selector) => {\n        const root = closedRoots.get(host);\n        return root ? Array.from(root.querySelectorAll(selector)) : [];\n      },\n      xpathClosed: (host, xp) => {\n        const root = closedRoots.get(host);\n        if (!root) return [];\n        const it = document.evaluate(\n          xp,\n          root,\n          null,\n          XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n          null\n        );\n        const out = [];\n        for (let i = 0; i < it.snapshotLength; ++i) {\n          const n = it.snapshotItem(i);\n          if (n) out.push(n);\n        }\n        return out;\n      }\n    };\n    if (!("__stagehand__" in window)) {\n      Object.defineProperty(window, "__stagehand__", {\n        value: backdoor,\n        enumerable: false,\n        writable: false,\n        configurable: false\n      });\n    }\n  })();\n  window.getScrollableElementXpaths = getScrollableElementXpaths;\n  window.getNodeFromXpath = getNodeFromXpath;\n  window.waitForElementScrollEnd = waitForElementScrollEnd;\n})();\n';
-
 // lib/StagehandPage.ts
 function getCurrentRootFrameId(session) {
   return __async(this, null, function* () {
@@ -3875,32 +3961,6 @@ var StagehandPage = class _StagehandPage {
   resetFrameOrdinals() {
     this.fidOrdinals = /* @__PURE__ */ new Map([[void 0, 0]]);
   }
-  ensureStagehandScript() {
-    return __async(this, null, function* () {
-      try {
-        const injected = yield this.rawPage.evaluate(
-          () => !!window.__stagehandInjected
-        );
-        if (injected) return;
-        const guardedScript = `if (!window.__stagehandInjected) { window.__stagehandInjected = true; ${scriptContent} }`;
-        yield this.rawPage.addInitScript({ content: guardedScript });
-        yield this.rawPage.evaluate(guardedScript);
-      } catch (err) {
-        if (!this.stagehand.isClosed) {
-          this.stagehand.log({
-            category: "dom",
-            message: "Failed to inject Stagehand helper script",
-            level: 1,
-            auxiliary: {
-              error: { value: err.message, type: "string" },
-              trace: { value: err.stack, type: "string" }
-            }
-          });
-          throw err;
-        }
-      }
-    });
-  }
   /** Register the custom selector engine that pierces open/closed shadow roots. */
   ensureStagehandSelectorEngine() {
     return __async(this, null, function* () {
@@ -4056,7 +4116,6 @@ var StagehandPage = class _StagehandPage {
             const value = target[prop];
             if (prop === "evaluate" || prop === "evaluateHandle" || prop === "$eval" || prop === "$$eval") {
               return (...args) => __async(this, null, function* () {
-                yield this.ensureStagehandScript();
                 return value.apply(
                   target,
                   args
@@ -4663,8 +4722,17 @@ var StagehandPage = class _StagehandPage {
   }
 };
 
+// lib/dom/build/scriptContent.ts
+var scriptContent = '(() => {\n  // lib/dom/process.ts\n  (() => {\n    const closedRoots = /* @__PURE__ */ new WeakMap();\n    const nativeAttachShadow = Element.prototype.attachShadow;\n    Element.prototype.attachShadow = function(init) {\n      const root = nativeAttachShadow.call(this, init);\n      if (init.mode === "closed") closedRoots.set(this, root);\n      return root;\n    };\n    const backdoor = {\n      getClosedRoot: (host) => closedRoots.get(host),\n      queryClosed: (host, selector) => {\n        const root = closedRoots.get(host);\n        return root ? Array.from(root.querySelectorAll(selector)) : [];\n      },\n      xpathClosed: (host, xp) => {\n        const root = closedRoots.get(host);\n        if (!root) return [];\n        const it = document.evaluate(\n          xp,\n          root,\n          null,\n          XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n          null\n        );\n        const out = [];\n        for (let i = 0; i < it.snapshotLength; ++i) {\n          const n = it.snapshotItem(i);\n          if (n) out.push(n);\n        }\n        return out;\n      }\n    };\n    if (!("__stagehand__" in window)) {\n      Object.defineProperty(window, "__stagehand__", {\n        value: backdoor,\n        enumerable: false,\n        writable: false,\n        configurable: false\n      });\n    }\n  })();\n})();\n';
+
 // lib/StagehandContext.ts
-var StagehandContext = class _StagehandContext {
+var stagehandInitScript = `
+  if (!window.__stagehandInjected) {
+    window.__stagehandInjected = true;
+    ${scriptContent}
+  }
+`;
+var _StagehandContext = class _StagehandContext {
   constructor(context, stagehand) {
     this.activeStagehandPage = null;
     this.frameIdMap = /* @__PURE__ */ new Map();
@@ -4723,6 +4791,10 @@ var StagehandContext = class _StagehandContext {
   }
   static init(context, stagehand) {
     return __async(this, null, function* () {
+      if (!_StagehandContext.contextsWithInitScript.has(context)) {
+        yield context.addInitScript({ content: stagehandInitScript });
+        _StagehandContext.contextsWithInitScript.add(context);
+      }
       const instance = new _StagehandContext(context, stagehand);
       context.on("page", (pwPage) => __async(null, null, function* () {
         yield instance.handleNewPlaywrightPage(pwPage);
@@ -4825,6 +4897,8 @@ var StagehandContext = class _StagehandContext {
     });
   }
 };
+_StagehandContext.contextsWithInitScript = /* @__PURE__ */ new WeakSet();
+var StagehandContext = _StagehandContext;
 
 // lib/api.ts
 var import_zod_to_json_schema = __toESM(require("zod-to-json-schema"));
@@ -20290,9 +20364,7 @@ var modelToProviderMap = {
   "gpt-4o-2024-08-06": "openai",
   "gpt-4.5-preview": "openai",
   "o1-preview": "openai",
-  "claude-3-5-sonnet-latest": "anthropic",
-  "claude-3-5-sonnet-20240620": "anthropic",
-  "claude-3-5-sonnet-20241022": "anthropic",
+  "claude-haiku-4-5": "anthropic",
   "claude-3-7-sonnet-20250219": "anthropic",
   "claude-3-7-sonnet-latest": "anthropic",
   "cerebras-llama-3.3-70b": "cerebras",
@@ -24090,9 +24162,7 @@ var AvailableModelSchema = import_v315.z.enum([
   "gpt-4o-2024-08-06",
   "gpt-4.5-preview",
   "o1-preview",
-  "claude-3-5-sonnet-latest",
-  "claude-3-5-sonnet-20241022",
-  "claude-3-5-sonnet-20240620",
+  "claude-haiku-4-5",
   "claude-3-7-sonnet-latest",
   "claude-3-7-sonnet-20250219",
   "cerebras-llama-3.3-70b",
@@ -24932,5 +25002,6 @@ var Stagehand3 = class {
   ZodSchemaValidationError,
   connectToMCPServer,
   defaultExtractSchema,
+  getAccessibilityTree,
   pageTextSchema
 });

package/dist/lib/StagehandContext.d.ts

@@ -8,6 +8,7 @@ export declare class StagehandContext {
     private pageMap;
     private activeStagehandPage;
     private readonly frameIdMap;
+    private static readonly contextsWithInitScript;
     private constructor();
     private createStagehandPage;
     static init(context: PlaywrightContext, stagehand: Stagehand): Promise<StagehandContext>;

package/dist/lib/StagehandPage.d.ts

@@ -30,7 +30,6 @@ export declare class StagehandPage {
     ordinalForFrameId(fid: string | undefined): number;
     encodeWithFrameId(fid: string | undefined, backendId: number): EncodedId;
     resetFrameOrdinals(): void;
-    private ensureStagehandScript;
     /** Register the custom selector engine that pierces open/closed shadow roots. */
     private ensureStagehandSelectorEngine;
     /**

package/dist/lib/a11y/utils.d.ts

@@ -55,6 +55,9 @@ export declare function getCDPFrameId(sp: StagehandPage, frame?: Frame): Promise
  * Retrieve and build a cleaned accessibility tree for a document or specific iframe.
  * Prunes, formats, and optionally filters by XPath, including scrollable role decoration.
  *
+ * @deprecated This helper is an escape hatch intended for troubleshooting. Prefer
+ * extract() for supported usage and reach for this only
+ * when absolutely necessary.
  * @param stagehandPage - The StagehandPage instance for Playwright and CDP interaction.
  * @param logger - Logging function for diagnostics and performance metrics.
  * @param selector - Optional XPath to filter the AX tree to a specific subtree.
@@ -97,25 +100,6 @@ export declare function injectSubtrees(tree: string, idToTree: Map<EncodedId, st
  * @returns A Promise resolving to CombinedA11yResult with combined tree text, xpath map, and URL map.
  */
 export declare function getAccessibilityTreeWithFrames(experimental: boolean, stagehandPage: StagehandPage, logger: (l: LogLine) => void, rootXPath?: string): Promise<CombinedA11yResult>;
-/**
- * `findScrollableElementIds` is a function that identifies elements in
- * the browser that are deemed "scrollable". At a high level, it does the
- * following:
- * - Calls the browser-side `window.getScrollableElementXpaths()` function,
- *   which returns a list of XPaths for scrollable containers.
- * - Iterates over the returned list of XPaths, locating each element in the DOM
- *   using `stagehandPage.sendCDP(...)`
- *     - During each iteration, we call `Runtime.evaluate` to run `document.evaluate(...)`
- *       with each XPath, obtaining a `RemoteObject` reference if it exists.
- *     - Then, for each valid object reference, we call `DOM.describeNode` to retrieve
- *       the element’s `backendNodeId`.
- * - Collects all resulting `backendNodeId`s in a Set and returns them.
- *
- * @param stagehandPage - A StagehandPage instance with built-in CDP helpers.
- * @returns A Promise that resolves to a Set of unique `backendNodeId`s corresponding
- *          to scrollable elements in the DOM.
- */
-export declare function findScrollableElementIds(stagehandPage: StagehandPage, targetFrame?: Frame): Promise<Set<number>>;
 /**
  * Resolve an XPath to a Chrome-DevTools-Protocol (CDP) remote-object ID.
  *

package/dist/lib/dom/build/scriptContent.d.ts

@@ -1 +1 @@
-export declare const scriptContent = "(() => {\n  // lib/dom/elementCheckUtils.ts\n  function isElementNode(node) {\n    return node.nodeType === Node.ELEMENT_NODE;\n  }\n  function isTextNode(node) {\n    return node.nodeType === Node.TEXT_NODE && Boolean(node.textContent?.trim());\n  }\n\n  // lib/dom/xpathUtils.ts\n  function getParentElement(node) {\n    return isElementNode(node) ? node.parentElement : node.parentNode;\n  }\n  function getCombinations(attributes, size) {\n    const results = [];\n    function helper(start, combo) {\n      if (combo.length === size) {\n        results.push([...combo]);\n        return;\n      }\n      for (let i = start; i < attributes.length; i++) {\n        combo.push(attributes[i]);\n        helper(i + 1, combo);\n        combo.pop();\n      }\n    }\n    helper(0, []);\n    return results;\n  }\n  function isXPathFirstResultElement(xpath, target) {\n    try {\n      const result = document.evaluate(\n        xpath,\n        document.documentElement,\n        null,\n        XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n        null\n      );\n      return result.snapshotItem(0) === target;\n    } catch (error) {\n      console.warn(`Invalid XPath expression: ${xpath}`, error);\n      return false;\n    }\n  }\n  function escapeXPathString(value) {\n    if (value.includes(\"'\")) {\n      if (value.includes('\"')) {\n        return \"concat(\" + value.split(/('+)/).map((part) => {\n          if (part === \"'\") {\n            return `\"'\"`;\n          } else if (part.startsWith(\"'\") && part.endsWith(\"'\")) {\n            return `\"${part}\"`;\n          } else {\n            return `'${part}'`;\n          }\n        }).join(\",\") + \")\";\n      } else {\n        return `\"${value}\"`;\n      }\n    } else {\n      return `'${value}'`;\n    }\n  }\n  async function generateXPathsForElement(element) {\n    if (!element) return [];\n    const [complexXPath, standardXPath, idBasedXPath] = await Promise.all([\n      generateComplexXPath(element),\n      generateStandardXPath(element),\n      generatedIdBasedXPath(element)\n    ]);\n    return [standardXPath, ...idBasedXPath ? [idBasedXPath] : [], complexXPath];\n  }\n  async function generateComplexXPath(element) {\n    const parts = [];\n    let currentElement = element;\n    while (currentElement && (isTextNode(currentElement) || isElementNode(currentElement))) {\n      if (isElementNode(currentElement)) {\n        const el = currentElement;\n        let selector = el.tagName.toLowerCase();\n        const attributePriority = [\n          \"data-qa\",\n          \"data-component\",\n          \"data-role\",\n          \"role\",\n          \"aria-role\",\n          \"type\",\n          \"name\",\n          \"aria-label\",\n          \"placeholder\",\n          \"title\",\n          \"alt\"\n        ];\n        const attributes = attributePriority.map((attr) => {\n          let value = el.getAttribute(attr);\n          if (attr === \"href-full\" && value) {\n            value = el.getAttribute(\"href\");\n          }\n          return value ? { attr: attr === \"href-full\" ? \"href\" : attr, value } : null;\n        }).filter((attr) => attr !== null);\n        let uniqueSelector = \"\";\n        for (let i = 1; i <= attributes.length; i++) {\n          const combinations = getCombinations(attributes, i);\n          for (const combo of combinations) {\n            const conditions = combo.map((a) => `@${a.attr}=${escapeXPathString(a.value)}`).join(\" and \");\n            const xpath2 = `//${selector}[${conditions}]`;\n            if (isXPathFirstResultElement(xpath2, el)) {\n              uniqueSelector = xpath2;\n              break;\n            }\n          }\n          if (uniqueSelector) break;\n        }\n        if (uniqueSelector) {\n          parts.unshift(uniqueSelector.replace(\"//\", \"\"));\n          break;\n        } else {\n          const parent = getParentElement(el);\n          if (parent) {\n            const siblings = Array.from(parent.children).filter(\n              (sibling) => sibling.tagName === el.tagName\n            );\n            const index = siblings.indexOf(el) + 1;\n            selector += siblings.length > 1 ? `[${index}]` : \"\";\n          }\n          parts.unshift(selector);\n        }\n      }\n      currentElement = getParentElement(currentElement);\n    }\n    const xpath = \"//\" + parts.join(\"/\");\n    return xpath;\n  }\n  async function generateStandardXPath(element) {\n    const parts = [];\n    while (element && (isTextNode(element) || isElementNode(element))) {\n      let index = 0;\n      let hasSameTypeSiblings = false;\n      const siblings = element.parentElement ? Array.from(element.parentElement.childNodes) : [];\n      for (let i = 0; i < siblings.length; i++) {\n        const sibling = siblings[i];\n        if (sibling.nodeType === element.nodeType && sibling.nodeName === element.nodeName) {\n          index = index + 1;\n          hasSameTypeSiblings = true;\n          if (sibling.isSameNode(element)) {\n            break;\n          }\n        }\n      }\n      if (element.nodeName !== \"#text\") {\n        const tagName = element.nodeName.toLowerCase();\n        const pathIndex = hasSameTypeSiblings ? `[${index}]` : \"\";\n        parts.unshift(`${tagName}${pathIndex}`);\n      }\n      element = element.parentElement;\n    }\n    return parts.length ? `/${parts.join(\"/\")}` : \"\";\n  }\n  async function generatedIdBasedXPath(element) {\n    if (isElementNode(element) && element.id) {\n      return `//*[@id='${element.id}']`;\n    }\n    return null;\n  }\n\n  // types/stagehandErrors.ts\n  var StagehandError = class extends Error {\n    constructor(message) {\n      super(message);\n      this.name = this.constructor.name;\n    }\n  };\n  var StagehandDomProcessError = class extends StagehandError {\n    constructor(message) {\n      super(`Error Processing Dom: ${message}`);\n    }\n  };\n\n  // lib/dom/utils.ts\n  function canElementScroll(elem) {\n    if (typeof elem.scrollTo !== \"function\") {\n      console.warn(\"canElementScroll: .scrollTo is not a function.\");\n      return false;\n    }\n    try {\n      const originalTop = elem.scrollTop;\n      elem.scrollTo({\n        top: originalTop + 100,\n        left: 0,\n        behavior: \"instant\"\n      });\n      if (elem.scrollTop === originalTop) {\n        throw new StagehandDomProcessError(\"scrollTop did not change\");\n      }\n      elem.scrollTo({\n        top: originalTop,\n        left: 0,\n        behavior: \"instant\"\n      });\n      return true;\n    } catch (error) {\n      console.warn(\"canElementScroll error:\", error.message || error);\n      return false;\n    }\n  }\n  function getNodeFromXpath(xpath) {\n    return document.evaluate(\n      xpath,\n      document.documentElement,\n      null,\n      XPathResult.FIRST_ORDERED_NODE_TYPE,\n      null\n    ).singleNodeValue;\n  }\n  function waitForElementScrollEnd(element, idleMs = 100) {\n    return new Promise((resolve) => {\n      let scrollEndTimer;\n      const handleScroll = () => {\n        clearTimeout(scrollEndTimer);\n        scrollEndTimer = window.setTimeout(() => {\n          element.removeEventListener(\"scroll\", handleScroll);\n          resolve();\n        }, idleMs);\n      };\n      element.addEventListener(\"scroll\", handleScroll, { passive: true });\n      handleScroll();\n    });\n  }\n\n  // lib/dom/process.ts\n  function getScrollableElements(topN) {\n    const docEl = document.documentElement;\n    const scrollableElements = [docEl];\n    const allElements = document.querySelectorAll(\"*\");\n    for (const elem of allElements) {\n      const style = window.getComputedStyle(elem);\n      const overflowY = style.overflowY;\n      const isPotentiallyScrollable = overflowY === \"auto\" || overflowY === \"scroll\" || overflowY === \"overlay\";\n      if (isPotentiallyScrollable) {\n        const candidateScrollDiff = elem.scrollHeight - elem.clientHeight;\n        if (candidateScrollDiff > 0 && canElementScroll(elem)) {\n          scrollableElements.push(elem);\n        }\n      }\n    }\n    scrollableElements.sort((a, b) => b.scrollHeight - a.scrollHeight);\n    if (topN !== void 0) {\n      return scrollableElements.slice(0, topN);\n    }\n    return scrollableElements;\n  }\n  async function getScrollableElementXpaths(topN) {\n    const scrollableElems = getScrollableElements(topN);\n    const xpaths = [];\n    for (const elem of scrollableElems) {\n      const allXPaths = await generateXPathsForElement(elem);\n      const firstXPath = allXPaths?.[0] || \"\";\n      xpaths.push(firstXPath);\n    }\n    return xpaths;\n  }\n  (() => {\n    const closedRoots = /* @__PURE__ */ new WeakMap();\n    const nativeAttachShadow = Element.prototype.attachShadow;\n    Element.prototype.attachShadow = function(init) {\n      const root = nativeAttachShadow.call(this, init);\n      if (init.mode === \"closed\") closedRoots.set(this, root);\n      return root;\n    };\n    const backdoor = {\n      getClosedRoot: (host) => closedRoots.get(host),\n      queryClosed: (host, selector) => {\n        const root = closedRoots.get(host);\n        return root ? Array.from(root.querySelectorAll(selector)) : [];\n      },\n      xpathClosed: (host, xp) => {\n        const root = closedRoots.get(host);\n        if (!root) return [];\n        const it = document.evaluate(\n          xp,\n          root,\n          null,\n          XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n          null\n        );\n        const out = [];\n        for (let i = 0; i < it.snapshotLength; ++i) {\n          const n = it.snapshotItem(i);\n          if (n) out.push(n);\n        }\n        return out;\n      }\n    };\n    if (!(\"__stagehand__\" in window)) {\n      Object.defineProperty(window, \"__stagehand__\", {\n        value: backdoor,\n        enumerable: false,\n        writable: false,\n        configurable: false\n      });\n    }\n  })();\n  window.getScrollableElementXpaths = getScrollableElementXpaths;\n  window.getNodeFromXpath = getNodeFromXpath;\n  window.waitForElementScrollEnd = waitForElementScrollEnd;\n})();\n";
+export declare const scriptContent = "(() => {\n  // lib/dom/process.ts\n  (() => {\n    const closedRoots = /* @__PURE__ */ new WeakMap();\n    const nativeAttachShadow = Element.prototype.attachShadow;\n    Element.prototype.attachShadow = function(init) {\n      const root = nativeAttachShadow.call(this, init);\n      if (init.mode === \"closed\") closedRoots.set(this, root);\n      return root;\n    };\n    const backdoor = {\n      getClosedRoot: (host) => closedRoots.get(host),\n      queryClosed: (host, selector) => {\n        const root = closedRoots.get(host);\n        return root ? Array.from(root.querySelectorAll(selector)) : [];\n      },\n      xpathClosed: (host, xp) => {\n        const root = closedRoots.get(host);\n        if (!root) return [];\n        const it = document.evaluate(\n          xp,\n          root,\n          null,\n          XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n          null\n        );\n        const out = [];\n        for (let i = 0; i < it.snapshotLength; ++i) {\n          const n = it.snapshotItem(i);\n          if (n) out.push(n);\n        }\n        return out;\n      }\n    };\n    if (!(\"__stagehand__\" in window)) {\n      Object.defineProperty(window, \"__stagehand__\", {\n        value: backdoor,\n        enumerable: false,\n        writable: false,\n        configurable: false\n      });\n    }\n  })();\n})();\n";

package/dist/lib/dom/index.d.ts

@@ -1,2 +1 @@
-export * from "./process";
-export * from "./utils";
+import "./process";

package/dist/lib/dom/process.d.ts

@@ -1,17 +0,0 @@
-/**
- * Finds and returns a list of scrollable elements on the page,
- * ordered from the element with the largest scrollHeight to the smallest.
- *
- * @param topN Optional maximum number of scrollable elements to return.
- *             If not provided, all found scrollable elements are returned.
- * @returns An array of HTMLElements sorted by descending scrollHeight.
- */
-export declare function getScrollableElements(topN?: number): HTMLElement[];
-/**
- * Calls getScrollableElements, then for each element calls generateXPaths,
- * and returns the first XPath for each.
- *
- * @param topN (optional) integer limit on how many scrollable elements to process
- * @returns string[] list of XPaths (1 for each scrollable element)
- */
-export declare function getScrollableElementXpaths(topN?: number): Promise<string[]>;

package/dist/lib/index.d.ts

@@ -91,4 +91,7 @@ export * from "../types/stagehandApiErrors";
 export * from "../types/stagehandErrors";
 export * from "./llm/LLMClient";
 export * from "./llm/aisdk";
+export type { TreeResult } from "../types/context";
 export { connectToMCPServer };
+/** @deprecated Direct AX access is not part of the stable API. Prefer extract(). */
+export { getAccessibilityTree } from "./a11y/utils";

package/dist/lib/version.d.ts

@@ -2,4 +2,4 @@
  * AUTO-GENERATED — DO NOT EDIT BY HAND
  *  Run `pnpm run gen-version` to refresh.
  */
-export declare const STAGEHAND_VERSION: "2.5.3";
+export declare const STAGEHAND_VERSION: "2.5.5";

package/dist/types/context.d.ts

@@ -51,6 +51,7 @@ export interface TreeResult {
     xpathMap: Record<EncodedId, string>;
 }
 export type DOMNode = {
+    nodeId?: number;
     backendNodeId?: number;
     nodeName?: string;
     children?: DOMNode[];
@@ -58,11 +59,14 @@ export type DOMNode = {
     contentDocument?: DOMNode;
     nodeType: number;
     frameId?: string;
+    isScrollable?: boolean;
+    childNodeCount?: number;
 };
 export type BackendIdMaps = {
     tagNameMap: Record<number, string>;
     xpathMap: Record<number, string>;
     iframeXPath?: string;
+    scrollableBackendIds: Set<number>;
 };
 export interface EnhancedContext extends Omit<PlaywrightContext, "newPage" | "pages"> {
     newPage(): Promise<Page>;

package/dist/types/model.d.ts

@@ -1,7 +1,7 @@
 import type { ClientOptions as AnthropicClientOptions } from "@anthropic-ai/sdk";
 import type { ClientOptions as OpenAIClientOptions } from "openai";
 import { z } from "zod/v3";
-export declare const AvailableModelSchema: z.ZodEnum<["gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "o4-mini", "o3", "o3-mini", "o1", "o1-mini", "gpt-4o", "gpt-4o-mini", "gpt-4o-2024-08-06", "gpt-4.5-preview", "o1-preview", "claude-3-5-sonnet-latest", "claude-3-5-sonnet-20241022", "claude-3-5-sonnet-20240620", "claude-3-7-sonnet-latest", "claude-3-7-sonnet-20250219", "cerebras-llama-3.3-70b", "cerebras-llama-3.1-8b", "groq-llama-3.3-70b-versatile", "groq-llama-3.3-70b-specdec", "gemini-1.5-flash", "gemini-1.5-pro", "gemini-1.5-flash-8b", "gemini-2.0-flash-lite", "gemini-2.0-flash", "gemini-2.5-flash-preview-04-17", "gemini-2.5-pro-preview-03-25"]>;
+export declare const AvailableModelSchema: z.ZodEnum<["gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "o4-mini", "o3", "o3-mini", "o1", "o1-mini", "gpt-4o", "gpt-4o-mini", "gpt-4o-2024-08-06", "gpt-4.5-preview", "o1-preview", "claude-haiku-4-5", "claude-3-7-sonnet-latest", "claude-3-7-sonnet-20250219", "cerebras-llama-3.3-70b", "cerebras-llama-3.1-8b", "groq-llama-3.3-70b-versatile", "groq-llama-3.3-70b-specdec", "gemini-1.5-flash", "gemini-1.5-pro", "gemini-1.5-flash-8b", "gemini-2.0-flash-lite", "gemini-2.0-flash", "gemini-2.5-flash-preview-04-17", "gemini-2.5-pro-preview-03-25"]>;
 export type AvailableModel = z.infer<typeof AvailableModelSchema> | string;
 export type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "google" | "aisdk";
 export type ClientOptions = OpenAIClientOptions | AnthropicClientOptions;

package/dist/types/stagehandErrors.d.ts

@@ -3,6 +3,7 @@ export declare class StagehandError extends Error {
     constructor(message: string);
 }
 export declare class StagehandDefaultError extends StagehandError {
+    causedBy?: Error | StagehandError;
     constructor(error?: unknown);
 }
 export declare class StagehandEnvironmentError extends StagehandError {