chore: import upstream snapshot with attribution

example/.gitignore

@@ -0,0 +1,6 @@
+.parcel-cache/
+dist/
+node_modules/
+example.wasm*
+build/
+.build/

example/AGENTS.md

@@ -0,0 +1,39 @@
+# Example Libghostty Projects
+
+Each example is a standalone project with its own `build.zig`,
+`build.zig.zon`, `README.md`, and `src/main.c` (or `.zig`). Examples are
+auto-discovered by CI via `example/*/build.zig.zon`, so no workflow file
+edits are needed when adding a new example.
+
+## Adding a New Example
+
+1. Copy an existing example directory (e.g., `c-vt-encode-focus/`) as a
+   starting point.
+2. Update `build.zig.zon`: change `.name`, generate a **new unique**
+   `.fingerprint` value (a random `u64` hex literal), and keep
+   `.minimum_zig_version` matching the others.
+3. Update `build.zig`: change the executable `.name` to match the directory.
+4. Write a `README.md` following the existing format.
+
+## Doxygen Snippet Tags
+
+Example source files use Doxygen `@snippet` tags so the corresponding
+header in `include/ghostty/vt/` can reference them. Wrap the relevant
+code with `//! [snippet-name]` markers:
+
+```c
+//! [my-snippet]
+int main() { ... }
+//! [my-snippet]
+```
+
+The header then uses `@snippet <dir>/src/main.c my-snippet` instead of
+inline `@code` blocks. Never duplicate example code inline in the
+headers — always use `@snippet`. When modifying example code, keep the
+snippet markers in sync with the headers in `include/ghostty/vt/`.
+
+## Conventions
+
+- Executable names use underscores: `c_vt_encode_focus` (not hyphens).
+- All C examples link `ghostty-vt` via `lazyDependency("ghostty", ...)`.
+- `build.zig` files follow a common template — keep them consistent.

example/README.md

@@ -0,0 +1,17 @@
+# Examples
+
+Standalone projects demonstrating the Ghostty library APIs.
+The directories starting with `c-` use the C API and the directories
+starting with `zig-` use the Zig API.
+
+Every example can be built and run using `zig build` and `zig build run`
+from within the respective example directory.
+Even the C API examples use the Zig build system (not the language) to
+build the project.
+
+## Running an Example
+
+```shell-session
+cd example/<dir>
+zig build run
+```

example/c-vt-build-info/README.md

@@ -0,0 +1,17 @@
+# Example: `ghostty-vt` Build Info
+
+This contains a simple example of how to use the `ghostty-vt` build info
+API to query compile-time build configuration.
+
+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-build-info/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_build_info",
+        .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-build-info/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_build_info,
+    .version = "0.0.0",
+    .fingerprint = 0xc6b57ed4f83fb16,
+    .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-build-info/src/main.c

@@ -0,0 +1,52 @@
+#include <stdio.h>
+#include <ghostty/vt.h>
+
+//! [build-info-query]
+void query_build_info() {
+  bool simd = false;
+  bool kitty_graphics = false;
+  bool tmux_control_mode = false;
+
+  ghostty_build_info(GHOSTTY_BUILD_INFO_SIMD, &simd);
+  ghostty_build_info(GHOSTTY_BUILD_INFO_KITTY_GRAPHICS, &kitty_graphics);
+  ghostty_build_info(GHOSTTY_BUILD_INFO_TMUX_CONTROL_MODE, &tmux_control_mode);
+
+  printf("SIMD: %s\n", simd ? "enabled" : "disabled");
+  printf("Kitty graphics: %s\n", kitty_graphics ? "enabled" : "disabled");
+  printf("Tmux control mode: %s\n", tmux_control_mode ? "enabled" : "disabled");
+
+  GhosttyString version_string = {0};
+  size_t version_major = 0;
+  size_t version_minor = 0;
+  size_t version_patch = 0;
+  GhosttyString version_pre = {0};
+  GhosttyString version_build = {0};
+
+  ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_STRING, &version_string);
+  ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_MAJOR, &version_major);
+  ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_MINOR, &version_minor);
+  ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_PATCH, &version_patch);
+  ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_PRE, &version_pre);
+  ghostty_build_info(GHOSTTY_BUILD_INFO_VERSION_BUILD, &version_build);
+
+  printf("Version: %.*s\n", (int)version_string.len, version_string.ptr);
+  printf("Version major: %zu\n", version_major);
+  printf("Version minor: %zu\n", version_minor);
+  printf("Version patch: %zu\n", version_patch);
+  if (version_pre.len > 0) {
+    printf("Version pre  : %.*s\n", (int)version_pre.len, version_pre.ptr);
+  } else {
+    printf("Version pre  : (none)\n");
+  }
+  if (version_build.len > 0) {
+    printf("Version build: %.*s\n", (int)version_build.len, version_build.ptr);
+  } else {
+    printf("Version build: (none)\n");
+  }
+}
+//! [build-info-query]
+
+int main() {
+  query_build_info();
+  return 0;
+}

example/c-vt-cmake-cross/CMakeLists.txt

@@ -0,0 +1,59 @@
+cmake_minimum_required(VERSION 3.19)
+
+# --- Determine cross-compilation target before project() --------------------
+#
+# We need to know the target before project() so we can set up zig cc as the
+# C/C++ compiler for the cross target.
+
+# Pick a cross-compilation target: build for a different OS than the host.
+# Can be overridden with -DZIG_TARGET=... on the command line.
+if(NOT ZIG_TARGET)
+    # CMAKE_HOST_SYSTEM_PROCESSOR may not be set before project(), so
+    # fall back to `uname -m`.
+    if(CMAKE_HOST_SYSTEM_PROCESSOR)
+        set(_arch "${CMAKE_HOST_SYSTEM_PROCESSOR}")
+    else()
+        execute_process(COMMAND uname -m OUTPUT_VARIABLE _arch OUTPUT_STRIP_TRAILING_WHITESPACE)
+    endif()
+    if(_arch MATCHES "^(x86_64|AMD64)$")
+        set(_arch "x86_64")
+    elseif(_arch MATCHES "^(aarch64|arm64|ARM64)$")
+        set(_arch "aarch64")
+    endif()
+
+    if(CMAKE_HOST_SYSTEM_NAME STREQUAL "Linux")
+        set(ZIG_TARGET "${_arch}-windows-gnu")
+    elseif(CMAKE_HOST_SYSTEM_NAME STREQUAL "Windows")
+        set(ZIG_TARGET "${_arch}-linux-gnu")
+    elseif(CMAKE_HOST_SYSTEM_NAME STREQUAL "Darwin")
+        set(ZIG_TARGET "${_arch}-linux-gnu")
+    else()
+        message(FATAL_ERROR
+            "Cannot derive ZIG_TARGET for ${CMAKE_HOST_SYSTEM_NAME}. "
+            "Pass -DZIG_TARGET=... manually.")
+    endif()
+
+    message(STATUS "Cross-compiling for ZIG_TARGET: ${ZIG_TARGET}")
+endif()
+
+# --- Set up zig cc as the cross compiler ------------------------------------
+
+# GhosttyZigCompiler.cmake must be called before project().
+# Downstream projects would copy this file into their tree; here we
+# include it directly from the repo.
+include(../../dist/cmake/GhosttyZigCompiler.cmake)
+ghostty_zig_compiler(ZIG_TARGET "${ZIG_TARGET}")
+
+project(c-vt-cmake-cross LANGUAGES C CXX)
+
+include(FetchContent)
+FetchContent_Declare(ghostty
+    GIT_REPOSITORY https://github.com/ghostty-org/ghostty.git
+    GIT_TAG main
+)
+FetchContent_MakeAvailable(ghostty)
+
+ghostty_vt_add_target(NAME cross ZIG_TARGET "${ZIG_TARGET}")
+
+add_executable(c_vt_cmake_cross src/main.c)
+target_link_libraries(c_vt_cmake_cross PRIVATE ghostty-vt-static-cross)

example/c-vt-cmake-cross/README.md

@@ -0,0 +1,21 @@
+# c-vt-cmake-cross
+
+Demonstrates using `ghostty_vt_add_target()` to cross-compile
+libghostty-vt with static linking. The target OS is chosen automatically:
+
+| Host    | Target          |
+| ------- | --------------- |
+| Linux   | Windows (MinGW) |
+| Windows | Linux (glibc)   |
+| macOS   | Linux (glibc)   |
+
+Override with `-DZIG_TARGET=...` if needed.
+
+## Building
+
+```shell-session
+cd example/c-vt-cmake-cross
+cmake -B build -DFETCHCONTENT_SOURCE_DIR_GHOSTTY=../..
+cmake --build build
+file build/c_vt_cmake_cross
+```

example/c-vt-cmake-cross/src/main.c

@@ -0,0 +1,52 @@
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+int main() {
+  // Create a terminal with a small grid
+  GhosttyTerminal terminal;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 24,
+    .max_scrollback = 0,
+  };
+  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Write some VT-encoded content into the terminal
+  const char *commands[] = {
+    "Hello from a \033[1mCMake\033[0m-built program!\r\n",
+    "Line 2: \033[4munderlined\033[0m text\r\n",
+    "Line 3: \033[31mred\033[0m \033[32mgreen\033[0m \033[34mblue\033[0m\r\n",
+  };
+  for (size_t i = 0; i < sizeof(commands) / sizeof(commands[0]); i++) {
+    ghostty_terminal_vt_write(terminal, (const uint8_t *)commands[i],
+                              strlen(commands[i]));
+  }
+
+  // Format the terminal contents as plain text
+  GhosttyFormatterTerminalOptions fmt_opts =
+      GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
+  fmt_opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
+  fmt_opts.trim = true;
+
+  GhosttyFormatter formatter;
+  result = ghostty_formatter_terminal_new(NULL, &formatter, terminal, fmt_opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  uint8_t *buf = NULL;
+  size_t len = 0;
+  result = ghostty_formatter_format_alloc(formatter, NULL, &buf, &len);
+  assert(result == GHOSTTY_SUCCESS);
+
+  printf("Plain text (%zu bytes):\n", len);
+  fwrite(buf, 1, len, stdout);
+  printf("\n");
+
+  ghostty_free(NULL, buf, len);
+  ghostty_formatter_free(formatter);
+  ghostty_terminal_free(terminal);
+  return 0;
+}

example/c-vt-cmake-static/CMakeLists.txt

@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.19)
+project(c-vt-cmake-static LANGUAGES C)
+
+include(FetchContent)
+FetchContent_Declare(ghostty
+    GIT_REPOSITORY https://github.com/ghostty-org/ghostty.git
+    GIT_TAG main
+)
+set(GHOSTTY_ZIG_BUILD_FLAGS "-Dsimd=false" CACHE STRING "" FORCE)
+FetchContent_MakeAvailable(ghostty)
+
+add_executable(c_vt_cmake_static src/main.c)
+target_link_libraries(c_vt_cmake_static PRIVATE ghostty-vt-static)

example/c-vt-cmake-static/README.md

@@ -0,0 +1,21 @@
+# c-vt-cmake-static
+
+Demonstrates consuming libghostty-vt as a **static** library from a CMake
+project using `FetchContent`. Creates a terminal, writes VT sequences into
+it, and formats the screen contents as plain text.
+
+## Building
+
+```shell-session
+cd example/c-vt-cmake-static
+cmake -B build
+cmake --build build
+./build/c_vt_cmake_static
+```
+
+To build against a local checkout instead of fetching from GitHub:
+
+```shell-session
+cmake -B build -DFETCHCONTENT_SOURCE_DIR_GHOSTTY=../..
+cmake --build build
+```

example/c-vt-cmake-static/src/main.c

