charm-ultraviolet

# Ultraviolet (charmbracelet/ultraviolet)

## What Is Ultraviolet (and When NOT to Use It)

Ultraviolet is a set of low-level primitives for terminal manipulation in Go. It provides cell-based rendering, unified input handling, and screen management. It powers Bubble Tea v2 and Lip Gloss v2 internally.

**This is NOT a framework.** It is infrastructure. Think of it like syscalls vs stdlib - you can use it directly, but most of the time you should not.

### When NOT to use it

- Building a standard TUI app - use Bubble Tea v2 instead
- Styling terminal output - use Lip Gloss v2 instead
- You want an architecture/framework with state management - use Bubble Tea v2
- Prototyping - too low-level, too much boilerplate

### When to use it directly

- Building your own TUI framework on top of these primitives
- Writing a custom renderer that needs cell-level control
- Performance-critical rendering where you need direct buffer manipulation
- Embedding terminal rendering into a non-Bubble Tea application
- Working on Bubble Tea / Lip Gloss internals

## API Stability Warning

The project README explicitly states: "This project currently exists to serve internal use cases. API stability is a goal, but expect no stability guarantees as of now." Plan accordingly.

## Core Abstractions

The library lives in a single flat Go package `uv` (import path: `github.com/charmbracelet/ultraviolet`), with helper sub-packages `screen/` and `layout/`.

### Cell

The fundamental unit. One terminal cell = one grapheme cluster.

```go
type Cell struct {
    Content string    // single grapheme cluster
    Style   Style     // fg, bg, attrs (bold, italic, etc.)
    Link    Link      // OSC 8 hyperlink
    Width   int       // columns occupied (1 for normal, 2 for wide chars like CJK)
}
```

Key constants/values:
- `EmptyCell` - a cell with `" "`, width 1, no style
- Zero-width cells (`Width == 0`) are placeholders for wide characters

### Buffer

A 2D grid of cells, organized as `Lines []Line` where `Line []Cell`.

```go
buf := uv.NewBuffer(80, 24)        // width, height
buf.SetCell(x, y, &cell)           // write a cell
cell := buf.CellAt(x, y)          // read a cell (nil if out of bounds)
buf.Resize(newW, newH)             // resize, preserving content
buf.Clear()                        // fill with EmptyCell
buf.Fill(&cell)                    // fill with custom cell
buf.FillArea(&cell, area)          // fill rectangular region
clone := buf.Clone()               // deep copy
```

Buffer implements `Drawable`, so you can `buf.Draw(screen, area)` to composite buffers onto screens.

### RenderBuffer

Wraps Buffer with change tracking. Only touched lines/cells get re-rendered.

```go
rbuf := uv.NewRenderBuffer(80, 24)
rbuf.SetCell(x, y, &cell)         // auto-marks line as touched
rbuf.TouchLine(x, y, n)           // manually mark region dirty
rbuf.TouchedLines()               // count of dirty lines
```

### Screen (Interface)

The core abstraction that anything drawable targets.

```go
type Screen interface {
    Bounds() Rectangle
    CellAt(x, y int) *Cell
    SetCell(x, y int, c *Cell)
    WidthMethod() WidthMethod
}
```

Implemented by: `Buffer`, `ScreenBuffer`, `Window`, `TerminalScreen`.

### Drawable (Interface)

Anything that can render itself onto a Screen.

```go
type Drawable interface {
    Draw(scr Screen, area Rectangle)
}
```

Implemented by: `Buffer`, `Window`, `StyledString`, and your own components.

### Window

A rectangular area that can own its own buffer or share a parent's buffer (view).

```go
// Root window (owns its buffer)
root := uv.NewScreen(80, 24)

// Child window with own buffer
child := root.NewWindow(x, y, width, height)

// View into parent buffer (shared memory)
view := root.NewView(x, y, width, height)
```

Windows support `MoveTo`, `MoveBy`, `Resize`, `Clone`.

