TUI Runtime

BMUX TUI runtime

bmux_tui_runtime is the domain-neutral execution layer for terminal user interfaces built from bmux_tui primitives and, optionally, bmux_tui_components controls. It owns scheduling and presentation mechanics; applications retain their state and product behavior.

Layer ownership

bmux_tui terminal primitives, frames, buffers, events, backends bmux_tui_components reusable controls and component-local interaction state bmux_tui_runtime bounded admission, scheduling, timers, commands, cadence application/plugin product state, semantic updates, effects, navigation, policy
bmux_tui_runtime depends on bmux_tui. It does not depend on bmux_tui_components, and neither lower layer depends on the runtime. The runtime must not interpret BMUX or consumer product domains such as windows, sessions, panes, clients, contexts, permissions, model turns, or tools.

Logical content-selection contract

Content selection is separate from ordinary hit routing. During rendering, components register a hierarchical SelectionScene containing caller-owned scope/content identities and visible fragments mapped to logical UTF-8 source boundaries. A caller-owned SelectionController resolves pointer gestures against the last committed scene, locks the deepest eligible initiation scope, and retains logical anchor/focus endpoints across redraws. Applications remain responsible for canonical source content, scrolling, copy/export formatting, and clipboard effects.
Selection scope is fixed where the drag begins. Initiation in a capturing child remains constrained to that child even when the pointer leaves it; delegated child chrome may instead select through an ancestor across ordered sibling content. Renderers can explicitly provide word and line ranges; item and whole-scope expansion use registered logical ordering. Missing semantic boundaries are rejected rather than inferred from terminal cells.
Only visible geometry belongs in a scene. Source text remains caller-owned, and snapshots contain logical source ranges rather than copied content. Reconcile controllers after each successful scene commit so content revision/removal invalidates stale endpoints. During modal or focus-trap activation, callers use set_obscured: active gestures are cancelled, while completed selections may be cleared or hidden and restored according to policy. Optional diagnostics deliberately expose only bounded phase, granularity, obscuration, and endpoint-presence state.
PaintCx::paint_selection is the deterministic overlay stage: consumers call it on the root paint context after normal content rendering with a snapshot from their controller. It patches only explicit selection style fields over the selected cells and never rewrites symbols. Terminal::draw commits the rendered selection scene transactionally with output, hits, focus, cursor, and images. Failed output and reset retain the prior scene as the authority corresponding to the last visible frame; resize forces a full redraw, whose successful commit replaces the old geometry. Regional draws retain selection fragments outside the damaged regions and replace emitted metadata inside them.
Selection scopes and fragments are generic renderer metadata. Runtime code must not interpret source identities, ranges, selection meaning, or autoscroll requests.
Pointer gestures that may either activate a control or select text go through bmux_tui::gesture::PointerGestureRecognizer::route_selection, which reports a click when press and release stay within a ClickSlop over the same interactive region, even while the selection is armed, and starts selection only once the pointer travels beyond the slop.

Automatic interaction contract

Interactive geometry is frame metadata, not application state. A standard component registers a HitRegion while it renders, using the exact terminal-cell Rect it painted. A region has a caller-owned stable ID, semantic role, layer, visibility, enabled state, pointer/hover acceptance, focusability, optional explicit tab order, and optional focus scope. Render order is the default tie-breaker, so ordinary controls need no parallel focus list.
Terminal::draw treats the frame metadata transactionally: terminal output must flush successfully before the frame’s HitMap, scope, and reconciled FocusTrap become authoritative. TerminalPresenter::with_commit exposes those committed values to an application callback. Failed presentation keeps the previous scene authoritative. Runtime code remains domain-neutral and applications map routed stable IDs to product actions.
Input follows this lifecycle:
  1. Paint components through the root PaintCx; standard controls register their exact bounds automatically.
  2. Successfully flush the frame, then publish its interaction scene and reconciled focus state.
  3. Commit that scene to an InteractionRouter.
  4. Route terminal input through the router. Pointer routes include the stable target, role, committed bounds, and target-local coordinates; keyboard and paste routes target current focus. Use InteractionRoute::event_for (or compare target) to dispatch only to the resolved control.
  5. Apply the resulting semantic action to application state and redraw when routing or application state changed.
