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 |
SetGuiActive
GUI → Engine. Tells the engine whether the GUI is active/foreground.
| Field | Type | Description |
|---|
tab_id | int64 | Target tab (0 = all tabs in the receiving engine) |
active | bool | Whether the GUI is active |
reason | string | Reason for the change |
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) |
ConsoleMessage
Fired for each console log entry from the page.
| Field | Type | Description |
|---|
tab_id | int64 | Source tab |
level | string | Log level |
message | string | Log message |
line_no | int32 | Source line number |
source_id | string | Source identifier |
RendererCrashed
Fired when a tab’s renderer process terminates (crash recovery).
| Field | Type | Description |
|---|
tab_id | int64 | Affected tab |
termination_status | string | Termination status |
termination_status_code | int32 | Status code |
url | string | URL at the time of the crash |
can_reload | bool | Whether the tab can be reloaded |
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 |
| Request | browser | string | Browser engine 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) |
TabInfo
A single tab entry, returned in QueryTabsReply.tabs.
| Field | Type | Description |
|---|
id | int64 | Tab ID |
inspected_tab_id | int64 | Inspected tab ID (DevTools tabs) |
pane_id | string | Owning pane |
url | string | Current URL |
HTTP Authentication
Engine ↔ GUI/TUI. Prompt for and submit HTTP auth credentials.
HttpAuthRequest / HttpAuthReply
The engine requests credentials when a server issues an auth challenge; the TUI collects them and replies.
| Message | Field | Type | Description |
|---|
| Request | tab_id | int64 | Requesting tab |
| Request | request_id | uint64 | Correlates the reply |
| Request | url | string | Challenging URL |
| Request | auth_scheme | string | Scheme (basic, digest, …) |
| Request | challenger | string | Challenging origin |
| Request | realm | string | Auth realm |
| Request | is_proxy | bool | Proxy authentication |
| Request | first_auth_attempt | bool | First attempt for this challenge |
| Request | is_primary_main_frame_navigation | bool | Main-frame navigation |
| Request | is_navigation | bool | Triggered by a navigation |
| Reply | tab_id | int64 | Target tab |
| Reply | request_id | uint64 | Matches the request |
| Reply | accepted | bool | Whether credentials were provided |
| Reply | username | string | Username (empty if cancelled) |
| Reply | password | string | Password (empty if cancelled) |
JavaScript Dialogs
Engine ↔ GUI/TUI. Handle alert/confirm/prompt/beforeunload dialogs.
JavaScriptDialogRequest / JavaScriptDialogReply
The engine requests a dialog response; the TUI presents it and replies.
| Message | Field | Type | Description |
|---|
| Request | tab_id | int64 | Requesting tab |
| Request | request_id | uint64 | Correlates the reply |
| Request | dialog_type | string | alert, confirm, prompt, or beforeunload |
| Request | origin_url | string | Originating URL |
| Request | message | string | Dialog message |
| Request | default_prompt_text | string | Default text (prompt dialogs) |
| Reply | tab_id | int64 | Target tab |
| Reply | request_id | uint64 | Matches the request |
| Reply | accepted | bool | Accept (OK) vs. cancel |
| Reply | prompt_text | string | Entered text (prompt dialogs) |
