Icod.Terminal 1.7.0

Icod.Terminal

Icod.Terminal is the managed, cross-platform live-terminal session layer for the Icod library family. It sits between Icod.TermInfo and higher-level consumers such as Icod.DCurses, terminal-aware command-line tools, monitors, editors, pagers, and REPLs.

Status

1.7.0 is the current development release line. It builds on the 1.5 control-language normalization and 1.6 complete-CSI foundation and adds the first raster graphics backend: Sixel over DCS.

The 1.7 program now provides:

• canonical internal DCS construction shared by existing DCS query families;
• byte-stable DECRQSS and XTGETTCAP request construction;
• a bounded deterministic Sixel grammar, quantizer, and encoder;
• committed streaming Sixel output through the existing session-output serialization boundary;
• evidence-based Sixel capability detection using Primary DA attribute 4 without terminal-brand heuristics;
• the first public backend-neutral raw raster model;
• TerminalSession.DisplayRasterAsync(...) as the first semantic raster-display operation;
• a new reviewed public API baseline shared identically by net8.0, net9.0, and net10.0.

The stable 1.0 architecture, ownership, lifecycle, input/query, restoration, security, and compatibility guarantees remain the floor for the 1.x line. Existing OSC, CSI, DCS-query, presentation, color, input-protocol, and notification APIs retain their documented behavior.

Release and design documents:

• Icod.Terminal 1.7.0 release notes
• 1.7.0 development roadmap
• D170 DCS construction contract
• D171 existing DCS reconciliation
• D172 Sixel grammar and codec
• D173 common raw raster model
• D174 deterministic Sixel quantization
• D175 Sixel encoder
• D176 committed streaming graphics output
• D177 Sixel capability evidence
• D178 first semantic raster-display operation
• D179 1.7.0 hardening/package/documentation closure
• Public API Baseline 1.7
• Control-language normalization and graphics roadmap
• Changelog

Installation

dotnet add package Icod.Terminal --version 1.7.0

The package targets:

net8.0
net9.0
net10.0

and depends on Icod.TermInfo 1.10.0 and Icod.Timing 1.0.0.

Architecture

Icod.TermInfo
      ^
      |
Icod.Terminal
      ^
      |
Icod.DCurses
      ^
      |
terminal applications

Icod.TermInfo remains the immutable terminal-capability authority. Icod.Terminal owns the live terminal conversation: endpoint observation, terminal modes, input decoding, lifecycle, active query routing, semantic output, protocol framing/routing, raster output, and scoped/reversible terminal state. Icod.DCurses owns the higher-level virtual-screen/curses presentation model.

PTY/process hosting remains orthogonal to this package.

Quick start

using Icod.Terminal;

await using TerminalSession session = await TerminalSession.OpenAsync(
	new TerminalSessionOptions {
		InputMode = TerminalInputMode.CBreak,
		EchoInput = false
	}
);

await session.WriteTextAsync( "Terminal session ready.\r\n" );

TerminalEvent terminalEvent = await session.ReadEventAsync(
	TimeSpan.FromSeconds( 1 )
);

For a curses-style virtual screen, prefer Icod.DCurses rather than rebuilding windows/cells/diff policy directly over TerminalSession.

Raster graphics in 1.7

The public raster API is deliberately semantic and backend-neutral.

Raw raster formats

Rgb24      tightly packed R G B
Rgba32     tightly packed R G B A
Indexed8   one-byte palette indices + RGBA8 palette

Create an immutable owned raster snapshot with the factory matching your storage:

TerminalRasterImage image = TerminalRasterImage.CreateRgb24(
	2,
	1,
	[
		255, 0, 0,
		0, 0, 255
	]
);

The constructor/factory path copies caller storage, so asynchronous output cannot observe later mutation of the supplied buffers.

The public model exposes dimensions, pixel format, pixel count, and typed per-pixel color inspection. It intentionally does not expose mutable backing buffers or Sixel command data.

Displaying a raster

TerminalControlMutationResult result = await session.DisplayRasterAsync( image );
if ( !result.Succeeded ) {
	Console.Error.WriteLine( result.Message );
}

In version 1.7, the semantic raster operation is implemented by Sixel only. The session requires verified Sixel capability evidence before committing graphics output. If such evidence is not already available, it may issue the bounded Primary Device Attributes probe used by D177.

Primary DA attribute 4 verifies the Sixel backend. A valid DA response without 4, or probe silence/timeout, remains uncertainty rather than fabricated proof that Sixel is unsupported.

The Sixel backend preserves fully transparent and fully opaque raster semantics. Fractional alpha remains valid backend-neutral raster data, but version 1.7 returns controlled Unsupported when Sixel cannot preserve it rather than silently compositing against an invented background.

Raster bounds

The raw raster contract is bounded:

maximum dimension       16,384
maximum pixels          16 Mi
maximum owned pixel data 64 MiB
maximum indexed palette 256 entries

Quantization uses bounded work state and deterministic output. Sixel payloads are emitted as bounded segments rather than one complete encoded-image allocation.

Committed graphics output

