chore: import upstream snapshot with attribution

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]