Add hover method #1406

tkattkat · 2025-12-12T20:03:34Z

why

We had page.click(x, y) for coordinate-based clicking but no equivalent for hovering. Also, the agent's will need hover abilities

what changed

Added page.hover(x, y, options?) to dispatch mouse move events at coordinates

test plan

Added page-hover.spec.ts with 6 tests covering:

Mouseover event triggers
Hover doesn't click
returnXpath option
CSS :hover pseudo-class activation
Multiple sequential hovers

Summary by cubic

Adds page.hover(x, y, options?) for coordinate-based hovering. Enables mouseover and CSS :hover without clicking, with an option to return the hovered element’s XPath.

New Features
- Dispatches mouseMoved at absolute page coordinates via CDP.
- Supports options.returnXpath to return the element XPath.
- Moves cursor without triggering click; activates mouseover and :hover states.

^{Written for commit 5b3b39f. Summary will update automatically on new commits.}

changeset-bot · 2025-12-12T20:03:37Z

🦋 Changeset detected

Latest commit: 5b3b39f

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

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

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

1 issue found across 3 files

Prompt for AI agents (all 1 issues)


Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/core/lib/v3/understudy/page.ts">

<violation number="1" location="packages/core/lib/v3/understudy/page.ts:1409">
P2: The log message &quot;hover failed&quot; is misleading - only the xpath resolution failed, not the hover action itself. The actual hover (cursor update and mouseMoved event) executes successfully after this catch block. This is also inconsistent with `click` and `scroll` which use silent catch blocks with `// best-effort` comments for the same xpath resolution failure case.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

packages/core/lib/v3/understudy/page.ts

greptile-apps · 2025-12-12T20:09:00Z

Greptile Overview

Greptile Summary

Added page.hover(x, y, options?) for coordinate-based hovering, mirroring the existing page.click() API. This enables AI agents to trigger mouseover events and CSS :hover states without clicking.

Key Changes

Implemented hover() method in packages/core/lib/v3/understudy/page.ts:1383-1447 using TypeScript function overloads for type safety
Dispatches mouseMoved CDP event at specified coordinates to trigger browser hover behaviors
Supports optional returnXpath parameter to return the XPath of the hovered element
Added comprehensive test suite with 6 tests covering mouseover events, CSS :hover activation, XPath resolution, and multiple sequential hovers

Implementation Notes

Follows the same pattern as existing click() and scroll() methods for consistency
Uses resolveXpathForLocation() for optional element identification at coordinates
Properly updates cursor position via updateCursor() before dispatching mouse events

Confidence Score: 4/5

Safe to merge with minor style inconsistency in error handling
The implementation correctly follows established patterns from click() and scroll() methods, has comprehensive test coverage (6 tests), and properly handles TypeScript overloads for type safety. Score reduced by 1 due to inconsistent error handling in the catch block (logs at level 0 vs silent catch in similar methods).
No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
.changeset/rude-steaks-lie.md	5/5	Added changeset for patch release documenting the new `page.hover()` method
packages/core/lib/v3/tests/page-hover.spec.ts	5/5	Comprehensive test suite with 6 tests covering mouseover events, CSS :hover states, returnXpath option, and multiple hovers
packages/core/lib/v3/understudy/page.ts	4/5	Implemented `hover(x, y, options?)` method following existing patterns for coordinate-based actions; includes optional xpath resolution and CDP mouse event dispatching

Sequence Diagram

sequenceDiagram
    participant Client
    participant Page
    participant resolveXpathForLocation
    participant updateCursor
    participant CDP as CDP Input Domain
    
    Client->>Page: hover(x, y, options?)
    
    alt options.returnXpath === true
        Page->>resolveXpathForLocation: resolve element at (x, y)
        resolveXpathForLocation-->>Page: hit.absoluteXPath or undefined
        Note over Page: Log hit details (level 2) or failure (level 0)
    end
    
    Page->>updateCursor: update cursor position to (x, y)
    updateCursor-->>Page: cursor updated
    
    Page->>CDP: dispatchMouseEvent({type: "mouseMoved", x, y, button: "none"})
    CDP-->>Page: mouse event dispatched
    Note over CDP: Triggers mouseover, CSS :hover, etc.
    
    alt options.returnXpath === true
        Page-->>Client: return xpathResult ?? ""
    else
        Page-->>Client: return void
    end

greptile-apps

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

packages/core/lib/v3/understudy/page.ts

@tkattkat

tkattkat added 2 commits December 12, 2025 12:01

add hover method

83b77c6

format

aed8d31

cubic-dev-ai bot reviewed Dec 12, 2025

View reviewed changes

packages/core/lib/v3/understudy/page.ts Show resolved Hide resolved

greptile-apps bot reviewed Dec 12, 2025

View reviewed changes

packages/core/lib/v3/understudy/page.ts Show resolved Hide resolved

tkattkat added 2 commits December 12, 2025 12:27

update log message

29fdd8f

update log level

5b3b39f

seanmcguire12 approved these changes Dec 16, 2025

View reviewed changes

tkattkat merged commit b40ae11 into main Dec 16, 2025
20 checks passed

This was referenced Dec 16, 2025

Version Packages #1414

Merged

Version Packages CloudEngineHub/stagehand#1

Open

Version Packages kenchikuliu/stagehand#1

Open

Version Packages shaneholloman/stagehand#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add hover method #1406

Add hover method #1406

Uh oh!

tkattkat commented Dec 12, 2025 •

edited by cubic-dev-ai bot

Loading

Uh oh!

changeset-bot bot commented Dec 12, 2025 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

Uh oh!

greptile-apps bot commented Dec 12, 2025

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add hover method #1406

Add hover method #1406

Uh oh!

Conversation

tkattkat commented Dec 12, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Summary by cubic

Uh oh!

changeset-bot bot commented Dec 12, 2025 • 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

Choose a reason for hiding this comment

Uh oh!

Uh oh!

greptile-apps bot commented Dec 12, 2025

Greptile Overview

Greptile Summary

Key Changes

Implementation Notes

Confidence Score: 4/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tkattkat commented Dec 12, 2025 •

edited by cubic-dev-ai bot

Loading

changeset-bot bot commented Dec 12, 2025 •

edited

Loading