nastech-tui 0.0.1

package/packages/nastech-ink/nastech-ink/src/ink/bidi.ts

@@ -0,0 +1,145 @@
+/**
+ * Bidirectional text reordering for terminal rendering.
+ *
+ * Terminals on Windows do not implement the Unicode Bidi Algorithm,
+ * so RTL text (Hebrew, Arabic, etc.) appears reversed. This module
+ * applies the bidi algorithm to reorder ClusteredChar arrays from
+ * logical order to visual order before Ink's LTR cell placement loop.
+ *
+ * On macOS terminals (Terminal.app, iTerm2) bidi works natively.
+ * Windows Terminal (including WSL) does not implement bidi
+ * (https://github.com/microsoft/terminal/issues/538).
+ *
+ * Detection: Windows Terminal sets WT_SESSION; native Windows cmd/conhost
+ * also lacks bidi. We enable bidi reordering when running on Windows or
+ * inside Windows Terminal (covers WSL).
+ */
+import bidiFactory from 'bidi-js'
+
+type ClusteredChar = {
+  value: string
+  width: number
+  styleId: number
+  hyperlink: string | undefined
+}
+
+let bidiInstance: ReturnType<typeof bidiFactory> | undefined
+let needsSoftwareBidi: boolean | undefined
+
+function needsBidi(): boolean {
+  if (needsSoftwareBidi === undefined) {
+    needsSoftwareBidi =
+      process.platform === 'win32' ||
+      typeof process.env['WT_SESSION'] === 'string' || // WSL in Windows Terminal
+      process.env['TERM_PROGRAM'] === 'vscode' // VS Code integrated terminal (xterm.js)
+  }
+
+  return needsSoftwareBidi
+}
+
+function getBidi() {
+  if (!bidiInstance) {
+    bidiInstance = bidiFactory()
+  }
+
+  return bidiInstance
+}
+
+/**
+ * Reorder an array of ClusteredChars from logical order to visual order
+ * using the Unicode Bidi Algorithm. Active on terminals that lack native
+ * bidi support (Windows Terminal, conhost, WSL).
+ *
+ * Returns the same array on bidi-capable terminals (no-op).
+ */
+export function reorderBidi(characters: ClusteredChar[]): ClusteredChar[] {
+  if (!needsBidi() || characters.length === 0) {
+    return characters
+  }
+
+  // Build a plain string from the clustered chars to run through bidi
+  const plainText = characters.map(c => c.value).join('')
+
+  // Check if there are any RTL characters — skip bidi if pure LTR
+  if (!hasRTLCharacters(plainText)) {
+    return characters
+  }
+
+  const bidi = getBidi()
+  const { levels } = bidi.getEmbeddingLevels(plainText, 'auto')
+
+  // Map bidi levels back to ClusteredChar indices.
+  // Each ClusteredChar may be multiple code units in the joined string.
+  const charLevels: number[] = []
+  let offset = 0
+
+  for (let i = 0; i < characters.length; i++) {
+    charLevels.push(levels[offset]!)
+    offset += characters[i]!.value.length
+  }
+
+  // Get reorder segments from bidi-js, but we need to work at the
+  // ClusteredChar level, not the string level. We'll implement the
+  // standard bidi reordering: find the max level, then for each level
+  // from max down to 1, reverse all contiguous runs >= that level.
+  const reordered = [...characters]
+  const maxLevel = Math.max(...charLevels)
+
+  for (let level = maxLevel; level >= 1; level--) {
+    let i = 0
+
+    while (i < reordered.length) {
+      if (charLevels[i]! >= level) {
+        // Find the end of this run
+        let j = i + 1
+
+        while (j < reordered.length && charLevels[j]! >= level) {
+          j++
+        }
+
+        // Reverse the run in both arrays
+        reverseRange(reordered, i, j - 1)
+        reverseRangeNumbers(charLevels, i, j - 1)
+        i = j
+      } else {
+        i++
+      }
+    }
+  }
+
+  return reordered
+}
+
+function reverseRange<T>(arr: T[], start: number, end: number): void {
+  while (start < end) {
+    const temp = arr[start]!
+    arr[start] = arr[end]!
+    arr[end] = temp
+    start++
+    end--
+  }
+}
+
+function reverseRangeNumbers(arr: number[], start: number, end: number): void {
+  while (start < end) {
+    const temp = arr[start]!
+    arr[start] = arr[end]!
+    arr[end] = temp
+    start++
+    end--
+  }
+}
+
+/**
+ * Quick check for RTL characters (Hebrew, Arabic, and related scripts).
+ * Avoids running the full bidi algorithm on pure-LTR text.
+ */
+function hasRTLCharacters(text: string): boolean {
+  // Hebrew: U+0590-U+05FF, U+FB1D-U+FB4F
+  // Arabic: U+0600-U+06FF, U+0750-U+077F, U+08A0-U+08FF, U+FB50-U+FDFF, U+FE70-U+FEFF
+  // Thaana: U+0780-U+07BF
+  // Syriac: U+0700-U+074F
+  return /[\u0590-\u05FF\uFB1D-\uFB4F\u0600-\u06FF\u0750-\u077F\u08A0-\u08FF\uFB50-\uFDFF\uFE70-\uFEFF\u0780-\u07BF\u0700-\u074F]/u.test(
+    text
+  )
+}

