Wezboard

Wezboard is a WezTerm fork with integrated browser overlay support. It is the active GUI for TermSurf — a full terminal emulator that also renders web pages via GPU-composited browser overlays.

What Wezboard Adds

Wezboard inherits all of WezTerm's features (splits, tabs, multiplexer, GPU rendering, Lua config) and adds the TermSurf protocol:

Protocol server — listens on a Unix socket for TUI and browser engine connections
Browser overlay rendering — composites Chromium's GPU output into terminal panes via CALayerHost (macOS)
Input forwarding — routes keyboard, mouse, and scroll events to browser engines in Browse mode
Browser process management — spawns, monitors, and shuts down Roamium processes (one per profile)
Mode synchronization — tracks browse/control mode per pane and syncs state with TUIs and engines
DevTools — opens Chrome DevTools in a split pane
Split pane borders — visual distinction between focused and unfocused split panes

How It Works

When Wezboard launches, it starts a TermSurf socket listener. The socket path is exposed to child processes via the TERMSURF_SOCKET environment variable. When a TUI like web runs in a pane, it connects to this socket and sends SetOverlay to request a browser.

Wezboard then spawns a browser engine process (Roamium) for the requested profile, routes protobuf messages between the TUI and engine, and renders the browser's GPU output as a CALayerHost overlay positioned within the terminal pane.

GPU Compositing

On macOS, browser content is rendered by Chromium's GPU process into a CAContext. Wezboard receives the context ID via the CaContext protobuf message and creates a CALayerHost to display it. This is zero-copy GPU rendering — no pixel data is transferred, only a layer ID.

The overlay is positioned as a subview of the terminal's content view, sharing the same coordinate space as the terminal rendering. Position coordinates come from the same paint_pane() function that positions terminal text, ensuring pixel-perfect alignment.

Source Layout

TermSurf Protocol Module

All TermSurf-specific code lives in wezboard-gui/src/termsurf/:

File	Purpose
`listener.rs`	Unix socket listener, accepts TUI and engine connections
`conn.rs`	Connection handler — message dispatch, server register, tab lifecycle, overlay management
`state.rs`	Shared state — pane registry, server registry, tab-to-pane mapping
`input.rs`	Input forwarding — converts WezTerm key/mouse events to protobuf and sends to Chromium
`metrics.rs`	Cell metrics — provides cell dimensions for pixel coordinate calculations

WezTerm Core

Directory	Purpose
`wezboard/`	Main application entry point and CLI
`wezboard-gui/`	GUI rendering, window management, overlay compositing
`mux/`	Terminal multiplexer core
`termwiz/`	Terminal widget library
`config/`	Configuration parsing (Lua-based, inherited from WezTerm)

Build and Install

scripts/build.sh wezboard --release
sudo scripts/install.sh wezboard

This installs:

/Applications/TermSurf Wezboard.app — the GUI application
/usr/local/bin/wezboard — the CLI (for wezboard cli subcommands)

Configuration

Wezboard uses WezTerm's Lua configuration system. The config file is at ~/.config/wezboard/wezboard.lua (or ~/.wezboard.lua). All WezTerm configuration options are supported. See Configuration for TermSurf-specific settings.

WezTerm Compatibility

Wezboard is a full WezTerm fork — all WezTerm features work: splits, tabs, copy mode, font rendering, Lua scripting, multiplexer, SSH, serial, and more. The TermSurf protocol additions are layered on top without modifying WezTerm's core terminal functionality.

WezTerm keybindings, color schemes, and configuration all work as documented in the WezTerm docs.