TermSurf Protocol

When you open a URL or a TermSurf app inside a pane, something must coordinate layout, processes, input, and page or app state. TermSurf is that language. Astrohacker TermSurf is the product host that ships today.

This page is for protocol and app implementers. It explains the design first. Full field-level message tables are on Messages. UDS framing detail is on Wire.

Example: open example.com with a client such as ahweb.

1. The client finds the host over a local Unix domain socket and asks for browser work on a pane.
2. The host talks to an engine helper (Chromium as shipped): create or reuse a tab, size it, drive load and input.
3. The engine reports surface context, URL, title, and load state. The host composites the page into the pane.

Clients usually address work by pane. Engines usually address work by tab. The host binds the two.

• Pane — a region in the host UI (what the user sees).
• Tab — a browser document instance inside an engine process.
• Host — panes, compositing, TermSurf routing.
• Client / TermSurf app — tools that request pane work without embedding an engine.
• Engine helper — process that owns tabs and render surfaces.
• Envelope — frames use protobuf TermSurfMessage variants.

  client (ahweb / app)
        │  Unix domain socket + protobuf
        ▼
     host (ahterm)
        │
        ▼
  engine helper (ah-chromiumd, …)

Multi-process isolation is intentional: real engines are large and crashable. Clients stay thin. The protocol is the contract—not a private in-process WebView API.

• TermSurf appBuild a full-pane client (like ahcalc or ahhelp) that opens work on a pane through the host.
• Engine helperImplement a browser-engine process that owns tabs and surfaces and speaks host↔engine messages.
• Terminal hostImplement a host that owns panes, compositing, and routing between clients and engines.

Wire transport (sockets and framing) is under Wire.

• Hello — client HelloRequest → host HelloReply; later BrowserReady when a browser connection is up for the pane.
• Open a page — client SetOverlay → host CreateTab / Navigate → engine TabReady, surface, UrlChanged / LoadingState.
• Back / refresh — client NavigationAction → host forwards to engine; engine NavigationState keeps chrome honest.

Full field-level catalog of every top-level message in live termsurf.proto:

TermSurf messages

Inside TermSurf, clients get TERMSURF_SOCKET (host UDS path) and TERMSURF_PANE_ID (this pane). Frames are length-prefixed protobuf—not raw TCP. Full transport, framing, and protocol env tables: Wire. Payload fields: Messages.

Schema: rust/proto/termsurf.proto in the Astrohacker monorepo / public TermSurf source tree. Product install docs and open-source README cover how to rebuild from patches; this section is protocol identity only.