sl0ptty: M0.5 — the headless driver and the harness everything rests on

--script runs the whole compositor with no tty: commands in (send, raw,
settle, resize, snapshot, alive), composited screen out as JSON — rows of
text, style runs, cursor, and the hit list.

Styles are emitted as runs rather than per-cell objects, because a test wants
'columns 0..5 of row 0 are bold red', not 1920 objects.

The hit list is empty until M1 paints something clickable, but the type, the
JSON, and hit_test() exist now: one geometry, established before there is
anything to get wrong.

Also fixes two host-policy defaults found by the cursor never appearing.
lib-vt is a VT library, not a terminal, so it starts with DECTCEM (mode 25)
off and grapheme clustering (2027) off. Both are now set via MODE_DEFAULT, so
they survive RIS.

tests/harness.py + tests/test_screen.py: 19 checks over composition, styling,
wide chars/clusters, scrollback, resize and the full input round trip —
including the kitty/legacy re-encoding matrix, which no longer needs a pty.

make test is now 2.4s for 59 checks; make test-live keeps the four that
genuinely need a tty.

7 files changed, 485 insertions, 35 deletions

diff --git a/src/headless.c b/src/headless.c
new file mode 100644
index 0000000..3da8ee7
--- /dev/null
+++ b/src/headless.c
@@ -0,0 +1,164 @@
+/* The headless driver (DESIGN.md, "headless from day one").
+ *
+ * The whole compositor with no tty: commands in on stdin, screen snapshots out
+ * on stdout. Tests drive this instead of screen-scraping a pty, so they are
+ * deterministic and take milliseconds.
+ *
+ * The command set is deliberately the vocabulary the M2 control socket will
+ * speak, so the harness moves over unchanged.
+ *
+ *   send <escaped>    bytes as if typed at the outer terminal (decoded first)
+ *   raw <escaped>     bytes straight to the pane's pty, decoder bypassed
+ *   settle [ms]       pump the pane until it has been quiet for ms
+ *   resize <c> <r>
+ *   snapshot [json|text]
+ *   quit
+ *
+ * <escaped> understands \e \n \r \t \\ \xHH, so a test can write \e[1;5A.
+ */
+#define _GNU_SOURCE
+#include "sl0ptty.h"
+
+#include <poll.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <unistd.h>
+
+typedef struct {
+  pane_t *pane;
+} hl_dispatch_t;
+
+static void hl_event(const input_event_t *ev, void *ud) {
+  hl_dispatch_t *d = ud;
+  switch (ev->kind) {
+    case EV_KEY: pane_send_key(d->pane, ev); break;
+    case EV_MOUSE: pane_send_mouse(d->pane, ev); break;
+    case EV_PASTE: pane_send_paste(d->pane, ev->paste, ev->paste_len); break;
+    default: break;
+  }
+}
+
+static int64_t ms_now(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+  return (int64_t)ts.tv_sec * 1000 + ts.tv_nsec / 1000000;
+}
+
+/* \e \n \r \t \\ \xHH -> bytes */
+static size_t unescape(const char *in, uint8_t *out, size_t cap) {
+  size_t n = 0;
+  for (const char *p = in; *p && n < cap; p++) {
+    if (*p != '\\') {
+      out[n++] = (uint8_t)*p;
+      continue;
+    }
+    p++;
+    switch (*p) {
+      case 'e': out[n++] = 0x1b; break;
+      case 'n': out[n++] = '\n'; break;
+      case 'r': out[n++] = '\r'; break;
+      case 't': out[n++] = '\t'; break;
+      case '0': out[n++] = 0; break;
+      case '\\': out[n++] = '\\'; break;
+      case 'x': {
+        int hi = 0, lo = 0;
+        sscanf(p + 1, "%1x%1x", &hi, &lo);
+        out[n++] = (uint8_t)(hi * 16 + lo);
+        p += 2;
+        break;
+      }
+      case 0: return n;
+      default: out[n++] = (uint8_t)*p; break;
+    }
+  }
+  return n;
+}
+
+/* Pump the pane until it has produced nothing for `quiet` ms. */
+static void settle(pane_t *p, int quiet) {
+  int64_t last = ms_now();
+  int64_t deadline = last + 3000;
+  while (pane_alive(p) && ms_now() < deadline) {
+    struct pollfd pfd = {.fd = pane_fd(p), .events = POLLIN};
+    int n = poll(&pfd, 1, 10);
+    if (n > 0) {
+      if (pane_pump(p) > 0) last = ms_now();
+      if (!pane_alive(p)) break;
+    }
+    if (ms_now() - last >= quiet) break;
+  }
+}
+
+int run_headless(const char *const argv[], uint16_t cols, uint16_t rows,
+                 int idle_ms, bool script) {
+  pane_t *p = pane_new(argv, cols, rows, NULL);
+  if (!p) {
+    fprintf(stderr, "sl0ptty: cannot spawn pane\n");
+    return 1;
+  }
+  screen_t s;
+  screen_init(&s, cols, rows);
+  input_parser_t *in = input_new();
+  hl_dispatch_t d = {.pane = p};
+
+  /* one-shot: run it, let it settle, print the screen */
+  if (!script) {
+    settle(p, idle_ms);
+    pane_compose(p, &s, 0, 0, true);
+    char *dump = screen_dump(&s);
+    fputs(dump, stdout);
+    free(dump);
+    goto done;
+  }
+
+  char line[4096];
+  while (fgets(line, sizeof line, stdin)) {
+    line[strcspn(line, "\r\n")] = 0;
+    char *sp = strchr(line, ' ');
+    const char *arg = sp ? sp + 1 : "";
+    if (sp) *sp = 0;
+
+    if (strcmp(line, "send") == 0) {
+      uint8_t buf[4096];
+      size_t n = unescape(arg, buf, sizeof buf);
+      input_feed(in, buf, n, hl_event, &d);
+      if (input_pending(in)) input_timeout(in, hl_event, &d);
+    } else if (strcmp(line, "raw") == 0) {
+      uint8_t buf[4096];
+      size_t n = unescape(arg, buf, sizeof buf);
+      pane_write(p, buf, n);
+    } else if (strcmp(line, "settle") == 0) {
+      settle(p, *arg ? atoi(arg) : idle_ms);
+    } else if (strcmp(line, "resize") == 0) {
+      int c = cols, r = rows;
+      sscanf(arg, "%d %d", &c, &r);
+      cols = (uint16_t)c;
+      rows = (uint16_t)r;
+      screen_resize(&s, cols, rows);
+      pane_resize(p, cols, rows);
+    } else if (strcmp(line, "snapshot") == 0) {
+      pane_compose(p, &s, 0, 0, true);
+      char *dump = strcmp(arg, "text") == 0 ? screen_dump(&s)
+                                            : screen_dump_json(&s);
+      fputs(dump, stdout);
+      fputs("\n", stdout);
+      free(dump);
+      fflush(stdout);
+    } else if (strcmp(line, "alive") == 0) {
+      printf("%s\n", pane_alive(p) ? "true" : "false");
+      fflush(stdout);
+    } else if (strcmp(line, "quit") == 0) {
+      break;
+    } else if (line[0]) {
+      fprintf(stderr, "sl0ptty: unknown command: %s\n", line);
+    }
+  }
+
+done:
+  input_free(in);
+  screen_free(&s);
+  pane_free(p);
+  return 0;
+}
diff --git a/src/json.c b/src/json.c
new file mode 100644
index 0000000..efbe120
--- /dev/null
+++ b/src/json.c
@@ -0,0 +1,111 @@
+#define _GNU_SOURCE
+#include "json.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static void reserve(json_t *j, size_t n) {
+  if (j->len + n <= j->cap) return;
+  size_t cap = j->cap ? j->cap : 4096;
+  while (cap < j->len + n) cap *= 2;
+  j->buf = realloc(j->buf, cap);
+  j->cap = cap;
+}
+
+static void raw(json_t *j, const char *s, size_t n) {
+  reserve(j, n + 1);
+  memcpy(j->buf + j->len, s, n);
+  j->len += n;
+  j->buf[j->len] = 0;
+}
+
+static void rawz(json_t *j, const char *s) { raw(j, s, strlen(s)); }
+
+void json_init(json_t *j) {
+  memset(j, 0, sizeof *j);
+  reserve(j, 4096);
+  j->buf[0] = 0;
+}
+
+void json_free(json_t *j) {
+  free(j->buf);
+  memset(j, 0, sizeof *j);
+}
+
+static void sep(json_t *j, const char *key) {
+  if (j->need_comma) rawz(j, ",");
+  if (key) {
+    rawz(j, "\"");
+    rawz(j, key);
+    rawz(j, "\":");
+  }
+  j->need_comma = true;
+}
+
+static void escaped(json_t *j, const char *s, size_t len) {
+  rawz(j, "\"");
+  for (size_t i = 0; i < len; i++) {
+    unsigned char c = (unsigned char)s[i];
+    switch (c) {
+      case '"': rawz(j, "\\\""); break;
+      case '\\': rawz(j, "\\\\"); break;
+      case '\n': rawz(j, "\\n"); break;
+      case '\r': rawz(j, "\\r"); break;
+      case '\t': rawz(j, "\\t"); break;
+      default:
+        if (c < 0x20) {
+          char b[8];
+          snprintf(b, sizeof b, "\\u%04x", c);
+          rawz(j, b);
+        } else {
+          raw(j, (const char *)&c, 1); /* UTF-8 passes through */
+        }
+    }
+  }
+  rawz(j, "\"");
+}
+
+void json_obj_open(json_t *j, const char *key) {
+  sep(j, key);
+  rawz(j, "{");
+  j->need_comma = false;
+}
+
+void json_obj_close(json_t *j) {
+  rawz(j, "}");
+  j->need_comma = true;
+}
+
+void json_arr_open(json_t *j, const char *key) {
+  sep(j, key);
+  rawz(j, "[");
+  j->need_comma = false;
+}
+
+void json_arr_close(json_t *j) {
+  rawz(j, "]");
+  j->need_comma = true;
+}
+
+void json_str(json_t *j, const char *key, const char *val, size_t len) {
+  sep(j, key);
+  escaped(j, val, len);
+}
+
+void json_int(json_t *j, const char *key, long long val) {
+  sep(j, key);
+  char b[32];
+  snprintf(b, sizeof b, "%lld", val);
+  rawz(j, b);
+}
+
+void json_bool(json_t *j, const char *key, bool val) {
+  sep(j, key);
+  rawz(j, val ? "true" : "false");
+}
+
+void json_null(json_t *j, const char *key) {
+  sep(j, key);
+  rawz(j, "null");
+}
diff --git a/src/json.h b/src/json.h
new file mode 100644
index 0000000..b1acc43
--- /dev/null
+++ b/src/json.h
@@ -0,0 +1,28 @@
+/* A minimal JSON writer. No parser: we only ever emit. */
+#ifndef SL0PTTY_JSON_H
+#define SL0PTTY_JSON_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+typedef struct {
+  char *buf;
+  size_t len, cap;
+  bool need_comma;
+} json_t;
+
+void json_init(json_t *j);
+void json_free(json_t *j);
+
+void json_obj_open(json_t *j, const char *key);  /* key may be NULL in arrays */
+void json_obj_close(json_t *j);
+void json_arr_open(json_t *j, const char *key);
+void json_arr_close(json_t *j);
+
+void json_str(json_t *j, const char *key, const char *val, size_t len);
+void json_int(json_t *j, const char *key, long long val);
+void json_bool(json_t *j, const char *key, bool val);
+void json_null(json_t *j, const char *key);
+
+#endif /* SL0PTTY_JSON_H */
diff --git a/src/main.c b/src/main.c
index a2a587c..1c097f2 100644
--- a/src/main.c
+++ b/src/main.c
@@ -81,39 +81,9 @@ static int64_t now_ms(void) {
   return (int64_t)ts.tv_sec * 1000 + ts.tv_nsec / 1000000;
 }
 
