Kitty graphics: images anchored to pruned scrollback rows render piled up at the top-left corner

[minpeter]

Issue Description

When the scrollback exceeds scrollback-limit and Ghostty prunes the oldest pages, Kitty graphics placements anchored to the pruned rows are not deleted. Instead they are silently re-anchored to the top-left corner of the remaining scrollback, so every pruned image renders piled up on top of each other in the corner, overlapping unrelated text.

This is easy to hit in practice with TUIs that replay a large history containing inline images (e.g. resuming an AI coding-agent session): the initial frame alone can exceed the default 10MB scrollback-limit, after which all of the earliest images collapse into the top-left of the scrollback.

Root cause analysis (from reading the source at main, 2de5e7d):

PageList.grow() prunes the first page when the page list exceeds maxSize(), and re-points every tracked pin on the pruned page to the top-left of the new first page, marking it as garbage (src/terminal/PageList.zig):

// Update any tracked pins that point to this page to point to the
// new first page to the top-left, and mark them as garbage.
const pin_keys = self.tracked_pins.keys();
for (pin_keys) |p| {
    if (p.node != first) continue;
    p.node = self.pages.first.?;
    p.y = 0;
    p.x = 0;
    p.garbage = true;
}

Kitty graphics placements are anchored by exactly such tracked pins (Placement.Location.pin in src/terminal/kitty/graphics_storage.zig), but nothing on the graphics side ever consults pin.garbage: the renderer (src/renderer/image.zig, kittyUpdate()) iterates all placements and renders .pin locations as-is. The search code, the inspector, and the C API grid refs all check garbage, so the flag exists precisely for this situation — the Kitty graphics path just never consumes it.

I verified this with a storage-level test: after forcing a prune via pages.grow(), the placement still exists with pin.garbage == true, pin.x == 0, pin.y == 0.

Proposed fix — delete placements whose pin has been marked garbage, matching Kitty's behavior of dropping placements whose rows scroll out of history. I have a working patch that:

1. adds ImageStorage.prunePlacements(), which removes any .pin placement whose pin is garbage (the image data itself is retained, since the client may still place it again by ID and unused images are already subject to the storage limit), and
2. calls it from renderer/image.zig kittyUpdate() before the placement list is rebuilt, so a stale placement is never drawn;
3. plus a regression test in graphics_storage.zig.

The full test suite passes (zig build test -Dapp-runtime=none), and I verified the fix end-to-end: with the patched build and the default 10MB limit, the reproduction below no longer shows the corner artifact, while images that are still within the retained scrollback keep rendering at their correct positions. I would be happy to open a PR with this change if the approach sounds right.

Expected Behavior

The image's anchor rows were pushed out of history together with the surrounding text, so the placement should be deleted and the image should no longer be rendered anywhere. This is what Kitty itself does: placements whose rows scroll off the history are dropped.

Actual Behavior

The image is glued to the top-left corner of the scrollback, drawn over the oldest retained filler lines (~line 293,000 in my run). With multiple images (the real-world case that led me here), they all stack on top of each other in that corner, overlapping unrelated text.

Setting scrollback-limit high enough that no pruning occurs makes the problem disappear, which confirms the pruning connection. (Raising scrollback-limit is also the current workaround.)

Reproduction Steps

1. Save the script below as kitty_prune_repro.sh and make it executable.
2. Run it inside Ghostty with the default scrollback-limit (I used ghostty --config-default-files=false -e /path/to/kitty_prune_repro.sh for a clean environment).
3. Wait for the seq flood to finish (a few seconds).
4. Scroll to the very top of the scrollback.
5. Observe the red image pinned at the top-left corner, overlapping the oldest retained filler lines, instead of having been discarded with its rows.

#!/usr/bin/env bash
# kitty_prune_repro.sh
set -euo pipefail

# 1. Generate a small test image (red 200x100 PNG), base64-encoded.
b64=$(python3 - <<'PY'
import base64, zlib, struct
def chunk(t, d):
    c = t + d
    return struct.pack(">I", len(d)) + c + struct.pack(">I", zlib.crc32(c))
w, h = 200, 100
raw = b"".join(b"\x00" + b"\xff\x00\x00" * w for _ in range(h))
png = (b"\x89PNG\r\n\x1a\n"
       + chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0))
       + chunk(b"IDAT", zlib.compress(raw))
       + chunk(b"IEND", b""))
