glyphix-tui

High-Performance, Low-Level Terminal User Interface Renderer for Node.js

glyphix-tui is a minimal, unopinionated, and highly optimized TUI rendering engine. It is designed to be the foundational "pixel pusher" for higher-level frameworks or performance-critical terminal applications.

日本語ドキュメント (Japanese)

Philosophy

• Single Source of Truth: The Buffer is the only truth. What you put in the buffer is what gets rendered.
• Zero Abstraction Cost: No hidden object allocations per cell. Everything is a 32-bit integer.
• Correctness First: The Renderer is a state machine that guarantees the terminal screen matches the buffer exactly, resolving complex attribute overlaps.
• Performance: Optimized diffing algorithms ensure only the necessary ANSI sequences are sent to the terminal.

Capabilities (What It Does)

• Bit-Packed Glyphs: Store character (ASCII), foreground color (xterm-256), background color (xterm-256), and attributes (Bold, Underline, etc.) in a single 32-bit integer.
• Efficient Rendering: Compares current and previous frames to emit minimal ANSI escape codes.
• State Management: Automatically handles ANSI state synchronization (colors, attributes), resetting only when necessary.
• Typed Arrays: Uses Uint32Array for buffer storage, ensuring cache locality and low memory overhead.

Non-Goals (What It Doesn't Do)

glyphix-tui is NOT a widget library. To keep the core lightweight and fast, the following are explicitly out of scope:

• Widgets: No buttons, lists, or text boxes.
• Layouts: No Flexbox or Grid systems.
• Input Handling: No keyboard or mouse event listeners.
• Unicode/Wide Characters: Strictly ASCII-oriented for predictable cell width (1 byte = 1 cell).

Installation

npm install glyphix-tui

Usage

Basic Example

const { Buffer, Renderer, Glyph, Attr } = require("glyphix-tui");

const WIDTH = 40;
const HEIGHT = 10;

// 1. Initialize Buffer and Renderer
const buf = new Buffer(WIDTH, HEIGHT);
const renderer = new Renderer(process.stdout, WIDTH, HEIGHT);

// 2. helper for packing glyphs
const { pack } = Glyph;

// 3. Draw to the buffer
// Example: Draw a red 'A' with bold attribute at (0, 0)
const char = "A".charCodeAt(0);
const fg = 196; // Red (xterm-256)
const bg = 0; // Black
const attr = Attr.BOLD | Attr.UNDERLINE;

buf.cells[0] = pack(char, fg, bg, attr);

// 4. Commit to the terminal
renderer.commit(buf);

Using Helpers

For convenience, light helper functions are provided for common drawing operations. Helpers are pure convenience utilities and do not affect the core rendering model or performance characteristics.

const { helper, Glyph } = require("glyphix-tui");

// Fill background with blue
helper.fillRect(buf, 0, 0, WIDTH, HEIGHT, Glyph.pack(32, 255, 21, 0));

// Draw text
helper.drawText(buf, 2, 2, "Hello World", (code) =>
  Glyph.pack(code, 255, 21, Glyph.Attr.BOLD),
);

renderer.commit(buf);

Documentation

Detailed documentation is available in the docs/ directory:

• Buffer: Memory structure and manipulation.
• Glyph: Bit-packing details and color/attribute handling.
• Renderer: Rendering lifecycle and diffing algorithm.
• Attributes: List of available style flags.
• Specification: The core specification document.

License

MIT