@earendil-works/pi-tui

Minimal terminal UI framework with differential rendering and synchronized output for flicker-free interactive CLI applications.

Features

• Interchangeable Renderers: Shared TUI interface with main-screen and alternate-screen implementations
• Differential Rendering: Updates only changed lines or viewport rows
• Application-owned Scrolling: Alternate-screen viewport supports mouse, trackpad, and keyboard navigation
• Synchronized Output: Uses CSI 2026 for atomic screen updates (no flicker)
• Bracketed Paste Mode: Handles large pastes correctly with markers for >10 line pastes
• Component-based: Simple Component interface with render() method
• Theme Support: Components accept theme interfaces for customizable styling
• Built-in Components: Text, TruncatedText, Input, Editor, Markdown, Loader, SelectList, SettingsList, MouseRegion, Spacer, Image, Box, Container, VStack, HStack, ScrollView
• Inline Images: Renders images in terminals that support Kitty or iTerm2 graphics protocols
• Autocomplete Support: File paths and slash commands

Quick Start

import { type TUI, Text, Editor, ProcessTerminal, TuiMainScreen, matchesKey } from "@earendil-works/pi-tui";

// Create terminal
const terminal = new ProcessTerminal();

// Create the default main-screen renderer through the shared TUI interface
const tui: TUI = new TuiMainScreen(terminal);

// Add components
tui.addChild(new Text("Welcome to my app!"));

import { defaultEditorTheme as editorTheme } from './test/test-themes.ts';
const editor = new Editor(tui, editorTheme);
editor.onSubmit = (text) => {
  console.log("Submitted:", text);
  tui.addChild(new Text(`You said: ${text}`));
};
tui.addChild(editor);

// Focus the editor so it receives keyboard input
tui.setFocus(editor);

// In raw mode Ctrl+C doesn't send SIGINT — intercept it here to allow exit
tui.addInputListener((data) => {
  if (matchesKey(data, 'ctrl+c')) {
    tui.stop();
    process.exit(0);
  }
});

// Start
tui.start();

Core API

TUI interface and renderers

TUI is the shared interface for component management, focus, overlays, input, lifecycle, terminal queries, and rendering. Choose a concrete renderer only when constructing the application:

• TuiMainScreen renders into the main terminal buffer and preserves terminal scrollback.
• TuiAltScreen renders a fixed-height viewport in the alternate terminal buffer with application-owned scrolling. When stopped, it restores the main buffer and prints the complete final document.

import { type TUI, TuiAltScreen, TuiMainScreen } from "@earendil-works/pi-tui";

const tui: TUI = new TuiMainScreen(terminal);
// To use an application-owned viewport in the alternate terminal buffer instead:
// const tui: TUI = new TuiAltScreen(terminal);

tui.addChild(component);
tui.removeChild(component);
tui.start();
tui.stop();
tui.requestRender(); // Request a re-render

// Global debug key handler (Shift+Ctrl+D)
tui.onDebug = () => console.log("Debug triggered");

Alternate-screen viewport layouts

TuiAltScreen can render an explicit terminal-height layout. VStack and HStack allocate constrained regions, while ScrollView owns scrolling for one region. These semantics are intentionally unavailable on TuiMainScreen, where the terminal owns scrollback.

import {
  Container,
  isViewportTUI,
  ScrollView,
  Text,
  VStack,
} from "@earendil-works/pi-tui";

const transcript = new Container();
transcript.addChild(new Text("History"));

const editorAndFooter = new VStack([
  editor,
  new Text("status"),
]);

if (isViewportTUI(tui)) {
  tui.setLayoutRoot(new VStack([
    {
      component: new ScrollView(transcript, {
        follow: "end",
        primary: true,
        overscroll: "chain",
      }),
      basis: 0,
      grow: 1,
      minSize: 1,
    },
    {
      component: editorAndFooter,
      basis: "auto",
      shrink: 1,
      minSize: 1,
    },
  ]));
}

