Architecture

TermSurf is a protocol, not just an app. It is a network of interchangeable components — terminals, browser engines, and TUIs — all speaking the same protobuf/Unix socket protocol.

Multi-process

TermSurf is multi-process by necessity. Each browser engine process serves exactly one profile (one set of cookies, storage, and cache). This is a hard constraint imposed by Chromium (one BrowserContext per process), and Gecko and Ladybird have the same limitation.

The multi-process design enables multi-engine support. Because each browser process is an independent program speaking the TermSurf protocol, the GUI doesn't care which engine is behind it. A user can have one pane running Roamium (Chromium), another running Surfari (WebKit), and a third running Girlbat (Ladybird) — all in the same terminal window.

Process Topology

N TUIs connect to 1 GUI. The GUI manages M browser engine processes, each serving one profile. Different profiles can use different engines.

┌─────────┐  ┌─────────┐  ┌─────────┐
│  TUI 1  │  │  TUI 2  │  │  TUI N  │    N TUIs (e.g., web)
└────┬────┘  └────┬────┘  └────┬────┘
     │            │            │
     └────────────┼────────────┘
                  │  Unix socket
           ┌──────┴──────┐
           │     GUI     │                1 GUI (Wezboard)
           └──┬───┬───┬──┘
              │   │   │
              │   │   │  Unix sockets
              │   │   │
     ┌────────┘   │   └──────┐
     │            │          │
┌────┴────┐ ┌─────┴───┐ ┌────┴────┐
│ Roamium │ │ Surfari │ │ Roamium │    M engines (one per profile)
│ profile │ │ profile │ │ profile │
│   "A"   │ │   "B"   │ │   "C"   │
└─────────┘ └─────────┘ └─────────┘

The GUI is the hub — it routes messages between TUIs and engines, manages pane layout, and composites browser overlays into the terminal window.

Unix Sockets + Protobuf

All inter-process communication uses Unix domain sockets with length-prefixed protobuf messages.

• TUI → GUI: The TUI reads the TERMSURF_SOCKET env var (set by the GUI) to discover the socket path.
• GUI → Engine: The GUI passes --ipc-socket={path} when launching browser engine processes.
• Wire format: 4-byte little-endian length prefix + serialized protobuf.
• Serialization: prost in Rust (GUI, TUI, engines), C++ protobuf in Chromium.

GPU Compositing

On macOS, browser content is rendered by Chromium's GPU process and composited into the terminal window via CALayerHost. This is zero-copy GPU rendering — the browser's framebuffer is shared with the terminal's window server through a CAContext layer ID. No pixel copying, no shared memory buffers.

Browser Engines

Each engine follows the same pattern: a C shared library wrapping the engine's embedding API (ts_* functions), linked by a Rust binary that handles Unix socket IPC, protobuf parsing, and process lifecycle. The Rust binary (~400 lines) is almost entirely reusable across engines.

Multiple GUIs

Any terminal emulator that implements the TermSurf protocol can host browser overlays. Current and planned GUIs:

• Wezboard — Active. WezTerm fork, Rust.
• Ghostboard — Archived. Will return from a fresh Ghostty fork after the protocol stabilizes.
• Kitty — Planned.
• Alacritty — Planned.
• iTerm2 — Planned.

Many TUIs

The first TUI, web, provides browser chrome (URL bar, navigation, modes) in the terminal pane. But TermSurf is a webview overlay protocol — many TUIs can embed web browsers:

• web — general-purpose web browser TUI (current)
• Future: documentation viewers, API explorers, email clients, dashboard monitors