ghostty-rs/docs/rewrite/notes/ghostty-terminal-kitty.md

ghostty-terminal: kitty graphics (agent K1)

Ported (Zig -> Rust, crates/ghostty-terminal/src/kitty/)

Zig	Rust	tests
graphics_image.zig	graphics_image.rs (LoadingImage, Image, Rect, Error)	11/11 Zig + 3 extra (nul//proc path rejection, file offset+size, shared memory)
graphics_storage.zig	graphics_storage.rs (ImageStorage, Placement, PlacementKey, TerminalInfo)	19/19 Zig + 3 extra (placement replace releases pin, eviction order + limit, image_by_number newest)
graphics_unicode.zig	graphics_unicode.rs (placement_iterator, Placement, render_placement)	16/16 Zig + 2 extra
graphics_render.zig	graphics_render.rs (Placement)	no tests in Zig
graphics_exec.zig	graphics_exec.rs (execute, ExecTerminal trait)	8/8 Zig + 8 extra (real Terminal, including lifecycle integration)
kitty.zig / graphics.zig	kitty/mod.rs (re-exports; the command parser stays in ghostty_vt::kitty::graphics_command)	-

pub mod kitty; added to lib.rs. Test data copied to kitty/testdata/. Deps added to ghostty-terminal: flate2, png, rustix (features shm, fs), thiserror. Zig tests skipped: none. (debugDump not ported: debug-only helper.)

Deviations

• Borrowing: Zig passes *Screen/*Terminal to storage methods. Rust's ImageStorage is meant to live in Screen.kitty_images, so methods take &mut PageList (disjoint field borrow &mut screen.pages) plus a TerminalInfo { cols, rows, width_px, height_px, cursor_x, cursor_y } snapshot (TerminalInfo::from_terminal(&Terminal)). deinit(pages), delete(pages, &info, cmd), set_limit(pages, limit), add_image(pages, img), add_placement(pages, image_id, placement_id, p).
• add_image/add_placement/set_limit take the PageList only so that placements evicted or replaced release their tracked pin (Zig leaks them in evictImage and when an external placement id is re-used).
• Placement location is Location::Pin(TrackedPin) (handle into the PageList) instead of *Pin; Placement::rect(&image, &info, &pages).
• imageById/imageByNumber return Option<&Image> (no copy). Placements are a BTreeMap (deterministic order); images a HashMap.
• zlib via flate2, PNG via png crate (EXPAND|STRIP_16, then converted to 8-bit RGBA like wuffs' RGBA_NONPREMUL); shm via rustix::shm::open + File::read_exact_at (no mmap, so no unsafe). The segment is unlinked after reading, as in Zig.
• File medium S= (size): data is truncated to min(S, 400MB). (Zig's appendRemaining(.limited(n)) may error when the file is longer; I chose the Kitty-spec behavior. Zig tests only use S=0.)
• Placement::rect uses saturating_sub(1) on rows/cols (Zig would underflow for a 0-sized grid).
• Preserved Zig quirks: delete range uses || (id >= first || id <= last, matches everything); eviction stops only when evicted > req (strictly); set_limit(0) resets storage to defaults (limit then set to 0); screen reset .{ .dirty = true } also resets total_limit to default.
• execute(terminal, &cmd) has no allocator; Command stays borrowed (the loading image copies the payload).

graphics_exec and Terminal integration — complete

Screen.kitty_images is the real ImageStorage. Initialization applies the configured limit, reset deinitializes storage and restores default limits with dirty = true, and Drop releases placement pins before dropping PageList. clone_screen does not copy images. The default is still 320,000,000 bytes.

Terminal implements ExecTerminal by splitting active-screen storage/pages, snapshotting TerminalInfo, and forwarding cursor/index operations. Both kitty_graphics(&mut Command) and the new borrowed kitty_graphics_command(&Command) execute commands and return real responses. All graphics_exec tests now use Terminal directly; the separate harness is gone.

Reference hook audit:

• .complete and .scroll_complete display erasure call Delete::All(true). .scrollback only erases history, as in Terminal.zig.
• Lazy alternate-screen creation inherits the primary image limit; screen switching marks the new screen's images dirty.
• All existing image dirty hooks in Screen and Terminal remain at their Zig locations (scrolling, index, insert/delete lines, screen switching).
• Full reset drops alternate storage and resets primary storage. Placeholder printing uses the shared graphics_unicode::PLACEHOLDER constant.

Four additional integration regressions cover screen clone/reset and pin release, erasure hooks, alternate-screen isolation/limit inheritance/full reset, and the legacy command entrypoint plus in-progress transfer reset.

API changes and consumer wiring

Added Terminal::kitty_graphics_command(&Command) and ExecTerminal for Terminal; retained Terminal::kitty_graphics(&mut Command) unchanged. Screen.kitty_images now has the required concrete ImageStorage type; existing .dirty access remains valid. No downstream callers needed edits.

Termio can pass APC G commands through either terminal entrypoint and encode returned responses to the pty. Storage limits use screen.kitty_images.set_limit(&mut screen.pages, limit); clear-screen bindings use Delete::All(true). Renderer consumers can inspect placements/images and Unicode placements and clear the storage dirty flag after updating graphics. Consumer implementation beyond the public terminal API remains owned by the concurrent renderer/termio agents.

Quality gate (2026-10-11 integration pass)

cargo test -p ghostty-terminal: 1252 unit tests (including 70 Kitty tests: 54 source cases + 16 extra) and 1 documentation test pass; 0 failed, 0 ignored. Clippy with --all-targets -- -D warnings, rustfmt, and the combined build of ghostty-font, ghostty-renderer, and ghostty-termio pass. No commit or version change was made. Existing non-integration deviations above are unchanged.