@browserbasehq/stagehand 1.1.0 → 1.1.2

package/README.md

@@ -137,7 +137,7 @@ This constructor is used to create an instance of Stagehand.
     - `1`: SDK-level logging
     - `2`: LLM-client level logging (most granular)
   - `debugDom`: a `boolean` that draws bounding boxes around elements presented to the LLM during automation.
-  - `domSettleTimeoutMs`: an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. Defaults to 30000 (30 seconds).
+  - `domSettleTimeoutMs`: an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. It can be overriden in individual function calls if needed. Defaults to 30000 (30 seconds).
   - `enableCaching`: a `boolean` that enables caching of LLM responses. When set to `true`, the LLM requests will be cached on disk and reused for identical requests. Defaults to `false`.
 
 - **Returns:**
@@ -179,6 +179,7 @@ This constructor is used to create an instance of Stagehand.
   - `action`: a `string` describing the action to perform, e.g., `"search for 'x'"`.
   - `modelName`: (optional) an `AvailableModel` string to specify the model to use.
   - `useVision`: (optional) a `boolean` or `"fallback"` to determine if vision-based processing should be used. Defaults to `"fallback"`.
+  - `domSettleTimeoutMs`: (optional) an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. If not set, defaults to the timeout value specified during initialization.
 
 - **Returns:**
 
@@ -201,6 +202,7 @@ This constructor is used to create an instance of Stagehand.
   - `instruction`: a `string` providing instructions for extraction.
   - `schema`: a `z.AnyZodObject` defining the structure of the data to extract.
   - `modelName`: (optional) an `AvailableModel` string to specify the model to use.
+  - `domSettleTimeoutMs`: (optional) an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. If not set, defaults to the timeout value specified during initialization.
 
 - **Returns:**
 
@@ -229,6 +231,7 @@ If you are looking for a specific element, you can also pass in an instruction t
 
   - `instruction`: a `string` providing instructions for the observation.
   - `useVision`: (optional) a `boolean` or `"fallback"` to determine if vision-based processing should be used. Defaults to `"fallback"`.
+  - `domSettleTimeoutMs`: (optional) an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. If not set, defaults to the timeout value specified during initialization.
 
 - **Returns:**
 

package/dist/dom/build/index.js