### Terminal

The main entry point for standalone UV apps. Manages console I/O, raw mode, event loop.

```go
t := uv.DefaultTerminal()
// or: t := uv.NewTerminal(console, opts)

t.Start()          // enter raw mode, start event loop
defer t.Stop()     // restore terminal, clean up

scr := t.Screen()  // returns *TerminalScreen

for ev := range t.Events() {
    switch ev := ev.(type) {
    case uv.WindowSizeEvent:
        scr.Resize(ev.Width, ev.Height)
    case uv.KeyPressEvent:
        if ev.MatchString("ctrl+c") { return }
    }
}
```

### TerminalScreen

The concrete screen for terminal output. Manages alt screen, cursor, colors, mouse mode, keyboard enhancements, synchronized updates.

```go
scr := t.Screen()

// Screen modes
scr.EnterAltScreen()    // alternate screen buffer
scr.ExitAltScreen()

// Rendering cycle
scr.SetCell(x, y, &cell)
scr.Render()            // diff current vs previous state
scr.Flush()             // write changes to terminal

// Or use Display for Drawable components
scr.Display(myDrawable) // clear + draw + render + flush

// Terminal features
scr.ShowCursor()
scr.SetCursorPosition(x, y)
scr.SetMouseMode(uv.MouseModeClick)
scr.SetBackgroundColor(color)
scr.SetWindowTitle("My App")
scr.SetSynchronizedUpdates(true)  // mode 2026
scr.SetKeyboardEnhancements(enh)  // kitty protocol

// Inline mode helper
scr.InsertAbove(content)  // insert text above without disrupting screen
```

### StyledString

Converts ANSI-styled strings into cell-based representation. Implements Drawable.

```go
ss := uv.NewStyledString("Hello \x1b[1mWorld\x1b[0m")
ss.Draw(screen, area)
```

## Sub-Packages

### screen/ - Screen Helpers

Utility functions that work with any `Screen` implementation.

```go
import "github.com/charmbracelet/ultraviolet/screen"

screen.Clear(scr)                    // clear entire screen
screen.ClearArea(scr, area)          // clear region
screen.Fill(scr, &cell)              // fill screen
screen.FillArea(scr, &cell, area)    // fill region
screen.Clone(scr)                    // deep copy to Buffer
screen.CloneArea(scr, area)          // deep copy region

// Drawing context with stateful style
ctx := screen.NewContext(scr)
ctx.SetForeground(ansi.Red)
ctx.SetBold(true)
ctx.DrawString("hello", x, y)
ctx.Printf("count: %d", n)          // implements io.Writer
```

### layout/ - Constraint-Based Layout

Cassowary-based layout solver (ported from Ratatui). Splits areas into non-overlapping rectangles.

```go
import "github.com/charmbracelet/ultraviolet/layout"

// Split area vertically into 3 parts
chunks := layout.New().
    Direction(layout.Vertical).
    Constraints(
        layout.Len(3),       // fixed 3 rows
        layout.Fill(1),      // fill remaining
        layout.Len(1),       // fixed 1 row
    ).
    Split(area)
```

Constraint types: `Len`, `Ratio`, `Percent`, `Fill`, `Min`, `Max`.

## Events

Events come from `t.Events()` channel. Key types:

| Event | Description |
|---|---|
| `WindowSizeEvent` | Terminal resized (width, height in cells) |
| `PixelSizeEvent` | Terminal resized (width, height in pixels) |
| `KeyPressEvent` | Key pressed. Use `ev.MatchString("ctrl+c", "q")` |
| `KeyReleaseEvent` | Key released (requires kitty keyboard protocol) |
| `MouseClickEvent` | Mouse click with position and button |
| `MouseMotionEvent` | Mouse moved (requires mouse mode enabled) |
| `PasteEvent` | Bracketed paste content |

Key matching uses human-readable strings: `"ctrl+a"`, `"shift+enter"`, `"alt+tab"`, `"f1"`, `"space"`.

