Hex1b

The Hex1b library is organized into several functional namespaces. Use these to locate specific functionality for building your TUI:

• Hex1b: Core application types, extension methods, and the render context.
• Hex1b.Widgets: Widget records used to describe UI components.
• Hex1b.Nodes: Mutable node classes that manage state and rendering logic.
• Hex1b.Layout: Layout primitives including Constraints, Size, Rect, and SizeHint.
• Hex1b.Input: Input handling, key bindings, and input routing.
• Hex1b.Events: Event argument types for widget interactions.
• Hex1b.Theming: The theme system for customizing colors and characters.
• Hex1b.Tokens: Design tokens for consistent theming.
• Hex1b.Animation: Animation timers and utilities.
• Hex1b.Automation: Terminal automation, input sequences, and snapshot testing.
• Hex1b.Surfaces: Low-level surface rendering and cell manipulation.

Testing Hex1b applications is achieved through a combination of a virtual terminal, an input sequence builder, and an automator. This approach allows you to simulate user interactions in a headless environment and verify application state.

Core Testing Components

• Hex1bTerminal(width, height): A virtual terminal used to capture screen output and provide a workload adapter.
• terminal.WorkloadAdapter: The bridge used to connect your Hex1bApp to the virtual terminal.
• Hex1bTerminalInputSequenceBuilder: A fluent API used to construct complex sequences of keyboard and mouse inputs.
• Hex1bTerminalAutomator: An imperative async API designed for complex tests requiring rich error diagnostics.
• terminal.GetScreenText(): An API to retrieve the current screen content as a string (automatically flushes the buffer).

// The general testing pattern
using var terminal = new Hex1bTerminal(80, 24);
using var app = new Hex1bApp(/* ... */);

var sequence = new Hex1bInputSequenceBuilder()
    .Type("Hello")
    .Enter()
    .Build();

await sequence.ApplyAsync(terminal);

StringAssert.Contains(terminal.GetScreenText(), "Hello");

The terminal manages two types of anchors in the scroll history:

1. Shell Marks: These are command ticks generated by the shell/application using OSC 133 output. They represent specific points in the command history (Prompt, Input, Executing, or Finished). Command marks require the shell to explicitly provide them; they are not automatically inferred.
2. Bookmarks: User-defined anchors that point to a specific row. Unlike shell marks, bookmarks are per-view and are not transferred between sessions or relayed via HMP1.

Navigation

• scrollToMarker: Use this API to jump to a specific mark. It supports producer reflow. If an anchor is unavailable, evicted, or expired, the jump will be rejected rather than jumping to an unrelated row.
• Marks (N) Menu: A menu in the window title bar that lists retained shell marks and bookmarks with clickable row locations and exit statuses.

HStackWidget supports three sizing modes for its children:

1. Content Sizing (Default): Children take up exactly the width required by their content.
2. Fill Sizing: Using .Fill() allows a child to expand and consume remaining available space. If multiple children use .Fill(), the space is distributed evenly among them.
3. Fixed Sizing: Using .FixedWidth(int) forces a child to take a specific width in cells.

To distribute space proportionally among multiple filling children, use .FillWidth(int) (Weighted Fill).

// Content Sizing
ctx.HStack(h => [
    h.Text("Short"),
    h.Text("Longer Text")
]);

// Fill Sizing (Even distribution)
ctx.HStack(h => [
    h.Text("Left").Fill(),
    h.Text("Right").Fill()
]);

// Fixed Sizing
ctx.HStack(h => [
    h.Text("Label").FixedWidth(20),
    h.TextBox(value, onChange).Fill()
]);

// Weighted Fill (Proportional distribution)
ctx.HStack(h => [
    h.Panel(sidebar).FillWidth(1), // Gets 1/3 of space
    h.Panel(main).FillWidth(2)     // Gets 2/3 of space
]);

Hex1b uses two distinct fluent surfaces to separate host configuration from UI description. It is critical to use the correct naming convention to ensure code readability and correct behavior.

1. Terminal Builder (Hex1bTerminalBuilder)

Used to wire up the host process (terminal plumbing, adapters, recording, mouse, etc.). This is configured once at startup.

• Naming Convention: All methods must use the With* prefix.
• Behavior: Mutates a builder configuration object and returns the same builder for chaining.
• Example: terminal.WithMouse().WithHex1bApp(...)

2. Widget Composition (WidgetContext<T> and widget instances)

Used to describe the UI tree on every render pass. Widgets are immutable records.

• Naming Convention: Use bare verb-nouns (no With* prefix).
• Behavior: Returns a new widget value (or a new instance via an extension method).
• Example: context.Border(b => [...]).Title("Hi")

Rule of thumb: If you are working with a widget and want to set a property, do not use WithTitle(...); use Title(...) instead.

// Correct Terminal Builder usage
terminal.WithMouse().WithHex1bApp(...);

// Correct Widget usage
context.Border(b => [ b.Text("Hello") ]).Title("My Border");