@browserbasehq/stagehand 1.13.1 → 1.14.0-alpha-66ccf1a5693cc0a67ecedabd29b39d372d8e42dd

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,2 @@
1
+ import { EvalFunction } from "@/types/evals";
2
+ export declare const extract_hamilton_weather: EvalFunction;
@@ -0,0 +1,2 @@
1
+ import { EvalFunction } from "@/types/evals";
2
+ export declare const extract_regulations_table: EvalFunction;
package/dist/index.d.ts CHANGED
@@ -206,6 +206,7 @@ interface ExtractOptions<T extends z.AnyZodObject> {
206
206
  modelClientOptions?: ClientOptions;
207
207
  domSettleTimeoutMs?: number;
208
208
  useTextExtract?: boolean;
209
+ selector?: string;
209
210
  }
210
211
  type ExtractResult<T extends z.AnyZodObject> = z.infer<T>;
211
212
  interface ObserveOptions {
package/dist/index.js CHANGED
@@ -2912,7 +2912,8 @@ var StagehandExtractHandler = class {
2912
2912
  llmClient,
2913
2913
  requestId,
2914
2914
  domSettleTimeoutMs,
2915
- useTextExtract = false
2915
+ useTextExtract = false,
2916
+ selector
2916
2917
  }) {
2917
2918
  if (useTextExtract) {
2918
2919
  return this.textExtract({
@@ -2921,7 +2922,8 @@ var StagehandExtractHandler = class {
2921
2922
  content,
2922
2923
  llmClient,
2923
2924
  requestId,
2924
- domSettleTimeoutMs
2925
+ domSettleTimeoutMs,
2926
+ selector
2925
2927
  });
2926
2928
  } else {
2927
2929
  return this.domExtract({
@@ -2943,7 +2945,8 @@ var StagehandExtractHandler = class {
2943
2945
  content = {},
2944
2946
  llmClient,
2945
2947
  requestId,
2946
- domSettleTimeoutMs
2948
+ domSettleTimeoutMs,
2949
+ selector
2947
2950
  }) {
2948
2951
  this.logger({
2949
2952
  category: "extraction",
@@ -2958,50 +2961,37 @@ var StagehandExtractHandler = class {
2958
2961
  });
2959
2962
  yield this.stagehandPage._waitForSettledDom(domSettleTimeoutMs);
2960
2963
  yield this.stagehandPage.startDomDebug();
2964
+ const targetXpath = selector;
2961
2965
  const originalDOM = yield this.stagehandPage.page.evaluate(
2962
- () => window.storeDOM()
2966
+ (xp) => window.storeDOM(xp),
2967
+ targetXpath
2968
+ );
2969
+ const { selectorMap } = yield this.stagehand.page.evaluate(
2970
+ (xp) => window.processAllOfDom(xp),
2971
+ targetXpath
2963
2972
  );
2964
- const { selectorMap } = yield this.stagehand.page.evaluate(() => window.processAllOfDom());
2965
2973
  this.logger({
2966
2974
  category: "extraction",
2967
2975
  message: `received output from processAllOfDom. selectorMap has ${Object.keys(selectorMap).length} entries`,
2968
2976
  level: 1
2969
2977
  });
2970
- yield this.stagehand.page.evaluate(() => window.createTextBoundingBoxes());
2971
- const pageWidth = yield this.stagehand.page.evaluate(
2972
- () => window.innerWidth
2978
+ yield this.stagehand.page.evaluate(
2979
+ (xp) => window.createTextBoundingBoxes(xp),
2980
+ targetXpath
2973
2981
  );
2974
- const pageHeight = yield this.stagehand.page.evaluate(
2975
- () => window.innerHeight
2982
+ const {
2983
+ width: containerWidth,
2984
+ height: containerHeight,
2985
+ offsetLeft = 0,
2986
+ offsetTop = 0
2987
+ } = yield this.getTargetDimensions(targetXpath);
2988
+ const allAnnotations = yield this.collectAllAnnotations(
2989
+ selectorMap,
2990
+ containerWidth,
2991
+ containerHeight,
2992
+ offsetLeft,
2993
+ offsetTop
2976
2994
  );
2977
- const allAnnotations = [];
2978
- for (const xpaths of Object.values(selectorMap)) {
2979
- const xpath = xpaths[0];
2980
- const boundingBoxes = yield this.stagehandPage.page.evaluate(
2981
- (xpath2) => window.getElementBoundingBoxes(xpath2),
2982
- xpath
2983
- );
2984
- for (const box of boundingBoxes) {
2985
- const bottom_left = {
2986
- x: box.left,
2987
- y: box.top + box.height
2988
- };
2989
- const bottom_left_normalized = {
2990
- x: box.left / pageWidth,
2991
- y: (box.top + box.height) / pageHeight
2992
- };
2993
- const annotation = {
2994
- text: box.text,
2995
- bottom_left,
2996
- bottom_left_normalized,
2997
- width: box.width,
2998
- height: box.height
2999
- };
3000
- if (annotation.text.length > 0) {
3001
- allAnnotations.push(annotation);
3002
- }
3003
- }
3004
- }
3005
2995
  const annotationsGroupedByText = /* @__PURE__ */ new Map();
3006
2996
  for (const annotation of allAnnotations) {
3007
2997
  if (!annotationsGroupedByText.has(annotation.text)) {
@@ -3027,10 +3017,13 @@ var StagehandExtractHandler = class {
3027
3017
  }
3028
3018
  }
3029
3019
  yield this.stagehandPage.page.evaluate(
3030
- (dom) => window.restoreDOM(dom),
3031
- originalDOM
3020
+ ({ dom, xp }) => window.restoreDOM(dom, xp),
3021
+ { dom: originalDOM, xp: targetXpath }
3022
+ );
3023
+ const formattedText = formatText(
3024
+ deduplicatedTextAnnotations,
3025
+ containerWidth
3032
3026
  );
3033
- const formattedText = formatText(deduplicatedTextAnnotations, pageWidth);
3034
3027
  const extractionResponse = yield extract({
3035
3028
  instruction,
3036
3029
  previouslyExtractedContent: content,
@@ -3197,6 +3190,87 @@ var StagehandExtractHandler = class {
3197
3190
  }
3198
3191
  });
3199
3192
  }
3193
+ /**
3194
+ * Get the width, height, and offsets of either the entire page or a specific element.
3195
+ * (Matches your existing getTargetDimensions logic, just adapted to accept a string | undefined.)
3196
+ */
3197
+ getTargetDimensions(targetXpath) {
3198
+ return __async(this, null, function* () {
3199
+ if (!targetXpath) {
3200
+ const { innerWidth, innerHeight } = yield this.stagehand.page.evaluate(
3201
+ () => ({
3202
+ innerWidth: window.innerWidth,
3203
+ innerHeight: window.innerHeight
3204
+ })
3205
+ );
3206
+ return {
3207
+ width: innerWidth,
3208
+ height: innerHeight,
3209
+ offsetLeft: 0,
3210
+ offsetTop: 0
3211
+ };
3212
+ }
3213
+ const { elemWidth, elemHeight, offsetLeft, offsetTop } = yield this.stagehand.page.evaluate((xp) => {
3214
+ const el = window.getNodeFromXpath(xp);
3215
+ if (!el) {
3216
+ return {
3217
+ elemWidth: window.innerWidth,
3218
+ elemHeight: window.innerHeight,
3219
+ offsetLeft: 0,
3220
+ offsetTop: 0
3221
+ };
3222
+ }
3223
+ const rect = el.getBoundingClientRect();
3224
+ return {
3225
+ elemWidth: rect.width,
3226
+ elemHeight: rect.height,
3227
+ offsetLeft: rect.left,
3228
+ offsetTop: rect.top
3229
+ };
3230
+ }, targetXpath);
3231
+ return {
3232
+ width: elemWidth,
3233
+ height: elemHeight,
3234
+ offsetLeft,
3235
+ offsetTop
3236
+ };
3237
+ });
3238
+ }
3239
+ /**
3240
+ * Collects the bounding boxes for each word inside each of the candidate element in selectorMap,
3241
+ * adjusting for container offsets, and producing an array of TextAnnotations.
3242
+ */
3243
+ collectAllAnnotations(selectorMap, containerWidth, containerHeight, offsetLeft, offsetTop) {
3244
+ return __async(this, null, function* () {
3245
+ const allAnnotations = [];
3246
+ for (const xpaths of Object.values(selectorMap)) {
3247
+ const xpath = xpaths[0];
3248
+ const boundingBoxes = yield this.stagehandPage.page.evaluate(
3249
+ (xp) => window.getElementBoundingBoxes(xp),
3250
+ xpath
3251
+ );
3252
+ for (const box of boundingBoxes) {
3253
+ const localLeft = box.left - offsetLeft;
3254
+ const localTop = box.top - offsetTop;
3255
+ const bottom_left = { x: localLeft, y: localTop + box.height };
3256
+ const bottom_left_normalized = {
3257
+ x: localLeft / containerWidth,
3258
+ y: (localTop + box.height) / containerHeight
3259
+ };
3260
+ if (box.text.trim().length > 0) {
3261
+ allAnnotations.push({
3262
+ text: box.text,
3263
+ bottom_left,
3264
+ bottom_left_normalized,
3265
+ width: box.width,
3266
+ height: box.height
3267
+ });
3268
+ }
3269
+ }
3270
+ }
3271
+ return allAnnotations;
3272
+ });
3273
+ }
3200
3274
  };
3201
3275
 
3202
3276
  // lib/a11y/utils.ts
@@ -3834,8 +3908,8 @@ var StagehandPage = class _StagehandPage {
3834
3908
  });
3835
3909
  }
3836
3910
  if (prop === "extract") {
3837
- return (options) => __async(this, null, function* () {
3838
- return this.extract(options);
3911
+ return (instructionOrOptions) => __async(this, null, function* () {
3912
+ return this.extract(instructionOrOptions);
3839
3913
  });
3840
3914
  }
3841
3915
  if (prop === "observe") {
@@ -4113,8 +4187,14 @@ var StagehandPage = class _StagehandPage {
4113
4187
  modelName,
4114
4188
  modelClientOptions,
4115
4189
  domSettleTimeoutMs,
4116
- useTextExtract
4190
+ useTextExtract,
4191
+ selector
4117
4192
  } = options;
4193
+ if (selector && useTextExtract !== true) {
4194
+ throw new Error(
4195
+ "NotImplementedError: Passing an xpath into extract is only supported when `useTextExtract: true`."
4196
+ );
4197
+ }
4118
4198
  if (this.api) {
4119
4199
  return this.api.extract(options);
4120
4200
  }
@@ -4145,7 +4225,8 @@ var StagehandPage = class _StagehandPage {
4145
4225
  llmClient,
4146
4226
  requestId,
4147
4227
  domSettleTimeoutMs,
4148
- useTextExtract
4228
+ useTextExtract,
4229
+ selector
4149
4230
  }).catch((e) => {
4150
4231
  this.stagehand.log({
4151
4232
  category: "extract",
@@ -4470,7 +4551,7 @@ var StagehandAPI = class {
4470
4551
  };
4471
4552
 
4472
4553
  // lib/dom/build/scriptContent.ts
4473
- var scriptContent = '(() => {\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 // lib/dom/utils.ts\n async function waitForDomSettle() {\n return new Promise((resolve) => {\n const createTimeout = () => {\n return setTimeout(() => {\n resolve();\n }, 2e3);\n };\n let timeout = createTimeout();\n const observer = new MutationObserver(() => {\n clearTimeout(timeout);\n timeout = createTimeout();\n });\n observer.observe(window.document.body, { childList: true, subtree: true });\n });\n }\n window.waitForDomSettle = waitForDomSettle;\n function calculateViewportHeight() {\n return Math.ceil(window.innerHeight * 0.75);\n }\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 Error("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\n // lib/dom/GlobalPageContainer.ts\n var GlobalPageContainer = class {\n getViewportHeight() {\n return calculateViewportHeight();\n }\n getScrollHeight() {\n return document.documentElement.scrollHeight;\n }\n async scrollTo(offset) {\n await new Promise((resolve) => setTimeout(resolve, 1500));\n window.scrollTo({ top: offset, left: 0, behavior: "smooth" });\n await this.waitForScrollEnd();\n }\n async waitForScrollEnd() {\n return new Promise((resolve) => {\n let scrollEndTimer;\n const handleScroll = () => {\n clearTimeout(scrollEndTimer);\n scrollEndTimer = window.setTimeout(() => {\n window.removeEventListener("scroll", handleScroll);\n resolve();\n }, 100);\n };\n window.addEventListener("scroll", handleScroll, { passive: true });\n handleScroll();\n });\n }\n };\n\n // lib/dom/ElementContainer.ts\n var ElementContainer = class {\n constructor(el) {\n this.el = el;\n }\n getViewportHeight() {\n return this.el.clientHeight;\n }\n getScrollHeight() {\n return this.el.scrollHeight;\n }\n async scrollTo(offset) {\n await new Promise((resolve) => setTimeout(resolve, 1500));\n this.el.scrollTo({ top: offset, left: 0, behavior: "smooth" });\n await this.waitForScrollEnd();\n }\n async waitForScrollEnd() {\n return new Promise((resolve) => {\n let scrollEndTimer;\n const handleScroll = () => {\n clearTimeout(scrollEndTimer);\n scrollEndTimer = window.setTimeout(() => {\n this.el.removeEventListener("scroll", handleScroll);\n resolve();\n }, 100);\n };\n this.el.addEventListener("scroll", handleScroll, { passive: true });\n handleScroll();\n });\n }\n };\n\n // lib/dom/containerFactory.ts\n function createStagehandContainer(obj) {\n if (obj instanceof Window) {\n return new GlobalPageContainer();\n } else {\n return new ElementContainer(obj);\n }\n }\n\n // lib/dom/process.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 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 async function processDom(chunksSeen) {\n const { chunk, chunksArray } = await pickChunk(chunksSeen);\n const container = createStagehandContainer(window);\n const { outputString, selectorMap } = await processElements(\n chunk,\n true,\n 0,\n container\n );\n console.log(\n `Stagehand (Browser Process): Extracted dom elements:\n${outputString}`\n );\n return {\n outputString,\n selectorMap,\n chunk,\n chunks: chunksArray\n };\n }\n async function processAllOfDom() {\n console.log("Stagehand (Browser Process): Processing all of DOM");\n const mainScrollableElements = getScrollableElements(1);\n const mainScrollable = mainScrollableElements[0];\n const container = mainScrollable === document.documentElement ? createStagehandContainer(window) : createStagehandContainer(mainScrollable);\n const viewportHeight = container.getViewportHeight();\n const documentHeight = container.getScrollHeight();\n const totalChunks = Math.ceil(documentHeight / viewportHeight);\n let index = 0;\n const results = [];\n for (let chunk = 0; chunk < totalChunks; chunk++) {\n const result = await processElements(chunk, true, index, container);\n results.push(result);\n index += Object.keys(result.selectorMap).length;\n }\n await container.scrollTo(0);\n const allOutputString = results.map((result) => result.outputString).join("");\n const allSelectorMap = results.reduce(\n (acc, result) => ({ ...acc, ...result.selectorMap }),\n {}\n );\n console.log(\n `Stagehand (Browser Process): All dom elements: ${allOutputString}`\n );\n return {\n outputString: allOutputString,\n selectorMap: allSelectorMap\n };\n }\n var xpathCache = /* @__PURE__ */ new Map();\n async function processElements(chunk, scrollToChunk = true, indexOffset = 0, container) {\n console.time("processElements:total");\n const stagehandContainer = container ?? createStagehandContainer(window);\n const viewportHeight = stagehandContainer.getViewportHeight();\n const totalScrollHeight = stagehandContainer.getScrollHeight();\n const chunkHeight = viewportHeight * chunk;\n const maxScrollTop = totalScrollHeight - viewportHeight;\n const offsetTop = Math.min(chunkHeight, maxScrollTop);\n if (scrollToChunk) {\n console.time("processElements:scroll");\n await stagehandContainer.scrollTo(offsetTop);\n console.timeEnd("processElements:scroll");\n }\n console.log("Stagehand (Browser Process): Generating candidate elements");\n console.time("processElements:findCandidates");\n const DOMQueue = [...document.body.childNodes];\n const candidateElements = [];\n while (DOMQueue.length > 0) {\n const element = DOMQueue.pop();\n let shouldAddElement = false;\n if (element && isElementNode(element)) {\n const childrenCount = element.childNodes.length;\n for (let i = childrenCount - 1; i >= 0; i--) {\n const child = element.childNodes[i];\n DOMQueue.push(child);\n }\n if (isInteractiveElement(element)) {\n if (isActive(element) && isVisible(element)) {\n shouldAddElement = true;\n }\n }\n if (isLeafElement(element)) {\n if (isActive(element) && isVisible(element)) {\n shouldAddElement = true;\n }\n }\n }\n if (element && isTextNode(element) && isTextVisible(element)) {\n shouldAddElement = true;\n }\n if (shouldAddElement) {\n candidateElements.push(element);\n }\n }\n console.timeEnd("processElements:findCandidates");\n const selectorMap = {};\n let outputString = "";\n console.log(\n `Stagehand (Browser Process): Processing candidate elements: ${candidateElements.length}`\n );\n console.time("processElements:processCandidates");\n console.time("processElements:generateXPaths");\n const xpathLists = await Promise.all(\n candidateElements.map(async (element) => {\n if (xpathCache.has(element)) {\n return xpathCache.get(element);\n }\n const xpaths = await generateXPathsForElement(element);\n xpathCache.set(element, xpaths);\n return xpaths;\n })\n );\n console.timeEnd("processElements:generateXPaths");\n candidateElements.forEach((element, index) => {\n const xpaths = xpathLists[index];\n let elementOutput = "";\n if (isTextNode(element)) {\n const textContent = element.textContent?.trim();\n if (textContent) {\n elementOutput += `${index + indexOffset}:${textContent}\n`;\n }\n } else if (isElementNode(element)) {\n const tagName = element.tagName.toLowerCase();\n const attributes = collectEssentialAttributes(element);\n const openingTag = `<${tagName}${attributes ? " " + attributes : ""}>`;\n const closingTag = `</${tagName}>`;\n const textContent = element.textContent?.trim() || "";\n elementOutput += `${index + indexOffset}:${openingTag}${textContent}${closingTag}\n`;\n }\n outputString += elementOutput;\n selectorMap[index + indexOffset] = xpaths;\n });\n console.timeEnd("processElements:processCandidates");\n console.timeEnd("processElements:total");\n return {\n outputString,\n selectorMap\n };\n }\n function collectEssentialAttributes(element) {\n const essentialAttributes = [\n "id",\n "class",\n "href",\n "src",\n "aria-label",\n "aria-name",\n "aria-role",\n "aria-description",\n "aria-expanded",\n "aria-haspopup",\n "type",\n "value"\n ];\n const attrs = essentialAttributes.map((attr) => {\n const value = element.getAttribute(attr);\n return value ? `${attr}="${value}"` : "";\n }).filter((attr) => attr !== "");\n Array.from(element.attributes).forEach((attr) => {\n if (attr.name.startsWith("data-")) {\n attrs.push(`${attr.name}="${attr.value}"`);\n }\n });\n return attrs.join(" ");\n }\n function storeDOM() {\n const originalDOM = document.body.cloneNode(true);\n console.log("DOM state stored.");\n return originalDOM.outerHTML;\n }\n function restoreDOM(storedDOM) {\n console.log("Restoring DOM");\n if (storedDOM) {\n document.body.innerHTML = storedDOM;\n } else {\n console.error("No DOM state was provided.");\n }\n }\n function createTextBoundingBoxes() {\n const style = document.createElement("style");\n document.head.appendChild(style);\n if (style.sheet) {\n style.sheet.insertRule(\n `\n .stagehand-highlighted-word, .stagehand-space {\n border: 0px solid orange;\n display: inline-block !important;\n visibility: visible;\n }\n `,\n 0\n );\n style.sheet.insertRule(\n `\n code .stagehand-highlighted-word, code .stagehand-space,\n pre .stagehand-highlighted-word, pre .stagehand-space {\n white-space: pre-wrap;\n display: inline !important;\n }\n `,\n 1\n );\n }\n function applyHighlighting(root) {\n root.querySelectorAll("body *").forEach((element) => {\n if (element.closest(".stagehand-nav, .stagehand-marker")) {\n return;\n }\n if (["SCRIPT", "STYLE", "IFRAME", "INPUT"].includes(element.tagName)) {\n return;\n }\n const childNodes = Array.from(element.childNodes);\n childNodes.forEach((node) => {\n if (node.nodeType === 3 && node.textContent?.trim().length > 0) {\n const textContent = node.textContent.replace(/\\u00A0/g, " ");\n const tokens = textContent.split(/(\\s+)/g);\n const fragment = document.createDocumentFragment();\n const parentIsCode = element.tagName === "CODE";\n tokens.forEach((token) => {\n const span = document.createElement("span");\n span.textContent = token;\n if (parentIsCode) {\n span.style.whiteSpace = "pre-wrap";\n span.style.display = "inline";\n }\n span.className = token.trim().length === 0 ? "stagehand-space" : "stagehand-highlighted-word";\n fragment.appendChild(span);\n });\n if (fragment.childNodes.length > 0 && node.parentNode) {\n element.insertBefore(fragment, node);\n node.remove();\n }\n }\n });\n });\n }\n applyHighlighting(document);\n document.querySelectorAll("iframe").forEach((iframe) => {\n try {\n iframe.contentWindow?.postMessage({ action: "highlight" }, "*");\n } catch (error) {\n console.error("Error accessing iframe content: ", error);\n }\n });\n }\n function getElementBoundingBoxes(xpath) {\n const element = document.evaluate(\n xpath,\n document,\n null,\n XPathResult.FIRST_ORDERED_NODE_TYPE,\n null\n ).singleNodeValue;\n if (!element) return [];\n const isValidText = (text) => text && text.trim().length > 0;\n let dropDownElem = element.querySelector("option[selected]");\n if (!dropDownElem) {\n dropDownElem = element.querySelector("option");\n }\n if (dropDownElem) {\n const elemText = dropDownElem.textContent || "";\n if (isValidText(elemText)) {\n const parentRect = element.getBoundingClientRect();\n return [\n {\n text: elemText.trim(),\n top: parentRect.top + window.scrollY,\n left: parentRect.left + window.scrollX,\n width: parentRect.width,\n height: parentRect.height\n }\n ];\n } else {\n return [];\n }\n }\n let placeholderText = "";\n if ((element.tagName.toLowerCase() === "input" || element.tagName.toLowerCase() === "textarea") && element.placeholder) {\n placeholderText = element.placeholder;\n } else if (element.tagName.toLowerCase() === "a") {\n placeholderText = "";\n } else if (element.tagName.toLowerCase() === "img") {\n placeholderText = element.alt || "";\n }\n const words = element.querySelectorAll(\n ".stagehand-highlighted-word"\n );\n const boundingBoxes = Array.from(words).map((word) => {\n const rect = word.getBoundingClientRect();\n return {\n text: word.innerText || "",\n top: rect.top + window.scrollY,\n left: rect.left + window.scrollX,\n width: rect.width,\n height: rect.height * 0.75\n };\n }).filter(\n (box) => box.width > 0 && box.height > 0 && box.top >= 0 && box.left >= 0 && isValidText(box.text)\n );\n if (boundingBoxes.length === 0) {\n const elementRect = element.getBoundingClientRect();\n return [\n {\n text: placeholderText,\n top: elementRect.top + window.scrollY,\n left: elementRect.left + window.scrollX,\n width: elementRect.width,\n height: elementRect.height * 0.75\n }\n ];\n }\n return boundingBoxes;\n }\n window.processDom = processDom;\n window.processAllOfDom = processAllOfDom;\n window.processElements = processElements;\n window.storeDOM = storeDOM;\n window.restoreDOM = restoreDOM;\n window.createTextBoundingBoxes = createTextBoundingBoxes;\n window.getElementBoundingBoxes = getElementBoundingBoxes;\n window.createStagehandContainer = createStagehandContainer;\n window.getScrollableElementXpaths = getScrollableElementXpaths;\n var leafElementDenyList = ["SVG", "IFRAME", "SCRIPT", "STYLE", "LINK"];\n var interactiveElementTypes = [\n "A",\n "BUTTON",\n "DETAILS",\n "EMBED",\n "INPUT",\n "LABEL",\n "MENU",\n "MENUITEM",\n "OBJECT",\n "SELECT",\n "TEXTAREA",\n "SUMMARY"\n ];\n var interactiveRoles = [\n "button",\n "menu",\n "menuitem",\n "link",\n "checkbox",\n "radio",\n "slider",\n "tab",\n "tabpanel",\n "textbox",\n "combobox",\n "grid",\n "listbox",\n "option",\n "progressbar",\n "scrollbar",\n "searchbox",\n "switch",\n "tree",\n "treeitem",\n "spinbutton",\n "tooltip"\n ];\n var interactiveAriaRoles = ["menu", "menuitem", "button"];\n var isVisible = (element) => {\n const rect = element.getBoundingClientRect();\n if (rect.width === 0 || rect.height === 0 || rect.top < 0 || rect.top > window.innerHeight) {\n return false;\n }\n if (!isTopElement(element, rect)) {\n return false;\n }\n const visible = element.checkVisibility({\n checkOpacity: true,\n checkVisibilityCSS: true\n });\n return visible;\n };\n var isTextVisible = (element) => {\n const range = document.createRange();\n range.selectNodeContents(element);\n const rect = range.getBoundingClientRect();\n if (rect.width === 0 || rect.height === 0 || rect.top < 0 || rect.top > window.innerHeight) {\n return false;\n }\n const parent = element.parentElement;\n if (!parent) {\n return false;\n }\n const visible = parent.checkVisibility({\n checkOpacity: true,\n checkVisibilityCSS: true\n });\n return visible;\n };\n function isTopElement(elem, rect) {\n const points = [\n { x: rect.left + rect.width * 0.25, y: rect.top + rect.height * 0.25 },\n { x: rect.left + rect.width * 0.75, y: rect.top + rect.height * 0.25 },\n { x: rect.left + rect.width * 0.25, y: rect.top + rect.height * 0.75 },\n { x: rect.left + rect.width * 0.75, y: rect.top + rect.height * 0.75 },\n { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 }\n ];\n return points.some((point) => {\n const topEl = document.elementFromPoint(point.x, point.y);\n let current = topEl;\n while (current && current !== document.body) {\n if (current.isSameNode(elem)) {\n return true;\n }\n current = current.parentElement;\n }\n return false;\n });\n }\n var isActive = (element) => {\n if (element.hasAttribute("disabled") || element.hasAttribute("hidden") || element.getAttribute("aria-disabled") === "true") {\n return false;\n }\n return true;\n };\n var isInteractiveElement = (element) => {\n const elementType = element.tagName;\n const elementRole = element.getAttribute("role");\n const elementAriaRole = element.getAttribute("aria-role");\n return elementType && interactiveElementTypes.includes(elementType) || elementRole && interactiveRoles.includes(elementRole) || elementAriaRole && interactiveAriaRoles.includes(elementAriaRole);\n };\n var isLeafElement = (element) => {\n if (element.textContent === "") {\n return false;\n }\n if (element.childNodes.length === 0) {\n return !leafElementDenyList.includes(element.tagName);\n }\n if (element.childNodes.length === 1 && isTextNode(element.childNodes[0])) {\n return true;\n }\n return false;\n };\n async function pickChunk(chunksSeen) {\n const viewportHeight = calculateViewportHeight();\n const documentHeight = document.documentElement.scrollHeight;\n const chunks = Math.ceil(documentHeight / viewportHeight);\n const chunksArray = Array.from({ length: chunks }, (_, i) => i);\n const chunksRemaining = chunksArray.filter((chunk2) => {\n return !chunksSeen.includes(chunk2);\n });\n const currentScrollPosition = window.scrollY;\n const closestChunk = chunksRemaining.reduce((closest, current) => {\n const currentChunkTop = viewportHeight * current;\n const closestChunkTop = viewportHeight * closest;\n return Math.abs(currentScrollPosition - currentChunkTop) < Math.abs(currentScrollPosition - closestChunkTop) ? current : closest;\n }, chunksRemaining[0]);\n const chunk = closestChunk;\n if (chunk === void 0) {\n throw new Error(`No chunks remaining to check: ${chunksRemaining}`);\n }\n return {\n chunk,\n chunksArray\n };\n }\n\n // lib/dom/debug.ts\n async function debugDom() {\n window.chunkNumber = 0;\n const { selectorMap: multiSelectorMap } = await window.processElements(\n window.chunkNumber\n );\n const selectorMap = multiSelectorMapToSelectorMap(multiSelectorMap);\n drawChunk(selectorMap);\n }\n function multiSelectorMapToSelectorMap(multiSelectorMap) {\n return Object.fromEntries(\n Object.entries(multiSelectorMap).map(([key, selectors]) => [\n Number(key),\n selectors[0]\n ])\n );\n }\n function drawChunk(selectorMap) {\n if (!window.showChunks) return;\n cleanupMarkers();\n Object.values(selectorMap).forEach((selector) => {\n const element = document.evaluate(\n selector,\n document,\n null,\n XPathResult.FIRST_ORDERED_NODE_TYPE,\n null\n ).singleNodeValue;\n if (element) {\n let rect;\n if (element.nodeType === Node.ELEMENT_NODE) {\n rect = element.getBoundingClientRect();\n } else {\n const range = document.createRange();\n range.selectNodeContents(element);\n rect = range.getBoundingClientRect();\n }\n const color = "grey";\n const overlay = document.createElement("div");\n overlay.style.position = "absolute";\n overlay.style.left = `${rect.left + window.scrollX}px`;\n overlay.style.top = `${rect.top + window.scrollY}px`;\n overlay.style.padding = "2px";\n overlay.style.width = `${rect.width}px`;\n overlay.style.height = `${rect.height}px`;\n overlay.style.backgroundColor = color;\n overlay.className = "stagehand-marker";\n overlay.style.opacity = "0.3";\n overlay.style.zIndex = "1000000000";\n overlay.style.border = "1px solid";\n overlay.style.pointerEvents = "none";\n document.body.appendChild(overlay);\n }\n });\n }\n async function cleanupDebug() {\n cleanupMarkers();\n }\n function cleanupMarkers() {\n const markers = document.querySelectorAll(".stagehand-marker");\n markers.forEach((marker) => {\n marker.remove();\n });\n }\n window.debugDom = debugDom;\n window.cleanupDebug = cleanupDebug;\n})();\n';
4554
+ 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 var leafElementDenyList = ["SVG", "IFRAME", "SCRIPT", "STYLE", "LINK"];\n var interactiveElementTypes = [\n "A",\n "BUTTON",\n "DETAILS",\n "EMBED",\n "INPUT",\n "LABEL",\n "MENU",\n "MENUITEM",\n "OBJECT",\n "SELECT",\n "TEXTAREA",\n "SUMMARY"\n ];\n var interactiveRoles = [\n "button",\n "menu",\n "menuitem",\n "link",\n "checkbox",\n "radio",\n "slider",\n "tab",\n "tabpanel",\n "textbox",\n "combobox",\n "grid",\n "listbox",\n "option",\n "progressbar",\n "scrollbar",\n "searchbox",\n "switch",\n "tree",\n "treeitem",\n "spinbutton",\n "tooltip"\n ];\n var interactiveAriaRoles = ["menu", "menuitem", "button"];\n var isVisible = (element) => {\n const rect = element.getBoundingClientRect();\n if (rect.width === 0 || rect.height === 0 || rect.top < 0 || rect.top > window.innerHeight) {\n return false;\n }\n if (!isTopElement(element, rect)) {\n return false;\n }\n const visible = element.checkVisibility({\n checkOpacity: true,\n checkVisibilityCSS: true\n });\n return visible;\n };\n var isTextVisible = (element) => {\n const range = document.createRange();\n range.selectNodeContents(element);\n const rect = range.getBoundingClientRect();\n if (rect.width === 0 || rect.height === 0 || rect.top < 0 || rect.top > window.innerHeight) {\n return false;\n }\n const parent = element.parentElement;\n if (!parent) {\n return false;\n }\n const visible = parent.checkVisibility({\n checkOpacity: true,\n checkVisibilityCSS: true\n });\n return visible;\n };\n function isTopElement(elem, rect) {\n const points = [\n { x: rect.left + rect.width * 0.25, y: rect.top + rect.height * 0.25 },\n { x: rect.left + rect.width * 0.75, y: rect.top + rect.height * 0.25 },\n { x: rect.left + rect.width * 0.25, y: rect.top + rect.height * 0.75 },\n { x: rect.left + rect.width * 0.75, y: rect.top + rect.height * 0.75 },\n { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 }\n ];\n return points.some((point) => {\n const topEl = document.elementFromPoint(point.x, point.y);\n let current = topEl;\n while (current && current !== document.body) {\n if (current.isSameNode(elem)) {\n return true;\n }\n current = current.parentElement;\n }\n return false;\n });\n }\n var isActive = (element) => {\n if (element.hasAttribute("disabled") || element.hasAttribute("hidden") || element.getAttribute("aria-disabled") === "true") {\n return false;\n }\n return true;\n };\n var isInteractiveElement = (element) => {\n const elementType = element.tagName;\n const elementRole = element.getAttribute("role");\n const elementAriaRole = element.getAttribute("aria-role");\n return elementType && interactiveElementTypes.includes(elementType) || elementRole && interactiveRoles.includes(elementRole) || elementAriaRole && interactiveAriaRoles.includes(elementAriaRole);\n };\n var isLeafElement = (element) => {\n if (element.textContent === "") {\n return false;\n }\n if (element.childNodes.length === 0) {\n return !leafElementDenyList.includes(element.tagName);\n }\n if (element.childNodes.length === 1 && isTextNode(element.childNodes[0])) {\n return true;\n }\n return false;\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 // lib/dom/utils.ts\n async function waitForDomSettle() {\n return new Promise((resolve) => {\n const createTimeout = () => {\n return setTimeout(() => {\n resolve();\n }, 2e3);\n };\n let timeout = createTimeout();\n const observer = new MutationObserver(() => {\n clearTimeout(timeout);\n timeout = createTimeout();\n });\n observer.observe(window.document.body, { childList: true, subtree: true });\n });\n }\n window.waitForDomSettle = waitForDomSettle;\n function calculateViewportHeight() {\n return Math.ceil(window.innerHeight * 0.75);\n }\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 Error("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\n // lib/dom/candidateCollector.ts\n var xpathCache = /* @__PURE__ */ new Map();\n async function collectCandidateElements(candidateContainerRoot, indexOffset = 0) {\n const DOMQueue = [...candidateContainerRoot.childNodes];\n const candidateElements = [];\n while (DOMQueue.length > 0) {\n const node = DOMQueue.pop();\n let shouldAdd = false;\n if (node && isElementNode(node)) {\n for (let i = node.childNodes.length - 1; i >= 0; i--) {\n DOMQueue.push(node.childNodes[i]);\n }\n if (isInteractiveElement(node)) {\n if (isActive(node) && isVisible(node)) {\n shouldAdd = true;\n }\n }\n if (isLeafElement(node)) {\n if (isActive(node) && isVisible(node)) {\n shouldAdd = true;\n }\n }\n }\n if (node && isTextNode(node) && isTextVisible(node)) {\n shouldAdd = true;\n }\n if (shouldAdd) {\n candidateElements.push(node);\n }\n }\n const selectorMap = {};\n let outputString = "";\n const xpathLists = await Promise.all(\n candidateElements.map((elem) => {\n if (xpathCache.has(elem)) {\n return Promise.resolve(xpathCache.get(elem));\n }\n return generateXPathsForElement(elem).then((xpaths) => {\n xpathCache.set(elem, xpaths);\n return xpaths;\n });\n })\n );\n candidateElements.forEach((elem, idx) => {\n const xpaths = xpathLists[idx];\n let elemOutput = "";\n if (isTextNode(elem)) {\n const textContent = elem.textContent?.trim();\n if (textContent) {\n elemOutput += `${idx + indexOffset}:${textContent}\n`;\n }\n } else if (isElementNode(elem)) {\n const tagName = elem.tagName.toLowerCase();\n const attributes = collectEssentialAttributes(elem);\n const opening = `<${tagName}${attributes ? " " + attributes : ""}>`;\n const closing = `</${tagName}>`;\n const textContent = elem.textContent?.trim() || "";\n elemOutput += `${idx + indexOffset}:${opening}${textContent}${closing}\n`;\n }\n outputString += elemOutput;\n selectorMap[idx + indexOffset] = xpaths;\n });\n return { outputString, selectorMap };\n }\n function collectEssentialAttributes(element) {\n const essentialAttributes = [\n "id",\n "class",\n "href",\n "src",\n "aria-label",\n "aria-name",\n "aria-role",\n "aria-description",\n "aria-expanded",\n "aria-haspopup",\n "type",\n "value"\n ];\n const attrs = essentialAttributes.map((attr) => {\n const value = element.getAttribute(attr);\n return value ? `${attr}="${value}"` : "";\n }).filter((attr) => attr !== "");\n Array.from(element.attributes).forEach((attr) => {\n if (attr.name.startsWith("data-")) {\n attrs.push(`${attr.name}="${attr.value}"`);\n }\n });\n return attrs.join(" ");\n }\n\n // lib/dom/StagehandContainer.ts\n var StagehandContainer = class {\n /**\n * Collects multiple "DOM chunks" by scrolling through the container\n * in increments from `startOffset` to `endOffset`. At each scroll\n * position, the function extracts a snapshot of "candidate elements"\n * using `collectCandidateElements`.\n *\n * Each chunk represents a subset of the DOM at a particular\n * vertical scroll offset, including:\n *\n * - `startOffset` & `endOffset`: The vertical scroll bounds for this chunk.\n * - `outputString`: A serialized representation of extracted DOM text.\n * - `selectorMap`: A mapping of temporary indices to the actual element(s)\n * that were collected in this chunk, useful for further processing.\n *\n * @param startOffset - The initial scroll offset from which to begin collecting.\n * @param endOffset - The maximum scroll offset to collect up to.\n * @param chunkSize - The vertical increment to move between each chunk.\n * @param scrollTo - Whether we should scroll to the chunk\n * @param scrollBackToTop - Whether to scroll the container back to the top once finished.\n * @param candidateContainer - Optionally, a specific container element within\n * the root for which to collect data. If omitted, uses `this.getRootElement()`.\n *\n * @returns A promise that resolves with an array of `DomChunk` objects.\n *\n * ### How It Works\n *\n * 1. **Scroll Range Calculation**:\n * - Computes `maxOffset` as the maximum offset that can be scrolled\n * (`scrollHeight - viewportHeight`).\n * - Restricts `endOffset` to not exceed `maxOffset`.\n *\n * 2. **Chunk Iteration**:\n * - Loops from `startOffset` to `endOffset` in steps of `chunkSize`.\n * - For each offset `current`, we call `this.scrollTo(current)`\n * to position the container.\n *\n * 3. **Element Collection**:\n * - Invokes `collectCandidateElements` on either `candidateContainer`\n * (if provided) or the result of `this.getRootElement()`.\n * - This returns both an `outputString` (serialized text)\n * and a `selectorMap` of found elements for that section of the DOM.\n *\n * 4. **Chunk Assembly**:\n * - Creates a `DomChunk` object for the current offset range,\n * storing `outputString`, `selectorMap`, and scroll offsets.\n * - Pushes it onto the `chunks` array.\n *\n * 5. **Scroll Reset**:\n * - Once iteration completes, if `scrollBackToTop` is `true`,\n * we scroll back to offset `0`.\n */\n async collectDomChunks(startOffset, endOffset, chunkSize, scrollTo = true, scrollBackToTop = true, candidateContainer) {\n const chunks = [];\n const maxOffset = this.getScrollHeight();\n const finalEnd = Math.min(endOffset, maxOffset);\n let index = 0;\n for (let current = startOffset; current <= finalEnd; current += chunkSize) {\n if (scrollTo) {\n await this.scrollTo(current);\n }\n const rootCandidate = candidateContainer || this.getRootElement();\n const { outputString, selectorMap } = await collectCandidateElements(\n rootCandidate,\n index\n );\n chunks.push({\n startOffset: current,\n endOffset: current + chunkSize,\n outputString,\n selectorMap\n });\n index += Object.keys(selectorMap).length;\n }\n if (scrollBackToTop) {\n await this.scrollTo(0);\n }\n return chunks;\n }\n };\n\n // lib/dom/GlobalPageContainer.ts\n var GlobalPageContainer = class extends StagehandContainer {\n getRootElement() {\n return document.body;\n }\n /**\n * Calculates the viewport height for the entire page, using a helper.\n * The helper returns 75% of the window height, to ensure that we don\'t\n * miss any content that may be behind sticky elements like nav bars.\n *\n * @returns The current height of the global viewport, in pixels.\n */\n getViewportHeight() {\n return calculateViewportHeight();\n }\n getScrollHeight() {\n return document.documentElement.scrollHeight;\n }\n getScrollPosition() {\n return window.scrollY;\n }\n /**\n * Smoothly scrolls the page to the specified vertical offset, and then\n * waits until scrolling has stopped. There is a delay built in to allow\n * for lazy loading and other asynchronous content to load.\n *\n * @param offset - The desired scroll offset from the top of the page.\n * @returns A promise that resolves once scrolling is complete.\n */\n async scrollTo(offset) {\n await new Promise((resolve) => setTimeout(resolve, 1500));\n window.scrollTo({ top: offset, behavior: "smooth" });\n await this.waitForScrollEnd();\n }\n /**\n * Scrolls the page so that a given element is visible, or scrolls to the top\n * if no element is specified. Uses smooth scrolling and waits for it to complete.\n *\n * @param element - The DOM element to bring into view. If omitted, scrolls to top.\n * @returns A promise that resolves once scrolling is complete.\n */\n async scrollIntoView(element) {\n if (!element) {\n window.scrollTo({ top: 0, behavior: "smooth" });\n } else {\n const rect = element.getBoundingClientRect();\n const currentY = window.scrollY || document.documentElement.scrollTop;\n const elementY = currentY + rect.top - window.innerHeight * 0.25;\n window.scrollTo({ top: elementY, behavior: "smooth" });\n }\n await this.waitForScrollEnd();\n }\n /**\n * Internal helper that waits until the global scroll activity has stopped.\n * It listens for scroll events, resetting a short timer every time a scroll\n * occurs, and resolves once there\'s no scroll for ~100ms.\n *\n * @returns A promise that resolves when scrolling has finished.\n */\n async waitForScrollEnd() {\n return new Promise((resolve) => {\n let scrollEndTimer;\n const handleScroll = () => {\n clearTimeout(scrollEndTimer);\n scrollEndTimer = window.setTimeout(() => {\n window.removeEventListener("scroll", handleScroll);\n resolve();\n }, 100);\n };\n window.addEventListener("scroll", handleScroll, { passive: true });\n handleScroll();\n });\n }\n };\n\n // lib/dom/ElementContainer.ts\n var ElementContainer = class extends StagehandContainer {\n /**\n * Creates an instance of `ElementContainer` tied to a specific element.\n * @param el - The scrollable `HTMLElement` that this container controls.\n */\n constructor(el) {\n super();\n this.el = el;\n }\n getRootElement() {\n return this.el;\n }\n /**\n * Retrieves the height of the visible viewport within this element\n * (`el.clientHeight`).\n *\n * @returns The visible (client) height of the element, in pixels.\n */\n getViewportHeight() {\n return this.el.clientHeight;\n }\n getScrollHeight() {\n return this.el.scrollHeight;\n }\n /**\n * Returns the element\'s current vertical scroll offset.\n */\n getScrollPosition() {\n return this.el.scrollTop;\n }\n /**\n * Smoothly scrolls this element to the specified vertical offset, and\n * waits for the scrolling to complete.\n *\n * @param offset - The scroll offset (in pixels) from the top of the element.\n * @returns A promise that resolves once scrolling is finished.\n */\n async scrollTo(offset) {\n this.el.scrollTo({ top: offset, behavior: "smooth" });\n await this.waitForScrollEnd();\n }\n /**\n * Scrolls this element so that the given `element` is visible, or\n * scrolls to the top if none is provided. Smoothly animates the scroll\n * and waits until it finishes.\n *\n * @param element - The child element to bring into view. If omitted, scrolls to top.\n * @returns A promise that resolves once scrolling completes.\n */\n async scrollIntoView(element) {\n if (!element) {\n this.el.scrollTo({ top: 0, behavior: "smooth" });\n } else {\n element.scrollIntoView({ behavior: "smooth", block: "end" });\n }\n await this.waitForScrollEnd();\n }\n /**\n * Internal helper that waits until scrolling in this element has\n * fully stopped. It listens for scroll events on the element,\n * resetting a short timer every time a scroll occurs, and resolves\n * once there\'s no scroll for ~100ms.\n *\n * @returns A promise that resolves when scrolling has finished.\n */\n async waitForScrollEnd() {\n return new Promise((resolve) => {\n let scrollEndTimer;\n const handleScroll = () => {\n clearTimeout(scrollEndTimer);\n scrollEndTimer = window.setTimeout(() => {\n this.el.removeEventListener("scroll", handleScroll);\n resolve();\n }, 100);\n };\n this.el.addEventListener("scroll", handleScroll, { passive: true });\n handleScroll();\n });\n }\n };\n\n // lib/dom/containerFactory.ts\n function createStagehandContainer(obj) {\n if (obj instanceof Window) {\n return new GlobalPageContainer();\n } else {\n return new ElementContainer(obj);\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 function getNearestScrollableParent(el) {\n const allScrollables = getScrollableElements();\n let current = el;\n while (current) {\n if (allScrollables.includes(current)) {\n return current;\n }\n current = current.parentElement;\n }\n return document.documentElement;\n }\n async function processDom(chunksSeen) {\n const { chunk, chunksArray } = await pickChunk(chunksSeen);\n const container = new GlobalPageContainer();\n const chunkSize = container.getViewportHeight();\n const startOffset = chunk * chunkSize;\n const endOffset = startOffset;\n const domChunks = await container.collectDomChunks(\n startOffset,\n endOffset,\n chunkSize,\n true,\n false,\n // scrollBackToTop\n void 0\n // BFS entire doc\n );\n const [domChunk] = domChunks;\n if (!domChunk) {\n return {\n outputString: "",\n selectorMap: {},\n chunk,\n chunks: chunksArray\n };\n }\n console.log("Extracted DOM chunk:\\n", domChunk.outputString);\n return {\n outputString: domChunk.outputString,\n selectorMap: domChunk.selectorMap,\n chunk,\n chunks: chunksArray\n };\n }\n async function processAllOfDom(xpath) {\n let candidateElementContainer = null;\n let scrollTarget;\n if (xpath) {\n const node = getNodeFromXpath(xpath);\n if (node) {\n candidateElementContainer = node;\n console.log(`Found element via XPath: ${xpath}`);\n const scrollableElem = getNearestScrollableParent(\n candidateElementContainer\n );\n if (scrollableElem === document.documentElement) {\n scrollTarget = new GlobalPageContainer();\n } else {\n scrollTarget = new ElementContainer(scrollableElem);\n }\n await scrollTarget.scrollIntoView(candidateElementContainer);\n const startOffset2 = scrollTarget.getScrollPosition();\n const scrollTargetHeight = scrollTarget.getViewportHeight();\n const rect = candidateElementContainer.getBoundingClientRect();\n if (rect.height <= scrollTargetHeight) {\n console.log(\n "Element is smaller/equal to container\\u2019s viewport. Doing single chunk."\n );\n const domChunks2 = await scrollTarget.collectDomChunks(\n startOffset2,\n // startOffset\n startOffset2,\n // endOffset => same as start => 1 chunk\n 1,\n // chunkSize=1 => doesn\'t matter, because start==end means exactly 1 iteration\n true,\n true,\n candidateElementContainer\n );\n const singleChunkOutput = combineChunks(domChunks2);\n console.log(\n "Final output (single-chunk):",\n singleChunkOutput.outputString\n );\n return singleChunkOutput;\n }\n console.log("Element is bigger. Doing multi-chunk approach.");\n } else {\n console.warn(`XPath not found: ${xpath}. Using entire doc.`);\n }\n } else {\n const scrollableElems = getScrollableElements(1);\n const mainScrollable = scrollableElems[0];\n scrollTarget = mainScrollable === document.documentElement ? createStagehandContainer(window) : createStagehandContainer(mainScrollable);\n }\n const startOffset = scrollTarget.getScrollPosition();\n const viewportHeight = scrollTarget.getViewportHeight();\n const maxScroll = candidateElementContainer ? startOffset + candidateElementContainer.getBoundingClientRect().height : scrollTarget.getScrollHeight();\n const chunkSize = viewportHeight;\n console.log("processAllOfDom chunk-based from", startOffset, "to", maxScroll);\n const domChunks = await scrollTarget.collectDomChunks(\n startOffset,\n maxScroll,\n chunkSize,\n true,\n true,\n candidateElementContainer ?? void 0\n );\n const finalOutput = combineChunks(domChunks);\n console.log(\n "All DOM elements combined (chunk-based):",\n finalOutput.outputString\n );\n return finalOutput;\n }\n function combineChunks(domChunks) {\n const outputString = domChunks.map((c) => c.outputString).join("");\n let finalSelectorMap = {};\n domChunks.forEach((c) => {\n finalSelectorMap = { ...finalSelectorMap, ...c.selectorMap };\n });\n return { outputString, selectorMap: finalSelectorMap };\n }\n function storeDOM(xpath) {\n if (!xpath) {\n const originalDOM = document.body.cloneNode(true);\n console.log("DOM state stored (root).");\n return originalDOM.outerHTML;\n } else {\n const node = getNodeFromXpath(xpath);\n if (!node) {\n console.error(\n `storeDOM: No element found for xpath: ${xpath}. Returning empty string.`\n );\n return "";\n }\n console.log(`DOM state stored (element at xpath: ${xpath}).`);\n return node.outerHTML;\n }\n }\n function restoreDOM(storedDOM, xpath) {\n console.log("Restoring DOM...");\n if (!storedDOM) {\n console.error("No DOM state was provided.");\n return;\n }\n if (!xpath) {\n document.body.innerHTML = storedDOM;\n console.log("DOM restored (root).");\n } else {\n const node = getNodeFromXpath(xpath);\n if (!node) {\n console.error(\n `restoreDOM: No element found for xpath: ${xpath}. Cannot restore.`\n );\n return;\n }\n node.outerHTML = storedDOM;\n console.log(`DOM restored (element at xpath: ${xpath}).`);\n }\n }\n function createTextBoundingBoxes(xpath) {\n const style = document.createElement("style");\n document.head.appendChild(style);\n if (style.sheet) {\n style.sheet.insertRule(\n `\n .stagehand-highlighted-word, .stagehand-space {\n border: 0px solid orange;\n display: inline-block !important;\n visibility: visible;\n }\n `,\n 0\n );\n style.sheet.insertRule(\n `\n code .stagehand-highlighted-word, code .stagehand-space,\n pre .stagehand-highlighted-word, pre .stagehand-space {\n white-space: pre-wrap;\n display: inline !important;\n }\n `,\n 1\n );\n }\n function applyHighlighting(root) {\n const containerSelector = root instanceof Document ? "body *" : "*";\n root.querySelectorAll(containerSelector).forEach((element) => {\n if (element.closest && element.closest(".stagehand-nav, .stagehand-marker")) {\n return;\n }\n if (["SCRIPT", "STYLE", "IFRAME", "INPUT"].includes(element.tagName)) {\n return;\n }\n const childNodes = Array.from(element.childNodes);\n childNodes.forEach((node) => {\n if (node.nodeType === 3 && node.textContent?.trim().length > 0) {\n const textContent = node.textContent.replace(/\\u00A0/g, " ");\n const tokens = textContent.split(/(\\s+)/g);\n const fragment = document.createDocumentFragment();\n const parentIsCode = element.tagName === "CODE";\n tokens.forEach((token) => {\n const span = document.createElement("span");\n span.textContent = token;\n if (parentIsCode) {\n span.style.whiteSpace = "pre-wrap";\n span.style.display = "inline";\n }\n span.className = token.trim().length === 0 ? "stagehand-space" : "stagehand-highlighted-word";\n fragment.appendChild(span);\n });\n if (fragment.childNodes.length > 0 && node.parentNode) {\n element.insertBefore(fragment, node);\n node.remove();\n }\n }\n });\n });\n }\n if (!xpath) {\n applyHighlighting(document);\n document.querySelectorAll("iframe").forEach((iframe) => {\n try {\n iframe.contentWindow?.postMessage({ action: "highlight" }, "*");\n } catch (error) {\n console.error("Error accessing iframe content: ", error);\n }\n });\n } else {\n const node = getNodeFromXpath(xpath);\n if (!node) {\n console.warn(\n `createTextBoundingBoxes: No element found for xpath "${xpath}".`\n );\n return;\n }\n applyHighlighting(node);\n }\n }\n function getElementBoundingBoxes(xpath) {\n const element = getNodeFromXpath(xpath);\n if (!element) return [];\n const isValidText = (text) => text && text.trim().length > 0;\n let dropDownElem = element.querySelector("option[selected]");\n if (!dropDownElem) {\n dropDownElem = element.querySelector("option");\n }\n if (dropDownElem) {\n const elemText = dropDownElem.textContent || "";\n if (isValidText(elemText)) {\n const parentRect = element.getBoundingClientRect();\n return [\n {\n text: elemText.trim(),\n top: parentRect.top + window.scrollY,\n left: parentRect.left + window.scrollX,\n width: parentRect.width,\n height: parentRect.height\n }\n ];\n } else {\n return [];\n }\n }\n let placeholderText = "";\n if ((element.tagName.toLowerCase() === "input" || element.tagName.toLowerCase() === "textarea") && element.placeholder) {\n placeholderText = element.placeholder;\n } else if (element.tagName.toLowerCase() === "a") {\n placeholderText = "";\n } else if (element.tagName.toLowerCase() === "img") {\n placeholderText = element.alt || "";\n }\n const words = element.querySelectorAll(\n ".stagehand-highlighted-word"\n );\n const boundingBoxes = Array.from(words).map((word) => {\n const rect = word.getBoundingClientRect();\n return {\n text: word.innerText || "",\n top: rect.top + window.scrollY,\n left: rect.left + window.scrollX,\n width: rect.width,\n height: rect.height * 0.75\n };\n }).filter(\n (box) => box.width > 0 && box.height > 0 && box.top >= 0 && box.left >= 0 && isValidText(box.text)\n );\n if (boundingBoxes.length === 0) {\n const elementRect = element.getBoundingClientRect();\n return [\n {\n text: placeholderText,\n top: elementRect.top + window.scrollY,\n left: elementRect.left + window.scrollX,\n width: elementRect.width,\n height: elementRect.height * 0.75\n }\n ];\n }\n return boundingBoxes;\n }\n window.processDom = processDom;\n window.processAllOfDom = processAllOfDom;\n window.storeDOM = storeDOM;\n window.restoreDOM = restoreDOM;\n window.createTextBoundingBoxes = createTextBoundingBoxes;\n window.getElementBoundingBoxes = getElementBoundingBoxes;\n window.createStagehandContainer = createStagehandContainer;\n window.getScrollableElementXpaths = getScrollableElementXpaths;\n window.getNodeFromXpath = getNodeFromXpath;\n async function pickChunk(chunksSeen) {\n const viewportHeight = calculateViewportHeight();\n const documentHeight = document.documentElement.scrollHeight;\n const chunks = Math.ceil(documentHeight / viewportHeight);\n const chunksArray = Array.from({ length: chunks }, (_, i) => i);\n const chunksRemaining = chunksArray.filter((chunk2) => {\n return !chunksSeen.includes(chunk2);\n });\n const currentScrollPosition = window.scrollY;\n const closestChunk = chunksRemaining.reduce((closest, current) => {\n const currentChunkTop = viewportHeight * current;\n const closestChunkTop = viewportHeight * closest;\n return Math.abs(currentScrollPosition - currentChunkTop) < Math.abs(currentScrollPosition - closestChunkTop) ? current : closest;\n }, chunksRemaining[0]);\n const chunk = closestChunk;\n if (chunk === void 0) {\n throw new Error(`No chunks remaining to check: ${chunksRemaining}`);\n }\n return {\n chunk,\n chunksArray\n };\n }\n\n // lib/dom/debug.ts\n async function debugDom() {\n window.chunkNumber = 0;\n const container = new GlobalPageContainer();\n const chunkSize = container.getViewportHeight();\n const startOffset = container.getScrollPosition();\n const endOffset = startOffset;\n const singleChunks = await container.collectDomChunks(\n startOffset,\n endOffset,\n chunkSize,\n false,\n false,\n // Don\'t scroll back to top\n void 0\n // BFS entire doc\n );\n const [singleChunk] = singleChunks;\n if (!singleChunk) {\n console.warn("No chunk was returned. Possibly empty doc?");\n return;\n }\n const multiSelectorMap = singleChunk.selectorMap;\n const selectorMap = multiSelectorMapToSelectorMap(multiSelectorMap);\n drawChunk(selectorMap);\n }\n function multiSelectorMapToSelectorMap(multiSelectorMap) {\n return Object.fromEntries(\n Object.entries(multiSelectorMap).map(([key, selectors]) => [\n Number(key),\n selectors[0]\n ])\n );\n }\n function drawChunk(selectorMap) {\n if (!window.showChunks) return;\n cleanupMarkers();\n Object.values(selectorMap).forEach((selector) => {\n const element = getNodeFromXpath(selector);\n if (element) {\n let rect;\n if (element.nodeType === Node.ELEMENT_NODE) {\n rect = element.getBoundingClientRect();\n } else {\n const range = document.createRange();\n range.selectNodeContents(element);\n rect = range.getBoundingClientRect();\n }\n const color = "grey";\n const overlay = document.createElement("div");\n overlay.style.position = "absolute";\n overlay.style.left = `${rect.left + window.scrollX}px`;\n overlay.style.top = `${rect.top + window.scrollY}px`;\n overlay.style.padding = "2px";\n overlay.style.width = `${rect.width}px`;\n overlay.style.height = `${rect.height}px`;\n overlay.style.backgroundColor = color;\n overlay.className = "stagehand-marker";\n overlay.style.opacity = "0.3";\n overlay.style.zIndex = "1000000000";\n overlay.style.border = "1px solid";\n overlay.style.pointerEvents = "none";\n document.body.appendChild(overlay);\n }\n });\n }\n async function cleanupDebug() {\n cleanupMarkers();\n }\n function cleanupMarkers() {\n const markers = document.querySelectorAll(".stagehand-marker");\n markers.forEach((marker) => {\n marker.remove();\n });\n }\n window.debugDom = debugDom;\n window.cleanupDebug = cleanupDebug;\n})();\n';
4474
4555
 
4475
4556
  // lib/cache/LLMCache.ts
4476
4557
  var LLMCache = class _LLMCache extends BaseCache {
@@ -0,0 +1,6 @@
1
+ export interface DomChunk {
2
+ startOffset: number;
3
+ endOffset: number;
4
+ outputString: string;
5
+ selectorMap: Record<number, string[]>;
6
+ }
@@ -1,9 +1,57 @@
1
1
  import { StagehandContainer } from "./StagehandContainer";
2
- export declare class ElementContainer implements StagehandContainer {
2
+ /**
3
+ * The ElementContainer class is a container implementation for a specific
4
+ * HTML element.
5
+ *
6
+ * Unlike `GlobalPageContainer`, which manages the entire page,
7
+ * this class focuses on one particular `HTMLElement`. Operations
8
+ * such as `scrollTo` and `scrollIntoView` apply to that element
9
+ * rather than `window`.
10
+ */
11
+ export declare class ElementContainer extends StagehandContainer {
3
12
  private el;
13
+ /**
14
+ * Creates an instance of `ElementContainer` tied to a specific element.
15
+ * @param el - The scrollable `HTMLElement` that this container controls.
16
+ */
4
17
  constructor(el: HTMLElement);
18
+ getRootElement(): HTMLElement;
19
+ /**
20
+ * Retrieves the height of the visible viewport within this element
21
+ * (`el.clientHeight`).
22
+ *
23
+ * @returns The visible (client) height of the element, in pixels.
24
+ */
5
25
  getViewportHeight(): number;
6
26
  getScrollHeight(): number;
27
+ /**
28
+ * Returns the element's current vertical scroll offset.
29
+ */
30
+ getScrollPosition(): number;
31
+ /**
32
+ * Smoothly scrolls this element to the specified vertical offset, and
33
+ * waits for the scrolling to complete.
34
+ *
35
+ * @param offset - The scroll offset (in pixels) from the top of the element.
36
+ * @returns A promise that resolves once scrolling is finished.
37
+ */
7
38
  scrollTo(offset: number): Promise<void>;
39
+ /**
40
+ * Scrolls this element so that the given `element` is visible, or
41
+ * scrolls to the top if none is provided. Smoothly animates the scroll
42
+ * and waits until it finishes.
43
+ *
44
+ * @param element - The child element to bring into view. If omitted, scrolls to top.
45
+ * @returns A promise that resolves once scrolling completes.
46
+ */
47
+ scrollIntoView(element?: HTMLElement): Promise<void>;
48
+ /**
49
+ * Internal helper that waits until scrolling in this element has
50
+ * fully stopped. It listens for scroll events on the element,
51
+ * resetting a short timer every time a scroll occurs, and resolves
52
+ * once there's no scroll for ~100ms.
53
+ *
54
+ * @returns A promise that resolves when scrolling has finished.
55
+ */
8
56
  private waitForScrollEnd;
9
57
  }
@@ -1,7 +1,48 @@
1
1
  import { StagehandContainer } from "./StagehandContainer";
2
- export declare class GlobalPageContainer implements StagehandContainer {
2
+ /**
3
+ * The `GlobalPageContainer` class is a container implementation for the entire
4
+ * webpage or global document.
5
+ *
6
+ * This container manages the global `window` scroll position and provides
7
+ * measurements using `document.documentElement`. It extends `StagehandContainer`
8
+ * to unify scrolling/height logic with other container types, such as element
9
+ * based containers from the `ElementContainer` class.
10
+ */
11
+ export declare class GlobalPageContainer extends StagehandContainer {
12
+ getRootElement(): HTMLElement;
13
+ /**
14
+ * Calculates the viewport height for the entire page, using a helper.
15
+ * The helper returns 75% of the window height, to ensure that we don't
16
+ * miss any content that may be behind sticky elements like nav bars.
17
+ *
18
+ * @returns The current height of the global viewport, in pixels.
19
+ */
3
20
  getViewportHeight(): number;
4
21
  getScrollHeight(): number;
22
+ getScrollPosition(): number;
23
+ /**
24
+ * Smoothly scrolls the page to the specified vertical offset, and then
25
+ * waits until scrolling has stopped. There is a delay built in to allow
26
+ * for lazy loading and other asynchronous content to load.
27
+ *
28
+ * @param offset - The desired scroll offset from the top of the page.
29
+ * @returns A promise that resolves once scrolling is complete.
30
+ */
5
31
  scrollTo(offset: number): Promise<void>;
32
+ /**
33
+ * Scrolls the page so that a given element is visible, or scrolls to the top
34
+ * if no element is specified. Uses smooth scrolling and waits for it to complete.
35
+ *
36
+ * @param element - The DOM element to bring into view. If omitted, scrolls to top.
37
+ * @returns A promise that resolves once scrolling is complete.
38
+ */
39
+ scrollIntoView(element?: HTMLElement): Promise<void>;
40
+ /**
41
+ * Internal helper that waits until the global scroll activity has stopped.
42
+ * It listens for scroll events, resetting a short timer every time a scroll
43
+ * occurs, and resolves once there's no scroll for ~100ms.
44
+ *
45
+ * @returns A promise that resolves when scrolling has finished.
46
+ */
6
47
  private waitForScrollEnd;
7
48
  }
@@ -1,5 +1,67 @@
1
- export interface StagehandContainer {
2
- getViewportHeight(): number;
3
- getScrollHeight(): number;
4
- scrollTo(offset: number): Promise<void>;
1
+ import { DomChunk } from "@/lib/dom/DomChunk";
2
+ /**
3
+ * The `StagehandContainer` class defines an abstract interface for
4
+ * scrolling and DOM inspection across various container types e.g.,
5
+ * the entire page (GlobalPageContainer), a specific sub element of the DOM,
6
+ * (ElementContainer).
7
+ */
8
+ export declare abstract class StagehandContainer {
9
+ abstract getViewportHeight(): number;
10
+ abstract getScrollHeight(): number;
11
+ abstract scrollTo(offset: number): Promise<void>;
12
+ abstract getRootElement(): HTMLElement | Document;
13
+ abstract scrollIntoView(element?: HTMLElement): Promise<void>;
14
+ abstract getScrollPosition(): number;
15
+ /**
16
+ * Collects multiple "DOM chunks" by scrolling through the container
17
+ * in increments from `startOffset` to `endOffset`. At each scroll
18
+ * position, the function extracts a snapshot of "candidate elements"
19
+ * using `collectCandidateElements`.
20
+ *
21
+ * Each chunk represents a subset of the DOM at a particular
22
+ * vertical scroll offset, including:
23
+ *
24
+ * - `startOffset` & `endOffset`: The vertical scroll bounds for this chunk.
25
+ * - `outputString`: A serialized representation of extracted DOM text.
26
+ * - `selectorMap`: A mapping of temporary indices to the actual element(s)
27
+ * that were collected in this chunk, useful for further processing.
28
+ *
29
+ * @param startOffset - The initial scroll offset from which to begin collecting.
30
+ * @param endOffset - The maximum scroll offset to collect up to.
31
+ * @param chunkSize - The vertical increment to move between each chunk.
32
+ * @param scrollTo - Whether we should scroll to the chunk
33
+ * @param scrollBackToTop - Whether to scroll the container back to the top once finished.
34
+ * @param candidateContainer - Optionally, a specific container element within
35
+ * the root for which to collect data. If omitted, uses `this.getRootElement()`.
36
+ *
37
+ * @returns A promise that resolves with an array of `DomChunk` objects.
38
+ *
39
+ * ### How It Works
40
+ *
41
+ * 1. **Scroll Range Calculation**:
42
+ * - Computes `maxOffset` as the maximum offset that can be scrolled
43
+ * (`scrollHeight - viewportHeight`).
44
+ * - Restricts `endOffset` to not exceed `maxOffset`.
45
+ *
46
+ * 2. **Chunk Iteration**:
47
+ * - Loops from `startOffset` to `endOffset` in steps of `chunkSize`.
48
+ * - For each offset `current`, we call `this.scrollTo(current)`
49
+ * to position the container.
50
+ *
51
+ * 3. **Element Collection**:
52
+ * - Invokes `collectCandidateElements` on either `candidateContainer`
53
+ * (if provided) or the result of `this.getRootElement()`.
54
+ * - This returns both an `outputString` (serialized text)
55
+ * and a `selectorMap` of found elements for that section of the DOM.
56
+ *
57
+ * 4. **Chunk Assembly**:
58
+ * - Creates a `DomChunk` object for the current offset range,
59
+ * storing `outputString`, `selectorMap`, and scroll offsets.
60
+ * - Pushes it onto the `chunks` array.
61
+ *
62
+ * 5. **Scroll Reset**:
63
+ * - Once iteration completes, if `scrollBackToTop` is `true`,
64
+ * we scroll back to offset `0`.
65
+ */
66
+ collectDomChunks(startOffset: number, endOffset: number, chunkSize: number, scrollTo?: boolean, scrollBackToTop?: boolean, candidateContainer?: HTMLElement): Promise<DomChunk[]>;
5
67
  }