1use std::io::{self, Write};
2use std::sync::{Arc, Mutex, Once, OnceLock, Weak};
3use std::time::{Duration, Instant};
4
5use crossterm::cursor::{Hide, Show};
6use crossterm::event::{
7 DisableBracketedPaste, DisableFocusChange, DisableMouseCapture, EnableBracketedPaste,
8 EnableFocusChange, EnableMouseCapture, KeyboardEnhancementFlags, PopKeyboardEnhancementFlags,
9 PushKeyboardEnhancementFlags,
10};
11use crossterm::terminal::{
12 BeginSynchronizedUpdate, EndSynchronizedUpdate, EnterAlternateScreen, LeaveAlternateScreen,
13};
14use crossterm::{ExecutableCommand as _, QueueableCommand as _};
15
16use super::hyperlink::write_close;
17
18const MAX_TERMINAL_TITLE_BYTES: usize = 64;
19const SAVE_WINDOW_TITLE: &[u8] = b"\x1b[22;2t";
20const SET_WINDOW_TITLE_PREFIX: &[u8] = b"\x1b]2;";
21const SET_WINDOW_TITLE_SUFFIX: &[u8] = b"\x07";
22const RESTORE_WINDOW_TITLE: &[u8] = b"\x1b[23;2t";
23
24#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum ColorCapability {
27 None,
29 Ansi16,
31 Ansi256,
33 TrueColor,
35}
36
37#[derive(Debug, Clone, Copy, PartialEq, Eq)]
39pub struct TerminalCapabilities {
40 color: ColorCapability,
41 reduced_motion: bool,
42 interactive: bool,
43 hyperlinks: bool,
44}
45
46impl TerminalCapabilities {
47 #[must_use]
49 pub fn detect(reduced_motion: bool) -> Self {
50 let terminal = std::env::var("TERM").ok();
51 let color_terminal = std::env::var("COLORTERM").ok();
52 Self::from_environment(
53 terminal.as_deref(),
54 color_terminal.as_deref(),
55 std::env::var_os("NO_COLOR").is_some(),
56 reduced_motion,
57 )
58 }
59
60 #[must_use]
62 pub fn from_environment(
63 terminal: Option<&str>,
64 color_terminal: Option<&str>,
65 no_color: bool,
66 reduced_motion: bool,
67 ) -> Self {
68 let dumb = terminal.is_some_and(|value| value.eq_ignore_ascii_case("dumb"));
69 let color = if no_color || dumb {
70 ColorCapability::None
71 } else if color_terminal.is_some_and(|value| {
72 let value = value.to_ascii_lowercase();
73 value.contains("truecolor") || value.contains("24bit")
74 }) {
75 ColorCapability::TrueColor
76 } else if terminal.is_some_and(|value| value.contains("256color")) {
77 ColorCapability::Ansi256
78 } else {
79 ColorCapability::Ansi16
80 };
81 let hyperlinks = terminal.is_some_and(supports_osc8_terminal);
82 Self {
83 color,
84 reduced_motion: reduced_motion || dumb,
85 interactive: !dumb,
86 hyperlinks,
87 }
88 }
89
90 #[must_use]
92 pub const fn color(self) -> ColorCapability {
93 self.color
94 }
95
96 #[must_use]
98 pub const fn reduced_motion(self) -> bool {
99 self.reduced_motion
100 }
101
102 #[must_use]
104 pub const fn supports_synchronized_output(self) -> bool {
105 self.interactive
106 }
107
108 #[must_use]
110 pub const fn supports_focus_events(self) -> bool {
111 self.interactive
112 }
113
114 #[must_use]
116 pub const fn supports_title(self) -> bool {
117 self.interactive
118 }
119
120 #[must_use]
122 pub const fn supports_hyperlinks(self) -> bool {
123 self.hyperlinks
124 }
125}
126
127fn supports_osc8_terminal(terminal: &str) -> bool {
128 let terminal = terminal.to_ascii_lowercase();
129 if terminal == "dumb" || terminal.starts_with("screen") || terminal.starts_with("tmux") {
130 return false;
131 }
132 [
133 "xterm",
134 "rxvt",
135 "kitty",
136 "wezterm",
137 "alacritty",
138 "foot",
139 "ghostty",
140 ]
141 .iter()
142 .any(|family| terminal.contains(family))
143}
144
145#[derive(Debug, Clone, Copy, PartialEq, Eq)]
147pub enum ViewportMode {
148 Fullscreen,
150 Inline,
152}
153
154#[derive(Clone, Copy, PartialEq, Eq)]
156pub struct TerminalTitle {
157 bytes: [u8; MAX_TERMINAL_TITLE_BYTES],
158 len: u8,
159}
160
161impl TerminalTitle {
162 #[must_use]
164 pub fn new(value: &str) -> Self {
165 let mut bytes = [0; MAX_TERMINAL_TITLE_BYTES];
166 let mut len = 0usize;
167 let mut pending_space = false;
168 for character in value.chars() {
169 if character.is_control() {
170 continue;
171 }
172 if character.is_whitespace() {
173 pending_space = len > 0;
174 continue;
175 }
176 if pending_space && len < MAX_TERMINAL_TITLE_BYTES {
177 bytes[len] = b' ';
178 len += 1;
179 }
180 pending_space = false;
181 let mut encoded = [0; 4];
182 let encoded = character.encode_utf8(&mut encoded).as_bytes();
183 if len.saturating_add(encoded.len()) > MAX_TERMINAL_TITLE_BYTES {
184 break;
185 }
186 bytes[len..len + encoded.len()].copy_from_slice(encoded);
187 len += encoded.len();
188 }
189 if len > 0 && bytes[len - 1] == b' ' {
190 len -= 1;
191 }
192 if len == 0 {
193 bytes[..3].copy_from_slice(b"Tea");
194 len = 3;
195 }
196 Self {
197 bytes,
198 len: u8::try_from(len).unwrap_or(64),
199 }
200 }
201
202 #[must_use]
204 pub fn as_str(&self) -> &str {
205 self.bytes
206 .get(..usize::from(self.len))
207 .and_then(|bytes| std::str::from_utf8(bytes).ok())
208 .unwrap_or("Tea")
209 }
210}
211
212impl Default for TerminalTitle {
213 fn default() -> Self {
214 Self::new("Tea")
215 }
216}
217
218impl std::fmt::Debug for TerminalTitle {
219 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
220 formatter
221 .debug_tuple("TerminalTitle")
222 .field(&self.as_str())
223 .finish()
224 }
225}
226
227#[derive(Debug, Clone, Copy, PartialEq, Eq)]
229pub enum TerminalMode {
230 Title(TerminalTitle),
232 Raw,
234 AlternateScreen,
236 BracketedPaste,
238 FocusEvents,
240 MouseCapture,
242 KeyboardEnhancement,
244 CursorHidden,
246 SynchronizedOutput,
248 HyperlinkOutput,
250}
251
252#[derive(Debug, Clone, Copy, PartialEq, Eq)]
254#[allow(clippy::struct_excessive_bools)] pub struct TerminalOptions {
256 pub title: Option<TerminalTitle>,
258 pub viewport: ViewportMode,
260 pub synchronized_output: bool,
262 pub focus_events: bool,
264 pub mouse_capture: bool,
266 pub keyboard_enhancement: bool,
268 pub cursor_visible: bool,
270 pub hyperlinks: bool,
272}
273
274impl Default for TerminalOptions {
275 fn default() -> Self {
276 Self {
277 title: None,
278 viewport: ViewportMode::Fullscreen,
279 synchronized_output: true,
280 focus_events: true,
281 mouse_capture: false,
282 keyboard_enhancement: false,
283 cursor_visible: false,
284 hyperlinks: false,
285 }
286 }
287}
288
289#[allow(clippy::missing_errors_doc)] pub trait TerminalDriver: Send {
292 fn enable(&mut self, mode: TerminalMode) -> io::Result<()>;
294 fn disable(&mut self, mode: TerminalMode) -> io::Result<()>;
296 fn drain(&mut self, deadline: Instant) -> io::Result<()>;
298}
299
300#[derive(Debug)]
302pub struct CrosstermDriver<W> {
303 writer: W,
304}
305
306impl<W> CrosstermDriver<W> {
307 #[must_use]
309 pub const fn new(writer: W) -> Self {
310 Self { writer }
311 }
312}
313
314impl<W: Write + Send> TerminalDriver for CrosstermDriver<W> {
315 fn enable(&mut self, mode: TerminalMode) -> io::Result<()> {
316 match mode {
317 TerminalMode::Title(title) => self.enable_title(title),
318 TerminalMode::Raw => crossterm::terminal::enable_raw_mode(),
319 TerminalMode::AlternateScreen => self.writer.execute(EnterAlternateScreen).map(drop),
320 TerminalMode::BracketedPaste => self.writer.execute(EnableBracketedPaste).map(drop),
321 TerminalMode::FocusEvents => self.writer.execute(EnableFocusChange).map(drop),
322 TerminalMode::MouseCapture => self.writer.execute(EnableMouseCapture).map(drop),
323 TerminalMode::KeyboardEnhancement => self
324 .writer
325 .execute(PushKeyboardEnhancementFlags(
326 KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES,
327 ))
328 .map(drop),
329 TerminalMode::CursorHidden => self.writer.execute(Hide).map(drop),
330 TerminalMode::SynchronizedOutput => {
331 self.writer.queue(BeginSynchronizedUpdate).map(drop)
332 }
333 TerminalMode::HyperlinkOutput => Ok(()),
334 }
335 }
336
337 fn disable(&mut self, mode: TerminalMode) -> io::Result<()> {
338 match mode {
339 TerminalMode::Title(_) => self.restore_title(),
340 TerminalMode::Raw => crossterm::terminal::disable_raw_mode(),
341 TerminalMode::AlternateScreen => self.writer.execute(LeaveAlternateScreen).map(drop),
342 TerminalMode::BracketedPaste => self.writer.execute(DisableBracketedPaste).map(drop),
343 TerminalMode::FocusEvents => self.writer.execute(DisableFocusChange).map(drop),
344 TerminalMode::MouseCapture => self.writer.execute(DisableMouseCapture).map(drop),
345 TerminalMode::KeyboardEnhancement => {
346 self.writer.execute(PopKeyboardEnhancementFlags).map(drop)
347 }
348 TerminalMode::CursorHidden => self.writer.execute(Show).map(drop),
349 TerminalMode::SynchronizedOutput => {
350 self.writer.execute(EndSynchronizedUpdate).map(drop)
351 }
352 TerminalMode::HyperlinkOutput => {
353 write_close(&mut self.writer)?;
354 self.writer.flush()
355 }
356 }
357 }
358
359 fn drain(&mut self, deadline: Instant) -> io::Result<()> {
360 if Instant::now() >= deadline {
361 return Err(io::Error::new(
362 io::ErrorKind::TimedOut,
363 "terminal frame drain deadline expired",
364 ));
365 }
366 self.writer.flush()?;
367 if Instant::now() > deadline {
368 return Err(io::Error::new(
369 io::ErrorKind::TimedOut,
370 "terminal frame drain exceeded its deadline",
371 ));
372 }
373 Ok(())
374 }
375}
376
377impl<W: Write> CrosstermDriver<W> {
378 fn enable_title(&mut self, title: TerminalTitle) -> io::Result<()> {
379 let result = (|| {
380 self.writer.write_all(SAVE_WINDOW_TITLE)?;
381 self.writer.write_all(SET_WINDOW_TITLE_PREFIX)?;
382 self.writer.write_all(title.as_str().as_bytes())?;
383 self.writer.write_all(SET_WINDOW_TITLE_SUFFIX)?;
384 self.writer.flush()
385 })();
386 if let Err(error) = result {
387 let _ = self.restore_title();
388 return Err(error);
389 }
390 Ok(())
391 }
392
393 fn restore_title(&mut self) -> io::Result<()> {
394 self.writer.write_all(RESTORE_WINDOW_TITLE)?;
395 self.writer.flush()
396 }
397}
398
399struct GuardState {
400 driver: Box<dyn TerminalDriver>,
401 enabled: Vec<TerminalMode>,
402 options: TerminalOptions,
403 input_parked: bool,
404}
405
406impl std::fmt::Debug for GuardState {
407 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
408 formatter
409 .debug_struct("GuardState")
410 .field("enabled", &self.enabled)
411 .field("options", &self.options)
412 .field("input_parked", &self.input_parked)
413 .finish_non_exhaustive()
414 }
415}
416
417impl GuardState {
418 fn enter(&mut self) -> io::Result<()> {
419 if let Some(title) = self.options.title {
420 self.enable(TerminalMode::Title(title))?;
421 }
422 self.enable(TerminalMode::Raw)?;
423 if self.options.viewport == ViewportMode::Fullscreen {
424 self.enable(TerminalMode::AlternateScreen)?;
425 }
426 self.enable(TerminalMode::BracketedPaste)?;
427 if self.options.focus_events {
428 self.enable(TerminalMode::FocusEvents)?;
429 }
430 if self.options.mouse_capture {
431 self.enable(TerminalMode::MouseCapture)?;
432 }
433 if self.options.keyboard_enhancement {
434 let _ = self.enable(TerminalMode::KeyboardEnhancement);
438 }
439 if !self.options.cursor_visible {
440 self.enable(TerminalMode::CursorHidden)?;
441 }
442 if self.options.hyperlinks {
443 self.enable(TerminalMode::HyperlinkOutput)?;
444 }
445 Ok(())
446 }
447
448 fn enable(&mut self, mode: TerminalMode) -> io::Result<()> {
449 if self.enabled.contains(&mode) {
450 return Ok(());
451 }
452 self.driver.enable(mode)?;
453 self.enabled.push(mode);
454 Ok(())
455 }
456
457 fn disable(&mut self, mode: TerminalMode) -> io::Result<()> {
458 if let Some(index) = self.enabled.iter().position(|enabled| *enabled == mode) {
459 self.driver.disable(mode)?;
460 self.enabled.remove(index);
461 }
462 Ok(())
463 }
464
465 fn restore(&mut self) -> io::Result<()> {
466 let mut first_error = None;
467 while let Some(mode) = self.enabled.pop() {
468 if let Err(error) = self.driver.disable(mode) {
469 first_error.get_or_insert(error);
470 }
471 }
472 first_error.map_or(Ok(()), Err)
473 }
474}
475
476static PANIC_HOOK_ONCE: Once = Once::new();
477static ACTIVE_TERMINAL: OnceLock<Mutex<Option<Weak<Mutex<GuardState>>>>> = OnceLock::new();
478
479fn install_panic_hook() {
480 PANIC_HOOK_ONCE.call_once(|| {
481 let previous = std::panic::take_hook();
482 std::panic::set_hook(Box::new(move |information| {
483 let active = ACTIVE_TERMINAL.get().and_then(|slot| {
484 slot.try_lock()
485 .map_or_else(
486 |error| match error {
487 std::sync::TryLockError::Poisoned(error) => Some(error.into_inner()),
488 std::sync::TryLockError::WouldBlock => None,
489 },
490 Some,
491 )
492 .and_then(|slot| slot.as_ref().and_then(Weak::upgrade))
493 });
494 if let Some(active) = active {
495 match active.try_lock() {
496 Ok(mut state) => {
497 let _ = state.restore();
498 }
499 Err(std::sync::TryLockError::Poisoned(error)) => {
500 let _ = error.into_inner().restore();
501 }
502 Err(std::sync::TryLockError::WouldBlock) => {}
503 }
504 }
505 previous(information);
506 }));
507 });
508}
509
510#[derive(Debug)]
512pub struct TerminalGuard {
513 state: Arc<Mutex<GuardState>>,
514}
515
516#[allow(clippy::missing_errors_doc)] impl TerminalGuard {
518 pub fn enter(
525 driver: impl TerminalDriver + 'static,
526 options: TerminalOptions,
527 ) -> io::Result<Self> {
528 install_panic_hook();
529 let state = Arc::new(Mutex::new(GuardState {
530 driver: Box::new(driver),
531 enabled: Vec::new(),
532 options,
533 input_parked: false,
534 }));
535 let guard = Self { state };
536 let slot = ACTIVE_TERMINAL.get_or_init(|| Mutex::new(None));
537 {
538 let mut active = slot
539 .lock()
540 .map_err(|_| io::Error::other("active terminal registry is poisoned"))?;
541 if active.as_ref().and_then(Weak::upgrade).is_some() {
542 return Err(io::Error::new(
543 io::ErrorKind::AlreadyExists,
544 "another terminal guard is already active",
545 ));
546 }
547 *active = Some(Arc::downgrade(&guard.state));
550 }
551 {
552 let mut locked = guard
553 .state
554 .lock()
555 .map_err(|_| io::Error::other("terminal mode ledger is poisoned"))?;
556 if let Err(error) = locked.enter() {
557 let _ = locked.restore();
558 return Err(error);
559 }
560 }
561 Ok(guard)
562 }
563
564 pub fn begin_frame(&self) -> io::Result<()> {
566 let mut state = self.lock()?;
567 if state.options.synchronized_output {
568 state.enable(TerminalMode::SynchronizedOutput)?;
569 }
570 Ok(())
571 }
572
573 pub fn end_frame(&self, timeout: Duration) -> io::Result<()> {
575 let mut state = self.lock()?;
576 let end_result = state.disable(TerminalMode::SynchronizedOutput);
577 let drain_result = state.driver.drain(Instant::now() + timeout);
578 end_result.and(drain_result)
579 }
580
581 pub fn suspend(&self, timeout: Duration) -> io::Result<()> {
583 let mut state = self.lock()?;
584 state.input_parked = true;
585 let sync_result = state.disable(TerminalMode::SynchronizedOutput);
586 let drain_result = state.driver.drain(Instant::now() + timeout);
587 let restore_result = state.restore();
588 sync_result.and(drain_result).and(restore_result)
589 }
590
591 pub fn resume(&self) -> io::Result<()> {
593 let mut state = self.lock()?;
594 if let Err(error) = state.enter() {
595 let _ = state.restore();
596 return Err(error);
597 }
598 state.input_parked = false;
599 Ok(())
600 }
601
602 pub fn handoff<T>(
605 &self,
606 timeout: Duration,
607 child: impl FnOnce() -> io::Result<T>,
608 ) -> io::Result<T> {
609 self.suspend(timeout)?;
610 let child_result = child();
611 let resume_result = self.resume();
612 match (child_result, resume_result) {
613 (Ok(value), Ok(())) => Ok(value),
614 (Err(error), _) | (Ok(_), Err(error)) => Err(error),
615 }
616 }
617
618 pub fn enabled_modes(&self) -> io::Result<Vec<TerminalMode>> {
620 Ok(self.lock()?.enabled.clone())
621 }
622
623 pub fn input_is_parked(&self) -> io::Result<bool> {
625 Ok(self.lock()?.input_parked)
626 }
627
628 fn lock(&self) -> io::Result<std::sync::MutexGuard<'_, GuardState>> {
629 self.state
630 .lock()
631 .map_err(|_| io::Error::other("terminal mode ledger is poisoned"))
632 }
633}
634
635impl Drop for TerminalGuard {
636 fn drop(&mut self) {
637 match self.state.lock() {
638 Ok(mut state) => {
639 let _ = state.restore();
640 }
641 Err(error) => {
642 let _ = error.into_inner().restore();
643 }
644 }
645 if let Some(slot) = ACTIVE_TERMINAL.get()
646 && let Ok(mut active) = slot.lock()
647 && active
648 .as_ref()
649 .and_then(Weak::upgrade)
650 .is_some_and(|value| Arc::ptr_eq(&value, &self.state))
651 {
652 *active = None;
653 }
654 }
655}
656
657#[cfg(test)]
658mod tests {
659 use super::{
660 ColorCapability, CrosstermDriver, TerminalCapabilities, TerminalDriver, TerminalMode,
661 TerminalTitle,
662 };
663
664 #[test]
665 fn environment_capabilities_are_conservative_for_dumb_and_no_color_terminals() {
666 let dumb = TerminalCapabilities::from_environment(Some("dumb"), None, false, false);
667 assert_eq!(dumb.color(), ColorCapability::None);
668 assert!(dumb.reduced_motion());
669 assert!(!dumb.supports_synchronized_output());
670 assert!(!dumb.supports_focus_events());
671 assert!(!dumb.supports_title());
672 assert!(!dumb.supports_hyperlinks());
673
674 let no_color =
675 TerminalCapabilities::from_environment(Some("xterm-256color"), None, true, false);
676 assert_eq!(no_color.color(), ColorCapability::None);
677 assert!(no_color.supports_synchronized_output());
678 assert!(no_color.supports_title());
679 assert!(no_color.supports_hyperlinks());
680
681 for terminal in [None, Some("screen-256color"), Some("tmux-256color")] {
682 assert!(
683 !TerminalCapabilities::from_environment(terminal, None, false, false)
684 .supports_hyperlinks()
685 );
686 }
687
688 let true_color = TerminalCapabilities::from_environment(
689 Some("xterm-256color"),
690 Some("truecolor"),
691 false,
692 true,
693 );
694 assert_eq!(true_color.color(), ColorCapability::TrueColor);
695 assert!(true_color.reduced_motion());
696 }
697
698 #[test]
699 fn crossterm_driver_saves_sets_and_restores_the_exact_window_title() {
700 let title = TerminalTitle::default();
701 let mode = TerminalMode::Title(title);
702 let mut driver = CrosstermDriver::new(Vec::new());
703
704 driver.enable(mode).unwrap();
705 driver.disable(mode).unwrap();
706
707 assert_eq!(driver.writer, b"\x1b[22;2t\x1b]2;Tea\x07\x1b[23;2t");
708 }
709
710 #[test]
711 fn crossterm_driver_closes_guarded_hyperlink_output() {
712 let mut driver = CrosstermDriver::new(Vec::new());
713
714 driver.enable(TerminalMode::HyperlinkOutput).unwrap();
715 driver.disable(TerminalMode::HyperlinkOutput).unwrap();
716
717 assert_eq!(driver.writer, b"\x1b]8;;\x1b\\");
718 }
719}