Arlecchino documentation
Arlecchino is a terminal UI framework for .NET. A view is a plain class, navigation keeps a history,
and every part of the machinery is a service in Microsoft.Extensions.DependencyInjection.
dotnet add package Arlecchino
New here? Getting started is the smallest application that runs, and Lexicon is every term these pages use — including the ones this framework deliberately does not have.
Start here
| Page | What it covers |
|---|---|
| Getting started | Installing the package, the smallest app that runs, the first view |
| Tutorial: your first app | A todo list from an empty project: a store of atoms, a list, two modals and a status bar |
| Showcase | The applications built on the framework and what each one demonstrates |
| Lexicon | Every term, in one place |
The application
| Page | What it covers |
|---|---|
| Hosting and options | AddArlecchino, every option, the builder API, running without the hosted service |
| The frame loop | When a frame is drawn, which thread draws it, and how work gets back onto it |
| Views and navigation | IArlecchinoView, ViewRoute, the navigator, history, view registration |
| Source generator | How ViewKind, the factories and the registrations are emitted, MSBuild switches |
Drawing
| Page | What it covers |
|---|---|
| Rendering | Surface: what a frame costs, geometry, headless rendering |
| Layout | The flow cursor, absolute calls, regions and clipping |
| Text and width | Why measurement is in columns, and the TextWidth calls that do it |
| Colors | TermColor, RgbTermColor, and what the terminal can actually show |
| Theming | Theme, ThemePalette, and the framework's own palette |
Input
| Page | What it covers |
|---|---|
| Keyboard | How a key travels, the keymap, the keys screen, layouts, paste and copy |
| Commands | IArlecchinoCommand, ViewCommand, the palette, the conflict check |
| Mouse | MouseEvent, hit-testing, and why Windows is different |
| Focus | FocusRing and IArlecchinoFocusable |
| ANSI and the terminal | What goes out, what comes in, and IArlecchinoTerminal |
State
| Page | What it covers |
|---|---|
| Atoms | TrackedAtom and LocalAtom, computed values, undo |
| Stores | A class of atoms that registers itself |
| Async atoms | Loading in the background, and tying work to a screen |
| Forms | Form and Field |
| Application state | ArlecchinoState, the output line, notifications |
| Modals | Every dialog that ships, plus stacking and validation |
Widgets
| Page | What it covers |
|---|---|
| Widgets overview | The two interfaces, and writing one of your own |
| ListBox | A scrolling, selectable, clickable list |
| Table | Columns that size themselves, and sorting |
| Tree | A hierarchy that fills its children in on demand |
| Tabs | A strip of titles across a pane |
| Scrolling | ScrollPane, ScrollWindow and ScrollBar |
| TextView | A block of text, wrapped and cached |
| Status bar and indicators | StatusBar, ProgressBar, Spinner |
| Charts | Sparkline, BarChart, Gauge |
| File picker | Requesting a path, the places sidebar, filters and keys |
Guides
| Page | What it covers |
|---|---|
| Localization | The generator that gives every string a name, and ArlecchinoStrings for the chrome |
| Diagnostics | The log overlay, notifications, and the report to attach to a bug |
| Testing | ArlecchinoTestHost, FakeTerminal, FrameText |
| Packages and building | What ships in which package, versioning, CI, benchmarks |
Releases
| Page | What it covers |
|---|---|
| Migrating to 2026.8.1 | What a 5.0 application edits: the notification, and the switch that showed the keys |
| Migrating to 5.0 | The keys a 4.x application reads, now that a binding is not a ConsoleKeyInfo |
| What's new in 4.0 | Every string gets a name, a dialog draws itself, namespaces follow their folders |
| Migrating to 4.0 | The using lines a 3.x application needs, and one quiet behavior change |
| What's new in 3.0 | Pictures, a terminal that is asked what it can do, panes that share a line |
| Migrating to 3.0 | The five members 2.x lost, all of them about typing |
| What's new in 2.0 | The three breaking changes, and what came with them |
| Migrating to 2.0 | The edits an application written against 1.x needs |
| API reference | Every public type, generated from the assemblies |
Where things live
| Assembly | Namespaces | Contents |
|---|---|---|
Arlecchino.Core | Arlecchino, Arlecchino.Rendering, Arlecchino.Input, Arlecchino.Atoms | Surface, SurfaceRegion, Atom, KeyText, IArlecchinoTerminal — the renderer, no DI |
Arlecchino | Arlecchino.Hosting, Arlecchino.Navigation, Arlecchino.Commands, Arlecchino.Modals, Arlecchino.State, Arlecchino.Views, Arlecchino.Forms, Arlecchino.Focus, Arlecchino.Widgets, Arlecchino.Diagnostics | views, navigation, modals, commands, forms, widgets, hosting, the file picker |
Arlecchino.Pictures | Arlecchino.Pictures | PictureFormats, PictureLimits — PNG, JPEG, BMP, Netpbm, QOI and Targa read into pixels |
Arlecchino.Testing | Arlecchino.Testing | ArlecchinoTestHost, FakeTerminal, FrameText — the headless host for tests |
Arlecchino.Generators | — | the incremental generator, shipped inside the Arlecchino package |
Four of those namespaces hold enough to be worth dividing, and since 4.0.0 the divisions are real
namespaces rather than folders nobody outside the repository can see:
| Namespace | Divided into |
|---|---|
Arlecchino.Modals | .Asking (text, number), .Choosing (choice, palette), .Setting (slider, toggle, color, date, time), .Telling (message, notification) |
Arlecchino.Widgets | .Lists (list, table, tree, tabs, scrolling), .Pictures, .Readouts (charts, indicators, status bar, text view) |
Arlecchino.Rendering | .Colors (theme, palette, color types), .Text (widths, joinery, symbols), .Terminals (capabilities, probe, image protocol) |
Arlecchino.Atoms | .Local, .Tracked, .Collections |
What each of them keeps is the vocabulary every file reaches for anyway: Modal and ModalFrame,
Surface and SurfaceRegion, Margin and Align, Atom and the store interfaces.
What changed between versions is in the changelog.