#![forbid(unsafe_code)]
use crate::program::{Cmd, Model};
use crate::state_persistence::StateRegistry;
use crate::tick_strategy::{TickDecision, TickStrategy};
use ftui_core::event::Event;
use ftui_render::buffer::Buffer;
use ftui_render::diff::BufferDiff;
use ftui_render::frame::Frame;
use ftui_render::grapheme_pool::GraphemePool;
use std::collections::VecDeque;
use std::sync::Arc;
use std::time::Duration;
#[derive(Debug, Clone, Copy, Default)]
pub struct StepResult {
pub events_processed: u32,
pub tick_fired: bool,
pub dirty: bool,
pub quit: bool,
}
pub struct RenderedFrame<'a> {
pub buffer: &'a Buffer,
pub diff: Option<BufferDiff>,
pub frame_idx: u64,
}
pub struct WasmRunner<M: Model> {
model: M,
pool: GraphemePool,
current: Buffer,
previous: Option<Buffer>,
running: bool,
dirty: bool,
initialized: bool,
width: u16,
height: u16,
frame_idx: u64,
tick_rate: Option<Duration>,
last_tick_at: Duration,
tick_count: u64,
tick_strategy: Option<Box<dyn TickStrategy>>,
last_active_screen_for_strategy: Option<String>,
state_registry: Option<Arc<StateRegistry>>,
event_queue: VecDeque<Event>,
logs: Vec<String>,
clipboard_requests: Vec<crate::program::ClipboardRequest>,
}
impl<M: Model> WasmRunner<M> {
#[must_use]
pub fn new(model: M, width: u16, height: u16) -> Self {
Self {
model,
pool: GraphemePool::new(),
current: Buffer::new(width, height),
previous: None,
running: true,
dirty: true, initialized: false,
width,
height,
frame_idx: 0,
tick_rate: None,
last_tick_at: Duration::ZERO,
tick_count: 0,
tick_strategy: None,
last_active_screen_for_strategy: None,
state_registry: None,
event_queue: VecDeque::new(),
logs: Vec::new(),
clipboard_requests: Vec::new(),
}
}
#[must_use]
pub fn with_registry(mut self, registry: Arc<StateRegistry>) -> Self {
self.state_registry = Some(registry);
self
}
#[must_use]
pub fn with_tick_strategy(mut self, strategy: impl TickStrategy + 'static) -> Self {
self.tick_strategy = Some(Box::new(strategy));
self
}
#[must_use]
pub fn tick_strategy_name(&self) -> Option<&str> {
self.tick_strategy.as_ref().map(|s| s.name())
}
pub fn init(&mut self) -> StepResult {
let cmd = self.model.init();
self.initialized = true;
self.dirty = true;
let mut result = StepResult {
dirty: true,
..Default::default()
};
self.execute_cmd(cmd, &mut result);
if self.running {
self.check_screen_transition(&mut result);
}
result
}
pub fn push_event(&mut self, event: Event) {
self.event_queue.push_back(event);
}
pub fn push_events(&mut self, events: impl IntoIterator<Item = Event>) {
self.event_queue.extend(events);
}
pub fn step(&mut self, now: Duration) -> StepResult {
if !self.running || !self.initialized {
return StepResult {
quit: !self.running,
..Default::default()
};
}
let mut result = StepResult::default();
while let Some(event) = self.event_queue.pop_front() {
if !self.running {
break;
}
self.handle_event(event, &mut result);
result.events_processed += 1;
}
if self.running
&& let Some(rate) = self.tick_rate
&& now.saturating_sub(self.last_tick_at) >= rate
{
self.last_tick_at = now;
self.tick_count = self.tick_count.wrapping_add(1);
let tick_count = self.tick_count;
let mut used_screen_dispatch = false;
if let Some(strategy) = self.tick_strategy.as_mut() {
let dispatch_snapshot = self.model.as_screen_tick_dispatch().map(|dispatch| {
let active = dispatch.active_screen_id();
let all_screens = dispatch.screen_ids();
(active, all_screens)
});
if let Some((active, all_screens)) = dispatch_snapshot {
used_screen_dispatch = true;
if let Some(previous_active) = self.last_active_screen_for_strategy.as_deref()
&& previous_active != active
{
strategy.on_screen_transition(previous_active, &active);
}
self.last_active_screen_for_strategy = Some(active.clone());
let mut tick_targets = Vec::with_capacity(all_screens.len().max(1));
tick_targets.push(active.clone());
for screen_id in all_screens {
if screen_id != active
&& strategy.should_tick(&screen_id, tick_count, &active)
== TickDecision::Tick
{
tick_targets.push(screen_id);
}
}
if let Some(dispatch) = self.model.as_screen_tick_dispatch() {
for screen_id in &tick_targets {
dispatch.tick_screen(screen_id, tick_count);
}
}
strategy.maintenance_tick(tick_count);
self.dirty = true;
result.tick_fired = true;
}
}
if !used_screen_dispatch {
self.last_active_screen_for_strategy = None;
let msg = M::Message::from(Event::Tick);
let cmd = self.model.update(msg);
self.dirty = true;
result.tick_fired = true;
self.execute_cmd(cmd, &mut result);
}
}
result.dirty = self.dirty;
result.quit = !self.running;
result
}
pub fn step_event(&mut self, event: Event) -> StepResult {
if !self.running || !self.initialized {
return StepResult {
quit: !self.running,
..Default::default()
};
}
let mut result = StepResult::default();
self.handle_event(event, &mut result);
result.events_processed = 1;
result.dirty = self.dirty;
result.quit = !self.running;
result
}
pub fn render(&mut self) -> Option<RenderedFrame<'_>> {
if !self.dirty {
return None;
}
Some(self.force_render())
}
pub fn force_render(&mut self) -> RenderedFrame<'_> {
let mut frame = Frame::new(self.width, self.height, &mut self.pool);
self.model.view(&mut frame);
let diff = self
.previous
.as_ref()
.map(|prev| BufferDiff::compute(prev, &frame.buffer));
self.previous = Some(std::mem::replace(&mut self.current, frame.buffer));
self.dirty = false;
let idx = self.frame_idx;
self.frame_idx += 1;
RenderedFrame {
buffer: &self.current,
diff,
frame_idx: idx,
}
}
pub fn resize(&mut self, width: u16, height: u16) {
if width == self.width && height == self.height {
return;
}
self.width = width;
self.height = height;
self.current = Buffer::new(width, height);
self.previous = None; self.dirty = true;
if self.running && self.initialized {
let msg = M::Message::from(Event::Resize { width, height });
let cmd = self.model.update(msg);
let mut result = StepResult::default();
self.execute_cmd(cmd, &mut result);
if self.running {
self.check_screen_transition(&mut result);
}
}
}
#[must_use]
pub fn is_running(&self) -> bool {
self.running
}
#[must_use]
pub fn is_dirty(&self) -> bool {
self.dirty
}
#[must_use]
pub fn is_initialized(&self) -> bool {
self.initialized
}
#[must_use]
pub fn size(&self) -> (u16, u16) {
(self.width, self.height)
}
#[must_use]
pub fn frame_idx(&self) -> u64 {
self.frame_idx
}
#[must_use]
pub fn tick_rate(&self) -> Option<Duration> {
self.tick_rate
}
#[must_use]
pub fn pending_events(&self) -> usize {
self.event_queue.len()
}
#[inline]
#[must_use]
pub fn model(&self) -> &M {
&self.model
}
#[inline]
pub fn model_mut(&mut self) -> &mut M {
&mut self.model
}
#[inline]
pub fn drain_logs(&mut self) -> Vec<String> {
std::mem::take(&mut self.logs)
}
#[inline]
#[must_use]
pub fn logs(&self) -> &[String] {
&self.logs
}
pub fn take_clipboard_requests(&mut self) -> Vec<crate::program::ClipboardRequest> {
std::mem::take(&mut self.clipboard_requests)
}
#[inline]
#[must_use]
pub fn current_buffer(&self) -> &Buffer {
&self.current
}
fn check_screen_transition(&mut self, result: &mut StepResult) {
if self.tick_strategy.is_none() || !self.running {
return;
}
let current_active = match self.model.as_screen_tick_dispatch() {
Some(dispatch) => dispatch.active_screen_id(),
None => return,
};
let previous = match self.last_active_screen_for_strategy.take() {
Some(prev) => prev,
None => {
self.last_active_screen_for_strategy = Some(current_active);
return;
}
};
if previous == current_active {
self.last_active_screen_for_strategy = Some(current_active);
return;
}
if let Some(strategy) = self.tick_strategy.as_mut() {
strategy.on_screen_transition(&previous, ¤t_active);
}
if let Some(dispatch) = self.model.as_screen_tick_dispatch() {
dispatch.tick_screen(¤t_active, self.tick_count);
self.dirty = true;
result.dirty = true;
}
self.last_active_screen_for_strategy = Some(current_active);
}
fn handle_event(&mut self, event: Event, result: &mut StepResult) {
if let Event::Resize { width, height } = event
&& (width != self.width || height != self.height)
{
self.width = width;
self.height = height;
self.current = Buffer::new(width, height);
self.previous = None;
}
let msg = M::Message::from(event);
let cmd = self.model.update(msg);
self.dirty = true;
self.execute_cmd(cmd, result);
if self.running {
self.check_screen_transition(result);
}
}
fn execute_cmd(&mut self, cmd: Cmd<M::Message>, result: &mut StepResult) {
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, result, &mut batches);
}
}
fn execute_one_cmd(
&mut self,
cmd: Cmd<M::Message>,
result: &mut StepResult,
batches: &mut Vec<std::vec::IntoIter<Cmd<M::Message>>>,
) -> Option<Cmd<M::Message>> {
match cmd {
Cmd::None => {}
Cmd::Quit => {
self.running = false;
result.quit = true;
if let Some(ref mut strategy) = self.tick_strategy {
strategy.shutdown();
}
}
Cmd::Msg(m) => {
return Some(self.model.update(m));
}
Cmd::Batch(cmds) | Cmd::Sequence(cmds) => {
batches.push(cmds.into_iter());
}
Cmd::Tick(duration) => {
self.tick_rate = Some(duration);
}
Cmd::Log { text, mode } => {
self.logs
.push(ftui_render::sanitize::sanitize_with(&text, mode).into_owned());
}
Cmd::Task(_, f) => {
let msg = f();
return Some(self.model.update(msg));
}
Cmd::SetMouseCapture(_) => {
}
Cmd::SetClipboard(text) => self
.clipboard_requests
.push(crate::program::ClipboardRequest::Set(text)),
Cmd::GetClipboard => self
.clipboard_requests
.push(crate::program::ClipboardRequest::Get),
Cmd::SaveState => {
if let Some(ref registry) = self.state_registry
&& let Err(error) = registry.flush()
{
let msg = format!("state save failed: {error}");
self.logs.push(msg.clone());
return Some(self.model.on_error(&msg));
}
}
Cmd::RestoreState => {
if let Some(ref registry) = self.state_registry {
match registry.load() {
Ok(_) => {
self.dirty = true;
result.dirty = true;
}
Err(error) => {
let msg = format!("state restore failed: {error}");
self.logs.push(msg.clone());
return Some(self.model.on_error(&msg));
}
}
}
}
Cmd::SetTickStrategy(strategy) => {
if let Some(ref mut prev) = self.tick_strategy {
prev.shutdown();
}
self.tick_strategy = Some(strategy);
self.last_active_screen_for_strategy = None;
}
}
None
}
}
#[cfg(test)]
mod tests {
use super::*;
use ftui_core::event::{KeyCode, KeyEvent, KeyEventKind, Modifiers};
use ftui_render::cell::Cell;
#[test]
fn clipboard_requests_are_drained_for_host_delivery() {
use crate::program::ClipboardRequest;
let mut runner = WasmRunner::new(Counter { value: 0 }, 10, 5);
let mut result = runner.init();
runner.execute_cmd(
Cmd::sequence(vec![Cmd::set_clipboard("界"), Cmd::get_clipboard()]),
&mut result,
);
assert_eq!(
runner.take_clipboard_requests(),
[ClipboardRequest::Set("界".into()), ClipboardRequest::Get]
);
assert!(runner.take_clipboard_requests().is_empty());
assert_eq!(runner.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 runner = WasmRunner::new(Walker { steps: 0 }, 10, 5);
let mut result = runner.init();
runner.execute_cmd(Cmd::msg(WalkMsg::Step(200_000)), &mut result);
assert_eq!(runner.model.steps, 200_000);
runner.running = false;
runner.execute_cmd(
Cmd::Batch(vec![Cmd::msg(WalkMsg::Step(2)), Cmd::none()]),
&mut result,
);
assert_eq!(runner.model.steps, 200_000);
}
struct Counter {
value: i32,
}
#[derive(Debug)]
#[allow(dead_code)]
enum CounterMsg {
Increment,
Decrement,
Quit,
ScheduleTick,
LogValue,
}
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('q') => CounterMsg::Quit,
_ => CounterMsg::Increment,
}
}
}
impl Model for Counter {
type Message = CounterMsg;
fn init(&mut self) -> Cmd<Self::Message> {
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::Quit => Cmd::quit(),
CounterMsg::ScheduleTick => Cmd::tick(Duration::from_millis(100)),
CounterMsg::LogValue => Cmd::log(format!("value={}", self.value)),
}
}
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));
}
}
}
}
fn key_event(c: char) -> Event {
Event::Key(KeyEvent {
code: KeyCode::Char(c),
modifiers: Modifiers::empty(),
kind: KeyEventKind::Press,
})
}
#[test]
fn init_marks_dirty() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
let result = runner.init();
assert!(result.dirty);
assert!(runner.is_initialized());
}
#[test]
fn step_event_updates_model() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
runner.init();
let r = runner.step_event(key_event('+'));
assert_eq!(runner.model().value, 1);
assert!(r.dirty);
assert_eq!(r.events_processed, 1);
}
#[test]
fn buffered_events_drain_on_step() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
runner.init();
runner.push_event(key_event('+'));
runner.push_event(key_event('+'));
runner.push_event(key_event('+'));
let r = runner.step(Duration::ZERO);
assert_eq!(r.events_processed, 3);
assert_eq!(runner.model().value, 3);
assert_eq!(runner.pending_events(), 0);
}
#[test]
fn quit_stops_processing() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
runner.init();
runner.push_event(key_event('+'));
runner.push_event(key_event('q'));
runner.push_event(key_event('+'));
let r = runner.step(Duration::ZERO);
assert!(r.quit);
assert!(!runner.is_running());
assert_eq!(runner.model().value, 1);
}
#[test]
fn render_produces_buffer() {
let mut runner = WasmRunner::new(Counter { value: 42 }, 80, 24);
runner.init();
let frame = runner.render().expect("should be dirty after init");
assert_eq!(frame.frame_idx, 0);
assert!(frame.diff.is_none());
assert_eq!(frame.buffer.get(0, 0).unwrap().content.as_char(), Some('C'));
}
#[test]
fn render_returns_none_when_clean() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
runner.init();
runner.render(); assert!(runner.render().is_none());
}
#[test]
fn second_render_has_diff() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
runner.init();
runner.render(); runner.step_event(key_event('+'));
let frame = runner.render().expect("dirty after event");
assert_eq!(frame.frame_idx, 1);
assert!(frame.diff.is_some());
}
#[test]
fn resize_invalidates_diff_baseline() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
runner.init();
runner.render();
runner.resize(100, 40);
assert!(runner.is_dirty());
assert_eq!(runner.size(), (100, 40));
let frame = runner.render().expect("dirty after resize");
assert!(frame.diff.is_none());
}
#[test]
fn tick_fires_when_due() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
runner.init();
runner.render();
runner.step_event(Event::Key(KeyEvent {
code: KeyCode::Char('t'),
modifiers: Modifiers::empty(),
kind: KeyEventKind::Press,
}));
runner.model_mut().value = 0;
let cmd: Cmd<CounterMsg> = Cmd::tick(Duration::from_millis(100));
let mut result = StepResult::default();
runner.execute_cmd(cmd, &mut result);
let r = runner.step(Duration::from_millis(50));
assert!(!r.tick_fired);
let r = runner.step(Duration::from_millis(100));
assert!(r.tick_fired);
}
#[test]
fn logs_accumulate() {
let mut runner = WasmRunner::new(Counter { value: 5 }, 80, 24);
runner.init();
runner.step_event(key_event('+'));
let cmd: Cmd<CounterMsg> = Cmd::log("hello");
let mut result = StepResult::default();
runner.execute_cmd(cmd, &mut result);
assert_eq!(runner.logs(), &["hello"]);
let drained = runner.drain_logs();
assert_eq!(drained, &["hello"]);
assert!(runner.logs().is_empty());
}
#[test]
fn log_modes_capture_policy_text_without_terminal_formatting() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
runner.init();
let payload = "a\x1b[31mb\x1b[2Jc\x1b]0;secret\x07d\n";
let mut result = StepResult::default();
runner.execute_cmd(
Cmd::sequence(vec![
Cmd::log(payload),
Cmd::log_sgr_only(payload),
Cmd::log_raw(payload),
Cmd::quit(),
Cmd::log("unreachable"),
]),
&mut result,
);
assert!(result.quit);
assert_eq!(runner.logs(), &["abcd\n", "a\x1b[31mbcd\n", payload]);
}
#[test]
fn deterministic_replay() {
fn run_scenario() -> Vec<Option<char>> {
let mut runner = WasmRunner::new(Counter { value: 0 }, 20, 1);
runner.init();
runner.push_event(key_event('+'));
runner.push_event(key_event('+'));
runner.push_event(key_event('-'));
runner.push_event(key_event('+'));
runner.step(Duration::ZERO);
let frame = runner.render().unwrap();
(0..20)
.map(|x| frame.buffer.get(x, 0).and_then(|c| c.content.as_char()))
.collect()
}
let r1 = run_scenario();
let r2 = run_scenario();
let r3 = run_scenario();
assert_eq!(r1, r2);
assert_eq!(r2, r3);
}
#[test]
fn events_after_quit_ignored() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
runner.init();
runner.step_event(key_event('q'));
assert!(!runner.is_running());
let r = runner.step_event(key_event('+'));
assert_eq!(r.events_processed, 0);
assert_eq!(runner.model().value, 0);
}
#[test]
fn step_before_init_is_noop() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
let r = runner.step(Duration::ZERO);
assert_eq!(r.events_processed, 0);
assert!(!runner.is_initialized());
}
#[test]
fn task_executes_synchronously() {
struct TaskModel {
result: Option<i32>,
}
#[derive(Debug)]
enum TaskMsg {
SpawnTask,
SetResult(i32),
}
impl From<Event> for TaskMsg {
fn from(_: Event) -> Self {
TaskMsg::SpawnTask
}
}
impl Model for TaskModel {
type Message = TaskMsg;
fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
match msg {
TaskMsg::SpawnTask => Cmd::task(|| TaskMsg::SetResult(42)),
TaskMsg::SetResult(v) => {
self.result = Some(v);
Cmd::none()
}
}
}
fn view(&self, _frame: &mut Frame) {}
}
let mut runner = WasmRunner::new(TaskModel { result: None }, 80, 24);
runner.init();
runner.step_event(key_event('x'));
assert_eq!(runner.model().result, Some(42));
}
#[test]
fn resize_delivers_event_to_model() {
struct SizeModel {
last_size: Option<(u16, u16)>,
}
#[derive(Debug)]
enum SizeMsg {
Resize(u16, u16),
Other,
}
impl From<Event> for SizeMsg {
fn from(event: Event) -> Self {
match event {
Event::Resize { width, height } => SizeMsg::Resize(width, height),
_ => SizeMsg::Other,
}
}
}
impl Model for SizeModel {
type Message = SizeMsg;
fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
if let SizeMsg::Resize(w, h) = msg {
self.last_size = Some((w, h));
}
Cmd::none()
}
fn view(&self, _frame: &mut Frame) {}
}
let mut runner = WasmRunner::new(SizeModel { last_size: None }, 80, 24);
runner.init();
runner.resize(120, 40);
assert_eq!(runner.model().last_size, Some((120, 40)));
}
#[test]
fn force_render_always_produces_frame() {
let mut runner = WasmRunner::new(Counter { value: 0 }, 80, 24);
runner.init();
runner.render(); assert!(!runner.is_dirty());
let frame = runner.force_render();
assert_eq!(frame.frame_idx, 1);
}
}