lib-vt: C API for SGR parser (#9352)

This exposes the SGR parser to the C and Wasm APIs. An example is shown
in c-vt-sgr.

Compressed example:

```c
#include <assert.h>
#include <stdio.h>
#include <ghostty/vt.h>

int main() {
  // Create parser
  GhosttySgrParser parser;
  assert(ghostty_sgr_new(NULL, &parser) == GHOSTTY_SUCCESS);

  // Parse: ESC[1;31m (bold + red foreground)
  uint16_t params[] = {1, 31};
  assert(ghostty_sgr_set_params(parser, params, NULL, 2) == GHOSTTY_SUCCESS);

  printf("Parsing: ESC[1;31m\n\n");

  // Iterate through attributes
  GhosttySgrAttribute attr;
  while (ghostty_sgr_next(parser, &attr)) {
    switch (attr.tag) {
      case GHOSTTY_SGR_ATTR_BOLD:
        printf("✓ Bold enabled\n");
        break;
      case GHOSTTY_SGR_ATTR_FG_8:
        printf("✓ Foreground color: %d (red)\n", attr.value.fg_8);
        break;
      default:
        break;
    }
  }

  ghostty_sgr_free(parser);
  return 0;
}
```

**AI disclosure:** Amp wrote most of the C headers, but I verified it
all. https://ampcode.com/threads/T-d9f145cb-e6ef-48a8-ad63-e5fc85c0d43e

Author: mitchellh

.github/workflows/test.yml

@@ -94,7 +94,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        dir: [c-vt, c-vt-key-encode, c-vt-paste, zig-vt, zig-vt-stream]
+        dir:
+          [c-vt, c-vt-key-encode, c-vt-paste, c-vt-sgr, zig-vt, zig-vt-stream]
     name: Example ${{ matrix.dir }}
     runs-on: namespace-profile-ghostty-sm
     needs: test

example/c-vt-sgr/README.md

@@ -0,0 +1,21 @@
+# Example: `ghostty-vt` SGR Parser
+
+This contains a simple example of how to use the `ghostty-vt` SGR parser
+to parse terminal styling sequences and extract text attributes.
+
+This example demonstrates parsing a complex SGR sequence from Kakoune that
+includes curly underline, RGB foreground/background colors, and RGB underline
+color with mixed semicolon and colon separators.
+
+This uses a `build.zig` and `Zig` to build the C program so that we
+can reuse a lot of our build logic and depend directly on our source
+tree, but Ghostty emits a standard C library that can be used with any
+C tooling.
+
+## Usage
+
+Run the program:
+
+```shell-session
+zig build run
+```

example/c-vt-sgr/build.zig

@@ -0,0 +1,42 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const run_step = b.step("run", "Run the app");
+
+    const exe_mod = b.createModule(.{
+        .target = target,
+        .optimize = optimize,
+    });
+    exe_mod.addCSourceFiles(.{
+        .root = b.path("src"),
+        .files = &.{"main.c"},
+    });
+
+    // You'll want to use a lazy dependency here so that ghostty is only
+    // downloaded if you actually need it.
+    if (b.lazyDependency("ghostty", .{
+        // Setting simd to false will force a pure static build that
+        // doesn't even require libc, but it has a significant performance
+        // penalty. If your embedding app requires libc anyway, you should
+        // always keep simd enabled.
+        // .simd = false,
+    })) |dep| {
+        exe_mod.linkLibrary(dep.artifact("ghostty-vt"));
+    }
+
+    // Exe
+    const exe = b.addExecutable(.{
+        .name = "c_vt_sgr",
+        .root_module = exe_mod,
+    });
+    b.installArtifact(exe);
+
+    // Run
+    const run_cmd = b.addRunArtifact(exe);
+    run_cmd.step.dependOn(b.getInstallStep());
+    if (b.args) |args| run_cmd.addArgs(args);
+    run_step.dependOn(&run_cmd.step);
+}

example/c-vt-sgr/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_sgr,
+    .version = "0.0.0",
+    .fingerprint = 0x6e9c6d318e59c268,
+    .minimum_zig_version = "0.15.1",
+    .dependencies = .{
+        // Ghostty dependency. In reality, you'd probably use a URL-based
+        // dependency like the one showed (and commented out) below this one.
+        // We use a path dependency here for simplicity and to ensure our
+        // examples always test against the source they're bundled with.
+        .ghostty = .{ .path = "../../" },
+
+        // Example of what a URL-based dependency looks like:
+        // .ghostty = .{
+        //     .url = "https://github.com/ghostty-org/ghostty/archive/COMMIT.tar.gz",
+        //     .hash = "N-V-__8AAMVLTABmYkLqhZPLXnMl-KyN38R8UVYqGrxqO36s",
+        // },
+    },
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+    },
+}

