Hwt1PresentationAdapter

Namespace: Hex1b

Assembly: Hex1b.dll

Presents authoritative terminal state to Hex1b's first-party browser client using HWT1.

public sealed class Hwt1PresentationAdapter : ICellImpactAwarePresentationAdapter, ITerminalLifecycleAwarePresentationAdapter, IHex1bTerminalPresentationAdapter, IAsyncDisposable, ITerminalReflowProvider

Inheritance

Object → Hwt1PresentationAdapter

Implements

• ICellImpactAwarePresentationAdapter
• ITerminalLifecycleAwarePresentationAdapter
• IHex1bTerminalPresentationAdapter
• IAsyncDisposable
• ITerminalReflowProvider

Constructors

Hwt1PresentationAdapter(int, int)

Creates an HWT1 presentation adapter with the initial grid dimensions.

Parameters:

• width (Int32): Initial width, from 20 to 300 columns.
• height (Int32): Initial height, from 10 to 100 rows.

public Hwt1PresentationAdapter(int width = 80, int height = 24)

Properties

AcknowledgementTimeout

Gets the maximum time the next frame read waits for the previous acknowledgement. Defaults to two minutes.

Returns: TimeSpan

public TimeSpan AcknowledgementTimeout { get; init; }

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; }

IsReadOnly

Gets or sets whether this view ignores client commands that modify the producer. Defaults to false.

Returns: Boolean

public bool IsReadOnly { get; set; }

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

DisposeAsync()

Disconnects this adapter and cancels pending frame, input, and acknowledgement waits.

Returns: ValueTask

An operation that completes after the view's HMP1 peer, if any, is disconnected.

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

HandleMessageAsync(ReadOnlyMemory<byte>, CancellationToken)

Processes one complete UTF-8 HWT1 client JSON message.

Parameters:

• utf8Json (ReadOnlyMemory<Byte>): An acknowledgement, resync, resize, requestPrimary, input, paste, key, mouse, viewport, selection, or copy message, at most 64 KiB.
• cancellationToken (CancellationToken): Cancels processing and workload input writes.

Returns: Task

A task that completes when the message has been handled.

public Task HandleMessageAsync(ReadOnlyMemory<byte> utf8Json, CancellationToken cancellationToken = default)

InvalidatePresentation()

Notifies the presentation that terminal state changed without producing output bytes.

public void InvalidatePresentation()

ReadFrameAsync(CancellationToken)

Reads the next complete HWT1 state frame.

Parameters:

• cancellationToken (CancellationToken): Cancels this read without acknowledging any frame.

Returns: ValueTask<Byte>>

The complete binary frame, whose memory remains valid after subsequent reads.

public ValueTask<ReadOnlyMemory<byte>> ReadFrameAsync(CancellationToken cancellationToken = default)

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)

TerminalCompleted(int)

Called when the terminal has completed execution.

Parameters:

• exitCode (Int32): The exit code from the terminal's run callback or workload.

public void TerminalCompleted(int exitCode)

TerminalCreated(Hex1bTerminal)

Called when the terminal instance is created and associated with this adapter.

Parameters:

• terminal (Hex1bTerminal): The terminal instance.

public void TerminalCreated(Hex1bTerminal terminal)

TerminalStarted()

Called when the terminal has started and is ready to process I/O.

public void TerminalStarted()

WithReflow(ITerminalReflowProvider)

Enables reflow when this adapter is attached directly to a terminal. By default, resize crops the screen without reflow.

Parameters:

• strategy (ITerminalReflowProvider): The reflow strategy; use for shell terminals.

Returns: Hwt1PresentationAdapter

This adapter for fluent configuration before terminal construction.

public Hwt1PresentationAdapter 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)

WriteOutputWithImpactsAsync(IReadOnlyList<AppliedToken>, CancellationToken)

Called when output is being sent to the presentation layer, with cell impact information.

Parameters:

• appliedTokens (IReadOnlyList<AppliedToken>): The applied tokens with their cell impacts.
• ct (CancellationToken): Cancellation token.

Returns: ValueTask

A task that completes when the output has been processed.

public ValueTask WriteOutputWithImpactsAsync(IReadOnlyList<AppliedToken> appliedTokens, 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

Attach one adapter to one terminal and one ordered, message-preserving connection. Send each result of as a complete binary message, and concurrently deliver client JSON messages to in transport order. The adapter owns projection, resources, acknowledgements, resync, and mode-aware input; the host owns transport, authentication, and terminal lifetime. No ASP.NET or WebSocket dependency is required. HWT1 is internal state transfer, not a supported contract for third-party frontend implementations. Keep the server and first-party client in sync and upgrade them together. The wire format may change without backward-compatibility or deprecation guarantees; its name and version field do not imply cross-release compatibility. This API is also experimental. The current client-requested profile uses 10x20 logical-pixel cells, 20..300 columns, and 10..100 rows. A directly attached supplies authoritative geometry and primary ownership instead; producer dimensions are not clamped to this request profile. Frames support up to 1024 columns, 512 rows, and 262144 total cells. Larger authoritative grids fail projection without resizing the producer. Reconnection requires a new adapter; resync repairs the existing connection only. Producer-backed views can be created with . Each connection owns its viewport and selection. Historical rendering is text-only, bounded to the producer's current grid; older, wider rows are cropped visually, but logical-line and normal multirow extraction retain their original widths and soft wraps. Resize, reflow, reset, and buffer switches invalidate selection coordinates explicitly. Erased or discarded selected rows also invalidate the whole selection. Output does not move a retained historical anchor. Keyboard input and paste clear selection and return live. Rewriting selected live text invalidates the selection before extension or copying; character writes and cell-level erases outside the selected span preserve its captured intent. Structural row operations conservatively invalidate selections touching affected rows. Selected text is bounded to 512 Ki UTF-16 code units (including padding before trimming). Word and logical-line expansion enforce this bound during traversal. An oversized selection is explicitly invalidated rather than copied partially. Frames also carry the captured , including an empty title. Title-only output can produce a frame with no changed cells. Titles follow the same coalescing and synchronized-output rules as other state; frames are not a lossless stream of individual title-setting sequences. Progress and shell-integration state use the same snapshot and coalescing rules. These fields are current even when the view is displaying historical text.