nastech-tui 0.0.1

package/packages/nastech-ink/src/ink/termio/ansi.ts

@@ -0,0 +1,75 @@
+/**
+ * ANSI Control Characters and Escape Sequence Introducers
+ *
+ * Based on ECMA-48 / ANSI X3.64 standards.
+ */
+
+/**
+ * C0 (7-bit) control characters
+ */
+export const C0 = {
+  NUL: 0x00,
+  SOH: 0x01,
+  STX: 0x02,
+  ETX: 0x03,
+  EOT: 0x04,
+  ENQ: 0x05,
+  ACK: 0x06,
+  BEL: 0x07,
+  BS: 0x08,
+  HT: 0x09,
+  LF: 0x0a,
+  VT: 0x0b,
+  FF: 0x0c,
+  CR: 0x0d,
+  SO: 0x0e,
+  SI: 0x0f,
+  DLE: 0x10,
+  DC1: 0x11,
+  DC2: 0x12,
+  DC3: 0x13,
+  DC4: 0x14,
+  NAK: 0x15,
+  SYN: 0x16,
+  ETB: 0x17,
+  CAN: 0x18,
+  EM: 0x19,
+  SUB: 0x1a,
+  ESC: 0x1b,
+  FS: 0x1c,
+  GS: 0x1d,
+  RS: 0x1e,
+  US: 0x1f,
+  DEL: 0x7f
+} as const
+
+// String constants for output generation
+export const ESC = '\x1b'
+export const BEL = '\x07'
+export const SEP = ';'
+
+/**
+ * Escape sequence type introducers (byte after ESC)
+ */
+export const ESC_TYPE = {
+  CSI: 0x5b, // [ - Control Sequence Introducer
+  OSC: 0x5d, // ] - Operating System Command
+  DCS: 0x50, // P - Device Control String
+  APC: 0x5f, // _ - Application Program Command
+  PM: 0x5e, // ^ - Privacy Message
+  SOS: 0x58, // X - Start of String
+  ST: 0x5c // \ - String Terminator
+} as const
+
+/** Check if a byte is a C0 control character */
+export function isC0(byte: number): boolean {
+  return byte < 0x20 || byte === 0x7f
+}
+
+/**
+ * Check if a byte is an ESC sequence final byte (0-9, :, ;, <, =, >, ?, @ through ~)
+ * ESC sequences have a wider final byte range than CSI
+ */
+export function isEscFinal(byte: number): boolean {
+  return byte >= 0x30 && byte <= 0x7e
+}

package/packages/nastech-ink/src/ink/termio/csi.ts

