uv library Ultraviolet

Ultraviolet (UV): High-performance terminal rendering and input.

The UV subsystem provides core rendering primitives, a diffing terminal renderer, structured cell buffers, and fast input decoders to build responsive, visually rich terminal UIs.

Key Components

Terminal: Lifecycle, I/O, and orchestration for UV apps.
Buffer: A 2D grid of Cells representing screen state.
Cell: A single glyph with UvStyle and optional Link.
UvTerminalRenderer: Efficient diff-based rendering to the terminal.
EventDecoder: Fast ANSI/kitty input decoder for keys and mouse.
Screen: High-level convenient API over buffers and rendering.
Canvas: Immediate-mode drawing utilities on top of buffers.

Quick Start

import 'package:artisanal/uv.dart';

void main() async {
  final terminal = Terminal();
  await terminal.start();

  // Draw a red "H" at (0, 0).
  terminal.setCell(0, 0, Cell(
    content: 'H',
    style: UvStyle(fg: UvColor.rgb(255, 0, 0)),
  ));

  terminal.draw();
  await terminal.stop();
}

Concepts

UV models the terminal as layers of drawable cells. A Buffer holds the current state, a UvTerminalRenderer diffs and flushes changes, and Terminal manages lifecycle and device capabilities. Use Canvas for immediate-mode drawing, or Screen for a higher-level facade.

A Cell contains a glyph and UvStyle (foreground/background, effects).
StyledString enables styled runs with state readers like readStyle.
Layer and Compositor support stacking and hit-testing (LayerHit).
Rectangle and Position describe geometry; see rect helper.

Rendering

The UvTerminalRenderer computes minimal diffs between the previous and next Buffer frames and emits optimized ANSI/OSC sequences to the terminal. Combine it with TerminalCapabilities to adapt to device features (kitty, sixel, hyperlinks, etc.). For text drawing, prefer StyledString and the style ops to avoid per-cell overhead.

Example (pseudo-flow):

final screen = Screen(size: Rectangle(0, 0, 80, 24));
final renderer = UvTerminalRenderer();
// mutate screen/buffers
renderer.render(screen.buffer);

Input and Events

Input is decoded by EventDecoder into typed events:

KeyEvent, KeyPressEvent for keyboard input.
MouseEvent, MouseClickEvent, MouseMotionEvent for mouse input.
WindowSizeEvent, FocusEvent, PasteEvent for terminal state.
KittyGraphicsEvent, PrimaryDeviceAttributesEvent for device features.

Access mouse modes via MouseMode and buttons via MouseButton.

Performance Tips

Batch mutations on buffers to reduce diff churn.
Prefer region updates; avoid full-screen rewrites.
Use StyledString runs instead of per-cell style objects when possible.
Cache geometry and avoid repeated allocations in hot paths.
Detect capabilities once; gate feature use via TerminalCapabilities.

Compatibility

UV targets modern terminals with ANSI + extended capabilities (kitty/sixel). Behavior can vary across emulators; query TerminalCapabilities and gracefully degrade. Hyperlinks (Link, LinkState) and RGB (UvRgb) may be unavailable on legacy terminals; fall back to UvBasic16 or UvIndexed256 palettes.

A Cell contains a glyph and UvStyle (foreground/background, effects).
StyledString enables styled runs with state readers like readStyle.
Layer and Compositor support stacking and hit-testing (LayerHit).
Rectangle and Position describe geometry; see rect helper.

Example (pseudo-flow):

final screen = Screen(size: Rectangle(0, 0, 80, 24));
final renderer = UvTerminalRenderer();
// mutate screen/buffers
renderer.render(screen.buffer);

Input is decoded by EventDecoder into typed events:

KeyEvent, KeyPressEvent for keyboard input.
MouseEvent, MouseClickEvent, MouseMotionEvent for mouse input.
WindowSizeEvent, FocusEvent, PasteEvent for terminal state.
KittyGraphicsEvent, PrimaryDeviceAttributesEvent for device features.

Access mouse modes via MouseMode and buttons via MouseButton.

Batch mutations on buffers to reduce diff churn.
Prefer region updates; avoid full-screen rewrites.
Use StyledString runs instead of per-cell style objects when possible.
Cache geometry and avoid repeated allocations in hot paths.
Detect capabilities once; gate feature use via TerminalCapabilities.

Classes

