Module image_preview 

Inline image preview support for kitty / iTerm2 graphics protocols.

detect_image_support looks at environment variables to pick a protocol. kitty_transmit_png / kitty_place / iterm_inline_png / text_fallback are pure escape-sequence builders — they return Strings the caller can emit through whatever terminal backend it owns. This module deliberately does NOT touch I/O; rendering and stdout writes are the caller’s job, so the encoders stay unit-testable.

Live viewport: transmit once (dedup by content-hash id) + place; rows committed to scrollback use text_fallback only — image pixels are not expected to survive terminal history (omp lesson).

Reference: https://sw.kovidgoyal.net/kitty/graphics-protocol/ and https://iterm2.com/documentation-images.html.

Structs

ImageAnchor

Screen position of a pending image’s tool box, recorded by the live render pass and consumed by the post-draw emit step.

ImageBudget

Tracks transmitted image ids so the renderer stays under the kitty working-set limit (IMAGE_BUDGET_LIMIT), emitting delete escapes for evicted ids. Ids should be content hashes — re-rendering the same image refreshes its position instead of re-transmitting.

ImagePreviews

Render-state owner for inline image previews: protocol detection, the settings kill-switch, the transmit budget, the pending queue, and the per-frame anchors shared between the render pass (recorder) and the post-draw emit step (consumer).

PendingImage

An image waiting for its first live placement, captured when a generate_image tool result lands in the transcript.

Enums

ImageSupport

Which inline-image protocol the host terminal supports.

Constants

IMAGE_BUDGET_LIMIT

Default maximum number of concurrently-transmitted images the terminal is expected to keep alive. When a new transmission would push us over the limit, the budget evicts the oldest id and returns its delete command so the caller can emit it before the new transmit.

Functions

content_hash_id

Stable content-hash id for dedup: first 32 bits of SHA-256.

detect_image_support

Decide which protocol the host terminal supports, from the live env.

detect_image_support_from

Pure decision core — env values passed in so tests can build a matrix.

iterm_inline_png

Build an iTerm2 inline-image escape sequence (OSC 1337).

kitty_delete

Build a kitty delete command for budget demotion — d=I (capital) deletes the image’s placements AND frees its stored data, provided nothing else (e.g. scrollback) still references it.

kitty_place

Build a kitty placement command for a previously-transmitted image id.

kitty_transmit_png

Build a kitty transmit escape sequence (APC G) — transmit only, no display (a=t).

text_fallback

Plain-text fallback used when no graphics protocol is supported or the inline_images kill-switch is off. path identifies the image.