@@ -1,8 +1,173 @@
 (() => {
+  // lib/dom/xpathUtils.ts
+  function getParentElement(node) {
+    return isElementNode(node) ? node.parentElement : node.parentNode;
+  }
+  function getCombinations(attributes, size) {
+    const results = [];
+    function helper(start, combo) {
+      if (combo.length === size) {
+        results.push([...combo]);
+        return;
+      }
+      for (let i = start; i < attributes.length; i++) {
+        combo.push(attributes[i]);
+        helper(i + 1, combo);
+        combo.pop();
+      }
+    }
+    helper(0, []);
+    return results;
+  }
+  function isXPathFirstResultElement(xpath, target) {
+    try {
+      const result = document.evaluate(
+        xpath,
+        document.documentElement,
+        null,
+        XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
+        null
+      );
+      return result.snapshotItem(0) === target;
+    } catch (error) {
+      console.warn(`Invalid XPath expression: ${xpath}`, error);
+      return false;
+    }
+  }
+  function escapeXPathString(value) {
+    if (value.includes("'")) {
+      if (value.includes('"')) {
+        return "concat(" + value.split(/('+)/).map((part) => {
+          if (part === "'") {
+            return `"'"`;
+          } else if (part.startsWith("'") && part.endsWith("'")) {
+            return `"${part}"`;
+          } else {
+            return `'${part}'`;
+          }
+        }).join(",") + ")";
+      } else {
+        return `"${value}"`;
+      }
+    } else {
+      return `'${value}'`;
+    }
+  }
+  async function generateXPathsForElement(element) {
+    if (!element) return [];
+    const [complexXPath, standardXPath, idBasedXPath] = await Promise.all([
+      generateComplexXPath(element),
+      generateStandardXPath(element),
+      generatedIdBasedXPath(element)
+    ]);
+    return [...idBasedXPath ? [idBasedXPath] : [], standardXPath, complexXPath];
+  }
+  async function generateComplexXPath(element) {
+    const parts = [];
+    let currentElement = element;
+    while (currentElement && (isTextNode(currentElement) || isElementNode(currentElement))) {
+      if (isElementNode(currentElement)) {
+        const el = currentElement;
+        let selector = el.tagName.toLowerCase();
+        const attributePriority = [
+          "data-qa",
+          "data-component",
+          "data-role",
+          "role",
+          "aria-role",
+          "type",
+          "name",
+          "aria-label",
+          "placeholder",
+          "title",
+          "alt"
+        ];
+        const attributes = attributePriority.map((attr) => {
+          let value = el.getAttribute(attr);
+          if (attr === "href-full" && value) {
+            value = el.getAttribute("href");
+          }
+          return value ? { attr: attr === "href-full" ? "href" : attr, value } : null;
+        }).filter((attr) => attr !== null);
+        let uniqueSelector = "";
+        for (let i = 1; i <= attributes.length; i++) {
+          const combinations = getCombinations(attributes, i);
+          for (const combo of combinations) {
+            const conditions = combo.map((a) => `@${a.attr}=${escapeXPathString(a.value)}`).join(" and ");
+            const xpath2 = `//${selector}[${conditions}]`;
+            if (isXPathFirstResultElement(xpath2, el)) {
+              uniqueSelector = xpath2;
+              break;
+            }
+          }
+          if (uniqueSelector) break;
+        }
+        if (uniqueSelector) {
+          parts.unshift(uniqueSelector.replace("//", ""));
+          break;
+        } else {
+          const parent = getParentElement(el);
+          if (parent) {
+            const siblings = Array.from(parent.children).filter(
+              (sibling) => sibling.tagName === el.tagName
+            );
+            const index = siblings.indexOf(el) + 1;
+            selector += siblings.length > 1 ? `[${index}]` : "";
+          }
+          parts.unshift(selector);
+        }
+      }
+      currentElement = getParentElement(currentElement);
+    }
+    const xpath = "//" + parts.join("/");
+    return xpath;
+  }
+  async function generateStandardXPath(element) {
+    const parts = [];
+    while (element && (isTextNode(element) || isElementNode(element))) {
+      let index = 0;
+      let hasSameTypeSiblings = false;
+      const siblings = element.parentElement ? Array.from(element.parentElement.childNodes) : [];
+      for (let i = 0; i < siblings.length; i++) {
+        const sibling = siblings[i];
+        if (sibling.nodeType === element.nodeType && sibling.nodeName === element.nodeName) {
+          index = index + 1;
+          hasSameTypeSiblings = true;
+          if (sibling.isSameNode(element)) {
+            break;
+          }
+        }
+      }
+      if (element.nodeName !== "#text") {
+        const tagName = element.nodeName.toLowerCase();
+        const pathIndex = hasSameTypeSiblings ? `[${index}]` : "";
+        parts.unshift(`${tagName}${pathIndex}`);
+      }
+      element = element.parentElement;
+    }
+    return parts.length ? `//${parts.join("//")}` : "";
+  }
+  async function generatedIdBasedXPath(element) {
+    if (isElementNode(element) && element.id) {
+      return `//*[@id='${element.id}']`;
+    }
+    return null;
+  }
+
   // lib/dom/process.ts
+  function isElementNode(node) {
+    return node.nodeType === Node.ELEMENT_NODE;
+  }
+  function isTextNode(node) {
+    return node.nodeType === Node.TEXT_NODE && Boolean(node.textContent?.trim());
+  }
   async function processDom(chunksSeen) {
     const { chunk, chunksArray } = await pickChunk(chunksSeen);
-    const { outputString, selectorMap } = await processElements2(chunk);
+    const { outputString, selectorMap } = await processElements2(
+      chunk,
+      void 0,
+      void 0
+    );
     console.log(
       `Stagehand (Browser Process): Extracted dom elements:
 ${outputString}`
@@ -49,12 +214,13 @@ ${outputString}`
         scrollEndTimer = window.setTimeout(() => {
           window.removeEventListener("scroll", handleScrollEnd);
           resolve();
-        }, 200);
+        }, 100);
       };
       window.addEventListener("scroll", handleScrollEnd, { passive: true });
       handleScrollEnd();
     });
   }
+  var xpathCache = /* @__PURE__ */ new Map();
   async function processElements2(chunk, scrollToChunk = true, indexOffset = 0) {
     console.time("processElements:total");
     const viewportHeight = window.innerHeight;
@@ -68,7 +234,6 @@ ${outputString}`
     }
     const candidateElements = [];
     const DOMQueue = [...document.body.childNodes];
-    const xpathCache = /* @__PURE__ */ new Map();
     console.log("Stagehand (Browser Process): Generating candidate elements");
     console.time("processElements:findCandidates");
     while (DOMQueue.length > 0) {
@@ -105,16 +270,25 @@ ${outputString}`
       `Stagehand (Browser Process): Processing candidate elements: ${candidateElements.length}`
     );
     console.time("processElements:processCandidates");
+    console.time("processElements:generateXPaths");
+    const xpathLists = await Promise.all(
+      candidateElements.map(async (element) => {
+        if (xpathCache.has(element)) {
+          return xpathCache.get(element);
+        }
+        const xpaths = await generateXPathsForElement(element);
+        xpathCache.set(element, xpaths);
+        return xpaths;
+      })
+    );
+    console.timeEnd("processElements:generateXPaths");
     candidateElements.forEach((element, index) => {
-      let xpath = xpathCache.get(element);
-      if (!xpath) {
-        xpath = generateXPath(element);
-        xpathCache.set(element, xpath);
-      }
+      const xpaths = xpathLists[index];
+      let elementOutput = "";
       if (isTextNode(element)) {
         const textContent = element.textContent?.trim();
         if (textContent) {
-          outputString += `${index + indexOffset}:${textContent}
+          elementOutput += `${index + indexOffset}:${textContent}
 `;
         }
       } else if (isElementNode(element)) {
@@ -123,10 +297,11 @@ ${outputString}`
         const openingTag = `<${tagName}${attributes ? " " + attributes : ""}>`;
         const closingTag = `</${tagName}>`;
         const textContent = element.textContent?.trim() || "";
-        outputString += `${index + indexOffset}:${openingTag}${textContent}${closingTag}
+        elementOutput += `${index + indexOffset}:${openingTag}${textContent}${closingTag}
 `;
       }
-      selectorMap[index + indexOffset] = xpath;
+      outputString += elementOutput;
+      selectorMap[index + indexOffset] = xpaths;
     });
     console.timeEnd("processElements:processCandidates");
     console.timeEnd("processElements:total");
