Icod.Terminal 1.15.0

Icod.Terminal 1.15.0

Unicode placeholder and virtual raster placement

Icod.Terminal 1.15.0 adds a backend-neutral semantic abstraction for terminal-resident raster presentation through Unicode placeholder cells while preserving caller ownership of cursor position, clipping, scrolling, damage, and layout.

The new public surface is additive over the stable 1.0.0 compatibility floor and the complete 1.14 API.

Highlights

• Adds TerminalCapability.UnicodeRasterPlaceholders = 10 without changing any previously released capability value.
• Adds opaque TerminalRasterPlaceholder ownership with required Columns / Rows in 1..256 and the existing TerminalRasterOwnershipState lifecycle vocabulary.
• Adds immutable TerminalRasterPlaceholderCell semantic row/column tokens through TerminalRasterPlaceholder.GetCell(...).
• Adds typed current-cursor single and bulk placeholder-cell output through TerminalSession.WriteRasterPlaceholderCellAsync(...) and WriteRasterPlaceholderCellsAsync(...).
• Adds TerminalRasterResource.CreatePlaceholderAsync(...) for acknowledged virtual-placement creation.
• Adds TerminalRasterResource.CreateRelativePlacementFromPlaceholderAsync(...), allowing a physical placement to use a current virtual placeholder as its immutable relative parent without exposing protocol identities.
• Keeps terminal image ids, image numbers, physical/virtual placement ids, session-generation ids, Unicode placeholder encoding details, combining-mark tables, SGR identity packing, raw APC commands, and production backend selection private.

Rendering and ownership contract

Every generated placeholder cell is self-contained: it carries enough private identity and coordinate information to render independently, with no left-neighbor shorthand. This preserves clipping, sparse redraw, scrolling, arbitrary cell ordering, overlapping rasters, and higher-level virtual-screen diffing.

Placeholder-cell output uses the caller's current text cursor. Icod.Terminal does not choose absolute screen coordinates and does not take ownership of windows, cells, clipping, scrolling, damage, or scene layout.

Virtual placements share the existing bounded persistent-placement registry:

maximum live persistent resources              256
maximum live physical + virtual placements     4096
maximum relative-placement depth                  8
placeholder rows                               1..256
placeholder columns                            1..256
private virtual-placement id            1..0x00FFFFFF

TerminalRasterPlaceholder reuses the 1.14 lifecycle model:

acknowledged placeholder             Current / None
session-generation invalidation      Stale / SessionStateLost
correlated missing resource          Stale / ResourceMissing
owning-resource release              Released / ResourceReleased
explicit wrapper disposal            Disposed / ExplicitDisposal

Stale, released, disposed, cross-session, and invalid-generation placeholder tokens are rejected before private identity is emitted.

Acknowledgement, failure, and cleanup

Placeholder creation reuses the authoritative session query/input transaction manager. A public placeholder is published only after a successful correlated acknowledgement.

Locally knowable invalid operations are rejected before output. Wrong identities, malformed responses, timeouts, late responses, and generic transport failures do not manufacture missing-resource truth. A correlated ENOENT follows the established missing-resource invalidation model.

Committed-output semantics remain unchanged: post-commit failure is surfaced without blind retry, backend switching, or hidden raster replay/re-upload.

Virtual-parent descendant cleanup remains deepest-first. Releasing a virtual parent releases dependent physical descendants while independently owned child raster resources remain independently owned unless separately released or invalidated.

Icod.TermInfo 1.14 integration

The direct production dependency advances to:

Icod.TermInfo 1.14.0
Icod.Timing   1.0.0

Optional integration tests and the Icod.Terminal.TermInfoPersistentRaster.Sample use Icod.TermInfo.Inspection 1.14.0; Inspection remains outside the production package graph.

The optional integration now exercises TermInfo 1.14's advisory Sixel/Kitty raster-backend evidence and selection planner while preserving the architectural boundary:

• backend availability remains separate from lifecycle and placement capability truth;
• only conclusive live PersistentRasterGraphics evidence is caller-mapped to Kitty availability;
• ordinary RasterGraphics does not identify one concrete backend;
• UnicodeRasterPlaceholders is not treated as TermInfo 1.14 lifecycle/placement evidence;
• Sixel and Kitty keep separate evidence/integration contexts;
• explicit backend preference remains caller policy;
• RasterBackendPlanner is not used by Icod.Terminal's production router.

Samples and qualification

The new Icod.Terminal.RasterPlaceholder.Sample demonstrates:

• semantic capability inspection;
• opaque resource and virtual-placeholder creation;
• complete and sparse placeholder-grid rendering;
• caller-controlled cursor positioning;
• out-of-order semantic cell emission;
• physical placement relative to a virtual placeholder;
• deterministic cleanup without raw protocol identities or backend branching.

The optional TermInfo persistent-raster sample demonstrates the 1.14 backend-planning boundary while Terminal retains live routing and execution authority.

The release is qualified on:

net8.0
net9.0
net10.0

across Windows, Linux, and macOS, with fresh packed-NuGet consumers, generated XML-documentation checks, public API fingerprint verification, package contract shards, and stable Icod.DCurses downstream acceptance.

The final 1.15 public API fingerprint is:

eb361cef615fda97ac2c0ef9da8ea3d63fdc1f537ec438164bcb93694eecd13d

Historical API baselines remain unchanged.

Compatibility and deliberate exclusions

Version 1.15 is additive. Existing consumers that do not use placeholder APIs retain the released persistent-resource, ordinary/relative placement, source-crop, signed-z-order, lifecycle-observation, generation-invalidation, capacity, cleanup, and no-replay semantics.

Version 1.15 does not add animation/frame ownership, absolute screen-coordinate layout, pixel-within-cell positioning, a scene graph, Terminal-owned windows/cells/damage, public protocol identities, generic raw Kitty dispatch, Sixel placeholder emulation, hidden replay caches, image decoding/transcoding, or PTY/ConPTY hosting.

See Persistent-Raster-Ownership.md, Architecture.md, Security-and-Privacy.md, Compatibility-and-Versioning.md, Public-API-Baseline-1.15.md, and Icod.Terminal-1.15.0-Development-Roadmap.md for the permanent contract and development evidence.