integrated-browser
Integrated Browser Architecture
The integrated browser ("browserView") embeds a real Chromium browser in VS Code, backed by an Electron WebContentsView. It renders live pages, presents each as an editor tab, and lets agents drive those pages through tools. It powers the in-product browser tab and the agent "browser" tools. It is not the old extensions/simple-browser (an iframe-in-a-webview), which now delegates to this on desktop.
It's a heavyweight, security-sensitive, multi-process primitive, and almost every design decision follows from that. This file describes the load-bearing ideas that rarely change. It deliberately does not enumerate current features/tools/commands/settings — those churn; the live features/ and tools/ folders are the source of truth. Build the mental model here, then go read the specific code you're changing.
The one idea everything follows from
A page is a native WebContentsView that only the main process may create, own, and position. Nothing else can touch it directly. It's owned by the main process and painted by the OS compositor on top of the workbench DOM — not inside it. Everything else works around this:
- The renderer (editor UI + agent tools) can't hold the page; it holds a model/proxy and talks to main over IPC.
- Playwright is heavy and long-lived, so it runs in the shared process, reaching the page over IPC too.
- The page paints over the DOM, so the workbench choreographs alignment, z-order, focus, and screenshots by hand.