twk_core
A terminal rendering core for Dart with no dependency but the
annotations of meta.
It keeps the screen as a packed cell buffer, works out which cells
changed, and writes the fewest bytes the terminal needs to show them.
Under that sit its own Unicode segmentation, an input parser, terminal
backends for Linux, macOS, Windows and the web, and a retained render
tree.
It is the core of twk, Flutter-like
widgets for terminal UIs. Use twk to build an app from widgets; use
twk_core directly for your own render objects, a frame loop without a
widget layer, or a command-line tool that only needs to write styled
lines and read keys.
Features
- A frame with no changes writes 0 bytes. A repaint touches only the cells that changed, and the presenter compares only damaged spans.
- Next to nothing is allocated per frame. Cells are typed arrays; styles and glyphs are interned.
- Few bytes on the wire. Frames are atomic (DEC 2026) and use
hardware scrolling (
DECSTBMwithSU/SD, DECSLRM), character insert and delete,REP,ECHandEL. - Unicode-correct. Grapheme segmentation (UAX #29), widths, and bidirectional text (UAX #9). Where a terminal disagrees about a character's width, the damage never leaves that glyph's cells.
- Three screen modes:
- fullscreen on the alternate screen;
- inline, a region under the shell's history that grows with its content and commits finished lines into the scrollback;
- a fixed viewport, a rectangle of the screen outside which nothing is written.
- Images in reserved cells, with kitty graphics, sixel or iTerm2.
- Plain text where the output is no terminal (a pipe, CI): no escape sequences, and the last frame written as lines.
- Input: keys (the kitty keyboard protocol where the terminal has it), the mouse, bracketed paste, focus, resize, and the terminal's color scheme.
- Anywhere a byte stream goes: a
Terminalover any link (TerminalLink), and a dart2wasm build for the web onto xterm.js.
Getting started
dart pub add twk_core
A render tree on the terminal: a counter that Space moves on, q to quit (example/main.dart):
import 'package:twk_core/twk_core.dart';
Future<void> main() async {
final app = TwkApp(await Terminal.open());
final styles = app.screen.styles;
final hint = styles.pen(const Pen(fg: Color.brightBlack));
final count = styles.pen(const Pen(fg: Color.green, attrs: Attr.bold));
final label = RenderText('Pressed 0 times', count);
final root = RenderBox(
pen: styles.pen(const Pen()),
padX: 2,
padY: 1,
child: RenderColumn(<(RenderObject, int?)>[
(RenderText('Space counts, q quits', hint), 1),
(label, 1),
]),
);
var pressed = 0;
await app.run(root, (event) {
if (event is! KeyEvent) {
return;
}
if (event.char == 'q') {
app.quit();
} else if (event.char == ' ') {
label.text = 'Pressed ${++pressed} times';
}
});
}
TerminalOptions(alternateScreen: false) runs the same tree inline, below
the shell's prompt. example/chat_demo.dart is a
larger app, an agent chat with a scrolling log, in either mode.
Without a screen
package:twk_core/terminal.dart is the terminal without the render tree
and the frame loop, for a logger, a prompt or a tool that writes lines.
It compiles in about two thirds of the time:
import 'package:twk_core/terminal.dart';
Future<void> main() async {
final terminal = await Terminal.open(
const TerminalOptions(alternateScreen: false, mouse: false),
);
final styles = StyleTable(colorMode: terminal.info.colorMode);
final ask = styles.style(fg: Color.yellow, attrs: Attr.bold);
final line = LineEncoder(styles, ansi: !terminal.info.plain)
..text(ask, 'Continue?')
..text(StyleId.base, ' [y/n] ')
..end();
terminal.write(line.out.view);
final key = await terminal.events.firstWhere((e) => e is KeyEvent);
await terminal.close();
print(key == const KeyEvent(KeyCode.char, char: 'y') ? 'yes' : 'no');
}
libc
package:twk_core/libc.dart is the libc calls twk's packages share on
Linux and macOS, bound through dart:ffi: poll, read, write,
pipe, close, ioctl with FIONREAD, tcgetattr and tcsetattr,
calloc and free, and errno. The core reads the process's terminal
with them, and twk_term's Pty drives a pseudo-terminal with them. It is
no part of twk_core.dart, which compiles for the web too.
Testing
HeadlessTerminal is a terminal in memory to run an app on in a test, and
renderToString paints a render tree once to text. The
twk_test
package adds a tester on a fake clock and a strict terminal emulator to
hold the bytes to.
Platforms
- Linux: the process's terminal through
dart:io, raw mode through termios,SIGWINCHor the in-band resize report. - macOS: the same POSIX path, with macOS's
termioslayout. - Windows: the console in virtual terminal mode, through
dart:ffito kernel32. - The web: dart2wasm, with xterm.js as the terminal.
Anywhere else, a Terminal over a TerminalLink you provide, such as a
socket or an SSH channel.
macOS is run by every package's tests and by hand in Terminal.app and iTerm2; Windows is written for but not yet run by the author, and reports of how it behaves are welcome. The limitations list what is known.
Learn more
- Design: how the cells, the presenter, Unicode, input and the screen modes work; how the core is tested and benchmarked; its limitations.
- The twk repository: the widget layer, the gallery and the other packages built on the core.
License
MIT. The bundled Unicode data keeps its own license; see NOTICE.
Libraries
- libc
- The libc calls twk's packages share on Linux and macOS, bound through
dart:ffi: poll and PollFd, read, write, open, ttyname, signal, getppid, pipe, close, ioctl (with fionread), tcgetattr and tcsetattr, calloc and free, and errno. The core reads the process's terminal with them, twk_term'sPtydrives a pseudo-terminal with them beside calls of its own, and twk's file watch takes its memory from them. - terminal
- The terminal without the render tree and the app: for a logger, a prompt or a command-line tool that writes lines and reads keys rather than drawing frames. Terminal opens the process's terminal (or one over a TerminalLink, or plain output where it takes no sequences) and says what it is (TerminalInfo, TerminalCaps); colorModeFor, plainAsked and runsInCi say what the environment asks for; StyleTable interns styles of Colors and Attrs, which a LineEncoder writes as lines of text with their SGR sequences; InputParser decodes the bytes read into InputEvents (KeyEvent, MouseEvent, PasteEvent, …); stringWidth, TextSegmenter and fitText measure and cut text in cells; the terminal's own sequences (a title, progress, a notification, the clipboard) are strings to write; and LogSink keeps what log records.
- twk_core
- A terminal UI core with no dependency but
package:meta's annotations: TwkApp, the frame loop that runs a render tree (RenderObject) on a Terminal; Screen, a Surface of cells painted through a Canvas with StyleTable pens, which a Presenter writes as the fewest bytes for what TerminalCaps says the terminal has; input decoded into InputEvents; Unicode segmentation and widths (TextSegmenter, stringWidth) and bidirectional text (BidiText); and, for tests and one-off output, HeadlessTerminal, renderToString and LineEncoder, lines of text in the SGR sequences of their styles.