package/packages/nastech-ink/nastech-ink/src/ink/cache-eviction.ts

@@ -0,0 +1,45 @@
+// Unified cache eviction for the four hot Ink module-level caches:
+//   - widthCache       (stringWidth.ts)
+//   - wrapCache        (wrap-text.ts)
+//   - sliceCache       (sliceAnsi.ts)
+//   - lineWidthCache   (line-width-cache.ts)
+//
+// Used by the host (TUI) under memory pressure or on session swap to drop
+// content-keyed entries that won't recur. All caches are content-keyed
+// (not session-keyed), so cross-session sharing is normally beneficial —
+// only evict when memory tightens or when the user explicitly resets.
+
+import { evictSliceCache, sliceCacheSize } from '../utils/sliceAnsi.js'
+
+import { evictLineWidthCache, lineWidthCacheSize } from './line-width-cache.js'
+import { evictWidthCache, widthCacheSize } from './stringWidth.js'
+import { evictWrapCache, wrapCacheSize } from './wrap-text.js'
+
+export interface InkCacheSizes {
+  lineWidth: number
+  slice: number
+  width: number
+  wrap: number
+}
+
+function inkCacheSizes(): InkCacheSizes {
+  return {
+    lineWidth: lineWidthCacheSize(),
+    slice: sliceCacheSize(),
+    width: widthCacheSize(),
+    wrap: wrapCacheSize()
+  }
+}
+
+export type EvictLevel = 'all' | 'half'
+
+export function evictInkCaches(level: EvictLevel = 'half'): InkCacheSizes {
+  const keep = level === 'half' ? 0.5 : 0
+
+  evictWidthCache(keep)
+  evictWrapCache(keep)
+  evictSliceCache(keep)
+  evictLineWidthCache(keep)
+
+  return inkCacheSizes()
+}

package/packages/nastech-ink/nastech-ink/src/ink/clearTerminal.ts