@@ -0,0 +1,52 @@
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+int main() {
+  // Create a terminal with a small grid
+  GhosttyTerminal terminal;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 24,
+    .max_scrollback = 0,
+  };
+  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Write some VT-encoded content into the terminal
+  const char *commands[] = {
+    "Hello from a \033[1mCMake\033[0m-built program (static)!\r\n",
+    "Line 2: \033[4munderlined\033[0m text\r\n",
+    "Line 3: \033[31mred\033[0m \033[32mgreen\033[0m \033[34mblue\033[0m\r\n",
+  };
+  for (size_t i = 0; i < sizeof(commands) / sizeof(commands[0]); i++) {
+    ghostty_terminal_vt_write(terminal, (const uint8_t *)commands[i],
+                              strlen(commands[i]));
+  }
+
+  // Format the terminal contents as plain text
+  GhosttyFormatterTerminalOptions fmt_opts =
+      GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
+  fmt_opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
+  fmt_opts.trim = true;
+
+  GhosttyFormatter formatter;
+  result = ghostty_formatter_terminal_new(NULL, &formatter, terminal, fmt_opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  uint8_t *buf = NULL;
+  size_t len = 0;
+  result = ghostty_formatter_format_alloc(formatter, NULL, &buf, &len);
+  assert(result == GHOSTTY_SUCCESS);
+
+  printf("Plain text (%zu bytes):\n", len);
+  fwrite(buf, 1, len, stdout);
+  printf("\n");
+
+  ghostty_free(NULL, buf, len);
+  ghostty_formatter_free(formatter);
+  ghostty_terminal_free(terminal);
+  return 0;
+}

example/c-vt-cmake/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.19)
+project(c-vt-cmake LANGUAGES C)
+
+include(FetchContent)
+FetchContent_Declare(ghostty
+    GIT_REPOSITORY https://github.com/ghostty-org/ghostty.git
+    GIT_TAG main
+)
+FetchContent_MakeAvailable(ghostty)
+
+add_executable(c_vt_cmake src/main.c)
+target_link_libraries(c_vt_cmake PRIVATE ghostty-vt)

example/c-vt-cmake/README.md

@@ -0,0 +1,21 @@
+# c-vt-cmake
+
+Demonstrates consuming libghostty-vt from a CMake project using
+`FetchContent`. Creates a terminal, writes VT sequences into it, and
+formats the screen contents as plain text.
+
+## Building
+
+```shell-session
+cd example/c-vt-cmake
+cmake -B build
+cmake --build build
+./build/c_vt_cmake
+```
+
+To build against a local checkout instead of fetching from GitHub:
+
+```shell-session
+cmake -B build -DFETCHCONTENT_SOURCE_DIR_GHOSTTY=../..
+cmake --build build
+```

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

@@ -0,0 +1,52 @@
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+int main() {
+  // Create a terminal with a small grid
+  GhosttyTerminal terminal;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 24,
+    .max_scrollback = 0,
+  };
+  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Write some VT-encoded content into the terminal
+  const char *commands[] = {
+    "Hello from a \033[1mCMake\033[0m-built program!\r\n",
+    "Line 2: \033[4munderlined\033[0m text\r\n",
+    "Line 3: \033[31mred\033[0m \033[32mgreen\033[0m \033[34mblue\033[0m\r\n",
+  };
+  for (size_t i = 0; i < sizeof(commands) / sizeof(commands[0]); i++) {
+    ghostty_terminal_vt_write(terminal, (const uint8_t *)commands[i],
+                              strlen(commands[i]));
+  }
+
+  // Format the terminal contents as plain text
+  GhosttyFormatterTerminalOptions fmt_opts =
+      GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
+  fmt_opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
+  fmt_opts.trim = true;
+
+  GhosttyFormatter formatter;
+  result = ghostty_formatter_terminal_new(NULL, &formatter, terminal, fmt_opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  uint8_t *buf = NULL;
+  size_t len = 0;
+  result = ghostty_formatter_format_alloc(formatter, NULL, &buf, &len);
+  assert(result == GHOSTTY_SUCCESS);
+
+  printf("Plain text (%zu bytes):\n", len);
+  fwrite(buf, 1, len, stdout);
+  printf("\n");
+
+  ghostty_free(NULL, buf, len);
+  ghostty_formatter_free(formatter);
+  ghostty_terminal_free(terminal);
+  return 0;
+}

example/c-vt-color-scheme/README.md

@@ -0,0 +1,18 @@
+# Example: `ghostty-vt` Color Scheme Report Encoding
+
+This contains a simple example of how to use the `ghostty-vt` color scheme
+report encoding API to encode terminal color scheme reports into escape
+sequences.
+
+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-color-scheme/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_color_scheme",
+        .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-color-scheme/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_color_scheme,
+    .version = "0.0.0",
+    .fingerprint = 0xb794dffb11875b23,
+    .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-color-scheme/src/main.c

@@ -0,0 +1,20 @@
+#include <stdio.h>
+#include <ghostty/vt.h>
+
+//! [color-scheme-report-encode]
+int main() {
+  char buf[16];
+  size_t written = 0;
+
+  GhosttyResult result = ghostty_color_scheme_report_encode(
+      GHOSTTY_COLOR_SCHEME_DARK, buf, sizeof(buf), &written);
+
+  if (result == GHOSTTY_SUCCESS) {
+    printf("Encoded %zu bytes: ", written);
+    fwrite(buf, 1, written, stdout);
+    printf("\n");
+  }
+
+  return 0;
+}
+//! [color-scheme-report-encode]

example/c-vt-colors/README.md

@@ -0,0 +1,18 @@
+# Example: `ghostty-vt` Terminal Colors
+
+This contains a simple example of how to set default terminal colors,
+read effective and default color values, and observe how OSC overrides
+layer on top of defaults using the `ghostty-vt` C library.
+
+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-colors/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_colors",
+        .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-colors/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_colors,
+    .version = "0.0.0",
+    .fingerprint = 0xe7ec4247f16d4fce,
+    .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-colors/src/main.c

@@ -0,0 +1,121 @@
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [colors-set-defaults]
+/// Set up a dark color theme with custom palette entries.
+void set_color_theme(GhosttyTerminal terminal) {
+  // Set default foreground (light gray) and background (dark)
+  GhosttyColorRgb fg = { .r = 0xDD, .g = 0xDD, .b = 0xDD };
+  GhosttyColorRgb bg = { .r = 0x1E, .g = 0x1E, .b = 0x2E };
+  GhosttyColorRgb cursor = { .r = 0xF5, .g = 0xE0, .b = 0xDC };
+
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND, &fg);
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND, &bg);
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_CURSOR, &cursor);
+
+  // Set a custom palette — start from the built-in default and override
+  // the first 8 entries with a custom dark theme.
+  GhosttyColorRgb palette[256];
+  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_COLOR_PALETTE, palette);
+
+  palette[GHOSTTY_COLOR_NAMED_BLACK]   = (GhosttyColorRgb){ 0x45, 0x47, 0x5A };
+  palette[GHOSTTY_COLOR_NAMED_RED]     = (GhosttyColorRgb){ 0xF3, 0x8B, 0xA8 };
+  palette[GHOSTTY_COLOR_NAMED_GREEN]   = (GhosttyColorRgb){ 0xA6, 0xE3, 0xA1 };
+  palette[GHOSTTY_COLOR_NAMED_YELLOW]  = (GhosttyColorRgb){ 0xF9, 0xE2, 0xAF };
+  palette[GHOSTTY_COLOR_NAMED_BLUE]    = (GhosttyColorRgb){ 0x89, 0xB4, 0xFA };
+  palette[GHOSTTY_COLOR_NAMED_MAGENTA] = (GhosttyColorRgb){ 0xF5, 0xC2, 0xE7 };
+  palette[GHOSTTY_COLOR_NAMED_CYAN]    = (GhosttyColorRgb){ 0x94, 0xE2, 0xD5 };
+  palette[GHOSTTY_COLOR_NAMED_WHITE]   = (GhosttyColorRgb){ 0xBA, 0xC2, 0xDE };
+
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_PALETTE, palette);
+}
+//! [colors-set-defaults]
+
+//! [colors-read]
+/// Print the effective and default values for a color, showing how
+/// OSC overrides layer on top of defaults.
+void print_color(GhosttyTerminal terminal,
+                 const char* name,
+                 GhosttyTerminalData effective_data,
+                 GhosttyTerminalData default_data) {
+  GhosttyColorRgb color;
+
+  GhosttyResult res = ghostty_terminal_get(terminal, effective_data, &color);
+  if (res == GHOSTTY_SUCCESS) {
+    printf("  %-12s effective: #%02X%02X%02X", name, color.r, color.g, color.b);
+  } else {
+    printf("  %-12s effective: (not set)", name);
+  }
+
+  res = ghostty_terminal_get(terminal, default_data, &color);
+  if (res == GHOSTTY_SUCCESS) {
+    printf("  default: #%02X%02X%02X\n", color.r, color.g, color.b);
+  } else {
+    printf("  default: (not set)\n");
+  }
+}
+
+void print_all_colors(GhosttyTerminal terminal, const char* label) {
+  printf("%s:\n", label);
+  print_color(terminal, "foreground",
+      GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND,
+      GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT);
+  print_color(terminal, "background",
+      GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND,
+      GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT);
+  print_color(terminal, "cursor",
+      GHOSTTY_TERMINAL_DATA_COLOR_CURSOR,
+      GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT);
+
+  // Show palette index 0 (black) as an example
+  GhosttyColorRgb palette[256];
+  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_COLOR_PALETTE, palette);
+  printf("  %-12s effective: #%02X%02X%02X", "palette[0]",
+      palette[0].r, palette[0].g, palette[0].b);
+
+  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT,
+      palette);
+  printf("  default: #%02X%02X%02X\n", palette[0].r, palette[0].g, palette[0].b);
+}
+//! [colors-read]
+
+//! [colors-main]
+int main() {
+  // Create a terminal
+  GhosttyTerminal terminal = NULL;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 24,
+    .max_scrollback = 0,
+  };
+  if (ghostty_terminal_new(NULL, &terminal, opts) != GHOSTTY_SUCCESS) {
+    fprintf(stderr, "Failed to create terminal\n");
+    return 1;
+  }
+
+  // Before setting any colors, everything is unset
+  print_all_colors(terminal, "Before setting defaults");
+
+  // Set our color theme defaults
+  set_color_theme(terminal);
+  print_all_colors(terminal, "\nAfter setting defaults");
+
+  // Simulate an OSC override (e.g. a program running inside the
+  // terminal changes the foreground via OSC 10)
+  const char* osc_fg = "\x1B]10;rgb:FF/00/00\x1B\\";
+  ghostty_terminal_vt_write(terminal, (const uint8_t*)osc_fg,
+                            strlen(osc_fg));
+  print_all_colors(terminal, "\nAfter OSC foreground override");
+
+  // Clear the foreground default — the OSC override is still active
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND, NULL);
+  print_all_colors(terminal, "\nAfter clearing foreground default");
+
+  ghostty_terminal_free(terminal);
+  return 0;
+}
+//! [colors-main]

example/c-vt-compression/README.md

@@ -0,0 +1,17 @@
+# Example: Scrollback Compression in C
+
+This example shows how a libghostty-vt embedding application can track
+compression-relevant terminal activity and perform incremental scrollback
+compression after its own idle delay.
+
+libghostty-vt does not create a timer or background thread. The embedding
+application remains responsible for scheduling compression and serializing it
+with other access to the terminal.
+
+## Usage
+
+Run the example:
+
+```shell-session
+zig build run
+```

example/c-vt-compression/build.zig

@@ -0,0 +1,32 @@
+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"},
+    });
+
+    if (b.lazyDependency("ghostty", .{})) |dep| {
+        exe_mod.linkLibrary(dep.artifact("ghostty-vt"));
+    }
+
+    const exe = b.addExecutable(.{
+        .name = "c_vt_compression",
+        .root_module = exe_mod,
+    });
+    b.installArtifact(exe);
+
+    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-compression/build.zig.zon

