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::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 modifiers,
1490 }))
1491 }
1492 "wheel" => {
1493 let x = extract_u16(data, "x").unwrap_or(0);
1494 let y = extract_u16(data, "y").unwrap_or(0);
1495 let dx = extract_i64(data, "dx")
1496 .and_then(|value| i16::try_from(value).ok())
1497 .unwrap_or(0);
1498 let dy = extract_i64(data, "dy")
1499 .and_then(|value| i16::try_from(value).ok())
1500 .unwrap_or(0);
1501 let kind = if dy < 0 {
1502 MouseEventKind::ScrollUp
1503 } else if dy > 0 {
1504 MouseEventKind::ScrollDown
1505 } else if dx < 0 {
1506 MouseEventKind::ScrollLeft
1507 } else if dx > 0 {
1508 MouseEventKind::ScrollRight
1509 } else {
1510 return Err("wheel event must include non-zero dx or dy".to_string());
1511 };
1512 let mods_bits = extract_u64(data, "modifiers")
1513 .or(extract_u64(data, "mods"))
1514 .unwrap_or(0) as u8;
1515 let modifiers = Modifiers::from_bits(mods_bits).unwrap_or_else(Modifiers::empty);
1516 Ok(Event::Mouse(MouseEvent {
1517 kind,
1518 x,
1519 y,
1520 modifiers,
1521 }))
1522 }
1523 "resize" => {
1524 let width = extract_u16(data, "width").ok_or("missing width")?;
1525 let height = extract_u16(data, "height").ok_or("missing height")?;
1526 Ok(Event::Resize { width, height })
1527 }
1528 "paste" => {
1529 let text = extract_str(data, "text")
1530 .or(extract_str(data, "data"))
1531 .map(json_unescape)
1532 .transpose()?
1533 .unwrap_or_default();
1534 let bracketed = extract_bool(data, "bracketed").unwrap_or(true);
1535 Ok(Event::Paste(PasteEvent::new(text, bracketed)))
1536 }
1537 "ime" | "composition" => {
1538 let phase_raw = extract_str(data, "phase").unwrap_or("update");
1539 let phase = parse_ime_phase(phase_raw)?;
1540 let text = extract_str(data, "text")
1541 .or(extract_str(data, "data"))
1542 .map(json_unescape)
1543 .transpose()?
1544 .unwrap_or_default();
1545 let ime = match phase {
1546 ImePhase::Start => ImeEvent::start(),
1547 ImePhase::Update => ImeEvent::update(text),
1548 ImePhase::Commit => ImeEvent::commit(text),
1549 ImePhase::Cancel => ImeEvent::cancel(),
1550 };
1551 Ok(Event::Ime(ime))
1552 }
1553 "focus" => {
1554 let gained = extract_bool(data, "gained")
1555 .or(extract_bool(data, "focused"))
1556 .unwrap_or(true);
1557 Ok(Event::Focus(gained))
1558 }
1559 "clipboard" => {
1560 let content = extract_str(data, "content")
1561 .map(json_unescape)
1562 .transpose()?
1563 .unwrap_or_default();
1564 let source_str = extract_str(data, "source").unwrap_or("unknown");
1565 let source = match source_str {
1566 "osc52" => ClipboardSource::Osc52,
1567 _ => ClipboardSource::Unknown,
1568 };
1569 Ok(Event::Clipboard(ClipboardEvent::new(content, source)))
1570 }
1571 "tick" => Ok(Event::Tick),
1572 other => Err(format!("unknown event kind: {other}")),
1573 }
1574}
1575
1576fn parse_ime_phase(phase: &str) -> Result<ImePhase, String> {
1577 match phase {
1578 "start" => Ok(ImePhase::Start),
1579 "update" => Ok(ImePhase::Update),
1580 "end" | "commit" => Ok(ImePhase::Commit),
1581 "cancel" => Ok(ImePhase::Cancel),
1582 other => Err(format!("unknown ime/composition phase: {other}")),
1583 }
1584}
1585
1586fn parse_key_code(s: &str) -> Result<KeyCode, String> {
1587 if let Some(rest) = s.strip_prefix("char:") {
1588 let ch = rest.chars().next().ok_or("empty char code")?;
1589 return Ok(KeyCode::Char(ch));
1590 }
1591 if let Some(rest) = s.strip_prefix("f:") {
1592 let n: u8 = rest.parse().map_err(|_| "invalid F-key number")?;
1593 return Ok(KeyCode::F(n));
1594 }
1595 if let Some(n) = parse_function_key_token(s) {
1596 return Ok(KeyCode::F(n));
1597 }
1598
1599 let mut chars = s.chars();
1600 if let Some(ch) = chars.next()
1601 && chars.next().is_none()
1602 {
1603 return Ok(KeyCode::Char(ch));
1604 }
1605
1606 let normalized = s.to_ascii_lowercase();
1607 match normalized.as_str() {
1608 "enter" | "return" => Ok(KeyCode::Enter),
1609 "escape" | "esc" => Ok(KeyCode::Escape),
1610 "backspace" => Ok(KeyCode::Backspace),
1611 "tab" => Ok(KeyCode::Tab),
1612 "backtab" => Ok(KeyCode::BackTab),
1613 "delete" => Ok(KeyCode::Delete),
1614 "insert" => Ok(KeyCode::Insert),
1615 "home" => Ok(KeyCode::Home),
1616 "end" => Ok(KeyCode::End),
1617 "pageup" => Ok(KeyCode::PageUp),
1618 "pagedown" => Ok(KeyCode::PageDown),
1619 "up" | "arrowup" => Ok(KeyCode::Up),
1620 "down" | "arrowdown" => Ok(KeyCode::Down),
1621 "left" | "arrowleft" => Ok(KeyCode::Left),
1622 "right" | "arrowright" => Ok(KeyCode::Right),
1623 "null" | "unidentified" => Ok(KeyCode::Null),
1624 "media_play_pause" => Ok(KeyCode::MediaPlayPause),
1625 "media_stop" => Ok(KeyCode::MediaStop),
1626 "media_next" => Ok(KeyCode::MediaNextTrack),
1627 "media_prev" => Ok(KeyCode::MediaPrevTrack),
1628 other => Err(format!("unknown key code: {other}")),
1629 }
1630}
1631
1632fn parse_function_key_token(s: &str) -> Option<u8> {
1633 let rest = s.strip_prefix('F').or_else(|| s.strip_prefix('f'))?;
1634 if rest.is_empty() || !rest.chars().all(|ch| ch.is_ascii_digit()) {
1635 return None;
1636 }
1637 rest.parse().ok()
1638}
1639
1640fn parse_key_event_kind(phase: &str, repeat: bool) -> KeyEventKind {
1641 if phase.eq_ignore_ascii_case("up") || phase.eq_ignore_ascii_case("release") {
1642 KeyEventKind::Release
1643 } else if repeat {
1644 KeyEventKind::Repeat
1645 } else {
1646 KeyEventKind::Press
1647 }
1648}
1649
1650fn parse_mouse_event_kind(s: &str) -> Result<MouseEventKind, String> {
1651 match s {
1652 "down_left" => Ok(MouseEventKind::Down(MouseButton::Left)),
1653 "down_right" => Ok(MouseEventKind::Down(MouseButton::Right)),
1654 "down_middle" => Ok(MouseEventKind::Down(MouseButton::Middle)),
1655 "up_left" => Ok(MouseEventKind::Up(MouseButton::Left)),
1656 "up_right" => Ok(MouseEventKind::Up(MouseButton::Right)),
1657 "up_middle" => Ok(MouseEventKind::Up(MouseButton::Middle)),
1658 "drag_left" => Ok(MouseEventKind::Drag(MouseButton::Left)),
1659 "drag_right" => Ok(MouseEventKind::Drag(MouseButton::Right)),
1660 "drag_middle" => Ok(MouseEventKind::Drag(MouseButton::Middle)),
1661 "moved" => Ok(MouseEventKind::Moved),
1662 "scroll_up" => Ok(MouseEventKind::ScrollUp),
1663 "scroll_down" => Ok(MouseEventKind::ScrollDown),
1664 "scroll_left" => Ok(MouseEventKind::ScrollLeft),
1665 "scroll_right" => Ok(MouseEventKind::ScrollRight),
1666 other => Err(format!("unknown mouse event kind: {other}")),
1667 }
1668}
1669
1670fn parse_mouse_phase_and_button(phase: &str, button: Option<u8>) -> Result<MouseEventKind, String> {
1671 match phase {
1672 "down" => Ok(MouseEventKind::Down(parse_mouse_button(
1673 button.ok_or("mouse down requires button")?,
1674 )?)),
1675 "up" => Ok(MouseEventKind::Up(parse_mouse_button(
1676 button.ok_or("mouse up requires button")?,
1677 )?)),
1678 "drag" => Ok(MouseEventKind::Drag(parse_mouse_button(
1679 button.ok_or("mouse drag requires button")?,
1680 )?)),
1681 "move" => Ok(MouseEventKind::Moved),
1682 other => Err(format!("unknown mouse phase: {other}")),
1683 }
1684}
1685
1686fn parse_mouse_button(raw: u8) -> Result<MouseButton, String> {
1687 match raw {
1688 0 => Ok(MouseButton::Left),
1689 1 => Ok(MouseButton::Middle),
1690 2 => Ok(MouseButton::Right),
1691 other => Err(format!("unsupported mouse button: {other}")),
1692 }
1693}
1694
1695pub fn gate_trace<M: ftui_runtime::program::Model>(
1703 model: M,
1704 trace: &SessionTrace,
1705) -> Result<GateReport, ReplayError> {
1706 let result = replay(model, trace)?;
1707
1708 let frame_checksums: Vec<(u64, u64)> = trace
1709 .records
1710 .iter()
1711 .filter_map(|r| match r {
1712 TraceRecord::Frame {
1713 frame_idx,
1714 checksum,
1715 ..
1716 } => Some((*frame_idx, *checksum)),
1717 _ => None,
1718 })
1719 .collect();
1720
1721 let diff = result.first_mismatch.as_ref().map(|m| {
1722 let mut event_idx: u64 = 0;
1724 let mut last_event_desc = String::new();
1725 let mut frame_count: u64 = 0;
1726 for record in &trace.records {
1727 match record {
1728 TraceRecord::Frame { .. } => {
1729 if frame_count == m.frame_idx {
1730 break;
1731 }
1732 frame_count += 1;
1733 }
1734 TraceRecord::Input { event, .. } => {
1735 last_event_desc = format!("{event:?}");
1736 event_idx += 1;
1737 }
1738 TraceRecord::Resize { cols, rows, .. } => {
1739 last_event_desc = format!("Resize({cols}x{rows})");
1740 event_idx += 1;
1741 }
1742 TraceRecord::Tick { ts_ns } => {
1743 last_event_desc = format!("Tick(ts_ns={ts_ns})");
1744 event_idx += 1;
1745 }
1746 _ => {}
1747 }
1748 }
1749
1750 GateDiff {
1751 frame_idx: m.frame_idx,
1752 event_idx,
1753 last_event: last_event_desc,
1754 expected_checksum: m.expected,
1755 actual_checksum: m.actual,
1756 }
1757 });
1758
1759 Ok(GateReport {
1760 passed: result.ok(),
1761 total_steps: result.total_steps,
1762 running: result.running,
1763 unprocessed_events: result.unprocessed_events,
1764 total_frames: result.total_frames,
1765 expected_frames: frame_checksums.len() as u64,
1766 final_checksum_chain: result.final_checksum_chain,
1767 diff,
1768 })
1769}
1770
1771#[derive(Debug, Clone)]
1773pub struct GateReport {
1774 pub passed: bool,
1776 pub total_steps: u64,
1778 pub running: bool,
1780 pub unprocessed_events: Vec<Event>,
1782 pub total_frames: u64,
1784 pub expected_frames: u64,
1786 pub final_checksum_chain: u64,
1788 pub diff: Option<GateDiff>,
1790}
1791
1792impl GateReport {
1793 pub fn format(&self) -> String {
1795 if self.passed {
1796 format!(
1797 "PASS: {}/{} frames verified, final_chain={:016x}, steps={}, running={}, unprocessed_events={}",
1798 self.total_frames,
1799 self.expected_frames,
1800 self.final_checksum_chain,
1801 self.total_steps,
1802 self.running,
1803 self.unprocessed_events.len()
1804 )
1805 } else if let Some(d) = &self.diff {
1806 format!(
1807 "FAIL at frame {} (after event #{}: {}): expected {:016x}, got {:016x}",
1808 d.frame_idx, d.event_idx, d.last_event, d.expected_checksum, d.actual_checksum
1809 )
1810 } else {
1811 format!(
1812 "FAIL: {}/{} frames, unknown mismatch",
1813 self.total_frames, self.expected_frames
1814 )
1815 }
1816 }
1817}
1818
1819#[derive(Debug, Clone)]
1821pub struct GateDiff {
1822 pub frame_idx: u64,
1824 pub event_idx: u64,
1826 pub last_event: String,
1828 pub expected_checksum: u64,
1830 pub actual_checksum: u64,
1832}
1833
1834#[cfg(test)]
1835mod tests {
1836 use super::*;
1837 use ftui_core::event::{
1838 KeyCode, KeyEvent, KeyEventKind, Modifiers, MouseButton, MouseEvent, MouseEventKind,
1839 PasteEvent,
1840 };
1841 use ftui_render::cell::Cell;
1842 use ftui_render::frame::Frame;
1843 use ftui_runtime::program::{Cmd, Model};
1844 use pretty_assertions::assert_eq;
1845 #[cfg(feature = "tracing")]
1846 use std::sync::{Arc, Mutex};
1847 #[cfg(feature = "tracing")]
1848 use tracing::Subscriber;
1849 #[cfg(feature = "tracing")]
1850 use tracing::field::{Field, Visit};
1851 #[cfg(feature = "tracing")]
1852 use tracing_subscriber::Layer;
1853 #[cfg(feature = "tracing")]
1854 use tracing_subscriber::filter::LevelFilter;
1855 #[cfg(feature = "tracing")]
1856 use tracing_subscriber::layer::{Context, SubscriberExt};
1857 #[cfg(feature = "tracing")]
1858 use tracing_subscriber::registry::LookupSpan;
1859
1860 #[cfg(feature = "tracing")]
1861 #[derive(Default, Clone)]
1862 struct TraceCaptureLayer {
1863 spans: Arc<Mutex<Vec<String>>>,
1864 events: Arc<Mutex<Vec<String>>>,
1865 }
1866
1867 #[cfg(feature = "tracing")]
1868 #[derive(Default)]
1869 struct EventMessageVisitor {
1870 message: Option<String>,
1871 }
1872
1873 #[cfg(feature = "tracing")]
1874 impl Visit for EventMessageVisitor {
1875 fn record_str(&mut self, field: &Field, value: &str) {
1876 if field.name() == "message" {
1877 self.message = Some(value.to_string());
1878 }
1879 }
1880
1881 fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) {
1882 if field.name() == "message" {
1883 self.message = Some(format!("{value:?}"));
1884 }
1885 }
1886 }
1887
1888 #[cfg(feature = "tracing")]
1889 impl<S> Layer<S> for TraceCaptureLayer
1890 where
1891 S: Subscriber + for<'lookup> LookupSpan<'lookup>,
1892 {
1893 fn on_new_span(
1894 &self,
1895 attrs: &tracing::span::Attributes<'_>,
1896 _id: &tracing::span::Id,
1897 _ctx: Context<'_, S>,
1898 ) {
1899 self.spans
1900 .lock()
1901 .expect("span capture lock")
1902 .push(attrs.metadata().name().to_string());
1903 }
1904
1905 fn on_event(&self, event: &tracing::Event<'_>, _ctx: Context<'_, S>) {
1906 let mut visitor = EventMessageVisitor::default();
1907 event.record(&mut visitor);
1908 let message = visitor.message.unwrap_or_default();
1909 self.events
1910 .lock()
1911 .expect("event capture lock")
1912 .push(format!("{}:{}", event.metadata().level(), message));
1913 }
1914 }
1915
1916 struct Counter {
1919 value: i32,
1920 }
1921
1922 #[derive(Debug)]
1923 enum CounterMsg {
1924 Increment,
1925 Decrement,
1926 Reset,
1927 Quit,
1928 }
1929
1930 impl From<Event> for CounterMsg {
1931 fn from(event: Event) -> Self {
1932 match event {
1933 Event::Key(k) if k.code == KeyCode::Char('+') => CounterMsg::Increment,
1934 Event::Key(k) if k.code == KeyCode::Char('-') => CounterMsg::Decrement,
1935 Event::Key(k) if k.code == KeyCode::Char('r') => CounterMsg::Reset,
1936 Event::Key(k) if k.code == KeyCode::Char('q') => CounterMsg::Quit,
1937 Event::Tick => CounterMsg::Increment,
1938 _ => CounterMsg::Increment,
1939 }
1940 }
1941 }
1942
1943 impl Model for Counter {
1944 type Message = CounterMsg;
1945
1946 fn init(&mut self) -> Cmd<Self::Message> {
1947 Cmd::none()
1948 }
1949
1950 fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
1951 match msg {
1952 CounterMsg::Increment => {
1953 self.value += 1;
1954 Cmd::none()
1955 }
1956 CounterMsg::Decrement => {
1957 self.value -= 1;
1958 Cmd::none()
1959 }
1960 CounterMsg::Reset => {
1961 self.value = 0;
1962 Cmd::none()
1963 }
1964 CounterMsg::Quit => Cmd::quit(),
1965 }
1966 }
1967
1968 fn view(&self, frame: &mut Frame) {
1969 let text = format!("Count: {}", self.value);
1970 for (i, c) in text.chars().enumerate() {
1971 if (i as u16) < frame.width() {
1972 frame.buffer.set_raw(i as u16, 0, Cell::from_char(c));
1973 }
1974 }
1975 }
1976 }
1977
1978 fn key_event(c: char) -> Event {
1979 Event::Key(KeyEvent {
1980 code: KeyCode::Char(c),
1981 modifiers: Modifiers::empty(),
1982 kind: KeyEventKind::Press,
1983 })
1984 }
1985
1986 fn parse_single_input_event(data_json: &str) -> Event {
1987 let line = format!(
1988 r#"{{"schema_version":"{}","event":"input","ts_ns":0,"data":{}}}"#,
1989 SCHEMA_VERSION, data_json
1990 );
1991 let trace = SessionTrace::from_jsonl(&line).expect("input JSON should parse");
1992 trace
1993 .records
1994 .into_iter()
1995 .next()
1996 .and_then(|record| match record {
1997 TraceRecord::Input { event, .. } => Some(event),
1998 _ => None,
1999 })
2000 .expect("expected single input record")
2001 }
2002
2003 fn new_counter(value: i32) -> Counter {
2004 Counter { value }
2005 }
2006
2007 struct ObservedModel {
2009 seen: std::rc::Rc<std::cell::RefCell<Vec<Event>>>,
2010 init_count: std::rc::Rc<std::cell::Cell<u32>>,
2011 quit_on_init: bool,
2012 honor_quit: bool,
2013 }
2014
2015 impl Model for ObservedModel {
2016 type Message = Event;
2017
2018 fn init(&mut self) -> Cmd<Event> {
2019 self.init_count.set(self.init_count.get() + 1);
2020 if self.quit_on_init {
2021 Cmd::quit()
2022 } else {
2023 Cmd::tick(Duration::from_millis(10))
2024 }
2025 }
2026
2027 fn update(&mut self, event: Event) -> Cmd<Event> {
2028 let quit = event == key_event('q') && self.honor_quit;
2029 self.seen.borrow_mut().push(event);
2030 if quit { Cmd::quit() } else { Cmd::none() }
2031 }
2032
2033 fn view(&self, frame: &mut Frame) {
2034 frame.buffer.set_raw(0, 0, Cell::from_char('X'));
2035 }
2036 }
2037
2038 fn observed_model(quit_on_init: bool, honor_quit: bool) -> ObservedModel {
2039 ObservedModel {
2040 seen: Default::default(),
2041 init_count: Default::default(),
2042 quit_on_init,
2043 honor_quit,
2044 }
2045 }
2046
2047 #[test]
2048 fn non_rendering_quit_replays_actual_updates_and_exact_accepted_tail() {
2049 let model = observed_model(false, true);
2050 let recorded_seen = model.seen.clone();
2051 let mut recorder = SessionRecorder::new(model, 20, 2, 7);
2052 recorder.init().unwrap();
2053 let tail = vec![
2054 Event::Paste(PasteEvent::bracketed("尾巴 🦀")),
2055 Event::Resize {
2056 width: 33,
2057 height: 4,
2058 },
2059 ];
2060 for event in [key_event('+'), key_event('q')]
2061 .into_iter()
2062 .chain(tail.clone())
2063 {
2064 recorder.push_event(9, event).unwrap();
2065 }
2066 let outcome = recorder.step().unwrap();
2067 assert_eq!(outcome.events_processed, 2);
2068 assert_eq!(outcome.events_pending, 2);
2069 assert!(!outcome.running && !outcome.rendered);
2070 assert_eq!(
2071 *recorded_seen.borrow(),
2072 vec![key_event('+'), key_event('q')]
2073 );
2074 let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2075 let model = observed_model(false, true);
2076 let replayed_seen = model.seen.clone();
2077 let init_count = model.init_count.clone();
2078 let result = replay(model, &trace).unwrap();
2079 assert!(result.ok());
2080 assert_eq!(result.total_steps, 2);
2081 assert_eq!(result.total_frames, 1);
2082 assert!(!result.running);
2083 assert_eq!(result.unprocessed_events, tail);
2084 assert_eq!(*replayed_seen.borrow(), *recorded_seen.borrow());
2085 assert_eq!(init_count.get(), 1);
2086 let gate = gate_trace(observed_model(false, true), &trace).unwrap();
2087 assert!(gate.passed);
2088 assert_eq!(gate.total_steps, 2);
2089 assert!(!gate.running);
2090 assert_eq!(gate.unprocessed_events, tail);
2091 assert!(gate.format().contains("unprocessed_events=2"));
2092 assert!(!gate.format().contains("尾巴"));
2093
2094 assert!(matches!(
2097 replay(observed_model(false, false), &trace),
2098 Err(ReplayError::StepMismatch { step_idx: 1, .. })
2099 ));
2100 }
2101
2102 #[test]
2103 fn initialization_quit_has_no_frame_and_recovers_preinit_input() {
2104 let mut recorder = SessionRecorder::new(observed_model(true, true), 20, 2, 7);
2105 recorder.push_event(1, key_event('+')).unwrap();
2106 recorder.resize(2, 40, 4).unwrap();
2107 recorder.init().unwrap();
2108 assert_eq!(recorder.program().size(), (20, 2));
2109 assert!(recorder.program().outputs().last_buffer.is_none());
2110 let stopped = recorder.step().unwrap();
2111 assert_eq!(stopped.events_pending, 2);
2112 assert_eq!(stopped.events_processed, 0);
2113 let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2114 let model = observed_model(true, true);
2115 let seen = model.seen.clone();
2116 let init_count = model.init_count.clone();
2117 let result = replay(model, &trace).unwrap();
2118 assert!(result.ok());
2119 assert!(!result.running);
2120 assert_eq!(result.total_frames, 0);
2121 assert_eq!(result.total_steps, 2);
2122 assert_eq!(init_count.get(), 1);
2123 assert!(seen.borrow().is_empty());
2124 assert_eq!(
2125 result.unprocessed_events,
2126 vec![
2127 key_event('+'),
2128 Event::Resize {
2129 width: 40,
2130 height: 4
2131 }
2132 ]
2133 );
2134 }
2135
2136 #[test]
2137 fn idle_steps_and_clock_deltas_replay_independently_of_metadata_timestamps() {
2138 let model = observed_model(false, true);
2139 let seen = model.seen.clone();
2140 let mut recorder = SessionRecorder::new(model, 20, 2, 7);
2141 recorder.init().unwrap();
2142 assert!(!recorder.step().unwrap().rendered);
2143 recorder.advance_time(1, Duration::from_millis(9));
2144 assert!(!recorder.step().unwrap().rendered);
2145 recorder.advance_time(2, Duration::from_millis(1));
2146 assert!(recorder.step().unwrap().rendered);
2147 assert!(!recorder.step().unwrap().rendered);
2148 assert_eq!(*seen.borrow(), vec![Event::Tick]);
2149 let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2150 let model = observed_model(false, true);
2151 let replayed = model.seen.clone();
2152 let result = replay(model, &trace).unwrap();
2153 assert!(result.ok());
2154 assert_eq!(result.total_steps, 5);
2155 assert_eq!(result.total_frames, 2);
2156 assert_eq!(*replayed.borrow(), vec![Event::Tick]);
2157 }
2158
2159 #[test]
2160 fn trace_requires_observed_boundaries_without_implicit_flush_or_stale_frames() {
2161 let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
2162 recorder.init().unwrap();
2163 recorder.push_event(1, key_event('q')).unwrap();
2164 recorder.step().unwrap();
2165 let trace = recorder.finish();
2166 trace.validate().unwrap();
2167 let quit_idx = trace.records.len() - 2;
2168 for missing in [1, 2, quit_idx] {
2169 let mut changed = trace.clone();
2170 changed.records.remove(missing);
2171 assert!(changed.validate().is_err(), "missing record {missing}");
2172 assert!(replay(new_counter(0), &changed).is_err());
2173 }
2174 let mut duplicate = trace.clone();
2175 duplicate
2176 .records
2177 .insert(quit_idx, trace.records[quit_idx].clone());
2178 assert!(duplicate.validate().is_err());
2179 let mut reordered = trace.clone();
2180 reordered.records.swap(1, 2);
2181 assert!(reordered.validate().is_err());
2182 let mut bad_count = trace.clone();
2183 if let TraceRecord::Step { result, .. } = &mut bad_count.records[quit_idx] {
2184 result.events_pending = 1;
2185 }
2186 assert!(bad_count.validate().is_err());
2187 let mut after_quit = trace.clone();
2188 after_quit.records.insert(
2189 quit_idx + 1,
2190 TraceRecord::Input {
2191 ts_ns: 1,
2192 event: key_event('+'),
2193 },
2194 );
2195 assert!(after_quit.validate().is_err());
2196
2197 let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
2198 recorder.init().unwrap();
2199 recorder.push_event(1, key_event('+')).unwrap();
2200 assert!(recorder.finish().validate().is_err());
2201 }
2202
2203 #[test]
2204 fn recorder_rejects_before_changing_trace_or_timestamp_and_replays_recovery() {
2205 let mut recorder = SessionRecorder::new(new_counter(0), 80, 24, 0);
2206 recorder.init().unwrap();
2207 for _ in 0..crate::WebEventSource::MAX_EVENTS {
2208 recorder.push_event(1, key_event('+')).unwrap();
2209 }
2210 let records_before = recorder.records.len();
2211 assert!(matches!(
2212 recorder.push_event(2, key_event('-')),
2213 Err(WebBackendError::InputQueueFull { .. })
2214 ));
2215 assert!(matches!(
2216 recorder.resize(3, 120, 40),
2217 Err(WebBackendError::InputQueueFull { .. })
2218 ));
2219 assert_eq!(recorder.records.len(), records_before);
2220 assert_eq!(recorder.current_ts_ns, 1);
2221 assert_eq!(recorder.program.size(), (80, 24));
2222 assert_eq!(
2223 recorder.step().unwrap().events_processed as usize,
2224 crate::WebEventSource::MAX_EVENTS
2225 );
2226 recorder.push_event(2, key_event('-')).unwrap();
2227 recorder.resize(3, 120, 40).unwrap();
2228 assert_eq!(recorder.step().unwrap().events_processed, 2);
2229 let trace = recorder.finish();
2230 trace.validate().unwrap();
2231 assert!(replay(new_counter(0), &trace).unwrap().ok());
2232 }
2233
2234 #[test]
2235 fn replay_rejects_an_overfull_batch_without_inserting_unrecorded_steps() {
2236 let mut recorder = SessionRecorder::new(new_counter(0), 80, 24, 0);
2237 recorder.init().unwrap();
2238 let mut trace = recorder.finish();
2239 let summary_index = trace.records.len() - 1;
2240 trace.records.splice(
2241 summary_index..summary_index,
2242 (0..=crate::WebEventSource::MAX_EVENTS).map(|_| TraceRecord::Input {
2243 ts_ns: 0,
2244 event: key_event('+'),
2245 }),
2246 );
2247 trace.records.insert(
2248 trace.records.len() - 1,
2249 TraceRecord::Step {
2250 step_idx: 1,
2251 ts_ns: 0,
2252 init: false,
2253 clock: Duration::ZERO,
2254 result: StepResult {
2255 running: false,
2256 rendered: false,
2257 events_processed: 0,
2258 events_pending: crate::WebEventSource::MAX_EVENTS as u32 + 1,
2259 frame_idx: 1,
2260 },
2261 },
2262 );
2263 trace.validate().unwrap();
2264 assert!(matches!(
2265 replay(new_counter(0), &trace),
2266 Err(ReplayError::Backend(WebBackendError::InputQueueFull {
2267 limit: crate::WebInputLimit::Events,
2268 ..
2269 }))
2270 ));
2271 }
2272
2273 #[test]
2276 fn fnv1a64_pair_is_deterministic() {
2277 let a = fnv1a64_pair(0, 1234);
2278 let b = fnv1a64_pair(0, 1234);
2279 assert_eq!(a, b);
2280 }
2281
2282 #[test]
2283 fn fnv1a64_pair_differs_for_different_input() {
2284 assert_ne!(fnv1a64_pair(0, 1), fnv1a64_pair(0, 2));
2285 assert_ne!(fnv1a64_pair(1, 0), fnv1a64_pair(2, 0));
2286 }
2287
2288 #[test]
2291 fn recorder_produces_header_and_summary() {
2292 let mut rec = SessionRecorder::new(new_counter(0), 80, 24, 42);
2293 rec.init().unwrap();
2294
2295 let trace = rec.finish();
2296 assert_eq!(trace.records.len(), 4); assert!(matches!(
2300 &trace.records[0],
2301 TraceRecord::Header {
2302 seed: 42,
2303 cols: 80,
2304 rows: 24,
2305 ..
2306 }
2307 ));
2308
2309 assert!(matches!(
2311 trace.records.last().unwrap(),
2312 TraceRecord::Summary {
2313 total_frames: 1,
2314 ..
2315 }
2316 ));
2317 }
2318
2319 #[test]
2320 fn recorder_captures_init_frame() {
2321 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2322 rec.init().unwrap();
2323
2324 let trace = rec.finish();
2325 let frames: Vec<_> = trace
2326 .records
2327 .iter()
2328 .filter(|r| matches!(r, TraceRecord::Frame { .. }))
2329 .collect();
2330 assert_eq!(frames.len(), 1);
2331
2332 if let TraceRecord::Frame {
2333 frame_idx,
2334 checksum,
2335 ..
2336 } = &frames[0]
2337 {
2338 assert_eq!(*frame_idx, 0);
2339 assert_ne!(*checksum, 0); }
2341 }
2342
2343 #[test]
2346 fn record_replay_identical_checksums() {
2347 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2349 rec.init().unwrap();
2350
2351 rec.push_event(1_000_000, key_event('+'))
2352 .expect("key admission");
2353 rec.push_event(2_000_000, key_event('+'))
2354 .expect("key admission");
2355 rec.push_event(3_000_000, key_event('-'))
2356 .expect("key admission");
2357 rec.step().unwrap();
2358
2359 rec.push_event(16_000_000, key_event('+'))
2360 .expect("key admission");
2361 rec.step().unwrap();
2362
2363 let trace = rec.finish();
2364 assert_eq!(trace.frame_count(), 3); let result = replay(new_counter(0), &trace).unwrap();
2368 assert!(result.ok(), "replay mismatch: {:?}", result.first_mismatch);
2369 assert_eq!(result.total_frames, 3);
2370 assert_eq!(
2371 result.final_checksum_chain,
2372 trace.final_checksum_chain().unwrap()
2373 );
2374 }
2375
2376 #[test]
2377 fn replay_detects_different_initial_state() {
2378 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2380 rec.init().unwrap();
2381 let trace = rec.finish();
2382
2383 let result = replay(new_counter(5), &trace).unwrap();
2385 assert!(!result.ok());
2386 assert_eq!(result.first_mismatch.as_ref().unwrap().frame_idx, 0);
2387 }
2388
2389 #[test]
2390 fn replay_detects_divergence_after_events() {
2391 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2393 rec.init().unwrap();
2394
2395 rec.push_event(1_000_000, key_event('+'))
2396 .expect("key admission");
2397 rec.push_event(2_000_000, key_event('+'))
2398 .expect("key admission");
2399 rec.step().unwrap();
2400
2401 let trace = rec.finish();
2402
2403 let result = replay(new_counter(1), &trace).unwrap();
2405 assert!(!result.ok());
2406 }
2407
2408 #[test]
2411 fn resize_is_recorded_and_replayed() {
2412 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2413 rec.init().unwrap();
2414
2415 rec.resize(5_000_000, 40, 2).expect("resize admission");
2416 rec.step().unwrap();
2417
2418 let trace = rec.finish();
2419
2420 assert!(trace.records.iter().any(|r| matches!(
2422 r,
2423 TraceRecord::Resize {
2424 cols: 40,
2425 rows: 2,
2426 ..
2427 }
2428 )));
2429
2430 let result = replay(new_counter(0), &trace).unwrap();
2432 assert!(
2433 result.ok(),
2434 "resize replay mismatch: {:?}",
2435 result.first_mismatch
2436 );
2437 }
2438
2439 #[test]
2442 fn multi_step_record_replay() {
2443 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2444 rec.init().unwrap();
2445
2446 for i in 0..5 {
2447 rec.push_event(i * 16_000_000, key_event('+'))
2448 .expect("key admission");
2449 rec.step().unwrap();
2450 }
2451
2452 let trace = rec.finish();
2453 assert_eq!(trace.frame_count(), 6); let result = replay(new_counter(0), &trace).unwrap();
2456 assert!(
2457 result.ok(),
2458 "multi-step mismatch: {:?}",
2459 result.first_mismatch
2460 );
2461 assert_eq!(result.total_frames, 6);
2462 }
2463
2464 #[test]
2467 fn quit_stops_recording() {
2468 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2469 rec.init().unwrap();
2470
2471 rec.push_event(1_000_000, key_event('+'))
2472 .expect("key admission");
2473 rec.push_event(2_000_000, key_event('q'))
2474 .expect("quit admission");
2475 let result = rec.step().unwrap();
2476 assert!(!result.running);
2477
2478 let trace = rec.finish();
2479 assert_eq!(trace.frame_count(), 1);
2481 }
2482
2483 #[test]
2486 fn empty_session_replay() {
2487 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2488 rec.init().unwrap();
2489 let trace = rec.finish();
2490
2491 let result = replay(new_counter(0), &trace).unwrap();
2492 assert!(result.ok());
2493 assert_eq!(result.total_frames, 1); }
2495
2496 #[test]
2499 fn session_trace_frame_count() {
2500 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2501 rec.init().unwrap();
2502 rec.push_event(1_000_000, key_event('+'))
2503 .expect("key admission");
2504 rec.step().unwrap();
2505 let trace = rec.finish();
2506 assert_eq!(trace.frame_count(), 2);
2507 }
2508
2509 #[test]
2510 fn session_trace_final_checksum_chain() {
2511 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2512 rec.init().unwrap();
2513 let trace = rec.finish();
2514 assert!(trace.final_checksum_chain().is_some());
2515 assert_ne!(trace.final_checksum_chain().unwrap(), 0);
2516 }
2517
2518 #[test]
2521 fn replay_missing_header_returns_error() {
2522 let trace = SessionTrace { records: vec![] };
2523 let result = replay(new_counter(0), &trace);
2524 assert!(matches!(result, Err(ReplayError::MissingHeader)));
2525 }
2526
2527 #[test]
2528 fn replay_non_header_first_returns_error() {
2529 let trace = SessionTrace {
2530 records: vec![TraceRecord::Tick { ts_ns: 0 }],
2531 };
2532 let result = replay(new_counter(0), &trace);
2533 assert!(matches!(result, Err(ReplayError::MissingHeader)));
2534 }
2535
2536 #[test]
2537 fn trace_validate_missing_summary_returns_typed_error() {
2538 let trace = SessionTrace {
2539 records: vec![TraceRecord::Header {
2540 seed: 0,
2541 cols: 80,
2542 rows: 24,
2543 profile: "modern".to_string(),
2544 }],
2545 };
2546 let result = trace.validate();
2547 assert_eq!(result, Err(TraceValidationError::MissingSummary));
2548 }
2549
2550 #[test]
2551 fn trace_validate_summary_frame_count_mismatch_returns_typed_error() {
2552 let trace = SessionTrace {
2553 records: vec![
2554 TraceRecord::Header {
2555 seed: 0,
2556 cols: 80,
2557 rows: 24,
2558 profile: "modern".to_string(),
2559 },
2560 TraceRecord::Frame {
2561 frame_idx: 0,
2562 ts_ns: 0,
2563 checksum: 0x1,
2564 checksum_chain: 0x10,
2565 },
2566 TraceRecord::Summary {
2567 total_frames: 2,
2568 final_checksum_chain: 0x10,
2569 },
2570 ],
2571 };
2572 let result = trace.validate();
2573 assert_eq!(
2574 result,
2575 Err(TraceValidationError::SummaryFrameCountMismatch {
2576 expected: 1,
2577 actual: 2,
2578 })
2579 );
2580 }
2581
2582 #[test]
2583 fn trace_validate_frame_index_gap_returns_typed_error() {
2584 let trace = SessionTrace {
2585 records: vec![
2586 TraceRecord::Header {
2587 seed: 0,
2588 cols: 80,
2589 rows: 24,
2590 profile: "modern".to_string(),
2591 },
2592 TraceRecord::Frame {
2593 frame_idx: 1,
2594 ts_ns: 0,
2595 checksum: 0x1,
2596 checksum_chain: 0x10,
2597 },
2598 TraceRecord::Summary {
2599 total_frames: 1,
2600 final_checksum_chain: 0x10,
2601 },
2602 ],
2603 };
2604 let result = trace.validate();
2605 assert_eq!(
2606 result,
2607 Err(TraceValidationError::FrameIndexMismatch {
2608 expected: 0,
2609 actual: 1,
2610 })
2611 );
2612 }
2613
2614 #[test]
2615 fn trace_validate_timestamp_regression_returns_typed_error() {
2616 let trace = SessionTrace {
2617 records: vec![
2618 TraceRecord::Header {
2619 seed: 0,
2620 cols: 80,
2621 rows: 24,
2622 profile: "modern".to_string(),
2623 },
2624 TraceRecord::Tick { ts_ns: 20 },
2625 TraceRecord::Tick { ts_ns: 10 },
2626 TraceRecord::Summary {
2627 total_frames: 0,
2628 final_checksum_chain: 0,
2629 },
2630 ],
2631 };
2632 let result = trace.validate();
2633 assert_eq!(
2634 result,
2635 Err(TraceValidationError::TimestampRegression {
2636 previous: 20,
2637 current: 10,
2638 record_index: 2,
2639 })
2640 );
2641 }
2642
2643 #[test]
2644 fn replay_validates_trace_before_execution() {
2645 let trace = SessionTrace {
2646 records: vec![TraceRecord::Header {
2647 seed: 0,
2648 cols: 80,
2649 rows: 24,
2650 profile: "modern".to_string(),
2651 }],
2652 };
2653 let result = replay(new_counter(0), &trace);
2654 assert_eq!(
2655 result,
2656 Err(ReplayError::InvalidTrace(
2657 TraceValidationError::MissingSummary
2658 ))
2659 );
2660 }
2661
2662 #[test]
2665 fn same_inputs_produce_same_trace_checksums() {
2666 fn record_session() -> SessionTrace {
2667 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2668 rec.init().unwrap();
2669
2670 rec.push_event(1_000_000, key_event('+'))
2671 .expect("key admission");
2672 rec.push_event(2_000_000, key_event('+'))
2673 .expect("key admission");
2674 rec.push_event(3_000_000, key_event('-'))
2675 .expect("key admission");
2676 rec.step().unwrap();
2677
2678 rec.push_event(16_000_000, key_event('+'))
2679 .expect("key admission");
2680 rec.step().unwrap();
2681
2682 rec.finish()
2683 }
2684
2685 let t1 = record_session();
2686 let t2 = record_session();
2687 let t3 = record_session();
2688
2689 let checksums = |t: &SessionTrace| -> Vec<u64> {
2691 t.records
2692 .iter()
2693 .filter_map(|r| match r {
2694 TraceRecord::Frame { checksum, .. } => Some(*checksum),
2695 _ => None,
2696 })
2697 .collect()
2698 };
2699
2700 assert_eq!(checksums(&t1), checksums(&t2));
2701 assert_eq!(checksums(&t2), checksums(&t3));
2702 assert_eq!(t1.final_checksum_chain(), t2.final_checksum_chain());
2703 }
2704
2705 #[test]
2708 fn mouse_event_record_replay() {
2709 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2710 rec.init().unwrap();
2711
2712 let mouse = Event::Mouse(MouseEvent {
2713 kind: MouseEventKind::Down(MouseButton::Left),
2714 x: 5,
2715 y: 0,
2716 modifiers: Modifiers::empty(),
2717 });
2718 rec.push_event(1_000_000, mouse).expect("mouse admission");
2719 rec.step().unwrap();
2720
2721 let trace = rec.finish();
2722 let result = replay(new_counter(0), &trace).unwrap();
2723 assert!(result.ok());
2724 }
2725
2726 #[test]
2727 fn paste_event_record_replay() {
2728 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2729 rec.init().unwrap();
2730
2731 let paste = Event::Paste(PasteEvent::bracketed("hello"));
2732 rec.push_event(1_000_000, paste).expect("paste admission");
2733 rec.step().unwrap();
2734
2735 let trace = rec.finish();
2736 let result = replay(new_counter(0), &trace).unwrap();
2737 assert!(result.ok());
2738 }
2739
2740 #[test]
2741 fn focus_event_record_replay() {
2742 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2743 rec.init().unwrap();
2744
2745 rec.push_event(1_000_000, Event::Focus(true))
2746 .expect("focus admission");
2747 rec.push_event(2_000_000, Event::Focus(false))
2748 .expect("focus admission");
2749 rec.step().unwrap();
2750
2751 let trace = rec.finish();
2752 let result = replay(new_counter(0), &trace).unwrap();
2753 assert!(result.ok());
2754 }
2755
2756 #[test]
2757 fn ime_event_record_replay() {
2758 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2759 rec.init().unwrap();
2760
2761 rec.push_event(1_000_000, Event::Ime(ImeEvent::start()))
2762 .expect("IME start admission");
2763 rec.push_event(2_000_000, Event::Ime(ImeEvent::update("你")))
2764 .expect("IME update admission");
2765 rec.push_event(3_000_000, Event::Ime(ImeEvent::commit("你好")))
2766 .expect("IME commit admission");
2767 rec.step().unwrap();
2768
2769 let trace = rec.finish();
2770 let result = replay(new_counter(0), &trace).unwrap();
2771 assert!(result.ok());
2772 }
2773
2774 #[test]
2777 fn checksum_chain_is_cumulative() {
2778 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2779 rec.init().unwrap();
2780
2781 rec.push_event(1_000_000, key_event('+'))
2782 .expect("key admission");
2783 rec.step().unwrap();
2784
2785 rec.push_event(2_000_000, key_event('+'))
2786 .expect("key admission");
2787 rec.step().unwrap();
2788
2789 let trace = rec.finish();
2790 let frame_records: Vec<_> = trace
2791 .records
2792 .iter()
2793 .filter_map(|r| match r {
2794 TraceRecord::Frame {
2795 checksum,
2796 checksum_chain,
2797 ..
2798 } => Some((*checksum, *checksum_chain)),
2799 _ => None,
2800 })
2801 .collect();
2802
2803 assert_eq!(frame_records.len(), 3);
2804
2805 let (c0, chain0) = frame_records[0];
2807 assert_eq!(chain0, fnv1a64_pair(0, c0));
2808
2809 let (c1, chain1) = frame_records[1];
2810 assert_eq!(chain1, fnv1a64_pair(chain0, c1));
2811
2812 let (c2, chain2) = frame_records[2];
2813 assert_eq!(chain2, fnv1a64_pair(chain1, c2));
2814
2815 assert_eq!(trace.final_checksum_chain(), Some(chain2));
2817 }
2818
2819 #[test]
2822 fn recorder_exposes_program() {
2823 let mut rec = SessionRecorder::new(new_counter(42), 20, 1, 0);
2824 rec.init().unwrap();
2825 assert_eq!(rec.program().model().value, 42);
2826 }
2827
2828 #[test]
2831 fn replay_result_ok_when_no_mismatch() {
2832 let r = ReplayResult {
2833 total_steps: 5,
2834 running: true,
2835 unprocessed_events: Vec::new(),
2836 total_frames: 5,
2837 final_checksum_chain: 123,
2838 first_mismatch: None,
2839 };
2840 assert!(r.ok());
2841 }
2842
2843 #[test]
2844 fn replay_result_not_ok_when_mismatch() {
2845 let r = ReplayResult {
2846 total_steps: 5,
2847 running: true,
2848 unprocessed_events: Vec::new(),
2849 total_frames: 5,
2850 final_checksum_chain: 123,
2851 first_mismatch: Some(ReplayMismatch {
2852 frame_idx: 2,
2853 expected: 100,
2854 actual: 200,
2855 }),
2856 };
2857 assert!(!r.ok());
2858 }
2859
2860 #[test]
2861 fn replay_error_display() {
2862 assert_eq!(
2863 ReplayError::MissingHeader.to_string(),
2864 "trace missing header record"
2865 );
2866 let invalid = ReplayError::InvalidTrace(TraceValidationError::MissingSummary);
2867 assert_eq!(
2868 invalid.to_string(),
2869 "invalid trace: trace is missing summary"
2870 );
2871 let be = ReplayError::Backend(WebBackendError::Unsupported("test"));
2872 assert!(be.to_string().contains("test"));
2873 }
2874
2875 #[test]
2878 fn trace_record_header_to_jsonl() {
2879 let r = TraceRecord::Header {
2880 seed: 42,
2881 cols: 80,
2882 rows: 24,
2883 profile: "modern".to_string(),
2884 };
2885 let line = r.to_jsonl();
2886 assert!(line.contains("\"event\":\"trace_header\""));
2887 assert!(line.contains("\"schema_version\":\"golden-trace-v2\""));
2888 assert!(line.contains("\"seed\":42"));
2889 assert!(line.contains("\"cols\":80"));
2890 assert!(line.contains("\"rows\":24"));
2891 assert!(line.contains("\"profile\":\"modern\""));
2892 }
2893
2894 #[test]
2895 fn trace_record_input_key_to_jsonl() {
2896 let r = TraceRecord::Input {
2897 ts_ns: 1_000_000,
2898 event: key_event('+'),
2899 };
2900 let line = r.to_jsonl();
2901 assert!(line.contains("\"event\":\"input\""));
2902 assert!(line.contains("\"ts_ns\":1000000"));
2903 assert!(line.contains("\"kind\":\"key\""));
2904 assert!(line.contains("\"code\":\"char:+\""));
2905 }
2906
2907 #[test]
2908 fn trace_record_resize_to_jsonl() {
2909 let r = TraceRecord::Resize {
2910 ts_ns: 5_000_000,
2911 cols: 120,
2912 rows: 40,
2913 };
2914 let line = r.to_jsonl();
2915 assert!(line.contains("\"event\":\"resize\""));
2916 assert!(line.contains("\"cols\":120"));
2917 assert!(line.contains("\"rows\":40"));
2918 }
2919
2920 #[test]
2921 fn trace_record_frame_to_jsonl() {
2922 let r = TraceRecord::Frame {
2923 frame_idx: 3,
2924 ts_ns: 48_000_000,
2925 checksum: 0xDEADBEEF,
2926 checksum_chain: 0xCAFEBABE,
2927 };
2928 let line = r.to_jsonl();
2929 assert!(line.contains("\"event\":\"frame\""));
2930 assert!(line.contains("\"frame_idx\":3"));
2931 assert!(line.contains("\"frame_hash\":\"00000000deadbeef\""));
2932 assert!(line.contains("\"checksum_chain\":\"00000000cafebabe\""));
2933 }
2934
2935 #[test]
2936 fn trace_record_summary_to_jsonl() {
2937 let r = TraceRecord::Summary {
2938 total_frames: 10,
2939 final_checksum_chain: 0x1234567890ABCDEF,
2940 };
2941 let line = r.to_jsonl();
2942 assert!(line.contains("\"event\":\"trace_summary\""));
2943 assert!(line.contains("\"total_frames\":10"));
2944 assert!(line.contains("\"final_checksum_chain\":\"1234567890abcdef\""));
2945 }
2946
2947 #[test]
2950 fn jsonl_round_trip_full_session() {
2951 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 42);
2953 rec.init().unwrap();
2954 rec.push_event(1_000_000, key_event('+'))
2955 .expect("key admission");
2956 rec.push_event(2_000_000, key_event('+'))
2957 .expect("key admission");
2958 rec.step().unwrap();
2959 let trace = rec.finish();
2960
2961 let jsonl = trace.to_jsonl();
2963 assert!(!jsonl.is_empty());
2964
2965 let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
2967 assert_eq!(parsed.records.len(), trace.records.len());
2968 assert_eq!(parsed.frame_count(), trace.frame_count());
2969 assert_eq!(parsed.final_checksum_chain(), trace.final_checksum_chain());
2970 }
2971
2972 #[test]
2973 fn jsonl_round_trip_preserves_events() {
2974 let events = vec![
2975 key_event('+'),
2976 key_event('-'),
2977 Event::Key(KeyEvent {
2978 code: KeyCode::Enter,
2979 modifiers: Modifiers::CTRL | Modifiers::SHIFT,
2980 kind: KeyEventKind::Press,
2981 }),
2982 Event::Key(KeyEvent {
2983 code: KeyCode::F(12),
2984 modifiers: Modifiers::ALT,
2985 kind: KeyEventKind::Repeat,
2986 }),
2987 Event::Mouse(MouseEvent {
2988 kind: MouseEventKind::Down(MouseButton::Left),
2989 x: 10,
2990 y: 5,
2991 modifiers: Modifiers::empty(),
2992 }),
2993 Event::Mouse(MouseEvent {
2994 kind: MouseEventKind::ScrollDown,
2995 x: 0,
2996 y: 0,
2997 modifiers: Modifiers::CTRL,
2998 }),
2999 Event::Paste(PasteEvent::bracketed("hello world")),
3000 Event::Focus(true),
3001 Event::Focus(false),
3002 Event::Tick,
3003 ];
3004
3005 for (i, event) in events.iter().enumerate() {
3006 let record = TraceRecord::Input {
3007 ts_ns: i as u64 * 1_000_000,
3008 event: event.clone(),
3009 };
3010 let jsonl = record.to_jsonl();
3011 let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
3012 let parsed_record = &parsed.records[0];
3013 let TraceRecord::Input {
3014 event: parsed_event,
3015 ..
3016 } = parsed_record
3017 else {
3018 unreachable!("expected Input record for event {i}");
3019 };
3020
3021 assert_eq!(parsed_event, event, "event {i} round-trip failed: {jsonl}");
3022 }
3023 }
3024
3025 #[test]
3026 fn jsonl_round_trip_with_resize() {
3027 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3028 rec.init().unwrap();
3029 rec.resize(5_000_000, 40, 2).expect("resize admission");
3030 rec.step().unwrap();
3031 let trace = rec.finish();
3032
3033 let jsonl = trace.to_jsonl();
3034 let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
3035
3036 let result = replay(new_counter(0), &parsed).unwrap();
3038 assert!(
3039 result.ok(),
3040 "parsed trace replay failed: {:?}",
3041 result.first_mismatch
3042 );
3043 }
3044
3045 #[test]
3048 fn step_jsonl_preserves_clock_and_requires_all_outcome_fields() {
3049 let record = TraceRecord::Step {
3050 step_idx: 4,
3051 ts_ns: 9,
3052 init: false,
3053 clock: Duration::new(u64::MAX, 999_999_999),
3054 result: StepResult {
3055 running: false,
3056 rendered: false,
3057 events_processed: 3,
3058 events_pending: 2,
3059 frame_idx: 2,
3060 },
3061 };
3062 let json = record.to_jsonl();
3063 assert_eq!(
3064 SessionTrace::from_jsonl(&json).unwrap().records,
3065 vec![record]
3066 );
3067 for field in [
3068 "step_idx",
3069 "ts_ns",
3070 "init",
3071 "clock_secs",
3072 "clock_subsec_nanos",
3073 "running",
3074 "rendered",
3075 "events_processed",
3076 "events_pending",
3077 "frame_idx",
3078 ] {
3079 let changed = json.replace(&format!("\"{field}\":"), "\"unknown\":");
3080 assert!(
3081 SessionTrace::from_jsonl(&changed).is_err(),
3082 "missing {field}"
3083 );
3084 }
3085 for (old, new) in [
3086 (
3087 "\"clock_subsec_nanos\":999999999",
3088 "\"clock_subsec_nanos\":1000000000",
3089 ),
3090 ("\"events_pending\":2", "\"events_pending\":4294967296"),
3091 ("\"events_processed\":3", "\"events_processed\":-1"),
3092 ("\"running\":false", "\"running\":null"),
3093 ("\"running\":false", "\"running\":falseX"),
3094 ("\"events_pending\":2", "\"events_pending\":2.5"),
3095 ("\"events_pending\":2", "\"events_pending\":2e3"),
3096 ("\"events_pending\":2", "\"nested\":{\"events_pending\":2}"),
3097 (
3098 "\"events_pending\":2",
3099 "\"events_pending\":2,\"events_pending\":2",
3100 ),
3101 ] {
3102 assert!(
3103 SessionTrace::from_jsonl(&json.replace(old, new)).is_err(),
3104 "invalid {new}"
3105 );
3106 }
3107 }
3108
3109 #[test]
3110 fn v1_trace_cannot_invent_missing_execution_boundaries() {
3111 let line = r#"{"schema_version":"golden-trace-v1","event":"tick","ts_ns":0}"#;
3112 let error = SessionTrace::from_jsonl(line).unwrap_err();
3113 assert!(error.message.contains("migration required"));
3114 }
3115
3116 #[test]
3117 fn text_payloads_with_braces_quotes_and_unicode_round_trip_in_quit_tail() {
3118 let text = "} { \\\" 🦀/\n\t\0\u{0008}\u{000c}";
3119 let tail = vec![
3120 Event::Paste(PasteEvent::bracketed(text)),
3121 Event::Ime(ImeEvent::commit(text)),
3122 Event::Clipboard(ftui_core::event::ClipboardEvent {
3123 content: text.to_owned(),
3124 source: ClipboardSource::Osc52,
3125 }),
3126 ];
3127 let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
3128 recorder.init().unwrap();
3129 recorder.push_event(0, key_event('q')).unwrap();
3130 for event in &tail {
3131 recorder.push_event(0, event.clone()).unwrap();
3132 }
3133 recorder.step().unwrap();
3134 let jsonl = recorder.finish().to_jsonl();
3135 let escaped = jsonl
3136 .replace('🦀', r"\ud83e\udd80")
3137 .replace('/', r"\/")
3138 .replace(r"\u0008", r"\b")
3139 .replace(r"\u000c", r"\f");
3140 for input in [&jsonl, &escaped] {
3141 let trace = SessionTrace::from_jsonl_validated(input).unwrap();
3142 assert_eq!(
3143 replay(new_counter(0), &trace).unwrap().unprocessed_events,
3144 tail
3145 );
3146 }
3147 }
3148
3149 #[test]
3150 fn malformed_text_escapes_are_rejected_without_changing_content() {
3151 for text in [r"\uZZZZ", r"\ud83e", r"\udd80", r"\ud83e\u0061", r"\q"] {
3152 let line = format!(
3153 r#"{{"schema_version":"{}","event":"input","ts_ns":0,"data":{{"kind":"paste","text":"{}"}}}}"#,
3154 SCHEMA_VERSION, text
3155 );
3156 assert!(SessionTrace::from_jsonl(&line).is_err(), "invalid {text}");
3157 }
3158 }
3159
3160 #[test]
3161 fn chain_only_corruption_cannot_pass_replay_or_gate() {
3162 let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
3163 recorder.init().unwrap();
3164 let mut trace = recorder.finish();
3165 for record in &mut trace.records {
3166 match record {
3167 TraceRecord::Frame { checksum_chain, .. } => *checksum_chain ^= 1,
3168 TraceRecord::Summary {
3169 final_checksum_chain,
3170 ..
3171 } => *final_checksum_chain ^= 1,
3172 _ => {}
3173 }
3174 }
3175 assert!(trace.validate().is_err());
3176 assert!(replay(new_counter(0), &trace).is_err());
3177 assert!(gate_trace(new_counter(0), &trace).is_err());
3178 }
3179
3180 #[test]
3181 fn from_jsonl_empty_is_ok() {
3182 let trace = SessionTrace::from_jsonl("").unwrap();
3183 assert!(trace.records.is_empty());
3184 }
3185
3186 #[test]
3187 fn from_jsonl_unknown_event_fails() {
3188 let line = r#"{"schema_version":"golden-trace-v2","event":"unknown_type","ts_ns":0}"#;
3189 let result = SessionTrace::from_jsonl(line);
3190 assert!(result.is_err());
3191 assert!(result.unwrap_err().message.contains("unknown event type"));
3192 }
3193
3194 #[test]
3195 fn from_jsonl_missing_event_field_fails() {
3196 let line = r#"{"schema_version":"golden-trace-v2","ts_ns":0}"#;
3197 let result = SessionTrace::from_jsonl(line);
3198 assert!(result.is_err());
3199 }
3200
3201 #[test]
3202 fn from_jsonl_missing_schema_version_fails() {
3203 let line = r#"{"event":"tick","ts_ns":0}"#;
3204 let result = SessionTrace::from_jsonl(line);
3205 assert!(result.is_err());
3206 assert!(result.unwrap_err().message.contains("schema_version"));
3207 }
3208
3209 #[test]
3210 fn from_jsonl_schema_matrix_current_writer_version_passes() {
3211 let line = format!(
3212 r#"{{"schema_version":"{}","event":"tick","ts_ns":0}}"#,
3213 SCHEMA_VERSION
3214 );
3215 let trace = SessionTrace::from_jsonl(&line).expect("matching schema should parse");
3216 assert_eq!(trace.records, vec![TraceRecord::Tick { ts_ns: 0 }]);
3217 }
3218
3219 #[test]
3220 fn from_jsonl_schema_matrix_newer_writer_version_fails_with_migration_error() {
3221 let line = r#"{"schema_version":"golden-trace-v3","event":"tick","ts_ns":0}"#;
3222 let result = SessionTrace::from_jsonl(line);
3223 assert!(result.is_err());
3224 let message = result.unwrap_err().message;
3225 assert!(message.contains("unsupported schema_version"));
3226 assert!(message.contains("migration required"));
3227 }
3228
3229 #[cfg(feature = "tracing")]
3230 #[test]
3231 fn schema_incompatibility_emits_compat_span_and_error_log() {
3232 let capture = TraceCaptureLayer::default();
3233 let subscriber =
3234 tracing_subscriber::registry().with(capture.clone().with_filter(LevelFilter::TRACE));
3235 let _guard = tracing::subscriber::set_default(subscriber);
3236
3237 let line = r#"{"schema_version":"golden-trace-v3","event":"tick","ts_ns":0}"#;
3238 let err = SessionTrace::from_jsonl(line).expect_err("newer schema should fail");
3239 assert!(err.message.contains("migration required"));
3240
3241 let spans = capture.spans.lock().expect("span capture lock");
3242 assert!(
3243 spans.iter().any(|name| name == "trace.compat_check"),
3244 "expected trace.compat_check span, got {spans:?}"
3245 );
3246 drop(spans);
3247
3248 let events = capture.events.lock().expect("event capture lock");
3249 assert!(
3250 events
3251 .iter()
3252 .any(|event| event.contains("ERROR:trace schema version incompatible")),
3253 "expected incompatible schema ERROR log, got {events:?}"
3254 );
3255 }
3256
3257 #[test]
3258 fn from_jsonl_validated_surfaces_validation_error_type() {
3259 let jsonl = TraceRecord::Header {
3260 seed: 0,
3261 cols: 80,
3262 rows: 24,
3263 profile: "modern".to_string(),
3264 }
3265 .to_jsonl();
3266 let result = SessionTrace::from_jsonl_validated(&jsonl);
3267 assert!(matches!(
3268 result,
3269 Err(TraceLoadError::Validation(
3270 TraceValidationError::MissingSummary
3271 ))
3272 ));
3273 }
3274
3275 #[test]
3278 fn json_escape_round_trip() {
3279 let cases = [
3280 "hello",
3281 "with\"quotes",
3282 "back\\slash",
3283 "line\nbreak",
3284 "tab\there",
3285 ];
3286 for input in cases {
3287 let escaped = json_escape(input);
3288 let unescaped = json_unescape(&escaped).unwrap();
3289 assert_eq!(unescaped, input, "round-trip failed for: {input:?}");
3290 }
3291 }
3292
3293 #[test]
3294 fn extract_str_basic() {
3295 let json = r#"{"name":"alice","age":30}"#;
3296 assert_eq!(extract_str(json, "name"), Some("alice"));
3297 }
3298
3299 #[test]
3300 fn extract_u64_basic() {
3301 let json = r#"{"count":42,"name":"test"}"#;
3302 assert_eq!(extract_u64(json, "count"), Some(42));
3303 }
3304
3305 #[test]
3306 fn extract_i64_basic() {
3307 let json = r#"{"dx":-12,"dy":7}"#;
3308 assert_eq!(extract_i64(json, "dx"), Some(-12));
3309 assert_eq!(extract_i64(json, "dy"), Some(7));
3310 }
3311
3312 #[test]
3313 fn extract_bool_basic() {
3314 let json = r#"{"enabled":true,"disabled":false}"#;
3315 assert_eq!(extract_bool(json, "enabled"), Some(true));
3316 assert_eq!(extract_bool(json, "disabled"), Some(false));
3317 }
3318
3319 #[test]
3320 fn extract_hex_u64_basic() {
3321 let json = r#"{"hash":"00000000deadbeef"}"#;
3322 assert_eq!(extract_hex_u64(json, "hash"), Some(0xDEADBEEF));
3323 }
3324
3325 #[test]
3326 fn from_jsonl_parses_frankenterm_key_schema() {
3327 let down = parse_single_input_event(
3328 r#"{"kind":"key","phase":"down","code":"F12","mods":5,"repeat":false}"#,
3329 );
3330 assert_eq!(
3331 down,
3332 Event::Key(KeyEvent {
3333 code: KeyCode::F(12),
3334 modifiers: Modifiers::SHIFT | Modifiers::CTRL,
3335 kind: KeyEventKind::Press,
3336 })
3337 );
3338
3339 let repeat = parse_single_input_event(
3340 r#"{"kind":"key","phase":"down","code":"a","mods":0,"repeat":true}"#,
3341 );
3342 assert_eq!(
3343 repeat,
3344 Event::Key(KeyEvent {
3345 code: KeyCode::Char('a'),
3346 modifiers: Modifiers::empty(),
3347 kind: KeyEventKind::Repeat,
3348 })
3349 );
3350
3351 let release = parse_single_input_event(
3352 r#"{"kind":"key","phase":"up","code":"Enter","mods":0,"repeat":false}"#,
3353 );
3354 assert_eq!(
3355 release,
3356 Event::Key(KeyEvent {
3357 code: KeyCode::Enter,
3358 modifiers: Modifiers::empty(),
3359 kind: KeyEventKind::Release,
3360 })
3361 );
3362 }
3363
3364 #[test]
3365 fn key_event_json_round_trip_unescapes_code() {
3366 let quote_key = Event::Key(KeyEvent {
3367 code: KeyCode::Char('"'),
3368 modifiers: Modifiers::empty(),
3369 kind: KeyEventKind::Press,
3370 });
3371 let quote_json = event_to_json("e_key);
3372 let parsed_quote = parse_event_json("e_json).expect("quote key should parse");
3373 assert_eq!(parsed_quote, quote_key);
3374
3375 let slash_key = Event::Key(KeyEvent {
3376 code: KeyCode::Char('\\'),
3377 modifiers: Modifiers::SHIFT,
3378 kind: KeyEventKind::Press,
3379 });
3380 let slash_json = event_to_json(&slash_key);
3381 let parsed_slash = parse_event_json(&slash_json).expect("slash key should parse");
3382 assert_eq!(parsed_slash, slash_key);
3383 }
3384
3385 #[test]
3386 fn from_jsonl_parses_frankenterm_mouse_and_wheel_schema() {
3387 let mouse = parse_single_input_event(
3388 r#"{"kind":"mouse","phase":"drag","button":2,"x":7,"y":9,"mods":3}"#,
3389 );
3390 assert_eq!(
3391 mouse,
3392 Event::Mouse(MouseEvent {
3393 kind: MouseEventKind::Drag(MouseButton::Right),
3394 x: 7,
3395 y: 9,
3396 modifiers: Modifiers::SHIFT | Modifiers::ALT,
3397 })
3398 );
3399
3400 let wheel =
3401 parse_single_input_event(r#"{"kind":"wheel","x":4,"y":6,"dx":0,"dy":-2,"mods":4}"#);
3402 assert_eq!(
3403 wheel,
3404 Event::Mouse(MouseEvent {
3405 kind: MouseEventKind::ScrollUp,
3406 x: 4,
3407 y: 6,
3408 modifiers: Modifiers::CTRL,
3409 })
3410 );
3411 }
3412
3413 #[test]
3414 fn from_jsonl_parses_frankenterm_paste_focus_and_composition_aliases() {
3415 let paste = parse_single_input_event(r#"{"kind":"paste","data":"hello\nworld"}"#);
3416 assert_eq!(paste, Event::Paste(PasteEvent::new("hello\nworld", true)));
3417
3418 let focus = parse_single_input_event(r#"{"kind":"focus","focused":false}"#);
3419 assert_eq!(focus, Event::Focus(false));
3420
3421 let composition_update =
3422 parse_single_input_event(r#"{"kind":"composition","phase":"update","data":"你"}"#);
3423 assert_eq!(
3424 composition_update,
3425 Event::Ime(ImeEvent::new(ImePhase::Update, "你"))
3426 );
3427
3428 let composition_end =
3429 parse_single_input_event(r#"{"kind":"composition","phase":"end","data":"你好"}"#);
3430 assert_eq!(
3431 composition_end,
3432 Event::Ime(ImeEvent::new(ImePhase::Commit, "你好"))
3433 );
3434 }
3435
3436 #[test]
3439 fn gate_trace_passes_on_correct_replay() {
3440 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3441 rec.init().unwrap();
3442 rec.push_event(1_000_000, key_event('+'))
3443 .expect("key admission");
3444 rec.step().unwrap();
3445 let trace = rec.finish();
3446
3447 let report = gate_trace(new_counter(0), &trace).unwrap();
3448 assert!(report.passed);
3449 assert_eq!(report.total_frames, 2);
3450 assert!(report.diff.is_none());
3451 assert!(report.format().starts_with("PASS"));
3452 }
3453
3454 #[test]
3455 fn gate_trace_fails_with_actionable_diff() {
3456 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3457 rec.init().unwrap();
3458 rec.push_event(1_000_000, key_event('+'))
3459 .expect("key admission");
3460 rec.push_event(2_000_000, key_event('+'))
3461 .expect("key admission");
3462 rec.step().unwrap();
3463 let trace = rec.finish();
3464
3465 let report = gate_trace(new_counter(5), &trace).unwrap();
3467 assert!(!report.passed);
3468 assert!(report.diff.is_some());
3469
3470 let diff = report.diff.as_ref().unwrap();
3471 assert_eq!(diff.frame_idx, 0); let formatted = report.format();
3474 assert!(formatted.starts_with("FAIL"));
3475 assert!(formatted.contains("frame 0"));
3476 }
3477
3478 #[test]
3479 fn gate_trace_diff_has_event_context() {
3480 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3481 rec.init().unwrap();
3482 rec.push_event(1_000_000, key_event('+'))
3483 .expect("key admission");
3484 rec.push_event(2_000_000, key_event('+'))
3485 .expect("key admission");
3486 rec.step().unwrap();
3487 rec.push_event(3_000_000, key_event('-'))
3488 .expect("key admission");
3489 rec.step().unwrap();
3490 let trace = rec.finish();
3491
3492 let mut tampered = trace.clone();
3494 let mut chain = 0;
3495 for record in &mut tampered.records {
3496 match record {
3497 TraceRecord::Frame {
3498 frame_idx,
3499 checksum,
3500 checksum_chain,
3501 ..
3502 } => {
3503 if *frame_idx == 2 {
3504 *checksum = 0xBAD;
3505 }
3506 chain = fnv1a64_pair(chain, *checksum);
3507 *checksum_chain = chain;
3508 }
3509 TraceRecord::Summary {
3510 final_checksum_chain,
3511 ..
3512 } => *final_checksum_chain = chain,
3513 _ => {}
3514 }
3515 }
3516 tampered.validate().unwrap();
3519
3520 let report = gate_trace(new_counter(0), &tampered).unwrap();
3521 assert!(!report.passed);
3522 let diff = report.diff.unwrap();
3523 assert_eq!(diff.frame_idx, 2);
3524 assert!(diff.event_idx > 0); }
3526
3527 #[test]
3530 fn jsonl_serialize_parse_replay_round_trip() {
3531 let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3533 rec.init().unwrap();
3534
3535 for i in 0..3 {
3536 rec.push_event(i * 16_000_000, key_event('+'))
3537 .expect("key admission");
3538 rec.step().unwrap();
3539 }
3540 let original_trace = rec.finish();
3541
3542 let jsonl = original_trace.to_jsonl();
3544
3545 let parsed_trace = SessionTrace::from_jsonl(&jsonl).unwrap();
3547
3548 let result = replay(new_counter(0), &parsed_trace).unwrap();
3550 assert!(
3551 result.ok(),
3552 "JSONL round-trip replay failed: {:?}",
3553 result.first_mismatch
3554 );
3555 assert_eq!(result.total_frames, original_trace.frame_count());
3556 assert_eq!(
3557 result.final_checksum_chain,
3558 original_trace.final_checksum_chain().unwrap()
3559 );
3560 }
3561
3562 #[test]
3565 fn trace_parse_error_display() {
3566 let e = TraceParseError {
3567 line: 5,
3568 message: "bad field".to_string(),
3569 };
3570 assert_eq!(e.to_string(), "line 5: bad field");
3571 }
3572}