@browserbasehq/stagehand 2.5.4 → 2.5.6

package/dist/index.d.ts

@@ -52,7 +52,7 @@ interface LLMTool {
     parameters: Record<string, unknown>;
 }
 
-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"]>;
+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"]>;
 type AvailableModel = z.infer<typeof AvailableModelSchema> | string;
 type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "google" | "aisdk";
 type ClientOptions = ClientOptions$1 | ClientOptions$2;
@@ -314,6 +314,9 @@ interface ObserveOptions {
      * @deprecated The `onlyVisible` parameter has no effect in this version of Stagehand and will be removed in later versions.
      */
     onlyVisible?: boolean;
+    /**
+     * @deprecated The `drawOverlay` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     */
     drawOverlay?: boolean;
     iframes?: boolean;
     frameId?: string;
@@ -796,6 +799,7 @@ declare class StagehandContext {
     private pageMap;
     private activeStagehandPage;
     private readonly frameIdMap;
+    private static readonly contextsWithInitScript;
     private constructor();
     private createStagehandPage;
     static init(context: BrowserContext$1, stagehand: Stagehand): Promise<StagehandContext>;
@@ -835,7 +839,6 @@ 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/index.js

@@ -494,7 +494,7 @@ var StagehandFunctionName = /* @__PURE__ */ ((StagehandFunctionName2) => {
 })(StagehandFunctionName || {});
 
 // lib/version.ts
-var STAGEHAND_VERSION = "2.5.4";
+var STAGEHAND_VERSION = "2.5.6";
 
 // types/stagehandErrors.ts
 var StagehandError = class extends Error {
@@ -2161,57 +2161,6 @@ function validateZodSchema(schema, data) {
   }
   throw new ZodSchemaValidationError(data, result.error.format());
 }
-function drawObserveOverlay(page, results) {
-  return __async(this, null, function* () {
-    const xpathList = results.map((result) => result.selector);
-    const validXpaths = xpathList.filter((xpath) => xpath !== "xpath=");
-    yield page.evaluate((selectors2) => {
-      selectors2.forEach((selector) => {
-        let element;
-        if (selector.startsWith("xpath=")) {
-          const xpath = selector.substring(6);
-          element = document.evaluate(
-            xpath,
-            document,
-            null,
-            XPathResult.FIRST_ORDERED_NODE_TYPE,
-            null
-          ).singleNodeValue;
-        } else {
-          element = document.querySelector(selector);
-        }
-        if (element instanceof HTMLElement) {
-          const overlay = document.createElement("div");
-          overlay.setAttribute("stagehandObserve", "true");
-          const rect = element.getBoundingClientRect();
-          overlay.style.position = "absolute";
-          overlay.style.left = rect.left + "px";
-          overlay.style.top = rect.top + "px";
-          overlay.style.width = rect.width + "px";
-          overlay.style.height = rect.height + "px";
-          overlay.style.backgroundColor = "rgba(255, 255, 0, 0.3)";
-          overlay.style.pointerEvents = "none";
-          overlay.style.zIndex = "10000";
-          document.body.appendChild(overlay);
-        }
-      });
-    }, validXpaths);
-  });
-}
-function clearOverlays(page) {
-  return __async(this, null, function* () {
-    yield page.evaluate(() => {
-      const elements = document.querySelectorAll('[stagehandObserve="true"]');
-      elements.forEach((el) => {
-        const parent = el.parentNode;
-        while (el.firstChild) {
-          parent == null ? void 0 : parent.insertBefore(el.firstChild, el);
-        }
-        parent == null ? void 0 : parent.removeChild(el);
-      });
-    });
-  });
-}
 function isRunningInBun() {
   return typeof process !== "undefined" && typeof process.versions !== "undefined" && "bun" in process.versions;
 }
@@ -2609,6 +2558,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;
@@ -2666,10 +2724,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())) {
@@ -3603,6 +3658,13 @@ var StagehandObserveHandler = class {
           level: 1
         });
       }
+      if (drawOverlay !== void 0) {
+        this.logger({
+          category: "observation",
+          message: "Warning: the drawOverlay parameter has been deprecated and this parameter is now a no-op.",
+          level: 1
+        });
+      }
       yield this.stagehandPage._waitForSettledDom();
       this.logger({
         category: "observation",
@@ -3730,9 +3792,6 @@ var StagehandObserveHandler = class {
           }
         }
       });
-      if (drawOverlay) {
-        yield drawObserveOverlay(this.stagehandPage.page, elementsWithSelectors);
-      }
       return elementsWithSelectors;
     });
   }
