Icod.Terminal 1.16.0

Icod.Terminal 1.16.0

Persistent raster animation and frame lifecycle

Icod.Terminal 1.16.0 adds backend-neutral ownership of terminal-resident raster animation frames and playback while preserving private protocol identity, caller-owned screen layout, and the established persistent-resource lifecycle.

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

Highlights

• Adds TerminalCapability.PersistentRasterAnimation = 11 without changing any previously released capability value.
• Gives every TerminalRasterResource one side-effect-free Animation controller and opaque RootFrame representing the resource's original pixels.
• Adds acknowledged full-size frame append through AddFrameAsync(...); a public frame token is returned only after a successful correlated result.
• Adds exact positive whole-millisecond timing through SetFrameDurationAsync(...).
• Adds semantic current-frame selection through SelectFrameAsync(...).
• Adds terminal-driven stop, loading-mode playback, and normal finite/indefinite playback through StopAsync(...), RunLoadingAsync(...), and RunAsync(...).
• Keeps image ids, image numbers, frame numbers, generation ids, raw animation commands, and backend selection private.

Ownership and sequence certainty

The animation controller is owned by its raster resource and is not independently disposable. Resource disposal remains final authority for terminal-resident image and frame data. Physical placements and virtual placeholders continue to refer to the same resource and do not acquire frame ownership.

Animation certainty is observed separately from raster-resource ownership:

Current
SequenceUncertain
Stale
Released
OwnerDisposed

If a committed frame append may have reached the terminal but its final result cannot be proven, the animation becomes SequenceUncertain / FrameSequenceAmbiguous. Terminal publishes no guessed token and performs no blind retry. The owning resource may remain current.

After sequence uncertainty, already-known frame timing/selection and stop remain available. New appends and run modes that depend on a known sequence tail return controlled unavailability.

Bounds, validation, and playback

Version 1.16 accepts full-size appended frames only. Each frame must match the owning resource's intrinsic dimensions.

session-wide known animation frames, roots included    4096
pending append reservations per animation                 1
frame duration                                  1..Int32.MaxValue ms
finite additional repeat count                   1..Int32.MaxValue-1
null repeat count                                indefinite looping

Root frames, acknowledged appended frames, and active append reservations participate in bounded capacity accounting. Stale, released, and owner-disposed animations release their registry capacity; sequence-uncertain animations retain acknowledged tokens.

Partial frames, delta editing, frame composition, and gapless composition frames are not exposed in 1.16.

Transport, failure, and cleanup

Animation uses the reviewed direct persistent-raster transport, serialized output gate, authoritative input/query reader, and correlated graphics-response parser.

Locally knowable invalid dimensions, durations, repeats, tokens, ownership, and capacity are rejected before private identity is emitted. Wrong/malformed identities, timeouts, late responses, terminal-negative responses, storage pressure, and pre/post-commit failures remain bounded.

Committed logical output is not intentionally truncated by later caller cancellation. Failure does not trigger blind replay, backend switching, hidden raster reconstruction, or a second input reader.

Session generation loss, resource-missing evidence, intentional resource release, and explicit resource-wrapper disposal propagate monotonically to animation/frame state. Placement or placeholder disposal does not delete animation frames.

Sample and qualification

Icod.Terminal.RasterAnimation.Sample demonstrates:

• capability inspection;
• resource creation and root-frame access;
• root timing and acknowledged full-size frame append;
• ordinary placement of the animated resource;
• loading-mode playback while appending another frame;
• stop and explicit frame selection;
• finite and indefinite normal playback;
• resource-owned deterministic cleanup.

The sample emits no raw Kitty commands and does not branch on protocol identities.

The release is qualified for:

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, fixed-count concurrency/hardening, validated artifacts, and stable Icod.DCurses downstream acceptance.

The final 1.16 public API fingerprint is:

d2acfa85aad87c739b3f682096d4d7139627f12bc9d8981b65529eeb79a2da8d

Historical API baselines remain unchanged. Production dependencies remain Icod.TermInfo 1.14.0 and Icod.Timing 1.0.0.

Compatibility and deliberate exclusions

Version 1.16 is additive. Existing consumers that do not use animation APIs retain the released resource, physical/relative placement, virtual-placeholder, lifecycle-observation, generation-invalidation, capacity, cleanup, committed-output, and no-replay semantics.

Version 1.16 does not add partial-frame updates, frame composition/delta editing, gapless composition frames, absolute screen-coordinate placement, pixel-within-cell positioning, GIF/APNG or other image decoding, audio/timeline synchronization, Terminal-owned scene/window/cell/damage/layout policy, public protocol identities, generic raw Kitty dispatch, hidden replay caches, or PTY/ConPTY hosting.

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