fix: waitForDomNetworkQuiet() can hang forever

[seanmcguire12]

why

• this PR fixes an issue where waitForDomNetworkQuiet() does not resolve
• this issue is caused by 2-3 underlying issues:
  • the first issue is that frame.waitForLoadState() was not listening for the correct lifecycle events from CDP. instead of listening for DOMContentLoaded, it was listening for domcontentloaded
  • the second issue is that frame.waitForLoadState() did not accept a timeout parameter
  • the third issue is that waitForDomNetworkQuiet() did not include the call to frame.waitForLoadState() as part of the total time that it waits for

what changed

• added string normalization of incoming lifecycle events from CDP in frame.waitForLoadState() (fixes the first issue)
• added a timeout parameter to frame.waitForLoadState()
• within waitForDomNetworkQuiet(), I included the call to frame.waitForLoadState() as part of the total time that it waits for

test plan

• existing unit tests & regression evals should be ok

[changeset-bot]

🦋 Changeset detected

Latest commit: 094ce98

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

This PR includes changesets to release 2 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	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

[greptile-apps]

Greptile Summary

• Fixed waitForDomNetworkQuiet() hanging indefinitely by normalizing CDP lifecycle event names (DOMContentLoaded → domcontentloaded) and adding timeout support to frame.waitForLoadState()
• Improved timeout accounting by tracking elapsed time during waitForLoadState() and using remaining budget for network monitoring phase

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are well-contained bug fixes that address a critical hanging issue. The implementation correctly normalizes CDP event names, adds proper timeout handling with rejection on timeout, and properly accounts for elapsed time across function boundaries. The logic is sound and defensive.
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/understudy/frame.ts	Fixed lifecycle event matching by normalizing CDP event names to lowercase and added timeout parameter to prevent indefinite hangs
packages/core/lib/v3/handlers/handlerUtils/actHandlerUtils.ts	Improved timeout handling in waitForDomNetworkQuiet() by accounting for time spent in waitForLoadState() and using remaining budget

Sequence Diagram

sequenceDiagram
    participant User
    participant ActHandler
    participant waitForDomNetworkQuiet
    participant Frame
    participant CDP

    User->>ActHandler: "act(instruction)"
    ActHandler->>waitForDomNetworkQuiet: "waitForDomNetworkQuiet(frame, timeout)"
    Note over waitForDomNetworkQuiet: "Start timer (settleStart)"
    waitForDomNetworkQuiet->>Frame: "evaluate('document.readyState')"
    Frame->>CDP: "Runtime.evaluate"
    CDP-->>Frame: "readyState value"
    Frame-->>waitForDomNetworkQuiet: "readyState result"
    alt "Document not ready"
        waitForDomNetworkQuiet->>Frame: "waitForLoadState('domcontentloaded', timeout)"
        Frame->>CDP: "Page.enable"
        Frame->>CDP: "Listen for Page.lifecycleEvent"
        CDP-->>Frame: "LifecycleEvent(name='DOMContentLoaded')"
        Note over Frame: "Normalize to lowercase"
        Note over Frame: "Match 'domcontentloaded'"
        Frame-->>waitForDomNetworkQuiet: "Load state reached"
    end
    Note over waitForDomNetworkQuiet: "Calculate elapsed & remainingBudget"
    waitForDomNetworkQuiet->>CDP: "Network.enable, Page.enable"
    Note over waitForDomNetworkQuiet: "Monitor network requests"
    waitForDomNetworkQuiet->>CDP: "Listen for Network events"
    CDP-->>waitForDomNetworkQuiet: "Network quiet (500ms)"
    waitForDomNetworkQuiet-->>ActHandler: "DOM settled"
    ActHandler-->>User: "Action completed"

Loading

[greptile-apps]

_{2 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile
React with 👍 or 👎 to share your feedback on this new summary format}