@@ -0,0 +1,14 @@
+.{
+    .name = .c_vt_compression,
+    .version = "0.0.0",
+    .fingerprint = 0x3d527aa68a4cf8d,
+    .minimum_zig_version = "0.15.1",
+    .dependencies = .{
+        .ghostty = .{ .path = "../../" },
+    },
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+    },
+}

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

@@ -0,0 +1,72 @@
+#include <assert.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [compression-idle-step]
+// Perform one step after the application's idle timer fires. Returning true
+// asks the application to schedule another step while the terminal is idle.
+static bool compression_idle_step(GhosttyTerminal terminal) {
+  GhosttyTerminalCompressionResult compression_result;
+  GhosttyResult result = ghostty_terminal_compress(
+      terminal,
+      GHOSTTY_TERMINAL_COMPRESSION_MODE_INCREMENTAL,
+      &compression_result);
+  assert(result == GHOSTTY_SUCCESS);
+
+  switch (compression_result) {
+    case GHOSTTY_TERMINAL_COMPRESSION_RESULT_PENDING:
+      return true;
+    case GHOSTTY_TERMINAL_COMPRESSION_RESULT_COMPLETE:
+    case GHOSTTY_TERMINAL_COMPRESSION_RESULT_UNSUPPORTED:
+      return false;
+    default:
+      assert(false);
+      return false;
+  }
+}
+//! [compression-idle-step]
+
+int main(void) {
+  GhosttyTerminal terminal;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 24,
+    .max_scrollback = 10 * 1024 * 1024,
+  };
+  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  //! [compression-activity]
+  uint64_t compression_activity;
+  result = ghostty_terminal_compression_activity(
+      terminal,
+      &compression_activity);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Terminal mutations may change the token. When it changes, restart the
+  // application's idle timer rather than compressing on the output path.
+  const char *line = "repeated and compressible terminal history\r\n";
+  for (size_t i = 0; i < 4000; i++) {
+    ghostty_terminal_vt_write(
+        terminal,
+        (const uint8_t *)line,
+        strlen(line));
+  }
+
+  uint64_t new_activity;
+  result = ghostty_terminal_compression_activity(terminal, &new_activity);
+  assert(result == GHOSTTY_SUCCESS);
+  if (new_activity != compression_activity) {
+    compression_activity = new_activity;
+    // Restart the application's compression idle timer here.
+  }
+  //! [compression-activity]
+
+  // Simulate the idle timer and its short pending-work continuations.
+  while (compression_idle_step(terminal)) {}
+
+  ghostty_terminal_free(terminal);
+  return 0;
+}

example/c-vt-effects/README.md

@@ -0,0 +1,22 @@
+# Example: `ghostty-vt` Terminal Effects
+
+This contains a simple example of how to register and use terminal
+effect callbacks (`write_pty`, `bell`, `title_changed`, and
+`clipboard_write`) with the
+`ghostty-vt` C library.
+
+The clipboard effect receives one atomic write with decoded, binary-safe
+MIME representations rather than protocol-specific OSC 52 data.
+
+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-effects/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_effects",
+        .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-effects/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_effects,
+    .version = "0.0.0",
+    .fingerprint = 0xc02634cd65f5b583,
+    .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-effects/src/main.c

@@ -0,0 +1,137 @@
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [effects-write-pty]
+void on_write_pty(GhosttyTerminal terminal,
+                  void* userdata,
+                  const uint8_t* data,
+                  size_t len) {
+  (void)terminal;
+  (void)userdata;
+  printf("  write_pty (%zu bytes): ", len);
+  fwrite(data, 1, len, stdout);
+  printf("\n");
+}
+//! [effects-write-pty]
+
+//! [effects-bell]
+void on_bell(GhosttyTerminal terminal, void* userdata) {
+  (void)terminal;
+  int* count = (int*)userdata;
+  (*count)++;
+  printf("  bell! (count=%d)\n", *count);
+}
+//! [effects-bell]
+
+//! [effects-title-changed]
+void on_title_changed(GhosttyTerminal terminal, void* userdata) {
+  (void)userdata;
+  // Query the cursor position to confirm the terminal processed the
+  // title change (the title itself is tracked by the embedder via the
+  // OSC parser or its own state).
+  uint16_t col = 0;
+  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_CURSOR_X, &col);
+  printf("  title changed (cursor at col %u)\n", col);
+}
+//! [effects-title-changed]
+
+//! [effects-clipboard-write]
+GhosttyClipboardWriteResult on_clipboard_write(
+    GhosttyTerminal terminal,
+    void* userdata,
+    const GhosttyClipboardWrite* write) {
+  (void)terminal;
+  (void)userdata;
+
+  printf("  clipboard write (location=%d, contents=%zu)\n",
+         (int)write->location, write->contents_len);
+  if (write->contents_len == 0) {
+    printf("    clear\n");
+  }
+
+  for (size_t i = 0; i < write->contents_len; i++) {
+    const GhosttyClipboardContent* content = &write->contents[i];
+    printf("    ");
+    if (content->mime.len > 0) {
+      fwrite(content->mime.ptr, 1, content->mime.len, stdout);
+    }
+    printf(" (%zu bytes): ", content->data.len);
+    if (content->data.len > 0) {
+      fwrite(content->data.ptr, 1, content->data.len, stdout);
+    }
+    printf("\n");
+  }
+
+  return GHOSTTY_CLIPBOARD_WRITE_RESULT_SUCCESS;
+}
+//! [effects-clipboard-write]
+
+//! [effects-register]
+int main() {
+  // Create a terminal
+  GhosttyTerminal terminal = NULL;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 24,
+    .max_scrollback = 0,
+  };
+  if (ghostty_terminal_new(NULL, &terminal, opts) != GHOSTTY_SUCCESS) {
+    fprintf(stderr, "Failed to create terminal\n");
+    return 1;
+  }
+
+  // Set up userdata — a simple bell counter
+  int bell_count = 0;
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_USERDATA, &bell_count);
+
+  // Register effect callbacks
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_WRITE_PTY,
+      (const void *)on_write_pty);
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_BELL,
+      (const void *)on_bell);
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_TITLE_CHANGED,
+      (const void *)on_title_changed);
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_CLIPBOARD_WRITE,
+      (const void *)on_clipboard_write);
+
+  // Feed VT data that triggers effects:
+
+  // 1. Bell (BEL = 0x07)
+  printf("Sending BEL:\n");
+  const uint8_t bel = 0x07;
+  ghostty_terminal_vt_write(terminal, &bel, 1);
+
+  // 2. Title change (OSC 2 ; <title> ST)
+  printf("Sending title change:\n");
+  const char* title_seq = "\x1B]2;Hello Effects\x1B\\";
+  ghostty_terminal_vt_write(terminal, (const uint8_t*)title_seq,
+                            strlen(title_seq));
+
+  // 3. Device status report (DECRQM for wraparound mode ?7)
+  //    triggers write_pty with the response
+  printf("Sending DECRQM query:\n");
+  const char* decrqm = "\x1B[?7$p";
+  ghostty_terminal_vt_write(terminal, (const uint8_t*)decrqm,
+                            strlen(decrqm));
+
+  // 4. Clipboard write (OSC 52 ; c ; <base64 data> ST)
+  printf("Sending clipboard write:\n");
+  const char* clipboard_seq =
+      "\x1B]52;c;SGVsbG8gY2xpcGJvYXJk\x1B\\";
+  ghostty_terminal_vt_write(terminal, (const uint8_t*)clipboard_seq,
+                            strlen(clipboard_seq));
+
+  // 5. Another bell to show the counter increments
+  printf("Sending another BEL:\n");
+  ghostty_terminal_vt_write(terminal, &bel, 1);
+
+  printf("Total bells: %d\n", bell_count);
+
+  ghostty_terminal_free(terminal);
+  return 0;
+}
+//! [effects-register]

example/c-vt-encode-focus/README.md

@@ -0,0 +1,17 @@
+# Example: `ghostty-vt` Encode Focus
+
+This contains a simple example of how to use the `ghostty-vt` focus
+encoding API to encode focus gained/lost events into escape sequences.
+
+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-encode-focus/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_encode_focus",
+        .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-encode-focus/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_encode_focus,
+    .version = "0.0.0",
+    .fingerprint = 0x89f01fd829fcc550,
+    .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-encode-focus/src/main.c

@@ -0,0 +1,20 @@
+#include <stdio.h>
+#include <ghostty/vt.h>
+
+//! [focus-encode]
+int main() {
+  char buf[8];
+  size_t written = 0;
+
+  GhosttyResult result = ghostty_focus_encode(
+      GHOSTTY_FOCUS_GAINED, buf, sizeof(buf), &written);
+
+  if (result == GHOSTTY_SUCCESS) {
+    printf("Encoded %zu bytes: ", written);
+    fwrite(buf, 1, written, stdout);
+    printf("\n");
+  }
+
+  return 0;
+}
+//! [focus-encode]

example/c-vt-encode-key/README.md

@@ -0,0 +1,22 @@
+# Example: `ghostty-vt` C Key Encoding
+
+This example demonstrates how to use the `ghostty-vt` C library to encode key
+events into terminal escape sequences.
+
+This example specifically shows how to:
+
+1. Create a key encoder with the C API
+2. Configure Kitty keyboard protocol flags (this example uses KKP)
+3. Create and configure a key event
+4. Encode the key event into a terminal escape sequence
+
+The example encodes a Ctrl key release event with the Ctrl modifier set,
+producing the escape sequence `\x1b[57442;5:3u`.
+
+## Usage
+
+Run the program:
+
+```shell-session
+zig build run
+```

example/c-vt-encode-key/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_encode_key",
+        .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-encode-key/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt,
+    .version = "0.0.0",
+    .fingerprint = 0x413a8529b1255f9a,
+    .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-encode-key/src/main.c

@@ -0,0 +1,40 @@
+#include <assert.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [key-encode]
+int main() {
+  // Create encoder
+  GhosttyKeyEncoder encoder;
+  GhosttyResult result = ghostty_key_encoder_new(NULL, &encoder);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Enable Kitty keyboard protocol with all features
+  ghostty_key_encoder_setopt(encoder, GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS,
+                             &(uint8_t){GHOSTTY_KITTY_KEY_ALL});
+
+  // Create and configure key event for Ctrl+C press
+  GhosttyKeyEvent event;
+  result = ghostty_key_event_new(NULL, &event);
+  assert(result == GHOSTTY_SUCCESS);
+  ghostty_key_event_set_action(event, GHOSTTY_KEY_ACTION_PRESS);
+  ghostty_key_event_set_key(event, GHOSTTY_KEY_C);
+  ghostty_key_event_set_mods(event, GHOSTTY_MODS_CTRL);
+
+  // Encode the key event
+  char buf[128];
+  size_t written = 0;
+  result = ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Use the encoded sequence (e.g., write to terminal)
+  fwrite(buf, 1, written, stdout);
+
+  // Cleanup
+  ghostty_key_event_free(event);
+  ghostty_key_encoder_free(encoder);
+  return 0;
+}
+//! [key-encode]

example/c-vt-encode-mouse/README.md

@@ -0,0 +1,23 @@
+# Example: `ghostty-vt` C Mouse Encoding
+
+This example demonstrates how to use the `ghostty-vt` C library to encode mouse
+events into terminal escape sequences.
+
+This example specifically shows how to:
+
+1. Create a mouse encoder with the C API
+2. Configure tracking mode and output format (this example uses SGR)
+3. Set terminal geometry for pixel-to-cell coordinate mapping
+4. Create and configure a mouse event
+5. Encode the mouse event into a terminal escape sequence
+
+The example encodes a left button press at pixel position (50, 40) using SGR
+format, producing an escape sequence like `\x1b[<0;6;3M`.
+
+## Usage
+
+Run the program:
+
+```shell-session
+zig build run
+```

