TermSurf messages

Protobuf payload reference: 49 top-level messages from live termsurf.proto. Transport (Unix domain sockets) is documented under Wire, not here.

About this reference

Every frame on the wire is a TermSurfMessage envelope. This page lists each top-level message type, who sends it, fields, and short implementer notes. For socket paths and framing see Wire. Concepts live on the protocol overview.

Source of truth: rust/proto/termsurf.proto. Completeness is checked against a live proto scan in webapp tests.

Envelope

TermSurfMessage

Wire envelope: every frame is exactly one typed variant in the msg oneof (protobuf on the local socket).

any → any · Every TermSurf IPC frame.

Field	Type	Tag	Meaning
create_tab	CreateTab	1	oneof msg — CreateTab variant.
create_devtools_tab	CreateDevtoolsTab	2	oneof msg — CreateDevtoolsTab variant.
resize	Resize	3	oneof msg — Resize variant.
close_tab	CloseTab	4	oneof msg — CloseTab variant.
navigate	Navigate	5	oneof msg — Navigate variant.
mouse_event	MouseEvent	6	oneof msg — MouseEvent variant.
mouse_move	MouseMove	7	oneof msg — MouseMove variant.
scroll_event	ScrollEvent	8	oneof msg — ScrollEvent variant.
key_event	KeyEvent	9	oneof msg — KeyEvent variant.
focus_changed	FocusChanged	10	oneof msg — FocusChanged variant.
set_color_scheme	SetColorScheme	11	oneof msg — SetColorScheme variant.
server_register	ServerRegister	12	oneof msg — ServerRegister variant.
tab_ready	TabReady	13	oneof msg — TabReady variant.
ca_context	CaContext	14	oneof msg — CaContext variant.
url_changed	UrlChanged	15	oneof msg — UrlChanged variant.
loading_state	LoadingState	16	oneof msg — LoadingState variant.
title_changed	TitleChanged	17	oneof msg — TitleChanged variant.
cursor_changed	CursorChanged	18	oneof msg — CursorChanged variant.
set_overlay	SetOverlay	19	oneof msg — SetOverlay variant.
set_devtools_overlay	SetDevtoolsOverlay	20	oneof msg — SetDevtoolsOverlay variant.
open_split	OpenSplit	21	oneof msg — OpenSplit variant.
mode_changed	ModeChanged	22	oneof msg — ModeChanged variant.
hello_request	HelloRequest	23	oneof msg — HelloRequest variant.
hello_reply	HelloReply	24	oneof msg — HelloReply variant.
query_last_request	QueryLastRequest	25	oneof msg — QueryLastRequest variant.
query_last_reply	QueryLastReply	26	oneof msg — QueryLastReply variant.
query_devtools_request	QueryDevtoolsRequest	27	oneof msg — QueryDevtoolsRequest variant.
query_devtools_reply	QueryDevtoolsReply	28	oneof msg — QueryDevtoolsReply variant.
query_tabs_request	QueryTabsRequest	29	oneof msg — QueryTabsRequest variant.
query_tabs_reply	QueryTabsReply	30	oneof msg — QueryTabsReply variant.
browser_ready	BrowserReady	31	oneof msg — BrowserReady variant.
target_url_changed	TargetUrlChanged	32	oneof msg — TargetUrlChanged variant.
set_gui_active	SetGuiActive	33	oneof msg — SetGuiActive variant.
javascript_dialog_request	JavaScriptDialogRequest	34	oneof msg — JavaScriptDialogRequest variant.
javascript_dialog_reply	JavaScriptDialogReply	35	oneof msg — JavaScriptDialogReply variant.
console_message	ConsoleMessage	36	oneof msg — ConsoleMessage variant.
http_auth_request	HttpAuthRequest	37	oneof msg — HttpAuthRequest variant.
http_auth_reply	HttpAuthReply	38	oneof msg — HttpAuthReply variant.
renderer_crashed	RendererCrashed	39	oneof msg — RendererCrashed variant.
render_surface	RenderSurface	43	oneof msg — RenderSurface variant.
navigation_action	NavigationAction	45	oneof msg — NavigationAction variant.
navigation_state	NavigationState	46	oneof msg — NavigationState variant.
set_presentation_visible	SetPresentationVisible	47	oneof msg — SetPresentationVisible variant.
file_chooser_request	FileChooserRequest	48	oneof msg — FileChooserRequest variant.
file_chooser_reply	FileChooserReply	49	oneof msg — FileChooserReply variant.
external_file_drop	ExternalFileDrop	50	oneof msg — ExternalFileDrop variant.
download_progress	DownloadProgress	51	oneof msg — DownloadProgress variant.

