Crate termwright_protocol 

Semantic side-channel client for the termwright terminal test driver.

An instrumented TUI publishes its widget tree over a unix socket and commits each render with a signed OSC marker, so tests can assert on roles and names instead of screen-scraping cells. This crate is the protocol side of that contract: framing, the marker, message and snapshot validation, and a blocking socket client. It ships no framework adapter — wire it into whatever draws your screen.

Dormant rule. Without TERMWRIGHT_ENDPOINT and TERMWRIGHT_TOKEN in the environment, Client::from_env returns None and nothing happens at all: no socket, no marker, no change to what the terminal receives.

use termwright_protocol::{Client, Node, Options, Rect, Role, Snapshot};

let mut client = match Client::from_env(Options::new("my-tui", "1.0.0")) {
    Some(client) => client,
    None => return, // not instrumented: render normally and stop here
};
client.connect(termwright_protocol::DIAL_TIMEOUT).expect("handshake");

let mut snapshot = Snapshot::new(80, 24);
snapshot.push(Node::new("root", Role::Dialog, "Permission"));
snapshot.push(
    Node::new("ok", Role::Button, "Approve")
        .with_parent("root")
        .with_bounds(Rect::new(1, 2, 9, 1)),
);

if let Some(marker) = client.publish(&mut snapshot).expect("publish") {
    // Only after the render's last byte has been written.
    print!("{marker}");
}

The normative implementation is the TypeScript package @termwright/protocol; this crate is verified against the shared vectors in clients/test-vectors.

Re-exports

pub use client::Client;

pub use client::Options;

pub use client::DIAL_TIMEOUT;

pub use client::ENV_ENDPOINT;

pub use client::ENV_PROTOCOL;

pub use client::ENV_TOKEN;

pub use debug::debug_path;

pub use debug::Category;

pub use debug::DebugLog;

pub use debug::ENV_DEBUG;

pub use debug::ENV_DEBUG_FILE;

pub use diffing::build_delta;

pub use diffing::diff_trees;

pub use diffing::DELTA_SHARE_CEILING;

pub use error::Error;

pub use error::ParseError;

pub use error::ValidationError;

pub use error::Violation;

pub use framing::encode_frame;

pub use framing::project_dto;

pub use framing::Frame;

pub use framing::FrameDecoder;

pub use framing::FRAME_HEADER_BYTES;

pub use limits::Limits;

pub use limits::ABSOLUTE_LIMITS;

pub use limits::DEFAULT_LIMITS;

pub use limits::DEFAULT_NEGOTIATION_MS;

pub use logs::validate_log_record;

pub use logs::AttrValue;

pub use logs::LogLevel;

pub use logs::LogRecord;

pub use logs::LOG_LEVELS;

pub use logs::MAX_LOG_ATTRS;

pub use marker::compute_mac;

pub use marker::encode_marker;

pub use marker::verify_marker_payload;

pub use marker::RenderMarker;

pub use marker::MARKER_MAC_BYTES;

pub use marker::MARKER_OSC_CODE;

pub use marker::MARKER_OSC_PREFIX;

pub use messages::parse_adapter_message;

pub use messages::parse_driver_message;

pub use messages::ProbeIdentityKind;

pub use messages::ProbeInfo;

pub use messages::PROTOCOL_ID;

pub use messages::PROTOCOL_V2_ID;

pub use messages::PROTOCOL_VERSION;

pub use roles::Action;

pub use roles::Capability;

pub use roles::Role;

pub use tree::Cursor;

pub use tree::CursorShape;

pub use tree::Node;

pub use tree::NodeGeometryObservations;

pub use tree::Observation;

pub use tree::Occlusion;

pub use tree::Orientation;

pub use tree::PointerHitGrid;

pub use tree::PointerHitRegion;

pub use tree::Provenance;

pub use tree::Rect;

pub use tree::Snapshot;

pub use tree::State;

pub use tree::TextRange;

pub use validate::apply_tree_delta;

pub use validate::validate_snapshot;

pub use validate::validate_tree_delta;

Modules

client

Blocking unix-socket client for the semantic side-channel.

debug

Opt-in diagnostic log for the adapter side, written to a file.

diffing

Turning two consecutive trees into the delta between them.

error

Error types shared by the protocol modules.

framing

Wire framing: a 4-byte big-endian length prefix and a UTF-8 JSON body.

limits

Protocol limits. Callers may tighten the defaults, never widen the maxima.

logs

Application log records carried over the semantic channel.

marker

Render-commit marker.

messages

Wire messages: typed builders for what an adapter sends, checked parsers for what it receives.

roles

Closed vocabularies. Unknown members are rejected, never passed through.

schema_keys

The fields a node and a state may carry, as this client knows them.

tree

Semantic tree DTOs.

validate

Snapshot validation.