Hex1bTerminalBuilder

Namespace: Hex1b

Assembly: Hex1b.dll

A builder for creating and configuring instances.

public sealed class Hex1bTerminalBuilder

Inheritance

Object → Hex1bTerminalBuilder

Constructors

Hex1bTerminalBuilder()

Creates a new terminal builder.

public Hex1bTerminalBuilder()

Methods

AddPresentationFilter(IHex1bTerminalPresentationFilter)

Adds a presentation filter to the terminal.

Parameters:

• filter (IHex1bTerminalPresentationFilter): The filter to add.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder AddPresentationFilter(IHex1bTerminalPresentationFilter filter)

AddWorkloadFilter(IHex1bTerminalWorkloadFilter)

Adds a workload filter to the terminal.

Parameters:

• filter (IHex1bTerminalWorkloadFilter): The filter to add.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder AddWorkloadFilter(IHex1bTerminalWorkloadFilter filter)

Build()

Builds the terminal with the configured options.

Returns: Hex1bTerminal

A configured instance.

public Hex1bTerminal Build()

WithAsciinemaPlayback(string, double)

Configures the terminal to play back an asciinema (.cast) recording file.

Parameters:

• filePath (String): Path to the .cast file to play back.
• speedMultiplier (Double): Optional playback speed multiplier. Default is 1.0 (normal speed). Set to 2.0 for 2x speed, 0.5 for half speed, etc.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithAsciinemaPlayback(string filePath, double speedMultiplier = 1)

WithAsciinemaPlayback(string, out AsciinemaRecording, double)

Configures the terminal to play back an asciinema (.cast) recording file, with access to playback controls.

Parameters:

• filePath (String): Path to the .cast file to play back.
• recording (AsciinemaRecording): When this method returns, contains the recording instance for playback control.
• speedMultiplier (Double): Optional initial playback speed multiplier. Default is 1.0 (normal speed).

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithAsciinemaPlayback(string filePath, out AsciinemaRecording recording, double speedMultiplier = 1)

WithAsciinemaRecording(string, Action<AsciinemaRecorder>, AsciinemaRecorderOptions?)

Adds Asciinema recording with access to the recorder instance.

Parameters:

• filePath (String): Path to the output file (typically with .cast extension).
• capture (Action<AsciinemaRecorder>): Callback that receives the recorder instance for external control.
• options (AsciinemaRecorderOptions): Optional recording options.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithAsciinemaRecording(string filePath, Action<AsciinemaRecorder> capture, AsciinemaRecorderOptions? options = null)

WithAsciinemaRecording(string, AsciinemaRecorderOptions?)

Adds Asciinema recording to capture the terminal session.

Parameters:

• filePath (String): Path to the output file (typically with .cast extension).
• options (AsciinemaRecorderOptions): Optional recording options.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithAsciinemaRecording(string filePath, AsciinemaRecorderOptions? options = null)

WithDiagnostics(string?, bool)

Enables MCP diagnostics for this terminal, allowing external MCP tools to capture terminal state and inject input.

Parameters:

• appName (String): Optional application name for identification. Defaults to the entry assembly name.
• forceEnable (Boolean): When true, enables diagnostics even in Release builds. By default, diagnostics are automatically disabled in Release builds for security.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithDiagnostics(string? appName = null, bool forceEnable = false)

WithDimensions(int, int)

Sets the dimensions for headless terminals.

Parameters:

• width (Int32): Terminal width in columns.
• height (Int32): Terminal height in rows.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithDimensions(int width, int height)

WithHeadless()

Configures the terminal to run in headless mode without a real terminal. This is useful for testing where no actual terminal I/O is needed.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithHeadless()

WithHeadless(TerminalCapabilities)

Configures the terminal to use a headless presentation adapter with specific capabilities.

Parameters:

• capabilities (TerminalCapabilities): Terminal capabilities to use.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithHeadless(TerminalCapabilities capabilities)

WithHex1bApp(Func<Hex1bApp, Hex1bAppOptions, Func<RootContext, Hex1bWidget>>)

