refactor(cli): remove coordinate XPath return flag by shrey150 · Pull Request #2835 · browserbase/stagehand

shrey150 · 2026-08-27T20:15:44Z

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)

chore(cli): import Browse V3 baseline #2833 — exact Browse V3 baseline import
refactor(cli): migrate Browse runtime and commands to Stagehand V4 #2834 — Stagehand V4 runtime and standard command parity
feat(cli): restore cursor overlay through page.evaluate #2869 — CLI-owned cursor overlay
fix(cli): restore V3 network capture through a CDP sidecar #2849 — CLI-private CDP sidecar; V3 network parity
refactor(cli): remove coordinate XPath return flag #2835 — remove --return-xpath; supported V3 parity/release checkpoint
test(evals): exercise the workspace V4 CLI #2838 — eval and packaging integration
fix(cli): persist context names in Browserbase #2839 — managed Context names (fast-follow)
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 · 2026-08-27T20:15:52Z

🦋 Changeset detected

Latest commit: 210433c

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

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

## Summary Import `packages/cli/**` exactly from the published `browse@0.9.6` V3 release, without changing its source or runtime behavior. This is intentionally a provenance checkpoint, not a line-by-line feature review. The imported source is kept runnable by a root, version-scoped pnpm override that resolves its unchanged Stagehand dependency to `3.7.1`. #2834 removes that override and starts the V4 migration. ## Exact-source provenance - Annotated tag: `browse@0.9.6` (`548c56407431db27823a212f53475443c7e8358d`) - Release commit: `1d49a95c0c230c346f8d50647e10303d6310fcd2` - Authoritative CLI tree: `b4048badce921cf54f199f96033d9a014ef977ec` - This PR's `HEAD:packages/cli` tree: `b4048badce921cf54f199f96033d9a014ef977ec` The tag's ignored README whitespace is retained too; formatting the import would invalidate the tree proof. ## Verification - Current remote head: `a77e1507b85e3c02553f36ead6ebd0237b0cccc6`, based on current `main`. - `HEAD:packages/cli` exactly equals the published V3 tree hash above. - pnpm 11 frozen install and the repository supply-chain release-age policy pass. - Browse lint, typecheck, and build pass; the full baseline suite passes: 25 files / 366 tests. - A fresh extension build still exactly matches the Go-embedded archive: SHA-256 `8efc7d171a625cca95c02d02d369b59435fae776cae6c7dd2f6fe72eb19785c0` on both files. This specifically verifies that adding the V3 dependency graph does not perturb the current V4 extension artifact. - This layer intentionally exercises V3 through the scoped Stagehand 3.7.1 override. V4 behavior starts in #2834. ## Stack (#2872) 1. **#2833 — exact Browse V3 baseline import** 2. #2834 — Stagehand V4 runtime and standard command parity 3. #2869 — CLI-owned cursor overlay 4. #2849 — CLI-private CDP sidecar; V3 network parity 5. #2835 — remove `--return-xpath`; supported V3 parity/release checkpoint 6. #2838 — eval and packaging integration 7. #2839 — managed Context names (fast-follow) 8. #2701 — shared Functions core consumer (fast-follow) ## Review and landing boundary Review this PR by verifying the tree hashes, dependency pin, root package wiring, and changeset—not by treating the imported V3 source as newly authored code. This head deliberately imports V3 code into the V4 repository and is not independently publishable. It lands only as the base of the complete stack. The framework network-event schema proposal in #2832 is intentionally outside this landing stack.