@@ -0,0 +1,334 @@
+/**
+ * CSI (Control Sequence Introducer) Types
+ *
+ * Enums and types for CSI command parameters.
+ */
+
+import { ESC, ESC_TYPE, SEP } from './ansi.js'
+
+export const CSI_PREFIX = ESC + String.fromCharCode(ESC_TYPE.CSI)
+
+/**
+ * CSI parameter byte ranges
+ */
+export const CSI_RANGE = {
+  PARAM_START: 0x30,
+  PARAM_END: 0x3f,
+  INTERMEDIATE_START: 0x20,
+  INTERMEDIATE_END: 0x2f,
+  FINAL_START: 0x40,
+  FINAL_END: 0x7e
+} as const
+
+/** Check if a byte is a CSI parameter byte */
+export function isCSIParam(byte: number): boolean {
+  return byte >= CSI_RANGE.PARAM_START && byte <= CSI_RANGE.PARAM_END
+}
+
+/** Check if a byte is a CSI intermediate byte */
+export function isCSIIntermediate(byte: number): boolean {
+  return byte >= CSI_RANGE.INTERMEDIATE_START && byte <= CSI_RANGE.INTERMEDIATE_END
+}
+
+/** Check if a byte is a CSI final byte (@ through ~) */
+export function isCSIFinal(byte: number): boolean {
+  return byte >= CSI_RANGE.FINAL_START && byte <= CSI_RANGE.FINAL_END
+}
+
+/**
+ * Generate a CSI sequence: ESC [ p1;p2;...;pN final
+ * Single arg: treated as raw body
+ * Multiple args: last is final byte, rest are params joined by ;
+ */
+export function csi(...args: (string | number)[]): string {
+  if (args.length === 0) {
+    return CSI_PREFIX
+  }
+
+  if (args.length === 1) {
+    return `${CSI_PREFIX}${args[0]}`
+  }
+
+  const params = args.slice(0, -1)
+  const final = args[args.length - 1]
+
+  return `${CSI_PREFIX}${params.join(SEP)}${final}`
+}
+
+/**
+ * CSI final bytes - the command identifier
+ */
+export const CSI = {
+  // Cursor movement
+  CUU: 0x41, // A - Cursor Up
+  CUD: 0x42, // B - Cursor Down
+  CUF: 0x43, // C - Cursor Forward
+  CUB: 0x44, // D - Cursor Back
+  CNL: 0x45, // E - Cursor Next Line
+  CPL: 0x46, // F - Cursor Previous Line
+  CHA: 0x47, // G - Cursor Horizontal Absolute
+  CUP: 0x48, // H - Cursor Position
+  CHT: 0x49, // I - Cursor Horizontal Tab
+  VPA: 0x64, // d - Vertical Position Absolute
+  HVP: 0x66, // f - Horizontal Vertical Position
+
+  // Erase
+  ED: 0x4a, // J - Erase in Display
+  EL: 0x4b, // K - Erase in Line
+  ECH: 0x58, // X - Erase Character
+
+  // Insert/Delete
+  IL: 0x4c, // L - Insert Lines
+  DL: 0x4d, // M - Delete Lines
+  ICH: 0x40, // @ - Insert Characters
+  DCH: 0x50, // P - Delete Characters
+
+  // Scroll
+  SU: 0x53, // S - Scroll Up
+  SD: 0x54, // T - Scroll Down
+
+  // Modes
+  SM: 0x68, // h - Set Mode
+  RM: 0x6c, // l - Reset Mode
+
+  // SGR
+  SGR: 0x6d, // m - Select Graphic Rendition
+
+  // Other
+  DSR: 0x6e, // n - Device Status Report
+  DECSCUSR: 0x71, // q - Set Cursor Style (with space intermediate)
+  DECSTBM: 0x72, // r - Set Top and Bottom Margins
+  SCOSC: 0x73, // s - Save Cursor Position
+  SCORC: 0x75, // u - Restore Cursor Position
+  CBT: 0x5a // Z - Cursor Backward Tabulation
+} as const
+
+/**
+ * Erase in Display regions (ED command parameter)
+ */
+export const ERASE_DISPLAY = ['toEnd', 'toStart', 'all', 'scrollback'] as const
+
+/**
+ * Erase in Line regions (EL command parameter)
+ */
+export const ERASE_LINE_REGION = ['toEnd', 'toStart', 'all'] as const
+
+/**
+ * Cursor styles (DECSCUSR)
+ */
+export type CursorStyle = 'block' | 'underline' | 'bar'
+
+export const CURSOR_STYLES: Array<{ style: CursorStyle; blinking: boolean }> = [
+  { style: 'block', blinking: true }, // 0 - default
+  { style: 'block', blinking: true }, // 1
+  { style: 'block', blinking: false }, // 2
+  { style: 'underline', blinking: true }, // 3
+  { style: 'underline', blinking: false }, // 4
+  { style: 'bar', blinking: true }, // 5
+  { style: 'bar', blinking: false } // 6
+]
+
+// Cursor movement generators
+
+/** Move cursor up n lines (CSI n A) */
+export function cursorUp(n = 1): string {
+  return n === 0 ? '' : csi(n, 'A')
+}
+
+/** Move cursor down n lines (CSI n B) */
+export function cursorDown(n = 1): string {
+  return n === 0 ? '' : csi(n, 'B')
+}
+
+/** Move cursor forward n columns (CSI n C) */
+export function cursorForward(n = 1): string {
+  return n === 0 ? '' : csi(n, 'C')
+}
+
+/** Move cursor back n columns (CSI n D) */
+export function cursorBack(n = 1): string {
+  return n === 0 ? '' : csi(n, 'D')
+}
+
+/** Move cursor to column n (1-indexed) (CSI n G) */
+export function cursorTo(col: number): string {
+  return csi(col, 'G')
+}
+
+/** Move cursor to column 1 (CSI G) */
+export const CURSOR_LEFT = csi('G')
+
+/** Move cursor to row, col (1-indexed) (CSI row ; col H) */
+export function cursorPosition(row: number, col: number): string {
+  return csi(row, col, 'H')
+}
+
+/** Move cursor to home position (CSI H) */
+export const CURSOR_HOME = csi('H')
+
+/**
+ * Move cursor relative to current position
+ * Positive x = right, negative x = left
+ * Positive y = down, negative y = up
+ */
+export function cursorMove(x: number, y: number): string {
+  let result = ''
+
+  // Horizontal first (matches ansi-escapes behavior)
+  if (x < 0) {
+    result += cursorBack(-x)
+  } else if (x > 0) {
+    result += cursorForward(x)
+  }
+
+  // Then vertical
+  if (y < 0) {
+    result += cursorUp(-y)
+  } else if (y > 0) {
+    result += cursorDown(y)
+  }
+
+  return result
+}
+
+// Save/restore cursor position
+
+/** Save cursor position (CSI s) */
+export const CURSOR_SAVE = csi('s')
+
+/** Restore cursor position (CSI u) */
+export const CURSOR_RESTORE = csi('u')
+
+// Erase generators
+
+/** Erase from cursor to end of line (CSI K) */
+export function eraseToEndOfLine(): string {
+  return csi('K')
+}
+
+/** Erase from cursor to start of line (CSI 1 K) */
+export function eraseToStartOfLine(): string {
+  return csi(1, 'K')
+}
+
+/** Erase entire line (CSI 2 K) */
+export function eraseLine(): string {
+  return csi(2, 'K')
+}
+
+/** Erase entire line - constant form */
+export const ERASE_LINE = csi(2, 'K')
+
+/** Erase from cursor to end of screen (CSI J) */
+export function eraseToEndOfScreen(): string {
+  return csi('J')
+}
+
+/** Erase from cursor to start of screen (CSI 1 J) */
+export function eraseToStartOfScreen(): string {
+  return csi(1, 'J')
+}
+
+/** Erase entire screen (CSI 2 J) */
+export function eraseScreen(): string {
+  return csi(2, 'J')
+}
+
+/** Erase entire screen - constant form */
+export const ERASE_SCREEN = csi(2, 'J')
+
+/** Erase scrollback buffer (CSI 3 J) */
+export const ERASE_SCROLLBACK = csi(3, 'J')
+
+/**
+ * Erase n lines starting from cursor line, moving cursor up
+ * This erases each line and moves up, ending at column 1
+ */
+export function eraseLines(n: number): string {
+  if (n <= 0) {
+    return ''
+  }
+
+  let result = ''
+
+  for (let i = 0; i < n; i++) {
+    result += ERASE_LINE
+
+    if (i < n - 1) {
+      result += cursorUp(1)
+    }
+  }
+
+  result += CURSOR_LEFT
+
+  return result
+}
+
+// Scroll
+
+/** Scroll up n lines (CSI n S) */
+export function scrollUp(n = 1): string {
+  return n === 0 ? '' : csi(n, 'S')
+}
+
+/** Scroll down n lines (CSI n T) */
+export function scrollDown(n = 1): string {
+  return n === 0 ? '' : csi(n, 'T')
+}
+
+/** Set scroll region (DECSTBM, CSI top;bottom r). 1-indexed, inclusive. */
+export function setScrollRegion(top: number, bottom: number): string {
+  return csi(top, bottom, 'r')
+}
+
+/** Reset scroll region to full screen (DECSTBM, CSI r). Homes the cursor. */
+export const RESET_SCROLL_REGION = csi('r')
+
+// Bracketed paste markers (input from terminal, not output)
+// These are sent by the terminal to delimit pasted content when
+// bracketed paste mode is enabled (via DEC mode 2004)
+
+/** Sent by terminal before pasted content (CSI 200 ~) */
+export const PASTE_START = csi('200~')
+
+/** Sent by terminal after pasted content (CSI 201 ~) */
+export const PASTE_END = csi('201~')
+
+// Focus event markers (input from terminal, not output)
+// These are sent by the terminal when focus changes while
+// focus events mode is enabled (via DEC mode 1004)
+
+/** Sent by terminal when it gains focus (CSI I) */
+export const FOCUS_IN = csi('I')
+
+/** Sent by terminal when it loses focus (CSI O) */
+export const FOCUS_OUT = csi('O')
+
+// Kitty keyboard protocol (CSI u)
+// Enables enhanced key reporting with modifier information
+// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+
+/**
+ * Enable Kitty keyboard protocol with basic modifier reporting
+ * CSI > 1 u - pushes mode with flags=1 (disambiguate escape codes)
+ * This makes Shift+Enter send CSI 13;2 u instead of just CR
+ */
+export const ENABLE_KITTY_KEYBOARD = csi('>1u')
+
+/**
+ * Disable Kitty keyboard protocol
+ * CSI < u - pops the keyboard mode stack
+ */
+export const DISABLE_KITTY_KEYBOARD = csi('<u')
+
+/**
+ * Enable xterm modifyOtherKeys level 2.
+ * tmux accepts this (not the kitty stack) to enable extended keys — when
+ * extended-keys-format is csi-u, tmux then emits keys in kitty format.
+ */
+export const ENABLE_MODIFY_OTHER_KEYS = csi('>4;2m')
+
+/**
+ * Disable xterm modifyOtherKeys (reset to default).
+ */
+export const DISABLE_MODIFY_OTHER_KEYS = csi('>4m')

