hqtui

HQTUI is a terminal UI library that renders btop-grade dashboards directly over ANSI/VT sequences, with no ncurses, no DOM, and no native addon. A single createApp() call sets up a dark theme, truecolor with automatic 256/16-colour fallback, mouse tracking, the alternate screen, resize handling, adaptive frame-rate rendering, and terminal restoration on any exit path including crashes.

On top of that runtime sits a widget and layout system: grids with fractional/percentage/auto sizing, panels, tables, trees, graphs, meters, gauges, a Braille-based canvas for 2x4-subpixel graphics, and interactive controls (buttons, checkboxes, selects, modals, a command palette) that all take mouse and keyboard input. A built-in Markdown export feature lets any summary pane copy its data to the clipboard over OSC 52, including through SSH and tmux.

The TypeScript implementation in this package is the reference model for a wider project: the same rendering approach (framebuffer, differential encoding, Braille graphics) is reimplemented natively in Rust, Go, Python, Zig, C++, and via bindings in Ruby, PHP, and Perl, all runnable from one demo launcher script.

What You Get

• One-import app bootstrap - createApp() sets up a dark truecolor theme, mouse tracking, alternate screen, resize handling, and guaranteed terminal restoration in a single call.
• A full widget library - panels, tables, trees, log viewers, graphs, meters, gauges, donuts, sparklines, tabs, modals, a command palette, and form controls, all composable through a grid/flex-style layout system.
• Braille and block graphics - a canvas with 2x4 pixels per terminal cell for line/area charts and a world map widget, with block, half-block, quadrant, and ASCII fallback modes.
• Automatic color and capability fallback - 24-bit truecolor with automatic downgrade to 256 and 16 colors, NO_COLOR support, and monochrome/high-contrast modes.
• Markdown clipboard export - any summary panel can expose a copy-as-Markdown control delivered via OSC 52, so dashboard state can be pasted elsewhere even over SSH.
• Cross-language reference implementation - the same rendering model is ported natively to Rust, Go, Python, Zig, and C++, with Ruby/PHP/Perl bindings, all runnable from one demo script.

Common Use Cases

• Server and infra dashboards - CPU/memory/network/process monitors that run over SSH without needing a web UI.
• CLI tool status screens - build tools, deployment scripts, or long-running jobs that want a live, interactive terminal display instead of scrolling log lines.
• Internal ops tooling - session/service/traffic monitors for teams that live in the terminal and want systemd, docker, and network state in one view.
• Cross-language TUI prototyping - teams evaluating the same dashboard design across TypeScript, Rust, Go, or Python can reuse the identical rendering model and widget set.

Under The Hood

Architecture HQTUI is layered from the terminal outward: terminal.ts and capabilities.ts own raw I/O and feature detection (color depth, mouse, SSH), buffer.ts holds a typed-array framebuffer that widgets paint into, and diff.ts encodes only the cells that changed between frames into minimal ANSI writes. surface.ts and layout.ts provide box-drawing and a single-pass constraint-based sizing system (fixed, percent, fractional, auto) that every widget composes through. ui.ts’s Container/GridContainer builds the widget tree and dispatches hit-testing and focus for input events, and app.ts ties the whole loop together — render callback, adaptive fps, quit keys, and emergency terminal restoration on any exit path. The result is a clear one-directional pipeline (input -> app state -> widget tree -> framebuffer -> diff -> terminal) with no widget reaching around the framebuffer to write to the terminal directly.

Tech Stack The package is pure TypeScript targeting modern JS runtimes (Bun, Node 22.6+, Deno 2), published as native ESM with a subpath exports map (., ./graphics, ./testing, ./cli) and zero runtime dependencies. It lives inside a larger Bun/pnpm-workspace monorepo that also contains a demo app and native ports of the same rendering model in Rust, Go, Python, Zig, and C++, plus FFI-based Ruby/PHP/Perl bindings built through CMake — all pinned through a single mise.toml toolchain file. The library itself builds with a plain tsc invocation against a dedicated build tsconfig.

Code Quality The package ships an extensive test suite (around thirty test files) written against Node’s built-in node:test and node:assert/strict, runnable under both Bun and Node, covering graphics primitives, layout, widgets, mouse handling, and security-sensitive input paths. A dedicated typecheck script runs tsc --noEmit in strict mode, and GitHub Actions CI exercises the native language bindings across an Ubuntu/macOS matrix. No dedicated linter configuration was found at the repo root, but the strict TypeScript types and broad test coverage substitute for a chunk of what a linter would normally catch.

What Makes It Unique Most terminal UI libraries stop at wrapping ncurses or exposing a widget set; HQTUI instead builds its own differential renderer over raw ANSI/VT sequences with a typed-array framebuffer and Braille-resolution graphics canvas, and then treats that rendering model as a specification to be reimplemented natively across nine language ecosystems from one TypeScript reference, each runnable from the same demo launcher. The built-in Markdown clipboard export for dashboard panels, delivered over OSC 52 through SSH and tmux, is also a level of polish uncommon in terminal UI tooling.