termui_pty 0.12.0
termui_pty: ^0.12.0 copied to clipboard
A custom ANSI terminal emulator and PTY view for termui.
termui_pty #
A high-performance virtual terminal emulator and PTY embedding widget for the termui ecosystem.
termui_pty provides a strict, MVVM-compliant terminal emulator that processes raw ANSI/VT100 byte streams into a visible buffer. It is designed to handle high-throughput command-line output (like htop, btop, or aggressive cat commands) without thrashing the rendering pipeline.
Features #
- High-Performance Rendering: Uses flat typed-data cell buffers (
Uint32Listattributes and code units) andpackage:charactersgrapheme segmentation to reduce allocation pressure during heavy I/O. - Strict MVVM Boundaries: The UI (
TerminalView) is decoupled from the state and I/O streams (VirtualTerminal). - Protocol Support: Parses standard CSI cursor movement,
DECSTBMscroll regions, line/char editing, SGR 16/256/TrueColor attributes, custom tab stops (HTS,TBC,CHT,CBT,DECST8C), DEC Special Graphics (G0/G1),REP,DECOM,IRM, alternate screen (?47/?1047/?1049), scrollback history (ScrollbackBuffer),OSC 52clipboard write/read-blocking, andDSR/CPR/DA1/DA2/DECRQM/XTWINOPS 18tquery replies. Also tracksDECTCEMcursor visibility,DECSCUSRcursor shape,DECAWMauto-wrap,?1004focus reporting,?1007alternate scroll,?2004bracketed paste,?2026synchronized output,?2027grapheme cluster mode, and?9/?1000/?1002/?1003/?1006mouse modes. - Transport Agnostic: The core
TerminalViewaccepts any byte or string stream. You can feed it local pseudo-terminals, remote SSH streams, or mock data for testing. pty2Integration: Includes a convenience widget (PseudoTerminalView) to mount apackage:pty2subprocess directly into yourtermuiwidget tree.
Installation #
Add it to your pubspec.yaml:
dependencies:
termui_pty: ^0.8.3
Usage #
The Easy Way (Local PTY subprocess) #
If you are using package:pty2 to spawn local shells, use the PseudoTerminalView wrapper. It manages the stream subscriptions, resize events, and input routing for you.
import 'package:pty2/pty2.dart';
import 'package:termui/termui.dart';
import 'package:termui_pty/termui_pty.dart';
Future<void> main() async {
final pty = PseudoTerminal.start(
'bash',
['-i'],
environment: {'TERM': 'xterm-256color'},
);
final terminal = Terminal();
final runner = PromptRunner<void>(
terminal: terminal,
alternateScreen: true,
widget: PseudoTerminalView(
pty: pty,
transparentBackground: false,
),
);
await runner.run();
}
The Architecturally Sound Way (Decoupled Transport) #
For full control, SSH streams, or mocking in TerminalTester, instantiate the VirtualTerminal (ViewModel) yourself and bind it to a TerminalView.
import 'package:termui/termui.dart';
import 'package:termui_pty/termui_pty.dart';
// 1. Initialize the ViewModel
final vterm = VirtualTerminal(width: 80, height: 24);
// 2. Feed it raw byte streams from your data source
myCustomSocket.listen((bytes) {
vterm.write(bytes);
});
// 3. Render the View and pipe user input back to the source
final runner = PromptRunner<void>(
terminal: Terminal(),
alternateScreen: true,
widget: TerminalView(
terminal: vterm,
onInput: (String data) {
myCustomSocket.write(data);
},
),
);
await runner.run();
Testing #
Because TerminalView requires only a VirtualTerminal instance, you can test terminal UIs using package:test and TerminalTester from termui_test without spawning a real OS process.
import 'package:termui_pty/termui_pty.dart';
import 'package:termui_test/termui_test.dart';
import 'package:test/test.dart';
void main() {
test('Terminal renders output', () {
final tester = TerminalTester();
tester.run(() async {
final vterm = VirtualTerminal(width: 80, height: 24);
await tester.pumpWidget(TerminalView(terminal: vterm));
// Inject mock ANSI sequence
vterm.writeString('\x1b[31mHello World\x1b[0m');
await tester.pump();
// Verify buffer state without needing an actual PTY
expect(vterm.buffer.getCharacter(0, 0), 'H');
});
});
}