/sharpconsoleui

name: sharpconsoleui
description: "Use SharpConsoleUI to build full terminal (TUI) applications in .NET — equally suited to full-screen single-window apps and multi-window desktops with overlapping draggable windows — using a compositor, a DOM layout engine, and 40+ reactive controls (data tables, tree views, forms, an embedded PTY terminal, markdown, charts, video). USE FOR: interactive console apps, full-screen TUIs, multi-window terminal desktops, dashboards, wizards, and admin/monitoring UIs that need focus, mouse, and flicker-free rendering over local terminals or SSH; NativeAOT console tools. DO NOT USE FOR: simple line-based CLI output or argument parsing; non-interactive scripts; GUI/desktop (WPF/WinForms) or web UIs. INVOKES: inspect the project, add the SharpConsoleUI package, scaffold a window/control tree, and build/run to verify the app renders."
compatibility: "Requires a .NET 8.0+ console project (net8.0/net9.0/net10.0) that can reference the `SharpConsoleUI` package and run against a modern terminal. Uses a retained-mode UI on a single cooperative UI thread, not immediate-mode Console.Write."

SharpConsoleUI terminal application framework

Trigger On

• building an interactive terminal UI: dashboards, wizards, settings screens, admin/monitoring consoles
• building a full-screen single-window TUI: a `.Frameless()` (no title bar, no title buttons) + `.Maximized()` app that owns the whole terminal
• building a multi-window terminal desktop: overlapping windows with drag/resize/minimize/maximize, z-order, focus routing, modal windows, and mouse support (full-screen and multi-window are equally first-class here)
• wanting flicker-free rendering that stays clean over SSH (diff-based cell buffer, not full repaints)
• needing rich terminal controls: data tables, tree/list views, forms, an embedded PTY terminal, markdown, charts, or video
• shipping a NativeAOT-ready console application with a real UI

Do not trigger for plain line-based CLI tools, argument parsing, or non-interactive scripts.

Install

• NuGet:
• `dotnet add package SharpConsoleUI`
• `dotnet add package SharpConsoleUI --version <version>`
• XML package reference:
• `<PackageReference Include="SharpConsoleUI" Version="x.y.z" />`
• Targets `net8.0`, `net9.0`, `net10.0`.
• Sources:
• [NuGet: SharpConsoleUI](https://www.nuget.org/packages/SharpConsoleUI/)
• [GitHub: nickprotop/ConsoleEx](https://github.com/nickprotop/ConsoleEx)
• [Docs site](https://nickprotop.github.io/ConsoleEx/)

Workflow

flowchart LR
  A["NetConsoleDriver (RenderMode.Buffer)"] --> B["ConsoleWindowSystem"]
  B --> C["WindowBuilder -> Window"]
  C --> D["window.AddControl(Controls.*)"]
  D --> E["DOM layout: Measure -> Arrange -> Paint"]
  E --> F["windowSystem.AddWindow(window)"]
  F --> G["windowSystem.Run()  (blocks until Shutdown)"]
  G --> H["compositor merges per-window buffers -> terminal"]

1. Create a `NetConsoleDriver` and a `ConsoleWindowSystem` that owns all windows. 2. Build one or more windows with `WindowBuilder` (title, size, position, borders, padding). 3. Add controls to each window with `window.AddControl(...)`, usually via the `Controls` static factory. 4. Wire interactivity through control events (e.g. `Button.OnClick`); call `windowSystem.Shutdown()` to exit. 5. `windowSystem.AddWindow(window)` then `windowSystem.Run()` starts the render/input loop (blocks until shutdown). 6. For layout, dialogs, portals/overlays, forms, and the full control set, load the reference files below.

Minimal app (read + show + interact)

using SharpConsoleUI;
using SharpConsoleUI.Builders;
using SharpConsoleUI.Controls;
using SharpConsoleUI.Drivers;

var driver = new NetConsoleDriver(RenderMode.Buffer);
var windowSystem = new ConsoleWindowSystem(driver);

var window = new WindowBuilder(windowSystem)
    .WithTitle("Hello World")
    .WithSize(50, 12)
    .Centered()
    .Build();

window.AddControl(Controls.Markup()
    .AddLine("[bold cyan]Hello, SharpConsoleUI![/]")
    .Build());

window.AddControl(Controls.Button("Quit")
    .OnClick((sender, e, win) => windowSystem.Shutdown())
    .Build());

windowSystem.AddWindow(window);
windowSystem.Run();

Layout + data example

Use a `GridControl` when you need columns/rows with fixed, size-to-content, or proportional (`Star`) tracks, and put content controls (tables, lists, markdown) into the cells:

var grid = Controls.Grid()
    .Columns(GridLength.Cells(20), GridLength.Star(1))   // fixed sidebar + fill
    .Rows(GridLength.Auto(), GridLength.Star(1))         // toolbar + body
    .RowGap(1)
    .Place(Controls.Markup("[bold]Dashboard[/]").Build(), 0, 0, colSpan: 2)
    .Place(sidebarList, 1, 0)
    .Place(dataTable, 1, 1)
    .Build();

window.AddControl(grid);

See `references/recipes.md` for full grid/table/form/dialog examples and `references/controls.md` for the control chosen per region.

Best practices

• Describe the UI declaratively (retained mode). Let the framework own redraws, focus, and input — do not mix raw `Console.Write` into a running app.
• The app runs on one cooperative UI thread. Never block it: don't call `.Result` / `.Wait()` on async work inside a handler (it deadlocks the loop). Push blocking/CPU work off-thread and marshal UI mutations back with `EnqueueOnUIThread` / `InvokeAsync`. See `references/architecture.md`.
• Use portals for dropdowns, overlays, and toasts, and the built-in `Dialogs` for confirm/prompt/progress, instead of hand-positioning windows. See `references/recipes.md`.
• Apply semantic control `Role`s (Primary, Success, Danger, …) so colors come from the active theme instead of being hand-set.
• Style all text with `[tag]text[/]` markup — it works everywhere text renders (labels, titles, status bars, table cells, tree nodes), including `[markdown]`, `[gradient=…]`, and inline `[spinner]`. Escape untrusted text with `MarkupParser.Escape(...)`. See `references/markup.md`.
• P