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 frame::TextDirection;
55pub use ftui_core::terminal_capabilities::ColorDepth;
56
57// Re-export text width helpers from ftui-core (single source of truth).
58pub(crate) use ftui_core::text_width::{char_width, display_width, grapheme_width};
59
60#[cfg(test)]
61mod tests {
62    use super::{char_width, display_width, grapheme_width};
63
64    // ── display_width ────────────────────────────────────────────────
65
66    #[test]
67    fn display_width_matches_expected_samples() {
68        // Avoid CJK samples to keep results independent of locale/CJK width flags.
69        // Note: ftui-core strips VS16 (U+FE0F) by default for terminal-realistic
70        // widths, so text-default emoji like ❤️/⌨️/⚠️ measure as their base
71        // text-presentation width rather than emoji-presentation width 2.
72        let samples = [
73            ("hello", 5usize),
74            ("😀", 2usize),
75            ("👩‍💻", 2usize),
76            ("🇺🇸", 2usize),
77            ("⭐", 2usize),
78            ("A😀B", 4usize),
79            ("ok ✅", 5usize),
80        ];
81        for (sample, expected) in samples {
82            assert_eq!(
83                display_width(sample),
84                expected,
85                "display width mismatch for {sample:?}"
86            );
87        }
88    }
89
90    #[test]
91    fn display_width_empty_string() {
92        assert_eq!(display_width(""), 0);
93    }
94
95    #[test]
96    fn display_width_single_ascii_char() {
97        assert_eq!(display_width("x"), 1);
98        assert_eq!(display_width(" "), 1);
99    }
100
101    #[test]
102    fn display_width_pure_ascii_fast_path() {
103        assert_eq!(display_width("Hello, World!"), 13);
104        assert_eq!(display_width("fn main() {}"), 12);
105    }
106
107    #[test]
108    fn display_width_ascii_with_tabs() {
109        assert_eq!(display_width("a\tb"), 3);
110        assert_eq!(display_width("\n"), 1);
111    }
112
113    #[test]
114    fn display_width_mixed_ascii_emoji() {
115        assert_eq!(display_width("hi 🎉"), 5);
116        assert_eq!(display_width("🚀start"), 7);
117    }
118
119    #[test]
120    fn display_width_zero_width_chars_in_string() {
121        let s = "a\u{00AD}b";
122        assert_eq!(display_width(s), 2);
123    }
124
125    #[test]
126    fn display_width_combining_characters() {
127        let s = "e\u{0301}";
128        assert_eq!(display_width(s), 1);
129    }
130
131    #[test]
132    fn display_width_multiple_emoji() {
133        assert_eq!(display_width("😀😀😀"), 6);
134    }
135
136    // ── grapheme_width ───────────────────────────────────────────────
137
138    #[test]
139    fn grapheme_width_matches_expected_samples() {
140        // VS16 emoji (❤️/⌨️/⚠️) removed — ftui-core strips VS16 by default
141        // (terminal-realistic) so their widths depend on base char EAW, not emoji
142        // presentation.  Dedicated VS16 tests live in ftui-core.
143        let samples = [
144            ("a", 1usize),
145            ("😀", 2usize),
146            ("👩‍💻", 2usize),
147            ("🇺🇸", 2usize),
148            ("👍🏽", 2usize),
149            ("⭐", 2usize),
150        ];
151        for (grapheme, expected) in samples {
152            assert_eq!(
153                grapheme_width(grapheme),
154                expected,
155                "grapheme width mismatch for {grapheme:?}"
156            );
157        }
158    }
159
160    #[test]
161    fn grapheme_width_ascii_space() {
162        assert_eq!(grapheme_width(" "), 1);
163    }
164
165    #[test]
166    fn grapheme_width_ascii_tilde() {
167        assert_eq!(grapheme_width("~"), 1);
168    }
169
170    #[test]
171    fn grapheme_width_tab() {
172        assert_eq!(grapheme_width("\t"), 1);
173    }
174
175    #[test]
176    fn grapheme_width_newline() {
177        assert_eq!(grapheme_width("\n"), 1);
178    }
179
180    #[test]
181    fn grapheme_width_combining_accent() {
182        assert_eq!(grapheme_width("e\u{0301}"), 1);
183    }
184
185    #[test]
186    fn grapheme_width_zero_width_space() {
187        assert_eq!(grapheme_width("\u{200B}"), 0);
188    }
189
190    #[test]
191    fn grapheme_width_zero_width_joiner() {
192        assert_eq!(grapheme_width("\u{200D}"), 0);
193    }
194
195    #[test]
196    fn grapheme_width_skin_tone_modifier() {
197        assert_eq!(grapheme_width("👍🏿"), 2);
198    }
199
200    // ── char_width ───────────────────────────────────────────────────
201
202    #[test]
203    fn char_width_ascii_printable() {
204        assert_eq!(char_width('A'), 1);
205        assert_eq!(char_width('z'), 1);
206        assert_eq!(char_width(' '), 1);
207        assert_eq!(char_width('~'), 1);
208        assert_eq!(char_width('!'), 1);
209    }
210
211    #[test]
212    fn char_width_ascii_whitespace() {
213        assert_eq!(char_width('\t'), 1);
214        assert_eq!(char_width('\n'), 1);
215        assert_eq!(char_width('\r'), 1);
216    }
217
218    #[test]
219    fn char_width_ascii_control() {
220        assert_eq!(char_width('\x00'), 0);
221        assert_eq!(char_width('\x01'), 0);
222        assert_eq!(char_width('\x1F'), 0);
223        assert_eq!(char_width('\x7F'), 0);
224    }
225
226    #[test]
227    fn char_width_zero_width_combining() {
228        assert_eq!(char_width('\u{0300}'), 0);
229        assert_eq!(char_width('\u{0301}'), 0);
230    }
231
232    #[test]
233    fn char_width_zero_width_special() {
234        assert_eq!(char_width('\u{200B}'), 0);
235        assert_eq!(char_width('\u{200D}'), 0);
236        assert_eq!(char_width('\u{FEFF}'), 0);
237        assert_eq!(char_width('\u{00AD}'), 0);
238    }
239
240    #[test]
241    fn char_width_variation_selectors() {
242        assert_eq!(char_width('\u{FE00}'), 0);
243        assert_eq!(char_width('\u{FE0F}'), 0);
244    }
245
246    #[test]
247    fn char_width_bidi_controls() {
248        assert_eq!(char_width('\u{200E}'), 0);
249        assert_eq!(char_width('\u{200F}'), 0);
250    }
251
252    #[test]
253    fn char_width_normal_non_ascii() {
254        assert_eq!(char_width('é'), 1);
255        assert_eq!(char_width('ñ'), 1);
256    }
257
258    #[test]
259    fn char_width_euro_sign() {
260        assert_eq!(char_width('€'), 1);
261    }
262}