Attr: Text attributes (bitmask).
BackgroundColorEvent: Background color report.
BlurEvent: Terminal focus lost event.
Buffer: A 2D buffer of Lines representing a terminal screen or a portion of it.
BufferFilter: Base class for buffer filters.
BufferRenderSink: A render sink that owns double-buffered render targets.
Canvas: Canvas is a cell-buffer that can be used to compose and draw Drawables.
CapabilityEvent: Capability string event (e.g., terminal features).
Cell: A single cell in a terminal Buffer.
CellSizeEvent: Reports terminal cell size in pixels.
ClearableScreen: Optional fast-path: clear the entire screen.
ClearAreaScreen: Optional fast-path: clear an area of the screen.
ClipboardEvent: Clipboard selection and content (OSC 52).
ClipboardSelection
CloneableScreen: Optional fast-path: clone the entire screen into a buffer.
CloneAreaScreen: Optional fast-path: clone a screen area into a buffer.
ColorPaletteEvent: Palette color report for an index.
Compositor: Compositor manages layer composition, drawing and hit testing.
Constraint: Layout constraints.
Cursor: Represents a cursor on the terminal screen.
CursorColorEvent: Cursor color report.
CursorPositionEvent: Reports cursor position.
DarkColorSchemeEvent: Terminal reports dark color scheme preference.
Drawable: Drawable can draw itself into a Screen.
EmptyDrawable: A no-op drawable with a fixed size.
Event: Base type for UV-style input events.
EventDecoder: A high-performance ANSI input decoder.
FillableScreen: Optional fast-path: fill the entire screen.
FillAreaScreen: Optional fast-path: fill an area of the screen.
Fixed: A constraint that represents a fixed size.
FocusEvent: Terminal focus gained event.
ForegroundColorEvent: Foreground color report.
HalfBlockImageDrawable: A Drawable that renders an image using half-block characters.
IgnoredEvent: Internal marker for sequences intentionally ignored.
ITerm2ImageDrawable: A Drawable that renders an image using the iTerm2 Image Protocol.
KeyboardEnhancementsEvent: Kitty keyboard enhancements support report.
KeyEvent: Base type for key press/release events.
KeyPressEvent: Key press event.
KeyReleaseEvent: Key release event.
KittyGraphicsEvent: Kitty graphics payload (APC G ... ST).
KittyImageDrawable: A Drawable that renders an image using the Kitty Graphics Protocol.
KittyOptions: Options parsed from a Kitty graphics report.
Layer: Layer represents a visual layer with content and positioning.
LayerHit
LegacyKeyEncoding: Legacy key encoding behavior flags.
LightColorSchemeEvent: Terminal reports light color scheme preference.
Line: A line is a fixed-width list of cells.
LineData: Metadata for a touched line.
Link: Upstream: third_party/ultraviolet/cell.go (Link). Terminal hyperlink metadata (OSC 8).
LinkState: Holds the parsed hyperlink URL from an OSC 8 sequence.
LiquifyFilter: A simple velocity-field liquify filter.
ModeReportEvent: Terminal mode report.
ModifyOtherKeysEvent: Xterm ModifyOtherKeys mode report.
Mouse: Mouse event payload.
MouseButton: Mouse button codes (X11-style).
MouseClickEvent: Mouse click event.
MouseEvent: Base type for mouse click/release/wheel/motion events.
MouseMotionEvent: Mouse motion (move/drag) event.
MouseReleaseEvent: Mouse button release event.
MouseWheelEvent: Mouse wheel (scroll) event.
MultiEvent: Aggregates multiple events decoded from a single input.
PasteEndEvent: Bracketed paste end.
PasteEvent: Bracketed paste content.
PasteStartEvent: Bracketed paste start.
Percent: A constraint that represents a percentage of the available size.
Position: Upstream: third_party/ultraviolet/buffer.go (Position, Rectangle). A 2D integer coordinate in terminal cell space.
PrimaryDeviceAttributesEvent: Primary device attributes (DA1) report.
Rectangle: Rectangle with inclusive-exclusive bounds: [min, max).
RenderMetrics: Tracks render performance metrics including FPS, frame times, and render durations.
Screen: Screen is a 2D surface of cells.
ScreenBuffer: A screen buffer that implements Screen operations and carries a width method for calculating cell widths.
SecondaryDeviceAttributesEvent: Secondary device attributes (DA2) report.
SgrParam: Represents a parsed SGR (Select Graphic Rendition) parameter.
Side: UvBorder primitives.
SixelImageDrawable: A Drawable that renders an image using Sixel Graphics.
Size: Reports terminal size in cells and optional pixels.
StyledString: StyledString is a string that can be decomposed into a series of styled lines and cells.
StyleState: Holds the result of parsing an SGR sequence.
Terminal: Terminal represents a terminal screen that can be manipulated and drawn to.
TerminalCapabilities: Terminal capabilities discovered via ANSI queries.
TerminalVersionEvent: Terminal version string (e.g., xterm-kitty 0.32.0).
TertiaryDeviceAttributesEvent: Tertiary device attributes (DA3) report.
UnknownApcEvent: Unknown APC event with raw payload.
UnknownCsiEvent: Unknown CSI event with raw payload.
UnknownDcsEvent: Unknown DCS event with raw payload.
UnknownEvent: Unknown event with raw payload.
UnknownOscEvent: Unknown OSC event with raw payload.
UnknownPmEvent: Unknown PM event with raw payload.
UnknownSosEvent: Unknown SOS event with raw payload.
UnknownSs3Event: Unknown SS3 event with raw payload.
UvBasic16: 16-color palette index (optionally bright).
UvBorder: A drawable border composed of Sides and corner glyphs.
UvColor: Color representation sufficient for Ultraviolet parity tests.
UvIndexed256: 256-color indexed palette entry.
UvRgb: 24-bit RGBA color.
UvStyle: Upstream: third_party/ultraviolet/cell.go (UvStyle). Style attributes for a terminal Cell.
UvTerminalRenderer: Low-level terminal renderer for the Ultraviolet engine.
WindowOpEvent: Window operation report (OSC 7/11/… payloads).
WindowPixelSizeEvent: Reports window size in pixels.
WindowSizeEvent: Reports window size in cells and optional pixels.

