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