@effect-tui/core 0.1.1 → 0.1.4

package/src/keys.ts

@@ -1,302 +1,482 @@
 // Minimal key decoder for Node raw input → semantic key messages.
 
+// SGR mouse button codes (low 2 bits, after masking modifiers)
+const MOUSE_LEFT = 0
+const MOUSE_MIDDLE = 1
+const MOUSE_RIGHT = 2
+const MOUSE_SCROLL_UP = 64
+const MOUSE_SCROLL_DOWN = 65
+
+// Modifier bits (subtract 1 from raw value before checking)
+const MOD_SHIFT = 1
+const MOD_ALT = 2
+const MOD_CTRL = 4
+const MOD_META = 8
+
+// Common key codes
+const KEY_TAB = 9
+const KEY_ENTER_CR = 13
+const KEY_ESC = 27
+const KEY_SPACE = 32
+const KEY_BS = 127
+
 export type KeyName =
-  | "up"
-  | "down"
-  | "left"
-  | "right"
-  | "enter"
-  | "escape"
-  | "tab"
-  | "shift-tab"
-  | "backspace"
-  | "delete"
-  | "home"
-  | "end"
-  | "pageup"
-  | "pagedown"
-  | "insert"
-  | "return"
-  | "space"
-  | "char" // printable
+	| "up"
+	| "down"
+	| "left"
+	| "right"
+	| "enter"
+	| "escape"
+	| "tab"
+	| "shift-tab"
+	| "backspace"
+	| "delete"
+	| "home"
+	| "end"
+	| "pageup"
+	| "pagedown"
+	| "insert"
+	| "return"
+	| "space"
+	| "char" // printable
 
 export type KeyMsg = {
-  type: "key"
-  name: KeyName
-  text?: string // for printable chars
-  ctrl?: boolean
-  meta?: boolean
-  shift?: boolean
-  /** Optional phase; currently always "press" but left extensible. */
-  phase?: "press" | "repeat" | "release"
-  /** Set by renderer to allow handlers to stop further propagation. */
-  defaultPrevented?: boolean
-  preventDefault?: () => void
-  /** Source protocol (raw|csiu|modifyOther|kitty). */
-  source?: "raw" | "csiu" | "modify-other" | "kitty"
+	type: "key"
+	name: KeyName
+	text?: string // for printable chars
+	ctrl?: boolean
+	meta?: boolean
+	shift?: boolean
+	/** Optional phase; currently always "press" but left extensible. */
+	phase?: "press" | "repeat" | "release"
+	/** Set by renderer to allow handlers to stop further propagation. */
+	defaultPrevented?: boolean
+	preventDefault?: () => void
+	/** Source protocol (raw|csiu|modifyOther|kitty). */
+	source?: "raw" | "csiu" | "modify-other" | "kitty"
 }
 
+export type MouseButton = "left" | "middle" | "right" | "scroll-up" | "scroll-down" | "none"
+
+export type MouseMsg = {
+	type: "mouse"
+	button: MouseButton
+	/** Column (0-based) */
+	x: number
+	/** Row (0-based) */
+	y: number
+	/** Press or release */
+	action: "press" | "release" | "drag" | "move"
+	ctrl?: boolean
+	meta?: boolean
+	shift?: boolean
+}
+
+/** Union of keyboard and mouse input events */
+export type InputMsg = KeyMsg | MouseMsg
+
 const ESC = "\x1b"
 