Component handle_event methods accept events that have already been dispatched to that component. They continue to reject disabled input, but local focused fields control cursor/focused styling and internal roving-child selection rather than repeating the router’s global target check. Applications that bypass InteractionRouter may therefore call one selected component directly without first setting a visual-focus boolean. Applications with multiple controls must not broadcast raw keyboard or paste events to every component; route once and dispatch only to the matching stable target.
The router traverses enabled, visible, non-empty focusable regions with Tab/Shift-Tab, preserving stable focus IDs across redraw and responsive reflow. Explicit tab_order is only for exceptional visual order. Pointer presses transfer focus, activation requires press and release on the same target, one move reports both hover leave and enter, and the highest layer/latest rendered region wins overlaps.
A frame focus_scope traps traversal and pointer routing to matching regions. Entering a scope saves background focus; nested scopes save their parent focus; leaving restores the most recent still-valid stable target. Components painted after PaintCx::set_focus_scope inherit that scope when focusable. Applications should render modal controls with stable IDs and must not separately route background geometry.

Minimal webpage-like surface

let save_state = Cell::new(ButtonState::new()); let save = ButtonComponent::new("profile.save", "Save", &save_state); let save_layout = save.layout(Constraints::tight(save_area.size()), &mut LayoutCx::new()); cx.with_child( i32::from(save_area.x), i64::from(save_area.y), LocalRect::new(0, 0, save_area.width, save_area.height), |cx| save.paint(&save_layout, cx), ); let cancel_state = Cell::new(ButtonState::new()); let cancel = ButtonComponent::new("profile.cancel", "Cancel", &cancel_state); // … same layout/paint pattern in cancel_area …
Both buttons register themselves and become independent tab stops in render order. Every component takes a caller-chosen stable ID so input maps to semantic actions and focus survives reflow; automatic IDs are not part of the component model.

Exceptional configuration

// Explicit ordering and a keyboard-only target, registered from inside a // component's `paint` through its scoped context. cx.push_hit( HitRegion::new("search.input", search_area) .role(HitRole::TextInput) .focusable(true) .tab_order(-10) .pointer_events(false), ); // Disabled or hidden targets are excluded without changing a parallel list. cx.push_hit( HitRegion::new("profile.delete", delete_area) .focusable(true) .enabled(can_delete) .visible(show_delete), ); // A dialog activates one focus scope; the controls it paints afterwards inherit it. cx.set_focus_scope(Some(HitId::new("confirm-dialog"))); dialog.paint(&dialog_layout, cx);
Composite controls such as tab bars, lists, and tables register their composite/option regions and retain conventional arrow-key or row navigation internally. Ordinary action rows expose every rendered button as an individual global tab stop; local wrapping or custom ordering should be configured only when the component’s interaction model intentionally requires it. Programmatic focus uses a stable HitId with InteractionRouter::set_focused (or FocusTrap::set_active when deliberately managing a trap directly) and succeeds only for a target in the committed active scope.

Direct dispatch and custom focus models

Component handle_event methods remain the component-local dispatch surface. Consumers should prefer committed semantic dispatch and must not fall through to recomputed mouse geometry once a committed pointer target exists. Every component registers its exact painted bounds and takes a caller-chosen stable ID, so semantic routing never depends on automatic identifiers. Explicit FocusTrap::with_targets remains useful for tests and deliberately custom focus models, but normal application traversal derives from committed frame hits.
For local cross-repository development, Nextjob resolves bmux_tui, bmux_tui_components, and bmux_tui_runtime directly from ../bmux workspace paths. A consuming workspace with transitive crates should use temporary root [patch.crates-io] entries for the same local BMUX packages so one dependency graph cannot contain both published and in-progress copies; verify the resolved sources with cargo metadata and remove patches that are not intentional long-term wiring.

Program model

A runtime serially delivers typed events to one Program owner. An event is terminal input, an application message, a keyed timer, or a command completion represented by an application message. Program::update mutates application-owned state and returns explicit presentation or exit intent. Long-running work is returned as owned 'static commands rather than awaited in update; work that must continue borrowing mutable program state is not a runtime command and must first be split into an owned request/result boundary by the application.
The runtime never owns canonical application state. It owns only bounded queues, task generations, timer deadlines, redraw state, and presentation cadence.

Admission and ordering

Admission is explicit rather than inferred from message contents.
  • Reliable messages use a bounded FIFO mailbox. Asynchronous senders wait for capacity; try_send reports saturation. Accepted messages are not silently dropped.
  • Terminal events use a separate bounded FIFO mailbox so application floods cannot consume all input capacity. Reliable key, paste, click, wheel, and focus events use this path.
  • Latest-value messages are keyed and bounded by key count. Replacing a pending value is explicit, latest-wins, and counted. Applications may use it only when skipped intermediate values are semantically safe.
  • Redraw requests use a dirty latch. Repeated requests do not consume queue entries.