@@ -163,34 +338,6 @@ ${outputString}`
   window.processAllOfDom = processAllOfDom;
   window.processElements = processElements2;
   window.scrollToHeight = scrollToHeight;
-  function generateXPath(element) {
-    if (isElementNode(element) && element.id) {
-      return `//*[@id='${element.id}']`;
-    }
-    const parts = [];
-    while (element && (isTextNode(element) || isElementNode(element))) {
-      let index = 0;
-      let hasSameTypeSiblings = false;
-      const siblings = element.parentElement ? Array.from(element.parentElement.childNodes) : [];
-      for (let i = 0; i < siblings.length; i++) {
-        const sibling = siblings[i];
-        if (sibling.nodeType === element.nodeType && sibling.nodeName === element.nodeName) {
-          index = index + 1;
-          hasSameTypeSiblings = true;
-          if (sibling.isSameNode(element)) {
-            break;
-          }
-        }
-      }
-      if (element.nodeName !== "#text") {
-        const tagName = element.nodeName.toLowerCase();
-        const pathIndex = hasSameTypeSiblings ? `[${index}]` : "";
-        parts.unshift(`${tagName}${pathIndex}`);
-      }
-      element = element.parentElement;
-    }
-    return parts.length ? `/${parts.join("/")}` : "";
-  }
   var leafElementDenyList = ["SVG", "IFRAME", "SCRIPT", "STYLE", "LINK"];
   var interactiveElementTypes = [
     "A",
@@ -231,13 +378,6 @@ ${outputString}`
     "tooltip"
   ];
   var interactiveAriaRoles = ["menu", "menuitem", "button"];
-  function isElementNode(node) {
-    return node.nodeType === Node.ELEMENT_NODE;
-  }
-  function isTextNode(node) {
-    const trimmedText = node.textContent?.trim().replace(/\s/g, "");
-    return node.nodeType === Node.TEXT_NODE && trimmedText !== "";
-  }
   var isVisible = (element) => {
     const rect = element.getBoundingClientRect();
     if (rect.width === 0 || rect.height === 0 || rect.top < 0 || rect.top > window.innerHeight) {

package/dist/dom/build/process.js

@@ -1,8 +1,173 @@
 (() => {
+  // lib/dom/xpathUtils.ts
+  function getParentElement(node) {
+    return isElementNode(node) ? node.parentElement : node.parentNode;
+  }
+  function getCombinations(attributes, size) {
+    const results = [];
+    function helper(start, combo) {
+      if (combo.length === size) {
+        results.push([...combo]);
+        return;
+      }
+      for (let i = start; i < attributes.length; i++) {
+        combo.push(attributes[i]);
+        helper(i + 1, combo);
+        combo.pop();
+      }
+    }
+    helper(0, []);
+    return results;
+  }
+  function isXPathFirstResultElement(xpath, target) {
+    try {
+      const result = document.evaluate(
+        xpath,
+        document.documentElement,
+        null,
+        XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
+        null
+      );
+      return result.snapshotItem(0) === target;
+    } catch (error) {
+      console.warn(`Invalid XPath expression: ${xpath}`, error);
+      return false;
+    }
+  }
+  function escapeXPathString(value) {
+    if (value.includes("'")) {
+      if (value.includes('"')) {
+        return "concat(" + value.split(/('+)/).map((part) => {
+          if (part === "'") {
+            return `"'"`;
+          } else if (part.startsWith("'") && part.endsWith("'")) {
+            return `"${part}"`;
+          } else {
+            return `'${part}'`;
+          }
+        }).join(",") + ")";
+      } else {
+        return `"${value}"`;
+      }
+    } else {
+      return `'${value}'`;
+    }
+  }
+  async function generateXPathsForElement(element) {
+    if (!element) return [];
+    const [complexXPath, standardXPath, idBasedXPath] = await Promise.all([
+      generateComplexXPath(element),
+      generateStandardXPath(element),
+      generatedIdBasedXPath(element)
+    ]);
+    return [...idBasedXPath ? [idBasedXPath] : [], standardXPath, complexXPath];
+  }
+  async function generateComplexXPath(element) {
+    const parts = [];
+    let currentElement = element;
+    while (currentElement && (isTextNode(currentElement) || isElementNode(currentElement))) {
+      if (isElementNode(currentElement)) {
+        const el = currentElement;
+        let selector = el.tagName.toLowerCase();
+        const attributePriority = [
+          "data-qa",
+          "data-component",
+          "data-role",
+          "role",
+          "aria-role",
+          "type",
+          "name",
+          "aria-label",
+          "placeholder",
+          "title",
+          "alt"
+        ];
+        const attributes = attributePriority.map((attr) => {
+          let value = el.getAttribute(attr);
+          if (attr === "href-full" && value) {
+            value = el.getAttribute("href");
+          }
+          return value ? { attr: attr === "href-full" ? "href" : attr, value } : null;
+        }).filter((attr) => attr !== null);
+        let uniqueSelector = "";
+        for (let i = 1; i <= attributes.length; i++) {
+          const combinations = getCombinations(attributes, i);
+          for (const combo of combinations) {
+            const conditions = combo.map((a) => `@${a.attr}=${escapeXPathString(a.value)}`).join(" and ");
+            const xpath2 = `//${selector}[${conditions}]`;
+            if (isXPathFirstResultElement(xpath2, el)) {
+              uniqueSelector = xpath2;
+              break;
+            }
+          }
+          if (uniqueSelector) break;
+        }
+        if (uniqueSelector) {
+          parts.unshift(uniqueSelector.replace("//", ""));
+          break;
+        } else {
+          const parent = getParentElement(el);
+          if (parent) {
+            const siblings = Array.from(parent.children).filter(
+              (sibling) => sibling.tagName === el.tagName
+            );
+            const index = siblings.indexOf(el) + 1;
+            selector += siblings.length > 1 ? `[${index}]` : "";
+          }
+          parts.unshift(selector);
+        }
+      }
+      currentElement = getParentElement(currentElement);
+    }
+    const xpath = "//" + parts.join("/");
+    return xpath;
+  }
+  async function generateStandardXPath(element) {
+    const parts = [];
+    while (element && (isTextNode(element) || isElementNode(element))) {
+      let index = 0;
+      let hasSameTypeSiblings = false;
+      const siblings = element.parentElement ? Array.from(element.parentElement.childNodes) : [];
+      for (let i = 0; i < siblings.length; i++) {
+        const sibling = siblings[i];
+        if (sibling.nodeType === element.nodeType && sibling.nodeName === element.nodeName) {
+          index = index + 1;
+          hasSameTypeSiblings = true;
+          if (sibling.isSameNode(element)) {
+            break;
+          }
+        }
+      }
+      if (element.nodeName !== "#text") {
+        const tagName = element.nodeName.toLowerCase();
+        const pathIndex = hasSameTypeSiblings ? `[${index}]` : "";
+        parts.unshift(`${tagName}${pathIndex}`);
+      }
+      element = element.parentElement;
+    }
+    return parts.length ? `//${parts.join("//")}` : "";
+  }
+  async function generatedIdBasedXPath(element) {
+    if (isElementNode(element) && element.id) {
+      return `//*[@id='${element.id}']`;
+    }
+    return null;
+  }
+
   // lib/dom/process.ts
