Skip to content

ADR 0003: Desktop browser boundary

Context

Desktop needs websites and local previews beside conversations. A remote document cannot share the privileged application's native capabilities or credential store. An iframe also cannot provide general website compatibility or native history. Future agent automation needs a separate, authorized effect boundary.

Decision

Use Tauri child WebViews with a private colossus-native-browser adapter for WebView2 on Windows and WKWebView on macOS. Its safe API exposes history, bounded native metadata, temporary session sharing, and HTTP(S) system-browser handoff. The Desktop crate continues to forbid unsafe code. The adapter's native pointers are borrowed only inside the owning-thread callback.

The native manager owns up to eight tabs across workspaces. Each workspace gets a separate temporary engine profile; its tabs share that profile. Selection generations reject commands from stale workspaces. Closing the last tab ends its authenticated session. URLs and cookies are not canonical workspace state and do not enter journals.

The local main WebView alone has browser command permissions. Capability matching uses its exact WebView label, not its parent window. Commands additionally check the controller document and selected workspace. Guests cannot invoke app commands, receive workspace event broadcasts, or access the terminal and approval protocol documents. No generic JavaScript evaluation, filesystem, process, HTTP, or WebView-control command is added. The native test driver can evaluate synthetic pages only in an explicit browser-test-bridge build, never through a production IPC command.

The trusted pane displays tabs, native URL/history state, loading, errors, and pending popup destinations. Native children are hidden under detected app overlays, on focus loss, controller navigation, workspace changes, and expired viewport heartbeats. This is required because a child WebView does not obey DOM clipping or stacking.

Only HTTP(S) destinations without embedded credentials are accepted. App protocol aliases and the Desktop development origin are reserved. A loopback origin must be explicitly opened for each tab; redirects do not automatically authorize another local origin. Normal TLS verification stays enabled. These checks are not a private-network firewall: arbitrary website networking, DNS rebinding, and platform subresource differences remain outside this navigation policy. Browsing uses the user's network independently of agent tool permissions.

Automatic popups and downloads are cancelled. Popups offer an explicit new-tab action; downloads and incompatible authentication can use the system browser. Cookies are not transferred. Native site permission callbacks deny elevated access. WebView2 messaging, host objects, autofill, password saving, script dialogs, context menus, browser accelerators, and external file drops are disabled. WebKit uses a replacement delegate and removes inherited scripts and message handlers before external navigation.

Platform acceptance

Normal Windows installations offer Browser in the shared right-side tool pane. macOS still requires the browser-preview Cargo feature while its platform acceptance is completed. The native acceptance driver runs on real engines against disposable local pages, with an isolated controller profile and a generated private home. Windows installs a fixed native file-chooser cancellation policy before navigation; failure to install it fails tab creation. The policy does not expose a debugging port or a general protocol command to the renderer.

Boundary Evidence / release gate
Windows history, cookies, IPC, popups, downloads, close Native acceptance driver; each assertion must pass.
macOS compilation, history, cookies, delegates Native macOS CI and on-device acceptance remain required.
Main view, guest focus, overlays, DPI UI fixtures cover responsive controls; native visual review remains required on both platforms.
Elevated site permissions Native geolocation probe and dialog suppression exercise the deny-all permission callback. Device-specific camera, microphone, clipboard, and notification checks remain part of platform compatibility testing.
Upload, print, fullscreen escape paths Windows acceptance verifies file-picker cancellation with user activation; macOS upload callback cancels. Browser accelerators and context menus are disabled; no print or fullscreen control is offered.
Controller and engine failures Controller navigation invalidates commands; heartbeat and crash state hide guests. Forced termination and recovery need native acceptance.
Disk cleanup Private sessions end when their last view closes. Engine-owned cache handles may outlive close; abnormal-termination cache cleanup remains a follow-up.

Windows and macOS pre-merge lanes lint the adapter and run the native harness. Also test the minimum supported macOS version before enabling it by default. Keep #205 open until these gates and its acceptance criteria are demonstrated. See test strategy.

Future automation

Keep human browsing separate from model and tool execution. Future browser tools must live behind a runtime port/adapter with scoped session and tab identity, policy decisions, audit records, cancellation, bounded results, and approvals for effects where required. They may reuse engine integration without receiving the human browser's cookies or authority implicitly. A deliberate session-sharing design is a separate feature.

Consequences

This avoids bundling another browser engine, but requires platform-specific acceptance and retains Tauri's unstable child-WebView API behind one adapter. Persistent profiles, session restoration, downloads, broad site permissions, and agent automation are separate work. Human browsing does not change runtime tool authority or the domain layer.