Configures the terminal to run a Hex1bApp with the specified widget builder.

Parameters:

• configure (Func<Hex1bApp, Hex1bAppOptions, RootContext, Hex1bWidget>>): A configuration function that receives the instance and for customization, and returns the widget builder function.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithHex1bApp(Func<Hex1bApp, Hex1bAppOptions, Func<RootContext, Hex1bWidget>> configure)

WithHex1bApp(Func<Hex1bApp, Hex1bAppOptions, Func<RootContext, Task<Hex1bWidget>>>)

Configures the terminal to run a Hex1bApp with full control over options, app capture, and async widget building.

Parameters:

• configure (Func<Hex1bApp, Hex1bAppOptions, RootContext, Hex1bWidget>>>): A configuration function that receives the instance and for customization, and returns an async widget builder function.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithHex1bApp(Func<Hex1bApp, Hex1bAppOptions, Func<RootContext, Task<Hex1bWidget>>> configure)

WithHex1bFlow(Func<Hex1bFlowContext, Task>, Action<Hex1bFlowOptions>?)

Configures the terminal to run a Hex1b Flow — a sequence of inline micro-TUI slices and optional full-screen TUI applications in the normal terminal buffer.

Parameters:

• flowCallback (Func<Hex1bFlowContext, Task>): Async callback that defines the flow steps. Use the flow context's for inline micro-TUIs and for full-screen apps.
• configureOptions (Action<Hex1bFlowOptions>): Optional callback to configure flow options (theme, etc.).

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithHex1bFlow(Func<Hex1bFlowContext, Task> flowCallback, Action<Hex1bFlowOptions>? configureOptions = null)

WithMcpDiagnostics(string?, bool)

Enables the diagnostics socket for this terminal.

Parameters:

• appName (String): Optional application name reported in diagnostics info.
• forceEnable (Boolean): When true, enables diagnostics even in Release builds.

Returns: Hex1bTerminalBuilder

This builder for chaining.

[Obsolete("Use WithDiagnostics() instead. This method will be removed in a future version.")]
public Hex1bTerminalBuilder WithMcpDiagnostics(string? appName = null, bool forceEnable = false)

WithMetrics()

Uses the default shared metrics instance.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithMetrics()

WithMetrics(Action<Hex1bMetricsOptions>)

Configures metrics options for OpenTelemetry instrumentation. Creates a new instance with the configured options.

Parameters:

• configure (Action<Hex1bMetricsOptions>): A callback to configure metrics options (e.g., enable per-node metrics).

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithMetrics(Action<Hex1bMetricsOptions> configure)

WithMetrics(Hex1bMetrics)

Sets a custom metrics instance for OpenTelemetry instrumentation.

Parameters:

• metrics (Hex1bMetrics): The metrics instance to use.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithMetrics(Hex1bMetrics metrics)

WithMouse(bool)

Enables mouse input for the Hex1bApp.

Parameters:

• enable (Boolean): Whether to enable mouse input. Defaults to true.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithMouse(bool enable = true)

WithPresentation(IHex1bTerminalPresentationAdapter)

Configures the terminal with a custom presentation adapter.

Parameters:

• adapter (IHex1bTerminalPresentationAdapter): The presentation adapter to use.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithPresentation(IHex1bTerminalPresentationAdapter adapter)

WithProcess(ProcessStartInfo)

Configures the terminal to run a process using standard .NET process primitives.

Parameters:

• startInfo (ProcessStartInfo): The process start info.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithProcess(ProcessStartInfo startInfo)

WithProcess(string, params string[])

Configures the terminal to run an arbitrary process using standard .NET process primitives.

Parameters:

• fileName (String): The executable to run.
• arguments (String[]): Command-line arguments for the process.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithProcess(string fileName, params string[] arguments)

WithPtyProcess(Action<Hex1bTerminalProcessOptions>)

Configures the terminal to run a PTY process with full options.

Parameters:

• configure (Action<Hex1bTerminalProcessOptions>): Action to configure the process options.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithPtyProcess(Action<Hex1bTerminalProcessOptions> configure)

