Ultraviolet

ultraviolet is a high-performance terminal rendering/runtime package for Dart. It provides the low-level primitives you need to build interactive terminal applications: screen buffers, styled cells, diff-based rendering, typed input events, and terminal capability handling.

Features

• Cell/buffer-based rendering model
• High-performance diff renderer (UvTerminalRenderer)
• Typed keyboard/mouse/focus/resize events
• Style + color primitives (UvStyle, UvColor)
• Per-cell diff policies (normal, skip, alwaysUpdate, forcedWidth)
• ANSI helpers (Ansi) and renderer-level ANSI sequences (UvAnsi)
• Terminal capability detection
• Image protocol support (Kitty, iTerm2, Sixel, fallback drawables)

Installation

From pub.dev:

dart pub add ultraviolet

Workspace usage:

dependencies:
  ultraviolet:

Git dependency usage:

dependencies:
  ultraviolet:
    git:
      url: https://github.com/kingwill101/artisanal.git
      path: pkgs/ultraviolet

Quick Start

import 'package:ultraviolet/ultraviolet.dart';

Future<void> main() async {
  final terminal = Terminal();
  await terminal.start();
  try {
    terminal.enterAltScreen();
    terminal.hideCursor();

    terminal.setCell(2, 1, Cell(content: 'U'));
    terminal.setCell(3, 1, Cell(content: 'V'));
    terminal.draw();

    await for (final event in terminal.events) {
      if (event is KeyEvent && event.matchString('q', 'esc', 'ctrl+c')) {
        break;
      }
    }
  } finally {
    terminal.showCursor();
    terminal.exitAltScreen();
    await terminal.stop();
  }
}

Demo Captures

Every example in pkgs/ultraviolet/example/ has a VHS recording regenerated from the tapes in pkgs/ultraviolet/example/.vhs/:

task uv-demos   # compiles each example, then records all GIFs into assets/

3D & raytracing

Raycast maze (example/raycast_maze.dart):

SDF raymarcher (example/sdf_raymarcher.dart):

Path tracer (example/path_tracer.dart):

Simulations

Conway's Game of Life (example/conway_life.dart):

Metaballs / marching squares (example/metaballs_marching_squares.dart):

Boids swarm (example/boids_swarm.dart):

N-body gravity (example/nbody_gravity.dart):

Network topology (example/network_topology_sim.dart):

Wave function collapse (example/wave_function_collapse.dart):

Games & interactive

Pong (example/pong.dart):

Mouse drawing (example/draw.dart):

Effects & shaders

Shader toy (example/terminal_shader_toy.dart):

Post effects (example/effects.dart):

TV test pattern (example/tv.dart):

Layout & UI

Layout (example/layout.dart):

Splits (example/splits.dart):

Hello world (example/main.dart, example/helloworld.dart):

Alternate screen toggle (example/altscreen.dart):

Space (example/space.dart):

Terminal demo (example/uv_demo.dart):

Image protocols (example/image.dart, example/uv_graphics_parity.dart):

File pager (example/bat.dart):

Panic recovery (example/panic.dart):

Prepend line (example/prependline.dart):

Performance Tips

• Prefer incremental updates over full-screen redraws.
• For resize-heavy or animation-heavy apps, consider:
  • terminal.setScrollOptim(false)
  • terminal.setSynchronizedOutput(true)

API Surface

• Terminal
  Runtime entrypoint: lifecycle, event stream, capability queries, and drawing.
• Buffer
  2D grid of cells representing screen state for a frame.
• Cell
  A single rendered glyph plus style/link metadata.
• UvStyle / UvColor
  Text attributes and color model for foreground/background styling.
• UvPaintPolicy Shared foreground/background, palette, reverse, faint, and conceal resolution for native raster, web CanvasTerminalRenderer, and Flutter painting. Set foreground, background, an optional 16- or 256-entry palette, and faintMix once when those backends must agree.
• UvTerminalRenderer
  Diff-based renderer that minimizes terminal output between frames.
• KittyImage / ITerm2Image / SixelImage — Raw protocol encoders exported by package:ultraviolet/rendering.dart.
• Ansi / UvAnsi
  ANSI escape sequence helpers (Ansi) and UV renderer ANSI controls (UvAnsi).
