feat(webview): add dev-only browser bridge for standalone Chrome UI

[hnbdr]

Related GitHub Issue

N/A — developer-only tooling; per repo triage, internal DX tooling does not require a pre-existing issue.

Description

Adds an opt-in browser bridge: the Zoo Code UI can run as the main page of a regular Chrome tab instead of a nested VSCode webview iframe.

Why: inside the webview iframe the UI shares one DevTools panel with the rest of the VSCode window and cannot load DevTools extensions, which makes inspection awkward. As a top-level document the UI gets its own DevTools with installable extensions (React DevTools etc.), and the extension IPC becomes plain socket.io traffic that can be monitored live in the Network tab as websocket frames.

How:

• src/core/webview/browserBridge.ts — BrowserBridgeServer: a loopback-only (127.0.0.1) socket.io server, owned one-per-ClineProvider. Port 0 by default so the OS assigns a unique free port per bridge (override with ROO_BROWSER_BRIDGE_PORT); the port is passed to the tab as ?bridgePort=.... A virtual webview adapter keeps the existing WebviewMessage / ExtensionMessage protocol unchanged — no protocol forks anywhere.
• src/activate/registerCommands.ts — registers the zoo-code.openInBrowser command only when ROO_BROWSER_BRIDGE=1 is set in the extension host env (added to the .vscode/launch.json dev config) and extensionMode === Development. It is intentionally not contributed in package.json, so end users never see a command-palette entry or toolbar button.
• src/core/webview/ClineProvider.ts — enableBrowserBridge() irreversibly switches a provider to its bridge (re-clicking the command reuses the existing port instead of leaking a second server). The real iframe then renders a static placeholder with a clickable link back to the browser tab, so the two environments never run React simultaneously. The bridge is disposed together with the provider.
• webview-ui/src/utils/vscode.ts — when acquireVsCodeApi is absent but ?bridgePort= is present, VSCodeAPIWrapper routes messages over socket.io; inbound extensionMessage events are re-dispatched through window.postMessage so existing message consumers work unchanged.
• webview-ui/src/index.css — dark-theme fallback values for the --vscode-* custom properties that VS Code normally injects, so the standalone tab renders sanely.
• New deps: socket.io (extension) / socket.io-client (webview).

Reviewer notes:

• Security boundary: server binds to 127.0.0.1 only, CORS restricted to local origins, and the whole path is gated behind Development mode + env var.
• One provider → one bridge → one port; multiple sidebar panels / browser tabs can run simultaneously, each on its own port.

Test Procedure

• Unit tests (new): cd src && npx vitest run core/webview/__tests__/browserBridge.spec.ts activate/__tests__/registerCommands.spec.ts core/webview/__tests__/ClineProvider.spec.ts — covers port allocation, virtual webview message routing, listener single-registration, placeholder rendering, dev-only command registration, bridge reuse/dispose.
• pnpm lint and pnpm check-types pass (also enforced by pre-commit / pre-push hooks).
• Manual: pnpm install → run webview dev server (pnpm --dir webview-ui dev) → F5 "Run and Debug → Run Extension" → in the extension host's command palette run Zoo Code: Open in Browser → Chrome opens http://localhost:5173/?bridgePort=<port> with the full UI as the main page; the sidebar iframe shows a placeholder link; DevTools → Network → WS shows every webview↔extension message pair live.

Pre-Submission Checklist

• Issue Linked: N/A for dev-only tooling (see above).
• Scope: Single focused feature — the browser bridge; no drive-by refactors.
• Self-Review: I have performed a thorough self-review of my code.
• Testing: New and/or updated tests have been added to cover my changes.
• Visual Snapshot (UI changes only): N/A — no user-visible rendered state changes (placeholder and theme fallbacks appear only in the dev-only browser mode).
• Documentation Impact: Considered — no user-facing docs needed (development-only tooling).
• Contribution Guidelines: I have read and agree to the Contributor Guidelines.

Documentation Updates

• No documentation updates are required (developer-only tooling; usage is documented in code comments).

Additional Notes

Local run of the changed-code mutation gate (scripts/stryker-diff.mjs) currently fails to spawn on Windows because spawnSync cannot execute the .cmd pnpm shims for vitest/stryker (ENOENT) — this is an infrastructure limitation of the gate script on Windows, not a code issue; CI (Linux) should run it normally. Happy to add a Stryker disable directive or focused tests in follow-up commits if the gate flags specific lines.

Get in Touch

GitHub: @hnbdr (Discord on request via GitHub/issue thread)

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• coderabbit-review-active

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 7b9ce564-ccae-4f4b-9c6a-b81643e0367e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}

[github-actions]

Review status

Thanks for contributing. This comment tracks the review sequence and the next action.

Current step: Mark the PR ready. Required CI must pass before CodeRabbit starts.

Review-state labels are managed by this workflow; do not edit them manually.

[codecov]

Codecov Report

❌ Patch coverage is 68.80000% with 39 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
webview-ui/src/utils/vscode.ts	15.78%	13 Missing and 3 partials ⚠️
src/core/webview/browserBridge.ts	77.04%	11 Missing and 3 partials ⚠️
src/core/webview/ClineProvider.ts	80.76%	3 Missing and 2 partials ⚠️
src/activate/registerCommands.ts	78.94%	3 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!