refactor(cli): remove coordinate XPath return flag

[shrey150]

Summary

Remove Browse's obsolete --return-xpath coordinate-action option instead of carrying a permanently unsupported V4 compatibility flag. This is also the first stack head with the complete supported V3 CLI surface on Stagehand V4, so the Browse minor-release changeset belongs here.

• Remove the option from mouse click, hover, scroll, and drag.
• Stop sending or accepting returnXPath in driver payloads.
• Remove obsolete examples and README guidance.
• Assert that the option is absent from all four command help surfaces.
• Add the single minor changeset for the V4 migration and contract removal.

XPath selectors and snapshot xpathMap are unchanged. This removes only the request to return an XPath from a raw coordinate action.

Stack (#2872)

1. chore(cli): import Browse V3 baseline #2833 — exact Browse V3 baseline import
2. refactor(cli): migrate Browse runtime and commands to Stagehand V4 #2834 — Stagehand V4 runtime and standard command parity
3. feat(cli): restore cursor overlay through page.evaluate #2869 — CLI-owned cursor overlay
4. fix(cli): restore V3 network capture through a CDP sidecar #2849 — CLI-private CDP sidecar; V3 network parity
5. refactor(cli): remove coordinate XPath return flag #2835 — remove --return-xpath; supported V3 parity/release checkpoint
6. test(evals): exercise the workspace V4 CLI #2838 — eval and packaging integration
7. fix(cli): persist context names in Browserbase #2839 — managed Context names (fast-follow)
8. refactor(cli): consume shared Functions core #2701 — shared Functions core consumer (fast-follow)

Review boundary

The diff from #2849 is intentionally small: one public-contract removal plus its release metadata. Browser lifecycle, standard commands, cursor, and network are proven independently below it. #2838 consumes this publishable parity head but no longer owns the migration changeset.

E2E Test Matrix

The current rebased #2835 head is 0a39cde0b8950caf28c46858a2bfaa199c9dea00. The full post-propagation verification below ran at 69cacfe76e0c03ccfcfbf1a956b61815d192f5fc; the only inherited change since then is #2849's test-helper timeout diagnostic, whose focused network tests and Browse lint/typecheck passed at sidecar head 9887732b6. Its eight-file XPath-removal patch has the same stable patch ID (a1c808ef2326383eef0385dad5eae1b4acedab85) as the previously exercised stack head. Every new browser run used a unique daemon directory and named session; the pre-existing default daemon was not reused or stopped.

Command / flow	Observed output	Confidence / sufficiency
pnpm install --frozen-lockfile; build extension, local Stagehand SDK, then browse	Frozen install and all three builds passed; the Oclif manifest was generated from the tested workspace.	Proves the exact clean stack head installs and builds from its lockfile with fresh extension/SDK/CLI artifacts.
Built CLI: browse mouse <click|hover|scroll|drag> --help	--return-xpath was absent from all four help surfaces.	Proves the removed contract is no longer advertised.
Invoke each of click, hover, scroll, and drag with --return-xpath	All four commands exited 2 with Error: Nonexistent flag: --return-xpath.	Proves no coordinate action silently accepts or forwards the obsolete option.
One real Browserbase composition flow: open Example Domain → cursor → network on → mouse hover → screenshot → reload → network off	Open returned remote mode and the expected title. Cursor enable and hover succeeded. The 2560×1440 PNG was 72,825 bytes and visually showed the cursor at the commanded coordinate. The marked reload emitted exactly 1 request and 1 response with status 200.	Proves the inherited evaluated cursor and private CDP network sidecar compose at this top parity head, while the changed coordinate command schema remains usable. The durable cursor screenshot proof remains attached to #2869.
Same real Browserbase flow: network clear → stop	Clear succeeded and stop reported stopped.	Proves scoped cleanup without touching unrelated sessions.
Exact parent #2849 validation	Frozen install, fresh extension/SDK/CLI build, focused 3-file/30-test network suite, full 27-file/390-test suite, and a real two-cycle Browserbase off/on lifecycle all passed at parent head adbe80d8b.	Proves this head inherits the freshly restacked sidecar rather than relying only on pre-restack evidence. #2849 contains the full V3/V4 deterministic and MSN/CNN stress matrices.
Earlier full-parity command matrix on the patch-identical #2835 change	Remote open/title/snapshot; Selenium form viewport/fill/get/click/keyboard/select/checkbox/highlight/wait; screenshot; tabs; back/forward; eval; and timeout wait all completed with the expected values.	Carried-forward breadth for the unchanged XPath-removal patch; the fully verified head is additionally covered by the fresh build, full suite, and cursor/network composition flow above.
pnpm --filter browse lint; pnpm --filter browse test with isolated daemon directory	Prettier, ESLint, and TypeScript passed; 27 files / 391 tests passed.	Broad regression coverage on the exact tested head.

The earlier deterministic network differential remains relevant and is owned by #2849: the built V3 and V4 CLIs each emitted 8 request / 7 response artifacts, with matching command/evaluation results and 0 normalized on-disk differences. XPath selector reads and snapshot xpathMap remain part of the supported surface; this PR removes only coordinate actions' XPath-return option.

[changeset-bot]

🦋 Changeset detected

Latest commit: 0a39cde

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

This PR includes changesets to release 1 package

Name	Type
browse	Minor

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

[cubic-dev-ai]

All reported issues were addressed across 8 files

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

Re-trigger cubic</sub>