Terminal UI package (packages/tui)
Overview
Path-routing coverage note: this doc owns packages/tui/**, including the TypeScript entrypoint and components under packages/tui/src/**, native helper sources and prebuilds under packages/tui/native/**, package metadata such as packages/…/package.json and packages/…/tsconfig.build.json, and tests/fixtures under packages/tui/test/**.
packages/tui publishes @earendil-works/pi-tui, a Node 22 ESM terminal UI library. packages/…/package.json points consumers at dist/index.js/dist/index.d.ts, builds TypeScript with tsc -p tsconfig.build.json, ships native prebuilds and source recipes for Darwin/Linux/Windows, and runs package tests with Node's built-in test runner over test/*.test.ts. packages/…/index.ts is the public API surface: it re-exports the renderer classes, components, keybinding utilities, terminal/image helpers, Markdown/LaTeX rendering, colors, native clipboard access, and width/truncation utilities.
The renderer core is packages/…/tui.ts. Components implement Component.render(width) and optional handleInput/handleMouse; Container concatenates child output and preserves unchanged child-line arrays so parent renders can reuse them. TuiBase owns terminal lifecycle, focus, overlays, input listeners, color-scheme/color-palette queries, render throttling, and process-exit restoration. It starts a Terminal, routes raw terminal sequences through input listeners and the focused component, filters Kitty key releases unless a component opts in, and schedules renders immediately for keyboard input but throttles ordinary repaint requests to about one frame per 16 ms. Overlay state lives in TuiBase: showOverlay() records focus history, supports non-capturing overlays, computes absolute/percentage/anchor-based bounds, composites overlay lines over base content with compositeTuiLine(), and hides terminal image placements that would otherwise draw above an overlay.
There are two concrete renderer modes. packages/…/tui-main-screen.ts implements regular/main-screen rendering into scrollback. It keeps previousLines, viewport/cursor bookkeeping, and previous Kitty image IDs, then writes only changed line ranges unless a width/height change, shrink clear, offscreen change, or image-row interaction requires a full render. Large writes go through BoundedTerminalWriter, which splits output into 1 MiB chunks and preserves surrogate pairs. Regular mode strips OSC 133 prompt markers before writing, appends line resets, validates non-image lines do not exceed terminal width, deletes changed Kitty images, and positions the hardware cursor from CURSOR_MARKER when focused components emit it.
packages/…/tui-alt-screen.ts implements fullscreen alternate-screen rendering and is also the ViewportTUI implementation. On start it enters the alternate screen, disables autowrap, enables SGR mouse tracking (button-motion inside tmux/screen-like multiplexers), resets selection/search/scroll state, and temporarily disables iTerm2 images because fullscreen image support is Kitty-oriented. Its frame path renders a layout tree via packages/…/layout.ts, optionally reuses the prior LayoutRenderCache for scroll-only frames, applies transcript search highlights, jump-to-end and flash overlays, general overlays, mouse-selection highlighting, and line resets, then writes changed rows inside synchronized output. It owns fullscreen behaviors that are not component-local: viewport scrolling, prompt navigation via OSC 133 markers in scroll content, transcript search overlays from packages/…/alt-screen-search.ts, scrollbar hit-testing/dragging, OSC 8 link activation, text selection/copy through injected clipboard logic or OSC 52, right-click paste on Windows, and Kitty image upload/placement caching.
Layout-aware components expose a LAYOUT_NODE from packages/…/layout-node.ts; packages/…/layout.ts lays out vertical/horizontal stacks and scroll views into LayoutBox trees, paints clipped boxes into fixed-height screen rows, composites overlapping content, paints transient or always-visible scrollbars, crops Kitty images at clip boundaries, and lets fullscreen mouse dispatch find deepest boxes or scroll views at a screen coordinate. packages/…/stack.ts, v-stack.ts, and h-stack.ts implement flex-like stack sizing with basis/grow/shrink/min/max/visibility, while packages/…/scroll-view.ts wraps exactly one child, tracks scrollTop, follow-end state, overscroll behavior, content/viewport height, and scrollbar visibility/activity.
The terminal adapter is packages/…/terminal.ts. ProcessTerminal puts stdin in raw mode, enables bracketed paste, listens for stdout resize, refreshes dimensions with a best-effort SIGWINCH, enables Windows VT input via the native helper, and negotiates Kitty keyboard protocol with a DA1-sentinel fallback to xterm modifyOtherKeys. It feeds raw stdin into packages/…/stdin-buffer.ts, which reassembles CSI/OSC/DCS/APC/mouse/bracketed-paste sequences, gives lone ESC a configurable timeout (PI_TUI_ESC_TIMEOUT, longer over SSH), and keeps delayed terminal replies from becoming keypresses. ProcessTerminal also handles OSC 9;4 progress, OSC 7501 program status from packages/…/program-status.ts, write logging via PI_TUI_WRITE_LOG, input draining before exit, and synchronous mode restoration from a process exit handler.
Keyboard matching is centralized in packages/…/keys.ts and packages/…/keybindings.ts. keys.ts parses legacy sequences, Kitty CSI-u/arrow/function sequences, xterm modifyOtherKeys, printable CSI-u characters, key release/repeat markers, non-Latin base-layout fallbacks, shifted symbols, keypad aliases, Windows raw backspace ambiguity, and typed KeyId strings. keybindings.ts defines namespaced defaults for editor, generic input, selection lists, and fullscreen viewport actions; KeybindingsManager resolves user bindings, detects conflicts among user-provided keys, and delegates matching to matchesKey().
Text measurement and ANSI-aware string operations live in packages/…/utils.ts. It uses Intl.Segmenter, get-east-asian-width, emoji/mark heuristics, and caches to compute terminal cell width; strips or preserves CSI/OSC/APC sequences; slices and truncates by terminal columns while closing/reopening OSC 8 links; wraps ANSI-styled text without leaking underline/strikethrough/hyperlinks across line padding; normalizes Thai/Lao AM vowels and visible tabs before terminal output; and exposes autocomplete/CJK punctuation regexes used by editors and Markdown. packages/…/colors.ts parses indexed, RGB, OKLCH, and OKHSL colors, converts through OKLab, mixes colors, and emits truecolor or 256-color SGR sequences. packages/…/terminal-colors.ts parses OSC 10/11/4 replies and terminal color-scheme reports; TuiBase.queryTerminalColors() writes those queries and completes on DA1/all replies or timeout.
The primary input widgets are packages/…/editor.ts and packages/…/input.ts. Editor is a multiline focused component with word/CJK wrapping, vertical scrolling capped at 30% of terminal rows (minimum 5), bracketed paste handling, paste-marker compaction/expansion for large pastes, prompt history, undo stack, kill ring, word/line/character movement, jump-to-character mode, submit/newline fallbacks, and asynchronous autocomplete. Its autocomplete menu uses SelectList, CombinedAutocompleteProvider from packages/…/autocomplete.ts, abort/debounce logic, trigger characters, slash commands, @ attachments, direct file completions, and fd-backed fuzzy file search when an fdPath is supplied. Input is a single-line version with horizontal scrolling, placeholder styling, mouse cursor placement, kill ring, undo, bracketed paste, and shared keybindings. packages/…/editor-component.ts defines the compatibility surface for custom editor implementations.
Renderable content components include Markdown, images, lists, and layout primitives. packages/…/markdown.ts parses with marked plus marked-cjk-friendly, customizes bare URL and strikethrough tokenization, adds inline/block LaTeX tokens rendered by packages/…/latex.ts, hides HTML comments, trims streamed partial code fences, preserves optional list/backslash styles, optionally reuses parsed tokens/rendered blocks/highlighted code through weak references, wraps with ANSI-aware utilities, and emits OSC 8 hyperlinks only when getCapabilities().hyperlinks is true. packages/…/image.ts renders inline images through packages/…/terminal-image.ts, converting non-PNG data to PNG for Kitty when a synchronous ImageTranscoder is registered, assigning/reusing Kitty image IDs, reserving rows for image height, and falling back to styled text with optional file hyperlinks. Selection widgets (select-list.ts, settings-list.ts), basic text/box/spacer/loader/cancellable-loader components, and mouse regions are thin Component implementations that rely on the same width/key/mouse contracts.
Terminal image support is in packages/…/terminal-image.ts. Capability detection is environment-driven with overrides (PI_IMAGE_PROTOCOL, PI_TRUE_COLOR, PI_HYPERLINKS) and special handling for tmux/screen, Herdr, Rex, Orca, Kitty, Ghostty, WezTerm, Warp, iTerm2, Windows Terminal, Alacritty, VS Code, Zed, JetBrains, and unknown terminals. It encodes Kitty and iTerm2 protocols, tracks Kitty image metadata/transmission generations, computes image cell size from pixel and cell dimensions, reads PNG/JPEG/GIF/WebP dimensions from base64 buffers, crops Kitty image lines when partially scrolled/clipped, emits placement-only reuse commands, and provides file/text fallbacks.
Native platform helpers are optional .node modules loaded by packages/…/native-platform.ts via candidate paths from packages/…/native-module-path.ts: installed package location, nearby dist/source-relative locations, and standalone binary-adjacent locations. Darwin and Windows helpers expose clipboard text/image writes/reads plus modifier-state checks; Windows also exposes enableVirtualTerminalInput. Linux only loads native/linux/prebuilds/*/linux-platform-x11.node when DISPLAY is set and exposes X11 clipboard text/image reads. The shared N-API shim in packages/…/napi.h resolves a small N-API surface dynamically without Node headers; packages/…/clipboard.h queues async clipboard jobs and converts empty/text/buffer/path results into promises. Build recipes are packages/…/build.sh, packages/…/build.sh, and packages/…/build.mjs, producing prebuilds for x64/arm64 targets.
Tests under packages/tui/test/** exercise renderer diffs, alt-screen behavior, overlays, layout, mouse dispatch, key/keybinding parsing, stdin buffering, terminal colors/status/images, native module path/clipboard behavior, text width/slicing/wrapping/truncation, Markdown/LaTeX rendering, editor/input/autocomplete/list widgets, and focused regressions such as image line detection, SIGWINCH EACCES handling, regional indicator width, ANSI ordering around slice boundaries, CJK overlay boundaries, and exit restoration. packages/…/virtual-terminal.ts is the in-scope test terminal harness for renderer tests.
Coupling
- If
Component.render()output semantics change in packages/…/tui.ts, verify both renderers: packages/…/tui-main-screen.ts assumes lines are immutable/cached and may diff by string identity/content, while packages/…/tui-alt-screen.ts may reuseLayoutRenderCachewhenTuiBase.contentChangedis false. - If
CURSOR_MARKER, fake cursor markers, or focus handling change in packages/…/tui.ts, verify packages/…/editor.ts, packages/…/input.ts, packages/…/tui-main-screen.ts, and packages/…/tui-alt-screen.ts; focused inputs emit these sentinels and both renderers must strip/resolve them before terminal output while still positioning the hardware cursor. - If terminal input splitting changes in packages/…/stdin-buffer.ts, re-check packages/…/terminal.ts keyboard-protocol negotiation and packages/…/keys.ts release/repeat matching.
ProcessTerminalrelies onStdinBufferto keep terminal replies, bracketed paste, Kitty protocol replies, mouse events, and legacy Alt sequences separated before keybindings see them. - If key identifiers or defaults change in packages/…/keys.ts or packages/…/keybindings.ts, verify packages/…/editor.ts, packages/…/input.ts, packages/…/select-list.ts, and packages/…/tui-alt-screen.ts; these components do not parse raw sequences themselves except for a few compatibility fallbacks.
- If visible-width, grapheme segmentation, ANSI extraction, OSC 8 handling, or
sliceByColumn()changes in packages/…/utils.ts, verify renderers, overlays, Markdown, editor/input cursor placement, selection copying, search highlights, and image/layout clipping. Many modules assumevisibleWidth()matches terminal cell occupation for diffing and bounds checks. - If image capability detection or Kitty metadata changes in packages/…/terminal-image.ts, verify packages/…/image.ts, packages/…/layout.ts, packages/…/tui-main-screen.ts, and packages/…/tui-alt-screen.ts; image rows are reserved, cropped, hidden under overlays, deleted/reused, and sometimes redrawn after text depending on the same metadata.
- If
LAYOUT_NODEshapes in packages/…/layout-node.ts or stack/scroll sizing in packages/…/layout.ts change, update packages/…/stack.ts, h-stack.ts, v-stack.ts, and scroll-view.ts together. Fullscreen mouse hit-testing, scrollbar geometry, primary scroll view selection, and O(viewport) scroll reuse all consume the layout boxes produced there. - If native prebuild names, directories, or package
filesentries change, update packages/…/native-platform.ts, packages/…/native-module-path.ts, packages/…/package.json, and the matchingpackages/tui/native/*/build.*script. Runtime loading constructs paths such asnative/<platform>/prebuilds/<platform>-<arch>/<platform>-platform*.nodeand packaging must include those files. - If clipboard result formats change in packages/…/clipboard.h, verify all platform implementations (
native/darwin/src/darwin-platform.m, native/…/win32-platform.c, native/…/linux-platform-x11.c) and packages/…/native-platform.ts; JS expectsundefinedfor unavailable,nullfor empty,Uint8Array/string/path arrays for content, and promise rejection for transfer failures. - If Markdown tokenization or rendering changes in packages/…/markdown.ts, verify packages/…/utils.ts wrapping/slicing, packages/…/terminal-image.ts image-line detection, and packages/…/latex.ts; Markdown emits styled lines, inline images, and LaTeX text that are later clipped and diffed by terminal cell width.
Risks
- packages/…/tui-main-screen.ts, packages/…/tui-alt-screen.ts, packages/…/layout.ts, packages/…/terminal-image.ts, and packages/…/image.ts form a fragile image-rendering path. If Kitty/iTerm2 image metadata, row reservation, clipping, deletion, or redraw order drifts, images can overwrite overlays, disappear while scrolling, or leave stale cells; recent history contains repeated fixes such as
fix(tui): hide terminal images covered by overlays,fix(tui): keep Kitty images across fullscreen full redraws, andfix(tui): draw fullscreen Kitty images after the rows they cover on every terminal. - packages/…/utils.ts is a high-risk width/ANSI primitive. If it miscounts graphemes, tabs, regional indicators, Thai/Lao marks, CJK boundaries, or OSC 8/SGR resets, renderers can auto-wrap unexpectedly, line diffs can target the wrong cells, and selections/search highlights can slice through escape sequences; history shows many targeted fixes for width accounting, ANSI ordering, CJK wrapping, regional indicators, and OSC 8 truncation.
- packages/…/stdin-buffer.ts, packages/…/terminal.ts, and packages/…/keys.ts are sensitive to partial escape sequences and terminal-specific keyboard protocols. If terminal replies or split sequences are forwarded as text, users can see control garbage typed into editors or lose shortcuts; history includes fixes for delayed replies, split Shift/Alt+Enter, Kitty negotiation, modifyOtherKeys fallback, and SSH key-release leaks.
- packages/…/tui.ts overlay focus restoration and mouse capture affect every component in fullscreen mode. If focus history or capture retargeting is wrong, hidden overlays can keep input, viewport keys can scroll the transcript instead of a focused overlay, or mouse releases can go to a stale child; prior fixes specifically hardened overlay focus restoration and focused-overlay interactivity.
- Native helpers under
packages/tui/native/**are hard to validate uniformly because each platform uses different OS APIs and prebuilt packaging. A mismatch between packages/…/native-module-path.ts, packages/…/native-platform.ts, build scripts, and packagefilescan silently disable clipboard/modifier support or Windows VT input in packaged or standalone binaries.