@hncode/hncode 0.4.2 → 0.5.0

package/src/term-caps.js

@@ -0,0 +1,411 @@
+  // Terminal capability probing — ASK the terminal instead of guessing.
+//
+  // WHY THIS EXISTS
+  // ---------------
+  // Everything this app does that is terminal-specific used to be either unconditional
+  // or env-var-gated. Three of those were guesses with real consequences:
+//
+  //   * `ESC[?2026h/l` (synchronized output) was wrapped around EVERY diff write. A
+  //     terminal that does not implement it is supposed to ignore the private mode,
+  //     but "supposed to" is doing a lot of work for two sequences per frame.
+  //   * the Kitty keyboard protocol was turned ON by default with only
+  //     `HNCODE_NO_KITTY_KEYS=1` to undo it, and the code's own comment admitted why
+  //     that is a gamble: a terminal that does not implement `>1u` "reacts badly
+  //     (dropped/mangled input)". That is a wrong-guess-causes-a-broken-keyboard bug.
+  //   * the theme was forced to `dark`, whose normal text is WHITE, while the frame
+  //     pads its rows with PLAIN SPACES — no background is ever painted. On a terminal
+  //     with a light background that is white text on white: the transcript is
+  //     invisible. Nothing in the process could tell, because nothing asked.
+//
+  // So this module asks. The protocol is the standard one, and it is worth spelling out
+  // because it is why this needs no timeout-based guessing:
+//
+  //   Terminals process input sequentially and answer queries IN ORDER. So the batch
+  //   ends with a Device Attributes request (`ESC[c`) — the one query every terminal
+  //   answers — and its reply doubles as the end-of-batch sentinel: everything asked
+  //   before it has been answered by the time it arrives. No per-query timeout, no
+  //   waiting for absent replies.
+//
+  // A response arrives on the SAME stream as keystrokes, so whoever reads stdin while
+  // the probe runs must route it here instead of into the key parser. `probeTerminal`
+  // owns stdin for that window and hands back anything it could not consume, so a key
+  // pressed during the probe is still delivered.
+//
+  // The whole thing is best-effort: an unanswered query leaves its field `null`, which
+  // every consumer reads as "no information", never as "not supported".
+
+/** How long to wait for the answers. Real terminals reply in ~1ms; this only bites
+ *  on a terminal that answers nothing at all, where it is the price of not guessing. */
+export const PROBE_TIMEOUT_MS = 250;
+
+/** The batch, in the order it is written. DA1 is LAST — it is the sentinel.
+ *    OSC 11 `?`          — report the background colour
+ *    CSI ? u             — report the Kitty KEYBOARD protocol flags
+ *    CSI ? 2026$p        — report whether synchronized output is known
+ *    ESC _G ... ESC\    — query the Kitty GRAPHICS protocol: does it exist, and does it
+ *                            accept the transmission format we would send
+ *    CSI 16 t            — the pixel size of ONE CELL (XTWINOPS 16)
+ *    CSI 14 t            — the pixel size of the TEXT AREA (XTWINOPS 14), a cross-check
+ *                            for the cell size on a terminal that answers only that
+ *    CSI c               — Device Attributes: the sentinel, and the VT level
+ *
+ *  Both query forms were wrong before, and both mattered only for images.
+ *
+ *  The graphics query is its own APC, not a `CSI ? u` variant — an earlier guess collided
+ *  with the keyboard probe, and since an unanswered query is inferred as "not supported"
+ *  once the sentinel arrives, that switched images OFF on the terminals that have them.
+ *  It carries a REAL payload: one transparent RGBA pixel, RFC 1950 zlib, direct data
+ *  (f=32, o=z) — the same path the renderer uploads on. A probe that asks about formats we
+ *  would not send reports on a format we would not send. (dsh-TUI's terminal-querier.ts
+ *  sends exactly this, with the same base64.)
+ *
+ *  The CELL size is XTWINOPS **16**, not 14: 14 is the text area. The reply to both is
+ *  `CSI 6 ; w ; h t` — opcode 6 for the cell — so the parser matches on the REPORT
+ *  opcode, and 14/18 were what an earlier version matched on and therefore never read.
+ */
+export const PROBE_QUERY = '\x1b]11;?\x07' + '\x1b[?u' + '\x1b[?2026$p'
+  + '\x1b_Gi=31,s=1,v=1,a=q,t=d,f=32,o=z;eAFjYGBgAAAABAAB\x1b\\'
+  + '\x1b[16t' + '\x1b[14t' + '\x1b[c';
+
+/** Synchronized output (BEGIN/END SYNCHRONIZED UPDATE). */
+export const SYNC_OUTPUT_MODE = 2026;
+
+/** DECRPM `status` values for a mode. 0 means "not recognised", which is the one that
+ *  says the terminal has never heard of the mode. */
+const DECRPM_SET = 1;
+const DECRPM_RESET = 2;
+
+/** VT level per the FIRST Device Attributes parameter. A small table on purpose:
+ *  the parameter identifies the level, not the program — `xterm`, `kitty`, `vte` and
+ *  Windows Terminal all report a VT level in this range, and telling THOSE apart is
+ *  what the environment is for (see terminalFamily). */
+const VT_LEVELS = {
+  1: 'vt100', 2: 'vt100-avo', 6: 'vt102', 12: 'vt125', 15: 'vt131',
+  16: 'vt132', 17: 'vt1xx', 18: 'vt330', 19: 'vt340',
+  41: 'vt420', 61: 'vt510', 62: 'vt220', 63: 'vt320', 64: 'vt420', 65: 'vt525',
+  };
+
+/** Meaning of the extension parameters that follow the VT level, for the ones that
+ *  change what this app may attempt. */
+const DA1_EXTENSIONS = {
+  4: 'sixel',
+  6: 'selective-erase',
+  21: 'horizontal-scroll',
+  22: 'ansi-color',
+  28: 'rectangular-edit',
+  52: 'clipboard',
+  };
+
+function emptyCaps() {
+  return {
+    probed: false,
+    bg: null,          // { r, g, b } of the terminal background, or null
+    kitty: null,       // true/false: does it speak the Kitty keyboard protocol
+    kittyGraphics: null, // true/false: does it speak the Kitty GRAPHICS protocol
+    sync: null,        // true/false: synchronized output usable
+    level: null,       // 'vt220', …
+    extensions: [],    // ['sixel', 'ansi-color', …]
+    textArea: null,    // { w, h } in PIXELS: the terminal's text area, or null
+    cell: null,        // { w, h } in pixels: one cell, or null
+    da1: null,         // the raw DA1 parameter list, for diagnostics
+    family: null,      // a human-readable name, from the environment
+    cols: null,        // columns, when the terminal reported them
+    rows: null,        // rows, when the terminal reported them
+  };
+  }
+
+let caps = emptyCaps();
+
+/** Everything learned so far. Read by the renderer and the theme picker. */
+export function terminalCaps() { return caps; }
+
+
+/** Merge in probe results. Exported so tests (and a future re-probe on resize) can
+ *  install a set without running the protocol. */
+export function setTerminalCaps(next) {
+  caps = Object.assign(emptyCaps(), caps, next, { probed: true });
+  return caps;
+  }
+
+/** Whether a `ESC[?2026h … ESC[?2026l` wrapper should be emitted. Unknown (no probe,
+ *  no reply) keeps the OLD unconditional behaviour — this must not silently change
+ *  what an already-good terminal receives. */
+export function syncOutputUsable() {
+  return caps.sync !== false;
+  }
+
+/** Whether `ESC[>1u` may be sent. Unknown keeps the old default (on), so a terminal
+ *  that answers nothing is treated exactly as before; only a terminal that ANSWERED
+ *  and did not report Kitty support turns it off. */
+export function kittyKeysUsable() {
+  return caps.kitty !== false;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Parsing
+  // ---------------------------------------------------------------------------
+
+  // `ESC ] 11 ; rgb :RRRR/GGGG/BBBB` then BEL or ST. Components are 1-4 hex digits.
+  // The `#rrggbb` spelling is also accepted: it is not xterm's, but several terminals
+  // answer OSC 11 that way and there is no reason to throw the reading away.
+const OSC11_RE = /\x1b\]11;(?:rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})|#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2}))(?:\x07|\x1b\\)/g;
+  // Kitty keyboard flags reply.
+const KITTY_RE = /\x1b\[\?(\d+)u/g;
+  // DECRPM: mode number, then `;`, then the status, then `$y`.
+const DECRPM_RE = /\x1b\[\?(\d+);(\d+)\$y/g;
+  // Device Attributes reply: `ESC [ ? <params> c`.
+const DA1_RE = /\x1b\[\?([0-9;]*)c/g;
+  // Kitty GRAPHICS query reply. The value is a bitmap of what the terminal accepts;
+  // per the spec, querying action=1 asks which features are supported.
+  const KITTY_GRAPHICS_RE = /\x1b\[_G([\s\S]*?)\x1b\\/g;
+  // XTWINOPS replies are `CSI <opcode> ; <value> ... t`, and the opcode in the
+  // REPLY is not the one in the QUERY. Reporting the cell size is opcode 6 and the
+  // text area is 4; 14 and 18 are those same operations’ query forms, so a parser
+  // written for the query numbers matched nothing at all: the cell size stayed unknown, so
+  // every image refused to draw ("image could not be displayed") on a terminal that had
+  // just reported one — and the unmatched bytes fell through to the key parser.
+  const XT_CELL_RE = /\x1b\[6;(\d+);(\d+)t/g;
+  const XT_AREA_RE = /\x1b\[4;(\d+);(\d+)t/g;
+
+/** One hex component of an OSC 11 reply, scaled to 0-255. xterm sends four digits
+ *  (`ffff`), others send two (`ff`), so the scale comes from the digit count. */
+function scaleHex(h) {
+  const n = parseInt(h, 16);
+  const max = Math.pow(16, h.length) - 1;
+  return max > 0 ? Math.round((n / max) * 255) : 0;
+}
+
+/** Is this background colour light? Used to pick a readable theme: the frame paints no
+ *  background of its own, so the terminal's shows through every padded row. */
+export function isLightBg(bg) {
+  if (!bg) return false;
+  // Rec. 601 luma, which matches how a colour reads far better than a plain average.
+  return (0.299 * bg.r + 0.587 * bg.g + 0.114 * bg.b) > 127;
+  }
+
+/** Human-readable terminal name. The ENVIRONMENT is what actually identifies the
+ *  program (`TERM_PROGRAM`, `WT_SESSION`, `TERM`); the DA1 level only says which VT
+ *  it emulates, which several of them report identically. */
+export function terminalFamily(env = process.env) {
+  if (env.WT_SESSION) return 'Windows Terminal';
+  if (env.TERM_PROGRAM) {
+    return /vscode/i.test(String(env.TERM_PROGRAM)) ? 'VS Code' : String(env.TERM_PROGRAM);
+  }
+  const term = String(env.TERM || '');
+  if (!term) return null;
+  if (/kitty/i.test(term)) return 'kitty';
+  if (/wezterm/i.test(term)) return 'WezTerm';
+  if (/ghostty/i.test(term)) return 'Ghostty';
+  if (/^screen/i.test(term)) return 'screen';
+  if (/^tmux/i.test(term)) return 'tmux';
+  if (/^xterm/i.test(term)) return 'xterm';
+  return term;
+  }
+
+/** Prefixes of the replies we are waiting for. Used to trim a dangling partial reply
+ *  from the bytes handed back to the key parser, so half an escape sequence does not
+ *  become garbage input. */
+const REPLY_PREFIXES = ['\x1b]11;', '\x1b[?', '\x1b[_G'];
+
+/** Longest suffix of `buf` that could still grow into one of the replies. */
+function danglingReplyLen(buf) {
+  let best = 0;
+  for (const p of REPLY_PREFIXES) {
+    const max = Math.min(p.length, buf.length);
+    for (let len = max; len >= 2; len--) {
+      if (buf.endsWith(p.slice(0, len))) { if (len > best) best = len; break; }
+    }
+  }
+  return best;
+  }
+
+/**
+ * Remove any complete probe reply from `s`.
+ *
+ * For ONE narrow case, after the probe has given up: a slow terminal answers anyway,
+ * and those bytes arrive on the keystroke stream. Without this they reach the key
+ * parser and are typed into the composer as garbage. A terminal that answered the DA1
+ * sentinel has nothing left outstanding, so its caller does not need this at all — see
+ * the `complete` flag `probeTerminal` returns.
+ */
+export function stripProbeReplies(s) {
+  const buf = String(s == null ? '' : s);
+  // Almost every chunk is ordinary typing; only touch the buffer when it could hold a
+  // reply at all.
+  if (buf.indexOf('\x1b') < 0) return buf;
+  const spans = [];
+  const noop = () => {};
+  takeMatches(OSC11_RE, buf, spans, noop);
+  takeMatches(KITTY_RE, buf, spans, noop);
+  takeMatches(KITTY_GRAPHICS_RE, buf, spans, noop);
+  takeMatches(XT_CELL_RE, buf, spans, noop);
+  takeMatches(XT_AREA_RE, buf, spans, noop);
+  takeMatches(DECRPM_RE, buf, spans, noop);
+  takeMatches(DA1_RE, buf, spans, noop);
+  return removeSpans(buf, spans);
+  }
+
+/** Collect the matches of `re` in `buf`, recording their spans so the caller can
+ *  compute what is LEFT after removing them. */
+function takeMatches(re, buf, spans, onMatch) {
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(buf)) !== null) {
+    spans.push([m.index, m.index + m[0].length]);
+    onMatch(m);
+    // A zero-length match cannot happen with these patterns, but guard the loop.
+    if (m[0].length === 0) re.lastIndex++;
+  }
+  }
+
+/** Everything not covered by a span. */
+function removeSpans(buf, spans) {
+  if (!spans.length) return buf;
+  spans.sort((a, b) => a[0] - b[0]);
+  let out = '';
+  let at = 0;
+  for (const [s, e] of spans) {
+    if (s > at) out += buf.slice(at, s);
+    at = Math.max(at, e);
+  }
+  return out + buf.slice(at);
+  }
+
+/**
+ * Parse whatever has arrived. Pure, so it is directly testable.
+ *
+ * @returns {{ found: object, rest: string, complete: boolean }}
+ *   `found` carries only the fields a reply actually provided; `rest` is the buffer
+ *   with every reply removed (the caller keeps the tail it could still use); and
+ *   `complete` is true once the DA1 sentinel has been seen.
+ */
+export function parseProbeReplies(buf) {
+  const spans = [];
+  const found = {};
+
+  takeMatches(OSC11_RE, buf, spans, (m) => {
+    found.bg = m[4] != null
+      ? { r: parseInt(m[4], 16), g: parseInt(m[5], 16), b: parseInt(m[6], 16) }
+      : { r: scaleHex(m[1]), g: scaleHex(m[2]), b: scaleHex(m[3]) };
+  });
+  takeMatches(KITTY_RE, buf, spans, () => {
+    // Any flags value, including 0, means the terminal implements the protocol: 0 is
+    // "supported, nothing enabled yet", which is exactly the state we ask from.
+    found.kitty = true;
+  });
+  takeMatches(DECRPM_RE, buf, spans, (m) => {
+    const mode = Number(m[1]);
+    const status = Number(m[2]);
+    if (mode === SYNC_OUTPUT_MODE) {
+      // 0 is "not recognised"; SET and RESET both mean the terminal knows the mode,
+      // and either state is something the wrapper can work with.
+      found.sync = status === DECRPM_SET || status === DECRPM_RESET;
+    }
+  });
+  // Kitty GRAPHICS: a supported query answers `OK`; a terminal without the protocol says
+  // nothing at all. Silence is resolved in probeTerminal (a sentinel arriving means every
+  // query was answered, so silence means "no"), not here.
+  takeMatches(KITTY_GRAPHICS_RE, buf, spans, (m) => {
+    if (!/\bOK\b/.test(m[1])) return;
+    found.kittyGraphics = true;
+  });
+  // XTWINOPS: the CELL size (reported as opcode 6) and the TEXT AREA (opcode 4). Both
+  // are needed to place an image in cells rather than guessing — and a guess here is wrong
+  // on every display whose font is not square, which is most of them.
+  takeMatches(XT_CELL_RE, buf, spans, (m) => {
+    const w = Number(m[1]);
+    const h = Number(m[2]);
+    // A terminal that answers 0x0 has nothing to say — treat it as unknown rather than
+    // as a cell of zero width, which would divide by zero downstream.
+    if (w > 0 && h > 0) found.cell = { w, h };
+  });
+  takeMatches(XT_AREA_RE, buf, spans, (m) => {
+    const w = Number(m[1]);
+    const h = Number(m[2]);
+    if (w > 0 && h > 0) found.textArea = { w, h };
+  });
+  let complete = false;
+  takeMatches(DA1_RE, buf, spans, (m) => {
+    const params = m[1].split(';').map((s) => Number(s)).filter((n) => Number.isFinite(n));
+    found.da1 = params;
+    found.level = VT_LEVELS[params[0]] || (params.length ? `vt?${params[0]}` : null);
+    found.extensions = params.slice(1).map((p) => DA1_EXTENSIONS[p]).filter(Boolean);
+    // The sentinel is the LAST DA1 in the batch, and we only write one.
+    complete = true;
+  });
+
+  const rest = removeSpans(buf, spans);
+  return { found, rest, complete };
+  }
+
+  // ---------------------------------------------------------------------------
+  // The probe
+  // ---------------------------------------------------------------------------
+
+/**
+ * Ask the terminal. Owns `stdin` for the duration.
+ *
+ * @param {object} opts
+ * @param {import('node:stream').Readable} opts.stdin  Raw-mode stdin.
+ * @param {{write: Function}} opts.stdout             Where the queries go.
+ * @param {number} [opts.timeoutMs]
+ * @returns {Promise<{ caps: object, rest: string }>} `rest` is everything that was
+ *   NOT a reply — a keystroke typed while the probe was waiting must not be eaten.
+ */
+export function probeTerminal({ stdin, stdout, timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    // A probe REPLACES what is known: a second run must not inherit the first one's
+    // answers, or a terminal that changed would keep stale flags.
+    caps = emptyCaps();
+    // Declared before the closures that use them: `finish` can run from the catch
+    // below, i.e. before the listener is attached.
+    const found = {};
+    let buf = '';
+    let settled = false;
+    let timer = null;
+    // Whether the DA1 sentinel ever arrived: everything asked before it is answered by
+    // then, so if it did, nothing is outstanding.
+    let sawSentinel = false;
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      try { stdin.removeListener('data', onData); } catch { /* stream may be gone */ }
+      // Anything still buffered that could be the head of a reply is a reply we never
+      // finished receiving: drop just that tail, and hand the rest back as real input.
+      const tail = danglingReplyLen(buf);
+      const rest = tail ? buf.slice(0, buf.length - tail) : buf;
+      // The environment is the only thing that actually identifies the PROGRAM; DA1
+      // only reports which VT it emulates, which several of them do identically.
+      if (!found.family) found.family = terminalFamily();
+      // A terminal that answered the DA1 SENTINEL answered everything asked before it,
+      // in order — so a query it left unanswered is one it does not implement. For
+      // Kitty that inference is load-bearing: the reply is mandatory when the protocol
+      // is supported, so silence means NO, and sending `>1u` anyway is exactly what
+      // mangles input. Only inferred when the sentinel arrived; without it, unknown.
+      if (sawSentinel && found.kitty === undefined) found.kitty = false;
+      resolve({ caps: setTerminalCaps(found), rest, complete: sawSentinel });
+    };
+
+    const onData = (chunk) => {
+      buf += String(chunk);
+      const parsed = parseProbeReplies(buf);
+      Object.assign(found, parsed.found);
+      buf = parsed.rest;
+      if (parsed.complete) { sawSentinel = true; finish(); }
+    };
+
+    try {
+      stdin.setEncoding?.('utf8');
+      stdin.on('data', onData);
+    } catch {
+      // No usable stdin: report "nothing learned" rather than hanging.
+      finish();
+      return;
+    }
+    timer = setTimeout(finish, timeoutMs);
+    if (timer.unref) timer.unref();
+    try { stdout.write(PROBE_QUERY); } catch { finish(); }
+  });
+  }