feat(snapshot): add opt-in locator hints

[pr1m8]

why

Stagehand snapshots are intentionally compact, but notebook and agent workflows sometimes need a stable hint for choosing the next locator without falling back to a raw DOM dump or screenshot-only reasoning.

This adds an opt-in richer formatted tree while preserving the default snapshot output and token cost for existing callers.

what changed

• Add page.snapshot({ expanded: true }).
• Append safe, unique locator hints to supported interactive accessibility-tree nodes.
• Prefer stable DOM attributes such as id, test IDs, name, autocomplete, aria-label, and safe relative link paths.
• Keep hints disabled by default.
• Restrict hints to the root frame and open shadow DOM.
• Exclude password inputs, duplicate values, generated-looking IDs, unsafe/control characters, unsuitable tag/attribute combinations, and non-link href hints.
• Add the shared protocol field and generated Python/Go SDK support.
• Document the option in the TypeScript, Python, and Go page references.
• Add a minor Changeset for @browserbasehq/stagehand.

test plan

• pnpm build
• pnpm fmt:check
• pnpm check
• Focused extension snapshot tests: 36 files / 323 tests passed.
• Focused protocol schema tests: 23 files / 325 tests passed.
• SDK package-contract, protocol parity, and documentation reference checks passed.
• Browser smoke rerun: 32 passed, 4 skipped.

pnpm test was also run. Its first parallel run had one unrelated timeout in the real-browser structured-extraction smoke test; rerunning that exact browser suite passed without code changes.

---

Summary by cubic

Adds an opt-in expanded option to page.snapshot() that appends safe, unique locator hints to interactive nodes in the formatted accessibility tree, while keeping the default compact output unchanged.

• expanded: true produces hints like #id, testid=..., aria-label=... on supported roles.
• Hints are limited to the root frame and open shadow DOM, and exclude password fields, duplicate values, and unsafe attribute combinations.
• The protocol schema and generated Python/Go SDKs now support the option.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 013b545

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 16 packages

Name	Type
@browserbasehq/stagehand	Minor
@browserbasehq/stagehand-integrations	Patch
@browserbasehq/stagehand-integrations-example-eve-facade	Patch
@browserbasehq/stagehand-integrations-example-pi-facade	Patch
@browserbasehq/stagehand-integrations-claude-agent-sdk	Patch
@browserbasehq/stagehand-integrations-example-claude-code-facade	Patch
@browserbasehq/stagehand-integrations-codex-sdk	Patch
@browserbasehq/stagehand-integrations-example-codex-facade	Patch
@browserbasehq/stagehand-integrations-cursor-sdk	Patch
@browserbasehq/stagehand-integrations-deepagents-sdk	Patch
@browserbasehq/stagehand-integrations-eve-sdk	Patch
@browserbasehq/stagehand-integrations-fx-sdk	Patch
@browserbasehq/stagehand-integrations-mastra-sdk	Patch
@browserbasehq/stagehand-integrations-example-mastra-facade	Patch
@browserbasehq/stagehand-integrations-pi-sdk	Patch
@browserbasehq/stagehand-integrations-example-vercel-ai-facade	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.