## Geometry

Uses `image.Point` and `image.Rectangle` from stdlib:

```go
pos := uv.Pos(x, y)                    // == image.Point{X: x, Y: y}
rect := uv.Rect(x, y, width, height)   // origin + size (NOT min/max)
```

Note: `uv.Rect(x, y, w, h)` takes width/height, not max coordinates. This differs from `image.Rect(x0, y0, x1, y1)`.

## Style System

Styles are value types with bitfield attributes:

```go
style := uv.Style{
    Fg:             ansi.Red,
    Bg:             ansi.Black,
    UnderlineColor: ansi.Blue,
    Underline:      uv.UnderlineCurly,
    Attrs:          uv.AttrBold | uv.AttrItalic,
}
```

Attributes: `AttrBold`, `AttrFaint`, `AttrItalic`, `AttrBlink`, `AttrReverse`, `AttrConceal`, `AttrStrikethrough`.

Underline styles: `UnderlineNone`, `UnderlineSingle`, `UnderlineDouble`, `UnderlineCurly`, `UnderlineDotted`, `UnderlineDashed`.

Style diffing is built in - the renderer computes minimal ANSI sequences to transition between styles.

## Rendering Pipeline

The "Cursed Renderer" is a cell-based diffing engine inspired by ncurses:

1. You write cells to the screen buffer via `SetCell`
2. `Render()` diffs current buffer against previous state
3. Renderer emits minimal ANSI escape sequences (cursor movement, style changes, text)
4. `Flush()` writes the accumulated output to the terminal

Optimizations include:
- Only touched lines are re-rendered
- Style diffs minimize SGR sequence length
- Cursor movement uses shortest path (absolute, relative, tabs, backspace)
- Supports synchronized updates (mode 2026) to prevent flicker
- Hash-based scroll detection for efficient content shifts

## Minimal Hello World

```go
package main

import (
    "log"
    uv "github.com/charmbracelet/ultraviolet"
    "github.com/charmbracelet/ultraviolet/screen"
)

func main() {
    t := uv.DefaultTerminal()
    scr := t.Screen()
    scr.EnterAltScreen()

    if err := t.Start(); err != nil {
        log.Fatal(err)
    }
    defer t.Stop()

    ctx := screen.NewContext(scr)

    for ev := range t.Events() {
        switch ev := ev.(type) {
        case uv.WindowSizeEvent:
            scr.Resize(ev.Width, ev.Height)
        case uv.KeyPressEvent:
            if ev.MatchString("q", "ctrl+c") {
                return
            }
        }

        screen.Clear(scr)
        ctx.DrawString("Hello, World!", 0, 0)
        scr.Render()
        scr.Flush()
    }
}
```

## Relationship to Bubble Tea v2

```
ultraviolet (primitives)
    |
    +-- Lip Gloss v2 (styling, composition)
    |
    +-- Bubble Tea v2 (framework: Elm architecture, state management, commands)
            |
            +-- Bubbles (components: text input, list, table, etc.)
```

- Ultraviolet provides: cells, buffers, screen management, input decoding, rendering
- Bubble Tea v2 provides: `Program`, `Model`, `Update`, `View`, commands, subscriptions
- Lip Gloss v2 provides: `Style`, layout, borders, padding, composition

If you are building a TUI application, start with Bubble Tea v2. Only reach for ultraviolet when Bubble Tea's abstractions get in your way.

## Checklist

Before using ultraviolet directly, confirm:

- [ ] Bubble Tea v2 genuinely cannot solve your problem
- [ ] You need cell-level rendering control
- [ ] You accept API instability risk
- [ ] You understand the rendering pipeline (SetCell -> Render -> Flush)
- [ ] You handle WindowSizeEvent and call Resize yourself
- [ ] You manage terminal raw mode and cleanup (Start/Stop)
- [ ] You have read the examples in the `examples/` directory