…2834) ## Summary Migrate Browse's browser lifecycle and standard command surface together from Stagehand V3 to V4. - Replace the V3 constructor/init lifecycle with V4 browser factories and `Stagehand.create()`. - Support managed local, Browserbase remote, and attached CDP connection targets. - Preserve owned-versus-attached cleanup, daemon persistence, Browserbase session identity, and timeout handling. - Restore navigation, page information, deterministic locator actions, keyboard/mouse input, viewport/screenshot, snapshot, eval, and tab commands on V4 APIs. - Keep click/fill/select deterministic; this does not add a model-free structured `act()` path. - Make the remaining cursor, network, and coordinate-XPath gaps fail explicitly for the stack layers that restore or remove them. ## Stack (#2872) 1. #2833 — exact Browse V3 baseline import 2. **#2834 — Stagehand V4 runtime and standard command parity** 3. #2869 — CLI-owned cursor overlay 4. #2849 — CLI-private CDP sidecar; V3 network parity 5. #2835 — remove `--return-xpath`; supported V3 parity/release checkpoint 6. #2838 — eval and packaging integration 7. #2839 — managed Context names (fast-follow) 8. #2701 — shared Functions core consumer (fast-follow) ## Review shape The lifecycle and command migration remain two ordered implementation commits: 1. `389e2dae6` — V4 browser/session foundation and lifecycle ownership. 2. `b45167462` — standard command translation on that foundation. They are one PR because both commits rewrite the same nine command/test files. Reviewing their combined final diff avoids temporary deletion/stubbing followed by reimplementation, while the commits still provide useful lifecycle-versus-command checkpoints. Review follow-up `24178275f` adds narrowly scoped ownership, error-sanitization, and timeout guards. The resulting PR diff is 23 files, +988/−436. Cursor DOM injection and private CDP network transport remain separate because they are independently reviewable mechanisms and cleanly additive diffs. The legacy coordinate `returnXPath` request is still accepted here but fails explicitly until #2835 removes the option. This remains an intentionally non-publishable intermediate head. ## E2E Test Matrix Fresh post-flatten verification used the actual built CLI at final head `6f7e9c209`. Every daemon command used an isolated owner-only runtime directory. | Command / flow | Observed output | Confidence / sufficiency | | --- | --- | --- | | `pnpm install --frozen-lockfile` | Lockfile passed supply-chain policy, was already up to date, and installation completed | Proves the flattened stack resolves exactly from the committed lockfile | | `pnpm exec turbo run build --filter=browse` | Protocol, extension, Stagehand SDK, and Browse CLI built successfully (4/4 tasks) | Proves the CLI was tested against this head's protocol/extension/SDK artifacts, not stale workspace `dist` files | | Compare the rebuilt extension with `packages/sdk-go/internal/extensionassets/stagehand-extension.zip` | Exact byte match; both SHA-256 `8efc7d171a625cca95c02d02d369b59435fae776cae6c7dd2f6fe72eb19785c0`; archive manifest and package version both `1.0.2` | Confirms the TypeScript/CLI build and Go-embedded extension are synchronized | | Built CLI: `browse open <synthetic-data-url> --remote`; `browse status` | Remote browser connected and initialized; deterministic fixture loaded | Exercises production Browserbase provisioning plus the V4 daemon/session lifecycle on the exact final head | | `browse get text //h1`; `fill`; `select`; `click`; `is checked`; `wait selector`; `highlight`; `viewport`; `screenshot`; `snapshot --full` | XPath returned `Ready`; input became `Ada`; select became `b`; click produced `Clicked`; checkbox was true; PNG was 17,761 bytes; snapshot contained the fixture | Covers deterministic V4 reads, actions, waits, state, and rendering without an LLM | | Set a page marker; `tab new`; `tab list`; `tab close`; read the marker from a new CLI process | Tab count changed to 2 and the original page returned marker `yes` | Proves daemon persistence, active-tab handling, and state reuse across invocations | | Inspect the isolated runtime directory/PID; `browse stop`; poll the Browserbase session | Modes were `0700` / `0600`; the owned remote session reached `COMPLETED` | Proves owner-only daemon files and owned Browserbase resource cleanup | | `browse cursor`; `browse network on`; `browse mouse hover ... --return-xpath` | Each exited 1 with the intended explicit layer-boundary error | Confirms this intermediate layer fails honestly until the cursor, network, and flag-removal layers land | | `pnpm --filter browse test` | 25 files / 385 tests passed | Full Browse unit/integration suite on the exact final head | The runner has no Chrome/Chromium installation, so a fresh attached-CDP ownership smoke was not possible. Attached-browser non-ownership remains covered by the focused suite and is not claimed as a fresh live result here.

