Messages
Complete reference for all protobuf messages in termsurf.proto.
Every message on the wire is a TermSurfMessage wrapper with
one oneof msg variant.
Tab Lifecycle
GUI → Engine. Manage browser tabs.
CreateTab
| Field | Type | Description |
|---|
url | string | Initial URL to load |
pane_id | string | Terminal pane identifier |
pixel_width | uint64 | Viewport width in pixels |
pixel_height | uint64 | Viewport height in pixels |
dark | bool | Dark mode preference |
CreateDevtoolsTab
| Field | Type | Description |
|---|
pane_id | string | Terminal pane identifier |
inspected_tab_id | int64 | Tab ID to inspect |
pixel_width | uint64 | Viewport width |
pixel_height | uint64 | Viewport height |
dark | bool | Dark mode preference |
Resize
| Field | Type | Description |
|---|
tab_id | int64 | Target tab |
pixel_width | uint64 | New width |
pixel_height | uint64 | New height |
CloseTab
| Field | Type | Description |
|---|
tab_id | int64 | Tab to close |
Navigation
TUI → GUI or GUI → Engine.
Navigate
| Field | Type | Description |
|---|
tab_id | int64 | Nonzero when GUI → Engine |
pane_id | string | Nonempty when TUI → GUI |
url | string | URL to navigate to |
Input
GUI → Engine. Forward user input to the browser.
MouseEvent
| Field | Type | Description |
|---|
tab_id | int64 | Target tab |
type | string | "down" or "up" |
button | string | "left", "right", "middle" |
x | double | X coordinate |
y | double | Y coordinate |
click_count | int64 | Click count (1 = single, 2 = double) |
modifiers | uint64 | Modifier bitmask |
MouseMove
| Field | Type | Description |
|---|
tab_id | int64 | Target tab |
x | double | X coordinate |
y | double | Y coordinate |
modifiers | uint64 | Modifier bitmask |
ScrollEvent
| Field | Type | Description |
|---|
tab_id | int64 | Target tab |
x | double | Scroll position X |
y | double | Scroll position Y |
delta_x | double | Scroll delta X |
delta_y | double | Scroll delta Y |
phase | uint64 | Scroll phase |
momentum_phase | uint64 | Momentum phase |
precise | bool | Precise scrolling (trackpad) |
modifiers | uint64 | Modifier bitmask |
KeyEvent
| Field | Type | Description |
|---|
tab_id | int64 | Target tab |
type | string | "down", "up", "repeat" |
windows_key_code | int64 | Windows virtual key code |
utf8 | string | UTF-8 text generated by keystroke |
modifiers | uint64 | Modifier bitmask (Shift=1, Ctrl=2, Alt=4, Meta=8) |
State
GUI → Engine. Update browser state.
FocusChanged
| Field | Type | Description |
|---|
tab_id | int64 | Target tab |
focused | bool | Whether the browser has focus (browse mode) |
SetColorScheme
| Field | Type | Description |
|---|
tab_id | int64 | Nonzero when GUI → Engine |
pane_id | string | Nonempty when TUI → GUI |
dark | bool | Dark mode on/off |
Engine Events
Engine → GUI. Browser state changes.
ServerRegister
First message from a browser engine. Identifies its profile.
| Field | Type | Description |
|---|
profile | string | Profile name |
TabReady
Tab created and assigned an ID.
| Field | Type | Description |
|---|
pane_id | string | Pane that requested the tab |
tab_id | int64 | Chromium's tab identifier |
CaContext
GPU layer ready for compositing (macOS CALayerHost).
| Field | Type | Description |
|---|
tab_id | int64 | Source tab |
ca_context_id | uint64 | CAContext layer ID for Window Server |
pixel_width | uint64 | Rendered width |
pixel_height | uint64 | Rendered height |
UrlChanged
| Field | Type | Description |
|---|
tab_id | int64 | Source tab |
url | string | New URL |
LoadingState
| Field | Type | Description |
|---|
tab_id | int64 | Source tab |
state | string | "loading", "progress", "done", "error" |
progress | uint64 | 0–100 |
TitleChanged
| Field | Type | Description |
|---|
tab_id | int64 | Source tab |
title | string | New page title |
CursorChanged
| Field | Type | Description |
|---|
tab_id | int64 | Source tab |
cursor_type | int64 | Cursor type (pointer, text, etc.) |
TargetUrlChanged
Fired when the user hovers over a link.
| Field | Type | Description |
|---|
tab_id | int64 | Source tab |
url | string | Hovered link URL (empty = hover ended) |
Overlay
TUI → GUI. Create and manage browser overlays.
SetOverlay
Create or resize a browser overlay in a terminal pane.
| Field | Type | Description |
|---|
pane_id | string | Terminal pane identifier |
col | uint64 | Column offset in pane |
row | uint64 | Row offset in pane |
width | uint64 | Overlay width in cells |
height | uint64 | Overlay height in cells |
url | string | Initial URL |
profile | string | Browser profile name |
browsing | bool | Initial browse mode state |
browser | string | Engine name (e.g., "roamium") |
SetDevtoolsOverlay
Create a DevTools overlay inspecting an existing tab.
| Field | Type | Description |
|---|
pane_id | string | Terminal pane identifier |
col | uint64 | Column offset |
row | uint64 | Row offset |
width | uint64 | Width in cells |
height | uint64 | Height in cells |
profile | string | Profile name |
browsing | bool | Initial browse mode |
inspected_tab_id | int64 | Tab to inspect |
browser | string | Engine name |
OpenSplit
Request the GUI to open a split pane with a command.
| Field | Type | Description |
|---|
pane_id | string | Source pane |
direction | string | "horizontal" or "vertical" |
command | string | Command to run in new pane |
Mode Sync
ModeChanged
Bidirectional — sent by both TUI and GUI.
| Field | Type | Description |
|---|
browsing | bool | Whether browse mode is active |
pane_id | string | Nonempty when TUI → GUI |
BrowserReady
GUI → TUI. Provides the browser's direct connection info.
| Field | Type | Description |
|---|
pane_id | string | Pane identifier |
tab_id | int64 | Tab identifier |
browser_socket | string | Browser's listen socket path |
browser | string | Engine name |
Request/Reply
TUI ↔ GUI. Synchronous query pairs.
HelloRequest / HelloReply
Initial handshake when TUI connects.
| Message | Field | Type | Description |
|---|
| Request | pane_id | string | Pane identifier |
| Reply | homepage | string | Configured homepage URL |
| Reply | browsers | string[] | Available browser engines |
QueryLastRequest / QueryLastReply
Find the last active browser pane (for DevTools auto-targeting).
| Message | Field | Type | Description |
|---|
| Request | pane_id | string | Requesting pane |
| Request | profile | string | Filter by profile (empty = any) |
| Reply | pane_id | string | Last active pane |
| Reply | tab_id | int64 | Its tab ID |
| Reply | profile | string | Its profile |
| Reply | error | string | Error message (empty = success) |
QueryDevtoolsRequest / QueryDevtoolsReply
Check if DevTools can be opened for a tab.
| Message | Field | Type | Description |
|---|
| Request | pane_id | string | Requesting pane |
| Request | inspected_tab_id | int64 | Tab to inspect (0 = auto) |
| Request | profile | string | Profile filter |
| Reply | tab_id | int64 | Resolved tab ID |
| Reply | browser | string | Engine name |
| Reply | profile | string | Profile name |
| Reply | error | string | Error (empty = success) |
QueryTabsRequest / QueryTabsReply
List all tabs across GUI and engines.
| Message | Field | Type | Description |
|---|
| Request | pane_id | string | Requesting pane |
| Request | profile | string | Profile filter (empty = all) |
| Reply | gui_panes | int64 | GUI pane count |
| Reply | chromium_tabs | int64 | Total Chromium tabs |
| Reply | chromium_browser | int64 | Browser tab count |
| Reply | chromium_devtools | int64 | DevTools tab count |
| Reply | tabs | TabInfo[] | Tab details |
| Reply | error | string | Error (empty = success) |
