6c3ecd04

feat: the CellRow codec, a grid row as runs of styled cells

a73x 2026-09-04 16:59

Commit message

feat: the CellRow codec, a grid row as runs of styled cells

One grid row on the wire as runs of styled cells, so a client can copy
cells into a grid instead of parsing VT. Nothing sends or reads these
yet; the daemon encoder and the client grid come next.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CsWfuJFQbTfGtKZLS5qw4q

src/engine/protocol.zig

+    return .{ .rest = payload[@min(payload.len, delta_header_len)..] };
+// ---------------------------------------------------------------------------
+// CellRow: one grid row as runs of styled cells. The client copies these into
+// a grid and never parses VT; the daemon's ghostty is the only parser left.
+// A row ends at the last cell that is not a default-style blank, and the
+// reader's caller fills the rest of the width with blanks.
+pub const Wide = enum(u2) { narrow = 0, wide = 1, spacer_tail = 2, spacer_head = 3 };
+pub const color_none: u32 = 0;
+pub fn colorPalette(index: u8) u32 {
+    return (1 << 24) | @as(u32, index);
+}
+pub fn colorRgb(r: u8, g: u8, b: u8) u32 {
+    return (2 << 24) | (@as(u32, r) << 16) | (@as(u32, g) << 8) | @as(u32, b);
+}
+pub const CellStyle = struct {
+    fg: u32 = color_none,
+    bg: u32 = color_none,
+    ul: u32 = color_none,
+    /// ghostty Style.Flags bit order: bold 0, italic 1, faint 2, blink 3,
+    /// inverse 4, invisible 5, strikethrough 6, overline 7, underline 8-10.
+    flags: u16 = 0,
+    pub fn eql(a: CellStyle, b: CellStyle) bool {
+        return a.fg == b.fg and a.bg == b.bg and a.ul == b.ul and a.flags == b.flags;
+    }
+    pub fn isDefault(self: CellStyle) bool {
+        return self.eql(.{});
+    }
+};
+/// Run flag bit: every cell in the run is one byte 0x20..0x7E, narrow, and
+/// carries no head byte. Dense text is what a wire pays for most.
+pub const run_ascii: u16 = 1 << 15;
+pub const run_header_len = 16;
+pub const cell_row_prefix_len = 2;
+pub const cell_text_max = 63;
+pub const DecodedCell = struct { style: CellStyle, wide: Wide, text: []const u8 };
+fn asciiCell(wide: Wide, text: []const u8) bool {
+    return wide == .narrow and text.len == 1 and text[0] >= 0x20 and text[0] <= 0x7E;
+}
+pub const CellRowWriter = struct {
+    list: *std.ArrayList(u8),
+    alloc: std.mem.Allocator,
+    prefix_at: usize,
+    ncells: u16 = 0,
+    /// The open run's cells, held back until the run closes so the ascii
+    /// decision is made over the whole run.
+    run: std.ArrayListUnmanaged(DecodedCell) = .empty,
+    run_style: CellStyle = .{},
+    pub fn begin(list: *std.ArrayList(u8), alloc: std.mem.Allocator) !CellRowWriter {
+        const at = list.items.len;
+        try list.appendSlice(alloc, &[_]u8{ 0, 0 });
+        return .{ .list = list, .alloc = alloc, .prefix_at = at };
+    }
+    pub fn cell(self: *CellRowWriter, style: CellStyle, wide: Wide, text: []const u8) !void {
+        std.debug.assert(text.len <= cell_text_max);
+        if (self.run.items.len > 0 and !style.eql(self.run_style)) try self.flush();
+        if (self.run.items.len == 0) self.run_style = style;
+        try self.run.append(self.alloc, .{ .style = style, .wide = wide, .text = text });
+        self.ncells += 1;
+    }
+    fn flush(self: *CellRowWriter) !void {
+        const cells = self.run.items;
+        if (cells.len == 0) return;
+        var ascii = true;
+        for (cells) |c| {
+            if (!asciiCell(c.wide, c.text)) {
+                ascii = false;
+                break;
+            }
+        }
+        var hdr: [run_header_len]u8 = undefined;
+        std.mem.writeInt(u16, hdr[0..2], @intCast(cells.len), .little);
+        std.mem.writeInt(u16, hdr[2..4], self.run_style.flags | (if (ascii) run_ascii else 0), .little);
+        std.mem.writeInt(u32, hdr[4..8], self.run_style.fg, .little);
+        std.mem.writeInt(u32, hdr[8..12], self.run_style.bg, .little);
+        std.mem.writeInt(u32, hdr[12..16], self.run_style.ul, .little);
+        try self.list.appendSlice(self.alloc, &hdr);
+        for (cells) |c| {
+            if (ascii) {
+                try self.list.append(self.alloc, c.text[0]);
+            } else {
+                const head: u8 = (@as(u8, @intFromEnum(c.wide)) << 6) | @as(u8, @intCast(c.text.len));
+                try self.list.append(self.alloc, head);
+                try self.list.appendSlice(self.alloc, c.text);
+            }
+        }
+        self.run.clearRetainingCapacity();
+    }
+    /// Closes the open run and stamps ncells. The writer is spent after this.
+    pub fn finish(self: *CellRowWriter) void {
+        self.flush() catch |e| switch (e) {
+            error.OutOfMemory => @panic("CellRowWriter.finish: out of memory"),
+        };
+        std.mem.writeInt(u16, self.list.items[self.prefix_at..][0..2], self.ncells, .little);
+        self.run.deinit(self.alloc);
+    }
+};
+pub const CellRowReader = struct {
+    rest: []const u8,
+    ncells: u16,
+    read: u16 = 0,
+    run_left: u16 = 0,
+    run_style: CellStyle = .{},
+    run_ascii: bool = false,
+    pub fn init(bytes: []const u8) !CellRowReader {
+        if (bytes.len < cell_row_prefix_len) return error.BadPayload;
+        return .{
+            .rest = bytes[cell_row_prefix_len..],
+            .ncells = std.mem.readInt(u16, bytes[0..2], .little),
+        };
+    }
+    pub fn next(self: *CellRowReader) !?DecodedCell {
+        if (self.read == self.ncells) return null;
+        if (self.run_left == 0) {
+            if (self.rest.len < run_header_len) return error.BadPayload;
+            const count = std.mem.readInt(u16, self.rest[0..2], .little);
+            const flags = std.mem.readInt(u16, self.rest[2..4], .little);
+            // A run may not claim cells the row does not have.
+            if (count == 0 or count > self.ncells - self.read) return error.BadPayload;
+            self.run_left = count;
+            self.run_ascii = flags & run_ascii != 0;
+            self.run_style = .{
+                .flags = flags & ~run_ascii,
+                .fg = std.mem.readInt(u32, self.rest[4..8], .little),
+                .bg = std.mem.readInt(u32, self.rest[8..12], .little),
+                .ul = std.mem.readInt(u32, self.rest[12..16], .little),
+            };
+            self.rest = self.rest[run_header_len..];
+        }
+        self.run_left -= 1;
+        self.read += 1;
+        if (self.run_ascii) {
+            if (self.rest.len < 1) return error.BadPayload;
+            const text = self.rest[0..1];
+            self.rest = self.rest[1..];
+            return .{ .style = self.run_style, .wide = .narrow, .text = text };
+        }
+        if (self.rest.len < 1) return error.BadPayload;
+        const head = self.rest[0];
+        const len: usize = head & 0x3f;
+        if (self.rest.len < 1 + len) return error.BadPayload;
+        const text = self.rest[1 .. 1 + len];
+        self.rest = self.rest[1 + len ..];
+        return .{ .style = self.run_style, .wide = @enumFromInt(head >> 6), .text = text };
+    }
+    /// The bytes after this row — the next row of a dense run, or nothing.
+    pub fn remaining(self: *const CellRowReader) []const u8 {
+        return self.rest;
+    }
+};
+pub const ComposedDelta = struct { header: DeltaHeader, bytes: []u8 };
+/// Turn a delta payload into the VT byte string that applies it: per row, CUP
+    try std.testing.expectEqual(MsgType.sessions_reply, got.type);
+    try std.testing.expectEqualStrings(payload, got.payload);
+test "cellrow: two default ascii cells are one ascii run" {
+    const alloc = std.testing.allocator;
+    var list: std.ArrayList(u8) = .empty;
+    defer list.deinit(alloc);
+    var w = try CellRowWriter.begin(&list, alloc);
+    try w.cell(.{}, .narrow, "a");
+    try w.cell(.{}, .narrow, "b");
+    w.finish();
+    // ncells=2; run: count=2, flags=ascii, fg=bg=ul=0; then "ab".
+    try std.testing.expectEqualSlices(u8, &[_]u8{
+, 0, // ncells
+,   0,   0x00, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // run header
+        'a', 'b',
+    }, list.items);
+}
+test "cellrow: a wide glyph and its spacer, a grapheme, and a styled run round-trip" {
+    const alloc = std.testing.allocator;
+    var list: std.ArrayList(u8) = .empty;
+    defer list.deinit(alloc);
+    const red: CellStyle = .{ .fg = colorPalette(1), .flags = 1 }; // bold red
+    var w = try CellRowWriter.begin(&list, alloc);
+    try w.cell(.{}, .wide, "漢");
+    try w.cell(.{}, .spacer_tail, "");
+    try w.cell(.{}, .narrow, "e\u{301}");
+    try w.cell(red, .narrow, "x");
+    try w.cell(red, .narrow, "");
+    w.finish();
+    var r = try CellRowReader.init(list.items);
+    try std.testing.expectEqual(@as(u16, 5), r.ncells);
+    const c0 = (try r.next()).?;
+    try std.testing.expectEqual(Wide.wide, c0.wide);
+    try std.testing.expectEqualStrings("漢", c0.text);
+    const c1 = (try r.next()).?;
+    try std.testing.expectEqual(Wide.spacer_tail, c1.wide);
+    try std.testing.expectEqualStrings("", c1.text);
+    const c2 = (try r.next()).?;
+    try std.testing.expectEqualStrings("e\u{301}", c2.text);
+    const c3 = (try r.next()).?;
+    try std.testing.expect(c3.style.eql(red));
+    try std.testing.expectEqualStrings("x", c3.text);
+    const c4 = (try r.next()).?;
+    try std.testing.expect(c4.style.eql(red));
+    try std.testing.expectEqualStrings("", c4.text);
+    try std.testing.expectEqual(@as(?DecodedCell, null), try r.next());
+    try std.testing.expectEqual(@as(usize, 0), r.remaining().len);
+}
+test "cellrow: an ascii run is only taken when every cell qualifies" {
+    const alloc = std.testing.allocator;
+    var list: std.ArrayList(u8) = .empty;
+    defer list.deinit(alloc);
+    var w = try CellRowWriter.begin(&list, alloc);
+    try w.cell(.{}, .narrow, "a");
+    try w.cell(.{}, .narrow, "é"); // 2 bytes: breaks the ascii form for the whole run
+    w.finish();
+    // ncells=2; run: count=2, flags=0; cells: head 1 'a', head 2 0xC3 0xA9
+    try std.testing.expectEqualSlices(u8, &[_]u8{
+, 0, // ncells
+, 0,   0, 0,    0,    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // run header
+, 'a', 2, 0xC3, 0xA9,
+    }, list.items);
+}
+test "cellrow: the reader leaves the bytes after the row alone" {
+    const alloc = std.testing.allocator;
+    var list: std.ArrayList(u8) = .empty;
+    defer list.deinit(alloc);
+    var w = try CellRowWriter.begin(&list, alloc);
+    try w.cell(.{}, .narrow, "a");
+    w.finish();
+    try list.appendSlice(alloc, "tail");
+    var r = try CellRowReader.init(list.items);
+    _ = try r.next();
+    try std.testing.expectEqual(@as(?DecodedCell, null), try r.next());
+    try std.testing.expectEqualStrings("tail", r.remaining());
+}
+test "cellrow: malformed rows are BadPayload, never a read past the end" {
+    // A run that claims more cells than the row's ncells: refused at the
+    // run header, before a cell is read.
+    var over = try CellRowReader.init(&[_]u8{ 1, 0, 2, 0, 0x00, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 'a', 'b' });
+    try std.testing.expectError(error.BadPayload, over.next());
+    // A cell whose text_len runs past the payload.
+    var short_text = try CellRowReader.init(&[_]u8{ 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 5, 'a' });
+    try std.testing.expectError(error.BadPayload, short_text.next());
+    // A row shorter than its own prefix.
+    try std.testing.expectError(error.BadPayload, CellRowReader.init(&[_]u8{1}));
+    // A row that ends mid-run header.
+    var mid_header = try CellRowReader.init(&[_]u8{ 1, 0, 1, 0, 0 });
+    try std.testing.expectError(error.BadPayload, mid_header.next());
+}