Icod.Terminal 1.9.0

Icod.Terminal

Icod.Terminal is a managed, cross-platform live-terminal session and terminal-control library for .NET. It sits between immutable terminal capability data from Icod.TermInfo and higher-level consumers such as Icod.DCurses, terminal-aware command-line tools, monitors, editors, pagers, and REPLs.

Status

1.9.0 is the current release candidate on this development branch. It adds a protocol-neutral unsolicited semantic-event path to the existing authoritative terminal reader and completes interactive Kitty OSC 99 desktop notifications with typed activation, button, close, and close-tracking-unavailable reports.

The stable 1.0.0 compatibility floor remains unchanged. Merge, post-merge Release validation, tagging, and publication are maintainer-controlled release actions and are not implied by this branch status.

Installation

After 1.9.0 is published, install it with:

dotnet add package Icod.Terminal --version 1.9.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 owns immutable terminal capability data and terminfo expansion.
• Icod.Terminal owns the live terminal conversation: endpoint observation, native modes, input decoding, lifecycle, active query routing, unsolicited semantic events, capability evidence, semantic terminal output, protocol framing/routing, raster output, and scoped/reversible terminal state.
• Icod.DCurses owns higher-level cells, windows, virtual-screen state, refresh/diff policy, and curses presentation abstractions.
• PTY/process hosting remains orthogonal to the Icod.Terminal runtime contract.

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

A live TerminalSession owns the authoritative input reader for its transport. Use ReadEventAsync(...) and typed query APIs rather than introducing a competing Console.Read* or stream reader on the same terminal conversation.

For a curses-style virtual screen, prefer Icod.DCurses rather than rebuilding cell/window/refresh policy directly over TerminalSession.

Unsolicited semantic events

Version 1.9 extends the unified event model with TerminalEventKind.Semantic while preserving all existing enum numeric values.

Incoming framed traffic is assigned in this order:

active query response
    -> recognized unsolicited semantic event
        -> ordinary application input

The first semantic family is interactive notification reporting. A semantic notification event is available through:

if ( terminalEvent.Kind == TerminalEventKind.Semantic ) {
	TerminalNotificationEvent? notification =
		terminalEvent.Semantic?.Notification;
}

The reviewed notification event kinds are:

Activated
ButtonActivated
Closed
CloseTrackingUnavailable

There is no second ReadSemanticEventAsync(...) path. Semantic events share the same bounded application-event ordering domain as ordinary input, and query responses retain first ownership of matching terminal traffic.

Interactive Kitty notifications

The existing SendKittyNotificationAsync(...) API now supports explicit opt-in reporting through KittyNotificationOptions:

await session.SendKittyNotificationAsync(
	"Build",
	"Compilation complete",
	new KittyNotificationOptions {
		Identifier = "build-42",
		ReportActivation = true,
		ReportClose = true,
		Buttons = [ "Acknowledge", "Dismiss" ]
	}
);

Reporting requires a caller-supplied identifier. Button reports are one-based. Notification identifiers and reported interactions are validated but unauthenticated terminal-controlled input; applications must not use them as an authorization boundary.

When the new interactive options are unused, existing Kitty notification behavior remains compatible with the 1.4 surface.

Raster graphics

The public raster API remains semantic and backend-neutral:

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

TerminalControlMutationResult result = await session.DisplayRasterAsync( image );

Supported public storage forms are Rgb24, Rgba32, and Indexed8 plus an RGBA8 palette. The session resolves raster output through verified Kitty Graphics/APC first and verified Sixel/DCS as fallback.

The raster contract deliberately does not expose raw DCS/Sixel or APC/Kitty dispatch, backend selection, persistent Kitty image identifiers, placement/scaling, source rectangles, z-order, Unicode placeholders, deletion, animation, or image-file decoding/transcoding.

Core 1.x guarantees

One authoritative input path

Application input, semantic events, lifecycle traffic, and terminal query responses share one coordinated session. Queries are bounded and correlation-aware. No feature opens a competing terminal reader.

Deterministic ownership

Active query responses have first refusal on matching framed traffic. Recognized unsolicited semantic reports are classified next, followed by ordinary application input. A frame is never intentionally double-delivered as both a query response and a semantic event.

Bounded protocol handling

Terminal-controlled input is untrusted. Control-frame parsing, query state, semantic-event buffering, raster dimensions/storage, and protocol payloads have explicit resource ceilings. Malformed/oversized owned semantic reports recover boundedly rather than leaking hostile bytes into ordinary text.

