OpenTUI Explained

A terminal acts as a grid of cells. Each cell displays a character with specific colors and styles. Unlike graphical apps that draw pixels, terminal apps write bytes to stdout. The terminal reads these bytes to decide what to show.

Text and control bytes

Everything in a terminal is text plus control bytes. Many controls use escape sequences starting with ESC (0x1B). Simpler control bytes like CR, LF, and TAB handle cursor movement and layout.

Control sequences tell the terminal what to do. The most common type is the CSI sequence. It starts with \x1b[ (ESC + [) and ends with a command character. Other sequences start with \x1b] (OSC) or \x1bP (DCS).

ANSI sequence structure

Common escape sequences

// Cursor control
pub const hideCursor = "\x1b[?25l";
pub const showCursor = "\x1b[?25h";
pub const home = "\x1b[H";

// Screen control
pub const clear = "\x1b[2J";
pub const reset = "\x1b[0m";

// Text attributes
pub const bold = "\x1b[1m";
pub const italic = "\x1b[3m";
pub const underline = "\x1b[4m";

// True color (24-bit RGB)
// Foreground: ESC[38;2;R;G;Bm
// Background: ESC[48;2;R;G;Bm

Create an ANSI sequence

OpenTUI uses a Structure of Arrays (SoA) layout. This means it stores each field in a separate array, rather than grouping fields into a structure for each cell. This layout improves cache speed and lets the CPU process data faster.

Cell structure

Attribute bit packing

Text attributes pack into the lower 8 bits of a u32 using bit flags. The remaining 24 bits store a link ID. This saves space and allows fast bitwise comparison.

Memory layout: SoA vs AoS

// Structure of Arrays - what OpenTUI uses
pub const OptimizedBuffer = struct {
    buffer: struct {
        char: []u32,        // All characters contiguous
        fg: []RGBA,          // All foregrounds contiguous
        bg: []RGBA,          // All backgrounds contiguous
        attributes: []u32,  // All attributes contiguous
    },
    width: u32,
    height: u32,
    // ...
};

// Index calculation: row-major order
fn coordsToIndex(x: u32, y: u32) u32 {
    return y * self.width + x;
}

One character on screen can use multiple Unicode codepoints. For example, emojis with skin tones or flags use several codepoints but appear as one symbol. These groups are called grapheme clusters. OpenTUI stores these clusters in a separate pool and refers to them by ID.

Grapheme ID encoding

When a character is a grapheme cluster, the char field stores a pool ID instead of a codepoint. The top 2 bits indicate the type:

// Bit 31-30 encoding:
// 00xxxxxx = direct Unicode codepoint
// 10xxxxxx = grapheme start (pool ID in lower bits)
// 11xxxxxx = continuation cell

pub const CHAR_FLAG_GRAPHEME: u32 = 0x8000_0000;
pub const CHAR_FLAG_CONTINUATION: u32 = 0xC000_0000;

pub fn isGraphemeChar(c: u32) bool {
    return (c & 0xC000_0000) == CHAR_FLAG_GRAPHEME;
}

pub fn graphemeIdFromChar(c: u32) u32 {
    return c & 0x03FF_FFFF;  // Lower 26 bits
}

The grapheme pool

Grapheme byte sequences live in a slab allocator with size classes: 8, 16, 32, 64, and 128 bytes. The 26-bit ID encodes the class (3 bits), generation (7 bits), and slot index (16 bits).

OpenTUI uses double buffering. It draws to a "next" buffer, then compares that with the "current" buffer. It only writes the changed cells to the terminal. This is important because a standard 80x24 terminal contains 1,920 cells.

Why speed matters

Terminals are character devices, not block devices. Unlike a GPU that updates a whole screen at once, a terminal sends one byte at a time. This happens over a serial connection.

The program does not know about the terminal emulator. It only sees stdout. Characters, cursor movements, and color codes all flow through this serial pipe. This uses bandwidth. Look at the cell skip logic in renderer.zig:611-626:

if (!force) {
    const charEqual = currentCell.?.char == nextCell.?.char;
    const attrEqual = currentCell.?.attributes == nextCell.?.attributes;

    if (charEqual and attrEqual and
        buf.rgbaEqual(currentCell.?.fg, nextCell.?.fg, colorEpsilon) and
        buf.rgbaEqual(currentCell.?.bg, nextCell.?.bg, colorEpsilon))
    {
        // Cell unchanged - skip it entirely, write zero bytes
        continue;
    }
}

When a cell hasn't changed, the renderer writes nothing—no cursor move, no character, no color codes. The colorEpsilon comparison even skips cells where colors are nearly identical, avoiding churn from floating-point precision.

How the diff works

fn prepareRenderFrame(self: *CliRenderer, force: bool) void {
    var currentFg: ?RGBA = null;
    var currentBg: ?RGBA = null;
    
    for (0..self.height) |y| {
        for (0..self.width) |x| {
            const currentCell = self.currentRenderBuffer.get(x, y);
            const nextCell = self.nextRenderBuffer.get(x, y);
            
            // Skip if unchanged
            if (!force and cellsEqual(currentCell, nextCell)) {
                continue;
            }
            
            // Only emit color codes if color changed
            if (!colorsMatch(currentFg, nextCell.fg)) {
                ansi.moveToOutput(writer, x + 1, y + 1);
                ansi.fgColorOutput(writer, nextCell.fg);
                currentFg = nextCell.fg;
            }
            
            // Write character
            writer.writeAll(nextCell.char);
            
            // Update current buffer to match
            self.currentRenderBuffer.set(x, y, nextCell);
        }
    }
}

OpenTUI renders frames like a game engine. In each frame, it runs callbacks, calculates layout, draws to the buffer, checks for changes, and outputs them. This loop handles both animations and static UI.

Two rendering modes

Rendering all the time wastes resources because most UIs stay static. OpenTUI uses two modes to save power:

The six phases

OpenTUI combines TypeScript and Zig. TypeScript manages components and easy-to-use APIs. Zig handles fast rendering. The two languages talk through a Foreign Function Interface (FFI).

Key data flow

Terminals also use escape sequences for input. Regular keys send raw UTF-8 bytes. Special keys and mouse actions send multi-byte sequences. OpenTUI turns these bytes into events.

Mouse event parsing

Mouse events use SGR (Select Graphic Rendition) extended format. The escape sequence encodes button, position, and modifiers. This demo shows pixel positions for clarity; real SGR events report 1-based cell coordinates.

// Mouse click at x=10, y=5
\x1b[<0;10;5M  // Button down
\x1b[<0;10;5m  // Button up (lowercase m)

// Button code bits:
// Bits 0-1: button (0=left, 1=middle, 2=right)
// Bit 2: Shift held
// Bit 3: Alt held
// Bit 4: Ctrl held
// Bit 5: Motion event
// Bit 6: Scroll event

Zig pointers become opaque ptr types in TypeScript. You can pass them around, but you cannot read them directly from JavaScript.

export fn createRenderer(
    width: u32, 
    height: u32,
    testing: bool
) ?*renderer.CliRenderer {
    const pool = gp.initGlobalPool(globalArena);
    return renderer.CliRenderer.create(
        globalAllocator, width, height, pool, testing
    ) catch return null;
}

// bun:ffi declaration
createRenderer: {
  args: ["u32", "u32", "bool"],
  returns: "ptr",  // Opaque pointer!
},

// Usage
this.rendererPtr = lib.createRenderer(
    width, height, testing
);

You need to understand the lifecycle to build custom components. This diagram shows the process from creation to deletion.

The hit grid is an array of IDs the size of the screen. Each cell holds the ID of the component at that spot. Mouse events check this grid to find which component to target.

Double buffering

The hit grid uses two buffers to prevent race conditions: mouse events read from currentHitGrid while rendering writes to nextHitGrid. After the frame completes, the buffers swap atomically.

Render list gating

Hit grid registration happens inside render(), which is only called for renderables in the render list. The render list is built during the layout pass (updateLayout), which both propagates positions and collects renderables for drawing. Each parent calls _getVisibleChildren() to decide which children to traverse. The default returns all children. A parent that returns [] hides its entire subtree from the render list.

Hidden children still exist in the tree and receive layout position updates, but they have no hit grid entry. Mouse clicks at their screen position will resolve to the parent (or nothing), and text selection cannot reach their content. This is how ScrollBoxRenderable culls off-screen children—they re-enter the render list when they scroll into view.

Scissor clipping

OpenTUI includes built-in debugging tools.

Debug overlay

// Toggle overlay (shows FPS, frame times, memory)
renderer.toggleDebugOverlay();

// Configure position
renderer.setDebugOverlay({ 
  enabled: true, 
  corner: 1  // 0=topLeft, 1=topRight, 2=bottomLeft, 3=bottomRight
});

Buffer dumping

renderer.dumpBuffers();      // Writes buffer state to file
renderer.dumpHitGrid();      // Logs hit grid to console
renderer.dumpStdoutBuffer(); // Writes raw ANSI output

Test renderer

const { 
  renderer, 
  mockInput, 
  mockMouse, 
  renderOnce, 
  captureCharFrame,  // Get text content as string
  captureSpans       // Get styled spans with colors
} = await createTestRenderer({ width: 80, height: 24 });

await renderOnce();
const frame = captureCharFrame();
const spans = captureSpans();

A guide to important files in the codebase.