For the past few months we’ve been architecting, refactoring, and refining. 146 commits. Dozens of PRs. One PR touched 493 files.
The long-awaited Beta isn’t just about revolutionary features. It’s about getting the architecture right and ensuring the API is stable for the future.
Terminal.Gui v2 is the ultimate framework for building cross-platform Terminal UI (TUI) apps with code that belongs in 2026, not 1999.
Here’s the stuff I’m the most proud of. To learn more and get started head to https://gui-cs.github.io/Terminal.Gui.
Killing the Static Singleton
Terminal.Gui v1 was built on a static singleton. Application.Init(), Application.Run(), global state everywhere. 2007-era architecture that survived into the 2020s through inertia.
You can’t test static singletons properly. Can’t mock them. Can’t run multiple instances. Modern C# developers expect better.
So we fixed it. Backward compatibility matters, so Tom built an instance-based IApplication interface and made the static API a thin (obsolete) wrapper.
How it was:
// Global. Singleton. The 2000s called, they want their pattern back.
Application.Init();
Window top = new Window();
top.Add(myView);
Application.Run(top);
Application.Shutdown();
How it is now:
// Proper resource management. Testable. Feels right.
using (IApplication app = Application.Create().Init())
{
Window top = new();
top.Add(myView);
app.Run(top);
}
The difference matters for tests, dependency injection, and running multiple app instances (useful for testing different drivers). The old way made all of that painful or impossible.
The new way: views get their IApplication through context. Tests create mock applications without global state pollution. Disposal actually cleans up.
Type-safe dialog results:
using (IApplication app = Application.Create().Init())
{
app.Run<ColorPickerDialog>();
Color? selectedColor = app.GetResult<Color>();
}
No casting. No object?. Generics doing their job.
On Naming Things
Renamed Application.TopLevels to Application.SessionStack. “TopLevels” made sense in 2007, confused everyone in 2025. “SessionStack” describes what it is: a stack of session tokens.
// Clear stack-based session management
SessionToken? main = app.Begin(mainWindow); // Push
SessionToken? dlg = app.Begin(dialog); // Push (dialog becomes modal)
app.End(dlg); // Pop (restore main)
app.End(main); // Pop (empty, app stops)
Prompt<TView, TResult>
Creating custom dialog classes for every input type is tedious. Need a color? Create ColorPickerDialog. Need a date? Create DatePickerDialog. Each with its own result property, cancel handling, buttons.
Now any view can become a type-safe dialog.
Before:
ColorPickerDialog dialog = new();
Application.Run(dialog);
if (dialog.Canceled) return null;
Color? color = dialog.SelectedColor;
After:
Color? color = mainWindow.Prompt<ColorPicker, Color?>(
resultExtractor: cp => cp.SelectedColor,
beginInitHandler: prompt => prompt.Title = "Pick Color"
);
One line. Type-safe. Returns null on cancel. Compiler checks result types at build time.
IValue<T>
For views that hold a value, there’s IValue<T>:
public class ColorPicker : View, IValue<Color?>
{
public Color? Value { get; set; }
// Events follow the Cancellable Work Pattern
}
Now Prompt knows how to extract the result automatically:
Color? result = mainWindow.Prompt<ColorPicker, Color?>();
No extractor needed. The system recognizes IValue<T> and extracts automatically.
The 493-File Mouse Refactoring
PR #4472. Four hundred ninety-three files changed. Complete rewrite of the mouse system, ANSI driver, and input injection.
Input injection means programmatic mouse events—clicks, double-clicks, drags—injected directly into the application pipeline. With virtual time control. Millisecond precision. No manual testing, no UI automation tools, no hacks.
Here’s a test for double-click detection. An actual, working test:
[Fact]
public void Button_DoubleClick_RaisesEvent()
{
VirtualTimeProvider time = new();
using IApplication app = Application.Create(time);
app.Init(DriverRegistry.Names.ANSI);
Button button = new() { Text = "Double-Click Me" };
var doubleClicked = false;
button.Accepting += (s, e) => {
if (e.Context?.Binding is MouseBinding {
Mouse.Flags: var f
} && f.HasFlag(MouseFlags.LeftButtonDoubleClicked))
{
doubleClicked = true;
}
};
// Inject first click
app.InjectMouse(new() {
Flags = MouseFlags.LeftButtonPressed,
ScreenPosition = new Point(0, 0)
});
time.Advance(TimeSpan.FromMilliseconds(50));
app.InjectMouse(new() {
Flags = MouseFlags.LeftButtonReleased
});
// Inject second click within threshold
time.Advance(TimeSpan.FromMilliseconds(200));
app.InjectMouse(new() {
Flags = MouseFlags.LeftButtonPressed
});
app.InjectMouse(new() {
Flags = MouseFlags.LeftButtonReleased
});
Assert.True(doubleClicked);
}
The test injects mouse events at specific timestamps, advances virtual time, asserts on double-click flags. Runs in milliseconds, deterministically.
VirtualTimeProvider controls time in tests. Two clicks 200ms apart? Advance time 200ms. No waiting. Tests run instantly whether on a fast desktop or slow CI runner.
The ANSI Driver
I have a thing for terminals. Spent time customizing shells, studying ANSI escape sequences, caring about CSI vs SS3 sequences. My original post mentioned fonts—it extends to the whole terminal stack.
When we rebuilt the mouse system, I wanted a proper ANSI driver. Pure escape sequences. Cross-platform. VT100-era standards that still work in 2026.
What Makes It Special
The ANSI driver doesn’t use platform-specific APIs for anything but reading & writing terminal IO. No Win32 Console calls. No Unix syscalls. Just ANSI escape sequences—the same ones terminals have understood since the 1970s.
Input parsing:
- Mouse SGR Format (CSI < Pb ; Px ; Py M/m) – The modern mouse reporting format that actually works
- Keyboard CSI sequences (CSI final[;modifiers]) – Arrow keys, function keys, the whole gamut
- SS3 sequences (ESC O final) – Because some terminals still use them for function keys
- Escape-as-Alt – ESC followed by another key = Alt modifier (the Unix way)
Output:
- DECSCUSR (CSI Ps SP q) – Those seven cursor styles I mentioned earlier
- SGR attributes (CSI Ps m) – Colors, bold, underline, all the formatting
- Cursor positioning (CSI Ps ; Ps H) – Direct addressing, no abstractions
- Device Status Reports (CSI 6 n, DSR) – Query the terminal for screen size changes
Why This Matters
Every terminal speaks ANSI. Windows Terminal, iTerm2, gnome-terminal, Alacritty, WezTerm—all ANSI.
One driver. Every platform. Consistent behavior. No “works on Linux, weird on macOS” bugs.
The Parser Pipeline (For the Terminal Nerds)
The ANSI parser is actually three parsers working together:
Console Input → Raw Bytes → Parser Triage
├─→ AnsiKeyboardParser → Key events
├─→ AnsiMouseParser → Mouse events
└─→ AnsiResponseParser → DSR responses
Each parser handles its own sequence format. Keyboard parser: CSI and SS3. Mouse parser: SGR. Response parser: terminal replies.
When you inject a mouse event in tests, it goes through AnsiMouseEncoder (converts to raw SGR format like ESC [ < 0 ; 10 ; 5 M), then AnsiMouseParser (back to mouse event structure). Round-trip encoding.
Another hat tip to contributor Tom; his work on this was brilliant.
The Cost
Edge cases: terminals that send SS3 for F1 but CSI for F2. Mouse coordinates 1-based in ANSI but 0-based internally. Escape sequences meaning different things depending on modifiers.
Took months. Now we have a driver that works everywhere. When someone reports “doesn’t work in my terminal,” switching to ANSI driver usually fixes it.
Testing the Driver
This is where input injection pays off. Want to test how Terminal.Gui handles a Shift+F5 keypress? Inject the ANSI sequence:
app.InjectKey(AnsiKeyboardEncoder.Encode(
Key.F5.WithShift
));
Want to test mouse wheel scrolling?
app.InjectMouse(AnsiMouseEncoder.Encode(new Mouse {
Flags = MouseFlags.WheeledDown,
ScreenPosition = new Point(10, 5)
}));
The encoders produce actual ANSI sequences—the same bytes a real terminal would send. The parsers consume them. We’re testing the real path, not a mock.
Cursors
Terminal emulators support seven cursor styles via ANSI DECSCUSR sequences. Blinking block, steady underline, blinking bar.
Terminal.Gui’s cursor handling was scattered—state everywhere, no explicit model. Fixed:
An Immutable Cursor Record
public record Cursor
{
public Point? Position { get; init; } // Null = hidden
public CursorStyle Style { get; init; } = CursorStyle.Hidden;
public bool IsVisible => Position.HasValue && Style != CursorStyle.Hidden;
}
Seven Cursor Styles (The ANSI Standard)
public enum CursorStyle
{
BlinkingBlock = 1, // █ Traditional terminal cursor
SteadyBlock = 2, // █ Steady (no blink)
BlinkingUnderline = 3, // _ Classic
SteadyUnderline = 4, // _ Steady
BlinkingBar = 5, // | Text editor style
SteadyBar = 6, // | Steady editor cursor
Hidden = -1 // No cursor
}
Maps directly to ANSI DECSCUSR (CSI Ps SP q). Windows driver translates to Win32 API automatically. Cross-platform cursor styles.
Using it in a view:
protected override void OnDrawContent(Rectangle viewport)
{
int cursorCol = _cursorPosition - _scrollOffset;
if (cursorCol >= 0 && cursorCol < Viewport.Width && HasFocus)
{
Point screenPos = ViewportToScreen(new Point(cursorCol, 0));
Cursor = new Cursor
{
Position = screenPos,
Style = CursorStyle.BlinkingBar
};
}
else
{
Cursor = new Cursor { Position = null }; // Hidden
}
}
Immutable record, value-type semantics, thread-safe. Caches intelligently—99% of PositionCursor() calls were redundant.
Simplified Command System
The command system had CommandContext<TBinding>. Generic, type-constrained. You had to know the binding type at compile time. Extending meant fighting the type system. Pattern matching was awkward.
Simplified:
Before:
public record struct CommandContext<TBinding> : ICommandContext
{
public TBinding? Binding { get; set; }
}
After:
public record struct CommandContext : ICommandContext
{
public IInputBinding? Binding { get; set; }
}
No generics. Just a common IInputBinding interface that KeyBinding, MouseBinding, and InputBinding all implement. Now you can pattern match:
var source = ctx.Binding switch
{
KeyBinding kb => $"Keyboard: {kb.Key}",
MouseBinding mb => $"Mouse: {mb.MouseEvent?.Flags}",
InputBinding => "Programmatic",
_ => "Unknown"
};
Pattern matching works when you let it. Best design gets out of the language’s way.
Documentation
Every API now has awesome (until you find bugs and report them) API reference documentation that includes sample code and cross-references. I take pride in this, so if you find problems, please submit issues!
Start here: https://gui-cs.github.io/Terminal.Gui/api/Terminal.Gui.App.html
The Deep Dives go deep and broad. See https://gui-cs.github.io/Terminal.Gui/docs/index.html
Other Work
Upgraded to .NET 10 and C# 14. Modern language features, collection expressions.
Modernized TextView to use the new Viewport/ScrollBar system. Touches more code than expected, makes everything slightly better.
Fixed macOS test runners that randomly hung. Fixed keyboard test timing issues. Stabilized stress tests.
What This Actually Means
If you’re building apps with Terminal.Gui: You get type-safe dialogs, testable mouse interactions, proper resource management, and an architecture that feels like 2026, not 2006.
If you’re contributing to Terminal.Gui: The codebase is now testable in ways it never was. Input injection works. The architecture has proper separation. The docs explain the “why” not just the “what.”
If you have a Terminal.Gui v1 app: You will need to port. Tons has changed. But we’ve provided a migration guide that will help. In the end, you’ll find the updated API is far simpler, easier to understand, and most of your porting work will be removing code that’s no longer needed. Pro-tip: Just point your favorite AI coding agent at https://gui-cs.github.io/Terminal.Gui/docs/migratingfromv1.html and let it do it for you.
Beta, Not 2.0
This is a Beta. The architecture is solid and we are now holding a very high bar for further API changes.
Use it. Test it. Tell me what’s broken. GitHub issues are open.
https://github.com/gui-cs/Terminal.Gui/issues
Thank You
To @BDisp, who tests thoroughly and catches bugs I miss. He’s always eager to dive into the trickiest bugs and work until they are resolved.
To @tznind, who’s architectural insights made IApplication and the new driver model possible. Plus Terminal.Gui.Designer is da’bomb.
To @dodexahedron, who regularly challenges us to do things right.
To all the dozens more who’ve submitted Issues and PRs!
To the AI agents (Claude, Copilot); you know your role.
And, of course, to Miguel de Icaza who started this 17 years ago.
- Still maintaining a terminal UI framework. Still ridiculous. Still wonderful.
-Tig
The post
Terminal.Gui: Still Absurd, Now Beta! first appeared on
tig.log.
Log in