Stack entries support basis, grow, shrink, minSize, maxSize, and responsive visible callbacks. Mouse-wheel input targets the scroll view under the pointer and unused delta chains to outer scroll views by default. The primary scroll view receives the alternate-screen keyboard navigation actions and wheel input over non-scrollable regions. It can also jump between OSC 133 semantic prompt markers, matching common terminal prompt-navigation shortcuts. Press Ctrl+Shift+F to open or close its bordered search panel. The panel shows the configured previous/next shortcuts and provides clickable arrow controls; by default, Enter/Ctrl+G and Shift+Enter/Ctrl+Shift+G move between matches, and Escape also closes search. TuiAltScreenOptions.searchMatchStyle and searchCurrentMatchStyle customize match highlighting, while searchNavigationButtonStyle styles each arrow button and receives its hover state. TuiAltScreenOptions.scrollToEndIndicator renders a clickable label centered on the last row of a follow: "end" primary scroll view while it is scrolled away from the end; clicking it resumes end-following.

Layout geometry is rebuilt for each requested frame. Stateful components are retained, and their existing rendered-line caches remain effective. Calling render(width) directly on these layout components produces an unbounded document, which is also used when alt mode restores the main screen.

Overlays

Overlays render components on top of existing content without replacing it. Useful for dialogs, menus, and modal UI.

// Show overlay with default options (centered, max 80 cols)
const handle = tui.showOverlay(component);

// Show overlay with custom positioning and sizing
// Values can be numbers (absolute) or percentage strings (e.g., "50%")
const handle = tui.showOverlay(component, {
  // Sizing
  width: 60,              // Fixed width in columns
  width: "80%",           // Width as percentage of terminal
  minWidth: 40,           // Minimum width floor
  maxHeight: 20,          // Maximum height in rows
  maxHeight: "50%",       // Maximum height as percentage of terminal

  // Anchor-based positioning (default: 'center')
  anchor: 'bottom-right', // Position relative to anchor point
  offsetX: 2,             // Horizontal offset from anchor
  offsetY: -1,            // Vertical offset from anchor

  // Percentage-based positioning (alternative to anchor)
  row: "25%",             // Vertical position (0%=top, 100%=bottom)
  col: "50%",             // Horizontal position (0%=left, 100%=right)

  // Absolute positioning (overrides anchor/percent)
  row: 5,                 // Exact row position
  col: 10,                // Exact column position

  // Margin from terminal edges
  margin: 2,              // All sides
  margin: { top: 1, right: 2, bottom: 1, left: 2 },

  // Responsive visibility
  visible: (termWidth, termHeight) => termWidth >= 100  // Hide on narrow terminals

  // Focus behavior
  nonCapturing: true       // Don't auto-focus when shown
});

// OverlayHandle methods
handle.hide();              // Permanently remove the overlay
handle.setHidden(true);     // Temporarily hide (can show again)
handle.setHidden(false);    // Show again after hiding
handle.isHidden();          // Check if temporarily hidden
handle.focus();             // Focus and bring to visual front
handle.unfocus();           // Release focus to normal fallback
handle.unfocus({ target: baseComponent }); // Release this overlay to a specific component
handle.unfocus({ target: null });   // Release this overlay and leave focus empty
handle.isFocused();         // Check if overlay has focus
handle.getBounds();         // Get last rendered terminal-relative bounds

handle.unfocus();
// Overlay loses focus; TUI falls back to another visible capturing overlay or the previous focus target.

handle.unfocus({ target: null });
// Overlay loses focus; no component receives input until focus is set again.

// A focused visible overlay reclaims keyboard input after temporary replacement UI
// releases focus. If you want a specific component to receive input while overlays remain
// visible, call handle.unfocus({ target: component }).

// Hide topmost overlay
tui.hideOverlay();

// Check if any visible overlay is active
tui.hasOverlay();

Anchor values: 'center', 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'top-center', 'bottom-center', 'left-center', 'right-center'

Resolution order:

