@cel-tui/core 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cel-tui/core",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Core framework engine for cel-tui — primitives, layout, rendering, input",
   "type": "module",
   "module": "src/index.ts",
@@ -34,7 +34,7 @@
     "layout"
   ],
   "dependencies": {
-    "@cel-tui/types": "0.4.0",
+    "@cel-tui/types": "0.4.1",
     "get-east-asian-width": "^1.5.0"
   },
   "peerDependencies": {

package/src/cel.ts

@@ -1,4 +1,9 @@
-import type { Node, Theme } from "@cel-tui/types";
+import type {
+  Node,
+  TextInputNode,
+  TextInputProps,
+  Theme,
+} from "@cel-tui/types";
 import { CellBuffer } from "./cell-buffer.js";
 import { emitBuffer, emitDiff, defaultTheme } from "./emitter.js";
 import {
@@ -8,7 +13,7 @@ import {
   collectKeyPressHandlers,
   collectFocusable,
 } from "./hit-test.js";
-import { parseKey, isEditingKey } from "./keys.js";
+import { decodeKeyEvents, isEditingKey, type KeyInput } from "./keys.js";
 import { layout, type LayoutNode } from "./layout.js";
 import {
   paint,
@@ -195,25 +200,49 @@ const SGR_MOUSE_RE = /\x1b\[<(\d+);(\d+);(\d+)([Mm])/g;
 // need to remember the offset we already dispatched via onScroll.
 let batchScrollOffsets: Map<object, number> | null = null;
 
+// Tracks the focused TextInput's latest edit state during a batched keyboard
+// chunk. The layout tree does not re-render until the next tick, so subsequent
+// keys in the same chunk must see the updated value/cursor immediately.
+let batchTextInputEdits: Map<TextInputProps, EditState> | null = null;
+
 function handleInput(data: string): void {
-  // Terminals may batch multiple mouse events into one data chunk.
-  // Scan for all SGR mouse sequences and handle each one.
   SGR_MOUSE_RE.lastIndex = 0;
-  let match = SGR_MOUSE_RE.exec(data);
-  if (match) {
-    batchScrollOffsets = new Map();
+  batchTextInputEdits = new Map();
+
+  let lastIndex = 0;
+
+  try {
+    let match = SGR_MOUSE_RE.exec(data);
     while (match) {
+      if (match.index > lastIndex) {
+        handleKeyChunk(data.slice(lastIndex, match.index));
+      }
+
+      if (batchScrollOffsets === null) {
+        batchScrollOffsets = new Map();
+      }
+
       const mouse = parseSgrMatch(match);
       if (mouse) handleMouseEvent(mouse);
+
+      lastIndex = match.index + match[0].length;
       match = SGR_MOUSE_RE.exec(data);
     }
+
+    if (lastIndex < data.length) {
+      handleKeyChunk(data.slice(lastIndex));
+    }
+  } finally {
     batchScrollOffsets = null;
-    return;
+    batchTextInputEdits = null;
   }
+}
 
-  // Keyboard input
-  const key = parseKey(data);
-  handleKeyEvent(key, data);
+function handleKeyChunk(data: string): void {
+  if (data.length === 0) return;
+  for (const key of decodeKeyEvents(data)) {
+    handleKeyEvent(key);
+  }
 }
 
 interface MouseEvent {
@@ -572,7 +601,18 @@ function findClickFocusTarget(path: LayoutNode[]): LayoutNode | null {
   return null;
 }
 
-function handleKeyEvent(key: string, rawData?: string): void {
+function getTextInputEditState(props: TextInputProps): EditState {
+  const batched = batchTextInputEdits?.get(props);
+  if (batched) return batched;
+  return {
+    value: props.value,
+    cursor: getTextInputCursor(props),
+  };
+}
+
+function handleKeyEvent(event: KeyInput): void {
+  const { key, text } = event;
+
   // --- Focus traversal keys ---
 
   // Tab / Shift+Tab: cycle through focusable elements
@@ -646,12 +686,10 @@ function handleKeyEvent(key: string, rawData?: string): void {
   }
 
   // --- TextInput key routing ---
-  // Find the focused TextInput (if any) to route editing keys
   const focusedInput = findFocusedTextInput();
 
   if (focusedInput) {
-    const props = focusedInput.node
-      .props as import("@cel-tui/types").TextInputProps;
+    const props = focusedInput.node.props as TextInputProps;
 
     // onKeyPress fires before editing — return false prevents the default action
     if (props.onKeyPress) {
@@ -662,12 +700,12 @@ function handleKeyEvent(key: string, rawData?: string): void {
       }
     }
 
-    // Editing keys are consumed by TextInput
-    if (isEditingKey(key)) {
-      const cursor = getTextInputCursor(props);
-      const editState: EditState = { value: props.value, cursor };
-      let newState: EditState | null = null;
+    let newState: EditState | null = null;
+    const editState = getTextInputEditState(props);
 
+    if (text !== undefined) {
+      newState = insertChar(editState, text);
+    } else if (isEditingKey(key)) {
       switch (key) {
         case "backspace":
           newState = deleteBackward(editState);
@@ -683,8 +721,7 @@ function handleKeyEvent(key: string, rawData?: string): void {
         case "end":
           {
             const tiPadX =
-              (focusedInput.node as import("@cel-tui/types").TextInputNode)
-                .props.padding?.x ?? 0;
+              (focusedInput.node as TextInputNode).props.padding?.x ?? 0;
             const contentWidth = Math.max(
               0,
               focusedInput.rect.width - tiPadX * 2,
@@ -709,24 +746,17 @@ function handleKeyEvent(key: string, rawData?: string): void {
         case "plus":
           newState = insertChar(editState, "+");
           break;
-        default:
-          // Single printable character — use raw data to preserve case
-          if (key.length === 1 && rawData && rawData.length === 1) {
-            newState = insertChar(editState, rawData);
-          } else if (key.length === 1) {
-            newState = insertChar(editState, key);
-          }
-          break;
       }
+    }
 
-      if (newState && newState !== editState) {
-        setTextInputCursor(props, newState.cursor);
-        if (newState.value !== editState.value) {
-          props.onChange(newState.value);
-        }
-        cel.render();
-        return;
+    if (newState && newState !== editState) {
+      batchTextInputEdits?.set(props, newState);
+      setTextInputCursor(props, newState.cursor);
+      if (newState.value !== editState.value) {
+        props.onChange(newState.value);
       }
+      cel.render();
+      return;
     }
   }
 

package/src/keys.ts

@@ -1,7 +1,7 @@
 /**
- * Key parsing for the Kitty keyboard protocol (level 1 — disambiguate).
+ * Key parsing for Kitty-first terminal input with legacy compatibility.
  *
- * At level 1, the terminal sends:
+ * The decoder accepts a mixed keyboard stream containing:
  * - **CSI u** (`ESC [ codepoint ; modifiers u`) for modified special keys
  *   and modifier combos (Ctrl+letter, Alt+letter, Shift+Tab, Ctrl+Enter, etc.)
  * - **CSI letter** (`ESC [ A/B/C/D/H/F` or `ESC [ 1 ; modifiers letter`) for
@@ -9,16 +9,26 @@
  * - **CSI tilde** (`ESC [ number ~` or `ESC [ number ; modifiers ~`) for
  *   Delete, PageUp, PageDown, and function keys
  * - **Legacy bytes** for unmodified special keys (Tab=0x09, Enter=0x0D,
- *   Escape=0x1B, Backspace=0x7F) — these retain their traditional encoding
- * - **Raw bytes** for unmodified printable characters
+ *   Escape=0x1B, Backspace=0x7F)
+ * - **Recoverable control bytes** for legacy `ctrl+letter` shortcuts
+ * - **ESC-prefixed Alt combinations** such as `ESC x`
+ * - **Raw printable text**
  *
  * Modifier bitmask (wire value = bitmask + 1):
- * shift=1, alt=2, ctrl=4 → e.g., ctrl = bitmask 4, wire param = 5
+ * shift=1, alt=2, ctrl=4 -> e.g., ctrl = bitmask 4, wire param = 5
  *
  * @module
  */
 
-// --- Codepoint → named key mappings ---
+/** A decoded keyboard event from the terminal input stream. */
+export interface KeyInput {
+  /** Normalized semantic key string (e.g. `"ctrl+s"`, `"enter"`, `"a"`). */
+  key: string;
+  /** Original insertable text, when this key should insert text. */
+  text?: string;
+}
+
+// --- Codepoint -> named key mappings ---
 
 /** Named key lookup from Unicode codepoint (for CSI u sequences). */
 const CODEPOINT_NAMES: Record<number, string> = {
@@ -60,7 +70,7 @@ const TILDE_NAMES: Record<number, string> = {
 };
 
 /**
- * Legacy byte → named key mapping for unmodified special keys.
+ * Legacy byte -> named key mapping for unmodified special keys.
  *
  * At Kitty level 1, unmodified special keys that have well-known legacy
  * encodings retain those encodings. Only modified variants (e.g., Shift+Tab,
@@ -68,8 +78,8 @@ const TILDE_NAMES: Record<number, string> = {
  * bytes that arrive for the unmodified case.
  */
 const LEGACY_BYTE_NAMES: Record<number, string> = {
-  9: "tab", // \t — also Ctrl+I in legacy, but at level 1 Ctrl+I → CSI u
-  13: "enter", // \r — also Ctrl+M in legacy, but at level 1 Ctrl+M → CSI u
+  9: "tab", // \t — also Ctrl+I in legacy, but collapsed to tab here
+  13: "enter", // \r — also Ctrl+M in legacy, but collapsed to enter here
   27: "escape", // \x1b — bare ESC byte
   127: "backspace", // \x7f — DEL byte
 };
@@ -99,9 +109,7 @@ function decodeModifiers(param: number): string {
   return parts.length > 0 ? parts.join("+") + "+" : "";
 }
 
-/**
- * Build a key string from a modifier prefix and base key name.
- */
+/** Build a key string from a modifier prefix and base key name. */
 function withModifiers(modParam: number, base: string): string {
   return decodeModifiers(modParam) + base;
 }
@@ -117,88 +125,157 @@ const CSI_LETTER_RE = /^(?:1;(\d+))?([A-H])$/;
 /** Match CSI tilde format: ESC [ <number> ; <modifiers> ~ */
 const CSI_TILDE_RE = /^(\d+)(?:;(\d+))?~$/;
 
-function parseCsiSequence(seq: string): string {
+function parseCsiSequence(seq: string): KeyInput {
   // Legacy Shift+Tab (CSI Z) — sent by tmux and some terminals
-  if (seq === "Z") return "shift+tab";
+  if (seq === "Z") return { key: "shift+tab" };
 
   // CSI u format: codepoint [; modifiers] u
   let match = CSI_U_RE.exec(seq);
   if (match) {
     const codepoint = parseInt(match[1]!, 10);
-    const modParam = match[2] ? parseInt(match[2], 10) : 0;
+    const modParam = match[2] ? parseInt(match[2]!, 10) : 0;
 
-    // Check named keys first
     const name = CODEPOINT_NAMES[codepoint];
-    if (name) return withModifiers(modParam, name);
-
-    // Printable character — convert codepoint to char, lowercase
-    const char = String.fromCodePoint(codepoint).toLowerCase();
-    return withModifiers(modParam, char);
+    if (name) {
+      return { key: withModifiers(modParam, name) };
+    }
+
+    const char = String.fromCodePoint(codepoint);
+    const key = withModifiers(modParam, char.toLowerCase());
+    if (modParam <= 1) {
+      return { key, text: char };
+    }
+    return { key };
   }
 
   // CSI letter format: [1 ; modifiers] <letter>
   match = CSI_LETTER_RE.exec(seq);
   if (match) {
-    const modParam = match[1] ? parseInt(match[1], 10) : 0;
+    const modParam = match[1] ? parseInt(match[1]!, 10) : 0;
     const letter = match[2]!;
     const name = LETTER_NAMES[letter];
-    if (name) return withModifiers(modParam, name);
+    if (name) return { key: withModifiers(modParam, name) };
   }
 
   // CSI tilde format: number [; modifiers] ~
   match = CSI_TILDE_RE.exec(seq);
   if (match) {
     const num = parseInt(match[1]!, 10);
-    const modParam = match[2] ? parseInt(match[2], 10) : 0;
+    const modParam = match[2] ? parseInt(match[2]!, 10) : 0;
     const name = TILDE_NAMES[num];
-    if (name) return withModifiers(modParam, name);
+    if (name) return { key: withModifiers(modParam, name) };
   }
 
-  return `unknown:${seq}`;
+  return { key: `unknown:${seq}` };
 }
 
-// --- Public API ---
-
-/**
- * Parse raw terminal input data into a normalized key string.
- *
- * Handles the Kitty keyboard protocol level 1 (disambiguate) encoding:
- * - CSI u sequences for special keys and modifier combos
- * - CSI letter sequences for arrow keys and Home/End (with optional modifiers)
- * - CSI tilde sequences for Delete, PageUp/Down, and function keys
- * - Raw printable characters (unmodified, arrive as raw bytes at level 1)
- *
- * @param data - Raw terminal input string.
- * @returns Normalized key string (e.g., `"ctrl+s"`, `"escape"`, `"alt+up"`).
- */
-export function parseKey(data: string): string {
-  // CSI sequences: ESC [ ...
-  if (data.startsWith("\x1b[")) {
-    return parseCsiSequence(data.slice(2));
+function decodeLegacyControlByte(code: number): string | null {
+  if (code >= 1 && code <= 26) {
+    return `ctrl+${String.fromCharCode(code + 96)}`;
   }
+  return null;
+}
 
-  // Single-character input
-  if (data.length === 1) {
-    const code = data.charCodeAt(0);
+function parseRawKeyInput(data: string): KeyInput {
+  const code = data.charCodeAt(0);
 
-    // Legacy bytes for unmodified special keys (Kitty level 1 retains these)
-    const legacy = LEGACY_BYTE_NAMES[code];
-    if (legacy) return legacy;
+  const legacy = LEGACY_BYTE_NAMES[code];
+  if (legacy) return { key: legacy };
 
-    // Named printable characters
-    const named = CHAR_NAMES[data];
-    if (named) return named;
+  const ctrl = decodeLegacyControlByte(code);
+  if (ctrl) return { key: ctrl };
+
+  const named = CHAR_NAMES[data];
+  if (named) return { key: named, text: data };
+
+  return { key: data.toLowerCase(), text: data };
+}
+
+function parseAltKeyInput(data: string): KeyInput {
+  const base = parseRawKeyInput(data);
+  return { key: normalizeKey(`alt+${base.key}`) };
+}
 
-    // Printable characters — return lowercase
-    return data.toLowerCase();
+function readCodePoint(
+  data: string,
+  index: number,
+): { value: string; nextIndex: number } | null {
+  if (index >= data.length) return null;
+  const codepoint = data.codePointAt(index);
+  if (codepoint === undefined) return null;
+  const value = String.fromCodePoint(codepoint);
+  return { value, nextIndex: index + value.length };
+}
+
+function readCsiSequence(
+  data: string,
+  index: number,
+): { value: string; nextIndex: number } | null {
+  if (!data.startsWith("\x1b[", index)) return null;
+
+  for (let i = index + 2; i < data.length; i++) {
+    const code = data.charCodeAt(i);
+    if (code >= 0x40 && code <= 0x7e) {
+      return { value: data.slice(index + 2, i + 1), nextIndex: i + 1 };
+    }
   }
 
-  // Multi-byte UTF-8 (e.g., emoji, CJK) — return as-is lowercase
-  if (data.length > 1) {
-    return data.toLowerCase();
+  return null;
+}
+
+/**
+ * Decode a raw keyboard data chunk into ordered key events.
+ *
+ * A single chunk may contain multiple key presses batched together.
+ */
+export function decodeKeyEvents(data: string): KeyInput[] {
+  const events: KeyInput[] = [];
+  let index = 0;
+
+  while (index < data.length) {
+    const csi = readCsiSequence(data, index);
+    if (csi) {
+      events.push(parseCsiSequence(csi.value));
+      index = csi.nextIndex;
+      continue;
+    }
+
+    const char = data[index]!;
+    if (char === "\x1b") {
+      const next = readCodePoint(data, index + 1);
+      if (next && next.value !== "[") {
+        events.push(parseAltKeyInput(next.value));
+        index = next.nextIndex;
+      } else {
+        events.push({ key: "escape" });
+        index += 1;
+      }
+      continue;
+    }
+
+    const codePoint = readCodePoint(data, index);
+    if (!codePoint) break;
+    events.push(parseRawKeyInput(codePoint.value));
+    index = codePoint.nextIndex;
   }
 
-  return `unknown:${data}`;
+  return events;
+}
+
+// --- Public API ---
+
+/**
+ * Parse a single raw key sequence into a normalized key string.
+ *
+ * This is a convenience wrapper around {@link decodeKeyEvents} for callers that
+ * already know the input contains one logical key event.
+ *
+ * @param data - Raw terminal input string.
+ * @returns Normalized key string (e.g., `"ctrl+s"`, `"escape"`, `"alt+up"`).
+ */
+export function parseKey(data: string): string {
+  const events = decodeKeyEvents(data);
+  return events[0]?.key ?? `unknown:${data}`;
 }
 
 /**
@@ -217,7 +294,6 @@ export function normalizeKey(key: string): string {
   const base = parts[parts.length - 1]!;
   const mods = parts.slice(0, -1);
 
-  // Canonical order: ctrl, alt, shift
   const ordered: string[] = [];
   if (mods.includes("ctrl")) ordered.push("ctrl");
   if (mods.includes("alt")) ordered.push("alt");
@@ -227,14 +303,15 @@ export function normalizeKey(key: string): string {
 }
 
 /**
- * Check if a parsed key is a text-editing key that TextInput should consume.
- * Modifier combos (ctrl+s, alt+x) are NOT editing keys and should bubble.
+ * Check whether a semantic key represents TextInput editing/navigation.
+ *
+ * Single-character semantic keys represent insertable text, while named keys
+ * like `"enter"` and `"left"` represent editing/navigation actions. Modifier
+ * combos (`ctrl+s`, `alt+x`) are NOT editing keys and should bubble.
  */
 export function isEditingKey(key: string): boolean {
-  // Single printable characters
   if (key.length === 1) return true;
 
-  // Navigation and editing keys consumed by TextInput
   const editingKeys = new Set([
     "enter",
     "backspace",

package/src/primitives/text-input.ts

@@ -11,12 +11,14 @@ import type { TextInputNode, TextInputProps } from "@cel-tui/types";
  * Scroll is always uncontrolled — the view follows the cursor and
  * responds to mouse wheel automatically.
  *
- * TextInput is always focusable. When focused, text-editing keys
- * (printable characters, arrows, backspace, Enter, Tab) are consumed.
- * Modifier combos (e.g., `ctrl+s`) bubble up to ancestor `onKeyPress` handlers.
+ * TextInput is always focusable. When focused, it consumes insertable text
+ * plus editing/navigation keys (arrows, backspace, delete, Enter, Tab).
+ * Modifier combos (e.g., `ctrl+s`) and non-insertable control keys bubble
+ * up to ancestor `onKeyPress` handlers.
  *
- * Use `onKeyPress` to intercept keys before editing. Return `false` to
- * prevent the default editing action for that key.
+ * Use `onKeyPress` to intercept keys before editing. The handler receives a
+ * normalized semantic key string; inserted text preserves the original
+ * characters. Return `false` to prevent the default editing action.
  *
  * @param props - Value, callbacks, sizing, styling, and focus props.
  * @returns A text input node for the UI tree.

package/src/terminal.ts

@@ -11,7 +11,13 @@ export interface Terminal {
   get columns(): number;
   /** Terminal height in rows. */
   get rows(): number;
-  /** Enter raw mode, enable Kitty keyboard protocol, enable mouse tracking, hide cursor. */
+  /**
+   * Enter raw mode, enable Kitty level 1 keyboard reporting, enable mouse
+   * tracking, and hide the cursor.
+   *
+   * The framework prefers Kitty semantics but its parser also accepts mixed
+   * tmux/legacy keyboard encodings that may still arrive on stdin.
+   */
   start(onInput: (data: string) => void, onResize: () => void): void;
   /** Restore terminal state. */
   stop(): void;
@@ -24,8 +30,10 @@ export interface Terminal {
 /**
  * Real terminal using process.stdin/stdout.
  *
- * Enables the Kitty keyboard protocol (level 1) for unambiguous key input,
- * SGR mouse tracking, and raw mode. All modes are restored on stop/crash.
+ * Enables Kitty keyboard protocol level 1, SGR mouse tracking, and raw mode.
+ * The runtime prefers Kitty semantics for full modifier fidelity, while the
+ * parser remains compatible with mixed tmux/legacy keyboard encodings that
+ * may still arrive on stdin. All modes are restored on stop/crash.
  */
 export class ProcessTerminal implements Terminal {
   private wasRaw = false;