1 files changed, 43 insertions, 0 deletions
diff --git a/tests/extern/README.md b/tests/extern/README.md
new file mode 100644
index 0000000..cff42ed
--- /dev/null
+++ b/tests/extern/README.md
@@ -0,0 +1,43 @@
+# Imported test suites
+
+This directory holds test suites imported from external projects. These are
+kept for reference and cross-checking against our own terminal emulator's
+behavior. On Linux, `make test` builds and runs the adapted Kitty parser suite.
+
+## kitty/
+
+Vendored from <https://github.com/kovidgoyal/kitty>, commit `f13c8cd4`.
+
+### Running the adapted suite
+
+```sh
+meson test -C build --suite kitty
+```
+
+This builds `kitty_bridge` (a shared library compiled from
+the project's terminal sources), then runs the
+Kitty parser test suite against it via a Python compatibility layer.
+
+### Files
+
+- `kitty/parser.py` — Kitty's VT/CSI parser test suite (`kitty_tests/parser.py`),
+  with imports patched to use the local compatibility modules below.
+- `kitty_parser.py` — Pure-Python VT parser that emits Kitty-style callback
+  events while feeding every byte to the C terminal via `screen.write()`.
+  Maintains state across calls for split-write (threading) tests.
+- `screen.py` — `ctypes` wrapper around `libterm.so` providing the Kitty
+  `Screen`, `Cursor`, `Line`, `CellCursor`, and `Callbacks` API.
+- `fast_data_types.py` — Pure-Python replacements for Kitty's C-extension
+  helpers (base64, UTF-8 decode, constants).
+- `kitty_harness.py` — `BaseTest`, `CmdDump`, and `parse_bytes` re-export.
+- `__init__.py` — Package marker.
+
+### Test status (14 tests)
+
+All 14 tests pass. Features implemented for Kitty parity include DEC
+Special Graphics charset translation (G0/G1, SO/SI), literal `\t` cells,
+LNM-default-off linefeed semantics, CSI insert-character and REP edge
+cases, DECRQM mode reports, DECRQSS (DCS `$q`) and XTGETTCAP (DCS `+q`)
+responses, DECCARA/DECSACE (CSI `$r` / `*x`), secondary device attributes
+(CSI `=c`), XTWINOPS cell-size report (CSI `14t`), underline styles 0–5,
+and SGR underline color (58/59) including colon-form subparameters.