1. minWidth is applied as a floor after width calculation
2. For position: absolute row/col > percentage row/col > anchor
3. margin clamps final position to stay within terminal bounds
4. visible callback controls whether overlay renders (called each frame)

Component Interface

All components implement:

interface Component {
  render(width: number): string[];
  handleInput?(data: string): void;
  handleMouse?(event: TuiMouseEvent): TuiMouseEventResult | undefined;
  invalidate?(): void;
}

The TUI appends a full SGR reset and OSC 8 reset at the end of each rendered line. Styles do not carry across lines. If you emit multi-line text with styling, reapply styles per line or use wrapTextWithAnsi() so styles are preserved for each wrapped line.

Mouse Input

TuiAltScreen normalizes SGR mouse input and hit-tests components and overlays. Events contain component-local x/y, absolute screenX/screenY, bounds, button, modifiers, click count, and wheel delta.

TuiMainScreen captures only while a host-owned lease is active: const release = tui.acquireMouseCapture("pending-question"); call release() when the interactive surface closes. Leases compose and releases are idempotent. A replacement renderer starts with no leases, so the host must reapply its intent after switching modes. Without a lease, native selection and scrollback remain untouched.

Regular mode supports unmodified left press/click only. A handler must acknowledge an eligible press with { handled: true } without activating; a same-cell release within 500 ms produces the click. Changed placement or target layout cancels the gesture. Wheel, motion, other buttons, and modified reports are consumed without dispatch, including in-flight reports after capture ends. While capture is active, use the terminal's selection bypass: usually Shift-drag, or Option-drag in iTerm2/Terminal.app. There is no regular-mode app-owned drag selection or wheel scrolling.

Clicks fail closed when frame placement is unknown, resized, or image-bearing. Short fresh frames use a private cursor-position query; clearing and viewport-filling frames provide their own anchors. A query timeout leaves keyboard interaction available; a clearing render can recover the anchor. External stdout/stderr invalidates placement, and the next regular-mode render appends a fresh frame before recalibrating without clearing diagnostics or scrollback. Tracking is disabled on non-TTY output, Termux, and Windows consoles without Windows Terminal.

import type { TuiMouseEvent, TuiMouseEventResult } from "@earendil-works/pi-tui";

handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
  if (event.type === "click" && event.button === "left") {
    this.expanded = !this.expanded;
    return { handled: true };
  }
  if (event.type === "press" && event.button === "left") {
    return { handled: true, capture: true, focus: true };
  }
  if (event.type === "drag") {
    this.updateFromPointer(event.x, event.y);
    return { handled: true, render: true };
  }
  return undefined;
}

Returning handled suppresses renderer-level fallback behavior. capture keeps subsequent drag and release events routed to the same component. focus requests keyboard focus. The optional render flag controls repainting: press, click, drag, and wheel default to rendering; move and release do not. Set render: true for a hover state that visibly changed, or render: false for a handled no-op. Render requests are coalesced and terminal output remains differential.

Unhandled gestures retain alternate-screen defaults: wheel input scrolls the nearest ScrollView and chains unused delta, primary-button drags select text, OSC 8 links open before parent click handlers, and unhandled right-click preserves configured paste behavior. A click is emitted only when press/release completes without a drag.

Use MouseRegion to add mouse behavior without changing a component's rendering:

const collapsible = new MouseRegion(content, (event) => {
  if (event.button !== "left") return undefined;
  if (event.type === "press") return { handled: true };
  if (event.type !== "click") return undefined;
  expanded = !expanded;
  return { handled: true };
});

Container and Box route events to nested children using geometry recorded by the last rendered frame, so pointer motion does not rerender children merely to hit-test them. Explicit VStack, HStack, and ScrollView layouts use the alternate-screen layout frame directly.

Focusable Interface (IME Support)

Components that display a text cursor and need IME (Input Method Editor) support should implement the Focusable interface:

import { CURSOR_MARKER, type Component, type Focusable } from "@earendil-works/pi-tui";

class MyInput implements Component, Focusable {
  focused: boolean = false;  // Set by TUI when focus changes
  
