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.

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.

Deliver

• an install + first-run guide ready to paste into a .NET console project
• a minimal window app and a layout/data example that actually render
• clear notes on the threading model, portals/dialogs, and terminal-capability tradeoffs

Validate

• dotnet add package SharpConsoleUI restores and the project compiles.
• The minimal app above builds and runs, showing a centered window with a working Quit button (Tab to focus, Enter/click to quit).
• One layout/control sample from references/recipes.md renders correctly.
• Any control used is confirmed against references/controls.md (correct factory/API).

Load References

Related skills