1#![forbid(unsafe_code)]
2
3use core::time::Duration;
51use std::sync::Arc;
52
53use ftui_a11y::tree::{
54 A11yTree, A11yTreeBuilder, ScreenReaderAnnouncement, ScreenReaderAnnouncements,
55 ScreenReaderMirror, ScreenReaderPolicy,
56};
57use ftui_backend::{BackendClock, BackendEventSource, BackendPresenter};
58use ftui_core::event::Event;
59use ftui_render::buffer::{Buffer, DoubleBuffer};
60use ftui_render::diff::BufferDiff;
61use ftui_render::frame::Frame;
62use ftui_render::grapheme_pool::GraphemePool;
63use ftui_runtime::program::{AccessibilityFrame, Cmd, Model};
64use ftui_runtime::state_persistence::StateRegistry;
65use ftui_runtime::tick_strategy::{TickDecision, TickStrategy};
66
67use crate::{WebBackend, WebBackendError, WebOutputs};
68
69const POOL_GC_INTERVAL_FRAMES: u64 = 256;
71const MIN_TERMINAL_DIMENSION: u16 = 1;
73
74#[inline]
75fn clamp_terminal_dimension(value: u16) -> u16 {
76 if value < MIN_TERMINAL_DIMENSION {
77 MIN_TERMINAL_DIMENSION
78 } else {
79 value
80 }
81}
82
83#[inline]
84fn clamp_terminal_size(width: u16, height: u16) -> (u16, u16) {
85 (
86 clamp_terminal_dimension(width),
87 clamp_terminal_dimension(height),
88 )
89}
90
91#[derive(Debug, Clone, Copy, PartialEq, Eq)]
93pub struct StepResult {
94 pub running: bool,
96 pub rendered: bool,
98 pub events_processed: u32,
100 pub events_pending: u32,
102 pub frame_idx: u64,
104}
105
106#[derive(Debug, Clone, Copy, PartialEq, Eq)]
107struct GeometryTransition {
108 from_cols: u16,
109 from_rows: u16,
110 to_cols: u16,
111 to_rows: u16,
112}
113
114pub struct StepProgram<M: Model> {
127 model: M,
128 backend: WebBackend,
129 pool: GraphemePool,
130 running: bool,
131 initialized: bool,
132 dirty: bool,
133 frame_idx: u64,
134 tick_rate: Option<Duration>,
135 last_tick: Duration,
136 tick_count: u64,
137 tick_strategy: Option<Box<dyn TickStrategy>>,
138 last_active_screen_for_strategy: Option<String>,
139 state_registry: Option<Arc<StateRegistry>>,
140 width: u16,
141 height: u16,
142 dbl_buf: Option<DoubleBuffer>,
144 pending_geometry_transition: Option<GeometryTransition>,
146 clipboard_requests: Vec<ftui_runtime::program::ClipboardRequest>,
147 accessibility: Option<ScreenReaderPolicy>,
149 a11y_tree: A11yTree,
150 a11y_order: Vec<u64>,
151 a11y_announcements: Vec<ScreenReaderAnnouncement>,
152 a11y_dropped: usize,
153}
154
155impl<M: Model> StepProgram<M> {
156 #[must_use]
158 pub fn new(model: M, width: u16, height: u16) -> Self {
159 let (width, height) = clamp_terminal_size(width, height);
160 Self {
161 model,
162 backend: WebBackend::new(width, height),
163 pool: GraphemePool::new(),
164 running: true,
165 initialized: false,
166 dirty: true,
167 frame_idx: 0,
168 tick_rate: None,
169 last_tick: Duration::ZERO,
170 tick_count: 0,
171 tick_strategy: None,
172 last_active_screen_for_strategy: None,
173 state_registry: None,
174 width,
175 height,
176 dbl_buf: None,
177 pending_geometry_transition: None,
178 clipboard_requests: Vec::new(),
179 accessibility: None,
180 a11y_tree: A11yTree::empty(),
181 a11y_order: Vec::new(),
182 a11y_announcements: Vec::new(),
183 a11y_dropped: 0,
184 }
185 }
186
187 #[must_use]
189 pub fn with_backend(model: M, mut backend: WebBackend) -> Self {
190 let (raw_width, raw_height) = backend.events_mut().size().unwrap_or((80, 24));
191 let (width, height) = clamp_terminal_size(raw_width, raw_height);
192 backend.events_mut().set_size(width, height);
193 Self {
194 model,
195 backend,
196 pool: GraphemePool::new(),
197 running: true,
198 initialized: false,
199 dirty: true,
200 frame_idx: 0,
201 tick_rate: None,
202 last_tick: Duration::ZERO,
203 tick_count: 0,
204 tick_strategy: None,
205 last_active_screen_for_strategy: None,
206 state_registry: None,
207 width,
208 height,
209 dbl_buf: None,
210 pending_geometry_transition: None,
211 clipboard_requests: Vec::new(),
212 accessibility: None,
213 a11y_tree: A11yTree::empty(),
214 a11y_order: Vec::new(),
215 a11y_announcements: Vec::new(),
216 a11y_dropped: 0,
217 }
218 }
219
220 #[must_use]
222 pub fn with_registry(mut self, registry: Arc<StateRegistry>) -> Self {
223 self.state_registry = Some(registry);
224 self
225 }
226
227 pub fn set_state_registry(&mut self, registry: Option<Arc<StateRegistry>>) {
229 self.state_registry = registry;
230 }
231
232 #[must_use]
234 pub fn state_registry(&self) -> Option<&Arc<StateRegistry>> {
235 self.state_registry.as_ref()
236 }
237
238 #[must_use]
240 pub fn with_tick_strategy(mut self, strategy: impl TickStrategy + 'static) -> Self {
241 self.tick_strategy = Some(Box::new(strategy));
242 self
243 }
244
245 #[must_use]
247 pub fn tick_strategy_name(&self) -> Option<&str> {
248 self.tick_strategy.as_ref().map(|s| s.name())
249 }
250
251 #[must_use]
256 pub fn with_accessibility(mut self, policy: ScreenReaderPolicy) -> Self {
257 self.set_accessibility_policy(Some(policy));
258 self
259 }
260
261 pub fn set_accessibility_policy(&mut self, policy: Option<ScreenReaderPolicy>) {
269 if self.accessibility == policy {
270 return;
271 }
272 self.accessibility = policy;
273 self.a11y_announcements.clear();
274 self.a11y_dropped = 0;
275 if policy.is_none() {
276 self.a11y_tree = A11yTree::empty();
277 self.a11y_order = Vec::new();
278 self.a11y_announcements = Vec::new();
279 }
280 self.dirty = true;
281 }
282
283 pub fn request_redraw(&mut self) {
292 self.dirty = true;
293 }
294
295 #[must_use]
297 pub fn accessibility_policy(&self) -> Option<ScreenReaderPolicy> {
298 self.accessibility
299 }
300
301 #[must_use]
303 pub fn accessibility_tree(&self) -> Option<&A11yTree> {
304 self.accessibility.map(|_| &self.a11y_tree)
305 }
306
307 #[must_use]
309 pub fn accessibility_order(&self) -> &[u64] {
310 &self.a11y_order
311 }
312
313 #[must_use]
319 pub fn accessibility_announcements(&self) -> &[ScreenReaderAnnouncement] {
320 &self.a11y_announcements
321 }
322
323 pub fn take_accessibility_announcements(&mut self) -> ScreenReaderAnnouncements {
332 ScreenReaderAnnouncements {
333 announcements: std::mem::take(&mut self.a11y_announcements),
334 dropped_count: std::mem::take(&mut self.a11y_dropped),
335 }
336 }
337
338 #[must_use]
344 pub fn accessibility_mirror(&self) -> Option<ScreenReaderMirror> {
345 self.accessibility
346 .map(|policy| self.a11y_tree.screen_reader_mirror(policy))
347 }
348
349 pub fn init(&mut self) -> Result<(), WebBackendError> {
355 assert!(!self.initialized, "StepProgram::init() called twice");
356 self.initialized = true;
357 let cmd = self.model.init();
358 self.execute_cmd(cmd);
359 if self.running {
360 self.check_screen_transition();
361 self.render_frame()?;
362 } else {
363 self.backend.events.set_size(self.width, self.height);
364 }
365 Ok(())
366 }
367
368 pub fn step(&mut self) -> Result<StepResult, WebBackendError> {
375 assert!(self.initialized, "StepProgram::step() called before init()");
376
377 if !self.running {
378 return Ok(StepResult {
379 running: false,
380 rendered: false,
381 events_processed: 0,
382 events_pending: self.pending_events(),
383 frame_idx: self.frame_idx,
384 });
385 }
386
387 let mut events_processed: u32 = 0;
389 while let Some(event) = self.backend.events.read_event()? {
390 events_processed += 1;
391 self.handle_event(event);
392 if !self.running {
393 break;
394 }
395 }
396
397 if self.running
399 && let Some(rate) = self.tick_rate
400 {
401 let now = self.backend.clock.now_mono();
402 let delta = now.saturating_sub(self.last_tick);
403 let should_tick = if rate.is_zero() { true } else { delta >= rate };
404 if should_tick {
405 if rate.is_zero() {
408 self.last_tick = now;
409 } else {
410 let rem_ns = delta.as_nanos() % rate.as_nanos();
411 let rem = Duration::from_nanos(rem_ns as u64);
412 self.last_tick = now.saturating_sub(rem);
413 }
414 self.tick_count = self.tick_count.wrapping_add(1);
415 let tick_count = self.tick_count;
416 let mut used_screen_dispatch = false;
417
418 if let Some(strategy) = self.tick_strategy.as_mut() {
421 let dispatch_snapshot = self.model.as_screen_tick_dispatch().map(|dispatch| {
422 let active = dispatch.active_screen_id();
423 let all_screens = dispatch.screen_ids();
424 (active, all_screens)
425 });
426
427 if let Some((active, all_screens)) = dispatch_snapshot {
428 used_screen_dispatch = true;
429 if let Some(previous_active) =
430 self.last_active_screen_for_strategy.as_deref()
431 && previous_active != active
432 {
433 strategy.on_screen_transition(previous_active, &active);
434 }
435 self.last_active_screen_for_strategy = Some(active.clone());
436
437 let mut tick_targets = Vec::with_capacity(all_screens.len().max(1));
438 tick_targets.push(active.clone());
439 for screen_id in all_screens {
440 if screen_id != active
441 && strategy.should_tick(&screen_id, tick_count, &active)
442 == TickDecision::Tick
443 {
444 tick_targets.push(screen_id);
445 }
446 }
447
448 if let Some(dispatch) = self.model.as_screen_tick_dispatch() {
449 for screen_id in &tick_targets {
450 dispatch.tick_screen(screen_id, tick_count);
451 }
452 }
453 strategy.maintenance_tick(tick_count);
454 self.dirty = true;
455 }
456 }
457
458 if !used_screen_dispatch {
459 self.last_active_screen_for_strategy = None;
460 let msg = M::Message::from(Event::Tick);
461 let cmd = self.model.update(msg);
462 self.dirty = true;
463 self.execute_cmd(cmd);
464 }
465 }
466 }
467
468 let rendered = if self.running && self.dirty {
470 self.render_frame()?;
471 true
472 } else {
473 false
474 };
475
476 if !self.running {
477 self.backend.events.set_size(self.width, self.height);
479 }
480
481 Ok(StepResult {
482 running: self.running,
483 rendered,
484 events_processed,
485 events_pending: self.pending_events(),
486 frame_idx: self.frame_idx,
487 })
488 }
489
490 pub fn push_event(&mut self, event: Event) -> Result<(), WebBackendError> {
496 if !self.running {
497 return Err(WebBackendError::Unsupported("program has stopped"));
498 }
499 let event = match event {
500 Event::Resize { width, height } => {
501 let (width, height) = clamp_terminal_size(width, height);
502 Event::Resize { width, height }
503 }
504 other => other,
505 };
506 let resize = match &event {
507 Event::Resize { width, height } => Some((*width, *height)),
508 _ => None,
509 };
510 self.backend.events_mut().push_event(event)?;
511 if let Some((width, height)) = resize {
514 self.backend.events_mut().set_size(width, height);
515 }
516 Ok(())
517 }
518
519 pub fn advance_time(&mut self, dt: Duration) {
521 self.backend.clock_mut().advance(dt);
522 }
523
524 pub fn set_time(&mut self, now: Duration) {
526 self.backend.clock_mut().set(now);
527 }
528
529 pub fn resize(&mut self, width: u16, height: u16) -> Result<(), WebBackendError> {
534 self.push_event(Event::Resize { width, height })
535 }
536
537 #[must_use]
539 pub fn pending_events(&self) -> u32 {
540 self.backend.events.queued_events() as u32
541 }
542
543 pub fn take_pending_events(&mut self) -> Vec<Event> {
549 let events = self.backend.events.drain_events().collect();
550 self.backend.events.set_size(self.width, self.height);
551 events
552 }
553
554 #[must_use]
556 pub fn time(&self) -> Duration {
557 self.backend.clock.now_mono()
558 }
559
560 pub fn take_outputs(&mut self) -> WebOutputs {
562 self.backend.presenter_mut().take_outputs()
563 }
564
565 pub fn take_clipboard_requests(&mut self) -> Vec<ftui_runtime::program::ClipboardRequest> {
568 std::mem::take(&mut self.clipboard_requests)
569 }
570
571 pub fn outputs(&self) -> &WebOutputs {
573 self.backend.presenter.outputs()
574 }
575
576 pub fn model(&self) -> &M {
578 &self.model
579 }
580
581 pub fn model_mut(&mut self) -> &mut M {
583 &mut self.model
584 }
585
586 pub fn backend(&self) -> &WebBackend {
588 &self.backend
589 }
590
591 pub fn backend_mut(&mut self) -> &mut WebBackend {
593 &mut self.backend
594 }
595
596 pub fn is_running(&self) -> bool {
598 self.running
599 }
600
601 pub fn is_initialized(&self) -> bool {
603 self.initialized
604 }
605
606 pub fn frame_idx(&self) -> u64 {
608 self.frame_idx
609 }
610
611 pub fn size(&self) -> (u16, u16) {
613 (self.width, self.height)
614 }
615
616 pub fn tick_rate(&self) -> Option<Duration> {
618 self.tick_rate
619 }
620
621 pub fn pool(&self) -> &GraphemePool {
623 &self.pool
624 }
625
626 fn check_screen_transition(&mut self) {
629 if self.tick_strategy.is_none() || !self.running {
630 return;
631 }
632 let current_active = match self.model.as_screen_tick_dispatch() {
633 Some(dispatch) => dispatch.active_screen_id(),
634 None => return,
635 };
636 let previous = match self.last_active_screen_for_strategy.take() {
637 Some(prev) => prev,
638 None => {
639 self.last_active_screen_for_strategy = Some(current_active);
640 return;
641 }
642 };
643 if previous == current_active {
644 self.last_active_screen_for_strategy = Some(current_active);
645 return;
646 }
647 if let Some(strategy) = self.tick_strategy.as_mut() {
648 strategy.on_screen_transition(&previous, ¤t_active);
649 }
650 if let Some(dispatch) = self.model.as_screen_tick_dispatch() {
651 dispatch.tick_screen(¤t_active, self.tick_count);
652 self.dirty = true;
653 }
654 self.last_active_screen_for_strategy = Some(current_active);
655 }
656
657 fn handle_event(&mut self, event: Event) {
658 if let Event::Resize { width, height } = &event {
659 let (prev_width, prev_height) = (self.width, self.height);
660 self.width = *width;
661 self.height = *height;
662 self.dbl_buf = None;
666 self.pending_geometry_transition = Some(GeometryTransition {
667 from_cols: prev_width,
668 from_rows: prev_height,
669 to_cols: *width,
670 to_rows: *height,
671 });
672 }
673 let msg = M::Message::from(event);
674 let cmd = self.model.update(msg);
675 self.dirty = true;
676 self.execute_cmd(cmd);
677 if self.running {
678 self.check_screen_transition();
679 }
680 }
681
682 fn render_frame(&mut self) -> Result<(), WebBackendError> {
683 let full_repaint = self.dbl_buf.is_none();
685 let geometry_transition = if full_repaint {
686 self.pending_geometry_transition.take()
687 } else {
688 None
689 };
690 if self.dbl_buf.is_none() {
691 self.dbl_buf = Some(DoubleBuffer::new(self.width, self.height));
692 }
693
694 {
696 let dbl = self.dbl_buf.as_mut().unwrap();
697 dbl.swap();
698 dbl.current_mut().clear();
699 }
700
701 let render_buf = std::mem::replace(
704 self.dbl_buf.as_mut().unwrap().current_mut(),
705 Buffer::new(1, 1),
706 );
707 let mut a11y_builder = self.accessibility.map(|_| A11yTreeBuilder::new());
708 let (rendered_buffer, a11y_order) = {
709 let mut frame = Frame::from_buffer(render_buf, &mut self.pool);
710 if let Some(builder) = a11y_builder.as_mut() {
711 frame.set_a11y(builder);
712 }
713 self.model.view(&mut frame);
714 frame.finish_a11y();
715 let order = frame.take_a11y_order();
716 (frame.buffer, order)
717 };
718 let a11y_tree = a11y_builder.map(A11yTreeBuilder::build);
719
720 *self.dbl_buf.as_mut().unwrap().current_mut() = rendered_buffer;
722
723 let dbl = self.dbl_buf.as_ref().unwrap();
725 let diff = if full_repaint {
726 None
727 } else {
728 Some(BufferDiff::compute(dbl.previous(), dbl.current()))
729 };
730 let buf = dbl.current().clone();
731
732 self.backend
733 .presenter_mut()
734 .present_ui_owned(buf, diff.as_ref(), full_repaint);
735
736 if let Some(transition) = geometry_transition {
737 self.emit_geometry_transition_markers(transition);
738 }
739
740 self.dirty = false;
741 let rendered_frame_idx = self.frame_idx;
742 self.frame_idx += 1;
743
744 if self.frame_idx.is_multiple_of(POOL_GC_INTERVAL_FRAMES) {
747 let Self { dbl_buf, pool, .. } = self;
748 let dbl = dbl_buf.as_ref().unwrap();
749 pool.gc(&[dbl.current(), dbl.previous()]);
750 }
751
752 if let (Some(tree), Some(policy)) = (a11y_tree, self.accessibility) {
753 let diff = tree.diff(&self.a11y_tree);
754 let changed = !diff.is_empty();
755 let batch = diff.screen_reader_announcements(&tree, policy);
756 self.a11y_tree = tree;
757 self.a11y_order = a11y_order;
758 self.a11y_announcements = batch.announcements;
759 self.a11y_dropped = batch.dropped_count;
760 if changed {
761 self.dirty = true;
765 let cmd = self.model.on_accessibility(AccessibilityFrame {
766 frame_idx: rendered_frame_idx,
767 tree: &self.a11y_tree,
768 order: &self.a11y_order,
769 announcements: &self.a11y_announcements,
770 dropped: self.a11y_dropped,
771 });
772 self.execute_cmd(cmd);
773 }
774 }
775 Ok(())
776 }
777
778 fn emit_geometry_transition_markers(&mut self, transition: GeometryTransition) {
779 let reset_marker = format!(
780 r#"{{"event":"diff_baseline_reset","reason":"geometry_transition","from_cols":{},"from_rows":{},"to_cols":{},"to_rows":{},"frame_idx":{}}}"#,
781 transition.from_cols,
782 transition.from_rows,
783 transition.to_cols,
784 transition.to_rows,
785 self.frame_idx
786 );
787 let repaint_marker = format!(
788 r#"{{"event":"full_repaint_boundary","reason":"geometry_transition","from_cols":{},"from_rows":{},"to_cols":{},"to_rows":{},"frame_idx":{},"full_repaint":true}}"#,
789 transition.from_cols,
790 transition.from_rows,
791 transition.to_cols,
792 transition.to_rows,
793 self.frame_idx
794 );
795 let presenter = self.backend.presenter_mut();
796 let _ = presenter.write_log(&reset_marker);
797 let _ = presenter.write_log(&repaint_marker);
798 }
799
800 fn execute_cmd(&mut self, cmd: Cmd<M::Message>) {
805 let mut batches: Vec<std::vec::IntoIter<Cmd<M::Message>>> = Vec::new();
806 let mut next = Some(cmd);
807 loop {
808 let cmd = match next.take() {
809 Some(cmd) => cmd,
810 None => {
811 let Some(rest) = batches.last_mut() else {
814 return;
815 };
816 if !self.running {
817 return;
818 }
819 match rest.next() {
820 Some(cmd) => cmd,
821 None => {
822 batches.pop();
823 continue;
824 }
825 }
826 }
827 };
828 next = self.execute_one_cmd(cmd, &mut batches);
829 }
830 }
831
832 fn execute_one_cmd(
835 &mut self,
836 cmd: Cmd<M::Message>,
837 batches: &mut Vec<std::vec::IntoIter<Cmd<M::Message>>>,
838 ) -> Option<Cmd<M::Message>> {
839 match cmd {
840 Cmd::None => {}
841 Cmd::Quit => {
842 self.running = false;
843 if let Some(ref mut strategy) = self.tick_strategy {
844 strategy.shutdown();
845 }
846 }
847 Cmd::Msg(m) => {
848 return Some(self.model.update(m));
849 }
850 Cmd::Batch(cmds) | Cmd::Sequence(cmds) => {
851 let mut rest = cmds.into_iter();
852 let first = rest.next();
853 batches.push(rest);
854 return first;
855 }
856 Cmd::Tick(duration) => {
857 self.tick_rate = Some(duration);
858 }
859 Cmd::Log { text, mode } => {
860 let text = ftui_render::sanitize::sanitize_with(&text, mode);
861 let _ = self.backend.presenter_mut().write_log(&text);
862 }
863 Cmd::Task(_spec, f) => {
864 let msg = f();
866 return Some(self.model.update(msg));
867 }
868 Cmd::SetMouseCapture(enabled) => {
869 let mut features = self.backend.events_mut().features();
870 features.mouse_capture = enabled;
871 let _ = self.backend.events_mut().set_features(features);
872 }
873 Cmd::SetClipboard(text) => self
874 .clipboard_requests
875 .push(ftui_runtime::program::ClipboardRequest::Set(text)),
876 Cmd::GetClipboard => self
877 .clipboard_requests
878 .push(ftui_runtime::program::ClipboardRequest::Get),
879 Cmd::SaveState => {
880 if let Some(ref registry) = self.state_registry
881 && let Err(error) = registry.flush()
882 {
883 let msg = format!("state save failed: {error}");
884 let _ = self.backend.presenter_mut().write_log(&msg);
885 return Some(self.model.on_error(&msg));
886 }
887 }
888 Cmd::RestoreState => {
889 if let Some(ref registry) = self.state_registry {
890 match registry.load() {
891 Ok(_) => {
892 self.dirty = true;
893 }
894 Err(error) => {
895 let msg = format!("state restore failed: {error}");
896 let _ = self.backend.presenter_mut().write_log(&msg);
897 return Some(self.model.on_error(&msg));
898 }
899 }
900 }
901 }
902 Cmd::SetTickStrategy(strategy) => {
903 if let Some(ref mut prev) = self.tick_strategy {
904 prev.shutdown();
905 }
906 self.tick_strategy = Some(strategy);
907 self.last_active_screen_for_strategy = None;
908 }
909 }
910 None
911 }
912}
913
914#[cfg(test)]
915mod tests {
916 use super::*;
917 use ftui_core::event::{KeyCode, KeyEvent, KeyEventKind, Modifiers};
918 use ftui_render::cell::Cell;
919 use ftui_render::drawing::Draw;
920 use pretty_assertions::assert_eq;
921
922 #[test]
925 fn clipboard_requests_are_drained_for_host_delivery() {
926 use ftui_runtime::program::ClipboardRequest;
927 let mut program = StepProgram::new(new_counter(0), 10, 5);
928 program.init().unwrap();
929 program.execute_cmd(Cmd::sequence(vec![
930 Cmd::set_clipboard("界"),
931 Cmd::get_clipboard(),
932 ]));
933 assert_eq!(
934 program.take_clipboard_requests(),
935 [ClipboardRequest::Set("界".into()), ClipboardRequest::Get]
936 );
937 assert!(program.take_clipboard_requests().is_empty());
938 assert_eq!(program.model.value, 0);
939 }
940
941 #[test]
942 fn long_msg_and_task_chains_run_without_recursion() {
943 struct Walker {
946 steps: u32,
947 }
948
949 enum WalkMsg {
950 Step(u32),
951 Event,
952 }
953
954 impl From<Event> for WalkMsg {
955 fn from(_: Event) -> Self {
956 WalkMsg::Event
957 }
958 }
959
960 impl Model for Walker {
961 type Message = WalkMsg;
962
963 fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
964 match msg {
965 WalkMsg::Step(0) | WalkMsg::Event => Cmd::none(),
966 WalkMsg::Step(n) if n % 2 == 0 => {
967 self.steps += 1;
968 Cmd::msg(WalkMsg::Step(n - 1))
969 }
970 WalkMsg::Step(n) => {
971 self.steps += 1;
972 Cmd::task(move || WalkMsg::Step(n - 1))
973 }
974 }
975 }
976
977 fn view(&self, _frame: &mut Frame) {}
978 }
979
980 let mut program = StepProgram::new(Walker { steps: 0 }, 10, 5);
981 program.init().unwrap();
982 program.execute_cmd(Cmd::msg(WalkMsg::Step(200_000)));
983 assert_eq!(program.model.steps, 200_000);
984 }
985
986 #[test]
992 fn the_simulator_and_the_step_program_run_a_command_tree_the_same_way() {
993 use ftui_runtime::ProgramSimulator;
994 use std::cell::RefCell;
995 use std::rc::Rc;
996
997 #[derive(Clone, Debug)]
1000 enum Plan {
1001 None,
1002 Msg(u32),
1003 Quit,
1004 Log(String),
1005 Batch(Vec<Plan>),
1006 Sequence(Vec<Plan>),
1007 }
1008
1009 fn build(plan: &Plan) -> Cmd<Step> {
1010 match plan {
1011 Plan::None => Cmd::none(),
1012 Plan::Msg(n) => Cmd::msg(Step::Seen(*n)),
1013 Plan::Quit => Cmd::quit(),
1014 Plan::Log(text) => Cmd::log(text.clone()),
1015 Plan::Batch(children) => Cmd::batch(children.iter().map(build).collect::<Vec<_>>()),
1016 Plan::Sequence(children) => {
1017 Cmd::sequence(children.iter().map(build).collect::<Vec<_>>())
1018 }
1019 }
1020 }
1021
1022 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
1023 enum Step {
1024 Seen(u32),
1025 Ignored,
1026 }
1027 impl From<Event> for Step {
1028 fn from(_: Event) -> Self {
1029 Step::Ignored
1030 }
1031 }
1032
1033 struct Recorder {
1034 plan: Plan,
1035 seen: Rc<RefCell<Vec<u32>>>,
1036 }
1037 impl Model for Recorder {
1038 type Message = Step;
1039 fn init(&mut self) -> Cmd<Step> {
1040 build(&self.plan)
1041 }
1042 fn update(&mut self, msg: Step) -> Cmd<Step> {
1043 if let Step::Seen(n) = msg {
1044 self.seen.borrow_mut().push(n);
1045 }
1046 Cmd::none()
1047 }
1048 fn view(&self, _frame: &mut Frame) {}
1049 }
1050
1051 let mut state = 0x2545_F491_4F6C_DD1Du64;
1053 let mut next = move || {
1054 state ^= state << 13;
1055 state ^= state >> 7;
1056 state ^= state << 17;
1057 state
1058 };
1059 let plan = |depth: u32, id: &mut u32, rng: &mut dyn FnMut() -> u64| -> Plan {
1060 fn go(depth: u32, id: &mut u32, rng: &mut dyn FnMut() -> u64) -> Plan {
1061 match rng() % if depth == 0 { 4 } else { 6 } {
1062 0 => Plan::None,
1063 1 | 2 => {
1064 *id += 1;
1065 Plan::Msg(*id)
1066 }
1067 3 => {
1068 if rng().is_multiple_of(6) {
1069 Plan::Quit
1070 } else {
1071 Plan::Log(format!("log{}", rng() % 100))
1072 }
1073 }
1074 4 => Plan::Batch((0..rng() % 4).map(|_| go(depth - 1, id, rng)).collect()),
1075 _ => Plan::Sequence((0..rng() % 4).map(|_| go(depth - 1, id, rng)).collect()),
1076 }
1077 }
1078 go(depth, id, rng)
1079 };
1080
1081 let (mut with_messages, mut that_quit) = (0u32, 0u32);
1082 for trial in 0..2_000 {
1083 let mut id = 0;
1084 let tree = plan(3, &mut id, &mut next);
1085
1086 let simulator_seen = Rc::new(RefCell::new(Vec::new()));
1087 let mut simulator = ProgramSimulator::new(Recorder {
1088 plan: tree.clone(),
1089 seen: Rc::clone(&simulator_seen),
1090 });
1091 simulator.init();
1092
1093 let step_seen = Rc::new(RefCell::new(Vec::new()));
1094 let mut program = StepProgram::new(
1095 Recorder {
1096 plan: tree.clone(),
1097 seen: Rc::clone(&step_seen),
1098 },
1099 80,
1100 24,
1101 );
1102 program.init().expect("init the step program");
1103
1104 let (from_simulator, from_step) =
1105 (simulator_seen.borrow().clone(), step_seen.borrow().clone());
1106 if !from_simulator.is_empty() {
1107 with_messages += 1;
1108 }
1109 if !simulator.is_running() {
1110 that_quit += 1;
1111 }
1112 assert_eq!(
1113 from_simulator, from_step,
1114 "trial {trial}: the two runtimes delivered different messages for {tree:?}"
1115 );
1116 assert_eq!(
1117 simulator.is_running(),
1118 program.is_running(),
1119 "trial {trial}: the two runtimes disagreed about quitting for {tree:?}"
1120 );
1121 }
1122
1123 assert!(
1125 with_messages > 500 && that_quit > 50,
1126 "the trees were too dull to compare: {with_messages} delivered a message \
1127 and {that_quit} quit"
1128 );
1129 }
1130
1131 struct Counter {
1132 value: i32,
1133 initialized: bool,
1134 }
1135
1136 #[derive(Debug)]
1137 enum CounterMsg {
1138 Increment,
1139 Decrement,
1140 Reset,
1141 Quit,
1142 LogValue,
1143 BatchIncrement(usize),
1144 SpawnTask,
1145 }
1146
1147 impl From<Event> for CounterMsg {
1148 fn from(event: Event) -> Self {
1149 match event {
1150 Event::Key(k) if k.code == KeyCode::Char('+') => CounterMsg::Increment,
1151 Event::Key(k) if k.code == KeyCode::Char('-') => CounterMsg::Decrement,
1152 Event::Key(k) if k.code == KeyCode::Char('r') => CounterMsg::Reset,
1153 Event::Key(k) if k.code == KeyCode::Char('q') => CounterMsg::Quit,
1154 Event::Tick => CounterMsg::Increment,
1155 _ => CounterMsg::Increment,
1156 }
1157 }
1158 }
1159
1160 impl Model for Counter {
1161 type Message = CounterMsg;
1162
1163 fn init(&mut self) -> Cmd<Self::Message> {
1164 self.initialized = true;
1165 Cmd::none()
1166 }
1167
1168 fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
1169 match msg {
1170 CounterMsg::Increment => {
1171 self.value += 1;
1172 Cmd::none()
1173 }
1174 CounterMsg::Decrement => {
1175 self.value -= 1;
1176 Cmd::none()
1177 }
1178 CounterMsg::Reset => {
1179 self.value = 0;
1180 Cmd::none()
1181 }
1182 CounterMsg::Quit => Cmd::quit(),
1183 CounterMsg::LogValue => Cmd::log(format!("value={}", self.value)),
1184 CounterMsg::BatchIncrement(n) => {
1185 let cmds: Vec<_> = (0..n).map(|_| Cmd::msg(CounterMsg::Increment)).collect();
1186 Cmd::batch(cmds)
1187 }
1188 CounterMsg::SpawnTask => Cmd::task(|| CounterMsg::Increment),
1189 }
1190 }
1191
1192 fn view(&self, frame: &mut Frame) {
1193 let text = format!("Count: {}", self.value);
1194 for (i, c) in text.chars().enumerate() {
1195 if (i as u16) < frame.width() {
1196 frame.buffer.set_raw(i as u16, 0, Cell::from_char(c));
1197 }
1198 }
1199 }
1200 }
1201
1202 struct GraphemeChurn {
1206 value: u32,
1207 }
1208
1209 impl Model for GraphemeChurn {
1210 type Message = CounterMsg;
1211
1212 fn init(&mut self) -> Cmd<Self::Message> {
1213 Cmd::none()
1214 }
1215
1216 fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
1217 if let CounterMsg::Increment = msg {
1218 self.value = self.value.wrapping_add(1);
1219 }
1220 Cmd::none()
1221 }
1222
1223 fn view(&self, frame: &mut Frame) {
1224 let base = char::from_u32(0x4e00 + (self.value % 2048)).unwrap_or('字');
1225 let text = format!("{base}\u{0301}");
1226 frame.print_text(0, 0, &text, Cell::default());
1227 }
1228 }
1229
1230 fn key_event(c: char) -> Event {
1231 Event::Key(KeyEvent {
1232 code: KeyCode::Char(c),
1233 modifiers: Modifiers::empty(),
1234 kind: KeyEventKind::Press,
1235 })
1236 }
1237
1238 fn new_counter(value: i32) -> Counter {
1239 Counter {
1240 value,
1241 initialized: false,
1242 }
1243 }
1244
1245 fn new_grapheme_churn() -> GraphemeChurn {
1246 GraphemeChurn { value: 0 }
1247 }
1248
1249 #[test]
1252 fn new_creates_uninitialized_program() {
1253 let prog = StepProgram::new(new_counter(0), 80, 24);
1254 assert!(!prog.is_initialized());
1255 assert!(prog.is_running());
1256 assert_eq!(prog.size(), (80, 24));
1257 assert_eq!(prog.frame_idx(), 0);
1258 assert!(prog.tick_rate().is_none());
1259 }
1260
1261 #[test]
1262 fn new_clamps_zero_dimensions_to_minimum() {
1263 let prog = StepProgram::new(new_counter(0), 0, 0);
1264 assert_eq!(prog.size(), (1, 1));
1265 }
1266
1267 #[test]
1268 fn with_backend_clamps_zero_dimensions_to_minimum() {
1269 let backend = WebBackend::new(0, 0);
1270 let prog = StepProgram::with_backend(new_counter(0), backend);
1271 assert_eq!(prog.size(), (1, 1));
1272 }
1273
1274 #[test]
1275 fn init_initializes_model_and_renders_first_frame() {
1276 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1277 prog.init().unwrap();
1278
1279 assert!(prog.is_initialized());
1280 assert!(prog.model().initialized);
1281 assert_eq!(prog.frame_idx(), 1); let outputs = prog.outputs();
1284 assert!(outputs.last_buffer.is_some());
1285 assert!(outputs.last_full_repaint_hint); assert_eq!(outputs.last_patches.len(), 1);
1287 let stats = outputs
1288 .last_patch_stats
1289 .expect("patch stats should be captured");
1290 assert_eq!(stats.patch_count, 1);
1291 assert_eq!(stats.dirty_cells, 80 * 24);
1292 }
1293
1294 #[test]
1295 #[should_panic(expected = "init() called twice")]
1296 fn double_init_panics() {
1297 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1298 prog.init().unwrap();
1299 prog.init().unwrap();
1300 }
1301
1302 #[test]
1303 #[should_panic(expected = "step() called before init()")]
1304 fn step_before_init_panics() {
1305 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1306 let _ = prog.step();
1307 }
1308
1309 #[test]
1312 fn step_processes_pushed_events() {
1313 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1314 prog.init().unwrap();
1315
1316 prog.push_event(key_event('+')).expect("key admission");
1317 prog.push_event(key_event('+')).expect("key admission");
1318 prog.push_event(key_event('+')).expect("key admission");
1319 let result = prog.step().unwrap();
1320
1321 assert!(result.running);
1322 assert!(result.rendered);
1323 assert_eq!(result.events_processed, 3);
1324 assert_eq!(prog.model().value, 3);
1325 }
1326
1327 #[test]
1328 fn step_with_no_events_does_not_render() {
1329 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1330 prog.init().unwrap();
1331
1332 prog.take_outputs();
1334
1335 let result = prog.step().unwrap();
1336 assert!(result.running);
1337 assert!(!result.rendered);
1338 assert_eq!(result.events_processed, 0);
1339 }
1340
1341 #[test]
1342 fn quit_event_stops_program() {
1343 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1344 prog.init().unwrap();
1345
1346 prog.push_event(key_event('+')).expect("key admission");
1347 prog.push_event(key_event('q')).expect("quit admission");
1348 prog.push_event(key_event('+')).expect("key admission"); let paste = Event::Paste(ftui_core::event::PasteEvent::bracketed("尾巴 🦀"));
1350 prog.push_event(paste.clone()).unwrap();
1351 prog.resize(120, 40).unwrap();
1352 let result = prog.step().unwrap();
1353
1354 assert!(!result.running);
1355 assert!(!result.rendered);
1356 assert_eq!(result.events_processed, 2);
1357 assert_eq!(result.events_pending, 3);
1358 assert!(!prog.is_running());
1359 assert_eq!(prog.model().value, 1); assert_eq!(prog.size(), (80, 24));
1361 assert_eq!(prog.backend.events_mut().size().unwrap(), (80, 24));
1362 assert_eq!(prog.step().unwrap().events_pending, 3);
1363 assert_eq!(
1364 prog.take_pending_events(),
1365 vec![
1366 key_event('+'),
1367 paste,
1368 Event::Resize {
1369 width: 120,
1370 height: 40
1371 }
1372 ]
1373 );
1374 assert_eq!(prog.pending_events(), 0);
1375 assert_eq!(prog.backend.events.queued_payload_bytes(), 0);
1376 assert!(prog.take_pending_events().is_empty());
1377 assert_eq!(prog.model().value, 1);
1378 }
1379
1380 #[test]
1381 fn step_after_quit_returns_immediately() {
1382 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1383 prog.init().unwrap();
1384
1385 prog.push_event(key_event('q')).expect("quit admission");
1386 prog.step().unwrap();
1387
1388 assert_eq!(
1390 prog.push_event(key_event('+')),
1391 Err(WebBackendError::Unsupported("program has stopped"))
1392 );
1393 assert_eq!(
1394 prog.resize(120, 40),
1395 Err(WebBackendError::Unsupported("program has stopped"))
1396 );
1397 assert_eq!(prog.size(), (80, 24));
1398 let result = prog.step().unwrap();
1399 assert!(!result.running);
1400 assert!(!result.rendered);
1401 assert_eq!(result.events_processed, 0);
1402 assert_eq!(prog.model().value, 0);
1403 }
1404
1405 #[test]
1408 fn rejected_resize_preserves_geometry_and_accepted_input_until_recovery() {
1409 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1410 prog.init().unwrap();
1411 for _ in 0..crate::WebEventSource::MAX_EVENTS {
1412 prog.push_event(key_event('+')).unwrap();
1413 }
1414 assert!(matches!(
1415 prog.resize(120, 40),
1416 Err(WebBackendError::InputQueueFull {
1417 limit: crate::WebInputLimit::Events,
1418 event: Event::Resize {
1419 width: 120,
1420 height: 40
1421 },
1422 })
1423 ));
1424 assert_eq!(prog.backend.events_mut().size().unwrap(), (80, 24));
1425 assert_eq!(prog.size(), (80, 24));
1426 let result = prog.step().unwrap();
1427 assert_eq!(
1428 result.events_processed as usize,
1429 crate::WebEventSource::MAX_EVENTS
1430 );
1431 assert_eq!(
1432 prog.model().value as usize,
1433 crate::WebEventSource::MAX_EVENTS
1434 );
1435 assert_eq!(prog.size(), (80, 24));
1436 prog.resize(120, 40).unwrap();
1437 assert_eq!(prog.step().unwrap().events_processed, 1);
1438 assert_eq!(prog.size(), (120, 40));
1439 assert_eq!(prog.backend.events_mut().size().unwrap(), (120, 40));
1440 }
1441
1442 #[test]
1443 fn resize_updates_dimensions() {
1444 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1445 prog.init().unwrap();
1446
1447 prog.resize(120, 40).expect("resize admission");
1448 prog.step().unwrap();
1449
1450 assert_eq!(prog.size(), (120, 40));
1451 }
1452
1453 #[test]
1454 fn resize_clamps_zero_dimensions_to_minimum() {
1455 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1456 prog.init().unwrap();
1457
1458 prog.resize(0, 0).expect("resize admission");
1459 prog.step().unwrap();
1460
1461 assert_eq!(prog.size(), (1, 1));
1462 let outputs = prog.outputs();
1463 let buf = outputs.last_buffer.as_ref().expect("resize should render");
1464 assert_eq!(buf.width(), 1);
1465 assert_eq!(buf.height(), 1);
1466 }
1467
1468 #[test]
1469 fn resize_produces_correctly_sized_buffer() {
1470 let mut prog = StepProgram::new(new_counter(42), 80, 24);
1471 prog.init().unwrap();
1472
1473 prog.resize(40, 10).expect("resize admission");
1474 prog.step().unwrap();
1475
1476 let outputs = prog.outputs();
1477 let buf = outputs.last_buffer.as_ref().unwrap();
1478 assert_eq!(buf.width(), 40);
1479 assert_eq!(buf.height(), 10);
1480 }
1481
1482 #[test]
1483 fn resize_emits_baseline_reset_and_full_repaint_markers() {
1484 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1485 prog.init().unwrap();
1486 let _ = prog.take_outputs(); prog.resize(120, 40).expect("resize admission");
1489 prog.step().unwrap();
1490
1491 let outputs = prog.outputs();
1492 assert!(
1493 outputs
1494 .logs
1495 .iter()
1496 .any(|line| line.contains(r#""event":"diff_baseline_reset""#))
1497 );
1498 assert!(
1499 outputs
1500 .logs
1501 .iter()
1502 .any(|line| line.contains(r#""event":"full_repaint_boundary""#))
1503 );
1504 assert!(
1505 outputs
1506 .logs
1507 .iter()
1508 .any(|line| line.contains(r#""from_cols":80"#) && line.contains(r#""to_cols":120"#))
1509 );
1510 }
1511
1512 #[test]
1513 fn same_size_resize_still_forces_repaint_boundary() {
1514 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1515 prog.init().unwrap();
1516 let _ = prog.take_outputs(); prog.resize(80, 24).expect("resize admission");
1519 prog.step().unwrap();
1520
1521 let outputs = prog.take_outputs();
1522 assert!(outputs.last_full_repaint_hint);
1523 assert_eq!(outputs.last_patches.len(), 1);
1524 assert_eq!(outputs.last_patches[0].offset, 0);
1525 assert_eq!(outputs.last_patches[0].cells.len(), 80usize * 24usize);
1526 assert!(outputs.logs.iter().any(|line| {
1527 line.contains(r#""event":"diff_baseline_reset""#)
1528 && line.contains(r#""from_cols":80"#)
1529 && line.contains(r#""to_cols":80"#)
1530 }));
1531 assert!(outputs.logs.iter().any(|line| {
1532 line.contains(r#""event":"full_repaint_boundary""#)
1533 && line.contains(r#""from_rows":24"#)
1534 && line.contains(r#""to_rows":24"#)
1535 }));
1536 }
1537
1538 #[test]
1539 fn resize_oscillation_forces_full_repaint_without_stale_patch_offsets() {
1540 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1541 prog.init().unwrap();
1542 let _ = prog.take_outputs();
1543
1544 for (w, h) in [(120, 40), (80, 24), (120, 40), (80, 24)] {
1545 prog.resize(w, h).expect("resize admission");
1546 prog.step().unwrap();
1547
1548 let outputs = prog.take_outputs();
1549 assert!(outputs.last_full_repaint_hint);
1550
1551 let buf = outputs
1552 .last_buffer
1553 .expect("resize render should produce a buffer");
1554 assert_eq!(buf.width(), w);
1555 assert_eq!(buf.height(), h);
1556
1557 let max_cells = usize::from(w) * usize::from(h);
1558 assert_eq!(outputs.last_patches.len(), 1);
1559 let run = &outputs.last_patches[0];
1560 assert_eq!(run.offset, 0);
1561 assert_eq!(run.cells.len(), max_cells);
1562 assert!(run.offset as usize + run.cells.len() <= max_cells);
1563 }
1564 }
1565
1566 #[test]
1567 fn resize_boundary_full_repaint_then_incremental_diff_resume() {
1568 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1569 prog.init().unwrap();
1570 let _ = prog.take_outputs();
1571
1572 prog.resize(100, 30).expect("resize admission");
1573 prog.step().unwrap();
1574 let after_resize = prog.take_outputs();
1575 assert!(after_resize.last_full_repaint_hint);
1576
1577 prog.push_event(key_event('+')).expect("key admission");
1578 prog.step().unwrap();
1579 let after_increment = prog.take_outputs();
1580 assert!(!after_increment.last_full_repaint_hint);
1581 assert!(!after_increment.last_patches.is_empty());
1582 }
1583
1584 #[test]
1587 fn tick_fires_when_rate_elapsed() {
1588 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1589 prog.init().unwrap();
1590
1591 prog.push_event(key_event('+')).expect("key admission");
1594 prog.step().unwrap();
1595
1596 prog.model_mut().value = 0;
1598 prog.execute_cmd(Cmd::tick(Duration::from_millis(100)));
1600 prog.dirty = false; prog.advance_time(Duration::from_millis(50));
1604 let result = prog.step().unwrap();
1605 assert_eq!(prog.model().value, 0);
1606 assert!(!result.rendered);
1607
1608 prog.advance_time(Duration::from_millis(60));
1610 let result = prog.step().unwrap();
1611 assert_eq!(prog.model().value, 1); assert!(result.rendered);
1613 }
1614
1615 #[test]
1616 fn tick_uses_deterministic_clock() {
1617 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1618 prog.init().unwrap();
1619 prog.execute_cmd(Cmd::tick(Duration::from_millis(100)));
1620
1621 prog.set_time(Duration::from_millis(200));
1623 prog.step().unwrap();
1624 assert_eq!(prog.model().value, 1);
1625
1626 prog.set_time(Duration::from_millis(350));
1628 prog.step().unwrap();
1629 assert_eq!(prog.model().value, 2);
1630 }
1631
1632 #[test]
1635 fn log_command_captures_to_presenter() {
1636 let mut prog = StepProgram::new(new_counter(5), 80, 24);
1637 prog.init().unwrap();
1638
1639 prog.execute_cmd(Cmd::msg(CounterMsg::LogValue));
1641
1642 let outputs = prog.outputs();
1643 assert_eq!(outputs.logs, vec!["value=5"]);
1644 }
1645
1646 #[test]
1647 fn log_modes_capture_policy_text_without_terminal_formatting() {
1648 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1649 prog.init().unwrap();
1650 let payload = "a\x1b[31mb\x1b[2Jc\x1b]0;secret\x07d\n";
1651 prog.execute_cmd(Cmd::sequence(vec![
1652 Cmd::log(payload),
1653 Cmd::log_sgr_only(payload),
1654 Cmd::log_raw(payload),
1655 Cmd::quit(),
1656 Cmd::log("unreachable"),
1657 ]));
1658 assert!(!prog.is_running());
1659 assert_eq!(prog.outputs().logs, ["abcd\n", "a\x1b[31mbcd\n", payload]);
1660 }
1661
1662 #[test]
1663 fn batch_command_executes_all() {
1664 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1665 prog.init().unwrap();
1666
1667 prog.execute_cmd(Cmd::msg(CounterMsg::BatchIncrement(5)));
1668 assert_eq!(prog.model().value, 5);
1669 }
1670
1671 #[test]
1672 fn task_executes_synchronously() {
1673 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1674 prog.init().unwrap();
1675
1676 prog.execute_cmd(Cmd::msg(CounterMsg::SpawnTask));
1677 assert_eq!(prog.model().value, 1); }
1679
1680 #[test]
1681 fn set_mouse_capture_updates_features() {
1682 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1683 prog.init().unwrap();
1684
1685 prog.execute_cmd(Cmd::set_mouse_capture(true));
1686 assert!(prog.backend().events.features().mouse_capture);
1687
1688 prog.execute_cmd(Cmd::set_mouse_capture(false));
1689 assert!(!prog.backend().events.features().mouse_capture);
1690 }
1691
1692 #[test]
1695 fn rendered_buffer_reflects_model_state() {
1696 let mut prog = StepProgram::new(new_counter(42), 80, 24);
1697 prog.init().unwrap();
1698
1699 let outputs = prog.outputs();
1700 let buf = outputs.last_buffer.as_ref().unwrap();
1701
1702 assert_eq!(buf.get(0, 0).unwrap().content.as_char(), Some('C'));
1704 assert_eq!(buf.get(7, 0).unwrap().content.as_char(), Some('4'));
1705 assert_eq!(buf.get(8, 0).unwrap().content.as_char(), Some('2'));
1706 }
1707
1708 #[test]
1709 fn subsequent_renders_produce_diffs() {
1710 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1711 prog.init().unwrap();
1712
1713 let outputs = prog.take_outputs();
1715 assert!(outputs.last_full_repaint_hint);
1716
1717 prog.push_event(key_event('+')).expect("key admission");
1719 prog.step().unwrap();
1720
1721 let outputs = prog.outputs();
1722 assert!(!outputs.last_full_repaint_hint);
1723 assert!(!outputs.last_patches.is_empty());
1724 let stats = outputs
1725 .last_patch_stats
1726 .expect("patch stats should be captured");
1727 assert!(stats.patch_count >= 1);
1728 assert!(stats.dirty_cells >= 1);
1729 }
1730
1731 #[test]
1732 fn take_outputs_clears_state() {
1733 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1734 prog.init().unwrap();
1735
1736 let outputs = prog.take_outputs();
1737 assert!(outputs.last_buffer.is_some());
1738
1739 let outputs = prog.outputs();
1741 assert!(outputs.last_buffer.is_none());
1742 assert!(outputs.logs.is_empty());
1743 }
1744
1745 #[test]
1748 fn identical_inputs_produce_identical_outputs() {
1749 fn run_scenario() -> (i32, u64, Vec<Option<char>>) {
1750 let mut prog = StepProgram::new(new_counter(0), 20, 1);
1751 prog.init().unwrap();
1752
1753 prog.push_event(key_event('+')).expect("key admission");
1754 prog.push_event(key_event('+')).expect("key admission");
1755 prog.push_event(key_event('-')).expect("key admission");
1756 prog.push_event(key_event('+')).expect("key admission");
1757 prog.step().unwrap();
1758
1759 let outputs = prog.outputs();
1760 let buf = outputs.last_buffer.as_ref().unwrap();
1761 let chars: Vec<Option<char>> = (0..20)
1762 .map(|x| buf.get(x, 0).and_then(|c| c.content.as_char()))
1763 .collect();
1764
1765 (prog.model().value, prog.frame_idx(), chars)
1766 }
1767
1768 let (v1, f1, c1) = run_scenario();
1769 let (v2, f2, c2) = run_scenario();
1770 let (v3, f3, c3) = run_scenario();
1771
1772 assert_eq!(v1, v2);
1773 assert_eq!(v2, v3);
1774 assert_eq!(v1, 2); assert_eq!(f1, f2);
1776 assert_eq!(f2, f3);
1777 assert_eq!(c1, c2);
1778 assert_eq!(c2, c3);
1779 }
1780
1781 #[test]
1784 fn with_backend_uses_provided_backend() {
1785 let mut backend = WebBackend::new(100, 50);
1786 backend.clock_mut().set(Duration::from_secs(10));
1787
1788 let prog = StepProgram::with_backend(new_counter(0), backend);
1789 assert_eq!(prog.size(), (100, 50));
1790 }
1791
1792 #[test]
1795 fn multi_step_interaction() {
1796 let mut prog = StepProgram::new(new_counter(0), 80, 24);
1797 prog.init().unwrap();
1798
1799 prog.push_event(key_event('+')).expect("key admission");
1801 prog.push_event(key_event('+')).expect("key admission");
1802 let r1 = prog.step().unwrap();
1803 assert_eq!(r1.events_processed, 2);
1804 assert!(r1.rendered);
1805 assert_eq!(prog.model().value, 2);
1806
1807 prog.push_event(key_event('-')).expect("key admission");
1809 let r2 = prog.step().unwrap();
1810 assert_eq!(r2.events_processed, 1);
1811 assert_eq!(prog.model().value, 1);
1812
1813 let r3 = prog.step().unwrap();
1815 assert_eq!(r3.events_processed, 0);
1816 assert!(!r3.rendered);
1817
1818 assert!(r2.frame_idx > r1.frame_idx);
1820 assert_eq!(r3.frame_idx, r2.frame_idx); }
1822
1823 #[test]
1824 fn periodic_pool_gc_bounds_grapheme_growth() {
1825 let mut prog = StepProgram::new(new_grapheme_churn(), 8, 1);
1826 prog.init().unwrap();
1827 prog.execute_cmd(Cmd::tick(Duration::from_millis(1)));
1828
1829 let mut peak_pool_len = prog.pool().len();
1830 for _ in 0..2000 {
1831 prog.advance_time(Duration::from_millis(1));
1832 let _ = prog.step().unwrap();
1833 peak_pool_len = peak_pool_len.max(prog.pool().len());
1834 }
1835
1836 let final_pool_len = prog.pool().len();
1837 assert!(
1838 peak_pool_len <= (POOL_GC_INTERVAL_FRAMES as usize).saturating_add(2),
1839 "peak grapheme pool length should stay bounded by GC interval (peak={peak_pool_len})"
1840 );
1841 assert!(
1842 final_pool_len <= (POOL_GC_INTERVAL_FRAMES as usize).saturating_add(2),
1843 "final grapheme pool length should stay bounded by GC interval (final={final_pool_len})"
1844 );
1845 }
1846
1847 #[test]
1848 fn save_restore_and_tick_strategy_work_in_step_program() {
1849 use ftui_runtime::tick_strategy::{ActiveOnly, ScreenTickDispatch, Uniform};
1850
1851 let registry = Arc::new(StateRegistry::in_memory());
1852 registry.set("viewer", 3, vec![4, 5, 6]);
1853 assert!(registry.is_dirty());
1854
1855 struct WebMultiScreenModel {
1856 active: &'static str,
1857 active_ticks: Vec<u64>,
1858 bg_ticks: Vec<u64>,
1859 }
1860
1861 enum WebMultiMsg {
1862 Tick,
1863 }
1864
1865 impl From<Event> for WebMultiMsg {
1866 fn from(_: Event) -> Self {
1867 Self::Tick
1868 }
1869 }
1870
1871 impl Model for WebMultiScreenModel {
1872 type Message = WebMultiMsg;
1873
1874 fn init(&mut self) -> Cmd<Self::Message> {
1875 Cmd::batch(vec![
1876 Cmd::tick(Duration::from_millis(10)),
1877 Cmd::set_tick_strategy(ActiveOnly),
1878 Cmd::save_state(),
1879 ])
1880 }
1881
1882 fn update(&mut self, _msg: Self::Message) -> Cmd<Self::Message> {
1883 Cmd::none()
1884 }
1885
1886 fn view(&self, _frame: &mut Frame) {}
1887
1888 fn as_screen_tick_dispatch(&mut self) -> Option<&mut dyn ScreenTickDispatch> {
1889 Some(self)
1890 }
1891 }
1892
1893 impl ScreenTickDispatch for WebMultiScreenModel {
1894 fn active_screen_id(&self) -> String {
1895 self.active.to_owned()
1896 }
1897
1898 fn screen_ids(&self) -> Vec<String> {
1899 vec!["alpha".to_owned(), "beta".to_owned()]
1900 }
1901
1902 fn tick_screen(&mut self, screen_id: &str, tick_count: u64) {
1903 if screen_id == self.active {
1904 self.active_ticks.push(tick_count);
1905 } else {
1906 self.bg_ticks.push(tick_count);
1907 }
1908 }
1909 }
1910
1911 let mut prog = StepProgram::new(
1912 WebMultiScreenModel {
1913 active: "alpha",
1914 active_ticks: Vec::new(),
1915 bg_ticks: Vec::new(),
1916 },
1917 40,
1918 10,
1919 )
1920 .with_registry(Arc::clone(®istry));
1921
1922 prog.init().unwrap();
1923 assert!(!registry.is_dirty(), "init SaveState should flush registry");
1924 assert_eq!(prog.tick_strategy_name(), Some("ActiveOnly"));
1925
1926 assert!(registry.remove("viewer").is_some());
1928 assert!(registry.get("viewer").is_none());
1929 prog.execute_cmd(Cmd::restore_state());
1930 let restored = registry
1931 .get("viewer")
1932 .expect("entry restored by Cmd::RestoreState");
1933 assert_eq!(restored.version, 3);
1934 assert_eq!(restored.data, vec![4, 5, 6]);
1935
1936 prog.advance_time(Duration::from_millis(10));
1938 prog.step().unwrap();
1939 assert_eq!(prog.model().active_ticks, vec![1]);
1940 assert!(prog.model().bg_ticks.is_empty());
1941
1942 prog.execute_cmd(Cmd::set_tick_strategy(Uniform::new(2)));
1944 assert_eq!(prog.tick_strategy_name(), Some("Uniform"));
1945 prog.advance_time(Duration::from_millis(10));
1946 prog.step().unwrap();
1947 assert_eq!(prog.model().active_ticks, vec![1, 2]);
1948 assert_eq!(prog.model().bg_ticks, vec![2]);
1949 }
1950}