@browserbasehq/stagehand 1.1.0 → 1.1.2

package/dist/dom/build/xpathUtils.js

@@ -0,0 +1,482 @@
+(() => {
+  // 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,
+      void 0,
+      void 0
+    );
+    console.log(
+      `Stagehand (Browser Process): Extracted dom elements:
+${outputString}`
+    );
+    return {
+      outputString,
+      selectorMap,
+      chunk,
+      chunks: chunksArray
+    };
+  }
+  async function processAllOfDom() {
+    console.log("Stagehand (Browser Process): Processing all of DOM");
+    const viewportHeight = window.innerHeight;
+    const documentHeight = document.documentElement.scrollHeight;
+    const totalChunks = Math.ceil(documentHeight / viewportHeight);
+    let index = 0;
+    const results = [];
+    for (let chunk = 0; chunk < totalChunks; chunk++) {
+      const result = await processElements(chunk, true, index);
+      results.push(result);
+      index += Object.keys(result.selectorMap).length;
+    }
+    await scrollToHeight(0);
+    const allOutputString = results.map((result) => result.outputString).join("");
+    const allSelectorMap = results.reduce(
+      (acc, result) => ({ ...acc, ...result.selectorMap }),
+      {}
+    );
+    console.log(
+      `Stagehand (Browser Process): All dom elements: ${allOutputString}`
+    );
+    return {
+      outputString: allOutputString,
+      selectorMap: allSelectorMap
+    };
+  }
+  async function scrollToHeight(height) {
+    window.scrollTo({ top: height, left: 0, behavior: "smooth" });
+    await new Promise((resolve) => {
+      let scrollEndTimer;
+      const handleScrollEnd = () => {
+        clearTimeout(scrollEndTimer);
+        scrollEndTimer = window.setTimeout(() => {
+          window.removeEventListener("scroll", handleScrollEnd);
+          resolve();
+        }, 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;
+    const chunkHeight = viewportHeight * chunk;
+    const maxScrollTop = document.documentElement.scrollHeight - window.innerHeight;
+    const offsetTop = Math.min(chunkHeight, maxScrollTop);
+    if (scrollToChunk) {
+      console.time("processElements:scroll");
+      await scrollToHeight(offsetTop);
+      console.timeEnd("processElements:scroll");
+    }
+    const candidateElements = [];
+    const DOMQueue = [...document.body.childNodes];
+    console.log("Stagehand (Browser Process): Generating candidate elements");
+    console.time("processElements:findCandidates");
+    while (DOMQueue.length > 0) {
+      const element = DOMQueue.pop();
+      let shouldAddElement = false;
+      if (element && isElementNode(element)) {
+        const childrenCount = element.childNodes.length;
+        for (let i = childrenCount - 1; i >= 0; i--) {
+          const child = element.childNodes[i];
+          DOMQueue.push(child);
+        }
+        if (isInteractiveElement(element)) {
+          if (isActive(element) && isVisible(element)) {
+            shouldAddElement = true;
+          }
+        }
+        if (isLeafElement(element)) {
+          if (isActive(element) && isVisible(element)) {
+            shouldAddElement = true;
+          }
+        }
+      }
+      if (element && isTextNode(element) && isTextVisible(element)) {
+        shouldAddElement = true;
+      }
+      if (shouldAddElement) {
+        candidateElements.push(element);
+      }
+    }
+    console.timeEnd("processElements:findCandidates");
+    const selectorMap = {};
+    let outputString = "";
+    console.log(
+      `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) => {
+      const xpaths = xpathLists[index];
+      let elementOutput = "";
+      if (isTextNode(element)) {
+        const textContent = element.textContent?.trim();
+        if (textContent) {
+          elementOutput += `${index + indexOffset}:${textContent}
+`;
+        }
+      } else if (isElementNode(element)) {
+        const tagName = element.tagName.toLowerCase();
+        const attributes = collectEssentialAttributes(element);
+        const openingTag = `<${tagName}${attributes ? " " + attributes : ""}>`;
+        const closingTag = `</${tagName}>`;
+        const textContent = element.textContent?.trim() || "";
+        elementOutput += `${index + indexOffset}:${openingTag}${textContent}${closingTag}
+`;
+      }
+      outputString += elementOutput;
+      selectorMap[index + indexOffset] = xpaths;
+    });
+    console.timeEnd("processElements:processCandidates");
+    console.timeEnd("processElements:total");
+    return {
+      outputString,
+      selectorMap
+    };
+  }
+  function collectEssentialAttributes(element) {
+    const essentialAttributes = [
+      "id",
+      "class",
+      "href",
+      "src",
+      "aria-label",
+      "aria-name",
+      "aria-role",
+      "aria-description",
+      "aria-expanded",
+      "aria-haspopup"
+    ];
+    const attrs = essentialAttributes.map((attr) => {
+      const value = element.getAttribute(attr);
+      return value ? `${attr}="${value}"` : "";
+    }).filter((attr) => attr !== "");
+    Array.from(element.attributes).forEach((attr) => {
+      if (attr.name.startsWith("data-")) {
+        attrs.push(`${attr.name}="${attr.value}"`);
+      }
+    });
+    return attrs.join(" ");
+  }
+  window.processDom = processDom;
+  window.processAllOfDom = processAllOfDom;
+  window.processElements = processElements;
+  window.scrollToHeight = scrollToHeight;
+  var leafElementDenyList = ["SVG", "IFRAME", "SCRIPT", "STYLE", "LINK"];
+  var interactiveElementTypes = [
+    "A",
+    "BUTTON",
+    "DETAILS",
+    "EMBED",
+    "INPUT",
+    "LABEL",
+    "MENU",
+    "MENUITEM",
+    "OBJECT",
+    "SELECT",
+    "TEXTAREA",
+    "SUMMARY"
+  ];
+  var interactiveRoles = [
+    "button",
+    "menu",
+    "menuitem",
+    "link",
+    "checkbox",
+    "radio",
+    "slider",
+    "tab",
+    "tabpanel",
+    "textbox",
+    "combobox",
+    "grid",
+    "listbox",
+    "option",
+    "progressbar",
+    "scrollbar",
+    "searchbox",
+    "switch",
+    "tree",
+    "treeitem",
+    "spinbutton",
+    "tooltip"
+  ];
+  var interactiveAriaRoles = ["menu", "menuitem", "button"];
+  var isVisible = (element) => {
+    const rect = element.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0 || rect.top < 0 || rect.top > window.innerHeight) {
+      return false;
+    }
+    if (!isTopElement(element, rect)) {
+      return false;
+    }
+    const visible = element.checkVisibility({
+      checkOpacity: true,
+      checkVisibilityCSS: true
+    });
+    return visible;
+  };
+  var isTextVisible = (element) => {
+    const range = document.createRange();
+    range.selectNodeContents(element);
+    const rect = range.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0 || rect.top < 0 || rect.top > window.innerHeight) {
+      return false;
+    }
+    const parent = element.parentElement;
+    if (!parent) {
+      return false;
+    }
+    if (!isTopElement(parent, rect)) {
+      return false;
+    }
+    const visible = parent.checkVisibility({
+      checkOpacity: true,
+      checkVisibilityCSS: true
+    });
+    return visible;
+  };
+  function isTopElement(elem, rect) {
+    const points = [
+      { x: rect.left + rect.width * 0.25, y: rect.top + rect.height * 0.25 },
+      { x: rect.left + rect.width * 0.75, y: rect.top + rect.height * 0.25 },
+      { x: rect.left + rect.width * 0.25, y: rect.top + rect.height * 0.75 },
+      { x: rect.left + rect.width * 0.75, y: rect.top + rect.height * 0.75 },
+      { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 }
+    ];
+    return points.some((point) => {
+      const topEl = document.elementFromPoint(point.x, point.y);
+      let current = topEl;
+      while (current && current !== document.body) {
+        if (current.isSameNode(elem)) {
+          return true;
+        }
+        current = current.parentElement;
+      }
+      return false;
+    });
+  }
+  var isActive = (element) => {
+    if (element.hasAttribute("disabled") || element.hasAttribute("hidden") || element.getAttribute("aria-disabled") === "true") {
+      return false;
+    }
+    return true;
+  };
+  var isInteractiveElement = (element) => {
+    const elementType = element.tagName;
+    const elementRole = element.getAttribute("role");
+    const elementAriaRole = element.getAttribute("aria-role");
+    return elementType && interactiveElementTypes.includes(elementType) || elementRole && interactiveRoles.includes(elementRole) || elementAriaRole && interactiveAriaRoles.includes(elementAriaRole);
+  };
+  var isLeafElement = (element) => {
+    if (element.textContent === "") {
+      return false;
+    }
+    if (element.childNodes.length === 0) {
+      return !leafElementDenyList.includes(element.tagName);
+    }
+    if (element.childNodes.length === 1 && isTextNode(element.childNodes[0])) {
+      return true;
+    }
+    return false;
+  };
+  async function pickChunk(chunksSeen) {
+    const viewportHeight = window.innerHeight;
+    const documentHeight = document.documentElement.scrollHeight;
+    const chunks = Math.ceil(documentHeight / viewportHeight);
+    const chunksArray = Array.from({ length: chunks }, (_, i) => i);
+    const chunksRemaining = chunksArray.filter((chunk2) => {
+      return !chunksSeen.includes(chunk2);
+    });
+    const currentScrollPosition = window.scrollY;
+    const closestChunk = chunksRemaining.reduce((closest, current) => {
+      const currentChunkTop = viewportHeight * current;
+      const closestChunkTop = viewportHeight * closest;
+      return Math.abs(currentScrollPosition - currentChunkTop) < Math.abs(currentScrollPosition - closestChunkTop) ? current : closest;
+    }, chunksRemaining[0]);
+    const chunk = closestChunk;
+    if (chunk === void 0) {
+      throw new Error(`No chunks remaining to check: ${chunksRemaining}`);
+    }
+    return {
+      chunk,
+      chunksArray
+    };
+  }
+
+  // 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;
+  }
+})();

package/dist/index.d.ts

@@ -54,7 +54,6 @@ declare class LLMProvider {
 declare class Stagehand {
     private llmProvider;
     private observations;
-    private actions;
     page: Page;
     context: BrowserContext;
     private env;
@@ -69,6 +68,8 @@ declare class Stagehand {
     private domSettleTimeoutMs;
     private browserBaseSessionCreateParams?;
     private enableCaching;
+    private variables;
+    private actHandler;
     private browserbaseResumeSessionID?;
     constructor({ env, apiKey, projectId, verbose, debugDom, llmProvider, headless, logger, browserBaseSessionCreateParams, domSettleTimeoutMs, enableCaching, browserbaseResumeSessionID, }?: {
         env: "LOCAL" | "BROWSERBASE";
@@ -88,8 +89,9 @@ declare class Stagehand {
         enableCaching?: boolean;
         browserbaseResumeSessionID?: string;
     });
-    init({ modelName, }?: {
+    init({ modelName, domSettleTimeoutMs, }?: {
         modelName?: AvailableModel;
+        domSettleTimeoutMs?: number;
     }): Promise<{
         debugUrl: string;
         sessionUrl: string;
@@ -109,30 +111,31 @@ declare class Stagehand {
     private _waitForSettledDom;
     private startDomDebug;
     private cleanupDomDebug;
-    private _generateId;
     private _recordObservation;
-    private _recordAction;
     private _extract;
     private _observe;
-    private _act;
-    act({ action, modelName, useVision, }: {
+    act({ action, modelName, useVision, variables, domSettleTimeoutMs, }: {
         action: string;
         modelName?: AvailableModel;
         useVision?: "fallback" | boolean;
+        variables?: Record<string, string>;
+        domSettleTimeoutMs?: number;
     }): Promise<{
         success: boolean;
         message: string;
         action: string;
     }>;
-    extract<T extends z.AnyZodObject>({ instruction, schema, modelName, }: {
+    extract<T extends z.AnyZodObject>({ instruction, schema, modelName, domSettleTimeoutMs, }: {
         instruction: string;
         schema: T;
         modelName?: AvailableModel;
+        domSettleTimeoutMs?: number;
     }): Promise<z.infer<T>>;
     observe(options?: {
         instruction?: string;
         modelName?: AvailableModel;
         useVision?: boolean;
+        domSettleTimeoutMs?: number;
     }): Promise<{
         selector: string;
         description: string;