TermSurf Protocol
Open real browser panes from tools in Astrohacker TermSurf—one shared language between the host, clients, and engine helpers.
What it enables
When you open a URL inside a TermSurf pane, something must coordinate layout, the browser process, input, and page events. TermSurf is that language. Astrohacker TermSurf and its tools use it so a command like ahweb can drive a real engine. Each tool does not invent its own wire format.
This page is for protocol and app implementers, and for builders who want the mental model. It explains the multi-process design first. Then it gives a reference catalog of every message in the live protobuf. It is not a field-level 1.0 spec.
One happy path
Example: open example.com in a pane.
- Client (e.g.
ahweb) talks to the TermSurf host: hello / session, then place a browser overlay on this pane (SetOverlay, navigate, profile and engine hints). - The host talks to an engine helper (Chromium, WebKit, or Ladybird as shipped): create or reuse a tab, size it, and send input when required.
- The engine reports back: tab ready, surface and context for compositing, URL, title, and load state.
- The host composites the surface into the pane. The client can query tabs or open DevTools through the same protocol family.
Clients usually address work by pane. Engines usually address work by tab. The host sits in the middle and binds the two.
Concepts
- Pane — a region in the TermSurf UI (what the user sees). Clients name panes when they request overlays, splits, or queries.
- Tab — a browser document instance inside an engine process. Host↔engine messages typically carry a tab id once the engine has created it.
- Host — the Astrohacker TermSurf process: panes, compositing, routing between clients and engines.
- Client — a tool or app that asks the host for browser work (
ahweb, TermSurf apps, automation harnesses). - Engine helper — a browser-engine process that owns tabs and surfaces, registers with the host, and streams page state.
- Envelope — every frame is a
TermSurfMessagewhoseoneofholds exactly one payload message.
Multi-process architecture
TermSurf is multi-process on purpose. Real engines stay isolated. Many clients can share one host without embedding a browser in every binary.
- Host ↔ client — overlays, navigation requests, splits, apps, hello and queries, some dialogs and auth replies used by harnesses.
- Host ↔ engine — tab create, resize, and close; input; surface metadata; URL, title, load, and related events.
Product docs for installable tools: TermSurf, Web. This page is the protocol, not the install guide.
Message catalog (reference)
Every top-level message in rust/proto/termsurf.proto, grouped by role in the story above. Short descriptions only—not field tables.
Wire envelope
- TermSurfMessage
- Wire envelope: every TermSurf frame is one of these; payload is a single oneof variant.
Session handshake
- HelloRequest
- Client → host: session hello for a pane (capability / handshake start).
- HelloReply
- Host → client: hello response with homepage and available browser families.
- BrowserReady
- Host → client: browser connection ready with tab id, socket, and engine name.
- ModeChanged
- Host ↔ client: browsing vs non-browsing mode for a pane.
Client ↔ host (panes and overlays)
- SetOverlay
- Client → host: place or update a browser overlay in a pane (geometry, URL, profile, engine).
- SetDevtoolsOverlay
- Client → host: place or update a DevTools overlay for an inspected tab.
- OpenSplit
- Client → host: open a split in a pane with direction and optional command.
- Navigate
- Load a URL (client → host by pane id, or host → engine by tab id).
- NavigationAction
- Back, forward, or refresh (client → host by pane id, or host → engine by tab id).
- NavigationState
- Engine → host (and host → client): whether back, forward, and refresh are available for a tab.
- SetColorScheme
- Prefer light or dark (client → host by pane id, or host → engine by tab id).
Host ↔ engine (tabs and surfaces)
- CreateTab
- Host → engine: create a browser tab for a pane with URL, size, and color scheme.
- CreateDevtoolsTab
- Host → engine: open a DevTools tab attached to an inspected tab.
- Resize
- Host → engine: update tab pixel size and optional screen geometry for layout.
- CloseTab
- Host → engine: close a tab by tab id.
- ServerRegister
- Engine → host: announce a browser process with profile and browser family.
- TabReady
- Engine → host: tab is ready; binds pane id to engine tab id.
- CaContext
- Engine → host: Core Animation (or equivalent) surface context id and dimensions for compositing.
- RenderSurface
- Engine → host: generic render-surface metadata (size, format, generation, optional attachment).
- SetGuiActive
- Host → engine: mark one or all tabs active/inactive with an optional reason.
Input (host → engine)
- FocusChanged
- Host → engine: whether a tab has keyboard focus.
- MouseEvent
- Host → engine: mouse button down/up with position, click count, and modifiers.
- MouseMove
- Host → engine: mouse move for a tab.
- ScrollEvent
- Host → engine: scroll wheel / trackpad deltas with optional phase and precision.
- KeyEvent
- Host → engine: key down/up/repeat with key code, UTF-8 text, and modifiers.
Page and load events (engine → host)
- UrlChanged
- Engine → host: committed or current URL for a tab.
- LoadingState
- Engine → host: load progress state (loading, progress, done, error) and optional percent.
- TitleChanged
- Engine → host: document title for a tab.
- CursorChanged
- Engine → host: CSS cursor type for a tab.
- TargetUrlChanged
- Engine → host: link hover target URL (empty when hover ends).
Dialogs, auth, console, crashes
- JavaScriptDialogRequest
- Engine → client/harness: alert/confirm/prompt/beforeunload dialog needs a response.
- JavaScriptDialogReply
- Client/harness → engine: accept/dismiss a JS dialog and optional prompt text.
- ConsoleMessage
- Engine → client/harness: console log line with level, message, and source location.
- HttpAuthRequest
- Engine → client/harness: HTTP authentication challenge needs credentials or cancel.
- HttpAuthReply
- Client/harness → engine: supply or reject credentials for an auth challenge.
- RendererCrashed
- Engine → client/harness: renderer process terminated; includes status and reload hint.
Queries and replies
- QueryLastRequest
- Client → host: ask for the last tab associated with a pane/profile.
- QueryLastReply
- Host → client: last tab id/profile or error for QueryLastRequest.
- QueryDevtoolsRequest
- Client → host: look up DevTools attachment for an inspected tab.
- QueryDevtoolsReply
- Host → client: DevTools tab id, engine/profile, or error.
- QueryTabsRequest
- Client → host: list tabs known for a pane/profile.
- TabInfo
- Tab summary type used inside QueryTabsReply (id, inspected id, pane, URL)—not a standalone wire oneof by itself in casual use.
- QueryTabsReply
- Host → client: tab inventory counts and TabInfo list, or error.
Source and limits
- Wire definition:
rust/proto/termsurf.protoin the Astrohacker repository. - Product host: Astrohacker TermSurf. The protocol is also named TermSurf; this page is the protocol, not the install guide.
- This page is not a versioned protocol 1.0 freeze, a field-by-field schema, or a multi-page reference set. Those are later work under the TermSurf protocol program.