-/* ---- headless: run a command, settle, dump the composited screen -------- */
-
-static int run_headless(const char *const argv[], uint16_t cols, uint16_t rows,
-                        int idle_ms) {
-  pane_t *p = pane_new(argv, cols, rows, NULL);
-  if (!p) {
-    fprintf(stderr, "sl0ptty: cannot spawn pane\n");
-    return 1;
-  }
-  screen_t s;
-  screen_init(&s, cols, rows);
-
-  int64_t last_activity = now_ms();
-  while (pane_alive(p)) {
-    struct pollfd pfd = {.fd = pane_fd(p), .events = POLLIN};
-    int n = poll(&pfd, 1, 20);
-    if (n > 0) {
-      if (pane_pump(p) > 0) last_activity = now_ms();
-      if (!pane_alive(p)) break;
-    }
-    if (now_ms() - last_activity > idle_ms) break;
-  }
-  pane_pump(p);
-
-  pane_compose(p, &s, 0, 0, true);
-  char *dump = screen_dump(&s);
-  fputs(dump, stdout);
-  free(dump);
-
-  screen_free(&s);
-  pane_free(p);
-  return 0;
-}
+/* headless lives in headless.c */
+int run_headless(const char *const argv[], uint16_t cols, uint16_t rows,
+                 int idle_ms, bool script);
 
 /* ---- interactive -------------------------------------------------------- */
 