  render(width: number): string[] {
    const marker = this.focused ? CURSOR_MARKER : "";
    // Emit marker right before the fake cursor
    return [`> ${beforeCursor}${marker}\x1b[7m${atCursor}\x1b[27m${afterCursor}`];
  }
}

When a Focusable component has focus, TUI:

1. Sets focused = true on the component
2. Scans rendered output for CURSOR_MARKER (a zero-width APC escape sequence)
3. Positions the hardware terminal cursor at that location
4. Shows the hardware cursor only when showHardwareCursor is enabled

The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with the renderer constructor's showHardwareCursor argument or setShowHardwareCursor(true). The Editor and Input built-in components already implement this interface.

Container components with embedded inputs: When a container component (dialog, selector, etc.) contains an Input or Editor child, the container must implement Focusable and propagate the focus state to the child:

import { Container, type Focusable, Input } from "@earendil-works/pi-tui";

class SearchDialog extends Container implements Focusable {
  private searchInput: Input;

  // Propagate focus to child input for IME cursor positioning
  private _focused = false;
  get focused(): boolean { return this._focused; }
  set focused(value: boolean) {
    this._focused = value;
    this.searchInput.focused = value;
  }

  constructor() {
    super();
    this.searchInput = new Input();
    this.addChild(this.searchInput);
  }
}

Without this propagation, typing with an IME (Chinese, Japanese, Korean, etc.) will show the candidate window in the wrong position.

Built-in Components

Container

Groups child components.

const container = new Container();
container.addChild(component);
container.removeChild(component);

Box

Container that applies padding and background color to all children.

const box = new Box(
  1,                              // paddingX (default: 1)
  1,                              // paddingY (default: 1)
  (text) => chalk.bgGray(text)   // optional background function
);
box.addChild(new Text("Content"));
box.setBgFn((text) => chalk.bgBlue(text));  // Change background dynamically

Text

Displays multi-line text with word wrapping and padding.

const text = new Text(
  "Hello World",                  // text content
  1,                              // paddingX (default: 1)
  1,                              // paddingY (default: 1)
  (text) => chalk.bgGray(text)   // optional background function
);
text.setText("Updated text");
text.setCustomBgFn((text) => chalk.bgBlue(text));

TruncatedText

Single-line text that truncates to fit viewport width. Useful for status lines and headers.

const truncated = new TruncatedText(
  "This is a very long line that will be truncated...",
  0,  // paddingX (default: 0)
  0   // paddingY (default: 0)
);

Input

Single-line text input with horizontal scrolling.

const input = new Input();
input.onSubmit = (value) => console.log(value);
input.setValue("initial");
input.getValue();

Clicking positions the cursor and gives the input keyboard focus in alternate-screen mode.

Key Bindings:

• Enter - Submit
• Ctrl+A / Ctrl+E - Line start/end
• Ctrl+W or Alt+Backspace - Delete word backwards
• Ctrl+U - Delete to start of line
• Ctrl+K - Delete to end of line
• Ctrl+Left / Ctrl+Right - Word navigation
• Alt+Left / Alt+Right - Word navigation
• Arrow keys, Backspace, Delete work as expected

Editor

Multi-line text editor with autocomplete, file completion, paste handling, and vertical scrolling when content exceeds terminal height.

interface EditorTheme {
  borderColor: (str: string) => string;
  selectList: SelectListTheme;
}

interface EditorOptions {
  paddingX?: number;  // Horizontal padding (default: 0)
}

const editor = new Editor(tui, theme, options?);  // tui is required for height-aware scrolling
editor.onSubmit = (text) => console.log(text);
editor.onChange = (text) => console.log("Changed:", text);
editor.disableSubmit = true; // Disable submit temporarily
editor.setAutocompleteProvider(provider);
editor.borderColor = (s) => chalk.blue(s); // Change border dynamically
editor.setPaddingX(1); // Update horizontal padding dynamically
editor.getPaddingX();  // Get current padding

Features:

