Reactive TUI

Overview  •  Installation  •  Quick start  •  Framework  •  Widgets  •  Features and platforms  •  Manual  •  Examples  •  FFI and TypeScript  •  Development  •  Contributing  •  License

Overview

Reactive TUI is a Rust framework for terminal applications. It combines retained components, reactive state, CSS-like layout, routed input, accessible semantics, images, dialogs, and owned terminal sessions.

Applications render complete, grapheme-aware cell frames. The primary SuprTUI backend owns terminal setup, input, presentation, and restoration. A debug backend renders into memory for deterministic tests.

The current checkout is version 1.0.0, as Cargo.toml declares, and is not yet published to crates.io. The last published release was 0.1.0 on 2026-09-14. The remaining release work is tracked in the recovery roadmap.

Main capabilities:

• Retained root components and keyed child components.
• Thread-safe signals, hooks, effects, scheduling, and wake-driven applications.
• Flex and grid layout through Taffy, plus utility classes and themes.
• Keyboard, mouse, paste, focus, capture, bubble, and custom event routing.
• Input, layout, display, menu, dialog, image, and terminal widgets.
• SuprTUI, Crossterm compatibility, and in-memory debug backends.
• Optional embedded Unix PTY sessions interpreted by libghostty.
• Optional graphics canvas: paths, gradients, images and text drawn on a GPU or by a software renderer, shown as Kitty graphics, Sixel or block glyphs.
• Optional C ABI and a TypeScript SDK.

Installation

The workspace requires Rust 1.95 or newer. Clone the current source and build with locked dependencies:

git clone https://github.com/eas4ai/reactive-tui.git
cd reactive-tui
cargo build --locked --jobs 8

Until the final crates.io release is tagged, applications can use a path dependency:

[dependencies]
reactive-tui = { path = "../reactive-tui" }

Optional tools depend on the features an application uses:

• Remote dialog validation and autocomplete require curl 8.4 or newer.
• Chafa and Viu are optional image-rendering fallbacks.
• embedded-terminal release builds require Zig 0.16.0.
• simd requires a nightly Rust compiler.
• The TypeScript SDK requires Node.js 20 or newer and a matching native library.

Quick start

This example paints a terminal frame through SuprTUI and exits on Escape or Ctrl+C:

use reactive_tui::app::RootComponent;
use reactive_tui::backend::SuprTuiBackend;
use reactive_tui::prelude::*;

struct Root;

impl RootComponent for Root {
    fn render(&self) -> Element {
        div()
            .class("flex-col w-full h-full p-4 bg-blue-900")
            .text("Hello, Reactive TUI!")
            .build()
    }
}

fn main() -> Result<()> {
    App::builder()
        .backend(SuprTuiBackend::new()?)
        .root(Root)
        .build()?
        .run()
}

Run the supported rendering example from this repository:

cargo run --locked --example gradient_blocks

This example demonstrates color gradients and block rendering.

Framework

System	What it provides	Manual chapter
Applications and components	App lifecycle, roots, retained components, props, and keyed identity	Applications and components
Elements and virtual DOM	Element builders, macros, keyed nodes, diffing, and patches	Elements, builders, and the virtual DOM
Reactive state	Signals, refs, hooks, effects, timers, schedulers, and application wakeups	Reactive state and hooks
Layout and style	Flex, grid, utility classes, colors, gradients, borders, and themes	Layout, style, and themes
Events and focus	Routed keyboard and mouse input, hit testing, focus, capture, and bubble	Events, focus, and input
Rendering	Cell surfaces, render trees, reconciliation, terminal capabilities, and backends	Rendering and backends
Animation and screens	Easing, keyframes, springs, timelines, transitions, and navigation	Animation and screens
Text systems	Editors, gap buffers, Markdown, and incremental syntax highlighting	Text editing, Markdown, and syntax
Accessibility	AccessKit semantics and an owned Linux AT-SPI connection	Accessibility
Native integration	C ABI ownership rules and TypeScript wrappers	FFI and TypeScript

App owns the main lifecycle. A root component produces an element tree. The framework reconciles that tree, computes layout, paints cells, presents the frame, and routes host input back to the retained application state.

Widgets

The widget library is grouped by purpose:

• Input: text input, checkbox, radio button, select, and slider.
• Layout: accordion, breadcrumb, scroll view, stack, and tabs.
• Display: charts, tables, data tables, trees, file explorer, progress, modals, popovers, and images.
• Menus: menu bars, context menus, popup menus, actions, shortcuts, and themes.
• Dialogs: confirmation, input, autocomplete, progress, toast, and wizard flows.
• Terminal: an owned child process with PTY input, resize, scrolling, focus, screen state, and error reporting.

Start with the input, layout, display, menu, dialog, and terminal widget chapters.

Features and platforms

Cargo features

Feature	Behavior
default	Enables Tokio support.
async-capabilities	Enables asynchronous capability detection through Tokio.
ffi	Exports the C ABI and builds the native integration surface.
embedded-terminal	Enables the libghostty-based embedded session on Unix.
simd	Enables nightly portable_simd color paths.
wgpu-graphics	Opt-in graphics canvas on a GPU, with a software renderer.
debug	Enables general diagnostic paths.
debug_patches	Enables reconcile patch diagnostics.

Platform behavior

