@kolu/surface

Declare live state once.

A surface is a typed, reactive slice of live state — a handful of values, lists, streams, events, and callable procedures — that you declare once. From that one declaration the framework derives the wire contract, wires the server, and binds the client. You stop hand-writing “fetch, then subscribe, then reconcile, then reconnect” and just read the values.

The same declaration works whether the state lives in the browser tab, in a long-lived daemon, or on a fleet of machines across an ssh network. You learn it once, in one process, and the same shape carries all the way out.

Three strata

The docs are organised as three layers. Basics is the foundation. Daemons and Multi-host each build on the basics independently — you can go straight to either. You only need the daemon layer for multi-host when a remote box happens to run one.

Not a ladder: Basics is the foundation, and Daemons and Multi-host are independent doors that each rest on it on their own. Multi-host reaches for Daemons only when a remote box happens to run one.

Surface basicsOne app, one process. Define a surface, serve it, and consume it — in the browser, from a CLI, or through an agent.Surface daemonsLong-lived local processes. A single-instance pid gate, a frozen control core, and live recycle under a connected client. kaval is the exemplar.Surface multi-hostThe same surface, mirrored from other machines over ssh, and a whole fleet gathered into one map. drishti is the exemplar.

The two upper strata are independent doors, not a ladder you must climb: kaval proves a daemon needn’t be multi-host, and drishti proves a multi-host fleet needn’t be daemons. Multi-host assumes the basics; daemons are optional to it.

What each layer answers

Why surfacesThe problem the framework removes, and what a surface is and is not.ReferenceThe austere facts: defineSurface, the five member kinds, the server, the client, and the links.GlossaryNew to the vocabulary? Plain-language definitions of every term — surface, mirror, entries, the daemon spine — each linked to where it's taught.