Skip to main content

ftui_render/
lib.rs

1// Index walks over parallel slices by a single counter; an iterator rewrite would
2// obscure the arithmetic without changing behaviour.
3#![allow(clippy::needless_range_loop)]
4#![forbid(unsafe_code)]
5
6//! Render kernel: cells, buffers, diffs, and ANSI presentation.
7//!
8//! # Role in FrankenTUI
9//! `ftui-render` is the deterministic rendering engine. It turns a logical
10//! `Frame` into a `Buffer`, computes diffs, and emits minimal ANSI output via
11//! the `Presenter`.
12//!
13//! # Primary responsibilities
14//! - **Cell/Buffer**: 2D grid with fixed-size cells and scissor/opacity stacks.
15//! - **BufferDiff**: efficient change detection between frames.
16//! - **Presenter**: stateful ANSI emitter with cursor/mode tracking.
17//! - **Frame**: rendering surface used by widgets and application views.
18//!
19//! # How it fits in the system
20//! `ftui-runtime` calls your model's `view()` to render into a `Frame`. That
21//! frame becomes a `Buffer`, which is diffed and presented to the terminal via
22//! `TerminalWriter`. This crate is the kernel of FrankenTUI's flicker-free,
23//! deterministic output guarantees.
24
25pub mod alloc_budget;
26pub mod ansi;
27pub mod arena;
28pub mod budget;
29pub mod buffer;
30pub mod cell;
31pub mod counting_writer;
32pub mod diff;
33pub mod diff_strategy;
34pub mod drawing;
35pub mod fit_metrics;
36pub mod frame;
37pub mod frame_guardrails;
38pub mod grapheme_pool;
39pub mod headless;
40pub mod link_registry;
41pub mod presenter;
42pub mod render_certificate;
43
44pub mod quotient_filter;
45#[cfg(feature = "experimental")]
46pub mod roaring_bitmap;
47pub mod sanitize;
48pub mod spatial_hit_index;
49pub mod terminal_model;
50
51// Terminal color fidelity is owned by ftui-core and re-exported here so the
52// downstream style layer can share the exact contract without a dependency
53// cycle back from the render kernel.
54pub use ftui_core::terminal_capabilities::ColorDepth;
55
56// Re-export text width helpers from ftui-core (single source of truth).
57pub(crate) use ftui_core::text_width::{char_width, display_width, grapheme_width};
58
59#[cfg(test)]
60mod tests {
61    use super::{char_width, display_width, grapheme_width};
62
63    // ── display_width ────────────────────────────────────────────────
64
65    #[test]
66    fn display_width_matches_expected_samples() {
67        // Avoid CJK samples to keep results independent of locale/CJK width flags.
68        // Note: ftui-core strips VS16 (U+FE0F) by default for terminal-realistic
69        // widths, so text-default emoji like ❤️/⌨️/⚠️ measure as their base
70        // text-presentation width rather than emoji-presentation width 2.
71        let samples = [
72            ("hello", 5usize),
73            ("😀", 2usize),
74            ("👩‍💻", 2usize),
75            ("🇺🇸", 2usize),
76            ("⭐", 2usize),
77            ("A😀B", 4usize),
78            ("ok ✅", 5usize),
79        ];
80        for (sample, expected) in samples {
81            assert_eq!(
82                display_width(sample),
83                expected,
84                "display width mismatch for {sample:?}"
85            );
86        }
87    }
88
89    #[test]
90    fn display_width_empty_string() {
91        assert_eq!(display_width(""), 0);
92    }
93
94    #[test]
95    fn display_width_single_ascii_char() {
96        assert_eq!(display_width("x"), 1);
97        assert_eq!(display_width(" "), 1);
98    }
99
100    #[test]
101    fn display_width_pure_ascii_fast_path() {
102        assert_eq!(display_width("Hello, World!"), 13);
103        assert_eq!(display_width("fn main() {}"), 12);
104    }
105
106    #[test]
107    fn display_width_ascii_with_tabs() {
108        assert_eq!(display_width("a\tb"), 3);
109        assert_eq!(display_width("\n"), 1);
110    }
111
112    #[test]
113    fn display_width_mixed_ascii_emoji() {
114        assert_eq!(display_width("hi 🎉"), 5);
115        assert_eq!(display_width("🚀start"), 7);
116    }
117
118    #[test]
119    fn display_width_zero_width_chars_in_string() {
120        let s = "a\u{00AD}b";
121        assert_eq!(display_width(s), 2);
122    }
123
124    #[test]
125    fn display_width_combining_characters() {
126        let s = "e\u{0301}";
127        assert_eq!(display_width(s), 1);
128    }
129
130    #[test]
131    fn display_width_multiple_emoji() {
132        assert_eq!(display_width("😀😀😀"), 6);
133    }
134
135    // ── grapheme_width ───────────────────────────────────────────────
136
137    #[test]
138    fn grapheme_width_matches_expected_samples() {
139        // VS16 emoji (❤️/⌨️/⚠️) removed — ftui-core strips VS16 by default
140        // (terminal-realistic) so their widths depend on base char EAW, not emoji
141        // presentation.  Dedicated VS16 tests live in ftui-core.
142        let samples = [
143            ("a", 1usize),
144            ("😀", 2usize),
145            ("👩‍💻", 2usize),
146            ("🇺🇸", 2usize),
147            ("👍🏽", 2usize),
148            ("⭐", 2usize),
149        ];
150        for (grapheme, expected) in samples {
151            assert_eq!(
152                grapheme_width(grapheme),
153                expected,
154                "grapheme width mismatch for {grapheme:?}"
155            );
156        }
157    }
158
159    #[test]
160    fn grapheme_width_ascii_space() {
161        assert_eq!(grapheme_width(" "), 1);
162    }
163
164    #[test]
165    fn grapheme_width_ascii_tilde() {
166        assert_eq!(grapheme_width("~"), 1);
167    }
168
169    #[test]
170    fn grapheme_width_tab() {
171        assert_eq!(grapheme_width("\t"), 1);
172    }
173
174    #[test]
175    fn grapheme_width_newline() {
176        assert_eq!(grapheme_width("\n"), 1);
177    }
178
179    #[test]
180    fn grapheme_width_combining_accent() {
181        assert_eq!(grapheme_width("e\u{0301}"), 1);
182    }
183
184    #[test]
185    fn grapheme_width_zero_width_space() {
186        assert_eq!(grapheme_width("\u{200B}"), 0);
187    }
188
189    #[test]
190    fn grapheme_width_zero_width_joiner() {
191        assert_eq!(grapheme_width("\u{200D}"), 0);
192    }
193
194    #[test]
195    fn grapheme_width_skin_tone_modifier() {
196        assert_eq!(grapheme_width("👍🏿"), 2);
197    }
198
199    // ── char_width ───────────────────────────────────────────────────
200
201    #[test]
202    fn char_width_ascii_printable() {
203        assert_eq!(char_width('A'), 1);
204        assert_eq!(char_width('z'), 1);
205        assert_eq!(char_width(' '), 1);
206        assert_eq!(char_width('~'), 1);
207        assert_eq!(char_width('!'), 1);
208    }
209
210    #[test]
211    fn char_width_ascii_whitespace() {
212        assert_eq!(char_width('\t'), 1);
213        assert_eq!(char_width('\n'), 1);
214        assert_eq!(char_width('\r'), 1);
215    }
216
217    #[test]
218    fn char_width_ascii_control() {
219        assert_eq!(char_width('\x00'), 0);
220        assert_eq!(char_width('\x01'), 0);
221        assert_eq!(char_width('\x1F'), 0);
222        assert_eq!(char_width('\x7F'), 0);
223    }
224
225    #[test]
226    fn char_width_zero_width_combining() {
227        assert_eq!(char_width('\u{0300}'), 0);
228        assert_eq!(char_width('\u{0301}'), 0);
229    }
230
231    #[test]
232    fn char_width_zero_width_special() {
233        assert_eq!(char_width('\u{200B}'), 0);
234        assert_eq!(char_width('\u{200D}'), 0);
235        assert_eq!(char_width('\u{FEFF}'), 0);
236        assert_eq!(char_width('\u{00AD}'), 0);
237    }
238
239    #[test]
240    fn char_width_variation_selectors() {
241        assert_eq!(char_width('\u{FE00}'), 0);
242        assert_eq!(char_width('\u{FE0F}'), 0);
243    }
244
245    #[test]
246    fn char_width_bidi_controls() {
247        assert_eq!(char_width('\u{200E}'), 0);
248        assert_eq!(char_width('\u{200F}'), 0);
249    }
250
251    #[test]
252    fn char_width_normal_non_ascii() {
253        assert_eq!(char_width('é'), 1);
254        assert_eq!(char_width('ñ'), 1);
255    }
256
257    #[test]
258    fn char_width_euro_sign() {
259        assert_eq!(char_width('€'), 1);
260    }
261}