FIFO is guaranteed within each reliable mailbox. No total ordering is invented across independent producers or between reliable and latest-value mailboxes. Applications that require cross-source ordering must carry and validate their own sequence contract.
The runtime has no generic drop-oldest policy. Lifecycle, authorization, cancellation, and durable semantic updates must use reliable admission unless their owning domain defines a safe replacement contract.

Fairness and backpressure

Each scheduler turn has both a message-count budget and a wall-time budget. Terminal input is checked before bounded application work, and due timers and presentation are reconsidered between turns. Saturated reliable producers are backpressured by bounded channel capacity. Latest-value producers are bounded by configured key capacity.
Budget exhaustion yields back to the Tokio scheduler and records a statistic. It does not discard accepted work.

Timers

Timers are keyed one-shot deadlines. Scheduling the same key replaces its pending deadline. A delivered timer is removed before Program::update; periodic behavior reschedules itself explicitly. This avoids an implicit global tick and allows idle runtimes to sleep until actual work is due.
Deadlines are measured on the runtime’s time source. RuntimeHandle::now returns it and RuntimeHandle::schedule_timer_after schedules relative to it; prefer these over deriving deadlines from Instant::now so deterministic test clocks control when timers become due. Production runtimes use the monotonic system clock.

Commands and cancellation

Commands are application-supplied futures that return zero or one application message. The runtime supports concurrent commands and keyed start-if-idle, replace, queue-latest, and cancel policies. Keyed generations prevent stale completions from replaced work from entering the application mailbox.
Runtime task abortion is local lifecycle management only. It must not be represented as cancellation of canonical application or remote work unless the application separately performs and observes that domain operation.

Rendering

Semantic updates never wait for frame cadence. An update marks presentation dirty; the runtime presents the latest application state when the frame deadline permits. Repeated invalidations coalesce. The next deadline is based on completion of the preceding presentation, so a delayed frame does not create catch-up bursts.
TerminalPresenter presents synchronously, which keeps the committed terminal buffer, hit map, cursor, image scene, and application-visible presentation acknowledgement aligned. AsyncTerminalPresenter keeps the same alignment with an owned frame snapshot and explicit commit acknowledgement: it paints a staging terminal (Terminal::stage, which takes over the retained cells instead of copying them), hands the encoded bytes to one output thread, and adopts the staged state only after the bytes were delivered. Its output owner implements CancellableOutput; bmux_tui::terminal::TtyOutput is the Unix implementation, a separate nonblocking open of stdout’s terminal device (so no shared descriptor flag changes) whose writes stop promptly on cancellation. While one frame is in flight no further frame is prepared; the next frame paints the latest state once delivery settles, so frames superseded under backpressure are never written and a slow terminal never blocks input.
Applications construct the canonical component tree and retain its caller-owned state and derived layout caches. The presenter’s render callback receives the application and one root bmux_tui::paint::PaintCx covering the terminal area; the callback resolves its tree under the terminal constraints (cx.area()) and paints through that scoped context, including hit, semantic, selection, image, cursor, and damage contributions and the deterministic PaintCx::paint_selection overlay stage. The raw Frame and Buffer are never exposed to application code. The runtime schedules and commits this work; it does not own component measurement, choose application layout, or retain a second geometry tree. Input routing uses the exact successfully presented layout and interaction/selection scenes. A failed presentation must not publish the attempted layout, hit map, selection scene, focus geometry, image scene, or cursor as the source for subsequent input.
Runtime APIs must not recreate area-assigned widget layout, line scrolling, or product-specific viewport correction, and must not reintroduce a frame- or buffer-level application callback.
A presenter failure terminates the runtime without treating the failed frame as committed. A reset request invalidates the terminal backend before the next presentation.

Managed terminal input

With the terminal-io feature, the runtime can own a blocking terminal reader thread. It forwards events through bounded terminal admission. Dropping the input source requests shutdown and detaches a reader blocked in the operating-system backend; the thread exits after the next event or when runtime admission closes. The runtime does not claim that a blocking OS read is synchronously cancellable.

Image-capable presenters

