terminal/README.md

terminal

Direct ANSI terminal control for Go with zero-allocation rendering. Built for sustained 60fps full-screen redraws in cell-based applications (games, dashboards, TUIs). Depends on github.com/lixenwraith/color (RGB, palettes, blending), golang.org/x/sys and golang.org/x/term.

The package bypasses terminfo/termcap entirely and emits ANSI sequences directly. Target environments: xterm-compatible terminals on Linux and BSDs, Windows consoles with VT processing, and browsers via xterm.js (WASM builds).

Features

• True color (24-bit), 256-color, ANSI 16-color and colorless output with automatic capability detection, and the terminal's own default colors
• Double-buffered output with cell-level diffing — only changed cells emit sequences
• Raw stdin parsing: keys, modifiers, UTF-8 runes, SGR mouse, resize, bracketed paste
• Draws on the controlling terminal when stdin or stdout is redirected (Unix)
• Perceptual (Redmean) RGB → 256-palette mapping via O(1) LUT, from color
• Panic-safe terminal restoration (Fini, EmergencyReset)
• Unix, Windows and WASM backends behind a common interface

Architecture

Terminal (interface)
  └── termImpl
        ├── outputBuffer   diffing, ANSI generation
        ├── writeLoop      the one goroutine that writes output
        ├── inputReader    escape sequence parser, event channel
        └── Backend (interface)
              ├── unixBackend     //go:build unix — termios, unix.Poll, SIGWINCH, /dev/tty
              ├── windowsBackend  //go:build windows — console modes, VT processing
              └── wasmBackend     //go:build wasm — syscall/js, xterm.js bridge

Shared code carries no build tags: cell diffing, ANSI generation, escape parsing. Platform specifics are isolated in the Backend implementations.

NewWithBackend(b, mode) builds a Terminal over a Backend of the caller's own: a pipe, an in-process emulator or a test standing in for the tty. It behaves as New's Terminal does, the writer goroutine included; New is NewWithBackend over the platform's backend and the detected color mode.

Rendering pipeline

The application owns a flat []Cell buffer (row-major, cells[y*width+x]) and passes it to Flush. The output buffer diffs against the previously flushed frame:

• Rows are scanned with early termination (trailing unchanged cells skipped).
• Cursor moves are emitted only when the write position is non-contiguous.
• SGR state (fg, bg, attributes) is coalesced across cells; redundant sequences are suppressed.
• If the backend size changed between buffer preparation and Flush, the frame is dropped to prevent resize-race corruption. The next frame (built at the new size) renders normally.
• A cell is one glyph in one column, on a terminal that draws ambiguous-width runes (box drawing, U+FFFD) narrow: a control or format character in Rune (a pasted escape, a bidi override, a line separator) is drawn as a space, and a rune a terminal draws in no column, in two or in its neighbour's cluster (a combining or spacing mark, a wide or emoji rune) as U+FFFD.

Sync() clears the screen and invalidates the front buffer, forcing a full redraw — required after any external process writes to the terminal.

Output is written on a goroutine of its own, so no call waits on the terminal. A terminal that stops reading (a hidden tab, a multiplexer client that went away, flow control) holds that goroutine in its write; meanwhile Flush keeps only the newest frame, drawn once the write returns, and control sequences (cursor, mouse, paste, Clear, Sync) queue behind it in call order. Blocked() reports how long the write in flight has waited, so a caller can stop composing frames nobody will see. Fini waits up to two seconds for the restoring sequences, then restores the termios without them.

Auto-wrap and, where the terminal follows ECMA-48 mode 8 (VTE), its own bidi reordering are off during the session: the bottom-right cell is writable without scroll side effects, and right-to-left text stays in its cells.

Quick start

package main

import (
    "github.com/lixenwraith/color"
    "github.com/lixenwraith/terminal"
)