example/c-vt-encode-mouse/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_encode_mouse",
+        .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-encode-mouse/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt,
+    .version = "0.0.0",
+    .fingerprint = 0x413a8529a6dd3c51,
+    .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-encode-mouse/src/main.c

@@ -0,0 +1,52 @@
+#include <assert.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [mouse-encode]
+int main() {
+  // Create encoder
+  GhosttyMouseEncoder encoder;
+  GhosttyResult result = ghostty_mouse_encoder_new(NULL, &encoder);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Configure SGR format with normal tracking
+  ghostty_mouse_encoder_setopt(encoder, GHOSTTY_MOUSE_ENCODER_OPT_EVENT,
+      &(GhosttyMouseTrackingMode){GHOSTTY_MOUSE_TRACKING_NORMAL});
+  ghostty_mouse_encoder_setopt(encoder, GHOSTTY_MOUSE_ENCODER_OPT_FORMAT,
+      &(GhosttyMouseFormat){GHOSTTY_MOUSE_FORMAT_SGR});
+
+  // Set terminal geometry for coordinate mapping
+  ghostty_mouse_encoder_setopt(encoder, GHOSTTY_MOUSE_ENCODER_OPT_SIZE,
+      &(GhosttyMouseEncoderSize){
+          .size = sizeof(GhosttyMouseEncoderSize),
+          .screen_width = 800, .screen_height = 600,
+          .cell_width = 10, .cell_height = 20,
+      });
+
+  // Create and configure a left button press event
+  GhosttyMouseEvent event;
+  result = ghostty_mouse_event_new(NULL, &event);
+  assert(result == GHOSTTY_SUCCESS);
+  ghostty_mouse_event_set_action(event, GHOSTTY_MOUSE_ACTION_PRESS);
+  ghostty_mouse_event_set_button(event, GHOSTTY_MOUSE_BUTTON_LEFT);
+  ghostty_mouse_event_set_position(event,
+      (GhosttyMousePosition){.x = 50.0f, .y = 40.0f});
+
+  // Encode the mouse event
+  char buf[128];
+  size_t written = 0;
+  result = ghostty_mouse_encoder_encode(encoder, event,
+      buf, sizeof(buf), &written);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Use the encoded sequence (e.g., write to terminal)
+  fwrite(buf, 1, written, stdout);
+
+  // Cleanup
+  ghostty_mouse_event_free(event);
+  ghostty_mouse_encoder_free(encoder);
+  return 0;
+}
+//! [mouse-encode]

example/c-vt-formatter/README.md

@@ -0,0 +1,18 @@
+# Example: `ghostty-vt` Terminal Formatter
+
+This contains a simple example of how to use the `ghostty-vt` terminal and
+formatter APIs to create a terminal, write VT-encoded content into it, and
+format the screen contents as plain text.
+
+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-formatter/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_formatter",
+        .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-formatter/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_formatter,
+    .version = "0.0.0",
+    .fingerprint = 0x9e3758265677a0c4,
+    .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-formatter/src/main.c

@@ -0,0 +1,63 @@
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+int main() {
+  // Create a terminal with a small grid
+  GhosttyTerminal terminal;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 24,
+    .max_scrollback = 0,
+  };
+  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Write VT-encoded content into the terminal to exercise various
+  // cursor movement and styling sequences.
+  const char *commands[] = {
+    "Line 1: Hello World!\r\n",           // Simple text on row 1
+    "Line 2: \033[1mBold\033[0m and "     // Bold text on row 2
+      "\033[4mUnderline\033[0m\r\n",
+    "Line 3: placeholder\r\n",            // Will be overwritten below
+    "\033[3;1H",                          // CUP: move cursor back to row 3, col 1
+    "\033[2K",                            // EL:  erase the entire line
+    "Line 3: Overwritten!\r\n",           // Rewrite row 3 with new content
+    "\033[5;10H",                         // CUP: jump to row 5, col 10
+    "Placed at (5,10)",                   // Write at that position
+    "\033[1;72H",                         // CUP: jump to row 1, col 72
+    "RIGHT->",                            // Near the right edge of row 1
+  };
+  for (size_t i = 0; i < sizeof(commands) / sizeof(commands[0]); i++) {
+    ghostty_terminal_vt_write(terminal, (const uint8_t *)commands[i],
+                              strlen(commands[i]));
+  }
+
+  // Create a plain-text formatter for the terminal
+  GhosttyFormatterTerminalOptions fmt_opts = GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
+  fmt_opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
+  fmt_opts.trim = true;
+
+  GhosttyFormatter formatter;
+  result = ghostty_formatter_terminal_new(NULL, &formatter, terminal, fmt_opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Format into an allocated buffer
+  uint8_t *buf = NULL;
+  size_t len = 0;
+  result = ghostty_formatter_format_alloc(formatter, NULL, &buf, &len);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Print the formatted output
+  printf("Formatted output (%zu bytes):\n", len);
+  fwrite(buf, 1, len, stdout);
+  printf("\n");
+
+  // Clean up
+  ghostty_free(NULL, buf, len);
+  ghostty_formatter_free(formatter);
+  ghostty_terminal_free(terminal);
+  return 0;
+}

example/c-vt-grid-ref-tracked/README.md

@@ -0,0 +1,19 @@
+# Example: `ghostty-vt` Tracked Grid References
+
+This contains a simple example of how to use the `ghostty-vt` terminal and
+tracked grid reference APIs to keep a long-lived reference to a cell as the
+terminal scrolls, detect when that reference loses its meaningful location,
+and move the same tracked handle to a new point.
+
+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-grid-ref-tracked/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_grid_ref_tracked",
+        .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-grid-ref-tracked/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_grid_ref_tracked,
+    .version = "0.0.0",
+    .fingerprint = 0x64bd14b59e76c294,
+    .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-grid-ref-tracked/src/main.c

@@ -0,0 +1,94 @@
+#include <assert.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [grid-ref-tracked]
+static uint32_t codepoint_at_tracked_ref(GhosttyTrackedGridRef tracked) {
+  GhosttyGridRef snapshot = GHOSTTY_INIT_SIZED(GhosttyGridRef);
+  GhosttyResult result = ghostty_tracked_grid_ref_snapshot(tracked, &snapshot);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttyCell cell;
+  result = ghostty_grid_ref_cell(&snapshot, &cell);
+  assert(result == GHOSTTY_SUCCESS);
+
+  bool has_text = false;
+  ghostty_cell_get(cell, GHOSTTY_CELL_DATA_HAS_TEXT, &has_text);
+  assert(has_text);
+
+  uint32_t codepoint = 0;
+  ghostty_cell_get(cell, GHOSTTY_CELL_DATA_CODEPOINT, &codepoint);
+  return codepoint;
+}
+
+int main() {
+  GhosttyTerminal terminal;
+  GhosttyTerminalOptions opts = {
+    .cols = 8,
+    .rows = 3,
+    .max_scrollback = 100,
+  };
+  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  const char *text = "alpha\r\n"
+                     "bravo\r\n"
+                     "charlie";
+  ghostty_terminal_vt_write(
+      terminal, (const uint8_t *)text, strlen(text));
+
+  GhosttyTrackedGridRef tracked = NULL;
+  GhosttyPoint alpha = {
+    .tag = GHOSTTY_POINT_TAG_ACTIVE,
+    .value = { .coordinate = { .x = 0, .y = 0 } },
+  };
+  result = ghostty_terminal_grid_ref_track(terminal, alpha, &tracked);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Writing another line scrolls the original "alpha" row into scrollback.
+  // The tracked ref still follows the same cell.
+  const char *more = "\r\ndelta";
+  ghostty_terminal_vt_write(
+      terminal, (const uint8_t *)more, strlen(more));
+
+  assert(ghostty_tracked_grid_ref_has_value(tracked));
+  printf("tracked codepoint after scroll: %c\n",
+      (char)codepoint_at_tracked_ref(tracked));
+
+  GhosttyPointCoordinate screen = {0};
+  result = ghostty_tracked_grid_ref_point(
+      tracked, GHOSTTY_POINT_TAG_SCREEN, &screen);
+  assert(result == GHOSTTY_SUCCESS);
+  printf("tracked screen point: %u,%u\n", screen.x, screen.y);
+
+  // Resetting the terminal discards the old grid contents. The tracked
+  // handle remains valid, but no longer has a meaningful location.
+  ghostty_terminal_reset(terminal);
+  assert(!ghostty_tracked_grid_ref_has_value(tracked));
+
+  GhosttyGridRef discarded = GHOSTTY_INIT_SIZED(GhosttyGridRef);
+  result = ghostty_tracked_grid_ref_snapshot(tracked, &discarded);
+  assert(result == GHOSTTY_NO_VALUE);
+
+  // The same handle can be moved to a new point after it loses its value.
+  const char *replacement = "echo";
+  ghostty_terminal_vt_write(
+      terminal, (const uint8_t *)replacement, strlen(replacement));
+
+  GhosttyPoint echo = {
+    .tag = GHOSTTY_POINT_TAG_ACTIVE,
+    .value = { .coordinate = { .x = 0, .y = 0 } },
+  };
+  result = ghostty_tracked_grid_ref_set(tracked, terminal, echo);
+  assert(result == GHOSTTY_SUCCESS);
+  assert(ghostty_tracked_grid_ref_has_value(tracked));
+  printf("tracked codepoint after reset/set: %c\n",
+      (char)codepoint_at_tracked_ref(tracked));
+
+  ghostty_tracked_grid_ref_free(tracked);
+  ghostty_terminal_free(terminal);
+  return 0;
+}
+//! [grid-ref-tracked]

example/c-vt-grid-traverse/README.md

@@ -0,0 +1,19 @@
+# Example: `ghostty-vt` Grid Traversal
+
+This contains a simple example of how to use the `ghostty-vt` terminal and
+grid reference APIs to create a terminal, write content into it, and then
+traverse the entire grid cell-by-cell using grid refs to inspect codepoints,
+row state, and styles.
+
+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-grid-traverse/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_grid_traverse",
+        .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-grid-traverse/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_grid_traverse,
+    .version = "0.0.0",
+    .fingerprint = 0xf694dd12db9be040,
+    .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-grid-traverse/src/main.c

@@ -0,0 +1,85 @@
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [grid-ref-traverse]
+int main() {
+  // Create a small terminal
+  GhosttyTerminal terminal;
+  GhosttyTerminalOptions opts = {
+    .cols = 10,
+    .rows = 3,
+    .max_scrollback = 0,
+  };
+  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Write some content so the grid has interesting data
+  const char *text = "Hello!\r\n"    // Row 0: H e l l o !
+                     "World\r\n"     // Row 1: W o r l d
+                     "\033[1mBold";   // Row 2: B o l d (bold style)
+  ghostty_terminal_vt_write(
+      terminal, (const uint8_t *)text, strlen(text));
+
+  // Get terminal dimensions
+  uint16_t cols, rows;
+  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_COLS, &cols);
+  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_ROWS, &rows);
+
+  // Traverse the entire grid using grid refs
+  for (uint16_t row = 0; row < rows; row++) {
+    printf("Row %u: ", row);
+    for (uint16_t col = 0; col < cols; col++) {
+      // Resolve the point to a grid reference
+      GhosttyGridRef ref = GHOSTTY_INIT_SIZED(GhosttyGridRef);
+      GhosttyPoint pt = {
+        .tag = GHOSTTY_POINT_TAG_ACTIVE,
+        .value = { .coordinate = { .x = col, .y = row } },
+      };
+      result = ghostty_terminal_grid_ref(terminal, pt, &ref);
+      assert(result == GHOSTTY_SUCCESS);
+
+      // Read the cell from the grid ref
+      GhosttyCell cell;
+      result = ghostty_grid_ref_cell(&ref, &cell);
+      assert(result == GHOSTTY_SUCCESS);
+
+      // Check if the cell has text
+      bool has_text = false;
+      ghostty_cell_get(cell, GHOSTTY_CELL_DATA_HAS_TEXT, &has_text);
+
+      if (has_text) {
+        uint32_t codepoint = 0;
+        ghostty_cell_get(cell, GHOSTTY_CELL_DATA_CODEPOINT, &codepoint);
+        printf("%c", (char)codepoint);
+      } else {
+        printf(".");
+      }
+    }
+
+    // Also inspect the row for wrap state
+    GhosttyGridRef ref = GHOSTTY_INIT_SIZED(GhosttyGridRef);
+    GhosttyPoint pt = {
+      .tag = GHOSTTY_POINT_TAG_ACTIVE,
+      .value = { .coordinate = { .x = 0, .y = row } },
+    };
+    ghostty_terminal_grid_ref(terminal, pt, &ref);
+
+    GhosttyRow grid_row;
+    ghostty_grid_ref_row(&ref, &grid_row);
+
+    bool wrap = false;
+    ghostty_row_get(grid_row, GHOSTTY_ROW_DATA_WRAP, &wrap);
+    printf(" (wrap=%s", wrap ? "true" : "false");
+
+    // Check the style of the first cell with text
+    GhosttyStyle style = GHOSTTY_INIT_SIZED(GhosttyStyle);
+    ghostty_grid_ref_style(&ref, &style);
+    printf(", bold=%s)\n", style.bold ? "true" : "false");
+  }
+
+  ghostty_terminal_free(terminal);
+  return 0;
+}
+//! [grid-ref-traverse]

