fix: stabilize browser launcher requests

[2wheeh]

Summary

• wait for the platform browser launcher to spawn and observe early handoff failures
• surface launcher failures as App.Target.BrowserLaunchError
• return explicit host, browser, and url outcomes from Target.open
• bound launcher observation so long-running xdg-open processes do not block the CLI
• update playground contracts, documentation, roadmap, and the daegari patch changeset

Contract

• browser requested means the URL was dispatched to the platform launcher
• it does not guarantee that a browser tab loaded or rendered

Verification

• pnpm check

Summary by CodeRabbit

• New Features

  • Opening a target now reports separate host and browser outcomes, plus a capability-bearing URL.
  • Browser launch requests are supported across platforms.
  • Added typed BrowserLaunchError reporting for launcher or handoff failures.

• Bug Fixes

  • Browser-launch failures now provide consistent, actionable error handling.

• Documentation

  • Updated lifecycle, architecture, and roadmap documentation to clarify browser request behavior and launch guarantees.

[coderabbitai]

Warning

Review limit reached

@2wheeh, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 30 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a53e1f0b-dde8-43c5-bcb0-eda65ff44263

📥 Commits

Reviewing files that changed from the base of the PR and between 1574a3f and 770f9b4.

📒 Files selected for processing (6)

• .changeset/quiet-browsers-request.md
• .github/workflows/test.yaml
• .github/workflows/verify.yaml
• packages/daegari/src/core/internal/browser-launcher.test.ts
• packages/daegari/src/core/internal/browser-launcher.ts
• packages/vite/package.json

📝 Walkthrough

Walkthrough

The PR adds cross-platform browser launching with typed failure reporting. Target.open() now returns separate browser-dispatch and Host lifecycle outcomes, with updated documentation and playground assertions.

Changes

Browser launch outcomes

Layer / File(s)	Summary
Public open contract packages/daegari/src/app/target.ts, packages/daegari/src/app/create.test.ts, packages/daegari/src/app/exports.test-d.ts, README.md, docs/v0.2-architecture.md, ROADMAP.md, .changeset/*	Adds BrowserLaunchError and changes open() results to browser, host, and url. Documentation and type tests describe the new contract.
Cross-platform browser launcher packages/daegari/src/core/internal/browser-launcher.ts, packages/daegari/src/core/internal/browser-launcher.test.ts	Selects platform-specific commands, starts detached processes, handles handoff timeouts, and maps launcher failures to BrowserLaunchError.
Runtime integration and consumers packages/daegari/src/core/internal/runtime.ts, playgrounds/greeting/scripts/*, playgrounds/mdv-poc/scripts/smoke.mjs, playgrounds/molt-poc/scripts/smoke.mjs	Invokes browser launching when enabled and updates lifecycle and smoke assertions to use separate host and browser fields.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Target.open
  participant requestBrowser
  participant PlatformLauncher
  Target.open->>requestBrowser: requestBrowser(url)
  requestBrowser->>PlatformLauncher: spawn detached browser command
  PlatformLauncher-->>requestBrowser: report handoff or failure
  requestBrowser-->>Target.open: resolve or throw BrowserLaunchError

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary browser launcher stabilization changes.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/browser-launcher-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.changeset/quiet-browsers-request.md:
- Around line 2-5: Update the changeset for the package entry “daegari” to use
the applicable breaking version bump instead of “patch,” reflecting the removed
status result contract and newly separated host and browser fields.

In `@packages/daegari/src/core/internal/browser-launcher.ts`:
- Around line 25-28: Update launcher() for win32 to avoid cmd.exe parsing of
URLs by using a shell-free Windows protocol handler or equivalent direct launch
mechanism. Preserve URL query text, including metacharacters such as ? and &, as
browser input, and add Windows coverage for absolute same-origin paths
containing query parameters.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e21bbdd1-c85c-4811-ba55-206cfe8ceb06

📥 Commits

Reviewing files that changed from the base of the PR and between 5801cfa and 1574a3f.

📒 Files selected for processing (14)

• .changeset/quiet-browsers-request.md
• README.md
• ROADMAP.md
• docs/v0.2-architecture.md
• packages/daegari/src/app/create.test.ts
• packages/daegari/src/app/exports.test-d.ts
• packages/daegari/src/app/target.ts
• packages/daegari/src/core/internal/browser-launcher.test.ts
• packages/daegari/src/core/internal/browser-launcher.ts
• packages/daegari/src/core/internal/runtime.ts
• playgrounds/greeting/scripts/lifecycle.mjs
• playgrounds/greeting/scripts/smoke.mjs
• playgrounds/mdv-poc/scripts/smoke.mjs
• playgrounds/molt-poc/scripts/smoke.mjs

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates Target open() to return explicit Host and browser-request outcomes and adds a cross-platform browser launcher with typed failures.

Changes:

• Replace status with host and add browser outcome to App.Target.open() return type
• Add requestBrowser() implementation + Vitest coverage and wire it into runtime open()
• Update playground smoke scripts and docs to match the new contract and error behavior

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
playgrounds/molt-poc/scripts/smoke.mjs	Updates assertions to new open() JSON shape (host, browser)
playgrounds/mdv-poc/scripts/smoke.mjs	Updates assertions to new open() JSON shape (host, browser)
playgrounds/greeting/scripts/smoke.mjs	Updates assertions to new open() JSON shape (host, browser)
playgrounds/greeting/scripts/lifecycle.mjs	Updates assertions and concurrency check to use host outcome
packages/daegari/src/core/internal/runtime.ts	Uses requestBrowser() and returns { browser, host, url } from open()
packages/daegari/src/core/internal/browser-launcher.ts	New cross-platform browser launcher with typed errors and bounded handoff
packages/daegari/src/core/internal/browser-launcher.test.ts	Tests launcher command dispatch, failure mapping, and handoff timeout behavior
packages/daegari/src/app/target.ts	Documents/introduces BrowserLaunchError and updates open.ReturnType
packages/daegari/src/app/exports.test-d.ts	Updates public type contract assertions for open()
packages/daegari/src/app/create.test.ts	Adds test coverage for BrowserLaunchError code
docs/v0.2-architecture.md	Updates architecture doc to new open() results + error semantics
ROADMAP.md	Marks browser-launch stabilization as complete
README.md	Updates consumer docs for new open() result fields + error behavior
.changeset/quiet-browsers-request.md	Declares release note for the change

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.