• Click-to-position cursor and clickable autocomplete rows in alternate-screen mode
• Multi-line editing with word wrap
• Slash command autocomplete (type /)
• File path autocomplete (press Tab)
• Large paste handling (>10 lines creates [paste #1 +50 lines] marker)
• Horizontal lines above/below editor
• Fake cursor rendering (hidden real cursor)

Key Bindings:

• Enter - Submit
• Shift+Enter, Ctrl+Enter, or Alt+Enter - New line (terminal-dependent, Alt+Enter most reliable)
• Tab - Autocomplete
• Ctrl+K - Delete to end of line
• Ctrl+U - Delete to start of line
• Ctrl+W or Alt+Backspace - Delete word backwards
• Alt+D or Alt+Delete - Delete word forwards
• Ctrl+A / Ctrl+E - Line start/end
• Ctrl+] - Jump forward to character (awaits next keypress, then moves cursor to first occurrence)
• Ctrl+Alt+] - Jump backward to character
• Arrow keys, Backspace, Delete work as expected

Markdown

Renders markdown with syntax highlighting and theming support.

interface MarkdownTheme {
  heading: (text: string) => string;
  link: (text: string) => string;
  linkUrl: (text: string) => string;
  code: (text: string) => string;
  codeBlock: (text: string) => string;
  codeBlockBorder: (text: string) => string;
  quote: (text: string) => string;
  quoteBorder: (text: string) => string;
  hr: (text: string) => string;
  listBullet: (text: string) => string;
  bold: (text: string) => string;
  italic: (text: string) => string;
  strikethrough: (text: string) => string;
  underline: (text: string) => string;
  highlightCode?: (code: string, lang?: string) => string[];
}

interface DefaultTextStyle {
  color?: (text: string) => string;
  bgColor?: (text: string) => string;
  bold?: boolean;
  italic?: boolean;
  strikethrough?: boolean;
  underline?: boolean;
}

const md = new Markdown(
  "# Hello\n\nSome **bold** text",
  1,              // paddingX
  1,              // paddingY
  theme,          // MarkdownTheme
  defaultStyle    // optional DefaultTextStyle
);
md.setText("Updated markdown");

Features:

• Headings, bold, italic, code blocks, lists, links, blockquotes
• HTML tags rendered as plain text
• Optional syntax highlighting via highlightCode
• Padding support
• Render caching for performance

Loader

Animated loading spinner.

const loader = new Loader(
  tui,                              // TUI instance for render updates
  (s) => chalk.cyan(s),            // spinner color function
  (s) => chalk.gray(s),            // message color function
  "Loading..."                      // message (default: "Loading...")
);
loader.start();
loader.setMessage("Still loading...");
loader.stop();

CancellableLoader

Extends Loader with Escape key handling and an AbortSignal for cancelling async operations.

const loader = new CancellableLoader(
  tui,                              // TUI instance for render updates
  (s) => chalk.cyan(s),            // spinner color function
  (s) => chalk.gray(s),            // message color function
  "Working..."                      // message
);
loader.onAbort = () => done(null); // Called when user presses Escape
doAsyncWork(loader.signal).then(done);

Properties:

• signal: AbortSignal - Aborted when user presses Escape
• aborted: boolean - Whether the loader was aborted
• onAbort?: () => void - Callback when user presses Escape

SelectList

Interactive selection list with keyboard navigation.

interface SelectItem {
  value: string;
  label: string;
  description?: string;
}

interface SelectListTheme {
  selectedPrefix: (text: string) => string;
  selectedText: (text: string) => string;
  description: (text: string) => string;
  scrollInfo: (text: string) => string;
  noMatch: (text: string) => string;
}

const list = new SelectList(
  [
    { value: "opt1", label: "Option 1", description: "First option" },
    { value: "opt2", label: "Option 2", description: "Second option" },
  ],
  5,      // maxVisible
  theme   // SelectListTheme
);

list.onSelect = (item) => console.log("Selected:", item);
list.onCancel = () => console.log("Cancelled");
list.onSelectionChange = (item) => console.log("Highlighted:", item);
list.setFilter("opt"); // Filter items

