Module binder

Expand description

ReadoutBinder — runtime adapter between the static workload binding and the live display surface. See SRD-63 §7.

Push 3 ships:

The trait surface (ReadoutBinder, ReadoutSink, LayoutHint, BinderKey, BakedBody, RenderStep).
A stateless DefaultBinder that walks each event’s bindings in order and renders. Stateful interactive variants (focus highlight, LOD overrides, overlay-held flag) land in Push 5.
A line-buffer StringSink that the terminal-mode surface uses; the TUI gets its own Vec<Span> sink in Push 5.

Structs§

BakedBody: A baked readout body — the artifact the body-grammar parser produces at workload-load time. Cheap to clone (steps are owned, but small) and shared across event fires.
DefaultBinder: Stateless default binder. Holds a slot → Vec<BakedBody> map; on fire(event) walks the matching slot’s bodies in declaration order. Push 5 introduces a stateful TuiReadoutBinder alongside.
StringSink: Plain-text line buffer. Concatenates everything into a single String; layout hints Block / InlineCompact resolve to “insert a \n before/after Block, share surrounding spaces for Inline.” This is what the terminal-mode \r\x1b[K… rewriter consumes.
TuiReadoutBinder: Stateful runtime adapter for the TUI surface (SRD-63 §7).

BinderKey: Keyboard events the interactive surface forwards to the binder via ReadoutBinder::on_key. Push 3’s stateless default binder ignores them; Push 5’s TuiReadoutBinder interprets them.
LayoutHint: What the binder writes to the sink for a single render step. The sink decides how to honour the hint: terminal-mode flattens to bytes; the TUI applies focus decoration around Focused wrappers.
LayoutMode: Layout intent expressed inside a readout body via the layout= option. See SRD-63 §5.3.1. The binder maps this to a LayoutHint for the sink at render time.
RenderStep: One step in a baked readout body. Either a literal run of text, a render call against a registered readout, or a colour / style directive (Push 4) that wraps the next step in ANSI on/off bytes.

ReadoutBinder: Stateful runtime adapter — drives readouts in response to events, applies any interactive state (Push 5), emits ordered render instructions to the sink.
ReadoutSink: Layout-aware writer the binder drives. Push 3 ships StringSink for terminal-mode line emission; Push 5 adds a TUI sink that holds Vec<Span>.

build_binder_from_workload: Build a DefaultBinder from a workload-level nmbrs_workload::model::ReadoutsBindings + a fallback table of built-in defaults. The workload’s bound bodies replace the matching slot’s defaults; unbound slots fall through to whatever defaults the caller seeds.
build_event_binder: Build a binder bound to a single event slot, applying the SRD-63 §5.4.1 composition / override rules:
build_event_binder_with_cli: Same as build_event_binder, with a CLI --readout override layered on top per SRD-63 §8 / Push 8. The override only applies to the Update slot (the only slot the single --readout flag targets); other slots resolve through the workload + default path. Push 9+ could grow per-event override flags (--readout-on-each=…) if demand arises.
layout_hint_for: Per-step layout classification per SRD-63 §7.4. mode doesn’t affect layout — the overlay shares shape and width with the value per §3.2 — so it isn’t an input here. The parameter stays in the signature so a future mode-aware layout (e.g. an “expand on Explanation” rule) doesn’t require changing every call site.
validate_body_for_event: Bake-time validation: every Render step in body must accept the firing slot’s subject kind. The binder calls this before binding, so a workload mistakenly binding phase_status to on_session_end errors at workload- load instead of rendering silent zeros at run time.

ReadoutHandle: Reference-counted readout handle. The Registry returns these by wrapping unit-struct builtins in Arc::new; per-workload custom readouts (planned for Push 4 of the SRD-63 follow-on work) ride the same shape. Cheap to clone — refcount bump only — and hands a &dyn Readout out via as_ref for the actual render call.