use locator inputs for observe & extract

[seanmcguire12]

why

• observe & extract previously accepted selector strings instead of locator's. for consistency across our APIs, this PR changes them to accept locator's

what changed

• replaced selector / ignoreSelectors observe and extract protocol options with locator descriptor fields
• migrated extension snapshot, observe, and extract internals to use locator descriptors, including nth
• bypasses the current server-side cache for locator-scoped observe/extract calls to avoid sending locator descriptors through the selector-shaped cache contract
• updated TypeScript, Python, and Go SDK public APIs to accept page-bound locator wrapper objects instead of protocol shaped locator schemas
• added validation for checking that supplied locators belong to the resolved target page before sending RPC requests
• serializes observe/extract locator options in TS batch callbacks after resolving the operation page
• updates v4 docs and examples to show page.locator(...) / page.Locator(...) scoping
• also updates evals to use locator-based extract scoping

returned selectors remain plain output data. Action.selector and snapshot selector maps are not wrapped as live locators by this PR

SDK shapes

TypeScript:

await stagehand.extract("Extract text", Schema, {
  page,
  locator: page.locator("main"),
  ignoreLocators: [page.locator("nav"), page.locator(".ad").nth(2)],
});

Python:

await stagehand.extract(
    "Extract text",
    Schema,
    page=page,
    locator=page.locator("main"),
    ignore_locators=[page.locator("nav")],
)

Go:

result, err := stagehand.Extract[resultType](
	ctx,
	client,
	"Extract text",
	&stagehand.StagehandClientExtractOptions{
		Page:    page,
		Locator: page.Locator("main"),
		IgnoreLocators: []*stagehand.PageLocator{
			page.Locator("nav"),
		},
	},
)

behaviour notes:

• page remains optional. If omitted, Stagehand resolves the active page and validates locators against that page
• Locator descriptors include selector and optional nth internally
• Locator-scoped observe/extract calls bypass the current server-side cache; unscoped calls keep existing cache behavior
• Ignored locators exclude matched nodes and descendants from the snapshot context
• observe results and act(Action) inputs still use selector strings as action data

test plan

• added protocol tests to cover the new observe/extract wire shape for locator & ignoreLocators
• extension tests cover locator-scoped observe/extract snapshots, ignored locator subtrees, cache bypass behavior, & nth handling
• TS SDK tests cover public Locator wrapper inputs, descriptor serialization, & cross-page validation
• Python SDK tests cover public Locator wrapper inputs, descriptor serialization, and cross-page validation
• Go SDK tests cover handwritten observe/extract client options, *PageLocator conversion, cross-page validation, and generated model compatibility for the SDK/internal packages
• also updated docs tests

---

Summary by cubic

Switch observe, extract, and act to accept page-bound locator inputs instead of selector strings, standardizing scoping, enabling precise nth targeting, and letting you exclude subtrees. Locator-scoped calls bypass server caching; SDKs validate that locators belong to the target page.

• New Features

  • Added locator and ignoreLocators to act/observe/extract; all support .nth for disambiguation. text= locators are not yet supported for snapshot scoping.
  • TypeScript, Python, and Go SDKs accept page-bound Locator objects for all three methods and enforce same-page validation; TS batch callbacks serialize locators after resolving the operation page.
  • Extension snapshotting and a11y scoping use locator descriptors (focusLocator/ignoreLocators) and honor .nth; added targeted tests.
  • Caching: locator-scoped act/observe/extract bypass server cache reads/writes; cache inputs omit locator descriptors; responses show metadata.cache.status as DISABLED.
  • Protocol schemas: ActOptions adds ignore_locators; observe/extract now use locator/ignore_locators.
  • Docs and evals updated to use page.locator("...") and xpath=...; evals Vitest config updated. Go SDK: flattened per-call fields for Act options and fixed nil IgnoreLocators handling.

• Migration

  • Replace selector with locator: page.locator("...") and ignoreSelectors with ignoreLocators: [page.locator("..."), ...] in observe/extract.
  • Use .nth(index) to target a specific match; include xpath= when using XPath locators.
  • Go SDK: move per-call fields to top-level of StagehandClientActOptions (and already for Observe/Extract), e.g., use Cache, Timeout, Model, Locator, IgnoreLocators, Variables directly.
  • Returned selectors in results remain strings; no change to action inputs/outputs.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6f21169

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[cubic-dev-ai]

All reported issues were addressed across 47 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 8 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 52 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 7 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>