example/c-vt-kitty-graphics/README.md

@@ -0,0 +1,18 @@
+# Example: `ghostty-vt` Kitty Graphics Protocol
+
+This contains a simple example of how to use the system interface
+(`ghostty_sys_set`) to install a PNG decoder callback, then send
+a Kitty Graphics Protocol image via `ghostty_terminal_vt_write`.
+
+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-kitty-graphics/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_kitty_graphics",
+        .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-kitty-graphics/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_kitty_graphics,
+    .version = "0.0.0",
+    .fingerprint = 0x432d40ecc8f15589,
+    .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-kitty-graphics/src/main.c

@@ -0,0 +1,232 @@
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [kitty-graphics-decode-png]
+/**
+ * Minimal PNG decoder callback for the sys interface.
+ *
+ * A real implementation would use a PNG library (libpng, stb_image, etc.)
+ * to decode the PNG data. This example uses a hardcoded 1x1 red pixel
+ * since we know exactly what image we're sending.
+ *
+ * WARNING: This is only an example for providing a callback, it DOES NOT 
+ * actually decode the PNG it is passed. It hardcodes a response.
+ */
+bool decode_png(void* userdata,
+                const GhosttyAllocator* allocator,
+                const uint8_t* data,
+                size_t data_len,
+                GhosttySysImage* out) {
+  int* count = (int*)userdata;
+  (*count)++;
+  printf("  decode_png called (size=%zu, call #%d)\n", data_len, *count);
+
+  /* Allocate RGBA pixel data through the provided allocator. */
+  const size_t pixel_len = 4;  /* 1x1 RGBA */
+  uint8_t* pixels = ghostty_alloc(allocator, pixel_len);
+  if (!pixels) return false;
+
+  /* Fill with red (R=255, G=0, B=0, A=255). */
+  pixels[0] = 255;
+  pixels[1] = 0;
+  pixels[2] = 0;
+  pixels[3] = 255;
+
+  out->width = 1;
+  out->height = 1;
+  out->data = pixels;
+  out->data_len = pixel_len;
+  return true;
+}
+//! [kitty-graphics-decode-png]
+
+//! [kitty-graphics-write-pty]
+/**
+ * write_pty callback to capture terminal responses.
+ *
+ * The Kitty graphics protocol sends an APC response back to the pty
+ * when an image is loaded (unless suppressed with q=2).
+ */
+void on_write_pty(GhosttyTerminal terminal,
+                  void* userdata,
+                  const uint8_t* data,
+                  size_t len) {
+  (void)terminal;
+  (void)userdata;
+  printf("  response (%zu bytes): ", len);
+  fwrite(data, 1, len, stdout);
+  printf("\n");
+}
+//! [kitty-graphics-write-pty]
+
+//! [kitty-graphics-main]
+int main() {
+  /* Install the PNG decoder via the sys interface. */
+  int decode_count = 0;
+  ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, &decode_count);
+  ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, (const void*)decode_png);
+
+  /* Create a terminal with Kitty graphics enabled. */
+  GhosttyTerminal terminal = NULL;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 24,
+    .max_scrollback = 0,
+  };
+  if (ghostty_terminal_new(NULL, &terminal, opts) != GHOSTTY_SUCCESS) {
+    fprintf(stderr, "Failed to create terminal\n");
+    return 1;
+  }
+
+  /* Set cell pixel dimensions so kitty graphics can compute grid sizes. */
+  ghostty_terminal_resize(terminal, 80, 24, 8, 16);
+
+  /* Set a storage limit to enable Kitty graphics. */
+  uint64_t storage_limit = 64 * 1024 * 1024;  /* 64 MiB */
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT,
+                       &storage_limit);
+
+  /* Install write_pty to see the protocol response. */
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_WRITE_PTY,
+                       (const void*)on_write_pty);
+
+  /*
+   * Send a Kitty graphics command with an inline 1x1 PNG image.
+   *
+   * The escape sequence is:
+   *   ESC _G a=T,f=100,q=1; <base64 PNG data> ESC \
+   *
+   * Where:
+   *   a=T   — transmit and display
+   *   f=100 — PNG format
+   *   q=1   — request a response (q=0 would suppress it)
+   */
+  printf("Sending Kitty graphics PNG image:\n");
+  const char* kitty_cmd =
+    "\x1b_Ga=T,f=100,q=1;"
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAA"
+    "DUlEQVR4nGP4z8DwHwAFAAH/iZk9HQAAAABJRU5ErkJggg=="
+    "\x1b\\";
+  ghostty_terminal_vt_write(terminal, (const uint8_t*)kitty_cmd,
+                            strlen(kitty_cmd));
+
+  printf("PNG decode calls: %d\n", decode_count);
+
+  /* Query the kitty graphics storage to verify the image was stored. */
+  GhosttyKittyGraphics graphics = NULL;
+  if (ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS,
+                           &graphics) != GHOSTTY_SUCCESS || !graphics) {
+    fprintf(stderr, "Failed to get kitty graphics storage\n");
+    return 1;
+  }
+  printf("\nKitty graphics storage is available.\n");
+
+  /*
+   * The storage-wide generation changes on every image/placement
+   * mutation. Renderers can compare it against the value from the
+   * previous frame: if unchanged, placement iteration and image
+   * staleness checks can be skipped entirely.
+   */
+  uint64_t generation = 0;
+  ghostty_kitty_graphics_get(graphics, GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION,
+                             &generation);
+  printf("Storage generation: %llu\n", (unsigned long long)generation);
+
+  /* Iterate placements to find the image ID. */
+  GhosttyKittyGraphicsPlacementIterator iter = NULL;
+  if (ghostty_kitty_graphics_placement_iterator_new(NULL, &iter) != GHOSTTY_SUCCESS) {
+    fprintf(stderr, "Failed to create placement iterator\n");
+    return 1;
+  }
+  if (ghostty_kitty_graphics_get(graphics,
+          GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR, &iter) != GHOSTTY_SUCCESS) {
+    fprintf(stderr, "Failed to get placement iterator\n");
+    return 1;
+  }
+
+  int placement_count = 0;
+  while (ghostty_kitty_graphics_placement_next(iter)) {
+    placement_count++;
+    uint32_t image_id = 0;
+    uint32_t placement_id = 0;
+    bool is_virtual = false;
+    int32_t z = 0;
+
+    ghostty_kitty_graphics_placement_get_multi(iter, 4,
+        (GhosttyKittyGraphicsPlacementData[]){
+            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID,
+            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_PLACEMENT_ID,
+            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IS_VIRTUAL,
+            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z,
+        },
+        (void*[]){ &image_id, &placement_id, &is_virtual, &z },
+        NULL);
+
+    printf("  placement #%d: image_id=%u placement_id=%u virtual=%s z=%d\n",
+           placement_count, image_id, placement_id,
+           is_virtual ? "true" : "false", z);
+
+    /* Look up the image and print its properties. */
+    GhosttyKittyGraphicsImage image =
+        ghostty_kitty_graphics_image(graphics, image_id);
+    if (!image) {
+      fprintf(stderr, "Failed to look up image %u\n", image_id);
+      return 1;
+    }
+
+    uint32_t width = 0, height = 0, number = 0;
+    GhosttyKittyImageFormat format = 0;
+    size_t data_len = 0;
+    uint64_t image_generation = 0;
+
+    /*
+     * The per-image generation changes on every add/replace of this
+     * image ID, so it detects retransmissions even when the size and
+     * format are unchanged. Texture caches should key staleness on it.
+     */
+    ghostty_kitty_graphics_image_get_multi(image, 6,
+        (GhosttyKittyGraphicsImageData[]){
+            GHOSTTY_KITTY_IMAGE_DATA_NUMBER,
+            GHOSTTY_KITTY_IMAGE_DATA_WIDTH,
+            GHOSTTY_KITTY_IMAGE_DATA_HEIGHT,
+            GHOSTTY_KITTY_IMAGE_DATA_FORMAT,
+            GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN,
+            GHOSTTY_KITTY_IMAGE_DATA_GENERATION,
+        },
+        (void*[]){ &number, &width, &height, &format, &data_len,
+                   &image_generation },
+        NULL);
+
+    printf("    image: number=%u size=%ux%u format=%d data_len=%zu "
+           "generation=%llu\n",
+           number, width, height, format, data_len,
+           (unsigned long long)image_generation);
+
+    /* Compute the rendered pixel size and grid size. */
+    uint32_t px_w = 0, px_h = 0, cols = 0, rows = 0;
+    if (ghostty_kitty_graphics_placement_pixel_size(iter, image, terminal,
+            &px_w, &px_h) == GHOSTTY_SUCCESS) {
+      printf("    rendered pixel size: %ux%u\n", px_w, px_h);
+    }
+    if (ghostty_kitty_graphics_placement_grid_size(iter, image, terminal,
+            &cols, &rows) == GHOSTTY_SUCCESS) {
+      printf("    grid size: %u cols x %u rows\n", cols, rows);
+    }
+  }
+  printf("Total placements: %d\n", placement_count);
+  ghostty_kitty_graphics_placement_iterator_free(iter);
+
+  /* Clean up. */
+  ghostty_terminal_free(terminal);
+
+  /* Clear the sys callbacks. */
+  ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, NULL);
+  ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, NULL);
+
+  return 0;
+}
+//! [kitty-graphics-main]

example/c-vt-modes/README.md

@@ -0,0 +1,18 @@
+# Example: `ghostty-vt` Mode Utilities
+
+This contains a simple example of how to use the `ghostty-vt` mode
+utilities to pack and unpack terminal mode identifiers and encode
+DECRPM responses.
+
+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-modes/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_modes",
+        .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-modes/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_modes,
+    .version = "0.0.0",
+    .fingerprint = 0x67ce079ebc70a02a,
+    .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-modes/src/main.c

