xterm-zerolag-input

Instant keystroke feedback overlay for xterm.js
Eliminates perceived input latency over high-RTT connections

The Problem

When using xterm.js over a remote connection (SSH web clients, cloud IDEs, mobile terminals), every keystroke takes a full round-trip to the server before appearing on screen. At 100-500ms RTT, typing feels sluggish and unresponsive. Users type blind, make mistakes they can't see, and the experience feels broken.

The Solution

xterm-zerolag-input renders typed characters immediately as a pixel-perfect DOM overlay positioned on the terminal's character grid. The overlay covers the terminal canvas at the prompt location, showing characters instantly while the server echo travels back. Once the server responds, the overlay seamlessly disappears and the real terminal text takes over.

Keystroke Flow:
                                    ┌─── DOM overlay (instant, 0ms)
User types 'h' ─── onData('h') ───┤
                                    └─── Your app sends to PTY ──→ Server
                                                                      │
Server echoes 'h' ←──────────────────────────────────────────────────┘
         │                                                  (200-500ms RTT)
         └──→ terminal.write('h') ──→ overlay.clear()
              (server output replaces overlay — seamless transition)

No changes to your backend needed. The addon is purely client-side.

Origin

This library was extracted from Codeman, the missing control plane for AI coding agents — multi-session management, real-time agent visualization, autonomous respawn loops, and a mobile-first web UI for Claude Code and OpenCode. The local echo system was built to make mobile and remote access feel instant, then battle-tested across thousands of hours of real usage. After 3 deep code audits, it was extracted into this standalone library with 78 tests covering every state transition.

Install

npm install xterm-zerolag-input

Zero runtime dependencies
Compatible with both xterm (pre-5.4) and @xterm/xterm (5.4+)
Dual CJS/ESM build with full TypeScript declarations
Works with canvas, WebGL, and DOM renderers

Quick Start

import { Terminal } from '@xterm/xterm';
import { ZerolagInputAddon } from 'xterm-zerolag-input';

const terminal = new Terminal();
terminal.open(document.getElementById('terminal')!);

// 1. Create addon with your prompt character
const zerolag = new ZerolagInputAddon({
  prompt: { type: 'character', char: '$', offset: 2 },
});
terminal.loadAddon(zerolag);

// 2. Wire your input handler
terminal.onData((data) => {
  if (data === '\r') {
    const text = zerolag.pendingText;
    zerolag.clear();
    ws.send(text + '\r');
  } else if (data === '\x7f') {
    const source = zerolag.removeChar();
    if (source === 'flushed') ws.send(data); // only backspace text already in PTY
  } else if (data.length === 1 && data.charCodeAt(0) >= 32) {
    zerolag.addChar(data);
  }
});

// 3. Re-render after terminal output (for full-screen TUI frameworks like Ink)
terminal.onWriteParsed(() => {
  if (zerolag.hasPending) zerolag.rerender();
});

Why This Is Hard

Most terminal UIs can't do local echo because:

Buffer writes corrupt: Frameworks like Ink (React for terminals) redraw the entire screen on every state change. Writing directly to the terminal buffer gets immediately overwritten.
Cursor position lies: In Ink, buffer.cursorY reflects internal state (near the status bar), not the visible prompt. You can't trust it.
Font matching: Canvas/WebGL renderers use their own text shaping. A DOM overlay must pixel-match the canvas grid — normal DOM text flow drifts due to sub-pixel glyph width differences.

This library solves all three by:

Using a DOM overlay that Ink can't touch (separate z-index layer)
Scanning the buffer bottom-up for the prompt character instead of trusting cursor position
Rendering each character as an absolutely-positioned <span> at exact cell-grid coordinates

Prompt Detection

The addon needs to know where user input starts. It scans the terminal buffer bottom-up for the prompt. Three strategies:

Character (default)

// Bash: user@host:~$
{ type: 'character', char: '$', offset: 2 }

// Zsh: user@host ~ %
{ type: 'character', char: '%', offset: 2 }

// Fish / Starship: ❯
{ type: 'character', char: '\u276f', offset: 2 }

// Simple arrow: >
{ type: 'character', char: '>', offset: 2 }

offset = characters between the prompt marker and where user input begins (e.g., "$ " = 2).

Regex

For complex prompts. The g flag is safely stripped to prevent lastIndex mutation.

