Hex1b

Hex1b is a .NET library for building rich, interactive terminal user interfaces (TUI) with a React-inspired declarative API. Create beautiful console applications with widgets, layouts, theming, and more.

✨ Features

• Declarative UI - Build UIs using a widget tree pattern inspired by React and Flutter
• Widget Library - TextBlock, TextBox, Button, List, VStack, HStack, Splitter, and more
• Layout System - Flexible constraint-based layout with size hints (Fill, Content, Fixed)
• Theming - Built-in themes with customizable colors and styles
• Input Handling - Keyboard navigation, focus management, and shortcut bindings
• Reconciliation - Efficient diff-based updates to minimize terminal redraws

📦 Installation

dotnet add package Hex1b

🚀 Quick Start

Here's a simple "Hello World" application:

using Hex1b;
using Hex1b.Widgets;

using var cts = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) => { e.Cancel = true; cts.Cancel(); };

using var app = new Hex1bApp(
    ctx => Task.FromResult<Hex1bWidget>(
        new VStackWidget([
            new TextBlockWidget("Hello, Terminal!"),
            new ButtonWidget("Exit", () => cts.Cancel())
        ])
    )
);

await app.RunAsync(cts.Token);

🎨 Widgets

Hex1b provides a variety of built-in widgets:

Widget	Description
TextBlockWidget	Display static or dynamic text
TextBoxWidget	Editable text input with cursor and selection
ButtonWidget	Clickable button with label and action
ListWidget	Scrollable list with selection
VStackWidget	Vertical layout container
HStackWidget	Horizontal layout container
SplitterWidget	Resizable split pane layout

📐 Layout System

Hex1b uses a constraint-based layout system with size hints:

// Children with size hints: first fills available space, second sizes to content
new VStackWidget(
    [contentWidget, statusBarWidget],
    [SizeHint.Fill, SizeHint.Content]
);

Size Hints:

• SizeHint.Fill - Expand to fill available space
• SizeHint.Content - Size to fit content
• SizeHint.Fixed(n) - Fixed size of n units

🎹 Input Bindings

Define keyboard bindings at any level of your widget tree:

var widget = new SplitterWidget(left, right, 25) with
{
    InputBindings = [
        InputBinding.Ctrl(Hex1bKey.S, Save, "Save"),
        InputBinding.Ctrl(Hex1bKey.Q, Quit, "Quit"),
    ]
};

Picking portable bindings. Different terminals intercept different combos before they reach Hex1b (e.g. Windows Terminal eats Ctrl+Shift+↑/↓ for scroll, GNOME Terminal eats Ctrl+Shift+T/N/W for tab/window management). See Keybinding Portability on hex1b.dev for the per-terminal interception matrix and recommendations, and use the KeyBindingTester sample to confirm what actually fires on your target terminals.

🎨 Theming

Apply built-in themes or create your own:

using var app = new Hex1bApp(builder, new Hex1bAppOptions { Theme = Hex1bThemes.Sunset });

🏗️ Architecture

Hex1b follows a widget/node separation pattern:

1. Widgets - Immutable configuration objects describing what to render
2. Nodes - Mutable render objects that manage state and layout
3. Reconciliation - Efficient diffing to update nodes when widgets change

┌─────────────────────────────────────────────────────────────┐
│                      Hex1bApp.RunAsync()                    │
├─────────────────────────────────────────────────────────────┤
│  1. Build widget tree (your code)                           │
│  2. Reconcile → Update node tree                            │
│  3. Layout → Measure and arrange nodes                      │
│  4. Render → Draw to terminal                               │
│  5. Wait for input → Dispatch to focused node               │
│  6. Repeat from step 1                                      │
└─────────────────────────────────────────────────────────────┘

🧪 Samples

The samples/ directory contains example applications demonstrating various features:

• Cancellation - Master-detail contact editor with save/cancel functionality
• RemoteTerminalAuthDemo - Connects a client to a bearer-protected remote terminal server

Running Samples with Aspire

This repository is set up with Aspire to make it easy to run and test sample applications:

dotnet run --project apphost.cs

Note: Aspire doesn't natively support interactive terminal applications, but this project explores techniques to make TUI app development and testing in Aspire possible.

🛠️ Development

Prerequisites

• .NET 10.0 SDK
• A terminal emulator with good ANSI support
• For source builds on Unix: build-essential on Ubuntu/Debian, or Xcode Command Line Tools on macOS (xcode-select --install).

Building

dotnet build src/Hex1b/Hex1b.csproj

Samples build their native interop dependency automatically. For example:

dotnet run --project samples/KgpCloudDemo

See Contributing for native build prerequisites and cross-publishing.

Running Tests

dotnet test tests/Hex1b.Tests/Hex1b.Tests.csproj

Project Structure

hex1b/
├── src/
│   └── Hex1b/              # Main library
│       ├── Layout/         # Constraint-based layout system
│       ├── Nodes/          # Render nodes (mutable, stateful)
│       ├── Widgets/        # Widget definitions (immutable config)
│       ├── Theming/        # Theme system and built-in themes
│       └── Input/          # Keyboard input and bindings
├── samples/                # Example applications
├── docs/                   # Architecture & reference documentation
├── tests/
│   └── Hex1b.Tests/        # Unit tests
└── apphost.cs              # Aspire app host for running samples

📚 Documentation

Full documentation lives at hex1b.dev. Highlights:

• Input Handling — focus, routing, declarative bindings, and Vim/Emacs-style remap walkthrough.
• Keybinding Portability — per-terminal interception matrix (Windows Terminal, ConPTY, macOS Terminal.app, iTerm2, Ghostty, kitty, GNOME Terminal, Ptyxis, xterm, tmux, ssh) plus cross-cutting ANSI protocol limits.
• Terminal Emulator — using the embedded terminal widget.
• API Reference — generated namespace docs.

In-repo guides and architecture notes (not on the website):

• docs/tape.md — VHS Tape parsing, terminal automation, and asciicast / golden-text capture.
• docs/terminal.md — Presentation/workload adapter architecture.
• docs/child-process-arch.md — Child process / PTY architecture.
• docs/muxer-protocol.md — Muxer wire protocol.

For the manual portability harness used to generate the per-terminal data, see samples/KeyBindingTester.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

For AI coding agents, see AGENTS.md for context and conventions.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• Spectre.Console - Beautiful console output
• Terminal.Gui - Cross-platform terminal UI toolkit
• Aspire - Cloud-ready stack for .NET