terminal library Terminal

Unified terminal module for artisanal.

This library provides a single source of truth for terminal operations used throughout the package, including both static components and the TUI runtime.

Quick Start

import 'package:artisanal/terminal.dart';

// Create a terminal
final terminal = StdioTerminal();

// Use terminal operations
terminal.hideCursor();
terminal.write('Hello, ');
terminal.writeln('World!');
terminal.showCursor();

// Use ANSI codes directly
import 'dart:io';
stdout.write(Ansi.bold);
stdout.write('Bold text');
stdout.write(Ansi.reset);

// Check key input
if (Keys.isPrintable(byte)) { ... }

Terminal Abstraction

Artisanal provides a unified Terminal interface that abstracts away the differences between standard I/O, string buffers (for testing), and specialized terminal emulators.

StdioTerminal: The default implementation for real terminal apps.
StringTerminal: Useful for unit testing terminal output.
TuiTerminal: Extended interface for interactive TUI applications.

Raw Mode and Input

Interactive applications often require "raw mode" to receive input character-by-character without waiting for a newline, and to disable local echo.

Use RawModeGuard or Terminal.enableRawMode to manage this state safely. Always ensure raw mode is disabled before the program exits to avoid leaving the user's terminal in a broken state.

ANSI and Escape Sequences

Artisanal includes a comprehensive Ansi utility class for generating standard ANSI escape sequences for colors, styles, cursor movement, and screen control.

For more advanced rendering, see the Ultraviolet subsystem. package:artisanal/uv.dart remains a compatibility re-export.

Artisanal provides a unified Terminal interface that abstracts away the differences between standard I/O, string buffers (for testing), and specialized terminal emulators.

StdioTerminal: The default implementation for real terminal apps.
StringTerminal: Useful for unit testing terminal output.
TuiTerminal: Extended interface for interactive TUI applications.

Interactive applications often require "raw mode" to receive input character-by-character without waiting for a newline, and to disable local echo.

Use RawModeGuard or Terminal.enableRawMode to manage this state safely. Always ensure raw mode is disabled before the program exits to avoid leaving the user's terminal in a broken state.

Artisanal includes a comprehensive Ansi utility class for generating standard ANSI escape sequences for colors, styles, cursor movement, and screen control.

For more advanced rendering, see the Ultraviolet subsystem. package:artisanal/uv.dart remains a compatibility re-export.

Classes

Ansi Terminal: Unified ANSI escape sequence constants and utilities.
BackendTerminal: Terminal implementation that layers ANSI/OSC semantics over a TerminalBackend.
BrowserTerminalHostServer: Reusable browser host server for remote TUI sessions.
EmbeddedTerminalBackend: Generic embedded backend backed by callbacks and externally supplied streams.
ITerm2Image: Utilities for the iTerm2 Image Protocol.
JsonTerminalBackend: Message-oriented backend that speaks the terminal bridge JSON protocol.
Key: Represents a parsed keyboard input event.
Keys: Key constants and utilities for keyboard input handling.
KittyImage: Utilities for the Kitty Graphics Protocol.
RawModeGuard: Guard object returned by Terminal.enableRawMode.
SharedInputStream: Shared broadcast input stream wrapper.
SixelImage: Utilities for Sixel Graphics.
SocketTerminalBackend: Socket-backed backend for remote/shell-mode terminal hosts.
SocketTerminalHostServer: Reusable raw socket host server for remote TUI sessions.
SplitTerminal: A terminal that splits "control/input" from "display/output".
StdioTerminal: Standard terminal implementation using dart:io.
StdioTerminalBackend: Native stdio backend for BackendTerminal.
StringTerminal: A terminal that captures output to a string buffer (for testing).
Terminal Terminal: Abstract terminal interface for all terminal operations.
TerminalBackend: Low-level I/O backend for a terminal host.
TerminalBridge: Bridge controller for embedded terminal hosts such as xterm.js, sockets, or custom UI surfaces.
TerminalBridgeJsonChannel: JSON message channel layered over a TerminalBridge.
TerminalBridgeMessage: JSON-serializable bridge message for remote/browser terminal hosts.
TtyTerminal: POSIX /dev/tty terminal implementation.
WebSocketTerminalBackend: WebSocket-backed backend that speaks the terminal bridge JSON protocol.

Enums

KeyType: Types of keyboard input events.
TerminalBridgeMessageType: Message kinds used by TerminalBridgeMessage.

Properties

isSharedStdinStreamStarted → bool: Returns true if the shared stdin stream has started listening to stdin.
no setter
sharedStdinStream → Stream<List<int>>: Shared broadcast stream for stdin to allow multiple listeners and restarts.
no setter

Functions

codePoints(String s) → List<int>: Decodes a Dart String (UTF-16) into Unicode scalar values (code points).
firstCodePoint(String s) → int
graphemes(String s) → Iterable<String>: Returns a lazy grapheme-cluster iterable.
isSingleCodePoint(String s) → bool
readGraphemeAt(String s, int index) → ({String grapheme, int nextIndex}): Reads the grapheme cluster starting at index and returns it along with the next UTF-16 code-unit index.
shutdownSharedStdinStream() → Future<void>: Shuts down the shared stdin stream so the process can exit cleanly.

Typedefs

BrowserTerminalSessionHandler = Future<void> Function(WebSocket socket): Session handler invoked for each accepted browser websocket connection.
SocketTerminalSessionHandler = Future<void> Function(Socket socket): Session handler invoked for each accepted raw socket terminal connection.
TerminalDimensions = ({int height, int width}): Terminal dimensions expressed in cells.