termwright-ratatui
Author-intent annotations for custom Ratatui widgets observed by Termwright's instrumented build probe.
use ;
let widget = new.annotated;
frame.render_widget;
Annotated<W> implements both Widget and StatefulWidget, including the
corresponding reference forms when the wrapped widget supports them. It calls
the original render exactly once with the same area, buffer and state.
Trust boundary
The SDK can express only author intent:
- role, name, description and test id;
- explicit application-domain JSON under
extended. - descriptive protocol actions, relationships to other semantic keys and an optional stable semantic key for a recreated widget value.
It has no API for bounds, focus, visibility, cells or collection selection.
Domain keys named bounds, state or actions remain nested JSON; the probe
never promotes them into portable facts or callback capabilities. A declared
Action is only a capability hint and still resolves through real terminal
input.
Geometry, collection state, frame commit ordering and occlusion: unknown
continue to come from the instrumented framework.
test_id remains a locator and correlation hint. semantic_key is deliberately
separate: a unique key produces a k:<key> node id that survives recreation and
can be used by labelled_by / described_by. Duplicate or empty keys degrade
to distinct frame-local ids. The handshake remains conservatively
identityKind: frame-local because ordinary unannotated Ratatui nodes still do.
The wrapper must be passed through Frame::render_widget or
Frame::render_stateful_widget. Ratatui composition that calls Widget::render
directly is not intercepted. The SDK detects that case and drops the nested
annotation instead of attaching it to the wrong outer render call.
Versions
This crate is pinned to Ratatui 0.30.2 and therefore declares Rust 1.88, the
same floor as Ratatui itself. termwright-protocol and
termwright-probe-ratatui remain independently buildable on Rust 1.74.
Both this SDK and the build probe it depends on are published on crates.io.
The release workflow publishes termwright-protocol, then
termwright-probe-ratatui, then this crate so every registry dependency exists
before its consumer is uploaded.