package/packages/nastech-ink/src/ink/termio/dec.ts

@@ -0,0 +1,99 @@
+/**
+ * DEC (Digital Equipment Corporation) Private Mode Sequences
+ *
+ * DEC private modes use CSI ? N h (set) and CSI ? N l (reset) format.
+ * These are terminal-specific extensions to the ANSI standard.
+ */
+
+import { csi } from './csi.js'
+
+/**
+ * DEC private mode numbers
+ */
+export const DEC = {
+  CURSOR_VISIBLE: 25,
+  ALT_SCREEN: 47,
+  ALT_SCREEN_CLEAR: 1049,
+  MOUSE_NORMAL: 1000,
+  MOUSE_BUTTON: 1002,
+  MOUSE_ANY: 1003,
+  MOUSE_SGR: 1006,
+  FOCUS_EVENTS: 1004,
+  BRACKETED_PASTE: 2004,
+  SYNCHRONIZED_UPDATE: 2026
+} as const
+
+/** Generate CSI ? N h sequence (set mode) */
+export function decset(mode: number): string {
+  return csi(`?${mode}h`)
+}
+
+/** Generate CSI ? N l sequence (reset mode) */
+export function decreset(mode: number): string {
+  return csi(`?${mode}l`)
+}
+
+// Pre-generated sequences for common modes
+export const BSU = decset(DEC.SYNCHRONIZED_UPDATE)
+export const ESU = decreset(DEC.SYNCHRONIZED_UPDATE)
+export const EBP = decset(DEC.BRACKETED_PASTE)
+export const DBP = decreset(DEC.BRACKETED_PASTE)
+export const EFE = decset(DEC.FOCUS_EVENTS)
+export const DFE = decreset(DEC.FOCUS_EVENTS)
+export const SHOW_CURSOR = decset(DEC.CURSOR_VISIBLE)
+export const HIDE_CURSOR = decreset(DEC.CURSOR_VISIBLE)
+export const ENTER_ALT_SCREEN = decset(DEC.ALT_SCREEN_CLEAR)
+export const EXIT_ALT_SCREEN = decreset(DEC.ALT_SCREEN_CLEAR)
+// Mouse tracking: 1000 reports button press/release/wheel, 1002 adds drag
+// events (button-motion), 1003 adds all-motion (no button held — for
+// hover), 1006 uses SGR format (CSI < btn;col;row M/m) instead of legacy
+// X10 bytes.
+//
+// Modes are addressable as a preset so users can opt out of 1003 (hover),
+// which is the noisy one inside tmux — every cursor cross of the prompt
+// row triggers a clipboard probe that surfaces as "No image in clipboard".
+// Presets:
+//   - 'off'     — no DECSET, terminal/tmux native selection + scroll work
+//   - 'wheel'   — 1000 + 1006: click + wheel only, no drag, no hover
+//   - 'buttons' — 1000 + 1002 + 1006: adds drag (text selection), no hover
+//   - 'all'     — 1000 + 1002 + 1003 + 1006: legacy behavior, hover-driven
+//                 UI (scrollbar paginate-on-hover, link mouseenter, etc.)
+export type MouseTrackingMode = 'all' | 'buttons' | 'off' | 'wheel'
+
+const MOUSE_NORMAL = decset(DEC.MOUSE_NORMAL)
+const MOUSE_BUTTON = decset(DEC.MOUSE_BUTTON)
+const MOUSE_ANY = decset(DEC.MOUSE_ANY)
+const MOUSE_SGR = decset(DEC.MOUSE_SGR)
+
+/** Sequence to enable the requested mouse tracking preset, or '' for 'off'. */
+export function enableMouseTrackingFor(mode: MouseTrackingMode): string {
+  switch (mode) {
+    case 'all':
+      return MOUSE_NORMAL + MOUSE_BUTTON + MOUSE_ANY + MOUSE_SGR
+
+    case 'buttons':
+      return MOUSE_NORMAL + MOUSE_BUTTON + MOUSE_SGR
+
+    case 'wheel':
+      return MOUSE_NORMAL + MOUSE_SGR
+
+    case 'off':
+      return ''
+
+    default:
+      // Defensive fallback: the type system guarantees exhaustiveness, but
+      // JS callers / corrupted config / hot-reloads in dev could reach this
+      // with an unknown value. Without a default, an unmatched mode returns
+      // undefined which then concatenates as the literal string "undefined"
+      // into the terminal byte stream — visibly garbling output. Treat
+      // unknown as 'off' (no DEC sequences) so the worst case is silent
+      // input loss rather than a wrecked screen.
+      return ''
+  }
+}
+
+/** Legacy alias for the maximal preset (1000 + 1002 + 1003 + 1006). */
+export const ENABLE_MOUSE_TRACKING = enableMouseTrackingFor('all')
+/** Reset every mouse mode unconditionally — safe to send when any subset is on. */
+export const DISABLE_MOUSE_TRACKING =
+  decreset(DEC.MOUSE_SGR) + decreset(DEC.MOUSE_ANY) + decreset(DEC.MOUSE_BUTTON) + decreset(DEC.MOUSE_NORMAL)

