Motivation
Transmission cache entries are never evicted except at VimLeavePre (or the test-only _reset()) — an idle entry's id and terminal-side pixel data are deliberately kept around so a later show() of the same file is cheap. But this means blit's reserved id pool (65,536 ids, per docs/spec/kitty-graphics.md's reserved range 0x626C0000-0x626CFFFF) is never reclaimed during a long-running session that show()s many distinct files. Documented as an accepted v0.x limitation in docs/spec/renderer-placement.md's "Transmission cache" section ("mirrors that memo's own acceptance of the range being merely 'negligible collision risk', not infinite").
Proposed Solution
Add an eviction policy for idle cache entries once the id pool nears exhaustion — e.g. LRU eviction of idle entries (freeing both the Lua-side cache entry and the terminal-side pixel data via d=I) triggered when alloc_id() is close to returning nil, err for range exhaustion. Needs a measurement first per AGENTS.md's performance rules ("every perf-motivated complexity increase must cite a measurement") — this issue should start with confirming whether any realistic session actually approaches 65,536 distinct transmitted files before designing the eviction policy itself.
Alternatives Considered
- Do nothing (status quo): acceptable unless/until a real session hits the limit —
alloc_id() already fails safely (nil, err) and show() propagates that as a normal error rather than crashing.
- Evict eagerly (small idle-entry cap): would undermine the "cache stays warm" performance goal for the common case of showing/hiding the same handful of images repeatedly (e.g. scrolling a file back into view) — rejected as the default without evidence it's needed.
Additional Context
Lowest priority of the v1.0-milestone issues; purely a scale concern for long-running sessions with many distinct images, not a correctness bug.
Checklist
Motivation
Transmission cache entries are never evicted except at
VimLeavePre(or the test-only_reset()) — an idle entry's id and terminal-side pixel data are deliberately kept around so a latershow()of the same file is cheap. But this means blit's reserved id pool (65,536 ids, perdocs/spec/kitty-graphics.md's reserved range0x626C0000-0x626CFFFF) is never reclaimed during a long-running session thatshow()s many distinct files. Documented as an accepted v0.x limitation indocs/spec/renderer-placement.md's "Transmission cache" section ("mirrors that memo's own acceptance of the range being merely 'negligible collision risk', not infinite").Proposed Solution
Add an eviction policy for idle cache entries once the id pool nears exhaustion — e.g. LRU eviction of idle entries (freeing both the Lua-side cache entry and the terminal-side pixel data via
d=I) triggered whenalloc_id()is close to returningnil, errfor range exhaustion. Needs a measurement first perAGENTS.md's performance rules ("every perf-motivated complexity increase must cite a measurement") — this issue should start with confirming whether any realistic session actually approaches 65,536 distinct transmitted files before designing the eviction policy itself.Alternatives Considered
alloc_id()already fails safely (nil, err) andshow()propagates that as a normal error rather than crashing.Additional Context
Lowest priority of the
v1.0-milestone issues; purely a scale concern for long-running sessions with many distinct images, not a correctness bug.Checklist