@browserbasehq/stagehand 2.5.3 → 2.5.4

package/dist/index.d.ts

@@ -318,7 +318,7 @@ interface ObserveOptions {
     iframes?: boolean;
     frameId?: string;
 }
-interface ObserveResult {
+interface ObserveResult$1 {
     selector: string;
     description: string;
     backendNodeId?: number;
@@ -498,9 +498,9 @@ interface ActToolResult {
     action?: string;
     error?: string;
     isIframe?: boolean;
-    playwrightArguments?: ObserveResult | null;
+    playwrightArguments?: ObserveResult$1 | null;
 }
-interface AgentAction {
+interface AgentAction$1 {
     type: string;
     reasoning?: string;
     taskCompleted?: boolean;
@@ -510,13 +510,13 @@ interface AgentAction {
     timestamp?: number;
     pageUrl?: string;
     instruction?: string;
-    playwrightArguments?: ObserveResult | null;
+    playwrightArguments?: ObserveResult$1 | null;
     [key: string]: unknown;
 }
-interface AgentResult {
+interface AgentResult$1 {
     success: boolean;
     message: string;
-    actions: AgentAction[];
+    actions: AgentAction$1[];
     completed: boolean;
     metadata?: Record<string, unknown>;
     usage?: {
@@ -525,14 +525,14 @@ interface AgentResult {
         inference_time_ms: number;
     };
 }
-interface AgentOptions {
+interface AgentOptions$1 {
     maxSteps?: number;
     autoScreenshot?: boolean;
     waitBetweenActions?: number;
     context?: string;
     highlightCursor?: boolean;
 }
-interface AgentExecuteOptions extends AgentOptions {
+interface AgentExecuteOptions$1 extends AgentOptions$1 {
     instruction: string;
 }
 type AgentProviderType = "openai" | "anthropic" | "google";
@@ -545,7 +545,7 @@ interface AgentClientOptions {
 }
 type AgentType = "openai" | "anthropic" | "google";
 interface AgentExecutionOptions {
-    options: AgentExecuteOptions;
+    options: AgentExecuteOptions$1;
     logger: (message: LogLine) => void;
     retries?: number;
 }
@@ -632,7 +632,7 @@ type ResponseInputItem = {
     output: string;
 };
 interface AgentInstance {
-    execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+    execute: (instructionOrOptions: string | AgentExecuteOptions$1) => Promise<AgentResult$1>;
     setScreenshotCollector?: (collector: unknown) => void;
 }
 
@@ -657,13 +657,13 @@ interface StagehandScreenshotOptions extends PageScreenshotOptions {
 interface Page extends Omit<Page$1, "on" | "screenshot"> {
     act(action: string): Promise<ActResult>;
     act(options: ActOptions): Promise<ActResult>;
-    act(observation: ObserveResult): Promise<ActResult>;
+    act(observation: ObserveResult$1): Promise<ActResult>;
     extract(instruction: string): Promise<ExtractResult<typeof defaultExtractSchema>>;
     extract<T extends z.AnyZodObject>(options: ExtractOptions<T>): Promise<ExtractResult<T>>;
     extract(): Promise<ExtractResult<typeof pageTextSchema>>;
-    observe(): Promise<ObserveResult[]>;
-    observe(instruction: string): Promise<ObserveResult[]>;
-    observe(options?: ObserveOptions): Promise<ObserveResult[]>;
+    observe(): Promise<ObserveResult$1[]>;
+    observe(instruction: string): Promise<ObserveResult$1[]>;
+    observe(options?: ObserveOptions): Promise<ObserveResult$1[]>;
     screenshot(options?: StagehandScreenshotOptions): Promise<Buffer>;
     on: {
         (event: "popup", listener: (page: Page) => unknown): Page;
@@ -672,6 +672,31 @@ interface Page extends Omit<Page$1, "on" | "screenshot"> {
 type BrowserContext = BrowserContext$1;
 type Browser = Browser$1;
 
+type AccessibilityNode = {
+    role: string;
+    name?: string;
+    description?: string;
+    value?: string;
+    children?: AccessibilityNode[];
+    childIds?: string[];
+    parentId?: string;
+    nodeId?: string;
+    backendDOMNodeId?: number;
+    properties?: {
+        name: string;
+        value: {
+            type: string;
+            value?: string;
+        };
+    }[];
+};
+interface TreeResult {
+    tree: AccessibilityNode[];
+    simplified: string;
+    iframes?: AccessibilityNode[];
+    idToUrl: Record<EncodedId, string>;
+    xpathMap: Record<EncodedId, string>;
+}
 interface EnhancedContext extends Omit<BrowserContext$1, "newPage" | "pages"> {
     newPage(): Promise<Page>;
     pages(): Page[];
@@ -703,14 +728,14 @@ interface StartSessionResult {
     available?: boolean;
 }
 
-interface ObserveResult$1 {
+interface ObserveResult {
     selector: string;
     description: string;
     backendNodeId?: number;
     method?: string;
     arguments?: string[];
 }
-interface AgentAction$1 {
+interface AgentAction {
     type: string;
     reasoning?: string;
     taskCompleted?: boolean;
@@ -720,13 +745,13 @@ interface AgentAction$1 {
     timestamp?: number;
     pageUrl?: string;
     instruction?: string;
-    playwrightArguments?: ObserveResult$1 | null;
+    playwrightArguments?: ObserveResult | null;
     [key: string]: unknown;
 }
-interface AgentResult$1 {
+interface AgentResult {
     success: boolean;
     message: string;
-    actions: AgentAction$1[];
+    actions: AgentAction[];
     completed: boolean;
     metadata?: Record<string, unknown>;
     usage?: {
@@ -735,14 +760,14 @@ interface AgentResult$1 {
         inference_time_ms: number;
     };
 }
-interface AgentOptions$1 {
+interface AgentOptions {
     maxSteps?: number;
     autoScreenshot?: boolean;
     waitBetweenActions?: number;
     context?: string;
     highlightCursor?: boolean;
 }
-interface AgentExecuteOptions$1 extends AgentOptions$1 {
+interface AgentExecuteOptions extends AgentOptions {
     instruction: string;
 }
 
@@ -755,11 +780,11 @@ declare class StagehandAPI {
     private fetchWithCookies;
     constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
     init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, debugDom, systemPrompt, selfHeal, waitForCaptchaSolves, actionTimeoutMs, browserbaseSessionCreateParams, browserbaseSessionID, }: StartSessionParams): Promise<StartSessionResult>;
-    act(options: ActOptions | ObserveResult): Promise<ActResult>;
+    act(options: ActOptions | ObserveResult$1): Promise<ActResult>;
     extract<T extends z.AnyZodObject>(options: ExtractOptions<T>): Promise<ExtractResult<T>>;
-    observe(options?: ObserveOptions): Promise<ObserveResult[]>;
+    observe(options?: ObserveOptions): Promise<ObserveResult$1[]>;
     goto(url: string, options?: GotoOptions): Promise<void>;
-    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions$1): Promise<AgentResult$1>;
+    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions): Promise<AgentResult>;
     end(): Promise<Response>;
     private execute;
     private request;
@@ -858,9 +883,9 @@ declare class StagehandPage {
      *                    `this.stagehand.domSettleTimeoutMs`.
      */
     _waitForSettledDom(timeoutMs?: number): Promise<void>;
-    act(actionOrOptions: string | ActOptions | ObserveResult): Promise<ActResult>;
+    act(actionOrOptions: string | ActOptions | ObserveResult$1): Promise<ActResult>;
     extract<T extends z.AnyZodObject = typeof defaultExtractSchema>(instructionOrOptions?: string | ExtractOptions<T>): Promise<ExtractResult<T>>;
-    observe(instructionOrOptions?: string | ObserveOptions): Promise<ObserveResult[]>;
+    observe(instructionOrOptions?: string | ObserveOptions): Promise<ObserveResult$1[]>;
     /**
      * Get or create a CDP session for the given target.
      * @param target  The Page or (OOPIF) Frame you want to talk to.
@@ -926,6 +951,7 @@ declare class StagehandError extends Error {
     constructor(message: string);
 }
 declare class StagehandDefaultError extends StagehandError {
+    causedBy?: Error | StagehandError;
     constructor(error?: unknown);
 }
 declare class StagehandEnvironmentError extends StagehandError {
@@ -1130,6 +1156,21 @@ declare class AISdkClient extends LLMClient {
     createChatCompletion<T = ChatCompletion>({ options, }: CreateChatCompletionOptions): Promise<T>;
 }
 
+/**
+ * Retrieve and build a cleaned accessibility tree for a document or specific iframe.
+ * Prunes, formats, and optionally filters by XPath, including scrollable role decoration.
+ *
+ * @deprecated This helper is an escape hatch intended for troubleshooting. Prefer
+ * extract() for supported usage and reach for this only
+ * when absolutely necessary.
+ * @param stagehandPage - The StagehandPage instance for Playwright and CDP interaction.
+ * @param logger - Logging function for diagnostics and performance metrics.
+ * @param selector - Optional XPath to filter the AX tree to a specific subtree.
+ * @param targetFrame - Optional Playwright.Frame to scope the AX tree retrieval.
+ * @returns A Promise resolving to a TreeResult with the hierarchical AX tree and related metadata.
+ */
+declare function getAccessibilityTree(experimental: boolean, stagehandPage: StagehandPage, logger: (log: LogLine) => void, selector?: string, targetFrame?: Frame): Promise<TreeResult>;
+
 declare class Stagehand {
     private stagehandPage;
     private stagehandContext;
@@ -1195,9 +1236,9 @@ declare class Stagehand {
      * @returns An agent instance with execute() method
      */
     agent(options?: AgentConfig): {
-        execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+        execute: (instructionOrOptions: string | AgentExecuteOptions$1) => Promise<AgentResult$1>;
         setScreenshotCollector?: (collector: unknown) => void;
     };
 }
 
-export { AISdkClient, type ActOptions, type ActResult, type ActToolResult, type ActionExecutionResult, type AgentAction, type AgentClientOptions, type AgentConfig, type AgentExecuteOptions, type AgentExecuteParams, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentOptions, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AvailableModel, AvailableModelSchema, type Browser, type BrowserContext, type BrowserResult, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, type ConstructorParams, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, type GotoOptions, HandlerNotInitializedError, type HistoryEntry, type InitResult, InvalidAISDKModelFormatError, LLMClient, type LLMResponse, LLMResponseError, LOG_LEVEL_NAMES, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelProvider, type ObserveOptions, type ObserveResult, type Page, PlaywrightCommandException, PlaywrightCommandMethodNotSupportedException, type ResponseInputItem, type ResponseItem, Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandFunctionName, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, type StagehandScreenshotOptions, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, XPathResolutionError, type ZodPathSegments, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, pageTextSchema };
+export { AISdkClient, type ActOptions, type ActResult, type ActToolResult, type ActionExecutionResult, type AgentAction$1 as AgentAction, type AgentClientOptions, type AgentConfig, type AgentExecuteOptions$1 as AgentExecuteOptions, type AgentExecuteParams, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentOptions$1 as AgentOptions, type AgentProviderType, type AgentResult$1 as AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AvailableModel, AvailableModelSchema, type Browser, type BrowserContext, type BrowserResult, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, type ConstructorParams, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, type GotoOptions, HandlerNotInitializedError, type HistoryEntry, type InitResult, InvalidAISDKModelFormatError, LLMClient, type LLMResponse, LLMResponseError, LOG_LEVEL_NAMES, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelProvider, type ObserveOptions, type ObserveResult$1 as ObserveResult, type Page, PlaywrightCommandException, PlaywrightCommandMethodNotSupportedException, type ResponseInputItem, type ResponseItem, Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandFunctionName, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, type StagehandScreenshotOptions, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, type TreeResult, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, XPathResolutionError, type ZodPathSegments, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getAccessibilityTree, pageTextSchema };

package/dist/index.js

@@ -473,6 +473,7 @@ __export(index_exports, {
   ZodSchemaValidationError: () => ZodSchemaValidationError,
   connectToMCPServer: () => connectToMCPServer,
   defaultExtractSchema: () => defaultExtractSchema,
+  getAccessibilityTree: () => getAccessibilityTree,
   pageTextSchema: () => pageTextSchema
 });
 module.exports = __toCommonJS(index_exports);
@@ -493,7 +494,7 @@ var StagehandFunctionName = /* @__PURE__ */ ((StagehandFunctionName2) => {
 })(StagehandFunctionName || {});
 
 // lib/version.ts
-var STAGEHAND_VERSION = "2.5.3";
+var STAGEHAND_VERSION = "2.5.4";
 
 // types/stagehandErrors.ts
 var StagehandError = class extends Error {
@@ -514,6 +515,7 @@ If you need help, please open a Github issue or reach out to us on Slack: https:
 Full error:
 ${error.message}`
       );
+      this.causedBy = error;
     }
   }
 };
@@ -2689,8 +2691,10 @@ function buildBackendIdMaps(experimental, sp, targetFrame) {
             if (n.contentDocument && locate(n.contentDocument)) return true;
             return false;
           } else {
-            if (n.backendNodeId === backendNodeId)
-              return iframeNode = n, true;
+            if (n.backendNodeId === backendNodeId) {
+              iframeNode = n;
+              return true;
+            }
             return ((_d2 = (_c2 = n.children) == null ? void 0 : _c2.some(locate)) != null ? _d2 : false) || (n.contentDocument ? locate(n.contentDocument) : false);
           }
         };
@@ -2702,17 +2706,25 @@ function buildBackendIdMaps(experimental, sp, targetFrame) {
       }
       const tagNameMap = {};
       const xpathMap = {};
+      const scrollableBackendIds = /* @__PURE__ */ new Set();
       const stack = [{ node: startNode, path: "", fid: rootFid }];
       const seen = /* @__PURE__ */ new Set();
       const joinStep = (base, step) => base.endsWith("//") ? `${base}${step}` : `${base}/${step}`;
       while (stack.length) {
         const { node, path: path4, fid } = stack.pop();
         if (!node.backendNodeId) continue;
+        const backendId = node.backendNodeId;
         const enc = sp.encodeWithFrameId(fid, node.backendNodeId);
         if (seen.has(enc)) continue;
         seen.add(enc);
         tagNameMap[enc] = lc(String(node.nodeName));
         xpathMap[enc] = path4;
+        if (node.isScrollable === true) {
+          scrollableBackendIds.add(backendId);
+        }
+        if (lc(String(node.nodeName)) === "html") {
+          scrollableBackendIds.add(backendId);
+        }
         if (lc(node.nodeName) === "iframe" && node.contentDocument) {
           const childFid = (_b = node.contentDocument.frameId) != null ? _b : fid;
           stack.push({ node: node.contentDocument, path: "", fid: childFid });
@@ -2753,7 +2765,7 @@ function buildBackendIdMaps(experimental, sp, targetFrame) {
           }
         }
       }
-      return { tagNameMap, xpathMap };
+      return { tagNameMap, xpathMap, scrollableBackendIds };
     } finally {
       yield sp.disableCDP(
         "DOM",
@@ -2885,11 +2897,7 @@ function getCDPFrameId(sp, frame) {
 }
 function getAccessibilityTree(experimental, stagehandPage, logger, selector, targetFrame) {
   return __async(this, null, function* () {
-    const { tagNameMap, xpathMap } = yield buildBackendIdMaps(
-      experimental,
-      stagehandPage,
-      targetFrame
-    );
+    const { tagNameMap, xpathMap, scrollableBackendIds } = yield buildBackendIdMaps(experimental, stagehandPage, targetFrame);
     yield stagehandPage.enableCDP("Accessibility", targetFrame);
     try {
       let params = {};
@@ -2916,10 +2924,6 @@ function getAccessibilityTree(experimental, stagehandPage, logger, selector, tar
         }
       }
       const { nodes: fullNodes } = yield stagehandPage.sendCDP("Accessibility.getFullAXTree", params, sessionFrame);
-      const scrollableIds = yield findScrollableElementIds(
-        stagehandPage,
-        targetFrame
-      );
       let nodes = fullNodes;
       if (selector) {
         nodes = yield filterAXTreeByXPath(
@@ -2931,7 +2935,7 @@ function getAccessibilityTree(experimental, stagehandPage, logger, selector, tar
       }
       const start = Date.now();
       const tree = yield buildHierarchicalTree(
-        decorateRoles(nodes, scrollableIds),
+        decorateRoles(nodes, scrollableBackendIds),
         tagNameMap,
         logger,
         xpathMap
@@ -2980,16 +2984,16 @@ function filterAXTreeByXPath(page, full, xpath, targetFrame) {
 }
 function decorateRoles(nodes, scrollables) {
   return nodes.map((n) => {
-    var _a15, _b, _c, _d, _e;
+    var _a15, _b, _c, _d, _e, _f;
     let role = (_b = (_a15 = n.role) == null ? void 0 : _a15.value) != null ? _b : "";
-    if (scrollables.has(n.backendDOMNodeId)) {
+    if (((_c = n.role) == null ? void 0 : _c.value) !== "RootWebArea" && scrollables.has(n.backendDOMNodeId)) {
       role = role && role !== "generic" && role !== "none" ? `scrollable, ${role}` : "scrollable";
     }
     return {
       role,
-      name: (_c = n.name) == null ? void 0 : _c.value,
-      description: (_d = n.description) == null ? void 0 : _d.value,
-      value: (_e = n.value) == null ? void 0 : _e.value,
+      name: (_d = n.name) == null ? void 0 : _d.value,
+      description: (_e = n.description) == null ? void 0 : _e.value,
+      value: (_f = n.value) == null ? void 0 : _f.value,
       nodeId: n.nodeId,
       backendDOMNodeId: n.backendDOMNodeId,
       parentId: n.parentId,
@@ -3219,27 +3223,6 @@ function getAccessibilityTreeWithFrames(experimental, stagehandPage, logger, roo
     return { combinedTree, combinedXpathMap, combinedUrlMap };
   });
 }
-function findScrollableElementIds(stagehandPage, targetFrame) {
-  return __async(this, null, function* () {
-    const xpaths = targetFrame ? yield targetFrame.evaluate(() => window.getScrollableElementXpaths()) : yield stagehandPage.page.evaluate(
-      () => window.getScrollableElementXpaths()
-    );
-    const backendIds = /* @__PURE__ */ new Set();
-    for (const xpath of xpaths) {
-      if (!xpath) continue;
-      const objectId = yield resolveObjectIdForXPath(
-        stagehandPage,
-        xpath,
-        targetFrame
-      );
-      if (objectId) {
-        const { node } = yield stagehandPage.sendCDP("DOM.describeNode", { objectId }, targetFrame);
-        if (node == null ? void 0 : node.backendNodeId) backendIds.add(node.backendNodeId);
-      }
-    }
-    return backendIds;
-  });
-}
 function resolveObjectIdForXPath(page, xpath, targetFrame) {
   return __async(this, null, function* () {
     const contextId = yield getFrameExecutionContextId(page, targetFrame);
@@ -24932,5 +24915,6 @@ var Stagehand3 = class {
   ZodSchemaValidationError,
   connectToMCPServer,
   defaultExtractSchema,
+  getAccessibilityTree,
   pageTextSchema
 });

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

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

package/dist/lib/index.d.ts

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

package/dist/lib/version.d.ts

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

package/dist/types/context.d.ts

@@ -58,11 +58,13 @@ export type DOMNode = {
     contentDocument?: DOMNode;
     nodeType: number;
     frameId?: string;
+    isScrollable?: boolean;
 };
 export type BackendIdMaps = {
     tagNameMap: Record<number, string>;
     xpathMap: Record<number, string>;
     iframeXPath?: string;
+    scrollableBackendIds: Set<number>;
 };
 export interface EnhancedContext extends Omit<PlaywrightContext, "newPage" | "pages"> {
     newPage(): Promise<Page>;

package/dist/types/stagehandErrors.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/stagehand",
-  "version": "2.5.3",
+  "version": "2.5.4",
   "description": "An AI web browsing framework focused on simplicity and extensibility.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -8,30 +8,6 @@
   "bin": {
     "evals": "./dist/evals/cli.js"
   },
-  "scripts": {
-    "example": "pnpm --filter @browserbasehq/stagehand-examples run start",
-    "format": "prettier --write .",
-    "prettier": "prettier --check .",
-    "prettier:fix": "prettier --write .",
-    "eslint": "eslint .",
-    "cache:clear": "rm -rf .cache",
-    "docs": "pnpm --filter @browserbasehq/stagehand-docs run dev",
-    "evals": "tsx scripts/run-evals.ts",
-    "evals:legacy": "tsx scripts/run-evals.ts",
-    "e2e": "pnpm run build && cd evals/deterministic && playwright test --config=e2e.playwright.config.ts",
-    "e2e:bb": "pnpm run build && cd evals/deterministic && playwright test --config=bb.playwright.config.ts",
-    "e2e:local": "pnpm run build && cd evals/deterministic && playwright test --config=local.playwright.config.ts",
-    "build-dom-scripts": "tsx lib/dom/genDomScripts.ts",
-    "build-types": "tsc --emitDeclarationOnly --outDir dist",
-    "build-js": "tsup lib/index.ts --dts",
-    "build:cli": "tsup evals/cli.ts --outDir dist/evals --format cjs && cp evals/evals.config.json dist/evals/ && chmod +x dist/evals/cli.js && npm link",
-    "build": "pnpm run lint && pnpm run gen-version && pnpm run build-dom-scripts && pnpm run build-js && pnpm run build-types",
-    "gen-version": "tsx scripts/gen-version.ts",
-    "prepare": "pnpm run build",
-    "lint": "pnpm run prettier:fix && pnpm run eslint",
-    "release": "pnpm run build && changeset publish",
-    "release-canary": "pnpm run build && changeset version --snapshot && changeset publish --tag alpha"
-  },
   "files": [
     "dist/**"
   ],
@@ -118,5 +94,27 @@
   "overrides": {
     "whatwg-url": "^14.0.0"
   },
-  "packageManager": "pnpm@9.15.0+sha512.76e2379760a4328ec4415815bcd6628dee727af3779aaa4c914e3944156c4299921a89f976381ee107d41f12cfa4b66681ca9c718f0668fa0831ed4c6d8ba56c"
-}
+  "scripts": {
+    "example": "pnpm --filter @browserbasehq/stagehand-examples run start",
+    "format": "prettier --write .",
+    "prettier": "prettier --check .",
+    "prettier:fix": "prettier --write .",
+    "eslint": "eslint .",
+    "cache:clear": "rm -rf .cache",
+    "docs": "pnpm --filter @browserbasehq/stagehand-docs run dev",
+    "evals": "tsx scripts/run-evals.ts",
+    "evals:legacy": "tsx scripts/run-evals.ts",
+    "e2e": "pnpm run build && cd evals/deterministic && playwright test --config=e2e.playwright.config.ts",
+    "e2e:bb": "pnpm run build && cd evals/deterministic && playwright test --config=bb.playwright.config.ts",
+    "e2e:local": "pnpm run build && cd evals/deterministic && playwright test --config=local.playwright.config.ts",
+    "build-dom-scripts": "tsx lib/dom/genDomScripts.ts",
+    "build-types": "tsc --emitDeclarationOnly --outDir dist",
+    "build-js": "tsup lib/index.ts --dts",
+    "build:cli": "tsup evals/cli.ts --outDir dist/evals --format cjs && cp evals/evals.config.json dist/evals/ && chmod +x dist/evals/cli.js && npm link",
+    "build": "pnpm run lint && pnpm run gen-version && pnpm run build-dom-scripts && pnpm run build-js && pnpm run build-types",
+    "gen-version": "tsx scripts/gen-version.ts",
+    "lint": "pnpm run prettier:fix && pnpm run eslint",
+    "release": "pnpm run build && changeset publish",
+    "release-canary": "pnpm run build && changeset version --snapshot && changeset publish --tag alpha"
+  }
+}