Crate spaceterm_proto 

Terminal Block Protocol (TBP) v1: wire types and codec.

TBP is an OSC escape sequence carrying a MIME bundle, directly inspired by Jupyter’s display_data message. A tool emits a block as one escape; the terminal selects the richest MIME representation it can render and falls back toward text/plain. Terminals that do not understand TBP ignore the escape.

The wire form is documented normatively in docs/terminal-block-protocol-spec.md; this crate is its reference codec. See encode and decode for the byte-stream entry points.

Structs

BlockId

Identifier correlating live-block updates (open/patch/close) and distinguishing concurrent blocks within one session.

BlockMeta

Optional presentation hints attached to a bundle.

Caps

What a terminal can render, sent back to a querying tool so it can choose a representation before emitting. Travels as JSON on the tool’s stdin, not as an OSC escape, so it is serialized directly rather than through [crate::wire].

EmitBlock

Payload of Message::Emit: a complete block rendered once.

MimeBundle

A set of alternative representations of one block, keyed by MIME type. The terminal renders the richest type it supports and falls back toward TEXT_PLAIN. Values are JSON: a string for text and image payloads, an object for structured specs (e.g. Vega-Lite).

OpenBlock

Payload of Message::Open: the initial state of a live block.

PatchBlock

Payload of Message::Patch: an RFC 6902 JSON patch applied to a live block.

Version

TBP protocol version. Wire form is a bare integer.

Enums

Message

A single TBP message, decoded from one OSC escape.

ProtoError

Failure decoding a TBP escape.

TrustTier

How much capability a block’s rendered content is granted. The emitting tool requests a tier; the terminal clamps it by policy.

Constants

OSC_NUMBER

Private-use OSC number that frames every TBP message. Provisional; the final number is coordinated with other terminals before 1.0.

PROTOCOL_VERSION

Protocol version this crate emits and is the highest it accepts.

TEXT_PLAIN

The mandatory fallback representation every well-formed bundle should carry.

Functions

decode

Parse the content of one OSC escape (the bytes between ESC ] and ST, with the introducer and terminator already stripped) into a Message.

decode_with_sidechannel

Like decode, but resolves file= references through file_reader. When an emit carries a file=RELATIVE_PATH parameter instead of an inline base64 payload, file_reader is called with the relative path and must return the raw file bytes. This avoids base64-encoding large payloads (images, PDFs) over the PTY stream.

encode

Render a message as a complete escape sequence ready to write to the stream.