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

[shrey150]

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. 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)

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.

No LLM path or customer data was involved.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 20f96c6

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 4 files

Architecture diagram

sequenceDiagram
    participant User as Browse CLI User
    participant CLI as Browse CLI
    participant Runtime as Runtime Command Handlers
    participant Manager as Page Manager
    participant Page as Active Browser Page
    participant DOM as Page DOM Overlay
    participant Browser as Browser Input and Renderer

    Note over CLI,DOM: CLI-owned cursor visualization (no Stagehand core cursor API)

    User->>CLI: browse cursor
    CLI->>Runtime: Dispatch cursor command
    Runtime->>Manager: Resolve activePage()
    Manager-->>Runtime: Active page
    Runtime->>Page: evaluate(CURSOR_OVERLAY_SCRIPT)
    Page->>DOM: Ensure fixed overlay exists

    alt Overlay already installed
        DOM-->>Page: Reuse __browse_cursor_overlay__
    else Overlay not installed
        DOM->>DOM: Create fixed SVG cursor element
        DOM->>DOM: Set aria-hidden, z-index, pointer-events none
        DOM->>DOM: Append overlay to document root
        DOM->>DOM: Install capture-phase mousemove listener
    end

    Page-->>Runtime: Evaluation complete
    Runtime-->>CLI: Return enabled=true
    CLI-->>User: Cursor overlay enabled

    User->>CLI: browse mouse hover x y
    CLI->>Browser: Move mouse to viewport coordinates
    Browser->>DOM: Dispatch mousemove event
    DOM->>DOM: Clamp clientX and clientY to non-negative values
    DOM->>DOM: Update fixed overlay left and top

    User->>CLI: browse screenshot --path cursor.png
    CLI->>Page: Capture current page
    Page->>Browser: Render DOM and overlay
    Browser-->>CLI: Screenshot including visible cursor
    CLI-->>User: Save cursor.png

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

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

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

Re-trigger cubic</sub>

[AzamAbdul]

Feedback from Astra labeled with my take:

seems like a good idea to change to DOM readiness

• The overlay can disappear after navigation until the next mouse action.
  The initialization script runs at document creation, when document.documentElement and document.body can still be absent. ensureCursor() then returns without scheduling another attempt. There is no DOMContentLoaded handler or retry, so a subsequent screenshot can have no cursor. V3 explicitly waited for DOM readiness and retried installation.
  Fix: retry installation once the DOM is ready.
  Reference:

  stagehand/packages/cli/src/lib/driver/cursor-overlay.ts

  Line 5 in 75d8e04

  const ensureCursor = () => {

not sure about this one

• A cursor rendering failure can prevent the actual mouse action.
  Click, hover, scroll, and drag all await the overlay update before performing the action. If that extra page.evaluate() fails—for example, during navigation—the command aborts before sending its mouse input. The branch already treats the final drag overlay update as optional, but does not do so for these initial updates. V3 swallowed cursor-update errors throughout.
  Fix: make visual position updates best-effort while continuing to propagate errors from the actual mouse operation.
  Reference:

  stagehand/packages/cli/src/lib/driver/commands/mouse.ts

  Line 22 in 75d8e04

  await positionCursorOverlay(manager, page, x, y);

lets definitely do this to support backwards compatibility

• browse cursor changes its JSON output unnecessarily.
  V3 returned { "cursor": "enabled" }; this branch returns { "enabled": true }. The command prints that result directly, so existing scripts checking .cursor break.
  Fix: preserve the old response unless this is an intentional API change.
  Reference:

  stagehand/packages/cli/src/lib/driver/commands/runtime.ts

  Line 92 in 75d8e04

  async cursor(manager) {

[shrey150]

Addressed the three points from #2869 (review) in 1035fbbf5:

• defer overlay installation to DOMContentLoaded when the document root is not available yet;
• make cursor-position rendering best-effort while preserving failures from the real mouse operation;
• restore the V3 response shape: { "cursor": "enabled" }.

I also reproduced the review findings on the prior head with the built CLI and a real Browserbase browser. The old code missed the overlay after 20/20 cross-origin navigations and aborted a coordinate click when the visual update was forced to fail. On this commit the overlay survived 20/20 navigations, the same forced visual failure still delivered the click, and the page recorded the click. Full Browse verification is green: lint passed and 26 test files / 390 tests passed. The PR description now contains the complete before/after matrix.

[cubic-dev-ai]

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

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

Re-trigger cubic</sub>