#![forbid(unsafe_code)]
use core::time::Duration;
use ftui_a11y::tree::{
A11yTree, A11yTreeBuilder, ScreenReaderAnnouncement, ScreenReaderAnnouncements,
ScreenReaderMirror, ScreenReaderPolicy,
};
use ftui_backend::{BackendClock, BackendEventSource, BackendPresenter};
use ftui_core::event::Event;
use ftui_render::buffer::{Buffer, DoubleBuffer};
use ftui_render::diff::BufferDiff;
use ftui_render::frame::Frame;
use ftui_render::grapheme_pool::GraphemePool;
use ftui_runtime::program::{AccessibilityFrame, Cmd, Model};
use crate::{WebBackend, WebBackendError, WebOutputs};
const POOL_GC_INTERVAL_FRAMES: u64 = 256;
const MIN_TERMINAL_DIMENSION: u16 = 1;
#[inline]
fn clamp_terminal_dimension(value: u16) -> u16 {
if value < MIN_TERMINAL_DIMENSION {
MIN_TERMINAL_DIMENSION
} else {
value
}
}
#[inline]
fn clamp_terminal_size(width: u16, height: u16) -> (u16, u16) {
(
clamp_terminal_dimension(width),
clamp_terminal_dimension(height),
)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StepResult {
pub running: bool,
pub rendered: bool,
pub events_processed: u32,
pub events_pending: u32,
pub frame_idx: u64,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct GeometryTransition {
from_cols: u16,
from_rows: u16,
to_cols: u16,
to_rows: u16,
}
pub struct StepProgram<M: Model> {
model: M,
backend: WebBackend,
pool: GraphemePool,
running: bool,
initialized: bool,
dirty: bool,
frame_idx: u64,
tick_rate: Option<Duration>,
last_tick: Duration,
width: u16,
height: u16,
dbl_buf: Option<DoubleBuffer>,
pending_geometry_transition: Option<GeometryTransition>,
clipboard_requests: Vec<ftui_runtime::program::ClipboardRequest>,
accessibility: Option<ScreenReaderPolicy>,
a11y_tree: A11yTree,
a11y_order: Vec<u64>,
a11y_announcements: Vec<ScreenReaderAnnouncement>,
a11y_dropped: usize,
}
impl<M: Model> StepProgram<M> {
#[must_use]
pub fn new(model: M, width: u16, height: u16) -> Self {
let (width, height) = clamp_terminal_size(width, height);
Self {
model,
backend: WebBackend::new(width, height),
pool: GraphemePool::new(),
running: true,
initialized: false,
dirty: true,
frame_idx: 0,
tick_rate: None,
last_tick: Duration::ZERO,
width,
height,
dbl_buf: None,
pending_geometry_transition: None,
clipboard_requests: Vec::new(),
accessibility: None,
a11y_tree: A11yTree::empty(),
a11y_order: Vec::new(),
a11y_announcements: Vec::new(),
a11y_dropped: 0,
}
}
#[must_use]
pub fn with_backend(model: M, mut backend: WebBackend) -> Self {
let (raw_width, raw_height) = backend.events_mut().size().unwrap_or((80, 24));
let (width, height) = clamp_terminal_size(raw_width, raw_height);
backend.events_mut().set_size(width, height);
Self {
model,
backend,
pool: GraphemePool::new(),
running: true,
initialized: false,
dirty: true,
frame_idx: 0,
tick_rate: None,
last_tick: Duration::ZERO,
width,
height,
dbl_buf: None,
pending_geometry_transition: None,
clipboard_requests: Vec::new(),
accessibility: None,
a11y_tree: A11yTree::empty(),
a11y_order: Vec::new(),
a11y_announcements: Vec::new(),
a11y_dropped: 0,
}
}
#[must_use]
pub fn with_accessibility(mut self, policy: ScreenReaderPolicy) -> Self {
self.set_accessibility_policy(Some(policy));
self
}
pub fn set_accessibility_policy(&mut self, policy: Option<ScreenReaderPolicy>) {
if self.accessibility == policy {
return;
}
self.accessibility = policy;
self.a11y_announcements.clear();
self.a11y_dropped = 0;
if policy.is_none() {
self.a11y_tree = A11yTree::empty();
self.a11y_order = Vec::new();
self.a11y_announcements = Vec::new();
}
self.dirty = true;
}
pub fn request_redraw(&mut self) {
self.dirty = true;
}
#[must_use]
pub fn accessibility_policy(&self) -> Option<ScreenReaderPolicy> {
self.accessibility
}
#[must_use]
pub fn accessibility_tree(&self) -> Option<&A11yTree> {
self.accessibility.map(|_| &self.a11y_tree)
}
#[must_use]
pub fn accessibility_order(&self) -> &[u64] {
&self.a11y_order
}
#[must_use]
pub fn accessibility_announcements(&self) -> &[ScreenReaderAnnouncement] {
&self.a11y_announcements
}
pub fn take_accessibility_announcements(&mut self) -> ScreenReaderAnnouncements {
ScreenReaderAnnouncements {
announcements: std::mem::take(&mut self.a11y_announcements),
dropped_count: std::mem::take(&mut self.a11y_dropped),
}
}
#[must_use]
pub fn accessibility_mirror(&self) -> Option<ScreenReaderMirror> {
self.accessibility
.map(|policy| self.a11y_tree.screen_reader_mirror(policy))
}
pub fn init(&mut self) -> Result<(), WebBackendError> {
assert!(!self.initialized, "StepProgram::init() called twice");
self.initialized = true;
let cmd = self.model.init();
self.execute_cmd(cmd);
if self.running {
self.render_frame()?;
} else {
self.backend.events.set_size(self.width, self.height);
}
Ok(())
}
pub fn step(&mut self) -> Result<StepResult, WebBackendError> {
assert!(self.initialized, "StepProgram::step() called before init()");
if !self.running {
return Ok(StepResult {
running: false,
rendered: false,
events_processed: 0,
events_pending: self.pending_events(),
frame_idx: self.frame_idx,
});
}
let mut events_processed: u32 = 0;
while let Some(event) = self.backend.events.read_event()? {
events_processed += 1;
self.handle_event(event);
if !self.running {
break;
}
}
if self.running
&& let Some(rate) = self.tick_rate
{
let now = self.backend.clock.now_mono();
let delta = now.saturating_sub(self.last_tick);
let should_tick = if rate.is_zero() { true } else { delta >= rate };
if should_tick {
if rate.is_zero() {
self.last_tick = now;
} else {
let rem_ns = delta.as_nanos() % rate.as_nanos();
let rem = Duration::from_nanos(rem_ns as u64);
self.last_tick = now.saturating_sub(rem);
}
let msg = M::Message::from(Event::Tick);
let cmd = self.model.update(msg);
self.dirty = true;
self.execute_cmd(cmd);
}
}
let rendered = if self.running && self.dirty {
self.render_frame()?;
true
} else {
false
};
if !self.running {
self.backend.events.set_size(self.width, self.height);
}
Ok(StepResult {
running: self.running,
rendered,
events_processed,
events_pending: self.pending_events(),
frame_idx: self.frame_idx,
})
}
pub fn push_event(&mut self, event: Event) -> Result<(), WebBackendError> {
if !self.running {
return Err(WebBackendError::Unsupported("program has stopped"));
}
let event = match event {
Event::Resize { width, height } => {
let (width, height) = clamp_terminal_size(width, height);
Event::Resize { width, height }
}
other => other,
};
let resize = match &event {
Event::Resize { width, height } => Some((*width, *height)),
_ => None,
};
self.backend.events_mut().push_event(event)?;
if let Some((width, height)) = resize {
self.backend.events_mut().set_size(width, height);
}
Ok(())
}
pub fn advance_time(&mut self, dt: Duration) {
self.backend.clock_mut().advance(dt);
}
pub fn set_time(&mut self, now: Duration) {
self.backend.clock_mut().set(now);
}
pub fn resize(&mut self, width: u16, height: u16) -> Result<(), WebBackendError> {
self.push_event(Event::Resize { width, height })
}
#[must_use]
pub fn pending_events(&self) -> u32 {
self.backend.events.queued_events() as u32
}
pub fn take_pending_events(&mut self) -> Vec<Event> {
let events = self.backend.events.drain_events().collect();
self.backend.events.set_size(self.width, self.height);
events
}
#[must_use]
pub fn time(&self) -> Duration {
self.backend.clock.now_mono()
}
pub fn take_outputs(&mut self) -> WebOutputs {
self.backend.presenter_mut().take_outputs()
}
pub fn take_clipboard_requests(&mut self) -> Vec<ftui_runtime::program::ClipboardRequest> {
std::mem::take(&mut self.clipboard_requests)
}
pub fn outputs(&self) -> &WebOutputs {
self.backend.presenter.outputs()
}
pub fn model(&self) -> &M {
&self.model
}
pub fn model_mut(&mut self) -> &mut M {
&mut self.model
}
pub fn backend(&self) -> &WebBackend {
&self.backend
}
pub fn backend_mut(&mut self) -> &mut WebBackend {
&mut self.backend
}
pub fn is_running(&self) -> bool {
self.running
}
pub fn is_initialized(&self) -> bool {
self.initialized
}
pub fn frame_idx(&self) -> u64 {
self.frame_idx
}
pub fn size(&self) -> (u16, u16) {
(self.width, self.height)
}
pub fn tick_rate(&self) -> Option<Duration> {
self.tick_rate
}
pub fn pool(&self) -> &GraphemePool {
&self.pool
}
fn handle_event(&mut self, event: Event) {
if let Event::Resize { width, height } = &event {
let (prev_width, prev_height) = (self.width, self.height);
self.width = *width;
self.height = *height;
self.dbl_buf = None;
self.pending_geometry_transition = Some(GeometryTransition {
from_cols: prev_width,
from_rows: prev_height,
to_cols: *width,
to_rows: *height,
});
}
let msg = M::Message::from(event);
let cmd = self.model.update(msg);
self.dirty = true;
self.execute_cmd(cmd);
}
fn render_frame(&mut self) -> Result<(), WebBackendError> {
let full_repaint = self.dbl_buf.is_none();
let geometry_transition = if full_repaint {
self.pending_geometry_transition.take()
} else {
None
};
if self.dbl_buf.is_none() {
self.dbl_buf = Some(DoubleBuffer::new(self.width, self.height));
}
{
let dbl = self.dbl_buf.as_mut().unwrap();
dbl.swap();
dbl.current_mut().clear();
}
let render_buf = std::mem::replace(
self.dbl_buf.as_mut().unwrap().current_mut(),
Buffer::new(1, 1),
);
let mut a11y_builder = self.accessibility.map(|_| A11yTreeBuilder::new());
let (rendered_buffer, a11y_order) = {
let mut frame = Frame::from_buffer(render_buf, &mut self.pool);
if let Some(builder) = a11y_builder.as_mut() {
frame.set_a11y(builder);
}
self.model.view(&mut frame);
frame.finish_a11y();
let order = frame.take_a11y_order();
(frame.buffer, order)
};
let a11y_tree = a11y_builder.map(A11yTreeBuilder::build);
*self.dbl_buf.as_mut().unwrap().current_mut() = rendered_buffer;
let dbl = self.dbl_buf.as_ref().unwrap();
let diff = if full_repaint {
None
} else {
Some(BufferDiff::compute(dbl.previous(), dbl.current()))
};
let buf = dbl.current().clone();
self.backend
.presenter_mut()
.present_ui_owned(buf, diff.as_ref(), full_repaint);
if let Some(transition) = geometry_transition {
self.emit_geometry_transition_markers(transition);
}
self.dirty = false;
let rendered_frame_idx = self.frame_idx;
self.frame_idx += 1;
if self.frame_idx.is_multiple_of(POOL_GC_INTERVAL_FRAMES) {
let Self { dbl_buf, pool, .. } = self;
let dbl = dbl_buf.as_ref().unwrap();
pool.gc(&[dbl.current(), dbl.previous()]);
}
if let (Some(tree), Some(policy)) = (a11y_tree, self.accessibility) {
let diff = tree.diff(&self.a11y_tree);
let changed = !diff.is_empty();
let batch = diff.screen_reader_announcements(&tree, policy);
self.a11y_tree = tree;
self.a11y_order = a11y_order;
self.a11y_announcements = batch.announcements;
self.a11y_dropped = batch.dropped_count;
if changed {
self.dirty = true;
let cmd = self.model.on_accessibility(AccessibilityFrame {
frame_idx: rendered_frame_idx,
tree: &self.a11y_tree,
order: &self.a11y_order,
announcements: &self.a11y_announcements,
dropped: self.a11y_dropped,
});
self.execute_cmd(cmd);
}
}
Ok(())
}
fn emit_geometry_transition_markers(&mut self, transition: GeometryTransition) {
let reset_marker = format!(
r#"{{"event":"diff_baseline_reset","reason":"geometry_transition","from_cols":{},"from_rows":{},"to_cols":{},"to_rows":{},"frame_idx":{}}}"#,
transition.from_cols,
transition.from_rows,
transition.to_cols,
transition.to_rows,
self.frame_idx
);
let repaint_marker = format!(
r#"{{"event":"full_repaint_boundary","reason":"geometry_transition","from_cols":{},"from_rows":{},"to_cols":{},"to_rows":{},"frame_idx":{},"full_repaint":true}}"#,
transition.from_cols,
transition.from_rows,
transition.to_cols,
transition.to_rows,
self.frame_idx
);
let presenter = self.backend.presenter_mut();
let _ = presenter.write_log(&reset_marker);
let _ = presenter.write_log(&repaint_marker);
}
fn execute_cmd(&mut self, cmd: Cmd<M::Message>) {
let mut batches: Vec<std::vec::IntoIter<Cmd<M::Message>>> = Vec::new();
let mut next = Some(cmd);
loop {
let cmd = match next.take() {
Some(cmd) => cmd,
None => {
let Some(rest) = batches.last_mut() else {
return;
};
if !self.running {
return;
}
match rest.next() {
Some(cmd) => cmd,
None => {
batches.pop();
continue;
}
}
}
};
next = self.execute_one_cmd(cmd, &mut batches);
}
}
fn execute_one_cmd(
&mut self,
cmd: Cmd<M::Message>,
batches: &mut Vec<std::vec::IntoIter<Cmd<M::Message>>>,
) -> Option<Cmd<M::Message>> {
match cmd {
Cmd::None => {}
Cmd::Quit => {
self.running = false;
}
Cmd::Msg(m) => {
return Some(self.model.update(m));
}
Cmd::Batch(cmds) | Cmd::Sequence(cmds) => {
let mut rest = cmds.into_iter();
let first = rest.next();
batches.push(rest);
return first;
}
Cmd::Tick(duration) => {
self.tick_rate = Some(duration);
}
Cmd::Log { text, mode } => {
let text = ftui_render::sanitize::sanitize_with(&text, mode);
let _ = self.backend.presenter_mut().write_log(&text);
}
Cmd::Task(_spec, f) => {
let msg = f();
return Some(self.model.update(msg));
}
Cmd::SetMouseCapture(enabled) => {
let mut features = self.backend.events_mut().features();
features.mouse_capture = enabled;
let _ = self.backend.events_mut().set_features(features);
}
Cmd::SetClipboard(text) => self
.clipboard_requests
.push(ftui_runtime::program::ClipboardRequest::Set(text)),
Cmd::GetClipboard => self
.clipboard_requests
.push(ftui_runtime::program::ClipboardRequest::Get),
Cmd::SaveState | Cmd::RestoreState => {
}
Cmd::SetTickStrategy(_) => {
}
}
None
}
}
#[cfg(test)]
mod tests {
use super::*;
use ftui_core::event::{KeyCode, KeyEvent, KeyEventKind, Modifiers};
use ftui_render::cell::Cell;
use ftui_render::drawing::Draw;
use pretty_assertions::assert_eq;
#[test]
fn clipboard_requests_are_drained_for_host_delivery() {
use ftui_runtime::program::ClipboardRequest;
let mut program = StepProgram::new(new_counter(0), 10, 5);
program.init().unwrap();
program.execute_cmd(Cmd::sequence(vec![
Cmd::set_clipboard("界"),
Cmd::get_clipboard(),
]));
assert_eq!(
program.take_clipboard_requests(),
[ClipboardRequest::Set("界".into()), ClipboardRequest::Get]
);
assert!(program.take_clipboard_requests().is_empty());
assert_eq!(program.model.value, 0);
}
#[test]
fn long_msg_and_task_chains_run_without_recursion() {
struct Walker {
steps: u32,
}
enum WalkMsg {
Step(u32),
Event,
}
impl From<Event> for WalkMsg {
fn from(_: Event) -> Self {
WalkMsg::Event
}
}
impl Model for Walker {
type Message = WalkMsg;
fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
match msg {
WalkMsg::Step(0) | WalkMsg::Event => Cmd::none(),
WalkMsg::Step(n) if n % 2 == 0 => {
self.steps += 1;
Cmd::msg(WalkMsg::Step(n - 1))
}
WalkMsg::Step(n) => {
self.steps += 1;
Cmd::task(move || WalkMsg::Step(n - 1))
}
}
}
fn view(&self, _frame: &mut Frame) {}
}
let mut program = StepProgram::new(Walker { steps: 0 }, 10, 5);
program.init().unwrap();
program.execute_cmd(Cmd::msg(WalkMsg::Step(200_000)));
assert_eq!(program.model.steps, 200_000);
}
#[test]
fn the_simulator_and_the_step_program_run_a_command_tree_the_same_way() {
use ftui_runtime::ProgramSimulator;
use std::cell::RefCell;
use std::rc::Rc;
#[derive(Clone, Debug)]
enum Plan {
None,
Msg(u32),
Quit,
Log(String),
Batch(Vec<Plan>),
Sequence(Vec<Plan>),
}
fn build(plan: &Plan) -> Cmd<Step> {
match plan {
Plan::None => Cmd::none(),
Plan::Msg(n) => Cmd::msg(Step::Seen(*n)),
Plan::Quit => Cmd::quit(),
Plan::Log(text) => Cmd::log(text.clone()),
Plan::Batch(children) => Cmd::batch(children.iter().map(build).collect::<Vec<_>>()),
Plan::Sequence(children) => {
Cmd::sequence(children.iter().map(build).collect::<Vec<_>>())
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Step {
Seen(u32),
Ignored,
}
impl From<Event> for Step {
fn from(_: Event) -> Self {
Step::Ignored
}
}
struct Recorder {
plan: Plan,
seen: Rc<RefCell<Vec<u32>>>,
}
impl Model for Recorder {
type Message = Step;
fn init(&mut self) -> Cmd<Step> {
build(&self.plan)
}
fn update(&mut self, msg: Step) -> Cmd<Step> {
if let Step::Seen(n) = msg {
self.seen.borrow_mut().push(n);
}
Cmd::none()
}
fn view(&self, _frame: &mut Frame) {}
}
let mut state = 0x2545_F491_4F6C_DD1Du64;
let mut next = move || {
state ^= state << 13;
state ^= state >> 7;
state ^= state << 17;
state
};
let plan = |depth: u32, id: &mut u32, rng: &mut dyn FnMut() -> u64| -> Plan {
fn go(depth: u32, id: &mut u32, rng: &mut dyn FnMut() -> u64) -> Plan {
match rng() % if depth == 0 { 4 } else { 6 } {
0 => Plan::None,
1 | 2 => {
*id += 1;
Plan::Msg(*id)
}
3 => {
if rng().is_multiple_of(6) {
Plan::Quit
} else {
Plan::Log(format!("log{}", rng() % 100))
}
}
4 => Plan::Batch((0..rng() % 4).map(|_| go(depth - 1, id, rng)).collect()),
_ => Plan::Sequence((0..rng() % 4).map(|_| go(depth - 1, id, rng)).collect()),
}
}
go(depth, id, rng)
};
let (mut with_messages, mut that_quit) = (0u32, 0u32);
for trial in 0..2_000 {
let mut id = 0;
let tree = plan(3, &mut id, &mut next);
let simulator_seen = Rc::new(RefCell::new(Vec::new()));
let mut simulator = ProgramSimulator::new(Recorder {
plan: tree.clone(),
seen: Rc::clone(&simulator_seen),
});
simulator.init();
let step_seen = Rc::new(RefCell::new(Vec::new()));
let mut program = StepProgram::new(
Recorder {
plan: tree.clone(),
seen: Rc::clone(&step_seen),
},
80,
24,
);
program.init().expect("init the step program");
let (from_simulator, from_step) =
(simulator_seen.borrow().clone(), step_seen.borrow().clone());
if !from_simulator.is_empty() {
with_messages += 1;
}
if !simulator.is_running() {
that_quit += 1;
}
assert_eq!(
from_simulator, from_step,
"trial {trial}: the two runtimes delivered different messages for {tree:?}"
);
assert_eq!(
simulator.is_running(),
program.is_running(),
"trial {trial}: the two runtimes disagreed about quitting for {tree:?}"
);
}
assert!(
with_messages > 500 && that_quit > 50,
"the trees were too dull to compare: {with_messages} delivered a message \
and {that_quit} quit"
);
}
struct Counter {
value: i32,
initialized: bool,
}
#[derive(Debug)]
enum CounterMsg {
Increment,
Decrement,
Reset,
Quit,
LogValue,
BatchIncrement(usize),
SpawnTask,
}
impl From<Event> for CounterMsg {
fn from(event: Event) -> Self {
match event {
Event::Key(k) if k.code == KeyCode::Char('+') => CounterMsg::Increment,
Event::Key(k) if k.code == KeyCode::Char('-') => CounterMsg::Decrement,
Event::Key(k) if k.code == KeyCode::Char('r') => CounterMsg::Reset,
Event::Key(k) if k.code == KeyCode::Char('q') => CounterMsg::Quit,
Event::Tick => CounterMsg::Increment,
_ => CounterMsg::Increment,
}
}
}
impl Model for Counter {
type Message = CounterMsg;
fn init(&mut self) -> Cmd<Self::Message> {
self.initialized = true;
Cmd::none()
}
fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
match msg {
CounterMsg::Increment => {
self.value += 1;
Cmd::none()
}
CounterMsg::Decrement => {
self.value -= 1;
Cmd::none()
}
CounterMsg::Reset => {
self.value = 0;
Cmd::none()
}
CounterMsg::Quit => Cmd::quit(),
CounterMsg::LogValue => Cmd::log(format!("value={}", self.value)),
CounterMsg::BatchIncrement(n) => {
let cmds: Vec<_> = (0..n).map(|_| Cmd::msg(CounterMsg::Increment)).collect();
Cmd::batch(cmds)
}
CounterMsg::SpawnTask => Cmd::task(|| CounterMsg::Increment),
}
}
fn view(&self, frame: &mut Frame) {
let text = format!("Count: {}", self.value);
for (i, c) in text.chars().enumerate() {
if (i as u16) < frame.width() {
frame.buffer.set_raw(i as u16, 0, Cell::from_char(c));
}
}
}
}
struct GraphemeChurn {
value: u32,
}
impl Model for GraphemeChurn {
type Message = CounterMsg;
fn init(&mut self) -> Cmd<Self::Message> {
Cmd::none()
}
fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
if let CounterMsg::Increment = msg {
self.value = self.value.wrapping_add(1);
}
Cmd::none()
}
fn view(&self, frame: &mut Frame) {
let base = char::from_u32(0x4e00 + (self.value % 2048)).unwrap_or('å—');
let text = format!("{base}\u{0301}");
frame.print_text(0, 0, &text, Cell::default());
}
}
fn key_event(c: char) -> Event {
Event::Key(KeyEvent {
code: KeyCode::Char(c),
modifiers: Modifiers::empty(),
kind: KeyEventKind::Press,
})
}
fn new_counter(value: i32) -> Counter {
Counter {
value,
initialized: false,
}
}
fn new_grapheme_churn() -> GraphemeChurn {
GraphemeChurn { value: 0 }
}
#[test]
fn new_creates_uninitialized_program() {
let prog = StepProgram::new(new_counter(0), 80, 24);
assert!(!prog.is_initialized());
assert!(prog.is_running());
assert_eq!(prog.size(), (80, 24));
assert_eq!(prog.frame_idx(), 0);
assert!(prog.tick_rate().is_none());
}
#[test]
fn new_clamps_zero_dimensions_to_minimum() {
let prog = StepProgram::new(new_counter(0), 0, 0);
assert_eq!(prog.size(), (1, 1));
}
#[test]
fn with_backend_clamps_zero_dimensions_to_minimum() {
let backend = WebBackend::new(0, 0);
let prog = StepProgram::with_backend(new_counter(0), backend);
assert_eq!(prog.size(), (1, 1));
}
#[test]
fn init_initializes_model_and_renders_first_frame() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
assert!(prog.is_initialized());
assert!(prog.model().initialized);
assert_eq!(prog.frame_idx(), 1);
let outputs = prog.outputs();
assert!(outputs.last_buffer.is_some());
assert!(outputs.last_full_repaint_hint); assert_eq!(outputs.last_patches.len(), 1);
let stats = outputs
.last_patch_stats
.expect("patch stats should be captured");
assert_eq!(stats.patch_count, 1);
assert_eq!(stats.dirty_cells, 80 * 24);
}
#[test]
#[should_panic(expected = "init() called twice")]
fn double_init_panics() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.init().unwrap();
}
#[test]
#[should_panic(expected = "step() called before init()")]
fn step_before_init_panics() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
let _ = prog.step();
}
#[test]
fn step_processes_pushed_events() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.push_event(key_event('+')).expect("key admission");
prog.push_event(key_event('+')).expect("key admission");
prog.push_event(key_event('+')).expect("key admission");
let result = prog.step().unwrap();
assert!(result.running);
assert!(result.rendered);
assert_eq!(result.events_processed, 3);
assert_eq!(prog.model().value, 3);
}
#[test]
fn step_with_no_events_does_not_render() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.take_outputs();
let result = prog.step().unwrap();
assert!(result.running);
assert!(!result.rendered);
assert_eq!(result.events_processed, 0);
}
#[test]
fn quit_event_stops_program() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.push_event(key_event('+')).expect("key admission");
prog.push_event(key_event('q')).expect("quit admission");
prog.push_event(key_event('+')).expect("key admission"); let paste = Event::Paste(ftui_core::event::PasteEvent::bracketed("尾巴 🦀"));
prog.push_event(paste.clone()).unwrap();
prog.resize(120, 40).unwrap();
let result = prog.step().unwrap();
assert!(!result.running);
assert!(!result.rendered);
assert_eq!(result.events_processed, 2);
assert_eq!(result.events_pending, 3);
assert!(!prog.is_running());
assert_eq!(prog.model().value, 1); assert_eq!(prog.size(), (80, 24));
assert_eq!(prog.backend.events_mut().size().unwrap(), (80, 24));
assert_eq!(prog.step().unwrap().events_pending, 3);
assert_eq!(
prog.take_pending_events(),
vec![
key_event('+'),
paste,
Event::Resize {
width: 120,
height: 40
}
]
);
assert_eq!(prog.pending_events(), 0);
assert_eq!(prog.backend.events.queued_payload_bytes(), 0);
assert!(prog.take_pending_events().is_empty());
assert_eq!(prog.model().value, 1);
}
#[test]
fn step_after_quit_returns_immediately() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.push_event(key_event('q')).expect("quit admission");
prog.step().unwrap();
assert_eq!(
prog.push_event(key_event('+')),
Err(WebBackendError::Unsupported("program has stopped"))
);
assert_eq!(
prog.resize(120, 40),
Err(WebBackendError::Unsupported("program has stopped"))
);
assert_eq!(prog.size(), (80, 24));
let result = prog.step().unwrap();
assert!(!result.running);
assert!(!result.rendered);
assert_eq!(result.events_processed, 0);
assert_eq!(prog.model().value, 0);
}
#[test]
fn rejected_resize_preserves_geometry_and_accepted_input_until_recovery() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
for _ in 0..crate::WebEventSource::MAX_EVENTS {
prog.push_event(key_event('+')).unwrap();
}
assert!(matches!(
prog.resize(120, 40),
Err(WebBackendError::InputQueueFull {
limit: crate::WebInputLimit::Events,
event: Event::Resize {
width: 120,
height: 40
},
})
));
assert_eq!(prog.backend.events_mut().size().unwrap(), (80, 24));
assert_eq!(prog.size(), (80, 24));
let result = prog.step().unwrap();
assert_eq!(
result.events_processed as usize,
crate::WebEventSource::MAX_EVENTS
);
assert_eq!(
prog.model().value as usize,
crate::WebEventSource::MAX_EVENTS
);
assert_eq!(prog.size(), (80, 24));
prog.resize(120, 40).unwrap();
assert_eq!(prog.step().unwrap().events_processed, 1);
assert_eq!(prog.size(), (120, 40));
assert_eq!(prog.backend.events_mut().size().unwrap(), (120, 40));
}
#[test]
fn resize_updates_dimensions() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.resize(120, 40).expect("resize admission");
prog.step().unwrap();
assert_eq!(prog.size(), (120, 40));
}
#[test]
fn resize_clamps_zero_dimensions_to_minimum() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.resize(0, 0).expect("resize admission");
prog.step().unwrap();
assert_eq!(prog.size(), (1, 1));
let outputs = prog.outputs();
let buf = outputs.last_buffer.as_ref().expect("resize should render");
assert_eq!(buf.width(), 1);
assert_eq!(buf.height(), 1);
}
#[test]
fn resize_produces_correctly_sized_buffer() {
let mut prog = StepProgram::new(new_counter(42), 80, 24);
prog.init().unwrap();
prog.resize(40, 10).expect("resize admission");
prog.step().unwrap();
let outputs = prog.outputs();
let buf = outputs.last_buffer.as_ref().unwrap();
assert_eq!(buf.width(), 40);
assert_eq!(buf.height(), 10);
}
#[test]
fn resize_emits_baseline_reset_and_full_repaint_markers() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
let _ = prog.take_outputs();
prog.resize(120, 40).expect("resize admission");
prog.step().unwrap();
let outputs = prog.outputs();
assert!(
outputs
.logs
.iter()
.any(|line| line.contains(r#""event":"diff_baseline_reset""#))
);
assert!(
outputs
.logs
.iter()
.any(|line| line.contains(r#""event":"full_repaint_boundary""#))
);
assert!(
outputs
.logs
.iter()
.any(|line| line.contains(r#""from_cols":80"#) && line.contains(r#""to_cols":120"#))
);
}
#[test]
fn same_size_resize_still_forces_repaint_boundary() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
let _ = prog.take_outputs();
prog.resize(80, 24).expect("resize admission");
prog.step().unwrap();
let outputs = prog.take_outputs();
assert!(outputs.last_full_repaint_hint);
assert_eq!(outputs.last_patches.len(), 1);
assert_eq!(outputs.last_patches[0].offset, 0);
assert_eq!(outputs.last_patches[0].cells.len(), 80usize * 24usize);
assert!(outputs.logs.iter().any(|line| {
line.contains(r#""event":"diff_baseline_reset""#)
&& line.contains(r#""from_cols":80"#)
&& line.contains(r#""to_cols":80"#)
}));
assert!(outputs.logs.iter().any(|line| {
line.contains(r#""event":"full_repaint_boundary""#)
&& line.contains(r#""from_rows":24"#)
&& line.contains(r#""to_rows":24"#)
}));
}
#[test]
fn resize_oscillation_forces_full_repaint_without_stale_patch_offsets() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
let _ = prog.take_outputs();
for (w, h) in [(120, 40), (80, 24), (120, 40), (80, 24)] {
prog.resize(w, h).expect("resize admission");
prog.step().unwrap();
let outputs = prog.take_outputs();
assert!(outputs.last_full_repaint_hint);
let buf = outputs
.last_buffer
.expect("resize render should produce a buffer");
assert_eq!(buf.width(), w);
assert_eq!(buf.height(), h);
let max_cells = usize::from(w) * usize::from(h);
assert_eq!(outputs.last_patches.len(), 1);
let run = &outputs.last_patches[0];
assert_eq!(run.offset, 0);
assert_eq!(run.cells.len(), max_cells);
assert!(run.offset as usize + run.cells.len() <= max_cells);
}
}
#[test]
fn resize_boundary_full_repaint_then_incremental_diff_resume() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
let _ = prog.take_outputs();
prog.resize(100, 30).expect("resize admission");
prog.step().unwrap();
let after_resize = prog.take_outputs();
assert!(after_resize.last_full_repaint_hint);
prog.push_event(key_event('+')).expect("key admission");
prog.step().unwrap();
let after_increment = prog.take_outputs();
assert!(!after_increment.last_full_repaint_hint);
assert!(!after_increment.last_patches.is_empty());
}
#[test]
fn tick_fires_when_rate_elapsed() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.push_event(key_event('+')).expect("key admission");
prog.step().unwrap();
prog.model_mut().value = 0;
prog.execute_cmd(Cmd::tick(Duration::from_millis(100)));
prog.dirty = false;
prog.advance_time(Duration::from_millis(50));
let result = prog.step().unwrap();
assert_eq!(prog.model().value, 0);
assert!(!result.rendered);
prog.advance_time(Duration::from_millis(60));
let result = prog.step().unwrap();
assert_eq!(prog.model().value, 1); assert!(result.rendered);
}
#[test]
fn tick_uses_deterministic_clock() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.execute_cmd(Cmd::tick(Duration::from_millis(100)));
prog.set_time(Duration::from_millis(200));
prog.step().unwrap();
assert_eq!(prog.model().value, 1);
prog.set_time(Duration::from_millis(350));
prog.step().unwrap();
assert_eq!(prog.model().value, 2);
}
#[test]
fn log_command_captures_to_presenter() {
let mut prog = StepProgram::new(new_counter(5), 80, 24);
prog.init().unwrap();
prog.execute_cmd(Cmd::msg(CounterMsg::LogValue));
let outputs = prog.outputs();
assert_eq!(outputs.logs, vec!["value=5"]);
}
#[test]
fn log_modes_capture_policy_text_without_terminal_formatting() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
let payload = "a\x1b[31mb\x1b[2Jc\x1b]0;secret\x07d\n";
prog.execute_cmd(Cmd::sequence(vec![
Cmd::log(payload),
Cmd::log_sgr_only(payload),
Cmd::log_raw(payload),
Cmd::quit(),
Cmd::log("unreachable"),
]));
assert!(!prog.is_running());
assert_eq!(prog.outputs().logs, ["abcd\n", "a\x1b[31mbcd\n", payload]);
}
#[test]
fn batch_command_executes_all() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.execute_cmd(Cmd::msg(CounterMsg::BatchIncrement(5)));
assert_eq!(prog.model().value, 5);
}
#[test]
fn task_executes_synchronously() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.execute_cmd(Cmd::msg(CounterMsg::SpawnTask));
assert_eq!(prog.model().value, 1); }
#[test]
fn set_mouse_capture_updates_features() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.execute_cmd(Cmd::set_mouse_capture(true));
assert!(prog.backend().events.features().mouse_capture);
prog.execute_cmd(Cmd::set_mouse_capture(false));
assert!(!prog.backend().events.features().mouse_capture);
}
#[test]
fn rendered_buffer_reflects_model_state() {
let mut prog = StepProgram::new(new_counter(42), 80, 24);
prog.init().unwrap();
let outputs = prog.outputs();
let buf = outputs.last_buffer.as_ref().unwrap();
assert_eq!(buf.get(0, 0).unwrap().content.as_char(), Some('C'));
assert_eq!(buf.get(7, 0).unwrap().content.as_char(), Some('4'));
assert_eq!(buf.get(8, 0).unwrap().content.as_char(), Some('2'));
}
#[test]
fn subsequent_renders_produce_diffs() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
let outputs = prog.take_outputs();
assert!(outputs.last_full_repaint_hint);
prog.push_event(key_event('+')).expect("key admission");
prog.step().unwrap();
let outputs = prog.outputs();
assert!(!outputs.last_full_repaint_hint);
assert!(!outputs.last_patches.is_empty());
let stats = outputs
.last_patch_stats
.expect("patch stats should be captured");
assert!(stats.patch_count >= 1);
assert!(stats.dirty_cells >= 1);
}
#[test]
fn take_outputs_clears_state() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
let outputs = prog.take_outputs();
assert!(outputs.last_buffer.is_some());
let outputs = prog.outputs();
assert!(outputs.last_buffer.is_none());
assert!(outputs.logs.is_empty());
}
#[test]
fn identical_inputs_produce_identical_outputs() {
fn run_scenario() -> (i32, u64, Vec<Option<char>>) {
let mut prog = StepProgram::new(new_counter(0), 20, 1);
prog.init().unwrap();
prog.push_event(key_event('+')).expect("key admission");
prog.push_event(key_event('+')).expect("key admission");
prog.push_event(key_event('-')).expect("key admission");
prog.push_event(key_event('+')).expect("key admission");
prog.step().unwrap();
let outputs = prog.outputs();
let buf = outputs.last_buffer.as_ref().unwrap();
let chars: Vec<Option<char>> = (0..20)
.map(|x| buf.get(x, 0).and_then(|c| c.content.as_char()))
.collect();
(prog.model().value, prog.frame_idx(), chars)
}
let (v1, f1, c1) = run_scenario();
let (v2, f2, c2) = run_scenario();
let (v3, f3, c3) = run_scenario();
assert_eq!(v1, v2);
assert_eq!(v2, v3);
assert_eq!(v1, 2); assert_eq!(f1, f2);
assert_eq!(f2, f3);
assert_eq!(c1, c2);
assert_eq!(c2, c3);
}
#[test]
fn with_backend_uses_provided_backend() {
let mut backend = WebBackend::new(100, 50);
backend.clock_mut().set(Duration::from_secs(10));
let prog = StepProgram::with_backend(new_counter(0), backend);
assert_eq!(prog.size(), (100, 50));
}
#[test]
fn multi_step_interaction() {
let mut prog = StepProgram::new(new_counter(0), 80, 24);
prog.init().unwrap();
prog.push_event(key_event('+')).expect("key admission");
prog.push_event(key_event('+')).expect("key admission");
let r1 = prog.step().unwrap();
assert_eq!(r1.events_processed, 2);
assert!(r1.rendered);
assert_eq!(prog.model().value, 2);
prog.push_event(key_event('-')).expect("key admission");
let r2 = prog.step().unwrap();
assert_eq!(r2.events_processed, 1);
assert_eq!(prog.model().value, 1);
let r3 = prog.step().unwrap();
assert_eq!(r3.events_processed, 0);
assert!(!r3.rendered);
assert!(r2.frame_idx > r1.frame_idx);
assert_eq!(r3.frame_idx, r2.frame_idx); }
#[test]
fn periodic_pool_gc_bounds_grapheme_growth() {
let mut prog = StepProgram::new(new_grapheme_churn(), 8, 1);
prog.init().unwrap();
prog.execute_cmd(Cmd::tick(Duration::from_millis(1)));
let mut peak_pool_len = prog.pool().len();
for _ in 0..2000 {
prog.advance_time(Duration::from_millis(1));
let _ = prog.step().unwrap();
peak_pool_len = peak_pool_len.max(prog.pool().len());
}
let final_pool_len = prog.pool().len();
assert!(
peak_pool_len <= (POOL_GC_INTERVAL_FRAMES as usize).saturating_add(2),
"peak grapheme pool length should stay bounded by GC interval (peak={peak_pool_len})"
);
assert!(
final_pool_len <= (POOL_GC_INTERVAL_FRAMES as usize).saturating_add(2),
"final grapheme pool length should stay bounded by GC interval (final={final_pool_len})"
);
}
}