Controls:

• Mouse move/wheel: Highlight rows in alternate-screen mode
• Click: Select a row
• Arrow keys: Navigate
• Enter: Select
• Escape: Cancel

SettingsList

Settings panel with value cycling and submenus.

interface SettingItem {
  id: string;
  label: string;
  description?: string;
  currentValue: string;
  values?: string[];  // If provided, Enter/Space cycles through these
  submenu?: (currentValue: string, done: (selectedValue?: string) => void) => Component;
}

interface SettingsListTheme {
  label: (text: string, selected: boolean) => string;
  value: (text: string, selected: boolean) => string;
  description: (text: string) => string;
  cursor: string;
  hint: (text: string) => string;
}

const settings = new SettingsList(
  [
    { id: "theme", label: "Theme", currentValue: "dark", values: ["dark", "light"] },
    { id: "model", label: "Model", currentValue: "gpt-4", submenu: (val, done) => modelSelector },
  ],
  10,      // maxVisible
  theme,   // SettingsListTheme
  (id, newValue) => console.log(`${id} changed to ${newValue}`),
  () => console.log("Cancelled")
);
settings.updateValue("theme", "light");

Controls:

• Mouse move/wheel: Highlight rows in alternate-screen mode
• Click: Activate a row
• Arrow keys: Navigate
• Enter/Space: Activate (cycle value or open submenu)
• Escape: Cancel

Spacer

Empty lines for vertical spacing.

const spacer = new Spacer(2); // 2 empty lines (default: 1)

Image

Renders images inline for terminals that support the Kitty graphics protocol (Kitty, Ghostty, WezTerm) or iTerm2 inline images. Falls back to a text placeholder on unsupported terminals.

interface ImageTheme {
  fallbackColor: (str: string) => string;
}

interface ImageOptions {
  maxWidthCells?: number;
  maxHeightCells?: number;
  filename?: string;
}

const image = new Image(
  base64Data,       // base64-encoded image data
  "image/png",      // MIME type
  theme,            // ImageTheme
  options           // optional ImageOptions
);
tui.addChild(image);

Supported formats: PNG, JPEG, GIF, WebP. Dimensions are parsed from the image headers automatically.

Alternate-screen image compatibility

TuiAltScreen supports inline images and partial viewport cropping in terminals that implement the Kitty graphics protocol, including Kitty and Ghostty. iTerm2's inline-image protocol does not provide operations to delete an existing placement or crop its source while scrolling. To prevent stale images from remaining over repainted content, TuiAltScreen renders image components as text placeholders in iTerm2. TuiMainScreen continues to render iTerm2 inline images normally.

Autocomplete

CombinedAutocompleteProvider

Supports both slash commands and file paths.

import { CombinedAutocompleteProvider } from "@earendil-works/pi-tui";

const provider = new CombinedAutocompleteProvider(
  [
    { name: "help", description: "Show help" },
    { name: "clear", description: "Clear screen" },
    { name: "delete", description: "Delete last message" },
  ],
  process.cwd() // base path for file completion
);

editor.setAutocompleteProvider(provider);

Features:

• Type / to see slash commands
• Press Tab for file path completion
• Works with ~/, ./, ../, and @ prefix
• Filters to attachable files for @ prefix

Key Detection

Use matchesKey() with the Key helper for detecting keyboard input (supports Kitty keyboard protocol):

import { matchesKey, Key } from "@earendil-works/pi-tui";

if (matchesKey(data, Key.ctrl("c"))) {
  process.exit(0);
}

if (matchesKey(data, Key.enter)) {
  submit();
} else if (matchesKey(data, Key.escape)) {
  cancel();
} else if (matchesKey(data, Key.up)) {
  moveUp();
}

Key identifiers (use Key.* for autocomplete, or string literals):