@@ -3771,9 +3830,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* () {
@@ -3858,32 +3914,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* () {
@@ -4039,7 +4069,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
@@ -4313,7 +4342,6 @@ var StagehandPage = class _StagehandPage {
         if (!this.actHandler) {
           throw new HandlerNotInitializedError("Act");
         }
-        yield clearOverlays(this.page);
         if (typeof actionOrOptions === "object" && actionOrOptions !== null) {
           if ("selector" in actionOrOptions && "method" in actionOrOptions) {
             const observeResult = actionOrOptions;
@@ -4392,7 +4420,6 @@ var StagehandPage = class _StagehandPage {
         if (!this.extractHandler) {
           throw new HandlerNotInitializedError("Extract");
         }
-        yield clearOverlays(this.page);
         if (!instructionOrOptions) {
           let result2;
           if (this.api) {
@@ -4495,7 +4522,6 @@ var StagehandPage = class _StagehandPage {
         if (!this.observeHandler) {
           throw new HandlerNotInitializedError("Observe");
         }
-        yield clearOverlays(this.page);
         const options = typeof instructionOrOptions === "string" ? { instruction: instructionOrOptions } : instructionOrOptions || {};
         const {
           instruction,
@@ -4646,8 +4672,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();
@@ -4706,6 +4741,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);
@@ -4808,6 +4847,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"));
@@ -20273,9 +20314,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",
@@ -24073,9 +24112,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",

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/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/handlers/observeHandler.d.ts

@@ -25,6 +25,9 @@ export declare class StagehandObserveHandler {
          * @deprecated The `onlyVisible` parameter has no effect in this version of Stagehand and will be removed in later versions.
          */
         onlyVisible?: boolean;
+        /**
+         * @deprecated The `drawOverlay` parameter has no effect in this version of Stagehand and will be removed in later versions.
+         */
         drawOverlay?: boolean;
         fromAct?: boolean;
         iframes?: boolean;

package/dist/lib/utils.d.ts

@@ -1,12 +1,9 @@
 import { Schema } from "@google/genai";
 import { z, ZodTypeAny } from "zod/v3";
-import { ObserveResult, Page } from ".";
 import { LogLine } from "../types/log";
 import { ModelProvider } from "../types/model";
 import { ZodPathSegments } from "../types/stagehand";
 export declare function validateZodSchema(schema: z.ZodTypeAny, data: unknown): boolean;
-export declare function drawObserveOverlay(page: Page, results: ObserveResult[]): Promise<void>;
-export declare function clearOverlays(page: Page): Promise<void>;
 /**
  * Detects if the code is running in the Bun runtime environment.
  * @returns {boolean} True if running in Bun, false otherwise.

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.4";
+export declare const STAGEHAND_VERSION: "2.5.6";

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[];
@@ -59,6 +60,7 @@ export type DOMNode = {
     nodeType: number;
     frameId?: string;
     isScrollable?: boolean;
+    childNodeCount?: number;
 };
 export type BackendIdMaps = {
     tagNameMap: Record<number, string>;

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/stagehand.d.ts

@@ -150,6 +150,9 @@ export interface ObserveOptions {
      * @deprecated The `onlyVisible` parameter has no effect in this version of Stagehand and will be removed in later versions.
      */
     onlyVisible?: boolean;
+    /**
+     * @deprecated The `drawOverlay` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     */
     drawOverlay?: boolean;
     iframes?: boolean;
     frameId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/stagehand",
-  "version": "2.5.4",
+  "version": "2.5.6",
   "description": "An AI web browsing framework focused on simplicity and extensibility.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

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

@@ -1,2 +0,0 @@
-export declare function isElementNode(node: Node): node is Element;
-export declare function isTextNode(node: Node): node is Text;

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

@@ -1,7 +0,0 @@
-/**
- * Tests if the element actually responds to .scrollTo(...)
- * and that scrollTop changes as expected.
- */
-export declare function canElementScroll(elem: HTMLElement): boolean;
-export declare function getNodeFromXpath(xpath: string): Node;
-export declare function waitForElementScrollEnd(element: HTMLElement, idleMs?: number): Promise<void>;

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

@@ -1,14 +0,0 @@
-/**
- * Escapes a string for use in an XPath expression.
- * Handles special characters, including single and double quotes.
- * @param value - The string to escape.
- * @returns The escaped string safe for XPath.
- */
-export declare function escapeXPathString(value: string): string;
-/**
- * Generates both a complicated XPath and a standard XPath for a given DOM element.
- * @param element - The target DOM element.
- * @param documentOverride - Optional document override.
- * @returns An object containing both XPaths.
- */
-export declare function generateXPathsForElement(element: ChildNode): Promise<string[]>;