termwright-ratatui 0.2.0

Author-intent annotations for custom Ratatui widgets observed by Termwright
Documentation

termwright-ratatui

Author-intent annotations for custom Ratatui widgets observed by Termwright's instrumented build probe.

use termwright_ratatui::{Action, Annotate, Role, Semantics};

let widget = DeployWidget::new().annotated(
    Semantics::new()
        .role(Role::Button)
        .name("Deploy")
        .description("Deploy the current release")
        .test_id("deploy-release")
        .semantic_key("deployment-control")
        .action(Action::Activate)
        .labelled_by("deployment-label")
        .domain("deploymentStatus", "ready"),
);
frame.render_widget(widget, area);

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.