tranquil
Docs

ADR-0002: A full Chromium browser, not a VS Code-style preview pane

Status: Active · Date: 2026-07-07

Context

Tranquil is a browser-first workspace: the embedded browser is a primary surface people work in all day, not an occasional preview of a doc or a localhost app. Having chosen a Pulsar/Electron base (ADR-0001), the open question was how much browser to build.

The natural reference point was VS Code’s Simple Browser — an <iframe src=url> inside a webview-backed panel, offering a URL box and back/forward and essentially nothing else. That model is adequate for previewing your own app on localhost, but it collapses the moment it is asked to be a general browsing surface.

Decision

Build the in-app browser as a full Chromium Electron <webview>, rendered as a first-class, serializable, splittable/dockable Pulsar pane item (the tranquil-browser package, forked from Atom’s browser-plus) — not a VS Code Simple Browser-style iframe preview.

Options considered

  • Option A: Full Chromium <webview> browser as a first-class pane item (chosen) — a real browser tab with its own chrome (URL bar with autocomplete, back/forward/reload, tabs, bookmarks, history, find-in-page, DevTools). It loads arbitrary real sites like a browser, and it becomes the substrate for per-window session isolation, CDP-based HAR capture/replay, page script/CSS injection, and IPC keyboard forwarding. Forking the mature browser-plus package meant most of that chrome already existed. Con: it is a heavier surface to own, with Electron <webview> foot-guns to manage.
  • Option B: VS Code Simple Browser-style iframe preview — cheap, simple, sandboxed. Rejected: an <iframe> is blocked by X-Frame-Options and CSP frame-ancestors on most real sites (Google, banks, most SaaS), so it cannot be a general browser; it shares one session, so no logging into the same domain under different accounts; and it offers no DevTools, no HAR, no page scripting, and no rich host↔guest channel. Fine for previewing your own app, wrong for a browser-first product.
  • Option C: Hand off to the OS browser (or a separate BrowserWindow) — gives real browsing, but it is not integrated: pages can’t be split or docked beside code, aren’t serialized into the workspace, and offer no in-app automation or HAR capture. It breaks the single-window workspace model Tranquil is built around.

Consequences

  • Easier: browser pages are genuine workspace citizens — they split, dock, serialize and restore across reloads, and reopen with cmd-shift-t. They load any real site, and they become the foundation for per-window sessions (ADR-0005), HAR capture/replay (ADR-0004), and package-driven automation via the browser-cross / addPlugin service.
  • Harder / new risks: Tranquil now owns a browser’s worth of surface area (chrome, history, favorites, autocomplete) plus Electron <webview> quirks — a focused guest steals keystrokes from the host keymap (mitigated by IPC key forwarding), DevTools can’t be embedded for an OOPIF guest, and we track Chromium/Electron security ourselves. Some capabilities (HAR capture, session partitions) also depend on a customized main process, not the package alone.
  • Re-evaluation triggers: Electron deprecating or removing the <webview> tag (it is discouraged upstream) would force a migration to WebContentsView / BrowserView; or the maintenance cost of the forked browser-plus code growing past the value it delivers.

See also