Build an engine helper

An engine helper is a long-lived process that implements the tab and surface side of TermSurf. It does not own pane layout. The host binds panes to tabs and composites your surfaces into the window. Pane clients (apps, ahweb) never embed your binary.

Product path today: ah-chromiumd (Chromium). Historical WebKit/Gecko helpers are not required for a current product build. This page describes the protocol role using the Chromium helper as the live reference.

  client (app / ahweb)
        │  TERMSURF_SOCKET (pane client)
        ▼
     host (ahterm)
        │  --ipc-socket=…   (engine connects here)
        │  --listen-socket=… (optional; engine may listen)
        ▼
  engine helper (ah-chromiumd)

Unlike TermSurf apps, helpers are usually spawned by the host with argv—not via TERMSURF_SOCKET alone. App how-to: App.

Also product knobs such as --incognito, --termsurf-warmup, --version / --help on the shipped helper.

1. Initialize the engine runtime and browser context.
2. If --ipc-socket is set, connect a Unix domain socket to the host (same framing as clients— Wire). Without it, the shipped helper skips IPC.
3. Send ServerRegister with profile and browser family identity.
4. Spawn a reader thread for host→engine frames.
5. If --listen-socket is set, bind, accept additional local clients, and replay state to them.

Names only—fields on Messages. Representative groups from the live Chromium dispatch path:

After register, emit tab readiness and ongoing page/surface state so the host can composite and keep chrome honest:

• ServerRegister
• TabReady
• CaContext
• RenderSurface
• UrlChanged
• LoadingState
• TitleChanged
• CursorChanged
• TargetUrlChanged
• NavigationState
• DownloadProgress
• ConsoleMessage
• JavaScriptDialogRequest
• FileChooserRequest
• HttpAuthRequest
• RendererCrashed

The engine reports surface or platform context (for example CaContext / RenderSurface) so the host can composite the tab into a pane. The host owns the window and pane geometry; you own the document and the buffer/layer identity.

• Missing --ipc-socket: shipped helper continues without IPC (no host channel).
• EOF / error on the GUI connection may quit the helper (product path treats host disconnect as fatal for the engine process).
• Optional traces: TERMSURF_ENGINE_STARTUP_TRACE / _FILE (see Wire secondary env).

• Do use the same length-prefixed TermSurfMessage frames as clients.
• Do register with ServerRegister before expecting tab work.
• Don’t invent a public TCP TermSurf port.
• Don’t claim multiple product engines ship unless the install does—Chromium is the current product path.
• Don’t implement pane splits or client SetOverlay layout—that is host/app territory.

• rust/ah-chromiumd/src/main.rs — argv, connect, ServerRegister, listen
• rust/ah-chromiumd/src/ipc.rs — framing, reader, listen accept
• rust/ah-chromiumd/src/dispatch.rs — inbound message handling
• Wire · Messages

Host how-to is still a short stub: Host. Apps: App. Overview: TermSurf.