1#![cfg_attr(not(test), forbid(unsafe_code))]
3#![cfg_attr(test, deny(unsafe_code))]
4
5pub mod animation;
24pub mod arena;
25pub use arena::{BumpVec, DEFAULT_ARENA_CAPACITY, FrameArena};
26pub mod capability_override;
27pub mod cursor;
28pub mod cx;
29pub mod event;
30pub mod event_coalescer;
31pub use event_coalescer::EventCoalescer;
32pub mod generic_diff;
33pub mod generic_repr;
34pub mod geometry;
35pub mod gesture;
36pub mod glyph_policy;
37pub mod hover_stabilizer;
38pub mod inline_mode;
39pub mod input_parser;
40pub mod key_sequence;
41pub mod keybinding;
42pub mod logging;
43pub mod mode_typestate;
44pub mod mux_passthrough;
45pub mod osc52;
46pub mod read_optimized;
47pub mod s3_fifo;
48pub mod semantic_event;
49pub mod session_teardown;
50pub mod terminal_capabilities;
51#[cfg(all(not(target_arch = "wasm32"), feature = "crossterm"))]
52pub mod terminal_session;
53pub mod voi;
54pub use session_teardown::with_panic_cleanup_suppressed;
55
56pub const TARGET_INPUT_PARSER: &str = "ftui.input.parser";
58
59pub const TARGET_EPROCESS: &str = "ftui.eprocess";
61
62pub mod shutdown_signal {
63 use std::sync::{
70 Mutex, OnceLock,
71 atomic::{AtomicI32, Ordering},
72 };
73
74 static PENDING_TERMINATION_SIGNAL: AtomicI32 = AtomicI32::new(0);
75
76 pub fn record_pending_termination_signal(signal: i32) {
81 let _ = PENDING_TERMINATION_SIGNAL.compare_exchange(
82 0,
83 signal,
84 Ordering::SeqCst,
85 Ordering::SeqCst,
86 );
87 }
88
89 #[must_use]
91 pub fn pending_termination_signal() -> Option<i32> {
92 match PENDING_TERMINATION_SIGNAL.load(Ordering::SeqCst) {
93 0 => None,
94 signal => Some(signal),
95 }
96 }
97
98 pub fn clear_pending_termination_signal() {
100 PENDING_TERMINATION_SIGNAL.store(0, Ordering::SeqCst);
101 }
102
103 #[doc(hidden)]
110 pub fn with_test_signal_serialization<R>(f: impl FnOnce() -> R) -> R {
111 static SIGNAL_TEST_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
112
113 let _guard = SIGNAL_TEST_LOCK
119 .get_or_init(|| Mutex::new(()))
120 .lock()
121 .unwrap_or_else(|poison| poison.into_inner());
122
123 struct ClearOnDrop;
128 impl Drop for ClearOnDrop {
129 fn drop(&mut self) {
130 clear_pending_termination_signal();
131 }
132 }
133
134 clear_pending_termination_signal();
135 let _clear_on_exit = ClearOnDrop;
136 f()
137 }
138
139 #[cfg(test)]
140 mod tests {
141 use super::*;
142
143 #[test]
144 fn serialization_clears_and_stays_usable_when_the_body_panics() {
145 let caught = std::panic::catch_unwind(|| {
146 with_test_signal_serialization(|| {
147 record_pending_termination_signal(15);
150 panic!("a signal test failing inside the critical section");
151 })
152 });
153 assert!(caught.is_err(), "the panic should propagate to the caller");
154 assert!(
155 pending_termination_signal().is_none(),
156 "a panicking body must not leave a pending signal behind"
157 );
158
159 with_test_signal_serialization(|| {
161 assert!(pending_termination_signal().is_none());
162 });
163 }
164 }
165}
166
167pub mod job_control {
168 #[cfg(unix)]
182 use std::sync::{
183 Arc, OnceLock,
184 atomic::{AtomicBool, AtomicUsize, Ordering},
185 };
186
187 #[cfg(unix)]
190 struct Handlers {
191 pending: Arc<AtomicUsize>,
192 unclaimed: Arc<AtomicBool>,
193 claims: AtomicUsize,
194 }
195
196 #[cfg(unix)]
197 fn handlers() -> Option<&'static Handlers> {
198 use signal_hook::consts::signal::{SIGTSTP, SIGTTIN, SIGTTOU};
199 static HANDLERS: OnceLock<Option<Handlers>> = OnceLock::new();
200 HANDLERS
201 .get_or_init(|| {
202 let pending = Arc::new(AtomicUsize::new(0));
203 let unclaimed = Arc::new(AtomicBool::new(true));
204 for signal in [SIGTSTP, SIGTTIN, SIGTTOU] {
205 signal_hook::flag::register_conditional_default(signal, Arc::clone(&unclaimed))
208 .ok()?;
209 let value = usize::try_from(signal).ok()?;
210 signal_hook::flag::register_usize(signal, Arc::clone(&pending), value).ok()?;
211 }
212 Some(Handlers {
213 pending,
214 unclaimed,
215 claims: AtomicUsize::new(0),
216 })
217 })
218 .as_ref()
219 }
220
221 #[cfg(unix)]
225 pub const KEYBOARD_STOP_SIGNAL: i32 = signal_hook::consts::signal::SIGTSTP;
226 #[cfg(not(unix))]
228 pub const KEYBOARD_STOP_SIGNAL: i32 = 20;
229
230 #[derive(Debug)]
232 pub struct JobControlClaim {
233 _private: (),
234 }
235
236 impl JobControlClaim {
237 #[must_use]
242 pub fn acquire() -> Option<Self> {
243 #[cfg(unix)]
244 {
245 let handlers = handlers()?;
246 if handlers.claims.fetch_add(1, Ordering::SeqCst) == 0 {
247 handlers.pending.store(0, Ordering::SeqCst);
251 handlers.unclaimed.store(false, Ordering::SeqCst);
252 }
253 Some(Self { _private: () })
254 }
255 #[cfg(not(unix))]
256 {
257 None
258 }
259 }
260
261 #[must_use]
263 pub fn take_pending(&self) -> Option<i32> {
264 #[cfg(unix)]
265 {
266 let signal = handlers()?.pending.swap(0, Ordering::SeqCst);
267 i32::try_from(signal).ok().filter(|&signal| signal != 0)
268 }
269 #[cfg(not(unix))]
270 {
271 None
272 }
273 }
274 }
275
276 impl Drop for JobControlClaim {
277 fn drop(&mut self) {
278 #[cfg(unix)]
279 if let Some(handlers) = handlers()
280 && handlers.claims.fetch_sub(1, Ordering::SeqCst) == 1
281 {
282 handlers.unclaimed.store(true, Ordering::SeqCst);
283 }
284 }
285 }
286
287 pub fn stop_process(signal: i32) -> std::io::Result<()> {
299 #[cfg(unix)]
300 {
301 signal_hook::low_level::emulate_default_handler(signal)
302 }
303 #[cfg(not(unix))]
304 {
305 let _ = signal;
306 Err(std::io::Error::new(
307 std::io::ErrorKind::Unsupported,
308 "job control is Unix-only",
309 ))
310 }
311 }
312
313 #[cfg(all(test, unix))]
314 mod tests {
315 use super::*;
316 use std::sync::{Mutex, MutexGuard};
317
318 fn serial() -> MutexGuard<'static, ()> {
320 static LOCK: Mutex<()> = Mutex::new(());
321 LOCK.lock().unwrap_or_else(|poison| poison.into_inner())
322 }
323
324 #[test]
325 fn claims_are_counted_and_the_default_returns_with_the_last() {
326 let _serial = serial();
327 let handlers = handlers().expect("handlers install on unix");
330 let before = handlers.claims.load(Ordering::SeqCst);
331 let first = JobControlClaim::acquire().expect("claim");
332 let second = JobControlClaim::acquire().expect("claim");
333 assert!(!handlers.unclaimed.load(Ordering::SeqCst));
334 drop(first);
335 assert!(
336 !handlers.unclaimed.load(Ordering::SeqCst),
337 "one claim still held"
338 );
339 drop(second);
340 if before == 0 {
341 assert!(handlers.unclaimed.load(Ordering::SeqCst));
342 }
343 }
344
345 #[test]
346 fn pending_signal_is_taken_once() {
347 let _serial = serial();
348 let claim = JobControlClaim::acquire().expect("claim");
349 let handlers = handlers().expect("handlers");
350 handlers.pending.store(20, Ordering::SeqCst);
351 assert_eq!(claim.take_pending(), Some(20));
352 assert_eq!(claim.take_pending(), None);
353 }
354 }
355}
356
357#[cfg(feature = "caps-probe")]
358pub mod caps_probe;
359
360#[cfg(feature = "tracing")]
362pub use logging::{
363 debug, debug_span, error, error_span, info, info_span, trace, trace_span, warn, warn_span,
364};
365
366pub mod text_width {
367 use std::sync::OnceLock;
398
399 use unicode_display_width::width as unicode_display_width;
400 use unicode_segmentation::UnicodeSegmentation;
401 use unicode_width::UnicodeWidthChar;
402
403 #[inline]
404 fn env_flag(value: &str) -> bool {
405 matches!(
406 value.trim().to_ascii_lowercase().as_str(),
407 "1" | "true" | "yes" | "on"
408 )
409 }
410
411 #[inline]
412 fn is_cjk_locale(locale: &str) -> bool {
413 let lower = locale.trim().to_ascii_lowercase();
414 lower.starts_with("ja") || lower.starts_with("zh") || lower.starts_with("ko")
415 }
416
417 #[inline]
418 fn cjk_width_from_env_impl<F>(get_env: F) -> bool
419 where
420 F: Fn(&str) -> Option<String>,
421 {
422 if let Some(value) = get_env("FTUI_GLYPH_DOUBLE_WIDTH") {
423 return env_flag(&value);
424 }
425 if let Some(value) = get_env("FTUI_TEXT_CJK_WIDTH").or_else(|| get_env("FTUI_CJK_WIDTH")) {
426 return env_flag(&value);
427 }
428 if let Some(locale) = get_env("LC_CTYPE").or_else(|| get_env("LANG")) {
429 return is_cjk_locale(&locale);
430 }
431 false
432 }
433
434 #[inline]
435 fn use_cjk_width() -> bool {
436 static CJK_WIDTH: OnceLock<bool> = OnceLock::new();
437 *CJK_WIDTH.get_or_init(|| cjk_width_from_env_impl(|key| std::env::var(key).ok()))
438 }
439
440 #[inline]
447 fn trust_vs16_width() -> bool {
448 static TRUST: OnceLock<bool> = OnceLock::new();
449 *TRUST.get_or_init(|| {
450 std::env::var("FTUI_EMOJI_VS16_WIDTH")
451 .map(|v| v.eq_ignore_ascii_case("unicode") || v == "2")
452 .unwrap_or(false)
453 })
454 }
455
456 #[inline]
458 pub fn vs16_trust_from_env<F>(get_env: F) -> bool
459 where
460 F: Fn(&str) -> Option<String>,
461 {
462 get_env("FTUI_EMOJI_VS16_WIDTH")
463 .map(|v| v.eq_ignore_ascii_case("unicode") || v == "2")
464 .unwrap_or(false)
465 }
466
467 #[inline]
469 pub fn vs16_width_trusted() -> bool {
470 trust_vs16_width()
471 }
472
473 #[inline]
476 fn strip_vs16(grapheme: &str) -> Option<String> {
477 if grapheme.contains('\u{FE0F}') {
478 Some(grapheme.chars().filter(|&c| c != '\u{FE0F}').collect())
479 } else {
480 None
481 }
482 }
483
484 #[inline]
486 pub fn cjk_width_from_env<F>(get_env: F) -> bool
487 where
488 F: Fn(&str) -> Option<String>,
489 {
490 cjk_width_from_env_impl(get_env)
491 }
492
493 #[inline]
495 pub fn cjk_width_enabled() -> bool {
496 use_cjk_width()
497 }
498
499 #[inline]
500 fn ascii_display_width(text: &str) -> usize {
501 let mut width = 0;
502 for b in text.bytes() {
503 match b {
504 b'\t' | b'\n' | b'\r' => width += 1,
505 0x20..=0x7E => width += 1,
506 _ => {}
507 }
508 }
509 width
510 }
511
512 #[inline]
523 #[must_use]
524 pub fn ascii_width(text: &str) -> Option<usize> {
525 #[cfg(feature = "simd")]
526 {
527 ftui_simd::ascii_width(text.as_bytes())
528 }
529 #[cfg(not(feature = "simd"))]
530 {
531 ascii_width_scalar(text)
532 }
533 }
534
535 #[inline]
538 #[must_use]
539 pub fn ascii_width_scalar(text: &str) -> Option<usize> {
540 if text.bytes().all(|b| (0x20..=0x7E).contains(&b)) {
541 Some(text.len())
542 } else {
543 None
544 }
545 }
546
547 #[inline]
548 fn is_zero_width_codepoint(c: char) -> bool {
549 let u = c as u32;
550 matches!(u, 0x0000..=0x001F | 0x007F..=0x009F)
551 || matches!(u, 0x0300..=0x036F | 0x1AB0..=0x1AFF | 0x1DC0..=0x1DFF | 0x20D0..=0x20FF)
552 || matches!(u, 0xFE20..=0xFE2F)
553 || matches!(u, 0xFE00..=0xFE0F | 0xE0100..=0xE01EF)
554 || matches!(
555 u,
556 0x00AD
557 | 0x034F
558 | 0x180E
559 | 0x200B
560 | 0x200C
561 | 0x200D
562 | 0x200E
563 | 0x200F
564 | 0x2060
565 | 0xFEFF
566 )
567 || matches!(u, 0x202A..=0x202E | 0x2066..=0x2069 | 0x206A..=0x206F)
568 }
569
570 const WIDTH_CACHE_CAPACITY: usize = 4096;
576
577 const WIDTH_CACHE_MAX_GRAPHEME_BYTES: usize = 128;
580
581 struct CachedGraphemeWidth {
582 grapheme: Box<str>,
583 width: usize,
584 }
585
586 pub const TARGET_WIDTH_CACHE: &str = "ftui.text.width_cache";
588
589 struct GraphemeWidthCache {
590 entries: crate::s3_fifo::S3Fifo<u64, CachedGraphemeWidth>,
591 hits: u64,
592 misses: u64,
593 }
594
595 impl GraphemeWidthCache {
596 fn new(capacity: usize) -> Self {
597 Self {
598 entries: crate::s3_fifo::S3Fifo::new(capacity),
599 hits: 0,
600 misses: 0,
601 }
602 }
603
604 fn width(&mut self, grapheme: &str, key: u64) -> usize {
605 if let Some(entry) = self.entries.get(&key)
606 && entry.grapheme.as_ref() == grapheme
607 {
608 self.hits += 1;
609 return entry.width;
610 }
611
612 self.misses += 1;
613 #[cfg(feature = "tracing")]
614 tracing::trace!(target: TARGET_WIDTH_CACHE, grapheme, key, "width cache miss");
615 let width = grapheme_width_uncached(grapheme);
616 self.entries.insert(
617 key,
618 CachedGraphemeWidth {
619 grapheme: grapheme.into(),
620 width,
621 },
622 );
623 width
624 }
625
626 fn stats(&self) -> crate::s3_fifo::S3FifoStats {
627 let mut stats = self.entries.stats();
628 stats.hits = self.hits;
631 stats.misses = self.misses;
632 stats
633 }
634
635 fn clear(&mut self) {
636 self.entries.clear();
637 self.hits = 0;
638 self.misses = 0;
639 }
640 }
641
642 #[inline]
645 fn use_width_cache() -> bool {
646 static ENABLED: OnceLock<bool> = OnceLock::new();
647 *ENABLED.get_or_init(|| {
648 std::env::var("FTUI_WIDTH_CACHE")
649 .map(|value| {
650 !matches!(
651 value.trim().to_ascii_lowercase().as_str(),
652 "0" | "false" | "off" | "no"
653 )
654 })
655 .unwrap_or(true)
656 })
657 }
658
659 thread_local! {
660 static WIDTH_CACHE: std::cell::RefCell<GraphemeWidthCache> =
668 std::cell::RefCell::new(GraphemeWidthCache::new(WIDTH_CACHE_CAPACITY));
669 }
670
671 #[inline]
672 fn grapheme_cache_key(grapheme: &str) -> u64 {
673 use std::hash::{BuildHasher, Hasher};
674 let mut hasher =
675 ahash::RandomState::with_seeds(0x5749_4454, 0x485f_4341, 0x4348_455f, 0x4b45_5921)
676 .build_hasher();
677 hasher.write(grapheme.as_bytes());
678 hasher.finish()
679 }
680
681 #[must_use]
688 pub fn width_cache_stats() -> Option<crate::s3_fifo::S3FifoStats> {
689 if !use_width_cache() {
690 return None;
691 }
692 Some(WIDTH_CACHE.with(|cache| cache.borrow().stats()))
693 }
694
695 pub fn clear_width_cache() {
697 WIDTH_CACHE.with(|cache| cache.borrow_mut().clear());
698 }
699
700 #[inline]
706 #[must_use]
707 pub fn grapheme_width(grapheme: &str) -> usize {
708 if grapheme.is_ascii() {
709 return ascii_display_width(grapheme);
710 }
711 if !use_width_cache() || grapheme.len() > WIDTH_CACHE_MAX_GRAPHEME_BYTES {
712 return grapheme_width_uncached(grapheme);
713 }
714 let key = grapheme_cache_key(grapheme);
715 cached_grapheme_width(grapheme, key)
716 }
717
718 #[inline]
719 fn cached_grapheme_width(grapheme: &str, key: u64) -> usize {
720 WIDTH_CACHE.with(|cache| cache.borrow_mut().width(grapheme, key))
721 }
722
723 #[inline]
726 #[must_use]
727 pub fn grapheme_width_uncached(grapheme: &str) -> usize {
728 grapheme_width_with_cjk(grapheme, use_cjk_width())
729 }
730
731 #[must_use]
738 pub fn grapheme_width_with_cjk(grapheme: &str, cjk: bool) -> usize {
739 if grapheme.is_ascii() {
740 return ascii_display_width(grapheme);
741 }
742 if grapheme.chars().all(is_zero_width_codepoint) {
743 return 0;
744 }
745 let base_width = if !trust_vs16_width()
749 && let Some(stripped) = strip_vs16(grapheme)
750 {
751 if stripped.is_empty() {
752 return 0;
753 }
754 unicode_display_width(&stripped) as usize
755 } else {
756 unicode_display_width(grapheme) as usize
757 };
758 if cjk
759 && base_width == 1
760 && grapheme
761 .chars()
762 .any(|c| !is_zero_width_codepoint(c) && c.width_cjk() == Some(2))
763 {
764 return 2;
769 }
770 base_width
771 }
772
773 #[inline]
775 #[must_use]
776 pub fn char_width(ch: char) -> usize {
777 if ch.is_ascii() {
778 return match ch {
779 '\t' | '\n' | '\r' => 1,
780 ' '..='~' => 1,
781 _ => 0,
782 };
783 }
784 if is_zero_width_codepoint(ch) {
785 return 0;
786 }
787 if use_cjk_width() {
788 ch.width_cjk().unwrap_or(0)
789 } else {
790 ch.width().unwrap_or(0)
791 }
792 }
793
794 #[inline]
801 #[must_use]
802 pub fn display_width(text: &str) -> usize {
803 if let Some(width) = ascii_width(text) {
804 return width;
805 }
806 if text.is_ascii() {
807 return ascii_display_width(text);
808 }
809 text.graphemes(true).map(grapheme_width).sum()
810 }
811
812 #[cfg(test)]
813 mod tests {
814 use super::*;
815
816 const CORPUS: &[&str] = &[
819 "é",
820 "日",
821 "本",
822 "語",
823 "한",
824 "😀",
825 "👨👩👧👦",
826 "🇯🇵",
827 "\u{1F3F4}\u{E0067}",
828 "a\u{0301}",
829 "\u{200B}",
830 "\u{FE0F}",
831 "☂\u{FE0F}",
832 "ア",
833 "Ω",
834 "→",
835 "…",
836 ];
837
838 #[test]
839 fn width_cache_rejects_hash_collisions() {
840 clear_width_cache();
841 for grapheme in ["\u{200B}", "日", "é", "👨👩👧👦", "\u{200B}"] {
844 for _ in 0..2 {
845 assert_eq!(
846 cached_grapheme_width(grapheme, 0),
847 grapheme_width_uncached(grapheme),
848 "collision changed the width of {grapheme:?}"
849 );
850 }
851 }
852 let stats = WIDTH_CACHE.with(|cache| cache.borrow().stats());
853 assert_eq!(stats.hits, 5, "only exact repeats are cache hits");
854 assert_eq!(stats.misses, 5, "collisions are cache misses");
855 assert_eq!(stats.small_size + stats.main_size, 1);
856 }
857
858 #[test]
859 fn width_cache_collision_and_eviction_order_preserves_corpus() {
860 let mut cache = GraphemeWidthCache::new(4);
861 for round in 0..32 {
862 for offset in 0..CORPUS.len() {
863 let index = (round + offset) % CORPUS.len();
864 let grapheme = CORPUS[index];
865 let key = (index % 6) as u64;
868 let expected = grapheme_width_uncached(grapheme);
869 assert_eq!(cache.width(grapheme, key), expected);
870 assert_eq!(cache.width(grapheme, key), expected);
871 let stats = cache.stats();
872 assert!(stats.small_size + stats.main_size <= 4);
873 assert!(stats.ghost_size <= 1);
874 }
875 }
876 }
877
878 #[test]
879 fn width_cache_bypasses_unbounded_combining_clusters() {
880 clear_width_cache();
881 let grapheme = format!("a{}", "\u{0301}".repeat(WIDTH_CACHE_MAX_GRAPHEME_BYTES));
882 assert_eq!(grapheme.graphemes(true).count(), 1);
883 assert!(grapheme.len() > WIDTH_CACHE_MAX_GRAPHEME_BYTES);
884 let before = WIDTH_CACHE.with(|cache| cache.borrow().stats());
885 for _ in 0..3 {
886 assert_eq!(
887 grapheme_width(&grapheme),
888 grapheme_width_uncached(&grapheme)
889 );
890 }
891 assert_eq!(WIDTH_CACHE.with(|cache| cache.borrow().stats()), before);
892 }
893
894 #[test]
895 fn width_cache_retained_key_boundary() {
896 clear_width_cache();
897 let grapheme = format!("é{}", "\u{0301}".repeat(63));
898 assert_eq!(grapheme.len(), WIDTH_CACHE_MAX_GRAPHEME_BYTES);
899 assert_eq!(grapheme.graphemes(true).count(), 1);
900 for _ in 0..2 {
901 assert_eq!(
902 grapheme_width(&grapheme),
903 grapheme_width_uncached(&grapheme)
904 );
905 }
906 if let Some(stats) = width_cache_stats() {
907 assert_eq!(stats.hits, 1);
908 assert_eq!(stats.misses, 1);
909 }
910 }
911
912 #[test]
913 fn width_cache_is_thread_local_and_clear_resets_identity() {
914 clear_width_cache();
915 assert_eq!(
916 cached_grapheme_width("日", 0),
917 grapheme_width_uncached("日")
918 );
919 let parent_stats = WIDTH_CACHE.with(|cache| cache.borrow().stats());
920 std::thread::spawn(|| {
921 let initial = WIDTH_CACHE.with(|cache| cache.borrow().stats());
922 assert_eq!(initial.hits + initial.misses, 0);
923 assert_eq!(cached_grapheme_width("\u{200B}", 0), 0);
924 clear_width_cache();
925 let cleared = WIDTH_CACHE.with(|cache| cache.borrow().stats());
926 assert_eq!(cleared.hits + cleared.misses, 0);
927 assert_eq!(cleared.small_size + cleared.main_size, 0);
928 })
929 .join()
930 .expect("thread-local cache checks");
931 assert_eq!(
932 WIDTH_CACHE.with(|cache| cache.borrow().stats()),
933 parent_stats
934 );
935 assert_eq!(
936 cached_grapheme_width("日", 0),
937 grapheme_width_uncached("日")
938 );
939 }
940
941 #[test]
944 fn width_cache_is_transparent_and_hits_on_repeat() {
945 clear_width_cache();
946 let before = width_cache_stats();
947 for grapheme in CORPUS {
948 assert_eq!(
949 grapheme_width(grapheme),
950 grapheme_width_uncached(grapheme),
951 "cached width differs for {grapheme:?}"
952 );
953 }
954 for grapheme in CORPUS {
955 assert_eq!(grapheme_width(grapheme), grapheme_width_uncached(grapheme));
956 }
957 if let (Some(before), Some(after)) = (before, width_cache_stats()) {
958 assert!(
959 after.hits >= before.hits + CORPUS.len() as u64,
960 "second pass must hit the cache: before={before:?} after={after:?}"
961 );
962 assert!(after.small_size + after.main_size >= 1);
963 }
964 }
965
966 #[test]
968 fn width_cache_skips_ascii() {
969 clear_width_cache();
970 let before = width_cache_stats();
971 for text in ["a", "hello", " ", "~", "\t"] {
972 let _ = grapheme_width(text);
973 }
974 let after = width_cache_stats();
975 assert_eq!(before.map(|s| s.hits), after.map(|s| s.hits));
976 assert_eq!(before.map(|s| s.misses), after.map(|s| s.misses));
977 }
978
979 #[test]
982 fn display_width_matches_uncached_sum_on_mixed_text() {
983 let samples = [
984 "hello 世界 👋🏽 done",
985 "table │ 日本語 │ ok",
986 "🇯🇵🇺🇸 flags and ☂\u{FE0F} rain",
987 "combining a\u{0301}e\u{0301} marks",
988 ];
989 for text in samples {
990 let expected: usize = text.graphemes(true).map(grapheme_width_uncached).sum();
991 assert_eq!(display_width(text), expected, "{text:?}");
992 assert_eq!(display_width(text), expected, "second pass {text:?}");
993 }
994 }
995
996 #[test]
999 fn cjk_width_env_explicit_true() {
1000 let get = |key: &str| match key {
1001 "FTUI_GLYPH_DOUBLE_WIDTH" => Some("1".into()),
1002 _ => None,
1003 };
1004 assert!(cjk_width_from_env(get));
1005 }
1006
1007 #[test]
1008 fn cjk_width_env_explicit_false() {
1009 let get = |key: &str| match key {
1010 "FTUI_GLYPH_DOUBLE_WIDTH" => Some("0".into()),
1011 _ => None,
1012 };
1013 assert!(!cjk_width_from_env(get));
1014 }
1015
1016 #[test]
1017 fn cjk_width_env_text_cjk_key() {
1018 let get = |key: &str| match key {
1019 "FTUI_TEXT_CJK_WIDTH" => Some("true".into()),
1020 _ => None,
1021 };
1022 assert!(cjk_width_from_env(get));
1023 }
1024
1025 #[test]
1026 fn cjk_width_env_fallback_key() {
1027 let get = |key: &str| match key {
1028 "FTUI_CJK_WIDTH" => Some("yes".into()),
1029 _ => None,
1030 };
1031 assert!(cjk_width_from_env(get));
1032 }
1033
1034 #[test]
1035 fn cjk_width_env_japanese_locale() {
1036 let get = |key: &str| match key {
1037 "LC_CTYPE" => Some("ja_JP.UTF-8".into()),
1038 _ => None,
1039 };
1040 assert!(cjk_width_from_env(get));
1041 }
1042
1043 #[test]
1044 fn cjk_width_env_chinese_locale() {
1045 let get = |key: &str| match key {
1046 "LANG" => Some("zh_CN.UTF-8".into()),
1047 _ => None,
1048 };
1049 assert!(cjk_width_from_env(get));
1050 }
1051
1052 #[test]
1053 fn cjk_width_env_korean_locale() {
1054 let get = |key: &str| match key {
1055 "LC_CTYPE" => Some("ko_KR.UTF-8".into()),
1056 _ => None,
1057 };
1058 assert!(cjk_width_from_env(get));
1059 }
1060
1061 #[test]
1062 fn cjk_width_env_english_locale_returns_false() {
1063 let get = |key: &str| match key {
1064 "LANG" => Some("en_US.UTF-8".into()),
1065 _ => None,
1066 };
1067 assert!(!cjk_width_from_env(get));
1068 }
1069
1070 #[test]
1071 fn cjk_width_env_no_vars_returns_false() {
1072 let get = |_: &str| -> Option<String> { None };
1073 assert!(!cjk_width_from_env(get));
1074 }
1075
1076 #[test]
1077 fn cjk_width_env_glyph_overrides_locale() {
1078 let get = |key: &str| match key {
1080 "FTUI_GLYPH_DOUBLE_WIDTH" => Some("0".into()),
1081 "LANG" => Some("ja_JP.UTF-8".into()),
1082 _ => None,
1083 };
1084 assert!(!cjk_width_from_env(get));
1085 }
1086
1087 #[test]
1088 fn cjk_width_env_on_is_true() {
1089 let get = |key: &str| match key {
1090 "FTUI_GLYPH_DOUBLE_WIDTH" => Some("on".into()),
1091 _ => None,
1092 };
1093 assert!(cjk_width_from_env(get));
1094 }
1095
1096 #[test]
1097 fn cjk_width_env_case_insensitive() {
1098 let get = |key: &str| match key {
1099 "FTUI_CJK_WIDTH" => Some("TRUE".into()),
1100 _ => None,
1101 };
1102 assert!(cjk_width_from_env(get));
1103 }
1104
1105 #[test]
1108 fn vs16_trust_unicode_string() {
1109 let get = |key: &str| match key {
1110 "FTUI_EMOJI_VS16_WIDTH" => Some("unicode".into()),
1111 _ => None,
1112 };
1113 assert!(vs16_trust_from_env(get));
1114 }
1115
1116 #[test]
1117 fn vs16_trust_value_2() {
1118 let get = |key: &str| match key {
1119 "FTUI_EMOJI_VS16_WIDTH" => Some("2".into()),
1120 _ => None,
1121 };
1122 assert!(vs16_trust_from_env(get));
1123 }
1124
1125 #[test]
1126 fn vs16_trust_not_set() {
1127 let get = |_: &str| -> Option<String> { None };
1128 assert!(!vs16_trust_from_env(get));
1129 }
1130
1131 #[test]
1132 fn vs16_trust_other_value() {
1133 let get = |key: &str| match key {
1134 "FTUI_EMOJI_VS16_WIDTH" => Some("1".into()),
1135 _ => None,
1136 };
1137 assert!(!vs16_trust_from_env(get));
1138 }
1139
1140 #[test]
1141 fn vs16_trust_case_insensitive() {
1142 let get = |key: &str| match key {
1143 "FTUI_EMOJI_VS16_WIDTH" => Some("UNICODE".into()),
1144 _ => None,
1145 };
1146 assert!(vs16_trust_from_env(get));
1147 }
1148
1149 #[test]
1152 fn ascii_width_pure_ascii() {
1153 assert_eq!(ascii_width("hello"), Some(5));
1154 }
1155
1156 #[test]
1157 fn ascii_width_empty() {
1158 assert_eq!(ascii_width(""), Some(0));
1159 }
1160
1161 #[test]
1162 fn ascii_width_with_space() {
1163 assert_eq!(ascii_width("hello world"), Some(11));
1164 }
1165
1166 #[test]
1167 fn ascii_width_non_ascii_returns_none() {
1168 assert_eq!(ascii_width("héllo"), None);
1169 }
1170
1171 #[test]
1172 fn ascii_width_with_tab_returns_none() {
1173 assert_eq!(ascii_width("hello\tworld"), None);
1175 }
1176
1177 #[test]
1178 fn ascii_width_with_newline_returns_none() {
1179 assert_eq!(ascii_width("hello\n"), None);
1180 }
1181
1182 #[test]
1183 fn ascii_width_control_char_returns_none() {
1184 assert_eq!(ascii_width("\x01"), None);
1185 }
1186
1187 #[test]
1190 fn char_width_ascii_letter() {
1191 assert_eq!(char_width('A'), 1);
1192 }
1193
1194 #[test]
1195 fn char_width_space() {
1196 assert_eq!(char_width(' '), 1);
1197 }
1198
1199 #[test]
1200 fn char_width_tab() {
1201 assert_eq!(char_width('\t'), 1);
1202 }
1203
1204 #[test]
1205 fn char_width_newline() {
1206 assert_eq!(char_width('\n'), 1);
1207 }
1208
1209 #[test]
1210 fn char_width_nul() {
1211 assert_eq!(char_width('\0'), 0);
1213 }
1214
1215 #[test]
1216 fn char_width_bell() {
1217 assert_eq!(char_width('\x07'), 0);
1219 }
1220
1221 #[test]
1222 fn char_width_combining_accent() {
1223 assert_eq!(char_width('\u{0301}'), 0);
1225 }
1226
1227 #[test]
1228 fn char_width_zwj() {
1229 assert_eq!(char_width('\u{200D}'), 0);
1231 }
1232
1233 #[test]
1234 fn char_width_zwnbsp() {
1235 assert_eq!(char_width('\u{FEFF}'), 0);
1237 }
1238
1239 #[test]
1240 fn char_width_soft_hyphen() {
1241 assert_eq!(char_width('\u{00AD}'), 0);
1243 }
1244
1245 #[test]
1246 fn char_width_wide_east_asian() {
1247 assert_eq!(char_width('⚡'), 2);
1249 }
1250
1251 #[test]
1252 fn char_width_cjk_ideograph() {
1253 assert_eq!(char_width('中'), 2);
1255 }
1256
1257 #[test]
1258 fn char_width_variation_selector() {
1259 assert_eq!(char_width('\u{FE0F}'), 0);
1261 }
1262
1263 #[test]
1266 fn display_width_ascii() {
1267 assert_eq!(display_width("hello"), 5);
1268 }
1269
1270 #[test]
1271 fn display_width_empty() {
1272 assert_eq!(display_width(""), 0);
1273 }
1274
1275 #[test]
1276 fn display_width_cjk_chars() {
1277 assert_eq!(display_width("中文"), 4);
1279 }
1280
1281 #[test]
1282 fn display_width_mixed_ascii_cjk() {
1283 assert_eq!(display_width("a中b"), 4);
1285 }
1286
1287 #[test]
1288 fn display_width_combining_chars() {
1289 assert_eq!(display_width("e\u{0301}"), 1);
1291 }
1292
1293 #[test]
1294 fn display_width_ascii_with_control_codes() {
1295 assert_eq!(display_width("a\tb"), 3);
1298 }
1299
1300 #[test]
1306 fn ascii_width_matches_scalar() {
1307 let cases: &[&str] = &[
1308 "",
1309 " ",
1310 "~",
1311 "hello world",
1312 "\u{1f}",
1313 "\u{7f}",
1314 "\t",
1315 "caf\u{e9}",
1316 "\u{65e5}\u{672c}",
1317 ];
1318 for case in cases {
1319 assert_eq!(ascii_width(case), ascii_width_scalar(case), "{case:?}");
1320 }
1321
1322 for len in [63_usize, 64, 65, 129, 300] {
1326 let clean = "a".repeat(len);
1327 assert_eq!(ascii_width(&clean), Some(len), "clean len {len}");
1328 assert_eq!(ascii_width(&clean), ascii_width_scalar(&clean));
1329
1330 for idx in [0, len / 2, len - 1] {
1331 for bad in ['\u{0}', '\u{1f}', '\u{7f}', '\u{e9}'] {
1332 let mut probe: Vec<char> = clean.chars().collect();
1333 probe[idx] = bad;
1334 let probe: String = probe.into_iter().collect();
1335 assert_eq!(
1336 ascii_width(&probe),
1337 ascii_width_scalar(&probe),
1338 "len {len}, idx {idx}, bad {bad:?}"
1339 );
1340 assert_eq!(ascii_width(&probe), None);
1341 }
1342 }
1343 }
1344 }
1345
1346 #[test]
1349 fn grapheme_width_ascii_char() {
1350 assert_eq!(grapheme_width("A"), 1);
1351 }
1352
1353 #[test]
1354 fn grapheme_width_cjk_ideograph() {
1355 assert_eq!(grapheme_width("中"), 2);
1356 }
1357
1358 #[test]
1359 fn grapheme_width_combining_sequence() {
1360 assert_eq!(grapheme_width("e\u{0301}"), 1);
1362 }
1363
1364 #[test]
1365 fn grapheme_width_zwj_cluster() {
1366 assert_eq!(grapheme_width("\u{200D}"), 0);
1368 }
1369
1370 #[test]
1371 fn grapheme_width_with_cjk_preserves_multi_codepoint_emoji_and_widens_ambiguous() {
1372 for emoji in ["😀", "👨👩👧👦", "👋🏽", "👍🏻", "🇯🇵", "🇺🇸", "🏳️🌈", "🏃🏿♂️", "👩🏻💻"]
1375 {
1376 assert_eq!(
1377 grapheme_width_with_cjk(emoji, false),
1378 2,
1379 "non-CJK emoji width for {emoji:?}"
1380 );
1381 assert_eq!(
1382 grapheme_width_with_cjk(emoji, true),
1383 2,
1384 "CJK emoji width for {emoji:?}"
1385 );
1386 }
1387
1388 for ambiguous in ["●", "—", "…", "→", "①", "│", "─"] {
1391 assert_eq!(
1392 grapheme_width_with_cjk(ambiguous, false),
1393 1,
1394 "non-CJK ambiguous width for {ambiguous:?}"
1395 );
1396 assert_eq!(
1397 grapheme_width_with_cjk(ambiguous, true),
1398 2,
1399 "CJK ambiguous width for {ambiguous:?}"
1400 );
1401 }
1402
1403 for letter in ["Ω", "Ж", "é"] {
1405 assert_eq!(grapheme_width_with_cjk(letter, false), 1);
1406 assert_eq!(grapheme_width_with_cjk(letter, true), 1);
1407 }
1408
1409 if !vs16_width_trusted() {
1412 assert_eq!(grapheme_width_with_cjk("❤\u{FE0F}", false), 1);
1413 assert_eq!(grapheme_width_with_cjk("❤\u{FE0F}", true), 1);
1414 assert_eq!(grapheme_width_with_cjk("☂\u{FE0F}", false), 1);
1415 assert_eq!(grapheme_width_with_cjk("☂\u{FE0F}", true), 1);
1416 }
1417 }
1418
1419 #[test]
1420 fn display_width_routes_non_ascii_through_s3_fifo_cache() {
1421 clear_width_cache();
1422 let before = width_cache_stats();
1423 let samples = [
1426 "名前 │ 状態 │ 更新 │ 備考",
1427 "hello 世界 👋🏽 done",
1428 "résumé café naïve",
1429 "مرحبا بالعالم",
1430 ];
1431 for sample in samples {
1432 let expected: usize = sample.graphemes(true).map(grapheme_width_uncached).sum();
1433 assert_eq!(display_width(sample), expected, "first pass {sample:?}");
1434 }
1435 let after_cold = width_cache_stats();
1436 for sample in samples {
1437 let expected: usize = sample.graphemes(true).map(grapheme_width_uncached).sum();
1438 assert_eq!(display_width(sample), expected, "second pass {sample:?}");
1439 }
1440 if let (Some(before), Some(after_cold), Some(after_warm)) =
1441 (before, after_cold, width_cache_stats())
1442 {
1443 assert!(
1444 after_cold.misses > before.misses,
1445 "cold display_width pass must populate S3-FIFO cache: before={before:?} after_cold={after_cold:?}"
1446 );
1447 assert!(
1448 after_warm.hits > after_cold.hits,
1449 "warm display_width pass must hit S3-FIFO cache: after_cold={after_cold:?} after_warm={after_warm:?}"
1450 );
1451 }
1452 }
1453
1454 #[test]
1455 fn grapheme_width_identical_with_simd() {
1456 for &grapheme in CORPUS {
1459 assert_eq!(
1460 grapheme_width(grapheme),
1461 grapheme_width_uncached(grapheme),
1462 "grapheme_width parity for {grapheme:?}"
1463 );
1464 }
1465
1466 for len in [0_usize, 1, 31, 63, 64, 65, 127, 128, 129, 512, 2048] {
1467 let ascii_run: String = (0..len)
1468 .map(|i| char::from(b' ' + (i % 95) as u8))
1469 .collect();
1470 assert_eq!(ascii_width(&ascii_run), ascii_width_scalar(&ascii_run));
1471 assert_eq!(display_width(&ascii_run), len);
1472 let by_graphemes: usize = ascii_run.graphemes(true).map(grapheme_width).sum();
1473 assert_eq!(display_width(&ascii_run), by_graphemes);
1474 }
1475
1476 for &grapheme in CORPUS {
1477 let mixed = format!("{}{}{}", "a".repeat(64), grapheme, "z".repeat(65));
1478 assert_eq!(ascii_width(&mixed), None);
1479 assert_eq!(ascii_width(&mixed), ascii_width_scalar(&mixed));
1480 let expected = 64 + grapheme_width_uncached(grapheme) + 65;
1481 assert_eq!(
1482 display_width(&mixed),
1483 expected,
1484 "mixed display_width for {grapheme:?}"
1485 );
1486 }
1487 }
1488 }
1489}