+  function isElementNode(node) {
+    return node.nodeType === Node.ELEMENT_NODE;
+  }
+  function isTextNode(node) {
+    return node.nodeType === Node.TEXT_NODE && Boolean(node.textContent?.trim());
+  }
   async function processDom(chunksSeen) {
     const { chunk, chunksArray } = await pickChunk(chunksSeen);
-    const { outputString, selectorMap } = await processElements(chunk);
+    const { outputString, selectorMap } = await processElements(
+      chunk,
+      void 0,
+      void 0
+    );
     console.log(
       `Stagehand (Browser Process): Extracted dom elements:
 ${outputString}`
@@ -49,12 +214,13 @@ ${outputString}`
         scrollEndTimer = window.setTimeout(() => {
           window.removeEventListener("scroll", handleScrollEnd);
           resolve();
-        }, 200);
+        }, 100);
       };
       window.addEventListener("scroll", handleScrollEnd, { passive: true });
       handleScrollEnd();
     });
   }
+  var xpathCache = /* @__PURE__ */ new Map();
   async function processElements(chunk, scrollToChunk = true, indexOffset = 0) {
     console.time("processElements:total");
     const viewportHeight = window.innerHeight;
@@ -68,7 +234,6 @@ ${outputString}`
     }
     const candidateElements = [];
     const DOMQueue = [...document.body.childNodes];
-    const xpathCache = /* @__PURE__ */ new Map();
     console.log("Stagehand (Browser Process): Generating candidate elements");
     console.time("processElements:findCandidates");
     while (DOMQueue.length > 0) {
@@ -105,16 +270,25 @@ ${outputString}`
       `Stagehand (Browser Process): Processing candidate elements: ${candidateElements.length}`
     );
     console.time("processElements:processCandidates");
+    console.time("processElements:generateXPaths");
+    const xpathLists = await Promise.all(
+      candidateElements.map(async (element) => {
+        if (xpathCache.has(element)) {
+          return xpathCache.get(element);
+        }
+        const xpaths = await generateXPathsForElement(element);
+        xpathCache.set(element, xpaths);
+        return xpaths;
+      })
+    );
+    console.timeEnd("processElements:generateXPaths");
     candidateElements.forEach((element, index) => {
-      let xpath = xpathCache.get(element);
-      if (!xpath) {
-        xpath = generateXPath(element);
-        xpathCache.set(element, xpath);
-      }
+      const xpaths = xpathLists[index];
+      let elementOutput = "";
       if (isTextNode(element)) {
         const textContent = element.textContent?.trim();
         if (textContent) {
-          outputString += `${index + indexOffset}:${textContent}
+          elementOutput += `${index + indexOffset}:${textContent}
 `;
         }
       } else if (isElementNode(element)) {
@@ -123,10 +297,11 @@ ${outputString}`
         const openingTag = `<${tagName}${attributes ? " " + attributes : ""}>`;
         const closingTag = `</${tagName}>`;
         const textContent = element.textContent?.trim() || "";
-        outputString += `${index + indexOffset}:${openingTag}${textContent}${closingTag}
+        elementOutput += `${index + indexOffset}:${openingTag}${textContent}${closingTag}
 `;
       }
