1#![forbid(unsafe_code)]
2
3use core::time::Duration;
49
50use ftui_core::event::{
51 ClipboardEvent, ClipboardSource, Event, ImeEvent, ImePhase, KeyCode, KeyEvent, KeyEventKind,
52 Modifiers, MouseButton, MouseEvent, MouseEventKind, PasteEvent,
53};
54use ftui_runtime::render_trace::checksum_buffer;
55
56use crate::WebBackendError;
57use crate::step_program::{StepProgram, StepResult};
58#[cfg(feature = "tracing")]
59use tracing::{error, info_span};
60
61pub const SCHEMA_VERSION: &str = "golden-trace-v2";
63
64const FNV_OFFSET_BASIS: u64 = 0xcbf29ce484222325;
66const FNV_PRIME: u64 = 0x100000001b3;
67
68fn fnv1a64_bytes(mut hash: u64, bytes: &[u8]) -> u64 {
69 for &b in bytes {
70 hash ^= b as u64;
71 hash = hash.wrapping_mul(FNV_PRIME);
72 }
73 hash
74}
75
76fn fnv1a64_u64(hash: u64, v: u64) -> u64 {
77 fnv1a64_bytes(hash, &v.to_le_bytes())
78}
79
80fn fnv1a64_pair(prev: u64, next: u64) -> u64 {
81 let hash = FNV_OFFSET_BASIS;
82 let hash = fnv1a64_u64(hash, prev);
83 fnv1a64_u64(hash, next)
84}
85
86#[derive(Debug, Clone, PartialEq)]
88pub enum TraceRecord {
89 Header {
91 seed: u64,
92 cols: u16,
93 rows: u16,
94 profile: String,
95 },
96 Input { ts_ns: u64, event: Event },
98 Resize { ts_ns: u64, cols: u16, rows: u16 },
100 Tick { ts_ns: u64 },
102 Step {
104 step_idx: u64,
105 ts_ns: u64,
106 init: bool,
107 clock: Duration,
108 result: StepResult,
109 },
110 Frame {
112 frame_idx: u64,
113 ts_ns: u64,
114 checksum: u64,
115 checksum_chain: u64,
116 },
117 Summary {
119 total_frames: u64,
120 final_checksum_chain: u64,
121 },
122}
123
124#[derive(Debug, Clone)]
126pub struct SessionTrace {
127 pub records: Vec<TraceRecord>,
128}
129
130impl SessionTrace {
131 pub fn frame_count(&self) -> u64 {
133 self.records
134 .iter()
135 .filter(|r| matches!(r, TraceRecord::Frame { .. }))
136 .count() as u64
137 }
138
139 pub fn final_checksum_chain(&self) -> Option<u64> {
141 self.records.iter().rev().find_map(|r| match r {
142 TraceRecord::Summary {
143 final_checksum_chain,
144 ..
145 } => Some(*final_checksum_chain),
146 _ => None,
147 })
148 }
149
150 pub fn validate(&self) -> Result<(), TraceValidationError> {
160 if self.records.is_empty() {
161 return Err(TraceValidationError::EmptyTrace);
162 }
163
164 let mut header_count: usize = 0;
165 let mut summary: Option<(usize, u64, u64)> = None;
166 let mut expected_frame_idx: u64 = 0;
167 let mut frame_count: u64 = 0;
168 let mut last_checksum_chain: u64 = 0;
169 let mut last_ts_ns: Option<u64> = None;
170
171 let mut validate_ts =
172 |ts_ns: u64, record_index: usize| -> Result<(), TraceValidationError> {
173 if let Some(previous) = last_ts_ns
174 && ts_ns < previous
175 {
176 return Err(TraceValidationError::TimestampRegression {
177 previous,
178 current: ts_ns,
179 record_index,
180 });
181 }
182 last_ts_ns = Some(ts_ns);
183 Ok(())
184 };
185
186 for (idx, record) in self.records.iter().enumerate() {
187 match record {
188 TraceRecord::Header { .. } => {
189 if summary.is_some() {
190 let summary_idx = summary.map(|(i, _, _)| i).unwrap_or_default();
191 return Err(TraceValidationError::SummaryNotLast {
192 summary_index: summary_idx,
193 });
194 }
195 header_count += 1;
196 }
197 TraceRecord::Summary {
198 total_frames,
199 final_checksum_chain,
200 } => {
201 if summary.is_some() {
202 return Err(TraceValidationError::MultipleSummaries);
203 }
204 summary = Some((idx, *total_frames, *final_checksum_chain));
205 }
206 TraceRecord::Frame {
207 frame_idx,
208 ts_ns,
209 checksum_chain,
210 ..
211 } => {
212 validate_ts(*ts_ns, idx)?;
213 if summary.is_some() {
214 let summary_idx = summary.map(|(i, _, _)| i).unwrap_or_default();
215 return Err(TraceValidationError::SummaryNotLast {
216 summary_index: summary_idx,
217 });
218 }
219 if *frame_idx != expected_frame_idx {
220 return Err(TraceValidationError::FrameIndexMismatch {
221 expected: expected_frame_idx,
222 actual: *frame_idx,
223 });
224 }
225 expected_frame_idx = expected_frame_idx.saturating_add(1);
226 frame_count = frame_count.saturating_add(1);
227 last_checksum_chain = *checksum_chain;
228 }
229 TraceRecord::Input { ts_ns, .. } => {
230 validate_ts(*ts_ns, idx)?;
231 if summary.is_some() {
232 let summary_idx = summary.map(|(i, _, _)| i).unwrap_or_default();
233 return Err(TraceValidationError::SummaryNotLast {
234 summary_index: summary_idx,
235 });
236 }
237 }
238 TraceRecord::Resize { ts_ns, .. } => {
239 validate_ts(*ts_ns, idx)?;
240 if summary.is_some() {
241 let summary_idx = summary.map(|(i, _, _)| i).unwrap_or_default();
242 return Err(TraceValidationError::SummaryNotLast {
243 summary_index: summary_idx,
244 });
245 }
246 }
247 TraceRecord::Tick { ts_ns } => {
248 validate_ts(*ts_ns, idx)?;
249 if summary.is_some() {
250 let summary_idx = summary.map(|(i, _, _)| i).unwrap_or_default();
251 return Err(TraceValidationError::SummaryNotLast {
252 summary_index: summary_idx,
253 });
254 }
255 }
256 TraceRecord::Step { ts_ns, .. } => {
257 validate_ts(*ts_ns, idx)?;
258 if let Some((summary_index, _, _)) = summary {
259 return Err(TraceValidationError::SummaryNotLast { summary_index });
260 }
261 }
262 }
263 }
264
265 if header_count == 0 {
266 return Err(TraceValidationError::MissingHeader);
267 }
268 if header_count > 1 {
269 return Err(TraceValidationError::MultipleHeaders);
270 }
271 if !matches!(self.records.first(), Some(TraceRecord::Header { .. })) {
272 return Err(TraceValidationError::HeaderNotFirst);
273 }
274
275 let Some((summary_idx, summary_frames, summary_chain)) = summary else {
276 return Err(TraceValidationError::MissingSummary);
277 };
278 if summary_idx != self.records.len().saturating_sub(1) {
279 return Err(TraceValidationError::SummaryNotLast {
280 summary_index: summary_idx,
281 });
282 }
283 if summary_frames != frame_count {
284 return Err(TraceValidationError::SummaryFrameCountMismatch {
285 expected: frame_count,
286 actual: summary_frames,
287 });
288 }
289 if summary_chain != last_checksum_chain {
290 return Err(TraceValidationError::SummaryChecksumChainMismatch {
291 expected: last_checksum_chain,
292 actual: summary_chain,
293 });
294 }
295
296 self.validate_steps()
297 }
298
299 fn validate_steps(&self) -> Result<(), TraceValidationError> {
300 let mut next_step = 0;
301 let mut frames = 0;
302 let mut queued = 0_u64;
303 let mut last_result: Option<StepResult> = None;
304 let mut frame_pending = false;
305 let mut inputs_pending = false;
306 let mut checksum_chain = 0;
307 for (record_index, record) in self.records.iter().enumerate() {
308 let invalid = |reason| TraceValidationError::InvalidExecution {
309 record_index,
310 reason,
311 };
312 if frame_pending && !matches!(record, TraceRecord::Frame { .. }) {
313 return Err(invalid("rendered step is missing its frame checkpoint"));
314 }
315 match record {
316 TraceRecord::Step {
317 step_idx,
318 init,
319 result,
320 ..
321 } => {
322 if *step_idx != next_step || *init != (next_step == 0) {
323 return Err(invalid(
324 "steps must start with init at zero and be contiguous",
325 ));
326 }
327 if *init && result.events_processed != 0 {
328 return Err(invalid("initialization cannot process queued input"));
329 }
330 if result.events_processed as u64 > queued {
331 return Err(invalid("step processed more events than were admitted"));
332 }
333 queued -= u64::from(result.events_processed);
334 if queued != u64::from(result.events_pending) {
335 return Err(invalid(
336 "step pending count does not account for accepted input",
337 ));
338 }
339 if let Some(previous) = last_result
340 && !previous.running
341 && (result.running || result.rendered || result.events_processed != 0)
342 {
343 return Err(invalid("a stopped program cannot resume or process input"));
344 }
345 if result.rendered && !result.running {
346 return Err(invalid("a stopped step cannot render"));
347 }
348 if result.frame_idx != frames + u64::from(result.rendered) {
349 return Err(invalid(
350 "step frame count does not match rendered checkpoints",
351 ));
352 }
353 frame_pending = result.rendered;
354 inputs_pending = false;
355 last_result = Some(*result);
356 next_step += 1;
357 }
358 TraceRecord::Frame {
359 checksum,
360 checksum_chain: supplied_chain,
361 ..
362 } => {
363 if !frame_pending {
364 return Err(invalid(
365 "frame checkpoint has no rendered execution boundary",
366 ));
367 }
368 checksum_chain = fnv1a64_pair(checksum_chain, *checksum);
369 if *supplied_chain != checksum_chain {
370 return Err(invalid("frame checksum chain does not match its hashes"));
371 }
372 frame_pending = false;
373 frames += 1;
374 }
375 TraceRecord::Input { .. } | TraceRecord::Resize { .. } => {
376 if last_result.is_some_and(|result| !result.running) {
377 return Err(invalid(
378 "input cannot be admitted after the program stopped",
379 ));
380 }
381 queued += 1;
382 inputs_pending = true;
383 }
384 TraceRecord::Tick { .. } => inputs_pending = true,
385 TraceRecord::Summary { .. } => {
386 if last_result.is_none() || inputs_pending {
387 return Err(invalid("trace ends without an observed execution boundary"));
388 }
389 }
390 TraceRecord::Header { .. } => {}
391 }
392 }
393 Ok(())
394 }
395}
396
397pub struct SessionRecorder<M: ftui_runtime::program::Model> {
403 program: StepProgram<M>,
404 records: Vec<TraceRecord>,
405 checksum_chain: u64,
406 current_ts_ns: u64,
407 next_step_idx: u64,
408}
409
410impl<M: ftui_runtime::program::Model> SessionRecorder<M> {
411 #[must_use]
413 pub fn new(model: M, width: u16, height: u16, seed: u64) -> Self {
414 let program = StepProgram::new(model, width, height);
415 let records = vec![TraceRecord::Header {
416 seed,
417 cols: width,
418 rows: height,
419 profile: "modern".to_string(),
420 }];
421 Self {
422 program,
423 records,
424 checksum_chain: 0,
425 current_ts_ns: 0,
426 next_step_idx: 0,
427 }
428 }
429
430 pub fn init(&mut self) -> Result<(), WebBackendError> {
432 self.program.init()?;
433 let result = StepResult {
434 running: self.program.is_running(),
435 rendered: self.program.frame_idx() > 0,
436 events_processed: 0,
437 events_pending: self.program.pending_events(),
438 frame_idx: self.program.frame_idx(),
439 };
440 self.record_step(true, result);
441 Ok(())
442 }
443
444 pub fn push_event(&mut self, ts_ns: u64, event: Event) -> Result<(), WebBackendError> {
446 self.program.push_event(event.clone())?;
447 self.current_ts_ns = ts_ns;
448 self.records.push(TraceRecord::Input { ts_ns, event });
449 Ok(())
450 }
451
452 pub fn resize(&mut self, ts_ns: u64, width: u16, height: u16) -> Result<(), WebBackendError> {
454 self.program.resize(width, height)?;
455 self.current_ts_ns = ts_ns;
456 self.records.push(TraceRecord::Resize {
457 ts_ns,
458 cols: width,
459 rows: height,
460 });
461 Ok(())
462 }
463
464 pub fn advance_time(&mut self, ts_ns: u64, dt: Duration) {
466 self.current_ts_ns = ts_ns;
467 self.records.push(TraceRecord::Tick { ts_ns });
468 self.program.advance_time(dt);
469 }
470
471 pub fn step(&mut self) -> Result<StepResult, WebBackendError> {
473 let result = self.program.step()?;
474 self.record_step(false, result);
475 Ok(result)
476 }
477
478 pub fn finish(mut self) -> SessionTrace {
483 let total_frames = self
484 .records
485 .iter()
486 .filter(|r| matches!(r, TraceRecord::Frame { .. }))
487 .count() as u64;
488 self.records.push(TraceRecord::Summary {
489 total_frames,
490 final_checksum_chain: self.checksum_chain,
491 });
492 SessionTrace {
493 records: self.records,
494 }
495 }
496
497 pub fn program(&self) -> &StepProgram<M> {
499 &self.program
500 }
501
502 pub fn program_mut(&mut self) -> &mut StepProgram<M> {
507 &mut self.program
508 }
509
510 fn record_step(&mut self, init: bool, result: StepResult) {
511 self.records.push(TraceRecord::Step {
512 step_idx: self.next_step_idx,
513 ts_ns: self.current_ts_ns,
514 init,
515 clock: self.program.time(),
516 result,
517 });
518 self.next_step_idx += 1;
519 if result.rendered {
520 self.record_frame();
521 }
522 }
523
524 fn record_frame(&mut self) {
525 let outputs = self.program.outputs();
526 if let Some(buf) = &outputs.last_buffer {
527 let checksum = checksum_buffer(buf, self.program.pool());
528 let chain = fnv1a64_pair(self.checksum_chain, checksum);
529 self.records.push(TraceRecord::Frame {
530 frame_idx: self.program.frame_idx().saturating_sub(1),
531 ts_ns: self.current_ts_ns,
532 checksum,
533 checksum_chain: chain,
534 });
535 self.checksum_chain = chain;
536 }
537 }
538}
539
540#[derive(Debug, Clone, PartialEq, Eq)]
542pub struct ReplayResult {
543 pub total_steps: u64,
545 pub running: bool,
547 pub unprocessed_events: Vec<Event>,
549 pub total_frames: u64,
551 pub final_checksum_chain: u64,
553 pub first_mismatch: Option<ReplayMismatch>,
555}
556
557impl ReplayResult {
558 #[must_use]
561 pub fn ok(&self) -> bool {
562 self.first_mismatch.is_none()
563 }
564}
565
566#[derive(Debug, Clone, PartialEq, Eq)]
568pub struct ReplayMismatch {
569 pub frame_idx: u64,
571 pub expected: u64,
573 pub actual: u64,
575}
576
577#[derive(Debug, Clone, PartialEq, Eq)]
579pub enum ReplayError {
580 MissingHeader,
582 InvalidTrace(TraceValidationError),
584 Backend(WebBackendError),
586 StepMismatch {
588 step_idx: u64,
589 expected: StepResult,
590 actual: StepResult,
591 },
592 MissingFrame { frame_idx: u64 },
594}
595
596impl core::fmt::Display for ReplayError {
597 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
598 match self {
599 Self::MissingHeader => write!(f, "trace missing header record"),
600 Self::InvalidTrace(e) => write!(f, "invalid trace: {e}"),
601 Self::Backend(e) => write!(f, "backend error: {e}"),
602 Self::StepMismatch {
603 step_idx,
604 expected,
605 actual,
606 } => write!(
607 f,
608 "execution mismatch at step {step_idx}: expected {expected:?}, got {actual:?}"
609 ),
610 Self::MissingFrame { frame_idx } => write!(f, "missing rendered frame {frame_idx}"),
611 }
612 }
613}
614
615impl std::error::Error for ReplayError {}
616
617impl From<WebBackendError> for ReplayError {
618 fn from(e: WebBackendError) -> Self {
619 Self::Backend(e)
620 }
621}
622
623pub fn replay<M: ftui_runtime::program::Model>(
632 model: M,
633 trace: &SessionTrace,
634) -> Result<ReplayResult, ReplayError> {
635 let (cols, rows) = trace
637 .records
638 .first()
639 .and_then(|r| match r {
640 TraceRecord::Header { cols, rows, .. } => Some((*cols, *rows)),
641 _ => None,
642 })
643 .ok_or(ReplayError::MissingHeader)?;
644 trace.validate().map_err(ReplayError::InvalidTrace)?;
645
646 let mut program = StepProgram::new(model, cols, rows);
647
648 let mut replay_frame_idx: u64 = 0;
649 let mut total_steps = 0;
650 let mut checksum_chain: u64 = 0;
651 let mut first_mismatch: Option<ReplayMismatch> = None;
652
653 for record in &trace.records {
656 match record {
657 TraceRecord::Input { event, .. } => {
658 program.push_event(event.clone())?;
659 }
660 TraceRecord::Resize { cols, rows, .. } => {
661 program.resize(*cols, *rows)?;
662 }
663 TraceRecord::Step {
664 step_idx,
665 init,
666 clock,
667 result: expected,
668 ..
669 } => {
670 program.set_time(*clock);
671 let actual = if *init {
672 program.init()?;
673 StepResult {
674 running: program.is_running(),
675 rendered: program.frame_idx() > 0,
676 events_processed: 0,
677 events_pending: program.pending_events(),
678 frame_idx: program.frame_idx(),
679 }
680 } else {
681 program.step()?
682 };
683 if actual != *expected {
684 return Err(ReplayError::StepMismatch {
685 step_idx: *step_idx,
686 expected: *expected,
687 actual,
688 });
689 }
690 total_steps += 1;
691 }
692 TraceRecord::Frame {
693 frame_idx: expected_idx,
694 checksum: expected_checksum,
695 ..
696 } => {
697 let outputs = program.outputs();
699 if let Some(buf) = &outputs.last_buffer {
700 let actual = checksum_buffer(buf, program.pool());
701 checksum_chain = fnv1a64_pair(checksum_chain, actual);
702 if actual != *expected_checksum && first_mismatch.is_none() {
703 first_mismatch = Some(ReplayMismatch {
704 frame_idx: *expected_idx,
705 expected: *expected_checksum,
706 actual,
707 });
708 }
709 } else {
710 return Err(ReplayError::MissingFrame {
711 frame_idx: *expected_idx,
712 });
713 }
714 replay_frame_idx += 1;
715 }
716 TraceRecord::Header { .. } | TraceRecord::Summary { .. } | TraceRecord::Tick { .. } => {
717 }
718 }
719 }
720
721 Ok(ReplayResult {
722 total_steps,
723 running: program.is_running(),
724 unprocessed_events: program.take_pending_events(),
725 total_frames: replay_frame_idx,
726 final_checksum_chain: checksum_chain,
727 first_mismatch,
728 })
729}
730
731fn json_escape(input: &str) -> String {
734 let mut out = String::with_capacity(input.len() + 8);
735 for ch in input.chars() {
736 match ch {
737 '"' => out.push_str("\\\""),
738 '\\' => out.push_str("\\\\"),
739 '\n' => out.push_str("\\n"),
740 '\r' => out.push_str("\\r"),
741 '\t' => out.push_str("\\t"),
742 c if c.is_control() => {
743 use core::fmt::Write as _;
744 let _ = write!(out, "\\u{:04x}", c as u32);
745 }
746 c => out.push(c),
747 }
748 }
749 out
750}
751
752fn event_to_json(event: &Event) -> String {
753 match event {
754 Event::Key(k) => {
755 let code = key_code_to_str(k.code);
756 let mods = k.modifiers.bits();
757 let kind = key_event_kind_to_str(k.kind);
758 format!(
759 r#"{{"kind":"key","code":"{}","modifiers":{},"event_kind":"{}"}}"#,
760 json_escape(&code),
761 mods,
762 kind
763 )
764 }
765 Event::Mouse(m) => {
766 let kind = mouse_event_kind_to_str(m.kind);
767 let mods = m.modifiers.bits();
768 format!(
769 r#"{{"kind":"mouse","mouse_kind":"{}","x":{},"y":{},"modifiers":{}}}"#,
770 kind, m.x, m.y, mods
771 )
772 }
773 Event::Resize { width, height } => {
774 format!(
775 r#"{{"kind":"resize","width":{},"height":{}}}"#,
776 width, height
777 )
778 }
779 Event::Paste(p) => {
780 format!(
781 r#"{{"kind":"paste","text":"{}","bracketed":{}}}"#,
782 json_escape(&p.text),
783 p.bracketed
784 )
785 }
786 Event::Ime(ime) => {
787 format!(
788 r#"{{"kind":"ime","phase":"{}","text":"{}"}}"#,
789 ime_phase_to_str(ime.phase),
790 json_escape(&ime.text)
791 )
792 }
793 Event::Focus(gained) => {
794 format!(r#"{{"kind":"focus","gained":{}}}"#, gained)
795 }
796 Event::Clipboard(c) => {
797 let source = clipboard_source_to_str(c.source);
798 format!(
799 r#"{{"kind":"clipboard","content":"{}","source":"{}"}}"#,
800 json_escape(&c.content),
801 source
802 )
803 }
804 Event::TerminalResponse(_) | Event::Tick => r#"{"kind":"tick"}"#.to_string(),
805 }
806}
807
808fn key_code_to_str(code: KeyCode) -> String {
809 match code {
810 KeyCode::Char(c) => format!("char:{c}"),
811 KeyCode::Enter => "enter".to_string(),
812 KeyCode::Escape => "escape".to_string(),
813 KeyCode::Backspace => "backspace".to_string(),
814 KeyCode::Tab => "tab".to_string(),
815 KeyCode::BackTab => "backtab".to_string(),
816 KeyCode::Delete => "delete".to_string(),
817 KeyCode::Insert => "insert".to_string(),
818 KeyCode::Home => "home".to_string(),
819 KeyCode::End => "end".to_string(),
820 KeyCode::PageUp => "pageup".to_string(),
821 KeyCode::PageDown => "pagedown".to_string(),
822 KeyCode::Up => "up".to_string(),
823 KeyCode::Down => "down".to_string(),
824 KeyCode::Left => "left".to_string(),
825 KeyCode::Right => "right".to_string(),
826 KeyCode::F(n) => format!("f:{n}"),
827 KeyCode::Null => "null".to_string(),
828 KeyCode::MediaPlayPause => "media_play_pause".to_string(),
829 KeyCode::MediaStop => "media_stop".to_string(),
830 KeyCode::MediaNextTrack => "media_next".to_string(),
831 KeyCode::MediaPrevTrack => "media_prev".to_string(),
832 }
833}
834
835fn key_event_kind_to_str(kind: KeyEventKind) -> &'static str {
836 match kind {
837 KeyEventKind::Press => "press",
838 KeyEventKind::Repeat => "repeat",
839 KeyEventKind::Release => "release",
840 }
841}
842
843fn mouse_event_kind_to_str(kind: MouseEventKind) -> &'static str {
844 match kind {
845 MouseEventKind::Down(MouseButton::Left) => "down_left",
846 MouseEventKind::Down(MouseButton::Right) => "down_right",
847 MouseEventKind::Down(MouseButton::Middle) => "down_middle",
848 MouseEventKind::Up(MouseButton::Left) => "up_left",
849 MouseEventKind::Up(MouseButton::Right) => "up_right",
850 MouseEventKind::Up(MouseButton::Middle) => "up_middle",
851 MouseEventKind::Drag(MouseButton::Left) => "drag_left",
852 MouseEventKind::Drag(MouseButton::Right) => "drag_right",
853 MouseEventKind::Drag(MouseButton::Middle) => "drag_middle",
854 MouseEventKind::Moved => "moved",
855 MouseEventKind::ScrollUp => "scroll_up",
856 MouseEventKind::ScrollDown => "scroll_down",
857 MouseEventKind::ScrollLeft => "scroll_left",
858 MouseEventKind::ScrollRight => "scroll_right",
859 }
860}
861
862fn clipboard_source_to_str(source: ClipboardSource) -> &'static str {
863 match source {
864 ClipboardSource::Osc52 => "osc52",
865 ClipboardSource::Unknown => "unknown",
866 }
867}
868
869fn ime_phase_to_str(phase: ImePhase) -> &'static str {
870 match phase {
871 ImePhase::Start => "start",
872 ImePhase::Update => "update",
873 ImePhase::Commit => "commit",
874 ImePhase::Cancel => "cancel",
875 }
876}
877
878impl TraceRecord {
879 pub fn to_jsonl(&self) -> String {
881 match self {
882 TraceRecord::Header {
883 seed,
884 cols,
885 rows,
886 profile,
887 } => format!(
888 r#"{{"schema_version":"{}","event":"trace_header","seed":{},"cols":{},"rows":{},"env":{{"target":"web"}},"profile":"{}"}}"#,
889 SCHEMA_VERSION,
890 seed,
891 cols,
892 rows,
893 json_escape(profile)
894 ),
895 TraceRecord::Input { ts_ns, event } => format!(
896 r#"{{"schema_version":"{}","event":"input","ts_ns":{},"data":{}}}"#,
897 SCHEMA_VERSION,
898 ts_ns,
899 event_to_json(event)
900 ),
901 TraceRecord::Resize { ts_ns, cols, rows } => format!(
902 r#"{{"schema_version":"{}","event":"resize","ts_ns":{},"cols":{},"rows":{}}}"#,
903 SCHEMA_VERSION, ts_ns, cols, rows
904 ),
905 TraceRecord::Tick { ts_ns } => format!(
906 r#"{{"schema_version":"{}","event":"tick","ts_ns":{}}}"#,
907 SCHEMA_VERSION, ts_ns
908 ),
909 TraceRecord::Step {
910 step_idx,
911 ts_ns,
912 init,
913 clock,
914 result,
915 } => format!(
916 r#"{{"schema_version":"{}","event":"step","step_idx":{},"ts_ns":{},"init":{},"clock_secs":{},"clock_subsec_nanos":{},"running":{},"rendered":{},"events_processed":{},"events_pending":{},"frame_idx":{}}}"#,
917 SCHEMA_VERSION,
918 step_idx,
919 ts_ns,
920 init,
921 clock.as_secs(),
922 clock.subsec_nanos(),
923 result.running,
924 result.rendered,
925 result.events_processed,
926 result.events_pending,
927 result.frame_idx
928 ),
929 TraceRecord::Frame {
930 frame_idx,
931 ts_ns,
932 checksum,
933 checksum_chain,
934 } => format!(
935 r#"{{"schema_version":"{}","event":"frame","frame_idx":{},"ts_ns":{},"hash_algo":"fnv1a64","frame_hash":"{:016x}","checksum_chain":"{:016x}"}}"#,
936 SCHEMA_VERSION, frame_idx, ts_ns, checksum, checksum_chain
937 ),
938 TraceRecord::Summary {
939 total_frames,
940 final_checksum_chain,
941 } => format!(
942 r#"{{"schema_version":"{}","event":"trace_summary","total_frames":{},"final_checksum_chain":"{:016x}"}}"#,
943 SCHEMA_VERSION, total_frames, final_checksum_chain
944 ),
945 }
946 }
947}
948
949impl SessionTrace {
950 pub fn to_jsonl(&self) -> String {
952 let mut out = String::new();
953 for record in &self.records {
954 out.push_str(&record.to_jsonl());
955 out.push('\n');
956 }
957 out
958 }
959
960 pub fn from_jsonl(input: &str) -> Result<Self, TraceParseError> {
964 let mut records = Vec::new();
965 for (line_num, line) in input.lines().enumerate() {
966 let line = line.trim();
967 if line.is_empty() {
968 continue;
969 }
970 let record = parse_trace_line(line, line_num + 1)?;
971 records.push(record);
972 }
973 Ok(SessionTrace { records })
974 }
975
976 pub fn from_jsonl_validated(input: &str) -> Result<Self, TraceLoadError> {
978 let trace = Self::from_jsonl(input)?;
979 trace.validate()?;
980 Ok(trace)
981 }
982}
983
984#[derive(Debug, Clone, PartialEq, Eq)]
986pub struct TraceParseError {
987 pub line: usize,
988 pub message: String,
989}
990
991impl core::fmt::Display for TraceParseError {
992 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
993 write!(f, "line {}: {}", self.line, self.message)
994 }
995}
996
997impl std::error::Error for TraceParseError {}
998
999#[derive(Debug, Clone, PartialEq, Eq)]
1001pub enum TraceValidationError {
1002 InvalidExecution {
1003 record_index: usize,
1004 reason: &'static str,
1005 },
1006 EmptyTrace,
1007 MissingHeader,
1008 HeaderNotFirst,
1009 MultipleHeaders,
1010 MissingSummary,
1011 MultipleSummaries,
1012 SummaryNotLast {
1013 summary_index: usize,
1014 },
1015 TimestampRegression {
1016 previous: u64,
1017 current: u64,
1018 record_index: usize,
1019 },
1020 FrameIndexMismatch {
1021 expected: u64,
1022 actual: u64,
1023 },
1024 SummaryFrameCountMismatch {
1025 expected: u64,
1026 actual: u64,
1027 },
1028 SummaryChecksumChainMismatch {
1029 expected: u64,
1030 actual: u64,
1031 },
1032}
1033
1034impl core::fmt::Display for TraceValidationError {
1035 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1036 match self {
1037 Self::InvalidExecution {
1038 record_index,
1039 reason,
1040 } => {
1041 write!(f, "invalid execution at record {record_index}: {reason}")
1042 }
1043 Self::EmptyTrace => write!(f, "trace is empty"),
1044 Self::MissingHeader => write!(f, "trace is missing header"),
1045 Self::HeaderNotFirst => write!(f, "trace header is not the first record"),
1046 Self::MultipleHeaders => write!(f, "trace contains multiple headers"),
1047 Self::MissingSummary => write!(f, "trace is missing summary"),
1048 Self::MultipleSummaries => write!(f, "trace contains multiple summaries"),
1049 Self::SummaryNotLast { summary_index } => write!(
1050 f,
1051 "trace summary at index {} is not the final record",
1052 summary_index
1053 ),
1054 Self::TimestampRegression {
1055 previous,
1056 current,
1057 record_index,
1058 } => write!(
1059 f,
1060 "timestamp regression at record {}: current ts_ns={} is less than previous ts_ns={}",
1061 record_index, current, previous
1062 ),
1063 Self::FrameIndexMismatch { expected, actual } => {
1064 write!(
1065 f,
1066 "frame index mismatch: expected {}, got {}",
1067 expected, actual
1068 )
1069 }
1070 Self::SummaryFrameCountMismatch { expected, actual } => write!(
1071 f,
1072 "summary frame-count mismatch: expected {}, got {}",
1073 expected, actual
1074 ),
1075 Self::SummaryChecksumChainMismatch { expected, actual } => write!(
1076 f,
1077 "summary checksum-chain mismatch: expected {:016x}, got {:016x}",
1078 expected, actual
1079 ),
1080 }
1081 }
1082}
1083
1084impl std::error::Error for TraceValidationError {}
1085
1086#[derive(Debug, Clone, PartialEq, Eq)]
1088pub enum TraceLoadError {
1089 Parse(TraceParseError),
1090 Validation(TraceValidationError),
1091}
1092
1093impl core::fmt::Display for TraceLoadError {
1094 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1095 match self {
1096 Self::Parse(e) => write!(f, "{e}"),
1097 Self::Validation(e) => write!(f, "{e}"),
1098 }
1099 }
1100}
1101
1102impl std::error::Error for TraceLoadError {}
1103
1104impl From<TraceParseError> for TraceLoadError {
1105 fn from(value: TraceParseError) -> Self {
1106 Self::Parse(value)
1107 }
1108}
1109
1110impl From<TraceValidationError> for TraceLoadError {
1111 fn from(value: TraceValidationError) -> Self {
1112 Self::Validation(value)
1113 }
1114}
1115
1116fn json_string_end(input: &str) -> Option<usize> {
1119 let bytes = input.as_bytes();
1120 if bytes.first() != Some(&b'"') {
1121 return None;
1122 }
1123 let mut i = 1;
1124 while i < bytes.len() {
1125 if bytes[i] == b'\\' {
1126 i += 2;
1127 continue;
1128 }
1129 if bytes[i] == b'"' {
1130 return Some(i + 1);
1131 }
1132 if bytes[i] < 0x20 {
1133 return None;
1134 }
1135 i += 1;
1136 }
1137 None
1138}
1139
1140fn json_value_end(input: &str) -> Option<usize> {
1141 match input.as_bytes().first()? {
1142 b'"' => json_string_end(input),
1143 b'{' | b'[' => {
1144 let mut closing = Vec::new();
1145 let mut index = 0;
1146 while index < input.len() {
1147 match input.as_bytes()[index] {
1148 b'"' => {
1149 index += json_string_end(&input[index..])?;
1150 continue;
1151 }
1152 b'{' => closing.push(b'}'),
1153 b'[' => closing.push(b']'),
1154 byte @ (b'}' | b']') => {
1155 if closing.pop()? != byte {
1156 return None;
1157 }
1158 if closing.is_empty() {
1159 return Some(index + 1);
1160 }
1161 }
1162 _ => {}
1163 }
1164 index += 1;
1165 }
1166 None
1167 }
1168 _ => Some(input.find([',', '}', ']']).unwrap_or(input.len())),
1169 }
1170}
1171
1172fn extract_value<'a>(json: &'a str, key: &str) -> Option<&'a str> {
1175 let mut rest = json.trim().strip_prefix('{')?.trim_start();
1176 let mut found = None;
1177 if rest == "}" {
1178 return None;
1179 }
1180 loop {
1181 let key_end = json_string_end(rest)?;
1182 let field_key = &rest[1..key_end - 1];
1183 rest = rest[key_end..].trim_start().strip_prefix(':')?.trim_start();
1184 let value_end = json_value_end(rest)?;
1185 let value = rest[..value_end].trim();
1186 if value.is_empty() {
1187 return None;
1188 }
1189 if field_key == key {
1190 if found.is_some() {
1191 return None;
1192 }
1193 found = Some(value);
1194 }
1195 rest = rest[value_end..].trim_start();
1196 if rest == "}" {
1197 return found;
1198 }
1199 rest = rest.strip_prefix(',')?.trim_start();
1200 }
1201}
1202
1203fn extract_str<'a>(json: &'a str, key: &str) -> Option<&'a str> {
1204 extract_value(json, key)?
1205 .strip_prefix('"')?
1206 .strip_suffix('"')
1207}
1208
1209fn extract_u64(json: &str, key: &str) -> Option<u64> {
1210 let value = extract_value(json, key)?;
1211 if !value.bytes().all(|byte| byte.is_ascii_digit())
1212 || (value.len() > 1 && value.starts_with('0'))
1213 {
1214 return None;
1215 }
1216 value.parse().ok()
1217}
1218
1219fn extract_i64(json: &str, key: &str) -> Option<i64> {
1220 let value = extract_value(json, key)?;
1221 let digits = value.strip_prefix('-').unwrap_or(value);
1222 if !digits.bytes().all(|byte| byte.is_ascii_digit())
1223 || (digits.len() > 1 && digits.starts_with('0'))
1224 {
1225 return None;
1226 }
1227 value.parse().ok()
1228}
1229
1230fn extract_u16(json: &str, key: &str) -> Option<u16> {
1231 extract_u64(json, key).and_then(|v| u16::try_from(v).ok())
1232}
1233
1234fn extract_bool(json: &str, key: &str) -> Option<bool> {
1235 match extract_value(json, key)? {
1236 "true" => Some(true),
1237 "false" => Some(false),
1238 _ => None,
1239 }
1240}
1241
1242fn extract_hex_u64(json: &str, key: &str) -> Option<u64> {
1243 let s = extract_str(json, key)?;
1244 u64::from_str_radix(s, 16).ok()
1245}
1246
1247fn extract_object<'a>(json: &'a str, key: &str) -> Option<&'a str> {
1248 let value = extract_value(json, key)?;
1249 (value.starts_with('{') && value.ends_with('}')).then_some(value)
1250}
1251
1252fn json_unescape(input: &str) -> Result<String, String> {
1253 fn hex_unit(chars: &mut core::str::Chars<'_>) -> Result<u32, String> {
1254 let mut unit = 0;
1255 for _ in 0..4 {
1256 let digit = chars
1257 .next()
1258 .and_then(|ch| ch.to_digit(16))
1259 .ok_or("invalid JSON Unicode escape")?;
1260 unit = unit * 16 + digit;
1261 }
1262 Ok(unit)
1263 }
1264
1265 let mut out = String::with_capacity(input.len());
1266 let mut chars = input.chars();
1267 while let Some(ch) = chars.next() {
1268 if ch == '\\' {
1269 match chars.next() {
1270 Some('"') => out.push('"'),
1271 Some('\\') => out.push('\\'),
1272 Some('/') => out.push('/'),
1273 Some('b') => out.push('\u{0008}'),
1274 Some('f') => out.push('\u{000c}'),
1275 Some('n') => out.push('\n'),
1276 Some('r') => out.push('\r'),
1277 Some('t') => out.push('\t'),
1278 Some('u') => {
1279 let mut cp = hex_unit(&mut chars)?;
1280 if (0xd800..=0xdbff).contains(&cp) {
1281 if chars.next() != Some('\\') || chars.next() != Some('u') {
1282 return Err("missing JSON low surrogate".to_string());
1283 }
1284 let low = hex_unit(&mut chars)?;
1285 if !(0xdc00..=0xdfff).contains(&low) {
1286 return Err("invalid JSON low surrogate".to_string());
1287 }
1288 cp = 0x10000 + ((cp - 0xd800) << 10) + (low - 0xdc00);
1289 }
1290 out.push(char::from_u32(cp).ok_or("invalid JSON Unicode scalar")?);
1291 }
1292 Some(_) => return Err("invalid JSON escape".to_string()),
1293 None => return Err("incomplete JSON escape".to_string()),
1294 }
1295 } else {
1296 out.push(ch);
1297 }
1298 }
1299 Ok(out)
1300}
1301
1302fn check_trace_schema_compat(schema_version: &str, line_num: usize) -> Result<(), TraceParseError> {
1303 let incompatible = schema_version != SCHEMA_VERSION;
1304
1305 #[cfg(feature = "tracing")]
1306 {
1307 let span = info_span!(
1308 "trace.compat_check",
1309 reader_schema_version = SCHEMA_VERSION,
1310 writer_schema_version = schema_version,
1311 line = line_num,
1312 compatible = !incompatible,
1313 );
1314 let _guard = span.enter();
1315
1316 if incompatible {
1317 error!(
1318 reader_schema_version = SCHEMA_VERSION,
1319 writer_schema_version = schema_version,
1320 line = line_num,
1321 "trace schema version incompatible"
1322 );
1323 }
1324 }
1325
1326 if incompatible {
1327 return Err(TraceParseError {
1328 line: line_num,
1329 message: format!(
1330 "unsupported schema_version: {schema_version} (reader={SCHEMA_VERSION}, migration required)"
1331 ),
1332 });
1333 }
1334 Ok(())
1335}
1336
1337fn parse_trace_line(line: &str, line_num: usize) -> Result<TraceRecord, TraceParseError> {
1338 let err = |msg: &str| TraceParseError {
1339 line: line_num,
1340 message: msg.to_string(),
1341 };
1342
1343 let schema_version = extract_str(line, "schema_version")
1344 .ok_or_else(|| err("missing \"schema_version\" field"))?;
1345 check_trace_schema_compat(schema_version, line_num)?;
1346
1347 let event = extract_str(line, "event").ok_or_else(|| err("missing \"event\" field"))?;
1348
1349 match event {
1350 "trace_header" => {
1351 let seed = extract_u64(line, "seed").unwrap_or(0);
1352 let cols = extract_u16(line, "cols").ok_or_else(|| err("missing cols"))?;
1353 let rows = extract_u16(line, "rows").ok_or_else(|| err("missing rows"))?;
1354 let profile = extract_str(line, "profile")
1355 .map(|s| s.to_string())
1356 .unwrap_or_else(|| "modern".to_string());
1357 Ok(TraceRecord::Header {
1358 seed,
1359 cols,
1360 rows,
1361 profile,
1362 })
1363 }
1364 "input" => {
1365 let ts_ns = extract_u64(line, "ts_ns").ok_or_else(|| err("missing ts_ns"))?;
1366 let data = extract_object(line, "data").ok_or_else(|| err("missing data object"))?;
1367 let event = parse_event_json(data).map_err(|e| err(&e))?;
1368 Ok(TraceRecord::Input { ts_ns, event })
1369 }
1370 "resize" => {
1371 let ts_ns = extract_u64(line, "ts_ns").ok_or_else(|| err("missing ts_ns"))?;
1372 let cols = extract_u16(line, "cols").ok_or_else(|| err("missing cols"))?;
1373 let rows = extract_u16(line, "rows").ok_or_else(|| err("missing rows"))?;
1374 Ok(TraceRecord::Resize { ts_ns, cols, rows })
1375 }
1376 "tick" => {
1377 let ts_ns = extract_u64(line, "ts_ns").ok_or_else(|| err("missing ts_ns"))?;
1378 Ok(TraceRecord::Tick { ts_ns })
1379 }
1380 "step" => {
1381 let required_u64 = |key| {
1382 extract_u64(line, key).ok_or_else(|| err(&format!("missing or invalid {key}")))
1383 };
1384 let required_u32 = |key| {
1385 required_u64(key).and_then(|value| {
1386 u32::try_from(value).map_err(|_| err(&format!("{key} out of range")))
1387 })
1388 };
1389 let required_bool = |key| {
1390 extract_bool(line, key).ok_or_else(|| err(&format!("missing or invalid {key}")))
1391 };
1392 let nanos = required_u32("clock_subsec_nanos")?;
1393 if nanos >= 1_000_000_000 {
1394 return Err(err("clock_subsec_nanos must be less than 1000000000"));
1395 }
1396 Ok(TraceRecord::Step {
1397 step_idx: required_u64("step_idx")?,
1398 ts_ns: required_u64("ts_ns")?,
1399 init: required_bool("init")?,
1400 clock: Duration::new(required_u64("clock_secs")?, nanos),
1401 result: StepResult {
1402 running: required_bool("running")?,
1403 rendered: required_bool("rendered")?,
1404 events_processed: required_u32("events_processed")?,
1405 events_pending: required_u32("events_pending")?,
1406 frame_idx: required_u64("frame_idx")?,
1407 },
1408 })
1409 }
1410 "frame" => {
1411 let frame_idx =
1412 extract_u64(line, "frame_idx").ok_or_else(|| err("missing frame_idx"))?;
1413 let ts_ns = extract_u64(line, "ts_ns").ok_or_else(|| err("missing ts_ns"))?;
1414 let checksum =
1415 extract_hex_u64(line, "frame_hash").ok_or_else(|| err("missing frame_hash"))?;
1416 let checksum_chain = extract_hex_u64(line, "checksum_chain")
1417 .ok_or_else(|| err("missing checksum_chain"))?;
1418 Ok(TraceRecord::Frame {
1419 frame_idx,
1420 ts_ns,
1421 checksum,
1422 checksum_chain,
1423 })
1424 }
1425 "trace_summary" => {
1426 let total_frames =
1427 extract_u64(line, "total_frames").ok_or_else(|| err("missing total_frames"))?;
1428 let final_checksum_chain = extract_hex_u64(line, "final_checksum_chain")
1429 .ok_or_else(|| err("missing final_checksum_chain"))?;
1430 Ok(TraceRecord::Summary {
1431 total_frames,
1432 final_checksum_chain,
1433 })
1434 }
1435 other => Err(err(&format!("unknown event type: {other}"))),
1436 }
1437}
1438
1439fn parse_event_json(data: &str) -> Result<Event, String> {
1440 let kind = extract_str(data, "kind").ok_or("missing event kind")?;
1441 match kind {
1442 "key" => {
1443 let code_str = extract_str(data, "code").ok_or("missing key code")?;
1444 let code = parse_key_code(&json_unescape(code_str)?)?;
1445 let mods_bits = extract_u64(data, "modifiers")
1446 .or(extract_u64(data, "mods"))
1447 .unwrap_or(0) as u8;
1448 let modifiers = Modifiers::from_bits(mods_bits).unwrap_or_else(Modifiers::empty);
1449 let event_kind = if let Some(event_kind_str) = extract_str(data, "event_kind") {
1450 match event_kind_str {
1451 "press" => KeyEventKind::Press,
1452 "repeat" => KeyEventKind::Repeat,
1453 "release" => KeyEventKind::Release,
1454 _ => KeyEventKind::Press,
1455 }
1456 } else {
1457 let phase = extract_str(data, "phase").unwrap_or("down");
1458 let repeat = extract_bool(data, "repeat").unwrap_or(false);
1459 parse_key_event_kind(phase, repeat)
1460 };
1461 Ok(Event::Key(KeyEvent {
1462 code,
1463 modifiers,
1464 kind: event_kind,
1465 }))
1466 }
1467 "mouse" => {
1468 let mouse_kind = if let Some(mouse_kind_str) = extract_str(data, "mouse_kind") {
1469 parse_mouse_event_kind(mouse_kind_str)?
1470 } else {
1471 let phase = extract_str(data, "phase").ok_or("missing phase for mouse event")?;
1472 let button = extract_u64(data, "button")
1473 .map(|raw| {
1474 u8::try_from(raw).map_err(|_| "mouse button out of range".to_string())
1475 })
1476 .transpose()?;
1477 parse_mouse_phase_and_button(phase, button)?
1478 };
1479 let x = extract_u16(data, "x").unwrap_or(0);
1480 let y = extract_u16(data, "y").unwrap_or(0);
1481 let mods_bits = extract_u64(data, "modifiers")
1482 .or(extract_u64(data, "mods"))
1483 .unwrap_or(0) as u8;
1484 let modifiers = Modifiers::from_bits(mods_bits).unwrap_or_else(Modifiers::empty);
1485 Ok(Event::Mouse(MouseEvent {
1486 kind: mouse_kind,
1487 x,
1488 y,
1489 pixel: None,
1490 modifiers,
1491 }))
1492 }
1493 "wheel" => {
1494 let x = extract_u16(data, "x").unwrap_or(0);
1495 let y = extract_u16(data, "y").unwrap_or(0);
1496 let dx = extract_i64(data, "dx")
1497 .and_then(|value| i16::try_from(value).ok())
1498 .unwrap_or(0);
1499 let dy = extract_i64(data, "dy")
1500 .and_then(|value| i16::try_from(value).ok())
1501 .unwrap_or(0);
1502 let kind = if dy < 0 {
1503 MouseEventKind::ScrollUp
1504 } else if dy > 0 {
1505 MouseEventKind::ScrollDown
1506 } else if dx < 0 {
1507 MouseEventKind::ScrollLeft
1508 } else if dx > 0 {
1509 MouseEventKind::ScrollRight
1510 } else {
1511 return Err("wheel event must include non-zero dx or dy".to_string());
1512 };
1513 let mods_bits = extract_u64(data, "modifiers")
1514 .or(extract_u64(data, "mods"))
1515 .unwrap_or(0) as u8;
1516 let modifiers = Modifiers::from_bits(mods_bits).unwrap_or_else(Modifiers::empty);
1517 Ok(Event::Mouse(MouseEvent {
1518 kind,
1519 x,
1520 y,
1521 pixel: None,
1522 modifiers,
1523 }))
1524 }
1525 "resize" => {
1526 let width = extract_u16(data, "width").ok_or("missing width")?;
1527 let height = extract_u16(data, "height").ok_or("missing height")?;
1528 Ok(Event::Resize { width, height })
1529 }
1530 "paste" => {
1531 let text = extract_str(data, "text")
1532 .or(extract_str(data, "data"))
1533 .map(json_unescape)
1534 .transpose()?
1535 .unwrap_or_default();
1536 let bracketed = extract_bool(data, "bracketed").unwrap_or(true);
1537 Ok(Event::Paste(PasteEvent::new(text, bracketed)))
1538 }
1539 "ime" | "composition" => {
1540 let phase_raw = extract_str(data, "phase").unwrap_or("update");
1541 let phase = parse_ime_phase(phase_raw)?;
1542 let text = extract_str(data, "text")
1543 .or(extract_str(data, "data"))
1544 .map(json_unescape)
1545 .transpose()?
1546 .unwrap_or_default();
1547 let ime = match phase {
1548 ImePhase::Start => ImeEvent::start(),
1549 ImePhase::Update => ImeEvent::update(text),
1550 ImePhase::Commit => ImeEvent::commit(text),
1551 ImePhase::Cancel => ImeEvent::cancel(),
1552 };
1553 Ok(Event::Ime(ime))
1554 }
1555 "focus" => {
1556 let gained = extract_bool(data, "gained")
1557 .or(extract_bool(data, "focused"))
1558 .unwrap_or(true);
1559 Ok(Event::Focus(gained))
1560 }
1561 "clipboard" => {
1562 let content = extract_str(data, "content")
1563 .map(json_unescape)
1564 .transpose()?
1565 .unwrap_or_default();
1566 let source_str = extract_str(data, "source").unwrap_or("unknown");
1567 let source = match source_str {
1568 "osc52" => ClipboardSource::Osc52,
1569 _ => ClipboardSource::Unknown,
1570 };
1571 Ok(Event::Clipboard(ClipboardEvent::new(content, source)))
1572 }
1573 "tick" => Ok(Event::Tick),
1574 other => Err(format!("unknown event kind: {other}")),
1575 }
1576}
1577
1578fn parse_ime_phase(phase: &str) -> Result<ImePhase, String> {
1579 match phase {
1580 "start" => Ok(ImePhase::Start),
1581 "update" => Ok(ImePhase::Update),
1582 "end" | "commit" => Ok(ImePhase::Commit),
1583 "cancel" => Ok(ImePhase::Cancel),
1584 other => Err(format!("unknown ime/composition phase: {other}")),
1585 }
1586}
1587
1588fn parse_key_code(s: &str) -> Result<KeyCode, String> {
1589 if let Some(rest) = s.strip_prefix("char:") {
1590 let ch = rest.chars().next().ok_or("empty char code")?;
1591 return Ok(KeyCode::Char(ch));
1592 }
1593 if let Some(rest) = s.strip_prefix("f:") {
1594 let n: u8 = rest.parse().map_err(|_| "invalid F-key number")?;
1595 return Ok(KeyCode::F(n));
1596 }
1597 if let Some(n) = parse_function_key_token(s) {
1598 return Ok(KeyCode::F(n));
1599 }
1600
1601 let mut chars = s.chars();
1602 if let Some(ch) = chars.next()
1603 && chars.next().is_none()
1604 {
1605 return Ok(KeyCode::Char(ch));
1606 }
1607
1608 let normalized = s.to_ascii_lowercase();
1609 match normalized.as_str() {
1610 "enter" | "return" => Ok(KeyCode::Enter),
1611 "escape" | "esc" => Ok(KeyCode::Escape),
1612 "backspace" => Ok(KeyCode::Backspace),
1613 "tab" => Ok(KeyCode::Tab),
1614 "backtab" => Ok(KeyCode::BackTab),
1615 "delete" => Ok(KeyCode::Delete),
1616 "insert" => Ok(KeyCode::Insert),
1617 "home" => Ok(KeyCode::Home),
1618 "end" => Ok(KeyCode::End),
1619 "pageup" => Ok(KeyCode::PageUp),
1620 "pagedown" => Ok(KeyCode::PageDown),
1621 "up" | "arrowup" => Ok(KeyCode::Up),
1622 "down" | "arrowdown" => Ok(KeyCode::Down),
1623 "left" | "arrowleft" => Ok(KeyCode::Left),
1624 "right" | "arrowright" => Ok(KeyCode::Right),
1625 "null" | "unidentified" => Ok(KeyCode::Null),
1626 "media_play_pause" => Ok(KeyCode::MediaPlayPause),
1627 "media_stop" => Ok(KeyCode::MediaStop),
1628 "media_next" => Ok(KeyCode::MediaNextTrack),
1629 "media_prev" => Ok(KeyCode::MediaPrevTrack),
1630 other => Err(format!("unknown key code: {other}")),
1631 }
1632}
1633
1634fn parse_function_key_token(s: &str) -> Option<u8> {
1635 let rest = s.strip_prefix('F').or_else(|| s.strip_prefix('f'))?;
1636 if rest.is_empty() || !rest.chars().all(|ch| ch.is_ascii_digit()) {
1637 return None;
1638 }
1639 rest.parse().ok()
1640}
1641
1642fn parse_key_event_kind(phase: &str, repeat: bool) -> KeyEventKind {
1643 if phase.eq_ignore_ascii_case("up") || phase.eq_ignore_ascii_case("release") {
1644 KeyEventKind::Release
1645 } else if repeat {
1646 KeyEventKind::Repeat
1647 } else {
1648 KeyEventKind::Press
1649 }
1650}
1651
1652fn parse_mouse_event_kind(s: &str) -> Result<MouseEventKind, String> {
1653 match s {
1654 "down_left" => Ok(MouseEventKind::Down(MouseButton::Left)),
1655 "down_right" => Ok(MouseEventKind::Down(MouseButton::Right)),
1656 "down_middle" => Ok(MouseEventKind::Down(MouseButton::Middle)),
1657 "up_left" => Ok(MouseEventKind::Up(MouseButton::Left)),
1658 "up_right" => Ok(MouseEventKind::Up(MouseButton::Right)),
1659 "up_middle" => Ok(MouseEventKind::Up(MouseButton::Middle)),
1660 "drag_left" => Ok(MouseEventKind::Drag(MouseButton::Left)),
1661 "drag_right" => Ok(MouseEventKind::Drag(MouseButton::Right)),
1662 "drag_middle" => Ok(MouseEventKind::Drag(MouseButton::Middle)),
1663 "moved" => Ok(MouseEventKind::Moved),
1664 "scroll_up" => Ok(MouseEventKind::ScrollUp),
1665 "scroll_down" => Ok(MouseEventKind::ScrollDown),
1666 "scroll_left" => Ok(MouseEventKind::ScrollLeft),
1667 "scroll_right" => Ok(MouseEventKind::ScrollRight),
1668 other => Err(format!("unknown mouse event kind: {other}")),
1669 }
1670}
1671
1672fn parse_mouse_phase_and_button(phase: &str, button: Option<u8>) -> Result<MouseEventKind, String> {
1673 match phase {
1674 "down" => Ok(MouseEventKind::Down(parse_mouse_button(
1675 button.ok_or("mouse down requires button")?,
1676 )?)),
1677 "up" => Ok(MouseEventKind::Up(parse_mouse_button(
1678 button.ok_or("mouse up requires button")?,
1679 )?)),
1680 "drag" => Ok(MouseEventKind::Drag(parse_mouse_button(
1681 button.ok_or("mouse drag requires button")?,
1682 )?)),
1683 "move" => Ok(MouseEventKind::Moved),
1684 other => Err(format!("unknown mouse phase: {other}")),
1685 }
1686}
1687
1688fn parse_mouse_button(raw: u8) -> Result<MouseButton, String> {
1689 match raw {
1690 0 => Ok(MouseButton::Left),
1691 1 => Ok(MouseButton::Middle),
1692 2 => Ok(MouseButton::Right),
1693 other => Err(format!("unsupported mouse button: {other}")),
1694 }
1695}
1696
1697pub fn gate_trace<M: ftui_runtime::program::Model>(
1705 model: M,
1706 trace: &SessionTrace,
1707) -> Result<GateReport, ReplayError> {
1708 let result = replay(model, trace)?;
1709
1710 let frame_checksums: Vec<(u64, u64)> = trace
1711 .records
1712 .iter()
1713 .filter_map(|r| match r {
1714 TraceRecord::Frame {
1715 frame_idx,
1716 checksum,
1717 ..
1718 } => Some((*frame_idx, *checksum)),
1719 _ => None,
1720 })
1721 .collect();
1722
1723 let diff = result.first_mismatch.as_ref().map(|m| {
1724 let mut event_idx: u64 = 0;
1726 let mut last_event_desc = String::new();
1727 let mut frame_count: u64 = 0;
1728 for record in &trace.records {
1729 match record {
1730 TraceRecord::Frame { .. } => {
1731 if frame_count == m.frame_idx {
1732 break;
1733 }
1734 frame_count += 1;
1735 }
1736 TraceRecord::Input { event, .. } => {
1737 last_event_desc = format!("{event:?}");
1738 event_idx += 1;
1739 }
1740 TraceRecord::Resize { cols, rows, .. } => {
1741 last_event_desc = format!("Resize({cols}x{rows})");
1742 event_idx += 1;
1743 }
1744 TraceRecord::Tick { ts_ns } => {
1745 last_event_desc = format!("Tick(ts_ns={ts_ns})");
1746 event_idx += 1;
1747 }
1748 _ => {}
1749 }
1750 }
1751
1752 GateDiff {
1753 frame_idx: m.frame_idx,
1754 event_idx,
1755 last_event: last_event_desc,
1756 expected_checksum: m.expected,
1757 actual_checksum: m.actual,
1758 }
1759 });
1760
1761 Ok(GateReport {
1762 passed: result.ok(),
1763 total_steps: result.total_steps,
1764 running: result.running,
1765 unprocessed_events: result.unprocessed_events,
1766 total_frames: result.total_frames,
1767 expected_frames: frame_checksums.len() as u64,
1768 final_checksum_chain: result.final_checksum_chain,
1769 diff,
1770 })
1771}
1772
1773#[derive(Debug, Clone)]
1775pub struct GateReport {
1776 pub passed: bool,
1778 pub total_steps: u64,
1780 pub running: bool,
1782 pub unprocessed_events: Vec<Event>,
1784 pub total_frames: u64,
1786 pub expected_frames: u64,
1788 pub final_checksum_chain: u64,
1790 pub diff: Option<GateDiff>,
1792}
1793
1794impl GateReport {
1795 pub fn format(&self) -> String {
1797 if self.passed {
1798 format!(
1799 "PASS: {}/{} frames verified, final_chain={:016x}, steps={}, running={}, unprocessed_events={}",
1800 self.total_frames,
1801 self.expected_frames,
1802 self.final_checksum_chain,
1803 self.total_steps,
1804 self.running,
1805 self.unprocessed_events.len()
1806 )
1807 } else if let Some(d) = &self.diff {
1808 format!(
1809 "FAIL at frame {} (after event #{}: {}): expected {:016x}, got {:016x}",
1810 d.frame_idx, d.event_idx, d.last_event, d.expected_checksum, d.actual_checksum
1811 )
1812 } else {
1813 format!(
1814 "FAIL: {}/{} frames, unknown mismatch",
1815 self.total_frames, self.expected_frames
1816 )
1817 }
1818 }
1819}
1820
1821#[derive(Debug, Clone)]
1823pub struct GateDiff {
1824 pub frame_idx: u64,
1826 pub event_idx: u64,
1828 pub last_event: String,
1830 pub expected_checksum: u64,
1832 pub actual_checksum: u64,
1834}
1835
1836#[cfg(test)]
1837mod tests {
1838 use super::*;
1839 use ftui_core::event::{
1840 KeyCode, KeyEvent, KeyEventKind, Modifiers, MouseButton, MouseEvent, MouseEventKind,
1841 PasteEvent,
1842 };
1843 use ftui_render::cell::Cell;
1844 use ftui_render::frame::Frame;
1845 use ftui_runtime::program::{Cmd, Model};
1846 use pretty_assertions::assert_eq;
1847 #[cfg(feature = "tracing")]
1848 use std::sync::{Arc, Mutex};
1849 #[cfg(feature = "tracing")]
1850 use tracing::Subscriber;
1851 #[cfg(feature = "tracing")]
1852 use tracing::field::{Field, Visit};
1853 #[cfg(feature = "tracing")]
1854 use tracing_subscriber::Layer;
1855 #[cfg(feature = "tracing")]
1856 use tracing_subscriber::filter::LevelFilter;
1857 #[cfg(feature = "tracing")]
1858 use tracing_subscriber::layer::{Context, SubscriberExt};
1859 #[cfg(feature = "tracing")]
1860 use tracing_subscriber::registry::LookupSpan;
1861
1862 #[cfg(feature = "tracing")]
1863 #[derive(Default, Clone)]
1864 struct TraceCaptureLayer {
1865 spans: Arc<Mutex<Vec<String>>>,
1866 events: Arc<Mutex<Vec<String>>>,
1867 }
1868
1869 #[cfg(feature = "tracing")]
1870 #[derive(Default)]
1871 struct EventMessageVisitor {
1872 message: Option<String>,
1873 }
1874
1875 #[cfg(feature = "tracing")]
1876 impl Visit for EventMessageVisitor {
1877 fn record_str(&mut self, field: &Field, value: &str) {
1878 if field.name() == "message" {
1879 self.message = Some(value.to_string());
1880 }
1881 }
1882
1883 fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) {
1884 if field.name() == "message" {
1885 self.message = Some(format!("{value:?}"));
1886 }
1887 }
1888 }
1889
1890 #[cfg(feature = "tracing")]
1891 impl<S> Layer<S> for TraceCaptureLayer
1892 where
1893 S: Subscriber + for<'lookup> LookupSpan<'lookup>,
1894 {
1895 fn on_new_span(
1896 &self,
1897 attrs: &tracing::span::Attributes<'_>,
1898 _id: &tracing::span::Id,
1899 _ctx: Context<'_, S>,
1900 ) {
1901 self.spans
1902 .lock()
1903 .expect("span capture lock")
1904 .push(attrs.metadata().name().to_string());
1905 }
1906
1907 fn on_event(&self, event: &tracing::Event<'_>, _ctx: Context<'_, S>) {
1908 let mut visitor = EventMessageVisitor::default();
1909 event.record(&mut visitor);
1910 let message = visitor.message.unwrap_or_default();
1911 self.events
1912 .lock()
1913 .expect("event capture lock")
1914 .push(format!("{}:{}", event.metadata().level(), message));
1915 }
1916 }
1917
1918 struct Counter {
1921 value: i32,
1922 }
1923
1924 #[derive(Debug)]
1925 enum CounterMsg {
1926 Increment,
1927 Decrement,
1928 Reset,
1929 Quit,
1930 }
1931
1932 impl From<Event> for CounterMsg {
1933 fn from(event: Event) -> Self {
1934 match event {
1935 Event::Key(k) if k.code == KeyCode::Char('+') => CounterMsg::Increment,
1936 Event::Key(k) if k.code == KeyCode::Char('-') => CounterMsg::Decrement,
1937 Event::Key(k) if k.code == KeyCode::Char('r') => CounterMsg::Reset,
1938 Event::Key(k) if k.code == KeyCode::Char('q') => CounterMsg::Quit,
1939 Event::Tick => CounterMsg::Increment,
1940 _ => CounterMsg::Increment,
1941 }
1942 }
1943 }
1944
1945 impl Model for Counter {
1946 type Message = CounterMsg;
1947
1948 fn init(&mut self) -> Cmd<Self::Message> {
1949 Cmd::none()
1950 }
1951
1952 fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
1953 match msg {
1954 CounterMsg::Increment => {
1955 self.value += 1;
1956 Cmd::none()
1957 }
1958 CounterMsg::Decrement => {
1959 self.value -= 1;
1960 Cmd::none()
1961 }
1962 CounterMsg::Reset => {
1963 self.value = 0;
1964 Cmd::none()
1965 }
1966 CounterMsg::Quit => Cmd::quit(),
1967 }
1968 }
1969
1970 fn view(&self, frame: &mut Frame) {
1971 let text = format!("Count: {}", self.value);
1972 for (i, c) in text.chars().enumerate() {
1973 if (i as u16) < frame.width() {
1974 frame.buffer.set_raw(i as u16, 0, Cell::from_char(c));
1975 }
1976 }
1977 }
1978 }
1979
1980 fn key_event(c: char) -> Event {
1981 Event::Key(KeyEvent {
1982 code: KeyCode::Char(c),
1983 modifiers: Modifiers::empty(),
1984 kind: KeyEventKind::Press,
1985 })
1986 }
1987
1988 fn parse_single_input_event(data_json: &str) -> Event {
1989 let line = format!(
1990 r#"{{"schema_version":"{}","event":"input","ts_ns":0,"data":{}}}"#,
1991 SCHEMA_VERSION, data_json
1992 );
1993 let trace = SessionTrace::from_jsonl(&line).expect("input JSON should parse");
1994 trace
1995 .records
1996 .into_iter()
1997 .next()
1998 .and_then(|record| match record {
1999 TraceRecord::Input { event, .. } => Some(event),
2000 _ => None,
2001 })
2002 .expect("expected single input record")
2003 }
2004
2005 fn new_counter(value: i32) -> Counter {
2006 Counter { value }
2007 }
2008
2009 struct ObservedModel {
2011 seen: std::rc::Rc<std::cell::RefCell<Vec<Event>>>,
2012 init_count: std::rc::Rc<std::cell::Cell<u32>>,
2013 quit_on_init: bool,
2014 honor_quit: bool,
2015 }
2016
2017 impl Model for ObservedModel {
2018 type Message = Event;
2019
2020 fn init(&mut self) -> Cmd<Event> {
2021 self.init_count.set(self.init_count.get() + 1);
2022 if self.quit_on_init {
2023 Cmd::quit()
2024 } else {
2025 Cmd::tick(Duration::from_millis(10))
2026 }
2027 }
2028
2029 fn update(&mut self, event: Event) -> Cmd<Event> {
2030 let quit = event == key_event('q') && self.honor_quit;
2031 self.seen.borrow_mut().push(event);
2032 if quit { Cmd::quit() } else { Cmd::none() }
2033 }
2034
2035 fn view(&self, frame: &mut Frame) {
2036 frame.buffer.set_raw(0, 0, Cell::from_char('X'));
2037 }
2038 }
2039
2040 fn observed_model(quit_on_init: bool, honor_quit: bool) -> ObservedModel {
2041 ObservedModel {
2042 seen: Default::default(),
2043 init_count: Default::default(),
2044 quit_on_init,
2045 honor_quit,
2046 }
2047 }
2048
2049 #[test]
2050 fn non_rendering_quit_replays_actual_updates_and_exact_accepted_tail() {
2051 let model = observed_model(false, true);
2052 let recorded_seen = model.seen.clone();
2053 let mut recorder = SessionRecorder::new(model, 20, 2, 7);
2054 recorder.init().unwrap();
2055 let tail = vec![
2056 Event::Paste(PasteEvent::bracketed("尾巴 🦀")),
2057 Event::Resize {
2058 width: 33,
2059 height: 4,
2060 },
2061 ];
2062 for event in [key_event('+'), key_event('q')]
2063 .into_iter()
2064 .chain(tail.clone())
2065 {
2066 recorder.push_event(9, event).unwrap();
2067 }
2068 let outcome = recorder.step().unwrap();
2069 assert_eq!(outcome.events_processed, 2);
2070 assert_eq!(outcome.events_pending, 2);
2071 assert!(!outcome.running && !outcome.rendered);
2072 assert_eq!(
2073 *recorded_seen.borrow(),
2074 vec![key_event('+'), key_event('q')]
2075 );
2076 let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2077 let model = observed_model(false, true);
2078 let replayed_seen = model.seen.clone();
2079 let init_count = model.init_count.clone();
2080 let result = replay(model, &trace).unwrap();
2081 assert!(result.ok());
2082 assert_eq!(result.total_steps, 2);
2083 assert_eq!(result.total_frames, 1);
2084 assert!(!result.running);
2085 assert_eq!(result.unprocessed_events, tail);
2086 assert_eq!(*replayed_seen.borrow(), *recorded_seen.borrow());
2087 assert_eq!(init_count.get(), 1);
2088 let gate = gate_trace(observed_model(false, true), &trace).unwrap();
2089 assert!(gate.passed);
2090 assert_eq!(gate.total_steps, 2);
2091 assert!(!gate.running);
2092 assert_eq!(gate.unprocessed_events, tail);
2093 assert!(gate.format().contains("unprocessed_events=2"));
2094 assert!(!gate.format().contains("尾巴"));
2095
2096 assert!(matches!(
2099 replay(observed_model(false, false), &trace),
2100 Err(ReplayError::StepMismatch { step_idx: 1, .. })
2101 ));
2102 }
2103
2104 #[test]
2105 fn initialization_quit_has_no_frame_and_recovers_preinit_input() {
2106 let mut recorder = SessionRecorder::new(observed_model(true, true), 20, 2, 7);
2107 recorder.push_event(1, key_event('+')).unwrap();
2108 recorder.resize(2, 40, 4).unwrap();
2109 recorder.init().unwrap();
2110 assert_eq!(recorder.program().size(), (20, 2));
2111 assert!(recorder.program().outputs().last_buffer.is_none());
2112 let stopped = recorder.step().unwrap();
2113 assert_eq!(stopped.events_pending, 2);
2114 assert_eq!(stopped.events_processed, 0);
2115 let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2116 let model = observed_model(true, true);
2117 let seen = model.seen.clone();
2118 let init_count = model.init_count.clone();
2119 let result = replay(model, &trace).unwrap();
2120 assert!(result.ok());
2121 assert!(!result.running);
2122 assert_eq!(result.total_frames, 0);
2123 assert_eq!(result.total_steps, 2);
2124 assert_eq!(init_count.get(), 1);
2125 assert!(seen.borrow().is_empty());
2126 assert_eq!(
2127 result.unprocessed_events,
2128 vec![
2129 key_event('+'),
2130 Event::Resize {
2131 width: 40,
2132 height: 4
2133 }
2134 ]
2135 );
2136 }
2137
2138 #[test]
2139 fn idle_steps_and_clock_deltas_replay_independently_of_metadata_timestamps() {
2140 let model = observed_model(false, true);
2141 let seen = model.seen.clone();
2142 let mut recorder = SessionRecorder::new(model, 20, 2, 7);
2143 recorder.init().unwrap();
2144 assert!(!recorder.step().unwrap().rendered);
2145 recorder.advance_time(1, Duration::from_millis(9));
2146 assert!(!recorder.step().unwrap().rendered);
2147 recorder.advance_time(2, Duration::from_millis(1));
2148 assert!(recorder.step().unwrap().rendered);
2149 assert!(!recorder.step().unwrap().rendered);
2150 assert_eq!(*seen.borrow(), vec![Event::Tick]);
2151 let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2152 let model = observed_model(false, true);
2153 let replayed = model.seen.clone();
2154 let result = replay(model, &trace).unwrap();
2155 assert!(result.ok());
2156 assert_eq!(result.total_steps, 5);
2157 assert_eq!(result.total_frames, 2);
2158 assert_eq!(*replayed.borrow(), vec![Event::Tick]);
2159 }
2160
2161 #[test]
2162 fn trace_requires_observed_boundaries_without_implicit_flush_or_stale_frames() {
2163 let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
2164 recorder.init().unwrap();
2165 recorder.push_event(1, key_event('q')).unwrap();
2166 recorder.step().unwrap();
2167 let trace = recorder.finish();
2168 trace.validate().unwrap();
2169 let quit_idx = trace.records.len() - 2;
2170 for missing in [1, 2, quit_idx] {
2171 let mut changed = trace.clone();
2172 changed.records.remove(missing);
2173 assert!(changed.validate().is_err(), "missing record {missing}");
2174 assert!(replay(new_counter(0), &changed).is_err());
2175 }
2176 let mut duplicate = trace.clone();
2177 duplicate
2178 .records
2179 .insert(quit_idx, trace.records[quit_idx].clone());
2180 assert!(duplicate.validate().is_err());
2181 let mut reordered = trace.clone();
2182 reordered.records.swap(1, 2);
2183 assert!(reordered.validate().is_err());
2184 let mut bad_count = trace.clone();
2185 if let TraceRecord::Step { result, .. } = &mut bad_count.records[quit_idx] {
2186 result.events_pending = 1;
2187 }
2188 assert!(bad_count.validate().is_err());
2189 let mut after_quit = trace.clone();
2190 after_quit.records.insert(
2191 quit_idx + 1,
2192 TraceRecord::Input {
2193 ts_ns: 1,
2194 event: key_event('+'),
2195 },
2196 );
2197 assert!(after_quit.validate().is_err());
2198
2199 let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
2200 recorder.init().unwrap();
2201 recorder.push_event(1, key_event('+')).unwrap();
2202 assert!(recorder.finish().validate().is_err());
2203 }
2204
2205 #[test]
2206 fn recorder_rejects_before_changing_trace_or_timestamp_and_replays_recovery() {
2207 let mut recorder = SessionRecorder::new(new_counter(0), 80, 24, 0);
2208 recorder.init().unwrap();
2209 for _ in 0..crate::WebEventSource::MAX_EVENTS {
2210 recorder.push_event(1, key_event('+')).unwrap();
2211 }
2212 let records_before = recorder.records.len();
2213 assert!(matches!(
2214 recorder.push_event(2, key_event('-')),
2215 Err(WebBackendError::InputQueueFull { .. })
2216 ));
2217 assert!(matches!(
2218 recorder.resize(3, 120, 40),
2219 Err(WebBackendError::InputQueueFull { .. })
2220 ));
2221 assert_eq!(recorder.records.len(), records_before);
2222 assert_eq!(recorder.current_ts_ns, 1);
2223 assert_eq!(recorder.program.size(), (80, 24));
2224 assert_eq!(
2225 recorder.step().unwrap().events_processed as usize,
2226 crate::WebEventSource::MAX_EVENTS
2227 );
2228 recorder.push_event(2, key_event('-')).unwrap();
2229 recorder.resize(3, 120, 40).unwrap();
2230 assert_eq!(recorder.step().unwrap().events_processed, 2);
2231 let trace = recorder.finish();
2232 trace.validate().unwrap();
2233 assert!(replay(new_counter(0), &trace).unwrap().ok());
2234 }
2235
2236 #[test]
2237 fn replay_rejects_an_overfull_batch_without_inserting_unrecorded_steps() {
2238 let mut recorder = SessionRecorder::new(new_counter(0), 80, 24, 0);
2239 recorder.init().unwrap();
2240 let mut trace = recorder.finish();
2241 let summary_index = trace.records.len() - 1;
2242 trace.records.splice(
2243 summary_index..summary_index,
2244 (0..=crate::WebEventSource::MAX_EVENTS).map(|_| TraceRecord::Input {
2245 ts_ns: 0,
2246 event: key_event('+'),
2247 }),
2248 );
2249 trace.records.insert(
2250 trace.records.len() - 1,
2251 TraceRecord::Step {
2252 step_idx: 1,
2253 ts_ns: 0,
2254 init: false,
2255 clock: Duration::ZERO,
2256 result: StepResult {
2257 running: false,
2258 rendered: false,
2259 events_processed: 0,
2260 events_pending: crate::WebEventSource::MAX_EVENTS as u32 + 1,
2261 frame_idx: 1,
2262 },
2263 },
2264 );
2265 trace.validate().unwrap();
2266 assert!(matches!(
2267 replay(new_counter(0), &trace),
2268 Err(ReplayError::Backend(WebBackendError::InputQueueFull {
2269 limit: crate::WebInputLimit::Events,
2270 ..
2271 }))
2272 ));
2273 }
2274
2275 #[test]
2278 fn fnv1a64_pair_is_deterministic() {
2279 let a = fnv1a64_pair(0, 1234);
2280 let b = fnv1a64_pair(0, 1234);
2281 assert_eq!(a, b);
2282 }
2283
2284 #[test]
2285 fn fnv1a64_pair_differs_for_different_input() {
2286 assert_ne!(fnv1a64_pair(0, 1), fnv1a64_pair(0, 2));
2287 assert_ne!(fnv1a64_pair(1, 0), fnv1a64_pair(2, 0));
2288 }
2289
2290 #[test]
2293 fn recorder_produces_header_and_summary() {
2294 let mut rec = SessionRecorder::new(new_counter(0), 80, 24, 42);
2295 rec.init().unwrap();
2296
2297 let trace = rec.finish();
2298 assert_eq!(trace.records.len(), 4); assert!(matches!(
2302 &trace.records[0],
2303 TraceRecord::Header {
2304 seed: 42,
2305 cols: 80,
2306 rows: 24,
2307 ..
2308 }
2309 ));
2310
2311 assert!(matches!(
2313 trace.records.last().unwrap(),
2314 TraceRecord::Summary {
2315 total_frames: 1,
2316 ..
2317 }
2318 ));
2319 }
2320
2321 #[test]
2322 fn recorder_captures_init_frame() {
2323 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2324 rec.init().unwrap();
2325
2326 let trace = rec.finish();
2327 let frames: Vec<_> = trace
2328 .records
2329 .iter()
2330 .filter(|r| matches!(r, TraceRecord::Frame { .. }))
2331 .collect();
2332 assert_eq!(frames.len(), 1);
2333
2334 if let TraceRecord::Frame {
2335 frame_idx,
2336 checksum,
2337 ..
2338 } = &frames[0]
2339 {
2340 assert_eq!(*frame_idx, 0);
2341 assert_ne!(*checksum, 0); }
2343 }
2344
2345 #[test]
2348 fn record_replay_identical_checksums() {
2349 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2351 rec.init().unwrap();
2352
2353 rec.push_event(1_000_000, key_event('+'))
2354 .expect("key admission");
2355 rec.push_event(2_000_000, key_event('+'))
2356 .expect("key admission");
2357 rec.push_event(3_000_000, key_event('-'))
2358 .expect("key admission");
2359 rec.step().unwrap();
2360
2361 rec.push_event(16_000_000, key_event('+'))
2362 .expect("key admission");
2363 rec.step().unwrap();
2364
2365 let trace = rec.finish();
2366 assert_eq!(trace.frame_count(), 3); let result = replay(new_counter(0), &trace).unwrap();
2370 assert!(result.ok(), "replay mismatch: {:?}", result.first_mismatch);
2371 assert_eq!(result.total_frames, 3);
2372 assert_eq!(
2373 result.final_checksum_chain,
2374 trace.final_checksum_chain().unwrap()
2375 );
2376 }
2377
2378 #[test]
2379 fn replay_detects_different_initial_state() {
2380 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2382 rec.init().unwrap();
2383 let trace = rec.finish();
2384
2385 let result = replay(new_counter(5), &trace).unwrap();
2387 assert!(!result.ok());
2388 assert_eq!(result.first_mismatch.as_ref().unwrap().frame_idx, 0);
2389 }
2390
2391 #[test]
2392 fn replay_detects_divergence_after_events() {
2393 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2395 rec.init().unwrap();
2396
2397 rec.push_event(1_000_000, key_event('+'))
2398 .expect("key admission");
2399 rec.push_event(2_000_000, key_event('+'))
2400 .expect("key admission");
2401 rec.step().unwrap();
2402
2403 let trace = rec.finish();
2404
2405 let result = replay(new_counter(1), &trace).unwrap();
2407 assert!(!result.ok());
2408 }
2409
2410 #[test]
2413 fn resize_is_recorded_and_replayed() {
2414 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2415 rec.init().unwrap();
2416
2417 rec.resize(5_000_000, 40, 2).expect("resize admission");
2418 rec.step().unwrap();
2419
2420 let trace = rec.finish();
2421
2422 assert!(trace.records.iter().any(|r| matches!(
2424 r,
2425 TraceRecord::Resize {
2426 cols: 40,
2427 rows: 2,
2428 ..
2429 }
2430 )));
2431
2432 let result = replay(new_counter(0), &trace).unwrap();
2434 assert!(
2435 result.ok(),
2436 "resize replay mismatch: {:?}",
2437 result.first_mismatch
2438 );
2439 }
2440
2441 #[test]
2444 fn multi_step_record_replay() {
2445 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2446 rec.init().unwrap();
2447
2448 for i in 0..5 {
2449 rec.push_event(i * 16_000_000, key_event('+'))
2450 .expect("key admission");
2451 rec.step().unwrap();
2452 }
2453
2454 let trace = rec.finish();
2455 assert_eq!(trace.frame_count(), 6); let result = replay(new_counter(0), &trace).unwrap();
2458 assert!(
2459 result.ok(),
2460 "multi-step mismatch: {:?}",
2461 result.first_mismatch
2462 );
2463 assert_eq!(result.total_frames, 6);
2464 }
2465
2466 #[test]
2469 fn quit_stops_recording() {
2470 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2471 rec.init().unwrap();
2472
2473 rec.push_event(1_000_000, key_event('+'))
2474 .expect("key admission");
2475 rec.push_event(2_000_000, key_event('q'))
2476 .expect("quit admission");
2477 let result = rec.step().unwrap();
2478 assert!(!result.running);
2479
2480 let trace = rec.finish();
2481 assert_eq!(trace.frame_count(), 1);
2483 }
2484
2485 #[test]
2488 fn empty_session_replay() {
2489 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2490 rec.init().unwrap();
2491 let trace = rec.finish();
2492
2493 let result = replay(new_counter(0), &trace).unwrap();
2494 assert!(result.ok());
2495 assert_eq!(result.total_frames, 1); }
2497
2498 #[test]
2501 fn session_trace_frame_count() {
2502 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2503 rec.init().unwrap();
2504 rec.push_event(1_000_000, key_event('+'))
2505 .expect("key admission");
2506 rec.step().unwrap();
2507 let trace = rec.finish();
2508 assert_eq!(trace.frame_count(), 2);
2509 }
2510
2511 #[test]
2512 fn session_trace_final_checksum_chain() {
2513 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2514 rec.init().unwrap();
2515 let trace = rec.finish();
2516 assert!(trace.final_checksum_chain().is_some());
2517 assert_ne!(trace.final_checksum_chain().unwrap(), 0);
2518 }
2519
2520 #[test]
2523 fn replay_missing_header_returns_error() {
2524 let trace = SessionTrace { records: vec![] };
2525 let result = replay(new_counter(0), &trace);
2526 assert!(matches!(result, Err(ReplayError::MissingHeader)));
2527 }
2528
2529 #[test]
2530 fn replay_non_header_first_returns_error() {
2531 let trace = SessionTrace {
2532 records: vec![TraceRecord::Tick { ts_ns: 0 }],
2533 };
2534 let result = replay(new_counter(0), &trace);
2535 assert!(matches!(result, Err(ReplayError::MissingHeader)));
2536 }
2537
2538 #[test]
2539 fn trace_validate_missing_summary_returns_typed_error() {
2540 let trace = SessionTrace {
2541 records: vec![TraceRecord::Header {
2542 seed: 0,
2543 cols: 80,
2544 rows: 24,
2545 profile: "modern".to_string(),
2546 }],
2547 };
2548 let result = trace.validate();
2549 assert_eq!(result, Err(TraceValidationError::MissingSummary));
2550 }
2551
2552 #[test]
2553 fn trace_validate_summary_frame_count_mismatch_returns_typed_error() {
2554 let trace = SessionTrace {
2555 records: vec![
2556 TraceRecord::Header {
2557 seed: 0,
2558 cols: 80,
2559 rows: 24,
2560 profile: "modern".to_string(),
2561 },
2562 TraceRecord::Frame {
2563 frame_idx: 0,
2564 ts_ns: 0,
2565 checksum: 0x1,
2566 checksum_chain: 0x10,
2567 },
2568 TraceRecord::Summary {
2569 total_frames: 2,
2570 final_checksum_chain: 0x10,
2571 },
2572 ],
2573 };
2574 let result = trace.validate();
2575 assert_eq!(
2576 result,
2577 Err(TraceValidationError::SummaryFrameCountMismatch {
2578 expected: 1,
2579 actual: 2,
2580 })
2581 );
2582 }
2583
2584 #[test]
2585 fn trace_validate_frame_index_gap_returns_typed_error() {
2586 let trace = SessionTrace {
2587 records: vec![
2588 TraceRecord::Header {
2589 seed: 0,
2590 cols: 80,
2591 rows: 24,
2592 profile: "modern".to_string(),
2593 },
2594 TraceRecord::Frame {
2595 frame_idx: 1,
2596 ts_ns: 0,
2597 checksum: 0x1,
2598 checksum_chain: 0x10,
2599 },
2600 TraceRecord::Summary {
2601 total_frames: 1,
2602 final_checksum_chain: 0x10,
2603 },
2604 ],
2605 };
2606 let result = trace.validate();
2607 assert_eq!(
2608 result,
2609 Err(TraceValidationError::FrameIndexMismatch {
2610 expected: 0,
2611 actual: 1,
2612 })
2613 );
2614 }
2615
2616 #[test]
2617 fn trace_validate_timestamp_regression_returns_typed_error() {
2618 let trace = SessionTrace {
2619 records: vec![
2620 TraceRecord::Header {
2621 seed: 0,
2622 cols: 80,
2623 rows: 24,
2624 profile: "modern".to_string(),
2625 },
2626 TraceRecord::Tick { ts_ns: 20 },
2627 TraceRecord::Tick { ts_ns: 10 },
2628 TraceRecord::Summary {
2629 total_frames: 0,
2630 final_checksum_chain: 0,
2631 },
2632 ],
2633 };
2634 let result = trace.validate();
2635 assert_eq!(
2636 result,
2637 Err(TraceValidationError::TimestampRegression {
2638 previous: 20,
2639 current: 10,
2640 record_index: 2,
2641 })
2642 );
2643 }
2644
2645 #[test]
2646 fn replay_validates_trace_before_execution() {
2647 let trace = SessionTrace {
2648 records: vec![TraceRecord::Header {
2649 seed: 0,
2650 cols: 80,
2651 rows: 24,
2652 profile: "modern".to_string(),
2653 }],
2654 };
2655 let result = replay(new_counter(0), &trace);
2656 assert_eq!(
2657 result,
2658 Err(ReplayError::InvalidTrace(
2659 TraceValidationError::MissingSummary
2660 ))
2661 );
2662 }
2663
2664 #[test]
2667 fn same_inputs_produce_same_trace_checksums() {
2668 fn record_session() -> SessionTrace {
2669 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2670 rec.init().unwrap();
2671
2672 rec.push_event(1_000_000, key_event('+'))
2673 .expect("key admission");
2674 rec.push_event(2_000_000, key_event('+'))
2675 .expect("key admission");
2676 rec.push_event(3_000_000, key_event('-'))
2677 .expect("key admission");
2678 rec.step().unwrap();
2679
2680 rec.push_event(16_000_000, key_event('+'))
2681 .expect("key admission");
2682 rec.step().unwrap();
2683
2684 rec.finish()
2685 }
2686
2687 let t1 = record_session();
2688 let t2 = record_session();
2689 let t3 = record_session();
2690
2691 let checksums = |t: &SessionTrace| -> Vec<u64> {
2693 t.records
2694 .iter()
2695 .filter_map(|r| match r {
2696 TraceRecord::Frame { checksum, .. } => Some(*checksum),
2697 _ => None,
2698 })
2699 .collect()
2700 };
2701
2702 assert_eq!(checksums(&t1), checksums(&t2));
2703 assert_eq!(checksums(&t2), checksums(&t3));
2704 assert_eq!(t1.final_checksum_chain(), t2.final_checksum_chain());
2705 }
2706
2707 #[test]
2710 fn mouse_event_record_replay() {
2711 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2712 rec.init().unwrap();
2713
2714 let mouse = Event::Mouse(MouseEvent {
2715 kind: MouseEventKind::Down(MouseButton::Left),
2716 x: 5,
2717 y: 0,
2718 pixel: None,
2719 modifiers: Modifiers::empty(),
2720 });
2721 rec.push_event(1_000_000, mouse).expect("mouse admission");
2722 rec.step().unwrap();
2723
2724 let trace = rec.finish();
2725 let result = replay(new_counter(0), &trace).unwrap();
2726 assert!(result.ok());
2727 }
2728
2729 #[test]
2730 fn paste_event_record_replay() {
2731 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2732 rec.init().unwrap();
2733
2734 let paste = Event::Paste(PasteEvent::bracketed("hello"));
2735 rec.push_event(1_000_000, paste).expect("paste admission");
2736 rec.step().unwrap();
2737
2738 let trace = rec.finish();
2739 let result = replay(new_counter(0), &trace).unwrap();
2740 assert!(result.ok());
2741 }
2742
2743 #[test]
2744 fn focus_event_record_replay() {
2745 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2746 rec.init().unwrap();
2747
2748 rec.push_event(1_000_000, Event::Focus(true))
2749 .expect("focus admission");
2750 rec.push_event(2_000_000, Event::Focus(false))
2751 .expect("focus admission");
2752 rec.step().unwrap();
2753
2754 let trace = rec.finish();
2755 let result = replay(new_counter(0), &trace).unwrap();
2756 assert!(result.ok());
2757 }
2758
2759 #[test]
2760 fn ime_event_record_replay() {
2761 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2762 rec.init().unwrap();
2763
2764 rec.push_event(1_000_000, Event::Ime(ImeEvent::start()))
2765 .expect("IME start admission");
2766 rec.push_event(2_000_000, Event::Ime(ImeEvent::update("你")))
2767 .expect("IME update admission");
2768 rec.push_event(3_000_000, Event::Ime(ImeEvent::commit("你好")))
2769 .expect("IME commit admission");
2770 rec.step().unwrap();
2771
2772 let trace = rec.finish();
2773 let result = replay(new_counter(0), &trace).unwrap();
2774 assert!(result.ok());
2775 }
2776
2777 #[test]
2780 fn checksum_chain_is_cumulative() {
2781 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2782 rec.init().unwrap();
2783
2784 rec.push_event(1_000_000, key_event('+'))
2785 .expect("key admission");
2786 rec.step().unwrap();
2787
2788 rec.push_event(2_000_000, key_event('+'))
2789 .expect("key admission");
2790 rec.step().unwrap();
2791
2792 let trace = rec.finish();
2793 let frame_records: Vec<_> = trace
2794 .records
2795 .iter()
2796 .filter_map(|r| match r {
2797 TraceRecord::Frame {
2798 checksum,
2799 checksum_chain,
2800 ..
2801 } => Some((*checksum, *checksum_chain)),
2802 _ => None,
2803 })
2804 .collect();
2805
2806 assert_eq!(frame_records.len(), 3);
2807
2808 let (c0, chain0) = frame_records[0];
2810 assert_eq!(chain0, fnv1a64_pair(0, c0));
2811
2812 let (c1, chain1) = frame_records[1];
2813 assert_eq!(chain1, fnv1a64_pair(chain0, c1));
2814
2815 let (c2, chain2) = frame_records[2];
2816 assert_eq!(chain2, fnv1a64_pair(chain1, c2));
2817
2818 assert_eq!(trace.final_checksum_chain(), Some(chain2));
2820 }
2821
2822 #[test]
2825 fn recorder_exposes_program() {
2826 let mut rec = SessionRecorder::new(new_counter(42), 20, 1, 0);
2827 rec.init().unwrap();
2828 assert_eq!(rec.program().model().value, 42);
2829 }
2830
2831 #[test]
2834 fn replay_result_ok_when_no_mismatch() {
2835 let r = ReplayResult {
2836 total_steps: 5,
2837 running: true,
2838 unprocessed_events: Vec::new(),
2839 total_frames: 5,
2840 final_checksum_chain: 123,
2841 first_mismatch: None,
2842 };
2843 assert!(r.ok());
2844 }
2845
2846 #[test]
2847 fn replay_result_not_ok_when_mismatch() {
2848 let r = ReplayResult {
2849 total_steps: 5,
2850 running: true,
2851 unprocessed_events: Vec::new(),
2852 total_frames: 5,
2853 final_checksum_chain: 123,
2854 first_mismatch: Some(ReplayMismatch {
2855 frame_idx: 2,
2856 expected: 100,
2857 actual: 200,
2858 }),
2859 };
2860 assert!(!r.ok());
2861 }
2862
2863 #[test]
2864 fn replay_error_display() {
2865 assert_eq!(
2866 ReplayError::MissingHeader.to_string(),
2867 "trace missing header record"
2868 );
2869 let invalid = ReplayError::InvalidTrace(TraceValidationError::MissingSummary);
2870 assert_eq!(
2871 invalid.to_string(),
2872 "invalid trace: trace is missing summary"
2873 );
2874 let be = ReplayError::Backend(WebBackendError::Unsupported("test"));
2875 assert!(be.to_string().contains("test"));
2876 }
2877
2878 #[test]
2881 fn trace_record_header_to_jsonl() {
2882 let r = TraceRecord::Header {
2883 seed: 42,
2884 cols: 80,
2885 rows: 24,
2886 profile: "modern".to_string(),
2887 };
2888 let line = r.to_jsonl();
2889 assert!(line.contains("\"event\":\"trace_header\""));
2890 assert!(line.contains("\"schema_version\":\"golden-trace-v2\""));
2891 assert!(line.contains("\"seed\":42"));
2892 assert!(line.contains("\"cols\":80"));
2893 assert!(line.contains("\"rows\":24"));
2894 assert!(line.contains("\"profile\":\"modern\""));
2895 }
2896
2897 #[test]
2898 fn trace_record_input_key_to_jsonl() {
2899 let r = TraceRecord::Input {
2900 ts_ns: 1_000_000,
2901 event: key_event('+'),
2902 };
2903 let line = r.to_jsonl();
2904 assert!(line.contains("\"event\":\"input\""));
2905 assert!(line.contains("\"ts_ns\":1000000"));
2906 assert!(line.contains("\"kind\":\"key\""));
2907 assert!(line.contains("\"code\":\"char:+\""));
2908 }
2909
2910 #[test]
2911 fn trace_record_resize_to_jsonl() {
2912 let r = TraceRecord::Resize {
2913 ts_ns: 5_000_000,
2914 cols: 120,
2915 rows: 40,
2916 };
2917 let line = r.to_jsonl();
2918 assert!(line.contains("\"event\":\"resize\""));
2919 assert!(line.contains("\"cols\":120"));
2920 assert!(line.contains("\"rows\":40"));
2921 }
2922
2923 #[test]
2924 fn trace_record_frame_to_jsonl() {
2925 let r = TraceRecord::Frame {
2926 frame_idx: 3,
2927 ts_ns: 48_000_000,
2928 checksum: 0xDEADBEEF,
2929 checksum_chain: 0xCAFEBABE,
2930 };
2931 let line = r.to_jsonl();
2932 assert!(line.contains("\"event\":\"frame\""));
2933 assert!(line.contains("\"frame_idx\":3"));
2934 assert!(line.contains("\"frame_hash\":\"00000000deadbeef\""));
2935 assert!(line.contains("\"checksum_chain\":\"00000000cafebabe\""));
2936 }
2937
2938 #[test]
2939 fn trace_record_summary_to_jsonl() {
2940 let r = TraceRecord::Summary {
2941 total_frames: 10,
2942 final_checksum_chain: 0x1234567890ABCDEF,
2943 };
2944 let line = r.to_jsonl();
2945 assert!(line.contains("\"event\":\"trace_summary\""));
2946 assert!(line.contains("\"total_frames\":10"));
2947 assert!(line.contains("\"final_checksum_chain\":\"1234567890abcdef\""));
2948 }
2949
2950 #[test]
2953 fn jsonl_round_trip_full_session() {
2954 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 42);
2956 rec.init().unwrap();
2957 rec.push_event(1_000_000, key_event('+'))
2958 .expect("key admission");
2959 rec.push_event(2_000_000, key_event('+'))
2960 .expect("key admission");
2961 rec.step().unwrap();
2962 let trace = rec.finish();
2963
2964 let jsonl = trace.to_jsonl();
2966 assert!(!jsonl.is_empty());
2967
2968 let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
2970 assert_eq!(parsed.records.len(), trace.records.len());
2971 assert_eq!(parsed.frame_count(), trace.frame_count());
2972 assert_eq!(parsed.final_checksum_chain(), trace.final_checksum_chain());
2973 }
2974
2975 #[test]
2976 fn jsonl_round_trip_preserves_events() {
2977 let events = vec![
2978 key_event('+'),
2979 key_event('-'),
2980 Event::Key(KeyEvent {
2981 code: KeyCode::Enter,
2982 modifiers: Modifiers::CTRL | Modifiers::SHIFT,
2983 kind: KeyEventKind::Press,
2984 }),
2985 Event::Key(KeyEvent {
2986 code: KeyCode::F(12),
2987 modifiers: Modifiers::ALT,
2988 kind: KeyEventKind::Repeat,
2989 }),
2990 Event::Mouse(MouseEvent {
2991 kind: MouseEventKind::Down(MouseButton::Left),
2992 x: 10,
2993 y: 5,
2994 pixel: None,
2995 modifiers: Modifiers::empty(),
2996 }),
2997 Event::Mouse(MouseEvent {
2998 kind: MouseEventKind::ScrollDown,
2999 x: 0,
3000 y: 0,
3001 pixel: None,
3002 modifiers: Modifiers::CTRL,
3003 }),
3004 Event::Paste(PasteEvent::bracketed("hello world")),
3005 Event::Focus(true),
3006 Event::Focus(false),
3007 Event::Tick,
3008 ];
3009
3010 for (i, event) in events.iter().enumerate() {
3011 let record = TraceRecord::Input {
3012 ts_ns: i as u64 * 1_000_000,
3013 event: event.clone(),
3014 };
3015 let jsonl = record.to_jsonl();
3016 let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
3017 let parsed_record = &parsed.records[0];
3018 let TraceRecord::Input {
3019 event: parsed_event,
3020 ..
3021 } = parsed_record
3022 else {
3023 unreachable!("expected Input record for event {i}");
3024 };
3025
3026 assert_eq!(parsed_event, event, "event {i} round-trip failed: {jsonl}");
3027 }
3028 }
3029
3030 #[test]
3031 fn jsonl_round_trip_with_resize() {
3032 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3033 rec.init().unwrap();
3034 rec.resize(5_000_000, 40, 2).expect("resize admission");
3035 rec.step().unwrap();
3036 let trace = rec.finish();
3037
3038 let jsonl = trace.to_jsonl();
3039 let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
3040
3041 let result = replay(new_counter(0), &parsed).unwrap();
3043 assert!(
3044 result.ok(),
3045 "parsed trace replay failed: {:?}",
3046 result.first_mismatch
3047 );
3048 }
3049
3050 #[test]
3053 fn step_jsonl_preserves_clock_and_requires_all_outcome_fields() {
3054 let record = TraceRecord::Step {
3055 step_idx: 4,
3056 ts_ns: 9,
3057 init: false,
3058 clock: Duration::new(u64::MAX, 999_999_999),
3059 result: StepResult {
3060 running: false,
3061 rendered: false,
3062 events_processed: 3,
3063 events_pending: 2,
3064 frame_idx: 2,
3065 },
3066 };
3067 let json = record.to_jsonl();
3068 assert_eq!(
3069 SessionTrace::from_jsonl(&json).unwrap().records,
3070 vec![record]
3071 );
3072 for field in [
3073 "step_idx",
3074 "ts_ns",
3075 "init",
3076 "clock_secs",
3077 "clock_subsec_nanos",
3078 "running",
3079 "rendered",
3080 "events_processed",
3081 "events_pending",
3082 "frame_idx",
3083 ] {
3084 let changed = json.replace(&format!("\"{field}\":"), "\"unknown\":");
3085 assert!(
3086 SessionTrace::from_jsonl(&changed).is_err(),
3087 "missing {field}"
3088 );
3089 }
3090 for (old, new) in [
3091 (
3092 "\"clock_subsec_nanos\":999999999",
3093 "\"clock_subsec_nanos\":1000000000",
3094 ),
3095 ("\"events_pending\":2", "\"events_pending\":4294967296"),
3096 ("\"events_processed\":3", "\"events_processed\":-1"),
3097 ("\"running\":false", "\"running\":null"),
3098 ("\"running\":false", "\"running\":falseX"),
3099 ("\"events_pending\":2", "\"events_pending\":2.5"),
3100 ("\"events_pending\":2", "\"events_pending\":2e3"),
3101 ("\"events_pending\":2", "\"nested\":{\"events_pending\":2}"),
3102 (
3103 "\"events_pending\":2",
3104 "\"events_pending\":2,\"events_pending\":2",
3105 ),
3106 ] {
3107 assert!(
3108 SessionTrace::from_jsonl(&json.replace(old, new)).is_err(),
3109 "invalid {new}"
3110 );
3111 }
3112 }
3113
3114 #[test]
3115 fn v1_trace_cannot_invent_missing_execution_boundaries() {
3116 let line = r#"{"schema_version":"golden-trace-v1","event":"tick","ts_ns":0}"#;
3117 let error = SessionTrace::from_jsonl(line).unwrap_err();
3118 assert!(error.message.contains("migration required"));
3119 }
3120
3121 #[test]
3122 fn text_payloads_with_braces_quotes_and_unicode_round_trip_in_quit_tail() {
3123 let text = "} { \\\" 🦀/\n\t\0\u{0008}\u{000c}";
3124 let tail = vec![
3125 Event::Paste(PasteEvent::bracketed(text)),
3126 Event::Ime(ImeEvent::commit(text)),
3127 Event::Clipboard(ftui_core::event::ClipboardEvent {
3128 content: text.to_owned(),
3129 source: ClipboardSource::Osc52,
3130 }),
3131 ];
3132 let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
3133 recorder.init().unwrap();
3134 recorder.push_event(0, key_event('q')).unwrap();
3135 for event in &tail {
3136 recorder.push_event(0, event.clone()).unwrap();
3137 }
3138 recorder.step().unwrap();
3139 let jsonl = recorder.finish().to_jsonl();
3140 let escaped = jsonl
3141 .replace('🦀', r"\ud83e\udd80")
3142 .replace('/', r"\/")
3143 .replace(r"\u0008", r"\b")
3144 .replace(r"\u000c", r"\f");
3145 for input in [&jsonl, &escaped] {
3146 let trace = SessionTrace::from_jsonl_validated(input).unwrap();
3147 assert_eq!(
3148 replay(new_counter(0), &trace).unwrap().unprocessed_events,
3149 tail
3150 );
3151 }
3152 }
3153
3154 #[test]
3155 fn malformed_text_escapes_are_rejected_without_changing_content() {
3156 for text in [r"\uZZZZ", r"\ud83e", r"\udd80", r"\ud83e\u0061", r"\q"] {
3157 let line = format!(
3158 r#"{{"schema_version":"{}","event":"input","ts_ns":0,"data":{{"kind":"paste","text":"{}"}}}}"#,
3159 SCHEMA_VERSION, text
3160 );
3161 assert!(SessionTrace::from_jsonl(&line).is_err(), "invalid {text}");
3162 }
3163 }
3164
3165 #[test]
3166 fn chain_only_corruption_cannot_pass_replay_or_gate() {
3167 let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
3168 recorder.init().unwrap();
3169 let mut trace = recorder.finish();
3170 for record in &mut trace.records {
3171 match record {
3172 TraceRecord::Frame { checksum_chain, .. } => *checksum_chain ^= 1,
3173 TraceRecord::Summary {
3174 final_checksum_chain,
3175 ..
3176 } => *final_checksum_chain ^= 1,
3177 _ => {}
3178 }
3179 }
3180 assert!(trace.validate().is_err());
3181 assert!(replay(new_counter(0), &trace).is_err());
3182 assert!(gate_trace(new_counter(0), &trace).is_err());
3183 }
3184
3185 #[test]
3186 fn from_jsonl_empty_is_ok() {
3187 let trace = SessionTrace::from_jsonl("").unwrap();
3188 assert!(trace.records.is_empty());
3189 }
3190
3191 #[test]
3192 fn from_jsonl_unknown_event_fails() {
3193 let line = r#"{"schema_version":"golden-trace-v2","event":"unknown_type","ts_ns":0}"#;
3194 let result = SessionTrace::from_jsonl(line);
3195 assert!(result.is_err());
3196 assert!(result.unwrap_err().message.contains("unknown event type"));
3197 }
3198
3199 #[test]
3200 fn from_jsonl_missing_event_field_fails() {
3201 let line = r#"{"schema_version":"golden-trace-v2","ts_ns":0}"#;
3202 let result = SessionTrace::from_jsonl(line);
3203 assert!(result.is_err());
3204 }
3205
3206 #[test]
3207 fn from_jsonl_missing_schema_version_fails() {
3208 let line = r#"{"event":"tick","ts_ns":0}"#;
3209 let result = SessionTrace::from_jsonl(line);
3210 assert!(result.is_err());
3211 assert!(result.unwrap_err().message.contains("schema_version"));
3212 }
3213
3214 #[test]
3215 fn from_jsonl_schema_matrix_current_writer_version_passes() {
3216 let line = format!(
3217 r#"{{"schema_version":"{}","event":"tick","ts_ns":0}}"#,
3218 SCHEMA_VERSION
3219 );
3220 let trace = SessionTrace::from_jsonl(&line).expect("matching schema should parse");
3221 assert_eq!(trace.records, vec![TraceRecord::Tick { ts_ns: 0 }]);
3222 }
3223
3224 #[test]
3225 fn from_jsonl_schema_matrix_newer_writer_version_fails_with_migration_error() {
3226 let line = r#"{"schema_version":"golden-trace-v3","event":"tick","ts_ns":0}"#;
3227 let result = SessionTrace::from_jsonl(line);
3228 assert!(result.is_err());
3229 let message = result.unwrap_err().message;
3230 assert!(message.contains("unsupported schema_version"));
3231 assert!(message.contains("migration required"));
3232 }
3233
3234 #[cfg(feature = "tracing")]
3235 #[test]
3236 fn schema_incompatibility_emits_compat_span_and_error_log() {
3237 let capture = TraceCaptureLayer::default();
3238 let subscriber =
3239 tracing_subscriber::registry().with(capture.clone().with_filter(LevelFilter::TRACE));
3240 let _guard = tracing::subscriber::set_default(subscriber);
3241
3242 let line = r#"{"schema_version":"golden-trace-v3","event":"tick","ts_ns":0}"#;
3243 let err = SessionTrace::from_jsonl(line).expect_err("newer schema should fail");
3244 assert!(err.message.contains("migration required"));
3245
3246 let spans = capture.spans.lock().expect("span capture lock");
3247 assert!(
3248 spans.iter().any(|name| name == "trace.compat_check"),
3249 "expected trace.compat_check span, got {spans:?}"
3250 );
3251 drop(spans);
3252
3253 let events = capture.events.lock().expect("event capture lock");
3254 assert!(
3255 events
3256 .iter()
3257 .any(|event| event.contains("ERROR:trace schema version incompatible")),
3258 "expected incompatible schema ERROR log, got {events:?}"
3259 );
3260 }
3261
3262 #[test]
3263 fn from_jsonl_validated_surfaces_validation_error_type() {
3264 let jsonl = TraceRecord::Header {
3265 seed: 0,
3266 cols: 80,
3267 rows: 24,
3268 profile: "modern".to_string(),
3269 }
3270 .to_jsonl();
3271 let result = SessionTrace::from_jsonl_validated(&jsonl);
3272 assert!(matches!(
3273 result,
3274 Err(TraceLoadError::Validation(
3275 TraceValidationError::MissingSummary
3276 ))
3277 ));
3278 }
3279
3280 #[test]
3283 fn json_escape_round_trip() {
3284 let cases = [
3285 "hello",
3286 "with\"quotes",
3287 "back\\slash",
3288 "line\nbreak",
3289 "tab\there",
3290 ];
3291 for input in cases {
3292 let escaped = json_escape(input);
3293 let unescaped = json_unescape(&escaped).unwrap();
3294 assert_eq!(unescaped, input, "round-trip failed for: {input:?}");
3295 }
3296 }
3297
3298 #[test]
3299 fn extract_str_basic() {
3300 let json = r#"{"name":"alice","age":30}"#;
3301 assert_eq!(extract_str(json, "name"), Some("alice"));
3302 }
3303
3304 #[test]
3305 fn extract_u64_basic() {
3306 let json = r#"{"count":42,"name":"test"}"#;
3307 assert_eq!(extract_u64(json, "count"), Some(42));
3308 }
3309
3310 #[test]
3311 fn extract_i64_basic() {
3312 let json = r#"{"dx":-12,"dy":7}"#;
3313 assert_eq!(extract_i64(json, "dx"), Some(-12));
3314 assert_eq!(extract_i64(json, "dy"), Some(7));
3315 }
3316
3317 #[test]
3318 fn extract_bool_basic() {
3319 let json = r#"{"enabled":true,"disabled":false}"#;
3320 assert_eq!(extract_bool(json, "enabled"), Some(true));
3321 assert_eq!(extract_bool(json, "disabled"), Some(false));
3322 }
3323
3324 #[test]
3325 fn extract_hex_u64_basic() {
3326 let json = r#"{"hash":"00000000deadbeef"}"#;
3327 assert_eq!(extract_hex_u64(json, "hash"), Some(0xDEADBEEF));
3328 }
3329
3330 #[test]
3331 fn from_jsonl_parses_frankenterm_key_schema() {
3332 let down = parse_single_input_event(
3333 r#"{"kind":"key","phase":"down","code":"F12","mods":5,"repeat":false}"#,
3334 );
3335 assert_eq!(
3336 down,
3337 Event::Key(KeyEvent {
3338 code: KeyCode::F(12),
3339 modifiers: Modifiers::SHIFT | Modifiers::CTRL,
3340 kind: KeyEventKind::Press,
3341 })
3342 );
3343
3344 let repeat = parse_single_input_event(
3345 r#"{"kind":"key","phase":"down","code":"a","mods":0,"repeat":true}"#,
3346 );
3347 assert_eq!(
3348 repeat,
3349 Event::Key(KeyEvent {
3350 code: KeyCode::Char('a'),
3351 modifiers: Modifiers::empty(),
3352 kind: KeyEventKind::Repeat,
3353 })
3354 );
3355
3356 let release = parse_single_input_event(
3357 r#"{"kind":"key","phase":"up","code":"Enter","mods":0,"repeat":false}"#,
3358 );
3359 assert_eq!(
3360 release,
3361 Event::Key(KeyEvent {
3362 code: KeyCode::Enter,
3363 modifiers: Modifiers::empty(),
3364 kind: KeyEventKind::Release,
3365 })
3366 );
3367 }
3368
3369 #[test]
3370 fn key_event_json_round_trip_unescapes_code() {
3371 let quote_key = Event::Key(KeyEvent {
3372 code: KeyCode::Char('"'),
3373 modifiers: Modifiers::empty(),
3374 kind: KeyEventKind::Press,
3375 });
3376 let quote_json = event_to_json("e_key);
3377 let parsed_quote = parse_event_json("e_json).expect("quote key should parse");
3378 assert_eq!(parsed_quote, quote_key);
3379
3380 let slash_key = Event::Key(KeyEvent {
3381 code: KeyCode::Char('\\'),
3382 modifiers: Modifiers::SHIFT,
3383 kind: KeyEventKind::Press,
3384 });
3385 let slash_json = event_to_json(&slash_key);
3386 let parsed_slash = parse_event_json(&slash_json).expect("slash key should parse");
3387 assert_eq!(parsed_slash, slash_key);
3388 }
3389
3390 #[test]
3391 fn from_jsonl_parses_frankenterm_mouse_and_wheel_schema() {
3392 let mouse = parse_single_input_event(
3393 r#"{"kind":"mouse","phase":"drag","button":2,"x":7,"y":9,"mods":3}"#,
3394 );
3395 assert_eq!(
3396 mouse,
3397 Event::Mouse(MouseEvent {
3398 kind: MouseEventKind::Drag(MouseButton::Right),
3399 x: 7,
3400 y: 9,
3401 pixel: None,
3402 modifiers: Modifiers::SHIFT | Modifiers::ALT,
3403 })
3404 );
3405
3406 let wheel =
3407 parse_single_input_event(r#"{"kind":"wheel","x":4,"y":6,"dx":0,"dy":-2,"mods":4}"#);
3408 assert_eq!(
3409 wheel,
3410 Event::Mouse(MouseEvent {
3411 kind: MouseEventKind::ScrollUp,
3412 x: 4,
3413 y: 6,
3414 pixel: None,
3415 modifiers: Modifiers::CTRL,
3416 })
3417 );
3418 }
3419
3420 #[test]
3421 fn from_jsonl_parses_frankenterm_paste_focus_and_composition_aliases() {
3422 let paste = parse_single_input_event(r#"{"kind":"paste","data":"hello\nworld"}"#);
3423 assert_eq!(paste, Event::Paste(PasteEvent::new("hello\nworld", true)));
3424
3425 let focus = parse_single_input_event(r#"{"kind":"focus","focused":false}"#);
3426 assert_eq!(focus, Event::Focus(false));
3427
3428 let composition_update =
3429 parse_single_input_event(r#"{"kind":"composition","phase":"update","data":"你"}"#);
3430 assert_eq!(
3431 composition_update,
3432 Event::Ime(ImeEvent::new(ImePhase::Update, "你"))
3433 );
3434
3435 let composition_end =
3436 parse_single_input_event(r#"{"kind":"composition","phase":"end","data":"你好"}"#);
3437 assert_eq!(
3438 composition_end,
3439 Event::Ime(ImeEvent::new(ImePhase::Commit, "你好"))
3440 );
3441 }
3442
3443 #[test]
3446 fn gate_trace_passes_on_correct_replay() {
3447 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3448 rec.init().unwrap();
3449 rec.push_event(1_000_000, key_event('+'))
3450 .expect("key admission");
3451 rec.step().unwrap();
3452 let trace = rec.finish();
3453
3454 let report = gate_trace(new_counter(0), &trace).unwrap();
3455 assert!(report.passed);
3456 assert_eq!(report.total_frames, 2);
3457 assert!(report.diff.is_none());
3458 assert!(report.format().starts_with("PASS"));
3459 }
3460
3461 #[test]
3462 fn gate_trace_fails_with_actionable_diff() {
3463 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3464 rec.init().unwrap();
3465 rec.push_event(1_000_000, key_event('+'))
3466 .expect("key admission");
3467 rec.push_event(2_000_000, key_event('+'))
3468 .expect("key admission");
3469 rec.step().unwrap();
3470 let trace = rec.finish();
3471
3472 let report = gate_trace(new_counter(5), &trace).unwrap();
3474 assert!(!report.passed);
3475 assert!(report.diff.is_some());
3476
3477 let diff = report.diff.as_ref().unwrap();
3478 assert_eq!(diff.frame_idx, 0); let formatted = report.format();
3481 assert!(formatted.starts_with("FAIL"));
3482 assert!(formatted.contains("frame 0"));
3483 }
3484
3485 #[test]
3486 fn gate_trace_diff_has_event_context() {
3487 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3488 rec.init().unwrap();
3489 rec.push_event(1_000_000, key_event('+'))
3490 .expect("key admission");
3491 rec.push_event(2_000_000, key_event('+'))
3492 .expect("key admission");
3493 rec.step().unwrap();
3494 rec.push_event(3_000_000, key_event('-'))
3495 .expect("key admission");
3496 rec.step().unwrap();
3497 let trace = rec.finish();
3498
3499 let mut tampered = trace.clone();
3501 let mut chain = 0;
3502 for record in &mut tampered.records {
3503 match record {
3504 TraceRecord::Frame {
3505 frame_idx,
3506 checksum,
3507 checksum_chain,
3508 ..
3509 } => {
3510 if *frame_idx == 2 {
3511 *checksum = 0xBAD;
3512 }
3513 chain = fnv1a64_pair(chain, *checksum);
3514 *checksum_chain = chain;
3515 }
3516 TraceRecord::Summary {
3517 final_checksum_chain,
3518 ..
3519 } => *final_checksum_chain = chain,
3520 _ => {}
3521 }
3522 }
3523 tampered.validate().unwrap();
3526
3527 let report = gate_trace(new_counter(0), &tampered).unwrap();
3528 assert!(!report.passed);
3529 let diff = report.diff.unwrap();
3530 assert_eq!(diff.frame_idx, 2);
3531 assert!(diff.event_idx > 0); }
3533
3534 #[test]
3537 fn jsonl_serialize_parse_replay_round_trip() {
3538 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3540 rec.init().unwrap();
3541
3542 for i in 0..3 {
3543 rec.push_event(i * 16_000_000, key_event('+'))
3544 .expect("key admission");
3545 rec.step().unwrap();
3546 }
3547 let original_trace = rec.finish();
3548
3549 let jsonl = original_trace.to_jsonl();
3551
3552 let parsed_trace = SessionTrace::from_jsonl(&jsonl).unwrap();
3554
3555 let result = replay(new_counter(0), &parsed_trace).unwrap();
3557 assert!(
3558 result.ok(),
3559 "JSONL round-trip replay failed: {:?}",
3560 result.first_mismatch
3561 );
3562 assert_eq!(result.total_frames, original_trace.frame_count());
3563 assert_eq!(
3564 result.final_checksum_chain,
3565 original_trace.final_checksum_chain().unwrap()
3566 );
3567 }
3568
3569 #[test]
3572 fn trace_parse_error_display() {
3573 let e = TraceParseError {
3574 line: 5,
3575 message: "bad field".to_string(),
3576 };
3577 assert_eq!(e.to_string(), "line 5: bad field");
3578 }
3579}