docs: extract inline code examples into standalone projects

Extract inline @code blocks from vt headers (size_report.h, modes.h,
sgr.h, paste.h, mouse.h, key.h) into standalone buildable examples
under example/. Each header now uses Doxygen @snippet tags to include
code from the example source files, keeping documentation in sync
with code that is verified to compile and run.

New example projects: c-vt-size-report and c-vt-modes. Existing
examples (c-vt-sgr, c-vt-paste, c-vt-mouse-encode, c-vt-key-encode)
gain snippet markers so their code can be referenced from the headers.
Conceptual snippets in key.h, mouse.h, and key/encoder.h that show
terminal-state usage patterns remain inline since they cannot be
compiled standalone.

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;
+}