Sixel output participates in the normal session output gate. Caller cancellation is honored before commitment. Once the DCS prefix has committed, ordinary caller cancellation is no longer allowed to truncate the control string; the transaction continues through its final ST and flush unless the transport itself fails.

Transport failure after commitment is surfaced to the caller. The library does not retry a partially written image or guess whether a terminator reached the terminal.

Version 1.7 deliberately does not expose:

• a generic raw DCS or Sixel writer;
• a public Sixel-backend selector;
• Sixel color-register manipulation;
• image placement/scaling options that cannot yet be preserved across backends;
• PNG/JPEG/GIF decoding;
• animation or persistent image identifiers.

Kitty Graphics is planned as a later backend behind the same semantic raster intent rather than as a replacement public image model.

Core 1.x guarantees

One authoritative input path

A live TerminalSession owns the only authoritative input reader for its transport. Ordinary consumers use:

• ReadEventAsync(...) for application input and lifecycle events;
• typed query operations for terminal responses.

Do not run a competing Console.Read*, stream read, or retained custom-transport read on the same live terminal conversation.

Bounded query routing

Queries share the same incremental input/router domain as application input. The contract includes bounded parser state, ambiguity-aware query serialization, finite caller timeouts, pre-emission versus post-emission cancellation semantics, bounded late-response ownership, and lifecycle query generations.

A timeout is not automatically proof that the terminal does not support a feature.

Reversible ownership

Scoped state uses leases where overlapping ownership matters. The 1.x documentation distinguishes:

1. exact restoration — a captured/observed external baseline is replayed exactly;
2. terminal-policy reset — control returns to terminal policy without claiming the exact previous value;
3. Icod-owned nested state — an outer library-owned value can be restored even when the pre-Icod state is not observable;
4. ephemeral metadata — explicit output with no lifecycle replay/restoration state.

TerminalSession.DisposeAsync() remains final cleanup/restoration authority for session-owned state. Version 1.7 additionally ensures teardown drains a committed Sixel transaction before output-state restoration proceeds.

Output serialization boundary

Use session semantic operations for ordinary terminal output. TerminalSession.Output remains available only as an advanced borrowed transport and is outside normal session serialization when used directly by callers.

WriteTerminalStringAsync(...) is intended for already-resolved terminfo capability strings; it is not a recommendation to construct arbitrary OSC/CSI/DCS/APC/vendor traffic manually.

Control-language normalization

Version 1.5 separates five layers which had previously been easy to conflate:

semantic intent
    -> capability/evidence resolution
    -> protocol backend selection
    -> control family framing
    -> dialect codec / wire transport

The normalized control-family vocabulary is:

CSI  ESC [
DCS  ESC P
OSC  ESC ]
APC  ESC _
PM   ESC ^
SOS  ESC X
ST   ESC \

Version 1.7 uses that architecture directly: Sixel is classified as a DCS dialect, while RasterGraphics is the semantic operation. The library does not conflate the two or expose generic control-family framing merely because internal normalization exists.

Examples:

DesktopNotification
    -> OSC 9
    -> OSC 777
    -> OSC 99

RasterGraphics
    -> Sixel / DCS       (1.7)
    -> Kitty Graphics / APC (planned later)

A terminal/vendor name is not itself a capability. Static TermInfo advertisement and generation-scoped live evidence are distinct. InvalidateState() expires live probe/protocol-response conclusions while retaining immutable selected profile/TermInfo evidence.

Other semantic terminal features

The stable surface also includes:

• application text and resolved terminfo capability output;
• terminal titles (OSC 0/1/2);
• current-location publication (OSC 7);
• hyperlinks (OSC 8);
• clipboard/selection operations and explicit reads (OSC 52);
• cursor style observation/ownership (DECSCUSR/DECRQSS);
• synchronized output (DEC private mode 2026);
• terminal progress (OSC 9;4);
• terminal pointer shape (OSC 22);
• typed Kitty desktop notifications and notification queries (OSC 99);
• portable semantic prompt/command metadata (OSC 133);
• typed VS Code shell integration (OSC 633);
• typed titled desktop notifications (OSC 777);
• typed iTerm2 shell-integration/semantic-history metadata (OSC 1337);
• indexed palette and selected dynamic terminal colors (OSC 4/104, 10–14, 17, 19 and resets);
• negotiated modern keyboard reporting;
• bracketed paste, focus, and mouse input protocols;
• bounded safe OSC 9 notification and Windows-CWD compatibility operations.

The safe OSC 9 subset intentionally excludes host-affecting vendor commands for sleep/blocking UI, GUI macros, process launch, environment disclosure, and emulator mutation.

Modern keyboard reporting

Modern keyboard reporting is opt-in through the compound input-protocol lease. Traditional keyboard decoding remains the compatibility floor.

The public modes are semantic:

Disambiguated
EventTypes
AllKeys

Kitty support is negotiated before reversible ownership is acquired. xterm modifyOtherKeys remains decode-only and is not blindly activated.

Security and privacy

Semantic APIs validate and bound terminal protocol data before commitment where the contract permits it. The library deliberately avoids generic raw vendor-command APIs as the ordinary extension mechanism.