@@ -0,0 +1,45 @@
+#include <stdio.h>
+#include <ghostty/vt.h>
+
+//! [modes-pack-unpack]
+void modes_example() {
+  // Create a mode for DEC mode 25 (cursor visible)
+  GhosttyMode tag = ghostty_mode_new(25, false);
+  printf("value=%u ansi=%d packed=0x%04x\n",
+      ghostty_mode_value(tag),
+      ghostty_mode_ansi(tag),
+      tag);
+
+  // Create a mode for ANSI mode 4 (insert mode)
+  GhosttyMode ansi_tag = ghostty_mode_new(4, true);
+  printf("value=%u ansi=%d packed=0x%04x\n",
+      ghostty_mode_value(ansi_tag),
+      ghostty_mode_ansi(ansi_tag),
+      ansi_tag);
+}
+//! [modes-pack-unpack]
+
+//! [modes-decrpm]
+void decrpm_example() {
+  char buf[32];
+  size_t written = 0;
+
+  // Encode a report that DEC mode 25 (cursor visible) is set
+  GhosttyResult result = ghostty_mode_report_encode(
+      GHOSTTY_MODE_CURSOR_VISIBLE,
+      GHOSTTY_MODE_REPORT_SET,
+      buf, sizeof(buf), &written);
+
+  if (result == GHOSTTY_SUCCESS) {
+    printf("Encoded %zu bytes: ", written);
+    fwrite(buf, 1, written, stdout);
+    printf("\n");  // prints: ESC[?25;1$y
+  }
+}
+//! [modes-decrpm]
+
+int main() {
+  modes_example();
+  decrpm_example();
+  return 0;
+}

example/c-vt-paste/README.md

@@ -0,0 +1,17 @@
+# Example: `ghostty-vt` Paste Utilities
+
+This contains a simple example of how to use the `ghostty-vt` paste
+utilities to check if paste data is safe and encode it for terminal input.
+
+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-paste/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_paste",
+        .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-paste/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_paste,
+    .version = "0.0.0",
+    .fingerprint = 0xa105002abbc8cf74,
+    .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-paste/src/main.c

@@ -0,0 +1,56 @@
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [paste-safety]
+void safety_example() {
+  const char* safe_data = "hello world";
+  const char* unsafe_data = "rm -rf /\n";
+
+  if (ghostty_paste_is_safe(safe_data, strlen(safe_data))) {
+    printf("Safe to paste\n");
+  }
+
+  if (!ghostty_paste_is_safe(unsafe_data, strlen(unsafe_data))) {
+    printf("Unsafe! Contains newline\n");
+  }
+}
+//! [paste-safety]
+
+//! [paste-encode]
+void encode_example() {
+  // The input buffer is modified in place (unsafe bytes are stripped).
+  char data[] = "hello\nworld";
+  char buf[64];
+  size_t written = 0;
+
+  GhosttyResult result = ghostty_paste_encode(
+      data, strlen(data), true, buf, sizeof(buf), &written);
+
+  if (result == GHOSTTY_SUCCESS) {
+    printf("Encoded %zu bytes: ", written);
+    fwrite(buf, 1, written, stdout);
+    printf("\n");
+  }
+}
+//! [paste-encode]
+
+int main() {
+  safety_example();
+
+  // Test unsafe paste data with bracketed paste end sequence
+  const char *unsafe_escape = "evil\x1b[201~code";
+  if (!ghostty_paste_is_safe(unsafe_escape, strlen(unsafe_escape))) {
+    printf("Data with escape sequence is UNSAFE\n");
+  }
+
+  // Test empty data
+  const char *empty_data = "";
+  if (ghostty_paste_is_safe(empty_data, 0)) {
+    printf("Empty data is safe\n");
+  }
+
+  encode_example();
+
+  return 0;
+}

example/c-vt-render/README.md

@@ -0,0 +1,19 @@
+# Example: `ghostty-vt` Render State
+
+This contains an example of how to use the `ghostty-vt` render-state API
+to create a render state, update it from terminal content, iterate rows
+and cells, read styles and colors, inspect cursor and row-local selection
+state, and manage dirty tracking.
+
+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-render/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_render",
+        .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-render/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_render,
+    .version = "0.0.0",
+    .fingerprint = 0xb10e18b2fab773c9,
+    .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-render/src/main.c