Enums

CursorShape: Cursor shape primitives.
ModeSetting
MouseMode: Mouse mode.
UnderlineStyle: Underline style for terminal cells.
WidthMethod: Specifies the method used to calculate character display width.

Extensions

CursorShapeEncode on CursorShape
WidthMethodX on WidthMethod: Extension on WidthMethod providing string width calculation.

Properties

emojiPresentationWidth ↔ int: Runtime configuration for width calculations that depend on terminal behavior.
getter/setter pair

Functions

asciiBorder() → UvBorder: Creates a plain ASCII border style.
blockBorder() → UvBorder: Creates a solid block border style.
bottomCenterRect(Rectangle area, int width, int height) → Rectangle: Returns a new Rectangle at the bottom-center of area with width and height.
bottomLeftRect(Rectangle area, int width, int height) → Rectangle: Returns a new Rectangle at the bottom-left of area with width and height.
bottomRightRect(Rectangle area, int width, int height) → Rectangle: Returns a new Rectangle at the bottom-right of area with width and height.
centerRect(Rectangle area, int width, int height) → Rectangle: Returns a new Rectangle centered within area with width and height.
doubleBorder() → UvBorder: Creates a double line border style.
hiddenBorder() → UvBorder: Creates an invisible border style (spaces for all sides).
innerHalfBlockBorder() → UvBorder: Creates an inner half-block border style.
leftCenterRect(Rectangle area, int width, int height) → Rectangle: Returns a new Rectangle at the left-center of area with width and height.
markdownBorder() → UvBorder: Creates a markdown-style border using | for verticals.
maxLineWidth(String s) → int: Returns the maximum display width across all lines in s.
newLayer(Object content, [List<Layer> layers = const []]) → Layer: Creates a new Layer from a String or Drawable.
newStyledString(String str) → StyledString: Factory function to create a StyledString from str.
normalBorder() → UvBorder
outerHalfBlockBorder() → UvBorder: Creates an outer half-block border style.
ratio(int numerator, int denominator) → Percent: Syntactic sugar for Percent.
readLink(String data, LinkState out) → void: Parses an OSC 8 hyperlink sequence from data into out.
readStyle(List<SgrParam> params, StyleState out) → void: Parses SGR params and applies them to the style in out.
rect(int x, int y, int width, int height) → Rectangle: Creates a rectangle from origin (x, y) and size (width, height).
rightCenterRect(Rectangle area, int width, int height) → Rectangle: Returns a new Rectangle at the right-center of area with width and height.
roundedBorder() → UvBorder: Creates a rounded border style.
runeWidth(int rune) → int: Returns the display width of a single Unicode code point.
setEmojiPresentationWidth(int width) → void: Sets the display width used for emoji presentation characters.
splitHorizontal(Rectangle area, Constraint c) → ({Rectangle left, Rectangle right}): Splits area horizontally into left/right.
splitVertical(Rectangle area, Constraint c) → ({Rectangle bottom, Rectangle top}): Splits area vertically into top/bottom.
stringWidth(String s) → int: Returns the terminal display width of s, counting per grapheme cluster.
styledStringBounds(String text, WidthMethod method) → Rectangle: Parses a string and returns its bounds (width/height) using a width method.
thickBorder() → UvBorder: Creates a thick line border style.
topCenterRect(Rectangle area, int width, int height) → Rectangle: Returns a new Rectangle at the top-center of area with width and height.
topLeftRect(Rectangle area, int width, int height) → Rectangle: Returns a new Rectangle at the top-left of area with width and height.
topRightRect(Rectangle area, int width, int height) → Rectangle: Returns a new Rectangle at the top-right of area with width and height.