[feat]: add page.snapshot() (#1518)

# why
- to expose a public API for the snapshotting functionality used by
stagehand internally
# what changed
- added a new `page.snapshot()` function, which returns a
`SnapshotResult` object containing:
- a stringified, hierarchical tree representation of the DOM (the same
one that is given to the LLM internally)
- an xpath map, which contains a mapping of xpaths for elements on the
page, keyed by IDs
- a URL map, which contains a mapping of all URLs inlcuded in the page,
keyed by IDs
# test plan
- we already have comprehensive testing for the internals of this
function (`captureHybridSnapshot()`), and this new function does not
have any additional branching logic. existing unit tests & evals should
suffice.

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Exposes a public page.snapshot() API to capture a formatted DOM snapshot
with xpath and URL maps. Addresses STG-1082 by making the internal
snapshotter available to users.

- New Features
- Added page.snapshot(): returns SnapshotResult { formattedTree,
xpathMap, urlMap } using captureHybridSnapshot (pierces shadow DOM).
- Introduced StagehandSnapshotError for snapshot failures (keeps
original cause).
  - Exported SnapshotResult type.

- Refactors
- StagehandError now accepts and stores an optional cause for better
error chaining.

<sup>Written for commit e89840f.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

Author: seanmcguire12

.changeset/tiny-pens-serve.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+add page.snapshot() for capturing a stringified DOM snapshot of the page, including an xpath map & url map

packages/core/lib/v3/types/public/page.ts

@@ -11,3 +11,9 @@ export type { ConsoleListener } from "../../understudy/consoleMessage";
 
 export type LoadState = "load" | "domcontentloaded" | "networkidle";
 export { Response } from "../../understudy/response";
+
+export type SnapshotResult = {
+  formattedTree: string;
+  xpathMap: Record<string, string>;
+  urlMap: Record<string, string>;
+};

packages/core/lib/v3/types/public/sdkErrors.ts

@@ -3,9 +3,14 @@ import { ZodError } from "zod";
 import { STAGEHAND_VERSION } from "../../../version";
 
 export class StagehandError extends Error {
-  constructor(message: string) {
+  public readonly cause?: unknown;
+
+  constructor(message: string, cause?: unknown) {
     super(message);
     this.name = this.constructor.name;
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
   }
 }
 
@@ -370,3 +375,15 @@ export class StagehandClosedError extends StagehandError {
     super("Stagehand session was closed");
   }
 }
+
+export class StagehandSnapshotError extends StagehandError {
+  constructor(cause?: unknown) {
+    const suffix =
+      cause instanceof Error
+        ? `: ${cause.message}`
+        : cause
+          ? `: ${String(cause)}`
+          : "";
+    super(`error taking snapshot${suffix}`, cause);
+  }
+}

packages/core/lib/v3/understudy/page.ts

@@ -7,17 +7,23 @@ import { CdpConnection } from "./cdp";
 import { Frame } from "./frame";
 import { FrameLocator } from "./frameLocator";
 import { deepLocatorFromPage, resolveLocatorTarget } from "./deepLocator";
-import { resolveXpathForLocation } from "./a11y/snapshot";
+import {
+  captureHybridSnapshot,
+  resolveXpathForLocation,
+} from "./a11y/snapshot";
 import { FrameRegistry } from "./frameRegistry";
 import { executionContexts } from "./executionContextRegistry";
-import { LoadState } from "../types/public/page";
+import { LoadState, SnapshotResult } from "../types/public/page";
 import { NetworkManager } from "./networkManager";
 import { LifecycleWatcher } from "./lifecycleWatcher";
 import { NavigationResponseTracker } from "./navigationResponseTracker";
 import { Response, isSerializableResponse } from "./response";
 import { ConsoleMessage, ConsoleListener } from "./consoleMessage";
 import type { StagehandAPIClient } from "../api";
-import type { LocalBrowserLaunchOptions } from "../types/public";
+import {
+  LocalBrowserLaunchOptions,
+  StagehandSnapshotError,
+} from "../types/public";
 import type { Locator } from "./locator";
 import {
   StagehandInvalidArgumentError,
@@ -1789,6 +1795,21 @@ export class Page {
     }
   }
 
+  @logAction("Page.snapshot")
+  async snapshot(): Promise<SnapshotResult> {
+    try {
+      const { combinedTree, combinedXpathMap, combinedUrlMap } =
+        await captureHybridSnapshot(this, { pierceShadow: true });
+      return {
+        formattedTree: combinedTree,
+        xpathMap: combinedXpathMap,
+        urlMap: combinedUrlMap,
+      };
+    } catch (err) {
+      throw new StagehandSnapshotError(err);
+    }
+  }
+
   // Track pressed modifier keys
   private _pressedModifiers = new Set<string>();
 

packages/core/tests/public-api/public-error-types.test.ts

@@ -48,6 +48,7 @@ export const publicErrorTypes = {
     Stagehand.StagehandShadowSegmentNotFoundError,
   StreamingCallbacksInNonStreamingModeError:
     Stagehand.StreamingCallbacksInNonStreamingModeError,
+  StagehandSnapshotError: Stagehand.StagehandSnapshotError,
   TimeoutError: Stagehand.TimeoutError,
   UnsupportedAISDKModelProviderError:
     Stagehand.UnsupportedAISDKModelProviderError,