• SuprTUI and Crossterm provide the normal terminal-host paths.
• The legacy pseudo-terminal API has Unix and Windows implementations. Windows uses the bundled OpenConsole/ConPTY runtime.
• The libghostty embedded-session API is available only on Unix.
• AccessKit semantics are cross-platform data. The owned AT-SPI connection is Linux-specific and requires a compatible desktop session.
• Image output selects a supported terminal protocol, Chafa or Viu, or a cell fallback.
• Supported-platform release CI and final cross-platform evidence remain part of the pre-release roadmap.

The framework bounds external work. Remote dialogs use explicit configured endpoints, HTTP or HTTPS only, a five-second deadline, a 1 MiB request limit, and a 64 KiB response limit. Static image decoding has a 256 MiB total memory budget. File-explorer copy and delete operations reject an entry whose filesystem identity changes after inspection. See Dialogs, Images and clipboard, and Display widgets for the exact rules.

Manual

The Reactive TUI manual is the main documentation entry point. The supported-API matrix maps every public crate module to its supported route, behavior checks, and verification limits. It contains a linked overview and 20 focused chapters grounded in the exported source, Cargo features, examples, and behavior tests.

Recommended starting points:

• Getting started
• Applications and components
• Reactive state and hooks
• Layout, style, and themes
• Events, focus, and input
• Rendering and backends
• Terminal and embedded sessions

Examples

Example	Command	Purpose
Widget catalog	cargo run --locked --example widget_catalog	Responsive live widget pages, local project logo, and a spinning wireframe cube for screenshots and video.
Gradient blocks	cargo run --locked --example gradient_blocks	Color gradients and block rendering.

For the optional graphics canvas, run cargo run --locked --features wgpu-graphics --example widget_catalog -- --motion. The line above the picture names the renderer that draws it. See Graphics canvas for the widget, fault options, limits and measurements.

The catalog uses arrows or 1–8 to select pages and Tab to focus controls. Use F1/F2 on the menus/dialogs page to capture one overlay demo at a time. Mouse-wheel scrolling reveals longer widget pages. It switches from a sidebar to compact navigation below 80 columns. Open page 3 for a full-width colored column-span grid. Example cards use compact gaps and switch between one and two columns with the terminal width. Open page 7 to record the cube animation, or page 6 for the tracked project logo. Ctrl+Q always quits. Ctrl+C and Escape quit when the active widget does not consume them (for example, Escape first closes an open menu).

The system page runs only a bounded command. It does not claim to fix the known Kitty embedded-shell crash. All catalog assets are local; no download is needed.

FFI and TypeScript

Enable ffi to build the Rust cdylib and C ABI:

cargo build --locked --features ffi --jobs 8

The public C header is include/reactive_tui.h. Opaque handles have explicit ownership, error, callback, and release rules described in the FFI manual.

The TypeScript SDK wraps the native ABI with typed owners and builders. Build and verify it with Node.js 20 or newer:

cargo build --locked --features ffi --jobs 8
cd bindings/typescript
npm ci
npm run build
npm test

The SDK does not download a native library. Set RTUI_LIBRARY_PATH or package a matching library with the TypeScript application.

Development

Keep build concurrency at eight jobs on this repository:

cargo fmt --all -- --check
cargo test --locked --lib --jobs 8
cargo clippy --locked --package reactive-tui --lib --no-deps --jobs 8 -- -D warnings
python3 -B scripts/check-framework-manual.py MAN-001
python3 -B scripts/check-framework-manual.py MAN-002

Run build and test commands sequentially. Some optional features require their platform toolchain or external program. Cairn specifications, commitments, decisions, mechanisms, evidence, and reviews record the release contracts.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, create a focused branch from main, add behavior-focused tests, update the relevant manual chapter, and keep public API documentation current.

Reactive TUI was created and is maintained by Shawn McAllister.

License

Reactive TUI is licensed under The Reactive TUI License, Version 1.0 (LICENSE, SPDX LicenseRef-ReactiveTUI-1.0): the MIT License with two riders.

For most users it is the MIT License. A person, or an organization with revenue of USD 1,000,000 a year or less, may build applications with Reactive TUI, ship them and sell them, with no fee and no permission.

Rider one: frameworks

You need written permission, a Framework License, to take Reactive TUI, or a copy of it that was changed or renamed, and offer it to other developers as a framework for building terminal applications, free or paid. Applications, copies used inside one organization, copies published to send changes to this project, and add-on libraries that depend on Reactive TUI are not affected.

Rider two: sponsorship

An organization that earns money from software built with Reactive TUI, and whose revenue, together with its affiliates, was above USD 1,000,000 in its last fiscal year, must sponsor the project for as long as it offers that software: https://github.com/sponsors/eas4ai. An organization that uses such software only inside its own business, or gives it away, owes nothing. Schools, universities and registered non-profit organizations are exempt.

What the license does not change

Versions that were published under the MIT License alone stay under it. Code of other projects inside this repository keeps its own license; see Section 4 of LICENSE.

LICENSE holds the terms. Requests for a Framework License, and questions about the license, go to [email protected]; see also https://eas4ai.com.

The project builds on Taffy for layout, Crossterm for terminal control, Comrak for Markdown, Lumis for syntax highlighting, AccessKit for accessibility semantics, and libghostty for embedded terminal interpretation.