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

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

Author: shrey150

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

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { updateCursorOverlayPosition } from "../cursor-overlay.js";
+import type { DriverPage, DriverSessionManager } from "../session-manager.js";
 import type { DriverCommandHandlers } from "./types.js";
 
 const ButtonSchema = z.enum(["left", "right", "middle"]).optional();
@@ -17,6 +19,7 @@ export const mouseHandlers: DriverCommandHandlers = {
       .parse(params);
     assertXPathUnavailable(returnXPath);
     const page = await manager.activePage();
+    await positionCursorOverlay(manager, page, x, y);
     await page.click(x, y, {
       ...(button === undefined ? {} : { button }),
       ...(clickCount === undefined ? {} : { clickCount }),
@@ -34,6 +37,7 @@ export const mouseHandlers: DriverCommandHandlers = {
       .parse(params);
     assertXPathUnavailable(returnXPath);
     const page = await manager.activePage();
+    await positionCursorOverlay(manager, page, x, y);
     await page.hover(x, y);
     return { hovered: true };
   },
@@ -50,6 +54,7 @@ export const mouseHandlers: DriverCommandHandlers = {
       .parse(params);
     assertXPathUnavailable(returnXPath);
     const page = await manager.activePage();
+    await positionCursorOverlay(manager, page, x, y);
     await page.scroll(x, y, deltaX, deltaY);
     return { scrolled: true };
   },
@@ -69,15 +74,33 @@ export const mouseHandlers: DriverCommandHandlers = {
       .parse(params);
     assertXPathUnavailable(returnXPath);
     const page = await manager.activePage();
+    await positionCursorOverlay(manager, page, fromX, fromY);
     await page.dragAndDrop(fromX, fromY, toX, toY, {
       ...(button === undefined ? {} : { button }),
       ...(delay === undefined ? {} : { delay }),
       ...(steps === undefined ? {} : { steps }),
     });
+    await positionCursorOverlay(manager, page, toX, toY);
     return { dragged: true };
   },
 };
 
+async function positionCursorOverlay(
+  manager: DriverSessionManager,
+  page: DriverPage,
+  x: number,
+  y: number,
+): Promise<void> {
+  if (!manager.isCursorOverlayEnabled(page)) return;
+  // The overlay is visual-only. A navigation can destroy its execution
+  // context, but that must not prevent or invalidate the real mouse action.
+  try {
+    await page.evaluate(updateCursorOverlayPosition, { x, y });
+  } catch {
+    // Best-effort parity with V3's cursor updates.
+  }
+}
+
 function assertXPathUnavailable(returnXPath: boolean | undefined): void {
   if (returnXPath) {
     throw new Error("Coordinate XPath lookup is not exposed by Stagehand V4");

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

@@ -2,8 +2,8 @@ import { promises as fs } from "node:fs";
 
 import { z } from "zod";
 
+import { CURSOR_OVERLAY_SCRIPT } from "../cursor-overlay.js";
 import type { DriverCommandHandlers } from "./types.js";
-import { unavailableCursorOverlay } from "./unavailable.js";
 
 export const runtimeHandlers: DriverCommandHandlers = {
   async screenshot(manager, params) {
@@ -89,7 +89,13 @@ export const runtimeHandlers: DriverCommandHandlers = {
     return { waited: true };
   },
 
-  cursor: unavailableCursorOverlay,
+  async cursor(manager) {
+    const page = await manager.activePage();
+    await page.addInitScript(CURSOR_OVERLAY_SCRIPT);
+    await page.evaluate(CURSOR_OVERLAY_SCRIPT);
+    manager.markCursorOverlayEnabled(page);
+    return { cursor: "enabled" };
+  },
 };
 
 function parseTimeoutMs(value: string | undefined): number {

packages/cli/src/lib/driver/commands/unavailable.ts

@@ -0,0 +1,80 @@
+export const CURSOR_OVERLAY_SCRIPT = `(() => {
+  if (globalThis !== globalThis.top) return;
+
+  const cursorId = "__browse_cursor_overlay__";
+  const ensureCursor = () => {
+    const existing = document.getElementById(cursorId);
+    if (existing instanceof HTMLDivElement) return existing;
+
+    const root = document.documentElement || document.body;
+    if (!root) return null;
+
+    const cursor = document.createElement("div");
+    cursor.id = cursorId;
+    cursor.setAttribute("aria-hidden", "true");
+    Object.assign(cursor.style, {
+      contain: "layout style paint",
+      height: "24px",
+      left: "0px",
+      mixBlendMode: "normal",
+      pointerEvents: "none",
+      position: "fixed",
+      top: "0px",
+      userSelect: "none",
+      width: "16px",
+      willChange: "left,top",
+      zIndex: "2147483647",
+    });
+    cursor.innerHTML =
+      '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="24" viewBox="0 0 16 24"><path d="M1 0 L1 22 L6 14 L15 14 Z" fill="black" stroke="white" stroke-width="0.7"/></svg>';
+    root.appendChild(cursor);
+    return cursor;
+  };
+
+  const moveCursor = (x, y) => {
+    const cursor = ensureCursor();
+    if (!cursor) return;
+    cursor.style.left = Math.max(0, x) + "px";
+    cursor.style.top = Math.max(0, y) + "px";
+  };
+
+  const installCursor = () => {
+    if (ensureCursor()) return;
+    if (globalThis.__browseCursorOverlayDomReadyListenerInstalled__) return;
+
+    document.addEventListener(
+      "DOMContentLoaded",
+      () => {
+        globalThis.__browseCursorOverlayDomReadyListenerInstalled__ = false;
+        ensureCursor();
+      },
+      { once: true },
+    );
+    globalThis.__browseCursorOverlayDomReadyListenerInstalled__ = true;
+  };
+
+  globalThis.__browseMoveCursorOverlay__ = moveCursor;
+  installCursor();
+  if (!globalThis.__browseCursorOverlayListenerInstalled__) {
+    document.addEventListener(
+      "mousemove",
+      (event) => {
+        moveCursor(event.clientX, event.clientY);
+      },
+      { capture: true },
+    );
+    globalThis.__browseCursorOverlayListenerInstalled__ = true;
+  }
+})()`;
+
+export function updateCursorOverlayPosition(position: {
+  x: number;
+  y: number;
+}): void {
+  const moveCursor = (
+    globalThis as typeof globalThis & {
+      __browseMoveCursorOverlay__?: (x: number, y: number) => void;
+    }
+  ).__browseMoveCursorOverlay__;
+  moveCursor?.(position.x, position.y);
+}

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

@@ -80,6 +80,7 @@ export class DriverSessionManager {
   private browserbaseIdentityValue: BrowserbaseIdentity = {};
   private consecutiveInitFailures = 0;
   private context: DriverContext | null = null;
+  private cursorOverlayPageIds = new Set<string>();
   private lastForwardedEnvSignature: string | null = null;
   private pendingEnv: ForwardedEnv | undefined;
   private initFailure: InitFailure | null = null;
@@ -207,6 +208,7 @@ export class DriverSessionManager {
     this.stagehand = null;
     this.browser = null;
     this.context = null;
+    this.cursorOverlayPageIds.clear();
     this.browserbaseIdentityValue = {};
     this.initFailure = null;
     this.consecutiveInitFailures = 0;
@@ -223,6 +225,14 @@ export class DriverSessionManager {
     return resolveCachedSelector(selector, this.refMaps);
   }
 
+  markCursorOverlayEnabled(page: DriverPage): void {
+    this.cursorOverlayPageIds.add(page.pageId);
+  }
+
+  isCursorOverlayEnabled(page: DriverPage): boolean {
+    return this.cursorOverlayPageIds.has(page.pageId);
+  }
+
   setRefMaps(refMaps: RefMaps): void {
     this.refMaps = refMaps;
   }

packages/cli/src/lib/driver/session-manager.ts

@@ -0,0 +1,123 @@
+import { createContext, runInContext } from "node:vm";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { CURSOR_OVERLAY_SCRIPT } from "../src/lib/driver/cursor-overlay.js";
+
+describe("cursor overlay", () => {
+  it("installs after DOMContentLoaded when the document root is not ready", () => {
+    const harness = createCursorHarness({ ready: false });
+
+    harness.install();
+
+    expect(harness.elements.size).toBe(0);
+    expect(harness.listeners.has("DOMContentLoaded")).toBe(true);
+
+    harness.makeDocumentReady();
+    harness.listeners.get("DOMContentLoaded")!();
+
+    expect(harness.cursor()).toBeInstanceOf(FakeDiv);
+  });
+
+  it("installs a click-through cursor once in an already-ready document", () => {
+    const harness = createCursorHarness();
+
+    harness.install();
+
+    expect(harness.cursor()?.style).toMatchObject({
+      left: "0px",
+      pointerEvents: "none",
+      position: "fixed",
+      top: "0px",
+      zIndex: "2147483647",
+    });
+    expect(harness.listeners.has("DOMContentLoaded")).toBe(false);
+    expect(harness.listeners.has("mousemove")).toBe(true);
+
+    harness.install();
+
+    expect(harness.document.createElement).toHaveBeenCalledOnce();
+    expect(harness.document.addEventListener).toHaveBeenCalledOnce();
+    expect(harness.elements.size).toBe(1);
+  });
+
+  it("moves and clamps the cursor from top-document mouse events", () => {
+    const harness = createCursorHarness();
+    harness.install();
+
+    const mousemove = harness.listeners.get("mousemove")!;
+    mousemove({ clientX: -25, clientY: 80 });
+    expect(harness.cursor()?.style).toMatchObject({
+      left: "0px",
+      top: "80px",
+    });
+
+    mousemove({ clientX: 140, clientY: -10 });
+    expect(harness.cursor()?.style).toMatchObject({
+      left: "140px",
+      top: "0px",
+    });
+  });
+
+  it("does not install inside a child frame", () => {
+    const harness = createCursorHarness({ topFrame: false });
+
+    harness.install();
+
+    expect(harness.elements.size).toBe(0);
+    expect(harness.document.createElement).not.toHaveBeenCalled();
+    expect(harness.document.addEventListener).not.toHaveBeenCalled();
+  });
+});
+
+class FakeDiv {
+  id = "";
+  innerHTML = "";
+  style: Record<string, string> = {};
+
+  setAttribute(): void {}
+}
+
+type CursorEvent = { clientX: number; clientY: number };
+type CursorListener = (event?: CursorEvent) => void;
+
+function createCursorHarness(
+  options: { ready?: boolean; topFrame?: boolean } = {},
+) {
+  const elements = new Map<string, FakeDiv>();
+  const listeners = new Map<string, CursorListener>();
+  const root = {
+    appendChild(element: FakeDiv) {
+      elements.set(element.id, element);
+    },
+  };
+  let documentElement: typeof root | null =
+    options.ready === false ? null : root;
+  const document = {
+    addEventListener: vi.fn((name: string, listener: CursorListener) => {
+      listeners.set(name, listener);
+    }),
+    body: null,
+    createElement: vi.fn(() => new FakeDiv()),
+    get documentElement() {
+      return documentElement;
+    },
+    getElementById: vi.fn((id: string) => elements.get(id) ?? null),
+  };
+  const context = createContext({ document, HTMLDivElement: FakeDiv });
+  runInContext(
+    `globalThis.top = ${options.topFrame === false ? "{}" : "globalThis"}`,
+    context,
+  );
+
+  return {
+    cursor: () => elements.get("__browse_cursor_overlay__"),
+    document,
+    elements,
+    install: () => runInContext(CURSOR_OVERLAY_SCRIPT, context),
+    listeners,
+    makeDocumentReady: () => {
+      documentElement = root;
+    },
+  };
+}