patterm/third_party/libghostty-vt/README.md

Vendored libghostty-vt

This directory holds a pinned checkout of libghostty-vt, the headless VT emulator extracted from Ghostty.

Pin

• Repo: https://github.com/ghostty-org/ghostty
• Branch: main
• Commit: see ./COMMIT — pinned to a specific SHA, not a tag.

We initially tried tag v1.3.1 (332b2aefc6...) but the terminal.h and formatter.h headers we need had not yet been added to the public API at that tag. The pin is to a later commit on main where the full libghostty-vt surface (terminal + formatter + encoders) is in include/ghostty/vt/.

The upstream API is explicitly unstable. Do not bump the pin casually — re-run the spike's test matrix when you do.

Layout

This directory is empty after git clone of patterm. The vendored source is fetched on demand by the project's Makefile:

make deps          # clones the pinned ghostty source into ./source/
                   # builds it via zig and installs into ./install/

After make deps the layout is:

third_party/libghostty-vt/
├── COMMIT                # the pinned SHA, source of truth
├── README.md
├── source/               # shallow clone of ghostty-org/ghostty at $(cat COMMIT)
└── install/              # build output (consumed by cgo)
    ├── include/ghostty/...
    ├── lib/libghostty-vt.a
    └── lib/libghostty-vt.so

source/ and install/ are gitignored.

Build prerequisites

• zig ≥ 0.15.2 on $PATH. Arch Linux currently ships 0.16.0, which is newer than the declared minimum_zig_version in upstream build.zig.zon. If zig refuses to build with the installed version, install the matching toolchain via zigup or your distro's archive.
• A C toolchain for cgo (gcc or clang).
• git and curl.

What we use from this library

The spike (cmd/spike) only touches a small surface:

• ghostty_terminal_new / ghostty_terminal_free
• ghostty_terminal_vt_write (feed PTY bytes in)
• ghostty_terminal_resize (on SIGWINCH)
• ghostty_terminal_set to install a WRITE_PTY callback (DA queries etc.)
• ghostty_terminal_get for ACTIVE_SCREEN, CURSOR_X, CURSOR_Y, CURSOR_VISIBLE
• ghostty_formatter_terminal_new + ghostty_formatter_format_alloc with GHOSTTY_FORMATTER_FORMAT_PLAIN, unwrap=true, trim=true

Everything else (Kitty graphics, OSC parsing, render state, key/mouse encoders) is deferred to later milestones.