Skip to content

[v2]: deprecate drawOverlay param #1396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
seanmcguire12 merged 1 commit into from
Dec 9, 2025
Merged

[v2]: deprecate drawOverlay param #1396

seanmcguire12 merged 1 commit into from
Dec 9, 2025

Conversation

@seanmcguire12
Copy link
Member

@seanmcguire12 seanmcguire12 commented Dec 9, 2025 •
edited by cubic-dev-ai bot
Loading

why

  • this is largely unused, and often results in cryptic page.evaluate() errors

what changed

  • removed the drawOverlay param from observe
  • removed the clearOverlay() and drawObserveOverlay() functions
  • added a warning log stating that the parameter is now a no-op

Summary by cubic

Deprecated the observe drawOverlay option and removed overlay rendering to prevent frequent page.evaluate errors. The option is now a no-op and logs a warning when used.

  • Refactors
    • Removed drawObserveOverlay and clearOverlays helpers; dropped overlay clearing calls from StagehandPage.
    • Observe handler logs a deprecation warning if drawOverlay is provided.
    • Updated types to mark drawOverlay as deprecated.

Written for commit c324836. Summary will update automatically on new commits.

@changeset-bot
Copy link

changeset-bot bot commented Dec 9, 2025

🦋 Changeset detected

Latest commit: c324836

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

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

@greptile-apps
Copy link
Contributor

greptile-apps bot commented Dec 9, 2025

Greptile Overview

Greptile Summary

Deprecated the drawOverlay parameter from the observe() method to eliminate cryptic page.evaluate() errors caused by overlay drawing logic.

  • Removed drawObserveOverlay() and clearOverlays() utility functions from lib/utils.ts
  • Removed clearOverlays() calls from act(), extract(), and observe() methods in StagehandPage.ts
  • Added deprecation warning in observeHandler.ts when drawOverlay is used
  • Marked drawOverlay as @deprecated in TypeScript interfaces
  • Documentation in docs/references/observe.mdx still references the deprecated parameter and should be updated

Confidence Score: 5/5

  • This PR is safe to merge with minimal risk
  • Clean deprecation implementation with proper warnings, no breaking changes since parameter becomes a no-op, and all related code properly removed
  • Documentation file docs/references/observe.mdx should be updated to reflect the deprecation

Important Files Changed

File Analysis

Filename Score Overview
.changeset/rich-cooks-rule.md 5/5 Added changeset documenting the deprecation of drawOverlay parameter
types/stagehand.ts 5/5 Added @deprecated JSDoc annotation to drawOverlay property in ObserveOptions interface
lib/handlers/observeHandler.ts 5/5 Added deprecation warning for drawOverlay parameter, removed overlay drawing logic
lib/StagehandPage.ts 5/5 Removed clearOverlays() calls from act(), extract(), and observe() methods
lib/utils.ts 5/5 Removed drawObserveOverlay() and clearOverlays() functions along with unused imports

Sequence Diagram

sequenceDiagram
    participant User
    participant StagehandPage
    participant ObserveHandler
    participant Utils
    
    Note over User,Utils: Before (with drawOverlay)
    User->>StagehandPage: observe({ drawOverlay: true })
    StagehandPage->>Utils: clearOverlays()
    Utils->>Utils: Remove existing overlays from DOM
    StagehandPage->>ObserveHandler: observe({ drawOverlay: true })
    ObserveHandler->>ObserveHandler: Process elements
    ObserveHandler->>Utils: drawObserveOverlay()
    Utils->>Utils: Draw yellow overlays on elements
    ObserveHandler-->>User: Return ObserveResult[]
    
    Note over User,Utils: After (deprecated)
    User->>StagehandPage: observe({ drawOverlay: true })
    StagehandPage->>ObserveHandler: observe({ drawOverlay: true })
    ObserveHandler->>ObserveHandler: Log deprecation warning
    ObserveHandler->>ObserveHandler: Process elements (no overlay)
    ObserveHandler-->>User: Return ObserveResult[]
Loading

greptile-apps[bot]
greptile-apps bot reviewed Dec 9, 2025
View reviewed changes
Copy link
Contributor

@greptile-apps greptile-apps bot left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional Comments (3)

  1. docs/references/observe.mdx, line 75-79 (link)

    style: documentation should be updated to mark drawOverlay as deprecated

  2. docs/references/observe.mdx, line 33 (link)

    style: remove drawOverlay from the interface definition or mark it as deprecated

  3. docs/references/observe.mdx, line 133 (link)

    style: remove usage of deprecated drawOverlay parameter from example code

4 files reviewed, 3 comments

Edit Code Review Agent Settings | Greptile

cubic-dev-ai[bot]
cubic-dev-ai bot reviewed Dec 9, 2025
View reviewed changes
Copy link
Contributor

@cubic-dev-ai cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 5 files

@seanmcguire12 seanmcguire12 merged commit b7bc0b6 into v2 Dec 9, 2025
16 checks passed
@github-actions github-actions bot mentioned this pull request Dec 9, 2025
Merged
seanmcguire12 pushed a commit that referenced this pull request Dec 9, 2025
@github-actions
Version Packages (#1397)
f2db0bb 
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to v2, this PR will
be updated.


# Releases
## @browserbasehq/[email protected]

### Patch Changes

- [#1396](#1396)
[`b7bc0b6`](b7bc0b6)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - deprecate
drawOverlay parameter in observe

## @browserbasehq/[email protected]

### Patch Changes

- Updated dependencies
\[[`b7bc0b6`](b7bc0b6)]:
    -   @browserbasehq/[email protected]

## @browserbasehq/[email protected]

### Patch Changes

- Updated dependencies
\[[`b7bc0b6`](b7bc0b6)]:
    -   @browserbasehq/[email protected]


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Publishes a patch release across the Stagehand packages. The main change
deprecates the drawOverlay parameter in observe in
@browserbasehq/stagehand v2.5.6.

- **Dependencies**
  - @browserbasehq/stagehand → 2.5.6 (deprecates observe drawOverlay)
  - @browserbasehq/stagehand-evals → 1.1.6 (deps update)
  - @browserbasehq/stagehand-examples → 1.0.15 (deps update)

- **Migration**
- Stop passing drawOverlay to observe. No behavior change now; removal
planned in a future release.

<sup>Written for commit 00540fd.
Summary will update automatically on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cubic-dev-ai cubic-dev-ai[bot] cubic-dev-ai[bot] left review comments

@miguelg719 miguelg719 miguelg719 approved these changes

+1 more reviewer

@greptile-apps greptile-apps[bot] greptile-apps[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@seanmcguire12 @miguelg719