## Summary Restore Browse's visible cursor as a CLI-owned DOM overlay, without adding a cursor API to core Stagehand V4. - Keep the overlay implementation in one dedicated `cursor-overlay.ts` file. - Install it idempotently for the current document through `page.evaluate(CURSOR_OVERLAY_SCRIPT)` and for future navigations through `page.addInitScript(...)`. - Retry installation on `DOMContentLoaded` when the init script runs before the document root exists. - Keep injection in the top frame and update the marker from coordinate input, including when input lands inside a child frame. - Treat visual position updates as best-effort so they cannot block or invalidate real mouse input. - Preserve the V3 `browse cursor` JSON response: `{ "cursor": "enabled" }`. ## Stack (#2872) 1. #2833 — exact Browse V3 baseline import 2. #2834 — Stagehand V4 runtime and standard command parity 3. **#2869 — CLI-owned cursor overlay** 4. #2849 — CLI-private CDP sidecar; V3 network parity 5. #2835 — remove `--return-xpath`; supported V3 parity/release checkpoint 6. #2838 — eval and packaging integration 7. #2839 — managed Context names (fast-follow) 8. #2701 — shared Functions core consumer (fast-follow) ## Why this is separate The cursor is a self-contained optional visual feature with different review concerns from the combined V4 runtime/command migration: injected DOM/CSS, idempotency, event handling, and screenshot behavior. Keeping it additive on #2834 lets this feature be reviewed or reverted without disturbing browser lifecycle or commands. ## E2E Test Matrix Review-feedback verification compared the exact prior head `6a9d6aa09` with fixed implementation head `1035fbbf5` through the built CLI and real Browserbase browsers. Final head `68f6fcb2c` only expands automated coverage and does not change runtime code. Targets were the public `example.com` and `example.org` pages. | Command / flow | Observed output | Confidence / sufficiency | | --- | --- | --- | | Prior head: enable cursor, alternate 20 cross-origin navigations, inspect `#__browse_cursor_overlay__` before any mouse input | Overlay count was `0` after 20/20 navigations | Reproduces the DOM-readiness bug raised in review | | Fixed head: repeat the same 20-navigation flow | Overlay count was `1` after 20/20 navigations (0 misses) | Proves the `DOMContentLoaded` retry restores the overlay after navigation in the real browser path | | Prior head: replace the page's cursor-position callback with a throwing function, then run `browse mouse click 200 200` against an oversized synthetic button | Command exited `1`; the page's click state remained `null` | Reproduces the visual-update failure blocking real mouse input | | Fixed head: repeat the same forced overlay failure and click | CLI returned `{ "clicked": true }`; page click state became `"yes"` | Proves overlay rendering is best-effort while real input still executes | | Built CLI: `browse cursor` | `{ "cursor": "enabled" }` (prior head returned `{ "enabled": true }`) | Confirms V3-compatible output for existing scripts | | `pnpm --filter browse lint` | Passed formatting, ESLint, and TypeScript checks | Static validation on the final head | | `pnpm --filter browse test:cli` | 26 files / 393 tests passed | Full Browse suite, including DOM readiness, safe styling, idempotency, top-frame isolation, cursor positioning/clamping, and all four coordinate input commands | | `browse stop` after each live run | Completed successfully | Covers Browserbase session and daemon cleanup | The already-uploaded screenshot below remains representative visual proof of the same overlay behavior. ![Browse V4 CLI cursor overlay surviving navigation and pointing inside an iframe](https://raw.githubusercontent.com/browserbase/stagehand/agent/browse-v4-e2e-assets/e2e-proof/browse-v4-cli-cursor-navigation-iframe-20260901.png) No LLM path or customer data was involved.

This was referenced Aug 27, 2026

test(evals): exercise the workspace V4 CLI #2838

Draft

chore(cli): import Browse V3 baseline #2833

Merged

feat(stagehand): expose typed network capture events #2832

Draft

refactor(cli): migrate Browse runtime and commands to Stagehand V4 #2834

Merged

shrey150 force-pushed the agent/browse-v4-5-remove-xpath branch from fc177d4 to 58a94c2 Compare August 28, 2026 02:52

This was referenced Aug 28, 2026

fix(cli): persist context names in Browserbase #2839

Draft

feat(stagehand): expose page cursor overlay #2831

Closed

refactor(cli): consume shared Functions core #2701

Draft

shrey150 changed the base branch from agent/browse-v4-4-runtime to agent/browse-v4-network-sidecar August 28, 2026 23:37

This was referenced Aug 28, 2026

fix(cli): restore V3 network capture through a CDP sidecar #2849

Open

refactor(cli): restore Stagehand V4 command parity #2868

Merged

feat(cli): restore cursor overlay through page.evaluate #2869

Merged

shrey150 marked this pull request as ready for review September 1, 2026 17:17

cubic-dev-ai Bot reviewed Sep 1, 2026

View reviewed changes

Comment thread .changeset/brave-browsers-migrate.md

Comment thread packages/cli/src/lib/driver/commands/mouse.ts

Comment thread .changeset/brave-browsers-migrate.md Outdated

shrey150 force-pushed the agent/browse-v4-5-remove-xpath branch from 5742ba2 to 9e8e3ae Compare September 11, 2026 17:49

shrey150 force-pushed the agent/browse-v4-5-remove-xpath branch 2 times, most recently from 69cacfe to 0a39cde Compare September 11, 2026 20:18

shrey150 force-pushed the agent/browse-v4-5-remove-xpath branch from 0a39cde to 212f53f Compare September 15, 2026 23:10

shrey150 force-pushed the agent/browse-v4-5-remove-xpath branch from 212f53f to 53c6831 Compare September 15, 2026 23:31

shrey150 added 3 commits September 15, 2026 17:23

feat(cli): restore cursor overlay through page.evaluate

6a9d6aa

fix(cli): capture network traffic through a CDP sidecar

7861d65

test(cli): include network wait timeout duration

eb42f45

refactor(cli): remove coordinate XPath return flag

210433c

shrey150 force-pushed the agent/browse-v4-5-remove-xpath branch from 53c6831 to 210433c Compare September 16, 2026 00:23

Navigation Menu

refactor(cli): remove coordinate XPath return flag - #2835

refactor(cli): remove coordinate XPath return flag#2835
shrey150 wants to merge 4 commits into
agent/browse-v4-network-sidecarfrom
agent/browse-v4-5-remove-xpath

shrey150 commented Aug 27, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Aug 27, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

shrey150 commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Stack (#2872)

Review boundary

E2E Test Matrix

Uh oh!

changeset-bot Bot commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

shrey150 commented Aug 27, 2026 •

edited

Loading

changeset-bot Bot commented Aug 27, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading