feat(cli): emit Page.lifecycleEvent in browse cdp

[derekmeegan]

Summary

browse cdp enables the Page domain via Page.enable, but Page.enable does not by itself emit Page.lifecycleEvent — that requires a separate Page.setLifecycleEventsEnabled opt-in. As a result, consumers of browse cdp today see only Page.frameNavigated and miss the granular lifecycle milestones (init, commit, DOMContentLoaded, load, firstPaint, firstContentfulPaint, firstMeaningfulPaint, networkAlmostIdle, networkIdle).

This PR enables lifecycle events whenever the Page domain is enabled (so it covers both the default-domain set and explicit --domain Page), and adds a --pretty formatter case that prints the milestone name.

Why

These events are exactly what observability/perf tools want from the firehose:

• approximate page-ready timing (DOMContentLoaded / load)
• network-settled signal (networkIdle)
• paint timing (firstPaint / firstContentfulPaint / firstMeaningfulPaint)

Without the opt-in, all of those have to be approximated from Page.frameNavigated + Network.loadingFinished, which loses the per-milestone resolution.

Verification

Built locally with pnpm exec tsx src/index.ts cdp 9333 against a debuggable Chrome and triggered an example.com navigation. Before this patch, no Page.lifecycleEvent lines. After:

[Page.lifecycleEvent] init
[Page.lifecycleEvent] commit
[Page.lifecycleEvent] DOMContentLoaded
[Page.lifecycleEvent] firstPaint
[Page.lifecycleEvent] firstContentfulPaint
[Page.lifecycleEvent] firstMeaningfulPaint
[Page.lifecycleEvent] load
[Page.lifecycleEvent] networkAlmostIdle
[Page.lifecycleEvent] networkIdle

Default mode (NDJSON) emits the same events with full params:

{"sessionId":"…","method":"Page.lifecycleEvent","params":{"frameId":"…","loaderId":"…","name":"DOMContentLoaded","timestamp":468107.080156}}

Test plan

• pnpm --filter @browserbasehq/browse-cli typecheck passes
• pnpm --filter @browserbasehq/browse-cli eslint passes
• pnpm --filter @browserbasehq/browse-cli test — no new failures (pre-existing failures in cli.test.ts / mode.test.ts reproduce on main and are unrelated to this change)
• Manual: browse cdp <port> against a debuggable Chrome shows Page.lifecycleEvent lines after a navigation
• Manual: browse cdp <port> --pretty formats [Page.lifecycleEvent] <name>
• Manual: browse cdp <port> --domain Network --domain Console (no Page) emits no lifecycle events — the opt-in is gated correctly

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: fce3171

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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]

No issues found across 2 files

Confidence score: 5/5

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

Architecture diagram

sequenceDiagram
    participant CLI as Browse CLI
    participant WS as WebSocket Connection
    participant Browser as Chrome/Browser (CDP)
    participant UI as Console Output

    Note over CLI,Browser: Domain Initialization

    CLI->>WS: sendCDP("Page.enable")
    WS->>Browser: Enable Page domain
    
    opt domain == "Page"
        CLI->>WS: NEW: sendCDP("Page.setLifecycleEventsEnabled", {enabled: true})
        WS->>Browser: Subscribe to granular lifecycle milestones
    end

    Note over CLI,Browser: Navigation/Runtime Flow

    Browser-->>WS: Event: Page.lifecycleEvent (e.g. "DOMContentLoaded")
    WS-->>CLI: Raw JSON payload

    alt --pretty flag enabled
        CLI->>CLI: CHANGED: Parse params.name from event
        CLI->>UI: "[Page.lifecycleEvent] DOMContentLoaded"
    else Default (NDJSON)
        CLI->>UI: {"method": "Page.lifecycleEvent", "params": {...}}
    end

    Browser-->>WS: Event: Page.lifecycleEvent (e.g. "networkIdle")
    WS-->>CLI: Raw JSON payload
    
    opt --pretty flag
        CLI->>UI: "[Page.lifecycleEvent] networkIdle"
    end

Loading