@@ -0,0 +1,272 @@
+#include <assert.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+/// Helper: resolve a style color to an RGB value using the palette.
+static GhosttyColorRgb resolve_color(GhosttyStyleColor color,
+                                     const GhosttyRenderStateColors* colors,
+                                     GhosttyColorRgb fallback) {
+  switch (color.tag) {
+    case GHOSTTY_STYLE_COLOR_RGB:
+      return color.value.rgb;
+    case GHOSTTY_STYLE_COLOR_PALETTE:
+      return colors->palette[color.value.palette];
+    default:
+      return fallback;
+  }
+}
+
+int main(void) {
+  GhosttyResult result;
+
+  //! [render-state-update]
+  // Create a terminal and render state, then update the render state
+  // from the terminal. The render state captures a snapshot of everything
+  // needed to draw a frame.
+  GhosttyTerminal terminal = NULL;
+  GhosttyTerminalOptions terminal_opts = {
+      .cols = 40,
+      .rows = 5,
+      .max_scrollback = 10000,
+  };
+  result = ghostty_terminal_new(NULL, &terminal, terminal_opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttyRenderState render_state = NULL;
+  result = ghostty_render_state_new(NULL, &render_state);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Feed some styled content into the terminal.
+  const char* content =
+      "Hello, \033[1;32mworld\033[0m!\r\n"     // bold green "world"
+      "\033[4munderlined\033[0m text\r\n"       // underlined text
+      "\033[38;2;255;128;0morange\033[0m\r\n";  // 24-bit orange fg
+  ghostty_terminal_vt_write(
+      terminal, (const uint8_t*)content, strlen(content));
+
+  // Select "underlined" on the second row. Render state exposes this
+  // later as a row-local selected cell range.
+  GhosttyGridRef selection_start = GHOSTTY_INIT_SIZED(GhosttyGridRef);
+  GhosttyPoint selection_start_pt = {
+      .tag = GHOSTTY_POINT_TAG_ACTIVE,
+      .value = { .coordinate = { .x = 0, .y = 1 } },
+  };
+  result = ghostty_terminal_grid_ref(
+      terminal, selection_start_pt, &selection_start);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttyGridRef selection_end = GHOSTTY_INIT_SIZED(GhosttyGridRef);
+  GhosttyPoint selection_end_pt = {
+      .tag = GHOSTTY_POINT_TAG_ACTIVE,
+      .value = { .coordinate = { .x = 9, .y = 1 } },
+  };
+  result = ghostty_terminal_grid_ref(terminal, selection_end_pt, &selection_end);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttySelection selection = GHOSTTY_INIT_SIZED(GhosttySelection);
+  selection.start = selection_start;
+  selection.end = selection_end;
+  result = ghostty_terminal_set(
+      terminal, GHOSTTY_TERMINAL_OPT_SELECTION, &selection);
+  assert(result == GHOSTTY_SUCCESS);
+
+  result = ghostty_render_state_update(render_state, terminal);
+  assert(result == GHOSTTY_SUCCESS);
+  //! [render-state-update]
+
+  //! [render-dirty-check]
+  // Check the global dirty state to decide how much work the renderer
+  // needs to do. After rendering, reset it to false.
+  GhosttyRenderStateDirty dirty;
+  result = ghostty_render_state_get(
+      render_state, GHOSTTY_RENDER_STATE_DATA_DIRTY, &dirty);
+  assert(result == GHOSTTY_SUCCESS);
+
+  switch (dirty) {
+    case GHOSTTY_RENDER_STATE_DIRTY_FALSE:
+      printf("Frame is clean, nothing to draw.\n");
+      break;
+    case GHOSTTY_RENDER_STATE_DIRTY_PARTIAL:
+      printf("Partial redraw needed.\n");
+      break;
+    case GHOSTTY_RENDER_STATE_DIRTY_FULL:
+      printf("Full redraw needed.\n");
+      break;
+  }
+  //! [render-dirty-check]
+
+  //! [render-colors]
+  // Retrieve colors (background, foreground, palette) from the render
+  // state. These are needed to resolve palette-indexed cell colors.
+  GhosttyRenderStateColors colors =
+      GHOSTTY_INIT_SIZED(GhosttyRenderStateColors);
+  result = ghostty_render_state_colors_get(render_state, &colors);
+  assert(result == GHOSTTY_SUCCESS);
+
+  printf("Background: #%02x%02x%02x\n",
+         colors.background.r, colors.background.g, colors.background.b);
+  printf("Foreground: #%02x%02x%02x\n",
+         colors.foreground.r, colors.foreground.g, colors.foreground.b);
+  //! [render-colors]
+
+  //! [render-cursor]
+  // Read cursor position and visual style from the render state.
+  bool cursor_visible = false;
+  ghostty_render_state_get(
+      render_state, GHOSTTY_RENDER_STATE_DATA_CURSOR_VISIBLE,
+      &cursor_visible);
+
+  bool cursor_in_viewport = false;
+  ghostty_render_state_get(
+      render_state, GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_HAS_VALUE,
+      &cursor_in_viewport);
+
+  if (cursor_visible && cursor_in_viewport) {
+    uint16_t cx, cy;
+    ghostty_render_state_get(
+        render_state, GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_X, &cx);
+    ghostty_render_state_get(
+        render_state, GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_Y, &cy);
+
+    GhosttyRenderStateCursorVisualStyle style;
+    ghostty_render_state_get(
+        render_state, GHOSTTY_RENDER_STATE_DATA_CURSOR_VISUAL_STYLE,
+        &style);
+
+    const char* style_name = "unknown";
+    switch (style) {
+      case GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BAR:
+        style_name = "bar";
+        break;
+      case GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK:
+        style_name = "block";
+        break;
+      case GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_UNDERLINE:
+        style_name = "underline";
+        break;
+      case GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK_HOLLOW:
+        style_name = "hollow";
+        break;
+    }
+    printf("Cursor at (%u, %u), style: %s\n", cx, cy, style_name);
+  }
+  //! [render-cursor]
+
+  //! [render-row-iterate]
+  // Iterate rows via the row iterator. For each dirty row, iterate its
+  // cells, read codepoints/graphemes and styles, and emit ANSI-colored
+  // output as a simple "renderer".
+  GhosttyRenderStateRowIterator row_iter = NULL;
+  result = ghostty_render_state_row_iterator_new(NULL, &row_iter);
+  assert(result == GHOSTTY_SUCCESS);
+
+  result = ghostty_render_state_get(
+      render_state, GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR, &row_iter);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttyRenderStateRowCells cells = NULL;
+  result = ghostty_render_state_row_cells_new(NULL, &cells);
+  assert(result == GHOSTTY_SUCCESS);
+
+  int row_index = 0;
+  while (ghostty_render_state_row_iterator_next(row_iter)) {
+    // Check per-row dirty state; a real renderer would skip clean rows.
+    bool row_dirty = false;
+    ghostty_render_state_row_get(
+        row_iter, GHOSTTY_RENDER_STATE_ROW_DATA_DIRTY, &row_dirty);
+
+    printf("Row %2d [%s]: ", row_index,
+           row_dirty ? "dirty" : "clean");
+
+    // Query the row-local selection range. Rows without a selection return
+    // GHOSTTY_NO_VALUE; selected rows return inclusive start/end columns.
+    GhosttyRenderStateRowSelection row_selection =
+        GHOSTTY_INIT_SIZED(GhosttyRenderStateRowSelection);
+    result = ghostty_render_state_row_get(
+        row_iter, GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION, &row_selection);
+    assert(result == GHOSTTY_SUCCESS || result == GHOSTTY_NO_VALUE);
+    if (result == GHOSTTY_SUCCESS) {
+      printf("selection=%u..%u ",
+             row_selection.start_x, row_selection.end_x);
+    }
+
+    // Get cells for this row (reuses the same cells handle).
+    result = ghostty_render_state_row_get(
+        row_iter, GHOSTTY_RENDER_STATE_ROW_DATA_CELLS, &cells);
+    assert(result == GHOSTTY_SUCCESS);
+
+    while (ghostty_render_state_row_cells_next(cells)) {
+      // Get the grapheme length; 0 means the cell is empty.
+      uint32_t grapheme_len = 0;
+      ghostty_render_state_row_cells_get(
+          cells, GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_LEN,
+          &grapheme_len);
+
+      if (grapheme_len == 0) {
+        putchar(' ');
+        continue;
+      }
+
+      // Read the style for this cell. Returns the default style for
+      // cells that have no explicit styling.
+      GhosttyStyle style = GHOSTTY_INIT_SIZED(GhosttyStyle);
+      ghostty_render_state_row_cells_get(
+          cells, GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_STYLE, &style);
+
+      // Resolve foreground color for this cell.
+      GhosttyColorRgb fg =
+          resolve_color(style.fg_color, &colors, colors.foreground);
+
+      // Emit ANSI true-color escape for the foreground.
+      printf("\033[38;2;%u;%u;%um", fg.r, fg.g, fg.b);
+      if (style.bold) printf("\033[1m");
+      if (style.underline) printf("\033[4m");
+
+      // Read grapheme codepoints into a buffer and print them.
+      // The buffer must be at least grapheme_len elements.
+      uint32_t codepoints[16];
+      uint32_t len = grapheme_len < 16 ? grapheme_len : 16;
+      ghostty_render_state_row_cells_get(
+          cells, GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_BUF,
+          codepoints);
+
+      for (uint32_t i = 0; i < len; i++) {
+        // Simple ASCII print; a real renderer would handle UTF-8.
+        if (codepoints[i] < 128)
+          putchar((char)codepoints[i]);
+        else
+          printf("U+%04X", codepoints[i]);
+      }
+
+      printf("\033[0m");  // Reset style after each cell.
+    }
+
+    printf("\n");
+
+    // Clear per-row dirty flag after "rendering" it.
+    bool clean = false;
+    ghostty_render_state_row_set(
+        row_iter, GHOSTTY_RENDER_STATE_ROW_OPTION_DIRTY, &clean);
+
+    row_index++;
+  }
+  //! [render-row-iterate]
+
+  //! [render-dirty-reset]
+  // After finishing the frame, reset the global dirty state so the next
+  // update can report changes accurately.
+  GhosttyRenderStateDirty clean_state = GHOSTTY_RENDER_STATE_DIRTY_FALSE;
+  result = ghostty_render_state_set(
+      render_state, GHOSTTY_RENDER_STATE_OPTION_DIRTY, &clean_state);
+  assert(result == GHOSTTY_SUCCESS);
+  //! [render-dirty-reset]
+
+  // Cleanup
+  ghostty_render_state_row_cells_free(cells);
+  ghostty_render_state_row_iterator_free(row_iter);
+  ghostty_render_state_free(render_state);
+  ghostty_terminal_free(terminal);
+  return 0;
+}

example/c-vt-selection-gesture/README.md

@@ -0,0 +1,18 @@
+# Example: `ghostty-vt` Selection Gestures
+
+This contains a simple example of how to use the `ghostty-vt` selection
+gesture API from C. It creates synthetic press, drag, release, and deep-press
+events and formats the resulting selection snapshots.
+
+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-selection-gesture/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_selection_gesture",
+        .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-selection-gesture/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_selection_gesture,
+    .version = "0.0.0",
+    .fingerprint = 0x5a4e72d27b582404,
+    .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-selection-gesture/src/main.c

@@ -0,0 +1,162 @@
+#include <assert.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [selection-gesture-main]
+static void vt_write(GhosttyTerminal terminal, const char *s) {
+  ghostty_terminal_vt_write(terminal, (const uint8_t *)s, strlen(s));
+}
+
+static GhosttyGridRef ref_at(GhosttyTerminal terminal, uint16_t x, uint16_t y) {
+  GhosttyGridRef ref = GHOSTTY_INIT_SIZED(GhosttyGridRef);
+  GhosttyPoint point = {
+    .tag = GHOSTTY_POINT_TAG_ACTIVE,
+    .value = { .coordinate = { .x = x, .y = y } },
+  };
+
+  GhosttyResult result = ghostty_terminal_grid_ref(terminal, point, &ref);
+  assert(result == GHOSTTY_SUCCESS);
+  return ref;
+}
+
+static void print_selection(
+    GhosttyTerminal terminal,
+    const char *label,
+    const GhosttySelection *selection) {
+  GhosttyTerminalSelectionFormatOptions opts =
+      GHOSTTY_INIT_SIZED(GhosttyTerminalSelectionFormatOptions);
+  opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
+  opts.trim = true;
+  opts.selection = selection;
+
+  uint8_t *buf = NULL;
+  size_t len = 0;
+  GhosttyResult result = ghostty_terminal_selection_format_alloc(
+      terminal, NULL, opts, &buf, &len);
+  assert(result == GHOSTTY_SUCCESS);
+
+  printf("%s: ", label);
+  fwrite(buf, 1, len, stdout);
+  printf("\n");
+
+  ghostty_free(NULL, buf, len);
+}
+
+static GhosttySelectionGestureEvent new_event(
+    GhosttySelectionGestureEventType type) {
+  GhosttySelectionGestureEvent event = NULL;
+  GhosttyResult result = ghostty_selection_gesture_event_new(NULL, &event, type);
+  assert(result == GHOSTTY_SUCCESS);
+  return event;
+}
+
+int main() {
+  GhosttyTerminal terminal;
+  GhosttyTerminalOptions opts = {
+    .cols = 20,
+    .rows = 4,
+    .max_scrollback = 100,
+  };
+  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  vt_write(terminal, "hello world\r\nsecond line");
+
+  GhosttySelectionGesture gesture = NULL;
+  result = ghostty_selection_gesture_new(NULL, &gesture);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttySelectionGestureEvent press =
+      new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS);
+  GhosttySelectionGestureEvent drag =
+      new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG);
+  GhosttySelectionGestureEvent release =
+      new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE);
+  GhosttySelectionGestureEvent deep_press =
+      new_event(GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS);
+
+  GhosttySelectionGestureGeometry geometry = {
+    .columns = 20,
+    .cell_width = 10,
+    .padding_left = 0,
+    .screen_height = 40,
+  };
+
+  // Press in the first cell. A normal single press records the click anchor but
+  // doesn't produce a selection yet, so we discard the optional output.
+  GhosttyGridRef press_ref = ref_at(terminal, 0, 0);
+  result = ghostty_selection_gesture_event_set(
+      press, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF, &press_ref);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttySurfacePosition press_pos = { .x = 2, .y = 8 };
+  result = ghostty_selection_gesture_event_set(
+      press, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION, &press_pos);
+  assert(result == GHOSTTY_SUCCESS);
+
+  result = ghostty_selection_gesture_event(
+      gesture, terminal, press, NULL);
+  assert(result == GHOSTTY_NO_VALUE);
+
+  // Drag across "hello". The drag event returns a selection snapshot that the
+  // embedder can apply to its UI, copy, or format immediately.
+  GhosttyGridRef drag_ref = ref_at(terminal, 4, 0);
+  result = ghostty_selection_gesture_event_set(
+      drag, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF, &drag_ref);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttySurfacePosition drag_pos = { .x = 46, .y = 8 };
+  result = ghostty_selection_gesture_event_set(
+      drag, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION, &drag_pos);
+  assert(result == GHOSTTY_SUCCESS);
+
+  result = ghostty_selection_gesture_event_set(
+      drag, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY, &geometry);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttySelection selection = GHOSTTY_INIT_SIZED(GhosttySelection);
+  result = ghostty_selection_gesture_event(
+      gesture, terminal, drag, &selection);
+  assert(result == GHOSTTY_SUCCESS);
+  print_selection(terminal, "drag", &selection);
+
+  // Release updates gesture state but never produces a selection.
+  result = ghostty_selection_gesture_event_set(
+      release, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF, &drag_ref);
+  assert(result == GHOSTTY_SUCCESS);
+  result = ghostty_selection_gesture_event(
+      gesture, terminal, release, NULL);
+  assert(result == GHOSTTY_NO_VALUE);
+
+  bool dragged = false;
+  result = ghostty_selection_gesture_get(
+      gesture, terminal, GHOSTTY_SELECTION_GESTURE_DATA_DRAGGED, &dragged);
+  assert(result == GHOSTTY_SUCCESS);
+  printf("dragged: %s\n", dragged ? "true" : "false");
+
+  // Deep press uses the active click anchor to select the surrounding word.
+  ghostty_selection_gesture_reset(gesture, terminal);
+  GhosttyGridRef world_ref = ref_at(terminal, 6, 0);
+  result = ghostty_selection_gesture_event_set(
+      press, GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF, &world_ref);
+  assert(result == GHOSTTY_SUCCESS);
+  result = ghostty_selection_gesture_event(
+      gesture, terminal, press, NULL);
+  assert(result == GHOSTTY_NO_VALUE);
+
+  result = ghostty_selection_gesture_event(
+      gesture, terminal, deep_press, &selection);
+  assert(result == GHOSTTY_SUCCESS);
+  print_selection(terminal, "deep press", &selection);
+
+  ghostty_selection_gesture_event_free(deep_press);
+  ghostty_selection_gesture_event_free(release);
+  ghostty_selection_gesture_event_free(drag);
+  ghostty_selection_gesture_event_free(press);
+  ghostty_selection_gesture_free(gesture, terminal);
+  ghostty_terminal_free(terminal);
+  return 0;
+}
+//! [selection-gesture-main]

example/c-vt-selection/README.md

@@ -0,0 +1,18 @@
+# Example: `ghostty-vt` Selection
+
+This contains a simple example of how to use the `ghostty-vt` terminal,
+grid reference, selection, and formatter APIs to derive selections such as a
+word, semantic command line, command output, and all visible content.
+
+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-selection/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_selection",
+        .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-selection/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_selection,
+    .version = "0.0.0",
+    .fingerprint = 0xb2c2f1a828086fef,
+    .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-selection/src/main.c

