1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
//! # Tenui
//!
//! **Tenui** is a modular, high-performance terminal user interface (TUI) framework for Rust.
//! It unifies the mechanical sympathy and predictable efficiency of immediate-mode rendering
//! with the compositional power of flexbox layout, fine-grained reactivity, and an enterprise widget suite.
//!
//! ## Core Architecture & Feature Layers
//!
//! Tenui is organized as a layered stack of focused, cohesive crates through progressive disclosure:
//!
//! ```text
//! ┌────────────────────────────────────────────────────────────────────────┐
//! │ Standard Suite (tenui-std) — Chat, Tables, Code, Diff, Charts, Themes │
//! ├────────────────────────────────────────────────────────────────────────┤
//! │ Retained Runtime (tenui-runtime) — App Reactor, Focus, Invalidation │
//! ├────────────────────────────────────────────────────────────────────────┤
//! │ Layer 2 (tenui-compositor) — Z-Layers, Occlusion Cut, Spatial Nav │
//! ├────────────────────────────────────────────────────────────────────────┤
//! │ Layer 1 (tenui-reactive) — Two-Lane Bus (PAINT vs LAYOUT), Batch │
//! ├────────────────────────────────────────────────────────────────────────┤
//! │ Layer 0 (tenui-layout) — Immediate Flexbox Layout via Taffy │
//! ├────────────────────────────────────────────────────────────────────────┤
//! │ Core (tenui-core) — Cell, Buffer, Diff Coalescer, Terminal │
//! └────────────────────────────────────────────────────────────────────────┘
//! ```
//!
//! ### Progressive Feature Tiers
//!
//! - **Core ([`core`])**: The bare-metal foundation. Provides the compact 8-byte [`Cell`] data union,
//! double-buffered [`Buffer`], differential [`SgrCoalescer`] emission engine, RAII [`TerminalGuard`],
//! and non-blocking terminal I/O drivers.
//! - **Layer 0 (`layer0` / [`layout`])**: Pure-Rust immediate-mode flexbox layout engine built on Taffy.
//! Allows declarative styling and proportional grid positioning without an asynchronous runtime.
//! - **Layer 1 (`layer1` / [`reactive`])**: Fine-grained reactive signal graph and the **Two-Lane Invalidation Engine**.
//! Explicitly distinguishes cosmetic changes ([`Invalidation::PAINT`](reactive::Invalidation::PAINT)) from
//! structural changes ([`Invalidation::LAYOUT`](reactive::Invalidation::LAYOUT)), guaranteeing that paint-only
//! updates never trigger layout reflow.
//! - **Layer 2 (`layer2` / [`compositor`])**: Off-screen spatial layer compositor ([`LayerCompositor`](compositor::LayerCompositor)),
//! coordinate cut-finding occlusion culling, WICG spatial navigation, and sub-cell vector graphics
//! (Braille, half-block, and quadrant rasterizers).
//! - **Kinetics (`anim` / [`anim`])**: Closed-form analytical spring dynamics ([`AnalyticalSpring`](anim::AnalyticalSpring)),
//! sub-cell Unicode 1/8th fractional micro-stepping ([`MicroStepper`](anim::MicroStepper)), and zero-idle
//! power scheduling ([`ActiveTicker`](anim::ActiveTicker)).
//! - **Runtime (`runtime` / [`runtime`])**: Retained-mode [`App`](runtime::App) reactor driving a persistent Taffy tree,
//! focus management, and the two-lane invalidation bus.
//! - **Standard Library (`std` / [`std_widgets`])**: Batteries-included widget suite including [`ChatThread`](std_widgets::ChatThread),
//! [`VirtualTable`](std_widgets::VirtualTable), [`TextInput`](std_widgets::TextInput), [`TextEditor`](std_widgets::TextEditor),
//! [`CodeView`](std_widgets::CodeView), [`DiffView`](std_widgets::DiffView), [`Form`](std_widgets::Form),
//! [`LinePlot`](std_widgets::LinePlot), [`BarChart`](std_widgets::BarChart), [`TreeView`](std_widgets::TreeView),
//! [`FilePicker`](std_widgets::FilePicker), and [`ThemePalette`](std_widgets::ThemePalette).
//! - **Visual Effects (`vfx` / [`vfx`])**: Procedural sub-cell shaders, acrylic blur filters, particle kinematics,
//! and CRT/shimmer/glitch effects.
//! - **Extensibility (`ext` / [`ext`])**: The open [`CustomWidget`](ext::CustomWidget) trait, Tower-inspired
//! input middleware pipeline, WASM component model contract, and embedded Lua/Rhai scripting bridge.
//! - **Macros (`macros` / [`macros`])**: Compile-time declarative [`view!`] macro for structured UI composition.
//! - **Advanced Systems (`advanced`)**: Drag-and-drop docking ([`dnd`]), virtual list acceleration ([`virt`]),
//! text buffers with branching undo ([`text`]), daemon workspace persistence ([`session`]), tactile audio cues ([`sound`]),
//! and hardware-accelerated GPU terminal rendering ([`wgpu`]).
//! - **Frontier Systems (`frontier`])**: Vectorized SIMD differential scanning ([`simd`]), multi-seat CRDT presence ([`collab`]),
//! half-block video streaming ([`media`]), sub-cell math typesetting ([`math`]), hardware/MIDI input bridges ([`hid`]),
//! and stream chaos fuzzing ([`chaos`]).
//!
//! ## Quickstart: Immediate-Mode "Hello, TUI"
//!
//! Below is a minimal, fully functional immediate-mode program:
//!
//! ```no_run
//! use std::io;
//! use tenui::{Terminal, Rect, Color, Modifier};
//!
//! fn main() -> io::Result<()> {
//! // Initialize terminal and acquire RAII guard (raw mode + alternate screen)
//! let mut term = Terminal::new()?;
//!
//! // Render an immediate-mode frame
//! term.draw(|canvas| {
//! let (w, h) = (canvas.width(), canvas.height());
//! canvas.clear(Color::Reset);
//! canvas.write_str_clipped(
//! 2,
//! 1,
//! "Hello from Tenui!",
//! Color::Cyan,
//! Color::Reset,
//! );
//! })?;
//!
//! Ok(())
//! }
//! ```
//!
//! For automated testing and headless assertion, buffers can be inspected in memory without a TTY:
//!
//! ```rust
//! use tenui::{Buffer, Rect, Color};
//!
//! let mut buffer = Buffer::new(40, 5);
//! {
//! let mut canvas = buffer.subview_mut(Rect::new(0, 0, 40, 5));
//! canvas.write_str_clipped(1, 1, "Headless Test", Color::Green, Color::Reset);
//! }
//!
//! assert_eq!(buffer.get(1, 1).unwrap().symbol.as_str(), "H");
//! assert_eq!(buffer.get(2, 1).unwrap().symbol.as_str(), "e");
//! ```
//!
//! ## Flagship Example: Streaming Chat Client
//!
//! For a complete, real-world application showcasing Tenui's three-zone shell (collapsible
//! sidebar, hybrid conversational transcript, multi-line composer), live SSE token streaming,
//! reasoning blocks, mouse drag-resizing, and theme switching, run:
//!
//! ```bash
//! cargo run --release --example chat
//! ```
//!
//! Located at [`crates/tenui/examples/chat/`](https://github.com/crg-labs/tenui/tree/main/crates/tenui/examples/chat),
//! it serves as the canonical worked case study for building flagship terminal applications.
//!
//! ## The Prelude
//!
//! For convenience, common types and traits can be imported via:
//!
//! ```rust
//! use tenui::prelude::*;
//! ```
pub use crossterm;
pub use taffy;
/// Sub-cell kinetics, analytical spring physics, and dynamic occupancy ticker.
pub use tenui_anim as anim;
/// Deterministic stream chaos fuzzing and fault injection.
pub use tenui_chaos as chaos;
/// Multi-seat real-time collaborative text editing backed by CRDT algorithms.
pub use tenui_collab as collab;
/// Layer 2: Off-screen spatial layer compositor, occlusion culling, and spatial navigation.
pub use tenui_compositor as compositor;
/// Core terminal rendering engine, differential SGR coalescer, cell primitives, and terminal driver.
pub use tenui_core as core;
// Convenient root re-exports
pub use ;
/// Drag-and-drop session management and multi-panel dock layout.
pub use tenui_dnd as dnd;
/// Extensibility, WASM component model contract, Tower input middleware, and scripting bridges.
pub use tenui_ext as ext;
/// Hardware knob, MIDI, and rotary controller input reactor.
pub use tenui_hid as hid;
/// Layer 0: Immediate-mode flexbox layout engine built on Taffy.
pub use tenui_layout as layout;
/// Declarative UI macros (`view!`).
pub use tenui_macros as macros;
pub use view;
/// Mathematical formula typesetting in terminal cells.
pub use tenui_math as math;
/// Sub-cell half-block video streaming and media decoding.
pub use tenui_media as media;
/// Layer 1: Two-Lane Invalidation reactive signal graph (`PAINT` vs `LAYOUT`).
pub use tenui_reactive as reactive;
/// Retained-mode application reactor and component tree runtime.
pub use tenui_runtime as runtime;
/// Daemon session persistence and serialized workspace layouts.
pub use tenui_session as session;
/// Vectorized SIMD differential scanning for ultra-high-resolution viewports.
pub use tenui_simd as simd;
/// Tactile audio feedback engine for terminal interactions.
pub use tenui_sound as sound;
/// Batteries-included standard widget library and theme system.
pub use tenui_std as std_widgets;
/// Text editing buffer with multi-cursor support and branching undo history.
pub use tenui_text as text;
/// Procedural visual effects, shaders, acrylic blur, and particle kinematics.
pub use tenui_vfx as vfx;
/// High-capacity virtualized list widgets with Fenwick tree coordinate acceleration.
pub use tenui_virt as virt;
/// Hardware-accelerated GPU terminal rendering pipeline using WGPU.
pub use tenui_wgpu as wgpu;
/// Common imports for rapid application development with Tenui.