1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
|
//! HISTORY record payload encoding.
//!
//! One HISTORY record describes the complete history for a previously encoded
//! screen. It is followed immediately by the number of complete PAGE records
//! declared by `page_count`. Those pages contain the history older than the
//! first page in the corresponding SCREEN sequence and are ordered from newest
//! to oldest.
//!
//! Every encoded SCREEN has one corresponding HISTORY record. A screen with no
//! older pages uses a zero page count and has no following PAGE records.
//!
//! The first SCREEN page may begin above the active area. Those incidental
//! history rows are already present at READY and are not repeated after
//! HISTORY. The corresponding SCREEN header declares the complete logical
//! history extent, including both that resident overlap and the following PAGE
//! records.
//!
//! All integers are unsigned and little-endian.
//!
//! ## Binary Format
//!
//! A HISTORY record is followed immediately by its declared PAGE records:
//!
//! ```text
//! +----------------------+
//! | HISTORY record |
//! +----------------------+
//! | PAGE record 0 | newest
//! +----------------------+
//! | ... |
//! +----------------------+
//! | PAGE record (n - 1) | oldest
//! +----------------------+
//!
//! n = page_count
//! ```
//!
//! Newest-to-oldest order lets a reader start showing most-recent
//! history as soon as possible which is more useful to a user.
//!
//! The PAGE sequence may be empty when all history is already included in the
//! first SCREEN page or when the screen has no history.
//!
//! ### Header
//!
//! The HISTORY payload consists only of this fixed header:
//!
//! ```text
//! 0 +--------------------------------+
//! | Screen key (u16) |
//! 2 +--------------------------------+
//! | Following page count (u32) |
//! 6 +--------------------------------+
//! ```
//!
//! A decoder uses `page_count`, rather than another record tag, to find the end
//! of the page sequence.
const std = @import("std");
const Allocator = std.mem.Allocator;
const test_fixture = @import("fixture.zig");
const io = @import("io.zig");
const page = @import("page.zig");
const record = @import("record.zig");
const screen = @import("screen.zig");
const TerminalPage = @import("../page.zig").Page;
const TerminalPageList = @import("../PageList.zig");
const TerminalScreen = @import("../Screen.zig");
const TerminalScreenKey = @import("../ScreenSet.zig").Key;
/// The complete fixed payload of one HISTORY record.
pub const Header = struct {
/// Number of encoded bytes in the fixed payload, calculated by its encoder.
pub const len = computeLen();
comptime {
// This size is part of the wire format. If it changes, the snapshot
// version must also change.
std.debug.assert(len == 6);
}
/// Identifies the previously encoded screen that owns this history.
key: TerminalScreenKey,
/// Number of complete PAGE records immediately following this record.
page_count: u32,
/// Encode the fixed HISTORY payload.
pub fn encode(
self: Header,
writer: *std.Io.Writer,
) std.Io.Writer.Error!void {
try io.writeInt(writer, u16, @intCast(@intFromEnum(self.key)));
try io.writeInt(writer, u32, self.page_count);
}
pub const DecodeError = std.Io.Reader.Error || error{InvalidKey};
/// Decode and validate the fixed HISTORY payload.
pub fn decode(reader: *std.Io.Reader) Header.DecodeError!Header {
const raw = try io.readInt(reader, u16);
const Tag = @typeInfo(TerminalScreenKey).@"enum".tag_type;
const value = std.math.cast(Tag, raw) orelse
return error.InvalidKey;
const key = std.enums.fromInt(
TerminalScreenKey,
value,
) orelse return error.InvalidKey;
return .{
.key = key,
.page_count = try io.readInt(reader, u32),
};
}
fn computeLen() usize {
comptime {
var buf: [128]u8 = undefined;
var writer: std.Io.Writer = .fixed(&buf);
const value: Header = .{
.key = .primary,
.page_count = 0,
};
value.encode(&writer) catch unreachable;
return writer.end;
}
}
};
/// Errors possible while encoding one HISTORY and its complete PAGE sequence.
pub const EncodeError = Allocator.Error ||
page.EncodeError ||
record.Writer.FinishError ||
error{
/// The complete historical prefix has more pages than the header fits.
PageCountOverflow,
};
/// Encode one screen's HISTORY and its complete historical pages.
///
/// Pages are encoded newest-to-oldest. Compressed source pages are inspected
/// without changing their storage state. Completed records may already be
/// emitted if a later page fails.
pub fn encode(
terminal_screen: *const TerminalScreen,
key: TerminalScreenKey,
destination: *record.Writer,
) EncodeError!void {
// SCREEN begins at the page containing the active area's first row. Its
// leading rows are already resident; every previous complete page belongs
// to this HISTORY sequence.
const first = terminal_screen.pages.getTopLeft(.active).node.prev;
const page_count: usize = count: {
var page_count: usize = 0;
var node = first;
while (node) |current| : (node = current.prev) {
page_count += 1;
}
break :count page_count;
};
const header: Header = .{
.key = key,
.page_count = std.math.cast(
u32,
page_count,
) orelse return error.PageCountOverflow,
};
// HISTORY declares exactly how many PAGE records follow.
{
const payload = destination.begin(.history);
errdefer destination.cancel();
try header.encode(payload);
try destination.finish();
}
// Walk backward so each page can be prepended by the decoder immediately.
// PreservedPage borrows resident pages and clones compressed pages without
// changing the source node's representation.
var node = first;
while (node) |current| : (node = current.prev) {
var preserved = try current.pagePreservingState(terminal_screen.alloc);
defer preserved.deinit();
try page.encode(preserved.page(), destination);
}
}
/// Errors possible while restoring one HISTORY and its PAGE sequence.
pub const DecodeError = Decoder.InitError ||
Decoder.RestoreError ||
error{
/// The HISTORY key does not match the caller-selected screen.
UnexpectedScreenKey,
};
/// Errors possible while restoring one history PAGE into a native Screen.
pub const DecodePageError = Allocator.Error ||
page.DecodeError ||
TerminalPageList.PageAllocation.FinalizeError;
/// Restore the next history PAGE record and prepend it to the native Screen.
///
/// Returns the number of rows added above the screen's existing content.
/// The page is decoded directly into a detached PageList-pooled allocation
/// and prepended only after its record validates, so a failure leaves the
/// screen unchanged. A limit failure from `finalize` occurs after the record
/// bytes were fully consumed, leaving `source` aligned on the next record.
pub fn decodePage(
source: *std.Io.Reader,
alloc: Allocator,
terminal_screen: *TerminalScreen,
) DecodePageError!usize {
// PAGE exposes its exact capacity before decoding the payload, allowing
// the destination PageList to allocate the final backing memory once.
var decoder: page.Decoder = undefined;
try decoder.init(source);
var allocation = try terminal_screen.pages.allocatePage(
decoder.capacity(),
);
defer allocation.deinit();
try decoder.decode(allocation.page(), alloc);
const rows = allocation.page().size.rows;
const contains_prompt = hasSemanticPrompt(allocation.page());
try allocation.finalize(.prepend);
if (contains_prompt) terminal_screen.semantic_prompt.seen = true;
return rows;
}
/// A decoded HISTORY manifest ready to restore its following PAGE records.
///
/// Keeping manifest decoding separate lets the full snapshot wrapper route a
/// HISTORY sequence by its encoded key before any pages mutate a Screen.
pub const Decoder = struct {
source: *std.Io.Reader,
header: Header,
pub const InitError = Header.DecodeError ||
record.Reader.InitError ||
record.Reader.FinishError ||
error{
/// The next record is valid but is not a HISTORY.
UnexpectedRecordTag,
};
pub const RestoreError = DecodePageError || error{
/// The Screen already contains complete pages before its active page.
ExistingHistory,
};
/// Decode and finish the self-contained HISTORY manifest.
pub fn init(self: *Decoder, source: *std.Io.Reader) InitError!void {
var record_reader: record.Reader = undefined;
try record_reader.init(source);
if (record_reader.header.tag != .history) {
return error.UnexpectedRecordTag;
}
const header = try Header.decode(record_reader.payloadReader());
try record_reader.finish();
self.* = .{ .source = source, .header = header };
}
/// Restore the declared PAGE records into the selected native Screen.
pub fn decode(
self: *Decoder,
alloc: Allocator,
terminal_screen: *TerminalScreen,
) RestoreError!void {
// A freshly restored SCREEN may carry overlap inside its first page,
// but cannot already contain a complete historical page before that
// boundary.
const active_top = terminal_screen.pages.getTopLeft(.active);
if (terminal_screen.pages.getTopLeft(.screen).node != active_top.node) {
return error.ExistingHistory;
}
// Native row totals remain derived from the actual PAGE dimensions.
for (0..self.header.page_count) |_| {
_ = try decodePage(self.source, alloc, terminal_screen);
}
terminal_screen.pages.assertIntegrity();
terminal_screen.assertIntegrity();
}
};
/// Restore one HISTORY and its declared PAGE records into a native Screen.
///
/// Each PAGE is decoded directly into a detached PageList-pooled allocation and
/// prepended only after its record and native integrity are validated. If a
/// later PAGE fails, earlier successful pages remain as a contiguous recent
/// history prefix.
pub fn decode(
source: *std.Io.Reader,
alloc: Allocator,
expected_key: TerminalScreenKey,
terminal_screen: *TerminalScreen,
) DecodeError!void {
var decoder: Decoder = undefined;
try decoder.init(source);
if (decoder.header.key != expected_key) return error.UnexpectedScreenKey;
try decoder.decode(alloc, terminal_screen);
}
fn hasSemanticPrompt(terminal_page: *const TerminalPage) bool {
const rows = terminal_page.rows.ptr(terminal_page.memory)[0..terminal_page.size.rows];
for (rows) |row| {
if (row.semantic_prompt != .none) return true;
const cells = row.cells.ptr(
terminal_page.memory,
)[0..terminal_page.size.cols];
for (cells) |cell| {
if (cell.semantic_content == .prompt) return true;
}
}
return false;
}
const test_header_fixture = test_fixture.parse(@embedFile("testdata/history-header-v1.hex"));
test "HISTORY header golden encoding and decoding" {
const expected: Header = .{
.key = .alternate,
.page_count = 0x01020304,
};
var encoded: [Header.len]u8 = undefined;
var writer: std.Io.Writer = .fixed(&encoded);
try expected.encode(&writer);
try test_fixture.expectEqual(
.bytes,
"src/terminal/snapshot/testdata/history-header-v1.hex",
"snapshot_fixture-history-header-v1.hex",
&test_header_fixture,
writer.buffered(),
);
try std.testing.expectEqual(Header.len, test_header_fixture.len);
var reader: std.Io.Reader = .fixed(&test_header_fixture);
try std.testing.expectEqualDeep(expected, try Header.decode(&reader));
for (0..Header.len) |fixture_len| {
var truncated: std.Io.Reader = .fixed(
test_header_fixture[0..fixture_len],
);
try std.testing.expectError(
error.EndOfStream,
Header.decode(&truncated),
);
}
var invalid_key = test_header_fixture;
invalid_key[0] = 2;
var invalid_key_reader: std.Io.Reader = .fixed(&invalid_key);
try std.testing.expectError(
error.InvalidKey,
Header.decode(&invalid_key_reader),
);
}
test "HISTORY encodes newest first and restores complete history" {
// Choose an active height which spans two native pages, then grow until
// exactly two additional complete pages precede the active boundary.
var probe = try TerminalScreen.init(
std.testing.io,
std.testing.allocator,
.{ .cols = 80, .rows = 1, .max_scrollback_bytes = 0 },
);
const page_rows = probe.pages.getTopLeft(.screen).node.capacity().rows;
probe.deinit();
const screen_rows = page_rows + 1;
var source_screen = try TerminalScreen.init(
std.testing.io,
std.testing.allocator,
.{
.cols = 80,
.rows = screen_rows,
.max_scrollback_bytes = null,
},
);
defer source_screen.deinit();
source_screen.cursorAbsolute(0, screen_rows - 1);
while (source_screen.pages.totalPages() < 4) {
try source_screen.testWriteString("\n");
}
const active_top = source_screen.pages.getTopLeft(.active);
const newest_history = active_top.node.prev.?;
const oldest_history = newest_history.prev.?;
try std.testing.expectEqual(
source_screen.pages.getTopLeft(.screen).node,
oldest_history,
);
try std.testing.expectEqual(null, oldest_history.prev);
// Mark the two complete historical pages so the wire sequence and final
// native order are visible. The oldest prompt also verifies derived state
// is updated only when that page is restored.
oldest_history.page().getRowAndCell(0, 0).cell.* = .init('A');
oldest_history.page().getRowAndCell(
0,
0,
).cell.semantic_content = .prompt;
newest_history.page().getRowAndCell(0, 0).cell.* = .init('B');
// Encode SCREEN before history compression, then compress eligible history
// and require HISTORY encoding to preserve each source storage state.
var destination: std.Io.Writer.Allocating = .init(
std.testing.allocator,
);
defer destination.deinit();
var stream: record.Writer = .init(
std.testing.allocator,
&destination.writer,
);
defer stream.deinit();
try screen.encode(&source_screen, .primary, &stream);
const history_offset = destination.written().len;
_ = source_screen.pages.compress(.full);
const oldest_storage = oldest_history.storage();
const newest_storage = newest_history.storage();
try encode(&source_screen, .primary, &stream);
try std.testing.expectEqual(oldest_storage, oldest_history.storage());
try std.testing.expectEqual(newest_storage, newest_history.storage());
// Inspect the manifest and PAGE records independently. Newest history is
// sent first even though native PageList order is oldest-to-newest.
var history_source: std.Io.Reader = .fixed(
destination.written()[history_offset..],
);
var history_record: record.Reader = undefined;
try history_record.init(&history_source);
try std.testing.expectEqual(record.Tag.history, history_record.header.tag);
const header = try Header.decode(history_record.payloadReader());
try history_record.finish();
try std.testing.expectEqual(TerminalScreenKey.primary, header.key);
try std.testing.expectEqual(@as(u32, 2), header.page_count);
var decoded_newest = try page.decode(
&history_source,
std.testing.allocator,
);
defer decoded_newest.deinit();
try std.testing.expectEqual(
@as(u21, 'B'),
decoded_newest.getRowAndCell(0, 0).cell.codepoint(),
);
var decoded_oldest = try page.decode(
&history_source,
std.testing.allocator,
);
defer decoded_oldest.deinit();
try std.testing.expectEqual(
@as(u21, 'A'),
decoded_oldest.getRowAndCell(0, 0).cell.codepoint(),
);
try std.testing.expectError(error.EndOfStream, history_source.takeByte());
// Restore SCREEN first, then prepend HISTORY directly into that PageList.
var restore_source: std.Io.Reader = .fixed(destination.written());
var decoded_screen = try screen.decode(
&restore_source,
std.testing.io,
std.testing.allocator,
.{
.cols = 80,
.rows = screen_rows,
.max_scrollback_bytes = null,
},
);
defer decoded_screen.deinit();
try std.testing.expectEqual(
TerminalScreenKey.primary,
decoded_screen.key,
);
try std.testing.expectEqual(
@as(u64, @intCast(source_screen.pages.total_rows - screen_rows)),
decoded_screen.history_rows,
);
const restored = &decoded_screen.screen;
try std.testing.expect(!restored.semantic_prompt.seen);
try decode(
&restore_source,
std.testing.allocator,
.primary,
restored,
);
try std.testing.expectEqual(
source_screen.pages.totalPages(),
restored.pages.totalPages(),
);
const restored_oldest = restored.pages.getTopLeft(.screen).node;
try std.testing.expectEqual(
@as(u21, 'A'),
restored_oldest.page().getRowAndCell(0, 0).cell.codepoint(),
);
try std.testing.expectEqual(
@as(u21, 'B'),
restored_oldest.next.?
.page().getRowAndCell(0, 0).cell.codepoint(),
);
try std.testing.expect(restored.semantic_prompt.seen);
try std.testing.expectError(error.EndOfStream, restore_source.takeByte());
// Reuse a writable copy of the sequence for failure-path fixtures.
const encoded = try std.testing.allocator.dupe(
u8,
destination.written(),
);
defer std.testing.allocator.free(encoded);
const first_page_offset = history_offset + record.Header.len + Header.len;
const first_payload_len = std.mem.readInt(
u32,
encoded[first_page_offset + 2 ..][0..4],
.little,
);
const second_page_offset =
first_page_offset + record.Header.len + first_payload_len;
// Truncate the first PAGE only after its header has exposed a capacity.
// Its detached allocation is discarded and the live SCREEN list remains
// completely unchanged.
var truncated_source: std.Io.Reader = .fixed(
encoded[0 .. second_page_offset - 1],
);
var decoded_truncated = try screen.decode(
&truncated_source,
std.testing.io,
std.testing.allocator,
.{
.cols = 80,
.rows = screen_rows,
.max_scrollback_bytes = null,
},
);
defer decoded_truncated.deinit();
const truncated = &decoded_truncated.screen;
const truncated_screen_first = truncated.pages.getTopLeft(.screen).node;
const truncated_screen_page_count = truncated.pages.totalPages();
try std.testing.expectError(
error.EndOfStream,
decode(
&truncated_source,
std.testing.allocator,
.primary,
truncated,
),
);
try std.testing.expectEqual(
truncated_screen_page_count,
truncated.pages.totalPages(),
);
try std.testing.expectEqual(
truncated_screen_first,
truncated.pages.getTopLeft(.screen).node,
);
truncated.pages.assertIntegrity();
truncated.assertIntegrity();
// Corrupt only the older PAGE tag. A failure in a later PAGE keeps only
// the successfully prepended newer pages, contiguous with SCREEN.
std.mem.writeInt(
u16,
encoded[second_page_offset..][0..2],
@intFromEnum(record.Tag.screen),
.little,
);
var partial_source: std.Io.Reader = .fixed(encoded);
var decoded_partial = try screen.decode(
&partial_source,
std.testing.io,
std.testing.allocator,
.{
.cols = 80,
.rows = screen_rows,
.max_scrollback_bytes = null,
},
);
defer decoded_partial.deinit();
const partial = &decoded_partial.screen;
const screen_page_count = partial.pages.totalPages();
try std.testing.expectError(
error.UnexpectedRecordTag,
decode(
&partial_source,
std.testing.allocator,
.primary,
partial,
),
);
try std.testing.expectEqual(
screen_page_count + 1,
partial.pages.totalPages(),
);
try std.testing.expectEqual(
@as(u21, 'B'),
partial.pages.getTopLeft(.screen).node
.page().getRowAndCell(0, 0).cell.codepoint(),
);
try std.testing.expect(!partial.semantic_prompt.seen);
partial.pages.assertIntegrity();
partial.assertIntegrity();
}
test "HISTORY encodes and restores an empty sequence" {
var terminal_screen = try TerminalScreen.init(
std.testing.io,
std.testing.allocator,
.{
.cols = 2,
.rows = 2,
.max_scrollback_bytes = null,
},
);
defer terminal_screen.deinit();
var destination: std.Io.Writer.Allocating = .init(
std.testing.allocator,
);
defer destination.deinit();
var stream: record.Writer = .init(
std.testing.allocator,
&destination.writer,
);
defer stream.deinit();
try encode(&terminal_screen, .primary, &stream);
var inspect_source: std.Io.Reader = .fixed(destination.written());
var history_record: record.Reader = undefined;
try history_record.init(&inspect_source);
const header = try Header.decode(history_record.payloadReader());
try history_record.finish();
try std.testing.expectEqual(@as(u32, 0), header.page_count);
try std.testing.expectError(error.EndOfStream, inspect_source.takeByte());
var decode_source: std.Io.Reader = .fixed(destination.written());
const initial_first = terminal_screen.pages.getTopLeft(.screen).node;
try decode(
&decode_source,
std.testing.allocator,
.primary,
&terminal_screen,
);
try std.testing.expectEqual(
initial_first,
terminal_screen.pages.getTopLeft(.screen).node,
);
try std.testing.expectError(error.EndOfStream, decode_source.takeByte());
}
test "HISTORY rejects invalid routing and incomplete sequences" {
var terminal_screen = try TerminalScreen.init(
std.testing.io,
std.testing.allocator,
.{
.cols = 2,
.rows = 2,
.max_scrollback_bytes = null,
},
);
defer terminal_screen.deinit();
// Routing and sequence length still determine which native screen is
// mutated and where the following record begins, so they remain strict.
const Case = struct {
header: Header,
expected: anyerror,
};
const cases = [_]Case{
.{
.header = .{
.key = .alternate,
.page_count = 0,
},
.expected = error.UnexpectedScreenKey,
},
.{
.header = .{
.key = .primary,
.page_count = 1,
},
.expected = error.EndOfStream,
},
};
for (cases) |case| {
var destination: std.Io.Writer.Allocating = .init(
std.testing.allocator,
);
defer destination.deinit();
var stream: record.Writer = .init(
std.testing.allocator,
&destination.writer,
);
defer stream.deinit();
const payload = stream.begin(.history);
errdefer stream.cancel();
try case.header.encode(payload);
try stream.finish();
var source: std.Io.Reader = .fixed(destination.written());
try std.testing.expectError(
case.expected,
decode(
&source,
std.testing.allocator,
.primary,
&terminal_screen,
),
);
terminal_screen.pages.assertIntegrity();
terminal_screen.assertIntegrity();
}
}
|