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.

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.

^{Written for commit e89840f. Summary will update on new commits.}