Skip to main content

ftui_web/
step_program.rs

1#![forbid(unsafe_code)]
2
3//! Step-based WASM program runner for FrankenTUI.
4//!
5//! [`StepProgram`] drives an [`ftui_runtime::program::Model`] through
6//! init / event / update / view / present cycles without threads or blocking.
7//! The host (JavaScript) controls the event loop:
8//!
9//! 1. Push events via [`StepProgram::push_event`].
10//! 2. Advance time via [`StepProgram::advance_time`].
11//! 3. Call [`StepProgram::step`] to process one batch of events and render.
12//! 4. Read the rendered buffer via [`StepProgram::take_outputs`].
13//!
14//! # Accessibility
15//!
16//! Opt in with [`StepProgram::with_accessibility`]. Each rendered frame then
17//! collects the widgets' accessibility nodes, finalizes hierarchy and focus,
18//! and uses the same diff/announcement policy as the native runtime. A changed
19//! tree invokes [`Model::on_accessibility`] after presentation. Mutations and
20//! commands from that hook are rendered on a subsequent host step, never by
21//! recursively rendering inside the callback.
22//!
23//! Hosts can read the current tree or bounded text mirror and drain the latest
24//! frame's announcements. This local channel is separate from renderer logs:
25//! labels, descriptions and input values are never implicitly logged. A host
26//! must forward announcements to its accessibility bridge; this runner does
27//! not itself create DOM nodes or deliver operating-system accessibility events.
28//!
29//! # Example
30//!
31//! ```ignore
32//! use ftui_web::step_program::StepProgram;
33//! use ftui_core::event::Event;
34//! use core::time::Duration;
35//!
36//! let mut prog = StepProgram::new(MyModel::default(), 80, 24);
37//! prog.init().unwrap();
38//!
39//! // Host-driven frame loop
40//! prog.push_event(Event::Tick).expect("tick admission");
41//! prog.advance_time(Duration::from_millis(16));
42//! let result = prog.step().unwrap();
43//!
44//! if result.rendered {
45//!     let outputs = prog.take_outputs();
46//!     // Send outputs.last_buffer to the renderer...
47//! }
48//! ```
49
50use 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
69/// Run grapheme-pool GC every N rendered frames in host-driven WASM mode.
70const POOL_GC_INTERVAL_FRAMES: u64 = 256;
71/// Minimum supported terminal dimension.
72const 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/// Result of a single [`StepProgram::step`] call.
92#[derive(Debug, Clone, Copy, PartialEq, Eq)]
93pub struct StepResult {
94    /// Whether the program is still running (false after `Cmd::Quit`).
95    pub running: bool,
96    /// Whether a frame was rendered during this step.
97    pub rendered: bool,
98    /// Number of events processed during this step.
99    pub events_processed: u32,
100    /// Accepted events still queued, including the unprocessed tail after quit.
101    pub events_pending: u32,
102    /// Current frame index (monotonically increasing).
103    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
114/// Host-driven, non-blocking program runner for WASM.
115///
116/// Wraps a [`Model`] and a [`WebBackend`], providing a step-based execution
117/// model suitable for `wasm32-unknown-unknown`. No threads, no blocking, no
118/// `std::time::Instant` — all I/O and time are host-driven.
119///
120/// # Lifecycle
121///
122/// 1. [`StepProgram::new`] — create with model and initial terminal size.
123/// 2. [`StepProgram::init`] — call once to initialize the model and render the first frame.
124/// 3. [`StepProgram::step`] — call repeatedly from the host event loop (e.g., `requestAnimationFrame`).
125/// 4. Read outputs after each step via [`StepProgram::take_outputs`].
126pub 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    /// Double-buffered render target: O(1) swap instead of O(w*h) clone.
143    dbl_buf: Option<DoubleBuffer>,
144    /// Pending geometry transition that must force a baseline reset + full repaint marker.
145    pending_geometry_transition: Option<GeometryTransition>,
146    clipboard_requests: Vec<ftui_runtime::program::ClipboardRequest>,
147    /// Opt-in, local accessibility channel. No builder is allocated when off.
148    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    /// Create a new step program with the given model and initial terminal size.
157    #[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    /// Create a step program with an existing [`WebBackend`].
188    #[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    /// Attach a [`StateRegistry`] for `Cmd::SaveState` and `Cmd::RestoreState` commands.
221    #[must_use]
222    pub fn with_registry(mut self, registry: Arc<StateRegistry>) -> Self {
223        self.state_registry = Some(registry);
224        self
225    }
226
227    /// Set or clear the [`StateRegistry`] used by `Cmd::SaveState` and `Cmd::RestoreState`.
228    pub fn set_state_registry(&mut self, registry: Option<Arc<StateRegistry>>) {
229        self.state_registry = registry;
230    }
231
232    /// Access the configured [`StateRegistry`], if any.
233    #[must_use]
234    pub fn state_registry(&self) -> Option<&Arc<StateRegistry>> {
235        self.state_registry.as_ref()
236    }
237
238    /// Attach a [`TickStrategy`] for selective background screen ticking.
239    #[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    /// Name of the active [`TickStrategy`], if any.
246    #[must_use]
247    pub fn tick_strategy_name(&self) -> Option<&str> {
248        self.tick_strategy.as_ref().map(|s| s.name())
249    }
250
251    /// Enable the local accessibility channel, normally before [`init`](Self::init).
252    ///
253    /// A host should choose either its model callback or the drain accessor
254    /// for speech delivery, not forward both copies of the same transition.
255    #[must_use]
256    pub fn with_accessibility(mut self, policy: ScreenReaderPolicy) -> Self {
257        self.set_accessibility_policy(Some(policy));
258        self
259    }
260
261    /// Enable, update, or disable accessibility collection at runtime.
262    ///
263    /// Disabling immediately releases the previous tree, reading order and
264    /// undrained announcements. Re-enabling builds a fresh baseline on the
265    /// next rendered step. Changing limits while enabled preserves the tree
266    /// baseline so it does not fabricate another focus arrival. Passing the
267    /// unchanged policy is a no-op, including for undrained announcements.
268    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    /// Schedule a repaint for the next [`step`](Self::step).
284    ///
285    /// Only an event, a tick or an accessibility-policy change marks the frame
286    /// stale. A host that reaches the model another way — [`model_mut`] to
287    /// select a screen, say — leaves nothing to render, and `step` reports
288    /// `rendered: false` until something else happens to arrive.
289    ///
290    /// [`model_mut`]: Self::model_mut
291    pub fn request_redraw(&mut self) {
292        self.dirty = true;
293    }
294
295    /// The active accessibility policy, or `None` when collection is disabled.
296    #[must_use]
297    pub fn accessibility_policy(&self) -> Option<ScreenReaderPolicy> {
298        self.accessibility
299    }
300
301    /// Latest finalized tree (empty until rendering), absent when disabled.
302    #[must_use]
303    pub fn accessibility_tree(&self) -> Option<&A11yTree> {
304        self.accessibility.map(|_| &self.a11y_tree)
305    }
306
307    /// Reading order from the latest render, independent of hash-map order.
308    #[must_use]
309    pub fn accessibility_order(&self) -> &[u64] {
310        &self.a11y_order
311    }
312
313    /// Announcements from the latest rendered frame, unless already drained.
314    ///
315    /// Rendering an unchanged tree clears this batch. An idle step that does
316    /// not render leaves it alone. Use the drain accessor for at-most-once
317    /// forwarding rather than replaying this slice on every animation tick.
318    #[must_use]
319    pub fn accessibility_announcements(&self) -> &[ScreenReaderAnnouncement] {
320        &self.a11y_announcements
321    }
322
323    /// Drain the latest frame's bounded batch without consuming visual output.
324    ///
325    /// Call after `init` and after each rendered `step`. This is a per-frame
326    /// channel, not an unbounded queue of old speech: a subsequent render
327    /// replaces any undrained batch. `dropped_count` reports the current
328    /// frame's policy-cap drops, not missed host reads. A second drain returns
329    /// an empty batch with zero drops. The model callback sees the batch before
330    /// the host can drain it; hosts must avoid forwarding both channels.
331    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    /// A bounded, deterministic mirror of the latest tree for a host bridge.
339    ///
340    /// Mirror text is not a live-region announcement. Hosts should expose it
341    /// for navigation without automatically speaking the entire tree on every
342    /// update. Native semantic bridges should not replay equivalent text too.
343    #[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    /// Initialize the model and render the first frame.
350    ///
351    /// Must be called exactly once before [`step`](Self::step).
352    /// Calls `Model::init()`, executes returned commands, and presents
353    /// the initial frame.
354    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    /// Process one batch of pending events, handle ticks, and render if dirty.
369    ///
370    /// This is the main entry point for the host event loop. Call this after
371    /// pushing events and advancing time.
372    ///
373    /// Returns [`StepResult`] describing what happened during the step.
374    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        // 1. Process all pending events.
388        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        // 2. Handle tick if tick_rate is set and enough time has elapsed.
398        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                // Preserve remainder when running on high-refresh displays:
406                // snapping `last_tick` to the nearest boundary avoids drift and under-ticking.
407                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                // Per-screen tick dispatch using the active TickStrategy when
419                // the model implements ScreenTickDispatch.
420                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        // 3. Render if dirty.
469        let rendered = if self.running && self.dirty {
470            self.render_frame()?;
471            true
472        } else {
473            false
474        };
475
476        if !self.running {
477            // Queued resizes after quit were accepted but never processed.
478            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    /// Push a terminal event into the event queue.
491    ///
492    /// Accepted events are processed on the next [`step`](Self::step) call.
493    /// Rejection leaves the queue and backend size unchanged. Capacity errors
494    /// return the event; a stopped program rejects further input as unsupported.
495    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        // Publish the requested size only after its event is admitted. The
512        // model and render baseline update when `step()` processes it.
513        if let Some((width, height)) = resize {
514            self.backend.events_mut().set_size(width, height);
515        }
516        Ok(())
517    }
518
519    /// Advance the deterministic clock by `dt`.
520    pub fn advance_time(&mut self, dt: Duration) {
521        self.backend.clock_mut().advance(dt);
522    }
523
524    /// Set the deterministic clock to an absolute time.
525    pub fn set_time(&mut self, now: Duration) {
526        self.backend.clock_mut().set(now);
527    }
528
529    /// Resize the terminal.
530    ///
531    /// Pushes a `Resize` event and updates the backend size. The resize
532    /// is processed on the next [`step`](Self::step) call.
533    pub fn resize(&mut self, width: u16, height: u16) -> Result<(), WebBackendError> {
534        self.push_event(Event::Resize { width, height })
535    }
536
537    /// Number of accepted events awaiting processing or explicit recovery.
538    #[must_use]
539    pub fn pending_events(&self) -> u32 {
540        self.backend.events.queued_events() as u32
541    }
542
543    /// Recover queued events in FIFO order without executing their effects.
544    ///
545    /// After quit, the host can retain this tail for inspection or another
546    /// session. Taking pending input cancels any queued resize request and
547    /// restores the backend's requested size to the last processed geometry.
548    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    /// Current deterministic clock value, independently of recording timestamps.
555    #[must_use]
556    pub fn time(&self) -> Duration {
557        self.backend.clock.now_mono()
558    }
559
560    /// Take the captured outputs (rendered buffer, logs), leaving empty defaults.
561    pub fn take_outputs(&mut self) -> WebOutputs {
562        self.backend.presenter_mut().take_outputs()
563    }
564
565    /// Drain clipboard effects for the host's clipboard API.
566    /// Successful reads should be returned through `push_event(Event::Clipboard(...))`.
567    pub fn take_clipboard_requests(&mut self) -> Vec<ftui_runtime::program::ClipboardRequest> {
568        std::mem::take(&mut self.clipboard_requests)
569    }
570
571    /// Read the captured outputs without consuming them.
572    pub fn outputs(&self) -> &WebOutputs {
573        self.backend.presenter.outputs()
574    }
575
576    /// Access the model.
577    pub fn model(&self) -> &M {
578        &self.model
579    }
580
581    /// Mutably access the model.
582    pub fn model_mut(&mut self) -> &mut M {
583        &mut self.model
584    }
585
586    /// Access the backend.
587    pub fn backend(&self) -> &WebBackend {
588        &self.backend
589    }
590
591    /// Mutably access the backend.
592    pub fn backend_mut(&mut self) -> &mut WebBackend {
593        &mut self.backend
594    }
595
596    /// Whether the program is still running.
597    pub fn is_running(&self) -> bool {
598        self.running
599    }
600
601    /// Whether the program has been initialized.
602    pub fn is_initialized(&self) -> bool {
603        self.initialized
604    }
605
606    /// Current frame index.
607    pub fn frame_idx(&self) -> u64 {
608        self.frame_idx
609    }
610
611    /// Current terminal dimensions.
612    pub fn size(&self) -> (u16, u16) {
613        (self.width, self.height)
614    }
615
616    /// Current tick rate, if any.
617    pub fn tick_rate(&self) -> Option<Duration> {
618        self.tick_rate
619    }
620
621    /// Access the grapheme pool (needed for deterministic checksumming).
622    pub fn pool(&self) -> &GraphemePool {
623        &self.pool
624    }
625
626    // --- Private helpers ---
627
628    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, &current_active);
649        }
650        if let Some(dispatch) = self.model.as_screen_tick_dispatch() {
651            dispatch.tick_screen(&current_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            // Invalidate diff baseline for every resize signal.
663            // Host-side fit/DPR/zoom transitions can require a repaint boundary
664            // even when cols/rows remain numerically unchanged.
665            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        // Ensure double buffer exists; first frame triggers allocation.
684        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        // Swap: previous current becomes the diff baseline, current is cleared.
695        {
696            let dbl = self.dbl_buf.as_mut().unwrap();
697            dbl.swap();
698            dbl.current_mut().clear();
699        }
700
701        // Take the cleared buffer out for Frame construction (avoids per-frame
702        // allocation). The 1×1 placeholder is trivially cheap.
703        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        // Move rendered buffer back into the double buffer's current slot.
721        *self.dbl_buf.as_mut().unwrap().current_mut() = rendered_buffer;
722
723        // Compute diff and present.
724        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        // Periodic grapheme-pool GC. Destructure to satisfy the borrow
745        // checker: pool and dbl_buf are disjoint fields.
746        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                // The hook may mutate model state even when it returns None.
762                // Match native Program's one-follow-up-frame contract. An
763                // identical subsequent tree does not invoke the hook again.
764                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    /// Commands run depth-first from an explicit stack of batch iterators, in
801    /// the order recursion gave. Running each `update` result recursively
802    /// overflowed the stack for a model that takes one step per `Cmd::Msg`,
803    /// which on wasm traps and kills the instance.
804    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                    // Resume the innermost batch. A batch stops after any
812                    // command that ends the program.
813                    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    /// Execute `cmd` for [`Self::execute_cmd`], returning the command to run
833    /// next and pushing the rest of a batch onto `batches`.
834    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                // WASM has no threads — execute tasks synchronously.
865                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 model ----
923
924    #[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        // One step per `Cmd::Msg` or inline task. Running each `update`
944        // result recursively overflowed the stack at a few thousand steps.
945        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    /// The runtime keeps several command executors — `ProgramSimulator`,
987    /// this `StepProgram`, `Program` and the experimental `WasmRunner` — and a
988    /// fix to one has repeatedly had to be made in all of them. Nothing held
989    /// them to the same answer, so this walks random command trees through two
990    /// of them and compares what the model saw.
991    #[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        /// A command tree in a form that can be replayed into both runtimes:
998        /// `Cmd` holds closures and cannot be cloned.
999        #[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        // Deterministic: the same trees on every machine and every run.
1052        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        // An equal pair of empty vectors would prove nothing.
1124        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    /// Test model that emits a new combining-mark grapheme each frame.
1203    ///
1204    /// Used to verify periodic grapheme-pool GC in `StepProgram`.
1205    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    // ---- Construction and lifecycle ----
1250
1251    #[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); // First frame rendered.
1282
1283        let outputs = prog.outputs();
1284        assert!(outputs.last_buffer.is_some());
1285        assert!(outputs.last_full_repaint_hint); // First frame is full repaint.
1286        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    // ---- Event processing ----
1310
1311    #[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        // Take initial outputs.
1333        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"); // Should not be processed.
1349        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); // Only first '+' processed.
1360        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        // Stopped programs reject new input and geometry changes.
1389        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    // ---- Resize ----
1406
1407    #[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(); // discard init frame
1487
1488        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(); // discard init frame
1517
1518        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    // ---- Tick handling ----
1585
1586    #[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        // Schedule tick at 100ms intervals.
1592        // Will map to Increment, but we use send for ScheduleTick.
1593        prog.push_event(key_event('+')).expect("key admission");
1594        prog.step().unwrap();
1595
1596        // Manually set tick rate (since our test model doesn't emit ScheduleTick from events).
1597        prog.model_mut().value = 0;
1598        // Directly use the Cmd to schedule ticks through a dedicated message.
1599        prog.execute_cmd(Cmd::tick(Duration::from_millis(100)));
1600        prog.dirty = false; // Reset dirty so we can detect tick-triggered renders.
1601
1602        // Advance less than tick rate — no tick.
1603        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        // Advance past tick rate — tick fires.
1609        prog.advance_time(Duration::from_millis(60));
1610        let result = prog.step().unwrap();
1611        assert_eq!(prog.model().value, 1); // Tick -> Increment.
1612        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        // Set absolute time to trigger tick.
1622        prog.set_time(Duration::from_millis(200));
1623        prog.step().unwrap();
1624        assert_eq!(prog.model().value, 1);
1625
1626        // Advance to next tick boundary.
1627        prog.set_time(Duration::from_millis(350));
1628        prog.step().unwrap();
1629        assert_eq!(prog.model().value, 2);
1630    }
1631
1632    // ---- Command execution ----
1633
1634    #[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        // LogValue emits Cmd::log("value=5").
1640        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); // Task returns Increment.
1678    }
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    // ---- Rendering ----
1693
1694    #[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        // "Count: 42"
1703        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        // First frame is full repaint.
1714        let outputs = prog.take_outputs();
1715        assert!(outputs.last_full_repaint_hint);
1716
1717        // Second frame after an event should not be full repaint.
1718        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        // After take, outputs should be empty.
1740        let outputs = prog.outputs();
1741        assert!(outputs.last_buffer.is_none());
1742        assert!(outputs.logs.is_empty());
1743    }
1744
1745    // ---- Determinism ----
1746
1747    #[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); // +1+1-1+1 = 2
1775        assert_eq!(f1, f2);
1776        assert_eq!(f2, f3);
1777        assert_eq!(c1, c2);
1778        assert_eq!(c2, c3);
1779    }
1780
1781    // ---- with_backend constructor ----
1782
1783    #[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    // ---- Multi-step scenario ----
1793
1794    #[test]
1795    fn multi_step_interaction() {
1796        let mut prog = StepProgram::new(new_counter(0), 80, 24);
1797        prog.init().unwrap();
1798
1799        // Frame 1: increment twice.
1800        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        // Frame 2: decrement once.
1808        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        // Frame 3: no events.
1814        let r3 = prog.step().unwrap();
1815        assert_eq!(r3.events_processed, 0);
1816        assert!(!r3.rendered);
1817
1818        // Frame indices are monotonic.
1819        assert!(r2.frame_idx > r1.frame_idx);
1820        assert_eq!(r3.frame_idx, r2.frame_idx); // No render, same index.
1821    }
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(&registry));
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        // Remove entry from in-memory cache and restore from backing storage via Cmd::RestoreState.
1927        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        // Under ActiveOnly, background screen "beta" is skipped on ticks.
1937        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        // Switch strategy to Uniform(2): tick_count=2 (even) ticks background screen "beta".
1943        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}