Kitty graphics: anonymous placements accumulate on same-id retransmit instead of replacing

[PavolUlicny]

Issue Description

A Kitty graphics client that retransmits an image with a=T, a fixed image id, and no p= key gets a new placement added on every transmit. Old placements are never reclaimed, so the number of placements always grows for as long as the client keeps drawing. This can completely lag your whole computer in extreme cases where you very quickly refresh frames. kitty replaces the placement instead, under the exact same input.

Ghostty:

Kitty:

Root cause

Source read at main (fea378e56); behaviour confirmed on 1.3.1.

src/terminal/kitty/graphics_storage.zig, addPlacement(): a placement with placement_id == 0 is stored under a new internal id every time, so it can never replace a previous one:

const key: PlacementKey = .{
    .image_id = image_id,
    .placement_id = if (placement_id == 0) .{
        .tag = .internal,
        .id = id: {
            defer self.next_internal_placement_id +%= 1;
            break :id self.next_internal_placement_id;
        },
    } else .{
        .tag = .external,
        .id = placement_id,
    },
};

The other half is addImage(), which deliberately keeps a replaced image's placements ("Write our new image, preserving placements across replacement", carrying placement_count forward). So retransmitting an existing id keeps every old placement and also adds a new anonymous one.

Image.metadata.placement_count is a u30, so the only ceiling is ~1.07e9 placements.

Each placement also holds a tracked pin (graphics_exec.zig, display() calls trackPin), so PageList.tracked_pins grows in lockstep, and src/renderer/image.zig rebuilds and sorts the placement list every frame and issues one vertex buffer plus one draw call per placement.

Not a duplicate

Distinct from #13468 (placements anchored to pruned scrollback rows). These placements sit on live rows and are never marked garbage, so the removeGarbagePlacements sweep added in 402b9227d does not reclaim them.

Why kitty differs

kitty/graphics.c, handle_add_command calls free_image_resources and free_refs_data when a transmit names an existing image id, freeing all of that image's refs before the new data loads.

Spec wording

docs/graphics-protocol.rst:

Not specifying a placement id or using p=0 for multiple put commands (a=p) with the same non-zero image id results in multiple placements the image.

The guarantee of multiple anonymous placements is scoped to a=p. a=T is not a put.

Possible fixes

1. Treat the implicit placement created by a=T as replacing that image's previous implicit placement, keyed distinctly from .internal so clients doing explicit a=p puts keep their multiple placements. No existing test asserts otherwise; "storage: add placement with zero placement id" calls addPlacement directly and never exercises a=T.
2. Mirror kitty: delete an image's existing placements when a transmit replaces that image id.

I'd LOVE to make a PR for whichever.

AI disclosure

Found the initial bug myself, but I thoroughly verified and tested it with Claude Code (Claude Fable 5 & Opus 5). And of course, everything AI-generated was also thoroughly verified by me.

Expected Behavior

Retransmitting the same image id with a=T and no p= key should not grow the placement set infinitely. kitty holds one placement for the image, so 24 transmits leave one rectangle on screen.

Actual Behavior

Every transmit adds a placement. Sending 24 transmits of the same image id at 24 different cursor positions leaves 24 rectangles on screen in Ghostty, versus 1 in kitty under the identical input. Adding p=1 makes Ghostty behave like kitty.

Reproduction Steps

trails.py transmits the same image id 24 times with a=T and no p= key, moving the cursor to a different cell before each one, so the placement count is directly countable on screen.

1. Save the script below and run python3 trails.py in Ghostty. Count the rectangles. There are 24.
2. Run python3 trails.py --p 1 in Ghostty. There is 1.
3. Run python3 trails.py in kitty. There is 1.

NOTE: This is a fully AI-generated python script, that I read and verified works.

trails.py

#!/usr/bin/env python3
"""Do anonymous kitty placements accumulate?

Transmits the same image id N times with a=T, each at a different cell.
  - accumulate -> every rectangle stays on screen
  - replace    -> exactly one rectangle
"""
import argparse
import base64
import sys
import zlib

ap = argparse.ArgumentParser()
ap.add_argument("--p", type=int, default=0, help="placement id; 0 omits the p= key")
ap.add_argument("--count", type=int, default=24, help="how many placements to make")
ap.add_argument("--w", type=int, default=80, help="image width in px")
ap.add_argument("--h", type=int, default=48, help="image height in px")
ap.add_argument("--cols", type=int, default=6, help="grid columns")
ap.add_argument("--col-step", type=int, default=24, help="cells between columns")
ap.add_argument("--row-step", type=int, default=6, help="cells between rows")
args = ap.parse_args()

W, H = args.w, args.h
out = sys.stdout.buffer

payload = base64.standard_b64encode(zlib.compress(bytes((64, 96, 255)) * (W * H), 1))


def transmit():
    p, first = payload, True
    while p or first:
        chunk, p = p[:4096], p[4096:]
        if first:
            keys = "q=2,i=1,a=T,t=d,f=24,o=z,s=%d,v=%d,C=1" % (W, H)
            if args.p > 0:
                keys += ",p=%d" % args.p
            if p:
                keys += ",m=1"
            first = False
        else:
            keys = "q=2,m=1" if p else "q=2,m=0"
        out.write(b"\033_G" + keys.encode() + b";" + chunk + b"\033\\")
    out.flush()


out.write(b"\033[?1049h\033[2J")

for i in range(args.count):
    row = 1 + (i // args.cols) * args.row_step
    col = 1 + (i % args.cols) * args.col_step
    out.write(b"\033[%d;%dH" % (row, col))
    out.flush()
    transmit()

arm = "no p= key" if args.p == 0 else "p=%d" % args.p
status = [
    "arm: %s | sent %d transmits of image id 1 at %d different cells" % (
        arm, args.count, args.count),
    "COUNT THE RECTANGLES, then press Enter.",
    "  %d visible -> placements accumulate (the bug)" % args.count,
    "  1 visible  -> each transmit replaced the last (no accumulation)",
]
base = 1 + (((args.count - 1) // args.cols) + 2) * args.row_step
for n, line in enumerate(status):
    out.write(b"\033[%d;1H\033[K" % (base + n))
    out.write(line.encode())
out.flush()

try:
    input()
except (EOFError, KeyboardInterrupt):
    pass

out.write(b"\033_Gq=2,a=d,d=I,i=1\033\\\033[?1049l")
out.flush()

Ghostty Logs

No warnings or errors are logged during reproduction.

Ghostty Version

Ghostty 1.3.1

Version
  - version: 1.3.1
  - channel: stable
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.14.5
    runtime       : 4.14.5
  - libadwaita    : enabled
    build         : 1.5.0
    runtime       : 1.5.0

OS Version Information

Ubuntu 24.04.4 LTS (kernel 7.0.0-28-generic)

(Linux only) Display Server

X11

(Linux only) Desktop Environment/Window Manager

GNOME Shell 46.0

Minimal Ghostty Configuration

# reproduces with an empty configuration

Additional Relevant Configuration

Compared against kitty 0.32.2 using the identical script.

GPU: Ghostty renders on the integrated AMD Radeon 780M (amdgpu, Mesa 25.2.8, OpenGL 4.6 compat). The machine also has an RTX 4060 Laptop GPU (driver 580.173.02) which Ghostty is not using.

P.S.: I'm a big fan of both Mitchell and Ghostty and would love to become a contributor by fixing this bug. This would also be my first contribution to a big project.

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.

[mitchellh]

Fixed: #13723

[PavolUlicny]

Confirmed fixed and working, thanks Mitchell