aboutsummaryrefslogtreecommitdiff
path: root/vendor/libghostty-vt/src/terminal/snapshot
diff options
context:
space:
mode:
authorCan Celik <ogulcancelik@gmail.com>2026-09-10 21:51:57 +0300
committerGitHub <noreply@github.com>2026-09-10 21:51:57 +0300
commit425c86179791cd32e2d4ce0ae7f269940b4b0663 (patch)
treee52c4383a6d69216cbe2a32638bf90841d7e2189 /vendor/libghostty-vt/src/terminal/snapshot
parent90e947a6e26e02f10ec7f1694c4eb5b78a86406b (diff)
chore: upgrade libghostty and preserve terminal behavior (#3906)
Diffstat (limited to 'vendor/libghostty-vt/src/terminal/snapshot')
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/AGENTS.md7
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/checkpoint.zig177
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/continuation.zig320
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/envelope.zig104
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/fixture.zig479
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/grid.zig2403
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/history.zig716
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/hyperlink.zig493
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/io.zig55
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/main.zig182
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/page.zig1828
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/record.zig601
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/screen.zig2460
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/snapshot.ksy1073
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/snapshot.zig2100
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/style.zig423
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/terminal.zig1850
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/checkpoint-ready-v1.hex10
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/complete-v1.hex120
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-apc-v1.hex8
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-csi-v1.hex8
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-dcs-v1.hex8
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-esc-v1.hex8
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-ground-v1.hex8
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-osc-v1.hex8
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-utf8-v1.hex8
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/envelope-v1.hex10
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/grid-v1.hex15
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/history-header-v1.hex10
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/hyperlink-explicit-v1.hex10
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/hyperlink-implicit-v1.hex10
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/page-empty-record-v1.hex12
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/page-header-v1.hex11
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/page-v1.hex22
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/record-page-header-v1.hex10
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/screen-header-v1.hex13
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/screen-saved-cursor-v1.hex11
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/style-v1.hex10
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/testdata/terminal-header-v1.hex16
-rwxr-xr-xvendor/libghostty-vt/src/terminal/snapshot/verify-kaitai.py400
40 files changed, 16017 insertions, 0 deletions
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/AGENTS.md b/vendor/libghostty-vt/src/terminal/snapshot/AGENTS.md
new file mode 100644
index 00000000..0ce37b5e
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/AGENTS.md
@@ -0,0 +1,7 @@
+# Terminal Binary Snapshot
+
+- Apply the robustness principle: "be conservative in what you do, be liberal
+ in what you accept from others."
+ - Validate on encode
+ - Gracefully degrade on decode, for example invalid styles degrade to
+ ignoring the style.
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/checkpoint.zig b/vendor/libghostty-vt/src/terminal/snapshot/checkpoint.zig
new file mode 100644
index 00000000..23ea755f
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/checkpoint.zig
@@ -0,0 +1,177 @@
+//! READY and FINISH snapshot marker records.
+//!
+//! READY separates the renderable terminal state from the history sequences.
+//! FINISH terminates one snapshot; bytes after it belong to the containing
+//! transport. Both markers have empty payloads, independently framed and
+//! protected by the same CRC32C as every other record.
+//!
+//! ## Binary Format
+//!
+//! READY and FINISH contain only their record headers. Their declared payload
+//! length must be zero.
+
+const std = @import("std");
+const test_fixture = @import("fixture.zig");
+const record = @import("record.zig");
+
+/// Selects one of the two marker positions in a snapshot.
+pub const Kind = enum {
+ ready,
+ finish,
+
+ fn tag(self: Kind) record.Tag {
+ return switch (self) {
+ .ready => .ready,
+ .finish => .finish,
+ };
+ }
+};
+
+pub const EncodeError = record.Writer.FinishError;
+
+/// Append one empty marker record.
+pub fn encode(kind: Kind, stream: *record.Writer) EncodeError!void {
+ _ = stream.begin(kind.tag());
+ errdefer stream.cancel();
+ try stream.finish();
+}
+
+pub const DecodeError = record.Reader.InitError ||
+ record.Reader.FinishError ||
+ error{
+ /// The next record is valid but is not the expected marker.
+ UnexpectedRecordTag,
+ };
+
+/// Decode one marker and require its payload to be empty.
+pub fn decode(
+ kind: Kind,
+ source: *std.Io.Reader,
+) DecodeError!void {
+ var record_reader: record.Reader = undefined;
+ try record_reader.init(source);
+ if (record_reader.header.tag != kind.tag()) {
+ return error.UnexpectedRecordTag;
+ }
+ try record_reader.finish();
+}
+
+const test_ready_fixture = test_fixture.parse(
+ @embedFile("testdata/checkpoint-ready-v1.hex"),
+);
+
+test "READY golden encoding" {
+ const prefix = "abc";
+
+ var snapshot: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer snapshot.deinit();
+ var stream: record.Writer = .init(
+ std.testing.allocator,
+ &snapshot.writer,
+ );
+ defer stream.deinit();
+ try stream.writer().writeAll(prefix);
+ try encode(.ready, &stream);
+
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/checkpoint-ready-v1.hex",
+ "snapshot_fixture-checkpoint-ready-v1.hex",
+ &test_ready_fixture,
+ snapshot.written(),
+ );
+
+ // Decode the checked-in record rather than the generated candidate.
+ var source: std.Io.Reader = .fixed(&test_ready_fixture);
+ try source.discardAll(prefix.len);
+ try decode(.ready, &source);
+}
+
+test "READY and FINISH are empty marker records" {
+ const testing = std.testing;
+
+ var snapshot: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer snapshot.deinit();
+ var stream: record.Writer = .init(
+ testing.allocator,
+ &snapshot.writer,
+ );
+ defer stream.deinit();
+ try stream.writer().writeAll("prefix");
+
+ const ready_offset = snapshot.written().len;
+ try encode(.ready, &stream);
+ try stream.writer().writeAll("history");
+ const finish_offset = snapshot.written().len;
+ try encode(.finish, &stream);
+
+ try testing.expectEqual(
+ record.Header.len,
+ finish_offset - ready_offset - "history".len,
+ );
+ try testing.expectEqual(
+ record.Header.len,
+ snapshot.written().len - finish_offset,
+ );
+
+ var source: std.Io.Reader = .fixed(snapshot.written());
+ try source.discardAll(ready_offset);
+ try decode(.ready, &source);
+ try source.discardAll("history".len);
+ try decode(.finish, &source);
+}
+
+test "checkpoint rejects wrong tags and nonempty payloads" {
+ const testing = std.testing;
+
+ var snapshot: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer snapshot.deinit();
+ var stream: record.Writer = .init(
+ testing.allocator,
+ &snapshot.writer,
+ );
+ defer stream.deinit();
+ try encode(.ready, &stream);
+
+ var wrong_tag_source: std.Io.Reader = .fixed(snapshot.written());
+ try testing.expectError(
+ error.UnexpectedRecordTag,
+ decode(.finish, &wrong_tag_source),
+ );
+
+ var invalid: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer invalid.deinit();
+ var invalid_stream: record.Writer = .init(
+ testing.allocator,
+ &invalid.writer,
+ );
+ defer invalid_stream.deinit();
+ const invalid_payload = invalid_stream.begin(.ready);
+ errdefer invalid_stream.cancel();
+ try invalid_payload.writeByte(0);
+ try invalid_stream.finish();
+
+ var invalid_source: std.Io.Reader = .fixed(invalid.written());
+ try testing.expectError(
+ error.PayloadNotExhausted,
+ decode(.ready, &invalid_source),
+ );
+}
+
+test "FINISH leaves continuation bytes unread" {
+ const testing = std.testing;
+
+ var finished: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer finished.deinit();
+ var finished_stream: record.Writer = .init(
+ testing.allocator,
+ &finished.writer,
+ );
+ defer finished_stream.deinit();
+ try encode(.finish, &finished_stream);
+ try finished.writer.writeByte(0);
+
+ var source: std.Io.Reader = .fixed(finished.written());
+ try decode(.finish, &source);
+ try testing.expectEqual(@as(u8, 0), try source.takeByte());
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/continuation.zig b/vendor/libghostty-vt/src/terminal/snapshot/continuation.zig
new file mode 100644
index 00000000..92b52da0
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/continuation.zig
@@ -0,0 +1,320 @@
+//! Continuation record type.
+//!
+//! Continuation uses the standard record header. All trailing bytes
+//! are payload bytes for the continuation state.
+//!
+//! A continuation's payload must be the minimal bytes to go from
+//! a ground state to a non-ground state in a VT emulator. Any extra
+//! bytes are treated as a validation error.
+
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const record = @import("record.zig");
+const stream_continuation = @import("../stream_continuation.zig");
+const test_fixture = @import("fixture.zig");
+
+/// A borrowed continuation value supplied to encode, or an allocator-owned
+/// value stored in a decoded complete snapshot.
+pub const Value = union(enum) {
+ /// Neither the VT parser nor UTF-8 decoder has unfinished state.
+ ground,
+
+ /// Canonical replay-safe PTY bytes. Empty is equivalent to `ground`.
+ bytes: []const u8,
+};
+
+pub const ValidateError = stream_continuation.ValidateError || error{
+ /// The common record's u32 payload length cannot represent these bytes.
+ Overflow,
+};
+
+/// Validate a continuation before any snapshot bytes are emitted.
+pub fn validate(value: Value) ValidateError!void {
+ switch (value) {
+ .ground => {},
+ .bytes => |bytes| {
+ if (std.math.cast(u32, bytes.len) == null) {
+ return error.Overflow;
+ }
+ try stream_continuation.validate(bytes);
+ },
+ }
+}
+
+pub const EncodeError = ValidateError || record.Writer.FinishError;
+
+/// Encode one complete CONTINUATION record.
+pub fn encode(
+ value: Value,
+ stream: *record.Writer,
+) EncodeError!void {
+ try validate(value);
+
+ const payload = stream.begin(.continuation);
+ errdefer stream.cancel();
+ switch (value) {
+ .ground => {},
+ .bytes => |bytes| try payload.writeAll(bytes),
+ }
+ try stream.finish();
+}
+
+pub const DecodeError = Allocator.Error ||
+ stream_continuation.ValidateError ||
+ record.Reader.InitError ||
+ record.Reader.FinishError ||
+ std.Io.Reader.Error ||
+ error{
+ /// The next record is valid but is not CONTINUATION.
+ UnexpectedRecordTag,
+
+ /// The declared payload exceeds caller policy.
+ ContinuationLimitExceeded,
+ };
+
+/// Decode and validate one CONTINUATION record.
+///
+/// A zero-length payload returns `ground` without allocating. A nonempty
+/// payload returns allocator-owned bytes; although `Value.bytes` is a const
+/// slice, the caller must eventually free it with the same allocator.
+pub fn decode(
+ alloc: Allocator,
+ source: *std.Io.Reader,
+ max_bytes: usize,
+) DecodeError!Value {
+ var record_reader: record.Reader = undefined;
+ try record_reader.init(source);
+ if (record_reader.header.tag != .continuation) {
+ return error.UnexpectedRecordTag;
+ }
+
+ // Validate the header payload vs our max size since the header
+ // enforces it.
+ const len: usize = record_reader.header.payload_len;
+ if (len > max_bytes) return error.ContinuationLimitExceeded;
+
+ if (len == 0) {
+ // Empty is the ground representation, but finish is still required:
+ // its CRC covers the tag and zero length even though there is no body.
+ try record_reader.finish();
+ return .ground;
+ }
+
+ // Consume the bytes
+ const bytes = try alloc.alloc(u8, len);
+ errdefer alloc.free(bytes);
+ try record_reader.payloadReader().readSliceAll(bytes);
+ try record_reader.finish();
+
+ // Framing is valid, so it is now safe to classify the bytes as replay
+ // state. Validation requires a minimal, unfinished, side-effect-free tail.
+ try stream_continuation.validate(bytes);
+
+ // Ownership transfers to the returned Value only after all validation.
+ return .{ .bytes = bytes };
+}
+
+const test_ground_fixture = test_fixture.parse(@embedFile("testdata/continuation-ground-v1.hex"));
+const test_utf8_fixture = test_fixture.parse(@embedFile("testdata/continuation-utf8-v1.hex"));
+const test_esc_fixture = test_fixture.parse(@embedFile("testdata/continuation-esc-v1.hex"));
+const test_csi_fixture = test_fixture.parse(@embedFile("testdata/continuation-csi-v1.hex"));
+const test_osc_fixture = test_fixture.parse(@embedFile("testdata/continuation-osc-v1.hex"));
+const test_dcs_fixture = test_fixture.parse(@embedFile("testdata/continuation-dcs-v1.hex"));
+const test_apc_fixture = test_fixture.parse(@embedFile("testdata/continuation-apc-v1.hex"));
+
+test "continuation golden records" {
+ const Golden = struct {
+ path: []const u8,
+ candidate: []const u8,
+ value: Value,
+ expected: []const u8,
+ };
+ const values = [_]Golden{
+ .{
+ .path = "src/terminal/snapshot/testdata/continuation-ground-v1.hex",
+ .candidate = "snapshot_fixture-continuation-ground-v1.hex",
+ .value = .ground,
+ .expected = &test_ground_fixture,
+ },
+ .{
+ .path = "src/terminal/snapshot/testdata/continuation-utf8-v1.hex",
+ .candidate = "snapshot_fixture-continuation-utf8-v1.hex",
+ .value = .{ .bytes = "\xF0\x9F\x98" },
+ .expected = &test_utf8_fixture,
+ },
+ .{
+ .path = "src/terminal/snapshot/testdata/continuation-esc-v1.hex",
+ .candidate = "snapshot_fixture-continuation-esc-v1.hex",
+ .value = .{ .bytes = "\x1b" },
+ .expected = &test_esc_fixture,
+ },
+ .{
+ .path = "src/terminal/snapshot/testdata/continuation-csi-v1.hex",
+ .candidate = "snapshot_fixture-continuation-csi-v1.hex",
+ .value = .{ .bytes = "\x1b[31" },
+ .expected = &test_csi_fixture,
+ },
+ .{
+ .path = "src/terminal/snapshot/testdata/continuation-osc-v1.hex",
+ .candidate = "snapshot_fixture-continuation-osc-v1.hex",
+ .value = .{ .bytes = "\x1b]2;title" },
+ .expected = &test_osc_fixture,
+ },
+ .{
+ .path = "src/terminal/snapshot/testdata/continuation-dcs-v1.hex",
+ .candidate = "snapshot_fixture-continuation-dcs-v1.hex",
+ .value = .{ .bytes = "\x1bPqdata" },
+ .expected = &test_dcs_fixture,
+ },
+ .{
+ .path = "src/terminal/snapshot/testdata/continuation-apc-v1.hex",
+ .candidate = "snapshot_fixture-continuation-apc-v1.hex",
+ .value = .{ .bytes = "\x1b_Gdata" },
+ .expected = &test_apc_fixture,
+ },
+ };
+
+ for (values) |golden| {
+ var encoded: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer encoded.deinit();
+ var stream: record.Writer = .init(
+ std.testing.allocator,
+ &encoded.writer,
+ );
+ defer stream.deinit();
+ try encode(golden.value, &stream);
+ try test_fixture.expectEqual(
+ .bytes,
+ golden.path,
+ golden.candidate,
+ golden.expected,
+ encoded.written(),
+ );
+ }
+}
+
+test "continuation validates supported unfinished states" {
+ const values = [_][]const u8{
+ "\x1b",
+ "\x1b[31",
+ "\x1b]2;title",
+ "\x1bPqdata",
+ "\x1b_Gdata",
+ "\xF0\x9F\x98",
+ };
+ for (values) |bytes| try validate(.{ .bytes = bytes });
+}
+
+test "empty continuation bytes encode and decode as ground" {
+ const testing = std.testing;
+ try validate(.{ .bytes = "" });
+
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ var stream: record.Writer = .init(testing.allocator, &encoded.writer);
+ defer stream.deinit();
+ try encode(.{ .bytes = "" }, &stream);
+ try testing.expectEqualStrings(&test_ground_fixture, encoded.written());
+
+ var source: std.Io.Reader = .fixed(encoded.written());
+ const decoded = try decode(testing.allocator, &source, 0);
+ try testing.expect(decoded == .ground);
+}
+
+test "continuation rejects invalid semantic shapes" {
+ const testing = std.testing;
+ try testing.expectError(
+ error.NoPendingState,
+ validate(.{ .bytes = "\x1b[31m" }),
+ );
+ try testing.expectError(
+ error.ReplayWouldCommit,
+ validate(.{ .bytes = "\x1b[31\x07" }),
+ );
+ try testing.expectError(
+ error.NonCanonicalContinuation,
+ validate(.{ .bytes = "prefix\x1b[31" }),
+ );
+ try testing.expectError(
+ error.NonCanonicalContinuation,
+ validate(.{ .bytes = "\x1b[31\x1b[4" }),
+ );
+}
+
+test "continuation record round trip and cap" {
+ const testing = std.testing;
+ const values = [_]Value{
+ .ground,
+ .{ .bytes = "\x1b[31" },
+ .{ .bytes = "\xF0\x9F" },
+ };
+
+ for (values) |value| {
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ var stream: record.Writer = .init(testing.allocator, &encoded.writer);
+ defer stream.deinit();
+ try encode(value, &stream);
+
+ var source: std.Io.Reader = .fixed(encoded.written());
+ const decoded = try decode(testing.allocator, &source, 1024);
+ defer switch (decoded) {
+ .ground => {},
+ .bytes => |bytes| testing.allocator.free(bytes),
+ };
+ switch (value) {
+ .ground => try testing.expect(decoded == .ground),
+ .bytes => |expected| try testing.expectEqualStrings(
+ expected,
+ decoded.bytes,
+ ),
+ }
+ }
+
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ var stream: record.Writer = .init(testing.allocator, &encoded.writer);
+ defer stream.deinit();
+ try encode(.{ .bytes = "\x1b[31" }, &stream);
+
+ var capped_source: std.Io.Reader = .fixed(encoded.written());
+ var failing = testing.FailingAllocator.init(testing.allocator, .{
+ .fail_index = 0,
+ });
+ try testing.expectError(
+ error.ContinuationLimitExceeded,
+ decode(failing.allocator(), &capped_source, 3),
+ );
+ try testing.expectEqual(
+ @as(usize, record.Header.len),
+ capped_source.seek,
+ );
+}
+
+test "continuation record rejects truncation, checksum, and tag" {
+ const testing = std.testing;
+
+ for (0..test_csi_fixture.len) |len| {
+ var source: std.Io.Reader = .fixed(test_csi_fixture[0..len]);
+ try testing.expectError(
+ error.EndOfStream,
+ decode(testing.allocator, &source, 1024),
+ );
+ }
+
+ var invalid_checksum = test_csi_fixture;
+ invalid_checksum[6] ^= 1;
+ var checksum_source: std.Io.Reader = .fixed(&invalid_checksum);
+ try testing.expectError(
+ error.InvalidChecksum,
+ decode(testing.allocator, &checksum_source, 1024),
+ );
+
+ var wrong_tag = test_ground_fixture;
+ std.mem.writeInt(u16, wrong_tag[0..2], @intFromEnum(record.Tag.ready), .little);
+ var tag_source: std.Io.Reader = .fixed(&wrong_tag);
+ try testing.expectError(
+ error.UnexpectedRecordTag,
+ decode(testing.allocator, &tag_source, 1024),
+ );
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/envelope.zig b/vendor/libghostty-vt/src/terminal/snapshot/envelope.zig
new file mode 100644
index 00000000..21fcefb9
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/envelope.zig
@@ -0,0 +1,104 @@
+//! Snapshot envelope.
+//!
+//! Every snapshot binary blob begins with exactly one envelope at byte zero.
+//! It is followed by a set of records. Each record provides their own
+//! tag, payload length, CRC, etc.
+//!
+//! The envelope identifies the bytes as a terminal snapshot and selects the
+//! single version governing the entire blob. A decoder validates both fields
+//! before reading any records.
+//!
+//! The envelope is exactly ten bytes. All integers are unsigned and
+//! little-endian.
+//!
+//! | Offset | Size | Field |
+//! | -----: | ---: | :------------------- |
+//! | 0 | 8 | Magic (`GHOSTSNP`) |
+//! | 8 | 2 | Version (`u16`) |
+
+const std = @import("std");
+const test_fixture = @import("fixture.zig");
+const io = @import("io.zig");
+
+/// Identifies a Ghostty terminal snapshot and rejects unrelated input before
+/// any record decoding begins. All eight bytes are part of the wire value.
+pub const magic = "GHOSTSNP";
+
+/// The complete compatibility boundary for snapshot layout and behavior.
+/// Version 1 readers require this value to match exactly.
+pub const version: u16 = 1;
+
+/// Number of bytes in the fixed envelope: magic followed by version.
+pub const encoded_len = computeLen();
+
+comptime {
+ // We expect this so if it changes we should think carefully.
+ std.debug.assert(encoded_len == 10);
+}
+
+pub const DecodeError = std.Io.Reader.Error || error{
+ InvalidMagic,
+ UnsupportedVersion,
+};
+
+/// Encode the envelope.
+pub fn encode(writer: *std.Io.Writer) std.Io.Writer.Error!void {
+ try writer.writeAll(magic);
+ try io.writeInt(writer, u16, version);
+}
+
+/// Decode and validate the envelope.
+pub fn decode(reader: *std.Io.Reader) DecodeError!void {
+ var actual_magic: [magic.len]u8 = undefined;
+ try reader.readSliceAll(&actual_magic);
+ if (!std.mem.eql(u8, magic, &actual_magic)) return error.InvalidMagic;
+
+ const actual_version = try io.readInt(reader, u16);
+ if (actual_version != version) return error.UnsupportedVersion;
+}
+
+fn computeLen() usize {
+ comptime {
+ var buf: [128]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ encode(&writer) catch unreachable;
+ return writer.end;
+ }
+}
+
+const test_golden_fixture = test_fixture.parse(@embedFile("testdata/envelope-v1.hex"));
+
+test "golden encoding" {
+ var buf: [encoded_len]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ try encode(&writer);
+
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/envelope-v1.hex",
+ "snapshot_fixture-envelope-v1.hex",
+ &test_golden_fixture,
+ writer.buffered(),
+ );
+
+ var reader: std.Io.Reader = .fixed(&test_golden_fixture);
+ try decode(&reader);
+}
+
+test "reject invalid magic and version" {
+ var invalid_magic: std.Io.Reader = .fixed("GHOSTSNX\x01\x00");
+ try std.testing.expectError(error.InvalidMagic, decode(&invalid_magic));
+
+ var invalid_version: std.Io.Reader = .fixed("GHOSTSNP\x00\x00");
+ try std.testing.expectError(
+ error.UnsupportedVersion,
+ decode(&invalid_version),
+ );
+}
+
+test "reject every truncation" {
+ for (0..encoded_len) |len| {
+ var reader: std.Io.Reader = .fixed(test_golden_fixture[0..len]);
+ try std.testing.expectError(error.EndOfStream, decode(&reader));
+ }
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/fixture.zig b/vendor/libghostty-vt/src/terminal/snapshot/fixture.zig
new file mode 100644
index 00000000..d5c86b2b
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/fixture.zig
@@ -0,0 +1,479 @@
+//! Test-only support for reviewable snapshot golden fixtures.
+//!
+//! Snapshot compatibility references are stored as annotated hexadecimal text
+//! under `testdata/`. Each byte is written as exactly two hexadecimal digits.
+//! Whitespace is insignificant, and `#` begins a comment through the end of the
+//! line. This permits field, record, and absolute-offset annotations without
+//! changing the bytes embedded by a test.
+//!
+//! `parse` validates and decodes an `@embedFile` at comptime. Tests should
+//! encode their native value, compare the generated bytes with that embedded
+//! reference using `expectEqual`, and then decode the reference itself. This
+//! keeps encoding regression coverage separate from backwards-decoding
+//! coverage.
+//!
+//! `expectEqual` formats a fresh candidate on every run. Matching candidates
+//! remain in the test's temporary directory. A mismatch copies the candidate
+//! to the repository root, reports its path and first differing byte, and
+//! fails without modifying the checked-in reference. After reviewing an
+//! intentional wire change, a maintainer manually replaces the reference.
+//! Fixture filenames include the snapshot version so a future format adds new
+//! references instead of overwriting compatibility data for an older version.
+//!
+//! A typical fixed-value test looks like this:
+//!
+//! ```zig
+//! const fixture = @import("fixture.zig");
+//!
+//! const reference = fixture.parse(
+//! @embedFile("testdata/example-v1.hex"),
+//! );
+//!
+//! test "example golden encoding and decoding" {
+//! var encoded: [Example.len]u8 = undefined;
+//! var writer: std.Io.Writer = .fixed(&encoded);
+//! try Example.encode(value, &writer);
+//!
+//! try fixture.expectEqual(
+//! .bytes,
+//! "src/terminal/snapshot/testdata/example-v1.hex",
+//! "snapshot_fixture-example-v1.hex",
+//! &reference,
+//! writer.buffered(),
+//! );
+//!
+//! var reader: std.Io.Reader = .fixed(&reference);
+//! try std.testing.expectEqualDeep(
+//! value,
+//! try Example.decode(&reader),
+//! );
+//! }
+//! ```
+//!
+//! ## Kaitai
+//!
+//! Every fixture has three machine-readable comment fields:
+//!
+//! ```text
+//! # Kaitai type: page_payload
+//! # Kaitai params:
+//! # Kaitai offset: 0
+//! ```
+//!
+//! These select a type from `snapshot.ksy`, its whitespace-separated
+//! parameters, and the byte offset where parsing begins. The Kaitai verifier
+//! discovers fixtures from the filesystem and uses this metadata instead of
+//! maintaining a parallel filename table. Generated candidates copy the
+//! metadata from their checked-in reference.
+//!
+
+const std = @import("std");
+const envelope = @import("envelope.zig");
+const record = @import("record.zig");
+
+const log = std.log.scoped(.snapshot_fixture);
+
+pub const Kind = enum {
+ bytes,
+ page,
+ snapshot,
+};
+
+/// Decode an annotated hexadecimal fixture at comptime.
+///
+/// Whitespace is ignored. `#` begins a comment that continues through the end
+/// of the line. Every other token must be exactly two hexadecimal digits.
+pub fn parse(comptime source: []const u8) [decodedLen(source)]u8 {
+ comptime {
+ // Large complete-snapshot fixtures exceed Zig's default comptime
+ // branch budget while scanning their comments and byte tokens.
+ @setEvalBranchQuota(100_000_000);
+
+ // The first pass in decodedLen gives this result its exact array type.
+ // Keeping it an array lets callers use the fixture in comptime slices.
+ var result: [decodedLen(source)]u8 = undefined;
+ var source_index: usize = 0;
+ var result_index: usize = 0;
+
+ while (source_index < source.len) {
+ // Comments and layout are purely for reviewers and contribute no
+ // bytes to the embedded reference.
+ skipIgnored(source, &source_index);
+ if (source_index == source.len) break;
+
+ // Every data token is one complete byte. Parse it directly rather
+ // than accepting variable-width integers or other hex syntax.
+ if (source_index + 1 >= source.len) {
+ @compileError("snapshot fixture ends with one hex digit");
+ }
+ result[result_index] =
+ hexNibble(source[source_index]) << 4 |
+ hexNibble(source[source_index + 1]);
+ result_index += 1;
+ source_index += 2;
+
+ // Requiring a separator catches accidental third digits and makes
+ // the accepted grammar match the formatter below.
+ if (source_index < source.len and
+ !std.ascii.isWhitespace(source[source_index]) and
+ source[source_index] != '#')
+ {
+ @compileError(
+ "snapshot fixture hex bytes must be separated by whitespace",
+ );
+ }
+ }
+
+ return result;
+ }
+}
+
+/// Compare generated bytes with a checked-in reference.
+///
+/// A formatted candidate is always created in a temporary directory. On a
+/// mismatch it is copied into the repository root before the test fails.
+pub fn expectEqual(
+ kind: Kind,
+ reference_path: []const u8,
+ candidate_name: []const u8,
+ expected: []const u8,
+ actual: []const u8,
+) !void {
+ const testing = std.testing;
+ const alloc = testing.allocator;
+
+ var tmp = testing.tmpDir(.{});
+ defer tmp.cleanup();
+
+ // Kaitai parser selection lives in the reference itself. Read the textual
+ // source so generated candidates preserve that metadata even though the
+ // byte comparison below uses the comptime-decoded reference.
+ const reference_source = try std.Io.Dir.cwd().readFileAlloc(
+ testing.io,
+ reference_path,
+ alloc,
+ .unlimited,
+ );
+ defer alloc.free(reference_source);
+
+ // Always materialize a candidate, even when it will match. This keeps the
+ // generation path exercised on every test run while avoiding repository
+ // artifacts for the normal successful case.
+ {
+ var candidate_file = try tmp.dir.createFile(
+ testing.io,
+ candidate_name,
+ .{},
+ );
+ defer candidate_file.close(testing.io);
+ var write_buffer: [4096]u8 = undefined;
+ var candidate_writer = candidate_file.writer(
+ testing.io,
+ &write_buffer,
+ );
+ try format(
+ kind,
+ reference_source,
+ actual,
+ &candidate_writer.interface,
+ );
+ try candidate_writer.interface.flush();
+ }
+
+ // Matching candidates remain in the temporary directory and disappear
+ // with its cleanup.
+ if (std.mem.eql(u8, expected, actual)) return;
+
+ // The test temp directory is not necessarily below the working directory.
+ // Resolve both paths before copying the candidate to the stable,
+ // user-visible repository-root name.
+ const tmp_path = try tmp.dir.realPathFileAlloc(
+ testing.io,
+ candidate_name,
+ alloc,
+ );
+ defer alloc.free(tmp_path);
+ const cwd = try std.Io.Dir.cwd().realPathFileAlloc(
+ testing.io,
+ ".",
+ alloc,
+ );
+ defer alloc.free(cwd);
+ const candidate_path = try std.fs.path.join(
+ alloc,
+ &.{ cwd, candidate_name },
+ );
+ defer alloc.free(candidate_path);
+ try std.Io.Dir.copyFileAbsolute(
+ tmp_path,
+ candidate_path,
+ testing.io,
+ .{},
+ );
+
+ // Report the first useful comparison point. When one byte sequence is a
+ // prefix of the other, this is the shared length where they diverge.
+ const difference = difference: {
+ const shared_len = @min(expected.len, actual.len);
+ for (
+ expected[0..shared_len],
+ actual[0..shared_len],
+ 0..,
+ ) |expected_byte, actual_byte, index| {
+ if (expected_byte != actual_byte) break :difference index;
+ }
+ break :difference shared_len;
+ };
+ log.err(
+ "snapshot fixture differs reference={s} candidate={s} " ++
+ "offset=0x{x} expected_len={} actual_len={}",
+ .{
+ reference_path,
+ candidate_path,
+ difference,
+ expected.len,
+ actual.len,
+ },
+ );
+ return error.TestExpectedEqual;
+}
+
+fn decodedLen(comptime source: []const u8) usize {
+ comptime {
+ // This is a complete validation pass, not just a count. Invalid syntax
+ // therefore fails before parse allocates and fills its result array.
+ @setEvalBranchQuota(100_000_000);
+
+ var index: usize = 0;
+ var result: usize = 0;
+ while (index < source.len) {
+ skipIgnored(source, &index);
+ if (index == source.len) break;
+
+ if (index + 1 >= source.len) {
+ @compileError("snapshot fixture ends with one hex digit");
+ }
+ _ = hexNibble(source[index]);
+ _ = hexNibble(source[index + 1]);
+ result += 1;
+ index += 2;
+
+ if (index < source.len and
+ !std.ascii.isWhitespace(source[index]) and
+ source[index] != '#')
+ {
+ @compileError(
+ "snapshot fixture hex bytes must be separated by whitespace",
+ );
+ }
+ }
+ return result;
+ }
+}
+
+fn skipIgnored(comptime source: []const u8, index: *usize) void {
+ while (index.* < source.len) {
+ // Layout whitespace is unrestricted so fixtures can group fields and
+ // keep deterministic sixteen-byte output lines.
+ if (std.ascii.isWhitespace(source[index.*])) {
+ index.* += 1;
+ continue;
+ }
+
+ // A comment consumes the rest of its line. The newline itself is
+ // consumed by the whitespace case on the next iteration.
+ if (source[index.*] != '#') return;
+ while (index.* < source.len and source[index.*] != '\n') {
+ index.* += 1;
+ }
+ }
+}
+
+fn hexNibble(comptime value: u8) u8 {
+ return switch (value) {
+ '0'...'9' => value - '0',
+ 'a'...'f' => value - 'a' + 10,
+ 'A'...'F' => value - 'A' + 10,
+ else => @compileError("snapshot fixture contains a non-hex digit"),
+ };
+}
+
+fn format(
+ kind: Kind,
+ reference_source: []const u8,
+ bytes: []const u8,
+ writer: *std.Io.Writer,
+) (std.Io.Writer.Error || error{InvalidKaitaiMetadata})!void {
+ // Every generated candidate starts with enough maintenance context to be
+ // understandable when copied out of a failing test's temp directory.
+ try writer.writeAll("# Ghostty snapshot fixture\n");
+ try writeKaitaiMetadata(reference_source, writer);
+ try writer.print(
+ "# Wire version: {}\n" ++
+ "# Generated by its snapshot test; review before replacing.\n" ++
+ "# On mismatch, the candidate is copied to the repository root.\n",
+ .{envelope.version},
+ );
+
+ // Small values only need a hex dump. Larger compound formats get
+ // structure-aware section labels without changing their decoded bytes.
+ switch (kind) {
+ .bytes => try writeSection(
+ "encoded bytes",
+ bytes,
+ 0,
+ bytes.len,
+ writer,
+ ),
+ .page => try formatPage(bytes, writer),
+ .snapshot => try formatSnapshot(bytes, writer),
+ }
+}
+
+fn writeKaitaiMetadata(
+ reference_source: []const u8,
+ writer: *std.Io.Writer,
+) (std.Io.Writer.Error || error{InvalidKaitaiMetadata})!void {
+ const prefixes = [_][]const u8{
+ "# Kaitai type:",
+ "# Kaitai params:",
+ "# Kaitai offset:",
+ };
+ var found = [_]bool{false} ** prefixes.len;
+
+ var lines = std.mem.splitScalar(u8, reference_source, '\n');
+ while (lines.next()) |untrimmed| {
+ const line = std.mem.trim(u8, untrimmed, " \r");
+ for (prefixes, &found) |prefix, *seen| {
+ if (!std.mem.startsWith(u8, line, prefix)) continue;
+ if (seen.*) return error.InvalidKaitaiMetadata;
+ seen.* = true;
+ try writer.print("{s}\n", .{line});
+ break;
+ }
+ }
+
+ for (found) |seen| {
+ if (!seen) return error.InvalidKaitaiMetadata;
+ }
+}
+
+fn formatPage(
+ bytes: []const u8,
+ writer: *std.Io.Writer,
+) std.Io.Writer.Error!void {
+ // PAGE version 1 has a twenty-byte fixed header. The remainder is
+ // self-describing through the counts and dimensions in that header.
+ const header_end = @min(bytes.len, 20);
+ try writeSection("PAGE header", bytes, 0, header_end, writer);
+ if (header_end < bytes.len) {
+ try writeSection(
+ "style and hyperlink tables, rows, and cells",
+ bytes,
+ header_end,
+ bytes.len,
+ writer,
+ );
+ }
+}
+
+fn formatSnapshot(
+ bytes: []const u8,
+ writer: *std.Io.Writer,
+) std.Io.Writer.Error!void {
+ // A complete snapshot begins with its unframed envelope. Clamp this first
+ // section so a partially generated candidate can still be inspected.
+ const envelope_end = @min(bytes.len, envelope.encoded_len);
+ try writeSection("snapshot envelope", bytes, 0, envelope_end, writer);
+
+ // Walk record framing only far enough to annotate boundaries. The emitted
+ // hex remains authoritative; this formatter never repairs candidate data.
+ var offset: usize = envelope_end;
+ while (offset < bytes.len) {
+ // A partial header cannot provide a safe payload boundary, so preserve
+ // the remaining bytes as one explicitly incomplete section.
+ if (bytes.len - offset < record.Header.len) {
+ try writeSection(
+ "trailing partial record",
+ bytes,
+ offset,
+ bytes.len,
+ writer,
+ );
+ return;
+ }
+
+ // Tag and payload length are the first six bytes of every record
+ // header. CRC validation belongs to the codec test, not this formatter.
+ const tag_raw = std.mem.readInt(
+ u16,
+ bytes[offset..][0..2],
+ .little,
+ );
+ const payload_len: u32 = std.mem.readInt(
+ u32,
+ bytes[offset + 2 ..][0..4],
+ .little,
+ );
+
+ // Clamp the section to the available candidate bytes. This makes a
+ // truncated payload reviewable instead of indexing beyond the slice.
+ const record_end: usize = @min(
+ bytes.len,
+ offset + record.Header.len + @as(usize, payload_len),
+ );
+
+ // Known tags make the annotated diff readable. Preserve unknown tags
+ // numerically so formatter output is still useful for encoder bugs.
+ if (std.enums.fromInt(record.Tag, tag_raw)) |tag| {
+ try writer.print(
+ "\n# offset 0x{x:0>8}: {s} record, payload {} bytes\n",
+ .{ offset, @tagName(tag), payload_len },
+ );
+ } else {
+ try writer.print(
+ "\n# offset 0x{x:0>8}: unknown record {}, payload {} bytes\n",
+ .{ offset, tag_raw, payload_len },
+ );
+ }
+ try writeHex(bytes, offset, record_end, writer);
+ offset = record_end;
+ }
+}
+
+fn writeSection(
+ name: []const u8,
+ bytes: []const u8,
+ start: usize,
+ end: usize,
+ writer: *std.Io.Writer,
+) std.Io.Writer.Error!void {
+ // Sections begin on a fresh line and carry their absolute wire offset.
+ try writer.print(
+ "\n# offset 0x{x:0>8}: {s}\n",
+ .{ start, name },
+ );
+ try writeHex(bytes, start, end, writer);
+}
+
+fn writeHex(
+ bytes: []const u8,
+ start: usize,
+ end: usize,
+ writer: *std.Io.Writer,
+) std.Io.Writer.Error!void {
+ const digits = "0123456789abcdef";
+ var offset = start;
+ while (offset < end) {
+ // Lowercase, sixteen-byte lines provide stable textual diffs. The
+ // trailing offset is a comment and is ignored by parse.
+ const line_end = @min(end, offset + 16);
+ for (bytes[offset..line_end], 0..) |byte, index| {
+ if (index != 0) try writer.writeByte(' ');
+ try writer.writeByte(digits[byte >> 4]);
+ try writer.writeByte(digits[byte & 0x0f]);
+ }
+ try writer.print(" # 0x{x:0>8}\n", .{offset});
+ offset = line_end;
+ }
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/grid.zig b/vendor/libghostty-vt/src/terminal/snapshot/grid.zig
new file mode 100644
index 00000000..3a890913
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/grid.zig
@@ -0,0 +1,2403 @@
+//! Grid (rows, cells, and grapheme suffixes) encoding.
+//!
+//! A grid contains the rows and cells of a terminal page. Its dimensions are
+//! supplied by the containing record rather than repeated here. The encoder
+//! writes exactly `rows` row records followed by one grapheme suffix section.
+//!
+//! All records are tightly packed with no padding between them. All integers
+//! are unsigned and little-endian.
+//!
+//! The layout is designed so the common case decodes with bulk copies: cells
+//! are fixed-size words, trailing default cells are elided per row, and the
+//! variable-length grapheme suffixes live outside the row data.
+//!
+//! ```text
+//! +---------------------------+
+//! | Row 0 |
+//! +---------------------------+
+//! | ... |
+//! +---------------------------+
+//! | Row (rows - 1) |
+//! +---------------------------+
+//! | Grapheme suffix section |
+//! +---------------------------+
+//! ```
+//!
+//! ## Row
+//!
+//! Each row has the following format:
+//!
+//! | Offset | Size | Field |
+//! | -----: | ----------------: | :------------------------- |
+//! | 0 | 1 | Row flags |
+//! | 1 | 2 | Encoded cell count (`u16`) |
+//! | 3 | `width` * `count` | Encoded cells |
+//!
+//! The row flag byte has the following format:
+//!
+//! | Bits | Field |
+//! | ---: | :------------------------ |
+//! | 0 | Wrap |
+//! | 1 | Wrap continuation |
+//! | 2-3 | Semantic prompt |
+//! | 4-5 | Encoded cell width |
+//! | 6-7 | Reserved, zero |
+//!
+//! Semantic prompt values are:
+//!
+//! | Value | Meaning |
+//! | ----: | :------------------ |
+//! | 0 | None |
+//! | 1 | Prompt |
+//! | 2 | Prompt continuation |
+//!
+//! Value 3 is not emitted in snapshot version 1. Decoders treat it as none.
+//!
+//! The encoded cell count must not exceed the grid's column count; it is a
+//! structural field and decoders reject larger values. Cells at and beyond
+//! the count are the default cell: all sixty-four bits zero, meaning an
+//! empty narrow codepoint cell with the default style and no hyperlink.
+//! Canonical encoders emit exactly through the row's last non-default cell,
+//! so a fully default row has a zero count and no cell words.
+//!
+//! ## Encoded cell width
+//!
+//! The two width bits select how many bytes encode each of the row's
+//! cells: `1 << width` is the size, so zero through three select one, two,
+//! four, or eight bytes. Narrower widths are truncated transports of the
+//! same cell word: a cell qualifies for a width when all of its higher
+//! word bits are zero.
+//!
+//! | Width | Bytes | Encoded value and admitted cells |
+//! | ----: | ----: | :--------------------------------------------------- |
+//! | 0 | 1 | Codepoint at or below U+00FF; all other bits zero |
+//! | 1 | 2 | Codepoint at or below U+FFFF; all other bits zero |
+//! | 2 | 4 | Word bits 0-31: any content kind and codepoint, style |
+//! | | | IDs 1-63, narrow, no flags, no hyperlink |
+//! | 3 | 8 | The complete word |
+//!
+//! Widths zero and one store the codepoint value itself, which is word
+//! bits 2-25 shifted down; the reconstructed word is the codepoint shifted
+//! left by two. Width two stores the word's low half unshifted. This makes
+//! every width a zero-extension on decode and a truncation on encode.
+//!
+//! Canonical encoders choose each row's smallest admissible width, which
+//! follows directly from the bitwise OR of the row's cell words. Decoders
+//! use the declared width for framing and accept rows encoded wider than
+//! necessary. The width of a row with a zero cell count is canonically
+//! zero and carries no meaning.
+//!
+//! Native row cache flags are not encoded. In particular, the Kitty virtual
+//! placeholder hint is derived while decoding cells containing U+10EEEE.
+//!
+//! ## Cell
+//!
+//! Each cell is one 64-bit little-endian word, transported at the row's
+//! encoded cell width as described above:
+//!
+//! ```text
+//! bit 0 +-------------------------------+
+//! | Content kind |
+//! | 2 bits |
+//! bit 2 +-------------------------------+
+//! | Content |
+//! | 24 bits |
+//! bit 26 +-------------------------------+
+//! | Style ID |
+//! | 16 bits |
+//! bit 42 +-------------------------------+
+//! | Width kind |
+//! | 2 bits |
+//! bit 44 +-------------------------------+
+//! | Protected |
+//! bit 45 +-------------------------------+
+//! | Hyperlink flag |
+//! bit 46 +-------------------------------+
+//! | Semantic content |
+//! | 2 bits |
+//! bit 48 +-------------------------------+
+//! | Hyperlink ID |
+//! | 16 bits |
+//! bit 64 +-------------------------------+
+//! ```
+//!
+//! Content kinds are:
+//!
+//! | Value | Meaning |
+//! | ----: | :------------------------------- |
+//! | 0 | Codepoint |
+//! | 1 | Codepoint with grapheme suffix |
+//! | 2 | Palette background |
+//! | 3 | RGB background |
+//!
+//! The content kind selects the layout of the 24-bit content field. All
+//! content bit positions below are relative to the start of the content
+//! field, so content bit 0 is cell word bit 2.
+//!
+//! For codepoint content (kinds 0 and 1), the content field is a Unicode
+//! scalar value. Values above U+10FFFF and surrogates decode as U+FFFD.
+//! Kind 1 additionally declares that the grapheme suffix section contains
+//! one entry for this cell; the cell is otherwise identical to kind 0.
+//!
+//! ```text
+//! bit 0 +-------------------------------+
+//! | Unicode scalar value |
+//! | 24 bits |
+//! bit 24 +-------------------------------+
+//! ```
+//!
+//! For a palette background (kind 2), the low byte is the palette index.
+//! The remaining content bits are reserved, canonically zero, and ignored
+//! by decoders.
+//!
+//! ```text
+//! bit 0 +-------------------------------+
+//! | Palette index |
+//! | 8 bits |
+//! bit 8 +-------------------------------+
+//! | Reserved, zero |
+//! | 16 bits |
+//! bit 24 +-------------------------------+
+//! ```
+//!
+//! For an RGB background (kind 3), the content field is one byte per
+//! channel:
+//!
+//! ```text
+//! bit 0 +-------------------------------+
+//! | Red |
+//! | 8 bits |
+//! bit 8 +-------------------------------+
+//! | Green |
+//! | 8 bits |
+//! bit 16 +-------------------------------+
+//! | Blue |
+//! | 8 bits |
+//! bit 24 +-------------------------------+
+//! ```
+//!
+//! Width kinds are:
+//!
+//! | Value | Meaning |
+//! | ----: | :---------- |
+//! | 0 | Narrow |
+//! | 1 | Wide |
+//! | 2 | Spacer tail |
+//! | 3 | Spacer head |
+//!
+//! Semantic content values are:
+//!
+//! | Value | Meaning |
+//! | ----: | :------ |
+//! | 0 | Output |
+//! | 1 | Input |
+//! | 2 | Prompt |
+//!
+//! Value 3 is not emitted in snapshot version 1. Decoders treat it as output.
+//!
+//! Style and hyperlink ID zero mean no style and no hyperlink. Other IDs
+//! refer to entries in the containing record's separate style and hyperlink
+//! tables. The hyperlink flag is set exactly when the hyperlink ID is
+//! nonzero; decoders derive cell linkage from the remapped ID and ignore the
+//! flag itself.
+//!
+//! ## Grapheme suffix section
+//!
+//! The section begins with an entry count followed by that many entries:
+//!
+//! | Offset | Size | Field |
+//! | -----: | ------: | :------------------- |
+//! | 0 | 4 | Entry count (`u32`) |
+//! | 4 | varies | Entries |
+//!
+//! Each entry:
+//!
+//! | Offset | Size | Field |
+//! | -----: | ----------: | :-------------------------- |
+//! | 0 | 2 | Row (`u16`) |
+//! | 2 | 2 | Column (`u16`) |
+//! | 4 | 2 | Codepoint count (`u16`) |
+//! | 6 | 4 * `count` | Codepoints (`u32` each) |
+//!
+//! Each codepoint is a Unicode scalar; invalid scalars are individually
+//! ignored by decoders. Canonical encoders emit exactly one entry, with at
+//! least one codepoint, for every kind 1 cell, in ascending row-then-column
+//! order. Decoders consume every declared entry and ignore entries whose
+//! target is out of range, is not a codepoint cell, has a zero codepoint, or
+//! already received an entry. A kind 1 cell that receives no suffix
+//! codepoints decodes as a plain codepoint cell.
+
+const std = @import("std");
+const assert = std.debug.assert;
+const builtin = @import("builtin");
+const Allocator = std.mem.Allocator;
+const test_fixture = @import("fixture.zig");
+const io = @import("io.zig");
+const terminal_hyperlink = @import("../hyperlink.zig");
+const terminal_page = @import("../page.zig");
+const terminal_style = @import("../style.zig");
+
+/// The Kitty virtual-placement placeholder remains wire-relevant even when
+/// runtime Kitty graphics support is compiled out.
+const kitty_virtual_placeholder: u21 = 0x10EEEE;
+
+const TerminalCell = terminal_page.Cell;
+const TerminalHyperlinkId = terminal_hyperlink.Id;
+const TerminalPage = terminal_page.Page;
+const TerminalRow = terminal_page.Row;
+const TerminalStyleId = terminal_style.Id;
+
+/// The header before every row's encoded cells.
+///
+/// The semantic prompt is a raw integer for the same reason as the wire
+/// cell fields: decoders must accept its reserved value without
+/// instantiating an invalid native enum. The width enum is exhaustive over
+/// its two bits, so every header byte bit-casts to a valid value.
+pub const Row = packed struct(u8) {
+ wrap: bool = false,
+ wrap_continuation: bool = false,
+ semantic_prompt: u2 = 0,
+ cell_width: Cell.EncodedWidth = .one,
+ _padding: u2 = 0,
+};
+
+/// The wire layout of one encoded cell. This is its own registry: the bit
+/// positions and field meanings are part of the snapshot format and are
+/// documented above independently of the native cell.
+///
+/// Enum-like fields are raw integers because decoders must accept reserved
+/// values (for example semantic content 3) without instantiating an invalid
+/// native enum.
+pub const Cell = packed struct(u64) {
+ kind: u2 = @intFromEnum(Kind.codepoint),
+ content: u24 = 0,
+ style_id: u16 = 0,
+ width: u2 = 0,
+ protected: bool = false,
+ hyperlink: bool = false,
+ semantic_content: u2 = 0,
+ hyperlink_id: u16 = 0,
+
+ /// Determines how `content` is interpreted.
+ pub const Kind = enum(u2) {
+ codepoint = 0,
+ codepoint_grapheme = 1,
+ bg_color_palette = 2,
+ bg_color_rgb = 3,
+ };
+
+ /// The encoded cell width declared by a row header: how many bytes
+ /// transport each of the row's cell words. See the format
+ /// documentation above for the value each width transports and the
+ /// cells it admits.
+ ///
+ /// `truncate` and `extend` are the transport transform itself, so the
+ /// admission masks derive from them rather than being maintained by
+ /// hand: a cell word is admitted exactly when it round-trips.
+ pub const EncodedWidth = enum(u2) {
+ one = 0,
+ two = 1,
+ four = 2,
+ eight = 3,
+
+ /// The number of bytes transporting one cell word.
+ pub fn size(self: EncodedWidth) usize {
+ return @as(usize, 1) << @intFromEnum(self);
+ }
+
+ /// The integer type transporting one cell word.
+ pub fn Int(comptime self: EncodedWidth) type {
+ return switch (self) {
+ .one => u8,
+ .two => u16,
+ .four => u32,
+ .eight => u64,
+ };
+ }
+
+ /// Truncate one cell word to its transported value. Only words
+ /// admitted by this width round-trip; `select` proves that for
+ /// every cell in a row before an encoder may use it.
+ pub fn truncate(comptime self: EncodedWidth, word: u64) self.Int() {
+ return @truncate(switch (self) {
+ // The bare codepoint, shifted down from the content field.
+ .one, .two => @as(Cell, @bitCast(word)).content,
+
+ // The word itself.
+ .four, .eight => word,
+ });
+ }
+
+ /// Widen one transported value back to its cell word.
+ pub fn extend(comptime self: EncodedWidth, value: self.Int()) u64 {
+ return switch (self) {
+ .one, .two => @bitCast(Cell{ .content = value }),
+ .four, .eight => value,
+ };
+ }
+
+ /// The word bits a cell may use and still round-trip through this
+ /// width.
+ pub fn mask(comptime self: EncodedWidth) u64 {
+ return comptime self.extend(std.math.maxInt(self.Int()));
+ }
+
+ /// The smallest width admitting the word, typically the bitwise
+ /// OR of every cell word in a row.
+ pub fn select(word: u64) EncodedWidth {
+ inline for ([_]EncodedWidth{ .one, .two, .four }) |width| {
+ if (word & ~width.mask() == 0) return width;
+ }
+ return .eight;
+ }
+ };
+};
+
+/// Whether the native cell's in-memory layout matches the wire cell layout
+/// bit for bit, with the wire hyperlink ID occupying the native padding.
+///
+/// The wire format does not require this: it is an optimization. When it
+/// holds, whole rows encode and decode as bulk copies. If the native layout
+/// ever diverges, the portable field-by-field codec below remains correct
+/// and this constant simply becomes false.
+const native_matches_wire = native: {
+ if (@bitSizeOf(TerminalCell) != 64) break :native false;
+
+ // The bulk copies above are only sound if we can prove the two layouts
+ // agree, and we want native cell changes to demote us to the portable
+ // codec automatically rather than corrupt snapshots.
+ //
+ // Instead of pinning every native field offset and enum value w/ assertions
+ // that must be maintained by hand, each probe below pairs a native
+ // cell with the wire cell that must share its exact bit pattern; both
+ // sides bit cast to a word and any difference means some field moved
+ // or some enum member was renumbered.
+ //
+ // Three probes, one per content payload, cover the whole cell.
+ const probes = [_]struct {
+ native: TerminalCell,
+ wire: Cell,
+ }{
+ .{
+ .native = .{
+ .content_tag = .codepoint_grapheme,
+ .content = .{ .codepoint = .{ .data = 0x10FFFF } },
+ .style_id = 0xBEEF,
+ .wide = .spacer_tail,
+ .protected = true,
+ ._padding = 0x1D2C,
+ },
+ .wire = .{
+ .kind = 1,
+ .content = 0x10FFFF,
+ .style_id = 0xBEEF,
+ .width = 2,
+ .protected = true,
+ // The native padding position, canonical wire or not.
+ .hyperlink_id = 0x1D2C,
+ },
+ },
+ .{
+ .native = .{
+ .content_tag = .bg_color_palette,
+ .content = .{ .color_palette = .{ .data = 0xAB } },
+ .wide = .spacer_head,
+ .hyperlink = true,
+ .semantic_content = .input,
+ },
+ .wire = .{
+ .kind = 2,
+ .content = 0xAB,
+ .width = 3,
+ .hyperlink = true,
+ .semantic_content = 1,
+ },
+ },
+ .{
+ .native = .{
+ .content_tag = .bg_color_rgb,
+ .content = .{ .color_rgb = .{
+ .r = 0x12,
+ .g = 0x34,
+ .b = 0x56,
+ } },
+ .wide = .wide,
+ .semantic_content = .prompt,
+ },
+ .wire = .{
+ .kind = 3,
+ .content = 0x563412,
+ .width = 1,
+ .semantic_content = 2,
+ },
+ },
+ };
+ for (probes) |probe| {
+ const native_bits: u64 = @bitCast(probe.native);
+ const wire_bits: u64 = @bitCast(probe.wire);
+ if (native_bits != wire_bits) break :native false;
+ }
+
+ break :native true;
+};
+
+/// Whether rows of cells can be copied between native and wire storage
+/// without per-cell transformation.
+const bulk_codec = native_matches_wire and
+ builtin.cpu.arch.endian() == .little;
+
+pub const EncodeError = std.Io.Writer.Error || error{
+ /// Wide and spacer cells do not form a valid row.
+ InvalidWideCell,
+
+ /// One cell's grapheme suffix exceeds the entry's u16 codepoint count.
+ TooManyGraphemes,
+};
+
+/// Encode every row, cell, and grapheme suffix directly from a page.
+///
+/// If an error is returned, partial data may have been written. If you
+/// want transactional writing, the caller is responsible for using something
+/// like a seekable stream and rolling back.
+pub fn encode(
+ page: *const TerminalPage,
+ writer: *std.Io.Writer,
+) EncodeError!void {
+ defer page.assertIntegrity();
+ for (0..page.size.rows) |y| {
+ const row = page.getRow(y);
+ const cells = page.getCells(row);
+
+ // Trailing default cells decode implicitly: wide/spacer pairs and
+ // hyperlinked or styled cells are always nonzero, so eliding the
+ // zero suffix never drops encoded state. The scan also accumulates
+ // the OR of the row's cell words to select its encoded cell width.
+ const count: usize, const word_or: u64 = scanRow(cells);
+
+ // Validate the wide state of every encoded cell so we don't encode
+ // corrupt data. The width bits of the OR word witness whether any
+ // encoded cell is non-narrow at all; rows without them, the common
+ // case, satisfy every pair rule vacuously. Trailing default cells
+ // are narrow, so checking the encoded prefix against the full row
+ // width covers every pair.
+ const wide_mask: u64 = comptime @bitCast(Cell{ .width = 3 });
+ if (word_or & wide_mask != 0) {
+ for (cells[0..count], 0..) |*cell, x| switch (cell.wide) {
+ .narrow => {},
+ .wide => if (x + 1 == cells.len or
+ cells[x + 1].wide != .spacer_tail)
+ {
+ return error.InvalidWideCell;
+ },
+ .spacer_tail => if (x == 0 or
+ cells[x - 1].wide != .wide)
+ {
+ return error.InvalidWideCell;
+ },
+ .spacer_head => if (x + 1 != cells.len or !row.wrap) {
+ return error.InvalidWideCell;
+ },
+ };
+ }
+
+ // Canonical rows use the smallest admissible width.
+ const cell_width: Cell.EncodedWidth = .select(word_or);
+
+ const row_header: Row = .{
+ .wrap = row.wrap,
+ .wrap_continuation = row.wrap_continuation,
+ .semantic_prompt = @intFromEnum(row.semantic_prompt),
+ .cell_width = cell_width,
+ };
+
+ // The bulk codec emits the row header and its encoded cells directly
+ // into the destination's spare buffer capacity, so a row costs no
+ // writer call at all instead of one for the header and one per cell
+ // chunk.
+ if (comptime bulk_codec) emit: {
+ const words: [*]const u64 = @ptrCast(cells.ptr);
+ switch (cell_width) {
+ inline .one, .two, .four => |width| {
+ const size = comptime width.size();
+ const needed = 3 + count * size;
+ if (writer.unusedCapacityLen() < needed) break :emit;
+ const out = writer.unusedCapacitySlice()[0..needed];
+ out[0] = @bitCast(row_header);
+ std.mem.writeInt(u16, out[1..3], @intCast(count), .little);
+ encodeNarrowInto(width, words, count, out[3..]);
+ writer.advance(needed);
+ continue;
+ },
+ .eight => {
+ // Hyperlink IDs live in a native side table, but we
+ // embed them in ours, so if we have any hyperlinks we
+ // need to fall back to the loop below.
+ const witness: Cell = @bitCast(word_or);
+ if (!witness.hyperlink and witness.hyperlink_id == 0) {
+ const needed = 3 + count * 8;
+ if (writer.unusedCapacityLen() < needed) break :emit;
+ const out = writer.unusedCapacitySlice()[0..needed];
+ out[0] = @bitCast(row_header);
+ std.mem.writeInt(
+ u16,
+ out[1..3],
+ @intCast(count),
+ .little,
+ );
+ @memcpy(
+ out[3..],
+ std.mem.sliceAsBytes(cells[0..count]),
+ );
+ writer.advance(needed);
+ continue;
+ }
+ },
+ }
+ }
+
+ // Row header: flags then the encoded cell count.
+ {
+ var header_bytes: [3]u8 = undefined;
+ header_bytes[0] = @bitCast(row_header);
+ std.mem.writeInt(u16, header_bytes[1..3], @intCast(count), .little);
+ try writer.writeAll(&header_bytes);
+ }
+
+ switch (cell_width) {
+ inline .one, .two, .four => |width| try encodeNarrowCells(
+ width,
+ cells[0..count],
+ writer,
+ ),
+
+ .eight => {
+ // Hyperlink IDs live in a native side table, but we embed
+ // them in ours, so if we have any hyperlinks we need
+ // to fallback to the loop below.
+ if (comptime bulk_codec) {
+ const witness: Cell = @bitCast(word_or);
+ if (!witness.hyperlink and witness.hyperlink_id == 0) {
+ try writer.writeAll(std.mem.sliceAsBytes(cells[0..count]));
+ continue;
+ }
+ }
+
+ for (cells[0..count]) |*cell| {
+ const link_id: TerminalHyperlinkId = if (cell.hyperlink)
+ page.lookupHyperlink(cell) orelse unreachable
+ else
+ 0;
+ try io.writeInt(
+ writer,
+ u64,
+ cellBits(cell.*, link_id),
+ );
+ }
+ },
+ }
+ }
+
+ try encodeGraphemes(page, writer);
+}
+
+/// The encoded cell count (through the last nonzero cell) and the bitwise
+/// OR of every encoded cell word for one row.
+fn scanRow(cells: []const TerminalCell) struct { usize, u64 } {
+ if (comptime bulk_codec) {
+ const words: [*]const u64 = @ptrCast(cells.ptr);
+ const V = @Vector(4, u64);
+ const VPtr = *align(@alignOf(u64)) const V;
+
+ // Count the zero cells using vectorized instructions
+ var count = cells.len;
+ while (count >= 4) {
+ const tail = @as(VPtr, @ptrCast(words + count - 4)).*;
+ if (@reduce(.Or, tail) != 0) break;
+ count -= 4;
+ }
+ while (count > 0 and words[count - 1] == 0) count -= 1;
+
+ // Accumulate the OR of the classifaction vectorized, with the
+ // scalar tail continuing from where the vector loop stopped.
+ const word_or: u64 = word_or: {
+ var acc: V = @splat(0);
+ var i: usize = 0;
+ while (i + 4 <= count) : (i += 4) {
+ acc |= @as(VPtr, @ptrCast(words + i)).*;
+ }
+ var word_or: u64 = @reduce(.Or, acc);
+ while (i < count) : (i += 1) word_or |= words[i];
+ break :word_or word_or;
+ };
+
+ return .{ count, word_or };
+ }
+
+ // Scalar path, count backwards
+ var count: usize = cells.len;
+ while (count > 0 and cells[count - 1].isZero()) count -= 1;
+ var word_or: u64 = 0;
+ for (cells[0..count]) |*cell| word_or |= classifyWord(cell);
+ return .{ count, word_or };
+}
+
+/// The word used to select a row's encoded cell width. This is the cell's
+/// wire word with the hyperlink flag reflecting the native cell, so linked
+/// cells and nonzero native padding disqualify every narrow width.
+inline fn classifyWord(cell: *const TerminalCell) u64 {
+ if (comptime native_matches_wire) return @bitCast(cell.*);
+
+ var wire: Cell = @bitCast(cellBits(cell.*, 0));
+ wire.hyperlink = cell.hyperlink;
+ return @bitCast(wire);
+}
+
+/// Write one row's cells truncated to the given encoded width.
+///
+/// Every admitted cell round-trips exactly because the row's width
+/// selection proved every cell word survives `truncate` then `extend`.
+fn encodeNarrowCells(
+ comptime width: Cell.EncodedWidth,
+ cells: []const TerminalCell,
+ writer: *std.Io.Writer,
+) std.Io.Writer.Error!void {
+ const size = comptime width.size();
+ var chunk: [1024]u8 = undefined;
+ var i: usize = 0;
+ while (i < cells.len) {
+ const n = @min(cells.len - i, chunk.len / size);
+ for (cells[i..][0..n], 0..) |*cell, j| {
+ std.mem.writeInt(
+ width.Int(),
+ chunk[j * size ..][0..size],
+ width.truncate(classifyWord(cell)),
+ .little,
+ );
+ }
+ try writer.writeAll(chunk[0 .. n * size]);
+ i += n;
+ }
+}
+
+/// Truncate one row's cell words into `out` at the given encoded width.
+fn encodeNarrowInto(
+ comptime width: Cell.EncodedWidth,
+ words: [*]const u64,
+ count: usize,
+ out: []u8,
+) void {
+ comptime assert(bulk_codec);
+ const size = comptime width.size();
+ const V = @Vector(2, u64);
+ const shift: V = @splat(comptime switch (width) {
+ .one, .two => @bitOffsetOf(Cell, "content"),
+ .four => 0,
+ .eight => unreachable,
+ });
+ const mask: @Vector(size * 4, i32) = comptime mask: {
+ var mask: [size * 4]i32 = undefined;
+ for (0..2) |lane| {
+ for (0..size) |byte| {
+ mask[lane * size + byte] = @intCast(lane * 8 + byte);
+ mask[(lane + 2) * size + byte] =
+ ~@as(i32, @intCast(lane * 8 + byte));
+ }
+ }
+ break :mask mask;
+ };
+
+ var j: usize = 0;
+ while (j + 4 <= count) : (j += 4) encodeNarrowStep(
+ width,
+ words,
+ j,
+ out,
+ shift,
+ mask,
+ );
+ if (j < count) {
+ if (count >= 4) {
+ encodeNarrowStep(width, words, count - 4, out, shift, mask);
+ } else {
+ while (j < count) : (j += 1) {
+ std.mem.writeInt(
+ width.Int(),
+ out[j * size ..][0..size],
+ width.truncate(words[j]),
+ .little,
+ );
+ }
+ }
+ }
+}
+
+/// Emit four truncated cell words starting at cell index `j`.
+inline fn encodeNarrowStep(
+ comptime width: Cell.EncodedWidth,
+ words: [*]const u64,
+ j: usize,
+ out: []u8,
+ shift: @Vector(2, u64),
+ mask: @Vector(width.size() * 4, i32),
+) void {
+ const size = comptime width.size();
+ const VPtr = *align(@alignOf(u64)) const @Vector(2, u64);
+ const lo: @Vector(16, u8) = @bitCast(@as(VPtr, @ptrCast(words + j)).* >> shift);
+ const hi: @Vector(16, u8) = @bitCast(@as(VPtr, @ptrCast(words + j + 2)).* >> shift);
+ @as(
+ *align(1) @Vector(size * 4, u8),
+ @ptrCast(out[j * size ..].ptr),
+ ).* = @shuffle(u8, lo, hi, mask);
+}
+
+/// Encode the grapheme suffix section for every kind 1 cell in the grid.
+fn encodeGraphemes(
+ page: *const TerminalPage,
+ writer: *std.Io.Writer,
+) EncodeError!void {
+ // Every grapheme cell owns exactly one entry in the page's grapheme
+ // map, so the section header comes straight from the page without a
+ // counting pass over the grid. Rows without the native grapheme hint
+ // contain no grapheme cells in any intact page.
+ const entries = page.graphemeCount();
+ try io.writeInt(writer, u32, @intCast(entries));
+ if (entries == 0) return;
+
+ // Entries are batched into a local buffer so hot pages perform one
+ // writer call per flush instead of several per entry.
+ var buffer: [4096]u8 = undefined;
+ var used: usize = 0;
+ var emitted: usize = 0;
+ for (0..page.size.rows) |y| {
+ const row = page.getRow(y);
+ if (!row.grapheme) continue;
+ for (page.getCells(row), 0..) |*cell, x| {
+ if (!cell.hasGrapheme()) continue;
+ const cps = page.lookupGrapheme(cell) orelse unreachable;
+ if (cps.len > std.math.maxInt(u16)) return error.TooManyGraphemes;
+ emitted += 1;
+
+ const needed = 6 + cps.len * 4;
+ if (buffer.len - used < needed) {
+ try writer.writeAll(buffer[0..used]);
+ used = 0;
+ }
+ if (needed > buffer.len) {
+ // An entry larger than the whole buffer streams directly.
+ try io.writeInt(writer, u16, @intCast(y));
+ try io.writeInt(writer, u16, @intCast(x));
+ try io.writeInt(writer, u16, @intCast(cps.len));
+ for (cps) |cp| try io.writeInt(writer, u32, cp);
+ continue;
+ }
+
+ std.mem.writeInt(u16, buffer[used..][0..2], @intCast(y), .little);
+ std.mem.writeInt(u16, buffer[used + 2 ..][0..2], @intCast(x), .little);
+ std.mem.writeInt(u16, buffer[used + 4 ..][0..2], @intCast(cps.len), .little);
+ used += 6;
+ for (cps) |cp| {
+ std.mem.writeInt(u32, buffer[used..][0..4], cp, .little);
+ used += 4;
+ }
+ }
+ }
+ try writer.writeAll(buffer[0..used]);
+
+ // The declared count is trusted by decoders for framing, so the grid
+ // must have produced exactly that many entries.
+ assert(emitted == entries);
+}
+
+pub const DecodeError = std.Io.Reader.Error || error{
+ /// A row declares more encoded cells than the grid has columns.
+ InvalidRowCellCount,
+};
+
+/// Maps encoded style table IDs to page-assigned style IDs.
+pub const StyleRemap = Remap(TerminalStyleId);
+
+/// Maps encoded hyperlink table IDs to page-assigned hyperlink IDs.
+pub const HyperlinkRemap = Remap(TerminalHyperlinkId);
+
+/// Decode every row, cell, and grapheme suffix directly into an
+/// initialized, empty page.
+///
+/// The grid does not encode dimensions, so `page` must already have the
+/// exact row and column count expected by the containing record. Capacity
+/// hints are advisory. Graphemes and cell hyperlink references that do not
+/// fit are discarded without affecting the rest of the grid.
+///
+/// Style and hyperlink table entries must be inserted into `page` before
+/// calling this function, with their encoded and page-assigned IDs recorded
+/// in `style_remap` and `hyperlink_remap`. ID zero always means the default
+/// style or no hyperlink. A nonzero ID missing from its remap is also
+/// treated as zero so unknown table references do not prevent the rest of
+/// the grid from decoding.
+///
+/// Invalid semantic data is normalized into a degraded form while
+/// preserving the declared byte boundaries. Unknown semantic values use
+/// their neutral variants, invalid Unicode becomes U+FFFD, invalid optional
+/// data is ignored, and malformed wide-cell relationships become narrow
+/// cells. The encoded cell count is the only structural field.
+pub fn decode(
+ page: *TerminalPage,
+ reader: *std.Io.Reader,
+ style_remap: *const StyleRemap,
+ hyperlink_remap: *const HyperlinkRemap,
+) DecodeError!void {
+ for (0..page.size.rows) |y| {
+ // Read the row header and cell count.
+ const row_header: Row, const count: u16 = header: {
+ // The staged payload path has every header buffered.
+ var row_header_bytes: [3]u8 = undefined;
+ if (reader.bufferedLen() >= 3) {
+ row_header_bytes = reader.buffered()[0..3].*;
+ reader.toss(3);
+ } else {
+ try reader.readSliceAll(&row_header_bytes);
+ }
+
+ // Every bit pattern is a valid header: booleans and the exhaustive
+ // width enum decode directly, and the raw semantic value gets a
+ // default below. Reserved bits do not change the known fields.
+ const row_header: Row = @bitCast(row_header_bytes[0]);
+ const count = std.mem.readInt(u16, row_header_bytes[1..3], .little);
+ break :header .{ row_header, count };
+ };
+
+ // A fully default row needs no work at all: decoded pages start
+ // zeroed, which is exactly the default row and cell state.
+ if (@as(u8, @bitCast(row_header)) == 0 and count == 0) continue;
+
+ // Update the row fields through one load and store instead of a
+ // read-modify-write per packed field.
+ const row = page.getRow(y);
+ var row_value = row.*;
+ row_value.wrap = row_header.wrap;
+ row_value.wrap_continuation = row_header.wrap_continuation;
+ row_value.semantic_prompt = std.enums.fromInt(
+ TerminalRow.SemanticPrompt,
+ row_header.semantic_prompt,
+ ) orelse .none;
+ row.* = row_value;
+
+ const cells = page.getCells(row);
+ if (count > cells.len) return error.InvalidRowCellCount;
+ if (count == 0) continue;
+
+ // The encoded cell width is framing: it determines exactly how many
+ // bytes this row occupies.
+ switch (row_header.cell_width) {
+ inline .one, .two => |width| try decodeNarrowCells(
+ width,
+ reader,
+ cells[0..count],
+ ),
+ .four => _ = try decodeWordCells(
+ .four,
+ page,
+ row,
+ cells,
+ count,
+ reader,
+ style_remap,
+ hyperlink_remap,
+ ),
+ .eight => {
+ if (comptime bulk_codec) {
+ // Read the encoded words directly into page storage,
+ // then normalize them in place. The raw words are only
+ // ever touched as integers until normalization makes
+ // them valid cells.
+ const words: [*]u64 = @ptrCast(cells.ptr);
+ try reader.readSliceAll(
+ std.mem.sliceAsBytes(cells[0..count]),
+ );
+ var row_or: u64 = 0;
+ for (0..count) |x| {
+ row_or |= words[x];
+ applyCell(
+ page,
+ row,
+ cells,
+ x,
+ words[x],
+ style_remap,
+ hyperlink_remap,
+ );
+ }
+ normalizeWideRow(.eight, row, cells, count, row_or);
+ } else {
+ _ = try decodeWordCells(
+ .eight,
+ page,
+ row,
+ cells,
+ count,
+ reader,
+ style_remap,
+ hyperlink_remap,
+ );
+ }
+
+ // The implicit cell after a short row is narrow, which
+ // resolves a trailing wide marker exactly like an explicit
+ // narrow neighbor. Only full-width rows can encode wide
+ // markers.
+ if (count < cells.len and cells[count - 1].wide == .wide) {
+ cells[count - 1].wide = .narrow;
+ }
+ },
+ }
+ }
+
+ try decodeGraphemes(page, reader);
+}
+
+/// Decode one row of width-one or width-two cells.
+///
+/// These widths admit only bare codepoints, so cells store directly with at
+/// most Unicode scalar validation: no styles, hyperlinks, wide pairs, or
+/// row hints are reachable and no normalization state is needed.
+fn decodeNarrowCells(
+ comptime width: Cell.EncodedWidth,
+ reader: *std.Io.Reader,
+ cells: []TerminalCell,
+) DecodeError!void {
+ const size = comptime width.size();
+
+ // The staged payload path has the complete row buffered, making this
+ // one bounds check followed by a vectorizable widening loop.
+ const total = cells.len * size;
+ if (reader.bufferedLen() >= total) {
+ widenCells(width, reader.buffered()[0..total], cells);
+ reader.toss(total);
+ return;
+ }
+
+ // Streaming sources fall back to bounded chunks.
+ var chunk: [1024]u8 = undefined;
+ var i: usize = 0;
+ while (i < cells.len) {
+ const n = @min(cells.len - i, chunk.len / size);
+ try reader.readSliceAll(chunk[0 .. n * size]);
+ widenCells(width, chunk[0 .. n * size], cells[i..][0..n]);
+ i += n;
+ }
+}
+
+/// Store codepoint-valued encoded cells of the given width.
+fn widenCells(
+ comptime width: Cell.EncodedWidth,
+ bytes: []const u8,
+ cells: []TerminalCell,
+) void {
+ const size = comptime width.size();
+
+ // With the bulk codec layout this is a pure widening store: sixteen
+ // transported bytes per step, shuffling each pair of encoded values
+ // into u64 lane position against a zero vector and shifting them into
+ // the content field. Zig 0.16 disables loop auto-vectorization, so the
+ // scalar loop would issue one widening store per cell.
+ if (comptime bulk_codec) {
+ const words: [*]u64 = @ptrCast(cells.ptr);
+ const step = 16 / size;
+ var i: usize = 0;
+ while (i + step <= cells.len) : (i += step) {
+ widenStep(width, bytes, words, i);
+ }
+ if (i < cells.len) {
+ if (cells.len >= step) {
+ // Reprocess the final full window with overlapping stores,
+ // which rewrite the same widened values.
+ widenStep(width, bytes, words, cells.len - step);
+ } else {
+ while (i < cells.len) : (i += 1) {
+ words[i] = width.extend(widenValue(width, bytes[i * size ..]));
+ }
+ }
+ }
+ return;
+ }
+
+ // When the native cell matches the wire word, this is a pure widening
+ // loop over integers.
+ if (comptime native_matches_wire) {
+ const words: [*]u64 = @ptrCast(cells.ptr);
+ for (0..cells.len) |i| {
+ words[i] = width.extend(widenValue(width, bytes[i * size ..]));
+ }
+ return;
+ }
+
+ for (cells, 0..) |*cell, i| {
+ storeCell(cell, width.extend(widenValue(width, bytes[i * size ..])));
+ }
+}
+
+/// Widen sixteen transported bytes into their cell words at cell index `i`:
+/// shuffle each pair of encoded values into u64 lane position against a
+/// zero vector, then shift the value into the content field. Width two
+/// first degrades surrogate lanes to U+FFFD, matching `widenValue`.
+inline fn widenStep(
+ comptime width: Cell.EncodedWidth,
+ bytes: []const u8,
+ words: [*]u64,
+ i: usize,
+) void {
+ const size = comptime width.size();
+ const step = 16 / size;
+
+ var in: @Vector(16, u8) = @as(
+ *align(1) const @Vector(16, u8),
+ @ptrCast(bytes[i * size ..].ptr),
+ ).*;
+
+ // Width two admits surrogates, which degrade to U+FFFD exactly
+ // like `widenValue`. Width one cannot encode an invalid scalar.
+ if (comptime width == .two) {
+ const values: @Vector(8, u16) = @bitCast(in);
+ const invalid = (values & @as(@Vector(8, u16), @splat(0xF800))) ==
+ @as(@Vector(8, u16), @splat(0xD800));
+ in = @bitCast(@select(
+ u16,
+ invalid,
+ @as(@Vector(8, u16), @splat(0xFFFD)),
+ values,
+ ));
+ }
+
+ const zero: @Vector(16, u8) = @splat(0);
+ inline for (0..step / 2) |pair| {
+ const mask: @Vector(16, i32) = comptime mask: {
+ var mask: [16]i32 = @splat(~@as(i32, 0));
+ for (0..size) |byte| {
+ mask[byte] = @intCast((2 * pair) * size + byte);
+ mask[8 + byte] = @intCast((2 * pair + 1) * size + byte);
+ }
+ break :mask mask;
+ };
+ const lanes: @Vector(2, u64) = @bitCast(
+ @shuffle(u8, in, zero, mask),
+ );
+ @as(
+ *align(@alignOf(u64)) @Vector(2, u64),
+ @ptrCast(words + i + 2 * pair),
+ ).* = lanes << @splat(@bitOffsetOf(Cell, "content"));
+ }
+}
+
+/// Read and validate one narrow transported value.
+inline fn widenValue(
+ comptime width: Cell.EncodedWidth,
+ bytes: []const u8,
+) width.Int() {
+ const size = comptime width.size();
+ const value = std.mem.readInt(width.Int(), bytes[0..size], .little);
+
+ // Width one cannot encode an invalid scalar. Width two admits
+ // surrogates, which degrade exactly like their full-width form.
+ if (comptime width != .one) {
+ if (!validScalar(value)) return 0xFFFD;
+ }
+ return value;
+}
+
+/// Decode one row of width-four or fallback full-width cells through the
+/// complete per-cell normalization path.
+///
+/// Returns the bitwise OR of every decoded wire word so callers can gate
+/// the trailing wide-pair resolution pass without a second scan.
+fn decodeWordCells(
+ comptime width: Cell.EncodedWidth,
+ page: *TerminalPage,
+ row: *TerminalRow,
+ cells: []TerminalCell,
+ count: usize,
+ reader: *std.Io.Reader,
+ style_remap: *const StyleRemap,
+ hyperlink_remap: *const HyperlinkRemap,
+) DecodeError!u64 {
+ const size = comptime width.size();
+ var row_or: u64 = 0;
+
+ // The staged payload path has the complete row buffered.
+ const total = count * size;
+ if (reader.bufferedLen() >= total) {
+ const bytes = reader.buffered()[0..total];
+ for (0..count) |x| {
+ const bits = width.extend(std.mem.readInt(
+ width.Int(),
+ bytes[x * size ..][0..size],
+ .little,
+ ));
+ row_or |= bits;
+ applyCell(
+ page,
+ row,
+ cells,
+ x,
+ bits,
+ style_remap,
+ hyperlink_remap,
+ );
+ }
+ reader.toss(total);
+ normalizeWideRow(width, row, cells, count, row_or);
+ return row_or;
+ }
+
+ // Streaming sources fall back to per-cell reads.
+ for (0..count) |x| {
+ const bits = width.extend(try io.readInt(reader, width.Int()));
+ row_or |= bits;
+ applyCell(
+ page,
+ row,
+ cells,
+ x,
+ bits,
+ style_remap,
+ hyperlink_remap,
+ );
+ }
+ normalizeWideRow(width, row, cells, count, row_or);
+ return row_or;
+}
+
+/// Resolve wide-pair relationships for one decoded row.
+///
+/// Cell decoding stores every cell unresolved, so this pass applies
+/// `normalizeWide` in order, which is equivalent to interleaving it with
+/// the stores. Rows whose word OR carries no wide bits are already
+/// normalized: every cell is narrow. Width four and narrower transports
+/// cannot encode wide bits at all, so those rows skip the check entirely.
+inline fn normalizeWideRow(
+ comptime width: Cell.EncodedWidth,
+ row: *const TerminalRow,
+ cells: []TerminalCell,
+ count: usize,
+ row_or: u64,
+) void {
+ if (comptime width != .eight) return;
+ const wide_mask: u64 = comptime @bitCast(Cell{ .width = 3 });
+ if (row_or & wide_mask == 0) return;
+ for (0..count) |x| normalizeWide(row, cells, x);
+}
+
+/// Whether the value is a valid Unicode scalar value.
+inline fn validScalar(cp: u32) bool {
+ return cp <= 0x10FFFF and (cp < 0xD800 or cp > 0xDFFF);
+}
+
+/// Normalize one encoded cell word and store it at `cells[x]`.
+///
+/// This owns every per-cell decode rule except grapheme suffixes and
+/// wide-pair resolution: content validation, reserved-value degradation,
+/// and style and hyperlink remapping with reference counting. Callers run
+/// `normalizeWideRow` over the stored row afterward.
+fn applyCell(
+ page: *TerminalPage,
+ row: *TerminalRow,
+ cells: []TerminalCell,
+ x: usize,
+ bits_wire: u64,
+ style_remap: *const StyleRemap,
+ hyperlink_remap: *const HyperlinkRemap,
+) void {
+ const cell = &cells[x];
+
+ // The default cell is the common case and needs no normalization,
+ // reference counting, or table lookups.
+ if (bits_wire == 0) {
+ storeCell(cell, 0);
+ return;
+ }
+
+ // Any word is a valid wire cell because its fields are raw integers,
+ // so all normalization below is plain field access.
+ var wire: Cell = @bitCast(bits_wire);
+
+ // Hyperlink linkage is derived from the remapped ID below. The stored
+ // native cell starts unlinked either way.
+ const link_encoded = wire.hyperlink_id;
+ wire.hyperlink_id = 0;
+ wire.hyperlink = false;
+
+ switch (@as(Cell.Kind, @enumFromInt(wire.kind))) {
+ // Kind 1 differs from 0 only by declaring a grapheme suffix section
+ // entry, which reattaches through the native grapheme APIs later.
+ .codepoint, .codepoint_grapheme => {
+ wire.kind = @intFromEnum(Cell.Kind.codepoint);
+ if (!validScalar(wire.content)) wire.content = 0xFFFD;
+
+ // Kitty image and placement state is not part of this snapshot
+ // version, but the placeholder is still a valid Unicode scalar.
+ // Preserve it and derive the native row hint so later row
+ // operations remain correct.
+ if (wire.content == kitty_virtual_placeholder) {
+ row.kitty_virtual_placeholder = true;
+ }
+ },
+
+ // Only the palette index is meaningful; the remaining content bits
+ // are reserved and must not obscure it.
+ .bg_color_palette => wire.content = @as(u8, @truncate(wire.content)),
+
+ .bg_color_rgb => {},
+ }
+
+ // Reserved semantic content degrades to plain output.
+ wire.semantic_content = @intFromEnum(std.enums.fromInt(
+ TerminalCell.SemanticContent,
+ wire.semantic_content,
+ ) orelse .output);
+
+ // IDs belong to the encoded page. Translate them to IDs assigned by the
+ // destination page before storing them on cells. The table owns one
+ // reference and each decoded cell owns one additional reference.
+ if (wire.style_id != 0) {
+ wire.style_id = style_remap.get(wire.style_id);
+ if (wire.style_id != 0) {
+ page.styles.use(page.memory, wire.style_id);
+ row.styled = true;
+ }
+ }
+
+ storeCell(cell, @bitCast(wire));
+
+ if (link_encoded != 0) link: {
+ const link_native = hyperlink_remap.get(link_encoded);
+ if (link_native == 0) break :link;
+
+ // setHyperlink records the cell mapping but intentionally does not
+ // increment the set's reference count. If its map is full, undo our
+ // reference and leave this cell unlinked.
+ page.hyperlink_set.use(page.memory, link_native);
+ page.setHyperlink(row, cell, link_native) catch {
+ page.hyperlink_set.release(page.memory, link_native);
+ };
+ }
+}
+
+/// Resolve wide-pair relationships for the cell at `x` against its already
+/// normalized predecessors.
+fn normalizeWide(row: *const TerminalRow, cells: []TerminalCell, x: usize) void {
+ // A following cell resolves whether the previous wide marker owns a
+ // tail. Normalize the current marker immediately when possible,
+ // including a wide marker at the row end.
+ if (x > 0 and
+ cells[x - 1].wide == .wide and
+ cells[x].wide != .spacer_tail)
+ {
+ cells[x - 1].wide = .narrow;
+ }
+ switch (cells[x].wide) {
+ .narrow => {},
+
+ // A non-final wide marker remains pending until the next cell.
+ .wide => if (x + 1 == cells.len) {
+ cells[x].wide = .narrow;
+ },
+
+ .spacer_tail => if (x == 0 or
+ cells[x - 1].wide != .wide)
+ {
+ cells[x].wide = .narrow;
+ },
+
+ .spacer_head => if (x + 1 != cells.len or !row.wrap) {
+ cells[x].wide = .narrow;
+ },
+ }
+}
+
+/// Decode the grapheme suffix section into already decoded cells.
+fn decodeGraphemes(
+ page: *TerminalPage,
+ reader: *std.Io.Reader,
+) DecodeError!void {
+ const entries = try io.readInt(reader, u32);
+ for (0..entries) |_| {
+ // The staged and borrowed payload paths have every header buffered.
+ const y: u16, const x: u16, const cp_count: u16 = header: {
+ if (reader.bufferedLen() >= 6) {
+ const bytes = reader.buffered()[0..6];
+ defer reader.toss(6);
+ break :header .{
+ std.mem.readInt(u16, bytes[0..2], .little),
+ std.mem.readInt(u16, bytes[2..4], .little),
+ std.mem.readInt(u16, bytes[4..6], .little),
+ };
+ }
+ break :header .{
+ try io.readInt(reader, u16),
+ try io.readInt(reader, u16),
+ try io.readInt(reader, u16),
+ };
+ };
+
+ // Resolve the target cell. Entries whose target cannot carry a
+ // suffix are optional detail: their codepoints are consumed to
+ // preserve framing and then dropped.
+ const target: ?struct {
+ row: *TerminalRow,
+ cell: *TerminalCell,
+ } = target: {
+ if (y >= page.size.rows or x >= page.size.cols) {
+ break :target null;
+ }
+ const row = page.getRow(y);
+ const cell = &page.getCells(row)[x];
+
+ // Cell decoding stores every kind 1 cell as a plain codepoint,
+ // so this also gives duplicate entries first-wins semantics.
+ if (cell.content_tag != .codepoint) break :target null;
+ if (cell.content.codepoint.data == 0) break :target null;
+ break :target .{ .row = row, .cell = cell };
+ };
+
+ // Always consume every declared codepoint. Invalid scalars and NUL
+ // are not meaningful grapheme suffix components and are ignored. A
+ // dropped entry's codepoints are discarded in bulk.
+ const resolved = target orelse {
+ try reader.discardAll(@as(usize, cp_count) * 4);
+ continue;
+ };
+
+ var accept = true;
+ var index: usize = 0;
+ while (index < cp_count) {
+ const buffered = reader.buffered();
+ if (buffered.len >= 4) {
+ const n = @min(cp_count - index, buffered.len / 4);
+ for (0..n) |i| applyGraphemeSuffix(
+ page,
+ resolved.row,
+ resolved.cell,
+ &accept,
+ std.mem.readInt(u32, buffered[i * 4 ..][0..4], .little),
+ );
+ reader.toss(n * 4);
+ index += n;
+ } else {
+ applyGraphemeSuffix(
+ page,
+ resolved.row,
+ resolved.cell,
+ &accept,
+ try io.readInt(reader, u32),
+ );
+ index += 1;
+ }
+ }
+ }
+}
+
+/// Attach one decoded suffix codepoint to its resolved target cell.
+///
+/// If native capacity is exhausted, any prefix already attached is removed
+/// so the cell never exposes a truncated cluster, and `accept` latches
+/// false so the entry's remaining codepoints are consumed but dropped.
+fn applyGraphemeSuffix(
+ page: *TerminalPage,
+ row: *TerminalRow,
+ cell: *TerminalCell,
+ accept: *bool,
+ cp: u32,
+) void {
+ if (!accept.*) return;
+ if (cp == 0 or !validScalar(cp)) return;
+
+ page.appendGrapheme(row, cell, @intCast(cp)) catch {
+ if (cell.hasGrapheme()) {
+ page.clearGrapheme(cell);
+ page.updateRowGraphemeFlag(row);
+ }
+ accept.* = false;
+ };
+}
+
+/// The encoded word for one native cell and its hyperlink ID.
+fn cellBits(cell: TerminalCell, link_id: TerminalHyperlinkId) u64 {
+ if (comptime native_matches_wire) {
+ var wire: Cell = @bitCast(cell);
+ wire.hyperlink = link_id != 0;
+ wire.hyperlink_id = link_id;
+ return @bitCast(wire);
+ }
+
+ const wire: Cell = .{
+ .kind = @intFromEnum(cell.content_tag),
+ .content = switch (cell.content_tag) {
+ .codepoint,
+ .codepoint_grapheme,
+ => cell.content.codepoint.data,
+ .bg_color_palette => cell.content.color_palette.data,
+ .bg_color_rgb => @as(u24, cell.content.color_rgb.r) |
+ (@as(u24, cell.content.color_rgb.g) << 8) |
+ (@as(u24, cell.content.color_rgb.b) << 16),
+ },
+ .style_id = cell.style_id,
+ .width = switch (cell.wide) {
+ .narrow => 0,
+ .wide => 1,
+ .spacer_tail => 2,
+ .spacer_head => 3,
+ },
+ .protected = cell.protected,
+ .hyperlink = link_id != 0,
+ .semantic_content = switch (cell.semantic_content) {
+ .output => 0,
+ .input => 1,
+ .prompt => 2,
+ },
+ .hyperlink_id = link_id,
+ };
+ return @bitCast(wire);
+}
+
+/// Store one normalized, hyperlink-free wire word as a native cell.
+fn storeCell(cell: *TerminalCell, bits: u64) void {
+ if (comptime native_matches_wire) {
+ const words: [*]u64 = @ptrCast(cell);
+ words[0] = bits;
+ return;
+ }
+
+ const wire: Cell = @bitCast(bits);
+ var native: TerminalCell = .init(0);
+ switch (@as(Cell.Kind, @enumFromInt(wire.kind))) {
+ .codepoint, .codepoint_grapheme => native.content = .{
+ .codepoint = .{ .data = @intCast(wire.content) },
+ },
+ .bg_color_palette => {
+ native.content_tag = .bg_color_palette;
+ native.content = .{
+ .color_palette = .{ .data = @truncate(wire.content) },
+ };
+ },
+ .bg_color_rgb => {
+ native.content_tag = .bg_color_rgb;
+ native.content = .{ .color_rgb = .{
+ .r = @truncate(wire.content),
+ .g = @truncate(wire.content >> 8),
+ .b = @truncate(wire.content >> 16),
+ } };
+ },
+ }
+ native.style_id = wire.style_id;
+ native.wide = @enumFromInt(wire.width);
+ native.protected = wire.protected;
+ native.semantic_content = @enumFromInt(wire.semantic_content);
+ cell.* = native;
+}
+
+/// Maps encoded table IDs to IDs assigned by the destination page.
+///
+/// Build this by inserting each decoded table entry into the page, then
+/// recording the encoded ID and the ID returned by the page's set. ID zero
+/// is implicit and does not need an entry. Lookup must be cheap because the
+/// grid decoder consults it for every styled or linked cell, so this is a
+/// direct-indexed table rather than a hash map.
+fn Remap(comptime Id: type) type {
+ return struct {
+ const Self = @This();
+
+ /// One slot for every possible encoded ID.
+ pub const capacity = std.math.maxInt(Id) + 1;
+
+ /// Indexed by encoded ID; zero means unmapped or default.
+ entries: []Id,
+
+ /// Tracks IDs that received an entry, including ones mapped to the
+ /// default, so callers can give duplicate table entries first-wins
+ /// semantics.
+ seen: std.DynamicBitSetUnmanaged,
+
+ /// A remap with no entries at all: every lookup is unmapped. Use
+ /// this instead of `init` when the encoded table is empty so pages
+ /// without styles or hyperlinks allocate nothing.
+ pub const empty: Self = .{ .entries = &.{}, .seen = .{} };
+
+ pub fn init(alloc: Allocator) Allocator.Error!Self {
+ const entries = try alloc.alloc(Id, capacity);
+ errdefer alloc.free(entries);
+ @memset(entries, 0);
+ const seen = try std.DynamicBitSetUnmanaged.initEmpty(
+ alloc,
+ capacity,
+ );
+ return .{ .entries = entries, .seen = seen };
+ }
+
+ pub fn deinit(self: *Self, alloc: Allocator) void {
+ if (self.entries.len != 0) {
+ alloc.free(self.entries);
+ self.seen.deinit(alloc);
+ }
+ self.* = undefined;
+ }
+
+ /// Record one encoded-to-native mapping. Illegal on `empty`.
+ pub fn put(self: *Self, encoded: Id, native: Id) void {
+ assert(!self.seen.isSet(encoded));
+ self.entries[encoded] = native;
+ self.seen.set(encoded);
+ }
+
+ /// Whether the encoded ID already has an entry, even a default
+ /// one. Illegal on `empty`.
+ pub fn contains(self: *const Self, encoded: Id) bool {
+ return self.seen.isSet(encoded);
+ }
+
+ /// The native ID for an encoded ID, or zero when unmapped.
+ pub inline fn get(self: *const Self, encoded: Id) Id {
+ if (self.entries.len == 0) return 0;
+ return self.entries[encoded];
+ }
+ };
+}
+const test_golden_fixture = test_fixture.parse(
+ @embedFile("testdata/grid-v1.hex"),
+);
+
+test "cell wire layout registry" {
+ const testing = std.testing;
+
+ // The wire bit positions are format constants. The shifts and masks
+ // derive from the packed struct, so pin the struct itself to the
+ // documented registry so an edit cannot silently move wire bits.
+ try testing.expectEqual(0, @bitOffsetOf(Cell, "kind"));
+ try testing.expectEqual(2, @bitOffsetOf(Cell, "content"));
+ try testing.expectEqual(26, @bitOffsetOf(Cell, "style_id"));
+ try testing.expectEqual(42, @bitOffsetOf(Cell, "width"));
+ try testing.expectEqual(44, @bitOffsetOf(Cell, "protected"));
+ try testing.expectEqual(45, @bitOffsetOf(Cell, "hyperlink"));
+ try testing.expectEqual(46, @bitOffsetOf(Cell, "semantic_content"));
+ try testing.expectEqual(48, @bitOffsetOf(Cell, "hyperlink_id"));
+
+ // The native cell currently matches the wire registry, which enables
+ // the bulk row codec. If this fails, the native layout diverged: either
+ // restore it or accept the portable codec and update this expectation.
+ try testing.expect(native_matches_wire);
+}
+
+test "encoded cell width transport registry" {
+ const testing = std.testing;
+
+ // Pin the transported value and admission mask of every width against
+ // the documented format: widths one and two carry the bare codepoint,
+ // width four the low word half, width eight the complete word.
+ const word: u64 = @bitCast(Cell{
+ .kind = 1,
+ .content = 0xABCDEF,
+ .style_id = 0x1234,
+ .hyperlink_id = 0x5678,
+ });
+ try testing.expectEqual(@as(u8, 0xEF), Cell.EncodedWidth.one.truncate(word));
+ try testing.expectEqual(@as(u16, 0xCDEF), Cell.EncodedWidth.two.truncate(word));
+ try testing.expectEqual(
+ @as(u32, @truncate(word)),
+ Cell.EncodedWidth.four.truncate(word),
+ );
+ try testing.expectEqual(word, Cell.EncodedWidth.eight.truncate(word));
+
+ try testing.expectEqual(
+ @as(u64, 0x0000_0000_0000_03FC),
+ Cell.EncodedWidth.one.mask(),
+ );
+ try testing.expectEqual(
+ @as(u64, 0x0000_0000_0003_FFFC),
+ Cell.EncodedWidth.two.mask(),
+ );
+ try testing.expectEqual(
+ @as(u64, 0x0000_0000_FFFF_FFFF),
+ Cell.EncodedWidth.four.mask(),
+ );
+ try testing.expectEqual(
+ @as(u64, 0xFFFF_FFFF_FFFF_FFFF),
+ Cell.EncodedWidth.eight.mask(),
+ );
+
+ // Selection returns the smallest admissible width, and every admitted
+ // word round-trips through its transport.
+ const cases = [_]struct { cell: Cell, width: Cell.EncodedWidth }{
+ .{ .cell = .{}, .width = .one },
+ .{ .cell = .{ .content = 0xFF }, .width = .one },
+ .{ .cell = .{ .content = 0x100 }, .width = .two },
+ .{ .cell = .{ .content = 0xFFFF }, .width = .two },
+ .{ .cell = .{ .content = 0x10000 }, .width = .four },
+ .{ .cell = .{ .kind = 2, .content = 7 }, .width = .four },
+ .{ .cell = .{ .content = 'a', .style_id = 63 }, .width = .four },
+ .{ .cell = .{ .content = 'a', .style_id = 64 }, .width = .eight },
+ .{ .cell = .{ .width = 1, .content = 'a' }, .width = .eight },
+ .{ .cell = .{ .protected = true }, .width = .eight },
+ .{ .cell = .{ .semantic_content = 1 }, .width = .eight },
+ .{ .cell = .{ .hyperlink = true, .hyperlink_id = 1 }, .width = .eight },
+ };
+ inline for (cases) |case| {
+ const case_word: u64 = @bitCast(case.cell);
+ try testing.expectEqual(
+ case.width,
+ Cell.EncodedWidth.select(case_word),
+ );
+ try testing.expectEqual(
+ case_word,
+ case.width.extend(case.width.truncate(case_word)),
+ );
+ }
+}
+
+test "grid golden encoding and decoding" {
+ const capacity: terminal_page.Capacity = .{
+ .cols = 3,
+ .rows = 4,
+ .styles = 0,
+ .hyperlink_bytes = 0,
+ .grapheme_bytes = 64,
+ .string_bytes = 0,
+ };
+ var source = try TerminalPage.init(capacity);
+ defer source.deinit();
+
+ // The first row covers semantic metadata, a wide-cell pair, and a
+ // multi-codepoint grapheme.
+ const wide = source.getRowAndCell(0, 0);
+ wide.row.semantic_prompt = .prompt;
+ wide.cell.* = .init('A');
+ wide.cell.wide = .wide;
+ wide.cell.protected = true;
+ wide.cell.semantic_content = .prompt;
+
+ const tail = source.getRowAndCell(1, 0);
+ tail.cell.wide = .spacer_tail;
+ tail.cell.semantic_content = .input;
+
+ const grapheme = source.getRowAndCell(2, 0);
+ grapheme.cell.* = .init('x');
+ try source.setGraphemes(
+ grapheme.row,
+ grapheme.cell,
+ &.{ 0x0301, 0x0302 },
+ );
+
+ // The second row covers both background-color kinds and a wrapped spacer
+ // head with the remaining row semantic value.
+ const palette = source.getRowAndCell(0, 1);
+ palette.cell.content_tag = .bg_color_palette;
+ palette.cell.content = .{ .color_palette = .{ .data = 7 } };
+
+ const rgb = source.getRowAndCell(1, 1);
+ rgb.cell.content_tag = .bg_color_rgb;
+ rgb.cell.content = .{ .color_rgb = .{
+ .r = 0xaa,
+ .g = 0xbb,
+ .b = 0xcc,
+ } };
+ rgb.cell.protected = true;
+
+ const head = source.getRowAndCell(2, 1);
+ head.cell.wide = .spacer_head;
+ head.row.wrap = true;
+ head.row.wrap_continuation = true;
+ head.row.semantic_prompt = .prompt_continuation;
+
+ // The third row is bare ASCII text with an interior blank, which uses
+ // the one-byte encoded cell width.
+ source.getRowAndCell(0, 2).cell.* = .init('h');
+ source.getRowAndCell(2, 2).cell.* = .init('i');
+
+ // The fourth row needs the two-byte width for a codepoint above U+00FF.
+ source.getRowAndCell(0, 3).cell.* = .init(0x0416); // Ж
+ source.getRowAndCell(1, 3).cell.* = .init('!');
+
+ var encoded: [160]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try encode(&source, &writer);
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/grid-v1.hex",
+ "snapshot_fixture-grid-v1.hex",
+ &test_golden_fixture,
+ writer.buffered(),
+ );
+
+ var destination = try TerminalPage.init(capacity);
+ defer destination.deinit();
+ var style_remap = try StyleRemap.init(std.testing.allocator);
+ defer style_remap.deinit(std.testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(std.testing.allocator);
+ defer hyperlink_remap.deinit(std.testing.allocator);
+
+ // Decode the checked-in reference through a one-byte reader buffer.
+ var fixture_reader: std.Io.Reader = .fixed(&test_golden_fixture);
+ var read_buffer: [1]u8 = undefined;
+ var limited = fixture_reader.limited(.unlimited, &read_buffer);
+ try decode(
+ &destination,
+ &limited.interface,
+ &style_remap,
+ &hyperlink_remap,
+ );
+ try destination.verifyIntegrity(std.testing.allocator);
+
+ const decoded_wide = destination.getRowAndCell(0, 0);
+ try std.testing.expectEqual(@as(u21, 'A'), decoded_wide.cell.codepoint());
+ try std.testing.expectEqual(TerminalCell.Wide.wide, decoded_wide.cell.wide);
+ try std.testing.expect(decoded_wide.cell.protected);
+ try std.testing.expectEqual(
+ TerminalCell.SemanticContent.prompt,
+ decoded_wide.cell.semantic_content,
+ );
+ try std.testing.expectEqual(
+ TerminalRow.SemanticPrompt.prompt,
+ decoded_wide.row.semantic_prompt,
+ );
+
+ const decoded_tail = destination.getRowAndCell(1, 0);
+ try std.testing.expectEqual(
+ TerminalCell.Wide.spacer_tail,
+ decoded_tail.cell.wide,
+ );
+ try std.testing.expectEqual(
+ TerminalCell.SemanticContent.input,
+ decoded_tail.cell.semantic_content,
+ );
+
+ const decoded_grapheme = destination.getRowAndCell(2, 0);
+ try std.testing.expectEqualSlices(
+ u21,
+ &.{ 0x0301, 0x0302 },
+ destination.lookupGrapheme(decoded_grapheme.cell).?,
+ );
+
+ const decoded_palette = destination.getRowAndCell(0, 1);
+ try std.testing.expectEqual(
+ TerminalCell.ContentTag.bg_color_palette,
+ decoded_palette.cell.content_tag,
+ );
+ try std.testing.expectEqual(
+ @as(u8, 7),
+ decoded_palette.cell.content.color_palette.data,
+ );
+
+ const decoded_rgb = destination.getRowAndCell(1, 1);
+ try std.testing.expectEqual(
+ TerminalCell.ContentTag.bg_color_rgb,
+ decoded_rgb.cell.content_tag,
+ );
+ try std.testing.expectEqual(
+ TerminalCell.RGB{ .r = 0xaa, .g = 0xbb, .b = 0xcc },
+ decoded_rgb.cell.content.color_rgb,
+ );
+ try std.testing.expect(decoded_rgb.cell.protected);
+
+ const decoded_head = destination.getRowAndCell(2, 1);
+ try std.testing.expectEqual(
+ TerminalCell.Wide.spacer_head,
+ decoded_head.cell.wide,
+ );
+ try std.testing.expect(decoded_head.row.wrap);
+ try std.testing.expect(decoded_head.row.wrap_continuation);
+ try std.testing.expectEqual(
+ TerminalRow.SemanticPrompt.prompt_continuation,
+ decoded_head.row.semantic_prompt,
+ );
+
+ try std.testing.expectEqual(
+ @as(u21, 'h'),
+ destination.getRowAndCell(0, 2).cell.codepoint(),
+ );
+ try std.testing.expect(destination.getRowAndCell(1, 2).cell.isZero());
+ try std.testing.expectEqual(
+ @as(u21, 'i'),
+ destination.getRowAndCell(2, 2).cell.codepoint(),
+ );
+ try std.testing.expectEqual(
+ @as(u21, 0x0416),
+ destination.getRowAndCell(0, 3).cell.codepoint(),
+ );
+ try std.testing.expectEqual(
+ @as(u21, '!'),
+ destination.getRowAndCell(1, 3).cell.codepoint(),
+ );
+
+ // A re-encode proves the decoded native page retains every wire field.
+ var reencoded: [160]u8 = undefined;
+ var rewriter: std.Io.Writer = .fixed(&reencoded);
+ try encode(&destination, &rewriter);
+ try std.testing.expectEqualStrings(
+ &test_golden_fixture,
+ rewriter.buffered(),
+ );
+}
+
+test "grid elides trailing default cells" {
+ const testing = std.testing;
+ var page = try TerminalPage.init(.{ .cols = 80, .rows = 3 });
+ defer page.deinit();
+
+ // Row 0 is fully default. Row 1 has content in columns zero and two.
+ // Row 2 has one protected-only cell at column four.
+ const middle = page.getRowAndCell(2, 1);
+ middle.cell.* = .init('b');
+ page.getRowAndCell(0, 1).cell.* = .init('a');
+ page.getRowAndCell(4, 2).cell.protected = true;
+
+ var encoded: [256]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try encode(&page, &writer);
+
+ // 3 bytes per row header and cells only through the last non-default
+ // cell, followed by an empty grapheme section. The text row uses the
+ // one-byte width while the protected flag forces the full width.
+ try testing.expectEqual(
+ @as(usize, 3 + (3 + 3 * 1) + (3 + 5 * 8) + 4),
+ writer.buffered().len,
+ );
+
+ var destination = try TerminalPage.init(.{ .cols = 80, .rows = 3 });
+ defer destination.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ try decode(&destination, &reader, &style_remap, &hyperlink_remap);
+ try destination.verifyIntegrity(testing.allocator);
+
+ try testing.expectEqual(
+ @as(u21, 'a'),
+ destination.getRowAndCell(0, 1).cell.codepoint(),
+ );
+ try testing.expectEqual(
+ @as(u21, 'b'),
+ destination.getRowAndCell(2, 1).cell.codepoint(),
+ );
+ try testing.expect(destination.getRowAndCell(4, 2).cell.protected);
+ try testing.expect(destination.getRowAndCell(79, 1).cell.isZero());
+}
+
+test "grid rejects a row cell count above the column count" {
+ const testing = std.testing;
+ var page = try TerminalPage.init(.{ .cols = 2, .rows = 1 });
+ defer page.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+
+ var payload: [64]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&payload);
+ try writer.writeByte(@bitCast(Row{}));
+ try io.writeInt(&writer, u16, 3);
+ for (0..3) |_| try io.writeInt(&writer, u64, 0);
+ try io.writeInt(&writer, u32, 0);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ try testing.expectError(
+ error.InvalidRowCellCount,
+ decode(&page, &reader, &style_remap, &hyperlink_remap),
+ );
+}
+
+test "grid normalizes incomplete wide cells" {
+ const testing = std.testing;
+ // One column puts the wide cell at the row end. Two columns put an
+ // ordinary narrow cell after it. Neither case supplies a spacer tail.
+ // Both rely on the implicit narrow cell rule when the tail is elided.
+ for ([_]u16{ 1, 2 }) |columns| {
+ const capacity: terminal_page.Capacity = .{
+ .cols = columns,
+ .rows = 1,
+ };
+
+ // Craft the malformed row directly on the wire. Decoding keeps its
+ // content but makes the incomplete wide cell narrow.
+ var payload: [64]u8 = undefined;
+ var payload_writer: std.Io.Writer = .fixed(&payload);
+ try payload_writer.writeByte(@bitCast(Row{ .cell_width = .eight }));
+ try io.writeInt(&payload_writer, u16, columns);
+ try io.writeInt(&payload_writer, u64, @bitCast(Cell{
+ .width = 1, // wide
+ .content = 'A',
+ }));
+ if (columns > 1) try io.writeInt(&payload_writer, u64, @bitCast(Cell{
+ .content = 'B',
+ }));
+ try io.writeInt(&payload_writer, u32, 0);
+
+ var destination = try TerminalPage.init(capacity);
+ defer destination.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+
+ var payload_reader: std.Io.Reader = .fixed(
+ payload_writer.buffered(),
+ );
+ try decode(
+ &destination,
+ &payload_reader,
+ &style_remap,
+ &hyperlink_remap,
+ );
+ try destination.verifyIntegrity(testing.allocator);
+
+ try testing.expectEqual(
+ @as(u21, 'A'),
+ destination.getRowAndCell(0, 0).cell.codepoint(),
+ );
+ try testing.expectEqual(
+ TerminalCell.Wide.narrow,
+ destination.getRowAndCell(0, 0).cell.wide,
+ );
+ if (columns > 1) {
+ const second = destination.getRowAndCell(1, 0).cell;
+ try testing.expectEqual(@as(u21, 'B'), second.codepoint());
+ try testing.expectEqual(TerminalCell.Wide.narrow, second.wide);
+ }
+ }
+
+ // A wide marker whose spacer tail was elided by a short cell count is
+ // also normalized, and the trailing cells stay default.
+ var page = try TerminalPage.init(.{ .cols = 4, .rows = 1 });
+ defer page.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+
+ var payload: [64]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&payload);
+ try writer.writeByte(@bitCast(Row{ .cell_width = .eight }));
+ try io.writeInt(&writer, u16, 1);
+ try io.writeInt(&writer, u64, @bitCast(Cell{
+ .width = 1, // wide
+ .content = 'W',
+ }));
+ try io.writeInt(&writer, u32, 0);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ try decode(&page, &reader, &style_remap, &hyperlink_remap);
+ try page.verifyIntegrity(testing.allocator);
+ try testing.expectEqual(
+ TerminalCell.Wide.narrow,
+ page.getRowAndCell(0, 0).cell.wide,
+ );
+ try testing.expect(page.getRowAndCell(1, 0).cell.isZero());
+}
+
+test "grid normalizes reserved cell values" {
+ const testing = std.testing;
+ var page = try TerminalPage.init(.{ .cols = 3, .rows = 1 });
+ defer page.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+
+ var payload: [64]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&payload);
+
+ // Reserved row flag bits six and seven are ignored while the unknown
+ // semantic-prompt value degrades to none and wrap survives. Bits four
+ // and five select the full encoded cell width.
+ try writer.writeByte(0xFD);
+ try io.writeInt(&writer, u16, 3);
+
+ // A surrogate codepoint with reserved semantic content 3.
+ try io.writeInt(&writer, u64, @bitCast(Cell{
+ .content = 0xD800,
+ .semantic_content = 3,
+ }));
+
+ // Reserved palette content bits do not obscure the palette index.
+ try io.writeInt(&writer, u64, @bitCast(Cell{
+ .kind = 2,
+ .content = 0xFFFF07,
+ }));
+
+ // An unknown style reference degrades to the default style, and an
+ // unknown hyperlink reference leaves the cell unlinked.
+ try io.writeInt(&writer, u64, @bitCast(Cell{
+ .content = 'x',
+ .style_id = 5,
+ .hyperlink = true,
+ .hyperlink_id = 9,
+ }));
+ try io.writeInt(&writer, u32, 0);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ try decode(&page, &reader, &style_remap, &hyperlink_remap);
+ try page.verifyIntegrity(testing.allocator);
+
+ const first = page.getRowAndCell(0, 0);
+ try testing.expect(first.row.wrap);
+ try testing.expectEqual(
+ TerminalRow.SemanticPrompt.none,
+ first.row.semantic_prompt,
+ );
+ try testing.expectEqual(@as(u21, 0xFFFD), first.cell.codepoint());
+ try testing.expectEqual(
+ TerminalCell.SemanticContent.output,
+ first.cell.semantic_content,
+ );
+
+ const second = page.getRowAndCell(1, 0).cell;
+ try testing.expectEqual(
+ TerminalCell.ContentTag.bg_color_palette,
+ second.content_tag,
+ );
+ try testing.expectEqual(@as(u8, 7), second.content.color_palette.data);
+
+ const third = page.getRowAndCell(2, 0).cell;
+ try testing.expectEqual(@as(u21, 'x'), third.codepoint());
+ try testing.expectEqual(@as(TerminalStyleId, 0), third.style_id);
+ try testing.expect(!third.hyperlink);
+ try testing.expectEqual(null, page.lookupHyperlink(third));
+}
+
+test "grid drops undeliverable grapheme entries" {
+ const testing = std.testing;
+ var page = try TerminalPage.init(.{
+ .cols = 4,
+ .rows = 1,
+ .grapheme_bytes = 64,
+ });
+ defer page.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+
+ var payload: [128]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&payload);
+ try writer.writeByte(@bitCast(Row{ .cell_width = .eight }));
+ try io.writeInt(&writer, u16, 4);
+ // A kind 1 cell that receives a valid entry.
+ try io.writeInt(&writer, u64, @bitCast(Cell{ .kind = 1, .content = 'x' }));
+ // A kind 1 cell without an entry decodes as a plain codepoint.
+ try io.writeInt(&writer, u64, @bitCast(Cell{ .kind = 1, .content = 'y' }));
+ // A background cell cannot carry a suffix.
+ try io.writeInt(&writer, u64, @bitCast(Cell{ .kind = 2, .content = 7 }));
+ // An empty codepoint cannot carry a suffix.
+ try io.writeInt(&writer, u64, @bitCast(Cell{}));
+
+ try io.writeInt(&writer, u32, 5);
+ // Valid entry with one invalid scalar dropped from within it.
+ try io.writeInt(&writer, u16, 0);
+ try io.writeInt(&writer, u16, 0);
+ try io.writeInt(&writer, u16, 4);
+ try io.writeInt(&writer, u32, 0x0301);
+ try io.writeInt(&writer, u32, 0);
+ try io.writeInt(&writer, u32, 0xD800);
+ try io.writeInt(&writer, u32, 0x0302);
+ // Duplicate entry for the same cell is consumed and dropped.
+ try io.writeInt(&writer, u16, 0);
+ try io.writeInt(&writer, u16, 0);
+ try io.writeInt(&writer, u16, 1);
+ try io.writeInt(&writer, u32, 0x0303);
+ // Entry for the background cell is consumed and dropped.
+ try io.writeInt(&writer, u16, 0);
+ try io.writeInt(&writer, u16, 2);
+ try io.writeInt(&writer, u16, 1);
+ try io.writeInt(&writer, u32, 0x0301);
+ // Entry for the empty cell is consumed and dropped.
+ try io.writeInt(&writer, u16, 0);
+ try io.writeInt(&writer, u16, 3);
+ try io.writeInt(&writer, u16, 1);
+ try io.writeInt(&writer, u32, 0x0301);
+ // Entry outside the grid is consumed and dropped.
+ try io.writeInt(&writer, u16, 7);
+ try io.writeInt(&writer, u16, 0);
+ try io.writeInt(&writer, u16, 1);
+ try io.writeInt(&writer, u32, 0x0301);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ try decode(&page, &reader, &style_remap, &hyperlink_remap);
+ try page.verifyIntegrity(testing.allocator);
+
+ const first = page.getRowAndCell(0, 0);
+ try testing.expectEqualSlices(
+ u21,
+ &.{ 0x0301, 0x0302 },
+ page.lookupGrapheme(first.cell).?,
+ );
+ const second = page.getRowAndCell(1, 0).cell;
+ try testing.expectEqual(@as(u21, 'y'), second.codepoint());
+ try testing.expect(!second.hasGrapheme());
+ try testing.expect(!page.getRowAndCell(2, 0).cell.hasGrapheme());
+ try testing.expect(!page.getRowAndCell(3, 0).cell.hasGrapheme());
+}
+
+test "grid drops a complete grapheme when capacity fails mid-cluster" {
+ const testing = std.testing;
+ var page = try TerminalPage.init(.{
+ .cols = 4,
+ .rows = 1,
+ .grapheme_bytes = 512,
+ });
+ defer page.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+
+ var payload: [1024]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&payload);
+ try writer.writeByte(@bitCast(Row{ .cell_width = .eight }));
+ try io.writeInt(&writer, u16, 4);
+ for (0..4) |i| try io.writeInt(
+ &writer,
+ u64,
+ @bitCast(Cell{ .kind = 1, .content = @intCast('x' + i) }),
+ );
+
+ // BitmapAllocator rounds this capacity to 64 four-codepoint chunks. The
+ // first three cells consume 34 chunks. On the fourth cell, appending the
+ // 61st suffix needs 16 new chunks while the old 15-chunk slice is still
+ // live, exceeding capacity and forcing the complete suffix to be dropped.
+ try io.writeInt(&writer, u32, 4);
+ for ([_]u16{ 64, 64, 8, 61 }, 0..) |count, x| {
+ try io.writeInt(&writer, u16, 0);
+ try io.writeInt(&writer, u16, @intCast(x));
+ try io.writeInt(&writer, u16, count);
+ for (0..count) |i| try io.writeInt(
+ &writer,
+ u32,
+ @intCast(0x0300 + i),
+ );
+ }
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ try decode(&page, &reader, &style_remap, &hyperlink_remap);
+ try page.verifyIntegrity(testing.allocator);
+
+ const cell = page.getRowAndCell(3, 0);
+ try testing.expectEqual(@as(u21, @intCast('x' + 3)), cell.cell.codepoint());
+ try testing.expect(!cell.cell.hasGrapheme());
+ try testing.expect(cell.row.grapheme);
+ try testing.expectEqual(@as(usize, 3), page.graphemeCount());
+}
+
+test "grid encodes rows at their narrowest width" {
+ const testing = std.testing;
+ var page = try TerminalPage.init(.{
+ .cols = 2,
+ .rows = 4,
+ .styles = 8,
+ });
+ defer page.deinit();
+
+ // Width zero: bare Latin-1 text.
+ page.getRowAndCell(0, 0).cell.* = .init('A');
+ page.getRowAndCell(1, 0).cell.* = .init(0xFF);
+
+ // Width one: any BMP codepoint.
+ page.getRowAndCell(0, 1).cell.* = .init(0x0100);
+
+ // Width two: a small style ID and a background color.
+ const style_id = try page.styles.add(page.memory, .{
+ .flags = .{ .bold = true },
+ });
+ try testing.expect(style_id <= 63);
+ const styled = page.getRowAndCell(0, 2);
+ styled.cell.* = .init('s');
+ styled.cell.style_id = style_id;
+ styled.row.styled = true;
+ const bg = page.getRowAndCell(1, 2);
+ bg.cell.content_tag = .bg_color_palette;
+ bg.cell.content = .{ .color_palette = .{ .data = 7 } };
+
+ // Width three: a protected cell.
+ page.getRowAndCell(0, 3).cell.protected = true;
+
+ var encoded: [128]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try encode(&page, &writer);
+
+ const bytes = writer.buffered();
+ try testing.expectEqual(
+ @as(usize, (3 + 2 * 1) + (3 + 1 * 2) + (3 + 2 * 4) + (3 + 1 * 8) + 4),
+ bytes.len,
+ );
+
+ // Each row header carries the expected width bits.
+ try testing.expectEqual(@as(u8, 0 << 4), bytes[0] & 0x30);
+ try testing.expectEqual(@as(u8, 1 << 4), bytes[5] & 0x30);
+ try testing.expectEqual(@as(u8, 2 << 4), bytes[10] & 0x30);
+ try testing.expectEqual(@as(u8, 3 << 4), bytes[21] & 0x30);
+
+ var destination = try TerminalPage.init(.{
+ .cols = 2,
+ .rows = 4,
+ .styles = 8,
+ });
+ defer destination.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+ const native_style = try destination.styles.add(destination.memory, .{
+ .flags = .{ .bold = true },
+ });
+ style_remap.put(style_id, native_style);
+
+ var reader: std.Io.Reader = .fixed(bytes);
+ try decode(&destination, &reader, &style_remap, &hyperlink_remap);
+ try destination.verifyIntegrity(testing.allocator);
+
+ try testing.expectEqual(
+ @as(u21, 'A'),
+ destination.getRowAndCell(0, 0).cell.codepoint(),
+ );
+ try testing.expectEqual(
+ @as(u21, 0xFF),
+ destination.getRowAndCell(1, 0).cell.codepoint(),
+ );
+ try testing.expectEqual(
+ @as(u21, 0x0100),
+ destination.getRowAndCell(0, 1).cell.codepoint(),
+ );
+ const decoded_styled = destination.getRowAndCell(0, 2);
+ try testing.expectEqual(@as(u21, 's'), decoded_styled.cell.codepoint());
+ try testing.expectEqual(native_style, decoded_styled.cell.style_id);
+ try testing.expect(decoded_styled.row.styled);
+ try testing.expectEqual(
+ @as(u8, 7),
+ destination.getRowAndCell(1, 2).cell.content.color_palette.data,
+ );
+ try testing.expect(destination.getRowAndCell(0, 3).cell.protected);
+}
+
+test "grid decodes non-canonical cell widths" {
+ const testing = std.testing;
+ var page = try TerminalPage.init(.{ .cols = 2, .rows = 1 });
+ defer page.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+
+ // A bare ASCII row encoded at the full width is wasteful but valid.
+ var payload: [64]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&payload);
+ try writer.writeByte(@bitCast(Row{ .cell_width = .eight }));
+ try io.writeInt(&writer, u16, 2);
+ try io.writeInt(&writer, u64, @bitCast(Cell{ .content = 'o' }));
+ try io.writeInt(&writer, u64, @bitCast(Cell{ .content = 'k' }));
+ try io.writeInt(&writer, u32, 0);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ try decode(&page, &reader, &style_remap, &hyperlink_remap);
+ try page.verifyIntegrity(testing.allocator);
+ try testing.expectEqual(
+ @as(u21, 'o'),
+ page.getRowAndCell(0, 0).cell.codepoint(),
+ );
+ try testing.expectEqual(
+ @as(u21, 'k'),
+ page.getRowAndCell(1, 0).cell.codepoint(),
+ );
+
+ // Re-encoding canonicalizes the row back to the one-byte width.
+ var reencoded: [16]u8 = undefined;
+ var rewriter: std.Io.Writer = .fixed(&reencoded);
+ try encode(&page, &rewriter);
+ try testing.expectEqual(@as(usize, 3 + 2 + 4), rewriter.buffered().len);
+}
+
+test "grid normalizes surrogates in two-byte cells" {
+ const testing = std.testing;
+ var page = try TerminalPage.init(.{ .cols = 2, .rows = 1 });
+ defer page.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+
+ var payload: [16]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&payload);
+ try writer.writeByte(@bitCast(Row{ .cell_width = .two }));
+ try io.writeInt(&writer, u16, 2);
+ try io.writeInt(&writer, u16, 0xD800);
+ try io.writeInt(&writer, u16, 0x0416);
+ try io.writeInt(&writer, u32, 0);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ try decode(&page, &reader, &style_remap, &hyperlink_remap);
+ try page.verifyIntegrity(testing.allocator);
+ try testing.expectEqual(
+ @as(u21, 0xFFFD),
+ page.getRowAndCell(0, 0).cell.codepoint(),
+ );
+ try testing.expectEqual(
+ @as(u21, 0x0416),
+ page.getRowAndCell(1, 0).cell.codepoint(),
+ );
+}
+
+test "grid four-byte cells run full normalization" {
+ const testing = std.testing;
+ var page = try TerminalPage.init(.{
+ .cols = 3,
+ .rows = 1,
+ .styles = 8,
+ });
+ defer page.deinit();
+ var style_remap = try StyleRemap.init(testing.allocator);
+ defer style_remap.deinit(testing.allocator);
+ var hyperlink_remap = try HyperlinkRemap.init(testing.allocator);
+ defer hyperlink_remap.deinit(testing.allocator);
+
+ var payload: [32]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&payload);
+ try writer.writeByte(@bitCast(Row{ .cell_width = .four }));
+ try io.writeInt(&writer, u16, 3);
+
+ // The Kitty placeholder does not fit two-byte cells but fits here
+ // and must still derive the native row hint.
+ try io.writeInt(&writer, u32, @truncate(@as(u64, @bitCast(Cell{
+ .content = kitty_virtual_placeholder,
+ }))));
+
+ // An unknown small style reference degrades to the default style.
+ try io.writeInt(&writer, u32, @truncate(@as(u64, @bitCast(Cell{
+ .content = 'x',
+ .style_id = 63,
+ }))));
+
+ // Reserved palette content bits are cleared at this width too.
+ try io.writeInt(&writer, u32, @truncate(@as(u64, @bitCast(Cell{
+ .kind = 2,
+ .content = 0xFFFF07,
+ }))));
+ try io.writeInt(&writer, u32, 0);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ try decode(&page, &reader, &style_remap, &hyperlink_remap);
+ try page.verifyIntegrity(testing.allocator);
+
+ const first = page.getRowAndCell(0, 0);
+ try testing.expectEqual(
+ kitty_virtual_placeholder,
+ first.cell.codepoint(),
+ );
+ try testing.expect(first.row.kitty_virtual_placeholder);
+
+ const second = page.getRowAndCell(1, 0).cell;
+ try testing.expectEqual(@as(u21, 'x'), second.codepoint());
+ try testing.expectEqual(@as(TerminalStyleId, 0), second.style_id);
+
+ const third = page.getRowAndCell(2, 0).cell;
+ try testing.expectEqual(
+ TerminalCell.ContentTag.bg_color_palette,
+ third.content_tag,
+ );
+ try testing.expectEqual(@as(u8, 7), third.content.color_palette.data);
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/history.zig b/vendor/libghostty-vt/src/terminal/snapshot/history.zig
new file mode 100644
index 00000000..90f1a749
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/history.zig
@@ -0,0 +1,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();
+ }
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/hyperlink.zig b/vendor/libghostty-vt/src/terminal/snapshot/hyperlink.zig
new file mode 100644
index 00000000..b10d0dc8
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/hyperlink.zig
@@ -0,0 +1,493 @@
+//! Snapshot hyperlink entry encoding.
+//!
+//! Each entry contains a URI and either an implicit numeric ID or an explicit
+//! byte-string ID. Implicit IDs are generated by the terminal when the source
+//! hyperlink has no explicit ID. A record can use these entries to build a
+//! hyperlink table and assign indexes according to that record's format.
+//! Indexing and ordering are properties of the containing record rather than
+//! this codec.
+//!
+//! URIs and explicit IDs are non-empty arbitrary byte strings. Their lengths
+//! are retained on the wire; they are not NUL-terminated and need not contain
+//! UTF-8. Native page storage requires every allocated hyperlink string to
+//! contain at least one byte. Encoding and standalone decoding reject empty
+//! strings; PAGE decoding consumes but ignores entries it cannot represent.
+//!
+//! All integers are unsigned and little-endian.
+//!
+//! ## Implicit ID
+//!
+//! | Offset | Size | Field |
+//! | -----: | --------: | :----------------- |
+//! | 0 | 1 | Kind, `1` |
+//! | 1 | 4 | Implicit ID (`u32`) |
+//! | 5 | 4 | URI length (`u32`) |
+//! | 9 | `uri_len` | URI bytes |
+//!
+//! ## Explicit ID
+//!
+//! | Offset | Size | Field |
+//! | -----------: | --------: | :------------------------- |
+//! | 0 | 1 | Kind, `2` |
+//! | 1 | 4 | Explicit ID length (`u32`) |
+//! | 5 | `id_len` | Explicit ID bytes |
+//! | `5 + id_len` | 4 | URI length (`u32`) |
+//! | `9 + id_len` | `uri_len` | URI bytes |
+//!
+//! Both variants have nine bytes of fixed overhead. The remaining bytes are
+//! the URI plus the explicit ID, when present.
+//!
+//! The standalone decoder returns an allocator-owned hyperlink. PAGE decoding
+//! reads strings directly into the destination page's allocator instead.
+
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const test_fixture = @import("fixture.zig");
+const io = @import("io.zig");
+const terminal_hyperlink = @import("../hyperlink.zig");
+const terminal_page = @import("../page.zig");
+const terminal_size = @import("../size.zig");
+
+const Kind = enum(u8) {
+ implicit = 1,
+ explicit = 2,
+};
+
+/// Errors possible while encoding one hyperlink entry.
+pub const EncodeError = std.Io.Writer.Error || error{
+ /// A native hyperlink URI must contain at least one byte.
+ InvalidUri,
+
+ /// A native explicit hyperlink ID must contain at least one byte.
+ InvalidExplicitId,
+
+ /// A string does not fit the version 1 length field.
+ StringTooLong,
+};
+
+/// Errors possible while decoding one allocator-owned hyperlink entry.
+pub const DecodeError = std.Io.Reader.Error || Allocator.Error || error{
+ /// The hyperlink kind is not defined by snapshot version 1.
+ InvalidKind,
+
+ /// A native hyperlink URI must contain at least one byte.
+ InvalidUri,
+
+ /// A native explicit hyperlink ID must contain at least one byte.
+ InvalidExplicitId,
+};
+
+/// Errors possible while decoding directly into a native page.
+pub const DecodePageError = std.Io.Reader.Error || error{
+ /// The hyperlink kind is not defined by snapshot version 1.
+ InvalidKind,
+};
+
+/// Encode one hyperlink entry.
+pub fn encode(
+ value: terminal_hyperlink.Hyperlink,
+ writer: *std.Io.Writer,
+) EncodeError!void {
+ // Validate the complete value before writing any part of this variable-
+ // length entry. This keeps callers able to roll back at entry boundaries.
+ if (value.uri.len == 0) return error.InvalidUri;
+ if (value.uri.len > std.math.maxInt(u32)) return error.StringTooLong;
+ if (value.id == .explicit) {
+ const id = value.id.explicit;
+ if (id.len == 0) return error.InvalidExplicitId;
+ if (id.len > std.math.maxInt(u32)) return error.StringTooLong;
+ }
+
+ switch (value.id) {
+ .implicit => |id| {
+ try writer.writeByte(@intFromEnum(Kind.implicit));
+ try io.writeInt(writer, u32, id);
+ try io.writeInt(writer, u32, @intCast(value.uri.len));
+ try writer.writeAll(value.uri);
+ },
+ .explicit => |id| {
+ try writer.writeByte(@intFromEnum(Kind.explicit));
+ try io.writeInt(writer, u32, @intCast(id.len));
+ try writer.writeAll(id);
+ try io.writeInt(writer, u32, @intCast(value.uri.len));
+ try writer.writeAll(value.uri);
+ },
+ }
+}
+
+/// Decode one allocator-owned hyperlink entry.
+///
+/// The caller owns the returned value and must call `Hyperlink.deinit`.
+pub fn decode(
+ reader: *std.Io.Reader,
+ alloc: Allocator,
+) DecodeError!terminal_hyperlink.Hyperlink {
+ const kind_raw = try reader.takeByte();
+ const kind = std.enums.fromInt(Kind, kind_raw) orelse
+ return error.InvalidKind;
+
+ return switch (kind) {
+ .implicit => implicit: {
+ const id = try io.readInt(reader, u32);
+ const uri_len: usize = @intCast(try io.readInt(reader, u32));
+ if (uri_len == 0) return error.InvalidUri;
+
+ const uri = try alloc.alloc(u8, uri_len);
+ errdefer alloc.free(uri);
+ try reader.readSliceAll(uri);
+
+ break :implicit .{
+ .id = .{ .implicit = id },
+ .uri = uri,
+ };
+ },
+
+ .explicit => explicit: {
+ const id_len: usize = @intCast(try io.readInt(reader, u32));
+ if (id_len == 0) return error.InvalidExplicitId;
+
+ const id = try alloc.alloc(u8, id_len);
+ errdefer alloc.free(id);
+ try reader.readSliceAll(id);
+
+ const uri_len: usize = @intCast(try io.readInt(reader, u32));
+ if (uri_len == 0) return error.InvalidUri;
+
+ const uri = try alloc.alloc(u8, uri_len);
+ errdefer alloc.free(uri);
+ try reader.readSliceAll(uri);
+
+ break :explicit .{
+ .id = .{ .explicit = id },
+ .uri = uri,
+ };
+ },
+ };
+}
+
+/// Decode one hyperlink directly into page-owned storage.
+///
+/// Explicit ID and URI bytes are read into the page string allocator and the
+/// completed entry is inserted into the page hyperlink set. The returned ID is
+/// the native ID assigned by the destination page. Zero is returned when the
+/// encoded value cannot be represented within the destination page, including
+/// empty strings and insufficient advertised capacity.
+pub fn decodePage(
+ page: *terminal_page.Page,
+ reader: *std.Io.Reader,
+) DecodePageError!terminal_hyperlink.Id {
+ const kind_raw = try reader.takeByte();
+ const kind = std.enums.fromInt(Kind, kind_raw) orelse
+ return error.InvalidKind;
+
+ const entry: terminal_hyperlink.PageEntry = switch (kind) {
+ .implicit => implicit: {
+ const id = try io.readInt(reader, u32);
+ const uri_len: usize = @intCast(try io.readInt(reader, u32));
+ if (uri_len == 0) return 0;
+
+ const uri = decodePageString(
+ page,
+ reader,
+ uri_len,
+ ) catch |err| switch (err) {
+ error.StringsOutOfMemory => {
+ try reader.discardAll(uri_len);
+ return 0;
+ },
+ else => |read_err| return read_err,
+ };
+
+ break :implicit .{
+ .id = .{ .implicit = id },
+ .uri = uri,
+ };
+ },
+
+ .explicit => explicit: {
+ const id_len: usize = @intCast(try io.readInt(reader, u32));
+ if (id_len == 0) {
+ const uri_len: usize = @intCast(
+ try io.readInt(reader, u32),
+ );
+ try reader.discardAll(uri_len);
+ return 0;
+ }
+
+ const id = decodePageString(
+ page,
+ reader,
+ id_len,
+ ) catch |err| switch (err) {
+ error.StringsOutOfMemory => {
+ try reader.discardAll(id_len);
+ const uri_len: usize = @intCast(
+ try io.readInt(reader, u32),
+ );
+ try reader.discardAll(uri_len);
+ return 0;
+ },
+ else => |read_err| return read_err,
+ };
+ errdefer page.string_alloc.free(
+ page.memory,
+ id.slice(page.memory),
+ );
+
+ const uri_len: usize = @intCast(try io.readInt(reader, u32));
+ if (uri_len == 0) {
+ page.string_alloc.free(
+ page.memory,
+ id.slice(page.memory),
+ );
+ return 0;
+ }
+
+ const uri = decodePageString(
+ page,
+ reader,
+ uri_len,
+ ) catch |err| switch (err) {
+ error.StringsOutOfMemory => {
+ try reader.discardAll(uri_len);
+ page.string_alloc.free(
+ page.memory,
+ id.slice(page.memory),
+ );
+ return 0;
+ },
+ else => |read_err| return read_err,
+ };
+
+ break :explicit .{
+ .id = .{ .explicit = id },
+ .uri = uri,
+ };
+ },
+ };
+ return page.hyperlink_set.addContext(
+ page.memory,
+ entry,
+ .{ .page = page },
+ ) catch {
+ // The entry was fully consumed, so capacity failure only loses this
+ // optional hyperlink. Free its strings and let cells restore unlinked.
+ entry.free(page);
+ return 0;
+ };
+}
+
+fn decodePageString(
+ page: *terminal_page.Page,
+ reader: *std.Io.Reader,
+ len: usize,
+) (std.Io.Reader.Error || error{StringsOutOfMemory})!terminal_size.Offset(u8).Slice {
+ std.debug.assert(len > 0);
+
+ // Allocate space for the string and read directly into it.
+ const value = page.string_alloc.alloc(
+ u8,
+ page.memory,
+ len,
+ ) catch return error.StringsOutOfMemory;
+ errdefer page.string_alloc.free(page.memory, value);
+ try reader.readSliceAll(value);
+
+ return .{
+ .len = value.len,
+ .offset = terminal_size.getOffset(
+ u8,
+ page.memory,
+ &value[0],
+ ),
+ };
+}
+
+const test_implicit_fixture = test_fixture.parse(@embedFile("testdata/hyperlink-implicit-v1.hex"));
+const test_explicit_fixture = test_fixture.parse(@embedFile("testdata/hyperlink-explicit-v1.hex"));
+
+test "golden implicit encoding" {
+ const value: terminal_hyperlink.Hyperlink = .{
+ .id = .{ .implicit = 0x01020304 },
+ .uri = "uri",
+ };
+
+ var buf: [128]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ try encode(value, &writer);
+
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/hyperlink-implicit-v1.hex",
+ "snapshot_fixture-hyperlink-implicit-v1.hex",
+ &test_implicit_fixture,
+ writer.buffered(),
+ );
+
+ var reader: std.Io.Reader = .fixed(&test_implicit_fixture);
+ var decoded = try decode(&reader, std.testing.allocator);
+ defer decoded.deinit(std.testing.allocator);
+ try std.testing.expectEqualDeep(value, decoded);
+}
+
+test "golden explicit encoding" {
+ const value: terminal_hyperlink.Hyperlink = .{
+ .id = .{ .explicit = "id" },
+ .uri = "uri",
+ };
+
+ var buf: [128]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ try encode(value, &writer);
+
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/hyperlink-explicit-v1.hex",
+ "snapshot_fixture-hyperlink-explicit-v1.hex",
+ &test_explicit_fixture,
+ writer.buffered(),
+ );
+
+ var reader: std.Io.Reader = .fixed(&test_explicit_fixture);
+ var decoded = try decode(&reader, std.testing.allocator);
+ defer decoded.deinit(std.testing.allocator);
+ try std.testing.expectEqualDeep(value, decoded);
+}
+
+test "encode rejects invalid strings before writing" {
+ const cases = [_]struct {
+ value: terminal_hyperlink.Hyperlink,
+ expected: anyerror,
+ }{
+ .{
+ .value = .{ .id = .{ .implicit = 1 }, .uri = "" },
+ .expected = error.InvalidUri,
+ },
+ .{
+ .value = .{ .id = .{ .explicit = "" }, .uri = "uri" },
+ .expected = error.InvalidExplicitId,
+ },
+ .{
+ .value = .{ .id = .{ .explicit = "id" }, .uri = "" },
+ .expected = error.InvalidUri,
+ },
+ };
+
+ for (cases) |case| {
+ var encoded: [32]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try std.testing.expectError(
+ case.expected,
+ encode(case.value, &writer),
+ );
+ try std.testing.expectEqual(@as(usize, 0), writer.end);
+ }
+}
+
+test "decode rejects empty strings" {
+ const cases = [_]struct {
+ fixture: []const u8,
+ expected: anyerror,
+ }{
+ .{
+ .fixture = "\x01\x04\x03\x02\x01\x00\x00\x00\x00",
+ .expected = error.InvalidUri,
+ },
+ .{
+ .fixture = "\x02\x00\x00\x00\x00",
+ .expected = error.InvalidExplicitId,
+ },
+ .{
+ .fixture = "\x02\x02\x00\x00\x00id\x00\x00\x00\x00",
+ .expected = error.InvalidUri,
+ },
+ };
+
+ for (cases) |case| {
+ var reader: std.Io.Reader = .fixed(case.fixture);
+ try std.testing.expectError(
+ case.expected,
+ decode(&reader, std.testing.allocator),
+ );
+ }
+}
+
+test "decodePage ignores empty strings" {
+ const fixtures = [_][]const u8{
+ "\x01\x04\x03\x02\x01\x00\x00\x00\x00",
+ "\x02\x00\x00\x00\x00\x03\x00\x00\x00uri",
+ "\x02\x02\x00\x00\x00id\x00\x00\x00\x00",
+ };
+
+ for (fixtures) |fixture| {
+ var page = try terminal_page.Page.init(.{
+ .cols = 1,
+ .rows = 1,
+ .hyperlink_bytes = 512,
+ .string_bytes = 16,
+ });
+ defer page.deinit();
+
+ var reader: std.Io.Reader = .fixed(fixture);
+ try std.testing.expectEqual(
+ @as(terminal_hyperlink.Id, 0),
+ try decodePage(&page, &reader),
+ );
+ try std.testing.expectEqual(@as(usize, 0), page.hyperlink_set.count());
+ try std.testing.expectError(error.EndOfStream, reader.takeByte());
+ }
+}
+
+test "decode rejects invalid kinds" {
+ for ([_]u8{ 0, 3, std.math.maxInt(u8) }) |kind| {
+ var fixture: [1]u8 = .{kind};
+ var reader: std.Io.Reader = .fixed(&fixture);
+ try std.testing.expectError(
+ error.InvalidKind,
+ decode(&reader, std.testing.allocator),
+ );
+ }
+}
+
+test "decode allocation failure" {
+ {
+ var reader: std.Io.Reader = .fixed(&test_implicit_fixture);
+ var failing = std.testing.FailingAllocator.init(
+ std.testing.allocator,
+ .{ .fail_index = 0 },
+ );
+ try std.testing.expectError(
+ error.OutOfMemory,
+ decode(&reader, failing.allocator()),
+ );
+ }
+
+ for (0..2) |fail_index| {
+ var failing = std.testing.FailingAllocator.init(
+ std.testing.allocator,
+ .{ .fail_index = fail_index },
+ );
+ var reader: std.Io.Reader = .fixed(&test_explicit_fixture);
+ try std.testing.expectError(
+ error.OutOfMemory,
+ decode(&reader, failing.allocator()),
+ );
+ }
+}
+
+test "reject every truncation" {
+ const fixtures: [2][]const u8 = .{
+ &test_implicit_fixture,
+ &test_explicit_fixture,
+ };
+
+ for (fixtures) |fixture| {
+ for (0..fixture.len) |fixture_len| {
+ var reader: std.Io.Reader = .fixed(fixture[0..fixture_len]);
+ try std.testing.expectError(
+ error.EndOfStream,
+ decode(&reader, std.testing.allocator),
+ );
+ }
+ }
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/io.zig b/vendor/libghostty-vt/src/terminal/snapshot/io.zig
new file mode 100644
index 00000000..d47f96cc
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/io.zig
@@ -0,0 +1,55 @@
+//! Wire-format I/O helpers.
+//!
+//! These are sometimes very thin layers over standard `std.Io.Writer`
+//! but its to help ensure consistency in our behavior and avoid some
+//! pitfalls.
+
+const std = @import("std");
+const testing = std.testing;
+
+/// writeInt ensures we write in little-endian since that is our
+/// standard form.
+pub fn writeInt(
+ writer: *std.Io.Writer,
+ comptime T: type,
+ value: T,
+) std.Io.Writer.Error!void {
+ try writer.writeInt(T, value, .little);
+}
+
+/// Read a little-endian integer.
+///
+/// This avoids `takeInt` because at the time of writing this the underlying
+/// implementation uses `takeArray` which asserts that the reader buffer
+/// is as large as T. Our approach works with caller-selected buffers that
+/// may be smaller.
+pub fn readInt(
+ reader: *std.Io.Reader,
+ comptime T: type,
+) std.Io.Reader.Error!T {
+ var buf: [@sizeOf(T)]u8 = undefined;
+ try reader.readSliceAll(&buf);
+ return std.mem.readInt(T, &buf, .little);
+}
+
+test "integer round trip with a one-byte reader buffer" {
+ var encoded: [6]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try writeInt(&writer, u16, 0x1234);
+ try writeInt(&writer, u32, 0x56789abc);
+
+ // Keep the reader buffer smaller than either integer to verify readInt
+ // does not inherit std.Io.Reader.takeInt's buffer-size requirement.
+ var source: std.Io.Reader = .fixed(&encoded);
+ var buf: [1]u8 = undefined;
+ var limited = source.limited(.unlimited, &buf);
+
+ try testing.expectEqual(
+ @as(u16, 0x1234),
+ try readInt(&limited.interface, u16),
+ );
+ try testing.expectEqual(
+ @as(u32, 0x56789abc),
+ try readInt(&limited.interface, u32),
+ );
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/main.zig b/vendor/libghostty-vt/src/terminal/snapshot/main.zig
new file mode 100644
index 00000000..f69d78c9
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/main.zig
@@ -0,0 +1,182 @@
+//! Terminal snapshot binary representation and codecs.
+//!
+//! This is NOT a full transport-ready format to implement generic replay
+//! software such as multiplexers, recorders (e.g. asciinema), etc. The goal
+//! of this package is to provide a documented, binary-compatible representation
+//! for a terminal state.
+//!
+//! We call this a "snapshot." The snapshot is purposely laid out in a way
+//! that prioritizes making a terminal functional as quickly as possible.
+//! To do that, it sends the active terminal state followed by a READY record,
+//! then complete history.
+//!
+//! READY denotes that enough state has been sent down to render the
+//! terminal and reconstruct its unfinished VT Stream state.
+//!
+//! After READY, we send history pages (scrollback). Finally, the
+//! snapshot ends with an empty FINISH marker.
+//!
+//! ## Snapshot Format
+//!
+//! This documents snapshot format 1. Version 1 is the work-in-progress
+//! format that we intended to continue to break until we can promise
+//! binary compatibility.
+//!
+//! A snapshot is one envelope followed by a sequence of records. The envelope
+//! occurs once at byte zero. Every record is independently framed as a fixed
+//! header followed by the number of payload bytes declared by that header.
+//!
+//! ```text
+//! +------------------+
+//! | Envelope |
+//! +------------------+
+//! | Record 1 header |
+//! +------------------+
+//! | Record 1 payload |
+//! +------------------+
+//! | Record 2 header |
+//! +------------------+
+//! | Record 2 payload |
+//! +------------------+
+//! | ... |
+//! +------------------+
+//! ```
+//!
+//! Record groups have a strict order:
+//!
+//! ```text
+//! +----------------------------------------+
+//! | TERMINAL |
+//! +----------------------------------------+
+//! | SCREEN * terminal.screen_count |
+//! | PAGE * each screen.page_count |
+//! +----------------------------------------+
+//! | CONTINUATION |
+//! +----------------------------------------+
+//! | READY |
+//! +----------------------------------------+
+//! | HISTORY * terminal.screen_count |
+//! | PAGE * each history.page_count |
+//! +----------------------------------------+
+//! | FINISH |
+//! +----------------------------------------+
+//! ```
+//!
+//! The SCREEN and HISTORY sequence groups may each appear in any key order.
+//! Each key must occur exactly once in each group and must identify one of the
+//! screens declared by TERMINAL. SCREEN contains the complete pages needed to
+//! restore each active area. HISTORY contains the older complete pages for its
+//! screen in newest-to-oldest order so they can be prepended as they arrive.
+//! Every SCREEN has one corresponding HISTORY, even when its history page count
+//! is zero. FINISH terminates the snapshot. Bytes after FINISH belong to the
+//! containing transport and are not consumed by snapshot decoding.
+//!
+//! CONTINUATION contains the bytes required to bring the terminal's
+//! VT parser/stream up to the same state, or no bytes if it should be
+//! in the ground state.
+//!
+//! READY and FINISH are empty marker records. READY separates the renderable
+//! active state and continuation from history; FINISH terminates the complete
+//! snapshot. Every record, including both markers, is independently protected
+//! by CRC32C. Each SCREEN declares its complete logical history extent, allowing
+//! a client to size its scrollbar at READY even though older PAGE records arrive
+//! afterward.
+//!
+//! ## Encoding
+//!
+//! Encode a complete snapshot into any writer:
+//!
+//! ```zig
+//! var output: std.Io.Writer.Allocating = .init(alloc);
+//! defer output.deinit();
+//!
+//! try snapshot.encode(alloc, &output.writer, &terminal, .{
+//! .continuation = .ground,
+//! });
+//!
+//! const bytes = output.written();
+//! ```
+//!
+//! Encoding begins at the writer's current position, so unrelated bytes may
+//! precede the snapshot. The encoder buffers only the current record payload
+//! to calculate its length and CRC32C; completed records stream immediately.
+//! Buffering is an encoder implementation detail, not a requirement of the
+//! wire format.
+//!
+//! A failure may leave prior complete records, or a partial record if the
+//! destination itself fails. Such a prefix has no FINISH marker and
+//! cannot be restored as a complete snapshot.
+//!
+//! Each record type usually exposes an `encode` function that encodes
+//! a complete record, such as `screen.encode`.
+//!
+//! ## Decoding
+//!
+//! `snapshot.decode` consumes exactly one snapshot through FINISH and leaves
+//! any following bytes unread. This permits multiple snapshots or live protocol
+//! data to share a stream without waiting for the peer to close it. Transports
+//! that deliver live PTY data before history finishes must multiplex that data
+//! outside this ordered snapshot record sequence.
+//!
+//! ```zig
+//! var decoded = try snapshot.decode(alloc, io, &reader, .{
+//! .max_continuation_bytes = 1024 * 1024,
+//! });
+//! defer decoded.deinit(alloc);
+//! var terminal = decoded.toOwned();
+//! defer terminal.deinit(alloc);
+//! ```
+//!
+//! Use `snapshot.decodeExact` for a bounded file or buffer that must contain
+//! only one snapshot. It preserves the stricter end-of-file check, which may
+//! block when used with a live stream.
+//!
+//! `snapshot.Decoder` decodes the same stream incrementally so the terminal
+//! becomes usable at READY, before history has arrived. Each `next` call
+//! applies one history page to the by-then live terminal and returning null
+//! validates FINISH:
+//!
+//! ```zig
+//! var decoder: snapshot.Decoder = .init(&reader);
+//! var decoded = try decoder.ready(alloc, io, .{
+//! .max_continuation_bytes = 1024 * 1024,
+//! });
+//! defer decoded.deinit(alloc);
+//!
+//! var terminal = decoded.toOwned();
+//! defer terminal.deinit(alloc);
+//!
+//! // Render, replay the continuation, process input...
+//! while (try decoder.next(alloc, &terminal)) |progress| {
+//! _ = progress; // Scrollback grew.
+//! }
+//! ```
+
+pub const checkpoint = @import("checkpoint.zig");
+pub const continuation = @import("continuation.zig");
+pub const envelope = @import("envelope.zig");
+pub const grid = @import("grid.zig");
+pub const history = @import("history.zig");
+pub const hyperlink = @import("hyperlink.zig");
+pub const page = @import("page.zig");
+pub const record = @import("record.zig");
+pub const screen = @import("screen.zig");
+pub const style = @import("style.zig");
+pub const terminal = @import("terminal.zig");
+
+const codec = @import("snapshot.zig");
+pub const EncodeError = codec.EncodeError;
+pub const DecodeError = codec.DecodeError;
+pub const DecodeExactError = codec.DecodeExactError;
+pub const Continuation = codec.Continuation;
+pub const EncodeOptions = codec.EncodeOptions;
+pub const DecodeOptions = codec.DecodeOptions;
+pub const Decoded = codec.Decoded;
+pub const Decoder = codec.Decoder;
+pub const encode = codec.encode;
+pub const decode = codec.decode;
+pub const decodeExact = codec.decodeExact;
+
+test {
+ @import("std").testing.refAllDecls(@This());
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/page.zig b/vendor/libghostty-vt/src/terminal/snapshot/page.zig
new file mode 100644
index 00000000..6c8bb5ce
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/page.zig
@@ -0,0 +1,1828 @@
+//! PAGE record payload encoding.
+//!
+//! One PAGE record represents a set of rows/columns in the terminal.
+//! In libghostty, this happens to map internally to a very specific
+//! data structure called a "page" (hence the name), but consumers of
+//! the format don't need to reproduce that.
+//!
+//! The important thing is that one page is fully self-contained: it has
+//! a dimension (cols x rows), a set of styles, hyperlinks, cells, etc.
+//! and depends on no external state to decode that with some exceptions
+//! like assets such as images.
+//!
+//! A page could have a dimension that doesn't match the terminal
+//! dimensions, e.g. for lazy resize/reflow. Callers must be prepared for
+//! that.
+//!
+//! ## Binary Format
+//!
+//! Every PAGE payload begins with a fixed header, followed by a
+//! payload of styles, hyperlinks, and rows and columns.
+//!
+//! All integers are unsigned and little-endian.
+//!
+//! ### Header
+//!
+//! | Offset | Size | Field |
+//! | -----: | ---: | :--------------------------------- |
+//! | 0 | 2 | Logical columns (`u16`) |
+//! | 2 | 2 | Logical rows (`u16`) |
+//! | 4 | 2 | Non-default style count (`u16`) |
+//! | 6 | 2 | Unique hyperlink count (`u16`) |
+//! | 8 | 2 | Style capacity hint (`u16`) |
+//! | 10 | 2 | Hyperlink capacity bytes (`u16`) |
+//! | 12 | 4 | Grapheme capacity bytes (`u32`) |
+//! | 16 | 4 | String capacity bytes (`u32`) |
+//!
+//! The first two fields (columns and rows) denote the dimensionality
+//! of the page. The payload is guaranteed to have this dimensionality;
+//! every row has exactly the columns specified.
+//!
+//! Next, the style count and hyperlink count denote the number of
+//! styles and hyperlinks respectively that are sent with the page.
+//! The default style and absence of a hyperlink are implicit at native
+//! ID zero and are not included in these counts. Each encoded table entry
+//! carries its nonzero native page ID.
+//!
+//! The final four fields are allocation hints copied from the source page.
+//! These represent upper limits on what this page might contain. A decoder
+//! can optionally choose to use this for preallocation or it can ignore
+//! and decode and allocate dynamically.
+//!
+//! ### Payload
+//!
+//! ```text
+//! +---------------------------+
+//! | Header |
+//! | 20 bytes |
+//! +---------------------------+
+//! | Style table |
+//! | style_count entries |
+//! +---------------------------+
+//! | Hyperlink table |
+//! | hyperlink_count entries |
+//! +---------------------------+
+//! | Grid |
+//! | rows and grapheme section |
+//! +---------------------------+
+//!
+//! Style entry = encoded ID + style record
+//! Hyperlink entry = encoded ID + hyperlink record
+//! Grid = row 0 ... row (rows - 1) + grapheme suffix section
+//! Row = row header + encoded cells
+//! ```
+//!
+//! Following the header, the payload contains exactly `style_count` style
+//! records and `hyperlink_count` hyperlink records, followed by exactly
+//! `rows` row records and one grapheme suffix section. There is no padding
+//! between records.
+//!
+//! Each style begins with an ID (`u16`) followed by the typical style
+//! binary representation (in style.zig). The ID is what cells will use
+//! to reference the style. Decoders must maintain some kind of mapping
+//! in order to associate these properly.
+//!
+//! Each hyperlink also begins with an ID (`u16`) with the same semantics
+//! as the style ID. The hyperlink and style IDs are separate namespaces,
+//! so they may collide. Following the ID, the hyperlink binary format
+//! is encoded directly.
+//!
+//! Both style and hyperlink IDs are not guaranteed to be in any specific
+//! order and may contain gaps (e.g. ID 1 and 3 but not 2).
+//!
+//! Rows and cells use the grid encoding documented in `grid.zig`.
+
+const std = @import("std");
+const build_options = @import("terminal_options");
+const Allocator = std.mem.Allocator;
+const test_fixture = @import("fixture.zig");
+const grid = @import("grid.zig");
+const hyperlink = @import("hyperlink.zig");
+const io = @import("io.zig");
+const record = @import("record.zig");
+const style = @import("style.zig");
+const terminal_hyperlink = @import("../hyperlink.zig");
+const terminal_page = @import("../page.zig");
+const terminal_style = @import("../style.zig");
+
+// Frequent constants we use
+const TerminalHyperlink = terminal_hyperlink.Hyperlink;
+const TerminalHyperlinkId = terminal_hyperlink.Id;
+const TerminalHyperlinkPageEntry = terminal_hyperlink.PageEntry;
+const TerminalCell = terminal_page.Cell;
+const TerminalPage = terminal_page.Page;
+const TerminalPageCapacity = terminal_page.Capacity;
+const TerminalRow = terminal_page.Row;
+const TerminalStyle = terminal_style.Style;
+const TerminalStyleId = terminal_style.Id;
+
+const PayloadEncodeError = hyperlink.EncodeError || grid.EncodeError;
+
+const PayloadDecodeError = std.Io.Reader.Error ||
+ Header.CapacityError ||
+ grid.DecodeError ||
+ error{
+ /// The hyperlink kind is not defined by snapshot version 1.
+ InvalidKind,
+
+ /// Native page backing memory could not be allocated.
+ OutOfMemory,
+
+ /// The caller-provided page does not have the advertised capacity.
+ InvalidDestinationCapacity,
+ };
+
+/// Errors possible while encoding a complete PAGE record.
+pub const EncodeError = PayloadEncodeError || record.Writer.FinishError;
+
+/// Encode one complete PAGE record from a native page.
+///
+/// The payload is built in the stream's reusable record buffer. If payload
+/// encoding fails, no bytes from this record are emitted.
+pub fn encode(
+ page: *const TerminalPage,
+ destination: *record.Writer,
+) EncodeError!void {
+ const payload = destination.begin(.page);
+ errdefer destination.cancel();
+ try encodePayload(page, payload);
+ try destination.finish();
+}
+
+/// Errors possible while decoding and validating a complete PAGE record.
+pub const DecodeError = PayloadDecodeError ||
+ record.Reader.InitError ||
+ record.Reader.FinishError ||
+ TerminalPage.IntegrityError ||
+ error{
+ /// The next record is valid but is not a PAGE.
+ UnexpectedRecordTag,
+ };
+
+/// Decode and validate one complete PAGE record into a fresh native page.
+///
+/// The record tag, payload boundary, CRC32C, payload contents, and final page
+/// integrity are all validated before the page is returned. `alloc` is used
+/// only for temporary decode remaps and integrity-check storage.
+pub fn decode(
+ reader: *std.Io.Reader,
+ alloc: Allocator,
+) DecodeError!TerminalPage {
+ var decoder: Decoder = undefined;
+ try decoder.init(reader);
+
+ var page = TerminalPage.init(decoder.capacity()) catch
+ return error.OutOfMemory;
+ errdefer page.deinit();
+ try decoder.decode(&page, alloc);
+ return page;
+}
+
+/// PAGE record decoder where the caller is responsible for owning
+/// the Page memory. This is particularly useful paired with
+/// PageList.Builder so you can build up a proper PageList with
+/// valid memory ownership.
+pub const Decoder = struct {
+ record_reader: record.Reader,
+ header: Header,
+
+ /// Begin decoding one PAGE record and expose its required capacity.
+ /// After this, call `capacity` to get the capacity to allocate
+ /// the page properly, then `decode` into it.
+ pub fn init(self: *Decoder, reader: *std.Io.Reader) DecodeError!void {
+ try self.record_reader.init(reader);
+ if (self.record_reader.header.tag != .page) {
+ return error.UnexpectedRecordTag;
+ }
+
+ self.header = try Header.decode(self.record_reader.payloadReader());
+ _ = try self.header.pageCapacity();
+ }
+
+ /// Return the exact native capacity advertised by the PAGE header.
+ pub fn capacity(self: *const Decoder) TerminalPageCapacity {
+ return self.header.pageCapacity() catch unreachable;
+ }
+
+ /// Largest remaining PAGE payload staged into one contiguous buffer.
+ /// This comfortably covers every payload a standard-capacity page can
+ /// produce while keeping the allocation an untrusted length can force
+ /// far below the record framing's four-byte length limit.
+ const max_staged_payload = 8 * 1024 * 1024;
+
+ /// Decode the remaining payload into caller-owned native page storage.
+ ///
+ /// The destination must be freshly initialized with `capacity`. `alloc`
+ /// is used only for temporary staging, ID remaps, and integrity-check
+ /// storage.
+ pub fn decode(
+ self: *Decoder,
+ destination: *TerminalPage,
+ alloc: Allocator,
+ ) DecodeError!void {
+ if (!std.meta.eql(destination.capacity, self.capacity())) {
+ return error.InvalidDestinationCapacity;
+ }
+
+ destination.size = .{
+ .cols = self.header.columns,
+ .rows = self.header.rows,
+ };
+
+ // `init` consumed exactly the fixed header from the declared
+ // payload, so this is the byte count of the tables and grid.
+ const remaining = self.record_reader.header.payload_len - Header.len;
+
+ if (self.record_reader.payloadReader().bufferedLen() >= remaining) {
+ // The complete payload is already buffered, e.g. borrowed from
+ // an in-memory snapshot. Parse it in place with no staging
+ // copy; `finish` still enforces the CRC and exact exhaustion.
+ try decodePayloadBody(
+ self.record_reader.payloadReader(),
+ alloc,
+ destination,
+ self.header,
+ );
+ } else if (remaining <= max_staged_payload) {
+ // Stage the payload with one bulk read. The whole payload passes
+ // through the checksum hasher as one update and the payload
+ // decoders then parse a flat buffer, which keeps per-row work free
+ // of stream adapters. The CRC and exact-length checks in `finish`
+ // are unaffected.
+ const staged = try alloc.alloc(u8, remaining);
+ defer alloc.free(staged);
+ try self.record_reader.payloadReader().readSliceAll(staged);
+
+ var staged_reader: std.Io.Reader = .fixed(staged);
+ try decodePayloadBody(
+ &staged_reader,
+ alloc,
+ destination,
+ self.header,
+ );
+ if (staged_reader.bufferedLen() != 0) {
+ return error.PayloadNotExhausted;
+ }
+ } else {
+ // A payload this large is either hostile or a page far beyond
+ // native capacities. Decode it through the streaming payload
+ // reader so its declared length cannot force an allocation.
+ try decodePayloadBody(
+ self.record_reader.payloadReader(),
+ alloc,
+ destination,
+ self.header,
+ );
+ }
+ try self.record_reader.finish();
+
+ // The decoder normalizes every semantic value, so a complete decode
+ // upholds native page invariants by construction. Verifying them
+ // again is a defense against decoder bugs and follows the native
+ // page policy: full integrity verification only when slow runtime
+ // safety is enabled.
+ if (comptime build_options.slow_runtime_safety) {
+ try destination.verifyIntegrity(alloc);
+ }
+ }
+};
+
+/// Errors possible while discarding one PAGE record without decoding it.
+pub const DiscardError = record.Reader.InitError ||
+ record.Reader.FinishError ||
+ std.Io.Reader.Error ||
+ error{
+ /// The next record is valid but is not a PAGE.
+ UnexpectedRecordTag,
+ };
+
+/// Consume exactly one complete PAGE record, validating its framing and
+/// CRC32C while discarding the payload without structural validation.
+///
+/// This lets a decoder stay aligned with the record sequence while dropping
+/// page content it can no longer apply.
+pub fn discard(source: *std.Io.Reader) DiscardError!void {
+ var record_reader: record.Reader = undefined;
+ try record_reader.init(source);
+ if (record_reader.header.tag != .page) {
+ return error.UnexpectedRecordTag;
+ }
+ try record_reader.payloadReader().discardAll(
+ record_reader.header.payload_len,
+ );
+ try record_reader.finish();
+}
+
+/// Encode a PAGE payload directly from a native page.
+fn encodePayload(
+ page: *const TerminalPage,
+ writer: *std.Io.Writer,
+) PayloadEncodeError!void {
+ // Write header
+ try Header.init(page).encode(writer);
+
+ // Sparse styles
+ var style_it = page.styles.iterator(page.memory);
+ while (style_it.next()) |entry| {
+ try io.writeInt(writer, TerminalStyleId, entry.id);
+ try style.encode(entry.value_ptr.*, writer);
+ }
+
+ // Sparse hyperlinks
+ var hyperlink_it = page.hyperlink_set.iterator(page.memory);
+ while (hyperlink_it.next()) |entry| {
+ try io.writeInt(writer, TerminalHyperlinkId, entry.id);
+ try hyperlink.encode(pageHyperlink(page, entry.value_ptr), writer);
+ }
+
+ // Rows and cells
+ try grid.encode(page, writer);
+}
+
+/// Decode a PAGE payload directly into a fresh native page.
+///
+/// `alloc` is used only for the temporary native-ID remap tables. Styles,
+/// hyperlinks, strings, graphemes, rows, and cells are stored in the page.
+fn decodePayload(
+ reader: *std.Io.Reader,
+ alloc: Allocator,
+) PayloadDecodeError!TerminalPage {
+ const header = try Header.decode(reader);
+ const capacity = try header.pageCapacity();
+ var page = TerminalPage.init(capacity) catch
+ return error.OutOfMemory;
+ errdefer page.deinit();
+ try decodePayloadBody(reader, alloc, &page, header);
+ return page;
+}
+
+/// Decode PAGE tables and grid after the header into initialized native page
+/// storage with the exact advertised capacity and dimensions.
+fn decodePayloadBody(
+ reader: *std.Io.Reader,
+ alloc: Allocator,
+ page: *TerminalPage,
+ header: Header,
+) PayloadDecodeError!void {
+ page.pauseIntegrityChecks(true);
+ defer page.pauseIntegrityChecks(false);
+
+ // Pages without styles or hyperlinks, the common case for plain
+ // scrollback, skip the remap tables entirely: every encoded cell ID
+ // resolves to the default through the empty remap.
+ var style_remap: grid.StyleRemap = if (header.style_count > 0)
+ grid.StyleRemap.init(alloc) catch return error.OutOfMemory
+ else
+ .empty;
+ defer style_remap.deinit(alloc);
+
+ var hyperlink_remap: grid.HyperlinkRemap = if (header.hyperlink_count > 0)
+ grid.HyperlinkRemap.init(alloc) catch return error.OutOfMemory
+ else
+ .empty;
+ defer hyperlink_remap.deinit(alloc);
+
+ // Styles. The complete fixed-size entry is parsed from the buffered
+ // payload when possible so each entry costs no reader calls.
+ const style_entry_len = @sizeOf(TerminalStyleId) + style.len;
+ for (0..header.style_count) |_| {
+ const native_id: TerminalStyleId, const value = entry: {
+ if (reader.bufferedLen() >= style_entry_len) {
+ const bytes = reader.buffered()[0..style_entry_len];
+ defer reader.toss(style_entry_len);
+ break :entry .{
+ std.mem.readInt(TerminalStyleId, bytes[0..2], .little),
+ style.parseOrNull(bytes[2..][0..style.len]),
+ };
+ }
+ break :entry .{
+ try io.readInt(reader, TerminalStyleId),
+ try style.decodeOrNull(reader),
+ };
+ };
+
+ // Zero is reserved for the implicit default. For a duplicate encoded
+ // ID, the first entry wins and this complete entry is simply ignored.
+ if (native_id == 0 or style_remap.contains(native_id)) continue;
+
+ // Invalid/default styles map to the native default. `add` returns
+ // the existing entry for a repeated concrete value, taking one
+ // reference either way, while capacity failure degrades only this
+ // style. The references are surrendered through the remap below
+ // once every cell reference is installed.
+ const decoded_id: TerminalStyleId = if (value) |valid| decoded: {
+ if (valid.default()) break :decoded 0;
+ break :decoded page.styles.add(
+ page.memory,
+ valid,
+ ) catch 0;
+ } else 0;
+ style_remap.put(native_id, decoded_id);
+ }
+
+ // Hyperlinks
+ for (0..header.hyperlink_count) |_| {
+ const native_id = try io.readInt(reader, TerminalHyperlinkId);
+ const decoded_id = try hyperlink.decodePage(page, reader);
+
+ // As with styles, zero is reserved and the first duplicate encoded ID
+ // wins. Release any native entry reference created for an ignored ID.
+ if (native_id == 0 or hyperlink_remap.contains(native_id)) {
+ if (decoded_id != 0) {
+ page.hyperlink_set.release(page.memory, decoded_id);
+ }
+ continue;
+ }
+
+ // Zero records an ignored table entry. Grid decoding treats every
+ // reference to it as no hyperlink.
+ hyperlink_remap.put(native_id, decoded_id);
+ }
+
+ // Rows and cells
+ try grid.decode(
+ page,
+ reader,
+ &style_remap,
+ &hyperlink_remap,
+ );
+
+ // Every accepted table entry took one reference through `add` so grid
+ // decoding can safely attach its style to any number of cells. Unlike
+ // organically built pages, those references do not themselves represent
+ // cells. Release through the encoded-ID remap, so duplicate values
+ // which deduplicated to the same native ID each surrender their own
+ // reference; unused entries then become dead and disappear from
+ // canonical re-encoding.
+ var style_it = style_remap.seen.iterator(.{});
+ while (style_it.next()) |encoded_id| {
+ const id = style_remap.entries[encoded_id];
+ if (id != 0) page.styles.release(page.memory, id);
+ }
+
+ // Hyperlink insertion likewise creates one temporary reference for every
+ // accepted wire table entry. Release through the encoded-ID remap rather
+ // than the native set so duplicate values which deduplicated to the same
+ // native ID each surrender their own reference.
+ var hyperlink_it = hyperlink_remap.seen.iterator(.{});
+ while (hyperlink_it.next()) |encoded_id| {
+ const id = hyperlink_remap.entries[encoded_id];
+ if (id != 0) page.hyperlink_set.release(page.memory, id);
+ }
+}
+
+/// The fixed logical dimensions, table counts, and allocation hints at the
+/// start of PAGE.
+pub const Header = struct {
+ /// Number of bytes written by `encode`, calculated using the encoder itself
+ /// so this remains synchronized with the field-by-field wire format.
+ pub const len = computeLen();
+
+ comptime {
+ // This size is part of the wire format. If it changes, the snapshot
+ // version and golden fixtures must also change.
+ std.debug.assert(len == 20);
+ }
+
+ /// Number of logical cells in every encoded row.
+ columns: u16,
+
+ /// Number of logical rows encoded after the tables.
+ rows: u16,
+
+ /// Number of non-default style entries following the header.
+ style_count: u16,
+
+ /// Number of unique hyperlink entries following the style table.
+ hyperlink_count: u16,
+
+ /// Suggested capacity for the native non-default style set.
+ style_capacity: u16,
+
+ /// Suggested native hyperlink storage capacity in bytes.
+ hyperlink_capacity_bytes: u16,
+
+ /// Suggested native grapheme storage capacity in bytes.
+ grapheme_capacity_bytes: u32,
+
+ /// Suggested native string storage capacity in bytes.
+ string_capacity_bytes: u32,
+
+ /// Encode the fixed PAGE payload header.
+ pub fn encode(
+ self: Header,
+ writer: *std.Io.Writer,
+ ) std.Io.Writer.Error!void {
+ try io.writeInt(writer, u16, self.columns);
+ try io.writeInt(writer, u16, self.rows);
+ try io.writeInt(writer, u16, self.style_count);
+ try io.writeInt(writer, u16, self.hyperlink_count);
+ try io.writeInt(writer, u16, self.style_capacity);
+ try io.writeInt(writer, u16, self.hyperlink_capacity_bytes);
+ try io.writeInt(writer, u32, self.grapheme_capacity_bytes);
+ try io.writeInt(writer, u32, self.string_capacity_bytes);
+ }
+
+ /// Decode the fixed PAGE payload header.
+ ///
+ /// This reads field values only. The complete PAGE decoder is responsible
+ /// for applying configured limits before using any capacity hint.
+ pub fn decode(reader: *std.Io.Reader) std.Io.Reader.Error!Header {
+ return .{
+ .columns = try io.readInt(reader, u16),
+ .rows = try io.readInt(reader, u16),
+ .style_count = try io.readInt(reader, u16),
+ .hyperlink_count = try io.readInt(reader, u16),
+ .style_capacity = try io.readInt(reader, u16),
+ .hyperlink_capacity_bytes = try io.readInt(reader, u16),
+ .grapheme_capacity_bytes = try io.readInt(reader, u32),
+ .string_capacity_bytes = try io.readInt(reader, u32),
+ };
+ }
+
+ /// Initialize a header from the current contents of a native page.
+ ///
+ /// This copies the page's existing allocation capacities. It does not
+ /// scan cells, allocate, or encode any bytes.
+ fn init(page: *const TerminalPage) Header {
+ return .{
+ .columns = page.size.cols,
+ .rows = page.size.rows,
+ .style_count = @intCast(page.styles.count()),
+ .hyperlink_count = @intCast(page.hyperlink_set.count()),
+ .style_capacity = page.capacity.styles,
+ .hyperlink_capacity_bytes = page.capacity.hyperlink_bytes,
+ .grapheme_capacity_bytes = page.capacity.grapheme_bytes,
+ .string_capacity_bytes = page.capacity.string_bytes,
+ };
+ }
+
+ pub const CapacityError = error{
+ InvalidDimensions,
+ };
+
+ /// Validate native allocation requirements and produce the page capacity.
+ fn pageCapacity(self: Header) CapacityError!TerminalPageCapacity {
+ if (self.columns == 0 or self.rows == 0) {
+ return error.InvalidDimensions;
+ }
+
+ return .{
+ .cols = self.columns,
+ .rows = self.rows,
+ .styles = self.style_capacity,
+ .hyperlink_bytes = self.hyperlink_capacity_bytes,
+ .grapheme_bytes = self.grapheme_capacity_bytes,
+ .string_bytes = self.string_capacity_bytes,
+ };
+ }
+
+ fn computeLen() usize {
+ var buf: [128]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ const header: Header = .{
+ .columns = 0,
+ .rows = 0,
+ .style_count = 0,
+ .hyperlink_count = 0,
+ .style_capacity = 0,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ };
+ header.encode(&writer) catch unreachable;
+ return writer.end;
+ }
+};
+
+fn pageHyperlink(
+ page: *const TerminalPage,
+ entry: *const TerminalHyperlinkPageEntry,
+) TerminalHyperlink {
+ return .{
+ .id = switch (entry.id) {
+ .implicit => |value| .{ .implicit = value },
+ .explicit => |value| .{ .explicit = value.slice(page.memory) },
+ },
+ .uri = entry.uri.slice(page.memory),
+ };
+}
+
+const test_page_fixture = test_fixture.parse(@embedFile("testdata/page-v1.hex"));
+const test_header_fixture = test_fixture.parse(@embedFile("testdata/page-header-v1.hex"));
+const test_empty_framed_page_fixture = test_fixture.parse(@embedFile("testdata/page-empty-record-v1.hex"));
+
+test "PAGE header golden encoding and decoding" {
+ const header: Header = .{
+ .columns = 0x0102,
+ .rows = 0x0304,
+ .style_count = 0x0506,
+ .hyperlink_count = 0x0708,
+ .style_capacity = 0x090a,
+ .hyperlink_capacity_bytes = 0x0b0c,
+ .grapheme_capacity_bytes = 0x0d0e0f10,
+ .string_capacity_bytes = 0x11121314,
+ };
+ var buf: [Header.len]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ try header.encode(&writer);
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/page-header-v1.hex",
+ "snapshot_fixture-page-header-v1.hex",
+ &test_header_fixture,
+ writer.buffered(),
+ );
+
+ var source: std.Io.Reader = .fixed(&test_header_fixture);
+ var read_buf: [1]u8 = undefined;
+ var limited = source.limited(.unlimited, &read_buf);
+ try std.testing.expectEqual(header, try Header.decode(&limited.interface));
+}
+
+test "reject every truncation" {
+ for (0..Header.len) |len| {
+ var reader: std.Io.Reader = .fixed(test_header_fixture[0..len]);
+ try std.testing.expectError(error.EndOfStream, Header.decode(&reader));
+ }
+}
+
+test "framed PAGE encode and decode a sparse native page" {
+ const capacity: TerminalPageCapacity = .{
+ .cols = 3,
+ .rows = 2,
+ .styles = 8,
+ .hyperlink_bytes = 512,
+ .grapheme_bytes = 128,
+ .string_bytes = 256,
+ };
+ var page = try TerminalPage.init(capacity);
+ defer page.deinit();
+
+ // Create holes in both source tables so the encoded IDs exercise sparse
+ // table remapping rather than coincidentally matching decoded IDs.
+ const style_a = try page.styles.add(page.memory, .{
+ .flags = .{ .bold = true },
+ });
+ const dead_style = try page.styles.add(page.memory, .{
+ .flags = .{ .italic = true },
+ });
+ const style_b = try page.styles.add(page.memory, .{
+ .bg_color = .{ .palette = 42 },
+ });
+ page.styles.release(page.memory, dead_style);
+
+ const first = page.getRowAndCell(0, 0);
+ first.cell.style_id = style_a;
+ first.row.styled = true;
+
+ const second = page.getRowAndCell(1, 0);
+ second.cell.style_id = style_b;
+ second.row.styled = true;
+
+ const third = page.getRowAndCell(2, 0);
+ page.styles.use(page.memory, style_a);
+ third.cell.style_id = style_a;
+ third.row.styled = true;
+
+ const hyperlink_a = try page.insertHyperlink(.{
+ .id = .{ .explicit = "a" },
+ .uri = "alpha",
+ });
+ const dead_hyperlink = try page.insertHyperlink(.{
+ .id = .{ .explicit = "dead-id" },
+ .uri = "dead-uri",
+ });
+ const hyperlink_b = try page.insertHyperlink(.{
+ .id = .{ .implicit = 0x01020304 },
+ .uri = "beta",
+ });
+ page.hyperlink_set.release(page.memory, dead_hyperlink);
+
+ page.hyperlink_set.use(page.memory, hyperlink_a);
+ try page.setHyperlink(first.row, first.cell, hyperlink_a);
+ try page.setHyperlink(second.row, second.cell, hyperlink_b);
+ try page.setHyperlink(third.row, third.cell, hyperlink_a);
+
+ // Cover graphemes, wide-cell pairs, colors, protection, and semantic
+ // metadata in one compact two-row page.
+ const grapheme = page.getRowAndCell(0, 1);
+ grapheme.cell.* = .init('x');
+ try page.setGraphemes(
+ grapheme.row,
+ grapheme.cell,
+ &.{ 0x0301, 0x0302 },
+ );
+
+ first.cell.content = .{ .codepoint = .{ .data = 'A' } };
+ first.cell.wide = .wide;
+ first.cell.protected = true;
+ first.cell.semantic_content = .prompt;
+ first.row.semantic_prompt = .prompt;
+
+ second.cell.wide = .spacer_tail;
+ second.cell.semantic_content = .input;
+
+ third.cell.content_tag = .bg_color_palette;
+ third.cell.content = .{ .color_palette = .{ .data = 7 } };
+
+ const rgb = page.getRowAndCell(1, 1);
+ rgb.cell.content_tag = .bg_color_rgb;
+ rgb.cell.content = .{ .color_rgb = .{
+ .r = 0xaa,
+ .g = 0xbb,
+ .b = 0xcc,
+ } };
+ rgb.cell.protected = true;
+
+ const spacer_head = page.getRowAndCell(2, 1);
+ spacer_head.cell.wide = .spacer_head;
+ spacer_head.row.wrap = true;
+ spacer_head.row.wrap_continuation = true;
+ spacer_head.row.semantic_prompt = .prompt_continuation;
+
+ const header: Header = .{
+ .columns = 3,
+ .rows = 2,
+ .style_count = 2,
+ .hyperlink_count = 2,
+ .style_capacity = 8,
+ .hyperlink_capacity_bytes = 512,
+ .grapheme_capacity_bytes = 128,
+ .string_capacity_bytes = 256,
+ };
+ try std.testing.expectEqual(header, Header.init(&page));
+
+ // Lock the payload bytes and independently verify the counting writer sees
+ // the same encoded length.
+ var counter: std.Io.Writer.Discarding = .init(&.{});
+ try encodePayload(&page, &counter.writer);
+
+ var encoded: [512]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try encodePayload(&page, &writer);
+
+ try test_fixture.expectEqual(
+ .page,
+ "src/terminal/snapshot/testdata/page-v1.hex",
+ "snapshot_fixture-page-v1.hex",
+ &test_page_fixture,
+ writer.buffered(),
+ );
+ try std.testing.expectEqual(
+ @as(u64, test_page_fixture.len),
+ counter.count,
+ );
+
+ // Decode the checked-in reference rather than the just-generated bytes.
+ // A one-byte backing buffer exercises streaming reads across every field.
+ var source: std.Io.Reader = .fixed(&test_page_fixture);
+ var read_buf: [1]u8 = undefined;
+ var limited = source.limited(.unlimited, &read_buf);
+ var decoded = try decodePayload(
+ &limited.interface,
+ std.testing.allocator,
+ );
+ defer decoded.deinit();
+
+ try std.testing.expectEqual(header, Header.init(&decoded));
+ try decoded.verifyIntegrity(std.testing.allocator);
+
+ // Decoding compacts the sparse source IDs while preserving table values
+ // and all cell references through the remap tables.
+ var style_it = decoded.styles.iterator(decoded.memory);
+ const decoded_style_a = style_it.next().?;
+ try std.testing.expectEqual(@as(TerminalStyleId, 1), decoded_style_a.id);
+ try std.testing.expect((TerminalStyle{
+ .flags = .{ .bold = true },
+ }).eql(decoded_style_a.value_ptr.*));
+ const decoded_style_b = style_it.next().?;
+ try std.testing.expectEqual(@as(TerminalStyleId, 2), decoded_style_b.id);
+ try std.testing.expect((TerminalStyle{
+ .bg_color = .{ .palette = 42 },
+ }).eql(decoded_style_b.value_ptr.*));
+ try std.testing.expectEqual(null, style_it.next());
+ try std.testing.expectEqual(
+ @as(u16, 2),
+ decoded.styles.refCount(decoded.memory, decoded_style_a.id),
+ );
+ try std.testing.expectEqual(
+ @as(u16, 1),
+ decoded.styles.refCount(decoded.memory, decoded_style_b.id),
+ );
+
+ var hyperlink_it = decoded.hyperlink_set.iterator(decoded.memory);
+ const decoded_link_a = hyperlink_it.next().?;
+ try std.testing.expectEqual(@as(TerminalHyperlinkId, 1), decoded_link_a.id);
+ const decoded_hyperlink_a = pageHyperlink(&decoded, decoded_link_a.value_ptr);
+ try std.testing.expectEqualStrings("a", decoded_hyperlink_a.id.explicit);
+ try std.testing.expectEqualStrings("alpha", decoded_hyperlink_a.uri);
+ const decoded_link_b = hyperlink_it.next().?;
+ try std.testing.expectEqual(@as(TerminalHyperlinkId, 2), decoded_link_b.id);
+ const decoded_hyperlink_b = pageHyperlink(&decoded, decoded_link_b.value_ptr);
+ try std.testing.expectEqual(@as(u32, 0x01020304), decoded_hyperlink_b.id.implicit);
+ try std.testing.expectEqualStrings("beta", decoded_hyperlink_b.uri);
+ try std.testing.expectEqual(null, hyperlink_it.next());
+
+ const decoded_first = decoded.getRowAndCell(0, 0);
+ try std.testing.expectEqual(@as(TerminalStyleId, 1), decoded_first.cell.style_id);
+ try std.testing.expectEqual(
+ @as(TerminalHyperlinkId, 1),
+ decoded.lookupHyperlink(decoded_first.cell).?,
+ );
+
+ const decoded_second = decoded.getRowAndCell(1, 0);
+ try std.testing.expectEqual(@as(TerminalStyleId, 2), decoded_second.cell.style_id);
+ try std.testing.expectEqual(
+ @as(TerminalHyperlinkId, 2),
+ decoded.lookupHyperlink(decoded_second.cell).?,
+ );
+
+ // The first re-encode reflects compacted IDs; subsequent round trips must
+ // stabilize byte-for-byte.
+ var reencoded: [512]u8 = undefined;
+ var rewriter: std.Io.Writer = .fixed(&reencoded);
+ try encodePayload(&decoded, &rewriter);
+ try std.testing.expect(!std.mem.eql(
+ u8,
+ writer.buffered(),
+ rewriter.buffered(),
+ ));
+
+ var reencoded_reader: std.Io.Reader = .fixed(rewriter.buffered());
+ var decoded_again = try decodePayload(
+ &reencoded_reader,
+ std.testing.allocator,
+ );
+ defer decoded_again.deinit();
+ try decoded_again.verifyIntegrity(std.testing.allocator);
+
+ var reencoded_again: [512]u8 = undefined;
+ var rewriter_again: std.Io.Writer = .fixed(&reencoded_again);
+ try encodePayload(&decoded_again, &rewriter_again);
+ try std.testing.expectEqualStrings(
+ rewriter.buffered(),
+ rewriter_again.buffered(),
+ );
+}
+
+test "framed PAGE golden empty record" {
+ const capacity: TerminalPageCapacity = .{
+ .cols = 1,
+ .rows = 1,
+ .styles = 0,
+ .hyperlink_bytes = 0,
+ .grapheme_bytes = 0,
+ .string_bytes = 0,
+ };
+ var page = try TerminalPage.init(capacity);
+ defer page.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(&page, &stream);
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/page-empty-record-v1.hex",
+ "snapshot_fixture-page-empty-record-v1.hex",
+ &test_empty_framed_page_fixture,
+ destination.written(),
+ );
+
+ var source: std.Io.Reader = .fixed(&test_empty_framed_page_fixture);
+ var decoded = try decode(&source, std.testing.allocator);
+ defer decoded.deinit();
+ try std.testing.expectEqual(
+ Header.init(&page),
+ Header.init(&decoded),
+ );
+}
+
+test "framed PAGE rejects incomplete wide cells transactionally" {
+ const testing = std.testing;
+
+ // One column puts the wide cell at the row end. Two columns put an
+ // ordinary narrow cell after it. Neither case supplies a spacer tail.
+ for ([_]u16{ 1, 2 }) |columns| {
+ var page = try TerminalPage.init(.{
+ .cols = columns,
+ .rows = 1,
+ });
+ defer page.deinit();
+ const first = page.getRowAndCell(0, 0).cell;
+ first.* = .init('A');
+ first.wide = .wide;
+ if (columns > 1) {
+ page.getRowAndCell(1, 0).cell.* = .init('B');
+ }
+
+ var destination: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer destination.deinit();
+ try destination.writer.writeAll("prefix");
+ var stream: record.Writer = .init(
+ testing.allocator,
+ &destination.writer,
+ );
+ defer stream.deinit();
+ try testing.expectError(
+ error.InvalidWideCell,
+ encode(&page, &stream),
+ );
+ try testing.expectEqualStrings("prefix", destination.written());
+ }
+}
+
+test "framed PAGE rejects a different record tag" {
+ var wrong_tag = test_empty_framed_page_fixture;
+ std.mem.writeInt(
+ u16,
+ wrong_tag[0..2],
+ @intFromEnum(record.Tag.screen),
+ .little,
+ );
+ var reader: std.Io.Reader = .fixed(&wrong_tag);
+ try std.testing.expectError(
+ error.UnexpectedRecordTag,
+ decode(&reader, std.testing.allocator),
+ );
+}
+
+test "framed PAGE preserves following bytes" {
+ var source: std.Io.Reader = .fixed(
+ test_empty_framed_page_fixture ++ "next",
+ );
+ var decoded = try decode(&source, std.testing.allocator);
+ defer decoded.deinit();
+ try std.testing.expectEqualStrings("next", try source.take(4));
+}
+
+test "decode sparse page rejects every truncation" {
+ for (0..test_page_fixture.len) |len| {
+ var reader: std.Io.Reader = .fixed(test_page_fixture[0..len]);
+ try std.testing.expectError(
+ error.EndOfStream,
+ decodePayload(&reader, std.testing.allocator),
+ );
+ }
+}
+
+test "decode accepts unordered sparse style IDs and ignores zero" {
+ const header: Header = .{
+ .columns = 2,
+ .rows = 1,
+ .style_count = 2,
+ .hyperlink_count = 0,
+ .style_capacity = 8,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ };
+
+ var descending: [
+ Header.len +
+ 2 * (2 + style.len) +
+ 3 + 2 * 8 + 4
+ ]u8 = undefined;
+ var descending_writer: std.Io.Writer = .fixed(&descending);
+ try header.encode(&descending_writer);
+ try io.writeInt(&descending_writer, TerminalStyleId, 3);
+ try style.encode(.{ .flags = .{ .bold = true } }, &descending_writer);
+ try io.writeInt(&descending_writer, TerminalStyleId, 2);
+ try style.encode(.{ .flags = .{ .italic = true } }, &descending_writer);
+ try descending_writer.writeByte(@bitCast(grid.Row{ .cell_width = .eight }));
+ try io.writeInt(&descending_writer, u16, 2); // cell count
+ try io.writeInt(&descending_writer, u64, @bitCast(grid.Cell{
+ .content = 'A',
+ .style_id = 3,
+ }));
+ try io.writeInt(&descending_writer, u64, @bitCast(grid.Cell{
+ .content = 'B',
+ .style_id = 2,
+ }));
+ try io.writeInt(&descending_writer, u32, 0); // grapheme section
+
+ var descending_reader: std.Io.Reader = .fixed(
+ descending_writer.buffered(),
+ );
+ var decoded_descending = try decodePayload(
+ &descending_reader,
+ std.testing.allocator,
+ );
+ defer decoded_descending.deinit();
+ try std.testing.expectEqual(@as(usize, 2), decoded_descending.styles.count());
+ try std.testing.expectEqual(
+ @as(TerminalStyleId, 1),
+ decoded_descending.getRowAndCell(0, 0).cell.style_id,
+ );
+ try std.testing.expectEqual(
+ @as(TerminalStyleId, 2),
+ decoded_descending.getRowAndCell(1, 0).cell.style_id,
+ );
+
+ const one_header: Header = .{
+ .columns = 1,
+ .rows = 1,
+ .style_count = 1,
+ .hyperlink_count = 0,
+ .style_capacity = 8,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ };
+
+ var zero: [Header.len + 2 + style.len + 7]u8 = undefined;
+ var zero_writer: std.Io.Writer = .fixed(&zero);
+ try one_header.encode(&zero_writer);
+ try io.writeInt(&zero_writer, TerminalStyleId, 0);
+ try style.encode(.{ .flags = .{ .bold = true } }, &zero_writer);
+
+ var zero_grid = try TerminalPage.init(.{ .cols = 1, .rows = 1 });
+ defer zero_grid.deinit();
+ try grid.encode(&zero_grid, &zero_writer);
+
+ var zero_reader: std.Io.Reader = .fixed(zero_writer.buffered());
+ var decoded_zero = try decodePayload(
+ &zero_reader,
+ std.testing.allocator,
+ );
+ defer decoded_zero.deinit();
+ try std.testing.expectEqual(@as(usize, 0), decoded_zero.styles.count());
+}
+
+test "decode accepts unordered sparse hyperlink IDs" {
+ const header: Header = .{
+ .columns = 2,
+ .rows = 1,
+ .style_count = 0,
+ .hyperlink_count = 2,
+ .style_capacity = 0,
+ .hyperlink_capacity_bytes = 512,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 6,
+ };
+
+ const first: TerminalHyperlink = .{
+ .id = .{ .implicit = 1 },
+ .uri = "one",
+ };
+ const second: TerminalHyperlink = .{
+ .id = .{ .implicit = 2 },
+ .uri = "two",
+ };
+
+ var encoded: [
+ Header.len +
+ 2 * 14 +
+ 3 + 2 * 8 + 4
+ ]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try header.encode(&writer);
+ try io.writeInt(&writer, TerminalHyperlinkId, 3);
+ try hyperlink.encode(first, &writer);
+ try io.writeInt(&writer, TerminalHyperlinkId, 2);
+ try hyperlink.encode(second, &writer);
+ try writer.writeByte(@bitCast(grid.Row{ .cell_width = .eight }));
+ try io.writeInt(&writer, u16, 2); // cell count
+ try io.writeInt(&writer, u64, @bitCast(grid.Cell{
+ .content = 'A',
+ .hyperlink = true,
+ .hyperlink_id = 3,
+ }));
+ try io.writeInt(&writer, u64, @bitCast(grid.Cell{
+ .content = 'B',
+ .hyperlink = true,
+ .hyperlink_id = 2,
+ }));
+ try io.writeInt(&writer, u32, 0); // grapheme section
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ var decoded = try decodePayload(
+ &reader,
+ std.testing.allocator,
+ );
+ defer decoded.deinit();
+ try std.testing.expectEqual(
+ @as(usize, 2),
+ decoded.hyperlink_set.count(),
+ );
+ const first_id = decoded.lookupHyperlink(
+ decoded.getRowAndCell(0, 0).cell,
+ ).?;
+ const second_id = decoded.lookupHyperlink(
+ decoded.getRowAndCell(1, 0).cell,
+ ).?;
+ try std.testing.expectEqual(
+ @as(u16, 1),
+ decoded.hyperlink_set.refCount(decoded.memory, first_id),
+ );
+ try std.testing.expectEqual(
+ @as(u16, 1),
+ decoded.hyperlink_set.refCount(decoded.memory, second_id),
+ );
+ try std.testing.expectEqualStrings(
+ "one",
+ decoded.hyperlink_set.get(
+ decoded.memory,
+ first_id,
+ ).uri.slice(decoded.memory),
+ );
+ try std.testing.expectEqualStrings(
+ "two",
+ decoded.hyperlink_set.get(
+ decoded.memory,
+ second_id,
+ ).uri.slice(decoded.memory),
+ );
+}
+
+test "decode defaults missing sparse cell references" {
+ // An unknown style ID falls back to the default style.
+ const style_header: Header = .{
+ .columns = 1,
+ .rows = 1,
+ .style_count = 0,
+ .hyperlink_count = 0,
+ .style_capacity = 8,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ };
+
+ var style_encoded: [Header.len + 3 + 8 + 4]u8 = undefined;
+ var style_writer: std.Io.Writer = .fixed(&style_encoded);
+ try style_header.encode(&style_writer);
+ try style_writer.writeByte(0x30); // row flags, full cell width
+ try io.writeInt(&style_writer, u16, 1); // cell count
+ try io.writeInt(&style_writer, u64, @bitCast(grid.Cell{
+ .style_id = 1,
+ }));
+ try io.writeInt(&style_writer, u32, 0); // grapheme section
+
+ var style_reader: std.Io.Reader = .fixed(style_writer.buffered());
+ var style_page = try decodePayload(
+ &style_reader,
+ std.testing.allocator,
+ );
+ defer style_page.deinit();
+ try std.testing.expectEqual(
+ @as(TerminalStyleId, 0),
+ style_page.getRowAndCell(0, 0).cell.style_id,
+ );
+
+ // An unknown hyperlink ID likewise falls back to no hyperlink.
+ const hyperlink_header: Header = .{
+ .columns = 1,
+ .rows = 1,
+ .style_count = 0,
+ .hyperlink_count = 0,
+ .style_capacity = 0,
+ .hyperlink_capacity_bytes = 512,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ };
+
+ var hyperlink_encoded: [Header.len + 3 + 8 + 4]u8 = undefined;
+ var hyperlink_writer: std.Io.Writer = .fixed(&hyperlink_encoded);
+ try hyperlink_header.encode(&hyperlink_writer);
+ try hyperlink_writer.writeByte(0x30); // row flags, full cell width
+ try io.writeInt(&hyperlink_writer, u16, 1); // cell count
+ try io.writeInt(&hyperlink_writer, u64, @bitCast(grid.Cell{
+ .hyperlink = true,
+ .hyperlink_id = 1,
+ }));
+ try io.writeInt(&hyperlink_writer, u32, 0); // grapheme section
+
+ var hyperlink_reader: std.Io.Reader = .fixed(
+ hyperlink_writer.buffered(),
+ );
+ var hyperlink_page = try decodePayload(
+ &hyperlink_reader,
+ std.testing.allocator,
+ );
+ defer hyperlink_page.deinit();
+ const hyperlink_cell = hyperlink_page.getRowAndCell(0, 0).cell;
+ try std.testing.expect(!hyperlink_cell.hyperlink);
+ try std.testing.expectEqual(
+ null,
+ hyperlink_page.lookupHyperlink(hyperlink_cell),
+ );
+}
+
+test "decode normalizes invalid grid semantics" {
+ const header: Header = .{
+ .columns = 3,
+ .rows = 1,
+ .style_count = 0,
+ .hyperlink_count = 0,
+ .style_capacity = 0,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ };
+
+ var encoded: [Header.len + 3 + 3 * 8 + 4 + 10]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try header.encode(&writer);
+
+ // Preserve wrap while degrading the unknown semantic-prompt value to none
+ // and ignoring all reserved row bits.
+ try writer.writeByte(0xFD);
+ try io.writeInt(&writer, u16, 3);
+
+ // A text cell replaces an invalid Unicode scalar with U+FFFD while its
+ // reserved semantic content degrades to output.
+ try io.writeInt(&writer, u64, @bitCast(grid.Cell{
+ .content = 0xD800,
+ .semantic_content = 3,
+ }));
+
+ // A declared grapheme suffix cannot fit the advertised zero capacity,
+ // so decoding preserves the base character and drops the suffix.
+ try io.writeInt(&writer, u64, @bitCast(grid.Cell{
+ .kind = 1,
+ .content = 'x',
+ }));
+
+ // Reserved palette content bits do not obscure the valid low palette
+ // byte.
+ try io.writeInt(&writer, u64, @bitCast(grid.Cell{
+ .kind = 2,
+ .content = 0xFFFF07,
+ }));
+
+ // The grapheme section carries the suffix for the second cell.
+ try io.writeInt(&writer, u32, 1);
+ try io.writeInt(&writer, u16, 0);
+ try io.writeInt(&writer, u16, 1);
+ try io.writeInt(&writer, u16, 1);
+ try io.writeInt(&writer, u32, 0x0301);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ var page = try decodePayload(&reader, std.testing.allocator);
+ defer page.deinit();
+ try page.verifyIntegrity(std.testing.allocator);
+
+ const first = page.getRowAndCell(0, 0);
+ try std.testing.expect(first.row.wrap);
+ try std.testing.expectEqual(
+ terminal_page.Row.SemanticPrompt.none,
+ first.row.semantic_prompt,
+ );
+ try std.testing.expectEqual(@as(u21, 0xFFFD), first.cell.codepoint());
+ try std.testing.expectEqual(
+ terminal_page.Cell.Wide.narrow,
+ first.cell.wide,
+ );
+ try std.testing.expectEqual(
+ terminal_page.Cell.SemanticContent.output,
+ first.cell.semantic_content,
+ );
+ try std.testing.expect(!first.cell.protected);
+ try std.testing.expect(!first.cell.hasGrapheme());
+
+ const second = page.getRowAndCell(1, 0).cell;
+ try std.testing.expectEqual(@as(u21, 'x'), second.codepoint());
+ try std.testing.expect(!second.hasGrapheme());
+
+ const third = page.getRowAndCell(2, 0).cell;
+ try std.testing.expectEqual(
+ terminal_page.Cell.ContentTag.bg_color_palette,
+ third.content_tag,
+ );
+ try std.testing.expectEqual(
+ @as(u8, 7),
+ third.content.color_palette.data,
+ );
+ try std.testing.expect(!third.hasGrapheme());
+}
+
+test "decode validates dimensions" {
+ const cases = [_]Header{
+ .{
+ .columns = 0,
+ .rows = 24,
+ .style_count = 0,
+ .hyperlink_count = 0,
+ .style_capacity = 0,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ },
+ .{
+ .columns = 80,
+ .rows = 0,
+ .style_count = 0,
+ .hyperlink_count = 0,
+ .style_capacity = 0,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ },
+ };
+
+ for (cases) |header| {
+ var encoded: [Header.len]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try header.encode(&writer);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ try std.testing.expectError(
+ error.InvalidDimensions,
+ decodePayload(&reader, std.testing.allocator),
+ );
+ }
+}
+
+test "decode propagates a style table read failure" {
+ const FailOnceReader = struct {
+ source: std.Io.Reader,
+ interface: std.Io.Reader,
+ bytes_before_failure: usize,
+ failed: bool = false,
+
+ fn init(bytes: []const u8, bytes_before_failure: usize) @This() {
+ return .{
+ .source = .fixed(bytes),
+ .interface = .{
+ .vtable = &.{ .stream = stream },
+ .buffer = &.{},
+ .seek = 0,
+ .end = 0,
+ },
+ .bytes_before_failure = bytes_before_failure,
+ };
+ }
+
+ fn stream(
+ reader: *std.Io.Reader,
+ writer: *std.Io.Writer,
+ limit: std.Io.Limit,
+ ) std.Io.Reader.StreamError!usize {
+ const self: *@This() = @fieldParentPtr("interface", reader);
+ if (self.bytes_before_failure == 0 and !self.failed) {
+ self.failed = true;
+ return error.ReadFailed;
+ }
+
+ const read_limit = if (self.failed)
+ limit
+ else
+ limit.min(.limited(self.bytes_before_failure));
+ const n = try self.source.stream(writer, read_limit);
+ if (!self.failed) self.bytes_before_failure -= n;
+ return n;
+ }
+ };
+
+ const header: Header = .{
+ .columns = 1,
+ .rows = 1,
+ .style_count = 1,
+ .hyperlink_count = 0,
+ .style_capacity = 8,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ };
+
+ // If the style read error is swallowed, its sixteen zero bytes are then
+ // misread as a valid empty grid and the unframed payload appears to decode.
+ var encoded: [Header.len + @sizeOf(TerminalStyleId) + style.len]u8 =
+ @splat(0);
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try header.encode(&writer);
+ try io.writeInt(&writer, TerminalStyleId, 1);
+ try writer.splatByteAll(0, style.len);
+
+ var source = FailOnceReader.init(
+ writer.buffered(),
+ Header.len + @sizeOf(TerminalStyleId),
+ );
+ var decoded = decodePayload(
+ &source.interface,
+ std.testing.allocator,
+ ) catch |err| {
+ try std.testing.expectEqual(error.ReadFailed, err);
+ return;
+ };
+ defer decoded.deinit();
+ try std.testing.expect(false);
+}
+
+test "decode normalizes duplicate default and invalid style entries" {
+ const header: Header = .{
+ .columns = 1,
+ .rows = 1,
+ .style_count = 2,
+ .hyperlink_count = 0,
+ .style_capacity = 16,
+ .hyperlink_capacity_bytes = 512,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 256,
+ };
+ const duplicate_style: TerminalStyle = .{
+ .flags = .{ .bold = true },
+ };
+
+ // Generate a valid grid whose cell references a sparse style ID. The PAGE
+ // table below can then give that ID duplicate, default, or invalid contents
+ // without hand-authoring the cell wire format.
+ var grid_page = try TerminalPage.init(.{
+ .cols = 1,
+ .rows = 1,
+ .styles = 8,
+ });
+ defer grid_page.deinit();
+ const released_style_a = try grid_page.styles.add(
+ grid_page.memory,
+ .{ .flags = .{ .italic = true } },
+ );
+ const released_style_b = try grid_page.styles.add(
+ grid_page.memory,
+ .{ .bg_color = .{ .palette = 1 } },
+ );
+ const encoded_style_id = try grid_page.styles.add(
+ grid_page.memory,
+ duplicate_style,
+ );
+ grid_page.styles.release(grid_page.memory, released_style_a);
+ grid_page.styles.release(grid_page.memory, released_style_b);
+ const grid_cell = grid_page.getRowAndCell(0, 0);
+ grid_cell.cell.* = .init('A');
+ grid_cell.cell.style_id = encoded_style_id;
+ grid_cell.row.styled = true;
+
+ var grid_bytes: [64]u8 = undefined;
+ var grid_writer: std.Io.Writer = .fixed(&grid_bytes);
+ try grid.encode(&grid_page, &grid_writer);
+
+ var encoded: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer encoded.deinit();
+ try header.encode(&encoded.writer);
+ try io.writeInt(&encoded.writer, TerminalStyleId, 1);
+ try style.encode(duplicate_style, &encoded.writer);
+ try io.writeInt(&encoded.writer, TerminalStyleId, encoded_style_id);
+ try style.encode(duplicate_style, &encoded.writer);
+ try encoded.writer.writeAll(grid_writer.buffered());
+
+ var reader: std.Io.Reader = .fixed(encoded.written());
+ var duplicate_decoded = try decodePayload(
+ &reader,
+ std.testing.allocator,
+ );
+ defer duplicate_decoded.deinit();
+ try std.testing.expectEqual(@as(usize, 1), duplicate_decoded.styles.count());
+ const duplicate_cell = duplicate_decoded.getRowAndCell(0, 0).cell;
+ try std.testing.expect(duplicate_cell.style_id != 0);
+ try std.testing.expect(
+ duplicate_decoded.styles.get(
+ duplicate_decoded.memory,
+ duplicate_cell.style_id,
+ ).flags.bold,
+ );
+
+ const default_header: Header = .{
+ .columns = 1,
+ .rows = 1,
+ .style_count = 1,
+ .hyperlink_count = 0,
+ .style_capacity = 16,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ };
+ var default_encoded: std.Io.Writer.Allocating = .init(
+ std.testing.allocator,
+ );
+ defer default_encoded.deinit();
+ try default_header.encode(&default_encoded.writer);
+ try io.writeInt(
+ &default_encoded.writer,
+ TerminalStyleId,
+ encoded_style_id,
+ );
+ try style.encode(.{}, &default_encoded.writer);
+ try default_encoded.writer.writeAll(grid_writer.buffered());
+
+ var default_reader: std.Io.Reader = .fixed(default_encoded.written());
+ var default_decoded = try decodePayload(
+ &default_reader,
+ std.testing.allocator,
+ );
+ defer default_decoded.deinit();
+ try std.testing.expectEqual(
+ @as(TerminalStyleId, 0),
+ default_decoded.getRowAndCell(0, 0).cell.style_id,
+ );
+
+ // The strict style codec rejects this kind, but PAGE owns the fixed entry
+ // boundary and can safely map the encoded ID to the default style. A zero
+ // capacity hint also remains advisory.
+ var invalid_header = default_header;
+ invalid_header.style_capacity = 0;
+ var invalid_encoded: std.Io.Writer.Allocating = .init(
+ std.testing.allocator,
+ );
+ defer invalid_encoded.deinit();
+ try invalid_header.encode(&invalid_encoded.writer);
+ try io.writeInt(
+ &invalid_encoded.writer,
+ TerminalStyleId,
+ encoded_style_id,
+ );
+ try invalid_encoded.writer.writeByte(3);
+ try invalid_encoded.writer.splatByteAll(0, style.len - 1);
+ try invalid_encoded.writer.writeAll(grid_writer.buffered());
+
+ var invalid_reader: std.Io.Reader = .fixed(invalid_encoded.written());
+ var invalid_decoded = try decodePayload(
+ &invalid_reader,
+ std.testing.allocator,
+ );
+ defer invalid_decoded.deinit();
+ try std.testing.expectEqual(
+ @as(TerminalStyleId, 0),
+ invalid_decoded.getRowAndCell(0, 0).cell.style_id,
+ );
+}
+
+test "decode releases unused style table references" {
+ const header: Header = .{
+ .columns = 1,
+ .rows = 1,
+ .style_count = 1,
+ .hyperlink_count = 0,
+ .style_capacity = 8,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ };
+
+ var empty_page = try TerminalPage.init(.{ .cols = 1, .rows = 1 });
+ defer empty_page.deinit();
+ var grid_bytes: [32]u8 = undefined;
+ var grid_writer: std.Io.Writer = .fixed(&grid_bytes);
+ try grid.encode(&empty_page, &grid_writer);
+
+ var encoded: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer encoded.deinit();
+ try header.encode(&encoded.writer);
+ try io.writeInt(&encoded.writer, TerminalStyleId, 7);
+ try style.encode(.{ .flags = .{ .bold = true } }, &encoded.writer);
+ try encoded.writer.writeAll(grid_writer.buffered());
+
+ var reader: std.Io.Reader = .fixed(encoded.written());
+ var decoded = try decodePayload(&reader, std.testing.allocator);
+ defer decoded.deinit();
+ try std.testing.expectEqual(@as(usize, 0), decoded.styles.count());
+
+ // The dead table-only entry is absent from the very first re-encode.
+ var canonical: [64]u8 = undefined;
+ var canonical_writer: std.Io.Writer = .fixed(&canonical);
+ try encodePayload(&decoded, &canonical_writer);
+ var canonical_reader: std.Io.Reader = .fixed(canonical_writer.buffered());
+ const canonical_header = try Header.decode(&canonical_reader);
+ try std.testing.expectEqual(@as(u16, 0), canonical_header.style_count);
+}
+
+test "decode reuses duplicate hyperlinks" {
+ const header: Header = .{
+ .columns = 1,
+ .rows = 1,
+ .style_count = 0,
+ .hyperlink_count = 2,
+ .style_capacity = 0,
+ .hyperlink_capacity_bytes = 512,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 16,
+ };
+ const duplicate: TerminalHyperlink = .{
+ .id = .{ .explicit = "id" },
+ .uri = "uri",
+ };
+
+ // As with styles above, use a sparse native ID to make grid.encode produce
+ // the cell reference whose table value this test deliberately duplicates.
+ var grid_page = try TerminalPage.init(.{
+ .cols = 1,
+ .rows = 1,
+ .hyperlink_bytes = 512,
+ .string_bytes = 64,
+ });
+ defer grid_page.deinit();
+ const released_hyperlink_a = try grid_page.insertHyperlink(.{
+ .id = .{ .implicit = 1 },
+ .uri = "one",
+ });
+ const released_hyperlink_b = try grid_page.insertHyperlink(.{
+ .id = .{ .implicit = 2 },
+ .uri = "two",
+ });
+ const encoded_hyperlink_id = try grid_page.insertHyperlink(.{
+ .id = .{ .implicit = 3 },
+ .uri = "three",
+ });
+ grid_page.hyperlink_set.release(
+ grid_page.memory,
+ released_hyperlink_a,
+ );
+ grid_page.hyperlink_set.release(
+ grid_page.memory,
+ released_hyperlink_b,
+ );
+ const grid_cell = grid_page.getRowAndCell(0, 0);
+ grid_cell.cell.* = .init('A');
+ try grid_page.setHyperlink(
+ grid_cell.row,
+ grid_cell.cell,
+ encoded_hyperlink_id,
+ );
+
+ var grid_bytes: [64]u8 = undefined;
+ var grid_writer: std.Io.Writer = .fixed(&grid_bytes);
+ try grid.encode(&grid_page, &grid_writer);
+
+ var encoded: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer encoded.deinit();
+ try header.encode(&encoded.writer);
+ try io.writeInt(&encoded.writer, TerminalHyperlinkId, 1);
+ try hyperlink.encode(duplicate, &encoded.writer);
+ try io.writeInt(
+ &encoded.writer,
+ TerminalHyperlinkId,
+ encoded_hyperlink_id,
+ );
+ try hyperlink.encode(duplicate, &encoded.writer);
+ try encoded.writer.writeAll(grid_writer.buffered());
+
+ var reader: std.Io.Reader = .fixed(encoded.written());
+ var decoded = try decodePayload(
+ &reader,
+ std.testing.allocator,
+ );
+ defer decoded.deinit();
+ try std.testing.expectEqual(@as(usize, 1), decoded.hyperlink_set.count());
+ const cell = decoded.getRowAndCell(0, 0).cell;
+ try std.testing.expect(cell.hyperlink);
+ const id = decoded.lookupHyperlink(cell).?;
+ const entry = decoded.hyperlink_set.get(decoded.memory, id);
+ try std.testing.expectEqual(
+ @as(u16, 1),
+ decoded.hyperlink_set.refCount(decoded.memory, id),
+ );
+ try std.testing.expectEqualStrings(
+ "uri",
+ entry.uri.slice(decoded.memory),
+ );
+
+ // Overwriting the sole linked cell must make the deduplicated entry dead.
+ // Any surviving reference belongs to the decode-time wire table, not the
+ // native page.
+ decoded.clearCells(decoded.getRow(0), 0, 1);
+ try std.testing.expectEqual(@as(usize, 0), decoded.hyperlink_set.count());
+}
+
+test "discard consumes exactly one PAGE record" {
+ const testing = std.testing;
+
+ // Discard validates framing only, so an arbitrary payload keeps this test
+ // focused on record consumption rather than page structure.
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ var stream: record.Writer = .init(testing.allocator, &encoded.writer);
+ defer stream.deinit();
+ {
+ const payload = stream.begin(.page);
+ errdefer stream.cancel();
+ try payload.writeAll("undecodable page payload");
+ try stream.finish();
+ }
+ const record_len = encoded.written().len;
+ try encoded.writer.writeAll("next");
+
+ var source: std.Io.Reader = .fixed(encoded.written());
+ try discard(&source);
+ try testing.expectEqualStrings("next", try source.take(4));
+
+ // Only PAGE records may be discarded; the tag remains strict.
+ var wrong_tag: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer wrong_tag.deinit();
+ var wrong_tag_stream: record.Writer = .init(
+ testing.allocator,
+ &wrong_tag.writer,
+ );
+ defer wrong_tag_stream.deinit();
+ {
+ const payload = wrong_tag_stream.begin(.history);
+ errdefer wrong_tag_stream.cancel();
+ try payload.writeAll("payload");
+ try wrong_tag_stream.finish();
+ }
+ var wrong_tag_source: std.Io.Reader = .fixed(wrong_tag.written());
+ try testing.expectError(
+ error.UnexpectedRecordTag,
+ discard(&wrong_tag_source),
+ );
+
+ // Discarded bytes are still covered by the record CRC.
+ const corrupted = try testing.allocator.dupe(
+ u8,
+ encoded.written()[0..record_len],
+ );
+ defer testing.allocator.free(corrupted);
+ corrupted[corrupted.len - 1] ^= 1;
+ var corrupted_source: std.Io.Reader = .fixed(corrupted);
+ try testing.expectError(error.InvalidChecksum, discard(&corrupted_source));
+
+ // A truncated payload is detected before `finish`.
+ var truncated_source: std.Io.Reader = .fixed(
+ encoded.written()[0 .. record_len - 1],
+ );
+ try testing.expectError(error.EndOfStream, discard(&truncated_source));
+}
+
+test "decode ignores empty hyperlink strings" {
+ const header: Header = .{
+ .columns = 1,
+ .rows = 1,
+ .style_count = 0,
+ .hyperlink_count = 1,
+ .style_capacity = 0,
+ .hyperlink_capacity_bytes = 0,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 16,
+ };
+ const fixtures = [_][]const u8{
+ // Empty implicit URI.
+ "\x01\x01\x00\x00\x00\x00\x00\x00\x00",
+ // Empty explicit ID.
+ "\x02\x00\x00\x00\x00\x03\x00\x00\x00uri",
+ // Empty explicit URI.
+ "\x02\x02\x00\x00\x00id\x00\x00\x00\x00",
+ // Valid contents that cannot fit the zero-capacity native set.
+ "\x01\x01\x00\x00\x00\x03\x00\x00\x00uri",
+ };
+
+ // Only the invalid hyperlink entry itself is hand-authored above. Generate
+ // its cell reference through the native grid encoder.
+ var grid_page = try TerminalPage.init(.{
+ .cols = 1,
+ .rows = 1,
+ .hyperlink_bytes = 256,
+ .string_bytes = 16,
+ });
+ defer grid_page.deinit();
+ const encoded_hyperlink_id = try grid_page.insertHyperlink(.{
+ .id = .{ .implicit = 1 },
+ .uri = "uri",
+ });
+ const grid_cell = grid_page.getRowAndCell(0, 0);
+ grid_cell.cell.* = .init('A');
+ try grid_page.setHyperlink(
+ grid_cell.row,
+ grid_cell.cell,
+ encoded_hyperlink_id,
+ );
+ var grid_bytes: [64]u8 = undefined;
+ var grid_writer: std.Io.Writer = .fixed(&grid_bytes);
+ try grid.encode(&grid_page, &grid_writer);
+
+ for (fixtures) |fixture| {
+ var encoded: std.Io.Writer.Allocating = .init(
+ std.testing.allocator,
+ );
+ defer encoded.deinit();
+ try header.encode(&encoded.writer);
+ try io.writeInt(
+ &encoded.writer,
+ TerminalHyperlinkId,
+ encoded_hyperlink_id,
+ );
+ try encoded.writer.writeAll(fixture);
+
+ // The cell refers to the ignored table entry. Its absent native
+ // remapping must degrade to no hyperlink while preserving the cell.
+ try encoded.writer.writeAll(grid_writer.buffered());
+
+ var reader: std.Io.Reader = .fixed(encoded.written());
+ var decoded = try decodePayload(
+ &reader,
+ std.testing.allocator,
+ );
+ defer decoded.deinit();
+
+ try std.testing.expectEqual(
+ @as(usize, 0),
+ decoded.hyperlink_set.count(),
+ );
+ const cell = decoded.getRowAndCell(0, 0).cell;
+ try std.testing.expectEqual(@as(u21, 'A'), cell.codepoint());
+ try std.testing.expect(!cell.hyperlink);
+ try std.testing.expectEqual(null, decoded.lookupHyperlink(cell));
+ }
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/record.zig b/vendor/libghostty-vt/src/terminal/snapshot/record.zig
new file mode 100644
index 00000000..397d00cb
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/record.zig
@@ -0,0 +1,601 @@
+//! Snapshot record framing.
+//!
+//! Records begin immediately after the single snapshot envelope and continue
+//! back-to-back until FINISH. Each record has one fixed-size header followed
+//! by exactly `payload_len` bytes. The payload length limits the record reader
+//! so malformed payloads cannot consume bytes from the following record.
+//!
+//! The CRC covers the first six header bytes (tag and payload length)
+//! followed by the payload. The CRC field itself is not included for obvious
+//! reasons. All integers are unsigned and little-endian.
+//!
+//! | Offset | Size | Field |
+//! | -----: | ------------: | :--------------------- |
+//! | 0 | 2 | Tag (`u16`) |
+//! | 2 | 4 | Payload length (`u32`) |
+//! | 6 | 4 | CRC32C (`u32`) |
+//! | 10 | `payload_len` | Payload |
+//!
+//! Supported tags are in `Tag`.
+
+const std = @import("std");
+const assert = std.debug.assert;
+const Allocator = std.mem.Allocator;
+const test_fixture = @import("fixture.zig");
+const io = @import("io.zig");
+
+/// CRC32C as specified by the snapshot format. This is the parameter set
+/// Zig's standard library names after its iSCSI use, backed by dedicated
+/// CRC32C instructions where the target has them.
+pub const Crc32c = @import("../../crc32c.zig").Crc32c;
+
+/// Identifies the layout and meaning of a record payload.
+/// The current snapshot version rejects every value not listed here.
+pub const Tag = enum(u16) {
+ /// Terminal-wide live state and configuration.
+ terminal = 1,
+
+ /// One live screen and its page sequence.
+ screen = 2,
+
+ /// One complete logical terminal page.
+ page = 3,
+
+ /// One screen's complete history manifest and page sequence.
+ history = 4,
+
+ /// Marker separating the renderable terminal state from history.
+ ready = 5,
+
+ /// Marker terminating the complete snapshot blob.
+ finish = 6,
+
+ /// Canonical unfinished standard TerminalStream input.
+ continuation = 7,
+};
+
+/// The fixed framing that precedes every record payload.
+pub const Header = struct {
+ /// Number of bytes written by `encode`, calculated using the encoder itself
+ /// so this remains synchronized with the field-by-field wire format.
+ pub const len = computeLen();
+
+ comptime {
+ // This size is part of the wire format. If it changes, the snapshot
+ // version and golden fixtures must also change.
+ assert(len == 10);
+ }
+
+ /// Determines how the payload is decoded.
+ tag: Tag,
+
+ /// Number of payload bytes immediately following this header.
+ payload_len: u32,
+
+ /// CRC32C over the encoded tag, payload length, and payload.
+ crc32c: u32,
+
+ /// Errors possible while decoding a record header.
+ pub const DecodeError = std.Io.Reader.Error || error{InvalidTag};
+
+ /// Encode the fixed record header.
+ pub fn encode(
+ self: Header,
+ writer: *std.Io.Writer,
+ ) std.Io.Writer.Error!void {
+ try encodeChecksumPrefix(self.tag, self.payload_len, writer);
+ try io.writeInt(writer, u32, self.crc32c);
+ }
+
+ /// Decode a fixed record header and reject unknown tags.
+ /// Payload length and CRC validation occur while decoding the payload.
+ pub fn decode(reader: *std.Io.Reader) DecodeError!Header {
+ const tag_raw = try io.readInt(reader, u16);
+ const tag = std.enums.fromInt(Tag, tag_raw) orelse {
+ return error.InvalidTag;
+ };
+
+ return .{
+ .tag = tag,
+ .payload_len = try io.readInt(reader, u32),
+ .crc32c = try io.readInt(reader, u32),
+ };
+ }
+
+ /// Computes the required header length at comptime.
+ fn computeLen() usize {
+ comptime {
+ var buf: [128]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ const header: Header = .{
+ .tag = .terminal,
+ .payload_len = 0,
+ .crc32c = 0,
+ };
+ header.encode(&writer) catch unreachable;
+ return writer.end;
+ }
+ }
+};
+
+/// A writer that calculates a record checksum without retaining payload bytes.
+/// The checksum is initialized with the encoded tag and payload length.
+pub const Checksum = struct {
+ hashing: std.Io.Writer.Hashing(Crc32c),
+
+ /// Begin a checksum with the encoded tag and payload length already added.
+ pub fn init(tag: Tag, payload_len: u32) Checksum {
+ var result: Checksum = .{
+ .hashing = .initHasher(.init(), &.{}),
+ };
+ encodeChecksumPrefix(
+ tag,
+ payload_len,
+ &result.hashing.writer,
+ ) catch unreachable;
+ return result;
+ }
+
+ /// Return the writer through which the complete payload must be encoded.
+ pub fn writer(self: *Checksum) *std.Io.Writer {
+ return &self.hashing.writer;
+ }
+
+ /// Finish and return the checksum stored in the record header.
+ pub fn final(self: *Checksum) u32 {
+ self.hashing.writer.flush() catch unreachable;
+ return self.hashing.hasher.final();
+ }
+};
+
+/// Streams complete records while retaining only one payload at a time.
+///
+/// The scratch allocation is retained between records so a stream's peak
+/// memory is the largest record payload rather than the complete snapshot.
+pub const Writer = struct {
+ destination: *std.Io.Writer,
+ scratch: std.Io.Writer.Allocating,
+ active_tag: ?Tag,
+
+ pub fn init(
+ alloc: Allocator,
+ destination: *std.Io.Writer,
+ ) Writer {
+ return .{
+ .destination = destination,
+ .scratch = .init(alloc),
+ .active_tag = null,
+ };
+ }
+
+ pub fn deinit(self: *Writer) void {
+ assert(self.active_tag == null);
+ assert(self.scratch.writer.end == 0);
+ self.scratch.deinit();
+ self.* = undefined;
+ }
+
+ /// Return the destination writer for unframed snapshot bytes.
+ pub fn writer(self: *Writer) *std.Io.Writer {
+ assert(self.active_tag == null);
+ return self.destination;
+ }
+
+ /// Begin one record and return its reusable payload writer.
+ pub fn begin(self: *Writer, tag: Tag) *std.Io.Writer {
+ assert(self.active_tag == null);
+ assert(self.scratch.writer.end == 0);
+ self.active_tag = tag;
+ return &self.scratch.writer;
+ }
+
+ pub const FinishError = std.Io.Writer.Error || error{
+ /// The payload cannot be represented by the record's `u32` length.
+ PayloadTooLarge,
+ };
+
+ /// Finish and emit the active record's header followed by its payload.
+ ///
+ /// Payload validation failures occur before this function and emit no part
+ /// of the record. A destination failure here may have emitted a prefix.
+ pub fn finish(self: *Writer) FinishError!void {
+ assert(self.active_tag != null);
+ const tag = self.active_tag.?;
+ defer self.cancel();
+
+ const payload = self.scratch.written();
+ const payload_len = std.math.cast(
+ u32,
+ payload.len,
+ ) orelse return error.PayloadTooLarge;
+
+ // The CRC prefix contains the payload length, so checksum the retained
+ // payload only after its final length is known.
+ var checksum: Checksum = .init(tag, payload_len);
+ checksum.writer().writeAll(payload) catch unreachable;
+
+ const header: Header = .{
+ .tag = tag,
+ .payload_len = payload_len,
+ .crc32c = checksum.final(),
+ };
+ var header_bytes: [Header.len]u8 = undefined;
+ var header_writer: std.Io.Writer = .fixed(&header_bytes);
+ header.encode(&header_writer) catch unreachable;
+
+ try self.destination.writeAll(&header_bytes);
+ try self.destination.writeAll(payload);
+ }
+
+ /// Discard the active record without emitting any bytes.
+ ///
+ /// This is idempotent so an outer error cleanup may call it after `finish`
+ /// has already cleared state following a destination failure.
+ pub fn cancel(self: *Writer) void {
+ self.scratch.shrinkRetainingCapacity(0);
+ self.active_tag = null;
+ }
+};
+
+/// Reads one complete record.
+///
+/// `init` decodes the header, `payloadReader` returns a reader limited to the
+/// declared payload, and `finish` verifies exact exhaustion and the CRC32C.
+pub const Reader = struct {
+ header: Header,
+
+ // The limited reader normally streams directly into the checksum reader's
+ // buffer. One byte is enough for operations that require it to buffer,
+ // such as peek and discard.
+ limited_buffer: [1]u8,
+
+ // Fixed-header decoding performs several small reads. 256 bytes batches
+ // them while CRC32C is calculated without making Reader large on the
+ // stack. Bulk payload reads bypass this buffer entirely.
+ hashing_buffer: [256]u8,
+
+ limited: std.Io.Reader.Limited,
+ hashing: std.Io.Reader.Hashed(Crc32c),
+
+ /// When the source already has the complete payload buffered, for
+ /// example an in-memory snapshot, the payload is borrowed straight
+ /// from the source buffer instead of streaming through the limited
+ /// and hashing adapters. The checksum is then verified with one bulk
+ /// update in `finish`, and the source is not advanced until `finish`.
+ borrowed: ?Borrowed,
+
+ const Borrowed = struct {
+ source: *std.Io.Reader,
+ payload: std.Io.Reader,
+ };
+
+ pub const InitError = Header.DecodeError;
+
+ /// Errors detected after a payload decoder returns.
+ pub const FinishError = error{
+ /// The payload bytes do not match the CRC in the record header.
+ InvalidChecksum,
+
+ /// The decoder did not consume exactly `payload_len` bytes.
+ PayloadNotExhausted,
+ };
+
+ /// Decode a record header and initialize its payload reader.
+ ///
+ /// `self` must remain at a stable address until `finish` returns. Decode
+ /// the payload only through the reader returned by `payloadReader`.
+ pub fn init(
+ self: *Reader,
+ source: *std.Io.Reader,
+ ) InitError!void {
+ self.* = undefined;
+ self.header = try Header.decode(source);
+
+ // The complete payload is already sitting in the source buffer:
+ // borrow it in place. Payload decoders read from a fixed reader
+ // over the borrowed bytes and `finish` checksums them in one pass.
+ if (source.bufferedLen() >= self.header.payload_len) {
+ self.borrowed = .{
+ .source = source,
+ .payload = .fixed(
+ source.buffered()[0..self.header.payload_len],
+ ),
+ };
+ return;
+ }
+
+ self.borrowed = null;
+ self.limited = .init(
+ source,
+ .limited(self.header.payload_len),
+ &self.limited_buffer,
+ );
+
+ const checksum: Checksum = .init(
+ self.header.tag,
+ self.header.payload_len,
+ );
+ self.hashing = .init(
+ &self.limited.interface,
+ checksum.hashing.hasher,
+ &self.hashing_buffer,
+ );
+ }
+
+ /// Return the length-limited, checksum-updating payload reader.
+ pub fn payloadReader(self: *Reader) *std.Io.Reader {
+ if (self.borrowed) |*borrowed| return &borrowed.payload;
+ return &self.hashing.reader;
+ }
+
+ /// Require exact payload exhaustion and validate its CRC32C.
+ pub fn finish(self: *Reader) FinishError!void {
+ if (self.borrowed) |*borrowed| {
+ if (borrowed.payload.bufferedLen() != 0) {
+ return error.PayloadNotExhausted;
+ }
+
+ var checksum: Checksum = .init(
+ self.header.tag,
+ self.header.payload_len,
+ );
+ checksum.writer().writeAll(
+ borrowed.payload.buffer[0..borrowed.payload.end],
+ ) catch unreachable;
+ if (checksum.final() != self.header.crc32c) {
+ return error.InvalidChecksum;
+ }
+
+ // The borrowed bytes validated, so consume them from the
+ // source only now, leaving it positioned at the next record.
+ borrowed.source.toss(self.header.payload_len);
+ return;
+ }
+
+ if (self.hashing.reader.bufferedLen() != 0 or
+ self.limited.remaining != .nothing)
+ {
+ return error.PayloadNotExhausted;
+ }
+
+ if (self.hashing.hasher.final() != self.header.crc32c) {
+ return error.InvalidChecksum;
+ }
+ }
+};
+
+/// Encode the portion of a record header covered by CRC32C.
+fn encodeChecksumPrefix(
+ tag: Tag,
+ payload_len: u32,
+ writer: *std.Io.Writer,
+) std.Io.Writer.Error!void {
+ try io.writeInt(writer, u16, @intFromEnum(tag));
+ try io.writeInt(writer, u32, payload_len);
+}
+
+const test_page_header_fixture = test_fixture.parse(
+ @embedFile("testdata/record-page-header-v1.hex"),
+);
+
+test "golden PAGE record header and checksum" {
+ const page_header =
+ "\x50\x00\x18\x00\x00\x00\x00\x00" ++
+ "\x00\x00\x00\x00\x00\x00\x00\x00" ++
+ "\x00\x00\x00\x00\x00\x00\x00\x00";
+
+ var checksum: Checksum = .init(.page, page_header.len);
+ try checksum.writer().writeAll(page_header);
+ try std.testing.expectEqual(@as(u32, 0x7178441b), checksum.final());
+
+ const header: Header = .{
+ .tag = .page,
+ .payload_len = page_header.len,
+ .crc32c = 0x7178441b,
+ };
+ var buf: [Header.len]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ try header.encode(&writer);
+
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/record-page-header-v1.hex",
+ "snapshot_fixture-record-page-header-v1.hex",
+ &test_page_header_fixture,
+ writer.buffered(),
+ );
+
+ var reader: std.Io.Reader = .fixed(&test_page_header_fixture);
+ try std.testing.expectEqual(header, try Header.decode(&reader));
+}
+
+test "reject invalid tags" {
+ for ([_]u16{ 0, 8, std.math.maxInt(u16) }) |tag| {
+ var fixture = [_]u8{0} ** Header.len;
+ std.mem.writeInt(u16, fixture[0..2], tag, .little);
+ var reader: std.Io.Reader = .fixed(&fixture);
+ try std.testing.expectError(error.InvalidTag, Header.decode(&reader));
+ }
+}
+
+test "reject every header truncation" {
+ for (0..Header.len) |len| {
+ var reader: std.Io.Reader = .fixed(
+ test_page_header_fixture[0..len],
+ );
+ try std.testing.expectError(error.EndOfStream, Header.decode(&reader));
+ }
+}
+
+test "record reader verifies exhaustion and checksum" {
+ const payload = "snapshot payload";
+ var checksum: Checksum = .init(.page, payload.len);
+ try checksum.writer().writeAll(payload);
+ const header: Header = .{
+ .tag = .page,
+ .payload_len = payload.len,
+ .crc32c = checksum.final(),
+ };
+
+ var encoded: [Header.len + payload.len + 4]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try header.encode(&writer);
+ try writer.writeAll(payload ++ "next");
+
+ var source: std.Io.Reader = .fixed(writer.buffered());
+ var record_reader: Reader = undefined;
+ try record_reader.init(&source);
+ var decoded: [payload.len]u8 = undefined;
+ try record_reader.payloadReader().readSliceAll(&decoded);
+ try record_reader.finish();
+ try std.testing.expectEqualStrings(payload, &decoded);
+ try std.testing.expectEqualStrings("next", try source.take(4));
+}
+
+test "record reader rejects remaining bytes and invalid checksum" {
+ const payload = "payload";
+ const header: Header = .{
+ .tag = .page,
+ .payload_len = payload.len,
+ .crc32c = 0,
+ };
+
+ var encoded: [Header.len + payload.len]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try header.encode(&writer);
+ try writer.writeAll(payload);
+
+ {
+ var source: std.Io.Reader = .fixed(writer.buffered());
+ var record_reader: Reader = undefined;
+ try record_reader.init(&source);
+ _ = try record_reader.payloadReader().takeByte();
+ try std.testing.expectError(
+ error.PayloadNotExhausted,
+ record_reader.finish(),
+ );
+ }
+
+ {
+ var source: std.Io.Reader = .fixed(writer.buffered());
+ var record_reader: Reader = undefined;
+ try record_reader.init(&source);
+ try record_reader.payloadReader().discardAll(payload.len);
+ try std.testing.expectError(
+ error.InvalidChecksum,
+ record_reader.finish(),
+ );
+ }
+}
+
+test "payload limit does not consume the next record" {
+ const payload = "ab";
+ var checksum: Checksum = .init(.page, payload.len);
+ try checksum.writer().writeAll(payload);
+ const header: Header = .{
+ .tag = .page,
+ .payload_len = payload.len,
+ .crc32c = checksum.final(),
+ };
+
+ var encoded: [Header.len + payload.len + 4]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try header.encode(&writer);
+ try writer.writeAll(payload ++ "next");
+
+ var source: std.Io.Reader = .fixed(writer.buffered());
+ var record_reader: Reader = undefined;
+ try record_reader.init(&source);
+ var too_long: [3]u8 = undefined;
+ try std.testing.expectError(
+ error.EndOfStream,
+ record_reader.payloadReader().readSliceAll(&too_long),
+ );
+ try record_reader.finish();
+ try std.testing.expectEqualStrings("next", try source.take(4));
+}
+
+test "record writer buffers a payload and appends framing" {
+ var destination: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer destination.deinit();
+ try destination.writer.writeAll("prefix");
+ var stream: Writer = .init(
+ std.testing.allocator,
+ &destination.writer,
+ );
+ defer stream.deinit();
+
+ const payload = stream.begin(.page);
+ errdefer stream.cancel();
+ try payload.writeAll("payload");
+ try stream.finish();
+
+ const encoded = destination.written();
+ try std.testing.expectEqualStrings("prefix", encoded[0..6]);
+
+ var source: std.Io.Reader = .fixed(encoded[6..]);
+ var record_reader: Reader = undefined;
+ try record_reader.init(&source);
+ try std.testing.expectEqual(Tag.page, record_reader.header.tag);
+ try std.testing.expectEqual(
+ @as(u32, 7),
+ record_reader.header.payload_len,
+ );
+ try std.testing.expectEqualStrings(
+ "payload",
+ try record_reader.payloadReader().take(7),
+ );
+ try record_reader.finish();
+}
+
+test "record writer cancel preserves preceding bytes" {
+ var destination: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer destination.deinit();
+ try destination.writer.writeAll("prefix");
+ var stream: Writer = .init(
+ std.testing.allocator,
+ &destination.writer,
+ );
+ defer stream.deinit();
+
+ const partial = stream.begin(.page);
+ errdefer stream.cancel();
+ try partial.writeAll("partial");
+ const scratch_capacity = stream.scratch.writer.buffer.len;
+ stream.cancel();
+
+ try std.testing.expectEqualStrings("prefix", destination.written());
+ try std.testing.expectEqual(
+ scratch_capacity,
+ stream.scratch.writer.buffer.len,
+ );
+
+ // Cancel retains the allocation but leaves it ready for the next record.
+ const next = stream.begin(.page);
+ try next.writeAll("next");
+ try stream.finish();
+
+ var source: std.Io.Reader = .fixed(destination.written()[6..]);
+ var record_reader: Reader = undefined;
+ try record_reader.init(&source);
+ try std.testing.expectEqualStrings(
+ "next",
+ try record_reader.payloadReader().take(4),
+ );
+ try record_reader.finish();
+}
+
+test "record writer clears active state after destination failure" {
+ // The header fits but the payload does not, leaving a permitted partial
+ // record in the destination while the reusable writer becomes idle again.
+ var destination_bytes: [Header.len]u8 = undefined;
+ var destination: std.Io.Writer = .fixed(&destination_bytes);
+ var stream: Writer = .init(std.testing.allocator, &destination);
+ defer stream.deinit();
+
+ const payload = stream.begin(.page);
+ try payload.writeByte(0);
+ try std.testing.expectError(error.WriteFailed, stream.finish());
+ try std.testing.expectEqual(@as(?Tag, null), stream.active_tag);
+ try std.testing.expectEqual(@as(usize, 0), stream.scratch.writer.end);
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/screen.zig b/vendor/libghostty-vt/src/terminal/snapshot/screen.zig
new file mode 100644
index 00000000..d4ef16f7
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/screen.zig
@@ -0,0 +1,2460 @@
+//! SCREEN record payload encoding.
+//!
+//! One SCREEN record represents the live state for one terminal screen. The
+//! record is followed immediately by the number of complete PAGE records
+//! declared by `page_count`. They are the minimal suffix of native pages needed
+//! to cover the active area and are ordered from oldest to newest. A decoder
+//! uses the declared count, rather than another record tag, to find the end of
+//! the screen's page sequence.
+//!
+//! The final screen-height rows are the active area. When its boundary falls
+//! inside the first encoded page, that page also contains an incidental history
+//! prefix. `history_rows` declares the complete logical history extent so a
+//! client can size its scrollbar at READY without waiting for HISTORY. A client
+//! may expose or ignore the resident overlap carried by SCREEN. The extent is
+//! advisory; native row totals remain derived from decoded PAGE records.
+//!
+//! Screen dimensions are terminal-wide state and are not repeated here. Page
+//! capacities, native page IDs and pointers, history availability, selection,
+//! viewport, dirty state, and derived semantic-prompt state are also omitted.
+//!
+//! All integers are unsigned and little-endian.
+//!
+//! ## Binary Format
+//!
+//! A SCREEN record is followed immediately by its declared PAGE records:
+//!
+//! ```text
+//! +----------------------+
+//! | SCREEN record |
+//! +----------------------+
+//! | PAGE record 0 |
+//! +----------------------+
+//! | ... |
+//! +----------------------+
+//! | PAGE record (n - 1) |
+//! +----------------------+
+//!
+//! n = page_count
+//! ```
+//!
+//! The HISTORY record for this screen declares and sends the older complete
+//! pages after the terminal becomes ready. The incidental prefix is already
+//! present in SCREEN and is not sent again.
+//!
+//! The SCREEN payload begins with a fixed header. When the header says there is
+//! no saved cursor, the payload is:
+//!
+//! ```text
+//! 0 +----------------------+
+//! | Header |
+//! 53 +----------------------+
+//! | Cursor hyperlink |
+//! | variable |
+//! end +----------------------+
+//! ```
+//!
+//! When a saved cursor is present, it is inserted before the cursor hyperlink:
+//!
+//! ```text
+//! 0 +----------------------+
+//! | Header |
+//! 53 +----------------------+
+//! | Saved cursor |
+//! 76 +----------------------+
+//! | Cursor hyperlink |
+//! | variable |
+//! end +----------------------+
+//! ```
+//!
+//! The cursor hyperlink begins with a one-byte kind. Zero means no hyperlink
+//! and has no following bytes. Kinds one and two use the implicit and explicit
+//! hyperlink encodings documented in `hyperlink.zig`.
+//!
+//! ### Header
+//!
+//! ```text
+//! 0 +----------------------------------+
+//! | Screen key (u16) |
+//! 2 +----------------------------------+
+//! | Page count (u16) |
+//! 4 +----------------------------------+
+//! | Logical history rows (u64) |
+//! 12 +----------------------------------+
+//! | Cursor x (u16) |
+//! 14 +----------------------------------+
+//! | Cursor y (u16) |
+//! 16 +----------------------------------+
+//! | Cursor visual style (u8) |
+//! 17 +----------------------------------+
+//! | Cursor flags (u8) |
+//! 18 +----------------------------------+
+//! | Concrete cursor pen (Style) |
+//! 34 +----------------------------------+
+//! | Hyperlink implicit counter (u32) |
+//! 38 +----------------------------------+
+//! | Current charset (CharsetState) |
+//! 40 +----------------------------------+
+//! | Protected mode (u8) |
+//! 41 +----------------------------------+
+//! | Kitty keyboard stack index (u8) |
+//! 42 +----------------------------------+
+//! | Kitty keyboard stack flags |
+//! | 8 * u8 |
+//! 50 +----------------------------------+
+//! | Semantic-click kind (u8) |
+//! 51 +----------------------------------+
+//! | Semantic-click value (u8) |
+//! 52 +----------------------------------+
+//! | Saved-cursor-present (u8) |
+//! 53 +----------------------------------+
+//! ```
+//!
+//! The concrete cursor pen uses the fixed style encoding from `style.zig`.
+//!
+//! ### Cursor flags
+//!
+//! ```text
+//! bit 0 +--------------------------------+
+//! | Pending wrap |
+//! bit 1 +--------------------------------+
+//! | Protected |
+//! bit 2 +--------------------------------+
+//! | Semantic content |
+//! | 2 bits |
+//! bit 4 +--------------------------------+
+//! | Semantic-content-clear-EOL |
+//! bit 5 +--------------------------------+
+//! | Reserved, zero |
+//! | 3 bits |
+//! bit 8 +--------------------------------+
+//! ```
+//!
+//! ### Charset state
+//!
+//! The current and saved cursor charset states share this packed layout:
+//!
+//! ```text
+//! bit 0 +-------------------------------+
+//! | G0 charset |
+//! | 2 bits |
+//! bit 2 +-------------------------------+
+//! | G1 charset |
+//! | 2 bits |
+//! bit 4 +-------------------------------+
+//! | G2 charset |
+//! | 2 bits |
+//! bit 6 +-------------------------------+
+//! | G3 charset |
+//! | 2 bits |
+//! bit 8 +-------------------------------+
+//! | GL slot |
+//! | 2 bits |
+//! bit 10 +-------------------------------+
+//! | GR slot |
+//! | 2 bits |
+//! bit 12 +-------------------------------+
+//! | Single shift |
+//! | 3 bits |
+//! bit 15 +-------------------------------+
+//! | Reserved, zero |
+//! bit 16 +-------------------------------+
+//! ```
+//!
+//! The Kitty keyboard stack contains its current index followed by all eight
+//! flag entries, including disabled entries.
+//!
+//! ### Saved cursor
+//!
+//! ```text
+//! 0 +-----------------------------+
+//! | Saved cursor x (u16) |
+//! 2 +-----------------------------+
+//! | Saved cursor y (u16) |
+//! 4 +-----------------------------+
+//! | Saved cursor pen (Style) |
+//! 20 +-----------------------------+
+//! | Saved cursor flags (u8) |
+//! 21 +-----------------------------+
+//! | Saved charset state |
+//! 23 +-----------------------------+
+//! ```
+//!
+//! ### Saved cursor flags
+//!
+//! ```text
+//! bit 0 +---------------------------+
+//! | Protected |
+//! bit 1 +---------------------------+
+//! | Pending wrap |
+//! bit 2 +---------------------------+
+//! | Origin |
+//! bit 3 +---------------------------+
+//! | Reserved, zero |
+//! | 5 bits |
+//! bit 8 +---------------------------+
+//! ```
+//!
+//! Native enum values used below are stable terminal registries. Their wire
+//! widths are fixed independently by this payload. Changing those values or
+//! any packed bit assignment requires a snapshot version bump.
+
+const std = @import("std");
+const build_options = @import("terminal_options");
+const Allocator = std.mem.Allocator;
+const hyperlink = @import("hyperlink.zig");
+const test_fixture = @import("fixture.zig");
+const io = @import("io.zig");
+const grid = @import("grid.zig");
+const page = @import("page.zig");
+const record = @import("record.zig");
+const style = @import("style.zig");
+const terminal_ansi = @import("../ansi.zig");
+const terminal_charsets = @import("../charsets.zig");
+const terminal_hyperlink = @import("../hyperlink.zig");
+const terminal_kitty = @import("../kitty.zig");
+const terminal_osc = @import("../osc.zig");
+const terminal_page = @import("../page.zig");
+const TerminalPageList = @import("../PageList.zig");
+const TerminalScreen = @import("../Screen.zig");
+const TerminalScreenKey = @import("../ScreenSet.zig").Key;
+const terminal_style = @import("../style.zig");
+
+const TerminalHyperlink = terminal_hyperlink.Hyperlink;
+const TerminalStyle = terminal_style.Style;
+
+/// Errors possible while encoding fixed SCREEN payload fields.
+const PayloadEncodeError = hyperlink.EncodeError || error{
+ InvalidCursorFlags,
+ InvalidCharsetState,
+ InvalidKittyKeyboardIndex,
+ InvalidKittyKeyboardFlags,
+ InvalidSavedCursorFlags,
+};
+
+/// Errors possible while encoding a SCREEN and its complete PAGE sequence.
+pub const EncodeError = Allocator.Error || PayloadEncodeError || page.EncodeError || error{
+ /// The active area spans more pages than the SCREEN header can declare.
+ PageCountOverflow,
+};
+
+/// Encode one SCREEN and its minimal suffix of complete native pages.
+///
+/// The suffix begins with the page containing the active area's first row and
+/// ends with the newest page. Completed records may already be emitted if a
+/// later record fails; the missing READY marker makes that prefix invalid.
+pub fn encode(
+ screen: *const TerminalScreen,
+ key: TerminalScreenKey,
+ destination: *record.Writer,
+) EncodeError!void {
+ // The active top may fall inside this page, leaving an incidental history
+ // prefix. Every earlier complete page is history and is omitted.
+ const first = screen.pages.getTopLeft(.active).node;
+ var page_count: usize = 0;
+ var node: ?@TypeOf(first) = first;
+ while (node) |current| : (node = current.next) page_count += 1;
+ const encoded_page_count = std.math.cast(
+ u16,
+ page_count,
+ ) orelse return error.PageCountOverflow;
+
+ // SCREEN declares exactly how many immediately following PAGE records
+ // belong to it.
+ {
+ const payload = destination.begin(.screen);
+ errdefer destination.cancel();
+ try encodePayload(
+ screen,
+ key,
+ encoded_page_count,
+ payload,
+ );
+ try destination.finish();
+ }
+
+ // Active pages are resident today, but use the representation-safe access
+ // path so a future PageList compression-policy change cannot turn this
+ // wire encoder's optimization invariant into undefined behavior.
+ node = first;
+ while (node) |current| : (node = current.next) {
+ var preserved = try current.pagePreservingState(screen.alloc);
+ defer preserved.deinit();
+ try page.encode(preserved.page(), destination);
+ }
+}
+
+/// Errors possible while restoring a SCREEN and its declared PAGE sequence.
+pub const DecodeError = PayloadDecodeError ||
+ page.DecodeError ||
+ record.Reader.InitError ||
+ record.Reader.FinishError ||
+ TerminalPageList.Builder.FinishError ||
+ TerminalPageList.IncreaseCapacityError ||
+ error{
+ /// The next record is valid but is not a SCREEN.
+ UnexpectedRecordTag,
+
+ /// A SCREEN must declare at least one PAGE.
+ InvalidPageCount,
+ };
+
+/// One decoded SCREEN sequence and the native screen identified by its header.
+pub const Decoded = struct {
+ key: TerminalScreenKey,
+ /// Expected history extent at READY, including resident SCREEN overlap.
+ history_rows: u64,
+ screen: TerminalScreen,
+
+ /// Release the decoded native screen before ownership is transferred.
+ pub fn deinit(self: *Decoded) void {
+ self.screen.deinit();
+ self.* = undefined;
+ }
+};
+
+/// Restore one SCREEN and its declared PAGE records into native terminal state.
+///
+/// The caller supplies terminal-wide dimensions and policy. The record sequence
+/// is decoded transactionally: on failure, all page, pin, hyperlink, and
+/// temporary allocations are released and no partially restored Screen escapes.
+/// The returned key selects the ScreenSet slot that owns the decoded screen.
+pub fn decode(
+ source: *std.Io.Reader,
+ io_: std.Io,
+ alloc: Allocator,
+ options: TerminalScreen.Options,
+) DecodeError!Decoded {
+ // Decode and finish the self-contained SCREEN record before consuming any
+ // of the PAGE records which follow it.
+ var record_reader: record.Reader = undefined;
+ try record_reader.init(source);
+ if (record_reader.header.tag != .screen) {
+ return error.UnexpectedRecordTag;
+ }
+
+ // The optional saved cursor and cursor hyperlink are both part of the
+ // SCREEN payload. Keep ownership of the decoded hyperlink locally until it
+ // has been copied into the native Screen.
+ const payload_reader = record_reader.payloadReader();
+ const header = try Header.decode(payload_reader);
+ const saved_cursor = if (header.saved_cursor_present)
+ try SavedCursor.decode(payload_reader)
+ else
+ null;
+ var cursor_hyperlink = try decodeCursorHyperlink(
+ payload_reader,
+ alloc,
+ );
+ defer if (cursor_hyperlink) |*value| value.deinit(alloc);
+ try record_reader.finish();
+
+ const key = header.key;
+ if (header.page_count == 0) return error.InvalidPageCount;
+
+ // Dimensions are terminal-wide state supplied by the enclosing snapshot.
+ // Validate them, and all cursor invariants which depend on them, before
+ // allocating the declared pages.
+ if (options.cols == 0 or options.rows == 0) {
+ return error.InvalidDimensions;
+ }
+
+ // Build the native page list transactionally. Alternate screens never
+ // retain scrollback, while primary screens inherit the caller's limits.
+ var result: TerminalScreen = result: {
+ var builder = try TerminalPageList.Builder.init(alloc, .{
+ .cols = options.cols,
+ .rows = options.rows,
+ .max_size = if (key == .alternate)
+ 0
+ else
+ options.max_scrollback_bytes,
+ .max_lines = if (key == .alternate)
+ 0
+ else
+ options.max_scrollback_lines,
+ });
+ defer builder.deinit();
+
+ // Allocate each PAGE at its declared capacity and decode directly into
+ // builder-owned storage, avoiding an intermediate page representation.
+ for (0..header.page_count) |_| {
+ var decoder: page.Decoder = undefined;
+ try decoder.init(source);
+ const native_page = try builder.allocatePage(decoder.capacity());
+ try decoder.decode(native_page, alloc);
+ }
+
+ // Finishing validates that the decoded suffix covers the active area
+ // and establishes the PageList's active viewport.
+ var pages = try builder.finish();
+ errdefer pages.deinit();
+
+ // Convert the payload-relative cursor position into the tracked native
+ // pin and page-local row/cell pointers required by TerminalScreen.
+ const cursor: TerminalScreen.Cursor = cursor: {
+ const y = @min(header.cursor_y, options.rows - 1);
+
+ // The active area can temporarily contain mixed-width pages after
+ // a reflow. Locate the row at column zero, then clamp the encoded
+ // x coordinate to the width of that physical page.
+ const row_pin = pages.pin(.{ .active = .{ .y = y } }) orelse unreachable;
+ const x = @min(header.cursor_x, row_pin.node.cols() - 1);
+ const pin = try pages.trackPin(.{
+ .node = row_pin.node,
+ .x = x,
+ .y = row_pin.y,
+ });
+ const rac = pin.rowAndCell();
+
+ break :cursor .{
+ .x = x,
+ .y = y,
+ .cursor_style = header.cursor_style,
+ .pending_wrap = header.cursor_flags.pending_wrap and
+ x == row_pin.node.cols() - 1,
+ .protected = header.cursor_flags.protected,
+ .style = header.cursor_pen,
+ .hyperlink_implicit_id = header.hyperlink_implicit_id,
+ .semantic_content = header.cursor_flags.semantic_content,
+ .semantic_content_clear_eol = header.cursor_flags
+ .semantic_content_clear_eol,
+ .page_pin = pin,
+ .page_row = rac.row,
+ .page_cell = rac.cell,
+ };
+ };
+
+ // Assemble the remaining native state from stable snapshot registries.
+ // Derived state and page-local table references are repaired below.
+ break :result .{
+ .io = io_,
+ .alloc = alloc,
+ .pages = pages,
+ .no_scrollback = key == .alternate or
+ options.max_scrollback_bytes == 0,
+ .cursor = cursor,
+ .saved_cursor = if (saved_cursor) |value|
+ value.terminal(options.cols, options.rows)
+ else
+ null,
+ .charset = header.charset,
+ .protected_mode = header.protected_mode,
+ .kitty_keyboard = header.kitty_keyboard.terminal(),
+ .semantic_prompt = .{
+ .seen = false,
+ .click = header.semantic_click,
+ },
+ };
+ };
+ errdefer result.deinit();
+
+ // Reinsert the concrete cursor style into its page-local style table. This
+ // existing Screen path grows or splits the page when the decoded table is
+ // already full.
+ try result.manualStyleUpdate();
+
+ // Reinsert the cursor hyperlink into its page-local hyperlink table. For an
+ // implicit link, temporarily seed the counter with the encoded link ID,
+ // then restore the independent next-ID counter from the header.
+ if (cursor_hyperlink) |value| {
+ switch (value.id) {
+ .explicit => |id| try result.startHyperlink(value.uri, id),
+ .implicit => |id| {
+ result.cursor.hyperlink_implicit_id = id;
+ try result.startHyperlink(value.uri, null);
+ result.cursor.hyperlink_implicit_id =
+ header.hyperlink_implicit_id;
+ },
+ }
+ }
+
+ // `seen` is derived state. Only resident prompt metadata participates
+ // because omitted history is outside the restored Screen model.
+ result.semantic_prompt.seen = seen: {
+ if (result.cursor.semantic_content == .prompt) break :seen true;
+
+ var node = result.pages.getTopLeft(.screen).node;
+ while (true) {
+ const native_page = node.pageAssumeResident();
+ const rows = native_page.rows.ptr(
+ native_page.memory,
+ )[0..native_page.size.rows];
+ for (rows) |row| {
+ if (row.semantic_prompt != .none) break :seen true;
+
+ const cells = row.cells.ptr(
+ native_page.memory,
+ )[0..native_page.size.cols];
+ for (cells) |cell| {
+ if (cell.semantic_content == .prompt) break :seen true;
+ }
+ }
+
+ node = node.next orelse break :seen false;
+ }
+
+ unreachable;
+ };
+
+ // Kitty image payloads are outside this record, but the restored Screen
+ // must still receive the caller's terminal-wide storage policy.
+ if (comptime build_options.kitty_graphics) {
+ result.kitty_images.setLimit(
+ io_,
+ alloc,
+ &result,
+ options.kitty_image_storage_limit,
+ );
+ result.kitty_images.image_limits = options.kitty_image_loading_limits;
+ }
+
+ // All fallible reconstruction is complete; verify the native invariants
+ // before transferring ownership to the caller.
+ result.pages.assertIntegrity();
+ result.assertIntegrity();
+ return .{
+ .key = key,
+ .history_rows = header.history_rows,
+ .screen = result,
+ };
+}
+
+/// Errors possible while decoding fixed SCREEN payload fields.
+const PayloadDecodeError = std.Io.Reader.Error || error{InvalidKey};
+
+/// Flags encoded after the cursor's visual shape.
+pub const CursorFlags = packed struct(u8) {
+ pending_wrap: bool = false,
+ protected: bool = false,
+ semantic_content: terminal_page.Cell.SemanticContent = .output,
+ semantic_content_clear_eol: bool = false,
+ _padding: u3 = 0,
+
+ fn init(cursor: *const TerminalScreen.Cursor) CursorFlags {
+ return .{
+ .pending_wrap = cursor.pending_wrap,
+ .protected = cursor.protected,
+ .semantic_content = cursor.semantic_content,
+ .semantic_content_clear_eol = cursor
+ .semantic_content_clear_eol,
+ };
+ }
+
+ /// Decode the cursor flag registry, normalizing unknown semantic state.
+ pub fn decode(reader: *std.Io.Reader) std.Io.Reader.Error!CursorFlags {
+ const raw = try reader.takeByte();
+ const bits: CursorFlags = @bitCast(raw);
+ const semantic_content_raw: u2 = @truncate(raw >> @bitOffsetOf(CursorFlags, "semantic_content"));
+ const semantic_content = std.enums.fromInt(
+ terminal_page.Cell.SemanticContent,
+ semantic_content_raw,
+ ) orelse .output;
+
+ return .{
+ .pending_wrap = bits.pending_wrap,
+ .protected = bits.protected,
+ .semantic_content = semantic_content,
+ .semantic_content_clear_eol = bits.semantic_content_clear_eol,
+ };
+ }
+};
+
+/// The packed wire bits shared by current and saved cursor charset state.
+///
+/// Native enum values are stable, but their backing type is `c_int` in C ABI
+/// builds. The wire therefore stores only checked integer values at its fixed
+/// bit widths.
+const CharsetBits = packed struct(u16) {
+ g0: u2 = 0,
+ g1: u2 = 0,
+ g2: u2 = 0,
+ g3: u2 = 0,
+ gl: u2 = 0,
+ gr: u2 = 2,
+ single_shift: u3 = 0,
+ _padding: u1 = 0,
+};
+
+fn enumFromInt(comptime T: type, raw: anytype) ?T {
+ const Tag = @typeInfo(T).@"enum".tag_type;
+ const value = std.math.cast(Tag, raw) orelse return null;
+ return std.enums.fromInt(T, value);
+}
+
+fn encodeCharsetState(
+ value: TerminalScreen.CharsetState,
+) error{InvalidCharsetState}!u16 {
+ const g0 = std.math.cast(
+ u2,
+ @intFromEnum(value.charsets.get(.G0)),
+ ) orelse return error.InvalidCharsetState;
+ const g1 = std.math.cast(
+ u2,
+ @intFromEnum(value.charsets.get(.G1)),
+ ) orelse return error.InvalidCharsetState;
+ const g2 = std.math.cast(
+ u2,
+ @intFromEnum(value.charsets.get(.G2)),
+ ) orelse return error.InvalidCharsetState;
+ const g3 = std.math.cast(
+ u2,
+ @intFromEnum(value.charsets.get(.G3)),
+ ) orelse return error.InvalidCharsetState;
+ const gl = std.math.cast(
+ u2,
+ @intFromEnum(value.gl),
+ ) orelse return error.InvalidCharsetState;
+ const gr = std.math.cast(
+ u2,
+ @intFromEnum(value.gr),
+ ) orelse return error.InvalidCharsetState;
+ const single_shift: u3 = if (value.single_shift) |slot| single_shift: {
+ const raw = std.math.cast(
+ u2,
+ @intFromEnum(slot),
+ ) orelse return error.InvalidCharsetState;
+ break :single_shift @as(u3, raw) + 1;
+ } else 0;
+
+ const bits: CharsetBits = .{
+ .g0 = g0,
+ .g1 = g1,
+ .g2 = g2,
+ .g3 = g3,
+ .gl = gl,
+ .gr = gr,
+ .single_shift = single_shift,
+ };
+ return @bitCast(bits);
+}
+
+fn decodeCharsetState(
+ raw: u16,
+) TerminalScreen.CharsetState {
+ const bits: CharsetBits = @bitCast(raw);
+
+ var result: TerminalScreen.CharsetState = .{};
+ result.gl = enumFromInt(
+ terminal_charsets.Slots,
+ bits.gl,
+ ) orelse result.gl;
+ result.gr = enumFromInt(
+ terminal_charsets.Slots,
+ bits.gr,
+ ) orelse result.gr;
+ result.single_shift = if (bits.single_shift == 0)
+ null
+ else if (bits.single_shift <= 4)
+ enumFromInt(
+ terminal_charsets.Slots,
+ bits.single_shift - 1,
+ )
+ else
+ null;
+ result.charsets.set(
+ .G0,
+ enumFromInt(
+ terminal_charsets.Charset,
+ bits.g0,
+ ) orelse .utf8,
+ );
+ result.charsets.set(
+ .G1,
+ enumFromInt(
+ terminal_charsets.Charset,
+ bits.g1,
+ ) orelse .utf8,
+ );
+ result.charsets.set(
+ .G2,
+ enumFromInt(
+ terminal_charsets.Charset,
+ bits.g2,
+ ) orelse .utf8,
+ );
+ result.charsets.set(
+ .G3,
+ enumFromInt(
+ terminal_charsets.Charset,
+ bits.g3,
+ ) orelse .utf8,
+ );
+ return result;
+}
+
+/// The complete fixed-size Kitty keyboard stack.
+pub const KittyKeyboard = struct {
+ index: u8 = 0,
+ flags: [8]Flags = @splat(.{}),
+
+ /// One byte in the fixed Kitty keyboard flag stack.
+ pub const Flags = packed struct(u8) {
+ disambiguate: bool = false,
+ report_events: bool = false,
+ report_alternates: bool = false,
+ report_all: bool = false,
+ report_associated: bool = false,
+ _padding: u3 = 0,
+
+ /// Decode one Kitty keyboard flag byte, ignoring reserved bits.
+ pub fn decode(reader: *std.Io.Reader) std.Io.Reader.Error!Flags {
+ var result: Flags = @bitCast(try reader.takeByte());
+ result._padding = 0;
+ return result;
+ }
+ };
+
+ fn init(value: terminal_kitty.KeyFlagStack) KittyKeyboard {
+ var result: KittyKeyboard = .{ .index = value.idx };
+ for (value.flags, &result.flags) |native, *snapshot| {
+ snapshot.* = .{
+ .disambiguate = native.disambiguate,
+ .report_events = native.report_events,
+ .report_alternates = native.report_alternates,
+ .report_all = native.report_all,
+ .report_associated = native.report_associated,
+ };
+ }
+ return result;
+ }
+
+ fn terminal(self: KittyKeyboard) terminal_kitty.KeyFlagStack {
+ var result: terminal_kitty.KeyFlagStack = .{
+ .idx = @intCast(self.index),
+ };
+ for (self.flags, &result.flags) |snapshot, *native| {
+ native.* = .{
+ .disambiguate = snapshot.disambiguate,
+ .report_events = snapshot.report_events,
+ .report_alternates = snapshot.report_alternates,
+ .report_all = snapshot.report_all,
+ .report_associated = snapshot.report_associated,
+ };
+ }
+ return result;
+ }
+
+ /// Decode the complete fixed Kitty keyboard stack.
+ pub fn decode(reader: *std.Io.Reader) std.Io.Reader.Error!KittyKeyboard {
+ const index_raw = try reader.takeByte();
+ const index = if (index_raw < 8) index_raw else 0;
+
+ var flags: [8]Flags = undefined;
+ for (&flags) |*entry| entry.* = try Flags.decode(reader);
+ return .{ .index = index, .flags = flags };
+ }
+};
+
+/// Decode semantic-click state, falling back to disabled for unknown values.
+fn decodeSemanticClick(
+ reader: *std.Io.Reader,
+) std.Io.Reader.Error!TerminalScreen.SemanticPrompt.SemanticClick {
+ const kind = enumFromInt(
+ TerminalScreen.SemanticPrompt.SemanticClickKind,
+ try reader.takeByte(),
+ );
+ const value = try reader.takeByte();
+
+ return switch (kind orelse return .none) {
+ .none => .none,
+ .click_events => .{ .click_events = enumFromInt(
+ terminal_osc.semantic_prompt.ClickEvents,
+ value,
+ ) orelse return .none },
+ .cl => .{ .cl = enumFromInt(
+ terminal_osc.semantic_prompt.Click,
+ value,
+ ) orelse return .none },
+ };
+}
+
+/// The optional fixed-size saved cursor state.
+pub const SavedCursor = struct {
+ /// Number of bytes written by `encode`, calculated using the encoder.
+ pub const len = computeLen();
+
+ comptime {
+ std.debug.assert(len == 23);
+ }
+
+ x: u16,
+ y: u16,
+ pen: TerminalStyle,
+ flags: Flags,
+ charset: TerminalScreen.CharsetState,
+
+ /// Flags encoded with an optional saved cursor.
+ pub const Flags = packed struct(u8) {
+ protected: bool = false,
+ pending_wrap: bool = false,
+ origin: bool = false,
+ _padding: u5 = 0,
+
+ /// Decode saved cursor flags, ignoring reserved bits.
+ pub fn decode(reader: *std.Io.Reader) std.Io.Reader.Error!Flags {
+ var result: Flags = @bitCast(try reader.takeByte());
+ result._padding = 0;
+ return result;
+ }
+ };
+
+ fn init(value: TerminalScreen.SavedCursor) SavedCursor {
+ return .{
+ .x = value.x,
+ .y = value.y,
+ .pen = value.style,
+ .flags = .{
+ .protected = value.protected,
+ .pending_wrap = value.pending_wrap,
+ .origin = value.origin,
+ },
+ .charset = value.charset,
+ };
+ }
+
+ fn terminal(
+ self: SavedCursor,
+ cols: u16,
+ rows: u16,
+ ) TerminalScreen.SavedCursor {
+ const x = @min(self.x, cols - 1);
+ return .{
+ .x = x,
+ .y = @min(self.y, rows - 1),
+ .style = self.pen,
+ .protected = self.flags.protected,
+ .pending_wrap = self.flags.pending_wrap and x == cols - 1,
+ .origin = self.flags.origin,
+ .charset = self.charset,
+ };
+ }
+
+ /// Encode one optional saved cursor value.
+ pub fn encode(
+ self: SavedCursor,
+ writer: *std.Io.Writer,
+ ) PayloadEncodeError!void {
+ if (self.flags._padding != 0) {
+ return error.InvalidSavedCursorFlags;
+ }
+ const charset = try encodeCharsetState(self.charset);
+
+ try io.writeInt(writer, u16, self.x);
+ try io.writeInt(writer, u16, self.y);
+ try style.encode(self.pen, writer);
+ try writer.writeByte(@bitCast(self.flags));
+ try io.writeInt(writer, u16, charset);
+ }
+
+ /// Decode and validate one optional saved cursor value.
+ pub fn decode(reader: *std.Io.Reader) PayloadDecodeError!SavedCursor {
+ return .{
+ .x = try io.readInt(reader, u16),
+ .y = try io.readInt(reader, u16),
+ .pen = (try style.decodeOrNull(reader)) orelse .{},
+ .flags = try Flags.decode(reader),
+ .charset = decodeCharsetState(
+ try io.readInt(reader, u16),
+ ),
+ };
+ }
+
+ fn computeLen() usize {
+ comptime {
+ var buf: [128]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ const value: SavedCursor = .{
+ .x = 0,
+ .y = 0,
+ .pen = .{},
+ .flags = .{},
+ .charset = .{},
+ };
+ value.encode(&writer) catch unreachable;
+ return writer.end;
+ }
+ }
+};
+
+/// The fixed fields at the start of every SCREEN payload.
+pub const Header = struct {
+ /// Number of bytes written by `encode`, calculated using the encoder.
+ pub const len = computeLen();
+
+ comptime {
+ std.debug.assert(len == 53);
+ }
+
+ key: TerminalScreenKey,
+ /// Complete pages in the minimal suffix covering the active area.
+ page_count: u16,
+ /// Advisory logical rows before the active area, including resident
+ /// SCREEN overlap.
+ history_rows: u64,
+ cursor_x: u16,
+ cursor_y: u16,
+ cursor_style: TerminalScreen.CursorStyle,
+ cursor_flags: CursorFlags,
+ cursor_pen: TerminalStyle,
+ hyperlink_implicit_id: u32,
+ charset: TerminalScreen.CharsetState,
+ protected_mode: terminal_ansi.ProtectedMode,
+ kitty_keyboard: KittyKeyboard,
+ semantic_click: TerminalScreen.SemanticPrompt.SemanticClick,
+ saved_cursor_present: bool,
+
+ /// Initialize the fixed header from one native screen.
+ fn init(
+ screen: *const TerminalScreen,
+ key: TerminalScreenKey,
+ page_count: u16,
+ ) Header {
+ return .{
+ .key = key,
+ .page_count = page_count,
+ .history_rows = @intCast(
+ screen.pages.total_rows - screen.pages.rows,
+ ),
+ .cursor_x = screen.cursor.x,
+ .cursor_y = screen.cursor.y,
+ .cursor_style = screen.cursor.cursor_style,
+ .cursor_flags = .init(&screen.cursor),
+ .cursor_pen = screen.cursor.style,
+ .hyperlink_implicit_id = screen.cursor.hyperlink_implicit_id,
+ .charset = screen.charset,
+ .protected_mode = screen.protected_mode,
+ .kitty_keyboard = .init(screen.kitty_keyboard),
+ .semantic_click = screen.semantic_prompt.click,
+ .saved_cursor_present = screen.saved_cursor != null,
+ };
+ }
+
+ /// Encode the fixed SCREEN payload header field by field.
+ pub fn encode(
+ self: Header,
+ writer: *std.Io.Writer,
+ ) PayloadEncodeError!void {
+ // Validate packed cursor state before writing any bytes.
+ if (self.cursor_flags._padding != 0) {
+ return error.InvalidCursorFlags;
+ }
+
+ // Validate and narrow native charset enum values before writing.
+ const charset = try encodeCharsetState(self.charset);
+
+ // Validate the complete Kitty keyboard stack.
+ if (self.kitty_keyboard.index >= self.kitty_keyboard.flags.len) {
+ return error.InvalidKittyKeyboardIndex;
+ }
+ for (self.kitty_keyboard.flags) |flags| {
+ if (flags._padding != 0) {
+ return error.InvalidKittyKeyboardFlags;
+ }
+ }
+
+ // Screen identity, expected history extent, and cursor position.
+ try io.writeInt(writer, u16, @intCast(@intFromEnum(self.key)));
+ try io.writeInt(writer, u16, self.page_count);
+ try io.writeInt(writer, u64, self.history_rows);
+ try io.writeInt(writer, u16, self.cursor_x);
+ try io.writeInt(writer, u16, self.cursor_y);
+
+ // Current cursor rendering state.
+ try writer.writeByte(@intCast(@intFromEnum(self.cursor_style)));
+ try writer.writeByte(@bitCast(self.cursor_flags));
+ try style.encode(self.cursor_pen, writer);
+ try io.writeInt(writer, u32, self.hyperlink_implicit_id);
+
+ // Charset and selective-erase state.
+ try io.writeInt(writer, u16, charset);
+ try writer.writeByte(@intCast(@intFromEnum(self.protected_mode)));
+
+ // Keyboard modes and semantic-click state.
+ try writer.writeByte(self.kitty_keyboard.index);
+ for (self.kitty_keyboard.flags) |flags| {
+ try writer.writeByte(@bitCast(flags));
+ }
+ try writer.writeByte(@intCast(@intFromEnum(
+ std.meta.activeTag(self.semantic_click),
+ )));
+ switch (self.semantic_click) {
+ .none => try writer.writeByte(0),
+ .click_events => |value| try writer.writeByte(
+ @intCast(@intFromEnum(value)),
+ ),
+ .cl => |value| try writer.writeByte(
+ @intCast(@intFromEnum(value)),
+ ),
+ }
+
+ // Presence of the optional saved-cursor suffix.
+ try writer.writeByte(@intFromBool(self.saved_cursor_present));
+ }
+
+ /// Decode the fixed SCREEN payload header.
+ ///
+ /// The screen key remains structural because it routes the following PAGE
+ /// sequence. Unknown semantic fields use native defaults instead.
+ pub fn decode(reader: *std.Io.Reader) PayloadDecodeError!Header {
+ // Screen identity, expected history extent, and cursor position.
+ const key = enumFromInt(
+ TerminalScreenKey,
+ try io.readInt(reader, u16),
+ ) orelse return error.InvalidKey;
+ const page_count = try io.readInt(reader, u16);
+ const history_rows = try io.readInt(reader, u64);
+ const cursor_x = try io.readInt(reader, u16);
+ const cursor_y = try io.readInt(reader, u16);
+
+ // Current cursor rendering state.
+ const cursor_style = enumFromInt(
+ TerminalScreen.CursorStyle,
+ try reader.takeByte(),
+ ) orelse .block;
+ const cursor_flags = try CursorFlags.decode(reader);
+ const cursor_pen: TerminalStyle =
+ (try style.decodeOrNull(reader)) orelse .{};
+ const hyperlink_implicit_id = try io.readInt(reader, u32);
+
+ // Charset and selective-erase state.
+ const charset = decodeCharsetState(
+ try io.readInt(reader, u16),
+ );
+ const protected_mode = enumFromInt(
+ terminal_ansi.ProtectedMode,
+ try reader.takeByte(),
+ ) orelse .off;
+
+ // Keyboard modes and semantic-click state.
+ const kitty_keyboard = try KittyKeyboard.decode(reader);
+ const semantic_click = try decodeSemanticClick(reader);
+
+ // Presence of the optional saved-cursor suffix.
+ const saved_cursor_present = try reader.takeByte() != 0;
+
+ return .{
+ .key = key,
+ .page_count = page_count,
+ .history_rows = history_rows,
+ .cursor_x = cursor_x,
+ .cursor_y = cursor_y,
+
+ .cursor_style = cursor_style,
+ .cursor_flags = cursor_flags,
+ .cursor_pen = cursor_pen,
+ .hyperlink_implicit_id = hyperlink_implicit_id,
+
+ .charset = charset,
+ .protected_mode = protected_mode,
+
+ .kitty_keyboard = kitty_keyboard,
+ .semantic_click = semantic_click,
+
+ .saved_cursor_present = saved_cursor_present,
+ };
+ }
+
+ fn computeLen() usize {
+ comptime {
+ var buf: [128]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ const value: Header = .{
+ .key = .primary,
+ .page_count = 0,
+ .history_rows = 0,
+ .cursor_x = 0,
+ .cursor_y = 0,
+ .cursor_style = .bar,
+ .cursor_flags = .{},
+ .cursor_pen = .{},
+ .hyperlink_implicit_id = 0,
+ .charset = .{},
+ .protected_mode = .off,
+ .kitty_keyboard = .{},
+ .semantic_click = .none,
+ .saved_cursor_present = false,
+ };
+ value.encode(&writer) catch unreachable;
+ return writer.end;
+ }
+ }
+};
+
+/// Encode the SCREEN payload, excluding its following PAGE records.
+fn encodePayload(
+ screen: *const TerminalScreen,
+ key: TerminalScreenKey,
+ page_count: u16,
+ writer: *std.Io.Writer,
+) PayloadEncodeError!void {
+ try Header.init(screen, key, page_count).encode(writer);
+
+ if (screen.saved_cursor) |saved_cursor| {
+ try SavedCursor.init(saved_cursor).encode(writer);
+ }
+
+ const cursor_hyperlink: ?TerminalHyperlink =
+ if (screen.cursor.hyperlink) |entry| entry.* else null;
+ try encodeCursorHyperlink(cursor_hyperlink, writer);
+}
+
+/// The variable cursor hyperlink at the end of every SCREEN payload.
+pub const CursorHyperlink = ?TerminalHyperlink;
+
+/// Encode the optional cursor hyperlink at the end of a SCREEN payload.
+pub fn encodeCursorHyperlink(
+ value: CursorHyperlink,
+ writer: *std.Io.Writer,
+) hyperlink.EncodeError!void {
+ if (value) |entry| return hyperlink.encode(entry, writer);
+ try writer.writeByte(0);
+}
+
+/// Decode one allocator-owned optional cursor hyperlink.
+///
+/// The caller owns a non-null returned value and must call `Hyperlink.deinit`.
+pub fn decodeCursorHyperlink(
+ reader: *std.Io.Reader,
+ alloc: Allocator,
+) std.Io.Reader.Error!CursorHyperlink {
+ if (try reader.peekByte() == 0) {
+ _ = try reader.takeByte();
+ return null;
+ }
+
+ return hyperlink.decode(reader, alloc) catch |err| switch (err) {
+ error.ReadFailed => error.ReadFailed,
+
+ // The cursor hyperlink is the final SCREEN payload field, so its
+ // record boundary lets us discard an invalid or unrepresentable value
+ // without losing the following PAGE sequence.
+ error.EndOfStream,
+ error.OutOfMemory,
+ error.InvalidKind,
+ error.InvalidUri,
+ error.InvalidExplicitId,
+ => {
+ _ = try reader.discardRemaining();
+ return null;
+ },
+ };
+}
+
+const test_header_fixture = test_fixture.parse(@embedFile("testdata/screen-header-v1.hex"));
+const test_saved_cursor_fixture = test_fixture.parse(@embedFile("testdata/screen-saved-cursor-v1.hex"));
+
+fn testCharsetState() TerminalScreen.CharsetState {
+ var result: TerminalScreen.CharsetState = .{
+ .gl = .G1,
+ .gr = .G3,
+ .single_shift = .G2,
+ };
+ result.charsets.set(.G0, .utf8);
+ result.charsets.set(.G1, .ascii);
+ result.charsets.set(.G2, .british);
+ result.charsets.set(.G3, .dec_special);
+ return result;
+}
+
+fn testHeader() Header {
+ return .{
+ .key = .alternate,
+ .page_count = 0x0203,
+ .history_rows = 0x0102030405060708,
+ .cursor_x = 0x0405,
+ .cursor_y = 0x0607,
+ .cursor_style = .block_hollow,
+ .cursor_flags = .{
+ .pending_wrap = true,
+ .semantic_content = .prompt,
+ .semantic_content_clear_eol = true,
+ },
+ .cursor_pen = .{
+ .fg_color = .none,
+ .bg_color = .{ .palette = 0x7f },
+ .underline_color = .{ .rgb = .{
+ .r = 0x12,
+ .g = 0x34,
+ .b = 0x56,
+ } },
+ .flags = .{
+ .bold = true,
+ .italic = true,
+ .faint = true,
+ .blink = true,
+ .inverse = true,
+ .invisible = true,
+ .strikethrough = true,
+ .overline = true,
+ .underline = .curly,
+ },
+ },
+ .hyperlink_implicit_id = 0x0a0b0c0d,
+ .charset = testCharsetState(),
+ .protected_mode = .dec,
+ .kitty_keyboard = .{
+ .index = 7,
+ .flags = .{
+ .{ .disambiguate = true },
+ .{ .report_events = true },
+ .{ .report_alternates = true },
+ .{ .report_all = true },
+ .{ .report_associated = true },
+ .{
+ .disambiguate = true,
+ .report_events = true,
+ .report_alternates = true,
+ .report_all = true,
+ .report_associated = true,
+ },
+ .{},
+ .{
+ .disambiguate = true,
+ .report_associated = true,
+ },
+ },
+ },
+ .semantic_click = .{ .cl = .smart_vertical },
+ .saved_cursor_present = true,
+ };
+}
+
+fn testSavedCursor() SavedCursor {
+ return .{
+ .x = 0x0102,
+ .y = 0x0304,
+ .pen = .{},
+ .flags = .{
+ .protected = true,
+ .pending_wrap = true,
+ .origin = true,
+ },
+ .charset = testCharsetState(),
+ };
+}
+
+test "SCREEN header golden encoding and decoding" {
+ var encoded: [Header.len]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try testHeader().encode(&writer);
+
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/screen-header-v1.hex",
+ "snapshot_fixture-screen-header-v1.hex",
+ &test_header_fixture,
+ writer.buffered(),
+ );
+ try std.testing.expectEqual(Header.len, test_header_fixture.len);
+
+ var source: std.Io.Reader = .fixed(&test_header_fixture);
+ var buffer: [1]u8 = undefined;
+ var limited = source.limited(.unlimited, &buffer);
+
+ try std.testing.expectEqualDeep(
+ testHeader(),
+ try Header.decode(&limited.interface),
+ );
+}
+
+test "native enum values used by the SCREEN format" {
+ const keys = [_]TerminalScreenKey{ .primary, .alternate };
+ for (keys, 0..) |value, expected| {
+ try std.testing.expectEqual(
+ expected,
+ @as(usize, @intCast(@intFromEnum(value))),
+ );
+ }
+
+ const cursor_styles = [_]TerminalScreen.CursorStyle{
+ .bar,
+ .block,
+ .underline,
+ .block_hollow,
+ };
+ for (cursor_styles, 0..) |value, expected| {
+ try std.testing.expectEqual(
+ expected,
+ @as(usize, @intCast(@intFromEnum(value))),
+ );
+ }
+
+ const semantic_contents = [_]terminal_page.Cell.SemanticContent{
+ .output,
+ .input,
+ .prompt,
+ };
+ for (semantic_contents, 0..) |value, expected| {
+ try std.testing.expectEqual(
+ expected,
+ @as(usize, @intCast(@intFromEnum(value))),
+ );
+ }
+
+ const charsets = [_]terminal_charsets.Charset{
+ .utf8,
+ .ascii,
+ .british,
+ .dec_special,
+ };
+ for (charsets, 0..) |value, expected| {
+ try std.testing.expectEqual(
+ expected,
+ @as(usize, @intCast(@intFromEnum(value))),
+ );
+ }
+
+ const slots = [_]terminal_charsets.Slots{ .G0, .G1, .G2, .G3 };
+ for (slots, 0..) |value, expected| {
+ try std.testing.expectEqual(
+ expected,
+ @as(usize, @intCast(@intFromEnum(value))),
+ );
+ }
+
+ const protected_modes = [_]terminal_ansi.ProtectedMode{
+ .off,
+ .iso,
+ .dec,
+ };
+ for (protected_modes, 0..) |value, expected| {
+ try std.testing.expectEqual(
+ expected,
+ @as(usize, @intCast(@intFromEnum(value))),
+ );
+ }
+
+ const click_kinds = [_]TerminalScreen.SemanticPrompt.SemanticClickKind{
+ .none,
+ .click_events,
+ .cl,
+ };
+ for (click_kinds, 0..) |value, expected| {
+ try std.testing.expectEqual(
+ expected,
+ @as(usize, @intCast(@intFromEnum(value))),
+ );
+ }
+
+ const click_events = [_]terminal_osc.semantic_prompt.ClickEvents{
+ .absolute,
+ .relative,
+ };
+ for (click_events, 0..) |value, expected| {
+ try std.testing.expectEqual(
+ expected,
+ @as(usize, @intCast(@intFromEnum(value))),
+ );
+ }
+
+ const clicks = [_]terminal_osc.semantic_prompt.Click{
+ .line,
+ .multiple,
+ .conservative_vertical,
+ .smart_vertical,
+ };
+ for (clicks, 0..) |value, expected| {
+ try std.testing.expectEqual(
+ expected,
+ @as(usize, @intCast(@intFromEnum(value))),
+ );
+ }
+}
+
+test "cursor, Kitty, and saved cursor flag bit layouts" {
+ const CursorCase = struct {
+ value: CursorFlags,
+ expected: u8,
+ };
+ const cursor_cases = [_]CursorCase{
+ .{ .value = .{ .pending_wrap = true }, .expected = 1 << 0 },
+ .{ .value = .{ .protected = true }, .expected = 1 << 1 },
+ .{
+ .value = .{ .semantic_content = .input },
+ .expected = 1 << 2,
+ },
+ .{
+ .value = .{ .semantic_content = .prompt },
+ .expected = 2 << 2,
+ },
+ .{
+ .value = .{ .semantic_content_clear_eol = true },
+ .expected = 1 << 4,
+ },
+ };
+ for (cursor_cases) |case| {
+ try std.testing.expectEqual(
+ case.expected,
+ @as(u8, @bitCast(case.value)),
+ );
+ }
+
+ const KittyCase = struct {
+ value: KittyKeyboard.Flags,
+ expected: u8,
+ };
+ const kitty_cases = [_]KittyCase{
+ .{ .value = .{ .disambiguate = true }, .expected = 1 << 0 },
+ .{ .value = .{ .report_events = true }, .expected = 1 << 1 },
+ .{
+ .value = .{ .report_alternates = true },
+ .expected = 1 << 2,
+ },
+ .{ .value = .{ .report_all = true }, .expected = 1 << 3 },
+ .{
+ .value = .{ .report_associated = true },
+ .expected = 1 << 4,
+ },
+ };
+ for (kitty_cases) |case| {
+ try std.testing.expectEqual(
+ case.expected,
+ @as(u8, @bitCast(case.value)),
+ );
+ }
+
+ const SavedCase = struct {
+ value: SavedCursor.Flags,
+ expected: u8,
+ };
+ const saved_cases = [_]SavedCase{
+ .{ .value = .{ .protected = true }, .expected = 1 << 0 },
+ .{ .value = .{ .pending_wrap = true }, .expected = 1 << 1 },
+ .{ .value = .{ .origin = true }, .expected = 1 << 2 },
+ };
+ for (saved_cases) |case| {
+ try std.testing.expectEqual(
+ case.expected,
+ @as(u8, @bitCast(case.value)),
+ );
+ }
+}
+
+test "header encoding rejects invalid state" {
+ var encoded: [Header.len]u8 = undefined;
+
+ var invalid_cursor_flags = testHeader();
+ invalid_cursor_flags.cursor_flags._padding = 1;
+ var cursor_flags_writer: std.Io.Writer = .fixed(&encoded);
+ try std.testing.expectError(
+ error.InvalidCursorFlags,
+ invalid_cursor_flags.encode(&cursor_flags_writer),
+ );
+
+ var invalid_kitty_index = testHeader();
+ invalid_kitty_index.kitty_keyboard.index = 8;
+ var kitty_index_writer: std.Io.Writer = .fixed(&encoded);
+ try std.testing.expectError(
+ error.InvalidKittyKeyboardIndex,
+ invalid_kitty_index.encode(&kitty_index_writer),
+ );
+
+ var invalid_kitty_flags = testHeader();
+ invalid_kitty_flags.kitty_keyboard.flags[3]._padding = 1;
+ var kitty_flags_writer: std.Io.Writer = .fixed(&encoded);
+ try std.testing.expectError(
+ error.InvalidKittyKeyboardFlags,
+ invalid_kitty_flags.encode(&kitty_flags_writer),
+ );
+}
+
+test "header decoding rejects structural values" {
+ const valid = [_]u8{0} ** Header.len;
+
+ var invalid_key = valid;
+ invalid_key[0] = 2;
+ var key_reader: std.Io.Reader = .fixed(&invalid_key);
+ try std.testing.expectError(error.InvalidKey, Header.decode(&key_reader));
+}
+
+test "header decoding normalizes unknown semantic values" {
+ var fixture = [_]u8{0} ** Header.len;
+
+ fixture[16] = 4; // Unknown cursor style.
+ fixture[17] = 0xFF; // Known flags, unknown semantic value, reserved bits.
+ fixture[18] = 3; // Unknown cursor foreground color kind.
+ fixture[39] = 0xD0; // Invalid single shift plus a reserved bit.
+ fixture[40] = 3; // Unknown protected mode.
+ fixture[41] = 8; // Out-of-range Kitty keyboard index.
+ @memset(fixture[42..50], 0xFF); // Known flags plus reserved bits.
+ fixture[50] = 3; // Unknown semantic-click kind.
+ fixture[51] = 0xFF;
+ fixture[52] = 2; // Noncanonical true.
+
+ var reader: std.Io.Reader = .fixed(&fixture);
+ const decoded = try Header.decode(&reader);
+
+ try std.testing.expectEqual(
+ TerminalScreen.CursorStyle.block,
+ decoded.cursor_style,
+ );
+ try std.testing.expect(decoded.cursor_pen.default());
+ try std.testing.expect(decoded.cursor_flags.pending_wrap);
+ try std.testing.expect(decoded.cursor_flags.protected);
+ try std.testing.expectEqual(
+ terminal_page.Cell.SemanticContent.output,
+ decoded.cursor_flags.semantic_content,
+ );
+ try std.testing.expect(
+ decoded.cursor_flags.semantic_content_clear_eol,
+ );
+ try std.testing.expectEqual(@as(u3, 0), decoded.cursor_flags._padding);
+
+ try std.testing.expectEqual(null, decoded.charset.single_shift);
+ try std.testing.expectEqual(terminal_charsets.Slots.G0, decoded.charset.gr);
+ try std.testing.expectEqual(
+ terminal_ansi.ProtectedMode.off,
+ decoded.protected_mode,
+ );
+ try std.testing.expectEqual(@as(u8, 0), decoded.kitty_keyboard.index);
+ for (decoded.kitty_keyboard.flags) |flags| {
+ try std.testing.expect(flags.disambiguate);
+ try std.testing.expect(flags.report_events);
+ try std.testing.expect(flags.report_alternates);
+ try std.testing.expect(flags.report_all);
+ try std.testing.expect(flags.report_associated);
+ try std.testing.expectEqual(@as(u3, 0), flags._padding);
+ }
+ try std.testing.expectEqual(
+ TerminalScreen.SemanticPrompt.SemanticClick.none,
+ decoded.semantic_click,
+ );
+ try std.testing.expect(decoded.saved_cursor_present);
+
+ // Known semantic-click kinds with unknown or noncanonical values also
+ // degrade to disabled while consuming both fixed bytes.
+ const invalid_semantic_clicks = [_][2]u8{
+ .{ 0, 1 },
+ .{ 1, 2 },
+ .{ 2, 4 },
+ };
+ for (invalid_semantic_clicks) |invalid| {
+ var semantic_fixture = [_]u8{0} ** Header.len;
+ semantic_fixture[50] = invalid[0];
+ semantic_fixture[51] = invalid[1];
+ var semantic_reader: std.Io.Reader = .fixed(&semantic_fixture);
+ const semantic_decoded = try Header.decode(&semantic_reader);
+ try std.testing.expectEqual(
+ TerminalScreen.SemanticPrompt.SemanticClick.none,
+ semantic_decoded.semantic_click,
+ );
+ }
+}
+
+test "header decoding rejects every truncation" {
+ for (0..Header.len) |fixture_len| {
+ var reader: std.Io.Reader = .fixed(
+ test_header_fixture[0..fixture_len],
+ );
+ try std.testing.expectError(error.EndOfStream, Header.decode(&reader));
+ }
+}
+
+test "native SCREEN payload omits absent optional state" {
+ var screen = try TerminalScreen.init(
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 2, .rows = 2, .max_scrollback_bytes = 0 },
+ );
+ defer screen.deinit();
+
+ var encoded: [Header.len + 1]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try encodePayload(&screen, .primary, 1, &writer);
+ try std.testing.expectEqual(encoded.len, writer.end);
+
+ var reader: std.Io.Reader = .fixed(writer.buffered());
+ const header = try Header.decode(&reader);
+ try std.testing.expectEqual(TerminalScreenKey.primary, header.key);
+ try std.testing.expectEqual(@as(u16, 1), header.page_count);
+ try std.testing.expectEqual(@as(u64, 0), header.history_rows);
+ try std.testing.expect(!header.saved_cursor_present);
+ try std.testing.expectEqual(
+ null,
+ try decodeCursorHyperlink(&reader, std.testing.allocator),
+ );
+}
+
+test "saved cursor golden encoding and decoding" {
+ var encoded: [SavedCursor.len]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try testSavedCursor().encode(&writer);
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/screen-saved-cursor-v1.hex",
+ "snapshot_fixture-screen-saved-cursor-v1.hex",
+ &test_saved_cursor_fixture,
+ writer.buffered(),
+ );
+ try std.testing.expectEqual(
+ SavedCursor.len,
+ test_saved_cursor_fixture.len,
+ );
+
+ var source: std.Io.Reader = .fixed(&test_saved_cursor_fixture);
+ var buffer: [1]u8 = undefined;
+ var limited = source.limited(.unlimited, &buffer);
+ try std.testing.expectEqualDeep(
+ testSavedCursor(),
+ try SavedCursor.decode(&limited.interface),
+ );
+}
+
+test "saved cursor encoding rejects and decoding normalizes invalid state" {
+ var encoded: [SavedCursor.len]u8 = undefined;
+
+ var invalid_flags = testSavedCursor();
+ invalid_flags.flags._padding = 1;
+ var flags_writer: std.Io.Writer = .fixed(&encoded);
+ try std.testing.expectError(
+ error.InvalidSavedCursorFlags,
+ invalid_flags.encode(&flags_writer),
+ );
+
+ var invalid = [_]u8{0} ** SavedCursor.len;
+ invalid[4] = 3; // Unknown saved-cursor foreground color kind.
+ invalid[20] = 0xF9; // Protected plus reserved bits.
+ invalid[22] = 0xD0; // Invalid single shift plus a reserved bit.
+ var reader: std.Io.Reader = .fixed(&invalid);
+ const decoded = try SavedCursor.decode(&reader);
+
+ try std.testing.expect(decoded.pen.default());
+ try std.testing.expect(decoded.flags.protected);
+ try std.testing.expect(!decoded.flags.pending_wrap);
+ try std.testing.expect(!decoded.flags.origin);
+ try std.testing.expectEqual(@as(u5, 0), decoded.flags._padding);
+ try std.testing.expectEqual(null, decoded.charset.single_shift);
+ try std.testing.expectEqual(
+ terminal_charsets.Slots.G0,
+ decoded.charset.gr,
+ );
+}
+
+test "saved cursor decoding rejects every truncation" {
+ for (0..SavedCursor.len) |fixture_len| {
+ var reader: std.Io.Reader = .fixed(
+ test_saved_cursor_fixture[0..fixture_len],
+ );
+ try std.testing.expectError(
+ error.EndOfStream,
+ SavedCursor.decode(&reader),
+ );
+ }
+}
+
+test "cursor hyperlink null encoding and decoding" {
+ var none_encoded: [1]u8 = undefined;
+ var none_writer: std.Io.Writer = .fixed(&none_encoded);
+ try encodeCursorHyperlink(null, &none_writer);
+ try std.testing.expectEqualStrings("\x00", none_writer.buffered());
+
+ var none_reader: std.Io.Reader = .fixed(none_writer.buffered());
+ try std.testing.expectEqual(
+ null,
+ try decodeCursorHyperlink(&none_reader, std.testing.allocator),
+ );
+}
+
+test "framed native SCREEN and PAGE sequence" {
+ var screen = try TerminalScreen.init(
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 8, .rows = 8, .max_scrollback_bytes = 0 },
+ );
+ defer screen.deinit();
+
+ // Configure the live cursor state represented by the fixed header.
+ screen.cursorAbsolute(7, 6);
+ screen.cursor.cursor_style = .block_hollow;
+ screen.cursor.pending_wrap = true;
+ screen.cursor.protected = false;
+ screen.cursor.semantic_content = .prompt;
+ screen.cursor.semantic_content_clear_eol = true;
+ screen.cursor.style = testHeader().cursor_pen;
+ screen.cursor.hyperlink_implicit_id = 0x0a0b0c0d;
+
+ // Configure the screen-wide modes and packed charset state.
+ var charset: TerminalScreen.CharsetState = .{
+ .gl = .G1,
+ .gr = .G3,
+ .single_shift = .G2,
+ };
+ charset.charsets.set(.G0, .utf8);
+ charset.charsets.set(.G1, .ascii);
+ charset.charsets.set(.G2, .british);
+ charset.charsets.set(.G3, .dec_special);
+ screen.charset = charset;
+ screen.protected_mode = .dec;
+ screen.kitty_keyboard = .{
+ .idx = 7,
+ .flags = .{
+ .{ .disambiguate = true },
+ .{ .report_events = true },
+ .{ .report_alternates = true },
+ .{ .report_all = true },
+ .{ .report_associated = true },
+ .{
+ .disambiguate = true,
+ .report_events = true,
+ .report_alternates = true,
+ .report_all = true,
+ .report_associated = true,
+ },
+ .{},
+ .{
+ .disambiguate = true,
+ .report_associated = true,
+ },
+ },
+ };
+ screen.semantic_prompt = .{
+ .seen = true,
+ .click = .{ .cl = .smart_vertical },
+ };
+
+ // Configure the optional cursor state encoded after the fixed header.
+ screen.saved_cursor = .{
+ .x = 0x0102,
+ .y = 0x0304,
+ .style = .{},
+ .protected = true,
+ .pending_wrap = true,
+ .origin = true,
+ .charset = charset,
+ };
+ try screen.startHyperlink("cursor-uri", null);
+
+ var destination: std.Io.Writer.Allocating = .init(
+ std.testing.allocator,
+ );
+ defer destination.deinit();
+ try destination.writer.writeAll("prefix");
+ var stream: record.Writer = .init(
+ std.testing.allocator,
+ &destination.writer,
+ );
+ defer stream.deinit();
+ try encode(&screen, .alternate, &stream);
+
+ try std.testing.expectEqualStrings(
+ "prefix",
+ destination.written()[0..6],
+ );
+
+ // The complete sequence restores directly into native Screen/PageList
+ // state, including page-local cursor references.
+ var restore_source: std.Io.Reader = .fixed(destination.written()[6..]);
+ var decoded = try decode(
+ &restore_source,
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 8, .rows = 8, .max_scrollback_bytes = 0 },
+ );
+ defer decoded.deinit();
+ try std.testing.expectEqual(TerminalScreenKey.alternate, decoded.key);
+ const restored = &decoded.screen;
+
+ try std.testing.expect(restored.no_scrollback);
+ try std.testing.expectEqual(@as(u16, 7), restored.cursor.x);
+ try std.testing.expectEqual(@as(u16, 6), restored.cursor.y);
+ try std.testing.expectEqual(
+ TerminalScreen.CursorStyle.block_hollow,
+ restored.cursor.cursor_style,
+ );
+ try std.testing.expect(restored.cursor.pending_wrap);
+ try std.testing.expectEqual(
+ terminal_page.Cell.SemanticContent.prompt,
+ restored.cursor.semantic_content,
+ );
+ try std.testing.expect(
+ restored.cursor.style.eql(testHeader().cursor_pen),
+ );
+ try std.testing.expect(restored.cursor.style_id != terminal_style.default_id);
+ try std.testing.expectEqual(
+ @as(u32, 0x0a0b0c0e),
+ restored.cursor.hyperlink_implicit_id,
+ );
+ const restored_hyperlink = restored.cursor.hyperlink.?.*;
+ try std.testing.expectEqualStrings(
+ "cursor-uri",
+ restored_hyperlink.uri,
+ );
+ switch (restored_hyperlink.id) {
+ .implicit => |id| try std.testing.expectEqual(
+ @as(u32, 0x0a0b0c0d),
+ id,
+ ),
+ .explicit => try std.testing.expect(false),
+ }
+
+ const restored_saved = restored.saved_cursor.?;
+ try std.testing.expectEqual(@as(u16, 7), restored_saved.x);
+ try std.testing.expectEqual(@as(u16, 7), restored_saved.y);
+ try std.testing.expect(restored_saved.protected);
+ try std.testing.expect(restored_saved.pending_wrap);
+ try std.testing.expect(restored_saved.origin);
+ try std.testing.expectEqual(
+ terminal_charsets.Charset.ascii,
+ restored.charset.charsets.get(.G1),
+ );
+ try std.testing.expectEqual(
+ terminal_ansi.ProtectedMode.dec,
+ restored.protected_mode,
+ );
+ try std.testing.expectEqual(@as(u8, 7), restored.kitty_keyboard.idx);
+ try std.testing.expect(restored.semantic_prompt.seen);
+ try std.testing.expectEqual(
+ TerminalScreen.SemanticPrompt.SemanticClick{
+ .cl = .smart_vertical,
+ },
+ restored.semantic_prompt.click,
+ );
+
+ // Restored page-local cursor IDs are immediately usable by normal writes.
+ try restored.testWriteString("Z");
+ const written = restored.pages.getCell(.{ .active = .{
+ .x = 0,
+ .y = 7,
+ } }).?;
+ try std.testing.expectEqual(@as(u21, 'Z'), written.cell.codepoint());
+ try std.testing.expectEqual(
+ restored.cursor.style_id,
+ written.cell.style_id,
+ );
+ try std.testing.expectEqual(
+ restored.cursor.hyperlink_id,
+ written.node.page().lookupHyperlink(written.cell).?,
+ );
+ try std.testing.expectEqual(
+ terminal_page.Cell.SemanticContent.prompt,
+ written.cell.semantic_content,
+ );
+ try std.testing.expectError(error.EndOfStream, restore_source.takeByte());
+}
+
+test "SCREEN encodes the minimal complete-page active suffix" {
+ 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 screen = try TerminalScreen.init(
+ std.testing.io,
+ std.testing.allocator,
+ .{
+ .cols = 80,
+ .rows = screen_rows,
+ .max_scrollback_bytes = null,
+ },
+ );
+ defer screen.deinit();
+
+ // Create one complete historical page followed by a mixed page whose
+ // first row is history and whose remaining rows begin the active area.
+ screen.cursorAbsolute(0, screen_rows - 1);
+ for (0..screen_rows) |_| try screen.testWriteString("\n");
+ try std.testing.expectEqual(@as(usize, 3), screen.pages.totalPages());
+
+ const active_top = screen.pages.getTopLeft(.active);
+ const historical = screen.pages.getTopLeft(.screen).node;
+ const mixed = historical.next.?;
+ const newest = mixed.next.?;
+ try std.testing.expectEqual(mixed, active_top.node);
+ try std.testing.expectEqual(@as(u16, 1), active_top.y);
+ try std.testing.expectEqual(null, newest.next);
+
+ // Mark each native page so the encoded sequence proves both omission and
+ // oldest-to-newest ordering. The mixed page's marker is in its incidental
+ // history prefix and must survive because complete pages are encoded.
+ historical.page().getRowAndCell(0, 0).cell.* = .init('A');
+ mixed.page().getRowAndCell(0, 0).cell.* = .init('B');
+ newest.page().getRowAndCell(0, 0).cell.* = .init('C');
+
+ 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(&screen, .primary, &stream);
+
+ var source: std.Io.Reader = .fixed(destination.written());
+ var screen_record: record.Reader = undefined;
+ try screen_record.init(&source);
+ try std.testing.expectEqual(record.Tag.screen, screen_record.header.tag);
+
+ const payload_reader = screen_record.payloadReader();
+ const header = try Header.decode(payload_reader);
+ try std.testing.expectEqual(TerminalScreenKey.primary, header.key);
+ try std.testing.expectEqual(@as(u16, 2), header.page_count);
+ try std.testing.expectEqual(
+ @as(u64, @intCast(screen.pages.total_rows - screen.pages.rows)),
+ header.history_rows,
+ );
+ try std.testing.expect(!header.saved_cursor_present);
+ try std.testing.expectEqual(
+ null,
+ try decodeCursorHyperlink(payload_reader, std.testing.allocator),
+ );
+ try screen_record.finish();
+
+ var decoded_mixed = try page.decode(&source, std.testing.allocator);
+ defer decoded_mixed.deinit();
+ try std.testing.expectEqual(
+ @as(u21, 'B'),
+ decoded_mixed.getRowAndCell(0, 0).cell.codepoint(),
+ );
+
+ var decoded_newest = try page.decode(&source, std.testing.allocator);
+ defer decoded_newest.deinit();
+ try std.testing.expectEqual(
+ @as(u21, 'C'),
+ decoded_newest.getRowAndCell(0, 0).cell.codepoint(),
+ );
+ try std.testing.expectError(error.EndOfStream, source.takeByte());
+
+ // Native restoration keeps the incidental history prefix and positions
+ // the active top within the first decoded page.
+ var restore_source: std.Io.Reader = .fixed(destination.written());
+ var decoded = try decode(
+ &restore_source,
+ std.testing.io,
+ std.testing.allocator,
+ .{
+ .cols = 80,
+ .rows = screen_rows,
+ .max_scrollback_bytes = null,
+ },
+ );
+ defer decoded.deinit();
+ try std.testing.expectEqual(TerminalScreenKey.primary, decoded.key);
+ try std.testing.expectEqual(header.history_rows, decoded.history_rows);
+ const restored = &decoded.screen;
+
+ try std.testing.expectEqual(@as(usize, 2), restored.pages.totalPages());
+ const restored_top = restored.pages.getTopLeft(.active);
+ try std.testing.expectEqual(@as(u16, 1), restored_top.y);
+ try std.testing.expectEqual(
+ @as(usize, restored_top.y),
+ restored.pages.total_rows - restored.pages.rows,
+ );
+ try std.testing.expect(
+ decoded.history_rows > @as(
+ u64,
+ @intCast(restored.pages.total_rows - restored.pages.rows),
+ ),
+ );
+ try std.testing.expectEqual(
+ @as(u21, 'B'),
+ restored.pages.getTopLeft(.screen).node
+ .page().getRowAndCell(0, 0).cell.codepoint(),
+ );
+ try std.testing.expectEqual(
+ @as(u21, 'C'),
+ restored.pages.getTopLeft(.screen).node.next.?
+ .page().getRowAndCell(0, 0).cell.codepoint(),
+ );
+
+ // The restored PageList resumes ordinary scrolling and row growth.
+ try restored.testWriteString("\n");
+ restored.pages.assertIntegrity();
+ restored.assertIntegrity();
+ try std.testing.expectError(error.EndOfStream, restore_source.takeByte());
+}
+
+test "SCREEN encoding preserves a compressed suffix page" {
+ const testing = std.testing;
+ const compression = @import("../compress.zig");
+
+ var screen = try TerminalScreen.init(
+ testing.io,
+ testing.allocator,
+ .{ .cols = 8, .rows = 2, .max_scrollback_bytes = 0 },
+ );
+ defer screen.deinit();
+ screen.pages.getCell(.{ .active = .{} }).?.cell.* = .init('A');
+
+ // Force the active suffix into the representation that current PageList
+ // policy normally reserves for history. This models a future policy change
+ // and makes pageAssumeResident an invalid tagged-union access.
+ const node = screen.pages.getTopLeft(.active).node;
+ const resident = node.pageAssumeResident();
+ const scratch = try testing.allocator.alloc(
+ u8,
+ try compression.Page.requiredScratch(resident.memory.len),
+ );
+ defer testing.allocator.free(scratch);
+ var table: compression.lz4.HashTable = undefined;
+ const compressed = (try compression.Page.init(
+ testing.allocator,
+ resident,
+ scratch,
+ &table,
+ )).?;
+ node.data = .{ .compressed = compressed };
+ try testing.expectEqual(.compressed, node.storage());
+
+ var destination: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer destination.deinit();
+ var stream: record.Writer = .init(testing.allocator, &destination.writer);
+ defer stream.deinit();
+ try encode(&screen, .primary, &stream);
+
+ // Encoding borrows or clones through PreservedPage and never changes the
+ // source node's storage representation.
+ try testing.expectEqual(.compressed, node.storage());
+
+ var source: std.Io.Reader = .fixed(destination.written());
+ var decoded = try decode(
+ &source,
+ testing.io,
+ testing.allocator,
+ .{ .cols = 8, .rows = 2, .max_scrollback_bytes = 0 },
+ );
+ defer decoded.deinit();
+ try testing.expectEqual(
+ @as(u21, 'A'),
+ decoded.screen.pages.getCell(.{ .active = .{} }).?.cell.codepoint(),
+ );
+}
+
+test "SCREEN restoration normalizes invalid cursor positions" {
+ var screen = try TerminalScreen.init(
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 2, .rows = 2, .max_scrollback_bytes = 0 },
+ );
+ defer screen.deinit();
+
+ const Case = struct {
+ x: u16,
+ y: u16,
+ pending_wrap: bool,
+ expected_x: u16,
+ expected_y: u16,
+ expected_pending_wrap: bool,
+ };
+ const cases = [_]Case{
+ // Out-of-range coordinates clamp to the bottom-right. Pending wrap is
+ // valid there and can be retained.
+ .{
+ .x = std.math.maxInt(u16),
+ .y = std.math.maxInt(u16),
+ .pending_wrap = true,
+ .expected_x = 1,
+ .expected_y = 1,
+ .expected_pending_wrap = true,
+ },
+ // Pending wrap away from the final column would trip native printing
+ // assertions, so retain the position and clear only that flag.
+ .{
+ .x = 0,
+ .y = 0,
+ .pending_wrap = true,
+ .expected_x = 0,
+ .expected_y = 0,
+ .expected_pending_wrap = false,
+ },
+ };
+
+ 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();
+
+ var header = Header.init(&screen, .primary, 1);
+ header.cursor_x = case.x;
+ header.cursor_y = case.y;
+ header.cursor_flags.pending_wrap = case.pending_wrap;
+ header.saved_cursor_present = false;
+
+ const screen_payload = stream.begin(.screen);
+ errdefer stream.cancel();
+ try header.encode(screen_payload);
+ try screen_payload.writeByte(0);
+ try stream.finish();
+
+ const native_page = screen.pages.getTopLeft(.active).node
+ .pageAssumeResident();
+ try page.encode(native_page, &stream);
+
+ var source: std.Io.Reader = .fixed(destination.written());
+ var decoded = try decode(
+ &source,
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 2, .rows = 2, .max_scrollback_bytes = 0 },
+ );
+ defer decoded.deinit();
+
+ try std.testing.expectEqual(case.expected_x, decoded.screen.cursor.x);
+ try std.testing.expectEqual(case.expected_y, decoded.screen.cursor.y);
+ try std.testing.expectEqual(
+ case.expected_pending_wrap,
+ decoded.screen.cursor.pending_wrap,
+ );
+ decoded.screen.assertIntegrity();
+ }
+}
+
+test "SCREEN validates pending wrap against a mixed-width cursor page" {
+ var screen = try TerminalScreen.init(
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 8, .rows = 1, .max_scrollback_bytes = 0 },
+ );
+ defer screen.deinit();
+
+ // Model a lazily reflowed active page that is narrower than the terminal.
+ // Column three is its physical final column even though it is not column
+ // seven of the current terminal dimensions.
+ var narrow_page = try terminal_page.Page.init(.{ .cols = 4, .rows = 1 });
+ defer narrow_page.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();
+
+ var header = Header.init(&screen, .primary, 1);
+ header.cursor_x = 3;
+ header.cursor_y = 0;
+ header.cursor_flags.pending_wrap = true;
+ header.saved_cursor_present = false;
+
+ const screen_payload = stream.begin(.screen);
+ errdefer stream.cancel();
+ try header.encode(screen_payload);
+ try screen_payload.writeByte(0);
+ try stream.finish();
+ try page.encode(&narrow_page, &stream);
+
+ var source: std.Io.Reader = .fixed(destination.written());
+ var decoded = try decode(
+ &source,
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 8, .rows = 1, .max_scrollback_bytes = 0 },
+ );
+ defer decoded.deinit();
+
+ try std.testing.expectEqual(@as(u16, 4), decoded.screen.cursor.page_pin.node.cols());
+ try std.testing.expectEqual(@as(u16, 3), decoded.screen.cursor.x);
+ try std.testing.expect(decoded.screen.cursor.pending_wrap);
+ decoded.screen.assertIntegrity();
+}
+
+test "SCREEN clamps a decoded saved cursor to terminal dimensions" {
+ var screen = try TerminalScreen.init(
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 2, .rows = 2, .max_scrollback_bytes = 0 },
+ );
+ defer 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();
+
+ var header = Header.init(&screen, .primary, 1);
+ header.saved_cursor_present = true;
+ const screen_payload = stream.begin(.screen);
+ try header.encode(screen_payload);
+ try (SavedCursor{
+ .x = std.math.maxInt(u16),
+ .y = std.math.maxInt(u16),
+ .pen = .{},
+ .flags = .{ .pending_wrap = true },
+ .charset = .{},
+ }).encode(screen_payload);
+ try screen_payload.writeByte(0);
+ try stream.finish();
+ try page.encode(
+ screen.pages.getTopLeft(.active).node.pageAssumeResident(),
+ &stream,
+ );
+
+ var source: std.Io.Reader = .fixed(destination.written());
+ var decoded = try decode(
+ &source,
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 2, .rows = 2, .max_scrollback_bytes = 0 },
+ );
+ defer decoded.deinit();
+
+ const saved = decoded.screen.saved_cursor.?;
+ try std.testing.expectEqual(@as(u16, 1), saved.x);
+ try std.testing.expectEqual(@as(u16, 1), saved.y);
+ try std.testing.expect(saved.pending_wrap);
+}
+
+test "SCREEN restoration rejects invalid and incomplete sequences" {
+ var screen = try TerminalScreen.init(
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 2, .rows = 2, .max_scrollback_bytes = 0 },
+ );
+ defer 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(&screen, .primary, &stream);
+
+ // Every truncation must fail without leaking a partially restored
+ // PageList, cursor pin, or cursor-owned state.
+ for (0..destination.written().len) |fixture_len| {
+ var source: std.Io.Reader = .fixed(
+ destination.written()[0..fixture_len],
+ );
+ var restored = decode(
+ &source,
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 2, .rows = 2, .max_scrollback_bytes = 0 },
+ ) catch continue;
+ restored.deinit();
+ try std.testing.expect(false);
+ }
+
+ // Native PageList construction is transactional on allocation failure.
+ {
+ var failing = std.testing.FailingAllocator.init(
+ std.testing.allocator,
+ .{ .fail_index = 0 },
+ );
+ var source: std.Io.Reader = .fixed(destination.written());
+ try std.testing.expectError(
+ error.OutOfMemory,
+ decode(
+ &source,
+ std.testing.io,
+ failing.allocator(),
+ .{ .cols = 2, .rows = 2, .max_scrollback_bytes = 0 },
+ ),
+ );
+ }
+
+ // A syntactically valid SCREEN cannot declare an empty PAGE sequence.
+ var empty_sequence: std.Io.Writer.Allocating = .init(
+ std.testing.allocator,
+ );
+ defer empty_sequence.deinit();
+ var empty_stream: record.Writer = .init(
+ std.testing.allocator,
+ &empty_sequence.writer,
+ );
+ defer empty_stream.deinit();
+ {
+ const payload = empty_stream.begin(.screen);
+ errdefer empty_stream.cancel();
+ try Header.init(&screen, .primary, 0).encode(
+ payload,
+ );
+ try payload.writeByte(0);
+ try empty_stream.finish();
+ }
+ var empty_source: std.Io.Reader = .fixed(empty_sequence.written());
+ try std.testing.expectError(
+ error.InvalidPageCount,
+ decode(
+ &empty_source,
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 2, .rows = 2, .max_scrollback_bytes = 0 },
+ ),
+ );
+}
+
+test "SCREEN sequence failure preserves preceding bytes" {
+ var screen = try TerminalScreen.init(
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 2, .rows = 2, .max_scrollback_bytes = 0 },
+ );
+ defer screen.deinit();
+
+ var destination: std.Io.Writer.Allocating = .init(
+ std.testing.allocator,
+ );
+ defer destination.deinit();
+ try destination.writer.writeAll("prefix");
+
+ var failing = std.testing.FailingAllocator.init(
+ std.testing.allocator,
+ .{ .fail_index = 0 },
+ );
+ var stream: record.Writer = .init(
+ failing.allocator(),
+ &destination.writer,
+ );
+ defer stream.deinit();
+
+ try std.testing.expectError(
+ error.WriteFailed,
+ encode(&screen, .primary, &stream),
+ );
+ try std.testing.expectEqualStrings("prefix", destination.written());
+}
+
+test "SCREEN decode ignores an invalid cursor hyperlink" {
+ var screen = try TerminalScreen.init(
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 1, .rows = 1, .max_scrollback_bytes = 0 },
+ );
+ defer 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();
+
+ var header = testHeader();
+ header.key = .primary;
+ header.page_count = 1;
+ header.cursor_x = 0;
+ header.cursor_y = 0;
+ header.cursor_flags.pending_wrap = false;
+ header.saved_cursor_present = false;
+
+ const screen_payload = stream.begin(.screen);
+ errdefer stream.cancel();
+ try header.encode(screen_payload);
+ try screen_payload.writeByte(1); // Implicit hyperlink.
+ try io.writeInt(screen_payload, u32, 1);
+ try io.writeInt(screen_payload, u32, 0); // Empty URI.
+ try stream.finish();
+
+ try page.encode(
+ screen.pages.getTopLeft(.active).node.pageAssumeResident(),
+ &stream,
+ );
+
+ var source: std.Io.Reader = .fixed(destination.written());
+ var decoded = try decode(
+ &source,
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 1, .rows = 1 },
+ );
+ defer decoded.deinit();
+ try std.testing.expectEqual(null, decoded.screen.cursor.hyperlink);
+}
+
+test "SCREEN decode ignores a PAGE with an empty hyperlink URI" {
+ 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();
+
+ var header = testHeader();
+ header.key = .primary;
+ header.page_count = 1;
+ header.cursor_x = 0;
+ header.cursor_y = 0;
+ header.cursor_flags.pending_wrap = false;
+ header.saved_cursor_present = false;
+
+ const screen_payload = stream.begin(.screen);
+ errdefer stream.cancel();
+ try header.encode(screen_payload);
+ try screen_payload.writeByte(0);
+ try stream.finish();
+
+ const page_header: page.Header = .{
+ .columns = 1,
+ .rows = 1,
+ .style_count = 0,
+ .hyperlink_count = 1,
+ .style_capacity = 16,
+ .hyperlink_capacity_bytes = 512,
+ .grapheme_capacity_bytes = 0,
+ .string_capacity_bytes = 0,
+ };
+ const page_payload = stream.begin(.page);
+ errdefer stream.cancel();
+ try page_header.encode(page_payload);
+ try io.writeInt(
+ page_payload,
+ terminal_hyperlink.Id,
+ 1,
+ );
+ try page_payload.writeByte(1); // Implicit hyperlink.
+ try io.writeInt(page_payload, u32, 1);
+ try io.writeInt(page_payload, u32, 0); // Empty URI.
+
+ // One narrow codepoint cell refers to the hyperlink table entry above.
+ // Since that entry is ignored, the cell must restore without a hyperlink.
+ try page_payload.writeByte(0x30); // row flags, full cell width
+ try io.writeInt(page_payload, u16, 1); // cell count
+ try io.writeInt(page_payload, u64, @bitCast(grid.Cell{
+ .content = 'A',
+ .hyperlink = true,
+ .hyperlink_id = 1,
+ }));
+ try io.writeInt(page_payload, u32, 0); // grapheme section
+ try stream.finish();
+
+ var source: std.Io.Reader = .fixed(destination.written());
+ var decoded = try decode(
+ &source,
+ std.testing.io,
+ std.testing.allocator,
+ .{ .cols = 1, .rows = 1 },
+ );
+ defer decoded.deinit();
+
+ try std.testing.expectEqual(
+ @as(u21, 'A'),
+ decoded.screen.cursor.page_cell.codepoint(),
+ );
+ try std.testing.expect(!decoded.screen.cursor.page_cell.hyperlink);
+
+ // Resizing copies the restored cells into a wider page. The ignored
+ // hyperlink must not leave a zero-length PageEntry to duplicate later.
+ try decoded.screen.resize(.{ .cols = 2, .rows = 1 });
+ try std.testing.expect(!decoded.screen.cursor.page_cell.hyperlink);
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/snapshot.ksy b/vendor/libghostty-vt/src/terminal/snapshot/snapshot.ksy
new file mode 100644
index 00000000..2da917ea
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/snapshot.ksy
@@ -0,0 +1,1073 @@
+meta:
+ id: ghostty_snapshot
+ title: Ghostty terminal snapshot
+ application: Ghostty
+ license: MIT
+ endian: le
+doc: |
+ Ghostty terminal snapshot format version 1.
+
+ A complete snapshot contains an envelope, terminal-wide state, one or two
+ renderable screen sequences, one raw standard-Stream CONTINUATION, a READY
+ marker, matching history sequences, and a FINISH marker. SCREEN pages
+ are oldest-to-newest. HISTORY pages are newest-to-oldest. FINISH terminates the
+ snapshot; bytes that follow belong to the containing transport and are outside
+ this schema. Each SCREEN declares its complete logical history extent before
+ READY.
+
+ Record CRC32C values are represented here but cannot be calculated by
+ portable Kaitai Struct expressions. The adjacent verify-kaitai.py script
+ validates those values after parsing.
+seq:
+ - id: envelope
+ type: envelope
+ - id: terminal
+ type: terminal_record
+ - id: screens
+ type: screen_sequence
+ repeat: expr
+ repeat-expr: terminal.payload.header.screen_count
+ - id: continuation
+ type: continuation_record
+ - id: ready
+ type: checkpoint_record(5)
+ - id: histories
+ type: history_sequence
+ repeat: expr
+ repeat-expr: terminal.payload.header.screen_count
+ - id: finish
+ type: checkpoint_record(6)
+enums:
+ record_tag:
+ 1: terminal
+ 2: screen
+ 3: page
+ 4: history
+ 5: ready
+ 6: finish
+ 7: continuation
+ screen_key:
+ 0: primary
+ 1: alternate
+ cursor_style:
+ 0: bar
+ 1: block
+ 2: underline
+ 3: block_hollow
+ status_display:
+ 0: main
+ 1: status_line
+ shell_redraw:
+ 0: full
+ 1: none
+ 2: last
+ mouse_event:
+ 0: none
+ 1: x10
+ 2: normal
+ 3: button
+ 4: any
+ mouse_format:
+ 0: x10
+ 1: utf8
+ 2: sgr
+ 3: urxvt
+ 4: sgr_pixels
+ mouse_shape:
+ 0: default
+ 1: context_menu
+ 2: help
+ 3: pointer
+ 4: progress
+ 5: wait
+ 6: cell
+ 7: crosshair
+ 8: text
+ 9: vertical_text
+ 10: alias
+ 11: copy
+ 12: move
+ 13: no_drop
+ 14: not_allowed
+ 15: grab
+ 16: grabbing
+ 17: all_scroll
+ 18: col_resize
+ 19: row_resize
+ 20: n_resize
+ 21: e_resize
+ 22: s_resize
+ 23: w_resize
+ 24: ne_resize
+ 25: nw_resize
+ 26: se_resize
+ 27: sw_resize
+ 28: ew_resize
+ 29: ns_resize
+ 30: nesw_resize
+ 31: nwse_resize
+ 32: zoom_in
+ 33: zoom_out
+ protected_mode:
+ 0: "off"
+ 1: iso
+ 2: dec
+ semantic_click_kind:
+ 0: none
+ 1: click_events
+ 2: cl
+ color_kind:
+ 0: none
+ 1: palette
+ 2: rgb
+ hyperlink_kind:
+ 0: none
+ 1: implicit
+ 2: explicit
+ cell_content_kind:
+ 0: codepoint
+ 1: background_palette
+ 2: background_rgb
+ cell_width:
+ 0: narrow
+ 1: wide
+ 2: spacer_tail
+ 3: spacer_head
+ underline:
+ 0: none
+ 1: single
+ 2: double
+ 3: curly
+ 4: dotted
+ 5: dashed
+ semantic_content:
+ 0: output
+ 1: input
+ 2: prompt
+ semantic_prompt:
+ 0: none
+ 1: prompt
+ 2: prompt_continuation
+types:
+ envelope:
+ doc: Fixed ten-byte snapshot identification and version header.
+ seq:
+ - id: magic
+ contents: [0x47, 0x48, 0x4f, 0x53, 0x54, 0x53, 0x4e, 0x50]
+ - id: version
+ type: u2
+ valid: 1
+
+ record_header:
+ doc: |
+ Common record framing. crc32c covers the encoded tag, payload length,
+ and payload bytes, excluding the crc32c field itself.
+ params:
+ - id: expected_tag
+ type: u2
+ seq:
+ - id: tag
+ type: u2
+ valid: expected_tag
+ - id: payload_length
+ type: u4
+ - id: crc32c
+ type: u4
+
+ terminal_record:
+ seq:
+ - id: header
+ type: record_header(1)
+ - id: payload
+ type: terminal_payload
+ size: header.payload_length
+
+ screen_record:
+ seq:
+ - id: header
+ type: record_header(2)
+ - id: payload
+ type: screen_payload
+ size: header.payload_length
+
+ page_record:
+ seq:
+ - id: header
+ type: record_header(3)
+ - id: payload
+ type: page_payload
+ size: header.payload_length
+
+ history_record:
+ seq:
+ - id: header
+ type: record_header(4)
+ - id: payload
+ type: history_payload
+ size: header.payload_length
+
+ continuation_record:
+ doc: |
+ Raw canonical standard TerminalStream continuation bytes. An empty
+ payload explicitly represents ground state.
+ seq:
+ - id: header
+ type: record_header(7)
+ - id: payload
+ size: header.payload_length
+
+ checkpoint_record:
+ doc: READY and FINISH are empty marker records.
+ params:
+ - id: expected_tag
+ type: u2
+ seq:
+ - id: header
+ type: record_header(expected_tag)
+ - id: payload
+ size: header.payload_length
+ valid:
+ expr: _.size == 0
+
+ screen_sequence:
+ doc: SCREEN followed by its declared PAGE records, oldest-to-newest.
+ seq:
+ - id: screen
+ type: screen_record
+ - id: pages
+ type: page_record
+ repeat: expr
+ repeat-expr: screen.payload.header.page_count
+
+ history_sequence:
+ doc: HISTORY followed by its declared PAGE records, newest-to-oldest.
+ seq:
+ - id: history
+ type: history_record
+ - id: pages
+ type: page_record
+ repeat: expr
+ repeat-expr: history.payload.page_count
+
+ terminal_payload:
+ seq:
+ - id: header
+ type: terminal_header
+ - id: tab_stops
+ type: tab_stops(header.columns)
+ - id: original_palette
+ type: rgb
+ repeat: expr
+ repeat-expr: 256
+ - id: palette_override_mask
+ size: 32
+ - id: palette_overrides
+ type: palette_override(palette_override_mask, _index)
+ repeat: expr
+ repeat-expr: 256
+ - id: len_pwd
+ type: u4
+ - id: pwd
+ size: len_pwd
+ - id: len_title
+ type: u4
+ - id: title
+ size: len_title
+ - id: trailing_data
+ size-eos: true
+ valid:
+ expr: _.size == 0
+
+ terminal_header:
+ seq:
+ - id: columns
+ type: u2
+ valid:
+ min: 1
+ - id: rows
+ type: u2
+ valid:
+ min: 1
+ - id: width_px
+ type: u4
+ - id: height_px
+ type: u4
+ - id: scrolling_region_top
+ type: u2
+ - id: scrolling_region_bottom
+ type: u2
+ valid:
+ expr: _ >= scrolling_region_top and _ < rows
+ - id: scrolling_region_left
+ type: u2
+ - id: scrolling_region_right
+ type: u2
+ valid:
+ expr: _ >= scrolling_region_left and _ < columns
+ - id: status_display
+ type: u1
+ enum: status_display
+ valid:
+ expr: _.to_i <= 1
+ - id: active_screen_key
+ type: u2
+ enum: screen_key
+ valid:
+ expr: _.to_i <= 1
+ - id: screen_count
+ type: u2
+ valid:
+ expr: (_ == 1 or _ == 2) and (active_screen_key.to_i == 0 or _ == 2)
+ - id: previous_codepoint
+ type: u4
+ valid:
+ expr: _ == 0xffffffff or (_ <= 0x10ffff and not (_ >= 0xd800 and _ <= 0xdfff))
+ - id: cursor_is_default
+ type: u1
+ valid:
+ max: 1
+ - id: cursor_default_style
+ type: u1
+ enum: cursor_style
+ valid:
+ expr: _.to_i <= 3
+ - id: cursor_default_blink
+ type: u1
+ valid:
+ max: 2
+ - id: shell_redraw
+ type: u1
+ enum: shell_redraw
+ valid:
+ expr: _.to_i <= 2
+ - id: modify_other_keys_2
+ type: u1
+ valid:
+ max: 1
+ - id: mouse_event
+ type: u1
+ enum: mouse_event
+ valid:
+ expr: _.to_i <= 4
+ - id: mouse_format
+ type: u1
+ enum: mouse_format
+ valid:
+ expr: _.to_i <= 4
+ - id: mouse_shift_capture
+ type: u1
+ valid:
+ max: 2
+ - id: mouse_shape
+ type: u1
+ enum: mouse_shape
+ valid:
+ expr: _.to_i <= 33
+ - id: password_input
+ type: u1
+ valid:
+ max: 1
+ - id: current_modes
+ type: mode_set
+ - id: saved_modes
+ type: mode_set
+ - id: default_modes
+ type: mode_set
+ - id: background
+ type: dynamic_rgb
+ - id: foreground
+ type: dynamic_rgb
+ - id: cursor_color
+ type: dynamic_rgb
+ - id: max_scrollback_bytes
+ type: u8
+ - id: max_scrollback_rows
+ type: u8
+
+ mode_set:
+ doc: |
+ The stable packed registry shared by current, saved, and default modes.
+ Each named instance exposes one bit from the little-endian integer.
+ Arithmetic division is used instead of bitwise operations because the
+ JavaScript target implements those operations with signed 32-bit values.
+ All values remain exact because the registry occupies only 43 bits,
+ within JavaScript's 53-bit safe integer range.
+ seq:
+ - id: raw
+ type: u8
+ valid:
+ max: 8796093022207
+ instances:
+ disable_keyboard:
+ value: (raw / 1) % 2 != 0
+ insert:
+ value: (raw / 2) % 2 != 0
+ send_receive_mode:
+ value: (raw / 4) % 2 != 0
+ linefeed:
+ value: (raw / 8) % 2 != 0
+ cursor_keys:
+ value: (raw / 16) % 2 != 0
+ column_132:
+ value: (raw / 32) % 2 != 0
+ slow_scroll:
+ value: (raw / 64) % 2 != 0
+ reverse_colors:
+ value: (raw / 128) % 2 != 0
+ origin:
+ value: (raw / 256) % 2 != 0
+ wraparound:
+ value: (raw / 512) % 2 != 0
+ autorepeat:
+ value: (raw / 1024) % 2 != 0
+ mouse_event_x10:
+ value: (raw / 2048) % 2 != 0
+ cursor_blinking:
+ value: (raw / 4096) % 2 != 0
+ cursor_visible:
+ value: (raw / 8192) % 2 != 0
+ enable_mode_3:
+ value: (raw / 16384) % 2 != 0
+ reverse_wrap:
+ value: (raw / 32768) % 2 != 0
+ alt_screen_legacy:
+ value: (raw / 65536) % 2 != 0
+ keypad_keys:
+ value: (raw / 131072) % 2 != 0
+ backarrow_key_mode:
+ value: (raw / 262144) % 2 != 0
+ enable_left_and_right_margin:
+ value: (raw / 524288) % 2 != 0
+ mouse_event_normal:
+ value: (raw / 1048576) % 2 != 0
+ mouse_event_button:
+ value: (raw / 2097152) % 2 != 0
+ mouse_event_any:
+ value: (raw / 4194304) % 2 != 0
+ focus_event:
+ value: (raw / 8388608) % 2 != 0
+ mouse_format_utf8:
+ value: (raw / 16777216) % 2 != 0
+ mouse_format_sgr:
+ value: (raw / 33554432) % 2 != 0
+ mouse_alternate_scroll:
+ value: (raw / 67108864) % 2 != 0
+ mouse_format_urxvt:
+ value: (raw / 134217728) % 2 != 0
+ mouse_format_sgr_pixels:
+ value: (raw / 268435456) % 2 != 0
+ ignore_keypad_with_numlock:
+ value: (raw / 536870912) % 2 != 0
+ alt_esc_prefix:
+ value: (raw / 1073741824) % 2 != 0
+ alt_sends_escape:
+ value: (raw / 2147483648) % 2 != 0
+ reverse_wrap_extended:
+ value: (raw / 4294967296) % 2 != 0
+ alt_screen:
+ value: (raw / 8589934592) % 2 != 0
+ save_cursor:
+ value: (raw / 17179869184) % 2 != 0
+ alt_screen_save_cursor_clear_enter:
+ value: (raw / 34359738368) % 2 != 0
+ bracketed_paste:
+ value: (raw / 68719476736) % 2 != 0
+ synchronized_output:
+ value: (raw / 137438953472) % 2 != 0
+ grapheme_cluster:
+ value: (raw / 274877906944) % 2 != 0
+ report_color_scheme:
+ value: (raw / 549755813888) % 2 != 0
+ report_visibility:
+ value: (raw / 1099511627776) % 2 != 0
+ in_band_size_reports:
+ value: (raw / 2199023255552) % 2 != 0
+ kitty_paste_events:
+ value: (raw / 4398046511104) % 2 != 0
+
+ tab_stops:
+ params:
+ - id: columns
+ type: u2
+ seq:
+ - id: complete_bytes
+ size: columns / 8
+ - id: partial_byte
+ type: u1
+ if: columns % 8 != 0
+ valid:
+ expr: _ < (1 << (columns % 8))
+
+ rgb:
+ seq:
+ - id: red
+ type: u1
+ - id: green
+ type: u1
+ - id: blue
+ type: u1
+
+ dynamic_rgb:
+ seq:
+ - id: default_present
+ type: u1
+ valid:
+ max: 1
+ - id: default_red
+ type: u1
+ valid:
+ expr: default_present == 1 or _ == 0
+ - id: default_green
+ type: u1
+ valid:
+ expr: default_present == 1 or _ == 0
+ - id: default_blue
+ type: u1
+ valid:
+ expr: default_present == 1 or _ == 0
+ - id: override_present
+ type: u1
+ valid:
+ max: 1
+ - id: override_red
+ type: u1
+ valid:
+ expr: override_present == 1 or _ == 0
+ - id: override_green
+ type: u1
+ valid:
+ expr: override_present == 1 or _ == 0
+ - id: override_blue
+ type: u1
+ valid:
+ expr: override_present == 1 or _ == 0
+
+ palette_override:
+ params:
+ - id: mask
+ type: bytes
+ - id: index
+ type: u2
+ seq:
+ - id: color
+ type: rgb
+ if: (mask[index / 8] & (1 << (index % 8))) != 0
+
+ screen_payload:
+ seq:
+ - id: header
+ type: screen_header
+ - id: saved_cursor
+ type: saved_cursor
+ if: header.saved_cursor_present == 1
+ - id: cursor_hyperlink
+ type: hyperlink(true, false)
+ - id: trailing_data
+ size-eos: true
+ valid:
+ expr: _.size == 0
+
+ screen_header:
+ seq:
+ - id: key
+ type: u2
+ enum: screen_key
+ valid:
+ expr: _.to_i <= 1
+ - id: page_count
+ type: u2
+ valid:
+ min: 1
+ - id: history_rows
+ type: u8
+ - id: cursor_x
+ type: u2
+ - id: cursor_y
+ type: u2
+ - id: cursor_style
+ type: u1
+ enum: cursor_style
+ valid:
+ expr: _.to_i <= 3
+ - id: cursor_flags
+ type: cursor_flags
+ - id: cursor_pen
+ type: style
+ - id: hyperlink_implicit_id
+ type: u4
+ - id: charset
+ type: charset_state
+ - id: protected_mode
+ type: u1
+ enum: protected_mode
+ valid:
+ expr: _.to_i <= 2
+ - id: kitty_keyboard_index
+ type: u1
+ valid:
+ max: 7
+ - id: kitty_keyboard_flags
+ type: kitty_keyboard_flags
+ repeat: expr
+ repeat-expr: 8
+ - id: semantic_click_kind
+ type: u1
+ enum: semantic_click_kind
+ valid:
+ expr: _.to_i <= 2
+ - id: semantic_click_value
+ type: u1
+ valid:
+ expr: |
+ semantic_click_kind.to_i == 0 ? _ == 0 :
+ semantic_click_kind.to_i == 1 ? _ <= 1 :
+ _ <= 3
+ - id: saved_cursor_present
+ type: u1
+ valid:
+ max: 1
+
+ cursor_flags:
+ seq:
+ - id: raw
+ type: u1
+ valid:
+ expr: (_ & 0xe0) == 0 and ((_ >> 2) & 0x3) <= 2
+ instances:
+ pending_wrap:
+ value: (raw & (1 << 0)) != 0
+ protected:
+ value: (raw & (1 << 1)) != 0
+ semantic_content:
+ value: (raw >> 2) & 0x3
+ semantic_content_clear_eol:
+ value: (raw & (1 << 4)) != 0
+
+ charset_state:
+ doc: |
+ Four selected character sets, the GL and GR slots, and an optional
+ single-shift slot. single_shift is zero for none or one plus a slot.
+ seq:
+ - id: raw
+ type: u2
+ valid:
+ expr: (_ & 0x8000) == 0 and ((_ >> 12) & 0x7) <= 4
+ instances:
+ g0:
+ value: (raw >> 0) & 0x3
+ g1:
+ value: (raw >> 2) & 0x3
+ g2:
+ value: (raw >> 4) & 0x3
+ g3:
+ value: (raw >> 6) & 0x3
+ gl:
+ value: (raw >> 8) & 0x3
+ gr:
+ value: (raw >> 10) & 0x3
+ single_shift:
+ value: (raw >> 12) & 0x7
+
+ kitty_keyboard_flags:
+ seq:
+ - id: raw
+ type: u1
+ valid:
+ expr: (_ & 0xe0) == 0
+ instances:
+ disambiguate:
+ value: (raw & (1 << 0)) != 0
+ report_events:
+ value: (raw & (1 << 1)) != 0
+ report_alternates:
+ value: (raw & (1 << 2)) != 0
+ report_all:
+ value: (raw & (1 << 3)) != 0
+ report_associated:
+ value: (raw & (1 << 4)) != 0
+
+ saved_cursor:
+ seq:
+ - id: x
+ type: u2
+ - id: y
+ type: u2
+ - id: pen
+ type: style
+ - id: flags
+ type: saved_cursor_flags
+ - id: charset
+ type: charset_state
+
+ saved_cursor_flags:
+ seq:
+ - id: raw
+ type: u1
+ valid:
+ expr: (_ & 0xf8) == 0
+ instances:
+ protected:
+ value: (raw & (1 << 0)) != 0
+ pending_wrap:
+ value: (raw & (1 << 1)) != 0
+ origin:
+ value: (raw & (1 << 2)) != 0
+
+ history_payload:
+ seq:
+ - id: key
+ type: u2
+ enum: screen_key
+ valid:
+ expr: _.to_i <= 1
+ - id: page_count
+ type: u4
+ - id: trailing_data
+ size-eos: true
+ valid:
+ expr: _.size == 0
+
+ page_payload:
+ seq:
+ - id: header
+ type: page_header
+ - id: styles
+ type: style_table_entry
+ repeat: expr
+ repeat-expr: header.style_count
+ - id: hyperlinks
+ type: hyperlink_table_entry
+ repeat: expr
+ repeat-expr: header.hyperlink_count
+ - id: grid
+ type: grid(header.rows, header.columns)
+ - id: trailing_data
+ size-eos: true
+ valid:
+ expr: _.size == 0
+
+ page_header:
+ seq:
+ - id: columns
+ type: u2
+ valid:
+ min: 1
+ - id: rows
+ type: u2
+ valid:
+ min: 1
+ - id: style_count
+ type: u2
+ - id: hyperlink_count
+ type: u2
+ - id: style_capacity
+ type: u2
+ - id: hyperlink_capacity_bytes
+ type: u2
+ - id: grapheme_capacity_bytes
+ type: u4
+ - id: string_capacity_bytes
+ type: u4
+
+ style_table_entry:
+ seq:
+ - id: encoded_id
+ type: u2
+ valid:
+ min: 1
+ - id: value
+ type: style
+
+ hyperlink_table_entry:
+ seq:
+ - id: encoded_id
+ type: u2
+ valid:
+ min: 1
+ - id: value
+ type: hyperlink(false, true)
+
+ style:
+ seq:
+ - id: foreground
+ type: style_color
+ - id: background
+ type: style_color
+ - id: underline_color
+ type: style_color
+ - id: flags
+ type: style_flags
+ - id: reserved
+ type: u2
+ valid: 0
+
+ style_flags:
+ seq:
+ - id: raw
+ type: u2
+ valid:
+ expr: (_ & 0xf800) == 0 and ((_ >> 8) & 0x7) <= 5
+ instances:
+ bold:
+ value: (raw & (1 << 0)) != 0
+ italic:
+ value: (raw & (1 << 1)) != 0
+ faint:
+ value: (raw & (1 << 2)) != 0
+ blink:
+ value: (raw & (1 << 3)) != 0
+ inverse:
+ value: (raw & (1 << 4)) != 0
+ invisible:
+ value: (raw & (1 << 5)) != 0
+ strikethrough:
+ value: (raw & (1 << 6)) != 0
+ overline:
+ value: (raw & (1 << 7)) != 0
+ underline:
+ value: (raw >> 8) & 0x7
+
+ style_color:
+ seq:
+ - id: kind
+ type: u1
+ enum: color_kind
+ valid:
+ expr: _.to_i <= 2
+ - id: first
+ type: u1
+ valid:
+ expr: kind.to_i != 0 or _ == 0
+ - id: second
+ type: u1
+ valid:
+ expr: kind.to_i == 2 or _ == 0
+ - id: third
+ type: u1
+ valid:
+ expr: kind.to_i == 2 or _ == 0
+
+ hyperlink:
+ params:
+ - id: allow_none
+ type: bool
+ - id: allow_empty
+ type: bool
+ seq:
+ - id: kind
+ type: u1
+ enum: hyperlink_kind
+ valid:
+ expr: _.to_i <= 2 and (allow_none or _.to_i != 0)
+ - id: implicit
+ type: implicit_hyperlink(allow_empty)
+ if: kind.to_i == 1
+ - id: explicit
+ type: explicit_hyperlink(allow_empty)
+ if: kind.to_i == 2
+
+ implicit_hyperlink:
+ params:
+ - id: allow_empty
+ type: bool
+ seq:
+ - id: id
+ type: u4
+ - id: len_uri
+ type: u4
+ valid:
+ expr: allow_empty or _ >= 1
+ - id: uri
+ size: len_uri
+
+ explicit_hyperlink:
+ params:
+ - id: allow_empty
+ type: bool
+ seq:
+ - id: len_id
+ type: u4
+ valid:
+ expr: allow_empty or _ >= 1
+ - id: id
+ size: len_id
+ - id: len_uri
+ type: u4
+ valid:
+ expr: allow_empty or _ >= 1
+ - id: uri
+ size: len_uri
+
+ grid:
+ params:
+ - id: num_rows
+ type: u2
+ - id: columns
+ type: u2
+ seq:
+ - id: rows
+ type: grid_row(columns)
+ repeat: expr
+ repeat-expr: num_rows
+ - id: num_grapheme_entries
+ type: u4
+ - id: grapheme_entries
+ type: grapheme_entry(num_rows, columns)
+ repeat: expr
+ repeat-expr: num_grapheme_entries
+
+ grid_row:
+ params:
+ - id: columns
+ type: u2
+ seq:
+ - id: flags
+ type: grid_row_flags
+ - id: cell_count
+ type: u2
+ valid:
+ expr: _ <= columns
+ - id: cells
+ type:
+ switch-on: flags.width_log2
+ cases:
+ 0: grid_cell_1
+ 1: grid_cell_2
+ 2: grid_cell_4
+ 3: grid_cell(_index, columns, flags.wrap)
+ repeat: expr
+ repeat-expr: cell_count
+
+ grid_row_flags:
+ seq:
+ - id: raw
+ type: u1
+ valid:
+ expr: (_ & 0xc0) == 0 and ((_ >> 2) & 0x3) <= 2
+ instances:
+ wrap:
+ value: (raw & 1) != 0
+ wrap_continuation:
+ value: (raw & 2) != 0
+ semantic_prompt:
+ value: (raw >> 2) & 0x3
+ width_log2:
+ value: (raw >> 4) & 0x3
+
+ grid_cell_1:
+ doc: One-byte encoded cell; the value is a codepoint at or below U+00FF.
+ seq:
+ - id: codepoint
+ type: u1
+
+ grid_cell_2:
+ doc: |
+ Two-byte encoded cell; the value is a codepoint at or below U+FFFF.
+ Canonical encoders never emit surrogates.
+ seq:
+ - id: codepoint
+ type: u2
+ valid:
+ expr: not (_ >= 0xd800 and _ <= 0xdfff)
+
+ grid_cell_4:
+ doc: |
+ Four-byte encoded cell holding the low half of the cell word: any
+ content kind and codepoint, style IDs one through sixty-three, and no
+ width, flag, or hyperlink bits.
+ seq:
+ - id: raw
+ type: u4
+ valid:
+ expr: |
+ (content_kind >= 2 or
+ (content <= 0x10ffff and
+ not (content >= 0xd800 and content <= 0xdfff))) and
+ (content_kind != 2 or content <= 0xff)
+ instances:
+ content_kind:
+ value: raw % 4
+ content:
+ value: (raw / 4) % 16777216
+ style_id:
+ value: raw / 67108864
+
+ grid_cell:
+ doc: |
+ One 64-bit little-endian cell word. The word is parsed as two 32-bit
+ halves so every derived field stays within JavaScript's safe integer
+ range, following the same approach as mode_set.
+
+ Canonical rules validated here: reserved semantic content is not
+ emitted, the hyperlink flag matches a nonzero hyperlink ID, codepoint
+ content is a Unicode scalar value, palette content uses only its low
+ eight bits, and spacer relationships match the preceding cell. Wide
+ markers cannot be validated forward because their spacer tail may be
+ the next cell or the implicit narrow cell after a short row.
+ params:
+ - id: index
+ type: u2
+ - id: columns
+ type: u2
+ - id: row_wrap
+ type: bool
+ seq:
+ - id: lo
+ type: u4
+ - id: hi
+ type: u4
+ valid:
+ expr: |
+ semantic_content <= 2 and
+ hyperlink == (hyperlink_id != 0) and
+ (content_kind >= 2 or
+ (content <= 0x10ffff and
+ not (content >= 0xd800 and content <= 0xdfff))) and
+ (content_kind != 2 or content <= 0xff) and
+ (width != 2 or
+ (index > 0 and
+ _parent.cells[index - 1].as<grid_cell>.width == 1)) and
+ (width != 3 or (index + 1 == columns and row_wrap))
+ instances:
+ content_kind:
+ value: lo % 4
+ content:
+ value: (lo / 4) % 16777216
+ style_id:
+ value: (lo / 67108864) + (hi % 1024) * 64
+ width:
+ value: (hi / 1024) % 4
+ protected:
+ value: (hi / 4096) % 2 != 0
+ hyperlink:
+ value: (hi / 8192) % 2 != 0
+ semantic_content:
+ value: (hi / 16384) % 4
+ hyperlink_id:
+ value: hi / 65536
+
+ grapheme_entry:
+ seq:
+ - id: row
+ type: u2
+ valid:
+ expr: _ < num_rows
+ - id: col
+ type: u2
+ valid:
+ expr: _ < columns
+ - id: num_codepoints
+ type: u2
+ valid:
+ min: 1
+ - id: codepoints
+ type: u4
+ repeat: expr
+ repeat-expr: num_codepoints
+ valid:
+ expr: _ <= 0x10ffff and not (_ >= 0xd800 and _ <= 0xdfff)
+ params:
+ - id: num_rows
+ type: u2
+ - id: columns
+ type: u2
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/snapshot.zig b/vendor/libghostty-vt/src/terminal/snapshot/snapshot.zig
new file mode 100644
index 00000000..9c6dc96d
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/snapshot.zig
@@ -0,0 +1,2100 @@
+//! Complete terminal snapshot encoding and restoration.
+
+const std = @import("std");
+const build_options = @import("terminal_options");
+const assert = std.debug.assert;
+const Allocator = std.mem.Allocator;
+const checkpoint = @import("checkpoint.zig");
+const continuation = @import("continuation.zig");
+const envelope = @import("envelope.zig");
+const test_fixture = @import("fixture.zig");
+const history = @import("history.zig");
+const page = @import("page.zig");
+const record = @import("record.zig");
+const screen = @import("screen.zig");
+const size = @import("../size.zig");
+const terminal = @import("terminal.zig");
+const Terminal = @import("../Terminal.zig");
+const TerminalStream = @import("../stream_terminal.zig").Stream;
+const terminal_kitty = @import("../kitty.zig");
+const TerminalPageList = @import("../PageList.zig");
+const TerminalScreen = @import("../Screen.zig");
+const TerminalScreenKey = @import("../ScreenSet.zig").Key;
+
+/// Re-export continuation to make it a bit more ergonomic to reference.
+pub const Continuation = continuation.Value;
+
+/// Errors possible while encoding one complete terminal snapshot.
+pub const EncodeError = terminal.EncodeError ||
+ screen.EncodeError ||
+ history.EncodeError ||
+ checkpoint.EncodeError ||
+ continuation.EncodeError;
+
+pub const EncodeOptions = struct {
+ continuation: Continuation,
+};
+
+/// Encode one complete terminal snapshot.
+///
+/// Encoding starts at the destination's current position. Only one record
+/// payload is buffered at a time; completed records stream immediately. On
+/// failure, the destination may contain a snapshot prefix without its required
+/// FINISH marker, and an output failure may have written part of a record.
+pub fn encode(
+ alloc: Allocator,
+ destination: *std.Io.Writer,
+ t: *const Terminal,
+ options: EncodeOptions,
+) EncodeError!void {
+ // Continuation errors must not emit even the snapshot envelope.
+ try continuation.validate(options.continuation);
+
+ // A measured 512-byte buffer handles our smallest records on the stack
+ // before larger records fall back to the heap.
+ var stack_alloc = std.heap.stackFallback(512, alloc);
+ var stream: record.Writer = .init(stack_alloc.get(), destination);
+ defer stream.deinit();
+
+ // 1. Envelope
+ try envelope.encode(stream.writer());
+
+ // 2. Terminal
+ try terminal.encode(t, &stream);
+
+ // 3. Primary and alt screen
+ try screen.encode(
+ t.screens.get(.primary).?,
+ .primary,
+ &stream,
+ );
+ if (t.screens.get(.alternate)) |alternate| try screen.encode(
+ alternate,
+ .alternate,
+ &stream,
+ );
+
+ // 4. Standard Stream continuation.
+ try continuation.encode(options.continuation, &stream);
+
+ // 5. Ready marker.
+ try checkpoint.encode(.ready, &stream);
+
+ // 6. History
+ try history.encode(
+ t.screens.get(.primary).?,
+ .primary,
+ &stream,
+ );
+ if (t.screens.get(.alternate)) |alternate| try history.encode(
+ alternate,
+ .alternate,
+ &stream,
+ );
+
+ // 7. Finish
+ try checkpoint.encode(.finish, &stream);
+}
+
+/// Errors possible while restoring one complete terminal snapshot.
+pub const DecodeError = Decoder.ReadyError || Decoder.NextError;
+
+pub const DecodeOptions = struct {
+ /// Largest non-ground continuation the decoder may allocate and return.
+ /// Set this to zero when only ground-state snapshots are acceptable.
+ max_continuation_bytes: usize,
+};
+
+/// One decoded Terminal and the bytes needed to resume its Stream.
+///
+/// `decode` returns this with all history present; `Decoder.ready` returns
+/// it at READY, when the terminal is complete for interactive use but its
+/// scrollback is still arriving through `Decoder.next`.
+///
+/// A successful decode owns both values. Keep this result alive until the
+/// Terminal's Stream has been restored, and always finish by calling `deinit`.
+/// The usual restoration sequence is:
+///
+/// 1. Inspect `continuation` and use its length to size continuation tracking.
+/// 2. Call `toOwned` once and store the returned Terminal at its final address.
+/// 3. Create the persistent, read-only standard TerminalStream for that
+/// address. If `continuation` contains bytes, feed them exactly once and
+/// verify that re-exporting the continuation returns the same bytes.
+/// 4. Call `deinit` to release the decoded continuation. The transferred
+/// Terminal and its Stream remain owned by the caller.
+/// 5. Process PTY bytes that came after the snapshot cut.
+///
+/// Do not create a Stream against the address of `terminal` in this struct.
+/// `toOwned` moves the Terminal, which would leave such a Stream pointing at
+/// its old address.
+pub const Decoded = struct {
+ /// Present until `toOwned` transfers the Terminal to the caller. Callers
+ /// may inspect it, but must transfer it before attaching a persistent
+ /// TerminalStream.
+ terminal: ?Terminal,
+
+ /// For decoded results, nonempty bytes are allocator-owned and remain
+ /// valid until `deinit`. Ground needs no replay. Bytes must be replayed
+ /// exactly once after the Terminal has reached its final address.
+ continuation: Continuation,
+
+ /// Advisory complete logical history extent declared by each restored
+ /// screen, including the resident overlap already carried by that
+ /// screen's own pages. A client may size scrollback UI from this at
+ /// READY, before HISTORY pages arrive; native row totals always remain
+ /// derived from the pages actually applied.
+ history_rows: std.EnumMap(TerminalScreenKey, u64),
+
+ /// Destroy an untransferred Terminal and always free continuation bytes.
+ /// After `toOwned`, this leaves the caller-owned Terminal untouched.
+ pub fn deinit(self: *Decoded, alloc: Allocator) void {
+ if (self.terminal) |*value| value.deinit(alloc);
+ switch (self.continuation) {
+ .ground => {},
+ .bytes => |bytes| alloc.free(bytes),
+ }
+ self.* = undefined;
+ }
+
+ /// Transfer the Terminal while retaining the continuation for replay.
+ ///
+ /// This may be called exactly once. Store the returned value directly at
+ /// its final address before creating the TerminalStream that will replay
+ /// `continuation`.
+ pub fn toOwned(self: *Decoded) Terminal {
+ const result = self.terminal.?;
+ self.terminal = null;
+ return result;
+ }
+};
+
+/// Incrementally restore one snapshot: renderable state first, then history.
+///
+/// The snapshot record order makes a terminal renderable at the READY
+/// marker, after only a small prefix of the stream. `Decoder` exposes
+/// that boundary: `ready` returns a complete, integrity-checked `Decoded` while
+/// scrollback is still in flight, and each `next` call then applies one
+/// history PAGE record off the critical path. `snapshot.decode` is the
+/// one-shot form and is implemented over this type.
+///
+/// ```zig
+/// var decoder: snapshot.Decoder = .init(&reader);
+/// var decoded = try decoder.ready(alloc, io, .{
+/// .max_continuation_bytes = 1024 * 1024,
+/// });
+/// defer decoded.deinit(alloc);
+///
+/// var terminal = decoded.toOwned();
+/// defer terminal.deinit(alloc);
+/// // The terminal is usable now: restore its Stream from the decoded
+/// // continuation and size scrollback UI from `decoded.history_rows`.
+///
+/// while (try decoder.next(alloc, &terminal)) |progress| {
+/// _ = progress; // Scrollback grew; e.g. refresh the scrollbar.
+/// }
+/// // FINISH validated: the complete snapshot has been decoded.
+/// ```
+///
+/// The terminal is live between `next` calls: the caller may render it and
+/// even feed it PTY bytes that arrived after the snapshot cut. `next`
+/// re-validates its destination on every call and degrades to discarding,
+/// consuming and validating wire bytes without applying them, when live
+/// changes have made a page inapplicable. See `next` for the drop rules.
+///
+/// The decoder owns no allocations and needs no deinit. It retains the
+/// source pointer given to `init`; the source must stay valid, and must not
+/// be read elsewhere, until decoding ends. The decoder itself is movable
+/// between calls. After any returned error both the decoder and the stream
+/// position are invalid: abandon the decoder, and destroy an already
+/// transferred Terminal or keep it with partial history, but do not resume.
+pub const Decoder = struct {
+ source: *std.Io.Reader,
+ state: State,
+
+ const State = union(enum) {
+ /// `ready` has not been called.
+ start,
+
+ /// READY validated; HISTORY sequences remain before FINISH.
+ history: History,
+
+ /// FINISH validated. `next` returns null.
+ finished,
+
+ /// A call returned an error; the stream position is unknown.
+ failed,
+ };
+
+ const History = struct {
+ /// The generation observed at READY for every screen the snapshot
+ /// declared. Presence is the declaration check for HISTORY routing;
+ /// the value detects screens removed or replaced by live terminal
+ /// use between calls.
+ generations: std.EnumMap(TerminalScreenKey, usize),
+
+ /// Keys whose HISTORY sequence was already consumed.
+ routed: std.EnumSet(TerminalScreenKey),
+
+ /// HISTORY sequences that have not begun streaming yet.
+ pending: usize,
+
+ /// The sequence currently streaming PAGE records.
+ current: ?Sequence,
+
+ /// Terminal width at READY. Encoded pages assume this width and are
+ /// dropped rather than mixed into a screen reflowed to another.
+ cols: size.CellCountInt,
+ };
+
+ const Sequence = struct {
+ key: TerminalScreenKey,
+
+ /// PAGE records not yet consumed from this sequence.
+ remaining: u32,
+
+ /// False once any page in this sequence was dropped. Later pages
+ /// are older, and applying one above a gap would corrupt scrollback
+ /// order, so a single drop discards the remainder of the sequence.
+ apply: bool,
+ };
+
+ /// The decoder begins reading only when `ready` is called.
+ pub fn init(source: *std.Io.Reader) Decoder {
+ return .{
+ .source = source,
+ .state = .start,
+ };
+ }
+
+ /// Errors possible while decoding the renderable prefix through READY.
+ pub const ReadyError = envelope.DecodeError ||
+ terminal.DecodeError ||
+ screen.DecodeError ||
+ continuation.DecodeError ||
+ checkpoint.DecodeError ||
+ error{
+ /// A SCREEN names a key not declared by TERMINAL.
+ UnexpectedScreenKey,
+
+ /// More than one SCREEN names the same key.
+ DuplicateScreen,
+ };
+
+ /// Decode through the READY marker and return the renderable state.
+ ///
+ /// The result is transactional and complete for interactive use: the
+ /// Terminal, its continuation, and the advisory history extents are all
+ /// validated through READY. Scrollback history is not present yet and
+ /// arrives through `next`. Asserts this is the first call.
+ pub fn ready(
+ self: *Decoder,
+ alloc: Allocator,
+ io_: std.Io,
+ options: DecodeOptions,
+ ) ReadyError!Decoded {
+ assert(self.state == .start);
+ errdefer self.state = .failed;
+ const reader = self.source;
+
+ // Read the envelope, which is currently just a verification step.
+ try envelope.decode(reader);
+
+ // TERMINAL establishes terminal-wide state and allocates empty
+ // screen slots with their final routing. SCREEN values replace those
+ // slots in place so ScreenSet pointers, including the active
+ // pointer, stay valid.
+ var result = try terminal.decode(reader, io_, alloc);
+ errdefer result.deinit(alloc);
+
+ // TERMINAL initializes exactly the number of screen slots it
+ // declared. Decode that many SCREEN sequences and route each one by
+ // its encoded key.
+ const screen_count = result.screens.all.count();
+ const screen_options: TerminalScreen.Options = options: {
+ const primary = result.screens.get(.primary).?;
+ const explicit_bytes = primary.pages.limits.bytes.explicit;
+ const explicit_lines = primary.pages.limits.lines.explicit;
+ break :options .{
+ .cols = result.cols,
+ .rows = result.rows,
+ .max_scrollback_bytes = if (explicit_bytes == std.math.maxInt(usize))
+ null
+ else
+ explicit_bytes,
+ .max_scrollback_lines = if (explicit_lines == std.math.maxInt(usize))
+ null
+ else
+ explicit_lines,
+ };
+ };
+
+ var routed: std.EnumSet(TerminalScreenKey) = .initEmpty();
+ var history_rows: std.EnumMap(TerminalScreenKey, u64) = .init(.{});
+ for (0..screen_count) |_| {
+ var decoded = try screen.decode(
+ reader,
+ io_,
+ alloc,
+ screen_options,
+ );
+ errdefer decoded.deinit();
+
+ const slot = result.screens.get(decoded.key) orelse
+ return error.UnexpectedScreenKey;
+ if (routed.contains(decoded.key)) return error.DuplicateScreen;
+ routed.insert(decoded.key);
+ history_rows.put(decoded.key, decoded.history_rows);
+
+ slot.deinit();
+ slot.* = decoded.screen;
+ decoded.screen = undefined;
+ }
+
+ // CONTINUATION is required after every active screen. Nonempty bytes
+ // are owned locally until the READY prefix validates.
+ const decoded_continuation = try continuation.decode(
+ alloc,
+ reader,
+ options.max_continuation_bytes,
+ );
+ errdefer switch (decoded_continuation) {
+ .ground => {},
+ .bytes => |bytes| alloc.free(bytes),
+ };
+
+ // READY marks the exact envelope-through-CONTINUATION boundary.
+ try checkpoint.decode(.ready, self.source);
+
+ // Record where history may be applied. The declared keys route the
+ // HISTORY sequences, and the generations detect declared screens
+ // that live terminal use destroys or replaces before their history
+ // arrives.
+ var generations: std.EnumMap(TerminalScreenKey, usize) = .init(.{});
+ var it = result.screens.all.iterator();
+ while (it.next()) |entry| generations.put(
+ entry.key,
+ result.screens.generation(entry.key),
+ );
+
+ self.state = .{ .history = .{
+ .generations = generations,
+ .routed = .initEmpty(),
+ .pending = screen_count,
+ .current = null,
+ .cols = result.cols,
+ } };
+ return .{
+ .terminal = result,
+ .continuation = decoded_continuation,
+ .history_rows = history_rows,
+ };
+ }
+
+ /// One history PAGE record consumed by `next`.
+ pub const Progress = struct {
+ /// The screen whose HISTORY sequence contained the decoded page.
+ key: TerminalScreenKey,
+
+ /// Rows prepended above that screen's existing content, or zero
+ /// when the page was consumed and validated but dropped.
+ rows: usize,
+
+ /// PAGE records still pending in the same HISTORY sequence.
+ remaining: u32,
+ };
+
+ /// Errors possible while decoding history records through FINISH.
+ pub const NextError = checkpoint.DecodeError ||
+ history.Decoder.InitError ||
+ page.DiscardError ||
+ page.DecodeError ||
+ Allocator.Error ||
+ error{
+ /// `next` was called before `ready` completed successfully.
+ DecoderNotReady,
+
+ /// A prior `next` call failed and invalidated the stream position.
+ DecoderFailed,
+
+ /// A HISTORY names a key not declared by TERMINAL.
+ UnexpectedHistoryKey,
+
+ /// More than one HISTORY names the same key.
+ DuplicateHistory,
+
+ /// A history PAGE cannot join a native PageList.
+ /// These propagate from `nextPage`'s non-limit finalize errors;
+ /// only limit failures are deliberately converted into drops.
+ InvalidPageDimensions,
+ RowCountOverflow,
+ PageSizeOverflow,
+ };
+
+ /// Decode one history PAGE record and prepend it to its screen in `t`.
+ ///
+ /// `t` must be the Terminal restored by this decoder's `ready` call,
+ /// wherever the caller now stores it. Returns null once FINISH has
+ /// validated, which completes the snapshot; the source is
+ /// left positioned exactly after it. Further calls return null.
+ ///
+ /// Wire validation stays strict: framing, CRCs, record order, routing,
+ /// and both marker records are always enforced. Application is
+ /// forgiving, because the terminal is live and may have changed since
+ /// READY. A page is consumed but dropped, reported as zero rows, when:
+ ///
+ /// * its screen was removed, or removed and recreated, since READY
+ /// (detected through ScreenSet generations);
+ /// * the terminal was resized since READY, since encoded pages assume
+ /// the encoded width;
+ /// * prepending it would exceed the screen's scrollback limits, e.g.
+ /// because post-cut output already consumed that budget, making
+ /// immediate eviction the only alternative.
+ ///
+ /// Once a page in a sequence is dropped, the rest of that sequence is
+ /// discarded too: later pages are older, and applying one above a gap
+ /// would corrupt scrollback ordering. History for other screens is
+ /// unaffected.
+ pub fn next(
+ self: *Decoder,
+ alloc: Allocator,
+ t: *Terminal,
+ ) NextError!?Progress {
+ switch (self.state) {
+ // `ready` must succeed before history exists to decode, and a
+ // failed decoder no longer knows its stream position.
+ .start => return error.DecoderNotReady,
+ .failed => return error.DecoderFailed,
+ .finished => return null,
+ .history => {},
+ }
+ errdefer self.state = .failed;
+ const state = &self.state.history;
+
+ while (true) {
+ // Stream the current sequence's next PAGE if one remains.
+ if (state.current) |*sequence| {
+ if (sequence.remaining > 0) {
+ return try self.nextPage(alloc, t, sequence);
+ }
+ state.current = null;
+ }
+
+ // All sequences are consumed: FINISH ends the snapshot, leaving
+ // trailing transport bytes unread.
+ if (state.pending == 0) {
+ try checkpoint.decode(.finish, self.source);
+ if (comptime build_options.slow_runtime_safety) {
+ var it = state.generations.iterator();
+ while (it.next()) |entry| {
+ const restored = t.screens.get(entry.key) orelse
+ continue;
+ restored.pages.assertIntegrity();
+ restored.assertIntegrity();
+ }
+ }
+ self.state = .finished;
+ return null;
+ }
+
+ // Begin the next HISTORY sequence. Keys route the sequences
+ // order-independently, but each must name a declared screen and
+ // may not repeat.
+ state.pending -= 1;
+ var manifest: history.Decoder = undefined;
+ try manifest.init(self.source);
+ const key = manifest.header.key;
+ if (state.generations.get(key) == null) {
+ return error.UnexpectedHistoryKey;
+ }
+ if (state.routed.contains(key)) return error.DuplicateHistory;
+ state.routed.insert(key);
+ state.current = .{
+ .key = key,
+ .remaining = manifest.header.page_count,
+ .apply = true,
+ };
+ }
+ }
+
+ /// Consume one PAGE record from the current sequence, applying it to
+ /// the live terminal when it is still applicable and discarding it
+ /// otherwise.
+ fn nextPage(
+ self: *Decoder,
+ alloc: Allocator,
+ t: *Terminal,
+ sequence: *Sequence,
+ ) NextError!Progress {
+ const state = &self.state.history;
+
+ // Application is re-decided on every page so live terminal changes
+ // between calls degrade to discarding instead of failing decoding.
+ const destination: ?*TerminalScreen = destination: {
+ if (!sequence.apply) break :destination null;
+ if (t.cols != state.cols) break :destination null;
+ const restored = t.screens.get(sequence.key) orelse
+ break :destination null;
+ if (t.screens.generation(sequence.key) !=
+ state.generations.get(sequence.key).?)
+ {
+ break :destination null;
+ }
+ break :destination restored;
+ };
+
+ sequence.remaining -= 1;
+ const rows: usize = rows: {
+ const restored = destination orelse {
+ // The record must still be consumed so decoding remains
+ // aligned with the following records and FINISH marker.
+ sequence.apply = false;
+ try page.discard(self.source);
+ break :rows 0;
+ };
+ // The one-shot history decoder rejects a Screen which already has
+ // complete history. This incremental path intentionally bypasses
+ // that guard: the terminal has been live since READY and may have
+ // accumulated new history. Generation and width checks above keep
+ // the destination compatible, while per-page finalization enforces
+ // its current scrollback limits.
+ break :rows history.decodePage(
+ self.source,
+ alloc,
+ restored,
+ ) catch |err| switch (err) {
+ // The page no longer fits the screen's scrollback limits,
+ // e.g. because post-cut output consumed the budget, so it
+ // would be evicted immediately anyway. Its record was fully
+ // consumed, leaving the stream aligned on the next record.
+ error.MaxSizeExceeded,
+ error.MaxLinesExceeded,
+ => drop: {
+ sequence.apply = false;
+ break :drop 0;
+ },
+ else => |other| return other,
+ };
+ };
+
+ return .{
+ .key = sequence.key,
+ .rows = rows,
+ .remaining = sequence.remaining,
+ };
+ }
+};
+
+/// Restore one complete snapshot into a native Terminal and continuation.
+///
+/// This consumes one snapshot through FINISH and leaves any following bytes
+/// in the reader for the containing transport. Restoration is transactional:
+/// the returned result is either complete and ready or not (error return).
+/// Individual record codecs normalize optional semantic state, and history
+/// beyond the declared scrollback limits is dropped rather than rejected,
+/// while framing, markers, declared sequence counts, and unique
+/// cross-record screen routing remain strict.
+///
+/// This is the one-shot form of `Decoder`, which can additionally hand the
+/// renderable terminal to the caller at READY, before history arrives.
+pub fn decode(
+ alloc: Allocator,
+ io_: std.Io,
+ source: *std.Io.Reader,
+ options: DecodeOptions,
+) DecodeError!Decoded {
+ var decoder: Decoder = .init(source);
+ var result = try decoder.ready(alloc, io_, options);
+ errdefer result.deinit(alloc);
+
+ // The Terminal has not been transferred, so history applies in place.
+ const t = &result.terminal.?;
+ while (try decoder.next(alloc, t)) |_| {}
+ return result;
+}
+
+/// Errors possible while restoring a snapshot that must end at end-of-file.
+pub const DecodeExactError = DecodeError || std.Io.Reader.Error || error{
+ /// FINISH was followed by additional bytes.
+ TrailingData,
+};
+
+/// Restore one snapshot and require FINISH to be followed by end-of-file.
+///
+/// This is intended for bounded snapshot files and buffers. On a live stream,
+/// checking for end-of-file may block; use `decode` to stop at FINISH instead.
+pub fn decodeExact(
+ alloc: Allocator,
+ io_: std.Io,
+ source: *std.Io.Reader,
+ options: DecodeOptions,
+) DecodeExactError!Decoded {
+ var result = try decode(alloc, io_, source, options);
+ errdefer result.deinit(alloc);
+
+ _ = source.peekByte() catch |err| switch (err) {
+ error.EndOfStream => return result,
+ else => return err,
+ };
+ return error.TrailingData;
+}
+
+const test_encode_options: EncodeOptions = .{ .continuation = .ground };
+const test_decode_options: DecodeOptions = .{ .max_continuation_bytes = 1024 };
+const test_complete_fixture = test_fixture.parse(@embedFile("testdata/complete-v1.hex"));
+
+/// Build a 2x3 test terminal whose primary screen carries `history_pages`
+/// complete two-row pages above a three-row active page. The top-left cell
+/// of each page is marked 'A', 'B', ... from oldest history to active.
+fn testHistoryTerminal(history_pages: u8) !Terminal {
+ const testing = std.testing;
+ var t = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 2,
+ .rows = 3,
+ .max_scrollback_bytes = null,
+ .max_scrollback_lines = null,
+ });
+ errdefer t.deinit(testing.allocator);
+
+ const primary = t.screens.get(.primary).?;
+ var replacement: TerminalScreen = replacement: {
+ var builder = try TerminalPageList.Builder.init(
+ testing.allocator,
+ .{
+ .cols = t.cols,
+ .rows = t.rows,
+ .max_size = null,
+ .max_lines = null,
+ },
+ );
+ defer builder.deinit();
+
+ for (0..history_pages) |index| {
+ const built = try builder.allocatePage(.{ .cols = 2, .rows = 2 });
+ built.size.rows = 2;
+ built.getRowAndCell(0, 0).cell.* = .init(
+ @intCast('A' + index),
+ );
+ }
+ const active = try builder.allocatePage(.{ .cols = 2, .rows = 3 });
+ active.size.rows = 3;
+ active.getRowAndCell(0, 0).cell.* = .init(
+ @intCast('A' + @as(usize, history_pages)),
+ );
+
+ var pages = try builder.finish();
+ errdefer pages.deinit();
+ const cursor_pin = try pages.trackPin(
+ pages.pin(.{ .active = .{} }).?,
+ );
+ const cursor_rac = cursor_pin.rowAndCell();
+ break :replacement .{
+ .io = testing.io,
+ .alloc = testing.allocator,
+ .pages = pages,
+ .cursor = .{
+ .page_pin = cursor_pin,
+ .page_row = cursor_rac.row,
+ .page_cell = cursor_rac.cell,
+ },
+ };
+ };
+ primary.deinit();
+ primary.* = replacement;
+ replacement = undefined;
+ return t;
+}
+
+/// The top-left screen cell, which lands in the oldest applied history page.
+fn testTopLeftCodepoint(terminal_screen: *const TerminalScreen) u21 {
+ return terminal_screen.pages.getTopLeft(.screen).node
+ .page().getRowAndCell(0, 0).cell.codepoint();
+}
+
+test "complete snapshot round trip with history and alternate screen" {
+ const testing = std.testing;
+
+ var t = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 2,
+ .rows = 3,
+ .max_scrollback_bytes = null,
+ .max_scrollback_lines = null,
+ });
+ defer t.deinit(testing.allocator);
+
+ // Exercise terminal-wide state.
+ t.width_px = 800;
+ t.height_px = 600;
+ t.colors.palette.set(7, .{ .r = 1, .g = 2, .b = 3 });
+ t.modes.values.bracketed_paste = true;
+ try t.setPwd("file:///tmp/snapshot");
+ try t.setTitle("complete snapshot");
+
+ const primary = t.screens.get(.primary).?;
+
+ // Use small exact capacities so this compound golden remains practical to
+ // review while still containing two complete history pages and one active
+ // page. Replacing the Screen in place preserves ScreenSet routing.
+ var replacement: TerminalScreen = replacement: {
+ var builder = try TerminalPageList.Builder.init(
+ testing.allocator,
+ .{
+ .cols = t.cols,
+ .rows = t.rows,
+ .max_size = null,
+ .max_lines = null,
+ },
+ );
+ defer builder.deinit();
+
+ const oldest = try builder.allocatePage(.{ .cols = 2, .rows = 2 });
+ oldest.size.rows = 2;
+ oldest.getRowAndCell(0, 0).cell.* = .init('A');
+
+ const recent = try builder.allocatePage(.{ .cols = 2, .rows = 2 });
+ recent.size.rows = 2;
+ recent.getRowAndCell(0, 0).cell.* = .init('B');
+
+ const active = try builder.allocatePage(.{ .cols = 2, .rows = 3 });
+ active.size.rows = 3;
+ active.getRowAndCell(0, 0).cell.* = .init('C');
+ active.getRowAndCell(0, 1).cell.* = .init('D');
+ active.getRowAndCell(0, 2).cell.* = .init('E');
+
+ var pages = try builder.finish();
+ errdefer pages.deinit();
+
+ const cursor_pin = try pages.trackPin(
+ pages.pin(.{ .active = .{} }).?,
+ );
+ const cursor_rac = cursor_pin.rowAndCell();
+ break :replacement .{
+ .io = testing.io,
+ .alloc = testing.allocator,
+ .pages = pages,
+ .cursor = .{
+ .page_pin = cursor_pin,
+ .page_row = cursor_rac.row,
+ .page_cell = cursor_rac.cell,
+ },
+ };
+ };
+ primary.deinit();
+ primary.* = replacement;
+ replacement = undefined;
+
+ try testing.expect(primary.pages.scrollbar().total > t.rows);
+
+ // Compression is an internal source representation and must remain
+ // unchanged while the complete history is inspected for encoding.
+ _ = primary.pages.compress(.full);
+ const source_memory = primary.pages.memoryStats();
+
+ // The optional alternate screen participates in both phases and remains
+ // the active screen after restoration.
+ _ = try t.switchScreen(.alternate);
+ try t.printString("alternate");
+
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, test_encode_options);
+ try testing.expectEqualDeep(source_memory, primary.pages.memoryStats());
+ try test_fixture.expectEqual(
+ .snapshot,
+ "src/terminal/snapshot/testdata/complete-v1.hex",
+ "snapshot_fixture-complete-v1.hex",
+ &test_complete_fixture,
+ encoded.written(),
+ );
+
+ // A complete snapshot can stream through a non-allocating destination.
+ // Independently hash that output so both its length and complete byte
+ // sequence are checked without retaining a second snapshot copy.
+ var discard: std.Io.Writer.Discarding = .init(&.{});
+ var hashing = discard.writer.hashed(record.Crc32c.init(), &.{});
+ try encode(testing.allocator, &hashing.writer, &t, test_encode_options);
+ try testing.expectEqual(
+ @as(u64, test_complete_fixture.len),
+ discard.fullCount(),
+ );
+ try testing.expectEqual(
+ record.Crc32c.hash(&test_complete_fixture),
+ hashing.hasher.final(),
+ );
+
+ // Restore the checked-in reference rather than the just-generated bytes.
+ var encoded_source: std.Io.Reader = .fixed(&test_complete_fixture);
+ var source_buffer: [1]u8 = undefined;
+ var limited = encoded_source.limited(.unlimited, &source_buffer);
+ var restored = try decode(
+ testing.allocator,
+ testing.io,
+ &limited.interface,
+ test_decode_options,
+ );
+ defer restored.deinit(testing.allocator);
+ const restored_terminal = &restored.terminal.?;
+
+ try testing.expectEqual(
+ TerminalScreenKey.alternate,
+ restored_terminal.screens.active_key,
+ );
+ try testing.expectEqual(
+ restored_terminal.screens.get(.alternate).?,
+ restored_terminal.screens.active,
+ );
+ try testing.expectEqualStrings(
+ "file:///tmp/snapshot",
+ restored_terminal.getPwd().?,
+ );
+ try testing.expectEqualStrings(
+ "complete snapshot",
+ restored_terminal.getTitle().?,
+ );
+ try testing.expectEqual(
+ primary.pages.scrollbar().total,
+ restored_terminal.screens.get(.primary).?.pages.scrollbar().total,
+ );
+
+ // Re-encoding is a compact semantic equality check over all TERMINAL,
+ // SCREEN, PAGE, and HISTORY fields and both marker boundaries.
+ var reencoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer reencoded.deinit();
+ try encode(
+ testing.allocator,
+ &reencoded.writer,
+ restored_terminal,
+ test_encode_options,
+ );
+ try testing.expectEqualStrings(
+ &test_complete_fixture,
+ reencoded.written(),
+ );
+
+ // SCREEN and HISTORY keys make both sequence groups order independent.
+ var reversed: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer reversed.deinit();
+ var reversed_stream: record.Writer = .init(
+ testing.allocator,
+ &reversed.writer,
+ );
+ defer reversed_stream.deinit();
+ try envelope.encode(reversed_stream.writer());
+ try terminal.encode(&t, &reversed_stream);
+ try screen.encode(
+ t.screens.get(.alternate).?,
+ .alternate,
+ &reversed_stream,
+ );
+ try screen.encode(primary, .primary, &reversed_stream);
+ try continuation.encode(.ground, &reversed_stream);
+ try checkpoint.encode(.ready, &reversed_stream);
+ try history.encode(
+ t.screens.get(.alternate).?,
+ .alternate,
+ &reversed_stream,
+ );
+ try history.encode(primary, .primary, &reversed_stream);
+ try checkpoint.encode(.finish, &reversed_stream);
+
+ var reversed_source: std.Io.Reader = .fixed(reversed.written());
+ var reversed_restored = try decode(
+ testing.allocator,
+ testing.io,
+ &reversed_source,
+ test_decode_options,
+ );
+ defer reversed_restored.deinit(testing.allocator);
+ const reversed_terminal = &reversed_restored.terminal.?;
+ try testing.expectEqual(
+ TerminalScreenKey.alternate,
+ reversed_terminal.screens.active_key,
+ );
+ try testing.expectEqual(
+ @as(usize, 0),
+ reversed_terminal.screens.generation(.primary),
+ );
+ try testing.expectEqual(
+ @as(usize, 0),
+ reversed_terminal.screens.generation(.alternate),
+ );
+}
+
+test "complete snapshot restores a canonical Stream continuation" {
+ const testing = std.testing;
+
+ var source_terminal = try Terminal.init(
+ testing.io,
+ testing.allocator,
+ .{ .cols = 8, .rows = 2 },
+ );
+ defer source_terminal.deinit(testing.allocator);
+ var source_stream = TerminalStream.init(.{
+ .allocator = testing.allocator,
+ .handler = .init(&source_terminal),
+ .continuation_max_bytes = 1024,
+ });
+ defer source_stream.deinit();
+
+ source_stream.nextSlice("A\x1b[31");
+ var exported_bytes: [1024]u8 = undefined;
+ var exported: std.Io.Writer = .fixed(&exported_bytes);
+ try source_stream.writeContinuation(&exported);
+ try testing.expectEqualStrings("\x1b[31", exported.buffered());
+
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &source_terminal, .{
+ .continuation = .{ .bytes = exported.buffered() },
+ });
+
+ var encoded_source: std.Io.Reader = .fixed(encoded.written());
+ var decoded = try decode(
+ testing.allocator,
+ testing.io,
+ &encoded_source,
+ .{ .max_continuation_bytes = 1024 },
+ );
+ defer decoded.deinit(testing.allocator);
+ try testing.expectEqualStrings(
+ exported.buffered(),
+ decoded.continuation.bytes,
+ );
+
+ var restored_terminal = decoded.toOwned();
+ defer restored_terminal.deinit(testing.allocator);
+ try testing.expect(decoded.terminal == null);
+ var restored_stream = TerminalStream.init(.{
+ .allocator = testing.allocator,
+ .handler = .init(&restored_terminal),
+ .continuation_max_bytes = 1024,
+ });
+ defer restored_stream.deinit();
+
+ restored_stream.nextSlice(decoded.continuation.bytes);
+ var reexported_bytes: [1024]u8 = undefined;
+ var reexported: std.Io.Writer = .fixed(&reexported_bytes);
+ try restored_stream.writeContinuation(&reexported);
+ try testing.expectEqualStrings(exported.buffered(), reexported.buffered());
+
+ // The identical post-cut bytes may use different feed chunking without
+ // changing terminal semantics.
+ source_stream.nextSlice("mB");
+ restored_stream.next('m');
+ restored_stream.next('B');
+ const source_text = try source_terminal.plainString(testing.allocator);
+ defer testing.allocator.free(source_text);
+ const restored_text = try restored_terminal.plainString(testing.allocator);
+ defer testing.allocator.free(restored_text);
+ try testing.expectEqualStrings(source_text, restored_text);
+ try testing.expectEqual(
+ source_terminal.screens.active.cursor.style_id,
+ restored_terminal.screens.active.cursor.style_id,
+ );
+}
+
+test "complete snapshot validates continuation before writing" {
+ const testing = std.testing;
+ var t = try Terminal.init(
+ testing.io,
+ testing.allocator,
+ .{ .cols = 2, .rows = 1 },
+ );
+ defer t.deinit(testing.allocator);
+
+ var destination: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer destination.deinit();
+ try destination.writer.writeAll("prefix");
+ try testing.expectError(
+ error.NoPendingState,
+ encode(testing.allocator, &destination.writer, &t, .{
+ .continuation = .{ .bytes = "\x1b[31m" },
+ }),
+ );
+ try testing.expectEqualStrings("prefix", destination.written());
+
+ var tail = [_]u8{ 0x1b, '[', '3', '1' };
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, .{
+ .continuation = .{ .bytes = &tail },
+ });
+ tail[2] = '4';
+
+ var source: std.Io.Reader = .fixed(encoded.written());
+ var decoded = try decode(
+ testing.allocator,
+ testing.io,
+ &source,
+ test_decode_options,
+ );
+ defer decoded.deinit(testing.allocator);
+ try testing.expectEqualStrings("\x1b[31", decoded.continuation.bytes);
+}
+
+test "complete snapshot waits for continuation tracking recovery" {
+ const testing = std.testing;
+ var t = try Terminal.init(
+ testing.io,
+ testing.allocator,
+ .{ .cols = 2, .rows = 1 },
+ );
+ defer t.deinit(testing.allocator);
+ var stream = TerminalStream.init(.{
+ .allocator = testing.allocator,
+ .handler = .init(&t),
+ .continuation_max_bytes = 4,
+ });
+ defer stream.deinit();
+
+ stream.nextSlice("\x1b[123");
+ var unavailable_bytes: [4]u8 = undefined;
+ var unavailable: std.Io.Writer = .fixed(&unavailable_bytes);
+ try testing.expectError(
+ error.ContinuationUnavailable,
+ stream.writeContinuation(&unavailable),
+ );
+
+ // A new replay start replaces the lost suffix and makes a later cut
+ // publishable without affecting normal terminal parsing.
+ stream.nextSlice("\x1b[");
+ var recovered_bytes: [4]u8 = undefined;
+ var recovered: std.Io.Writer = .fixed(&recovered_bytes);
+ try stream.writeContinuation(&recovered);
+ try testing.expectEqualStrings("\x1b[", recovered.buffered());
+
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, .{
+ .continuation = .{ .bytes = recovered.buffered() },
+ });
+}
+
+test "complete snapshot preserves every supported continuation cut" {
+ const testing = std.testing;
+ const corpora = [_][]const u8{
+ "plain \xF0\x9F\x98\x84 utf8",
+ "bad \xE0\xA0\xF0\x9F\x98\x84 utf8",
+ "\x1b[1\x07;2mstyled\x1b[0m",
+ "\x1b]2;window title\x1b\\text",
+ "\x1bP$qm\x1b\\text",
+ "\x1b_Ga=q;payload\x1b\\text",
+ "\x1b_25a1;s\x1b\\text",
+ "\x1b]2;first\x1b\\\x1b_Gsecond",
+ "\x1b[12\x9D2;title\x1b\\text",
+ "\x1b[12\x18text\x1b[1\x1Atext",
+ };
+
+ for (corpora) |corpus| for (0..corpus.len + 1) |cut| {
+ var source_terminal = try Terminal.init(
+ testing.io,
+ testing.allocator,
+ .{ .cols = 20, .rows = 4 },
+ );
+ defer source_terminal.deinit(testing.allocator);
+ var source_stream = TerminalStream.init(.{
+ .allocator = testing.allocator,
+ .handler = .init(&source_terminal),
+ .continuation_max_bytes = 4096,
+ });
+ defer source_stream.deinit();
+ source_stream.nextSlice(corpus[0..cut]);
+
+ var cut_bytes: [4096]u8 = undefined;
+ var cut_writer: std.Io.Writer = .fixed(&cut_bytes);
+ try source_stream.writeContinuation(&cut_writer);
+ const cut_continuation: Continuation = if (cut_writer.end == 0)
+ .ground
+ else
+ .{ .bytes = cut_writer.buffered() };
+
+ var snapshot_bytes: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer snapshot_bytes.deinit();
+ try encode(
+ testing.allocator,
+ &snapshot_bytes.writer,
+ &source_terminal,
+ .{ .continuation = cut_continuation },
+ );
+
+ var snapshot_source: std.Io.Reader = .fixed(snapshot_bytes.written());
+ var decoded = try decode(
+ testing.allocator,
+ testing.io,
+ &snapshot_source,
+ .{ .max_continuation_bytes = 4096 },
+ );
+ defer decoded.deinit(testing.allocator);
+ var restored_terminal = decoded.toOwned();
+ defer restored_terminal.deinit(testing.allocator);
+ var restored_stream = TerminalStream.init(.{
+ .allocator = testing.allocator,
+ .handler = .init(&restored_terminal),
+ .continuation_max_bytes = 4096,
+ });
+ defer restored_stream.deinit();
+ switch (decoded.continuation) {
+ .ground => {},
+ .bytes => |bytes| restored_stream.nextSlice(bytes),
+ }
+
+ var reexport_bytes: [4096]u8 = undefined;
+ var reexport_writer: std.Io.Writer = .fixed(&reexport_bytes);
+ try restored_stream.writeContinuation(&reexport_writer);
+ try testing.expectEqualStrings(
+ cut_writer.buffered(),
+ reexport_writer.buffered(),
+ );
+
+ source_stream.nextSlice(corpus[cut..]);
+ var offset = cut;
+ var partition = cut +% corpus.len +% 1;
+ while (offset < corpus.len) {
+ partition = partition *% 1664525 +% 1013904223;
+ const len = @min(1 + partition % 7, corpus.len - offset);
+ restored_stream.nextSlice(corpus[offset..][0..len]);
+ offset += len;
+ }
+
+ var source_final_bytes: [4096]u8 = undefined;
+ var source_final_writer: std.Io.Writer = .fixed(&source_final_bytes);
+ try source_stream.writeContinuation(&source_final_writer);
+ var restored_final_bytes: [4096]u8 = undefined;
+ var restored_final_writer: std.Io.Writer = .fixed(&restored_final_bytes);
+ try restored_stream.writeContinuation(&restored_final_writer);
+ try testing.expectEqualStrings(
+ source_final_writer.buffered(),
+ restored_final_writer.buffered(),
+ );
+
+ const final_continuation: Continuation = if (source_final_writer.end == 0)
+ .ground
+ else
+ .{ .bytes = source_final_writer.buffered() };
+ var source_final_snapshot: std.Io.Writer.Allocating = .init(
+ testing.allocator,
+ );
+ defer source_final_snapshot.deinit();
+ try encode(
+ testing.allocator,
+ &source_final_snapshot.writer,
+ &source_terminal,
+ .{ .continuation = final_continuation },
+ );
+ var restored_final_snapshot: std.Io.Writer.Allocating = .init(
+ testing.allocator,
+ );
+ defer restored_final_snapshot.deinit();
+ try encode(
+ testing.allocator,
+ &restored_final_snapshot.writer,
+ &restored_terminal,
+ .{ .continuation = final_continuation },
+ );
+ try testing.expectEqualStrings(
+ source_final_snapshot.written(),
+ restored_final_snapshot.written(),
+ );
+ };
+}
+
+test "complete snapshot preserves Kitty virtual placeholders" {
+ if (comptime !build_options.kitty_graphics) return error.SkipZigTest;
+
+ const testing = std.testing;
+ var t = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 2,
+ .rows = 1,
+ });
+ defer t.deinit(testing.allocator);
+
+ // Register a real virtual placement, then write its grid representation:
+ // U+10EEEE followed by row and column diacritics. The image and placement
+ // registry is intentionally omitted, but the grid content must remain
+ // decodable.
+ try t.screens.active.kitty_images.addImage(
+ testing.io,
+ testing.allocator,
+ t.screens.active,
+ .{ .id = 1 },
+ );
+ try t.screens.active.kitty_images.addPlacement(
+ testing.io,
+ testing.allocator,
+ t.screens.active,
+ 1,
+ 0,
+ .{
+ .location = .{ .virtual = {} },
+ .columns = 1,
+ .rows = 1,
+ },
+ );
+ try t.setAttribute(.{ .@"256_fg" = 1 });
+ try t.printString("\u{10EEEE}\u{0305}\u{0305}");
+ const source_cell = t.screens.active.pages.getCell(.{
+ .screen = .{},
+ }).?;
+ try testing.expectEqual(
+ terminal_kitty.graphics.unicode.placeholder,
+ source_cell.cell.codepoint(),
+ );
+ try testing.expect(source_cell.row.kitty_virtual_placeholder);
+
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, test_encode_options);
+
+ var encoded_source: std.Io.Reader = .fixed(encoded.written());
+ var restored = try decode(
+ testing.allocator,
+ testing.io,
+ &encoded_source,
+ test_decode_options,
+ );
+ defer restored.deinit(testing.allocator);
+ const restored_terminal = &restored.terminal.?;
+
+ const restored_cell = restored_terminal.screens.active.pages.getCell(.{
+ .screen = .{},
+ }).?;
+ try testing.expectEqual(
+ terminal_kitty.graphics.unicode.placeholder,
+ restored_cell.cell.codepoint(),
+ );
+ try testing.expect(restored_cell.cell.hasGrapheme());
+ try testing.expect(restored_cell.row.kitty_virtual_placeholder);
+ try testing.expectEqual(
+ @as(usize, 0),
+ restored_terminal.screens.active.kitty_images.images.count(),
+ );
+ try testing.expectEqual(
+ @as(usize, 0),
+ restored_terminal.screens.active.kitty_images.placements.count(),
+ );
+}
+
+test "complete snapshot encoding streams from the current writer position" {
+ const testing = std.testing;
+
+ var t = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 2,
+ .rows = 1,
+ });
+ defer t.deinit(testing.allocator);
+
+ // Encoding begins with this call's envelope, independent of bytes that
+ // were already present in the destination.
+ var nonempty: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer nonempty.deinit();
+ try nonempty.writer.writeAll("prefix");
+ const snapshot_offset = nonempty.written().len;
+ try encode(testing.allocator, &nonempty.writer, &t, test_encode_options);
+ try testing.expectEqualStrings(
+ "prefix",
+ nonempty.written()[0..snapshot_offset],
+ );
+ var appended_source: std.Io.Reader = .fixed(
+ nonempty.written()[snapshot_offset..],
+ );
+ var appended = try decode(
+ testing.allocator,
+ testing.io,
+ &appended_source,
+ test_decode_options,
+ );
+ appended.deinit(testing.allocator);
+
+ // Payload validation happens in the record-local scratch allocation. The
+ // already-streamed envelope remains, but no partial TERMINAL is emitted.
+ t.colors.palette.current[7] = .{ .r = 1, .g = 2, .b = 3 };
+ var destination: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer destination.deinit();
+ try destination.writer.writeAll("prefix");
+ try testing.expectError(
+ error.InvalidPalette,
+ encode(
+ testing.allocator,
+ &destination.writer,
+ &t,
+ test_encode_options,
+ ),
+ );
+ var expected_envelope: [envelope.encoded_len]u8 = undefined;
+ var envelope_writer: std.Io.Writer = .fixed(&expected_envelope);
+ try envelope.encode(&envelope_writer);
+ try testing.expectEqualStrings(
+ &expected_envelope,
+ destination.written()["prefix".len..],
+ );
+}
+
+test "complete snapshot rejects ordering and invalid markers" {
+ const testing = std.testing;
+
+ var t = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 2,
+ .rows = 1,
+ });
+ defer t.deinit(testing.allocator);
+ const primary = t.screens.get(.primary).?;
+
+ // Old version-1 snapshots proceeded directly from SCREEN to READY. READY
+ // is individually valid here, but CONTINUATION is now required first.
+ var old_order: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer old_order.deinit();
+ var old_order_stream: record.Writer = .init(
+ testing.allocator,
+ &old_order.writer,
+ );
+ defer old_order_stream.deinit();
+ try envelope.encode(old_order_stream.writer());
+ try terminal.encode(&t, &old_order_stream);
+ try screen.encode(primary, .primary, &old_order_stream);
+ try checkpoint.encode(.ready, &old_order_stream);
+ var old_order_source: std.Io.Reader = .fixed(old_order.written());
+ try testing.expectError(
+ error.UnexpectedRecordTag,
+ decode(
+ testing.allocator,
+ testing.io,
+ &old_order_source,
+ test_decode_options,
+ ),
+ );
+
+ // A second CONTINUATION is rejected where READY is required.
+ var duplicate_continuation: std.Io.Writer.Allocating = .init(
+ testing.allocator,
+ );
+ defer duplicate_continuation.deinit();
+ var duplicate_continuation_stream: record.Writer = .init(
+ testing.allocator,
+ &duplicate_continuation.writer,
+ );
+ defer duplicate_continuation_stream.deinit();
+ try envelope.encode(duplicate_continuation_stream.writer());
+ try terminal.encode(&t, &duplicate_continuation_stream);
+ try screen.encode(primary, .primary, &duplicate_continuation_stream);
+ try continuation.encode(.ground, &duplicate_continuation_stream);
+ try continuation.encode(.ground, &duplicate_continuation_stream);
+ var duplicate_continuation_source: std.Io.Reader = .fixed(
+ duplicate_continuation.written(),
+ );
+ try testing.expectError(
+ error.UnexpectedRecordTag,
+ decode(
+ testing.allocator,
+ testing.io,
+ &duplicate_continuation_source,
+ test_decode_options,
+ ),
+ );
+
+ // HISTORY is individually valid here, but the full decoder requires the
+ // primary SCREEN before READY.
+ var reordered: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer reordered.deinit();
+ var reordered_stream: record.Writer = .init(
+ testing.allocator,
+ &reordered.writer,
+ );
+ defer reordered_stream.deinit();
+ try envelope.encode(reordered_stream.writer());
+ try terminal.encode(&t, &reordered_stream);
+ try history.encode(primary, .primary, &reordered_stream);
+ var reordered_source: std.Io.Reader = .fixed(reordered.written());
+ try testing.expectError(
+ error.UnexpectedRecordTag,
+ decode(
+ testing.allocator,
+ testing.io,
+ &reordered_source,
+ test_decode_options,
+ ),
+ );
+
+ // Construct a correctly framed READY with a nonempty payload so the full
+ // driver rejects a marker that does not match the required empty shape.
+ var invalid_ready: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer invalid_ready.deinit();
+ var invalid_ready_stream: record.Writer = .init(
+ testing.allocator,
+ &invalid_ready.writer,
+ );
+ defer invalid_ready_stream.deinit();
+ try envelope.encode(invalid_ready_stream.writer());
+ try terminal.encode(&t, &invalid_ready_stream);
+ try screen.encode(primary, .primary, &invalid_ready_stream);
+ try continuation.encode(.ground, &invalid_ready_stream);
+ const ready_payload = invalid_ready_stream.begin(.ready);
+ errdefer invalid_ready_stream.cancel();
+ try ready_payload.writeByte(0);
+ try invalid_ready_stream.finish();
+ var invalid_ready_source: std.Io.Reader = .fixed(
+ invalid_ready.written(),
+ );
+ try testing.expectError(
+ error.PayloadNotExhausted,
+ decode(
+ testing.allocator,
+ testing.io,
+ &invalid_ready_source,
+ test_decode_options,
+ ),
+ );
+
+ // A SCREEN key must name one of the slots declared by TERMINAL.
+ var undeclared: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer undeclared.deinit();
+ var undeclared_stream: record.Writer = .init(
+ testing.allocator,
+ &undeclared.writer,
+ );
+ defer undeclared_stream.deinit();
+ try envelope.encode(undeclared_stream.writer());
+ try terminal.encode(&t, &undeclared_stream);
+ try screen.encode(primary, .alternate, &undeclared_stream);
+ var undeclared_source: std.Io.Reader = .fixed(undeclared.written());
+ try testing.expectError(
+ error.UnexpectedScreenKey,
+ decode(
+ testing.allocator,
+ testing.io,
+ &undeclared_source,
+ test_decode_options,
+ ),
+ );
+
+ // HISTORY sequences are also routed by key, which must name a declared
+ // screen even when the sequence contains no PAGE records.
+ var undeclared_history: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer undeclared_history.deinit();
+ var undeclared_history_stream: record.Writer = .init(
+ testing.allocator,
+ &undeclared_history.writer,
+ );
+ defer undeclared_history_stream.deinit();
+ try envelope.encode(undeclared_history_stream.writer());
+ try terminal.encode(&t, &undeclared_history_stream);
+ try screen.encode(primary, .primary, &undeclared_history_stream);
+ try continuation.encode(.ground, &undeclared_history_stream);
+ try checkpoint.encode(.ready, &undeclared_history_stream);
+ try history.encode(primary, .alternate, &undeclared_history_stream);
+ var undeclared_history_source: std.Io.Reader = .fixed(
+ undeclared_history.written(),
+ );
+ try testing.expectError(
+ error.UnexpectedHistoryKey,
+ decode(
+ testing.allocator,
+ testing.io,
+ &undeclared_history_source,
+ test_decode_options,
+ ),
+ );
+
+ // The declared count cannot be satisfied by repeating the same key.
+ _ = try t.switchScreen(.alternate);
+ var duplicate: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer duplicate.deinit();
+ var duplicate_stream: record.Writer = .init(
+ testing.allocator,
+ &duplicate.writer,
+ );
+ defer duplicate_stream.deinit();
+ try envelope.encode(duplicate_stream.writer());
+ try terminal.encode(&t, &duplicate_stream);
+ try screen.encode(primary, .primary, &duplicate_stream);
+ try screen.encode(primary, .primary, &duplicate_stream);
+ var duplicate_source: std.Io.Reader = .fixed(duplicate.written());
+ try testing.expectError(
+ error.DuplicateScreen,
+ decode(
+ testing.allocator,
+ testing.io,
+ &duplicate_source,
+ test_decode_options,
+ ),
+ );
+
+ // The declared count cannot be satisfied by repeating one HISTORY key.
+ var duplicate_history: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer duplicate_history.deinit();
+ var duplicate_history_stream: record.Writer = .init(
+ testing.allocator,
+ &duplicate_history.writer,
+ );
+ defer duplicate_history_stream.deinit();
+ try envelope.encode(duplicate_history_stream.writer());
+ try terminal.encode(&t, &duplicate_history_stream);
+ try screen.encode(primary, .primary, &duplicate_history_stream);
+ try screen.encode(
+ t.screens.get(.alternate).?,
+ .alternate,
+ &duplicate_history_stream,
+ );
+ try continuation.encode(.ground, &duplicate_history_stream);
+ try checkpoint.encode(.ready, &duplicate_history_stream);
+ try history.encode(primary, .primary, &duplicate_history_stream);
+ try history.encode(primary, .primary, &duplicate_history_stream);
+ var duplicate_history_source: std.Io.Reader = .fixed(
+ duplicate_history.written(),
+ );
+ try testing.expectError(
+ error.DuplicateHistory,
+ decode(
+ testing.allocator,
+ testing.io,
+ &duplicate_history_source,
+ test_decode_options,
+ ),
+ );
+}
+
+test "complete snapshot leaves continuation bytes unread" {
+ const testing = std.testing;
+
+ var t = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 2,
+ .rows = 1,
+ });
+ defer t.deinit(testing.allocator);
+
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, test_encode_options);
+ const snapshot_len = encoded.written().len;
+ try encoded.writer.writeAll("pty");
+
+ var source: std.Io.Reader = .fixed(encoded.written());
+ var restored = try decode(
+ testing.allocator,
+ testing.io,
+ &source,
+ test_decode_options,
+ );
+ defer restored.deinit(testing.allocator);
+
+ var trailing: [3]u8 = undefined;
+ try source.readSliceAll(&trailing);
+ try testing.expectEqualStrings("pty", &trailing);
+
+ var exact_source: std.Io.Reader = .fixed(encoded.written());
+ try testing.expectError(
+ error.TrailingData,
+ decodeExact(
+ testing.allocator,
+ testing.io,
+ &exact_source,
+ test_decode_options,
+ ),
+ );
+
+ var bounded_source: std.Io.Reader = .fixed(
+ encoded.written()[0..snapshot_len],
+ );
+ var bounded = try decodeExact(
+ testing.allocator,
+ testing.io,
+ &bounded_source,
+ test_decode_options,
+ );
+ defer bounded.deinit(testing.allocator);
+}
+
+test "complete snapshots decode sequentially from one reader" {
+ const testing = std.testing;
+
+ var t = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 2,
+ .rows = 1,
+ });
+ defer t.deinit(testing.allocator);
+
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, test_encode_options);
+ try encode(testing.allocator, &encoded.writer, &t, test_encode_options);
+
+ var source: std.Io.Reader = .fixed(encoded.written());
+ var first = try decode(
+ testing.allocator,
+ testing.io,
+ &source,
+ test_decode_options,
+ );
+ defer first.deinit(testing.allocator);
+ var second = try decode(
+ testing.allocator,
+ testing.io,
+ &source,
+ test_decode_options,
+ );
+ defer second.deinit(testing.allocator);
+ try testing.expectError(error.EndOfStream, source.takeByte());
+}
+
+test "complete snapshot decode allocation failures are transactional" {
+ const testing = std.testing;
+ const S = struct {
+ fn exercise(bytes: []const u8) !void {
+ var baseline = testing.FailingAllocator.init(testing.allocator, .{
+ .fail_index = std.math.maxInt(usize),
+ });
+ var baseline_source: std.Io.Reader = .fixed(bytes);
+ var baseline_decoded = try decode(
+ baseline.allocator(),
+ testing.io,
+ &baseline_source,
+ test_decode_options,
+ );
+ baseline_decoded.deinit(baseline.allocator());
+ const allocation_count = baseline.alloc_index;
+ try testing.expect(allocation_count > 0);
+
+ var saw_out_of_memory = false;
+ for (0..allocation_count) |fail_index| {
+ var failing = testing.FailingAllocator.init(
+ testing.allocator,
+ .{ .fail_index = fail_index },
+ );
+ var source: std.Io.Reader = .fixed(bytes);
+ var decoded = decode(
+ failing.allocator(),
+ testing.io,
+ &source,
+ test_decode_options,
+ ) catch |err| switch (err) {
+ error.OutOfMemory => {
+ saw_out_of_memory = true;
+ continue;
+ },
+ else => return err,
+ };
+ decoded.deinit(failing.allocator());
+ }
+ try testing.expect(saw_out_of_memory);
+ }
+ };
+
+ // The complete golden exercises Terminal, both screens, and history.
+ try S.exercise(&test_complete_fixture);
+
+ // A non-ground component additionally exercises owned continuation bytes.
+ var t = try Terminal.init(
+ testing.io,
+ testing.allocator,
+ .{ .cols = 2, .rows = 1 },
+ );
+ defer t.deinit(testing.allocator);
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, .{
+ .continuation = .{ .bytes = "\x1b[31" },
+ });
+ try S.exercise(encoded.written());
+}
+
+test "incremental decode restores a renderable terminal at READY" {
+ const testing = std.testing;
+
+ // Trailing transport bytes must remain unread after FINISH.
+ var transport: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer transport.deinit();
+ try transport.writer.writeAll(&test_complete_fixture);
+ try transport.writer.writeAll("pty");
+
+ var source: std.Io.Reader = .fixed(transport.written());
+ var decoder: Decoder = .init(&source);
+ var decoded = try decoder.ready(
+ testing.allocator,
+ testing.io,
+ test_decode_options,
+ );
+ defer decoded.deinit(testing.allocator);
+
+ // READY restored the complete interactive state, so the Terminal can
+ // move to its final address before any history has been decoded.
+ var restored = decoded.toOwned();
+ defer restored.deinit(testing.allocator);
+ try testing.expectEqual(
+ TerminalScreenKey.alternate,
+ restored.screens.active_key,
+ );
+ try testing.expectEqualStrings(
+ "complete snapshot",
+ restored.getTitle().?,
+ );
+
+ // The advisory extents size scrollback UI immediately even though only
+ // the resident SCREEN pages exist. The alternate screen's extent is
+ // entirely resident overlap, so it must match its live row count.
+ const primary = restored.screens.get(.primary).?;
+ const alternate = restored.screens.get(.alternate).?;
+ try testing.expectEqual(3, primary.pages.scrollbar().total);
+ try testing.expectEqual(4, decoded.history_rows.get(.primary).?);
+ try testing.expectEqual(
+ alternate.pages.scrollbar().total - restored.rows,
+ decoded.history_rows.get(.alternate).?,
+ );
+
+ // Each call prepends exactly one history page, newest first.
+ const first = (try decoder.next(testing.allocator, &restored)).?;
+ try testing.expectEqualDeep(Decoder.Progress{
+ .key = .primary,
+ .rows = 2,
+ .remaining = 1,
+ }, first);
+ try testing.expectEqual(5, primary.pages.scrollbar().total);
+ try testing.expectEqual(@as(u21, 'B'), testTopLeftCodepoint(primary));
+
+ const second = (try decoder.next(testing.allocator, &restored)).?;
+ try testing.expectEqualDeep(Decoder.Progress{
+ .key = .primary,
+ .rows = 2,
+ .remaining = 0,
+ }, second);
+ try testing.expectEqual(7, primary.pages.scrollbar().total);
+ try testing.expectEqual(@as(u21, 'A'), testTopLeftCodepoint(primary));
+
+ // The alternate screen's empty sequence produces no event: the next
+ // call validates FINISH, and further calls remain null.
+ try testing.expect(try decoder.next(testing.allocator, &restored) == null);
+ try testing.expect(try decoder.next(testing.allocator, &restored) == null);
+ try testing.expectEqualStrings("pty", try source.take(3));
+
+ // The incremental path restores the same complete terminal as the
+ // one-shot decoder, byte for byte.
+ var reencoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer reencoded.deinit();
+ try encode(
+ testing.allocator,
+ &reencoded.writer,
+ &restored,
+ test_encode_options,
+ );
+ try testing.expectEqualStrings(&test_complete_fixture, reencoded.written());
+}
+
+test "incremental next reports invalid decoder states" {
+ const testing = std.testing;
+ var source: std.Io.Reader = .fixed("");
+ var decoder: Decoder = .init(&source);
+ var terminal_value = try Terminal.init(
+ testing.io,
+ testing.allocator,
+ .{ .cols = 1, .rows = 1 },
+ );
+ defer terminal_value.deinit(testing.allocator);
+
+ try testing.expectError(
+ error.DecoderNotReady,
+ decoder.next(testing.allocator, &terminal_value),
+ );
+}
+
+test "incremental decode applies history below live PTY output" {
+ const testing = std.testing;
+
+ var t = try testHistoryTerminal(2);
+ defer t.deinit(testing.allocator);
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, test_encode_options);
+
+ var source: std.Io.Reader = .fixed(encoded.written());
+ var decoder: Decoder = .init(&source);
+ var decoded = try decoder.ready(
+ testing.allocator,
+ testing.io,
+ test_decode_options,
+ );
+ defer decoded.deinit(testing.allocator);
+ var restored = decoded.toOwned();
+ defer restored.deinit(testing.allocator);
+
+ // The terminal is interactive at READY: post-cut PTY bytes append to
+ // the bottom while snapshot history is still pending.
+ var live = restored.vtStream();
+ defer live.deinit();
+ live.nextSlice("1\r\n2\r\n3\r\n4\r\n5\r\n");
+ const primary = restored.screens.get(.primary).?;
+ const live_total = primary.pages.scrollbar().total;
+ try testing.expect(live_total > 3);
+
+ // History still lands above both the snapshot content and the live
+ // output, preserving complete scrollback ordering.
+ while (try decoder.next(testing.allocator, &restored)) |progress| {
+ try testing.expectEqual(TerminalScreenKey.primary, progress.key);
+ try testing.expectEqual(2, progress.rows);
+ }
+ try testing.expectEqual(live_total + 4, primary.pages.scrollbar().total);
+ try testing.expectEqual(@as(u21, 'A'), testTopLeftCodepoint(primary));
+ const newest_history = primary.pages.getTopLeft(.screen).node.next.?;
+ try testing.expectEqual(
+ @as(u21, 'B'),
+ newest_history.page().getRowAndCell(0, 0).cell.codepoint(),
+ );
+
+ // The page below the applied history is the snapshot's active page,
+ // whose top-left cell the live output already overwrote.
+ try testing.expectEqual(
+ @as(u21, '1'),
+ newest_history.next.?.page().getRowAndCell(0, 0).cell.codepoint(),
+ );
+}
+
+test "incremental decode discards history for screens changed since READY" {
+ const testing = std.testing;
+
+ var t = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 2,
+ .rows = 3,
+ });
+ defer t.deinit(testing.allocator);
+ _ = try t.switchScreen(.alternate);
+ try t.printString("alt");
+ _ = try t.switchScreen(.primary);
+
+ // The encoder never produces alternate-screen history, but the format
+ // permits it, so the decoder must stay stream-aligned even when the
+ // pages can no longer be applied. Order independence lets the discarded
+ // sequence come first.
+ var crafted: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer crafted.deinit();
+ var stream: record.Writer = .init(testing.allocator, &crafted.writer);
+ defer stream.deinit();
+ try envelope.encode(stream.writer());
+ try terminal.encode(&t, &stream);
+ try screen.encode(t.screens.get(.primary).?, .primary, &stream);
+ try screen.encode(t.screens.get(.alternate).?, .alternate, &stream);
+ try continuation.encode(.ground, &stream);
+ try checkpoint.encode(.ready, &stream);
+ {
+ const payload = stream.begin(.history);
+ errdefer stream.cancel();
+ try (history.Header{ .key = .alternate, .page_count = 1 }).encode(
+ payload,
+ );
+ try stream.finish();
+ }
+ try page.encode(
+ t.screens.get(.alternate).?.pages
+ .getTopLeft(.screen).node.pageAssumeResident(),
+ &stream,
+ );
+ try history.encode(t.screens.get(.primary).?, .primary, &stream);
+ try checkpoint.encode(.finish, &stream);
+
+ // An unchanged declared screen accepts crafted history, establishing
+ // the baseline that the following runs degrade from.
+ {
+ var source: std.Io.Reader = .fixed(crafted.written());
+ var decoder: Decoder = .init(&source);
+ var decoded = try decoder.ready(
+ testing.allocator,
+ testing.io,
+ test_decode_options,
+ );
+ defer decoded.deinit(testing.allocator);
+ const restored = &decoded.terminal.?;
+
+ const progress = (try decoder.next(testing.allocator, restored)).?;
+ try testing.expectEqual(TerminalScreenKey.alternate, progress.key);
+ try testing.expect(progress.rows > 0);
+ try testing.expect(try decoder.next(testing.allocator, restored) == null);
+ try testing.expectEqual(
+ @as(usize, 2),
+ restored.screens.get(.alternate).?.pages.totalPages(),
+ );
+ }
+
+ // A screen removed since READY discards its history. FINISH still
+ // validates, proving discarded records leave the stream aligned.
+ {
+ var source: std.Io.Reader = .fixed(crafted.written());
+ var decoder: Decoder = .init(&source);
+ var decoded = try decoder.ready(
+ testing.allocator,
+ testing.io,
+ test_decode_options,
+ );
+ defer decoded.deinit(testing.allocator);
+ const restored = &decoded.terminal.?;
+ restored.screens.remove(testing.allocator, .alternate);
+
+ const progress = (try decoder.next(testing.allocator, restored)).?;
+ try testing.expectEqualDeep(Decoder.Progress{
+ .key = .alternate,
+ .rows = 0,
+ .remaining = 0,
+ }, progress);
+ try testing.expect(try decoder.next(testing.allocator, restored) == null);
+ }
+
+ // A screen removed and recreated since READY has a new generation, so
+ // stale history never mixes into its replacement's content.
+ {
+ var source: std.Io.Reader = .fixed(crafted.written());
+ var decoder: Decoder = .init(&source);
+ var decoded = try decoder.ready(
+ testing.allocator,
+ testing.io,
+ test_decode_options,
+ );
+ defer decoded.deinit(testing.allocator);
+ const restored = &decoded.terminal.?;
+ restored.screens.remove(testing.allocator, .alternate);
+ _ = try restored.switchScreen(.alternate);
+
+ const progress = (try decoder.next(testing.allocator, restored)).?;
+ try testing.expectEqual(TerminalScreenKey.alternate, progress.key);
+ try testing.expectEqual(0, progress.rows);
+ try testing.expect(try decoder.next(testing.allocator, restored) == null);
+ try testing.expectEqual(
+ @as(usize, 1),
+ restored.screens.get(.alternate).?.pages.totalPages(),
+ );
+ }
+}
+
+test "incremental decode discards history after a resize" {
+ const testing = std.testing;
+
+ var t = try testHistoryTerminal(2);
+ defer t.deinit(testing.allocator);
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, test_encode_options);
+
+ var source: std.Io.Reader = .fixed(encoded.written());
+ var decoder: Decoder = .init(&source);
+ var decoded = try decoder.ready(
+ testing.allocator,
+ testing.io,
+ test_decode_options,
+ );
+ defer decoded.deinit(testing.allocator);
+ var restored = decoded.toOwned();
+ defer restored.deinit(testing.allocator);
+
+ // Encoded pages assume the READY width. After a live resize reflows the
+ // restored screen, pending history is consumed but never applied.
+ try restored.resize(testing.allocator, .{ .cols = 3, .rows = 3 });
+ const primary = restored.screens.get(.primary).?;
+ const resized_total = primary.pages.scrollbar().total;
+
+ var pages: usize = 0;
+ while (try decoder.next(testing.allocator, &restored)) |progress| {
+ try testing.expectEqual(TerminalScreenKey.primary, progress.key);
+ try testing.expectEqual(0, progress.rows);
+ pages += 1;
+ }
+ try testing.expectEqual(2, pages);
+ try testing.expectEqual(resized_total, primary.pages.scrollbar().total);
+}
+
+test "decode drops history beyond the declared scrollback limits" {
+ const testing = std.testing;
+
+ // Declare a byte limit the complete history cannot satisfy. The limit
+ // is validated at page granularity on decode, so the snapshot itself
+ // remains well formed and fully validated.
+ var t = try testHistoryTerminal(3);
+ defer t.deinit(testing.allocator);
+ t.screens.get(.primary).?.pages.limits.set(.bytes, 1);
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, test_encode_options);
+
+ // Incremental: the newest page fits the effective floor, the next page
+ // exceeds it, and one drop discards the remainder of the sequence so no
+ // ordering gap can form.
+ {
+ var source: std.Io.Reader = .fixed(encoded.written());
+ var decoder: Decoder = .init(&source);
+ var decoded = try decoder.ready(
+ testing.allocator,
+ testing.io,
+ test_decode_options,
+ );
+ defer decoded.deinit(testing.allocator);
+ const restored = &decoded.terminal.?;
+
+ var rows: [3]usize = undefined;
+ var pages: usize = 0;
+ while (try decoder.next(testing.allocator, restored)) |progress| {
+ rows[pages] = progress.rows;
+ pages += 1;
+ }
+ try testing.expectEqual(3, pages);
+ try testing.expectEqualSlices(usize, &.{ 2, 0, 0 }, &rows);
+
+ const primary = restored.screens.get(.primary).?;
+ try testing.expectEqual(@as(usize, 2), primary.pages.totalPages());
+ try testing.expectEqual(@as(u21, 'C'), testTopLeftCodepoint(primary));
+ }
+
+ // The one-shot decoder degrades identically instead of rejecting the
+ // snapshot.
+ {
+ var source: std.Io.Reader = .fixed(encoded.written());
+ var decoded = try decode(
+ testing.allocator,
+ testing.io,
+ &source,
+ test_decode_options,
+ );
+ defer decoded.deinit(testing.allocator);
+ const primary = decoded.terminal.?.screens.get(.primary).?;
+ try testing.expectEqual(@as(usize, 2), primary.pages.totalPages());
+ try testing.expectEqual(@as(u21, 'C'), testTopLeftCodepoint(primary));
+ }
+}
+
+test "incremental decode failure leaves applied history usable" {
+ const testing = std.testing;
+
+ var t = try testHistoryTerminal(2);
+ defer t.deinit(testing.allocator);
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ try encode(testing.allocator, &encoded.writer, &t, test_encode_options);
+
+ // Truncate FINISH. READY and both history pages decode, then the
+ // failure surfaces on the call that would have completed the snapshot.
+ var source: std.Io.Reader = .fixed(
+ encoded.written()[0 .. encoded.written().len - 1],
+ );
+ var decoder: Decoder = .init(&source);
+ var decoded = try decoder.ready(
+ testing.allocator,
+ testing.io,
+ test_decode_options,
+ );
+ defer decoded.deinit(testing.allocator);
+ var restored = decoded.toOwned();
+ defer restored.deinit(testing.allocator);
+
+ for (0..2) |_| {
+ const progress = (try decoder.next(testing.allocator, &restored)).?;
+ try testing.expectEqual(2, progress.rows);
+ }
+ try testing.expectError(
+ error.EndOfStream,
+ decoder.next(testing.allocator, &restored),
+ );
+ try testing.expectError(
+ error.DecoderFailed,
+ decoder.next(testing.allocator, &restored),
+ );
+
+ // The transferred terminal was never owned by the decoder: it remains
+ // valid with the contiguous history prefix that did apply; only the
+ // incomplete snapshot stream is lost.
+ const primary = restored.screens.get(.primary).?;
+ try testing.expectEqual(@as(usize, 3), primary.pages.totalPages());
+ try testing.expectEqual(@as(u21, 'A'), testTopLeftCodepoint(primary));
+ primary.pages.assertIntegrity();
+ primary.assertIntegrity();
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/style.zig b/vendor/libghostty-vt/src/terminal/snapshot/style.zig
new file mode 100644
index 00000000..bd0d445c
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/style.zig
@@ -0,0 +1,423 @@
+//! Snapshot style entry encoding.
+//!
+//! Each entry describes one terminal style. A record can use these entries to
+//! build a style table and assign indexes according to that record's format.
+//! Indexing, ordering, etc. are properties of the containing record.
+//!
+//! Styles are encoded field by field from the terminal's native `Style` type.
+//! The native packed representation is deliberately not part of the snapshot
+//! format. This gives flexibility for changing one side or the other.
+//!
+//! All integers are unsigned and little-endian.
+//!
+//! | Offset | Size | Field |
+//! | -----: | ---: | :------------------------ |
+//! | 0 | 4 | Foreground color |
+//! | 4 | 4 | Background color |
+//! | 8 | 4 | Underline color |
+//! | 12 | 2 | Style flags (`u16`) |
+//! | 14 | 2 | Reserved, must be zero |
+//!
+//! The trailing reserved field is explicit wire padding that rounds each
+//! style entry from 14 bytes to 16 bytes. This makes entry offsets and byte
+//! counts straightforward.
+//!
+//! Each color begins with a one-byte kind followed by three data bytes:
+//!
+//! | Kind | Meaning | Data bytes |
+//! | ---: | :------ | :--------------------------------- |
+//! | 0 | None | All zero |
+//! | 1 | Palette | Palette index, then two zero bytes |
+//! | 2 | RGB | Red, green, blue |
+//!
+//! Style flag bits 0 through 7 are bold, italic, faint, blink, inverse,
+//! invisible, strikethrough, and overline. Bits 8 through 10 contain the
+//! underline kind. Bits 11 through 15 must be zero.
+//!
+//! | Underline | Meaning |
+//! | --------: | :------ |
+//! | 0 | None |
+//! | 1 | Single |
+//! | 2 | Double |
+//! | 3 | Curly |
+//! | 4 | Dotted |
+//! | 5 | Dashed |
+//!
+//! Underline values 6 and 7 are invalid in snapshot version 1.
+
+const std = @import("std");
+const test_fixture = @import("fixture.zig");
+const sgr = @import("../sgr.zig");
+const terminal_style = @import("../style.zig");
+
+/// Number of bytes in one encoded style entry. This size is part of the
+/// wire format: the codec reads and writes fixed offsets within an entry
+/// of exactly this size, so if the layout changes, the snapshot version
+/// and golden fixtures must also change.
+pub const len = 16;
+
+const Flags = packed struct(u16) {
+ bold: bool = false,
+ italic: bool = false,
+ faint: bool = false,
+ blink: bool = false,
+ inverse: bool = false,
+ invisible: bool = false,
+ strikethrough: bool = false,
+ overline: bool = false,
+ underline: u3 = 0,
+ reserved: u5 = 0,
+};
+
+const ColorKind = enum(u8) {
+ none = 0,
+ palette = 1,
+ rgb = 2,
+};
+
+/// Semantic validation errors for one complete style entry buffer.
+const ParseError = error{
+ /// A color kind is not defined by snapshot version 1.
+ InvalidColorKind,
+
+ /// Bytes unused by the selected color kind are not zero.
+ InvalidColor,
+
+ /// The encoded underline kind is not defined by snapshot version 1.
+ InvalidUnderline,
+
+ /// One or more reserved style flag bits are set.
+ InvalidFlags,
+
+ /// The trailing reserved field is not zero.
+ InvalidReserved,
+};
+
+/// Errors possible while decoding one style entry.
+pub const DecodeError = std.Io.Reader.Error || ParseError;
+
+/// Encode one terminal style as a fixed-size snapshot style entry.
+///
+/// The entry is assembled in a fixed buffer and written once, so hot
+/// encoders perform a single writer call per style.
+pub fn encode(
+ value: terminal_style.Style,
+ writer: *std.Io.Writer,
+) std.Io.Writer.Error!void {
+ var encoded: [len]u8 = @splat(0);
+ encodeColorBuf(encoded[0..4], value.fg_color);
+ encodeColorBuf(encoded[4..8], value.bg_color);
+ encodeColorBuf(encoded[8..12], value.underline_color);
+
+ const flags: Flags = .{
+ .bold = value.flags.bold,
+ .italic = value.flags.italic,
+ .faint = value.flags.faint,
+ .blink = value.flags.blink,
+ .inverse = value.flags.inverse,
+ .invisible = value.flags.invisible,
+ .strikethrough = value.flags.strikethrough,
+ .overline = value.flags.overline,
+ .underline = @intFromEnum(value.flags.underline),
+ };
+ std.mem.writeInt(u16, encoded[12..14], @bitCast(flags), .little);
+ try writer.writeAll(&encoded);
+}
+
+/// Decode and validate one fixed-size snapshot style entry.
+pub fn decode(reader: *std.Io.Reader) DecodeError!terminal_style.Style {
+ var encoded: [len]u8 = undefined;
+ try reader.readSliceAll(&encoded);
+ return parse(&encoded);
+}
+
+/// Decode and validate one complete fixed-size style entry buffer.
+fn parse(encoded: *const [len]u8) ParseError!terminal_style.Style {
+ const fg_color = try parseColor(encoded[0..4]);
+ const bg_color = try parseColor(encoded[4..8]);
+ const underline_color = try parseColor(encoded[8..12]);
+
+ const flags: Flags = @bitCast(
+ std.mem.readInt(u16, encoded[12..14], .little),
+ );
+ if (flags.reserved != 0) return error.InvalidFlags;
+
+ const underline = std.enums.fromInt(
+ sgr.Attribute.Underline,
+ flags.underline,
+ ) orelse return error.InvalidUnderline;
+
+ const reserved = std.mem.readInt(u16, encoded[14..16], .little);
+ if (reserved != 0) return error.InvalidReserved;
+
+ return .{
+ .fg_color = fg_color,
+ .bg_color = bg_color,
+ .underline_color = underline_color,
+ .flags = .{
+ .bold = flags.bold,
+ .italic = flags.italic,
+ .faint = flags.faint,
+ .blink = flags.blink,
+ .inverse = flags.inverse,
+ .invisible = flags.invisible,
+ .strikethrough = flags.strikethrough,
+ .overline = flags.overline,
+ .underline = underline,
+ },
+ };
+}
+
+/// Decode strictly after consuming one complete fixed-size style entry.
+///
+/// Unlike `decode`, a semantic error leaves `reader` at the next entry. This
+/// lets an enclosing codec catch the error and choose its own fallback without
+/// losing the surrounding payload boundary.
+pub fn decodeOrDiscard(
+ reader: *std.Io.Reader,
+) DecodeError!terminal_style.Style {
+ var encoded: [len]u8 = undefined;
+ try reader.readSliceAll(&encoded);
+ return parse(&encoded);
+}
+
+/// Decode one complete entry, returning null for invalid semantic contents.
+///
+/// Reader errors remain structural and are always propagated. This is the
+/// lenient entry point for enclosing codecs which can safely replace an
+/// invalid fixed-size style without treating truncation as invalid styling.
+pub fn decodeOrNull(
+ reader: *std.Io.Reader,
+) std.Io.Reader.Error!?terminal_style.Style {
+ return decodeOrDiscard(reader) catch |err| switch (err) {
+ error.ReadFailed => return error.ReadFailed,
+ error.EndOfStream => return error.EndOfStream,
+
+ error.InvalidColorKind,
+ error.InvalidColor,
+ error.InvalidUnderline,
+ error.InvalidFlags,
+ error.InvalidReserved,
+ => null,
+ };
+}
+
+/// `decodeOrNull` over one already-buffered entry, for enclosing codecs
+/// that parse many entries from a flat payload without reader calls.
+pub fn parseOrNull(encoded: *const [len]u8) ?terminal_style.Style {
+ return parse(encoded) catch null;
+}
+
+fn encodeColorBuf(
+ encoded: *[4]u8,
+ value: terminal_style.Style.Color,
+) void {
+ switch (value) {
+ .none => encoded[0] = @intFromEnum(ColorKind.none),
+ .palette => |index| {
+ encoded[0] = @intFromEnum(ColorKind.palette);
+ encoded[1] = index;
+ },
+ .rgb => |rgb| {
+ encoded[0] = @intFromEnum(ColorKind.rgb);
+ encoded[1] = rgb.r;
+ encoded[2] = rgb.g;
+ encoded[3] = rgb.b;
+ },
+ }
+}
+
+fn parseColor(
+ encoded: *const [4]u8,
+) ParseError!terminal_style.Style.Color {
+ // Kind must be something we know about.
+ const kind = std.enums.fromInt(ColorKind, encoded[0]) orelse {
+ return error.InvalidColorKind;
+ };
+
+ return switch (kind) {
+ .none => if (encoded[1] == 0 and encoded[2] == 0 and encoded[3] == 0)
+ .none
+ else
+ error.InvalidColor,
+ .palette => if (encoded[2] == 0 and encoded[3] == 0)
+ .{ .palette = encoded[1] }
+ else
+ error.InvalidColor,
+ .rgb => .{ .rgb = .{
+ .r = encoded[1],
+ .g = encoded[2],
+ .b = encoded[3],
+ } },
+ };
+}
+
+const test_golden_fixture = test_fixture.parse(@embedFile("testdata/style-v1.hex"));
+
+test "golden encoding and decoding" {
+ const value: terminal_style.Style = .{
+ .fg_color = .none,
+ .bg_color = .{ .palette = 0x7f },
+ .underline_color = .{ .rgb = .{
+ .r = 0x12,
+ .g = 0x34,
+ .b = 0x56,
+ } },
+ .flags = .{
+ .bold = true,
+ .italic = true,
+ .faint = true,
+ .blink = true,
+ .inverse = true,
+ .invisible = true,
+ .strikethrough = true,
+ .overline = true,
+ .underline = .curly,
+ },
+ };
+ var buf: [len]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ try encode(value, &writer);
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/style-v1.hex",
+ "snapshot_fixture-style-v1.hex",
+ &test_golden_fixture,
+ writer.buffered(),
+ );
+
+ var source: std.Io.Reader = .fixed(&test_golden_fixture);
+ var read_buf: [1]u8 = undefined;
+ var limited = source.limited(.unlimited, &read_buf);
+ try std.testing.expect(value.eql(try decode(&limited.interface)));
+}
+
+test "flag bit layout" {
+ const Case = struct {
+ value: Flags,
+ expected: u16,
+ };
+ const cases = [_]Case{
+ .{ .value = .{ .bold = true }, .expected = 1 << 0 },
+ .{ .value = .{ .italic = true }, .expected = 1 << 1 },
+ .{ .value = .{ .faint = true }, .expected = 1 << 2 },
+ .{ .value = .{ .blink = true }, .expected = 1 << 3 },
+ .{ .value = .{ .inverse = true }, .expected = 1 << 4 },
+ .{ .value = .{ .invisible = true }, .expected = 1 << 5 },
+ .{ .value = .{ .strikethrough = true }, .expected = 1 << 6 },
+ .{ .value = .{ .overline = true }, .expected = 1 << 7 },
+ .{
+ .value = .{
+ .underline = @intFromEnum(sgr.Attribute.Underline.single),
+ },
+ .expected = 1 << 8,
+ },
+ .{
+ .value = .{
+ .underline = @intFromEnum(sgr.Attribute.Underline.double),
+ },
+ .expected = 2 << 8,
+ },
+ .{
+ .value = .{
+ .underline = @intFromEnum(sgr.Attribute.Underline.curly),
+ },
+ .expected = 3 << 8,
+ },
+ .{
+ .value = .{
+ .underline = @intFromEnum(sgr.Attribute.Underline.dotted),
+ },
+ .expected = 4 << 8,
+ },
+ .{
+ .value = .{
+ .underline = @intFromEnum(sgr.Attribute.Underline.dashed),
+ },
+ .expected = 5 << 8,
+ },
+ .{ .value = .{ .reserved = 1 }, .expected = 1 << 11 },
+ };
+
+ for (cases) |case| {
+ try std.testing.expectEqual(
+ case.expected,
+ @as(u16, @bitCast(case.value)),
+ );
+ }
+}
+
+test "reject invalid colors" {
+ for ([_]usize{ 0, 4, 8 }) |offset| {
+ var invalid_kind: [len]u8 = @splat(0);
+ invalid_kind[offset] = 3;
+ var reader: std.Io.Reader = .fixed(&invalid_kind);
+ try std.testing.expectError(error.InvalidColorKind, decode(&reader));
+ }
+
+ var invalid_none: [len]u8 = @splat(0);
+ invalid_none[1] = 1;
+ var none_reader: std.Io.Reader = .fixed(&invalid_none);
+ try std.testing.expectError(error.InvalidColor, decode(&none_reader));
+
+ var invalid_palette: [len]u8 = @splat(0);
+ invalid_palette[0] = @intFromEnum(ColorKind.palette);
+ invalid_palette[2] = 1;
+ var palette_reader: std.Io.Reader = .fixed(&invalid_palette);
+ try std.testing.expectError(error.InvalidColor, decode(&palette_reader));
+}
+
+test "reject invalid flags and reserved field" {
+ for ([_]u16{ 6, 7 }) |underline| {
+ var invalid_underline: [len]u8 = @splat(0);
+ std.mem.writeInt(
+ u16,
+ invalid_underline[12..14],
+ underline << 8,
+ .little,
+ );
+ var reader: std.Io.Reader = .fixed(&invalid_underline);
+ try std.testing.expectError(error.InvalidUnderline, decode(&reader));
+ }
+
+ var invalid_flags: [len]u8 = @splat(0);
+ std.mem.writeInt(u16, invalid_flags[12..14], 1 << 11, .little);
+ var flags_reader: std.Io.Reader = .fixed(&invalid_flags);
+ try std.testing.expectError(error.InvalidFlags, decode(&flags_reader));
+
+ var invalid_reserved: [len]u8 = @splat(0);
+ std.mem.writeInt(u16, invalid_reserved[14..16], 1, .little);
+ var reserved_reader: std.Io.Reader = .fixed(&invalid_reserved);
+ try std.testing.expectError(
+ error.InvalidReserved,
+ decode(&reserved_reader),
+ );
+}
+
+test "decodeOrDiscard preserves the next entry boundary" {
+ var fixture: [len + 1]u8 = @splat(0);
+ fixture[0] = 3;
+ fixture[len] = 0xFF;
+
+ var reader: std.Io.Reader = .fixed(&fixture);
+ try std.testing.expectError(error.InvalidColorKind, decodeOrDiscard(&reader));
+ try std.testing.expectEqual(@as(u8, 0xFF), try reader.takeByte());
+}
+
+test "decodeOrNull distinguishes semantic errors from truncation" {
+ var invalid: [len]u8 = @splat(0);
+ invalid[0] = 3;
+ var invalid_reader: std.Io.Reader = .fixed(&invalid);
+ try std.testing.expectEqual(null, try decodeOrNull(&invalid_reader));
+
+ var truncated: std.Io.Reader = .fixed(invalid[0 .. len - 1]);
+ try std.testing.expectError(error.EndOfStream, decodeOrNull(&truncated));
+}
+
+test "reject every truncation" {
+ const fixture = [_]u8{0} ** len;
+ for (0..len) |fixture_len| {
+ var reader: std.Io.Reader = .fixed(fixture[0..fixture_len]);
+ try std.testing.expectError(error.EndOfStream, decode(&reader));
+ }
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/terminal.zig b/vendor/libghostty-vt/src/terminal/snapshot/terminal.zig
new file mode 100644
index 00000000..19305372
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/terminal.zig
@@ -0,0 +1,1850 @@
+//! TERMINAL record payload encoding.
+//!
+//! One TERMINAL record contains terminal-wide state shared by every screen. It
+//! is the first record in a snapshot and declares which SCREEN sequences follow
+//! it. Screen contents, cursors, and history are encoded by `screen.zig` and
+//! `history.zig`.
+//!
+//! Snapshot version 1 supports the primary screen and an optional alternate
+//! screen. `screen_count` is therefore one or two. SCREEN records identify
+//! their destination by key and may appear in either order. Canonical encoders
+//! write primary first, then alternate when present. `active_screen_key` must
+//! name one of those declared screens.
+//!
+//! All integers are unsigned and little-endian.
+//!
+//! ## Binary Format
+//!
+//! The payload begins with a fixed header followed by terminal-wide variable
+//! state. The enclosing record supplies the payload boundary.
+//!
+//! ```text
+//! 0 +--------------------------+
+//! | Header |
+//! 103 +--------------------------+
+//! | Tab stops |
+//! | ceil(columns / 8) bytes |
+//! +--------------------------+
+//! | Original palette |
+//! | 256 * RGB |
+//! +--------------------------+
+//! | Palette override mask |
+//! | 32 bytes |
+//! +--------------------------+
+//! | Palette overrides |
+//! | 3 * popcount(mask) bytes |
+//! +--------------------------+
+//! | PWD length (u32) |
+//! +--------------------------+
+//! | PWD bytes |
+//! +--------------------------+
+//! | Title length (u32) |
+//! +--------------------------+
+//! | Title bytes |
+//! end +--------------------------+
+//! ```
+//!
+//! ### Header
+//!
+//! ```text
+//! 0 +-----------------------------------+
+//! | Columns (u16) |
+//! 2 +-----------------------------------+
+//! | Rows (u16) |
+//! 4 +-----------------------------------+
+//! | Pixel width (u32) |
+//! 8 +-----------------------------------+
+//! | Pixel height (u32) |
+//! 12 +-----------------------------------+
+//! | Scrolling-region top (u16) |
+//! 14 +-----------------------------------+
+//! | Scrolling-region bottom (u16) |
+//! 16 +-----------------------------------+
+//! | Scrolling-region left (u16) |
+//! 18 +-----------------------------------+
+//! | Scrolling-region right (u16) |
+//! 20 +-----------------------------------+
+//! | Status display (u8) |
+//! 21 +-----------------------------------+
+//! | Active screen key (u16) |
+//! 23 +-----------------------------------+
+//! | Screen count (u16) |
+//! 25 +-----------------------------------+
+//! | Previous codepoint (u32) |
+//! 29 +-----------------------------------+
+//! | Cursor is-default (u8) |
+//! 30 +-----------------------------------+
+//! | Cursor default visual style (u8) |
+//! 31 +-----------------------------------+
+//! | Cursor default blink policy (u8) |
+//! 32 +-----------------------------------+
+//! | Shell-redraw policy (u8) |
+//! 33 +-----------------------------------+
+//! | Modify-other-keys level 2 (u8) |
+//! 34 +-----------------------------------+
+//! | Mouse event (u8) |
+//! 35 +-----------------------------------+
+//! | Mouse format (u8) |
+//! 36 +-----------------------------------+
+//! | Mouse shift-capture policy (u8) |
+//! 37 +-----------------------------------+
+//! | Mouse shape (u8) |
+//! 38 +-----------------------------------+
+//! | Password-input flag (u8) |
+//! 39 +-----------------------------------+
+//! | Current modes (ModePacked) |
+//! 47 +-----------------------------------+
+//! | Saved modes (ModePacked) |
+//! 55 +-----------------------------------+
+//! | Default modes (ModePacked) |
+//! 63 +-----------------------------------+
+//! | Background color (DynamicRGB) |
+//! 71 +-----------------------------------+
+//! | Foreground color (DynamicRGB) |
+//! 79 +-----------------------------------+
+//! | Cursor color (DynamicRGB) |
+//! 87 +-----------------------------------+
+//! | Maximum scrollback bytes (u64) |
+//! 95 +-----------------------------------+
+//! | Maximum scrollback rows (u64) |
+//! 103 +-----------------------------------+
+//! ```
+//!
+//! The previous codepoint is a Unicode scalar value or `0xffffffff` when there
+//! is no previous character. Boolean fields are zero or one.
+//! Cursor blink and mouse shift-capture policies encode null as zero, false as
+//! one, and true as two.
+//! Canonical encoders use only the documented enum and boolean values.
+//! Decoders replace unknown semantic values with neutral native defaults,
+//! discard invalid previous codepoints, and reset each invalid scrolling axis
+//! to the terminal's full extent. Dimensions and screen count remain
+//! structural.
+//!
+//! A scrollback limit of `0xffffffffffffffff` means unlimited. Every other
+//! value is finite, including zero. The values are the source primary
+//! PageList's explicit policies, not its dimension-adjusted effective limits.
+//! Alternate-screen no-scrollback behavior is derived from the screen key.
+//!
+//! ### Tab stops
+//!
+//! One bit is encoded for each column, least-significant bit first within each
+//! byte. Bit zero of the first byte is column zero. Unused high bits in the last
+//! byte are canonically zero and ignored by decoders.
+//!
+//! ### Dynamic RGB
+//!
+//! The three terminal dynamic colors share this layout:
+//!
+//! ```text
+//! 0 +----------------------------+
+//! | Default present (u8) |
+//! 1 +----------------------------+
+//! | Default RGB |
+//! 4 +----------------------------+
+//! | Override present (u8) |
+//! 5 +----------------------------+
+//! | Override RGB |
+//! 8 +----------------------------+
+//! ```
+//!
+//! Presence values are zero or one. The corresponding RGB bytes must be zero
+//! when a value is absent. Decoders treat every other presence value as absent
+//! and ignore RGB bytes belonging to an absent value.
+//!
+//! ### Palette
+//!
+//! The complete original 256-color palette is encoded first in index order.
+//! Each mask bit then states whether the current palette entry overrides that
+//! original value. Bit zero of the first mask byte is palette index zero.
+//! Override RGB values follow in increasing index order with no index or count
+//! fields.
+//!
+//! ### Modes
+//!
+//! Current, saved, and default modes use the same stable bit registry:
+//!
+//! ```text
+//! bit 0 disable_keyboard
+//! bit 1 insert
+//! bit 2 send_receive_mode
+//! bit 3 linefeed
+//! bit 4 cursor_keys
+//! bit 5 132_column
+//! bit 6 slow_scroll
+//! bit 7 reverse_colors
+//! bit 8 origin
+//! bit 9 wraparound
+//! bit 10 autorepeat
+//! bit 11 mouse_event_x10
+//! bit 12 cursor_blinking
+//! bit 13 cursor_visible
+//! bit 14 enable_mode_3
+//! bit 15 reverse_wrap
+//! bit 16 alt_screen_legacy
+//! bit 17 keypad_keys
+//! bit 18 backarrow_key_mode
+//! bit 19 enable_left_and_right_margin
+//! bit 20 mouse_event_normal
+//! bit 21 mouse_event_button
+//! bit 22 mouse_event_any
+//! bit 23 focus_event
+//! bit 24 mouse_format_utf8
+//! bit 25 mouse_format_sgr
+//! bit 26 mouse_alternate_scroll
+//! bit 27 mouse_format_urxvt
+//! bit 28 mouse_format_sgr_pixels
+//! bit 29 ignore_keypad_with_numlock
+//! bit 30 alt_esc_prefix
+//! bit 31 alt_sends_escape
+//! bit 32 reverse_wrap_extended
+//! bit 33 alt_screen
+//! bit 34 save_cursor
+//! bit 35 alt_screen_save_cursor_clear_enter
+//! bit 36 bracketed_paste
+//! bit 37 synchronized_output
+//! bit 38 grapheme_cluster
+//! bit 39 report_color_scheme
+//! bit 40 report_visibility
+//! bit 41 in_band_size_reports
+//! bit 42 kitty_paste_events
+//! bits 43-63 reserved, zero
+//! ```
+//!
+//! This is the packed field order of native `ModePacked`. Its layout is
+//! well-defined and is the snapshot registry. Moving or adding a native mode
+//! therefore requires a snapshot version bump. Decoders ignore reserved bits.
+//!
+//! ## Field classification
+//!
+//! The TERMINAL payload encodes terminal dimensions, pixel dimensions,
+//! scrolling region, status display, tab stops, PWD, title, color state,
+//! previous character, all three mode sets, cursor defaults, mouse behavior,
+//! password-input state, source scrollback policies, the active screen key, and
+//! the set of declared screens.
+//!
+//! SCREEN and HISTORY sequences encode each Screen's pages, cursor, saved
+//! cursor, charset, protected mode, Kitty keyboard stack, semantic-click state,
+//! and complete history. The semantic-prompt `seen` bit is derived from
+//! restored resident content.
+//!
+//! Native allocators, I/O implementations, pools, pointers, page IDs, byte
+//! accounting, tracked pins, and ScreenSet generations are reconstructed.
+//! PageList row totals and the active viewport are derived from decoded pages.
+//! The destination surface supplies its own focus state. Selections, scrolled
+//! viewports, selection-scroll activity, dirty flags, search flags, hyperlink
+//! hover state, and incremental compression state are presentation or cache
+//! state and reset during restore.
+//!
+//! Kitty image state and glyph glossary registrations are unsupported by this
+//! snapshot version and are ignored during capture. Unicode virtual placeholder
+//! cells are preserved as grid content, but their image and placement state is
+//! not restored. Build-time terminal behavior, Unicode width policy, parser
+//! continuation, and external callbacks are version-level or caller-local
+//! requirements.
+//!
+//! Native enum declaration indices and mode bit positions used by this format
+//! are snapshot-version registries. Changing any of them requires a snapshot
+//! version bump.
+
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const test_fixture = @import("fixture.zig");
+const io = @import("io.zig");
+const record = @import("record.zig");
+const terminal_ansi = @import("../ansi.zig");
+const terminal_color = @import("../color.zig");
+const terminal_modes = @import("../modes.zig");
+const terminal_mouse = @import("../mouse.zig");
+const terminal_osc = @import("../osc.zig");
+const Terminal = @import("../Terminal.zig");
+const TerminalScreen = @import("../Screen.zig");
+const TerminalScreenKey = @import("../ScreenSet.zig").Key;
+const TerminalTabstops = @import("../Tabstops.zig");
+const ModeBits = @typeInfo(
+ terminal_modes.ModePacked,
+).@"struct".backing_integer.?;
+
+/// Reuse the terminal's semantic RGB value without adopting its memory layout
+/// as a wire encoding.
+pub const RGB = terminal_color.RGB;
+
+/// Reuse the terminal's semantic dynamic color without adopting its memory
+/// layout as a wire encoding.
+pub const DynamicRGB = terminal_color.DynamicRGB;
+
+const ValidationError = error{
+ InvalidDimensions,
+ InvalidScrollingRegion,
+ InvalidScreenCount,
+ InvalidActiveScreenKey,
+ InvalidPreviousCodepoint,
+ InvalidScrollbackLimit,
+};
+
+const HeaderInitError = error{
+ ScrollbackLimitOverflow,
+};
+
+/// Errors possible while encoding a TERMINAL payload.
+const PayloadEncodeError = std.Io.Writer.Error ||
+ ValidationError ||
+ error{
+ InvalidTabStops,
+ InvalidPalette,
+ StringTooLong,
+ };
+
+/// Errors possible while decoding a TERMINAL payload.
+const PayloadDecodeError = std.Io.Reader.Error ||
+ Allocator.Error ||
+ error{
+ /// Terminal dimensions control every following native allocation.
+ InvalidDimensions,
+
+ /// The count determines how many SCREEN and HISTORY sequences follow.
+ InvalidScreenCount,
+ };
+
+/// The fixed fields at the start of every TERMINAL payload.
+pub const Header = struct {
+ /// Number of bytes written by `encode`, calculated using the encoder.
+ pub const len = computeLen();
+
+ comptime {
+ std.debug.assert(len == 103);
+ }
+
+ // Terminal geometry and its current scrolling region.
+ columns: u16,
+ rows: u16,
+ width_px: u32,
+ height_px: u32,
+
+ scrolling_region_top: u16,
+ scrolling_region_bottom: u16,
+ scrolling_region_left: u16,
+ scrolling_region_right: u16,
+
+ // Status display, screen routing, and character context.
+ status_display: terminal_ansi.StatusDisplay,
+ active_screen_key: TerminalScreenKey,
+ screen_count: u16,
+ previous_codepoint: ?u21,
+
+ // Cursor presentation defaults shared by the screens.
+ cursor_is_default: bool,
+ cursor_default_style: TerminalScreen.CursorStyle,
+ cursor_default_blink: ?bool,
+
+ // Terminal input, semantic redraw, and pointer behavior.
+ shell_redraw: terminal_osc.semantic_prompt.Redraw,
+ modify_other_keys_2: bool,
+ mouse_event: terminal_mouse.Event,
+ mouse_format: terminal_mouse.Format,
+ mouse_shift_capture: ?bool,
+ mouse_shape: terminal_mouse.Shape,
+ password_input: bool,
+
+ // Runtime, saved, and reset mode sets.
+ current_modes: terminal_modes.ModePacked,
+ saved_modes: terminal_modes.ModePacked,
+ default_modes: terminal_modes.ModePacked,
+
+ // Terminal-wide dynamic color state.
+ background: DynamicRGB,
+ foreground: DynamicRGB,
+ cursor_color: DynamicRGB,
+
+ // Explicit primary-screen scrollback policies.
+ max_scrollback_bytes: ?u64,
+ max_scrollback_rows: ?u64,
+
+ /// Capture the terminal-wide native state represented by this header.
+ fn init(terminal: *const Terminal) HeaderInitError!Header {
+ const primary = terminal.screens.get(.primary).?;
+
+ return .{
+ // Terminal geometry and its current scrolling region.
+ .columns = terminal.cols,
+ .rows = terminal.rows,
+ .width_px = terminal.width_px,
+ .height_px = terminal.height_px,
+ .scrolling_region_top = terminal.scrolling_region.top,
+ .scrolling_region_bottom = terminal.scrolling_region.bottom,
+ .scrolling_region_left = terminal.scrolling_region.left,
+ .scrolling_region_right = terminal.scrolling_region.right,
+
+ // Status display, screen routing, and character context.
+ .status_display = terminal.status_display,
+ .active_screen_key = terminal.screens.active_key,
+ .screen_count = if (terminal.screens.get(.alternate) == null)
+ 1
+ else
+ 2,
+ .previous_codepoint = terminal.previous_char,
+
+ // Cursor presentation defaults shared by the screens.
+ .cursor_is_default = terminal.cursor.is_default,
+ .cursor_default_style = terminal.cursor.default_style,
+ .cursor_default_blink = terminal.cursor.default_blink,
+
+ // Terminal input, semantic redraw, and pointer behavior.
+ .shell_redraw = terminal.flags.shell_redraws_prompt,
+ .modify_other_keys_2 = terminal.flags.modify_other_keys_2,
+ .mouse_event = terminal.flags.mouse_event,
+ .mouse_format = terminal.flags.mouse_format,
+ .mouse_shift_capture = switch (terminal.flags.mouse_shift_capture) {
+ .null => null,
+ .false => false,
+ .true => true,
+ },
+ .mouse_shape = terminal.mouse_shape,
+ .password_input = terminal.flags.password_input,
+
+ // Runtime, saved, and reset mode sets.
+ .current_modes = terminal.modes.values,
+ .saved_modes = terminal.modes.saved,
+ .default_modes = terminal.modes.default,
+
+ // Terminal-wide dynamic color state.
+ .background = terminal.colors.background,
+ .foreground = terminal.colors.foreground,
+ .cursor_color = terminal.colors.cursor,
+
+ // Explicit primary-screen scrollback policies.
+ .max_scrollback_bytes = try encodeScrollbackLimit(
+ primary.pages.limits.bytes.explicit,
+ ),
+ .max_scrollback_rows = try encodeScrollbackLimit(
+ primary.pages.limits.lines.explicit,
+ ),
+ };
+ }
+
+ /// Encode the fixed TERMINAL payload header field by field.
+ pub fn encode(
+ self: Header,
+ writer: *std.Io.Writer,
+ ) PayloadEncodeError!void {
+ try self.validate();
+
+ // Terminal geometry and its current scrolling region.
+ try io.writeInt(writer, u16, self.columns);
+ try io.writeInt(writer, u16, self.rows);
+ try io.writeInt(writer, u32, self.width_px);
+ try io.writeInt(writer, u32, self.height_px);
+ try io.writeInt(writer, u16, self.scrolling_region_top);
+ try io.writeInt(writer, u16, self.scrolling_region_bottom);
+ try io.writeInt(writer, u16, self.scrolling_region_left);
+ try io.writeInt(writer, u16, self.scrolling_region_right);
+
+ // Status display, screen routing, and character context.
+ try writer.writeByte(@intCast(@intFromEnum(self.status_display)));
+ try io.writeInt(
+ writer,
+ u16,
+ @intCast(@intFromEnum(self.active_screen_key)),
+ );
+ try io.writeInt(writer, u16, self.screen_count);
+ try io.writeInt(
+ writer,
+ u32,
+ if (self.previous_codepoint) |value|
+ @intCast(value)
+ else
+ std.math.maxInt(u32),
+ );
+
+ // Cursor presentation defaults shared by the screens.
+ try writer.writeByte(@intFromBool(self.cursor_is_default));
+ try writer.writeByte(
+ @intCast(@intFromEnum(self.cursor_default_style)),
+ );
+ try writer.writeByte(encodeOptionalBool(self.cursor_default_blink));
+
+ // Terminal input, semantic redraw, and pointer behavior.
+ try writer.writeByte(@intCast(@intFromEnum(self.shell_redraw)));
+ try writer.writeByte(@intFromBool(self.modify_other_keys_2));
+ try writer.writeByte(@intCast(@intFromEnum(self.mouse_event)));
+ try writer.writeByte(@intCast(@intFromEnum(self.mouse_format)));
+ try writer.writeByte(encodeOptionalBool(self.mouse_shift_capture));
+ try writer.writeByte(@intCast(@intFromEnum(self.mouse_shape)));
+ try writer.writeByte(@intFromBool(self.password_input));
+
+ // Runtime, saved, and reset mode sets. ModePacked occupies 43 bits;
+ // its eight-byte wire slots zero-extend the native packed value.
+ const mode_values = [_]terminal_modes.ModePacked{
+ self.current_modes,
+ self.saved_modes,
+ self.default_modes,
+ };
+ for (mode_values) |value| {
+ const bits: ModeBits = @bitCast(value);
+ try io.writeInt(writer, u64, @intCast(bits));
+ }
+
+ // Terminal-wide dynamic color state.
+ try encodeDynamicRGB(self.background, writer);
+ try encodeDynamicRGB(self.foreground, writer);
+ try encodeDynamicRGB(self.cursor_color, writer);
+
+ // Explicit primary-screen scrollback policies.
+ try io.writeInt(
+ writer,
+ u64,
+ self.max_scrollback_bytes orelse std.math.maxInt(u64),
+ );
+ try io.writeInt(
+ writer,
+ u64,
+ self.max_scrollback_rows orelse std.math.maxInt(u64),
+ );
+ }
+
+ /// Decode the fixed TERMINAL payload header, normalizing semantic values.
+ pub fn decode(reader: *std.Io.Reader) PayloadDecodeError!Header {
+ // Terminal geometry and its current scrolling region.
+ const columns = try io.readInt(reader, u16);
+ const rows = try io.readInt(reader, u16);
+ const width_px = try io.readInt(reader, u32);
+ const height_px = try io.readInt(reader, u32);
+ const scrolling_region_top = try io.readInt(reader, u16);
+ const scrolling_region_bottom = try io.readInt(reader, u16);
+ const scrolling_region_left = try io.readInt(reader, u16);
+ const scrolling_region_right = try io.readInt(reader, u16);
+
+ // Status display, screen routing, and character context.
+ const status_display = enumFromInt(
+ terminal_ansi.StatusDisplay,
+ try reader.takeByte(),
+ ) orelse .main;
+ const active_screen_key_raw = try io.readInt(reader, u16);
+ const screen_count = try io.readInt(reader, u16);
+ const previous_raw = try io.readInt(reader, u32);
+ const previous_codepoint: ?u21 = previous: {
+ if (previous_raw == std.math.maxInt(u32)) break :previous null;
+ const value = std.math.cast(u21, previous_raw) orelse
+ break :previous null;
+ if (value > 0x10FFFF or
+ (value >= 0xD800 and value <= 0xDFFF))
+ {
+ break :previous null;
+ }
+ break :previous value;
+ };
+
+ // Cursor presentation defaults shared by the screens.
+ const cursor_is_default = switch (try reader.takeByte()) {
+ 0 => false,
+ 1 => true,
+ else => true,
+ };
+ const cursor_default_style = enumFromInt(
+ TerminalScreen.CursorStyle,
+ try reader.takeByte(),
+ ) orelse .block;
+ const cursor_default_blink: ?bool = switch (try reader.takeByte()) {
+ 0 => null,
+ 1 => false,
+ 2 => true,
+ else => null,
+ };
+
+ // Terminal input, semantic redraw, and pointer behavior.
+ const shell_redraw = enumFromInt(
+ terminal_osc.semantic_prompt.Redraw,
+ try reader.takeByte(),
+ ) orelse .true;
+ const modify_other_keys_2 = switch (try reader.takeByte()) {
+ 0 => false,
+ 1 => true,
+ else => false,
+ };
+ const mouse_event = enumFromInt(
+ terminal_mouse.Event,
+ try reader.takeByte(),
+ ) orelse .none;
+ const mouse_format = enumFromInt(
+ terminal_mouse.Format,
+ try reader.takeByte(),
+ ) orelse .x10;
+ const mouse_shift_capture: ?bool = switch (try reader.takeByte()) {
+ 0 => null,
+ 1 => false,
+ 2 => true,
+ else => null,
+ };
+ const mouse_shape = enumFromInt(
+ terminal_mouse.Shape,
+ try reader.takeByte(),
+ ) orelse .text;
+ const password_input = switch (try reader.takeByte()) {
+ 0 => false,
+ 1 => true,
+ else => false,
+ };
+
+ // Runtime, saved, and reset mode sets.
+ var mode_values: [3]terminal_modes.ModePacked = undefined;
+ for (&mode_values) |*value| {
+ const raw = try io.readInt(reader, u64);
+ const bits: ModeBits = @truncate(raw);
+ value.* = @bitCast(bits);
+ }
+
+ // Terminal-wide dynamic color state.
+ const background = try decodeDynamicRGB(reader);
+ const foreground = try decodeDynamicRGB(reader);
+ const cursor_color = try decodeDynamicRGB(reader);
+
+ // Explicit primary-screen scrollback policies.
+ const max_scrollback_bytes = decodeOptionalLimit(
+ try io.readInt(reader, u64),
+ );
+ const max_scrollback_rows = decodeOptionalLimit(
+ try io.readInt(reader, u64),
+ );
+
+ // Dimensions and sequence count are the only header fields that define
+ // following allocation or record boundaries.
+ if (columns == 0 or rows == 0) return error.InvalidDimensions;
+ if (screen_count != 1 and screen_count != 2) {
+ return error.InvalidScreenCount;
+ }
+
+ const scrolling_region_vertical_valid =
+ scrolling_region_top <= scrolling_region_bottom and
+ scrolling_region_bottom < rows;
+ const scrolling_region_horizontal_valid =
+ scrolling_region_left <= scrolling_region_right and
+ scrolling_region_right < columns;
+ const active_screen_key: TerminalScreenKey = active: {
+ const decoded = enumFromInt(
+ TerminalScreenKey,
+ active_screen_key_raw,
+ ) orelse break :active .primary;
+ if (decoded == .alternate and screen_count != 2) {
+ break :active .primary;
+ }
+ break :active decoded;
+ };
+
+ const result: Header = .{
+ .columns = columns,
+ .rows = rows,
+ .width_px = width_px,
+ .height_px = height_px,
+
+ .scrolling_region_top = if (scrolling_region_vertical_valid)
+ scrolling_region_top
+ else
+ 0,
+ .scrolling_region_bottom = if (scrolling_region_vertical_valid)
+ scrolling_region_bottom
+ else
+ rows - 1,
+ .scrolling_region_left = if (scrolling_region_horizontal_valid)
+ scrolling_region_left
+ else
+ 0,
+ .scrolling_region_right = if (scrolling_region_horizontal_valid)
+ scrolling_region_right
+ else
+ columns - 1,
+
+ .status_display = status_display,
+ .active_screen_key = active_screen_key,
+ .screen_count = screen_count,
+ .previous_codepoint = previous_codepoint,
+
+ .cursor_is_default = cursor_is_default,
+ .cursor_default_style = cursor_default_style,
+ .cursor_default_blink = cursor_default_blink,
+
+ .shell_redraw = shell_redraw,
+ .modify_other_keys_2 = modify_other_keys_2,
+ .mouse_event = mouse_event,
+ .mouse_format = mouse_format,
+ .mouse_shift_capture = mouse_shift_capture,
+ .mouse_shape = mouse_shape,
+ .password_input = password_input,
+
+ .current_modes = mode_values[0],
+ .saved_modes = mode_values[1],
+ .default_modes = mode_values[2],
+
+ .background = background,
+ .foreground = foreground,
+ .cursor_color = cursor_color,
+
+ .max_scrollback_bytes = max_scrollback_bytes,
+ .max_scrollback_rows = max_scrollback_rows,
+ };
+ return result;
+ }
+
+ fn validate(self: Header) ValidationError!void {
+ if (self.columns == 0 or self.rows == 0) {
+ return error.InvalidDimensions;
+ }
+ if (self.scrolling_region_top > self.scrolling_region_bottom or
+ self.scrolling_region_bottom >= self.rows or
+ self.scrolling_region_left > self.scrolling_region_right or
+ self.scrolling_region_right >= self.columns)
+ {
+ return error.InvalidScrollingRegion;
+ }
+
+ if (self.screen_count != 1 and self.screen_count != 2) {
+ return error.InvalidScreenCount;
+ }
+ if (self.active_screen_key == .alternate and self.screen_count != 2) {
+ return error.InvalidActiveScreenKey;
+ }
+
+ if (self.previous_codepoint) |value| {
+ if (value > 0x10FFFF or
+ (value >= 0xD800 and value <= 0xDFFF))
+ {
+ return error.InvalidPreviousCodepoint;
+ }
+ }
+
+ if (self.max_scrollback_bytes == std.math.maxInt(u64) or
+ self.max_scrollback_rows == std.math.maxInt(u64))
+ {
+ return error.InvalidScrollbackLimit;
+ }
+ }
+
+ fn computeLen() usize {
+ comptime {
+ var buf: [128]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&buf);
+ const value: Header = .{
+ .columns = 1,
+ .rows = 1,
+ .width_px = 0,
+ .height_px = 0,
+ .scrolling_region_top = 0,
+ .scrolling_region_bottom = 0,
+ .scrolling_region_left = 0,
+ .scrolling_region_right = 0,
+ .status_display = .main,
+ .active_screen_key = .primary,
+ .screen_count = 1,
+ .previous_codepoint = null,
+ .cursor_is_default = true,
+ .cursor_default_style = .block,
+ .cursor_default_blink = null,
+ .shell_redraw = .true,
+ .modify_other_keys_2 = false,
+ .mouse_event = .none,
+ .mouse_format = .x10,
+ .mouse_shift_capture = null,
+ .mouse_shape = .text,
+ .password_input = false,
+ .current_modes = .{},
+ .saved_modes = .{},
+ .default_modes = .{},
+ .background = .unset,
+ .foreground = .unset,
+ .cursor_color = .unset,
+ .max_scrollback_bytes = null,
+ .max_scrollback_rows = null,
+ };
+ value.encode(&writer) catch unreachable;
+ return writer.end;
+ }
+ }
+};
+
+/// Allocator-owned semantic state decoded from one TERMINAL payload.
+///
+/// The fixed header is a value. `tabstops`, `palette`, `pwd`, and `title`
+/// own allocations and are released by `deinit`.
+const DecodedPayload = struct {
+ header: Header,
+ tabstops: TerminalTabstops,
+ palette: terminal_color.DynamicPalette,
+ pwd: []u8,
+ title: []u8,
+
+ fn deinit(self: *DecodedPayload, alloc: Allocator) void {
+ self.tabstops.deinit(alloc);
+ self.palette.deinit(alloc);
+ alloc.free(self.pwd);
+ alloc.free(self.title);
+ self.* = undefined;
+ }
+};
+
+/// Encode one complete TERMINAL payload without record framing.
+fn encodePayload(
+ header: Header,
+ tabstops: *const TerminalTabstops,
+ palette: *const terminal_color.DynamicPalette,
+ pwd: []const u8,
+ title: []const u8,
+ writer: *std.Io.Writer,
+) PayloadEncodeError!void {
+ // Validate the complete semantic value before writing any bytes.
+ try header.validate();
+ if (tabstops.cols != @as(usize, header.columns)) {
+ return error.InvalidTabStops;
+ }
+ if (pwd.len > std.math.maxInt(u32) or
+ title.len > std.math.maxInt(u32))
+ {
+ return error.StringTooLong;
+ }
+ for (palette.original, palette.current, 0..) |original, current, index| {
+ if (!palette.mask.isSet(index) and !original.eql(current)) {
+ return error.InvalidPalette;
+ }
+ }
+
+ try header.encode(writer);
+
+ // Tab stops are packed least-significant bit first.
+ const tabstop_len = (@as(usize, header.columns) + 7) / 8;
+ for (0..tabstop_len) |byte_index| {
+ var raw: u8 = 0;
+ for (0..8) |bit| {
+ const column = byte_index * 8 + bit;
+ if (column >= header.columns) break;
+ if (tabstops.get(column)) {
+ raw |= @as(u8, 1) << @intCast(bit);
+ }
+ }
+ try writer.writeByte(raw);
+ }
+
+ // Encode the original palette, then a compact mask and only the active
+ // overrides in increasing palette-index order.
+ for (palette.original) |value| try encodeRGB(value, writer);
+ for (0..32) |byte_index| {
+ var raw: u8 = 0;
+ for (0..8) |bit| {
+ if (palette.mask.isSet(byte_index * 8 + bit)) {
+ raw |= @as(u8, 1) << @intCast(bit);
+ }
+ }
+ try writer.writeByte(raw);
+ }
+ for (palette.current, 0..) |value, index| {
+ if (palette.mask.isSet(index)) try encodeRGB(value, writer);
+ }
+
+ // Length-prefixed terminal strings end the payload.
+ try io.writeInt(writer, u32, @intCast(pwd.len));
+ try writer.writeAll(pwd);
+ try io.writeInt(writer, u32, @intCast(title.len));
+ try writer.writeAll(title);
+}
+
+/// Decode one complete allocator-owned TERMINAL payload.
+///
+/// The enclosing record reader remains responsible for verifying exact payload
+/// exhaustion. On success, the caller owns the result and must call `deinit`.
+fn decodePayload(
+ reader: *std.Io.Reader,
+ alloc: Allocator,
+) PayloadDecodeError!DecodedPayload {
+ const header = try Header.decode(reader);
+
+ // Restore the native tab-stop representation from its packed wire bits.
+ var tabstops = try TerminalTabstops.init(alloc, header.columns, 0);
+ errdefer tabstops.deinit(alloc);
+ const tabstop_len = (@as(usize, header.columns) + 7) / 8;
+ for (0..tabstop_len) |byte_index| {
+ const raw = try reader.takeByte();
+ for (0..8) |bit| {
+ const mask = @as(u8, 1) << @intCast(bit);
+ const column = byte_index * 8 + bit;
+ if (column < header.columns and raw & mask != 0) {
+ tabstops.set(column);
+ }
+ }
+ }
+
+ // Reconstruct the dynamic palette from its original values and sparse
+ // current-value overrides.
+ var original: terminal_color.Palette = undefined;
+ for (&original) |*value| value.* = try decodeRGB(reader);
+ var override_mask: [32]u8 = undefined;
+ try reader.readSliceAll(&override_mask);
+
+ var palette: terminal_color.DynamicPalette = try .init(alloc, original);
+ errdefer palette.deinit(alloc);
+ for (0..256) |index| {
+ const mask = @as(u8, 1) << @intCast(index % 8);
+ if (override_mask[index / 8] & mask != 0) {
+ palette.set(@intCast(index), try decodeRGB(reader));
+ }
+ }
+
+ // Read the two allocator-owned terminal strings last so all earlier
+ // fixed-size validation happens before allocating them.
+ const pwd_len: usize = @intCast(try io.readInt(reader, u32));
+ const pwd = try alloc.alloc(u8, pwd_len);
+ errdefer alloc.free(pwd);
+ try reader.readSliceAll(pwd);
+
+ const title_len: usize = @intCast(try io.readInt(reader, u32));
+ const title = try alloc.alloc(u8, title_len);
+ errdefer alloc.free(title);
+ try reader.readSliceAll(title);
+
+ return .{
+ .header = header,
+ .tabstops = tabstops,
+ .palette = palette,
+ .pwd = pwd,
+ .title = title,
+ };
+}
+
+/// Errors possible while encoding one native TERMINAL record.
+pub const EncodeError = HeaderInitError ||
+ PayloadEncodeError ||
+ record.Writer.FinishError;
+
+/// Encode terminal-wide native state as one framed TERMINAL record.
+///
+/// State not represented by this snapshot version is ignored. Payload failures
+/// emit no part of the TERMINAL record.
+pub fn encode(
+ terminal: *const Terminal,
+ destination: *record.Writer,
+) EncodeError!void {
+ const header = try Header.init(terminal);
+
+ const payload = destination.begin(.terminal);
+ errdefer destination.cancel();
+ try encodePayload(
+ header,
+ &terminal.tabstops,
+ &terminal.colors.palette,
+ terminal.getPwd() orelse "",
+ terminal.getTitle() orelse "",
+ payload,
+ );
+ try destination.finish();
+}
+
+/// Errors possible while decoding one native TERMINAL record.
+pub const DecodeError = PayloadDecodeError ||
+ record.Reader.InitError ||
+ record.Reader.FinishError ||
+ error{
+ /// The next record is valid but is not a TERMINAL.
+ UnexpectedRecordTag,
+ };
+
+/// Decode one framed TERMINAL record directly into native terminal state.
+///
+/// The returned terminal owns every decoded allocation and contains empty
+/// primary and optional alternate screens with the declared routing. Later
+/// SCREEN records replace those screens in place. On failure, all decoded and
+/// partially initialized native state is released.
+pub fn decode(
+ source: *std.Io.Reader,
+ io_: std.Io,
+ alloc: Allocator,
+) DecodeError!Terminal {
+ // Finish the complete record before constructing native terminal state.
+ var payload: DecodedPayload = payload: {
+ var record_reader: record.Reader = undefined;
+ try record_reader.init(source);
+ if (record_reader.header.tag != .terminal) {
+ return error.UnexpectedRecordTag;
+ }
+
+ var payload = try decodePayload(record_reader.payloadReader(), alloc);
+ errdefer payload.deinit(alloc);
+ try record_reader.finish();
+ break :payload payload;
+ };
+ defer payload.deinit(alloc);
+
+ const header = payload.header;
+ const max_scrollback_bytes = nativeScrollbackLimit(
+ header.max_scrollback_bytes,
+ );
+ const max_scrollback_lines = nativeScrollbackLimit(
+ header.max_scrollback_rows,
+ );
+
+ // Terminal.init establishes native pools, pins, defaults, and ownership.
+ var result = try Terminal.init(io_, alloc, .{
+ .cols = header.columns,
+ .rows = header.rows,
+ .max_scrollback_bytes = max_scrollback_bytes,
+ .max_scrollback_lines = max_scrollback_lines,
+ .colors = .{
+ .background = header.background,
+ .foreground = header.foreground,
+ .cursor = header.cursor_color,
+ .palette = payload.palette,
+ },
+ .default_modes = header.default_modes,
+ .default_cursor_style = header.cursor_default_style,
+ .default_cursor_blink = header.cursor_default_blink,
+ });
+ errdefer result.deinit(alloc);
+
+ // The terminal owns the decoded palette now, so the payload must not
+ // release it.
+ payload.palette = .default;
+
+ // Recreate the optional screen now so ScreenSet routing is complete before
+ // its empty screens are replaced by the following SCREEN records.
+ if (header.screen_count == 2) {
+ _ = try result.screens.getInit(io_, alloc, .alternate, .{
+ .cols = header.columns,
+ .rows = header.rows,
+ .max_scrollback_bytes = 0,
+ });
+ }
+ result.screens.switchTo(header.active_screen_key);
+
+ // Restore terminal-wide runtime state that is not an initialization
+ // policy. Presentation-only flags retain Terminal.init defaults.
+ result.width_px = header.width_px;
+ result.height_px = header.height_px;
+ result.scrolling_region = .{
+ .top = header.scrolling_region_top,
+ .bottom = header.scrolling_region_bottom,
+ .left = header.scrolling_region_left,
+ .right = header.scrolling_region_right,
+ };
+ result.status_display = header.status_display;
+ result.previous_char = header.previous_codepoint;
+ result.cursor = .{
+ .is_default = header.cursor_is_default,
+ .default_style = header.cursor_default_style,
+ .default_blink = header.cursor_default_blink,
+ };
+ result.modes = .{
+ .values = header.current_modes,
+ .saved = header.saved_modes,
+ .default = header.default_modes,
+ };
+ result.flags.shell_redraws_prompt = header.shell_redraw;
+ result.flags.modify_other_keys_2 = header.modify_other_keys_2;
+ result.flags.mouse_event = header.mouse_event;
+ result.flags.mouse_format = header.mouse_format;
+ result.flags.mouse_shift_capture = if (header.mouse_shift_capture) |value|
+ if (value) .true else .false
+ else
+ .null;
+ result.flags.password_input = header.password_input;
+ result.mouse_shape = header.mouse_shape;
+
+ // Native strings retain trailing NUL sentinels. Setters construct those
+ // without exposing that detail in the wire format.
+ try result.setPwd(payload.pwd);
+ try result.setTitle(payload.title);
+
+ // Transfer decoded tab-stop ownership last. The deferred payload cleanup
+ // releases the table originally allocated by Terminal.init.
+ const initialized_tabstops = result.tabstops;
+ result.tabstops = payload.tabstops;
+ payload.tabstops = initialized_tabstops;
+
+ result.screens.active.pages.assertIntegrity();
+ return result;
+}
+
+fn enumFromInt(comptime T: type, raw: anytype) ?T {
+ const Tag = @typeInfo(T).@"enum".tag_type;
+ const value = std.math.cast(Tag, raw) orelse return null;
+ return std.enums.fromInt(T, value);
+}
+
+fn encodeOptionalBool(value: ?bool) u8 {
+ return if (value) |present|
+ if (present) 2 else 1
+ else
+ 0;
+}
+
+fn encodeRGB(
+ value: RGB,
+ writer: *std.Io.Writer,
+) std.Io.Writer.Error!void {
+ try writer.writeByte(value.r);
+ try writer.writeByte(value.g);
+ try writer.writeByte(value.b);
+}
+
+fn decodeRGB(reader: *std.Io.Reader) std.Io.Reader.Error!RGB {
+ return .{
+ .r = try reader.takeByte(),
+ .g = try reader.takeByte(),
+ .b = try reader.takeByte(),
+ };
+}
+
+fn encodeDynamicRGB(
+ value: DynamicRGB,
+ writer: *std.Io.Writer,
+) std.Io.Writer.Error!void {
+ if (value.default) |rgb| {
+ try writer.writeByte(1);
+ try encodeRGB(rgb, writer);
+ } else {
+ try writer.writeByte(0);
+ try writer.splatByteAll(0, 3);
+ }
+
+ if (value.override) |rgb| {
+ try writer.writeByte(1);
+ try encodeRGB(rgb, writer);
+ } else {
+ try writer.writeByte(0);
+ try writer.splatByteAll(0, 3);
+ }
+}
+
+fn decodeDynamicRGB(
+ reader: *std.Io.Reader,
+) std.Io.Reader.Error!DynamicRGB {
+ const default_present = try reader.takeByte();
+ const default_rgb = try decodeRGB(reader);
+ const default: ?RGB = if (default_present == 1) default_rgb else null;
+
+ const override_present = try reader.takeByte();
+ const override_rgb = try decodeRGB(reader);
+ const override: ?RGB = if (override_present == 1) override_rgb else null;
+
+ return .{ .default = default, .override = override };
+}
+
+fn decodeOptionalLimit(raw: u64) ?u64 {
+ return if (raw == std.math.maxInt(u64)) null else raw;
+}
+
+fn encodeScrollbackLimit(value: usize) HeaderInitError!?u64 {
+ if (value == std.math.maxInt(usize)) return null;
+ const result = std.math.cast(u64, value) orelse
+ return error.ScrollbackLimitOverflow;
+ if (result == std.math.maxInt(u64)) {
+ return error.ScrollbackLimitOverflow;
+ }
+ return result;
+}
+
+fn nativeScrollbackLimit(
+ value: ?u64,
+) ?usize {
+ const present = value orelse return null;
+ return @intCast(@min(
+ present,
+ @as(u64, std.math.maxInt(usize) - 1),
+ ));
+}
+
+const test_header: Header = header: {
+ var current_modes = std.mem.zeroes(terminal_modes.ModePacked);
+ current_modes.disable_keyboard = true;
+ var saved_modes = std.mem.zeroes(terminal_modes.ModePacked);
+ saved_modes.in_band_size_reports = true;
+ var default_modes = current_modes;
+ default_modes.in_band_size_reports = true;
+
+ break :header .{
+ .columns = 0x0102,
+ .rows = 0x0304,
+ .width_px = 0x05060708,
+ .height_px = 0x090a0b0c,
+
+ .scrolling_region_top = 1,
+ .scrolling_region_bottom = 2,
+ .scrolling_region_left = 3,
+ .scrolling_region_right = 4,
+
+ .status_display = .status_line,
+ .active_screen_key = .alternate,
+ .screen_count = 2,
+ .previous_codepoint = 'A',
+
+ .cursor_is_default = true,
+ .cursor_default_style = .block_hollow,
+ .cursor_default_blink = true,
+
+ .shell_redraw = .last,
+ .modify_other_keys_2 = true,
+ .mouse_event = .any,
+ .mouse_format = .sgr_pixels,
+ .mouse_shift_capture = false,
+ .mouse_shape = .zoom_out,
+ .password_input = true,
+
+ .current_modes = current_modes,
+ .saved_modes = saved_modes,
+ .default_modes = default_modes,
+
+ .background = .{
+ .default = .{ .r = 1, .g = 2, .b = 3 },
+ .override = null,
+ },
+ .foreground = .{
+ .default = null,
+ .override = .{ .r = 4, .g = 5, .b = 6 },
+ },
+ .cursor_color = .{
+ .default = .{ .r = 7, .g = 8, .b = 9 },
+ .override = .{ .r = 10, .g = 11, .b = 12 },
+ },
+
+ .max_scrollback_bytes = null,
+ .max_scrollback_rows = 0x0102030405060708,
+ };
+};
+
+const test_header_fixture = test_fixture.parse(
+ @embedFile("testdata/terminal-header-v1.hex"),
+);
+
+test "TERMINAL mode bit layout" {
+ try std.testing.expectEqual(
+ @as(usize, 43),
+ @bitSizeOf(terminal_modes.ModePacked),
+ );
+
+ var first: terminal_modes.ModePacked = std.mem.zeroes(
+ terminal_modes.ModePacked,
+ );
+ first.disable_keyboard = true;
+ try std.testing.expectEqual(
+ @as(u43, 1) << 0,
+ @as(u43, @bitCast(first)),
+ );
+
+ var visibility: terminal_modes.ModePacked = std.mem.zeroes(
+ terminal_modes.ModePacked,
+ );
+ visibility.report_visibility = true;
+ try std.testing.expectEqual(
+ @as(u43, 1) << 40,
+ @as(u43, @bitCast(visibility)),
+ );
+
+ var size_reports: terminal_modes.ModePacked = std.mem.zeroes(
+ terminal_modes.ModePacked,
+ );
+ size_reports.in_band_size_reports = true;
+ try std.testing.expectEqual(
+ @as(u43, 1) << 41,
+ @as(u43, @bitCast(size_reports)),
+ );
+
+ var last: terminal_modes.ModePacked = std.mem.zeroes(
+ terminal_modes.ModePacked,
+ );
+ last.kitty_paste_events = true;
+ try std.testing.expectEqual(
+ @as(u43, 1) << 42,
+ @as(u43, @bitCast(last)),
+ );
+}
+
+test "TERMINAL header golden encoding and decoding" {
+ const testing = std.testing;
+
+ var encoded: [Header.len]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try test_header.encode(&writer);
+ try test_fixture.expectEqual(
+ .bytes,
+ "src/terminal/snapshot/testdata/terminal-header-v1.hex",
+ "snapshot_fixture-terminal-header-v1.hex",
+ &test_header_fixture,
+ writer.buffered(),
+ );
+ try testing.expectEqual(Header.len, test_header_fixture.len);
+
+ // Exercise the streaming path with less buffered data than every integer.
+ var source: std.Io.Reader = .fixed(&test_header_fixture);
+ var buffer: [1]u8 = undefined;
+ var limited = source.limited(.unlimited, &buffer);
+ try testing.expectEqualDeep(
+ test_header,
+ try Header.decode(&limited.interface),
+ );
+
+ for (0..Header.len) |fixture_len| {
+ var truncated: std.Io.Reader = .fixed(
+ test_header_fixture[0..fixture_len],
+ );
+ try testing.expectError(
+ error.EndOfStream,
+ Header.decode(&truncated),
+ );
+ }
+}
+
+test "TERMINAL header encoding rejects noncanonical values" {
+ const testing = std.testing;
+
+ // Semantic values are validated before encoding writes anything.
+ var invalid_header = test_header;
+ invalid_header.columns = 0;
+ var encoded: [Header.len]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try testing.expectError(
+ error.InvalidDimensions,
+ invalid_header.encode(&writer),
+ );
+ try testing.expectEqual(@as(usize, 0), writer.end);
+
+ invalid_header = test_header;
+ invalid_header.max_scrollback_bytes = std.math.maxInt(u64);
+ writer = .fixed(&encoded);
+ try testing.expectError(
+ error.InvalidScrollbackLimit,
+ invalid_header.encode(&writer),
+ );
+ try testing.expectEqual(@as(usize, 0), writer.end);
+}
+
+test "TERMINAL header decoding rejects structural values" {
+ const testing = std.testing;
+
+ var invalid_dimensions = test_header_fixture;
+ invalid_dimensions[0] = 0;
+ invalid_dimensions[1] = 0;
+ var dimensions_reader: std.Io.Reader = .fixed(&invalid_dimensions);
+ try testing.expectError(
+ error.InvalidDimensions,
+ Header.decode(&dimensions_reader),
+ );
+
+ var invalid_screen_count = test_header_fixture;
+ invalid_screen_count[23] = 3;
+ var screen_count_reader: std.Io.Reader = .fixed(&invalid_screen_count);
+ try testing.expectError(
+ error.InvalidScreenCount,
+ Header.decode(&screen_count_reader),
+ );
+}
+
+test "TERMINAL header decoding normalizes semantic values" {
+ const testing = std.testing;
+
+ var fixture = test_header_fixture;
+
+ // Unknown enum and boolean encodings use their neutral native defaults.
+ fixture[20] = 2;
+ fixture[21] = 2;
+ fixture[22] = 0;
+ fixture[29] = 2;
+ fixture[30] = 4;
+ fixture[31] = 3;
+ fixture[32] = 3;
+ fixture[33] = 2;
+ fixture[34] = 5;
+ fixture[35] = 5;
+ fixture[36] = 3;
+ fixture[37] = 34;
+ fixture[38] = 2;
+
+ // Reserved mode bits are ignored while known low bits survive.
+ fixture[44] = 4;
+
+ // Unknown presence and nonzero absent-value bytes both become absent.
+ fixture[63] = 2;
+ fixture[68] = 1;
+ fixture[72] = 0xAA;
+
+ // An invalid scrolling region becomes the full terminal region.
+ fixture[14] = 0x04;
+ fixture[15] = 0x03;
+
+ // Surrogates cannot become native previous-character state.
+ fixture[25] = 0x00;
+ fixture[26] = 0xD8;
+ fixture[27] = 0x00;
+ fixture[28] = 0x00;
+
+ var reader: std.Io.Reader = .fixed(&fixture);
+ const decoded = try Header.decode(&reader);
+ try testing.expectEqual(terminal_ansi.StatusDisplay.main, decoded.status_display);
+ try testing.expectEqual(TerminalScreenKey.primary, decoded.active_screen_key);
+ try testing.expectEqual(@as(u16, 0), decoded.scrolling_region_top);
+ try testing.expectEqual(test_header.rows - 1, decoded.scrolling_region_bottom);
+ try testing.expectEqual(test_header.scrolling_region_left, decoded.scrolling_region_left);
+ try testing.expectEqual(test_header.scrolling_region_right, decoded.scrolling_region_right);
+ try testing.expectEqual(null, decoded.previous_codepoint);
+ try testing.expect(decoded.cursor_is_default);
+ try testing.expectEqual(TerminalScreen.CursorStyle.block, decoded.cursor_default_style);
+ try testing.expectEqual(null, decoded.cursor_default_blink);
+ try testing.expectEqual(terminal_osc.semantic_prompt.Redraw.true, decoded.shell_redraw);
+ try testing.expect(!decoded.modify_other_keys_2);
+ try testing.expectEqual(terminal_mouse.Event.none, decoded.mouse_event);
+ try testing.expectEqual(terminal_mouse.Format.x10, decoded.mouse_format);
+ try testing.expectEqual(null, decoded.mouse_shift_capture);
+ try testing.expectEqual(terminal_mouse.Shape.text, decoded.mouse_shape);
+ try testing.expect(!decoded.password_input);
+ try testing.expect(decoded.current_modes.disable_keyboard);
+ try testing.expectEqualDeep(DynamicRGB.unset, decoded.background);
+ try testing.expectEqual(null, decoded.foreground.default);
+ try testing.expectEqual(
+ RGB{ .r = 4, .g = 5, .b = 6 },
+ decoded.foreground.override.?,
+ );
+
+ // Each scrolling axis is normalized independently.
+ var invalid_horizontal = test_header_fixture;
+ invalid_horizontal[18] = 0x02;
+ invalid_horizontal[19] = 0x01;
+ var horizontal_reader: std.Io.Reader = .fixed(&invalid_horizontal);
+ const horizontal = try Header.decode(&horizontal_reader);
+ try testing.expectEqual(
+ test_header.scrolling_region_top,
+ horizontal.scrolling_region_top,
+ );
+ try testing.expectEqual(
+ test_header.scrolling_region_bottom,
+ horizontal.scrolling_region_bottom,
+ );
+ try testing.expectEqual(@as(u16, 0), horizontal.scrolling_region_left);
+ try testing.expectEqual(
+ test_header.columns - 1,
+ horizontal.scrolling_region_right,
+ );
+
+ // Alternate cannot be active when only the primary screen is declared.
+ var missing_active_screen = test_header_fixture;
+ missing_active_screen[23] = 1;
+ var active_screen_reader: std.Io.Reader = .fixed(&missing_active_screen);
+ try testing.expectEqual(
+ TerminalScreenKey.primary,
+ (try Header.decode(&active_screen_reader)).active_screen_key,
+ );
+
+ const largest_finite = std.math.maxInt(u64) - 1;
+ try testing.expectEqual(
+ @as(usize, @intCast(@min(
+ largest_finite,
+ @as(u64, std.math.maxInt(usize) - 1),
+ ))),
+ nativeScrollbackLimit(largest_finite).?,
+ );
+}
+
+test "TERMINAL payload round trip" {
+ const testing = std.testing;
+
+ // Include a partial final tab-stop byte so its bit order and padding are
+ // both exercised.
+ var tabstops = try TerminalTabstops.init(
+ testing.allocator,
+ test_header.columns,
+ 0,
+ );
+ defer tabstops.deinit(testing.allocator);
+ tabstops.set(0);
+ tabstops.set(8);
+ tabstops.set(test_header.columns - 1);
+
+ // Use overrides at both ends of the palette to make ordering explicit.
+ var palette: terminal_color.DynamicPalette = .default;
+ palette.set(0, .{ .r = 1, .g = 2, .b = 3 });
+ palette.set(255, .{ .r = 4, .g = 5, .b = 6 });
+
+ var destination: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer destination.deinit();
+ try encodePayload(
+ test_header,
+ &tabstops,
+ &palette,
+ "file:///tmp/example",
+ "snapshot title",
+ &destination.writer,
+ );
+
+ // Tab stops and the sparse palette mask both use least-significant-bit
+ // first ordering.
+ const bytes = destination.written();
+ const tabstop_len = (@as(usize, test_header.columns) + 7) / 8;
+ try testing.expectEqual(@as(u8, 0x01), bytes[Header.len]);
+ try testing.expectEqual(@as(u8, 0x01), bytes[Header.len + 1]);
+ try testing.expectEqual(
+ @as(u8, 0x02),
+ bytes[Header.len + tabstop_len - 1],
+ );
+ const palette_mask_offset = Header.len + tabstop_len + 256 * 3;
+ try testing.expectEqual(@as(u8, 0x01), bytes[palette_mask_offset]);
+ try testing.expectEqual(
+ @as(u8, 0x80),
+ bytes[palette_mask_offset + 31],
+ );
+
+ // Decode through a one-byte reader buffer to cover streaming of the large
+ // fixed palette and allocator-owned strings.
+ var source: std.Io.Reader = .fixed(bytes);
+ var buffer: [1]u8 = undefined;
+ var limited = source.limited(.unlimited, &buffer);
+ var decoded = try decodePayload(
+ &limited.interface,
+ testing.allocator,
+ );
+ defer decoded.deinit(testing.allocator);
+
+ try testing.expectEqualDeep(test_header, decoded.header);
+ for (0..test_header.columns) |column| {
+ try testing.expectEqual(
+ tabstops.get(column),
+ decoded.tabstops.get(column),
+ );
+ }
+ try testing.expectEqualDeep(palette, decoded.palette);
+ try testing.expectEqualStrings("file:///tmp/example", decoded.pwd);
+ try testing.expectEqualStrings("snapshot title", decoded.title);
+}
+
+test "TERMINAL payload rejects noncanonical state" {
+ const testing = std.testing;
+
+ // A tab-stop set for different dimensions cannot represent this header.
+ var tabstops = try TerminalTabstops.init(
+ testing.allocator,
+ test_header.columns - 1,
+ 0,
+ );
+ defer tabstops.deinit(testing.allocator);
+ var palette: terminal_color.DynamicPalette = .default;
+ var encoded: [2048]u8 = undefined;
+ var writer: std.Io.Writer = .fixed(&encoded);
+ try testing.expectError(
+ error.InvalidTabStops,
+ encodePayload(
+ test_header,
+ &tabstops,
+ &palette,
+ "",
+ "",
+ &writer,
+ ),
+ );
+ try testing.expectEqual(@as(usize, 0), writer.end);
+
+ // Unmasked current colors must remain equal to their originals.
+ tabstops.cols = test_header.columns;
+ palette.current[7] = .{ .r = 1, .g = 2, .b = 3 };
+ writer = .fixed(&encoded);
+ try testing.expectError(
+ error.InvalidPalette,
+ encodePayload(
+ test_header,
+ &tabstops,
+ &palette,
+ "",
+ "",
+ &writer,
+ ),
+ );
+ try testing.expectEqual(@as(usize, 0), writer.end);
+}
+
+test "TERMINAL payload ignores tab-stop padding" {
+ const testing = std.testing;
+
+ var tabstops = try TerminalTabstops.init(
+ testing.allocator,
+ test_header.columns,
+ 0,
+ );
+ defer tabstops.deinit(testing.allocator);
+ var palette: terminal_color.DynamicPalette = .default;
+ palette.set(1, .{ .r = 1, .g = 2, .b = 3 });
+
+ var destination: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer destination.deinit();
+ try encodePayload(
+ test_header,
+ &tabstops,
+ &palette,
+ "pwd",
+ "title",
+ &destination.writer,
+ );
+
+ // Only two bits in the last byte correspond to terminal columns.
+ const tabstop_len = (@as(usize, test_header.columns) + 7) / 8;
+ const last_tabstop = Header.len + tabstop_len - 1;
+ const invalid_padding = try testing.allocator.dupe(
+ u8,
+ destination.written(),
+ );
+ defer testing.allocator.free(invalid_padding);
+ invalid_padding[last_tabstop] |= 1 << 7;
+ var padding_reader: std.Io.Reader = .fixed(invalid_padding);
+ var decoded = try decodePayload(
+ &padding_reader,
+ testing.allocator,
+ );
+ defer decoded.deinit(testing.allocator);
+ for (0..test_header.columns) |column| {
+ try testing.expectEqual(
+ tabstops.get(column),
+ decoded.tabstops.get(column),
+ );
+ }
+}
+
+test "TERMINAL record encodes native terminal state" {
+ const testing = std.testing;
+
+ var terminal = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 10,
+ .rows = 3,
+ .max_scrollback_bytes = 12_345,
+ .max_scrollback_lines = 67,
+ });
+ defer terminal.deinit(testing.allocator);
+
+ // Exercise every native header section plus sentinel-backed strings.
+ terminal.width_px = 800;
+ terminal.height_px = 600;
+ terminal.scrolling_region = .{
+ .top = 1,
+ .bottom = 2,
+ .left = 2,
+ .right = 8,
+ };
+ terminal.status_display = .status_line;
+ terminal.previous_char = 'X';
+ terminal.cursor = .{
+ .is_default = false,
+ .default_style = .underline,
+ .default_blink = true,
+ };
+ terminal.flags.shell_redraws_prompt = .last;
+ terminal.flags.modify_other_keys_2 = true;
+ terminal.flags.mouse_event = .button;
+ terminal.flags.mouse_format = .sgr;
+ terminal.flags.mouse_shift_capture = .true;
+ terminal.flags.password_input = true;
+ terminal.mouse_shape = .pointer;
+ terminal.modes.values.disable_keyboard = true;
+ terminal.modes.saved.in_band_size_reports = true;
+ terminal.modes.default.bracketed_paste = true;
+ terminal.colors.background = .{
+ .default = .{ .r = 1, .g = 2, .b = 3 },
+ .override = .{ .r = 4, .g = 5, .b = 6 },
+ };
+ terminal.colors.palette.set(7, .{ .r = 7, .g = 8, .b = 9 });
+ terminal.tabstops.reset(0);
+ terminal.tabstops.set(1);
+ terminal.tabstops.set(9);
+ try terminal.setPwd("file:///tmp/native");
+ try terminal.setTitle("native title");
+
+ // Encode and restore through the public record codec.
+ var destination: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer destination.deinit();
+ var stream: record.Writer = .init(
+ testing.allocator,
+ &destination.writer,
+ );
+ defer stream.deinit();
+ try encode(&terminal, &stream);
+
+ var source: std.Io.Reader = .fixed(destination.written());
+ var restored = try decode(
+ &source,
+ testing.io,
+ testing.allocator,
+ );
+ defer restored.deinit(testing.allocator);
+
+ try testing.expectEqual(@as(u16, 10), restored.cols);
+ try testing.expectEqual(@as(u16, 3), restored.rows);
+ try testing.expectEqual(@as(u32, 800), restored.width_px);
+ try testing.expectEqual(@as(u32, 600), restored.height_px);
+ try testing.expectEqual(terminal.scrolling_region, restored.scrolling_region);
+ try testing.expectEqual(terminal.status_display, restored.status_display);
+ try testing.expectEqual(.primary, restored.screens.active_key);
+ try testing.expect(restored.screens.get(.alternate) == null);
+ try testing.expectEqual(@as(?u21, 'X'), restored.previous_char);
+ try testing.expectEqualDeep(terminal.cursor, restored.cursor);
+ try testing.expectEqual(
+ terminal.flags.shell_redraws_prompt,
+ restored.flags.shell_redraws_prompt,
+ );
+ try testing.expectEqual(
+ terminal.flags.modify_other_keys_2,
+ restored.flags.modify_other_keys_2,
+ );
+ try testing.expectEqual(
+ terminal.flags.mouse_event,
+ restored.flags.mouse_event,
+ );
+ try testing.expectEqual(
+ terminal.flags.mouse_format,
+ restored.flags.mouse_format,
+ );
+ try testing.expectEqual(
+ terminal.flags.mouse_shift_capture,
+ restored.flags.mouse_shift_capture,
+ );
+ try testing.expectEqual(
+ terminal.flags.password_input,
+ restored.flags.password_input,
+ );
+ try testing.expectEqual(terminal.mouse_shape, restored.mouse_shape);
+ try testing.expectEqualDeep(terminal.modes, restored.modes);
+ try testing.expectEqualDeep(terminal.colors, restored.colors);
+ try testing.expectEqual(
+ @as(usize, 12_345),
+ restored.screens.active.pages.limits.bytes.explicit,
+ );
+ try testing.expectEqual(
+ @as(usize, 67),
+ restored.screens.active.pages.limits.lines.explicit,
+ );
+ try testing.expect(restored.tabstops.get(1));
+ try testing.expect(restored.tabstops.get(9));
+ try testing.expectEqualStrings(
+ "file:///tmp/native",
+ restored.getPwd().?,
+ );
+ try testing.expectEqualStrings("native title", restored.getTitle().?);
+}
+
+test "TERMINAL record declares an initialized alternate screen" {
+ const testing = std.testing;
+
+ var terminal = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 10,
+ .rows = 3,
+ });
+ defer terminal.deinit(testing.allocator);
+ _ = try terminal.switchScreen(.alternate);
+
+ var destination: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer destination.deinit();
+ var stream: record.Writer = .init(
+ testing.allocator,
+ &destination.writer,
+ );
+ defer stream.deinit();
+ try encode(&terminal, &stream);
+
+ var source: std.Io.Reader = .fixed(destination.written());
+ var restored = try decode(
+ &source,
+ testing.io,
+ testing.allocator,
+ );
+ defer restored.deinit(testing.allocator);
+
+ const primary = restored.screens.get(.primary).?;
+ const alternate = restored.screens.get(.alternate).?;
+ try testing.expectEqual(.alternate, restored.screens.active_key);
+ try testing.expectEqual(alternate, restored.screens.active);
+ try testing.expect(primary != alternate);
+ try testing.expectEqual(@as(u16, 10), alternate.pages.cols);
+ try testing.expectEqual(@as(u16, 3), alternate.pages.rows);
+ try testing.expectEqual(
+ @as(usize, 0),
+ alternate.pages.limits.bytes.explicit,
+ );
+}
+
+test "TERMINAL payload failure emits no incomplete record" {
+ const testing = std.testing;
+
+ var terminal = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 10,
+ .rows = 3,
+ });
+ defer terminal.deinit(testing.allocator);
+
+ var destination: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer destination.deinit();
+ try destination.writer.writeAll("prefix");
+ var stream: record.Writer = .init(
+ testing.allocator,
+ &destination.writer,
+ );
+ defer stream.deinit();
+
+ // Payload validation occurs in the reusable record scratch buffer. The
+ // invalid TERMINAL is never emitted to the destination.
+ terminal.colors.palette.current[7] = .{ .r = 1, .g = 2, .b = 3 };
+ try testing.expectError(
+ error.InvalidPalette,
+ encode(&terminal, &stream),
+ );
+ try testing.expectEqualStrings("prefix", destination.written());
+}
+
+test "TERMINAL record decoding rejects malformed input transactionally" {
+ const testing = std.testing;
+
+ // A valid record of another type is not accepted as TERMINAL state.
+ var wrong_tag: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer wrong_tag.deinit();
+ var wrong_tag_stream: record.Writer = .init(
+ testing.allocator,
+ &wrong_tag.writer,
+ );
+ defer wrong_tag_stream.deinit();
+ {
+ _ = wrong_tag_stream.begin(.screen);
+ errdefer wrong_tag_stream.cancel();
+ try wrong_tag_stream.finish();
+ }
+ var wrong_tag_source: std.Io.Reader = .fixed(wrong_tag.written());
+ try testing.expectError(
+ error.UnexpectedRecordTag,
+ decode(&wrong_tag_source, testing.io, testing.allocator),
+ );
+
+ // Build one canonical record for exhaustive truncation and allocation
+ // failure checks below.
+ var terminal = try Terminal.init(testing.io, testing.allocator, .{
+ .cols = 10,
+ .rows = 3,
+ });
+ defer terminal.deinit(testing.allocator);
+ try terminal.setPwd("pwd");
+ try terminal.setTitle("title");
+
+ var encoded: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer encoded.deinit();
+ var encoded_stream: record.Writer = .init(
+ testing.allocator,
+ &encoded.writer,
+ );
+ defer encoded_stream.deinit();
+ try encode(&terminal, &encoded_stream);
+
+ for (0..encoded.written().len) |fixture_len| {
+ var source: std.Io.Reader = .fixed(
+ encoded.written()[0..fixture_len],
+ );
+ var restored = decode(
+ &source,
+ testing.io,
+ testing.allocator,
+ ) catch continue;
+ restored.deinit(testing.allocator);
+ try testing.expect(false);
+ }
+
+ var failing = testing.FailingAllocator.init(
+ testing.allocator,
+ .{ .fail_index = 0 },
+ );
+ var failing_source: std.Io.Reader = .fixed(encoded.written());
+ try testing.expectError(
+ error.OutOfMemory,
+ decode(&failing_source, testing.io, failing.allocator()),
+ );
+}
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/checkpoint-ready-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/checkpoint-ready-v1.hex
new file mode 100644
index 00000000..3ff7c5d0
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/checkpoint-ready-v1.hex
@@ -0,0 +1,10 @@
+# Ghostty snapshot fixture
+# Kaitai type: checkpoint_record
+# Kaitai params: 5
+# Kaitai offset: 3
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+61 62 63 05 00 00 00 00 00 e4 20 ef 0a # 0x00000000
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/complete-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/complete-v1.hex
new file mode 100644
index 00000000..1fa59f61
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/complete-v1.hex
@@ -0,0 +1,120 @@
+# Ghostty snapshot fixture
+# Kaitai type: ghostty_snapshot
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: snapshot envelope
+47 48 4f 53 54 53 4e 50 01 00 # 0x00000000
+
+# offset 0x0000000a: terminal record, payload 952 bytes
+01 00 b8 03 00 00 e3 5f 8b cc 02 00 03 00 20 03 # 0x0000000a
+00 00 58 02 00 00 00 00 02 00 00 00 01 00 00 01 # 0x0000001a
+00 02 00 65 00 00 00 01 01 01 00 00 00 00 00 08 # 0x0000002a
+00 04 22 00 64 10 00 00 00 04 22 00 64 00 00 00 # 0x0000003a
+00 04 22 00 64 00 00 00 00 00 00 00 00 00 00 00 # 0x0000004a
+00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 # 0x0000005a
+00 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff # 0x0000006a
+ff 00 1d 1f 21 cc 66 66 b5 bd 68 f0 c6 74 81 a2 # 0x0000007a
+be b2 94 bb 8a be b7 c5 c8 c6 66 66 66 d5 4e 53 # 0x0000008a
+b9 ca 4a e7 c5 47 7a a6 da c3 97 d8 70 c0 b1 ea # 0x0000009a
+ea ea 00 00 00 00 00 5f 00 00 87 00 00 af 00 00 # 0x000000aa
+d7 00 00 ff 00 5f 00 00 5f 5f 00 5f 87 00 5f af # 0x000000ba
+00 5f d7 00 5f ff 00 87 00 00 87 5f 00 87 87 00 # 0x000000ca
+87 af 00 87 d7 00 87 ff 00 af 00 00 af 5f 00 af # 0x000000da
+87 00 af af 00 af d7 00 af ff 00 d7 00 00 d7 5f # 0x000000ea
+00 d7 87 00 d7 af 00 d7 d7 00 d7 ff 00 ff 00 00 # 0x000000fa
+ff 5f 00 ff 87 00 ff af 00 ff d7 00 ff ff 5f 00 # 0x0000010a
+00 5f 00 5f 5f 00 87 5f 00 af 5f 00 d7 5f 00 ff # 0x0000011a
+5f 5f 00 5f 5f 5f 5f 5f 87 5f 5f af 5f 5f d7 5f # 0x0000012a
+5f ff 5f 87 00 5f 87 5f 5f 87 87 5f 87 af 5f 87 # 0x0000013a
+d7 5f 87 ff 5f af 00 5f af 5f 5f af 87 5f af af # 0x0000014a
+5f af d7 5f af ff 5f d7 00 5f d7 5f 5f d7 87 5f # 0x0000015a
+d7 af 5f d7 d7 5f d7 ff 5f ff 00 5f ff 5f 5f ff # 0x0000016a
+87 5f ff af 5f ff d7 5f ff ff 87 00 00 87 00 5f # 0x0000017a
+87 00 87 87 00 af 87 00 d7 87 00 ff 87 5f 00 87 # 0x0000018a
+5f 5f 87 5f 87 87 5f af 87 5f d7 87 5f ff 87 87 # 0x0000019a
+00 87 87 5f 87 87 87 87 87 af 87 87 d7 87 87 ff # 0x000001aa
+87 af 00 87 af 5f 87 af 87 87 af af 87 af d7 87 # 0x000001ba
+af ff 87 d7 00 87 d7 5f 87 d7 87 87 d7 af 87 d7 # 0x000001ca
+d7 87 d7 ff 87 ff 00 87 ff 5f 87 ff 87 87 ff af # 0x000001da
+87 ff d7 87 ff ff af 00 00 af 00 5f af 00 87 af # 0x000001ea
+00 af af 00 d7 af 00 ff af 5f 00 af 5f 5f af 5f # 0x000001fa
+87 af 5f af af 5f d7 af 5f ff af 87 00 af 87 5f # 0x0000020a
+af 87 87 af 87 af af 87 d7 af 87 ff af af 00 af # 0x0000021a
+af 5f af af 87 af af af af af d7 af af ff af d7 # 0x0000022a
+00 af d7 5f af d7 87 af d7 af af d7 d7 af d7 ff # 0x0000023a
+af ff 00 af ff 5f af ff 87 af ff af af ff d7 af # 0x0000024a
+ff ff d7 00 00 d7 00 5f d7 00 87 d7 00 af d7 00 # 0x0000025a
+d7 d7 00 ff d7 5f 00 d7 5f 5f d7 5f 87 d7 5f af # 0x0000026a
+d7 5f d7 d7 5f ff d7 87 00 d7 87 5f d7 87 87 d7 # 0x0000027a
+87 af d7 87 d7 d7 87 ff d7 af 00 d7 af 5f d7 af # 0x0000028a
+87 d7 af af d7 af d7 d7 af ff d7 d7 00 d7 d7 5f # 0x0000029a
+d7 d7 87 d7 d7 af d7 d7 d7 d7 d7 ff d7 ff 00 d7 # 0x000002aa
+ff 5f d7 ff 87 d7 ff af d7 ff d7 d7 ff ff ff 00 # 0x000002ba
+00 ff 00 5f ff 00 87 ff 00 af ff 00 d7 ff 00 ff # 0x000002ca
+ff 5f 00 ff 5f 5f ff 5f 87 ff 5f af ff 5f d7 ff # 0x000002da
+5f ff ff 87 00 ff 87 5f ff 87 87 ff 87 af ff 87 # 0x000002ea
+d7 ff 87 ff ff af 00 ff af 5f ff af 87 ff af af # 0x000002fa
+ff af d7 ff af ff ff d7 00 ff d7 5f ff d7 87 ff # 0x0000030a
+d7 af ff d7 d7 ff d7 ff ff ff 00 ff ff 5f ff ff # 0x0000031a
+87 ff ff af ff ff d7 ff ff ff 08 08 08 12 12 12 # 0x0000032a
+1c 1c 1c 26 26 26 30 30 30 3a 3a 3a 44 44 44 4e # 0x0000033a
+4e 4e 58 58 58 62 62 62 6c 6c 6c 76 76 76 80 80 # 0x0000034a
+80 8a 8a 8a 94 94 94 9e 9e 9e a8 a8 a8 b2 b2 b2 # 0x0000035a
+bc bc bc c6 c6 c6 d0 d0 d0 da da da e4 e4 e4 ee # 0x0000036a
+ee ee 80 00 00 00 00 00 00 00 00 00 00 00 00 00 # 0x0000037a
+00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 # 0x0000038a
+00 00 01 02 03 14 00 00 00 66 69 6c 65 3a 2f 2f # 0x0000039a
+2f 74 6d 70 2f 73 6e 61 70 73 68 6f 74 11 00 00 # 0x000003aa
+00 63 6f 6d 70 6c 65 74 65 20 73 6e 61 70 73 68 # 0x000003ba
+6f 74 # 0x000003ca
+
+# offset 0x000003cc: screen record, payload 54 bytes
+02 00 36 00 00 00 67 31 0e c6 00 00 01 00 04 00 # 0x000003cc
+00 00 00 00 00 00 00 00 00 00 01 00 00 00 00 00 # 0x000003dc
+00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 # 0x000003ec
+00 08 00 00 00 00 00 00 00 00 00 00 00 00 00 00 # 0x000003fc
+
+# offset 0x0000040c: page record, payload 36 bytes
+03 00 24 00 00 00 a2 4f 26 d1 02 00 03 00 00 00 # 0x0000040c
+00 00 10 00 c0 00 00 04 00 00 00 08 00 00 00 01 # 0x0000041c
+00 43 00 01 00 44 00 01 00 45 00 00 00 00 # 0x0000042c
+
+# offset 0x0000043a: screen record, payload 54 bytes
+02 00 36 00 00 00 ce 1f 9f 08 01 00 01 00 00 00 # 0x0000043a
+00 00 00 00 00 00 01 00 02 00 01 00 00 00 00 00 # 0x0000044a
+00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 # 0x0000045a
+00 08 00 00 00 00 00 00 00 00 00 00 00 00 00 00 # 0x0000046a
+
+# offset 0x0000047a: page record, payload 38 bytes
+03 00 26 00 00 00 62 1c ab 7b 02 00 03 00 00 00 # 0x0000047a
+00 00 80 00 c0 00 00 02 00 00 00 08 00 00 03 02 # 0x0000048a
+00 72 6e 03 02 00 61 74 02 01 00 65 00 00 00 00 # 0x0000049a
+
+# offset 0x000004aa: continuation record, payload 0 bytes
+07 00 00 00 00 00 27 80 63 d1 # 0x000004aa
+
+# offset 0x000004b4: ready record, payload 0 bytes
+05 00 00 00 00 00 e4 20 ef 0a # 0x000004b4
+
+# offset 0x000004be: history record, payload 6 bytes
+04 00 06 00 00 00 20 32 ed e1 00 00 02 00 00 00 # 0x000004be
+
+# offset 0x000004ce: page record, payload 31 bytes
+03 00 1f 00 00 00 4a ed 2f c2 02 00 02 00 00 00 # 0x000004ce
+00 00 10 00 c0 00 00 04 00 00 00 08 00 00 00 01 # 0x000004de
+00 42 00 00 00 00 00 00 00 # 0x000004ee
+
+# offset 0x000004f7: page record, payload 31 bytes
+03 00 1f 00 00 00 23 6a 6b 19 02 00 02 00 00 00 # 0x000004f7
+00 00 10 00 c0 00 00 04 00 00 00 08 00 00 00 01 # 0x00000507
+00 41 00 00 00 00 00 00 00 # 0x00000517
+
+# offset 0x00000520: history record, payload 6 bytes
+04 00 06 00 00 00 b8 7a ba b1 01 00 00 00 00 00 # 0x00000520
+
+# offset 0x00000530: finish record, payload 0 bytes
+06 00 00 00 00 00 3e eb 53 3e # 0x00000530
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-apc-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-apc-v1.hex
new file mode 100644
index 00000000..4e3054bb
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-apc-v1.hex
@@ -0,0 +1,8 @@
+# Ghostty snapshot fixture
+# Kaitai type: continuation_record
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+
+# Incomplete Kitty APC payload.
+07 00 07 00 00 00 bd ff a8 ff 1b 5f 47 64 61 74 61
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-csi-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-csi-v1.hex
new file mode 100644
index 00000000..b83aceca
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-csi-v1.hex
@@ -0,0 +1,8 @@
+# Ghostty snapshot fixture
+# Kaitai type: continuation_record
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+
+# Incomplete SGR CSI.
+07 00 04 00 00 00 30 d5 20 17 1b 5b 33 31
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-dcs-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-dcs-v1.hex
new file mode 100644
index 00000000..e8e3ebda
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-dcs-v1.hex
@@ -0,0 +1,8 @@
+# Ghostty snapshot fixture
+# Kaitai type: continuation_record
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+
+# Incomplete supported DCS payload.
+07 00 07 00 00 00 63 ae 0a 1d 1b 50 71 64 61 74 61
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-esc-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-esc-v1.hex
new file mode 100644
index 00000000..0ca1d5b1
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-esc-v1.hex
@@ -0,0 +1,8 @@
+# Ghostty snapshot fixture
+# Kaitai type: continuation_record
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+
+# Bare ESC leaves the VT parser unfinished.
+07 00 01 00 00 00 1c d9 1d 17 1b
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-ground-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-ground-v1.hex
new file mode 100644
index 00000000..42463c35
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-ground-v1.hex
@@ -0,0 +1,8 @@
+# Ghostty snapshot fixture
+# Kaitai type: continuation_record
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+
+# Empty payload is the explicit ground-state assertion.
+07 00 00 00 00 00 27 80 63 d1
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-osc-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-osc-v1.hex
new file mode 100644
index 00000000..10d6aef4
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-osc-v1.hex
@@ -0,0 +1,8 @@
+# Ghostty snapshot fixture
+# Kaitai type: continuation_record
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+
+# Incomplete title OSC.
+07 00 09 00 00 00 39 7d 6e 08 1b 5d 32 3b 74 69 74 6c 65
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-utf8-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-utf8-v1.hex
new file mode 100644
index 00000000..dc07c803
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/continuation-utf8-v1.hex
@@ -0,0 +1,8 @@
+# Ghostty snapshot fixture
+# Kaitai type: continuation_record
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+
+# Partial four-byte UTF-8 codepoint.
+07 00 03 00 00 00 b8 07 2a 22 f0 9f 98
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/envelope-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/envelope-v1.hex
new file mode 100644
index 00000000..04a7eb6d
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/envelope-v1.hex
@@ -0,0 +1,10 @@
+# Ghostty snapshot fixture
+# Kaitai type: envelope
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+47 48 4f 53 54 53 4e 50 01 00 # 0x00000000
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/grid-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/grid-v1.hex
new file mode 100644
index 00000000..b9a74af3
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/grid-v1.hex
@@ -0,0 +1,15 @@
+# Ghostty snapshot fixture
+# Kaitai type: grid
+# Kaitai params: 4 3
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+34 03 00 04 01 00 00 00 94 00 00 00 00 00 00 00 # 0x00000000
+48 00 00 e1 01 00 00 00 00 00 00 3b 03 00 1e 00 # 0x00000010
+00 00 00 00 00 00 ab ee 32 03 00 10 00 00 00 00 # 0x00000020
+00 00 00 0c 00 00 00 03 00 68 00 69 10 02 00 16 # 0x00000030
+04 21 00 01 00 00 00 00 00 02 00 02 00 01 03 00 # 0x00000040
+00 02 03 00 00 # 0x00000050
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/history-header-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/history-header-v1.hex
new file mode 100644
index 00000000..dc8333e5
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/history-header-v1.hex
@@ -0,0 +1,10 @@
+# Ghostty snapshot fixture
+# Kaitai type: history_payload
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+01 00 04 03 02 01 # 0x00000000
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/hyperlink-explicit-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/hyperlink-explicit-v1.hex
new file mode 100644
index 00000000..7643b203
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/hyperlink-explicit-v1.hex
@@ -0,0 +1,10 @@
+# Ghostty snapshot fixture
+# Kaitai type: hyperlink
+# Kaitai params: false false
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+02 02 00 00 00 69 64 03 00 00 00 75 72 69 # 0x00000000
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/hyperlink-implicit-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/hyperlink-implicit-v1.hex
new file mode 100644
index 00000000..cb15cf12
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/hyperlink-implicit-v1.hex
@@ -0,0 +1,10 @@
+# Ghostty snapshot fixture
+# Kaitai type: hyperlink
+# Kaitai params: false false
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+01 04 03 02 01 03 00 00 00 75 72 69 # 0x00000000
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/page-empty-record-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/page-empty-record-v1.hex
new file mode 100644
index 00000000..cda4f1d9
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/page-empty-record-v1.hex
@@ -0,0 +1,12 @@
+# Ghostty snapshot fixture
+# Kaitai type: page_record
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+03 00 1b 00 00 00 5e 0d 0a d4 01 00 01 00 00 00 # 0x00000000
+00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 # 0x00000010
+00 00 00 00 00 # 0x00000020
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/page-header-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/page-header-v1.hex
new file mode 100644
index 00000000..b7b00765
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/page-header-v1.hex
@@ -0,0 +1,11 @@
+# Ghostty snapshot fixture
+# Kaitai type: page_header
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+02 01 04 03 06 05 08 07 0a 09 0c 0b 10 0f 0e 0d # 0x00000000
+14 13 12 11 # 0x00000010
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/page-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/page-v1.hex
new file mode 100644
index 00000000..78018ebb
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/page-v1.hex
@@ -0,0 +1,22 @@
+# Ghostty snapshot fixture
+# Kaitai type: page_payload
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: PAGE header
+03 00 02 00 02 00 02 00 08 00 00 02 80 00 00 00 # 0x00000000
+00 01 00 00 # 0x00000010
+
+# offset 0x00000014: style and hyperlink tables, rows, and cells
+01 00 00 00 00 00 00 00 00 00 00 00 00 00 01 00 # 0x00000014
+00 00 03 00 00 00 00 00 01 2a 00 00 00 00 00 00 # 0x00000024
+00 00 00 00 01 00 02 01 00 00 00 61 05 00 00 00 # 0x00000034
+61 6c 70 68 61 03 00 01 04 03 02 01 04 00 00 00 # 0x00000044
+62 65 74 61 34 03 00 04 01 00 04 00 b4 01 00 00 # 0x00000054
+00 00 0c 00 68 03 00 1e 00 00 04 00 20 01 00 3b # 0x00000064
+03 00 e1 01 00 00 00 00 00 00 ab ee 32 03 00 10 # 0x00000074
+00 00 00 00 00 00 00 0c 00 00 01 00 00 00 01 00 # 0x00000084
+00 00 02 00 01 03 00 00 02 03 00 00 # 0x00000094
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/record-page-header-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/record-page-header-v1.hex
new file mode 100644
index 00000000..28e6269a
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/record-page-header-v1.hex
@@ -0,0 +1,10 @@
+# Ghostty snapshot fixture
+# Kaitai type: record_header
+# Kaitai params: 3
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+03 00 18 00 00 00 1b 44 78 71 # 0x00000000
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/screen-header-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/screen-header-v1.hex
new file mode 100644
index 00000000..7a29df76
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/screen-header-v1.hex
@@ -0,0 +1,13 @@
+# Ghostty snapshot fixture
+# Kaitai type: screen_header
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+01 00 03 02 08 07 06 05 04 03 02 01 05 04 07 06 # 0x00000000
+03 19 00 00 00 00 01 7f 00 00 02 12 34 56 ff 03 # 0x00000010
+00 00 0d 0c 0b 0a e4 3d 02 07 01 02 04 08 10 1f # 0x00000020
+00 11 02 03 01 # 0x00000030
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/screen-saved-cursor-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/screen-saved-cursor-v1.hex
new file mode 100644
index 00000000..f4bd7e3a
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/screen-saved-cursor-v1.hex
@@ -0,0 +1,11 @@
+# Ghostty snapshot fixture
+# Kaitai type: saved_cursor
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+02 01 04 03 00 00 00 00 00 00 00 00 00 00 00 00 # 0x00000000
+00 00 00 00 07 e4 3d # 0x00000010
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/style-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/style-v1.hex
new file mode 100644
index 00000000..0e834f87
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/style-v1.hex
@@ -0,0 +1,10 @@
+# Ghostty snapshot fixture
+# Kaitai type: style
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+00 00 00 00 01 7f 00 00 02 12 34 56 ff 03 00 00 # 0x00000000
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/testdata/terminal-header-v1.hex b/vendor/libghostty-vt/src/terminal/snapshot/testdata/terminal-header-v1.hex
new file mode 100644
index 00000000..9c9eb4bf
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/testdata/terminal-header-v1.hex
@@ -0,0 +1,16 @@
+# Ghostty snapshot fixture
+# Kaitai type: terminal_header
+# Kaitai params:
+# Kaitai offset: 0
+# Wire version: 1
+# Generated by its snapshot test; review before replacing.
+# On mismatch, the candidate is copied to the repository root.
+
+# offset 0x00000000: encoded bytes
+02 01 04 03 08 07 06 05 0c 0b 0a 09 01 00 02 00 # 0x00000000
+03 00 04 00 01 01 00 02 00 41 00 00 00 01 03 02 # 0x00000010
+02 01 04 04 01 21 01 01 00 00 00 00 00 00 00 00 # 0x00000020
+00 00 00 00 02 00 00 01 00 00 00 00 02 00 00 01 # 0x00000030
+01 02 03 00 00 00 00 00 00 00 00 01 04 05 06 01 # 0x00000040
+07 08 09 01 0a 0b 0c ff ff ff ff ff ff ff ff 08 # 0x00000050
+07 06 05 04 03 02 01 # 0x00000060
diff --git a/vendor/libghostty-vt/src/terminal/snapshot/verify-kaitai.py b/vendor/libghostty-vt/src/terminal/snapshot/verify-kaitai.py
new file mode 100755
index 00000000..65df64c9
--- /dev/null
+++ b/vendor/libghostty-vt/src/terminal/snapshot/verify-kaitai.py
@@ -0,0 +1,400 @@
+#!/usr/bin/env python3
+"""Compile the snapshot Kaitai schema and parse every checked-in fixture.
+
+Run this from a Ghostty development shell:
+
+ src/terminal/snapshot/verify-kaitai.py
+
+To turn an annotated fixture into a binary suitable for the Kaitai Web IDE:
+
+ src/terminal/snapshot/verify-kaitai.py \
+ --write-binary \
+ src/terminal/snapshot/testdata/complete-v1.hex \
+ /tmp/complete-v1.bin
+
+Then load `snapshot.ksy` and the generated binary into
+https://ide.kaitai.io/.
+
+The generated Python parser exists only in a temporary directory. This keeps
+snapshot.ksy as the source of truth and ensures this check cannot accidentally
+pass against stale generated code. After structural parsing, the script checks
+record CRC32C values and cross-record invariants that portable Kaitai
+expressions cannot represent.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import io
+import shutil
+import struct
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+try:
+ from kaitaistruct import KaitaiStream
+except ImportError as error:
+ raise SystemExit(
+ "missing Kaitai verifier dependencies; run this inside "
+ "`nix develop`"
+ ) from error
+
+
+SNAPSHOT_DIR = Path(__file__).resolve().parent
+SCHEMA_PATH = SNAPSHOT_DIR / "snapshot.ksy"
+TESTDATA_DIR = SNAPSHOT_DIR / "testdata"
+SNAPSHOT_ENVELOPE_SIZE = 10
+RECORD_HEADER_SIZE = struct.calcsize("<HII")
+
+
+@dataclass(frozen=True)
+class Fixture:
+ path: Path
+ type_name: str
+ params: tuple[object, ...]
+ offset: int
+ data: bytes
+
+
+def load_fixture(path: Path) -> Fixture:
+ """Load one self-describing annotated hexadecimal fixture."""
+ metadata: dict[str, str] = {}
+ chunks: list[str] = []
+ for line in path.read_text(encoding="utf-8").splitlines():
+ content, separator, comment = line.partition("#")
+ chunks.extend(content.split())
+
+ if not separator:
+ continue
+ comment = comment.strip()
+ if not comment.startswith("Kaitai "):
+ continue
+ key, colon, value = comment.removeprefix("Kaitai ").partition(":")
+ if not colon or key not in {"type", "params", "offset"}:
+ raise ValueError(f"{path}: invalid Kaitai metadata: {comment}")
+ if key in metadata:
+ raise ValueError(f"{path}: duplicate Kaitai {key} metadata")
+ metadata[key] = value.strip()
+
+ try:
+ data = bytes.fromhex(" ".join(chunks))
+ except ValueError as error:
+ raise ValueError(f"{path}: invalid annotated hexadecimal") from error
+
+ required = {"type", "params", "offset"}
+ if metadata.keys() != required:
+ missing = sorted(required - metadata.keys())
+ extra = sorted(metadata.keys() - required)
+ raise ValueError(
+ f"{path}: Kaitai metadata drift: missing={missing}, extra={extra}"
+ )
+ if not metadata["type"]:
+ raise ValueError(f"{path}: empty Kaitai type")
+
+ params: list[object] = []
+ for value in metadata["params"].split():
+ if value == "true":
+ params.append(True)
+ elif value == "false":
+ params.append(False)
+ else:
+ try:
+ params.append(int(value, 0))
+ except ValueError as error:
+ raise ValueError(
+ f"{path}: invalid Kaitai parameter {value!r}"
+ ) from error
+
+ try:
+ offset = int(metadata["offset"], 0)
+ except ValueError as error:
+ raise ValueError(f"{path}: invalid Kaitai offset") from error
+ if offset < 0 or offset > len(data):
+ raise ValueError(f"{path}: Kaitai offset is outside the fixture")
+
+ return Fixture(
+ path=path,
+ type_name=metadata["type"],
+ params=tuple(params),
+ offset=offset,
+ data=data,
+ )
+
+
+def parse_type(
+ parser_type: type[Any],
+ data: bytes,
+ *params: object,
+) -> Any:
+ """Construct one generated Kaitai type and require exact exhaustion."""
+ stream = KaitaiStream(io.BytesIO(data))
+ result = parser_type(*params, stream)
+ if not stream.is_eof():
+ raise ValueError(
+ f"{parser_type.__name__} left "
+ f"{stream.size() - stream.pos()} trailing bytes"
+ )
+ return result
+
+
+def crc32c(data: bytes) -> int:
+ """Return CRC32C using the reflected Castagnoli polynomial."""
+ result = 0xFFFFFFFF
+ for byte in data:
+ result ^= byte
+ for _ in range(8):
+ result = (
+ (result >> 1) ^ 0x82F63B78
+ if result & 1
+ else result >> 1
+ )
+ return result ^ 0xFFFFFFFF
+
+
+def validate_record(record: Any, data: bytes, offset: int) -> int:
+ """Validate one parsed record's source bytes and CRC32C."""
+ payload = getattr(record, "_raw_payload", record.payload)
+ header = record.header
+ if header.payload_length != len(payload):
+ raise ValueError(
+ f"record at 0x{offset:x}: declared {header.payload_length} "
+ f"payload bytes but parsed {len(payload)}"
+ )
+
+ encoded_header = data[offset : offset + RECORD_HEADER_SIZE]
+ expected_header = struct.pack(
+ "<HII",
+ header.tag,
+ header.payload_length,
+ header.crc32c,
+ )
+ if encoded_header != expected_header:
+ raise ValueError(f"record at 0x{offset:x}: parsed header drift")
+
+ covered = struct.pack("<HI", header.tag, header.payload_length) + payload
+ actual_crc = crc32c(covered)
+ if header.crc32c != actual_crc:
+ raise ValueError(
+ f"record at 0x{offset:x}: CRC32C 0x{header.crc32c:08x} "
+ f"does not match 0x{actual_crc:08x}"
+ )
+
+ return offset + RECORD_HEADER_SIZE + len(payload)
+
+
+def all_snapshot_records(snapshot: Any) -> list[Any]:
+ """Return complete-snapshot records in wire order."""
+ records = [snapshot.terminal]
+ for sequence in snapshot.screens:
+ records.append(sequence.screen)
+ records.extend(sequence.pages)
+ records.append(snapshot.continuation)
+ records.append(snapshot.ready)
+ for sequence in snapshot.histories:
+ records.append(sequence.history)
+ records.extend(sequence.pages)
+ records.append(snapshot.finish)
+ return records
+
+
+def validate_complete_snapshot(snapshot: Any, data: bytes) -> None:
+ """Validate ordering relationships, record CRCs, and markers."""
+ screen_keys = [
+ sequence.screen.payload.header.key for sequence in snapshot.screens
+ ]
+ history_keys = [
+ sequence.history.payload.key for sequence in snapshot.histories
+ ]
+ if len(set(screen_keys)) != len(screen_keys):
+ raise ValueError("complete snapshot contains a duplicate SCREEN key")
+ if len(set(history_keys)) != len(history_keys):
+ raise ValueError("complete snapshot contains a duplicate HISTORY key")
+ if set(screen_keys) != set(history_keys):
+ raise ValueError("SCREEN and HISTORY keys do not match")
+
+ terminal_header = snapshot.terminal.payload.header
+ expected_key_values = (
+ {0} if terminal_header.screen_count == 1 else {0, 1}
+ )
+ screen_key_values = {key.value for key in screen_keys}
+ if screen_key_values != expected_key_values:
+ raise ValueError(
+ f"TERMINAL declares screen keys {expected_key_values}, "
+ f"but SCREEN records contain {screen_key_values}"
+ )
+
+ screens_by_key = {
+ sequence.screen.payload.header.key: sequence
+ for sequence in snapshot.screens
+ }
+ for sequence in snapshot.screens:
+ header = sequence.screen.payload.header
+ if (
+ header.cursor_x >= terminal_header.columns
+ or header.cursor_y >= terminal_header.rows
+ or (
+ header.cursor_flags.pending_wrap
+ and header.cursor_x != terminal_header.columns - 1
+ )
+ ):
+ raise ValueError(f"SCREEN key {header.key}: invalid cursor position")
+
+ for sequence in snapshot.histories:
+ payload = sequence.history.payload
+ screen = screens_by_key[payload.key]
+ screen_rows = sum(
+ page.payload.header.rows for page in screen.pages
+ )
+ if screen_rows < terminal_header.rows:
+ raise ValueError(
+ f"SCREEN key {payload.key}: PAGE rows do not cover "
+ "the active area"
+ )
+ overlap_rows = screen_rows - terminal_header.rows
+ history_rows = overlap_rows + sum(
+ page.payload.header.rows for page in sequence.pages
+ )
+ if history_rows != screen.screen.payload.header.history_rows:
+ raise ValueError(
+ f"SCREEN key {payload.key}: history_rows "
+ f"{screen.screen.payload.header.history_rows} "
+ f"does not match {history_rows}"
+ )
+
+ for record in all_snapshot_records(snapshot):
+ if not hasattr(record, "payload"):
+ continue
+ payload = record.payload
+ if not hasattr(payload, "styles"):
+ continue
+ style_ids = [entry.encoded_id for entry in payload.styles]
+ hyperlink_ids = [entry.encoded_id for entry in payload.hyperlinks]
+ if len(set(style_ids)) != len(style_ids):
+ raise ValueError("PAGE contains a duplicate style ID")
+ if len(set(hyperlink_ids)) != len(hyperlink_ids):
+ raise ValueError("PAGE contains a duplicate hyperlink ID")
+
+ offset = SNAPSHOT_ENVELOPE_SIZE
+ for record in all_snapshot_records(snapshot):
+ offset = validate_record(record, data, offset)
+
+ if offset != len(data):
+ raise ValueError(
+ f"complete snapshot accounted for {offset} of {len(data)} bytes"
+ )
+
+
+def compile_schema(output_dir: Path) -> type[Any]:
+ """Compile snapshot.ksy and import its temporary Python parser."""
+ compiler = shutil.which("kaitai-struct-compiler") or shutil.which("ksc")
+ if compiler is None:
+ raise SystemExit(
+ "kaitai-struct-compiler is not available; run this inside "
+ "`nix develop`"
+ )
+
+ subprocess.run(
+ [
+ compiler,
+ "--target=python",
+ f"--outdir={output_dir}",
+ str(SCHEMA_PATH),
+ ],
+ check=True,
+ )
+
+ sys.path.insert(0, str(output_dir))
+ try:
+ module = importlib.import_module("ghostty_snapshot")
+ finally:
+ sys.path.pop(0)
+ return module.GhosttySnapshot
+
+
+def resolve_type(parser: type[Any], type_name: str) -> type[Any]:
+ """Resolve one KSY snake-case type name on the generated parser."""
+ root_type_name = "".join(
+ f"_{character.lower()}" if character.isupper() else character
+ for character in parser.__name__
+ ).lstrip("_")
+ if type_name == root_type_name:
+ return parser
+
+ class_name = "".join(
+ part[:1].upper() + part[1:] for part in type_name.split("_")
+ )
+ try:
+ return getattr(parser, class_name)
+ except AttributeError as error:
+ raise ValueError(f"snapshot.ksy has no type {type_name!r}") from error
+
+
+def main() -> int:
+ cli = argparse.ArgumentParser(description=__doc__)
+ cli.add_argument(
+ "--write-binary",
+ nargs=2,
+ metavar=("FIXTURE", "OUTPUT"),
+ type=Path,
+ help="decode one annotated fixture into a raw binary",
+ )
+ args = cli.parse_args()
+
+ if args.write_binary:
+ fixture_path, output_path = args.write_binary
+ fixture = load_fixture(fixture_path)
+ output_path.write_bytes(fixture.data)
+ print(f"wrote {len(fixture.data)} bytes to {output_path}")
+ return 0
+
+ with tempfile.TemporaryDirectory(prefix="ghostty-kaitai-") as temp:
+ parser = compile_schema(Path(temp))
+
+ fixture_paths = sorted(TESTDATA_DIR.rglob("*.hex"))
+ if not fixture_paths:
+ raise ValueError(f"{TESTDATA_DIR}: no snapshot fixtures")
+
+ for path in fixture_paths:
+ fixture = load_fixture(path)
+ parser_type = resolve_type(parser, fixture.type_name)
+ fixture_label = path.relative_to(TESTDATA_DIR)
+ try:
+ parsed = parse_type(
+ parser_type,
+ fixture.data[fixture.offset:],
+ *fixture.params,
+ )
+ except Exception as error:
+ raise ValueError(
+ f"{fixture_label}: Kaitai parse failed"
+ ) from error
+
+ if parser_type is parser:
+ if fixture.offset != 0:
+ raise ValueError(
+ f"{fixture_label}: root parser must begin at offset zero"
+ )
+ validate_complete_snapshot(parsed, fixture.data)
+ elif hasattr(parsed, "_raw_payload"):
+ record_end = validate_record(
+ parsed,
+ fixture.data,
+ fixture.offset,
+ )
+ if record_end != len(fixture.data):
+ raise ValueError(
+ f"{fixture_label}: record has trailing data"
+ )
+ print(f"ok {fixture_label}")
+
+ print(f"validated {len(fixture_paths)} snapshot fixtures")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())