WithPtyProcess(string, params string[])

Configures the terminal to run an arbitrary process with a PTY (pseudo-terminal) attached.

Parameters:

• fileName (String): The executable to run.
• arguments (String[]): Command-line arguments for the process.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithPtyProcess(string fileName, params string[] arguments)

WithReflow()

Enables terminal reflow with automatic strategy detection based on the running terminal emulator (via TERM_PROGRAM, WT_SESSION, etc.).

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithReflow()

WithReflow(ITerminalReflowProvider)

Enables terminal reflow with a specific strategy.

Parameters:

• strategy (ITerminalReflowProvider): The reflow strategy to use during resize operations.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithReflow(ITerminalReflowProvider strategy)

WithRemoteTerminal(Uri, out RemoteTerminalWorkloadAdapter)

Configures the terminal to connect to a remote terminal host over WebSocket, providing access to the adapter for advanced control.

Parameters:

• uri (Uri): WebSocket URI of the remote host's attach endpoint.
• adapter (RemoteTerminalWorkloadAdapter): When this method returns, contains the adapter instance for querying remote state (dimensions, leadership) or sending shutdown commands.

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithRemoteTerminal(Uri uri, out RemoteTerminalWorkloadAdapter adapter)

WithRemoteTerminal(Uri)

Configures the terminal to connect to a remote terminal host over WebSocket.

Parameters:

• uri (Uri): WebSocket URI of the remote host's attach endpoint (e.g. ws://localhost:8080/ws/attach).

Returns: Hex1bTerminalBuilder

This builder instance for fluent chaining.

public Hex1bTerminalBuilder WithRemoteTerminal(Uri uri)

WithScrollback(int, Action<ScrollbackRowEventArgs>?)

Enables a scrollback buffer that retains rows scrolled off the top of the terminal.

Parameters:

• capacity (Int32): Maximum number of lines to retain in the scrollback buffer. Default is 1000.
• onRowScrolledOff (Action<ScrollbackRowEventArgs>): Optional callback invoked each time a row enters the scrollback buffer.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithScrollback(int capacity = 1000, Action<ScrollbackRowEventArgs>? onRowScrolledOff = null)

WithTerminalWidget(out TerminalWidgetHandle)

Configures the terminal to use a as the presentation adapter. This allows embedding the terminal output within a TUI application using .

Parameters:

• handle (TerminalWidgetHandle): When this method returns, contains the handle that can be passed to ctx.Terminal(...).

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithTerminalWidget(out TerminalWidgetHandle handle)

WithTimeProvider(TimeProvider)

Sets the time provider for the terminal. Used for testing.

Parameters:

• timeProvider (TimeProvider): The time provider to use.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithTimeProvider(TimeProvider timeProvider)

WithWorkload(IHex1bTerminalWorkloadAdapter)

Configures the terminal with a custom workload adapter.

Parameters:

• adapter (IHex1bTerminalWorkloadAdapter): The workload adapter to use.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithWorkload(IHex1bTerminalWorkloadAdapter adapter)

WithWorkloadLogging(string, bool)

Adds a workload logging filter that writes all workload data to a file.

Parameters:

• filePath (String): Path to the log file.
• includeHexDump (Boolean): Whether to include hex dumps of raw bytes. Default true.

Returns: Hex1bTerminalBuilder

This builder for chaining.

public Hex1bTerminalBuilder WithWorkloadLogging(string filePath, bool includeHexDump = true)

Remarks

The builder provides a fluent API for configuring terminal workloads, presentation adapters, and filters. It supports multiple workload types including Hex1bApp, shell processes, and custom adapters.

Simple Hex1bApp:

await using var terminal = Hex1bTerminal.CreateBuilder()
    .WithHex1bApp((app, options) => ctx => ctx.Text("Hello, World!"))
    .Build();

await terminal.RunAsync();

Shell with recording:

await using var terminal = Hex1bTerminal.CreateBuilder()
    .WithShellProcess("/bin/bash")
    .WithAsciinemaRecording("session.cast")
    .Build();

await terminal.RunAsync();