@@ -0,0 +1,68 @@
+/**
+ * Cross-platform terminal clearing with scrollback support.
+ * Detects modern terminals that support ESC[3J for clearing scrollback.
+ */
+
+import { csi, CURSOR_HOME, ERASE_SCREEN, ERASE_SCROLLBACK } from './termio/csi.js'
+
+// HVP (Horizontal Vertical Position) - legacy Windows cursor home
+const CURSOR_HOME_WINDOWS = csi(0, 'f')
+
+function isWindowsTerminal(): boolean {
+  return process.platform === 'win32' && !!process.env.WT_SESSION
+}
+
+function isMintty(): boolean {
+  // mintty 3.1.5+ sets TERM_PROGRAM to 'mintty'
+  if (process.env.TERM_PROGRAM === 'mintty') {
+    return true
+  }
+
+  // GitBash/MSYS2/MINGW use mintty and set MSYSTEM
+  if (process.platform === 'win32' && process.env.MSYSTEM) {
+    return true
+  }
+
+  return false
+}
+
+function isModernWindowsTerminal(): boolean {
+  // Windows Terminal sets WT_SESSION environment variable
+  if (isWindowsTerminal()) {
+    return true
+  }
+
+  // VS Code integrated terminal on Windows with ConPTY support
+  if (process.platform === 'win32' && process.env.TERM_PROGRAM === 'vscode' && process.env.TERM_PROGRAM_VERSION) {
+    return true
+  }
+
+  // mintty (GitBash/MSYS2/Cygwin) supports modern escape sequences
+  if (isMintty()) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Returns the ANSI escape sequence to clear the terminal including scrollback.
+ * Automatically detects terminal capabilities.
+ */
+export function getClearTerminalSequence(): string {
+  if (process.platform === 'win32') {
+    if (isModernWindowsTerminal()) {
+      return ERASE_SCREEN + ERASE_SCROLLBACK + CURSOR_HOME
+    } else {
+      // Legacy Windows console - can't clear scrollback
+      return ERASE_SCREEN + CURSOR_HOME_WINDOWS
+    }
+  }
+
+  return ERASE_SCREEN + ERASE_SCROLLBACK + CURSOR_HOME
+}
+
+/**
+ * Clears the terminal screen. On supported terminals, also clears scrollback.
+ */
+export const clearTerminal = getClearTerminalSequence()

package/packages/nastech-ink/nastech-ink/src/ink/colorize.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  CHALK_USES_RICH_EIGHT_BIT_DOWNGRADE,
+  richEightBitColorNumber,
+  shouldUseRichEightBitDowngradeForLegacyAppleTerminal
+} from './colorize.js'
+
+describe('shouldUseRichEightBitDowngradeForLegacyAppleTerminal', () => {
+  it('memoizes the current process decision for render hot paths', () => {
+    expect(typeof CHALK_USES_RICH_EIGHT_BIT_DOWNGRADE).toBe('boolean')
+  })
+
+  it('uses Rich-compatible 256-color downgrade on legacy Apple Terminal', () => {
+    expect(
+      shouldUseRichEightBitDowngradeForLegacyAppleTerminal({ TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv, 2)
+    ).toBe(true)
+  })
+
+  it('normalizes Apple Terminal names before matching', () => {
+    expect(
+      shouldUseRichEightBitDowngradeForLegacyAppleTerminal({ TERM_PROGRAM: ' Apple_Terminal ' } as NodeJS.ProcessEnv, 2)
+    ).toBe(true)
+  })
+
+  it('does not rewrite when Apple Terminal advertises truecolor', () => {
+    expect(
+      shouldUseRichEightBitDowngradeForLegacyAppleTerminal(
+        { COLORTERM: 'truecolor', TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv,
+        3
+      )
+    ).toBe(false)
+  })
+
+  it('does not override explicit color environment choices', () => {
+    expect(
+      shouldUseRichEightBitDowngradeForLegacyAppleTerminal(
+        { FORCE_COLOR: '2', TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv,
+        2
+      )
+    ).toBe(false)
+    expect(
+      shouldUseRichEightBitDowngradeForLegacyAppleTerminal(
+        { NASTECH_TUI_TRUECOLOR: '1', TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv,
+        3
+      )
+    ).toBe(false)
+  })
+})
+
+describe('richEightBitColorNumber', () => {
+  it('matches Rich downgrade output for default NasTech skin colors', () => {
+    expect(richEightBitColorNumber(0xff, 0xd7, 0x00)).toBe(220)
+    expect(richEightBitColorNumber(0xff, 0xbf, 0x00)).toBe(214)
+    expect(richEightBitColorNumber(0xcd, 0x7f, 0x32)).toBe(173)
+    expect(richEightBitColorNumber(0xb8, 0x86, 0x0b)).toBe(136)
+    expect(richEightBitColorNumber(0xff, 0xf8, 0xdc)).toBe(230)
+  })
+})
+

package/packages/nastech-ink/nastech-ink/src/ink/colorize.ts

@@ -0,0 +1,277 @@
+import chalk from 'chalk'
+
+import type { Color, TextStyles } from './styles.js'
+
+/**
+ * xterm.js (VS Code, Cursor, code-server, Coder) has supported truecolor
+ * since 2017, but code-server/Coder containers often don't set
+ * COLORTERM=truecolor. chalk's supports-color doesn't recognize
+ * TERM_PROGRAM=vscode (it only knows iTerm.app/Apple_Terminal), so it falls
+ * through to the -256color regex → level 2. At level 2, chalk.rgb()
+ * downgrades to the nearest 6×6×6 cube color: rgb(215,119,87) → idx 174
+ * rgb(215,135,135) — washed-out salmon.
+ *
+ * Gated on level === 2 (not < 3) to respect NO_COLOR / FORCE_COLOR=0 —
+ * those yield level 0 and are an explicit "no colors" request. Desktop VS
+ * Code sets COLORTERM=truecolor itself, so this is a no-op there (already 3).
+ *
+ * Must run BEFORE the tmux clamp — if tmux is running inside a VS Code
+ * terminal, tmux's passthrough limitation wins and we want level 2.
+ */
+function boostChalkLevelForXtermJs(): boolean {
+  if (process.env.TERM_PROGRAM === 'vscode' && chalk.level === 2) {
+    chalk.level = 3
+
+    return true
+  }
+
+  return false
+}
+
+export function shouldUseRichEightBitDowngradeForLegacyAppleTerminal(
+  env: NodeJS.ProcessEnv = process.env,
+  level = chalk.level
+): boolean {
+  const termProgram = (env.TERM_PROGRAM ?? '').trim()
+  const truecolorOverride = /^(?:1|true|yes|on)$/i.test((env.NASTECH_TUI_TRUECOLOR ?? '').trim())
+  const advertisesTruecolor = /^(?:truecolor|24bit)$/i.test((env.COLORTERM ?? '').trim())
+
+  return termProgram === 'Apple_Terminal' && !truecolorOverride && !advertisesTruecolor && !('FORCE_COLOR' in env) && level === 2
+}
+
+export function richEightBitColorNumber(red: number, green: number, blue: number): number {
+  const rn = red / 255
+  const gn = green / 255
+  const bn = blue / 255
+  const max = Math.max(rn, gn, bn)
+  const min = Math.min(rn, gn, bn)
+  const lightness = (max + min) / 2
+  const saturation = max === min ? 0 : lightness > 0.5 ? (max - min) / (2 - max - min) : (max - min) / (max + min)
+
+  if (saturation < 0.15) {
+    const gray = Math.round(lightness * 25)
+
+    return gray === 0 ? 16 : gray === 25 ? 231 : 231 + gray
+  }
+
+  const sixRed = red < 95 ? red / 95 : 1 + (red - 95) / 40
+  const sixGreen = green < 95 ? green / 95 : 1 + (green - 95) / 40
+  const sixBlue = blue < 95 ? blue / 95 : 1 + (blue - 95) / 40
+
+  return 16 + 36 * Math.round(sixRed) + 6 * Math.round(sixGreen) + Math.round(sixBlue)
+}
+
+/**
+ * tmux parses truecolor SGR (\e[48;2;r;g;bm) into its cell buffer correctly,
+ * but its client-side emitter only re-emits truecolor to the outer terminal if
+ * the outer terminal advertises Tc/RGB capability (via terminal-overrides).
+ * Default tmux config doesn't set this, so tmux emits the cell to iTerm2/etc
+ * WITHOUT the bg sequence — outer terminal's buffer has bg=default → black on
+ * dark profiles. Clamping to level 2 makes chalk emit 256-color (\e[48;5;Nm),
+ * which tmux passes through cleanly. grey93 (255) is visually identical to
+ * rgb(240,240,240).
+ *
+ * Users who HAVE set `terminal-overrides ,*:Tc` get a technically-unnecessary
+ * downgrade, but the visual difference is imperceptible. Querying
+ * `tmux show -gv terminal-overrides` to detect this would add a subprocess on
+ * startup — not worth it.
+ *
+ * $TMUX is a pty-lifecycle env var set by tmux itself; it never comes from
+ * globalSettings.env, so reading it here is correct. chalk is a singleton, so
+ * this clamps ALL truecolor output (fg+bg+hex) across the entire app.
+ */
+function clampChalkLevelForTmux(): boolean {
+  if (process.env.TMUX && chalk.level > 2) {
+    chalk.level = 2
+
+    return true
+  }
+
+  return false
+}
+
+// Computed once at module load — terminal/tmux environment doesn't change mid-session.
+// Order matters: boost first; then tmux can still clamp RGB to 256.
+// Exported for debugging — tree-shaken if unused.
+export const CHALK_BOOSTED_FOR_XTERMJS = boostChalkLevelForXtermJs()
+export const CHALK_CLAMPED_FOR_TMUX = clampChalkLevelForTmux()
+export const CHALK_USES_RICH_EIGHT_BIT_DOWNGRADE = shouldUseRichEightBitDowngradeForLegacyAppleTerminal()
+
+export type ColorType = 'foreground' | 'background'
+
+const RGB_REGEX = /^rgb\(\s?(\d+),\s?(\d+),\s?(\d+)\s?\)$/
+const ANSI_REGEX = /^ansi256\(\s?(\d+)\s?\)$/
+const HEX_REGEX = /^#[0-9a-fA-F]{6}$/
+
+export const colorize = (str: string, color: string | undefined, type: ColorType): string => {
+  if (!color) {
+    return str
+  }
+
+  if (color.startsWith('ansi:')) {
+    const value = color.substring('ansi:'.length)
+
+    switch (value) {
+      case 'black':
+        return type === 'foreground' ? chalk.black(str) : chalk.bgBlack(str)
+
+      case 'red':
+        return type === 'foreground' ? chalk.red(str) : chalk.bgRed(str)
+
+      case 'green':
+        return type === 'foreground' ? chalk.green(str) : chalk.bgGreen(str)
+
+      case 'yellow':
+        return type === 'foreground' ? chalk.yellow(str) : chalk.bgYellow(str)
+
+      case 'blue':
+        return type === 'foreground' ? chalk.blue(str) : chalk.bgBlue(str)
+
+      case 'magenta':
+        return type === 'foreground' ? chalk.magenta(str) : chalk.bgMagenta(str)
+
+      case 'cyan':
+        return type === 'foreground' ? chalk.cyan(str) : chalk.bgCyan(str)
+
+      case 'white':
+        return type === 'foreground' ? chalk.white(str) : chalk.bgWhite(str)
+
+      case 'blackBright':
+        return type === 'foreground' ? chalk.blackBright(str) : chalk.bgBlackBright(str)
+
+      case 'redBright':
+        return type === 'foreground' ? chalk.redBright(str) : chalk.bgRedBright(str)
+
+      case 'greenBright':
+        return type === 'foreground' ? chalk.greenBright(str) : chalk.bgGreenBright(str)
+
+      case 'yellowBright':
+        return type === 'foreground' ? chalk.yellowBright(str) : chalk.bgYellowBright(str)
+
+      case 'blueBright':
+        return type === 'foreground' ? chalk.blueBright(str) : chalk.bgBlueBright(str)
+
+      case 'magentaBright':
+        return type === 'foreground' ? chalk.magentaBright(str) : chalk.bgMagentaBright(str)
+
+      case 'cyanBright':
+        return type === 'foreground' ? chalk.cyanBright(str) : chalk.bgCyanBright(str)
+
+      case 'whiteBright':
+        return type === 'foreground' ? chalk.whiteBright(str) : chalk.bgWhiteBright(str)
+    }
+  }
+
+  if (color.startsWith('#')) {
+    if (HEX_REGEX.test(color) && CHALK_USES_RICH_EIGHT_BIT_DOWNGRADE) {
+      const value = Number.parseInt(color.slice(1), 16)
+      const red = (value >> 16) & 0xff
+      const green = (value >> 8) & 0xff
+      const blue = value & 0xff
+      const ansi = richEightBitColorNumber(red, green, blue)
+
+      return type === 'foreground' ? chalk.ansi256(ansi)(str) : chalk.bgAnsi256(ansi)(str)
+    }
+
+    return type === 'foreground' ? chalk.hex(color)(str) : chalk.bgHex(color)(str)
+  }
+
+  if (color.startsWith('ansi256')) {
+    const matches = ANSI_REGEX.exec(color)
+
+    if (!matches) {
+      return str
+    }
+
+    const value = Number(matches[1])
+
+    return type === 'foreground' ? chalk.ansi256(value)(str) : chalk.bgAnsi256(value)(str)
+  }
+
+  if (color.startsWith('rgb')) {
+    const matches = RGB_REGEX.exec(color)
+
+    if (!matches) {
+      return str
+    }
+
+    const firstValue = Number(matches[1])
+    const secondValue = Number(matches[2])
+    const thirdValue = Number(matches[3])
+
+    if (CHALK_USES_RICH_EIGHT_BIT_DOWNGRADE) {
+      const ansi = richEightBitColorNumber(firstValue, secondValue, thirdValue)
+
+      return type === 'foreground' ? chalk.ansi256(ansi)(str) : chalk.bgAnsi256(ansi)(str)
+    }
+
+    return type === 'foreground'
+      ? chalk.rgb(firstValue, secondValue, thirdValue)(str)
+      : chalk.bgRgb(firstValue, secondValue, thirdValue)(str)
+  }
+
+  return str
+}
+
+/**
+ * Apply TextStyles to a string using chalk.
+ * This is the inverse of parsing ANSI codes - we generate them from structured styles.
+ * Theme resolution happens at component layer, not here.
+ */
+export function applyTextStyles(text: string, styles: TextStyles): string {
+  let result = text
+
+  // Apply styles in reverse order of desired nesting.
+  // chalk wraps text so later calls become outer wrappers.
+  // Desired order (outermost to innermost):
+  //   background > foreground > text modifiers
+  // So we apply: text modifiers first, then foreground, then background last.
+
+  if (styles.inverse) {
+    result = chalk.inverse(result)
+  }
+
+  if (styles.strikethrough) {
+    result = chalk.strikethrough(result)
+  }
+
+  if (styles.underline) {
+    result = chalk.underline(result)
+  }
+
+  if (styles.italic) {
+    result = chalk.italic(result)
+  }
+
+  if (styles.bold) {
+    result = chalk.bold(result)
+  }
+
+  if (styles.dim) {
+    result = chalk.dim(result)
+  }
+
+  if (styles.color) {
+    // Color is now always a raw color value (theme resolution happens at component layer)
+    result = colorize(result, styles.color, 'foreground')
+  }
+
+  if (styles.backgroundColor) {
+    // backgroundColor is now always a raw color value
+    result = colorize(result, styles.backgroundColor, 'background')
+  }
+
+  return result
+}
+
+/**
+ * Apply a raw color value to text.
+ * Theme resolution should happen at component layer, not here.
+ */
+export function applyColor(text: string, color: Color | undefined): string {
+  if (!color) {
+    return text
+  }
+
+  return colorize(text, color, 'foreground')
+}