The wire protocol, v2

Every control on a tablet is one of three things. The difference is entirely about what the host publishes for it:

A flip button never toggles itself; it draws what the host says. That is why there is no acknowledgement anywhere in this protocol. The state echo is the receipt. A tablet that flipped optimistically would lie whenever a command was dropped and disagree with the second tablet in the room.

The third kind applies the same idea to time rather than value. It is how a host reports progress with no ack to report it on. The command goes out once. The host publishes <something>Pending while the work is outstanding and clears it when done. The tablet shows a spinner and refuses a second press meanwhile. Two things follow from this being state rather than a per-client reply: every tablet in the room shows the same wait, and a tablet reloading mid-wait comes back showing it, because hello carries the key like any other.

A host owning one of these owes it a clear on start-up, not only on completion. If the work was interrupted — a level torn down, a process restarted — nothing is left to clear the key. A tablet is then holding a spinner over an action nobody is doing.

The same obligation applies to a flip button, for a different reason. A tablet cannot know which way an unpublished toggle is about to move, so a flip button whose key has never been published stays disabled. This is deliberate — !undefined would make it claim "on" is next — but a host forgetting to publish the initial value ships a permanently greyed control, not a control that guesses.

Adding a button is therefore a tablet-side change plus, for the last two kinds, one published key. There is nothing to register.

hello always carries a complete state snapshot, never a patch, so a freshly connected or reconnected tablet never renders from stale assumptions.

A client may receive hello more than once on the same connection, and must treat every one as a wholesale replacement of its state mirror. Three things cause this: a trusted local client is authorised the moment the socket opens and gets one unprompted, so its own hello draws a second; sys.resync produces one; and the reference host re-sends hello to every authorised client when its command vocabulary changes. server.rev is the same counter the state patches carry, so seed your gap detection from it rather than from the first patch. server.boot is a per-process id for diagnostics. A client does not have to compare it, because replacing state wholesale on every hello already handles a restarted host. The reference client stores it nowhere and compares nothing.

The client’s client field is a free-form name for logs, and optional in both directions. The reference client always sends one and the reference host never reads it, preferring the peer address because that identifies a tablet in a room with three of them. Send it or don’t. A host that wants to name connections has it, and a host that doesn’t misses nothing.

Until authorised, any message other than hello is answered with unauthorized. The host closes the connection after a short grace period or a few bad frames.

Start listening as early as you can. A client has no way to learn that a host exists other than a successful connect attempt. The socket opening is the entire discovery mechanism, and every second before it is a second of spinner. The reference host binds its port from the game instance subsystem’s Initialize, before any level has loaded. The tablet is then live, if briefly stateless, while the world is still coming up. Clients should expect this: a hello may arrive carrying almost no state, and keys appear as the host learns them.

The host holds an authoritative map of flat, dotted keys — paused, volume, custom.blackout. Keys are never nested, because a patch like {"custom": {"blackout": true}} is ambiguous about whether it replaces the whole custom object or merges into it. Flat keys have exactly one meaning and cannot lose a sibling.

rev increments by one per patch. On a gap, the client sends sys.resync and takes the resulting full snapshot. A null value means the key was removed.

This is the only channel a control renders from. A tablet that flipped a button optimistically would lie every time a command was dropped, disagreeing with the second tablet in the room. State is also how a host locks a control while it is busy — see below.

The reference host publishes:

notice is read by the reference tablet — it renders any string published under that key as a banner — but nothing publishes one today. It is the cheap way for a host to say something without the protocol growing a message type for it.

One thing to know before you publish a notice: that banner has three possible sources. The reference tablet ranks them err > health.failed > notice. A project’s own message is replaced while a self-diagnostic check is failing — deliberately, since a queue length or a "closing in ten minutes" line is less urgent than the kiosk not working, and the operator needs to know which. That ordering is a tablet decision, not a protocol rule. A tablet is free to choose differently, or to draw all three. This is noted only so a host author is not surprised by a message silently vanishing.

subtitles and assistancePending are published by the project, not by the reference host. They are two worked examples of a button getting its state without the host learning what the button means: subtitles a flip for a setting in the project’s own UI, and assistancePending a progress key for an action ending in a human being fetched — the one place where how long it takes is a deployment’s business and nobody else’s.

Note what blackout implies for a tablet: a control taking the host out of service must not be gated on the host being healthy. Ours deliberately carries no busy key, because the moment you reach for it is the moment everything else is already broken.

That is the entire client-to-host vocabulary. cmd is a string the host and the tablet have agreed on; args.value may be a string, a number or a bool.

args.value is optional in the envelope — a command like restart that names its whole action carries none. But a host can and should require one per command. Once coerced, an absent value is indistinguishable from a false one. A host treating "missing" as "false" lets a single malformed frame lift a lockout or mute a kiosk. The reference host requires a value for pause, volume, micMuted, blackout and locale, and a numeric one for volume. Commands arriving without required values are logged and ignored, never guessed at.

Nothing is acknowledged. There is no correlation id and no ack, because the confirmation a control actually needs is the returned state: press Pause, and the button changes when paused does. A host reports progress or refusal by publishing state, which every connected tablet sees.

sys.resync needs no registration and makes the host re-send hello. Like any message, it is subject to authorisation and the rate budget.

Worth implementing on both sides: a host with a wedged main thread leaves the socket open while serving nothing. Silence — not disconnection — becomes the only symptom. The reference client marks the host stale after 8 s without a frame.

A host whose transport can only deliver one frame per tick may coalesce a frame’s worth of messages. Clients must unwrap this and process the entries in order.

v1 carried a capability manifest in hello: the host declared every control with a 15-field descriptor (kind, group, order, localised labels, icons, state key, busy key, range bounds, enum options). The tablet rendered whatever it was told, and each command was correlated and acknowledged with ack / err and a client-side timeout.

It was an RPC framework serving eight buttons that all completed synchronously. v2 drops the manifest, the registration API behind it, correlation ids, and ack. A tablet declares its own buttons; the host publishes state and answers to strings.

Removed: capabilities in hello, ack, the id correlation field, and the command-level error codes (unknownCommand, unsupported, disabled, badArgs, busy, internal).

Added, later in v2: server.commands in hello. This is not the manifest returning — the difference is what the declaration is for. v1’s manifest drove rendering (fifteen fields per control), and registration was mandatory, meaning an unregistered command could not work. The v2 list simply names commands, value types, and the key each command reflects. It drives nothing, and an unregistered command behaves exactly as before. It exists because a README stops being an adequate answer the moment a second host implementation exists. It is optional and additive, so a client written before it still works.

Also removed, later in v2: the event frame — a one-shot notification channel ({"t":"event","name":…,"data":…}) that no host ever sent and no tablet ever read. Everything a tablet needs to render is persistent, making it state. A frame type existing only in this document was just one more thing for a host author to implement for nothing. Nothing else in the wire format has changed, so a client written against earlier v2 still works.