-      selectorMap[index + indexOffset] = xpath;
+      outputString += elementOutput;
+      selectorMap[index + indexOffset] = xpaths;
     });
     console.timeEnd("processElements:processCandidates");
     console.timeEnd("processElements:total");
@@ -163,34 +338,6 @@ ${outputString}`
   window.processAllOfDom = processAllOfDom;
   window.processElements = processElements;
   window.scrollToHeight = scrollToHeight;
-  function generateXPath(element) {
-    if (isElementNode(element) && element.id) {
-      return `//*[@id='${element.id}']`;
-    }
-    const parts = [];
-    while (element && (isTextNode(element) || isElementNode(element))) {
-      let index = 0;
-      let hasSameTypeSiblings = false;
-      const siblings = element.parentElement ? Array.from(element.parentElement.childNodes) : [];
-      for (let i = 0; i < siblings.length; i++) {
-        const sibling = siblings[i];
-        if (sibling.nodeType === element.nodeType && sibling.nodeName === element.nodeName) {
-          index = index + 1;
-          hasSameTypeSiblings = true;
-          if (sibling.isSameNode(element)) {
-            break;
-          }
-        }
-      }
-      if (element.nodeName !== "#text") {
-        const tagName = element.nodeName.toLowerCase();
-        const pathIndex = hasSameTypeSiblings ? `[${index}]` : "";
-        parts.unshift(`${tagName}${pathIndex}`);
-      }
-      element = element.parentElement;
-    }
-    return parts.length ? `/${parts.join("/")}` : "";
-  }
   var leafElementDenyList = ["SVG", "IFRAME", "SCRIPT", "STYLE", "LINK"];
   var interactiveElementTypes = [
     "A",
@@ -231,13 +378,6 @@ ${outputString}`
     "tooltip"
   ];
   var interactiveAriaRoles = ["menu", "menuitem", "button"];
-  function isElementNode(node) {
-    return node.nodeType === Node.ELEMENT_NODE;
-  }
-  function isTextNode(node) {
-    const trimmedText = node.textContent?.trim().replace(/\s/g, "");
-    return node.nodeType === Node.TEXT_NODE && trimmedText !== "";
-  }
   var isVisible = (element) => {
     const rect = element.getBoundingClientRect();
     if (rect.width === 0 || rect.height === 0 || rect.top < 0 || rect.top > window.innerHeight) {