Icod.Terminal 1.13.0

Icod.Terminal 1.13.0

Icod.Terminal 1.13.0 extends the opaque persistent-raster placement model with bounded relative placement ownership. A placement may now be positioned relative to one existing placement while retaining a separate raster-resource ownership relationship.

The package targets:

net8.0
net9.0
net10.0

The stable compatibility floor remains 1.0.0.

Relative persistent-raster placement

Version 1.13 adds two public operations:

TerminalRasterResource.CreateRelativePlacementAsync(
	TerminalRasterPlacement parent,
	int columnOffset,
	int rowOffset,
	TerminalRasterPlacementOptions? options = null,
	CancellationToken cancellationToken = default
)

TerminalRasterPlacement.UpdateRelativeAsync(
	int columnOffset,
	int rowOffset,
	TerminalRasterPlacementOptions? options = null,
	CancellationToken cancellationToken = default
)

Parentage is immutable. It is selected during successful relative creation and cannot be changed through a public reparenting operation or mutable parent property.

columnOffset and rowOffset are signed terminal-cell offsets. The full signed int domain is retained. They are not source-image pixels, absolute terminal coordinates, or pixel-within-cell offsets.

The portable relative-depth ceiling is 8. Ordinary current-cursor placements have depth 0; a direct relative child has depth 1. Creation that would produce depth 9 is rejected locally before output.

Two independent ownership axes

Relative placement deliberately separates raster-resource ownership from parent-placement lifetime:

TerminalRasterResource
    -> owns placement resource/storage membership

TerminalRasterPlacement parent
    -> owns relative-placement lifetime subtree

A placement of Resource B may therefore be relative to a placement of Resource A.

Disposing a parent placement removes its relative descendants, deepest-first, but does not automatically dispose descendant raster resources. A child resource remains independently owned and may participate in other placements.

Disposing a resource removes its own placements and any relative descendant placements whose lifetime depends on them, including descendants that place other still-live resources. Those descendant resources themselves remain independently owned.

Updates and common geometry

TerminalRasterPlacementOptions remains the single common crop/extents/z-order contract.

UpdateAsync(...) preserves the placement's established positioning mode:

• ordinary placements continue to update at the current cursor location;
• relative placements preserve their immutable parent and last acknowledged offsets while replacing common geometry.

UpdateRelativeAsync(...) changes signed offsets plus common geometry while retaining the same parent.

No API silently converts an ordinary placement to relative placement or reparents an existing relative placement.

Acknowledgement and protocol behavior

Relative create/update operations use the existing serialized acknowledged persistent-placement transaction path and the same authoritative terminal input/query stream.

The private Kitty encoding adds parent image/placement identity and signed offset fields while retaining child image/placement identity as the response-correlation authority. Relative offsets are committed locally only after a successful acknowledgement.

Existing 1.12 current-cursor placement bytes and behavior remain unchanged when the relative APIs are unused.

Cleanup and lifecycle

Current parent/subtree cleanup is descendant-before-parent and deepest-first. Each placement delete uses that placement's own owning-resource image identity, including cross-resource relative graphs.

Placement and resource disposal remain locally idempotent. A child handle already closed by parent cascading cannot double-release terminal identity.

Generation invalidation stales the complete graph. Stale cleanup is local-only and emits no stale numeric terminal identities. No hidden raster replay, re-upload, or rebind is introduced.

Session teardown drains current placement graphs deepest-first before resource data and preserves the existing restoration/failure-aggregation model.

Terminal-negative responses

Version 1.13 narrows graph-related terminal failure classification:

• correlated ENOPARENT invalidates certainty for the affected parent placement subtree without automatically declaring its raster resource missing;
• correlated ECYCLE remains a controlled failure because supported public construction cannot form a cycle;
• correlated ETOODEEP remains a controlled failure because local depth 8 prevents deeper supported construction;
• correlated ENOENT retains established missing-resource/identity invalidation where the response denotes missing resource identity;
• malformed correlated responses, wrong child identities, late responses, and transport failures retain the established bounded transaction-manager behavior.

Correlation establishes transaction ownership, not terminal authenticity.

Bounds and compatibility

The existing registry ceilings remain unchanged:

maximum live persistent resources   256 per session
maximum live persistent placements 4096 per session
maximum relative placement depth       8

Private placement-id wrap/collision rules remain nonzero and collision-safe. Existing generation, acknowledgement, committed-output, capacity, crop, and signed z-order contracts are preserved.

Version 1.13 is additive over the published 1.12 public surface and the stable 1.0.0 compatibility floor.

Sample and package qualification

Icod.Terminal.PersistentRaster.Sample demonstrates:

1. Resource A with an ordinary current-cursor parent placement;
2. independently owned Resource B;
3. a Resource B placement relative to Resource A's placement;
4. signed relative offsets plus 1.12 crop/extents/z-order geometry;
5. ordinary UpdateAsync(...) preserving the relative parent and acknowledged offsets while replacing common geometry;
6. UpdateRelativeAsync(...) replacing offsets/common geometry without reparenting;
7. parent disposal cascading descendant-placement cleanup while Resource B remains independently owned; and
8. successful creation of a fresh ordinary placement from Resource B after the parent cascade.

The optional Icod.Terminal.TermInfoPersistentRaster.Sample and dedicated integration tests consume Icod.TermInfo.Inspection 1.12.0. They retain the 1.11.1 lifecycle-planning boundary and additionally qualify the additive TermInfo 1.12 source-rectangle/signed-z-order placement planner without adding Inspection to the production package graph. TermInfo 1.12 does not plan the relative-parent graph introduced by Terminal 1.13.

The fresh NuGet-only persistent-raster consumer compiles and executes the new public surface on net8.0, net9.0, and net10.0. Generated XML documentation is verified for both new methods on every supported TFM.

The stable 1.x package shard continues to run the published Icod.DCurses acceptance/hardening witness. No DCurses source change is required merely to consume the additive 1.13 package.

Public API

The intended public additions over 1.12 are exactly:

TerminalRasterResource.CreateRelativePlacementAsync(
    TerminalRasterPlacement,
    int,
    int,
    TerminalRasterPlacementOptions?,
    CancellationToken
)

TerminalRasterPlacement.UpdateRelativeAsync(
    int,
    int,
    TerminalRasterPlacementOptions?,
    CancellationToken
)

The final 1.13 public API fingerprint is:

c9dc8b86dc1e8beed7161f1f5a122dce67a9187d3f4ee0b85ad5b49f09bd0da9

Historical public API baselines remain unchanged.

Dependencies

The production dependency graph is:

Icod.TermInfo 1.12.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.13 does not add:

• reparenting or mutable parentage;
• public parent/image/placement numeric identities;
• Unicode placeholder / virtual placements;
• animation or frame lifecycle;
• absolute screen-coordinate placement;
• pixel-within-cell positioning;
• automatic replay/re-upload/rebind;
• retained source-image caches;
• caller-selected graphics backends or generic raw Kitty dispatch;
• Sixel persistent-resource emulation;
• image-file decoding/transcoding;
• PTY/ConPTY hosting;
• cells, windows, damage, layout, or scene ownership.

Relative placement is a bounded positioning/lifetime relationship, not a general scene graph.

Qualification

The final stable release candidate must pass the ordinary exact-head matrix:

Runtime Windows
Runtime Linux
Runtime macOS
Package candidate / public API freeze
Package Foundation
Package Presentation
Package Semantic and hardening
Package Stable 1.x release line
Validated package artifact

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