# Vendored libghostty-vt

This directory holds a pinned checkout of [libghostty-vt](https://libghostty.tip.ghostty.org/),
the headless VT emulator extracted from [Ghostty](https://github.com/ghostty-org/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](https://github.com/marler8997/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.