Icod.Terminal 1.12.0

Icod.Terminal 1.12.0

Icod.Terminal 1.12.0 extends the opaque persistent-raster placement model with bounded source-pixel cropping and signed z-order while preserving the 1.11 ownership, acknowledgement, lifecycle, cleanup, and dependency contracts.

The package targets:

net8.0
net9.0
net10.0

The stable compatibility floor remains 1.0.0.

Advanced persistent-raster placement

Version 1.12 adds the immutable backend-neutral source rectangle:

TerminalRasterSourceRectangle source = new(
	0,
	0,
	320,
	180
);

Persistent placement options now support:

TerminalRasterPlacementOptions options = new() {
	SourceRectangle = source,
	Columns = 40,
	ZIndex = -1
};

SourceRectangle coordinates are zero-based source-image pixels. Width and height must be positive, scalar values remain bounded by the raster dimension ceiling, and create/update validation requires the complete rectangle to fit inside the resource before any placement output is committed. Placement options revalidate every present rectangle, including default(TerminalRasterSourceRectangle) values that bypass the public constructor, so a zero-sized default value cannot reach the encoder or wire.

ZIndex is nullable signed int and accepts the full int.MinValue..int.MaxValue range. null retains backend/default order.

Create and update use the same acknowledged placement transaction. A source rectangle, when present, is emitted atomically as all four crop fields; z-order uses invariant signed decimal formatting. Existing placement bytes and behavior remain unchanged when the new options are omitted.

Ownership remains opaque and bounded

Version 1.12 does not expose terminal image ids, placement ids, raw APC dictionaries, or backend selection. Placement position remains the current terminal cursor location; source cropping is not absolute screen positioning.

The existing bounds remain unchanged:

maximum live persistent resources   256 per session
maximum live persistent placements 4096 per session

Persistent identities remain generation scoped. Invalidation makes existing handles stale; stale mutation returns controlled Unavailable before output and stale disposal remains local-only. The library does not retain source-image copies for hidden replay.

Acknowledgement and adversarial behavior

Advanced geometry uses the same authoritative input/query path as 1.11 persistent placement operations.

Qualification covers:

• wrong image and placement identities;
• malformed and duplicate correlated fields;
• bounded timeout and late-response ownership;
• correlated ENOENT invalidation;
• source rectangles ending exactly at source right/bottom edges;
• invalid create/update rectangles—including default struct values—producing no new output;
• int.MinValue and int.MaxValue z-order through real acknowledged operations;
• generation invalidation and stale local-only cleanup;
• repeated create/place/update/delete cycles with advanced geometry.

Correlation establishes transaction ownership, not terminal authenticity.

TermInfo evidence cleanup

Before adding the public geometry surface, 1.12 table-drives the internal TerminalTermInfoSemanticEvidence exact-semantic and metadata-backed backend rules. This is behavior-preserving internal cleanup: evidence states, routing outcomes, public API, and package dependencies remain unchanged.

Samples and package consumption

Icod.Terminal.PersistentRaster.Sample now demonstrates a bounded source-pixel crop and nonzero signed z-order, then updates the same placement with a different crop and stacking order. The example remains backend-neutral and exposes no Kitty/Sixel ids or raw commands.

The fresh NuGet-only persistent-raster smoke consumer compiles and executes TerminalRasterSourceRectangle, SourceRectangle, and ZIndex on net8.0, net9.0, and net10.0. Package verification also requires generated XML documentation for the rectangle type, constructor, four properties, and both new placement-option properties on every supported TFM.

Current Icod.DCurses package acceptance/hardening remains a required downstream witness; no downstream code change is expected for this additive release.

Public API

The only intended public additions over 1.11 are:

TerminalRasterSourceRectangle
TerminalRasterSourceRectangle..ctor(int,int,int,int)
TerminalRasterSourceRectangle.X
TerminalRasterSourceRectangle.Y
TerminalRasterSourceRectangle.Width
TerminalRasterSourceRectangle.Height
TerminalRasterPlacementOptions.SourceRectangle
TerminalRasterPlacementOptions.ZIndex

The final 1.12 public API fingerprint is:

eed5fc18e5cdd1cdadf340ba37c3664a01fb9338c2080b709168606d51d934a8

Historical public API baselines remain unchanged.

Dependencies

The production dependency graph remains:

Icod.TermInfo 1.11.0
Icod.Timing   1.0.0

No Inspection, Source, graphics-codec, or scene-layout dependency is added to the production package.

Deliberate exclusions

Version 1.12 does not add:

• relative placement graphs or parent placement identities;
• absolute screen-coordinate or pixel-offset placement;
• Unicode placeholder/virtual placements;
• animation or frame lifecycle;
• caller-selected raster backends or raw Kitty command dispatch;
• automatic replay/re-upload after invalidation;
• hidden source-image caches;
• Sixel persistence emulation;
• image-file decoding/transcoding;
• PTY/ConPTY hosting;
• cells, windows, damage, or layout policy owned by Icod.DCurses.

Compatibility

Version 1.12 is an additive minor release over the stable 1.0.0 compatibility floor. Existing signatures and enum numeric values are preserved. Existing 1.11 persistent placement behavior is byte-for-byte preserved when SourceRectangle and ZIndex are not supplied.

See Persistent-Raster-Ownership.md, Compatibility-and-Versioning.md, Public-API-Baseline-1.12.md, and Icod.Terminal-1.12.0-Development-Roadmap.md for the permanent contract and development evidence.