Build a TermSurf host

The host is the middle of the multi-process design. It owns panes and window layout, the client-facing Unix domain socket, routing between pane clients and engine helpers, and compositing of engine surfaces into those panes. It is not the Chromium process and not an app’s loopback UI server.

Product host: Astrohacker TermSurf.app / ahterm (Ghostty-based). Protocol name remains TermSurf. This page is role-level: implement the contracts App and Engine clients already rely on.

  client (ahweb / app)
        │  connect(TERMSURF_SOCKET)
        │  framed TermSurfMessage
        ▼
     HOST (ahterm)  ◄── listen; inject SOCKET + PANE_ID
        │  spawn/attach engine --ipc-socket=…
        │  framed TermSurfMessage
        ▼
  engine (ah-chromiumd)

Same frame format on both links: Wire.

1. Own a listen path for pane clients (Unix domain socket file).
2. When starting a shell or app in a pane, inject:
   • TERMSURF_SOCKET — path of the host listen socket
   • TERMSURF_PANE_ID — this pane’s id
3. Accept connections; read and write length-prefixed frames.
4. Handle client intents (names → Messages):

Representative host → client replies:

• HelloReply
• BrowserReady
• ModeChanged
• QueryTabsReply
• QueryLastReply
• QueryDevtoolsReply

App-side view of the same contract: App how-to.

1. Spawn or attach a helper (product: ah-chromiumd) with --ipc-socket=<path> and profile / user-data / browser-name as needed.
2. Expect ServerRegister; then create tabs and wait for TabReady.
3. Forward host→engine work (create/resize/close, navigate, input, presentation) and consume engine→host events (surfaces, URL/load, navigation state, dialogs, crashes).

Routing surface (representative):

Helper-side view: Engine how-to.

Clients speak pane. Engines speak tab. Only the host binds pane_id to tab_id. Do not make clients invent tab ids or make engines own window layout.

When the engine reports CaContext / RenderSurface (and related presentation signals), place that content into the correct pane region. The host owns splits, focus chrome, and the product window. Platform-specific layer attachment is an implementation detail of ahterm—not a second protocol.

Client and engine links use the same wire: 4-byte little-endian length + protobuf TermSurfMessage. Details: Wire. Fields: Messages.

1. Own panes, window chrome, and split layout
2. Listen for pane-client TermSurf connections on a host-owned Unix domain socket
3. Inject TERMSURF_SOCKET and TERMSURF_PANE_ID into pane children
4. Spawn or attach engine helpers with --ipc-socket (and product profile argv)
5. Bind pane_id (clients) to tab_id (engine) and route framed messages
6. Composite engine surfaces into pane regions

• Do own layout, pane ids, and routing tables.
• Do inject TERMSURF_SOCKET and TERMSURF_PANE_ID for children.
• Don’t embed a full browser engine in every client.
• Don’t invent a public TCP TermSurf API.
• Don’t let clients assign native tab ids.

• Product clients that require host injection: rust/ahweb/src/ipc.rs, bun/ahcalc/app/cli/termsurf-client.ts
• Engine attach contract: rust/ah-chromiumd/src/main.rs
• Host integration lives in the Ghostty/ahterm TermSurf surfaces (local fork checkout when present)—role contracts above are the public implementer API.
• Wire · Messages · App · Engine

With App, Engine, Host, Messages, and Wire documented, the protocol docs set covers the three implementer roles. Optional narrative: the whitepaper issue. Issue close is a separate manual gate after you accept the full goal.

Overview: TermSurf.