Terminal traffic and query responses are untrusted external input. Successful byte transmission does not prove terminal-side application unless the protocol provides and the library receives an explicit correlated response.

Raster-specific security properties include bounded dimensions/storage/work state, verified capability gating, deterministic quantization, pre-commit validation, committed-frame integrity, no silent retry of partial output, and no automatic image-file decoding.

Several existing operations disclose caller-supplied metadata by design, including clipboard contents, filesystem locations, hyperlinks, shell metadata, notification text/metadata, and rich input events. The library does not automatically discover or redact secrets; applications decide what is appropriate to publish.

See Security and Privacy.

Compatibility policy

Stable 1.0.0 remains the compatibility floor. Versions 1.1–1.4 added compatible OSC 633, OSC 777, OSC 1337, and OSC 99 surfaces. Versions 1.5 and 1.6 were internal architecture releases and retained the 1.4 public fingerprint. Version 1.7 intentionally adds the compatible raster surface and advances the current public API baseline to:

847441fb4a8cdc89979aca9e96178f939895b93ec19a973232210af09716f700

Historical baselines remain checked in unchanged. See Public API Baseline 1.7 and Compatibility and Versioning.

For stable 1.x:

• patch releases fix/harden the documented contract without intentionally breaking it;
• minor releases may add compatible API/semantic features with an intentional baseline update;
• ordinary removals, renames, signature breaks, enum renumbering, or incompatible ownership/security/restoration changes require a new major release.

Vendor runtime EOL alone is not sufficient reason to drop net8.0 or net9.0; a concrete security/toolchain/maintenance blocker is required.

Platform support

The built-in SystemTerminalControlProvider supports:

• Windows;
• Linux;
• macOS.

Other hosts receive controlled Unsupported results from the built-in provider. Custom implementations may be supplied through ITerminalControlProvider, ITerminalInput, and ITerminalOutput.

Permanent documentation

Primary permanent authorities include:

• Architecture
• Terminal Session and Ownership
• Lifecycle and Restoration
• Input and Events
• Queries and Responses
• Presentation and Reversible State
• Semantic Output Protocols
• Control-Language Normalization and Graphics Roadmap
• D170–D179 1.7 contracts
• Security and Privacy
• Compatibility and Versioning
• Public API Baseline 1.7
• Migration to 1.0

Historical T-series, N150–N159, C160–C165, 0.x baselines, and earlier stable baselines remain available as design/release evidence.

Samples

Repository samples are indexed by task in samples/README.md. They cover session basics, rich input, queries, scoped presentation/state, colors, titles, location, hyperlinks, clipboard, semantic prompt metadata, notifications, and shell metadata.

Build and validation

On Windows:

build.cmd

On POSIX hosts:

sh build.sh

PR validation runs Windows/Linux/macOS runtime/source validation, the current machine public-API fingerprint, one portable package candidate, and four parallel package-contract shards retaining historical and stable 1.x contracts.

The semantic package shard compiles and runs fresh NuGet-only consumers on net8.0, net9.0, and net10.0, including the 1.7 raster consumer, and verifies generated XML documentation for the corresponding public APIs.

The Stable 1.x release-line shard retains the current Icod.DCurses integration/ownership package-boundary witness. These downstream checks complement rather than replace Terminal's own API, invariant, unit/hardening, and package gates.

After merge, Release distribution validation runs Windows/Linux/macOS x64/ARM64 runtime jobs plus the portable package and package-contract shards.

Release process

1.7.0 is publishable only after:

1. the exact final 1.7 PR head passes the complete Staging matrix;
2. the PR is explicitly merged;
3. the resulting main head passes Release distribution validation;
4. tagging/publication is explicitly authorized.

The tag-triggered workflow requires curated docs/releases/1.7.0.md release notes and re-runs public API, hardening, historical package, stable release-line package, semantic package consumers, and downstream compatibility gates before publication.

Tagging triggers publication; no release tag should be created merely because a PR is green.

Development roadmap

Current release status is tracked in Icod.Terminal-Development-Roadmap.md. The detailed current release program is Icod.Terminal-1.7.0-Development-Roadmap.md. Completed 1.6 and 1.5 programs remain preserved in their versioned roadmaps.

Authors

Inspired by original work from Bill Joy, author of the original termcap; Mary Ann (born Mark) Horton, author of terminfo; Pavel Curtis, author of pcurses; and Zeyd Ben-Halim, Eric S. Raymond, and Thomas Dickey, whose work developed and maintained libtinfo and ncurses.

Managed .NET implementation by Timothy J. Bruce uniblab@hotmail.com.

Copyright

Copyright (c) 2026 Timothy J. Bruce

License

The published Icod.Terminal library package and the C# sources compiled into the library are licensed under LGPL-3.0-or-later.

Repository executable/test programs—including Icod.Terminal.Tests, samples, package smoke tests, validation utilities, and downstream acceptance tools—are licensed under GPL-3.0-or-later. Their GPL license does not change the LGPL license of the reusable Icod.Terminal library they consume.

The root LICENSE contains the LGPLv3 terms and the incorporated GPLv3 terms. See Licensing for the project-by-project policy and source-header requirements.