@@ -241,7 +211,7 @@ static int run_interactive(const char *const argv[]) {
 }
 
 int main(int argc, char **argv) {
-  bool headless = false;
+  bool headless = false, script = false;
   uint16_t cols = 80, rows = 24;
   int idle_ms = 300;
   const char *cmd_argv[64];
@@ -249,6 +219,7 @@ int main(int argc, char **argv) {
 
   for (int i = 1; i < argc; i++) {
     if (strcmp(argv[i], "--headless") == 0) headless = true;
+    else if (strcmp(argv[i], "--script") == 0) headless = script = true;
     else if (strcmp(argv[i], "--cols") == 0 && i + 1 < argc) cols = (uint16_t)atoi(argv[++i]);
     else if (strcmp(argv[i], "--rows") == 0 && i + 1 < argc) rows = (uint16_t)atoi(argv[++i]);
     else if (strcmp(argv[i], "--idle-ms") == 0 && i + 1 < argc) idle_ms = atoi(argv[++i]);
@@ -274,6 +245,6 @@ int main(int argc, char **argv) {
   signal(SIGPIPE, SIG_IGN);
   signal(SIGCHLD, SIG_IGN); /* no zombies; EOF on the pty is our signal */
 
-  return headless ? run_headless(cmd_argv, cols, rows, idle_ms)
+  return headless ? run_headless(cmd_argv, cols, rows, idle_ms, script)
                   : run_interactive(cmd_argv);
 }
diff --git a/src/pane.c b/src/pane.c
index f5eeac7..5850a57 100644
--- a/src/pane.c
+++ b/src/pane.c
@@ -78,6 +78,21 @@ pane_t *pane_new(const char *const argv[], uint16_t cols, uint16_t rows,
   ghostty_terminal_set(p->term, GHOSTTY_TERMINAL_OPT_WRITE_PTY, &wfn);
   ghostty_terminal_set(p->term, GHOSTTY_TERMINAL_OPT_TITLE_CHANGED, &tfn);
 
+  /* lib-vt makes no assumptions a host terminal would: it starts with DECTCEM
+   * (mode 25) off, so the cursor is invisible until someone says otherwise.
+   * MODE_DEFAULT sets the current value *and* the one restored by RIS, so a
+   * program that resets the terminal does not lose its cursor.
+   *
+   * 2027 is grapheme clustering: one cell per cluster, so flags and ZWJ emoji
+   * stay whole. We are opinionated about the outer terminal (D11) and it
+   * clusters too; under a terminal that does not, wide emoji may misalign. */
+  static const uint16_t default_on[] = {25, 2027};
+  for (size_t i = 0; i < sizeof default_on / sizeof *default_on; i++) {
+    GhosttyTerminalModeConfig mc = {.mode = ghostty_mode_new(default_on[i], false),
+                                    .value = true};
+    ghostty_terminal_set(p->term, GHOSTTY_TERMINAL_OPT_MODE_DEFAULT, &mc);
+  }
+
   if (pty_spawn(&p->pty, argv, cols, rows, cwd) != 0) goto fail;
   p->alive = true;
   p->dirty = true;
diff --git a/src/screen.c b/src/screen.c
index 73d2fb0..9d31640 100644
--- a/src/screen.c
+++ b/src/screen.c
@@ -9,6 +9,35 @@
 #include <string.h>
 #include <unistd.h>
 
+#include "json.h"
+
+/* ---- hit list ----------------------------------------------------------- */
+
+void hit_reset(hitlist_t *hl) { hl->len = 0; }
+
+void hit_add(hitlist_t *hl, uint16_t x, uint16_t y, uint16_t w, uint16_t h,
+             const char *action) {
+  if (hl->len == hl->cap) {
+    hl->cap = hl->cap ? hl->cap * 2 : 16;
+    hl->items = realloc(hl->items, hl->cap * sizeof *hl->items);
+  }
+  hit_t *e = &hl->items[hl->len++];
+  e->x = x;
+  e->y = y;
+  e->w = w;
+  e->h = h;
+  snprintf(e->action, sizeof e->action, "%s", action);
+}
+
+const char *hit_test(const hitlist_t *hl, uint16_t x, uint16_t y) {
+  for (size_t i = hl->len; i-- > 0;) {
+    const hit_t *e = &hl->items[i];
+    if (x >= e->x && x < e->x + e->w && y >= e->y && y < e->y + e->h)
+      return e->action;
+  }
+  return NULL;
+}
+
 static void out_reserve(screen_t *s, size_t n) {
   if (s->out_len + n <= s->out_cap) return;
   size_t cap = s->out_cap ? s->out_cap : 8192;
@@ -57,6 +86,7 @@ void screen_free(screen_t *s) {
   free(s->cur);
   free(s->prev);
   free(s->out);
+  free(s->hits.items);
   memset(s, 0, sizeof *s);
 }
 
@@ -185,6 +215,115 @@ void screen_flush(screen_t *s, int fd) {
   }
 }
 
+/* Style runs rather than per-cell objects: a test wants to say "columns 0..5 of
+ * row 0 are bold red", and 1920 cell objects per snapshot is unreadable. */
+static void dump_style_runs(screen_t *s, json_t *j) {
+  json_arr_open(j, "styles");
+  for (uint16_t y = 0; y < s->rows; y++) {
+    uint16_t x = 0;
+    while (x < s->cols) {
+      cell_t *c = &s->cur[(size_t)y * s->cols + x];
+      bool plain = !c->attrs && !c->fg.set && !c->bg.set;
+      if (plain) {
+        x++;
+        continue;
+      }
+      uint16_t start = x;
+      while (x < s->cols) {
+        cell_t *n = &s->cur[(size_t)y * s->cols + x];
+        if (n->attrs != c->attrs || !color_eq(n->fg, c->fg) ||
+            !color_eq(n->bg, c->bg))
+          break;
+        x++;
+      }
+      json_obj_open(j, NULL);
+      json_int(j, "x", start);
+      json_int(j, "y", y);
+      json_int(j, "w", x - start);
+      char col[8];
+      if (c->fg.set) {
+        snprintf(col, sizeof col, "#%02x%02x%02x", c->fg.r, c->fg.g, c->fg.b);
+        json_str(j, "fg", col, strlen(col));
+      } else {
+        json_null(j, "fg");
+      }
+      if (c->bg.set) {
+        snprintf(col, sizeof col, "#%02x%02x%02x", c->bg.r, c->bg.g, c->bg.b);
+        json_str(j, "bg", col, strlen(col));
+      } else {
+        json_null(j, "bg");
+      }
+      json_arr_open(j, "attrs");
+      static const struct {
+        uint16_t bit;
+        const char *name;
+      } names[] = {
+          {ATTR_BOLD, "bold"},       {ATTR_DIM, "dim"},
+          {ATTR_ITALIC, "italic"},   {ATTR_UNDERLINE, "underline"},
+          {ATTR_BLINK, "blink"},     {ATTR_INVERSE, "inverse"},
+          {ATTR_INVISIBLE, "invisible"}, {ATTR_STRIKE, "strike"},
+      };
+      for (size_t i = 0; i < sizeof names / sizeof *names; i++)
+        if (c->attrs & names[i].bit)
+          json_str(j, NULL, names[i].name, strlen(names[i].name));
+      json_arr_close(j);
+      json_obj_close(j);
+    }
+  }
+  json_arr_close(j);
+}
+
+char *screen_dump_json(screen_t *s) {
+  json_t j;
+  json_init(&j);
+  json_obj_open(&j, NULL);
+  json_int(&j, "cols", s->cols);
+  json_int(&j, "rows", s->rows);
+
+  json_arr_open(&j, "text");
+  char *line = malloc((size_t)s->cols * 4 + 1);
+  for (uint16_t y = 0; y < s->rows; y++) {
+    size_t o = 0;
+    for (uint16_t x = 0; x < s->cols; x++) {
+      cell_t *c = &s->cur[(size_t)y * s->cols + x];
+      if (c->width == 0) continue;
+      if (c->len) {
+        memcpy(line + o, c->text, c->len);
+        o += c->len;
+      } else {
+        line[o++] = ' ';
+      }
+    }
+    json_str(&j, NULL, line, o);
+  }
+  free(line);
+  json_arr_close(&j);
+
+  dump_style_runs(s, &j);
+
+  json_obj_open(&j, "cursor");
+  json_bool(&j, "visible", s->cursor_visible);
+  json_int(&j, "x", s->cursor_x);
+  json_int(&j, "y", s->cursor_y);
+  json_obj_close(&j);
+
+  json_arr_open(&j, "hits");
+  for (size_t i = 0; i < s->hits.len; i++) {
+    hit_t *e = &s->hits.items[i];
+    json_obj_open(&j, NULL);
+    json_int(&j, "x", e->x);
+    json_int(&j, "y", e->y);
+    json_int(&j, "w", e->w);
+    json_int(&j, "h", e->h);
+    json_str(&j, "action", e->action, strlen(e->action));
+    json_obj_close(&j);
+  }
+  json_arr_close(&j);
+
+  json_obj_close(&j);
+  return j.buf; /* caller frees */
+}
+
 char *screen_dump(screen_t *s) {
   size_t cap = (size_t)(s->cols + 1) * s->rows * 4 + 1;
   char *buf = malloc(cap);
diff --git a/src/sl0ptty.h b/src/sl0ptty.h
index c71ec9e..962de66 100644
--- a/src/sl0ptty.h
+++ b/src/sl0ptty.h
@@ -38,11 +38,31 @@ typedef struct {
   color_t fg, bg;
 } cell_t;
 
+/* One geometry (DESIGN.md): every painted interactive element records its rect
+ * here as it is painted, and a click is a lookup. Drawing and hit-testing
+ * cannot disagree because there is only one of them. */
+typedef struct {
+  uint16_t x, y, w, h;
+  char action[48];
+} hit_t;
+
+typedef struct {
+  hit_t *items;
+  size_t len, cap;
+} hitlist_t;
+
+void hit_reset(hitlist_t *hl);
+void hit_add(hitlist_t *hl, uint16_t x, uint16_t y, uint16_t w, uint16_t h,
+             const char *action);
+/* The action at a point, or NULL. Later entries win: painted last is on top. */
+const char *hit_test(const hitlist_t *hl, uint16_t x, uint16_t y);
+
 typedef struct {
   uint16_t cols, rows;
   cell_t *cur;  /* what we want on screen */
   cell_t *prev; /* what the terminal last received */
   bool force_full;
+  hitlist_t hits;
 
   /* where the real cursor goes after a flush */
   bool cursor_visible;
@@ -64,6 +84,8 @@ void screen_put_utf8(screen_t *s, uint16_t x, uint16_t y, const char *txt,
 void screen_flush(screen_t *s, int fd);
 /* Plain-text dump of the composited screen; caller frees. (headless tests) */
 char *screen_dump(screen_t *s);
+/* The same screen as JSON: rows of text, style runs, cursor, hit-list. */
+char *screen_dump_json(screen_t *s);
 
 /* ---- pty --------------------------------------------------------------- */