Skip to main content

ftui_core/
lib.rs

1// Forbid unsafe in production; deny (with targeted allows) in tests for env var helpers.
2#![cfg_attr(not(test), forbid(unsafe_code))]
3#![cfg_attr(test, deny(unsafe_code))]
4
5//! Core: terminal lifecycle, capability detection, events, and input parsing.
6//!
7//! # Role in FrankenTUI
8//! `ftui-core` is the input layer. It owns terminal session setup/teardown,
9//! capability probing, and normalized event types that the runtime consumes.
10//!
11//! # Primary responsibilities
12//! - **TerminalSession**: RAII lifecycle for raw mode, alt-screen, and cleanup.
13//! - **Event**: canonical input events (keys, mouse, paste, resize, focus).
14//! - **Capability detection**: terminal features and overrides.
15//! - **Input parsing**: robust decoding of terminal input streams.
16//!
17//! # How it fits in the system
18//! The runtime (`ftui-runtime`) consumes `ftui-core::Event` values and drives
19//! application models. The render kernel (`ftui-render`) is independent of
20//! input, so `ftui-core` is the clean bridge between terminal I/O and the
21//! deterministic render pipeline.
22
23pub 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
56/// Tracing target for input parser protocol events (DCS, APC, XTWINOPS, SGR-Pixels).
57pub const TARGET_INPUT_PARSER: &str = "ftui.input.parser";
58
59/// Tracing target for e-process throttle and budget gate decisions.
60pub const TARGET_EPROCESS: &str = "ftui.eprocess";
61
62pub mod shutdown_signal {
63    //! Process-wide graceful-termination signal state shared by runtime and backends.
64    //!
65    //! Signal handlers record the first pending termination signal here. The
66    //! runtime polls it, performs graceful teardown, then clears it to
67    //! acknowledge completion back to the signal thread.
68
69    use std::sync::{
70        Mutex, OnceLock,
71        atomic::{AtomicI32, Ordering},
72    };
73
74    static PENDING_TERMINATION_SIGNAL: AtomicI32 = AtomicI32::new(0);
75
76    /// Record that a termination signal was intercepted and graceful shutdown is required.
77    ///
78    /// The first pending signal wins until the runtime explicitly clears it
79    /// after finishing teardown.
80    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    /// Inspect the currently pending termination signal, if any.
90    #[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    /// Clear any pending graceful-termination request.
99    pub fn clear_pending_termination_signal() {
100        PENDING_TERMINATION_SIGNAL.store(0, Ordering::SeqCst);
101    }
102
103    /// Serialize tests that touch the process-global termination signal slot.
104    ///
105    /// This helper is intentionally exported so downstream workspace crates can
106    /// wrap signal-sensitive tests with the same lock. Without cross-crate
107    /// serialization, parallel test execution can clear the pending signal out
108    /// from under a runtime test and leave it blocked in the event loop.
109    #[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        // Recover from poison rather than propagating it. The guarded value is
114        // `()`, so there is no invariant a panic could have broken - and a
115        // test that fails inside `f` would otherwise turn every later signal
116        // test in the process into "shutdown signal test lock poisoned",
117        // burying the one real failure under a cascade of fake ones.
118        let _guard = SIGNAL_TEST_LOCK
119            .get_or_init(|| Mutex::new(()))
120            .lock()
121            .unwrap_or_else(|poison| poison.into_inner());
122
123        // Clear on the way out even if `f` unwinds. Declared after `_guard`,
124        // so it runs first and the slot is clean before the lock is released;
125        // a plain statement after `f()` was skipped on panic and left a
126        // pending signal for whoever ran next.
127        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                    // Any non-zero signal number; `signal_hook`'s constants are
148                    // Unix-gated and this behaviour is not platform-specific.
149                    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            // And the next test is not punished for the previous one's failure.
160            with_test_signal_serialization(|| {
161                assert!(pending_termination_signal().is_none());
162            });
163        }
164    }
165}
166
167pub mod job_control {
168    //! Process-wide job-control state: SIGTSTP, SIGTTIN and SIGTTOU.
169    //!
170    //! By default those signals stop the process on the spot, which leaves a
171    //! raw-mode terminal behind for the shell. A live session holds a
172    //! [`JobControlClaim`]; while any claim is held the signals are only
173    //! recorded, the runtime hands the terminal back, and then calls
174    //! [`stop_process`] itself. Design: `docs/spec/suspend-resume.md`.
175    //!
176    //! With no claim held the signals keep their default action. That fallback
177    //! is load-bearing: signal-hook never removes a handler once installed, so
178    //! without it a program that had exited would leave its process impossible
179    //! to suspend for the rest of its life.
180
181    #[cfg(unix)]
182    use std::sync::{
183        Arc, OnceLock,
184        atomic::{AtomicBool, AtomicUsize, Ordering},
185    };
186
187    /// Handlers installed once per process: the stop signal last recorded
188    /// while a claim was held, and whether no claim is held.
189    #[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                    // Default action first, so a partial installation still
206                    // stops the process rather than swallowing the signal.
207                    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    /// SIGTSTP, the signal a terminal's Ctrl-Z would send: 18 on macOS and
222    /// the BSDs, 20 on Linux. A non-zero placeholder where there is no job
223    /// control, so a keyboard stop request still reads as a request.
224    #[cfg(unix)]
225    pub const KEYBOARD_STOP_SIGNAL: i32 = signal_hook::consts::signal::SIGTSTP;
226    /// SIGTSTP, the signal a terminal's Ctrl-Z would send.
227    #[cfg(not(unix))]
228    pub const KEYBOARD_STOP_SIGNAL: i32 = 20;
229
230    /// A live session's hold on the stop signals; released on drop.
231    #[derive(Debug)]
232    pub struct JobControlClaim {
233        _private: (),
234    }
235
236    impl JobControlClaim {
237        /// Claim the stop signals for a live session.
238        ///
239        /// Returns `None` where they cannot be intercepted: non-Unix targets,
240        /// or when the handlers failed to install.
241        #[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                    // A signal recorded while unclaimed already stopped the
248                    // process through the default action; it is not a request
249                    // for this session.
250                    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        /// Take the stop signal that arrived since the last call, if any.
262        #[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    /// Stop the process the way `signal`'s default action would, returning
288    /// once it has been continued (SIGCONT).
289    ///
290    /// For the stop signals this raises SIGSTOP, which cannot be caught, so a
291    /// supervisor reading `WSTOPSIG` sees SIGSTOP rather than `signal`. Call it
292    /// only after the terminal has been handed back.
293    ///
294    /// # Errors
295    ///
296    /// Fails if `signal` is unknown or cannot be raised, and on non-Unix
297    /// targets, which have no job control.
298    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        /// The claim count is process-global; `cargo test` runs these in threads.
319        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            // Never raise a stop signal here: a stopped test process hangs the
328            // suite. This checks the bookkeeping that decides whether one would.
329            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// Re-export tracing macros at crate root for ergonomic use.
361#[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    //! Shared display width helpers for layout and rendering.
368    //!
369    //! This module centralizes glyph width calculation so layout (ftui-text)
370    //! and rendering (ftui-render) stay in lockstep. It intentionally avoids
371    //! ad-hoc emoji heuristics and relies on Unicode data tables.
372    //!
373    //! ## Emoji Width Handling
374    //!
375    //! Most terminals render **text-default** emoji (those with
376    //! `Emoji_Presentation=No`, like U+2764 RED HEART) at **width 1**, even
377    //! when a Variation Selector 16 (U+FE0F) is appended. The Unicode spec
378    //! says VS16 requests emoji presentation (width 2), but terminal reality
379    //! disagrees.
380    //!
381    //! **Default behavior** (`FTUI_EMOJI_VS16_WIDTH` unset):
382    //! - `strip_vs16` removes U+FE0F before width calculation.
383    //! - Text-default emoji render at width 1 (matching most terminals).
384    //! - Emoji with `Emoji_Presentation=Yes` (e.g. U+1F600) are unaffected
385    //!   — they are always width 2.
386    //!
387    //! **Opt-in** for terminals that correctly render VS16 at width 2
388    //! (WezTerm, Kitty, Ghostty):
389    //! ```text
390    //! FTUI_EMOJI_VS16_WIDTH=unicode   # or =2
391    //! ```
392    //!
393    //! The policy is read once at startup via [`OnceLock`]. Changing the env
394    //! var mid-process has no effect. See [`vs16_width_trusted`] and
395    //! [`vs16_trust_from_env`] for the API surface.
396
397    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    /// Whether the terminal is trusted to render text-default emoji + VS16 at
441    /// width 2 (matching the Unicode spec).  Most terminals do NOT — they
442    /// render these at width 1 — so the default is `false`.
443    ///
444    /// Set `FTUI_EMOJI_VS16_WIDTH=unicode` (or `=2`) to opt in for terminals
445    /// that handle this correctly (WezTerm, Kitty, Ghostty).
446    #[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    /// Compute VS16 trust policy using a custom environment lookup (testable).
457    #[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    /// Cached VS16 width trust policy (fast path).
468    #[inline]
469    pub fn vs16_width_trusted() -> bool {
470        trust_vs16_width()
471    }
472
473    /// Strip U+FE0F (VS16) from a grapheme cluster.  Returns `None` if the
474    /// grapheme does not contain VS16 (no allocation needed).
475    #[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    /// Compute CJK width policy using a custom environment lookup.
485    #[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    /// Cached CJK width policy (fast path).
494    #[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    /// Fast-path width for pure printable ASCII.
513    ///
514    /// `None` means the run needs the real width tables, which covers both
515    /// non-ASCII bytes and ASCII control characters.
516    ///
517    /// With the `simd` feature this delegates to `ftui_simd::ascii_width`,
518    /// which is the same predicate over 64-byte vector chunks: measured at
519    /// 21x the scalar loop over a kilobyte and 5x over 64 bytes
520    /// (`docs/perf/simd_kernels_2026-09-18.md`). Both paths return identical
521    /// answers for identical input, which `ascii_width_matches_scalar` pins.
522    #[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    /// Scalar printable-ASCII width, and the reference the `simd` path is
536    /// tested against.
537    #[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    /// Capacity of the per-thread grapheme width cache (entries).
571    ///
572    /// 4096 distinct non-ASCII graphemes covers the working set of a busy
573    /// CJK/emoji screen many times over; S3-FIFO keeps one-off scans (a log
574    /// stream of unique emoji) from evicting the hot set.
575    const WIDTH_CACHE_CAPACITY: usize = 4096;
576
577    /// Bound retained key bytes even for arbitrarily long combining clusters.
578    /// Larger graphemes remain valid input and use the uncached width tables.
579    const WIDTH_CACHE_MAX_GRAPHEME_BYTES: usize = 128;
580
581    struct CachedGraphemeWidth {
582        grapheme: Box<str>,
583        width: usize,
584    }
585
586    /// Tracing target for width cache operations and misses.
587    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            // A matching hash is only a hit after exact byte verification.
629            // Collisions replace that hash's entry and count as width misses.
630            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    /// Whether the grapheme width cache is enabled (`FTUI_WIDTH_CACHE=0`,
643    /// `false`, `off`, or `no` disables it; anything else keeps it on).
644    #[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        /// Per-thread S3-FIFO cache from grapheme hash to display width.
661        ///
662        /// Non-ASCII width lookups (`unicode_display_width`, VS16 stripping,
663        /// zero-width scans) are the expensive part of measuring text; every
664        /// wrap, table column, and diff of a CJK or emoji screen repeats them
665        /// for the same handful of clusters. A hash selects the candidate;
666        /// exact cluster bytes decide whether its width can be reused.
667        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    /// Snapshot of the calling thread's grapheme width cache statistics,
682    /// or `None` when the cache is disabled.
683    ///
684    /// Hits require exact grapheme equality; hash collisions count as misses.
685    /// ASCII and clusters exceeding the retained-key byte limit bypass the
686    /// cache and do not contribute to either counter.
687    #[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    /// Drop every cached width on the calling thread (tests and benchmarks).
696    pub fn clear_width_cache() {
697        WIDTH_CACHE.with(|cache| cache.borrow_mut().clear());
698    }
699
700    /// Width of a single grapheme cluster.
701    ///
702    /// ASCII is answered inline; every other cluster goes through the
703    /// per-thread width cache (see [`width_cache_stats`]) in front of the
704    /// Unicode width tables.
705    #[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    /// Width of a non-ASCII grapheme cluster, computed from the Unicode
724    /// tables every time (the cached path in [`grapheme_width`] wraps this).
725    #[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    /// Width of a grapheme cluster with East Asian Ambiguous characters
732    /// double-width when `cjk` is set, instead of as the environment says.
733    ///
734    /// For callers with their own width policy, such as a search that reports
735    /// columns for a caller-chosen mode. Otherwise it measures exactly as
736    /// [`grapheme_width`] does.
737    #[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        // Terminal-realistic VS16 handling: most terminals render text-default
746        // emoji (Emoji_Presentation=No) at 1 cell even with VS16 appended.
747        // Strip VS16 so unicode_display_width returns the text-presentation width.
748        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            // East Asian Ambiguous characters (e.g. 'Ω', '●', '—', '…', '→', '①')
765            // have non-CJK width 1 and CJK width 2, while multi-codepoint emoji
766            // clusters (ZWJ, skin-tone modifiers, flags) already have base_width 2
767            // and must not sum constituent codepoints to 4 or 8.
768            return 2;
769        }
770        base_width
771    }
772
773    /// Width of a single Unicode scalar.
774    #[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    /// Width of a string in terminal cells.
795    ///
796    /// Printable ASCII runs take the inline/SIMD fast path (`ascii_width`);
797    /// strings containing non-ASCII bytes segment into grapheme clusters and
798    /// route every non-ASCII cluster (`<= 128` bytes) through the per-thread
799    /// S3-FIFO width cache (`grapheme_width`).
800    #[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        // ── grapheme width cache ────────────────────────────────────
817
818        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            // Route distinct real clusters through the same production lookup
842            // with a deliberately colliding hash, independent of hash quality.
843            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                    // Six hashes pressure a four-entry cache; each hash also
866                    // has multiple byte-distinct graphemes competing for it.
867                    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        /// The cache must be invisible: cached answers equal the uncached
942        /// computation for every cluster, and repeated lookups are hits.
943        #[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        /// ASCII never touches the cache: its width is answered inline.
967        #[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        /// `display_width` over mixed text agrees with a from-scratch sum of
980        /// uncached grapheme widths, so the cache cannot change measurements.
981        #[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        // ── env helpers (testable without OnceLock) ─────────────────
997
998        #[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            // FTUI_GLYPH_DOUBLE_WIDTH=0 should override a CJK locale
1079            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        // ── VS16 trust from env ─────────────────────────────────────
1106
1107        #[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        // ── ascii_width fast path ───────────────────────────────────
1150
1151        #[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            // Tab (0x09) is outside 0x20..=0x7E
1174            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        // ── char_width ──────────────────────────────────────────────
1188
1189        #[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            // NUL (0x00) is an ASCII control char, zero width
1212            assert_eq!(char_width('\0'), 0);
1213        }
1214
1215        #[test]
1216        fn char_width_bell() {
1217            // BEL (0x07) is an ASCII control char, zero width
1218            assert_eq!(char_width('\x07'), 0);
1219        }
1220
1221        #[test]
1222        fn char_width_combining_accent() {
1223            // U+0301 COMBINING ACUTE ACCENT is zero-width
1224            assert_eq!(char_width('\u{0301}'), 0);
1225        }
1226
1227        #[test]
1228        fn char_width_zwj() {
1229            // U+200D ZERO WIDTH JOINER
1230            assert_eq!(char_width('\u{200D}'), 0);
1231        }
1232
1233        #[test]
1234        fn char_width_zwnbsp() {
1235            // U+FEFF ZERO WIDTH NO-BREAK SPACE
1236            assert_eq!(char_width('\u{FEFF}'), 0);
1237        }
1238
1239        #[test]
1240        fn char_width_soft_hyphen() {
1241            // U+00AD SOFT HYPHEN
1242            assert_eq!(char_width('\u{00AD}'), 0);
1243        }
1244
1245        #[test]
1246        fn char_width_wide_east_asian() {
1247            // '⚡' (U+26A1) has east_asian_width=W, always width 2
1248            assert_eq!(char_width('⚡'), 2);
1249        }
1250
1251        #[test]
1252        fn char_width_cjk_ideograph() {
1253            // CJK ideographs are always width 2
1254            assert_eq!(char_width('中'), 2);
1255        }
1256
1257        #[test]
1258        fn char_width_variation_selector() {
1259            // U+FE0F VARIATION SELECTOR-16 is zero-width
1260            assert_eq!(char_width('\u{FE0F}'), 0);
1261        }
1262
1263        // ── display_width ───────────────────────────────────────────
1264
1265        #[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            // Each CJK character is width 2
1278            assert_eq!(display_width("中文"), 4);
1279        }
1280
1281        #[test]
1282        fn display_width_mixed_ascii_cjk() {
1283            // 'a' = 1, '中' = 2, 'b' = 1
1284            assert_eq!(display_width("a中b"), 4);
1285        }
1286
1287        #[test]
1288        fn display_width_combining_chars() {
1289            // 'e' + combining acute = 1 grapheme, width 1
1290            assert_eq!(display_width("e\u{0301}"), 1);
1291        }
1292
1293        #[test]
1294        fn display_width_ascii_with_control_codes() {
1295            // Non-printable ASCII control chars in non-pure-ASCII path
1296            // Tab/newline/CR get width 1 via ascii_display_width
1297            assert_eq!(display_width("a\tb"), 3);
1298        }
1299
1300        // ── ascii_width ─────────────────────────────────────────────
1301
1302        /// Whichever path the `simd` feature selected must agree with the
1303        /// scalar reference, including on the boundaries either side of
1304        /// printable ASCII and past a full 64-byte vector chunk.
1305        #[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            // Lengths around one chunk, with a rejected byte at each end and
1323            // in the middle, so a chunked implementation cannot pass by
1324            // looking only at the head.
1325            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        // ── grapheme_width ──────────────────────────────────────────
1347
1348        #[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            // 'e' + combining accent is one grapheme, width 1
1361            assert_eq!(grapheme_width("e\u{0301}"), 1);
1362        }
1363
1364        #[test]
1365        fn grapheme_width_zwj_cluster() {
1366            // ZWJ alone is zero-width
1367            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            // Multi-codepoint emoji clusters must occupy 2 cells in both
1373            // non-CJK and CJK modes (never summing scalar codepoints to 4 or 8).
1374            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            // East Asian Ambiguous symbols/punctuation/box-drawing/arrows widen
1389            // from 1 cell (non-CJK) to 2 cells (CJK).
1390            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            // Non-East-Asian script letters ('Ω', 'Ж') remain 1 cell in both modes.
1404            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            // Text-default emoji + VS16 ('❤' U+2764, '☂' U+2602) stay 1 cell
1410            // when VS16 is untrusted in both non-CJK and CJK modes.
1411            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            // Pure non-ASCII and mixed strings with no zero-width codepoints
1424            // must still populate and hit the S3-FIFO width cache.
1425            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            // Verify grapheme_width and display_width parity across CORPUS,
1457            // multi-chunk ASCII strings, and mixed ASCII + Unicode strings.
1458            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}