[Claimed #2010] fix: respect connectTimeoutMs when waiting for first top-level page

[github-actions]

Mirrored from external contributor PR #2010 after approval by @pirate.

Original author: @octo-patch
Original PR: #2010
Approved source head SHA: fd9ed12d2499c022b45ba30703c75082dc743a78

@octo-patch, please continue any follow-up discussion on this mirrored PR. When the external PR gets new commits, this same internal PR will be marked stale until the latest external commit is approved and refreshed here.

Original description

Fixes #1287

Problem

On slow machines, Chrome may still be setting up the first tab by the time
the CDP WebSocket handshake completes. V3Context.create() previously
waited a fixed 5 seconds (DEFAULT_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS) for
the first top-level page to register, regardless of any user-supplied
timeout, causing a TimeoutError: waitForFirstTopLevelPage (no top-level Page) timed out after 5000ms on slow hardware.

Solution

Take the maximum of localBrowserLaunchOptions.connectTimeoutMs and the
existing env-var / CI-derived default. This means users who already bump
connectTimeoutMs to accommodate a slow environment automatically get the
same patience when waiting for the initial page—no new API surface needed.

// Before
await ctx.ensureFirstTopLevelPage(getFirstTopLevelPageTimeoutMs());

// After
const firstPageTimeoutMs = Math.max(
  opts?.localBrowserLaunchOptions?.connectTimeoutMs ?? 0,
  getFirstTopLevelPageTimeoutMs(),
);
await ctx.ensureFirstTopLevelPage(firstPageTimeoutMs);

Existing escape hatches (STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS env
var, CI auto-bump to 30 s) are unchanged—this change only applies a
floor when the user has explicitly set a higher connectTimeoutMs.

Testing

• Existing unit and integration tests continue to pass (no change to default behaviour).
• Users on slow machines / WSL2 can now set connectTimeoutMs: 30000 in
  localBrowserLaunchOptions and the first-page wait will scale with it.

---

Summary by cubic

Respect connectTimeoutMs when waiting for the first top‑level page to avoid startup timeouts on slow machines. Fixes #1287.

• Bug Fixes
  • V3Context.create() now waits up to max(localBrowserLaunchOptions.connectTimeoutMs, getFirstTopLevelPageTimeoutMs()) for the first page.
  • Keeps STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS and CI defaults unchanged; no API changes.

^{Written for commit 0998c75. Summary will update on new commits. Review in cubic}

[github-actions]

This mirrored PR has been merged into main. The original external PR #2010 is now completed.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0998c75

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]

No issues found across 1 file

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.