The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
import { colorize } from '@hermes/ink'
import { describe, expect, it } from 'vitest'
import {
canFastAppendShape,
canFastBackspaceShape,
colorizeEcho,
colorizeHint,
hintCursorCell,
supportsFastEchoTerminal
} from '../components/textInput.js'
// The fast-echo path bypasses Ink and writes characters directly to stdout
// for the common case of typing plain English at the end of the line. These
// tests pin the shape preconditions that make that bypass safe.
//
// Regression intent: any non-ASCII text — Vietnamese precomposed letters
// (one grapheme, `text.length === 1`, `stringWidth === 1`, but produced
// via IME composition across multiple keystrokes), combining marks
// (zero width), CJK (double width), emoji (variable width), or anything
// that could be produced by an in-flight IME composition — must NOT
// take the bypass. Closes:
// - "TUI is experiencing font errors when using Unicode to type Vietnamese"
// - #5221 TUI input box renders incorrectly for CJK / East-Asian wide
// - #7443 CLI TUI renders and deletes Chinese characters incorrectly
// - #17602 / #17603 Chinese text scattering / ghosting
describe('canFastAppendShape', () => {
const COLS = 40
it('accepts plain ASCII appended at end of single-line input', () => {
expect(canFastAppendShape('hello', 5, 'x', COLS, 5)).toBe(true)
expect(canFastAppendShape('hello', 5, ' world', COLS, 5)).toBe(true)
})
it('rejects when cursor is not at end of line', () => {
expect(canFastAppendShape('hello', 3, 'x', COLS, 5)).toBe(false)
})
it('rejects when current is empty (placeholder render path needed)', () => {
expect(canFastAppendShape('', 0, 'x', COLS, 0)).toBe(false)
})
it('rejects when current contains a newline (multi-line layout)', () => {
expect(canFastAppendShape('hi\nthere', 8, 'x', COLS, 5)).toBe(false)
})
it('rejects when appending would hit the wrap column', () => {
// Reaching cols on append must trigger a wrap, which the bypass
// cannot draw. Stay strictly below cols.
expect(canFastAppendShape('hello', 5, 'x', 6, 5)).toBe(false)
})
// -- Regression coverage: Vietnamese / combining marks / IME --
it('rejects Vietnamese precomposed letter ề (U+1EC1) — IME composition path', () => {
// 'ề' is one grapheme, length 1, width 1, but Vietnamese Telex/IME
// produces it via a multi-key composition. Fast-echo would commit the
// intermediate state to stdout and desync once the final commit
// arrives.
expect(canFastAppendShape('hello', 5, 'ề', COLS, 5)).toBe(false)
})
it('rejects NFD combining marks (U+0300 grave, U+0301 acute, U+0302 circumflex)', () => {
// Decomposed Vietnamese: 'e' + combining circumflex + combining grave
// = 'ề'. Each combining mark is zero-width but length 1; without the
// ASCII guard the second/third keypress would be fast-echoed and
// desync the cell column.
expect(canFastAppendShape('hello', 5, '\u0300', COLS, 5)).toBe(false)
expect(canFastAppendShape('hello', 5, '\u0301', COLS, 5)).toBe(false)
expect(canFastAppendShape('hello', 5, '\u0302', COLS, 5)).toBe(false)
})
it('rejects CJK (East-Asian wide) characters', () => {
expect(canFastAppendShape('hello', 5, '你', COLS, 5)).toBe(false)
expect(canFastAppendShape('hello', 5, '日本', COLS, 5)).toBe(false)
})
it('rejects ANSI-bearing or control text', () => {
expect(canFastAppendShape('hello', 5, '\x1b[31m', COLS, 5)).toBe(false)
expect(canFastAppendShape('hello', 5, '\t', COLS, 5)).toBe(false)
expect(canFastAppendShape('hello', 5, '\x7f', COLS, 5)).toBe(false)
})
})
describe('canFastBackspaceShape', () => {
it('accepts deleting the last ASCII char', () => {
expect(canFastBackspaceShape('hello', 5)).toBe(true)
})
it('rejects when cursor is not at end', () => {
expect(canFastBackspaceShape('hello', 3)).toBe(false)
})
it('rejects when there is nothing to delete', () => {
expect(canFastBackspaceShape('', 0)).toBe(false)
expect(canFastBackspaceShape('hello', 0)).toBe(false)
})
it('rejects when value contains a newline', () => {
expect(canFastBackspaceShape('hi\nthere', 8)).toBe(false)
})
it('rejects deleting a CJK character (2 cells)', () => {
expect(canFastBackspaceShape('hi你', 'hi你'.length)).toBe(false)
})
it('rejects deleting a NFD-composed grapheme with combining marks', () => {
// 'e' + U+0302 (circumflex) + U+0300 (grave) — final grapheme is one
// cluster but the previous-grapheme slice is multi-codepoint. Width
// is 1 but the bypass would be unsafe because the rendered cell
// already contained the combined glyph.
const s = 'hello' + 'e\u0302\u0300'
expect(canFastBackspaceShape(s, s.length)).toBe(false)
})
// Closes Copilot PR #26717 round 3: the "\b \b" sequence cannot move
// the terminal cursor onto the previous visual row across a
// soft-wrap boundary. When the caret sits at visual column 0 of a
// wrapped row (column == 0 in the computed cursor layout), backspace
// would leave the physical cursor in place while the logical caret
// moves up to the end of the previous visual line — desyncing both
// Ink's displayCursor model and the user-visible position. The fast
// path must fall through in that case so the normal Ink render path
// can lay out the correct cursor position.
it('rejects fast-backspace at a soft-wrap boundary when columns is known', () => {
// value width 6 in a column of 6 → cursorLayout produces (line 1, col 0)
// i.e. the caret has overflowed onto the next visual line.
const value = 'hello '
expect(canFastBackspaceShape(value, value.length, 6)).toBe(false)
})
it('still accepts fast-backspace inside a wrapped line', () => {
// Caret mid-visual-line — "\b \b" can move the cursor one cell left
// without crossing a wrap boundary.
expect(canFastBackspaceShape('hello world', 'hello world'.length, 20)).toBe(true)
expect(canFastBackspaceShape('abcdefghi', 9, 6)).toBe(true) // visual line 1, col 3 → ok
})
})
describe('colorizeEcho', () => {
// The fast-echo bypass writes raw cells past Ink, so a themed input must
// carry the theme fg explicitly — a default-fg glyph goes invisible when a
// skin repaints the background to the opposite polarity (dark skin on a
// light terminal ⇒ black-on-black).
it('matches Ink exactly, never a hand-rolled truecolor escape', () => {
// The bypass and the Ink render paint the same cells, so they must agree
// byte-for-byte at whatever depth the terminal supports. Hand-rolling
// `38;2;r;g;b` shipped an escape a 256-color terminal (Apple Terminal)
// cannot parse: the accent fell back to the default fg and read GRAY.
// Asserted as an equality rather than a literal because chalk resolves
// its depth at import time — under vitest that's level 0 (no color).
for (const tone of ['#ff2d95', '#e77fa3', 'ansi256(211)']) {
expect(colorizeEcho('x', tone)).toBe(colorize('x', tone, 'foreground'))
}
})
it('passes through untouched without a color (unthemed keeps terminal default)', () => {
expect(colorizeEcho('x')).toBe('x')
expect(colorizeEcho('x', undefined)).toBe('x')
})
it('passes through on a non-color value (never emit a garbage SGR)', () => {
expect(colorizeEcho('x', 'red')).toBe('x')
expect(colorizeEcho('x', '#fff')).toBe('x')
})
})
describe('colorizeHint / hintCursorCell', () => {
// The placeholder bypass writes raw bytes past Ink too. Hand-rolling
// `38;2;r;g;b` here was WORSE than the gray-accent bug colorizeEcho had:
// legacy Terminal.app walks compound params one by one, so the literal `2`
// in `38;2;…` landed as SGR 2 (dim ON) with no closing `22m` — every
// frame that painted the placeholder left the terminal's dim flag stuck,
// and later unstyled cells rendered randomly dimmed. Both helpers must
// route through Ink's own colorize so depth downgrades with the terminal.
it('hint matches Ink exactly, never a hand-rolled truecolor escape', () => {
for (const tone of ['#8a8094', '#e77fa3']) {
expect(colorizeHint('Try it', tone)).toBe(colorize('Try it', tone, 'foreground'))
}
})
it('hint falls back to the neutral gray on junk, still through colorize', () => {
expect(colorizeHint('x')).toBe(colorize('x', '#808080', 'foreground'))
expect(colorizeHint('x', 'nope')).toBe(colorize('x', '#808080', 'foreground'))
})
it('cursor chip composes bg+fg through colorize only', () => {
expect(hintCursorCell('T', '#8a8094')).toBe(
colorize(colorize('T', '#ffffff', 'foreground'), '#8a8094', 'background')
)
})
})
describe('supportsFastEchoTerminal', () => {
it('disables fast-echo in Apple Terminal', () => {
expect(supportsFastEchoTerminal({ TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBe(false)
})
it('disables fast-echo inside tmux', () => {
expect(supportsFastEchoTerminal({ TMUX: '/tmp/tmux-1000/default,1234,0' } as NodeJS.ProcessEnv)).toBe(false)
expect(supportsFastEchoTerminal({ TMUX: '/private/tmp/tmux-501/default' } as NodeJS.ProcessEnv)).toBe(false)
})
it('tmux wins over Termux fast-echo opt-in', () => {
expect(
supportsFastEchoTerminal({
TMUX: '/tmp/tmux-1000/default,1234,0',
HERMES_TUI_TERMUX_FAST_ECHO: '1',
TERMUX_VERSION: '0.118.0'
})
).toBe(false)
})
it('keeps fast-echo enabled when TMUX is empty or unset', () => {
expect(supportsFastEchoTerminal({ TMUX: '' } as NodeJS.ProcessEnv)).toBe(true)
expect(supportsFastEchoTerminal({ TERM_PROGRAM: 'vscode' } as NodeJS.ProcessEnv)).toBe(true)
})
it('disables fast-echo when only a tmux-flavored TERM is present (SSH from tmux, no TMUX forwarded)', () => {
// OpenSSH forwards TERM but not TMUX, so a TUI on a remote host launched
// from inside local tmux sees TERM=tmux-256color with no TMUX var. The
// cursor-drift bug still applies, so fast-echo must stay off.
expect(supportsFastEchoTerminal({ TERM: 'tmux' } as NodeJS.ProcessEnv)).toBe(false)
expect(supportsFastEchoTerminal({ TERM: 'tmux-256color' } as NodeJS.ProcessEnv)).toBe(false)
})
it('does NOT disable fast-echo for screen-flavored TERM (GNU screen out of scope, no reported drift)', () => {
// GNU screen sets TERM=screen/screen-256color and has no reported drift.
// We must not widen the tmux guard to screen* and regress its perf.
expect(supportsFastEchoTerminal({ TERM: 'screen' } as NodeJS.ProcessEnv)).toBe(true)
expect(supportsFastEchoTerminal({ TERM: 'screen-256color' } as NodeJS.ProcessEnv)).toBe(true)
// And an unrelated 256color TERM must stay enabled.
expect(supportsFastEchoTerminal({ TERM: 'xterm-256color' } as NodeJS.ProcessEnv)).toBe(true)
})
it('disables fast-echo by default in Termux mode', () => {
expect(
supportsFastEchoTerminal({
TERMUX_VERSION: '0.118.0',
PREFIX: '/data/data/com.termux/files/usr'
})
).toBe(false)
})
it('allows explicit Termux fast-echo opt-in via env override', () => {
expect(
supportsFastEchoTerminal({
HERMES_TUI_TERMUX_FAST_ECHO: '1',
TERMUX_VERSION: '0.118.0'
})
).toBe(true)
})
it('keeps fast-echo enabled in VS Code and unknown terminals', () => {
expect(supportsFastEchoTerminal({ TERM_PROGRAM: 'vscode' } as NodeJS.ProcessEnv)).toBe(true)
expect(supportsFastEchoTerminal({ TERM: 'xterm-256color' } as NodeJS.ProcessEnv)).toBe(true)
})
})