func main() {
    term := terminal.New() // color mode auto-detected
    if err := term.Init(); err != nil {
        panic(err)
    }
    defer term.Fini()

    w, h := term.Size()
    cells := make([]terminal.Cell, w*h)

    for {
        // Build frame
        for i := range cells {
            cells[i] = terminal.Cell{Rune: ' ', Bg: color.Gunmetal}
        }
        msg := "hello"
        for i, ch := range msg {
            // len(msg) to utf8.RuneCountIdString(msg) for non-ASCII
            cells[(h/2)*w+(w-len(msg))/2+i] = terminal.Cell{
                Rune: ch, Fg: color.Amber, Bg: color.Gunmetal,
                Attrs: terminal.AttrBold,
            }
        }
        term.Flush(cells, w, h)

        // Handle input
        ev := term.PollEvent()
        switch ev.Type {
        case terminal.EventKey:
            if ev.Key == terminal.KeyEscape || ev.Rune == 'q' {
                return
            }
        case terminal.EventResize:
            w, h = ev.Width, ev.Height
            cells = make([]terminal.Cell, w*h)
        }
    }
}

Cells and attributes

type Cell struct {
    Rune  rune
    Fg    color.RGB
    Bg    color.RGB
    Attrs Attr
}

Attr is a bitmask: AttrBold, AttrDim, AttrItalic, AttrUnderline, AttrBlink, AttrReverse.

Attr is 16 bits wide; the bits above the styles say how to read a cell's colors:

• With AttrFg256 / AttrBg256 set, Fg.R / Bg.R holds an xterm-256 palette index directly and G/B are ignored. This allows exact palette output on true color terminals and skips RGB → palette conversion. Indices 0-15 are the ANSI 16, which every terminal shows in its own theme's shades.
• With AttrFgDefault / AttrBgDefault set, the color is the terminal's own (SGR 39/49), whatever Fg / Bg hold: an application keeps a light or dark terminal's background without knowing which it is.

Color system

Modes

