Initial patterm project

third_party/libghostty-vt/COMMIT

@@ -0,0 +1 @@
+b0f8276658fbcc75318d2125d40146074a3fc505

third_party/libghostty-vt/README.md

@@ -0,0 +1,67 @@
+# 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.