• Basic keys: Key.enter, Key.escape, Key.tab, Key.space, Key.backspace, Key.delete, Key.home, Key.end
• Arrow keys: Key.up, Key.down, Key.left, Key.right
• With modifiers: Key.ctrl("c"), Key.shift("tab"), Key.alt("left"), Key.ctrlShift("p")
• String format also works: "enter", "ctrl+c", "shift+tab", "ctrl+shift+p"

Rendering modes

TuiMainScreen uses three rendering strategies:

1. First Render: Output all lines without clearing scrollback
2. Width Changed or Change Above Viewport: Clear screen and fully re-render
3. Normal Update: Move the cursor to the first changed line, clear to the end, and render changed lines

TuiAltScreen owns a terminal-height viewport. Without an explicit layout root it preserves the legacy single-document scrolling behavior. With setLayoutRoot(), VStack, HStack, and nested ScrollView components can reserve fixed regions and independently scroll constrained regions. It updates changed viewport rows in place, follows streaming output while at the bottom, and preserves a manually selected scroll position while content grows. Mouse-wheel and configurable keyboard navigation scroll without modifying terminal scrollback, including jumps between OSC 133 semantic prompt markers. Scrollbars support hover expansion, thumb dragging, and track-click jumping. Clicking an OSC 8 hyperlink opens it with the configured URL handler. Dragging with the primary mouse button selects text and, unless TuiAltScreenOptions.copyOnSelect is false, copies it to the clipboard with OSC 52; holding the drag at a scroll view's top or bottom edge auto-scrolls and extends the selection into off-screen content. Kitty images support vertical viewport cropping; iTerm2 inline images fall back to text because the iTerm2 protocol cannot delete or crop placements during viewport repainting.

