HeadlessPresentationAdapter

Namespace: Hex1b

Assembly: Hex1b.dll

A presentation adapter that discards output and provides no input. Use this for headless/testing scenarios where no actual terminal I/O is needed.

public sealed class HeadlessPresentationAdapter : IHex1bTerminalPresentationAdapter, ITerminalReflowProvider, IAsyncDisposable, IDisposable

Inheritance

Object → HeadlessPresentationAdapter

Implements

• IHex1bTerminalPresentationAdapter
• ITerminalReflowProvider
• IAsyncDisposable
• IDisposable

Constructors

HeadlessPresentationAdapter(int, int, TerminalCapabilities?)

Creates a new headless presentation adapter with the specified dimensions.

Parameters:

• width (Int32): Terminal width in columns.
• height (Int32): Terminal height in rows.
• capabilities (TerminalCapabilities): Optional terminal capabilities. Defaults to .

public HeadlessPresentationAdapter(int width = 80, int height = 24, TerminalCapabilities? capabilities = null)

Properties

Capabilities

Capability hints that inform optimization strategies.

Returns: TerminalCapabilities

public TerminalCapabilities Capabilities { get; }

Height

Current terminal height in rows.

Returns: Int32

public int Height { get; }

ReflowEnabled

Gets whether reflow is enabled. When false, the terminal uses standard crop-and-extend resize behavior even though the adapter implements this interface. Defaults to true.

Returns: Boolean

public bool ReflowEnabled { get; }

ShouldClearSoftWrapOnAbsolutePosition

Gets whether absolute cursor positioning (CUP, HVP) should clear the flag on the current row's last cell.

Returns: Boolean

public bool ShouldClearSoftWrapOnAbsolutePosition { get; }

Width

Current terminal width in columns.

Returns: Int32

public int Width { get; }

Methods

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()

EnterRawModeAsync(CancellationToken)

Enter raw mode for proper input capture.

Parameters:

• ct (CancellationToken): Cancellation token.

Returns: ValueTask

public ValueTask EnterRawModeAsync(CancellationToken ct = default)

ExitRawModeAsync(CancellationToken)

Exit raw mode and restore normal terminal input handling.

Parameters:

• ct (CancellationToken): Cancellation token.

Returns: ValueTask

public ValueTask ExitRawModeAsync(CancellationToken ct = default)

FlushAsync(CancellationToken)

Flush any buffered output immediately.

Parameters:

• ct (CancellationToken): Cancellation token.

Returns: ValueTask

public ValueTask FlushAsync(CancellationToken ct = default)

GetCursorPosition()

Gets the current cursor position in the terminal. Returns (0, 0) if the position cannot be determined.

Returns: ValueTuple<Int32, Int32>

A tuple of (Row, Column), both 0-based.

public (int Row, int Column) GetCursorPosition()

ReadInputAsync(CancellationToken)

Receive input (keystrokes, mouse events as ANSI sequences) FROM the user.

Parameters:

• ct (CancellationToken): Cancellation token.

Returns: ValueTask<Byte>>

Raw input bytes from the user, or empty when disconnected.

public ValueTask<ReadOnlyMemory<byte>> ReadInputAsync(CancellationToken ct = default)

Reflow(ReflowContext)

Performs reflow of terminal content during a resize operation.

Parameters:

• context (ReflowContext): The current terminal state including screen buffer, scrollback, and cursor position.

Returns: ReflowResult

The reflowed terminal state with new buffer, scrollback, and cursor position.

public ReflowResult Reflow(ReflowContext context)

TriggerResize(int, int)

Triggers a resize event for testing purposes.

Parameters:

• width (Int32): New width.
• height (Int32): New height.

public void TriggerResize(int width, int height)

WithReflow(ITerminalReflowProvider)

Configures the reflow strategy for this adapter and enables reflow. By default, reflow is disabled and resize uses standard crop behavior.

Parameters:

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

Returns: HeadlessPresentationAdapter

This adapter for fluent chaining.

public HeadlessPresentationAdapter WithReflow(ITerminalReflowProvider strategy)

WriteOutputAsync(ReadOnlyMemory<byte>, CancellationToken)

Write rendered output TO the presentation layer (display).

Parameters:

• data (ReadOnlyMemory<Byte>): The output data to send to the display.
• ct (CancellationToken): Cancellation token.

Returns: ValueTask

public ValueTask WriteOutputAsync(ReadOnlyMemory<byte> data, CancellationToken ct = default)

Events

Disconnected

Raised when the presentation layer disconnects (e.g., terminal closed, WebSocket dropped).

Returns: Action

public event Action? Disconnected

Resized

Raised when the presentation layer is resized by the user.

Returns: Action<Int32, Int32>

public event Action<int, int>? Resized

Remarks

The headless adapter satisfies the presentation adapter interface but:

WriteOutputAsync discards all dataReadInputAsync blocks until cancelledRaw mode operations are no-ops

This is useful for:

Unit tests that verify workload behavior without terminal I/OIntegration tests with presentation filters (e.g., asciinema recording)CI/CD environments where no TTY is available

Optionally implements when a reflow strategy is configured via . This enables testing different terminal emulator reflow behaviors in headless mode.

Examples

await Hex1bTerminal.CreateBuilder()
    .WithHex1bApp(ctx => ctx.Text("Hello"))
    .WithHeadless()
    .WithDimensions(80, 24)
    .WithAsciinemaRecording("output.cast")
    .RunAsync();