Reversible ownership

Scoped state uses leases where overlapping ownership matters. TerminalSession.DisposeAsync() remains final cleanup/restoration authority for session-owned state. Ephemeral notifications and semantic observations are not replayed as reversible state across suspend/resume.

Serialized semantic output

Ordinary terminal-aware output should use session semantic operations. TerminalSession.Output is an advanced borrowed transport outside normal session serialization when used directly by callers.

Committed multi-frame graphics operations do not intentionally truncate after commitment, and partial transport failure is surfaced without blind replay or automatic backend switching.

Feature highlights

The stable 1.x surface includes:

• application text and resolved terminfo capability output;
• terminal input, lifecycle events, bracketed paste, focus, mouse, and negotiated modern keyboard reporting;
• unsolicited protocol-neutral semantic events, beginning with interactive notification reports;
• bounded Primary/Secondary DA, DSR, CPR, DECRQSS, XTGETTCAP, color, pointer, clipboard, and notification queries;
• terminal titles (OSC 0/1/2) and current location (OSC 7);
• hyperlinks (OSC 8) and clipboard/selection operations (OSC 52);
• cursor-style observation/ownership (DECSCUSR/DECRQSS);
• synchronized output (DEC private mode 2026);
• terminal progress (OSC 9;4) and pointer shape (OSC 22);
• desktop notifications through OSC 9, OSC 777, and typed Kitty OSC 99, including opt-in interactive reporting;
• portable semantic prompt/command metadata (OSC 133);
• typed VS Code shell integration (OSC 633);
• 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);
• backend-neutral raw raster display with verified Sixel and Kitty Graphics backends.

Samples

The samples directory contains focused, buildable examples grouped by consumer goal. Recommended starting points are:

• Icod.Terminal.Sample — session construction and basic event reading;
• Icod.Terminal.RichInput.Sample — text, keys, paste, focus, mouse, and modern keyboard reporting;
• Icod.Terminal.Query.Sample — bounded terminal queries;
• Icod.Terminal.Notification.Sample — OSC 9/777/99 notification output plus --kitty-interactive semantic-event reporting;
• Icod.Terminal.RasterGraphics.Sample — backend-neutral raster display without image-decoder dependencies;
• Icod.Terminal.SemanticPrompt.Sample — portable prompt/command metadata;
• Icod.Terminal.VsCodeShellIntegration.Sample and Icod.Terminal.ITerm2ShellIntegration.Sample — explicit vendor-specific shell-integration examples.

Focused sample verifiers build the newer protocol and raster examples on every supported target framework during repository validation.

Security and privacy

Terminal protocol traffic is external input/output and must be treated accordingly. Icod.Terminal validates and bounds semantic protocol data and deliberately avoids generic raw vendor-command/event APIs as the normal extension mechanism.

Notification interaction reports can be fabricated by the terminal path. An identifier is correlation data, not authentication. Successful notification emission does not prove that the desktop displayed the notification, and a later typed report does not prove a trusted user action.

Several APIs intentionally publish caller-supplied metadata, including filesystem locations, hyperlinks, clipboard contents, notification text, shell metadata, and command lines. The library does not automatically discover or redact secrets; applications decide what is appropriate to disclose to the terminal.

See Security and Privacy.

Compatibility

Stable 1.0.0 remains the compatibility floor. Versions 1.1–1.4 added compatible semantic protocol surfaces; 1.5 and 1.6 normalized internal control-language/query infrastructure; 1.7 introduced the public raster contract; 1.8 added Kitty Graphics beneath that unchanged raster surface; and 1.9 adds the protocol-neutral semantic-event envelope plus interactive Kitty notification request options.

The final 1.9 public API fingerprint is:

e652e6fd65cd43422ca84b7c4c2a1815ee7ead9b2a64285e0e17cf39614b0315

See Compatibility and Versioning. Consumers upgrading from the pre-1.0 line should also review Migration to 1.0.

Documentation

Start with:

• 1.9.0 release notes
• Current development roadmap
• 1.9.0 development roadmap
• Architecture
• Input and Events
• Queries and Responses
• Security and Privacy
• Compatibility and Versioning
• Migration to 1.0
• Samples
• Changelog

Historical release and tranche records remain in the repository for design evidence, while the root README and current roadmap are maintained as concise consumer/contributor entry points.

License

Icod.Terminal is licensed under the GNU Lesser General Public License, version 3 or later. Sample applications are licensed under the GNU General Public License, version 3 or later, as stated in their source headers.