example/c-vt-sgr/src/main.c

@@ -0,0 +1,131 @@
+#include <assert.h>
+#include <stdio.h>
+#include <ghostty/vt.h>
+
+int main() {
+  // Create parser
+  GhosttySgrParser parser;
+  GhosttyResult result = ghostty_sgr_new(NULL, &parser);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Parse a complex SGR sequence from Kakoune
+  // This corresponds to the escape sequence:
+  // ESC[4:3;38;2;51;51;51;48;2;170;170;170;58;2;255;97;136m
+  //
+  // Breaking down the sequence:
+  // - 4:3 = curly underline (colon-separated sub-parameters)
+  // - 38;2;51;51;51 = foreground RGB color (51, 51, 51) - dark gray
+  // - 48;2;170;170;170 = background RGB color (170, 170, 170) - light gray
+  // - 58;2;255;97;136 = underline RGB color (255, 97, 136) - pink
+  uint16_t params[] = {4, 3, 38, 2, 51, 51, 51, 48, 2, 170, 170, 170, 58, 2, 255, 97, 136};
+  
+  // Separator array: ':' at position 0 (between 4 and 3), ';' elsewhere
+  char separators[] = ";;;;;;;;;;;;;;;;";
+  separators[0] = ':';
+  
+  result = ghostty_sgr_set_params(parser, params, separators, sizeof(params) / sizeof(params[0]));
+  assert(result == GHOSTTY_SUCCESS);
+
+  printf("Parsing Kakoune SGR sequence:\n");
+  printf("ESC[4:3;38;2;51;51;51;48;2;170;170;170;58;2;255;97;136m\n\n");
+
+  // Iterate through attributes
+  GhosttySgrAttribute attr;
+  int count = 0;
+  while (ghostty_sgr_next(parser, &attr)) {
+    count++;
+    printf("Attribute %d: ", count);
+    
+    switch (attr.tag) {
+      case GHOSTTY_SGR_ATTR_UNDERLINE:
+        printf("Underline style = ");
+        switch (attr.value.underline) {
+          case GHOSTTY_SGR_UNDERLINE_NONE:
+            printf("none\n");
+            break;
+          case GHOSTTY_SGR_UNDERLINE_SINGLE:
+            printf("single\n");
+            break;
+          case GHOSTTY_SGR_UNDERLINE_DOUBLE:
+            printf("double\n");
+            break;
+          case GHOSTTY_SGR_UNDERLINE_CURLY:
+            printf("curly\n");
+            break;
+          case GHOSTTY_SGR_UNDERLINE_DOTTED:
+            printf("dotted\n");
+            break;
+          case GHOSTTY_SGR_UNDERLINE_DASHED:
+            printf("dashed\n");
+            break;
+          default:
+            printf("unknown (%d)\n", attr.value.underline);
+            break;
+        }
+        break;
+
+      case GHOSTTY_SGR_ATTR_DIRECT_COLOR_FG:
+        printf("Foreground RGB = (%d, %d, %d)\n",
+               attr.value.direct_color_fg.r,
+               attr.value.direct_color_fg.g,
+               attr.value.direct_color_fg.b);
+        break;
+
+      case GHOSTTY_SGR_ATTR_DIRECT_COLOR_BG:
+        printf("Background RGB = (%d, %d, %d)\n",
+               attr.value.direct_color_bg.r,
+               attr.value.direct_color_bg.g,
+               attr.value.direct_color_bg.b);
+        break;
+
+      case GHOSTTY_SGR_ATTR_UNDERLINE_COLOR:
+        printf("Underline color RGB = (%d, %d, %d)\n",
+               attr.value.underline_color.r,
+               attr.value.underline_color.g,
+               attr.value.underline_color.b);
+        break;
+
+      case GHOSTTY_SGR_ATTR_FG_8:
+        printf("Foreground 8-color = %d\n", attr.value.fg_8);
+        break;
+
+      case GHOSTTY_SGR_ATTR_BG_8:
+        printf("Background 8-color = %d\n", attr.value.bg_8);
+        break;
+
+      case GHOSTTY_SGR_ATTR_FG_256:
+        printf("Foreground 256-color = %d\n", attr.value.fg_256);
+        break;
+
+      case GHOSTTY_SGR_ATTR_BG_256:
+        printf("Background 256-color = %d\n", attr.value.bg_256);
+        break;
+
+      case GHOSTTY_SGR_ATTR_BOLD:
+        printf("Bold\n");
+        break;
+
+      case GHOSTTY_SGR_ATTR_ITALIC:
+        printf("Italic\n");
+        break;
+
+      case GHOSTTY_SGR_ATTR_UNSET:
+        printf("Reset all attributes\n");
+        break;
+
+      case GHOSTTY_SGR_ATTR_UNKNOWN:
+        printf("Unknown attribute\n");
+        break;
+
+      default:
+        printf("Other attribute (tag=%d)\n", attr.tag);
+        break;
+    }
+  }
+
+  printf("\nTotal attributes parsed: %d\n", count);
+
+  // Cleanup
+  ghostty_sgr_free(parser);
+  return 0;
+}

