Roamium

Roamium is the Chromium browser engine binary for TermSurf. It wraps libtermsurf_chromium (a C shared library built from the Chromium fork) in a ~400-line Rust binary that handles Unix socket IPC, protobuf message dispatch, and process lifecycle.

How It Works

The GUI (Wezboard) spawns one Roamium process per browser profile. Each process serves exactly one profile — one set of cookies, storage, and cache. This is a hard constraint imposed by Chromium's BrowserContext.

Startup sequence:

GUI spawns Roamium with --ipc-socket, --user-data-dir, and --listen-socket
Roamium calls ts_content_main to enter Chromium's message loop
Chromium initializes, fires the on_initialized callback
Roamium creates a BrowserContext and connects to the GUI socket
Roamium sends ServerRegister with its profile name
GUI sends CreateTab with a URL and dimensions
Chromium creates a WebContents, fires on_tab_ready
Roamium sends TabReady back to the GUI
Chromium renders and sends CaContext (GPU layer ID) to the GUI

Architecture

Roamium follows a two-layer pattern designed to be reusable across browser engines:

libtermsurf_chromium — a C shared library that wraps Chromium's embedding API. Exports ts_* functions for lifecycle, navigation, input forwarding, and state management. Built from the Chromium fork.
Roamium — a Rust binary that links the C library and handles IPC. Parses command-line args, connects to the GUI socket, dispatches protobuf messages to ts_* FFI calls, and relays Chromium callbacks back as protobuf messages.

Source Layout

File	Purpose
`main.rs`	Entry point, arg parsing, callback registration, Chromium message loop
`dispatch.rs`	Message dispatch — routes protobuf messages to FFI calls, relays callbacks
`ipc.rs`	Unix socket connection, length-prefixed protobuf framing, reader loop
`ffi.rs`	FFI bindings to `libtermsurf_chromium` C functions

C API

The ts_* functions exported by libtermsurf_chromium:

Lifecycle

Function	Purpose
`ts_content_main`	Enter Chromium's message loop (blocks)
`ts_set_on_initialized`	Register initialization callback
`ts_post_task`	Post a task to the UI thread
`ts_quit`	Shut down Chromium

Profiles and Tabs

Function	Purpose
`ts_create_browser_context`	Create a profile (BrowserContext)
`ts_create_web_contents`	Create a browser tab
`ts_create_devtools_web_contents`	Create a DevTools tab
`ts_destroy_web_contents`	Close a tab

Navigation and Input

Function	Purpose
`ts_load_url`	Navigate to a URL
`ts_forward_mouse_event`	Forward mouse click
`ts_forward_mouse_move`	Forward mouse movement
`ts_forward_scroll_event`	Forward scroll
`ts_forward_key_event`	Forward keyboard input

State

Function	Purpose
`ts_set_focus`	Set focus state (browse/control mode)
`ts_set_color_scheme`	Set dark/light mode
`ts_set_view_size`	Resize the viewport

Callbacks

Chromium fires callbacks on the UI thread. Roamium converts them to protobuf messages and sends them to the GUI:

Callback	Protobuf Message	Purpose
`on_tab_ready`	`TabReady`	Tab created, tab_id assigned
`on_ca_context_id`	`CaContext`	GPU layer ready for compositing
`on_url_changed`	`UrlChanged`	Page navigated
`on_loading_state`	`LoadingState`	Loading started/finished
`on_title_changed`	`TitleChanged`	Page title updated
`on_cursor_changed`	`CursorChanged`	Cursor type changed (pointer, text, etc.)
`on_target_url_changed`	`TargetUrlChanged`	Link hover target

Multi-Engine Pattern

Roamium is the first engine binary, but the architecture is designed for multiple engines. Each engine follows the same pattern:

A C shared library wrapping the engine's embedding API (ts_* functions)
A Rust binary (~400 lines) handling IPC and protobuf

The Rust binary is almost entirely reusable — only the C library changes per engine. Planned engines: Surfari (WebKit), Waterwolf (Gecko), Girlbat (Ladybird).

Installation

Roamium installs to /usr/local/roamium/ alongside Chromium's dylibs, .pak resource files, and ICU data. The GUI knows to look for it there.

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