Hex1bTerminal

Namespace: Hex1b

Assembly: Hex1b.dll

A virtual terminal that bridges workload and presentation layers, with optional screen buffer capture for testing and debugging.

public sealed class Hex1bTerminal : IDisposable, IAsyncDisposable

Inheritance

Object → Hex1bTerminal

Implements

• IDisposable
• IAsyncDisposable

Constructors

Hex1bTerminal(Hex1bTerminalOptions)

Creates a new terminal with the specified options.

Parameters:

• options (Hex1bTerminalOptions): Terminal configuration options.

public Hex1bTerminal(Hex1bTerminalOptions options)

Properties

IconName

Gets the current icon name set by OSC 0 or OSC 1 sequences.

Returns: String

public string IconName { get; }

WindowTitle

Gets the current window title set by OSC 0 or OSC 2 sequences.

Returns: String

public string WindowTitle { get; }

Methods

CreateBuilder()

Creates a new terminal builder for fluent configuration.

Returns: Hex1bTerminalBuilder

A new instance.

public static Hex1bTerminalBuilder CreateBuilder()

CreateSnapshot()

Creates an immutable snapshot of the current terminal state. Useful for assertions and wait conditions in tests. Automatically flushes pending output before creating the snapshot.

Returns: Hex1bTerminalSnapshot

public Hex1bTerminalSnapshot CreateSnapshot()

CreateSnapshot(int, ScrollbackWidth, TerminalCell?)

Creates an immutable snapshot of the current terminal state, optionally including lines from the scrollback buffer.

Parameters:

• scrollbackLines (Int32): Number of scrollback lines to include above the visible area. Zero means no scrollback.
• scrollbackWidth (ScrollbackWidth): Controls how scrollback line widths are adapted in the snapshot.
• voidCell (Nullable<TerminalCell>): The cell used to fill void regions where the snapshot is wider than a row's original content. Defaults to (a space with no attributes).

Returns: Hex1bTerminalSnapshot

A snapshot with scrollback lines prepended above the visible content.

public Hex1bTerminalSnapshot CreateSnapshot(int scrollbackLines, ScrollbackWidth scrollbackWidth = ScrollbackWidth.CurrentTerminal, TerminalCell? voidCell = null)

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

Returns: ValueTask

A task that represents the asynchronous dispose operation.

public ValueTask DisposeAsync()

Resize(int, int)

Resizes the terminal, preserving content where possible. If the presentation adapter implements , soft-wrapped lines are re-wrapped to the new width.

Parameters:

• newWidth (Int32):
• newHeight (Int32):

public void Resize(int newWidth, int newHeight)

RunAsync(CancellationToken)

Runs the terminal until the workload exits.

Parameters:

• ct (CancellationToken): Cancellation token to stop the terminal.

Returns: Task<Int32>

The exit code from the workload (0 = success).

public Task<int> RunAsync(CancellationToken ct = default)

SendInputAsync(byte[], CancellationToken)

Sends raw input bytes to the workload.

Parameters:

• bytes (Byte[]): The bytes to send.
• ct (CancellationToken): Cancellation token.

Returns: Task

public Task SendInputAsync(byte[] bytes, CancellationToken ct = default)

Events

IconNameChanged

Event raised when the icon name changes (OSC 0 or OSC 1).

Returns: Action<String>

public event Action<string>? IconNameChanged

WindowTitleChanged

Event raised when the window title changes (OSC 0 or OSC 2).

Returns: Action<String>

public event Action<string>? WindowTitleChanged

Remarks

Hex1bTerminal serves as a mediator between:

• the raw I/O layer (console, WebSocket, etc.) - the workload (app, process, etc.)

The workload adapter is provided by the caller. For Hex1bApp, use . This design keeps the terminal decoupled from specific workload types.

When no presentation adapter is provided (null), the terminal operates in "headless" mode, capturing all output to the screen buffer. This is ideal for testing.

Examples

Production usage:

var presentation = new ConsolePresentationAdapter();
var workload = new Hex1bAppWorkloadAdapter(presentation.Width, presentation.Height);
var terminal = new Hex1bTerminal(presentation, workload);
var app = new Hex1bApp(workload, ctx => ctx.Text("Hello"));
await app.RunAsync();

Testing usage:

var workload = new Hex1bAppWorkloadAdapter(80, 24);
var terminal = new Hex1bTerminal(workload);  // headless
var app = new Hex1bApp(workload, ctx => ctx.Text("Hello"));
// ... run and test ...
Assert.True(terminal.ContainsText("Hello"));