include/ghostty/vt.h

@@ -30,6 +30,7 @@
  * The API is organized into the following groups:
  * - @ref key "Key Encoding" - Encode key events into terminal sequences
  * - @ref osc "OSC Parser" - Parse OSC (Operating System Command) sequences
+ * - @ref sgr "SGR Parser" - Parse SGR (Select Graphic Rendition) sequences
  * - @ref paste "Paste Utilities" - Validate paste data safety
  * - @ref allocator "Memory Management" - Memory management and custom allocators
  * - @ref wasm "WebAssembly Utilities" - WebAssembly convenience functions
@@ -40,6 +41,7 @@
  * - @ref c-vt/src/main.c - OSC parser example
  * - @ref c-vt-key-encode/src/main.c - Key encoding example
  * - @ref c-vt-paste/src/main.c - Paste safety check example
+ * - @ref c-vt-sgr/src/main.c - SGR parser example
  *
  */
 
@@ -58,6 +60,11 @@
  * paste data is safe before sending it to the terminal.
  */
 
+/** @example c-vt-sgr/src/main.c
+ * This example demonstrates how to use the SGR parser to parse terminal
+ * styling sequences and extract text attributes like colors and underline styles.
+ */
+
 #ifndef GHOSTTY_VT_H
 #define GHOSTTY_VT_H
 
@@ -68,6 +75,7 @@ extern "C" {
 #include <ghostty/vt/result.h>
 #include <ghostty/vt/allocator.h>
 #include <ghostty/vt/osc.h>
+#include <ghostty/vt/sgr.h>
 #include <ghostty/vt/key.h>
 #include <ghostty/vt/paste.h>
 #include <ghostty/vt/wasm.h>

include/ghostty/vt/color.h

@@ -0,0 +1,77 @@
+/**
+ * @file color.h
+ *
+ * Color types and utilities.
+ */
+
+#ifndef GHOSTTY_VT_COLOR_H
+#define GHOSTTY_VT_COLOR_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * RGB color value.
+ *
+ * @ingroup sgr
+ */
+typedef struct {
+  uint8_t r; /**< Red component (0-255) */
+  uint8_t g; /**< Green component (0-255) */
+  uint8_t b; /**< Blue component (0-255) */
+} GhosttyColorRgb;
+
+/**
+ * Palette color index (0-255).
+ *
+ * @ingroup sgr
+ */
+typedef uint8_t GhosttyColorPaletteIndex;
+
+/** @addtogroup sgr
+ * @{
+ */
+
+/** Black color (0) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_BLACK 0
+/** Red color (1) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_RED 1
+/** Green color (2) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_GREEN 2
+/** Yellow color (3) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_YELLOW 3
+/** Blue color (4) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_BLUE 4
+/** Magenta color (5) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_MAGENTA 5
+/** Cyan color (6) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_CYAN 6
+/** White color (7) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_WHITE 7
+/** Bright black color (8) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_BRIGHT_BLACK 8
+/** Bright red color (9) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_BRIGHT_RED 9
+/** Bright green color (10) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_BRIGHT_GREEN 10
+/** Bright yellow color (11) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_BRIGHT_YELLOW 11
+/** Bright blue color (12) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_BRIGHT_BLUE 12
+/** Bright magenta color (13) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_BRIGHT_MAGENTA 13
+/** Bright cyan color (14) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_BRIGHT_CYAN 14
+/** Bright white color (15) @ingroup sgr */
+#define GHOSTTY_COLOR_NAMED_BRIGHT_WHITE 15
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* GHOSTTY_VT_COLOR_H */

include/ghostty/vt/result.h

@@ -15,6 +15,8 @@ typedef enum {
     GHOSTTY_SUCCESS = 0,
     /** Operation failed due to failed allocation */
     GHOSTTY_OUT_OF_MEMORY = -1,
+    /** Operation failed due to invalid value */
+    GHOSTTY_INVALID_VALUE = -2,
 } GhosttyResult;
 
 #endif /* GHOSTTY_VT_RESULT_H */