aboutsummaryrefslogtreecommitdiff
path: root/vendor/libghostty-vt/src/terminal/snapshot/grid.zig
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/grid.zig
parent90e947a6e26e02f10ec7f1694c4eb5b78a86406b (diff)
chore: upgrade libghostty and preserve terminal behavior (#3906)
Diffstat (limited to 'vendor/libghostty-vt/src/terminal/snapshot/grid.zig')
-rw-r--r--vendor/libghostty-vt/src/terminal/snapshot/grid.zig2403
1 files changed, 2403 insertions, 0 deletions
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);
+}