#![forbid(unsafe_code)]
#![doc = "Backend traits for FrankenTUI: platform abstraction for input, presentation, and time."]
#![doc = ""]
#![doc = "This crate defines the boundary between the ftui runtime and platform-specific"]
#![doc = "implementations (native terminal via `ftui-tty`, WASM via `ftui-web`)."]
#![doc = ""]
#![doc = "See ADR-008 for the design rationale."]
use core::time::Duration;
use std::sync::Arc;
use ftui_core::event::Event;
use ftui_core::osc52::ClipboardSelection;
use ftui_core::terminal_capabilities::TerminalCapabilities;
use ftui_render::buffer::Buffer;
use ftui_render::diff::BufferDiff;
pub use ftui_render::diff_strategy::DiffStrategy;
use ftui_render::grapheme_pool::GraphemePool;
use ftui_render::link_registry::LinkRegistry;
pub use ftui_render::sanitize::SanitizeMode;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct PresentTimings {
pub diff_us: u64,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ScreenMode {
Inline {
ui_height: u16,
},
InlineAuto {
min_height: u16,
max_height: u16,
},
#[default]
AltScreen,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum UiAnchor {
#[default]
Bottom,
Top,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct BackendFeatures {
pub mouse_capture: bool,
pub bracketed_paste: bool,
pub focus_events: bool,
pub kitty_keyboard: bool,
}
pub trait BackendClock {
fn now_mono(&self) -> Duration;
}
pub trait BackendEventSource {
type Error: core::fmt::Debug + core::fmt::Display;
fn size(&self) -> Result<(u16, u16), Self::Error>;
fn set_features(&mut self, features: BackendFeatures) -> Result<(), Self::Error>;
fn poll_event(&mut self, timeout: Duration) -> Result<bool, Self::Error>;
fn read_event(&mut self) -> Result<Option<Event>, Self::Error>;
fn supports_suspend(&self) -> bool {
false
}
fn suspend(&mut self) -> Result<bool, Self::Error> {
Ok(false)
}
fn resume(&mut self) -> Result<(), Self::Error> {
Ok(())
}
}
pub trait BackendPresenter {
type Error: core::fmt::Debug + core::fmt::Display;
fn capabilities(&self) -> &TerminalCapabilities;
fn write_log(&mut self, text: &str) -> Result<(), Self::Error>;
fn present_ui(
&mut self,
buf: &Buffer,
diff: Option<&BufferDiff>,
full_repaint_hint: bool,
) -> Result<(), Self::Error>;
fn gc(&mut self) {}
fn resize(&mut self, _cols: u16, _rows: u16) {}
fn screen_mode(&self) -> ScreenMode {
ScreenMode::default()
}
fn set_screen_mode(&mut self, _mode: ScreenMode) {}
fn set_evidence_writer(&mut self, _w: Option<Arc<dyn Fn(&str) + Send + Sync>>) {}
fn last_diff_strategy(&self) -> Option<DiffStrategy> {
None
}
fn last_diff_elapsed(&self) -> Option<Duration> {
None
}
fn begin_shutdown(&mut self) -> Result<(), Self::Error> {
Ok(())
}
fn flush(&mut self) -> Result<(), Self::Error> {
Ok(())
}
fn suspend(&mut self) -> Result<(), Self::Error> {
self.flush()
}
fn take_render_buffer(&mut self, width: u16, height: u16) -> Buffer {
Buffer::new(width, height)
}
fn begin_link_frame(&mut self) {}
fn pool_and_links_mut(&mut self) -> (&mut GraphemePool, &mut LinkRegistry);
fn pool_mut(&mut self) -> &mut GraphemePool;
fn inline_auto_bounds(&self) -> Option<(u16, u16)> {
None
}
fn auto_ui_height(&self) -> Option<u16> {
None
}
fn render_height_hint(&self) -> u16 {
0
}
fn set_auto_ui_height(&mut self, _height: u16) {}
fn clear_auto_ui_height(&mut self) {}
fn take_last_present_timings(&mut self) -> Option<PresentTimings> {
None
}
fn estimate_memory_usage(&self) -> usize {
0
}
fn present_ui_owned(
&mut self,
buf: Buffer,
cursor: Option<(u16, u16)>,
cursor_visible: bool,
) -> Result<(), Self::Error> {
let _ = (cursor, cursor_visible);
self.present_ui(&buf, None, false)
}
fn write_log_line_with_mode(
&mut self,
text: &str,
_mode: SanitizeMode,
) -> Result<(), Self::Error> {
self.write_log(text)
}
fn write_osc52_set(
&mut self,
_selection: ClipboardSelection,
_data: &[u8],
) -> Result<(), Self::Error> {
Ok(())
}
fn write_osc52_query(&mut self, _selection: ClipboardSelection) -> Result<(), Self::Error> {
Ok(())
}
fn set_timing_enabled(&mut self, _enabled: bool) {}
fn set_hyperlink_limit(&mut self, _limit: usize) {}
}
pub trait Backend {
type Error: core::fmt::Debug + core::fmt::Display;
type Clock: BackendClock;
type Events: BackendEventSource<Error = Self::Error>;
fn clock(&self) -> &Self::Clock;
fn events(&mut self) -> &mut Self::Events;
}
#[cfg(test)]
mod tests {
use super::*;
use core::fmt;
use ftui_core::terminal_capabilities::TerminalCapabilities;
#[test]
fn backend_features_default_all_false() {
let f = BackendFeatures::default();
assert!(!f.mouse_capture);
assert!(!f.bracketed_paste);
assert!(!f.focus_events);
assert!(!f.kitty_keyboard);
}
#[test]
fn backend_features_equality() {
let a = BackendFeatures {
mouse_capture: true,
bracketed_paste: false,
focus_events: true,
kitty_keyboard: false,
};
let b = BackendFeatures {
mouse_capture: true,
bracketed_paste: false,
focus_events: true,
kitty_keyboard: false,
};
assert_eq!(a, b);
}
#[test]
fn backend_features_inequality() {
let a = BackendFeatures::default();
let b = BackendFeatures {
mouse_capture: true,
..BackendFeatures::default()
};
assert_ne!(a, b);
}
#[test]
fn backend_features_clone() {
let a = BackendFeatures {
mouse_capture: true,
bracketed_paste: true,
focus_events: true,
kitty_keyboard: true,
};
let b = a;
assert_eq!(a, b);
}
#[test]
fn backend_features_debug() {
let f = BackendFeatures::default();
let debug = format!("{f:?}");
assert!(debug.contains("BackendFeatures"));
assert!(debug.contains("mouse_capture"));
}
struct TestClock {
elapsed: Duration,
}
impl BackendClock for TestClock {
fn now_mono(&self) -> Duration {
self.elapsed
}
}
#[derive(Debug)]
struct TestError(String);
impl fmt::Display for TestError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "TestError: {}", self.0)
}
}
struct TestEventSource {
features: BackendFeatures,
events: Vec<Event>,
}
impl BackendEventSource for TestEventSource {
type Error = TestError;
fn size(&self) -> Result<(u16, u16), Self::Error> {
Ok((80, 24))
}
fn set_features(&mut self, features: BackendFeatures) -> Result<(), Self::Error> {
self.features = features;
Ok(())
}
fn poll_event(&mut self, _timeout: Duration) -> Result<bool, Self::Error> {
Ok(!self.events.is_empty())
}
fn read_event(&mut self) -> Result<Option<Event>, Self::Error> {
Ok(if self.events.is_empty() {
None
} else {
Some(self.events.remove(0))
})
}
}
struct TestPresenter {
caps: TerminalCapabilities,
logs: Vec<String>,
present_count: usize,
gc_count: usize,
pool: GraphemePool,
links: LinkRegistry,
}
impl BackendPresenter for TestPresenter {
type Error = TestError;
fn capabilities(&self) -> &TerminalCapabilities {
&self.caps
}
fn write_log(&mut self, text: &str) -> Result<(), Self::Error> {
self.logs.push(text.to_owned());
Ok(())
}
fn present_ui(
&mut self,
_buf: &Buffer,
_diff: Option<&BufferDiff>,
_full_repaint_hint: bool,
) -> Result<(), Self::Error> {
self.present_count += 1;
Ok(())
}
fn gc(&mut self) {
self.gc_count += 1;
}
fn pool_and_links_mut(&mut self) -> (&mut GraphemePool, &mut LinkRegistry) {
(&mut self.pool, &mut self.links)
}
fn pool_mut(&mut self) -> &mut GraphemePool {
&mut self.pool
}
}
struct TestBackend {
clock: TestClock,
events: TestEventSource,
}
impl Backend for TestBackend {
type Error = TestError;
type Clock = TestClock;
type Events = TestEventSource;
fn clock(&self) -> &Self::Clock {
&self.clock
}
fn events(&mut self) -> &mut Self::Events {
&mut self.events
}
}
fn make_test_backend() -> TestBackend {
TestBackend {
clock: TestClock {
elapsed: Duration::from_millis(42),
},
events: TestEventSource {
features: BackendFeatures::default(),
events: Vec::new(),
},
}
}
#[test]
fn clock_returns_elapsed() {
let clock = TestClock {
elapsed: Duration::from_secs(5),
};
assert_eq!(clock.now_mono(), Duration::from_secs(5));
}
#[test]
fn clock_zero_duration() {
let clock = TestClock {
elapsed: Duration::ZERO,
};
assert_eq!(clock.now_mono(), Duration::ZERO);
}
#[test]
fn event_source_size() {
let src = TestEventSource {
features: BackendFeatures::default(),
events: Vec::new(),
};
assert_eq!(src.size().unwrap(), (80, 24));
}
#[test]
fn event_source_set_features() {
let mut src = TestEventSource {
features: BackendFeatures::default(),
events: Vec::new(),
};
let features = BackendFeatures {
mouse_capture: true,
bracketed_paste: true,
focus_events: false,
kitty_keyboard: false,
};
src.set_features(features).unwrap();
assert!(src.features.mouse_capture);
assert!(src.features.bracketed_paste);
}
#[test]
fn event_source_poll_empty() {
let mut src = TestEventSource {
features: BackendFeatures::default(),
events: Vec::new(),
};
assert!(!src.poll_event(Duration::from_millis(10)).unwrap());
}
#[test]
fn event_source_read_none_when_empty() {
let mut src = TestEventSource {
features: BackendFeatures::default(),
events: Vec::new(),
};
assert!(src.read_event().unwrap().is_none());
}
#[test]
fn event_source_poll_with_events() {
let mut src = TestEventSource {
features: BackendFeatures::default(),
events: vec![Event::Focus(true)],
};
assert!(src.poll_event(Duration::from_millis(10)).unwrap());
}
#[test]
fn event_source_read_drains_events() {
let mut src = TestEventSource {
features: BackendFeatures::default(),
events: vec![Event::Focus(true), Event::Focus(false)],
};
let e1 = src.read_event().unwrap();
assert!(e1.is_some());
let e2 = src.read_event().unwrap();
assert!(e2.is_some());
let e3 = src.read_event().unwrap();
assert!(e3.is_none());
}
fn make_test_presenter() -> TestPresenter {
TestPresenter {
caps: TerminalCapabilities::default(),
logs: Vec::new(),
present_count: 0,
gc_count: 0,
pool: GraphemePool::new(),
links: LinkRegistry::new(),
}
}
#[test]
fn presenter_capabilities() {
let p = make_test_presenter();
let _caps = p.capabilities();
}
#[test]
fn presenter_write_log() {
let mut p = make_test_presenter();
p.write_log("hello").unwrap();
p.write_log("world").unwrap();
assert_eq!(p.logs.len(), 2);
assert_eq!(p.logs[0], "hello");
assert_eq!(p.logs[1], "world");
}
#[test]
fn presenter_present_ui() {
let mut p = make_test_presenter();
let buf = Buffer::new(10, 5);
p.present_ui(&buf, None, false).unwrap();
p.present_ui(&buf, None, true).unwrap();
assert_eq!(p.present_count, 2);
}
#[test]
fn presenter_gc() {
let mut p = make_test_presenter();
p.gc();
p.gc();
assert_eq!(p.gc_count, 2);
}
#[test]
fn presenter_defaults() {
let mut p = make_test_presenter();
assert_eq!(p.screen_mode(), ScreenMode::default());
p.set_screen_mode(ScreenMode::AltScreen);
p.resize(120, 40);
assert_eq!(p.render_height_hint(), 0);
assert_eq!(p.estimate_memory_usage(), 0);
assert!(p.last_diff_strategy().is_none());
assert!(p.last_diff_elapsed().is_none());
assert!(p.begin_shutdown().is_ok());
assert!(p.flush().is_ok());
}
#[test]
fn backend_clock_access() {
let backend = make_test_backend();
assert_eq!(backend.clock().now_mono(), Duration::from_millis(42));
}
#[test]
fn backend_events_access() {
let mut backend = make_test_backend();
let size = backend.events().size().unwrap();
assert_eq!(size, (80, 24));
}
#[test]
fn backend_full_cycle() {
let mut backend = make_test_backend();
let mut presenter = make_test_presenter();
let _now = backend.clock().now_mono();
backend
.events()
.set_features(BackendFeatures {
mouse_capture: true,
..BackendFeatures::default()
})
.unwrap();
assert!(backend.events.features.mouse_capture);
let buf = Buffer::new(80, 24);
presenter.write_log("frame start").unwrap();
presenter.present_ui(&buf, None, false).unwrap();
presenter.gc();
assert_eq!(presenter.logs.len(), 1);
assert_eq!(presenter.present_count, 1);
assert_eq!(presenter.gc_count, 1);
}
#[test]
fn test_error_display() {
let err = TestError("something failed".into());
assert_eq!(format!("{err}"), "TestError: something failed");
}
#[test]
fn test_error_debug() {
let err = TestError("oops".into());
let debug = format!("{err:?}");
assert!(debug.contains("oops"));
}
}