feat: input parser probe-response recognition → CapabilityEvent (#132)

Co-authored-by: bombshell-cooper[bot] <300334852+bombshell-cooper[bot]@users.noreply.github.com>

Author: natemoo-re

.changeset/cooper-approved-132.md

@@ -0,0 +1,22 @@
+---
+"@bomb.sh/tty": minor
+---
+
+Adds `CapabilityEvent` to `InputEvent` and changes `InputOptions.terminfo` to accept a `TerminalInfo`.
+
+`scan()` now parses terminal probe responses — OSC 10/11/12 theme colors, OSC 21 kitty color protocol, OSC 22 pointer shape, XTGETTCAP (`DCS`), kitty graphics (`APC`), kitty keyboard (`CSI ?…u`), synchronized output (`DECRPM`), and DA1 — and surfaces them as typed `CapabilityEvent` objects with keys `foreground-color`, `background-color`, `cursor-color`, `colordepth`, `sync-output`, `kitty-keyboard`, `kitty-graphics`, and `pointer-shape`.
+
+**Breaking:** `InputOptions.terminfo` now takes the `TerminalInfo` returned by `detectTerminal()` instead of raw compiled terminfo bytes. It seeds the key-sequence trie from `terminfo.keys` and uses `terminfo.capabilities.colors` to resolve colordepth denial events to the correct tier (`"16"` vs `"256"`). Raw bytes now go to `detectTerminal({ entry })`.
+
+#### Migration
+
+```diff
+- import { createInput } from "@bomb.sh/tty";
++ import { createInput, detectTerminal } from "@bomb.sh/tty";
+
+- const input = await createInput({ terminfo: myTerminfoBinary });
++ const terminfo = await detectTerminal({ env: process.env, entry: myTerminfoBinary });
++ const input = await createInput({ terminfo });
+```
+
+Omit `terminfo` entirely to keep the xterm default key sequences.

input-native.ts

@@ -2,13 +2,29 @@ export const EVENT_KEY = 1;
 export const EVENT_MOUSE = 2;
 export const EVENT_RESIZE = 3;
 export const EVENT_CURSOR = 4;
+export const EVENT_CAPABILITY = 5;
 
 export const MOD_ALT = 1;
 export const MOD_CTRL = 2;
 export const MOD_SHIFT = 4;
 export const MOD_MOTION = 8;
 export const MOD_RELEASE = 16;
 
+/* Capability key constants — must match CAP_* in src/input.h */
+export const CAP_FOREGROUND_COLOR = 1;
+export const CAP_BACKGROUND_COLOR = 2;
+export const CAP_CURSOR_COLOR = 3;
+export const CAP_COLORDEPTH = 4;
+export const CAP_SYNC_OUTPUT = 5;
+export const CAP_KITTY_KEYBOARD = 6;
+export const CAP_KITTY_GRAPHICS = 7;
+export const CAP_POINTER_SHAPE = 8;
+
+/* CAP_COLORDEPTH ch values — must match COLORDEPTH_* in src/input.c */
+export const COLORDEPTH_16 = 0;
+export const COLORDEPTH_256 = 1;
+export const COLORDEPTH_TRUECOLOR = 2;
+
 export const KEY_F1 = 0xFFFF;
 export const KEY_F2 = 0xFFFE;
 export const KEY_F3 = 0xFFFD;
@@ -169,10 +185,20 @@ export interface InputNative {
   delay(st: number): number;
 }
 
+// Must match SCAN_BUFFER_SIZE in input.c — the maximum bytes input_scan()
+// can accept in a single call.
+export const SCAN_BUFFER_SIZE = 4096;
+
+function align8(n: number): number {
+  return (n + 7) & ~7;
+}
+
 import { compiled } from "./wasm.ts";
 
 export async function createInputNative(
   escLatency: number,
+  keys?: Uint8Array,
+  initialColors?: number,
 ): Promise<InputNative> {
   let memory = new WebAssembly.Memory({ initial: 4 });
 
@@ -191,17 +217,52 @@ export async function createInputNative(
   let exports = instance.exports as unknown as {
     __heap_base: WebAssembly.Global;
     input_size(): number;
-    input_init(mem: number, escLatency: number): number;
+    input_init(
+      mem: number,
+      escLatency: number,
+      terminfo: number,
+      terminfoLen: number,
+      initialColors: number,
+    ): number;
     input_scan(st: number, buf: number, len: number, now: number): number;
     input_count(st: number): number;
     input_event(st: number, index: number): number;
     input_delay(st: number): number;
   };
 
-  let heap = exports.__heap_base.value as number;
-  let size = exports.input_size();
-  let state = exports.input_init(heap, escLatency);
-  let buffer = (heap + size + 7) & ~7;
+  // Linear memory layout, each region 8-byte aligned:
+  //
+  //   [0, __heap_base)   wasm data and stack
+  //   keys               terminfo key table (keys.byteLength, may be empty)
+  //   InputState         parser state (input_size())
+  //   scan buffer        input_scan() transfer buffer (SCAN_BUFFER_SIZE)
+  //
+  // Memory is grown once to cover the end of the scan buffer.
+  let keysLen = keys?.byteLength ?? 0;
+
+  let top = align8(exports.__heap_base.value as number);
+  let keysPtr = keysLen > 0 ? top : 0;
+  top = align8(top + keysLen);
+  let statePtr = top;
+  top = align8(top + exports.input_size());
+  let buffer = top;
+  top += SCAN_BUFFER_SIZE;
+
+  let pages = Math.ceil(top / 65536);
+  let current = memory.buffer.byteLength / 65536;
+  if (pages > current) memory.grow(pages - current);
+
+  if (keys && keysLen > 0) {
+    new Uint8Array(memory.buffer).set(keys, keysPtr);
+  }
+
+  let state = exports.input_init(
+    statePtr,
+    escLatency,
+    keysPtr,
+    keysLen,
+    initialColors ?? 256,
+  );
 
   return {
     memory,
@@ -213,12 +274,3 @@ export async function createInputNative(
     delay: exports.input_delay,
   };
 }
-
-// Compiled terminfo entries are limited to 4096 bytes (legacy) or 32768
-// bytes (extended ncurses format). We use the extended limit as our upper
-// bound. See https://man7.org/linux/man-pages/man5/term.5.html
-export const MAX_TERMINFO = 32768;
-
-// Must match SCAN_BUFFER_SIZE in input.c — the maximum bytes input_scan()
-// can accept in a single call.
-export const SCAN_BUFFER_SIZE = 4096;

input.ts

@@ -7,7 +7,17 @@
  */
 
 import {
+  CAP_BACKGROUND_COLOR,
+  CAP_COLORDEPTH,
+  CAP_CURSOR_COLOR,
+  CAP_FOREGROUND_COLOR,
+  CAP_KITTY_GRAPHICS,
+  CAP_KITTY_KEYBOARD,
+  CAP_POINTER_SHAPE,
+  CAP_SYNC_OUTPUT,
+  COLORDEPTH_TRUECOLOR,
   createInputNative,
+  EVENT_CAPABILITY,
   EVENT_CURSOR,
   EVENT_KEY,
   EVENT_MOUSE,
@@ -77,7 +87,6 @@ import {
   KEY_SUPER_LEFT,
   KEY_SUPER_RIGHT,
   KEY_TAB,
-  MAX_TERMINFO,
   MOD_ALT,
   MOD_CTRL,
   MOD_MOTION,
@@ -87,6 +96,8 @@ import {
   readEvent,
   SCAN_BUFFER_SIZE,
 } from "./input-native.ts";
+import type { Rgb, TerminalInfo } from "./terminfo.ts";
+import { rgbOf } from "./terminfo.ts";
 
 /**
  * Modifier keys held during a key or mouse event.
@@ -371,6 +382,57 @@ export interface CursorEvent {
   column: number;
 }
 
+/** Color depth tier reported by the terminal's XTGETTCAP probe response. */
+export type ColorDepth = "truecolor" | "256" | "16";
+
+/**
+ * A probe-response event emitted by scan() when the terminal answers one
+ * of the capability queries in TerminalInfo.probe. Route to term.update().
+ */
+export type CapabilityEvent =
+  | {
+    readonly type: "capability";
+    readonly key: "foreground-color";
+    readonly value: Rgb;
+  }
+  | {
+    readonly type: "capability";
+    readonly key: "background-color";
+    readonly value: Rgb;
+  }
+  | {
+    readonly type: "capability";
+    readonly key: "cursor-color";
+    readonly value: Rgb;
+  }
+  | {
+    readonly type: "capability";
+    readonly key: "colordepth";
+    readonly value: ColorDepth;
+  }
+  | {
+    readonly type: "capability";
+    readonly key: "sync-output";
+    readonly value: boolean;
+  }
+  | {
+    readonly type: "capability";
+    readonly key: "kitty-keyboard";
+    readonly value: boolean;
+  }
+  | {
+    readonly type: "capability";
+    readonly key: "kitty-graphics";
+    readonly value: boolean;
+  }
+  | {
+    readonly type: "capability";
+    readonly key: "pointer-shape";
+    readonly value: boolean;
+  };
+
+export type { Rgb };
+
 import type { PointerEvent } from "./term.ts";
 
 export type InputEvent =
@@ -381,6 +443,7 @@ export type InputEvent =
   | WheelEvent
   | ResizeEvent
   | CursorEvent
+  | CapabilityEvent
   | PointerEvent;
 
 /**
@@ -426,38 +489,31 @@ export interface Input {
 export interface InputOptions {
   /**
    * Milliseconds to wait before resolving a lone ESC byte as the Escape
-   * key rather than the start of an escape sequence. Lower values feel
-   * snappier but risk misinterpreting sequences on slow connections.
-   *
-   * For reference, Vim's `ttimeoutlen` defaults to 100ms and ncurses
-   * `ESCDELAY` defaults to 1000ms. The default of 25ms is tuned for
-   * local terminals where escape sequences arrive within microseconds.
+   * key rather than the start of an escape sequence.
    *
    * @default 25
    */
   escLatency?: number;
 
   /**
-   * Compiled terminfo binary to load terminal-specific escape sequences.
-   *
-   * This is the format used by files like /usr/lib/terminfo/78/xterm-256color
-   * and they can be directly loaded from disk into this option.
-   *
-   * If no terminfo is provided it will use xterm capabilities as the default
+   * Terminal detection from detectTerminal(). Seeds the key trie from
+   * terminfo.keys and uses terminfo.capabilities.colors for
+   * colordepth denial events. When omitted, the parser uses xterm
+   * default key sequences and a 256-color baseline.
    */
-  terminfo?: Uint8Array;
+  terminfo?: TerminalInfo;
 }
 
 export async function createInput(options: InputOptions = {}): Promise<Input> {
   let { escLatency = 25, terminfo } = options;
 
-  if (terminfo && terminfo.byteLength > MAX_TERMINFO) {
-    throw new RangeError(
-      `terminfo exceeds ${MAX_TERMINFO} byte limit (got ${terminfo.byteLength})`,
-    );
-  }
+  let native = await createInputNative(
+    escLatency,
+    terminfo?.keys,
+    terminfo?.capabilities.colors,
+  );
 
-  let native = await createInputNative(escLatency);
+  let initialColors = terminfo?.capabilities.colors ?? 256;
 
   return {
     scan(bytes: Uint8Array = new Uint8Array(0)): ScanResult {
@@ -482,8 +538,11 @@ export async function createInput(options: InputOptions = {}): Promise<Input> {
         let view = new DataView(native.memory.buffer);
         for (let i = 0; i < count; i++) {
           let ptr = native.event(native.state, i);
-          if (ptr !== 0) {
-            events.push(mapEvent(readEvent(view, ptr)));
+          let event = ptr !== 0
+            ? mapEvent(readEvent(view, ptr), initialColors)
+            : undefined;
+          if (event) {
+            events.push(event);
           }
         }
 
@@ -632,8 +691,70 @@ function mapKeyEvent(native: NativeInputEvent): KeyEvent {
   return ev;
 }
 
-function mapEvent(native: NativeInputEvent): InputEvent {
+function mapCapEvent(
+  native: NativeInputEvent,
+  initialColors: number,
+): CapabilityEvent | undefined {
+  switch (native.key) {
+    case CAP_FOREGROUND_COLOR:
+      return {
+        type: "capability",
+        key: "foreground-color",
+        value: rgbOf(native.ch),
+      };
+    case CAP_BACKGROUND_COLOR:
+      return {
+        type: "capability",
+        key: "background-color",
+        value: rgbOf(native.ch),
+      };
+    case CAP_CURSOR_COLOR:
+      return {
+        type: "capability",
+        key: "cursor-color",
+        value: rgbOf(native.ch),
+      };
+    case CAP_COLORDEPTH: {
+      let value: ColorDepth = native.ch === COLORDEPTH_TRUECOLOR
+        ? "truecolor"
+        : initialColors <= 16
+        ? "16"
+        : "256";
+      return { type: "capability", key: "colordepth", value };
+    }
+    case CAP_SYNC_OUTPUT:
+      return { type: "capability", key: "sync-output", value: native.ch !== 0 };
+    case CAP_KITTY_KEYBOARD:
+      return {
+        type: "capability",
+        key: "kitty-keyboard",
+        value: native.ch !== 0,
+      };
+    case CAP_KITTY_GRAPHICS:
+      return {
+        type: "capability",
+        key: "kitty-graphics",
+        value: native.ch !== 0,
+      };
+    case CAP_POINTER_SHAPE:
+      return {
+        type: "capability",
+        key: "pointer-shape",
+        value: native.ch !== 0,
+      };
+    default:
+      return undefined;
+  }
+}
+
+function mapEvent(
+  native: NativeInputEvent,
+  initialColors: number,
+): InputEvent | undefined {
   switch (native.type) {
+    case EVENT_CAPABILITY: {
+      return mapCapEvent(native, initialColors);
+    }
     case EVENT_KEY: {
       return mapKeyEvent(native);
     }

mod.ts

@@ -5,10 +5,10 @@ export * from "./settings.ts";
 export * from "./termcodes.ts";
 export {
   type Capabilities,
-  type Detection,
   type DetectOptions,
   detectTerminal,
   type KeyTable,
-  MAX_TERMINFO,
+  MAX_TERMINFO_ENTRY,
   type Rgb,
+  type TerminalInfo,
 } from "./terminfo.ts";