Jumbee.Console
0.1.7
dotnet add package Jumbee.Console --version 0.1.7
NuGet\Install-Package Jumbee.Console -Version 0.1.7
<PackageReference Include="Jumbee.Console" Version="0.1.7" />
<PackageVersion Include="Jumbee.Console" Version="0.1.7" />
<PackageReference Include="Jumbee.Console" />
paket add Jumbee.Console --version 0.1.7
#r "nuget: Jumbee.Console, 0.1.7"
#:package Jumbee.Console@0.1.7
#addin nuget:?package=Jumbee.Console&version=0.1.7
#tool nuget:?package=Jumbee.Console&version=0.1.7
Jumbee.Console
About
Jumbee.Console is a .NET library for advanced TUIs that focuses on performance and usability. Inspired by libs like ratatui and Textual, it tries to provide a high-performance retained-mode library that is easy-to-use with idiomatic .NET GUI and Task patterns, while flexible enough to create different types of TUI applications from news readers to animated dashboards to IDEs to agent harnesses to graphics apps.
Features
- 100% managed AOT-compatible code.
- Retained-mode GUI framework with an API designed to be easy to use and extend.
- Sub-ms frame rendering times and minimal CPU consumption even with complex displays like multi-tab document editing and syntax highlighting.
- Uses modern terminal features: ANSI/VT control sequences, 24-bit colour, SGR-encoded mouse (mode 1006) with motion tracking, bracketed paste (mode 2004), focus reporting (mode 1004), and the alternate-screen buffer (mode 1049).
- Also support legacy non-ANSI terminal emulators like the classic Windows console.
- Uses Spectre.Console-compatible markup, styles, text rendering, and widgets in a retained-mode rendering pipeline.
- Supports both fixed-width layouts like
Gridand flexible, resizable layouts likeDockPanel,HorizontalStack,VerticalStack, resizableSplitPanel. - Large set of common GUI controls: menus, buttons, trees, text inputs with autocomplete, modal dialog windows, etc...., supports easy composition of controls.
- Control frames support adornments like titles, borders, margins, and scrollbars.
- Cross-platform 100% managed code terminal-emulator.
- Multi-tab editor that supports C#, JavaScript, C++, Markdown + a dozen other languages.
- Split-pane interactive editors with preview for Markdown, AsciiDoc, Mermaid documents, Mermaid embedded in Markdown.
- Visualization and graphics: Many different types of plots and graphs like candlestick & heatmap plots & bar/run charts, world maps, sub-cell drawing canvas and shapes, 3D texture rendering, and support for animation.
- Flexible themes that support styling both colors and glyphs independently.
- Headless snapshot testing: render any control or layout to text or PNG without a real terminal.
Getting Started
dotnet add package Jumbee.Console
A first app — a label and a button that increments a counter:
using Jumbee.Console;
using static Jumbee.Console.Color; // import the static colour names
var count = 0;
var label = new TextLabel(TextLabelOrientation.Horizontal, "Count: 0", Cyan1);
var button = new Button("Increment");
button.Activated += (_, _) =>
{
count++;
label.Text = $"Count: {count}";
};
// One column, two rows: the label above the button.
var root = new Grid(
columnWidths: [30],
rowHeights: [1, 3],
controls:
[
[label],
[button],
]);
UI.RegisterHotKey(UI.HotKeys.Escape, UI.Stop); // Esc quits (Ctrl+Q also quits by default)
UI.SetFocus(button); // focus it so Enter/Space activates
// Start the UI. Mouse/hover need a VtInputSource or omit for keyboard only.
// Returns a task.
var t = UI.Start(root, width: 34, height: 6, input: new VtInputSource(anyMotion: true));
// Wait for the UI to stop.
t.Wait();
See GETTING-STARTED.md and the documentation.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- NTokenizers (>= 6.1.1)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Jumbee.Console:
| Package | Downloads |
|---|---|
|
Jumbee.Console.Snapshot
Headless snapshot testing for Jumbee.Console TUIs: render controls to text or PNG without a real terminal, for unit tests and visual verification. |
|
|
Jumbee.Console.Documents
Document viewers and editors for Jumbee.Console: Markdown, AsciiDoc, and Mermaid diagram rendering and interactive editing controls for TUIs. |
GitHub repositories
This package is not used by any popular GitHub repositories.
# Changelog
## 0.1.7
### Added
- **`ProgressBar` control** — a composable, themeable single-row task-progress display: a settable description, a smooth sub-cell fill bar, and optional percentage, elapsed/remaining-time and spinner columns, plus an indeterminate pulse for work whose total isn't known.
### Fixed
- **Framed controls now render their frame inside a `VerticalStackPanel` / `HorizontalStackPanel`. A margin on a stacked control now reserves space as expected.
### Docs
- Added `/llms.txt` generation (per [llmstxt.org](https://llmstxt.org/)) to the API-docs script — a curated, link-listed index of the docs and public API for LLM tooling.
## 0.1.6
### Added
- **`PlotPalette`** (`Jumbee.Console.Styles`) and **`IStyleTheme.PlotSeries`** — plot colours are now themeable: the axis, grid, tick and surface chrome plus the series palette come from the active theme instead of being passed per call, so a runtime theme switch re-colours existing plots.
- **`Plot.DamageTracking`** — opt-in partial redraw. The plot reports only the sub-rectangles a draw actually changed and the compositor skips the rest; roughly 5× off the composite for a sparse figure. Off by default — see the remarks on the property for when it pays and when it costs.
- **`ConsolePlot`: axis ticks can be set to `0`**, which removes that axis's grid lines and labels.
### Changed
- **`TextLabel` takes its colours from `IStyleTheme.LabelText`** (both foreground and background) until one is set explicitly. Colours passed to the constructor still win and now register as theme overrides, so a later theme switch re-colours only the labels that never asked for a colour. A theme supplying a background lets labels sit on a coloured strip without every caller passing one.
### Fixed
- **`CompositeControl` swallowed clicks on display composites.** A composite that opted into the mouse (`WantsMouse`) but whose children were not themselves focusable or mouse-listening produced cells with no listener, so a click anywhere over such a child never reached the composite. Those cells now carry the composite's own listener, restoring click-to-focus for panes like a plot; a child with its own listener is unaffected.
- `ConsolePlot`: custom tick values are honoured, and `Clear` no longer rewrites the whole buffer.
### Docs
- Documented the **cost model of damage tracking**, not just its benefit: it narrows what the compositor *scans* and never what the terminal *receives*, and because the scan it replaces is a linear buffer walk while damage bookkeeping is scattered, break-even needs the changing region to be a small fraction of the control — see `Control.TracksDamage` and "When damage tracking pays" in `docs/internal/Rendering Model.md`.
### Examples
- **New AudioScope demo** — a real-time oscilloscope, spectroscope and vectorscope over one shared audio source. Fully managed and cross-platform: MP3/WAV decode through NLayer, capture through WASAPI (Windows) or ALSA (Linux), with device selection, loopback, mono, `--overlap`, `--tick` and four colour schemes.
- Both Docker images gained an `audio-scope` target with a bundled sample track, and now ship the ALSA runtime so `audio-scope live` works on a Linux host given `--device /dev/snd`.
## 0.1.5
### Added
- **`Color.FromHexString`** — parses a hex colour string (e.g. `"#FF8800"`) into a `Jumbee.Console.Color`.
- **24-bit (true-color) support in ConsolePlot** — plot chrome and series take full RGB `Jumbee.Console.Color` values.
- `Plot` **screen-anchored axis titles** — the Y title pins to the top-left and the X title to the bottom-right, so they stay put as the axes rescale.
### Changed
- Performance optimizations for `Plot` control.
- **`UI.Start`: the frame-rate parameter is now `fps`** (frames per second) instead of `paintInterval`
- `Overlay` and `TextLabel` are now `sealed`.
### Fixed
- Fixed a latent crash when drawing **scatter points outside a fixed axis range** — such a point mapped past the plot buffer and threw `IndexOutOfRangeException`; it is now correctly clipped.
- UI/threading robustness: self-heal a UI run that was previously hard-killed, plus assorted input/UI/threading fixes.
## 0.1.4
### Fixed
- `MarkdownViewer` now **word-wraps paragraph text** to the control width. Previously a paragraph wider than the view clipped at the right edge and dropped everything past the first row (its doc already claimed it "reflows to the control width"). Implemented via a new opt-in `wrapWords` mode on `AnsiConsoleBuffer` (word-boundaried, with a character-level fallback for an over-long word); other controls are unaffected.
- The package now bundles the **XML documentation** of its private assemblies (`Jumbee.Console.Styles`, the Spectre.Console fork, ConsolePlot, …) alongside their DLLs in `lib/`. Previously only the DLLs shipped, so the theming/`Color`/`IStyleTheme`/`IGlyphTheme` API (in `Jumbee.Console.Styles`) and the bundled Spectre types had **no IntelliSense/doc surface** for consumers. (The bundling target's `.xml` match never fired because the XML doc copies don't carry `ReferenceSourceTarget=ProjectReference`.)
### Added
- `UI.HotKeys.Char(char)` — builds a `ConsoleKeyInfo` for a bare letter, digit, punctuation, or space key so it can be registered as a global hotkey (e.g. `UI.RegisterHotKey(UI.HotKeys.Char('q'), UI.Stop)`). It mirrors the input decoder exactly — including that punctuation keys (e.g. `/`) carry key code `0` with the character — so a registered hotkey matches a real keypress, and the same value drives a headless `routeGlobal` snapshot test.
- `Tree.SelectionChanged` event — raised whenever the highlighted node changes (arrow/vim keys, Home/End/PageUp/PageDown, or a mouse click), mirroring `ListBox.SelectionChanged`. Lets a detail pane follow tree navigation instead of only reacting to `NodeActivated` (leaf Enter/double-click).
- `TreeGuide.None` — a connector-less tree where hierarchy is shown by indentation (and node glyphs) alone.
- `Tree.TreeNode.Tag` and `ListBox.ListBoxItem.Tag` — an `object?` slot for arbitrary application data, so a node/row can map back to its domain object without a side dictionary.
### Changed
- `Tree.TreeNode.UpdateTree()` is now `public` (was `protected`) — it appeared in the docs but wasn't callable (`CS0122`). It forces a redraw of the owning tree, for the rare case a mutation didn't go through a property setter.
### Docs
- Documented that `ConsoleSnapshot.ToTextAfter`/`RenderAfter` deliver keys to the `control` argument itself, not to whatever `UI.SetFocus` last targeted — pass the control that actually changes (for a composite app, the specific child under test, not the root).
- Refreshed the "Snapshot Testing" internals page to the current input API (`routeGlobal`, `UI.HotKeys.Char`) and cross-linked the getting-started "Testing without a terminal" guide. The getting-started hotkey examples now use `UI.HotKeys.Char`; the previous punctuation example built the key with `ConsoleKey.Oem2`, which does not match a real `/` keypress.
- `UI.RegisterHotKey`: documented that the hotkey table is **process-global** (not scoped to a `UI.Start` root) — so a hotkey letter never reaches a focused text field (unregister/re-register around focus), and a second app instance re-registers the same keys (register/exercise one at a time in headless tests).
- `Grid`: documented its **fixed-cell** sizing (each value is an absolute cell count; the grid's size is their sum; `0` is a collapsed row/column, **not** fill-the-parent like `DockPanel`) — use `DockPanel`/`SplitPanel` for proportional/fill layouts.
- `SplitPanel.MinFirst`: documented it clamps to ≥ 1, so `SplitPosition` can't reach 0 (a "fully collapsed" pane is a 1-cell sliver).
- Composite Controls: added the single-child idiom (`SetContent(new Boundary(child))`).
- Troubleshooting: added the `Jumbee.Console.Tree` vs `Spectre.Console.Tree` name-ambiguity (`CS0104`) fix, and clarified that `MarkdownViewer` lives in core `Jumbee.Console` while the other viewers are in `Jumbee.Console.Documents`.
## 0.1.3
### Changed
- `ConsoleSnapshot.Key(key, …)` now fills in `KeyChar` for letter and digit keys (lowercase, uppercase under Shift, the control char under Ctrl), so a simulated key matches a hotkey registered the natural way (a bare letter). Previously it left `KeyChar='\0'`, so `ToTextAfter(…, routeGlobal: true)` silently failed to fire bare-letter global hotkeys. Non-character keys (arrows, function keys) are unchanged.
### Docs
- Documented that text snapshots (`ConsoleSnapshot.ToText`) don't capture colour or decoration — assert colour with `SavePng`/`ToImage`, or render a visible marker.
- Documented the runtime-reconfiguration pattern on `UI.Layout` (read-only): for a full-screen "zen" toggle, collapse a `SplitPanel` pane via `SplitPosition` or reassign `DockPanel.DockedControl`/`FillControl`, rather than swapping the root.
## 0.1.2
### Added
- `UI.SendInput(target, key, routeGlobal)` — an opt-in overload that runs the global hotkey dispatch (keys registered with `UI.RegisterHotKey`) before routing to the focused control, mirroring the live input path. Backward-compatible; existing calls route straight to the control as before.
- `Jumbee.Console.Snapshot`: `ConsoleSnapshot.RenderAfter` and `ToTextAfter` now accept a `routeGlobal` flag, so a headless snapshot test can exercise an app's global keybindings, not just control-routed input. Build the simulated key the same way the hotkey was registered so it compares equal.
### Changed
- The bundled package README now includes a runnable first-app example and a note about the private Spectre.Console fork: do not also reference the upstream `Spectre.Console` NuGet package (the assembly identities collide and the build fails with `CS1704`).
## 0.1.1
- Initial public release.