Terminal.Emulation 0.1.0

Terminal.Avalonia

A lightweight, fast terminal-emulator control for Avalonia (.NET 10), built from scratch — not a wrapper around an existing emulator. Designed to host any terminal program (PowerShell, bash, …) and full-screen dynamic TUI apps (claude code, opencode, vim, htop).

Drop as many TerminalControl instances as you like into one app — each owns its own emulator engine and child process, so they run independently and resize with their layout slot.

Why from scratch

Generic terminal controls fail on real TUIs because they skip the query/response sequences — the app hangs waiting for a reply. This project implements the full contract that makes TUIs work:

• Response channel — DA (ESC[c), DSR/CPR (ESC[6n), DECRQM — apps that ask get answered.
• VT500 parser — canonical DEC ANSI state machine (Paul Williams), robust to split/garbled input.
• Alternate screen (?1049h), truecolor (38;2;r;g;b) + 256-color, Unicode width (CJK/emoji = 2 cells, combining marks = 0), deferred autowrap, scroll regions, ICH/DCH/IL/DL/ECH, synchronized output, bracketed paste, SGR mouse reporting.
• PTY backends — native ConPTY on Windows, forkpty on Linux/macOS.

Layout

Install

dotnet add package Terminal.Avalonia

Three packages, always released together on one version number:

On Windows, Terminal.Pty also lays conpty/<arch>/{conpty.dll,OpenConsole.exe} into your output and publish directories and runs sessions on that host rather than the in-box conhost.exe, which crashes on some TUI teardowns and takes the shell with it. Nothing to configure; IPtyConnection.HostDescription says which host a session actually got. To lay the files out yourself, set <TerminalPtyDeployConsoleHost>false</TerminalPtyDeployConsoleHost>.

Usage

var term = new TerminalControl { FontSize = 14 };
myGrid.Children.Add(term);

term.Start(new PtyOptions
{
    Command = OperatingSystem.IsWindows() ? "powershell.exe" : "/bin/bash",
    Columns = 80,
    Rows = 24,
});

The control sizes itself to its slot (columns/rows are derived from the font metrics) and forwards resizes to the child via SIGWINCH / ConPTY resize. Dispose (or detach from the visual tree) to kill the child and release the PTY.

Input & interaction

• Full keyboard mapping incl. modifiers, function keys, application-cursor mode.
• Mouse text selection (drag, double-click word, triple-click line) + SGR mouse reporting for TUIs; wheel scrolls history (or is reported to the app).
• Ctrl+Shift+C / Ctrl+Shift+V copy & paste (bracketed-paste aware); Shift+PageUp/PageDown scroll.
• Draggable scrollbar over the scrollback ring.
• Bindable/stylable FontFamily, FontSize, Palette styled properties; cursor blinks when focused and shows a hollow block when not.

Roadmap

Prioritized gap analysis versus mature emulators (xterm.js, Windows Terminal, WezTerm, …) lives in docs/ROADMAP.md.

Build & test

dotnet build Terminal.Avalonia.slnx
dotnet test  Terminal.Avalonia.slnx
dotnet run --project samples/Terminal.Avalonia.Demo
build.cmd                       # build + test + pack into artifacts/

Releasing

python Deploy/publish.py --dry-run   # test, pack, stop short of pushing
python Deploy/publish.py             # test, bump the patch, build, pack, push all three

The version lives once, in Directory.Build.props. A ProjectReference packs as a PackageReference pinned to exactly that version, so the three go out together or a consumer resolves an engine its control was never built against. The API key goes in Deploy/.env (gitignored — copy .env.example).

License

MIT — see LICENSE. Terminal.Pty redistributes the MIT-licensed open-source console host from microsoft/terminal.

⚠️ Run the demo as a normal GUI app. Under a host whose stdout is redirected to a pipe (dotnet run captured by a tool, dotnet test), a console child can inherit that pipe instead of the pseudo console — a launcher artifact, not a bug in the control.