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
//! `ttui` — a terminal UI framework built around layered buffers,
//! `Transition`-driven animation, and dumb (no-internal-state) widgets.
//!
//! # Quick start
//!
//! An app is one type implementing [`App`](app::App). You own the state;
//! `ttui` owns the loop, the diffing, and the terminal.
//!
//! ```no_run
//! use crossterm::event::{Event, KeyCode};
//! use ttui::app::{run, App};
//! use ttui::buffer::LayerStack;
//! use ttui::layout::Rect;
//! use ttui::widgets::text::Text;
//!
//! struct Hello {
//! quit: bool,
//! }
//!
//! impl App for Hello {
//! fn update(&mut self, event: &Event) {
//! if let Event::Key(key) = event {
//! if key.code == KeyCode::Char('q') {
//! self.quit = true;
//! }
//! }
//! }
//!
//! fn view(&self, area: Rect, buf: &mut LayerStack) {
//! Text::new("hello, terminal — press q to quit").render(area, buf);
//! }
//!
//! fn should_quit(&self) -> bool {
//! self.quit
//! }
//! }
//!
//! fn main() -> std::io::Result<()> {
//! run(&mut Hello { quit: false })
//! }
//! ```
//!
//! [`run`](app::run) enables raw mode, installs a panic hook that restores
//! the terminal, and only redraws cells that actually changed.
//!
//! # How it fits together
//!
//! ```text
//! App state ──view()──▶ LayerStack ──composite()──▶ Buffer ──diff()──▶ terminal
//! ▲ │
//! └──────────────── update(event) / on_tick(elapsed) ◀─────────────────┘
//! ```
//!
//! - **[`buffer`]** — [`Cell`](buffer::Cell), [`Buffer`](buffer::Buffer) and
//! [`LayerStack`](buffer::LayerStack), the render target. Layers composite
//! top-to-bottom by alpha, so an effects layer can sit over a UI layer
//! without either knowing about the other.
//! - **[`layout`]** — splits a [`Rect`](layout::Rect) by
//! [`Constraint`](layout::Constraint)s. No widget computes its own position.
//! - **[`widgets`]** — stateless renderers. A widget is handed an area and a
//! buffer and draws; it never holds selection or scroll state, so your app
//! stays the single source of truth.
//! - **[`transition`]** — [`Transition`](transition::Transition) tracks
//! real elapsed time as `0.0..=1.0` progress, and
//! [`Phases`](transition::Phases) subdivides that progress into named
//! stages without writing every boundary twice.
//! - **[`theme`]** — one palette and border set threaded through widgets.
//!
//! Beyond the core: [`canvas`] (sub-cell half-block and braille drawing),
//! [`perspective`] (fixed-forward 3D projection), [`particles`], [`glitch`],
//! [`effects`], [`camera`], [`input`] (key chords), [`easing`], [`noise`] and
//! [`audio`].
//!
//! # Animation
//!
//! Return a [`tick_rate`](app::App::tick_rate) and `ttui` calls
//! [`on_tick`](app::App::on_tick) with the *real* elapsed time, so animation
//! stays correct when a frame runs long:
//!
//! ```
//! use std::time::Duration;
//! use ttui::transition::{Phases, Transition};
//!
//! // Three stages across one 900ms transition: 20% fade in, 60% hold,
//! // 20% fade out. Boundaries are written once, not twice.
//! const STAGES: Phases<3> = Phases::new([0.2, 0.8, 1.0]);
//!
//! let t = Transition::start(Duration::from_millis(900));
//! let (stage, progress_within) = STAGES.at(t.progress());
//! assert!(stage < 3);
//! assert!((0.0..=1.0).contains(&progress_within));
//! ```
//!
//! # Examples
//!
//! The repository carries ten runnable example apps and a `showcase` demo
//! reel. From a checkout:
//!
//! ```text
//! cargo run --bin showcase # mascot-hosted reel of five vignettes
//! cargo run --example demo # nested panes, Tab focus, list + table
//! cargo run --example falcon # cockpit: starfield, HUD, glitch effects
//! ```
//!
//! See [`examples/README.md`] for what each one demonstrates.
//!
//! [`examples/README.md`]: https://github.com/tatemeyer/ttui/blob/main/examples/README.md
/// Terminal event loop and the `App` trait apps implement.
/// `AudioSink` trait for optional sound-effect playback.
/// Cell/`Buffer`/`LayerStack` — the framework's core render target.
/// Deterministic camera viewport and brightness scaling.
/// Sub-cell rendering primitive (half-block + braille) — graduated,
/// committed API; see the module docs for `HalfBlock` vs `Braille`
/// details.
/// Linear/eased interpolation and progress helpers.
/// Screen-shake and other whole-buffer visual effects.
/// Decaying noise overlay for glitch/corruption effects.
/// Key-binding resolver: single keys and multi-key chords resolving
/// to an app-defined action type.
/// `Rect`/`Constraint`-based area splitting.
/// Deterministic seed-driven jitter for scattering and placement.
/// A simple particle system for bursts and impacts.
/// Fixed-forward pinhole-camera projection: points, lines, polygons.
/// Raw-mode terminal setup/teardown.
/// App color palette and border glyph set.
/// Time-driven progress tracking for animations, and the `Phases`
/// subdivision of a progress range.
/// Ready-to-render widgets — see `widgets` module docs.