print(base64.b64encode(png).decode())
PY
)

# 2. Display it via the Kitty graphics protocol (a=T, PNG, 20x5 cells).
printf '\x1b_Ga=T,f=100,c=20,r=5,i=42;%s\x1b\\' "$b64"
printf '\n>>> image placed above <<<\n'

# 3. Flood the scrollback well past the default 10MB scrollback-limit.
seq -f 'scrollback filler line %.0f' 1 300000

sleep infinity

Ghostty Logs

No relevant log output is produced during the reproduction (no warnings or
errors from the kitty graphics or renderer subsystems).

Ghostty Version

Ghostty 1.3.0-dev+0000000

Version
  - version: 1.3.0-dev+0000000
  - channel: tip
Build Config
  - Zig version   : 0.15.2
  - build mode    : .ReleaseFast
  - app runtime   : .gtk
  - font engine   : .fontconfig_freetype
  - renderer      : renderer.generic.Renderer(renderer.OpenGL)
  - libxev        : io_uring
  - kernel version: 7.0.0-28-generic
  - desktop env   : other
  - GTK version   :
    build         : 4.22.2
    runtime       : 4.22.4
  - libadwaita    : enabled
    build         : 1.9.0
    runtime       : 1.9.1
  - libX11        : enabled
  - libwayland    : enabled

(Ubuntu 26.04 distribution package. Also reproduced with a source build of main at 2de5e7d.)

OS Version Information

Ubuntu 26.04 LTS

(Linux only) Display Server

X11

(Linux only) Desktop Environment/Window Manager

None (headless X11/Xvfb for the minimal repro; originally observed in a regular desktop session as well)

Minimal Ghostty Configuration

# No configuration required: reproduces with an empty/default configuration
# (verified with --config-default-files=false).

Additional Relevant Configuration

No other programs are required; the reproduction script above is self-contained (bash + python3 for generating the test PNG).

I acknowledge that:

• I have reviewed the FAQ and confirm that my issue is NOT among them.
• I have searched the Ghostty repository (both open and closed Discussions and Issues) and confirm this is not a duplicate of an existing issue or discussion.
• I have checked the "Preview" tab on all text fields to ensure that everything looks right, and have wrapped all configuration and code in code blocks with a group of three backticks (```) on separate lines.

AI Disclosure

Per the AI usage policy: this investigation and write-up were done with substantial AI assistance (a Claude-based coding agent), driven and reviewed by me. The findings are not speculative — everything stated above was verified empirically on my machines: the reproduction script was run against the stock Ubuntu 1.3.0 package and a source build of main, the regression test was confirmed to fail on unpatched main and pass with the patch, the full test suite was run, and the patched build was verified end-to-end against the original real-world scenario. I have reviewed the analysis, the patch, and this post.

[minpeter]

For anyone interested in the concrete change, I have pushed the fix described above to a branch on my fork:

Diff: main...minpeter:ghostty:fix-kitty-placement-scrollback-prune

It is intentionally minimal (2 files, +115/-0):

• src/terminal/kitty/graphics_storage.zig — adds ImageStorage.prunePlacements(), which deletes any .pin placement whose tracked pin has been marked garbage by scrollback pruning, plus a regression test that forces a prune through PageList.grow() and asserts the placement is dropped (and that the image data itself is retained for future placements by ID).
• src/renderer/image.zig — calls prunePlacements() at the start of kittyUpdate(), before the placement list is rebuilt, so a stale placement is never drawn.

Validation performed:

• The new regression test fails against current main (placement survives with its pin clamped to the top-left and garbage == true) and passes with the fix.
• zig build test -Dapp-runtime=none passes with no regressions.
• End-to-end: with a patched build and the default 10MB scrollback-limit, the reproduction script above no longer shows the corner artifact, while images still within the retained scrollback continue to render at their correct positions.

Following the contribution guidelines I am holding off on opening a PR until this is confirmed; happy to submit it (and adjust the approach, e.g. moving the cleanup out of the renderer if a different call site is preferred) once triaged.

(AI disclosure: as noted in the post above, this patch was developed with AI assistance and verified by me — the regression test fails on unpatched main, and the patched build was validated end-to-end.)

[mitchellh]

Fixed on main