{ type: 'regex', pattern: /\$\s*$/, offset: 2 }
{ type: 'regex', pattern: /\(venv\)\s+\w+\s+%/, offset: 2 }

Custom

Full control:

{
  type: 'custom',
  offset: 0,
  find: (terminal) => {
    // Return { row, col } or null. Row is viewport-relative.
    return { row: terminal.rows - 1, col: 0 };
  },
}

API Reference

`ZerolagInputAddon`

Implements xterm.js ITerminalAddon. The addon does not hook terminal.onData() — you wire your own input handler and call these methods. This gives you full control over which keystrokes are echoed vs forwarded.

Input

Method	Returns	Description
`addChar(char)`	`void`	Add a single printable character. Auto-detects existing buffer text on first keystroke.
`appendText(text)`	`void`	Append multiple characters (paste).
`removeChar()`	`'pending'` \| `'flushed'` \| `false`	Remove last char. See backspace handling.
`clear()`	`void`	Clear all state, hide overlay. Call on Enter/Ctrl+C/Escape.

Backspace Handling

removeChar() cascades through three layers and tells you what it removed:

Return	Source	Your action
`'pending'`	Unsent text (never transmitted to PTY)	Do nothing
`'flushed'`	Text already sent to PTY	Send `\x7f` backspace to PTY
`false`	Nothing to remove	Do nothing

The cascade: pending text first, then flushed text, then auto-detect buffer text (handles tab completion). This means backspace "just works" through any combination of typed, flushed, and tab-completed text.

Flushed Text

"Flushed" = sent to PTY but echo hasn't arrived yet. Happens during tab switches and tab completion.

Method	Description
`setFlushed(count, text, render?)`	Mark text as flushed. Pass `render=false` during tab-switch restore (buffer not loaded yet).
`getFlushed()`	Returns `{ count, text }`.
`clearFlushed()`	Clear flushed state when server echo arrives.

Buffer Detection

Scan the terminal for text that exists after the prompt but wasn't typed through the overlay.

Method	Description
`detectBufferText()`	Scan and return detected text (or `null`). Sets it as flushed. Guarded: runs once per `clear()` cycle.
`resetBufferDetection()`	Re-enable detection.
`suppressBufferDetection()`	Block detection until next `clear()`. Use for sessions with UI framework text after the prompt.
`undoDetection()`	Undo last detection — clears flushed state, re-enables detection. For tab completion retry.

Rendering

Method	Description
`rerender()`	Force re-render. Call after buffer reloads, screen redraws, resizes, reconnects.
`refreshFont()`	Re-cache font properties from terminal. Call after font size or theme changes.

Prompt Utilities

Method	Description
`findPrompt()`	Find prompt position. Returns `{ row, col }` or `null`.
`readPromptText()`	Read text after prompt marker. Returns string or `null`.

State

Property	Type	Description
`pendingText`	`string`	Unacknowledged text (read-only)
`hasPending`	`boolean`	`true` if overlay has any content
`state`	`ZerolagInputState`	Full snapshot: pendingText, flushedLength, flushedText, visible, promptPosition

Options

{
  prompt?: PromptFinder,       // Default: { type: 'character', char: '>', offset: 2 }
  zIndex?: number,             // Default: 7
  backgroundColor?: string,    // Default: from terminal theme
  foregroundColor?: string,    // Default: from computed .xterm-rows style
  showCursor?: boolean,        // Default: true
  cursorColor?: string,        // Default: from terminal theme
  scrollDebounceMs?: number,   // Default: 50
}

Integration Patterns

Buffered Input (hold until Enter)

The quick start example above. Characters accumulate in the overlay and are sent on Enter. Best for remote shells where you want to batch input.

Char-at-a-Time (send immediately)

terminal.onData((data) => {
  if (data === '\r') {
    zerolag.clear();
    ws.send('\r');
  } else if (data === '\x7f') {
    zerolag.removeChar();
    ws.send(data);
  } else if (data.length === 1 && data.charCodeAt(0) >= 32) {
    zerolag.addChar(data);
    ws.send(data); // send immediately — overlay shows while echo travels back
  }
});

Tab Switching (multi-session)