package/packages/nastech-ink/src/ink/termio/esc.ts

@@ -0,0 +1,69 @@
+/**
+ * ESC Sequence Parser
+ *
+ * Handles simple escape sequences: ESC + one or two characters
+ */
+
+import type { Action } from './types.js'
+
+/**
+ * Parse a simple ESC sequence
+ *
+ * @param chars - Characters after ESC (not including ESC itself)
+ */
+export function parseEsc(chars: string): Action | null {
+  if (chars.length === 0) {
+    return null
+  }
+
+  const first = chars[0]!
+
+  // Full reset (RIS)
+  if (first === 'c') {
+    return { type: 'reset' }
+  }
+
+  // Cursor save (DECSC)
+  if (first === '7') {
+    return { type: 'cursor', action: { type: 'save' } }
+  }
+
+  // Cursor restore (DECRC)
+  if (first === '8') {
+    return { type: 'cursor', action: { type: 'restore' } }
+  }
+
+  // Index - move cursor down (IND)
+  if (first === 'D') {
+    return {
+      type: 'cursor',
+      action: { type: 'move', direction: 'down', count: 1 }
+    }
+  }
+
+  // Reverse index - move cursor up (RI)
+  if (first === 'M') {
+    return {
+      type: 'cursor',
+      action: { type: 'move', direction: 'up', count: 1 }
+    }
+  }
+
+  // Next line (NEL)
+  if (first === 'E') {
+    return { type: 'cursor', action: { type: 'nextLine', count: 1 } }
+  }
+
+  // Horizontal tab set (HTS)
+  if (first === 'H') {
+    return null // Tab stop, not commonly needed
+  }
+
+  // Charset selection (ESC ( X, ESC ) X, etc.) - silently ignore
+  if ('()'.includes(first) && chars.length >= 2) {
+    return null
+  }
+
+  // Unknown
+  return { type: 'unknown', sequence: `\x1b${chars}` }
+}