Ultraviolet

Once the environment is set up, you can run the standard test suite or perform targeted fuzzing to find new failing inputs. Use the -fuzz flag to run a specific target for a set duration.

# Run the fuzz targets over their seed corpus, plus the regular tests
go test ./...

# Search for new failing inputs for a specific target (e.g., FuzzRenderer)
go test -run='XXX' -fuzz='FuzzRenderer$' -fuzztime=5m

To begin the application lifecycle, call t.Start(). This performs several critical actions:

• Puts the console into raw mode (disabling echoing and line buffering).
• Initializes the input event loop.
• Prepares the screen for rendering.

Always use defer t.Stop() to ensure the terminal is cleaned up properly. Stop() restores the console, exits the alternate screen, and is safe to call multiple times.

if err := t.Start(); err != nil {
    log.Fatalf("failed to start terminal: %v", err)
}
defer t.Stop()

The conformance module contains fuzz tests that validate the terminal renderer by comparing its output against a real terminal emulator (using libghostty). These tests ensure that the renderer's internal model of the screen stays in sync with what is actually displayed.

Note: These tests are in a separate module to avoid forcing cgo and specific Go version requirements on users of the main ultraviolet library. They must be run from within the internal/conformance directory, as they are excluded from the root module's test suite.

# 1. Build libghostty-vt using zig and CMake
git clone https://github.com/mitchellh/go-libghostty
cd go-libghostty && make build

# 2. Set the PKG_CONFIG_PATH
export PKG_CONFIG_PATH="$PWD/build/_deps/ghostty-src/zig-out/share/pkgconfig"

# 3. Run tests from the conformance directory
go test ./...

A Terminal is the central manager for the console, the input event loop, and the screen state.

You can initialize a terminal using the default configuration:

t := uv.DefaultTerminal()

Alternatively, you can create a custom terminal by providing a Console (which wraps os.Stdin, os.Stdout, and environment variables) and an Options struct:

con := uv.NewConsole(os.Stdin, os.Stdout, os.Environ())
t := uv.NewTerminal(con, &uv.Options{
    Logger: myLogger, // optional, for debugging I/O
})

To use Ultraviolet in your Go project, install it using go get:

go get github.com/charmbracelet/ultraviolet@latest

A Window represents a rectangular area on the screen. It can function as a root window (no parent) or a sub-window (with a parent).

Windows handle text data through a Buffer. A window can either own its own unique buffer or act as a 'view' that shares the buffer of its parent window.

import "github.com/charmbracelet/ultraviolet"

// Create a root window
root := uv.NewWindow(80, 24, nil)

// Create a sub-window that owns its own buffer
subWindow := root.NewWindow(10, 10, 20, 5)

// Create a view that shares the root's buffer
view := root.NewView(5, 5, 10, 10)

A RenderBuffer extends a standard Buffer by tracking which parts of the screen have changed (been "touched"). This allows for efficient rendering by only updating the modified portions of the screen rather than the entire buffer.

When you use RenderBuffer methods like SetCell, InsertLine, or FillArea, the buffer automatically marks the affected lines as "touched" using TouchLine. You can then query TouchedLines() to determine how much work is needed for the next render cycle.

// Create a render buffer for efficient updates
rb := uv.NewRenderBuffer(80, 24)

// Setting a cell automatically marks the line as touched
rb.SetCell(5, 5, &someCell)

// Check how many lines need re-rendering
if rb.TouchedLines() > 0 {
    // Perform optimized render logic
}

A StyledString is a string that can be decomposed into styled lines and cells. It is used to disassemble strings containing ANSI escape codes (including SGR and Hyperlink codes) into a series of cells that can be used within a [Buffer] or Screen.

Key features include:

• Wrapping: Control whether the string wraps to the next line.
• Truncation: If Wrap is false, you can specify a Tail string to be appended when the string is truncated to fit the available area.
• Decomposition: Convert the string into a slice of Line objects or draw it directly to a Screen.

// Create a new styled string
ss := uv.NewStyledString("\x1b[31mHello\x1b[0m World")

// Draw it to a screen at a specific area
ss.Draw(myScreen, myRectangle)

Use NewTerminalScreen to create a new TerminalScreen instance. It requires an io.Writer (typically os.Stdout) and an Environ object to handle environment variables. The constructor automatically detects the terminal's color profile and configures renderer optimizations like tab stops and backspace support based on the terminal state.

screen := uv.NewTerminalScreen(os.Stdout, env)