Session and hello

ModeChanged

Browse vs control mode for a pane (browsing flag and optional pane id).

host ↔ client

Field	Type	Tag	Meaning
browsing	bool	1	browsing (bool).
pane_id	string	2	pane_id (string).

BrowserReady

Host reports that a browser connection is ready for a pane (tab id, optional engine socket).

host → client

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).
tab_id	int64	2	tab_id (int64).
browser_socket	string	3	browser_socket (string).
browser	string	4	browser (string).

HelloRequest

Client greets the host and identifies the pane it is binding to.

client → host

Related: HelloReply

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).

HelloReply

Host answers hello with homepage URL and available browser family names.

host → client

Related: HelloRequest

Field	Type	Tag	Meaning
homepage	string	1	homepage (string).
browsers	repeated string	2	browsers (repeated string).

Overlay and splits (client → host)

SetOverlay

Place or update a browser overlay on a pane (grid geometry, URL, profile, engine family).

client → host

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).
col	uint64	2	Grid column of the overlay.
row	uint64	3	Grid row of the overlay.
width	uint64	4	Grid width in cells.
height	uint64	5	Grid height in cells.
url	string	6	url (string).
profile	string	7	Browser profile name.
browsing	bool	8	Whether the pane should enter browsing mode.
browser	string	9	Engine family hint (e.g. chromium).

SetDevtoolsOverlay

Place a DevTools overlay inspecting a tab on a pane.

client → host

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).
col	uint64	2	col (uint64).
row	uint64	3	row (uint64).
width	uint64	4	width (uint64).
height	uint64	5	height (uint64).
profile	string	6	profile (string).
browsing	bool	7	browsing (bool).
inspected_tab_id	int64	8	inspected_tab_id (int64).
browser	string	9	browser (string).

OpenSplit

Request a host split from a pane (direction and optional command).

client → host

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).
direction	string	2	horizontal or vertical.
command	string	3	Optional command for the new region.

Tab lifecycle (host → engine)

CreateTab

Create a browser tab for a pane with pixel size and dark preference.

host → engine

Field	Type	Tag	Meaning
url	string	1	Initial URL for the tab.
pane_id	string	2	Host pane this tab is bound to.
pixel_width	uint64	3	Backing pixel width.
pixel_height	uint64	4	Backing pixel height.
dark	bool	5	Prefer dark color scheme when true.

CreateDevtoolsTab

Create a DevTools tab inspecting another tab.

host → engine

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).
inspected_tab_id	int64	2	inspected_tab_id (int64).
pixel_width	uint64	3	pixel_width (uint64).
pixel_height	uint64	4	pixel_height (uint64).
dark	bool	5	dark (bool).

Resize

Resize a tab and supply screen DIP geometry for the engine.

host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
pixel_width	uint64	2	pixel_width (uint64).
pixel_height	uint64	3	pixel_height (uint64).
screen_x	double	4	screen_x (double).
screen_y	double	5	screen_y (double).
screen_width	double	6	screen_width (double).
screen_height	double	7	screen_height (double).
screen_scale	double	8	screen_scale (double).

CloseTab

Close a native tab by tab id.

host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).

Navigation

Navigate

Load a URL: pane_id when client→host; tab_id when host→engine.

client → host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
pane_id	string	2	pane_id (string).
url	string	3	url (string).

NavigationAction

Semantic navigation: back, forward, refresh, or refresh_ignore_cache (hard reload).

client → host → engine

Related: NavigationState

Field	Type	Tag	Meaning
tab_id	int64	1	Native tab when host→engine; 0 on client→host.
pane_id	string	2	Owning pane on client→host; empty host→engine.
action	string	3	One of: back, forward, refresh, refresh_ignore_cache.
request_id	uint64	4	Zero client→host; nonzero host→engine for refresh correlation.

NavigationState

Authoritative can_go_back / can_go_forward / can_refresh for one tab.

engine → host → client

Related: NavigationAction

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
can_go_back	bool	2	can_go_back (bool).
can_go_forward	bool	3	can_go_forward (bool).
can_refresh	bool	4	can_refresh (bool).

Input

MouseEvent

