Shared TypeScript Protocol Code

Shared message types, strict UTF-8 JSON serialization, and OSC framing for TUI and Terminal consumers. This code was extracted from the reference-codec prototype without changing wire behavior. Its API remains experimental and unpublished; protocol design drafts remain in docs/protocol/.

@tui-protocol/protocol is the private workspace entry point, backed by src/index.ts; test/codec.test.ts retains the existing codec checks. The implementation has no SDK, prototype, renderer, or PTY dependency. Consumers import it; there is no duplicate codec in the SDK.

It implements the current drafts for:

Proven

  • A fixed Capability query matches independently recorded JSON and OSC wire bytes.

  • Every baseline Message kind, including block.extend and block.replace_suffix, can round-trip through JSON and OSC framing.

  • A Message larger than one frame is split, independently Base64 encoded, reassembled, and decoded when every byte arrives in a separate write.

  • A complete Message is accepted at the 1048576-byte framing limit and rejected when its serialized form exceeds that limit by one byte.

  • The tested invalid-UTF-8, BOM, closed-schema, duplicate-member, invalid-Unicode, malformed-Base64, invalid-framing, and fragment-interruption cases are rejected deterministically.

  • For tested schema-invalid requests and Operations, the decoder exposes a correlation identity only when the recognized version, kind, and required request or Operation IDs are valid.

  • A tested block.extend with an empty fragment is rejected while retaining its valid correlation identity.

  • Tested negative, fractional, and unsafe retain values in block.replace_suffix are rejected while retaining valid correlation identity; an empty replacement remains valid.

  • A framing failure discards only its incomplete Message and parsing resumes at a later valid protocol frame.

  • In the tested mixed-decoding cases, ordinary text and another OSC sequence retain their tested byte content around a recognized protocol Message, and their emitted events retain stream order across every split point of that fixture.

  • One tested BEL-ended unrelated OSC and its adjacent non-UTF-8 bytes are emitted with exactly the same bytes; one malformed protocol OSC is consumed as an error instead of being emitted as ordinary data.

  • The same codec processes the tested OSC Messages in the browser protocol endpoint without a Node-only Base64 dependency.

  • A narrow xterm parser bridge forwards tested completed OSC 9002 payloads through the same decoder; that bridge’s mixed-stream limitations are recorded in its README.

Experimental Boundaries

  • OSC number 9002 remains provisional and is not a public allocation.

  • The exported TypeScript API is experimental, not a stable package contract.

  • Base64 uses the standard btoa and atob globals available in the declared Node.js runtime and tested browser; broader runtime portability is untested.

  • Only the baseline text/plain content schema is implemented because no optional content type schema has been selected.

  • Decoder error events are local diagnostics; they are not wire-level protocol.error Messages.

  • A reported invalid-Message identity is only a correlation hint for a higher protocol layer; the codec does not construct responses or consume IDs.

  • Ordinary-data events are opt-in so existing protocol-only consumers do not receive them. They preserve bytes for a later terminal parser but do not interpret the native effect of those bytes.

Not Proven

  • Context or Block semantic state transitions and correlated error responses.

  • Capability timeouts, retry storage, or unsupported-terminal fallback.

  • Complete mixed-stream terminal-parser coverage, multiplexer integration, or a bidirectional PTY path from codec-only tests. The separate PTY demonstration records its environment-specific process-to-browser evidence.

  • Authentication, provenance, reset behavior, or resource exhaustion outside the framing limits.

  • A stable public API or compatibility with future protocol versions.

Run

pnpm typecheck
pnpm test