terminal: glyph protocol parser and response encoder

This adds the core parse/encode for the still in-development and experimental
terminal glyph protocol: raphamorim/rio#1542

The only cross-cutting change necessary was changing the APC
identification logic which previously only looked at a single byte to
support multi-byte identifiers since the glyph protocol uses `25a1`.

Author: mitchellh

src/terminal/apc.zig

@@ -2,6 +2,7 @@ const std = @import("std");
 const build_options = @import("terminal_options");
 const Allocator = std.mem.Allocator;
 
+const glyph = @import("apc/glyph.zig");
 const kitty_gfx = @import("kitty/graphics.zig");
 
 const log = std.log.scoped(.terminal_apc);
@@ -18,6 +19,7 @@ pub const Handler = struct {
     /// use `.initFull`.
     max_bytes: std.EnumMap(Protocol, usize) = .initFullWith(.{
         .kitty = Protocol.defaultMaxBytes(.kitty),
+        .glyph = Protocol.defaultMaxBytes(.glyph),
     }),
 
     pub fn deinit(self: *Handler) void {
@@ -26,7 +28,7 @@ pub const Handler = struct {
 
     pub fn start(self: *Handler) void {
         self.state.deinit();
-        self.state = .{ .identify = {} };
+        self.state = .{ .identify = .{} };
     }
 
     pub fn feed(self: *Handler, alloc: Allocator, byte: u8) void {
@@ -38,21 +40,45 @@ pub const Handler = struct {
             .ignore => return,
 
             // We identify the APC command by the first byte.
-            .identify => {
-                switch (byte) {
-                    // Kitty graphics protocol
-                    'G' => self.state = if (comptime build_options.kitty_graphics)
-                        .{ .kitty = .init(
+            .identify => |*id| id: {
+                // Kitty graphics is detected immediately on the `G` byte,
+                // since commands begin immediately after with no termination
+                // character after the 'G'.
+                if (comptime build_options.kitty_graphics) {
+                    if (id.len == 0 and byte == 'G') {
+                        self.state = .{ .kitty = .init(
                             alloc,
                             self.max_bytes.get(.kitty) orelse
                                 Protocol.defaultMaxBytes(.kitty),
-                        ) }
-                    else
-                        .ignore,
+                        ) };
+                        break :id;
+                    }
+                }
 
-                    // Unknown
-                    else => self.state = .ignore,
+                // If we hit `;` then identify...
+                if (byte == ';') {
+                    const str = id.buf[0..id.len];
+                    if (std.mem.eql(u8, str, "25a1")) {
+                        self.state = .{ .glyph = .init(
+                            alloc,
+                            self.max_bytes.get(.glyph) orelse
+                                Protocol.defaultMaxBytes(.glyph),
+                        ) };
+                    } else {
+                        self.state = .ignore;
+                    }
+
+                    break :id;
+                }
+
+                // If we're out of space to buffer then we're done.
+                if (id.len >= id.buf.len) {
+                    self.state = .ignore;
+                    break :id;
                 }
+
+                id.buf[id.len] = byte;
+                id.len += 1;
             },
 
             .kitty => |*p| if (comptime build_options.kitty_graphics) {
@@ -62,6 +88,12 @@ pub const Handler = struct {
                     self.state = .ignore;
                 };
             } else unreachable,
+
+            .glyph => |*p| p.feed(byte) catch |err| {
+                log.warn("glyph protocol error: {}", .{err});
+                p.deinit();
+                self.state = .ignore;
+            },
         }
     }
 
@@ -86,31 +118,54 @@ pub const Handler = struct {
 
                 break :kitty .{ .kitty = command };
             },
+
+            .glyph => |*p| glyph_cmd: {
+                const command = p.complete(p.alloc) catch |err| {
+                    log.warn("glyph protocol error: {}", .{err});
+                    break :glyph_cmd null;
+                };
+
+                break :glyph_cmd .{ .glyph = command };
+            },
         };
     }
 };
 
 pub const State = union(enum) {
     /// We're not in the middle of an APC command yet.
-    inactive: void,
+    inactive,
 
     /// We got an unrecognized APC sequence or the APC sequence we
     /// recognized became invalid. We're just dropping bytes.
-    ignore: void,
-
-    /// We're waiting to identify the APC sequence. This is done by
-    /// inspecting the first byte of the sequence.
-    identify: void,
+    ignore,
+
+    /// We're waiting to identify the APC sequence. The way this is done
+    /// is pretty fluid depending on supported APC protocols, but for now
+    /// our rule is:
+    ///
+    ///  * 'G' - immediate transition to Kitty graphics protocol
+    ///  * Buffer up to `;` and the bytes before dictate the protocol.
+    ///    If we overflow then we're immediately invalid because we don't
+    ///    support anything longer than this.
+    ///
+    identify: struct {
+        len: u3 = 0,
+        buf: [4]u8 = undefined,
+    },
 
     /// Kitty graphics protocol
     kitty: if (build_options.kitty_graphics)
         kitty_gfx.CommandParser
     else
         void,
 
+    /// Glyph protocol
+    glyph: glyph.CommandParser,
+
     pub fn deinit(self: *State) void {
         switch (self.*) {
             .inactive, .ignore, .identify => {},
+            .glyph => |*v| v.deinit(),
             .kitty => |*v| if (comptime build_options.kitty_graphics)
                 v.deinit()
             else
@@ -122,13 +177,18 @@ pub const State = union(enum) {
 /// Possible APC command types.
 pub const Protocol = enum {
     kitty,
+    glyph,
 
     /// Returns the default maximum bytes for the given protocol.
     pub fn defaultMaxBytes(self: Protocol) usize {
         return switch (self) {
             // Kitty graphics payloads can be very large (e.g. full images
             // encoded as base64), so the default is set to 65 MiB.
             .kitty => 65 * 1024 * 1024,
+            // Glyph protocol messages carry single glyf outlines which
+            // are small, but base64 encoding inflates them. 1 MiB is
+            // generous for any single simple-glyph record.
+            .glyph => 1 * 1024 * 1024,
         };
     }
 };
@@ -140,12 +200,16 @@ pub const Command = union(Protocol) {
     else
         void,
 
+    glyph: glyph.Request,
+
     pub fn deinit(self: *Command, alloc: Allocator) void {
         switch (self.*) {
             .kitty => |*v| if (comptime build_options.kitty_graphics)
                 v.deinit(alloc)
             else
                 unreachable,
+
+            .glyph => |*v| v.deinit(alloc),
         }
     }
 };
@@ -246,3 +310,66 @@ test "valid Kitty command" {
     defer cmd.deinit(alloc);
     try testing.expect(cmd == .kitty);
 }
+
+test "identify with unrecognized command" {
+    const testing = std.testing;
+    const alloc = testing.allocator;
+
+    var h: Handler = .{};
+    h.start();
+    for ("abcd;payload") |c| h.feed(alloc, c);
+    try testing.expect(h.end() == null);
+}
+
+test "identify buffer overflow" {
+    const testing = std.testing;
+    const alloc = testing.allocator;
+
+    var h: Handler = .{};
+    h.start();
+    for ("abcde;payload") |c| h.feed(alloc, c);
+    try testing.expect(h.end() == null);
+}
+
+test "identify with no input" {
+    const testing = std.testing;
+
+    var h: Handler = .{};
+    h.start();
+    try testing.expect(h.end() == null);
+}
+
+test "identify with unknown partial input" {
+    const testing = std.testing;
+    const alloc = testing.allocator;
+
+    var h: Handler = .{};
+    h.start();
+    for ("25a") |c| h.feed(alloc, c);
+    try testing.expect(h.end() == null);
+}
+
+test "garbage glyph command" {
+    const testing = std.testing;
+    const alloc = testing.allocator;
+
+    var h: Handler = .{};
+    h.start();
+    for ("25a1;X") |c| h.feed(alloc, c);
+
+    try testing.expect(h.end() == null);
+}
+
+test "valid glyph command" {
+    const testing = std.testing;
+    const alloc = testing.allocator;
+
+    var h: Handler = .{};
+    h.start();
+    for ("25a1;q;cp=E0A0") |c| h.feed(alloc, c);
+
+    var cmd = h.end().?;
+    defer cmd.deinit(alloc);
+    try testing.expect(cmd == .glyph);
+    try testing.expect(cmd.glyph == .query);
+}

src/terminal/apc/glyph.zig

@@ -0,0 +1,131 @@
+//! # Glyph Protocol
+//!
+//! The Glyph Protocol lets applications register custom glyphs with the
+//! terminal at runtime and query whether a given codepoint is already
+//! covered by a system font or a prior registration. It eliminates the
+//! requirement for users to install patched fonts (e.g. Nerd Fonts) in
+//! order to render icons in TUIs.
+//!
+//! This file documents the wire protocol surface implemented by the parser
+//! and response formatter below.
+//!
+//! ## Transport
+//!
+//! Messages use APC (Application Program Command) framing.
+//! Terminals that do not implement the protocol can safely ignore APC
+//! sequences. Every message is prefixed with the identifier `25a1`
+//! (U+25A1 WHITE SQUARE — the canonical tofu symbol).
+//!
+//! ## Framing
+//!
+//! ```
+//! ESC _ 25a1 ; <verb> [ ; key=value ]* [ ; <payload> ] ESC \
+//! ```
+//!
+//! Four verbs are defined:
+//!
+//!   - `s` — support query
+//!   - `q` — codepoint query
+//!   - `r` — register a glyph
+//!   - `c` — clear registrations
+//!
+//! ## Support (`s`)
+//!
+//! Detects whether the terminal implements Glyph Protocol and which
+//! payload formats it supports.
+//!
+//! Request:   `ESC _ 25a1 ; s ESC \`
+//! Response:  `ESC _ 25a1 ; s ; fmt=<bitfield> ESC \`
+//!
+//! `fmt` bits:
+//!   - bit 0 (`1`): `glyf`   — TrueType simple glyphs (required in v1)
+//!   - bit 1 (`2`): `colrv0` — COLR v0 layered flat-colour glyphs
+//!   - bit 2 (`4`): `colrv1` — COLR v1 paint-graph glyphs
+//!
+//! Any reply confirms support; no reply within a timeout means the
+//! terminal does not implement the protocol.
+//!
+//! ## Query (`q`)
+//!
+//! Asks whether a codepoint is renderable and by whom.
+//!
+//! Request:   `ESC _ 25a1 ; q ; cp=<hex> ESC \`
+//! Response:  `ESC _ 25a1 ; q ; cp=<hex> ; status=<u8> ESC \`
+//!
+//! `status` is a two-bit field:
+//!   - `0` (`free`)     — nothing renders this codepoint (tofu)
+//!   - `1` (`system`)   — a system font covers it
+//!   - `2` (`glossary`) — a session registration covers it
+//!   - `3` (`both`)     — both; the registration shadows the system font
+//!
+//! ## Register (`r`)
+//!
+//! Registers a glyph outline at a Private Use Area codepoint.
+//!
+//! Request:
+//!   `ESC _ 25a1 ; r ; cp=<hex> [; fmt=glyf] [; upm=<int>]
+//!         [; reply=<0|1|2>] ; <base64-payload> ESC \`
+//!
+//! Response:
+//!   `ESC _ 25a1 ; r ; cp=<hex> ; status=0 ESC \`
+//!   On error: `status=<nonzero> ; reason=<code>`
+//!
+//! Parameters:
+//!   - `cp`    — target codepoint (hex). Must be in a PUA range:
+//!               U+E000–U+F8FF, U+F0000–U+FFFFD, or U+100000–U+10FFFD.
+//!               Non-PUA values are rejected with `reason=out_of_namespace`.
+//!   - `fmt`   — payload format. Default `glyf`; `colrv0` and `colrv1`
+//!               are optional and advertised via the `s` reply.
+//!   - `upm`   — units-per-em for the coordinate space. Default 1000.
+//!   - `reply` — response verbosity:
+//!               `1` (default) = success + failure replies
+//!               `2` = failure replies only (silent success)
+//!               `0` = no replies (fire-and-forget)
+//!   - payload — base64-encoded `glyf` simple-glyph record.
+//!
+//! The `glyf` subset accepted:
+//!   - Simple glyphs only (no composites).
+//!   - Standard flag encoding (on-curve, off-curve, x/y-short, repeat).
+//!   - No hinting instructions.
+//!   - Coordinates are in the `upm` space; the terminal scales to cell size.
+//!
+//! A second `r` on the same `cp` overwrites the previous registration.
+//! `glyf` outlines render in the current foreground colour.
+//!
+//! ## Clear (`c`)
+//!
+//! Removes registrations.
+//!
+//! Single slot: `ESC _ 25a1 ; c ; cp=<hex> ESC \`
+//! All slots:   `ESC _ 25a1 ; c ESC \`
+//!
+//! The terminal acks with `status=0` even if the slot was already empty.
+//! Clear replies do not echo `cp`. `cp` must be in a PUA range; non-PUA values return
+//! `reason=out_of_namespace`.
+//!
+//! ## Glossary Capacity
+//!
+//! Each session holds at most 1024 registrations keyed by codepoint.
+//! Registrations live for the session duration. A 1025th registration
+//! evicts the oldest entry (FIFO). Sessions are isolated: two tabs may
+//! independently register the same codepoint.
+//!
+//! ## Security: PUA-Only Restriction
+//!
+//! Registration is restricted to the three Unicode Private Use Areas to
+//! prevent glyph-spoofing attacks. PUA codepoints never appear in normal
+//! text (filenames, URLs, commands), so a registered glyph cannot alter
+//! how real text is perceived. The cell buffer always stores the original
+//! codepoint — copy/paste, search, and hyperlink detection return the
+//! codepoint the application emitted, never the rendered glyph.
+//!
+//! Reference: <https://rapha.land/introducing-glyph-protocol-for-terminals/>
+
+const std = @import("std");
+
+pub const request = @import("glyph/request.zig");
+pub const response = @import("glyph/response.zig");
+
+pub const CommandParser = request.CommandParser;
+pub const Request = request.Request;
+pub const Response = response.Response;