Both renderers wrap updates in synchronized output (\x1b[?2026h ... \x1b[?2026l) for atomic, flicker-free rendering.

Terminal Interface

The TUI works with any object implementing the Terminal interface:

interface Terminal {
  start(onInput: (data: string) => void, onResize: () => void): void;
  stop(): void;
  write(data: string): void;
  get columns(): number;
  get rows(): number;
  moveBy(lines: number): void;
  hideCursor(): void;
  showCursor(): void;
  clearLine(): void;
  clearFromCursor(): void;
  clearScreen(): void;
}

Built-in implementation:

• ProcessTerminal - Uses process.stdin/stdout

Utilities

import { visibleWidth, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";

// Get visible width of string (ignoring ANSI codes)
const width = visibleWidth("\x1b[31mHello\x1b[0m"); // 5

// Truncate string to width (preserving ANSI codes, adds ellipsis)
const truncated = truncateToWidth("Hello World", 8); // "Hello..."

// Truncate without ellipsis
const truncatedNoEllipsis = truncateToWidth("Hello World", 8, ""); // "Hello Wo"

// Wrap text to width (preserving ANSI codes across line breaks)
const lines = wrapTextWithAnsi("This is a long line that needs wrapping", 20);
// ["This is a long line", "that needs wrapping"]

Colors and terminal styles

Colors are values that can be converted or mixed before terminal rendering:

import {
  colorToRgb,
  foregroundAnsi,
  getTerminalColorMode,
  mixColors,
  parseColor,
  rgbColor,
  styleText,
} from "@earendil-works/pi-tui";

const accent = parseColor("oklch(70% 0.12 220)");
const background = parseColor("#20242a");
const foreground = mixColors(accent, background, 0.2);

const text = styleText(
  "Ready",
  { fg: foreground, bg: background, bold: true },
  getTerminalColorMode(),
);

Color is an indexed ANSI color, an sRGB color, or an OKLCH color. Every color converts to sRGB, so color math such as mixColors() always works. Indices 0-15 follow the user's terminal palette, so their sRGB values are approximations. styleText() converts colors to truecolor or 256-color output based on the requested terminal mode.

parseColor() also accepts OKHSL, as in okhsl(250 60% 55%); okhslColor() builds it in code and colorToOkhsl() reads any color's OKHSL channels. OKHSL saturation is relative to the most the sRGB gamut allows at that hue and lightness, so every value is in gamut. OKHSL colors are converted to sRGB when created.

Conversions are not cached, and OKLCH colors outside the sRGB gamut are the most expensive to convert. For colors used on every render, convert once and reuse the result:

const { r, g, b } = colorToRgb(mixColors(accent, background, 0.2));
const foreground = rgbColor(r, g, b); // cheap to render repeatedly
const foregroundCode = foregroundAnsi(foreground, getTerminalColorMode());

Creating Custom Components

When creating custom components, each line returned by render() must not exceed the width parameter. The TUI will error if any line is wider than the terminal.

Handling Input

Use matchesKey() with the Key helper for keyboard input:

import { matchesKey, Key, truncateToWidth } from "@earendil-works/pi-tui";
import type { Component } from "@earendil-works/pi-tui";

class MyInteractiveComponent implements Component {
  private selectedIndex = 0;
  private items = ["Option 1", "Option 2", "Option 3"];
  
  public onSelect?: (index: number) => void;
  public onCancel?: () => void;

  handleInput(data: string): void {
    if (matchesKey(data, Key.up)) {
      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
    } else if (matchesKey(data, Key.down)) {
      this.selectedIndex = Math.min(this.items.length - 1, this.selectedIndex + 1);
    } else if (matchesKey(data, Key.enter)) {
      this.onSelect?.(this.selectedIndex);
    } else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
      this.onCancel?.();
    }
  }

  render(width: number): string[] {
    return this.items.map((item, i) => {
      const prefix = i === this.selectedIndex ? "> " : "  ";
      return truncateToWidth(prefix + item, width);
    });
  }
}

Handling Line Width

Use the provided utilities to ensure lines fit:

import { visibleWidth, truncateToWidth } from "@earendil-works/pi-tui";
import type { Component } from "@earendil-works/pi-tui";

class MyComponent implements Component {
  private text: string;

  constructor(text: string) {
    this.text = text;
  }

  render(width: number): string[] {
    // Option 1: Truncate long lines
    return [truncateToWidth(this.text, width)];

    // Option 2: Check and pad to exact width
    const line = this.text;
    const visible = visibleWidth(line);
    if (visible > width) {
      return [truncateToWidth(line, width)];
    }
    // Pad to exact width (optional, for backgrounds)
    return [line + " ".repeat(width - visible)];
  }
}

ANSI Code Considerations

Both visibleWidth() and truncateToWidth() correctly handle ANSI escape codes:

• visibleWidth() ignores ANSI codes when calculating width
• truncateToWidth() preserves ANSI codes and properly closes them when truncating

import chalk from "chalk";

const styled = chalk.red("Hello") + " " + chalk.blue("World");
const width = visibleWidth(styled); // 11 (not counting ANSI codes)
const truncated = truncateToWidth(styled, 8); // Red "Hello" + " W..." with proper reset

Caching

For performance, components should cache their rendered output and only re-render when necessary:

class CachedComponent implements Component {
  private text: string;
  private cachedWidth?: number;
  private cachedLines?: string[];

  render(width: number): string[] {
    if (this.cachedLines && this.cachedWidth === width) {
      return this.cachedLines;
    }

    const lines = [truncateToWidth(this.text, width)];

    this.cachedWidth = width;
    this.cachedLines = lines;
    return lines;
  }

  invalidate(): void {
    this.cachedWidth = undefined;
    this.cachedLines = undefined;
  }
}

Example

See test/chat-simple.ts for a complete chat interface example with:

• Markdown messages with custom background colors
• Loading spinner during responses
• Editor with autocomplete and slash commands
• Spacers between messages

Run it:

bunx tsx test/chat-simple.ts

Development

# Install dependencies (from monorepo root)
npm install
# Bun alternative: bun install

# Run type checking
bun run check

# Run the demo
bunx tsx test/chat-simple.ts

Debug logging

Set PI_TUI_WRITE_LOG to capture the raw ANSI stream written to stdout.

PI_TUI_WRITE_LOG=/tmp/tui-ansi.log bunx tsx test/chat-simple.ts