Mouse button down/up for a tab (button, position, click count, modifiers).

host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
type	string	2	type (string).
button	string	3	button (string).
x	double	4	x (double).
y	double	5	y (double).
click_count	int64	6	click_count (int64).
modifiers	uint64	7	modifiers (uint64).

MouseMove

Mouse move for a tab.

host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
x	double	2	x (double).
y	double	3	y (double).
modifiers	uint64	4	modifiers (uint64).

ScrollEvent

Scroll/wheel for a tab including phase and momentum fields.

host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
x	double	2	x (double).
y	double	3	y (double).
delta_x	double	4	delta_x (double).
delta_y	double	5	delta_y (double).
phase	uint64	6	phase (uint64).
momentum_phase	uint64	7	momentum_phase (uint64).
precise	bool	8	precise (bool).
modifiers	uint64	9	modifiers (uint64).

KeyEvent

Key down/up/repeat with Windows key code, UTF-8 text, and modifiers.

host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
type	string	2	type (string).
windows_key_code	int64	3	windows_key_code (int64).
utf8	string	4	utf8 (string).
modifiers	uint64	5	modifiers (uint64).

Presentation and state

SetPresentationVisible

Whether compositor output for the tab is actually hosted/visible (not focus).

host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
visible	bool	2	visible (bool).

FocusChanged

Whether a tab is focused for input.

host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
focused	bool	2	focused (bool).

SetColorScheme

Dark/light preference for a pane or tab.

client → host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
pane_id	string	2	pane_id (string).
dark	bool	3	dark (bool).

SetGuiActive

Whether the GUI considers the tab (or all tabs) active, with a reason string.

host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
active	bool	2	active (bool).
reason	string	3	reason (string).

Engine events and surfaces

ServerRegister

Engine process registers profile and browser family identity.

engine → host

Field	Type	Tag	Meaning
profile	string	1	profile (string).
browser	string	2	browser (string).

TabReady

Tab is ready; binds pane_id to tab_id.

engine → host

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).
tab_id	int64	2	tab_id (int64).

CaContext

macOS CALayer context id and pixel size for compositing.

engine → host

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
ca_context_id	uint64	2	ca_context_id (uint64).
pixel_width	uint64	3	pixel_width (uint64).
pixel_height	uint64	4	pixel_height (uint64).

RenderSurface

Generic render surface metadata (size, format, generation, attachment).

engine → host

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
pixel_width	uint64	2	pixel_width (uint64).
pixel_height	uint64	3	pixel_height (uint64).
bytes_per_row	uint64	4	bytes_per_row (uint64).
pixel_format	uint32	5	pixel_format (uint32).
generation	uint64	6	generation (uint64).
attachment_id	uint64	7	attachment_id (uint64).

UrlChanged

Document URL changed for a tab.

engine → host → client

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
url	string	2	url (string).

LoadingState

Load lifecycle: loading/progress/done/error plus optional progress and refresh correlation id.

engine → host → client

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
state	string	2	loading \| progress \| done \| error.
progress	uint64	3	0–100 when known.
navigation_request_id	uint64	4	Nonzero only for correlated refresh.

DownloadProgress

Download lifecycle for pane surface progress (active/done/error/cancelled; total 0 = unknown).

engine → host → client

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
state	string	2	active \| done \| error \| cancelled.
received_bytes	uint64	3	received_bytes (uint64).
total_bytes	uint64	4	0 means unknown size (indeterminate UI).

TitleChanged

Document title changed.

engine → host → client

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
title	string	2	title (string).

CursorChanged

CSS/OS cursor type for the tab surface.

engine → host

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
cursor_type	int64	2	cursor_type (int64).

TargetUrlChanged

Hovered link target URL (empty when hover ends).

engine → host

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
url	string	2	url (string).

Queries

QueryLastRequest

Query last tab association for a pane/profile.

client → host

Related: QueryLastReply

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).
profile	string	2	profile (string).

QueryLastReply

Answer for QueryLastRequest (tab id, profile, or error).

host → client

Related: QueryLastRequest

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).
tab_id	int64	2	tab_id (int64).
profile	string	3	profile (string).
error	string	4	error (string).

QueryDevtoolsRequest

Ask host/engine for DevTools tab info for an inspected tab.

client → host

Related: QueryDevtoolsReply

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).
inspected_tab_id	int64	2	inspected_tab_id (int64).
profile	string	3	profile (string).
browser	string	4	browser (string).