• Event types (KeyEvent, MouseEvent, WindowSizeEvent, etc.)
  Typed input and terminal-state events from terminal.events.

Small How-Tos

For a narrower dependency surface, import the focused entrypoint matching the layer you use:

import 'package:ultraviolet/core.dart';      // cells, buffers, layout
import 'package:ultraviolet/input.dart';     // events and decoding
import 'package:ultraviolet/rendering.dart'; // diff renderer and effects
import 'package:ultraviolet/terminal.dart';  // terminal lifecycle
import 'package:ultraviolet/unicode.dart';   // graphemes and cell widths

Non-ANSI backends can share one color policy:

import 'package:ultraviolet/core.dart';
import 'package:ultraviolet/web.dart';

final policy = UvPaintPolicy(
  foreground: const UvRgb(204, 204, 204),
  background: const UvRgb(0, 0, 0),
);
final canvas = CanvasTerminalRenderer(paintPolicy: policy);

The native raster renderer exposes the equivalent values through RasterRenderOptions; Flutter accepts the policy directly. This aligns cell color/attribute resolution; it does not make glyph pixels identical. Font hinting, antialiasing, and the selected font can still differ.

All five entrypoints are browser-safe. The umbrella package:ultraviolet/ultraviolet.dart remains available when an application needs APIs from several layers. package:ultraviolet/uv.dart exposes the complete low-level UV surface for compatibility consumers.

Write ANSI sequences directly:

import 'dart:io';
import 'package:ultraviolet/ultraviolet.dart';

stdout.write(Ansi.clearScreen);
stdout.write(Ansi.cursorTo(1, 1));
stdout.write('${Ansi.bold}Ultraviolet${Ansi.reset}');

Draw a styled label:

terminal.setCell(
  2,
  2,
  Cell(
    content: 'H',
    style: const UvStyle(
      fg: UvColor.rgb(255, 210, 120),
      attrs: Attr.bold,
    ),
  ),
);
terminal.setCell(3, 2, Cell(content: 'i'));
terminal.draw();

Control exceptional diff behavior on a cell:

terminal.setCell(
  0,
  0,
  Cell(content: '•', diffOption: CellDiffOption.alwaysUpdate),
);

Use CellDiffOption.skip for terminal cells owned by an external renderer and CellDiffOption.forcedWidth(width) for escape-sequence-backed content whose display width cannot be inferred from its text. Ordinary cells should keep the default CellDiffOption.normal fast path.

Fill an area:

final panel = rect(0, 0, 20, 6);
terminal.fillArea(
  Cell(content: ' ', style: const UvStyle(bg: UvColor.rgb(24, 32, 48))),
  panel,
);
terminal.draw();

Handle resize safely:

await for (final event in terminal.events) {
  if (event is WindowSizeEvent) {
    terminal.resize(event.width, event.height);
    terminal.clearScreen();
    terminal.draw();
  }
}

Run a simple animation loop:

final timer = Timer.periodic(const Duration(milliseconds: 33), (_) {
  // update state
  terminal.clear();
  // redraw frame
  terminal.draw();
});

Pick best image protocol automatically:

final drawable = terminal.bestImageDrawableForTerminal(
  image,
  columns: 40,
  rows: 20,
);
drawable.draw(terminal, rect(2, 2, 40, 20));
terminal.draw();

Use synchronized output for heavy redraws:

terminal.setScrollOptim(false);
terminal.setSynchronizedOutput(true);

Examples

See:

• pkgs/ultraviolet/example/

Libraries

colorprofile

raster

Native software rasterization entry point for UV buffers.

ultraviolet

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

web

Web-only Ultraviolet APIs.

Ultraviolet

core

Core cell-buffer, geometry, layout, and drawing primitives.

input

Typed terminal events, input decoding, and input stream utilities.

rendering

Diff rendering, ANSI styling, effects, and terminal graphics primitives.

terminal

Terminal lifecycle, cursor, and native console integration.

unicode

Unicode grapheme iteration and terminal display-width utilities.

uv

The complete low-level Ultraviolet API surface.