function switchToSession(newId: string) {
  // Save
  const pending = zerolag.pendingText;
  const { count, text } = zerolag.getFlushed();
  if (pending) sendToPty(currentId, pending);
  savedState.set(currentId, { count: count + pending.length, text: text + pending });
  zerolag.clear();

  // Load new buffer...
  loadBuffer(newId);

  // Restore
  zerolag.suppressBufferDetection();
  const saved = savedState.get(newId);
  if (saved) zerolag.setFlushed(saved.count, saved.text, false); // silent

  // Render after buffer loads
  terminal.write('', () => zerolag.rerender());
}

Tab Completion

const baseline = zerolag.readPromptText();
zerolag.clear();
sendToPty('\t');

// After response:
zerolag.resetBufferDetection();
const detected = zerolag.detectBufferText();
if (detected && detected !== baseline) {
  zerolag.rerender(); // completion happened
} else if (detected) {
  zerolag.undoDetection(); // same text, retry next cycle
}

Resize / Font / Reconnect

fitAddon.fit();
zerolag.rerender();

terminal.options.fontSize = 18;
zerolag.refreshFont();

function onReconnect() { zerolag.rerender(); }

How It Works

DOM Structure

div.xterm-screen (position: relative)
  ├── div.xterm-rows (z-index: auto)     ← terminal owns this
  ├── div.xterm-selection (z-index: 1)
  ├── div.xterm-helpers (z-index: 5)
  ├── div.xterm-decoration-container (z-index: 6-7)
  └── div[zerolag overlay] (z-index: 7)  ← our overlay (invisible to Ink)

Per-Character Grid Alignment

Each character is an absolutely-positioned <span>:

left  = charIndex * cellWidth   (CSS pixels)
top   = lineIndex * cellHeight  (CSS pixels)
width = cellWidth               (exact cell width)

This avoids sub-pixel drift from normal DOM text flow.

Font Matching

fontFamily, fontSize, fontWeight from terminal.options
letterSpacing from computed style of .xterm-rows
-webkit-font-smoothing: antialiased (matches canvas grayscale)
font-feature-settings: 'liga' 0, 'calt' 0 (no ligatures)
text-rendering: geometricPrecision

Cell Dimensions

xterm.js v5.x: terminal._core._renderService.dimensions.css.cell (private API)
xterm.js v7+: terminal.dimensions.css.cell (public API, auto-detected)

Prompt Column Locking

When flushed text exists, the prompt column is locked to prevent jitter from full-screen redraws. Row changes are allowed (output can scroll the prompt).

Scroll Awareness

Overlay hides when scrolled up (viewportY !== baseY). Debounced re-render when scrolling back to bottom.

Known Limitations

Canvas/WebGL font mismatch: Minor sub-pixel differences possible. Per-character absolute positioning minimizes this.
Unicode/emoji: Multi-byte characters occupy variable cell widths — rendered at single-cell width, causing misalignment.
Password prompts: Overlay shows characters that aren't echoed. Call clear() when you detect no-echo mode.
Prompt in output: If $ appears in command output, prompt detection may find the wrong position. Use regex or custom finder.

License

MIT — Codeman Contributors

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

xterm-zerolag-input

The Problem

The Solution

Origin

Install

Quick Start

Why This Is Hard

Prompt Detection

Character (default)

Regex

Custom

API Reference

`ZerolagInputAddon`

Input

Backspace Handling

Flushed Text

Buffer Detection

Rendering

Prompt Utilities

State

Options

Integration Patterns

Buffered Input (hold until Enter)

Char-at-a-Time (send immediately)

Tab Switching (multi-session)

Tab Completion

Resize / Font / Reconnect

How It Works

DOM Structure

Per-Character Grid Alignment

Font Matching

Cell Dimensions

Prompt Column Locking

Scroll Awareness

Known Limitations

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

xterm-zerolag-input

The Problem

The Solution

Origin

Install

Quick Start

Why This Is Hard

Prompt Detection

Character (default)

Regex

Custom

API Reference

ZerolagInputAddon

Input

Backspace Handling

Flushed Text

Buffer Detection

Rendering

Prompt Utilities

State

Options

Integration Patterns

Buffered Input (hold until Enter)

Char-at-a-Time (send immediately)

Tab Switching (multi-session)

Tab Completion

Resize / Font / Reconnect

How It Works

DOM Structure

Per-Character Grid Alignment

Font Matching

Cell Dimensions

Prompt Column Locking

Scroll Awareness

Known Limitations

License

`ZerolagInputAddon`