ColorModeTrueColor emits 38;2;R;G;B sequences; ColorMode256 emits 38;5;N after mapping; ColorMode16 emits 30-37/90-97 and 40-47/100-107, an RGB or palette color mapped to the nearest ANSI index; ColorModeNone emits attributes only, so a highlight drawn as a background color alone (a list's CursorBg) does not show; the tui form controls mark every selection with a glyph.

DetectColorMode() reports what the terminal can show from the environment (COLORTERM, TERM): 16 colors on a text console (TERM of linux, cons25*, vt and a digit, ansi or *-16color), whatever COLORTERM says. In 16 colors every color change restates the style from a reset, since a console's bright colors (90-97) also set bold. New() also honours NO_COLOR, choosing ColorModeNone; a mode passed to New overrides both, as a --color=always or never would. Init refuses TERM=dumb, which cannot address the cursor.

Init and Sync clear the screen to the terminal's own background. EmergencyReset(os.Stdout) writes to the controlling terminal when stdout is redirected, so the reset never lands in the program's output.

RGB → 256 mapping

RGBTo256 maps any RGB to the nearest xterm-256 index using perceptually weighted Redmean distance. The full mapping is pre-computed at init into a 6-bit-quantized LUT (256KB, L2-resident), making per-cell conversion a single array load. Applications targeting 256-color terminals can render in RGB throughout; degradation is automatic.

Palette helpers: Cube256(r,g,b) / CubeRGB256(idx) for 6×6×6 cube math, Gray256(step) for the grayscale ramp, plus named constants (P256Amber, P256SteelBlue, ...) and named true color values (Amber, Gunmetal, Obsidian, ...), all in github.com/lixenwraith/color.

Blending

github.com/lixenwraith/color provides compositing primitives operating on RGB. All take destination first and are branch-free in the hot path or LUT-backed; suitable for per-cell use at frame rate.

• Blend(dst, src, alpha): linear interpolation, standard transparency
• Add(dst, src, alpha): saturating add, bright accumulation, clips
• Screen(dst, src, alpha): 1-(1-d)(1-s), lightens, never clips
• Overlay(dst, src, alpha): multiply/screen split at 0.5, contrast, keeps dst structure
• SoftLight(dst, src, intensity): Perez soft light, gentle tint/glow
• Max(dst, src, alpha): per-channel max, non-additive highlight
• Scale(c, factor): channel multiply, dim/brighten
• Grayscale(c): Rec. 601 luma, desaturation
• c.Lerp(other, t): method on RGB, gradients, animation

alpha/intensity/t are [0,1]; out-of-range values clamp. alpha of 0 or 1 short-circuits without float math. All float→channel conversions round half-up, so gradients from Blend, Scale, Lerp, and SoftLight are bit-consistent.

bg := color.Gunmetal
glow := color.RGB{R: 255, G: 160, B: 40}

cell.Bg = color.Screen(bg, color.Scale(glow, pulse), 1.0) // pulsing glow
cell.Bg = color.Blend(cell.Bg, color.Black, 0.6)          // dim overlay backdrop
cell.Fg = color.SoftLight(cell.Fg, tint, 0.4)                // subtle recolor
bar := cold.Lerp(hot, load)                                     // value-mapped gradient

Integer paths (Add, Screen, Overlay) use a (x + (x>>8) + 1) >> 8 division approximation; SoftLight uses init-time LUTs replacing math.Sqrt.

Input

PollEvent() blocks on a unified channel. Event.Type values:

• EventKey — Key for named keys (KeyEnter, KeyUp, KeyCtrlC, ...), Key == KeyRune with Rune set for printable input, Modifiers bitmask (ModShift, ModAlt, ModCtrl), Action (KeyPress, and KeyRepeat and KeyRelease while releases are reported; see below)
• EventMouse — 0-indexed MouseX/Y, MouseBtn (buttons, wheel), MouseAction (press/release/move/drag), modifiers. Enable via SetMouseMode(MouseModeClick | MouseModeDrag); SGR protocol only.
• EventResize — new Width/Height
• EventPaste — Text holds a whole paste, as sent, control characters included. Enable via SetPasteMode(true) (bracketed paste); off, a paste arrives as keys, its newlines pressing Enter.
• EventKeyReport — the outcome of a SetKeyReport ask: Report and Source
• EventFocus — Focused, while releases come through the terminal's protocol
• EventError, EventClosed

A standalone ESC press is disambiguated from escape sequences by a short input-idle timeout (one ~10ms poll cycle). ESC ESC is Alt+Escape alone, Escape before a paste, and Alt with the key that follows otherwise (rxvt's Alt+arrows). Partial UTF-8 and escape sequences at read boundaries are reassembled in a persistent buffer. With paste mode off, a paste marker is not a paste. A paste whose end marker never arrives ends once input pauses for a second, so what follows a paste that stalls that long arrives as keys.

On Unix, a redirected stdin or stdout is replaced by /dev/tty, so app > out.toml and cmd | app keep both as data while the application draws and reads keys on the terminal. PostEvent injects synthetic events (used for clean shutdown of blocked PollEvent).

Key releases

A terminal reports presses: a key held down arrives as more presses at the keyboard's repeat rate, and nothing says when it comes up. A game that needs holds asks for releases:

term.SetKeyReport(terminal.KeyReportReleases, terminal.KeySourceConsole|terminal.KeySourceProtocol)

The ask returns at once. An EventKeyReport follows with what the terminal reports now (Report) and where releases come from (Source), so a game learns the outcome of every ask and can fall back, to taps for one, where there are none. SetKeyReport(terminal.KeyReportPresses, 0) gives the source back. Until a game asks for releases, nothing is sent to the terminal or switched, and every key event is a press, as before.

While releases are reported:

• Each key event carries its Action: KeyPress, KeyRepeat while held, and KeyRelease. A release carries what its press carried, paired by physical key, so letting go of Shift first still releases 'A', not 'a'.
• A key event the terminal names no physical key for (text from an input method, a key its protocol leaves out) can't be held: its release follows at once.
• Every hold ends. Focus leaving, the console switching away, a change of source and Fini release the keys held with Lost set, since their own releases won't arrive. A press of a key already held means its release was lost (a terminal's own mode can swallow one): the old hold ends, Lost, before the new press.

Releases come from the first of these sources a game allows that the terminal has:

• KeySourceConsole: the kernel console's own keyboard, on the console the game runs on: a Linux VT (/dev/ttyN) or FreeBSD's vt(4) (/dev/ttyvN). While releases are reported the package switches the keyboard to raw keycodes, which the kernel allows without root (Linux's K_MEDIUMRAW on the game's controlling tty, FreeBSD's K_CODE on a console the game has open), and switches it back when the game goes back to presses, at Fini and in EmergencyReset. Each key types what the console types for it cooked, by the console's own keymap read at the switch. Switching to another console ends the holds. The console's mouse reports pause while the keyboard is raw, and a mouse paste then reads as keys. Never over ssh, where the keyboard is the far terminal's.

  On Linux that is loadkeys layouts, dead keys and compose, the locks and their lights, Alt+Fn and Alt+arrows switching consoles, and cursor keys with modifiers from Linux 7.1. Left out while raw: codes typed with Alt on the keypad, braille, Ctrl+Alt+Del, and Scroll Lock, which only lets stopped output go on.

  On FreeBSD it is kbdmap layouts and their accents, the locks and their lights, Alt+Fn and Print Screen switching consoles, codes typed with left Alt on the keypad, and Alt as ESC before a character (right Alt too with kern.vt.enable_altgr=0). Left out while raw: the machine's keys (Ctrl+Alt+Del, the debugger, suspend), Shift+Insert's paste, and Scroll Lock. With Scroll Lock on, the console's history mode takes every key, so the keyboard stays as it is and the ask reports presses; an ask after Scroll Lock goes off tries again. syscons (kern.vty=sc) has no console source.

  Before the first switch the package runs the game's binary again as console-guard, which switches the keyboard back, restores the tty and shows the cursor if the game dies where nothing of its own runs: kill -9, the OOM killer, a Go fatal error. A game leading its console's session (on Linux, run with exec from the login shell or by an autologin) takes the console with it as it dies; the guard then opens it again to restore it. The package's init turns the guard's run aside before main; the inits of packages initialized before it run in the guard too, so keep side effects out of them. On FreeBSD the guard goes by the game's name, so pkill -9 by that name ends it too: kill the game by its PID. Should the guard be killed as well, switch the keyboard back from elsewhere: on Linux sudo kbd_mode -u -C /dev/ttyN; FreeBSD has no command for it, so build one:

  printf '#include <sys/ioctl.h>\n#include <sys/kbio.h>\nint main(void) { return ioctl(0, KDSKBMODE, K_XLATE); }\n' |
      cc -x c -o /tmp/kbdxlate - && /tmp/kbdxlate < /dev/ttyvN
  

• KeySourceProtocol: the terminal's key event protocol, CSI u with event types. The package asks the terminal whether it has the protocol (CSI ? u, fenced by a DA1 request every terminal answers), pushes its flags and confirms what they came to before reporting releases; it goes by the terminal's answers, never by TERM or the terminal's name. Alacritty 0.13 and later is the reference (Enter, Tab and Backspace release from 0.15). Other terminals that answer the same way (foot, Ghostty, WezTerm with its opt-in setting, recent Konsole) should work but are untested. Works over ssh. tmux, screen and mosh don't pass the protocol through, and VTE terminals and xterm don't have it; there the answer is presses after one round trip. The flags are popped when the game goes back to presses, at Fini, and in EmergencyReset.

  With the protocol on, every key arrives as an escape code, and each press reads as the key a legacy terminal sends for it reads, so a game can keep the protocol on for its whole run: Shift goes into the character, Ctrl with a character becomes its control key, and Alt stays a modifier. Ctrl with a character that has no control key (Ctrl+1) keeps ModCtrl, which a legacy terminal can't send. Escape no longer waits out the ESC timeout. Lone modifier keys, media keys and F13 and up report nothing. Alacritty reports no keys while its own Vi mode, search or hints run; a key held then ends on its next press, or as focus leaves.

KeyHolds is the pairing on its own, for a host that reads its platform's key events and builds Events itself (KeySourceHost): it gives each release its press's key and turns the contradictions above into Lost releases.

A Terminal over a caller's backend (NewWithBackend) reports presses.

WASM

WASM builds bridge to xterm.js via JS globals:

goTerminalWrite(Uint8Array)    // Go → JS terminal output
goTerminalInput(Uint8Array)    // JS → Go keyboard input
goTerminalResize(cols, rows)   // JS → Go resize
xterm.cols, xterm.rows         // initial size query

Sub-packages

• tui — immediate-mode widget toolkit (regions, layout, widgets, scroll/editor state) built on the cell buffer model.