@treactui/protocol

The wire protocol between a backend and the @treactui/tty React component: JSON text frames over one WebSocket. It has no dependencies and runs in the browser and in Node, so the React package and every backend adapter share one definition. The Go adapter (tty-go) mirrors it in protocol/.

| Direction | type | Carries | |---|---|---| | backend → browser | hello | version | | | output | data: terminal output (ANSI) | | | a11y-snapshot | snapshot: { title, nodes[] } of ARIA roles | | | announce | text, politeness (polite | assertive) | | | event | name, payload: a web-only action for the host page | | | commands | commands: what the browser may run (see below) | | browser → backend | input | data: keystrokes | | | resize | cols, rows (whole numbers, 1 to 1000) | | | run | command, args: run one of the offered commands (at most 100 arguments, each at most 10 000 characters, no NUL) | | | stop | stop the running command |

Each direction has an encoder (a mapper) and a parser (a validator that says why it rejects a frame). A selectable list is a listbox of option nodes (aria-selected is invalid on a listitem). @treactui/tty renders the described screen read-only, as a plain list with the selected item marked aria-current, because a screen reader reads a listbox as a single stop in browse mode; it also announces when the selected option changes.

Commands

A backend that offers commands (for instance a commander CLI) sends a commands message: a list of CommandSpec, each with a name, a description, its arguments and its options (a flag, whether it takes a value, its choices, default and whether it is required). The page then shows a launcher and starts one with run; the backend runs only commands from its own list. A backend that serves one program never sends commands.

Schemas and conformance cases

For an adapter in another language, the package ships what the parsers are checked against:

• schema/server-message.schema.json and schema/client-message.schema.json: JSON Schema (2020-12), one per direction, with the limits in them. Import them as @treactui/protocol/schema/server-message.json and @treactui/protocol/schema/client-message.json.
• conformance/cases.json (@treactui/protocol/conformance/cases.json): raw frames, their direction, and whether each is valid. The TypeScript parsers, the schemas and the Go adapter all run the same list.

Integrating another language says how to use them. The schema is the contract a backend should meet; the browser's parser is slightly more lenient (it renders an unknown role as given, and reads any politeness other than assertive as polite).

How this package is organised

src/
  index.ts            the public API
  a11y-snapshot/      the semantic description of a screen (contract only)
  command-catalog/    the commands a backend offers: contract and parser
  server-messages/    backend → browser: contract, encoder, parser
  client-messages/    browser → backend: contract, encoder, parser
  protocol-version/   the version number, bumped on any incompatible change