The optional bmux_tui_runtime::ImageTerminalPresenter is the runtime boundary for applications that contribute protocol-neutral images through bmux_tui frames. It combines retained cell drawing with bmux_image scene compositing inside one synchronized update and flush. The presenter publishes committed interaction metadata only after both outputs succeed.
Image support is split into additive Cargo features: images enables the presenter and individual image-kitty, image-sixel, and image-iterm2 features enable host protocols. Defaults independently enable all-protocols (all three image protocols) and terminal-io. Text-only runtime users can retain a minimal dependency graph with default-features = false (--no-default-features for Cargo commands).
Environment-only detection is safe before input admission because it performs no terminal I/O. Active capability queries must run after raw mode is active and before a runtime terminal reader starts. Applications must retain presenter ownership long enough to call cleanup_images before graceful exit, suspension, or application-error recovery; reset_presentation combines image cleanup with retained-frame invalidation.

Deterministic testing

The non-default testing feature provides bmux_tui_runtime::testing::ProgramHarness, a synchronously stepped driver for any Program. Enable it only from test builds:
[dev-dependencies] bmux_tui_runtime = { workspace = true, features = ["testing"] }
The harness owns a real Runtime and calls its production update, presentation, and commit paths; it substitutes only time and task execution:
  • Time. A ManualClock replaces the system clock for timer deadlines and frame cadence. It captures one anchor instant and afterwards moves only on advance. Commands and subscriptions run on a harness-owned current-thread Tokio runtime with a paused clock that advances together with the manual clock, so tokio::time::sleep in a command completes exactly when the test advances past it.
  • Delivery. push_terminal, push_key, push_mouse, push_resize, push_paste, push_message, and push_timer script events in order. step, deliver(n), and settle deliver scripted events first, then runtime-owned sources through the production fair rotation: due timers, command completions, subscription messages, and messages or terminal events admitted through handle(). settle is bounded and reports programs that never go idle.
  • Presentation. Delivery never presents in the default PresentMode::Manual, so any number of events and effect results can be applied between frames. present commits one frame when a redraw is pending (ignoring cadence), force_present requests one first, and present_if_due applies the configured cadence on the manual clock. PresentMode::AfterEachEvent and PresentMode::Cadence present automatically. Each presentation draws into an in-memory Terminal, runs the optional on_commit hit-map/focus observer, then Program::presentation_committed, and applies its update, exactly as the running runtime does.
  • Damage. Without configuration every presentation is a full repaint. HarnessBuilder::damage installs a callback that declares each presentation’s Damage, which the harness draws with Terminal::draw_damage, so regional and scroll damage retain committed cells and metadata exactly as a regional production frame does. HarnessBuilder::scroll_region_acceleration selects ScrollRegionAcceleration for the in-memory terminal.
  • Inspection. frame() exposes the committed buffer, row text, cell-accurate find, style runs, cursor, hit map, selection scene, semantics, focus, and the PresentReport; FrameView::text is suitable for snapshot assertions. FrameView::damage returns the effective damage regions of the committed frame (the declared damage after promotion, for example to Full on the first frame or after a reset), FrameView::declared_damage what the program declared, and FrameView::applied_scroll any terminal scroll the output used. Unlike PresentReport::full_repaint, these distinguish regional and scroll damage from a full repaint. The harness also exposes pending timers and deadlines, keyed command state, pending redraw/reset latches, reset history, all reports, the last output bytes, and runtime statistics.
Programs that retain a RuntimeHandle receive the harness handle through HarnessBuilder::build_with. The harness is a test surface: it is excluded from production builds and is not a second runtime implementation.

Shutdown and errors

Graceful exit stops admission processing, cancels runtime-owned command and subscription tasks, performs no speculative final semantic update, and returns the final program and runtime statistics to the caller. Immediate abort follows the same ownership cleanup but may skip an application-requested final redraw. Program and presenter errors are surfaced distinctly.

Observability

A lightweight runtime statistics snapshot reports queue depth and high-water marks, backpressure/rejection counts, latest-value replacements, processed event classes, scheduler budget exhaustion, redraw requests and coalescing, frame count and scheduling delay, successful update and presentation time, presenter-reported changed cells and full repaints, command lifecycle, stale completions, and timer activity. Timing fields are cumulative microsecond observations intended for attribution and consumer-side deltas, not embedded product SLOs. Failed updates and presentations do not advance successful-work or committed-output totals. Consumers translate these neutral measurements into their own metrics systems.

Non-goals

  • Product state, navigation semantics, authorization, persistence, network clients, and plugin behavior.
  • Portable frontend or plugin protocol contracts.
  • Interpreting event payloads to decide whether they may be dropped or replaced.
  • Making local task cancellation authoritative for remote work.
  • Replacing bmux_tui frame construction or retained-buffer terminal diffing.
  • Mechanically reproducing Bubble Tea APIs.