+// ─────────────────────────────────────────────────────────────
+// CSI sequence parsing (xterm-style modified keys)
+// ─────────────────────────────────────────────────────────────
+
+// CSI pattern: ESC [ <params> <final>
+// Examples: ESC[A (up), ESC[1;2A (shift+up), ESC[5~ (pageup)
+const CSI_RE = /^\x1b\[([0-9;]*)([A-Za-z~])$/
+
+// Map CSI final character to key name
+const CSI_ARROW_MAP: Record<string, KeyName> = {
+	A: "up",
+	B: "down",
+	C: "right",
+	D: "left",
+	H: "home",
+	F: "end",
+}
+
+// Map CSI ~ sequences to key names (e.g., ESC[5~ = pageup)
+const CSI_TILDE_MAP: Record<number, KeyName> = {
+	2: "insert",
+	3: "delete",
+	5: "pageup",
+	6: "pagedown",
+}
+
+/**
+ * Parse xterm modifier parameter into boolean flags.
+ * xterm uses 1+bitmask encoding: 2=shift, 3=alt, 4=shift+alt, 5=ctrl, etc.
+ * Bits: 0=shift, 1=alt/meta, 2=ctrl, 3=meta (extended)
+ */
+function parseModifiers(modParam: number): { shift: boolean; meta: boolean; ctrl: boolean } {
+	const bits = modParam - 1
+	return {
+		shift: !!(bits & MOD_SHIFT),
+		meta: !!(bits & MOD_ALT), // Alt is typically mapped to meta
+		ctrl: !!(bits & MOD_CTRL),
+	}
+}
+
+/**
+ * Try to decode a CSI sequence with optional modifiers.
+ * Handles: arrows (A/B/C/D), home/end (H/F), and tilde sequences (2~/3~/5~/6~)
+ */
+function decodeCsiSequence(s: string): KeyMsg | null {
+	const match = CSI_RE.exec(s)
+	if (!match) return null
+
+	const params = match[1] ? match[1].split(";").map(Number) : []
+	const final = match[2]
+
+	// Handle arrow keys and home/end (A/B/C/D/H/F)
+	const arrowName = CSI_ARROW_MAP[final]
+	if (arrowName) {
+		// Get modifier from 2nd param (ESC[1;2A) or 1st if only one (rare)
+		const modParam = params.length >= 2 ? params[1] : params.length === 1 && params[0] >= 2 ? params[0] : null
+		const mods = modParam ? parseModifiers(modParam) : { shift: false, meta: false, ctrl: false }
+
+		return {
+			type: "key",
+			name: arrowName,
+			...(mods.shift && { shift: true }),
+			...(mods.meta && { meta: true }),
+			...(mods.ctrl && { ctrl: true }),
+		}
+	}
+
+	// Handle tilde sequences (ESC[5~, ESC[3;5~ for ctrl+delete, etc.)
+	if (final === "~") {
+		const keyCode = params[0]
+		const tildeName = keyCode !== undefined ? CSI_TILDE_MAP[keyCode] : undefined
+		if (tildeName) {
+			const modParam = params.length >= 2 ? params[1] : null
+			const mods = modParam ? parseModifiers(modParam) : { shift: false, meta: false, ctrl: false }
+
+			return {
+				type: "key",
+				name: tildeName,
+				...(mods.shift && { shift: true }),
+				...(mods.meta && { meta: true }),
+				...(mods.ctrl && { ctrl: true }),
+			}
+		}
+	}
+
+	return null
+}
+
+// SGR mouse event regex
+const SGR_MOUSE_RE = /\x1b\[<(\d+);(\d+);(\d+)([Mm])/g
+
+/**
+ * Parse SGR mouse button code into button name and modifiers.
+ * Code format: low 2 bits = button (0-2), bits 2-5 = modifiers, bit 5 = motion, bits 6-7 = scroll
+ */
+function parseSgrMouse(code: number, cx: number, cy: number, isRelease: boolean): MouseMsg {
+	// Scroll events (bits 6-7)
+	if (code >= 64) {
+		return {
+			type: "mouse",
+			button: code === MOUSE_SCROLL_UP ? "scroll-up" : "scroll-down",
+			x: cx - 1, // Convert to 0-based
+			y: cy - 1,
+			action: "press", // Scroll doesn't have release
+			shift: Boolean(code & 4),
+			meta: Boolean(code & 8),
+			ctrl: Boolean(code & 16),
+		}
+	}
+
+	// Button events
+	const buttonBits = code & 3
+	const isMotion = Boolean(code & 32)
+
+	let button: MouseButton
+	if (buttonBits === MOUSE_LEFT) button = "left"
+	else if (buttonBits === MOUSE_MIDDLE) button = "middle"
+	else if (buttonBits === MOUSE_RIGHT) button = "right"
+	else button = "none"
+
+	let action: MouseMsg["action"]
+	if (isMotion) {
+		action = button === "none" ? "move" : "drag"
+	} else {
+		action = isRelease ? "release" : "press"
+	}
+
+	return {
+		type: "mouse",
+		button,
+		x: cx - 1,
+		y: cy - 1,
+		action,
+		shift: Boolean(code & 4),
+		meta: Boolean(code & 8),
+		ctrl: Boolean(code & 16),
+	}
+}
+
+/**
+ * Decode input buffer into keyboard and mouse events.
+ * Use this instead of decodeKeys if you want mouse support.
+ */
+export function* decodeInput(buf: Buffer): Iterable<InputMsg> {
+	let s = buf.toString("utf8")
+
+	// Extract all SGR mouse events first
+	for (const m of s.matchAll(SGR_MOUSE_RE)) {
+		const code = parseInt(m[1], 10)
+		const cx = parseInt(m[2], 10)
+		const cy = parseInt(m[3], 10)
+		const isRelease = m[4] === "m"
+		const mouse = parseSgrMouse(code, cx, cy, isRelease)
+
+		// Yield the mouse event
+		yield mouse
+
+		// For scroll wheel, ALSO emit legacy KeyMsg for backward compatibility
+		// (useScroll listens for pageup/pagedown with meta: true)
+		if (mouse.button === "scroll-up") {
+			yield { type: "key", name: "pageup", meta: true } as KeyMsg
+		} else if (mouse.button === "scroll-down") {
+			yield { type: "key", name: "pagedown", meta: true } as KeyMsg
+		}
+	}
+
+	// Strip mouse sequences and process remaining as keys
+	s = s.replace(SGR_MOUSE_RE, "")
+	if (s.length > 0) {
+		yield* decodeKeys(Buffer.from(s, "utf8"))
+	}
+}
+
 export function* decodeKeys(buf: Buffer): Iterable<KeyMsg> {
-  // Handle control characters (0x00-0x1F)
-  // These are generated by Ctrl+letter combinations
-  if (buf.length === 1 && buf[0] !== undefined && buf[0] < 0x20) {
-    const byte = buf[0]
-
-    // Special control characters with specific meanings
-    switch (byte) {
-      case 0x03: // Ctrl-C (ETX - End of Text)
-        yield { type: "key", name: "char", text: "c", ctrl: true }
-        return
-      case 0x04: // Ctrl-D (EOT - End of Transmission)
-        yield { type: "key", name: "char", text: "d", ctrl: true }
-        return
-      case 0x17: // Ctrl-W (ETB - End of Transmission Block)
-        yield { type: "key", name: "char", text: "w", ctrl: true }
-        return
-      case 0x1a: // Ctrl-Z (SUB - Substitute)
-        yield { type: "key", name: "char", text: "z", ctrl: true }
-        return
-      case 0x0c: // Ctrl-L (FF - Form Feed)
-        yield { type: "key", name: "char", text: "l", ctrl: true }
-        return
-      case 0x09: // Tab (HT - Horizontal Tab)
-        yield { type: "key", name: "tab" }
-        return
-      case 0x0d: // Enter (CR - Carriage Return)
-        yield { type: "key", name: "enter" }
-        return
-      case 0x0a: // Line Feed (LF)
-        yield { type: "key", name: "enter" }
-        return
-      case 0x08: // Backspace (BS)
-        yield { type: "key", name: "backspace" }
-        return
-      case 0x1b: // Escape (ESC)
-        yield { type: "key", name: "escape" }
-        return
-      default:
-        // Other control characters: convert back to letter
-        // Ctrl-A = 0x01, Ctrl-B = 0x02, etc.
-        if (byte >= 0x01 && byte <= 0x1a) {
-          const letter = String.fromCharCode(byte + 96) // 0x01 + 96 = 'a'
-          yield { type: "key", name: "char", text: letter, ctrl: true }
-        } else {
-          // Unknown control character, emit raw
-          yield { type: "key", name: "char", text: String.fromCharCode(byte), ctrl: true }
-        }
-        return
-    }
-  }
-
-  // Handle 0x7F (DEL) separately as it's outside the control character range
-  if (buf.length === 1 && buf[0] === 0x7f) {
-    yield { type: "key", name: "backspace" }
-    return
-  }
-
-  let s = buf.toString("utf8")
-
-  // Handle one or more SGR mouse reports possibly coalesced in a single chunk.
-  // Format: ESC [ < Cb ; Cx ; Cy (M|m) — terminals vary on the trailing letter; accept any A-Z.
-  const sgrRe = /\x1b\x5b<(?<cb>\d+);(?<cx>\d+);(?<cy>\d+)(?<updown>[A-Za-z])/g
-  let matchedAny = false
-  for (const m of s.matchAll(sgrRe)) {
-    matchedAny = true
-    const code = parseInt(m.groups?.cb ?? "0", 10)
-    if (code === 64) {
-      yield { type: "key", name: "pageup", meta: true }
-      continue
-    }
-    if (code === 65) {
-      yield { type: "key", name: "pagedown", meta: true }
-    }
-    // ignore other mouse events
-  }
-  if (matchedAny) {
-    // Strip SGR mouse sequences so they never leak into the input as text
-    // Create a fresh regex since the global one was consumed by matchAll()
-    s = s.replace(/\x1b\x5b<(?<cb>\d+);(?<cx>\d+);(?<cy>\d+)(?<updown>[A-Za-z])/g, "")
-    if (s.length === 0) return
-  }
-
-  // Legacy single SGR report path (when only one arrives)
-  const sgr = /^\x1b\[<(?<cb>\d+);(?<cx>\d+);(?<cy>\d+)(?<updown>[A-Za-z])$/.exec(s)
-  if (sgr?.groups) {
-    const code = parseInt(sgr.groups.cb ?? "0", 10)
-    if (code === 64) {
-      yield { type: "key", name: "pageup", meta: true }
-      return
-    }
-    if (code === 65) {
-      yield { type: "key", name: "pagedown", meta: true }
-      return
-    }
-    return
-  }
-
-  // Meta+Backspace (Option+Backspace on macOS terminals) — often ESC + DEL / BS
-  if (s === `${ESC}\x7f` || s === `${ESC}\b` || s === `${ESC}\x08`) {
-    yield { type: "key", name: "backspace", meta: true }
-    return
-  }
-
-  // Alt/Meta + Enter (many terminals send ESC + CR/LF)
-  if (s === `${ESC}\r` || s === `${ESC}\n`) {
-    yield { type: "key", name: "enter", meta: true }
-    return
-  }
-
-  // modifyOtherKeys (xterm / some terminals): CSI 27;modifier;code~
-  const moo = /^\x1b\[27;(?<mod>\d+);(?<code>\d+)~$/.exec(s)
-  if (moo?.groups) {
-    const mod = parseInt(moo.groups.mod ?? "1", 10) - 1
-    const code = parseInt(moo.groups.code ?? "0", 10)
-    const shift = !!(mod & 1)
-    const alt = !!(mod & 2)
-    const ctrl = !!(mod & 4)
-    const meta = !!(mod & 8) || alt
-    const key = fromCharCode(code, { shift, ctrl, meta, source: "modify-other" })
-    if (key) {
-      yield key
-      return
-    }
-  }
-
-  // CSI-u (modern modifyOtherKeys): CSI <code> ; <modifier> u
-  const csiu = /^\x1b\[(?<code>\d+);(?<mod>\d+)u$/.exec(s)
-  if (csiu?.groups) {
-    const mod = parseInt(csiu.groups.mod ?? "1", 10) - 1
-    const code = parseInt(csiu.groups.code ?? "0", 10)
-    const shift = !!(mod & 1)
-    const alt = !!(mod & 2)
-    const ctrl = !!(mod & 4)
-    const meta = !!(mod & 8) || alt
-    const key = fromCharCode(code, { shift, ctrl, meta, source: "csiu" })
-    if (key) {
-      yield key
-      return
-    }
-  }
-
-  // Escape (lone ESC) - handle after meta combinations
-  if (s === ESC) {
-    yield { type: "key", name: "escape" }
-    return
-  }
-
-  // Single printable
-  if (s.length === 1 && s !== ESC && s !== "\x7f") {
-    if (s === " ") {
-      yield { type: "key", name: "space", text: " " }
-      return
-    }
-    if (s >= " ") {
-      yield { type: "key", name: "char", text: s }
-      return
-    }
-  }
-
-  // Common escapes
-  switch (s) {
-    case `${ESC}[A`:
-      yield { type: "key", name: "up" }
-      return
-    case `${ESC}[B`:
-      yield { type: "key", name: "down" }
-      return
-    case `${ESC}[C`:
-      yield { type: "key", name: "right" }
-      return
-    case `${ESC}[D`:
-      yield { type: "key", name: "left" }
-      return
-    case `${ESC}[1;3C`:
-      yield { type: "key", name: "right", meta: true }
-      return
-    case `${ESC}[1;3D`:
-      yield { type: "key", name: "left", meta: true }
-      return
-    case `${ESC}OP`: // F1 (ignored)
-      return
-    case `${ESC}[H`:
-      yield { type: "key", name: "home" }
-      return
-    case `${ESC}[F`:
-      yield { type: "key", name: "end" }
-      return
-    case `${ESC}[5~`:
-      yield { type: "key", name: "pageup" }
-      return
-    case `${ESC}[6~`:
-      yield { type: "key", name: "pagedown" }
-      return
-    case `${ESC}[2~`:
-      yield { type: "key", name: "insert" }
-      return
-    case `${ESC}[3~`:
-      yield { type: "key", name: "delete" }
-      return
-    case `${ESC}[3;3~`: // Meta+Delete (best-effort for some terminals)
-      yield { type: "key", name: "delete", meta: true }
-      return
-    case `${ESC}[Z`:
-      yield { type: "key", name: "shift-tab", shift: true }
-      return
-  }
-
-  // Alt/Meta + char (ESC <char>)
-  if (s.length === 2 && s[0] === ESC && s[1] && s[1] >= " ") {
-    const ch = s[1]
-    if (ch === " ") {
-      yield { type: "key", name: "space", text: " ", meta: true }
-      return
-    }
-    yield { type: "key", name: "char", text: ch, meta: true }
-    return
-  }
-
-  // Fallback: emit printable chars individually
-  for (const ch of s) {
-    if (ch >= " ") yield { type: "key", name: "char", text: ch }
-  }
+	// Handle control characters (0x00-0x1F)
+	// These are generated by Ctrl+letter combinations
+	if (buf.length === 1 && buf[0] !== undefined && buf[0] < 0x20) {
+		const byte = buf[0]
+
+		// Special control characters with specific meanings
+		switch (byte) {
+			case 0x03: // Ctrl-C (ETX - End of Text)
+				yield { type: "key", name: "char", text: "c", ctrl: true }
+				return
+			case 0x04: // Ctrl-D (EOT - End of Transmission)
+				yield { type: "key", name: "char", text: "d", ctrl: true }
+				return
+			case 0x17: // Ctrl-W (ETB - End of Transmission Block)
+				yield { type: "key", name: "char", text: "w", ctrl: true }
+				return
+			case 0x1a: // Ctrl-Z (SUB - Substitute)
+				yield { type: "key", name: "char", text: "z", ctrl: true }
+				return
+			case 0x0c: // Ctrl-L (FF - Form Feed)
+				yield { type: "key", name: "char", text: "l", ctrl: true }
+				return
+			case 0x09: // Tab (HT - Horizontal Tab)
+				yield { type: "key", name: "tab" }
+				return
+			case 0x0d: // Enter (CR - Carriage Return)
+				yield { type: "key", name: "enter" }
+				return
+			case 0x0a: // Line Feed (LF)
+				yield { type: "key", name: "enter" }
+				return
+			case 0x08: // Backspace (BS)
+				yield { type: "key", name: "backspace" }
+				return
+			case 0x1b: // Escape (ESC)
+				yield { type: "key", name: "escape" }
+				return
+			default:
+				// Other control characters: convert back to letter
+				// Ctrl-A = 0x01, Ctrl-B = 0x02, etc.
+				if (byte >= 0x01 && byte <= 0x1a) {
+					const letter = String.fromCharCode(byte + 96) // 0x01 + 96 = 'a'
+					yield { type: "key", name: "char", text: letter, ctrl: true }
+				} else {
+					// Unknown control character, emit raw
+					yield { type: "key", name: "char", text: String.fromCharCode(byte), ctrl: true }
+				}
+				return
+		}
+	}
+
+	// Handle 0x7F (DEL) separately as it's outside the control character range
+	if (buf.length === 1 && buf[0] === 0x7f) {
+		yield { type: "key", name: "backspace" }
+		return
+	}
+
+	let s = buf.toString("utf8")
+
+	// Handle one or more SGR mouse reports possibly coalesced in a single chunk.
+	// Format: ESC [ < Cb ; Cx ; Cy (M|m) — terminals vary on the trailing letter; accept any A-Z.
+	const sgrRe = /\x1b\x5b<(?<cb>\d+);(?<cx>\d+);(?<cy>\d+)(?<updown>[A-Za-z])/g
+	let matchedAny = false
+	for (const m of s.matchAll(sgrRe)) {
+		matchedAny = true
+		const code = parseInt(m.groups?.cb ?? "0", 10)
+		if (code === MOUSE_SCROLL_UP) {
+			yield { type: "key", name: "pageup", meta: true }
+			continue
+		}
+		if (code === MOUSE_SCROLL_DOWN) {
+			yield { type: "key", name: "pagedown", meta: true }
+		}
+		// ignore other mouse events
+	}
+	if (matchedAny) {
+		// Strip SGR mouse sequences so they never leak into the input as text
+		// Create a fresh regex since the global one was consumed by matchAll()
+		s = s.replace(/\x1b\x5b<(?<cb>\d+);(?<cx>\d+);(?<cy>\d+)(?<updown>[A-Za-z])/g, "")
+		if (s.length === 0) return
+	}
+
+	// Legacy single SGR report path (when only one arrives)
+	const sgr = /^\x1b\[<(?<cb>\d+);(?<cx>\d+);(?<cy>\d+)(?<updown>[A-Za-z])$/.exec(s)
+	if (sgr?.groups) {
+		const code = parseInt(sgr.groups.cb ?? "0", 10)
+		if (code === MOUSE_SCROLL_UP) {
+			yield { type: "key", name: "pageup", meta: true }
+			return
+		}
+		if (code === MOUSE_SCROLL_DOWN) {
+			yield { type: "key", name: "pagedown", meta: true }
+			return
+		}
+		return
+	}
+
+	// Meta+Backspace (Option+Backspace on macOS terminals) — often ESC + DEL / BS
+	if (s === `${ESC}\x7f` || s === `${ESC}\b` || s === `${ESC}\x08`) {
+		yield { type: "key", name: "backspace", meta: true }
+		return
+	}
+
+	// Alt/Meta + Enter (many terminals send ESC + CR/LF)
+	if (s === `${ESC}\r` || s === `${ESC}\n`) {
+		yield { type: "key", name: "enter", meta: true }
+		return
+	}
+
+	// modifyOtherKeys (xterm / some terminals): CSI 27;modifier;code~
+	const moo = /^\x1b\[27;(?<mod>\d+);(?<code>\d+)~$/.exec(s)
+	if (moo?.groups) {
+		const mod = parseInt(moo.groups.mod ?? "1", 10) - 1
+		const code = parseInt(moo.groups.code ?? "0", 10)
+		const shift = !!(mod & MOD_SHIFT)
+		const alt = !!(mod & MOD_ALT)
+		const ctrl = !!(mod & MOD_CTRL)
+		const meta = !!(mod & MOD_META) || alt
+		const key = fromCharCode(code, { shift, ctrl, meta, source: "modify-other" })
+		if (key) {
+			yield key
+			return
+		}
+	}
+
+	// CSI-u (modern modifyOtherKeys): CSI <code> ; <modifier> u
+	const csiu = /^\x1b\[(?<code>\d+);(?<mod>\d+)u$/.exec(s)
+	if (csiu?.groups) {
+		const mod = parseInt(csiu.groups.mod ?? "1", 10) - 1
+		const code = parseInt(csiu.groups.code ?? "0", 10)
+		const shift = !!(mod & MOD_SHIFT)
+		const alt = !!(mod & MOD_ALT)
+		const ctrl = !!(mod & MOD_CTRL)
+		const meta = !!(mod & MOD_META) || alt
+		const key = fromCharCode(code, { shift, ctrl, meta, source: "csiu" })
+		if (key) {
+			yield key
+			return
+		}
+	}
+
+	// Escape (lone ESC) - handle after meta combinations
+	if (s === ESC) {
+		yield { type: "key", name: "escape" }
+		return
+	}
+
+	// Single printable
+	if (s.length === 1 && s !== ESC && s !== "\x7f") {
+		if (s === " ") {
+			yield { type: "key", name: "space", text: " " }
+			return
+		}
+		if (s >= " ") {
+			yield { type: "key", name: "char", text: s }
+			return
+		}
+	}
+
+	// Try generic CSI parser first (handles all modifier combinations)
+	const csiKey = decodeCsiSequence(s)
+	if (csiKey) {
+		yield csiKey
+		return
+	}
+
+	// Special cases not handled by generic CSI parser
+	switch (s) {
+		case `${ESC}OP`: // F1 (ignored)
+			return
+		case `${ESC}[Z`:
+			yield { type: "key", name: "shift-tab", shift: true }
+			return
+	}
+
+	// Alt/Meta + char (ESC <char>)
+	if (s.length === 2 && s[0] === ESC && s[1] && s[1] >= " ") {
+		const ch = s[1]
+		if (ch === " ") {
+			yield { type: "key", name: "space", text: " ", meta: true }
+			return
+		}
+		yield { type: "key", name: "char", text: ch, meta: true }
+		return
+	}
+
+	// Fallback: emit printable chars individually
+	for (const ch of s) {
+		if (ch >= " ") yield { type: "key", name: "char", text: ch }
+	}
 }
 
 function fromCharCode(
-  code: number,
-  mods: { shift?: boolean; ctrl?: boolean; meta?: boolean; source: KeyMsg["source"] },
+	code: number,
+	mods: { shift?: boolean; ctrl?: boolean; meta?: boolean; source: KeyMsg["source"] },
 ): KeyMsg | null {
-  const { shift, ctrl, meta, source } = mods
-  const common: Omit<KeyMsg, "name"> = {
-    type: "key",
-    ctrl,
-    meta,
-    shift,
-    phase: "press",
-    source,
-  }
-
-  switch (code) {
-    case 13:
-      return { ...common, name: "enter" }
-    case 27:
-      return { ...common, name: "escape" }
-    case 9:
-      return { ...common, name: "tab" }
-    case 32:
-      return { ...common, name: "space", text: " " }
-    case 127:
-    case 8:
-      return { ...common, name: "backspace" }
-  }
-
-  if (code >= 0 && code < 32) {
-    // Control character -> map to letter when possible
-    const letter = String.fromCharCode(code + 96)
-    return { ...common, name: "char", text: letter, ctrl: true }
-  }
-
-  const ch = String.fromCharCode(code)
-  return { ...common, name: "char", text: ch }
+	const { shift, ctrl, meta, source } = mods
+	const common: Omit<KeyMsg, "name"> = {
+		type: "key",
+		ctrl,
+		meta,
+		shift,
+		phase: "press",
+		source,
+	}
+
+	switch (code) {
+		case KEY_ENTER_CR:
+			return { ...common, name: "enter" }
+		case KEY_ESC:
+			return { ...common, name: "escape" }
+		case KEY_TAB:
+			return { ...common, name: "tab" }
+		case KEY_SPACE:
+			return { ...common, name: "space", text: " " }
+		case KEY_BS:
+		case 8: // Backspace (legacy)
+			return { ...common, name: "backspace" }
+	}
+
+	if (code >= 0 && code < 32) {
+		// Control character -> map to letter when possible
+		const letter = String.fromCharCode(code + 96)
+		return { ...common, name: "char", text: letter, ctrl: true }
+	}
+
+	const ch = String.fromCharCode(code)
+	return { ...common, name: "char", text: ch }
 }