Skip to main content

ftui_runtime/
input_macro.rs

1#![forbid(unsafe_code)]
2
3//! Input macro recording and playback.
4//!
5//! Record terminal input events with timing information for deterministic
6//! replay through the [`ProgramSimulator`](crate::simulator::ProgramSimulator).
7//!
8//! # Example
9//!
10//! ```ignore
11//! use ftui_runtime::input_macro::{InputMacro, MacroRecorder, MacroPlayer};
12//! use ftui_runtime::simulator::ProgramSimulator;
13//! use ftui_core::event::Event;
14//! use std::time::Duration;
15//!
16//! // Record events
17//! let mut recorder = MacroRecorder::new("test_flow");
18//! recorder.record_event(some_event.clone());
19//! // ... time passes ...
20//! recorder.record_event(another_event.clone());
21//! let macro_recording = recorder.finish();
22//!
23//! // Replay through simulator
24//! let mut sim = ProgramSimulator::new(my_model);
25//! sim.init();
26//! let mut player = MacroPlayer::new(&macro_recording);
27//! player.replay_all(&mut sim);
28//! ```
29
30use ftui_core::event::Event;
31use web_time::{Duration, Instant};
32
33/// A recorded input event with timing relative to recording start.
34#[derive(Debug, Clone)]
35pub struct TimedEvent {
36    /// The recorded event.
37    pub event: Event,
38    /// Delay from the previous event (or from recording start for the first event).
39    pub delay: Duration,
40}
41
42impl TimedEvent {
43    /// Create a new timed event with the given delay.
44    pub fn new(event: Event, delay: Duration) -> Self {
45        Self { event, delay }
46    }
47
48    /// Create a timed event with zero delay.
49    pub fn immediate(event: Event) -> Self {
50        Self {
51            event,
52            delay: Duration::ZERO,
53        }
54    }
55}
56
57/// Metadata about a recorded macro.
58#[derive(Debug, Clone)]
59pub struct MacroMetadata {
60    /// Human-readable name for this macro.
61    pub name: String,
62    /// Terminal size at recording time.
63    pub terminal_size: (u16, u16),
64    /// Total duration of the recording.
65    pub total_duration: Duration,
66}
67
68/// A recorded sequence of input events with timing.
69///
70/// An `InputMacro` captures events and their relative timing so they can
71/// be replayed deterministically through a [`ProgramSimulator`](crate::simulator::ProgramSimulator).
72#[derive(Debug, Clone)]
73pub struct InputMacro {
74    /// The recorded events with timing.
75    events: Vec<TimedEvent>,
76    /// Recording metadata.
77    metadata: MacroMetadata,
78}
79
80impl InputMacro {
81    /// Create a new macro from events and metadata.
82    pub fn new(events: Vec<TimedEvent>, metadata: MacroMetadata) -> Self {
83        Self { events, metadata }
84    }
85
86    /// Create a macro from events with no timing (all zero delay).
87    ///
88    /// Useful for building test macros programmatically.
89    pub fn from_events(name: impl Into<String>, events: Vec<Event>) -> Self {
90        let timed: Vec<TimedEvent> = events.into_iter().map(TimedEvent::immediate).collect();
91        Self {
92            metadata: MacroMetadata {
93                name: name.into(),
94                terminal_size: (80, 24),
95                total_duration: Duration::ZERO,
96            },
97            events: timed,
98        }
99    }
100
101    /// Get the recorded events.
102    pub fn events(&self) -> &[TimedEvent] {
103        &self.events
104    }
105
106    /// Get the metadata.
107    #[inline]
108    pub fn metadata(&self) -> &MacroMetadata {
109        &self.metadata
110    }
111
112    /// Get the number of recorded events.
113    #[inline]
114    pub fn len(&self) -> usize {
115        self.events.len()
116    }
117
118    /// Check if the macro has no events.
119    #[inline]
120    pub fn is_empty(&self) -> bool {
121        self.events.is_empty()
122    }
123
124    /// Get the total duration of the recording.
125    #[inline]
126    pub fn total_duration(&self) -> Duration {
127        self.metadata.total_duration
128    }
129
130    /// Extract just the events (without timing) in order.
131    pub fn bare_events(&self) -> Vec<Event> {
132        self.events.iter().map(|te| te.event.clone()).collect()
133    }
134
135    /// Replay this macro through a simulator, honoring recorded delays.
136    pub fn replay_with_timing<M: crate::program::Model>(
137        &self,
138        sim: &mut crate::simulator::ProgramSimulator<M>,
139    ) {
140        let mut player = MacroPlayer::new(self);
141        player.replay_with_timing(sim);
142    }
143
144    /// Replay this macro through a simulator with a custom sleep function.
145    ///
146    /// Useful for tests that want deterministic timing without wall-clock sleep.
147    pub fn replay_with_sleeper<M, F>(
148        &self,
149        sim: &mut crate::simulator::ProgramSimulator<M>,
150        sleep: F,
151    ) where
152        M: crate::program::Model,
153        F: FnMut(Duration),
154    {
155        let mut player = MacroPlayer::new(self);
156        player.replay_with_sleeper(sim, sleep);
157    }
158}
159
160/// Records input events with timing into an [`InputMacro`].
161///
162/// Call [`record_event`](Self::record_event) for each event, then
163/// [`finish`](Self::finish) to produce the final macro.
164pub struct MacroRecorder {
165    name: String,
166    terminal_size: (u16, u16),
167    events: Vec<TimedEvent>,
168    last_event_time: Instant,
169    recorded_duration: Duration,
170}
171
172impl MacroRecorder {
173    /// Start a new recording session.
174    pub fn new(name: impl Into<String>) -> Self {
175        let now = Instant::now();
176        Self {
177            name: name.into(),
178            terminal_size: (80, 24),
179            events: Vec::new(),
180            last_event_time: now,
181            recorded_duration: Duration::ZERO,
182        }
183    }
184
185    /// Set the terminal size metadata.
186    #[must_use]
187    pub fn with_terminal_size(mut self, width: u16, height: u16) -> Self {
188        self.terminal_size = (width, height);
189        self
190    }
191
192    /// Record an event at the current time.
193    ///
194    /// The delay is measured from the previous event (or recording start).
195    pub fn record_event(&mut self, event: Event) {
196        let now = Instant::now();
197        let delay = now.saturating_duration_since(self.last_event_time);
198        #[cfg(feature = "tracing")]
199        tracing::debug!(event = ?event, delay = ?delay, "macro record event");
200        self.events.push(TimedEvent::new(event, delay));
201        self.recorded_duration = self.recorded_duration.saturating_add(delay);
202        self.last_event_time = now;
203    }
204
205    /// Record an event with an explicit delay from the previous event.
206    pub fn record_event_with_delay(&mut self, event: Event, delay: Duration) {
207        #[cfg(feature = "tracing")]
208        tracing::debug!(event = ?event, delay = ?delay, "macro record event");
209        self.events.push(TimedEvent::new(event, delay));
210        self.recorded_duration = self.recorded_duration.saturating_add(delay);
211        // Advance the synthetic clock when representable. Overflow should not
212        // make explicit-delay recording panic; the accumulated duration above
213        // remains authoritative.
214        self.last_event_time = self
215            .last_event_time
216            .checked_add(delay)
217            .unwrap_or_else(Instant::now);
218    }
219
220    /// Get the number of events recorded so far.
221    pub fn event_count(&self) -> usize {
222        self.events.len()
223    }
224
225    /// Finish recording and produce the macro.
226    pub fn finish(self) -> InputMacro {
227        InputMacro {
228            events: self.events,
229            metadata: MacroMetadata {
230                name: self.name,
231                terminal_size: self.terminal_size,
232                total_duration: self.recorded_duration,
233            },
234        }
235    }
236}
237
238/// Replays an [`InputMacro`] through a `ProgramSimulator`.
239///
240/// Events are injected in order. Timing information is available
241/// for inspection but does not cause real delays (the simulator
242/// is deterministic and instant).
243pub struct MacroPlayer<'a> {
244    input_macro: &'a InputMacro,
245    position: usize,
246    elapsed: Duration,
247}
248
249impl<'a> MacroPlayer<'a> {
250    /// Create a player for the given macro.
251    pub fn new(input_macro: &'a InputMacro) -> Self {
252        Self {
253            input_macro,
254            position: 0,
255            elapsed: Duration::ZERO,
256        }
257    }
258
259    /// Get current playback position (event index).
260    pub fn position(&self) -> usize {
261        self.position
262    }
263
264    /// Get elapsed virtual time.
265    pub fn elapsed(&self) -> Duration {
266        self.elapsed
267    }
268
269    /// Check if playback is complete.
270    pub fn is_done(&self) -> bool {
271        self.position >= self.input_macro.len()
272    }
273
274    /// Get the number of remaining events.
275    pub fn remaining(&self) -> usize {
276        self.input_macro.len().saturating_sub(self.position)
277    }
278
279    /// Step one event, injecting it into the simulator.
280    ///
281    /// Returns `true` if an event was played, `false` if playback is complete.
282    pub fn step<M: crate::program::Model>(
283        &mut self,
284        sim: &mut crate::simulator::ProgramSimulator<M>,
285    ) -> bool {
286        if self.is_done() {
287            return false;
288        }
289
290        let timed = &self.input_macro.events[self.position];
291        #[cfg(feature = "tracing")]
292        tracing::debug!(event = ?timed.event, delay = ?timed.delay, "macro playback event");
293        self.elapsed = self.elapsed.saturating_add(timed.delay);
294        sim.inject_events(std::slice::from_ref(&timed.event));
295        self.position += 1;
296        true
297    }
298
299    /// Replay all remaining events into the simulator.
300    ///
301    /// Stops early if the simulator quits.
302    pub fn replay_all<M: crate::program::Model>(
303        &mut self,
304        sim: &mut crate::simulator::ProgramSimulator<M>,
305    ) {
306        while !self.is_done() && sim.is_running() {
307            self.step(sim);
308        }
309    }
310
311    /// Replay all remaining events, honoring recorded delays.
312    ///
313    /// This uses real wall-clock sleeping for each recorded delay before
314    /// injecting the event. Stops early if the simulator quits.
315    pub fn replay_with_timing<M: crate::program::Model>(
316        &mut self,
317        sim: &mut crate::simulator::ProgramSimulator<M>,
318    ) {
319        self.replay_with_sleeper(sim, std::thread::sleep);
320    }
321
322    /// Replay all remaining events with a custom sleep function.
323    ///
324    /// Useful for tests that want to avoid real sleeping while still verifying
325    /// the delay schedule.
326    pub fn replay_with_sleeper<M, F>(
327        &mut self,
328        sim: &mut crate::simulator::ProgramSimulator<M>,
329        mut sleep: F,
330    ) where
331        M: crate::program::Model,
332        F: FnMut(Duration),
333    {
334        while !self.is_done() && sim.is_running() {
335            let timed = &self.input_macro.events[self.position];
336            if timed.delay > Duration::ZERO {
337                sleep(timed.delay);
338            }
339            self.step(sim);
340        }
341    }
342
343    /// Replay events up to the given virtual time.
344    ///
345    /// Only events whose cumulative delay is within `until` are played.
346    pub fn replay_until<M: crate::program::Model>(
347        &mut self,
348        sim: &mut crate::simulator::ProgramSimulator<M>,
349        until: Duration,
350    ) {
351        while !self.is_done() && sim.is_running() {
352            let timed = &self.input_macro.events[self.position];
353            let next_elapsed = self.elapsed.saturating_add(timed.delay);
354            if next_elapsed > until {
355                break;
356            }
357            self.step(sim);
358        }
359    }
360
361    /// Reset playback to the beginning.
362    pub fn reset(&mut self) {
363        self.position = 0;
364        self.elapsed = Duration::ZERO;
365    }
366}
367
368// ---------------------------------------------------------------------------
369// MacroPlayback – deterministic scheduler for live playback
370// ---------------------------------------------------------------------------
371
372/// Deterministic playback scheduler with speed and looping controls.
373///
374/// Invariants:
375/// - Event order is preserved.
376/// - `elapsed` is monotonic for a given `advance` sequence.
377/// - No events are emitted without their cumulative delay being satisfied.
378///
379/// Failure modes:
380/// - If total duration is zero and looping is enabled, looping is ignored to
381///   avoid infinite emission within a single `advance` call.
382#[derive(Debug, Clone)]
383pub struct MacroPlayback {
384    input_macro: InputMacro,
385    position: usize,
386    elapsed: Duration,
387    next_due: Duration,
388    speed: f64,
389    looping: bool,
390    start_logged: bool,
391    stop_logged: bool,
392    error_logged: bool,
393}
394
395/// Safety cap to prevent pathological looping replays from monopolizing a
396/// frame when elapsed time spikes (e.g. host clock jumps / extreme speed).
397const MAX_DUE_EVENTS_PER_ADVANCE: usize = 4096;
398
399impl MacroPlayback {
400    /// Create a new playback scheduler for the given macro.
401    pub fn new(input_macro: InputMacro) -> Self {
402        let next_due = input_macro
403            .events()
404            .first()
405            .map(|e| e.delay)
406            .unwrap_or(Duration::ZERO);
407        Self {
408            input_macro,
409            position: 0,
410            elapsed: Duration::ZERO,
411            next_due,
412            speed: 1.0,
413            looping: false,
414            start_logged: false,
415            stop_logged: false,
416            error_logged: false,
417        }
418    }
419
420    /// Set playback speed (must be finite and positive).
421    pub fn set_speed(&mut self, speed: f64) {
422        self.speed = normalize_speed(speed);
423    }
424
425    /// Fluent speed setter.
426    #[must_use]
427    pub fn with_speed(mut self, speed: f64) -> Self {
428        self.set_speed(speed);
429        self
430    }
431
432    /// Enable or disable looping.
433    pub fn set_looping(&mut self, looping: bool) {
434        self.looping = looping;
435    }
436
437    /// Fluent looping setter.
438    #[must_use]
439    pub fn with_looping(mut self, looping: bool) -> Self {
440        self.set_looping(looping);
441        self
442    }
443
444    /// Get the current playback speed.
445    pub fn speed(&self) -> f64 {
446        self.speed
447    }
448
449    /// Get current playback position (event index).
450    pub fn position(&self) -> usize {
451        self.position
452    }
453
454    /// Get elapsed virtual time.
455    pub fn elapsed(&self) -> Duration {
456        self.elapsed
457    }
458
459    /// Check if playback is complete (non-looping).
460    pub fn is_done(&self) -> bool {
461        if self.input_macro.is_empty() {
462            return true;
463        }
464        if self.looping && self.input_macro.total_duration() > Duration::ZERO {
465            return false;
466        }
467        self.position >= self.input_macro.len()
468    }
469
470    /// Reset playback to the beginning.
471    pub fn reset(&mut self) {
472        self.position = 0;
473        self.elapsed = Duration::ZERO;
474        self.next_due = self
475            .input_macro
476            .events()
477            .first()
478            .map(|e| e.delay)
479            .unwrap_or(Duration::ZERO);
480        self.start_logged = false;
481        self.stop_logged = false;
482        self.error_logged = false;
483    }
484
485    /// Advance playback time and return any events now due.
486    pub fn advance(&mut self, delta: Duration) -> Vec<Event> {
487        if self.input_macro.is_empty() {
488            #[cfg(feature = "tracing")]
489            if !self.error_logged {
490                let meta = self.input_macro.metadata();
491                tracing::warn!(
492                    macro_event = "playback_error",
493                    reason = "macro_empty",
494                    name = %meta.name,
495                    events = 0usize,
496                    duration_ms = duration_millis_saturating(self.input_macro.total_duration()),
497                );
498                self.error_logged = true;
499            }
500            return Vec::new();
501        }
502        if self.is_done() {
503            return Vec::new();
504        }
505
506        #[cfg(feature = "tracing")]
507        if !self.start_logged {
508            let meta = self.input_macro.metadata();
509            tracing::info!(
510                macro_event = "playback_start",
511                name = %meta.name,
512                events = self.input_macro.len(),
513                duration_ms = duration_millis_saturating(self.input_macro.total_duration()),
514                speed = self.speed,
515                looping = self.looping,
516            );
517            self.start_logged = true;
518        }
519
520        let scaled = scale_duration(delta, self.speed);
521        let total_duration = self.input_macro.total_duration();
522        if self.looping && total_duration > Duration::ZERO && scaled == Duration::MAX {
523            // Overflowed speed scaling can produce effectively infinite backlog.
524            // Collapse to a single bounded loop window for this advance tick.
525            self.elapsed =
526                loop_elapsed_remainder(self.elapsed, total_duration).saturating_add(total_duration);
527        } else {
528            self.elapsed = self.elapsed.saturating_add(scaled);
529        }
530        let events = self.drain_due_events();
531
532        #[cfg(feature = "tracing")]
533        if self.is_done() && !self.stop_logged {
534            let meta = self.input_macro.metadata();
535            tracing::info!(
536                macro_event = "playback_stop",
537                reason = "completed",
538                name = %meta.name,
539                events = self.input_macro.len(),
540                elapsed_ms = duration_millis_saturating(self.elapsed),
541                looping = self.looping,
542            );
543            self.stop_logged = true;
544        }
545
546        events
547    }
548
549    fn drain_due_events(&mut self) -> Vec<Event> {
550        let mut out = Vec::new();
551        let total_duration = self.input_macro.total_duration();
552        let can_loop = self.looping && total_duration > Duration::ZERO;
553        if can_loop && self.position >= self.input_macro.len() {
554            self.elapsed = loop_elapsed_remainder(self.elapsed, total_duration);
555            self.position = 0;
556            self.next_due = self
557                .input_macro
558                .events()
559                .first()
560                .map(|e| e.delay)
561                .unwrap_or(Duration::ZERO);
562        }
563
564        while out.len() < MAX_DUE_EVENTS_PER_ADVANCE
565            && self.position < self.input_macro.len()
566            && self.elapsed >= self.next_due
567        {
568            let timed = &self.input_macro.events[self.position];
569            #[cfg(feature = "tracing")]
570            tracing::debug!(event = ?timed.event, delay = ?timed.delay, "macro playback event");
571            out.push(timed.event.clone());
572            self.position += 1;
573            if self.position < self.input_macro.len() {
574                self.next_due = self
575                    .next_due
576                    .saturating_add(self.input_macro.events[self.position].delay);
577            } else if can_loop {
578                // Carry any overflow elapsed time into the next loop.
579                self.elapsed = self.elapsed.saturating_sub(total_duration);
580                self.position = 0;
581                self.next_due = self
582                    .input_macro
583                    .events()
584                    .first()
585                    .map(|e| e.delay)
586                    .unwrap_or(Duration::ZERO);
587            }
588        }
589
590        if can_loop && out.len() == MAX_DUE_EVENTS_PER_ADVANCE {
591            // Collapse extreme backlog so a single advance cannot spin for
592            // unbounded time under huge elapsed/speed spikes.
593            self.elapsed = loop_elapsed_remainder(self.elapsed, total_duration);
594            if self.position >= self.input_macro.len() {
595                self.position = 0;
596                self.next_due = self
597                    .input_macro
598                    .events()
599                    .first()
600                    .map(|e| e.delay)
601                    .unwrap_or(Duration::ZERO);
602            }
603        }
604
605        out
606    }
607}
608
609fn normalize_speed(speed: f64) -> f64 {
610    if !speed.is_finite() {
611        return 1.0;
612    }
613    if speed <= 0.0 {
614        return 0.0;
615    }
616    speed
617}
618
619fn scale_duration(delta: Duration, speed: f64) -> Duration {
620    if delta == Duration::ZERO {
621        return Duration::ZERO;
622    }
623    let speed = normalize_speed(speed);
624    if speed == 0.0 {
625        return Duration::ZERO;
626    }
627    if speed == 1.0 {
628        return delta;
629    }
630    duration_from_secs_f64_saturating(delta.as_secs_f64() * speed)
631}
632
633fn duration_from_secs_f64_saturating(secs: f64) -> Duration {
634    if secs.is_nan() || secs <= 0.0 {
635        return Duration::ZERO;
636    }
637    Duration::try_from_secs_f64(secs).unwrap_or(Duration::MAX)
638}
639
640#[cfg(any(feature = "tracing", test))]
641fn duration_millis_saturating(duration: Duration) -> u64 {
642    u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
643}
644
645fn loop_elapsed_remainder(elapsed: Duration, total_duration: Duration) -> Duration {
646    let total_secs = total_duration.as_secs_f64();
647    if total_secs <= 0.0 {
648        return Duration::ZERO;
649    }
650    let elapsed_secs = elapsed.as_secs_f64() % total_secs;
651    duration_from_secs_f64_saturating(elapsed_secs)
652}
653
654// ---------------------------------------------------------------------------
655// EventRecorder – live event stream recording with start/stop/pause
656// ---------------------------------------------------------------------------
657
658/// State of an [`EventRecorder`].
659#[derive(Debug, Clone, Copy, PartialEq, Eq)]
660pub enum RecordingState {
661    /// Not yet started or has been stopped.
662    Idle,
663    /// Actively recording events.
664    Recording,
665    /// Temporarily paused (events are ignored).
666    Paused,
667}
668
669/// Records events from a live event stream with start/stop/pause control.
670///
671/// This is a higher-level wrapper around [`MacroRecorder`] designed for
672/// integration with the [`Program`](crate::program::Program) event loop.
673///
674/// # Usage
675///
676/// ```ignore
677/// let mut recorder = EventRecorder::new("my_session");
678/// recorder.start();
679///
680/// // In event loop:
681/// for event in events {
682///     recorder.record(&event);  // No-op if not recording
683///     // ... process event normally ...
684/// }
685///
686/// recorder.pause();
687/// // ... events here are not recorded ...
688/// recorder.resume();
689///
690/// let macro_recording = recorder.finish();
691/// ```
692pub struct EventRecorder {
693    inner: MacroRecorder,
694    state: RecordingState,
695    pause_start: Option<Instant>,
696    total_paused: Duration,
697    event_count: usize,
698}
699
700impl EventRecorder {
701    /// Create a new recorder with the given name.
702    ///
703    /// Starts in [`RecordingState::Idle`]. Call [`start`](Self::start)
704    /// to begin recording.
705    pub fn new(name: impl Into<String>) -> Self {
706        Self {
707            inner: MacroRecorder::new(name),
708            state: RecordingState::Idle,
709            pause_start: None,
710            total_paused: Duration::ZERO,
711            event_count: 0,
712        }
713    }
714
715    /// Set the terminal size metadata.
716    #[must_use]
717    pub fn with_terminal_size(mut self, width: u16, height: u16) -> Self {
718        self.inner = self.inner.with_terminal_size(width, height);
719        self
720    }
721
722    /// Get the current recording state.
723    pub fn state(&self) -> RecordingState {
724        self.state
725    }
726
727    /// Check if actively recording (not idle or paused).
728    pub fn is_recording(&self) -> bool {
729        self.state == RecordingState::Recording
730    }
731
732    /// Start recording. No-op if already recording.
733    pub fn start(&mut self) {
734        match self.state {
735            RecordingState::Idle => {
736                self.state = RecordingState::Recording;
737                #[cfg(feature = "tracing")]
738                tracing::info!(
739                    macro_event = "recorder_start",
740                    name = %self.inner.name,
741                    term_cols = self.inner.terminal_size.0,
742                    term_rows = self.inner.terminal_size.1,
743                );
744            }
745            RecordingState::Paused => {
746                self.resume();
747            }
748            RecordingState::Recording => {} // Already recording
749        }
750    }
751
752    /// Pause recording. Events received while paused are ignored.
753    ///
754    /// No-op if not recording.
755    pub fn pause(&mut self) {
756        if self.state == RecordingState::Recording {
757            self.state = RecordingState::Paused;
758            self.pause_start = Some(Instant::now());
759        }
760    }
761
762    /// Resume recording after a pause.
763    ///
764    /// No-op if not paused.
765    pub fn resume(&mut self) {
766        if self.state == RecordingState::Paused {
767            if let Some(pause_start) = self.pause_start.take() {
768                self.total_paused = self.total_paused.saturating_add(pause_start.elapsed());
769            }
770            // Reset the inner recorder's timestamp so the next event's
771            // delay is measured from the resume instant, not from the
772            // last event before the pause.
773            self.inner.last_event_time = Instant::now();
774            self.state = RecordingState::Recording;
775        }
776    }
777
778    /// Record an event. Only records if state is [`RecordingState::Recording`].
779    ///
780    /// Returns `true` if the event was recorded.
781    pub fn record(&mut self, event: &Event) -> bool {
782        if self.state != RecordingState::Recording {
783            return false;
784        }
785        self.inner.record_event(event.clone());
786        self.event_count += 1;
787        true
788    }
789
790    /// Record an event with an explicit delay override.
791    ///
792    /// Returns `true` if the event was recorded.
793    pub fn record_with_delay(&mut self, event: &Event, delay: Duration) -> bool {
794        if self.state != RecordingState::Recording {
795            return false;
796        }
797        self.inner.record_event_with_delay(event.clone(), delay);
798        self.event_count += 1;
799        true
800    }
801
802    /// Get the number of events recorded so far.
803    pub fn event_count(&self) -> usize {
804        self.event_count
805    }
806
807    /// Get the total time spent paused.
808    pub fn total_paused(&self) -> Duration {
809        let mut total = self.total_paused;
810        if let Some(pause_start) = self.pause_start {
811            total = total.saturating_add(pause_start.elapsed());
812        }
813        total
814    }
815
816    /// Stop recording and produce the final [`InputMacro`].
817    ///
818    /// Consumes the recorder.
819    pub fn finish(self) -> InputMacro {
820        self.finish_internal(true)
821    }
822
823    #[allow(unused_variables)]
824    fn finish_internal(self, log: bool) -> InputMacro {
825        let paused = self.total_paused();
826        let macro_data = self.inner.finish();
827        #[cfg(feature = "tracing")]
828        if log {
829            let meta = macro_data.metadata();
830            tracing::info!(
831                macro_event = "recorder_stop",
832                name = %meta.name,
833                events = macro_data.len(),
834                duration_ms = duration_millis_saturating(macro_data.total_duration()),
835                paused_ms = duration_millis_saturating(paused),
836                term_cols = meta.terminal_size.0,
837                term_rows = meta.terminal_size.1,
838            );
839        }
840        macro_data
841    }
842
843    /// Stop recording and discard all events.
844    ///
845    /// Returns the number of events that were discarded.
846    pub fn discard(self) -> usize {
847        self.event_count
848    }
849}
850
851/// Filter specification for recording.
852///
853/// Controls which events are recorded. Useful for excluding noise
854/// events (like resize storms or mouse moves) from recordings.
855#[derive(Debug, Clone)]
856pub struct RecordingFilter {
857    /// Record keyboard events.
858    pub keys: bool,
859    /// Record mouse events.
860    pub mouse: bool,
861    /// Record resize events.
862    pub resize: bool,
863    /// Record paste events.
864    pub paste: bool,
865    /// Record IME composition events.
866    pub ime: bool,
867    /// Record focus events.
868    pub focus: bool,
869}
870
871impl Default for RecordingFilter {
872    fn default() -> Self {
873        Self {
874            keys: true,
875            mouse: true,
876            resize: true,
877            paste: true,
878            ime: true,
879            focus: true,
880        }
881    }
882}
883
884impl RecordingFilter {
885    /// Record only keyboard events.
886    pub fn keys_only() -> Self {
887        Self {
888            keys: true,
889            mouse: false,
890            resize: false,
891            paste: false,
892            ime: false,
893            focus: false,
894        }
895    }
896
897    /// Check if an event should be recorded.
898    pub fn accepts(&self, event: &Event) -> bool {
899        match event {
900            Event::Key(_) => self.keys,
901            Event::Mouse(_) => self.mouse,
902            Event::Resize { .. } => self.resize,
903            Event::Paste(_) => self.paste,
904            Event::Ime(_) => self.ime,
905            Event::Focus(_) => self.focus,
906            Event::Clipboard(_) => true, // Always record clipboard responses
907            Event::Tick => false,        // Internal timing, not recorded
908        }
909    }
910}
911
912/// A filtered event recorder that only records events matching a filter.
913pub struct FilteredEventRecorder {
914    recorder: EventRecorder,
915    filter: RecordingFilter,
916    filtered_count: usize,
917}
918
919impl FilteredEventRecorder {
920    /// Create a filtered recorder.
921    pub fn new(name: impl Into<String>, filter: RecordingFilter) -> Self {
922        Self {
923            recorder: EventRecorder::new(name),
924            filter,
925            filtered_count: 0,
926        }
927    }
928
929    /// Set terminal size metadata.
930    #[must_use]
931    pub fn with_terminal_size(mut self, width: u16, height: u16) -> Self {
932        self.recorder = self.recorder.with_terminal_size(width, height);
933        self
934    }
935
936    /// Start recording.
937    pub fn start(&mut self) {
938        self.recorder.start();
939    }
940
941    /// Pause recording.
942    pub fn pause(&mut self) {
943        self.recorder.pause();
944    }
945
946    /// Resume recording.
947    pub fn resume(&mut self) {
948        self.recorder.resume();
949    }
950
951    /// Get current state.
952    pub fn state(&self) -> RecordingState {
953        self.recorder.state()
954    }
955
956    /// Check if actively recording.
957    pub fn is_recording(&self) -> bool {
958        self.recorder.is_recording()
959    }
960
961    /// Record an event if it passes the filter.
962    ///
963    /// Returns `true` if the event was recorded (passed filter and recorder is active).
964    pub fn record(&mut self, event: &Event) -> bool {
965        if !self.filter.accepts(event) {
966            self.filtered_count += 1;
967            return false;
968        }
969        self.recorder.record(event)
970    }
971
972    /// Record an event with an explicit delay, applying the same filter.
973    ///
974    /// The filtered counterpart of [`EventRecorder::record_with_delay`], for
975    /// callers that need timing they chose rather than timing the machine
976    /// happened to produce.
977    pub fn record_with_delay(&mut self, event: &Event, delay: Duration) -> bool {
978        if !self.filter.accepts(event) {
979            self.filtered_count += 1;
980            return false;
981        }
982        self.recorder.record_with_delay(event, delay)
983    }
984
985    /// Get the number of events that were filtered out.
986    pub fn filtered_count(&self) -> usize {
987        self.filtered_count
988    }
989
990    /// Get the number of events actually recorded.
991    pub fn event_count(&self) -> usize {
992        self.recorder.event_count()
993    }
994
995    /// Stop recording and produce the final macro.
996    #[allow(unused_variables)]
997    pub fn finish(self) -> InputMacro {
998        let filtered = self.filtered_count;
999        let paused = self.recorder.total_paused();
1000        let macro_data = self.recorder.finish_internal(false);
1001        #[cfg(feature = "tracing")]
1002        {
1003            let meta = macro_data.metadata();
1004            tracing::info!(
1005                macro_event = "recorder_stop",
1006                name = %meta.name,
1007                events = macro_data.len(),
1008                filtered,
1009                duration_ms = duration_millis_saturating(macro_data.total_duration()),
1010                paused_ms = duration_millis_saturating(paused),
1011                term_cols = meta.terminal_size.0,
1012                term_rows = meta.terminal_size.1,
1013            );
1014        }
1015        macro_data
1016    }
1017}
1018
1019#[cfg(test)]
1020mod tests {
1021    use super::*;
1022    use crate::program::{Cmd, Model};
1023    use crate::simulator::ProgramSimulator;
1024    use ftui_core::event::{KeyCode, KeyEvent, KeyEventKind, Modifiers};
1025    use ftui_render::frame::Frame;
1026    use proptest::prelude::*;
1027
1028    // ---------- Test model ----------
1029
1030    struct Counter {
1031        value: i32,
1032    }
1033
1034    #[derive(Debug)]
1035    enum CounterMsg {
1036        Increment,
1037        Decrement,
1038        Quit,
1039    }
1040
1041    impl From<Event> for CounterMsg {
1042        fn from(event: Event) -> Self {
1043            match event {
1044                Event::Key(k) if k.code == KeyCode::Char('+') => CounterMsg::Increment,
1045                Event::Key(k) if k.code == KeyCode::Char('-') => CounterMsg::Decrement,
1046                Event::Key(k) if k.code == KeyCode::Char('q') => CounterMsg::Quit,
1047                _ => CounterMsg::Increment,
1048            }
1049        }
1050    }
1051
1052    impl Model for Counter {
1053        type Message = CounterMsg;
1054
1055        fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
1056            match msg {
1057                CounterMsg::Increment => {
1058                    self.value += 1;
1059                    Cmd::none()
1060                }
1061                CounterMsg::Decrement => {
1062                    self.value -= 1;
1063                    Cmd::none()
1064                }
1065                CounterMsg::Quit => Cmd::quit(),
1066            }
1067        }
1068
1069        fn view(&self, _frame: &mut Frame) {}
1070    }
1071
1072    fn key_event(c: char) -> Event {
1073        Event::Key(KeyEvent {
1074            code: KeyCode::Char(c),
1075            modifiers: Modifiers::empty(),
1076            kind: KeyEventKind::Press,
1077        })
1078    }
1079
1080    // ---------- TimedEvent tests ----------
1081
1082    #[test]
1083    fn timed_event_immediate_has_zero_delay() {
1084        let te = TimedEvent::immediate(key_event('a'));
1085        assert_eq!(te.delay, Duration::ZERO);
1086    }
1087
1088    #[test]
1089    fn timed_event_new_preserves_delay() {
1090        let delay = Duration::from_millis(100);
1091        let te = TimedEvent::new(key_event('x'), delay);
1092        assert_eq!(te.delay, delay);
1093    }
1094
1095    // ---------- InputMacro tests ----------
1096
1097    #[test]
1098    fn macro_from_events_has_zero_delays() {
1099        let m = InputMacro::from_events("test", vec![key_event('+'), key_event('-')]);
1100        assert_eq!(m.len(), 2);
1101        assert!(!m.is_empty());
1102        assert_eq!(m.total_duration(), Duration::ZERO);
1103        for te in m.events() {
1104            assert_eq!(te.delay, Duration::ZERO);
1105        }
1106    }
1107
1108    #[test]
1109    fn macro_metadata() {
1110        let m = InputMacro::from_events("my_macro", vec![key_event('a')]);
1111        assert_eq!(m.metadata().name, "my_macro");
1112        assert_eq!(m.metadata().terminal_size, (80, 24));
1113    }
1114
1115    #[test]
1116    fn empty_macro() {
1117        let m = InputMacro::from_events("empty", vec![]);
1118        assert!(m.is_empty());
1119        assert_eq!(m.len(), 0);
1120    }
1121
1122    #[test]
1123    fn bare_events_extracts_events() {
1124        let events = vec![key_event('+'), key_event('-'), key_event('q')];
1125        let m = InputMacro::from_events("test", events.clone());
1126        let bare = m.bare_events();
1127        assert_eq!(bare.len(), 3);
1128        assert_eq!(bare, events);
1129    }
1130
1131    // ---------- MacroRecorder tests ----------
1132
1133    #[test]
1134    fn recorder_captures_events() {
1135        let mut rec = MacroRecorder::new("rec_test");
1136        rec.record_event(key_event('+'));
1137        rec.record_event(key_event('+'));
1138        rec.record_event(key_event('-'));
1139        assert_eq!(rec.event_count(), 3);
1140
1141        let m = rec.finish();
1142        assert_eq!(m.len(), 3);
1143        assert_eq!(m.metadata().name, "rec_test");
1144    }
1145
1146    #[test]
1147    fn recorder_with_terminal_size() {
1148        let rec = MacroRecorder::new("sized").with_terminal_size(120, 40);
1149        let m = rec.finish();
1150        assert_eq!(m.metadata().terminal_size, (120, 40));
1151    }
1152
1153    #[test]
1154    fn recorder_explicit_delays() {
1155        let mut rec = MacroRecorder::new("delayed");
1156        rec.record_event_with_delay(key_event('+'), Duration::from_millis(0));
1157        rec.record_event_with_delay(key_event('-'), Duration::from_millis(50));
1158        rec.record_event_with_delay(key_event('q'), Duration::from_millis(100));
1159
1160        let m = rec.finish();
1161        assert_eq!(m.events()[0].delay, Duration::from_millis(0));
1162        assert_eq!(m.events()[1].delay, Duration::from_millis(50));
1163        assert_eq!(m.events()[2].delay, Duration::from_millis(100));
1164        assert_eq!(m.total_duration(), Duration::from_millis(150));
1165    }
1166
1167    #[test]
1168    fn recorder_explicit_delay_overflow_saturates_total_duration() {
1169        let mut rec = MacroRecorder::new("huge-delay");
1170        rec.record_event_with_delay(key_event('+'), Duration::MAX);
1171        rec.record_event_with_delay(key_event('-'), Duration::from_millis(1));
1172
1173        let m = rec.finish();
1174        assert_eq!(m.events()[0].delay, Duration::MAX);
1175        assert_eq!(m.events()[1].delay, Duration::from_millis(1));
1176        assert_eq!(m.total_duration(), Duration::MAX);
1177        assert_eq!(duration_millis_saturating(m.total_duration()), u64::MAX);
1178    }
1179
1180    // ---------- MacroPlayer tests ----------
1181
1182    #[test]
1183    fn player_replays_all_events() {
1184        let m = InputMacro::from_events(
1185            "replay",
1186            vec![key_event('+'), key_event('+'), key_event('+')],
1187        );
1188
1189        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1190        sim.init();
1191
1192        let mut player = MacroPlayer::new(&m);
1193        assert_eq!(player.remaining(), 3);
1194        assert!(!player.is_done());
1195
1196        player.replay_all(&mut sim);
1197
1198        assert!(player.is_done());
1199        assert_eq!(player.remaining(), 0);
1200        assert_eq!(sim.model().value, 3);
1201    }
1202
1203    #[test]
1204    fn player_step_advances_position() {
1205        let m = InputMacro::from_events("step", vec![key_event('+'), key_event('+')]);
1206
1207        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1208        sim.init();
1209
1210        let mut player = MacroPlayer::new(&m);
1211        assert_eq!(player.position(), 0);
1212
1213        assert!(player.step(&mut sim));
1214        assert_eq!(player.position(), 1);
1215        assert_eq!(sim.model().value, 1);
1216
1217        assert!(player.step(&mut sim));
1218        assert_eq!(player.position(), 2);
1219        assert_eq!(sim.model().value, 2);
1220
1221        assert!(!player.step(&mut sim));
1222    }
1223
1224    #[test]
1225    fn player_stops_on_quit() {
1226        let m = InputMacro::from_events(
1227            "quit_test",
1228            vec![key_event('+'), key_event('q'), key_event('+')],
1229        );
1230
1231        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1232        sim.init();
1233
1234        let mut player = MacroPlayer::new(&m);
1235        player.replay_all(&mut sim);
1236
1237        // Only increment and quit processed; third event skipped
1238        assert_eq!(sim.model().value, 1);
1239        assert!(!sim.is_running());
1240    }
1241
1242    #[test]
1243    fn player_replay_until_respects_time() {
1244        let events = vec![
1245            TimedEvent::new(key_event('+'), Duration::from_millis(10)),
1246            TimedEvent::new(key_event('+'), Duration::from_millis(20)),
1247            TimedEvent::new(key_event('+'), Duration::from_millis(100)),
1248        ];
1249        let m = InputMacro::new(
1250            events,
1251            MacroMetadata {
1252                name: "timed".to_string(),
1253                terminal_size: (80, 24),
1254                total_duration: Duration::from_millis(130),
1255            },
1256        );
1257
1258        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1259        sim.init();
1260
1261        let mut player = MacroPlayer::new(&m);
1262
1263        // Play events up to 50ms: first two events (10ms + 20ms = 30ms)
1264        player.replay_until(&mut sim, Duration::from_millis(50));
1265        assert_eq!(sim.model().value, 2);
1266        assert_eq!(player.position(), 2);
1267
1268        // Third event at 130ms, play until 200ms
1269        player.replay_until(&mut sim, Duration::from_millis(200));
1270        assert_eq!(sim.model().value, 3);
1271        assert!(player.is_done());
1272    }
1273
1274    #[test]
1275    fn player_elapsed_tracks_virtual_time() {
1276        let events = vec![
1277            TimedEvent::new(key_event('+'), Duration::from_millis(10)),
1278            TimedEvent::new(key_event('+'), Duration::from_millis(20)),
1279        ];
1280        let m = InputMacro::new(
1281            events,
1282            MacroMetadata {
1283                name: "elapsed".to_string(),
1284                terminal_size: (80, 24),
1285                total_duration: Duration::from_millis(30),
1286            },
1287        );
1288
1289        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1290        sim.init();
1291
1292        let mut player = MacroPlayer::new(&m);
1293        assert_eq!(player.elapsed(), Duration::ZERO);
1294
1295        player.step(&mut sim);
1296        assert_eq!(player.elapsed(), Duration::from_millis(10));
1297
1298        player.step(&mut sim);
1299        assert_eq!(player.elapsed(), Duration::from_millis(30));
1300    }
1301
1302    #[test]
1303    fn player_reset_restarts_playback() {
1304        let m = InputMacro::from_events("reset", vec![key_event('+'), key_event('+')]);
1305
1306        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1307        sim.init();
1308
1309        let mut player = MacroPlayer::new(&m);
1310        player.replay_all(&mut sim);
1311        assert_eq!(sim.model().value, 2);
1312        assert!(player.is_done());
1313
1314        // Reset player and replay into fresh simulator
1315        player.reset();
1316        assert_eq!(player.position(), 0);
1317        assert!(!player.is_done());
1318
1319        let mut sim2 = ProgramSimulator::new(Counter { value: 10 });
1320        sim2.init();
1321        player.replay_all(&mut sim2);
1322        assert_eq!(sim2.model().value, 12);
1323    }
1324
1325    #[test]
1326    fn player_replay_with_sleeper_respects_delays() {
1327        let events = vec![
1328            TimedEvent::new(key_event('+'), Duration::from_millis(10)),
1329            TimedEvent::new(key_event('+'), Duration::from_millis(0)),
1330            TimedEvent::new(key_event('+'), Duration::from_millis(25)),
1331        ];
1332        let m = InputMacro::new(
1333            events,
1334            MacroMetadata {
1335                name: "timed_sleep".to_string(),
1336                terminal_size: (80, 24),
1337                total_duration: Duration::from_millis(35),
1338            },
1339        );
1340
1341        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1342        sim.init();
1343
1344        let mut player = MacroPlayer::new(&m);
1345        let mut sleeps = Vec::new();
1346        player.replay_with_sleeper(&mut sim, |d| sleeps.push(d));
1347
1348        assert_eq!(
1349            sleeps,
1350            vec![Duration::from_millis(10), Duration::from_millis(25)]
1351        );
1352        assert_eq!(sim.model().value, 3);
1353    }
1354
1355    // ---------- MacroPlayback tests ----------
1356
1357    #[test]
1358    fn playback_emits_due_events_in_order() {
1359        let events = vec![
1360            TimedEvent::new(key_event('+'), Duration::from_millis(10)),
1361            TimedEvent::new(key_event('+'), Duration::from_millis(10)),
1362        ];
1363        let m = InputMacro::new(
1364            events,
1365            MacroMetadata {
1366                name: "playback".to_string(),
1367                terminal_size: (80, 24),
1368                total_duration: Duration::from_millis(20),
1369            },
1370        );
1371
1372        let mut playback = MacroPlayback::new(m.clone());
1373        assert!(playback.advance(Duration::from_millis(5)).is_empty());
1374        let first = playback.advance(Duration::from_millis(5));
1375        assert_eq!(first.len(), 1);
1376        let second = playback.advance(Duration::from_millis(10));
1377        assert_eq!(second.len(), 1);
1378        assert!(playback.advance(Duration::from_millis(10)).is_empty());
1379    }
1380
1381    #[test]
1382    fn playback_speed_scales_time() {
1383        let events = vec![TimedEvent::new(key_event('+'), Duration::from_millis(10))];
1384        let m = InputMacro::new(
1385            events,
1386            MacroMetadata {
1387                name: "speed".to_string(),
1388                terminal_size: (80, 24),
1389                total_duration: Duration::from_millis(10),
1390            },
1391        );
1392
1393        let mut playback = MacroPlayback::new(m.clone()).with_speed(2.0);
1394        let events = playback.advance(Duration::from_millis(5));
1395        assert_eq!(events.len(), 1);
1396    }
1397
1398    #[test]
1399    fn playback_speed_huge_value_does_not_panic() {
1400        let events = vec![TimedEvent::new(key_event('+'), Duration::from_millis(10))];
1401        let m = InputMacro::new(
1402            events,
1403            MacroMetadata {
1404                name: "huge-speed".to_string(),
1405                terminal_size: (80, 24),
1406                total_duration: Duration::from_millis(10),
1407            },
1408        );
1409
1410        let mut playback = MacroPlayback::new(m).with_speed(f64::MAX);
1411        let events = playback.advance(Duration::from_millis(1));
1412        assert_eq!(events.len(), 1);
1413    }
1414
1415    #[test]
1416    fn playback_speed_huge_looping_multiple_advances_do_not_panic() {
1417        let events = vec![TimedEvent::new(key_event('+'), Duration::from_millis(10))];
1418        let m = InputMacro::new(
1419            events,
1420            MacroMetadata {
1421                name: "huge-speed-looping".to_string(),
1422                terminal_size: (80, 24),
1423                total_duration: Duration::from_millis(10),
1424            },
1425        );
1426
1427        let mut playback = MacroPlayback::new(m)
1428            .with_speed(f64::MAX)
1429            .with_looping(true);
1430        let first = playback.advance(Duration::from_millis(1));
1431        assert_eq!(first.len(), 1);
1432        let second = playback.advance(Duration::from_millis(1));
1433        assert_eq!(second.len(), 1);
1434    }
1435
1436    #[test]
1437    fn playback_looping_handles_large_delta() {
1438        let events = vec![
1439            TimedEvent::new(key_event('+'), Duration::from_millis(10)),
1440            TimedEvent::new(key_event('+'), Duration::from_millis(10)),
1441        ];
1442        let m = InputMacro::new(
1443            events,
1444            MacroMetadata {
1445                name: "loop".to_string(),
1446                terminal_size: (80, 24),
1447                total_duration: Duration::from_millis(20),
1448            },
1449        );
1450
1451        let mut playback = MacroPlayback::new(m.clone()).with_looping(true);
1452        let events = playback.advance(Duration::from_millis(50));
1453        assert_eq!(events.len(), 5);
1454    }
1455
1456    #[test]
1457    fn playback_zero_duration_does_not_loop_forever() {
1458        let m = InputMacro::from_events("zero", vec![key_event('+'), key_event('+')]);
1459        let mut playback = MacroPlayback::new(m.clone()).with_looping(true);
1460
1461        let events = playback.advance(Duration::ZERO);
1462        assert_eq!(events.len(), 2);
1463        assert!(playback.advance(Duration::from_millis(10)).is_empty());
1464    }
1465
1466    #[test]
1467    fn macro_replay_with_sleeper_wrapper() {
1468        let events = vec![
1469            TimedEvent::new(key_event('+'), Duration::from_millis(5)),
1470            TimedEvent::new(key_event('+'), Duration::from_millis(10)),
1471        ];
1472        let m = InputMacro::new(
1473            events,
1474            MacroMetadata {
1475                name: "wrapper".to_string(),
1476                terminal_size: (80, 24),
1477                total_duration: Duration::from_millis(15),
1478            },
1479        );
1480
1481        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1482        sim.init();
1483
1484        let mut slept = Vec::new();
1485        m.replay_with_sleeper(&mut sim, |d| slept.push(d));
1486
1487        assert_eq!(
1488            slept,
1489            vec![Duration::from_millis(5), Duration::from_millis(10)]
1490        );
1491        assert_eq!(sim.model().value, 2);
1492    }
1493
1494    #[test]
1495    fn empty_macro_replay() {
1496        let m = InputMacro::from_events("empty", vec![]);
1497
1498        let mut sim = ProgramSimulator::new(Counter { value: 5 });
1499        sim.init();
1500
1501        let mut player = MacroPlayer::new(&m);
1502        assert!(player.is_done());
1503        player.replay_all(&mut sim);
1504        assert_eq!(sim.model().value, 5);
1505    }
1506
1507    #[test]
1508    fn macro_with_mixed_events() {
1509        let events = vec![
1510            key_event('+'),
1511            Event::Resize {
1512                width: 100,
1513                height: 50,
1514            },
1515            key_event('-'),
1516            Event::Focus(true),
1517            key_event('+'),
1518        ];
1519        let m = InputMacro::from_events("mixed", events);
1520
1521        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1522        sim.init();
1523
1524        let mut player = MacroPlayer::new(&m);
1525        player.replay_all(&mut sim);
1526
1527        // +1, resize->increment, -1, focus->increment, +1 = 3
1528        // (Counter converts all non-matching events to Increment)
1529        assert_eq!(sim.model().value, 3);
1530    }
1531
1532    #[test]
1533    fn deterministic_replay() {
1534        let m = InputMacro::from_events(
1535            "determinism",
1536            vec![
1537                key_event('+'),
1538                key_event('+'),
1539                key_event('-'),
1540                key_event('+'),
1541                key_event('+'),
1542            ],
1543        );
1544
1545        // Replay twice and verify identical results
1546        let result1 = {
1547            let mut sim = ProgramSimulator::new(Counter { value: 0 });
1548            sim.init();
1549            MacroPlayer::new(&m).replay_all(&mut sim);
1550            sim.model().value
1551        };
1552
1553        let result2 = {
1554            let mut sim = ProgramSimulator::new(Counter { value: 0 });
1555            sim.init();
1556            MacroPlayer::new(&m).replay_all(&mut sim);
1557            sim.model().value
1558        };
1559
1560        assert_eq!(result1, result2);
1561        assert_eq!(result1, 3);
1562    }
1563
1564    // ---------- EventRecorder tests ----------
1565
1566    #[test]
1567    fn event_recorder_starts_idle() {
1568        let rec = EventRecorder::new("test");
1569        assert_eq!(rec.state(), RecordingState::Idle);
1570        assert!(!rec.is_recording());
1571        assert_eq!(rec.event_count(), 0);
1572    }
1573
1574    #[test]
1575    fn event_recorder_start_activates() {
1576        let mut rec = EventRecorder::new("test");
1577        rec.start();
1578        assert_eq!(rec.state(), RecordingState::Recording);
1579        assert!(rec.is_recording());
1580    }
1581
1582    #[test]
1583    fn event_recorder_ignores_events_when_idle() {
1584        let mut rec = EventRecorder::new("test");
1585        assert!(!rec.record(&key_event('a')));
1586        assert_eq!(rec.event_count(), 0);
1587    }
1588
1589    #[test]
1590    fn event_recorder_records_when_active() {
1591        let mut rec = EventRecorder::new("test");
1592        rec.start();
1593        assert!(rec.record(&key_event('a')));
1594        assert!(rec.record(&key_event('b')));
1595        assert_eq!(rec.event_count(), 2);
1596
1597        let m = rec.finish();
1598        assert_eq!(m.len(), 2);
1599    }
1600
1601    #[test]
1602    fn event_recorder_pause_ignores_events() {
1603        let mut rec = EventRecorder::new("test");
1604        rec.start();
1605        rec.record(&key_event('a'));
1606        rec.pause();
1607        assert_eq!(rec.state(), RecordingState::Paused);
1608        assert!(!rec.is_recording());
1609
1610        // Events during pause are ignored
1611        assert!(!rec.record(&key_event('b')));
1612        assert_eq!(rec.event_count(), 1);
1613    }
1614
1615    #[test]
1616    fn event_recorder_resume_after_pause() {
1617        let mut rec = EventRecorder::new("test");
1618        rec.start();
1619        rec.record(&key_event('a'));
1620        rec.pause();
1621        rec.record(&key_event('b')); // ignored
1622        rec.resume();
1623        assert!(rec.is_recording());
1624        rec.record(&key_event('c'));
1625        assert_eq!(rec.event_count(), 2);
1626
1627        let m = rec.finish();
1628        assert_eq!(m.len(), 2);
1629        assert_eq!(m.bare_events()[0], key_event('a'));
1630        assert_eq!(m.bare_events()[1], key_event('c'));
1631    }
1632
1633    #[test]
1634    fn event_recorder_resume_saturates_total_paused() {
1635        let mut rec = EventRecorder::new("test");
1636        rec.start();
1637        rec.total_paused = Duration::MAX;
1638        rec.pause();
1639        std::thread::sleep(Duration::from_millis(1));
1640        rec.resume();
1641
1642        assert_eq!(rec.total_paused(), Duration::MAX);
1643    }
1644
1645    #[test]
1646    fn event_recorder_active_pause_saturates_total_paused_query() {
1647        let mut rec = EventRecorder::new("test");
1648        rec.start();
1649        rec.total_paused = Duration::MAX;
1650        rec.pause();
1651        std::thread::sleep(Duration::from_millis(1));
1652
1653        assert_eq!(rec.total_paused(), Duration::MAX);
1654    }
1655
1656    #[test]
1657    fn event_recorder_start_resumes_when_paused() {
1658        let mut rec = EventRecorder::new("test");
1659        rec.start();
1660        rec.pause();
1661        assert_eq!(rec.state(), RecordingState::Paused);
1662
1663        rec.start(); // Should resume
1664        assert_eq!(rec.state(), RecordingState::Recording);
1665    }
1666
1667    #[test]
1668    fn event_recorder_pause_noop_when_idle() {
1669        let mut rec = EventRecorder::new("test");
1670        rec.pause();
1671        assert_eq!(rec.state(), RecordingState::Idle);
1672    }
1673
1674    #[test]
1675    fn event_recorder_resume_noop_when_idle() {
1676        let mut rec = EventRecorder::new("test");
1677        rec.resume();
1678        assert_eq!(rec.state(), RecordingState::Idle);
1679    }
1680
1681    #[test]
1682    fn event_recorder_discard() {
1683        let mut rec = EventRecorder::new("test");
1684        rec.start();
1685        rec.record(&key_event('a'));
1686        rec.record(&key_event('b'));
1687        let count = rec.discard();
1688        assert_eq!(count, 2);
1689    }
1690
1691    #[test]
1692    fn event_recorder_with_terminal_size() {
1693        let mut rec = EventRecorder::new("sized").with_terminal_size(120, 40);
1694        rec.start();
1695        rec.record(&key_event('x'));
1696        let m = rec.finish();
1697        assert_eq!(m.metadata().terminal_size, (120, 40));
1698    }
1699
1700    #[test]
1701    fn event_recorder_finish_produces_valid_macro() {
1702        let mut rec = EventRecorder::new("full_test");
1703        rec.start();
1704        rec.record(&key_event('+'));
1705        rec.record(&key_event('+'));
1706        rec.record(&key_event('-'));
1707
1708        let m = rec.finish();
1709        assert_eq!(m.len(), 3);
1710        assert_eq!(m.metadata().name, "full_test");
1711
1712        // Replay and verify
1713        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1714        sim.init();
1715        MacroPlayer::new(&m).replay_all(&mut sim);
1716        assert_eq!(sim.model().value, 1); // +1 +1 -1 = 1
1717    }
1718
1719    #[test]
1720    fn event_recorder_record_with_delay() {
1721        let mut rec = EventRecorder::new("delayed");
1722        rec.start();
1723        assert!(rec.record_with_delay(&key_event('a'), Duration::from_millis(50)));
1724        assert!(rec.record_with_delay(&key_event('b'), Duration::from_millis(100)));
1725        assert_eq!(rec.event_count(), 2);
1726
1727        let m = rec.finish();
1728        assert_eq!(m.events()[0].delay, Duration::from_millis(50));
1729        assert_eq!(m.events()[1].delay, Duration::from_millis(100));
1730    }
1731
1732    #[test]
1733    fn event_recorder_record_with_delay_ignores_when_idle() {
1734        let mut rec = EventRecorder::new("test");
1735        assert!(!rec.record_with_delay(&key_event('a'), Duration::from_millis(50)));
1736        assert_eq!(rec.event_count(), 0);
1737    }
1738
1739    // ---------- RecordingFilter tests ----------
1740
1741    #[test]
1742    fn filter_default_accepts_all() {
1743        let filter = RecordingFilter::default();
1744        assert!(filter.accepts(&key_event('a')));
1745        assert!(filter.accepts(&Event::Resize {
1746            width: 80,
1747            height: 24
1748        }));
1749        assert!(filter.accepts(&Event::Focus(true)));
1750    }
1751
1752    #[test]
1753    fn filter_keys_only() {
1754        let filter = RecordingFilter::keys_only();
1755        assert!(filter.accepts(&key_event('a')));
1756        assert!(!filter.accepts(&Event::Resize {
1757            width: 80,
1758            height: 24
1759        }));
1760        assert!(!filter.accepts(&Event::Focus(true)));
1761    }
1762
1763    #[test]
1764    fn filter_custom() {
1765        let filter = RecordingFilter {
1766            keys: true,
1767            mouse: false,
1768            resize: false,
1769            paste: true,
1770            ime: false,
1771            focus: false,
1772        };
1773        assert!(filter.accepts(&key_event('a')));
1774        assert!(!filter.accepts(&Event::Resize {
1775            width: 80,
1776            height: 24
1777        }));
1778        assert!(!filter.accepts(&Event::Focus(false)));
1779    }
1780
1781    // ---------- FilteredEventRecorder tests ----------
1782
1783    #[test]
1784    fn filtered_recorder_records_matching_events() {
1785        let mut rec = FilteredEventRecorder::new("filtered", RecordingFilter::default());
1786        rec.start();
1787        assert!(rec.record(&key_event('a')));
1788        assert_eq!(rec.event_count(), 1);
1789        assert_eq!(rec.filtered_count(), 0);
1790    }
1791
1792    #[test]
1793    fn filtered_recorder_skips_filtered_events() {
1794        let mut rec = FilteredEventRecorder::new("keys_only", RecordingFilter::keys_only());
1795        rec.start();
1796        assert!(rec.record(&key_event('a')));
1797        assert!(!rec.record(&Event::Focus(true)));
1798        assert!(!rec.record(&Event::Resize {
1799            width: 100,
1800            height: 50
1801        }));
1802        assert!(rec.record(&key_event('b')));
1803
1804        assert_eq!(rec.event_count(), 2);
1805        assert_eq!(rec.filtered_count(), 2);
1806    }
1807
1808    #[test]
1809    fn filtered_recorder_finish_produces_macro() {
1810        let mut rec = FilteredEventRecorder::new("test", RecordingFilter::keys_only());
1811        rec.start();
1812        rec.record(&key_event('+'));
1813        rec.record(&Event::Focus(true)); // filtered
1814        rec.record(&key_event('+'));
1815
1816        let m = rec.finish();
1817        assert_eq!(m.len(), 2);
1818
1819        let mut sim = ProgramSimulator::new(Counter { value: 0 });
1820        sim.init();
1821        MacroPlayer::new(&m).replay_all(&mut sim);
1822        assert_eq!(sim.model().value, 2);
1823    }
1824
1825    #[test]
1826    fn filtered_recorder_pause_resume() {
1827        let mut rec = FilteredEventRecorder::new("test", RecordingFilter::default());
1828        rec.start();
1829        rec.record(&key_event('a'));
1830        rec.pause();
1831        assert!(!rec.record(&key_event('b'))); // paused
1832        rec.resume();
1833        rec.record(&key_event('c'));
1834        assert_eq!(rec.event_count(), 2);
1835    }
1836
1837    #[test]
1838    fn filtered_recorder_with_terminal_size() {
1839        let mut rec = FilteredEventRecorder::new("sized", RecordingFilter::default())
1840            .with_terminal_size(200, 60);
1841        rec.start();
1842        rec.record(&key_event('x'));
1843        let m = rec.finish();
1844        assert_eq!(m.metadata().terminal_size, (200, 60));
1845    }
1846
1847    // ---------- Property tests ----------
1848
1849    #[derive(Default)]
1850    struct EventSink {
1851        events: Vec<Event>,
1852    }
1853
1854    #[derive(Debug, Clone)]
1855    struct EventMsg(Event);
1856
1857    impl From<Event> for EventMsg {
1858        fn from(event: Event) -> Self {
1859            Self(event)
1860        }
1861    }
1862
1863    impl Model for EventSink {
1864        type Message = EventMsg;
1865
1866        fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
1867            self.events.push(msg.0);
1868            Cmd::none()
1869        }
1870
1871        fn view(&self, _frame: &mut Frame) {}
1872    }
1873
1874    proptest! {
1875        #[test]
1876        fn recorder_with_explicit_delays_roundtrips(pairs in proptest::collection::vec((0u8..=25, 0u16..=2000), 0..32)) {
1877            let mut recorder = MacroRecorder::new("prop").with_terminal_size(80, 24);
1878            let mut expected_total = Duration::ZERO;
1879            let mut expected_events = Vec::with_capacity(pairs.len());
1880
1881            for (ch_idx, delay_ms) in &pairs {
1882                let ch = char::from(b'a' + *ch_idx);
1883                let delay = Duration::from_millis(*delay_ms as u64);
1884                expected_total += delay;
1885                let ev = key_event(ch);
1886                expected_events.push(ev.clone());
1887                recorder.record_event_with_delay(ev, delay);
1888            }
1889
1890            let m = recorder.finish();
1891            prop_assert_eq!(m.len(), pairs.len());
1892            prop_assert_eq!(m.metadata().terminal_size, (80, 24));
1893            prop_assert_eq!(m.total_duration(), expected_total);
1894            prop_assert_eq!(m.bare_events(), expected_events);
1895        }
1896
1897        #[test]
1898        fn player_replays_events_in_order(pairs in proptest::collection::vec((0u8..=25, 0u16..=2000), 0..32)) {
1899            let mut timed = Vec::with_capacity(pairs.len());
1900            let mut total = Duration::ZERO;
1901            let mut expected_events = Vec::with_capacity(pairs.len());
1902
1903            for (ch_idx, delay_ms) in &pairs {
1904                let ch = char::from(b'a' + *ch_idx);
1905                let delay = Duration::from_millis(*delay_ms as u64);
1906                total += delay;
1907                let ev = key_event(ch);
1908                expected_events.push(ev.clone());
1909                timed.push(TimedEvent::new(ev, delay));
1910            }
1911
1912            let m = InputMacro::new(timed, MacroMetadata {
1913                name: "prop".to_string(),
1914                terminal_size: (80, 24),
1915                total_duration: total,
1916            });
1917
1918            let mut sim = ProgramSimulator::new(EventSink::default());
1919            sim.init();
1920            let mut player = MacroPlayer::new(&m);
1921            player.replay_all(&mut sim);
1922
1923            prop_assert_eq!(sim.model().events.clone(), expected_events);
1924            prop_assert_eq!(player.elapsed(), total);
1925        }
1926    }
1927}