@@ -0,0 +1,136 @@
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [selection-main]
+static void vt_write(GhosttyTerminal terminal, const char *s) {
+  ghostty_terminal_vt_write(terminal, (const uint8_t *)s, strlen(s));
+}
+
+static GhosttyGridRef ref_at(GhosttyTerminal terminal, uint16_t x, uint16_t y) {
+  GhosttyGridRef ref = GHOSTTY_INIT_SIZED(GhosttyGridRef);
+  GhosttyPoint point = {
+    .tag = GHOSTTY_POINT_TAG_ACTIVE,
+    .value = { .coordinate = { .x = x, .y = y } },
+  };
+
+  GhosttyResult result = ghostty_terminal_grid_ref(terminal, point, &ref);
+  assert(result == GHOSTTY_SUCCESS);
+  return ref;
+}
+
+static void print_selection(
+    GhosttyTerminal terminal,
+    const char *label,
+    const GhosttySelection *selection) {
+  GhosttyFormatterTerminalOptions opts = GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
+  opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
+  opts.trim = true;
+  opts.selection = selection;
+
+  GhosttyFormatter formatter;
+  GhosttyResult result = ghostty_formatter_terminal_new(
+      NULL, &formatter, terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  uint8_t *buf = NULL;
+  size_t len = 0;
+  result = ghostty_formatter_format_alloc(formatter, NULL, &buf, &len);
+  assert(result == GHOSTTY_SUCCESS);
+
+  printf("%s: ", label);
+  fwrite(buf, 1, len, stdout);
+  printf("\n");
+
+  ghostty_free(NULL, buf, len);
+  ghostty_formatter_free(formatter);
+}
+
+int main() {
+  GhosttyTerminal terminal;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 8,
+    .max_scrollback = 0,
+  };
+  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // A realistic shell transcript with OSC 133 semantic prompt markers.
+  // Ghostty uses these markers to distinguish prompt/input from command
+  // output for semantic line and output selections.
+  vt_write(terminal,
+      "\033]133;A\007$ "           // Prompt starts: "$ "
+      "\033]133;B\007git status"  // Input starts: "git status"
+      "\033]133;C\007\r\n"        // Output starts after Enter
+      "On branch main\r\n"
+      "nothing to commit, working tree clean");
+
+  GhosttySelection selection = GHOSTTY_INIT_SIZED(GhosttySelection);
+
+  // Double-click style word selection under the cursor.
+  GhosttyTerminalSelectWordOptions word = GHOSTTY_INIT_SIZED(GhosttyTerminalSelectWordOptions);
+  word.ref = ref_at(terminal, 6, 0); // the "status" in "git status"
+  result = ghostty_terminal_select_word(terminal, &word, &selection);
+  assert(result == GHOSTTY_SUCCESS);
+  print_selection(terminal, "word", &selection);
+
+  //! [selection-word-between]
+  // Double-click-and-drag style selection. Suppose the user double-clicks
+  // "git" and drags to "status". The pointer may pass over whitespace, so
+  // select the nearest word between the original click and current drag point
+  // in both directions, then combine the outer word bounds.
+  GhosttyGridRef click_ref = ref_at(terminal, 2, 0); // the "git" in "git status"
+  GhosttyGridRef drag_ref = ref_at(terminal, 6, 0);  // the "status" in "git status"
+
+  GhosttyTerminalSelectWordBetweenOptions start_word_opts =
+      GHOSTTY_INIT_SIZED(GhosttyTerminalSelectWordBetweenOptions);
+  start_word_opts.start = click_ref;
+  start_word_opts.end = drag_ref;
+
+  GhosttySelection start_word = GHOSTTY_INIT_SIZED(GhosttySelection);
+  result = ghostty_terminal_select_word_between(
+      terminal, &start_word_opts, &start_word);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttyTerminalSelectWordBetweenOptions end_word_opts =
+      GHOSTTY_INIT_SIZED(GhosttyTerminalSelectWordBetweenOptions);
+  end_word_opts.start = drag_ref;
+  end_word_opts.end = click_ref;
+
+  GhosttySelection end_word = GHOSTTY_INIT_SIZED(GhosttySelection);
+  result = ghostty_terminal_select_word_between(
+      terminal, &end_word_opts, &end_word);
+  assert(result == GHOSTTY_SUCCESS);
+
+  GhosttySelection drag_selection = GHOSTTY_INIT_SIZED(GhosttySelection);
+  drag_selection.start = start_word.start;
+  drag_selection.end = end_word.end;
+  print_selection(terminal, "double-click drag", &drag_selection);
+  //! [selection-word-between]
+
+  // Triple-click style line selection. With semantic prompt boundaries enabled,
+  // this selects only the input area rather than the leading "$ " prompt.
+  GhosttyTerminalSelectLineOptions line = GHOSTTY_INIT_SIZED(GhosttyTerminalSelectLineOptions);
+  line.ref = ref_at(terminal, 2, 0); // the "git status" input area
+  line.semantic_prompt_boundary = true;
+  result = ghostty_terminal_select_line(terminal, &line, &selection);
+  assert(result == GHOSTTY_SUCCESS);
+  print_selection(terminal, "line", &selection);
+
+  // Select exactly the command output for the command under the cursor.
+  result = ghostty_terminal_select_output(
+      terminal, ref_at(terminal, 0, 1), &selection);
+  assert(result == GHOSTTY_SUCCESS);
+  print_selection(terminal, "output", &selection);
+
+  // Select all visible content.
+  result = ghostty_terminal_select_all(terminal, &selection);
+  assert(result == GHOSTTY_SUCCESS);
+  print_selection(terminal, "all", &selection);
+
+  ghostty_terminal_free(terminal);
+  return 0;
+}
+//! [selection-main]

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,164 @@
+#include <assert.h>
+#include <stdio.h>
+#include <ghostty/vt.h>
+
+//! [sgr-basic]
+void basic_example() {
+  // Create parser
+  GhosttySgrParser parser;
+  GhosttyResult result = ghostty_sgr_new(NULL, &parser);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // Parse "bold, red foreground" sequence: ESC[1;31m
+  uint16_t params[] = {1, 31};
+  result = ghostty_sgr_set_params(parser, params, NULL, 2);
+  assert(result == GHOSTTY_SUCCESS);
+
+  // 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\n", attr.value.fg_8);
+        break;
+      default:
+        break;
+    }
+  }
+
+  // Cleanup
+  ghostty_sgr_free(parser);
+}
+//! [sgr-basic]
+
+void advanced_example() {
+  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("\nParsing 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");
+
+  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);
+  ghostty_sgr_free(parser);
+}
+
+int main() {
+  basic_example();
+  advanced_example();
+  return 0;
+}

example/c-vt-size-report/README.md

@@ -0,0 +1,17 @@
+# Example: `ghostty-vt` Size Report Encoding
+
+This contains a simple example of how to use the `ghostty-vt` size report
+encoding API to encode terminal size reports into escape sequences.
+
+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-size-report/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_size_report",
+        .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-size-report/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_size_report,
+    .version = "0.0.0",
+    .fingerprint = 0x17e8cdb658fab232,
+    .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-size-report/src/main.c

@@ -0,0 +1,27 @@
+#include <stdio.h>
+#include <ghostty/vt.h>
+
+//! [size-report-encode]
+int main() {
+  GhosttySizeReportSize size = {
+    .rows = 24,
+    .columns = 80,
+    .cell_width = 9,
+    .cell_height = 18,
+  };
+
+  char buf[64];
+  size_t written = 0;
+
+  GhosttyResult result = ghostty_size_report_encode(
+      GHOSTTY_SIZE_REPORT_MODE_2048, size, buf, sizeof(buf), &written);
+
+  if (result == GHOSTTY_SUCCESS) {
+    printf("Encoded %zu bytes: ", written);
+    fwrite(buf, 1, written, stdout);
+    printf("\n");
+  }
+
+  return 0;
+}
+//! [size-report-encode]

example/c-vt-static/README.md

@@ -0,0 +1,18 @@
+# Example: `ghostty-vt` Static Linking
+
+This contains a simple example of how to statically link the `ghostty-vt`
+C library with a C program using the `ghostty-vt-static` artifact. It is
+otherwise identical to the `c-vt` example.
+
+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-static/build.zig

@@ -0,0 +1,44 @@
+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| {
+        // Use "ghostty-vt-static" for static linking instead of
+        // "ghostty-vt" which provides a shared library.
+        exe_mod.linkLibrary(dep.artifact("ghostty-vt-static"));
+    }
+
+    // Exe
+    const exe = b.addExecutable(.{
+        .name = "c_vt_static",
+        .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-static/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_static,
+    .version = "0.0.0",
+    .fingerprint = 0xa592a9fdd5d87ed2,
+    .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-static/src/main.c

@@ -0,0 +1,36 @@
+#include <stddef.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+int main() {
+  GhosttyOscParser parser;
+  if (ghostty_osc_new(NULL, &parser) != GHOSTTY_SUCCESS) {
+    return 1;
+  }
+  
+  // Setup change window title command to change the title to "hello"
+  ghostty_osc_next(parser, '0');
+  ghostty_osc_next(parser, ';');
+  const char *title = "hello";
+  for (size_t i = 0; i < strlen(title); i++) {
+    ghostty_osc_next(parser, title[i]);
+  }
+  
+  // End parsing and get command
+  GhosttyOscCommand command = ghostty_osc_end(parser, 0);
+  
+  // Get and print command type
+  GhosttyOscCommandType type = ghostty_osc_command_type(command);
+  printf("Command type: %d\n", type);
+  
+  // Extract and print the title
+  if (ghostty_osc_command_data(command, GHOSTTY_OSC_DATA_CHANGE_WINDOW_TITLE_STR, &title)) {
+    printf("Extracted title: %s\n", title);
+  } else {
+    printf("Failed to extract title\n");
+  }
+  
+  ghostty_osc_free(parser);
+  return 0;
+}

example/c-vt-stream/README.md

@@ -0,0 +1,19 @@
+# Example: VT Stream Processing in C
+
+This contains a simple example of how to use `ghostty_terminal_vt_write`
+to parse and process VT sequences in C. This is the C equivalent of
+the `zig-vt-stream` example, ideal for read-only terminal applications
+such as replay tooling, CI log viewers, and PaaS builder output.
+
+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-stream/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_stream",
+        .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-stream/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt_stream,
+    .version = "0.0.0",
+    .fingerprint = 0xd5bb3fc45e3f4dfc,
+    .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-stream/src/main.c

@@ -0,0 +1,74 @@
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+int main(void) {
+  //! [vt-stream-init]
+  // Create a terminal
+  GhosttyTerminal terminal;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 24,
+    .max_scrollback = 0,
+  };
+  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
+  assert(result == GHOSTTY_SUCCESS);
+  //! [vt-stream-init]
+
+  //! [vt-stream-write]
+  // Feed VT data into the terminal
+  const char *text = "Hello, World!\r\n";
+  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
+
+  // ANSI color codes: ESC[1;32m = bold green, ESC[0m = reset
+  text = "\x1b[1;32mGreen Text\x1b[0m\r\n";
+  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
+
+  // Cursor positioning: ESC[1;1H = move to row 1, column 1
+  text = "\x1b[1;1HTop-left corner\r\n";
+  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
+
+  // Cursor movement: ESC[5B = move down 5 lines
+  text = "\x1b[5B";
+  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
+  text = "Moved down!\r\n";
+  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
+
+  // Erase line: ESC[2K = clear entire line
+  text = "\x1b[2K";
+  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
+  text = "New content\r\n";
+  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
+
+  // Multiple lines
+  text = "Line A\r\nLine B\r\nLine C\r\n";
+  ghostty_terminal_vt_write(terminal, (const uint8_t *)text, strlen(text));
+  //! [vt-stream-write]
+
+  //! [vt-stream-read]
+  // Get the final terminal state as a plain string using the formatter
+  GhosttyFormatterTerminalOptions fmt_opts =
+      GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
+  fmt_opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
+  fmt_opts.trim = true;
+
+  GhosttyFormatter formatter;
+  result = ghostty_formatter_terminal_new(NULL, &formatter, terminal, fmt_opts);
+  assert(result == GHOSTTY_SUCCESS);
+
+  uint8_t *buf = NULL;
+  size_t len = 0;
+  result = ghostty_formatter_format_alloc(formatter, NULL, &buf, &len);
+  assert(result == GHOSTTY_SUCCESS);
+
+  fwrite(buf, 1, len, stdout);
+  printf("\n");
+
+  ghostty_free(NULL, buf, len);
+  ghostty_formatter_free(formatter);
+  //! [vt-stream-read]
+
+  ghostty_terminal_free(terminal);
+  return 0;
+}

example/c-vt/README.md

@@ -0,0 +1,17 @@
+# Example: `ghostty-vt` C Program
+
+This contains a simple example of how to use the `ghostty-vt` C library
+with a C program.
+
+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/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",
+        .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/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .c_vt,
+    .version = "0.0.0",
+    .fingerprint = 0x413a8529b1255f9a,
+    .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/src/main.c

@@ -0,0 +1,36 @@
+#include <stddef.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+int main() {
+  GhosttyOscParser parser;
+  if (ghostty_osc_new(NULL, &parser) != GHOSTTY_SUCCESS) {
+    return 1;
+  }
+  
+  // Setup change window title command to change the title to "hello"
+  ghostty_osc_next(parser, '0');
+  ghostty_osc_next(parser, ';');
+  const char *title = "hello";
+  for (size_t i = 0; i < strlen(title); i++) {
+    ghostty_osc_next(parser, title[i]);
+  }
+  
+  // End parsing and get command
+  GhosttyOscCommand command = ghostty_osc_end(parser, 0);
+  
+  // Get and print command type
+  GhosttyOscCommandType type = ghostty_osc_command_type(command);
+  printf("Command type: %d\n", type);
+  
+  // Extract and print the title
+  if (ghostty_osc_command_data(command, GHOSTTY_OSC_DATA_CHANGE_WINDOW_TITLE_STR, &title)) {
+    printf("Extracted title: %s\n", title);
+  } else {
+    printf("Failed to extract title\n");
+  }
+  
+  ghostty_osc_free(parser);
+  return 0;
+}