QueryDevtoolsReply

DevTools query result (tab id, browser, profile, or error).

host → client

Related: QueryDevtoolsRequest

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
error	string	2	error (string).
browser	string	3	browser (string).
profile	string	4	profile (string).

QueryTabsRequest

List tabs for a pane/profile.

client → host

Related: QueryTabsReply, TabInfo

Field	Type	Tag	Meaning
pane_id	string	1	pane_id (string).
profile	string	2	profile (string).

TabInfo

One tab row: id, optional inspected tab, pane, and URL.

embedded in QueryTabsReply

Related: QueryTabsReply

Field	Type	Tag	Meaning
id	int64	1	id (int64).
inspected_tab_id	int64	2	inspected_tab_id (int64).
pane_id	string	3	pane_id (string).
url	string	4	url (string).

QueryTabsReply

Tab list plus aggregate counts (panes, chromium tabs, etc.).

host → client

Related: QueryTabsRequest, TabInfo

Field	Type	Tag	Meaning
gui_panes	int64	1	gui_panes (int64).
chromium_tabs	int64	2	chromium_tabs (int64).
chromium_browser	int64	3	chromium_browser (int64).
chromium_devtools	int64	4	chromium_devtools (int64).
tabs	repeated TabInfo	5	tabs (repeated TabInfo).
error	string	6	error (string).

Dialogs, chooser, drop, console, auth

JavaScriptDialogRequest

JS alert/confirm/prompt/beforeunload request parked for product UI.

engine → host → client

Related: JavaScriptDialogReply

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
request_id	uint64	2	request_id (uint64).
dialog_type	string	3	alert \| confirm \| prompt \| beforeunload.
origin_url	string	4	origin_url (string).
message	string	5	message (string).
default_prompt_text	string	6	default_prompt_text (string).

JavaScriptDialogReply

Answer a JS dialog (accepted + optional prompt text).

client → host → engine

Related: JavaScriptDialogRequest

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
request_id	uint64	2	request_id (uint64).
accepted	bool	3	accepted (bool).
prompt_text	string	4	prompt_text (string).

FileChooserRequest

Engine parks file select; host owns the native open panel.

engine → host

Related: FileChooserReply

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
request_id	uint64	2	request_id (uint64).
mode	string	3	open \| open_multiple.
accept	repeated string	4	Optional MIME/extensions from the page.
origin_url	string	5	origin_url (string).

FileChooserReply

File chooser result: cancel or absolute paths.

host → engine

Related: FileChooserRequest

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
request_id	uint64	2	request_id (uint64).
accepted	bool	3	accepted (bool).
paths	repeated string	4	paths (repeated string).

ExternalFileDrop

Finder/OS file drag phases onto the overlay (enter/over/leave/drop).

host → engine

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
paths	repeated string	2	Absolute file paths from the OS drop.
x	double	3	x (double).
y	double	4	y (double).
phase	string	5	enter \| over \| leave \| drop (empty treated as drop).

ConsoleMessage

Console line from the page (level, message, line, source).

engine → host → client

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
level	string	2	level (string).
message	string	3	message (string).
line_no	int32	4	line_no (int32).
source_id	string	5	source_id (string).

HttpAuthRequest

HTTP auth challenge details for product UI.

engine → host → client

Related: HttpAuthReply

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
request_id	uint64	2	request_id (uint64).
url	string	3	url (string).
auth_scheme	string	4	auth_scheme (string).
challenger	string	5	challenger (string).
realm	string	6	realm (string).
is_proxy	bool	7	is_proxy (bool).
first_auth_attempt	bool	8	first_auth_attempt (bool).
is_primary_main_frame_navigation	bool	9	is_primary_main_frame_navigation (bool).
is_navigation	bool	10	is_navigation (bool).

HttpAuthReply

Credentials or cancel for HTTP auth.

client → host → engine

Related: HttpAuthRequest

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
request_id	uint64	2	request_id (uint64).
accepted	bool	3	accepted (bool).
username	string	4	username (string).
password	string	5	password (string).

Crashes and recovery

RendererCrashed

Renderer process crash/termination with optional reload affordance.

engine → host → client

Field	Type	Tag	Meaning
tab_id	int64	1	tab_id (int64).
termination_status	string	2	termination_status (string).
termination_status_code	int32	3	termination_status_code (int32).
url	string	4	url (string).
can_reload	bool	5	can_reload (bool).