Kitty graphics: replacing a shown image blanks it until the new one is decoded

[sorokin-vladimir]

Issue Description

When an image is transmitted (a=T) under an id that a Unicode placeholder grid is currently showing, the cells go blank until the new image has been decoded, instead of keeping the old image until the new one is ready. With frames of 100-200 KB this is a 10-20 ms blank on every frame, so any animation done by re-transmitting under one id visibly blinks

Expected Behavior

The previous image stays visible until the replacement is complete and decoded, then the cells switch to it

Actual Behavior

The cells show nothing between the start of the new transmission and the moment it is decoded. Alternating between two ids, and pointing the placeholders at an id only after its image was sent, does not blink

Reproduction Steps

1. Start Ghostty with --config-default-files=false
2. Run the attached Go program (standard library only): go run main.go
3. Phase 1 (4 s) re-sends two light noise frames (~140 KB PNG each) under one id at 15 fps with a fixed placeholder grid: dark flashes between frames. Phase 2 (4 s) alternates between two ids: no flashes

Ghostty Logs

No response

Ghostty Version

Ghostty 1.4.0

Version
  - version: 1.4.0
  - channel: stable
Build Config
  - Zig version   : 0.17.0
  - build mode    : .fast
  - app runtime   : .none
  - font engine   : .coretext
  - renderer      : renderer.generic.Renderer(renderer.Metal)
  - libxev        : kqueue

OS Version Information

macOS 27.0.1 (26A434)

(Linux only) Display Server

None

(Linux only) Desktop Environment/Window Manager

No response

Minimal Ghostty Configuration

None, reproduced with --config-default-files=false

Additional Relevant Configuration

No response

I acknowledge that:

• I have reviewed the FAQ and confirm that my issue is NOT among them.
• I have searched the Ghostty documentation and confirm there doesn't exist a configuration option that solves my issue.
• 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.

[sorokin-vladimir]

// Minimal reproduction: replacing the image under a Kitty graphics id that a
// Unicode placeholder grid is showing leaves the cells blank until the new
// image is decoded. Run it in Ghostty with `go run main.go`; only the Go
// standard library is used.
//
// Phase 1 (4 s): two light noise frames (~640x360 PNG, a few hundred KB) are
// sent alternately to the same image id at 15 fps; the grid on screen never
// changes. Dark flashes appear between frames.
// Phase 2 (4 s): the same frames alternate between two ids, and the grid is
// switched to an id only on the tick after its image was sent. No flashes.
package main

import (
	"bytes"
	"encoding/base64"
	"fmt"
	"image"
	"image/color"
	"image/png"
	"math/rand"
	"os"
	"strings"
	"time"
)

const cols, rows = 40, 12

// diacritics are the first row/column diacritics of the Kitty protocol.
var diacritics = []rune{
	'̅', '̍', '̎', '̐', '̒', '̽', '̾', '̿',
	'͆', '͊', '͋', '͌', '͐', '͑', '͒', '͗',
	'͛', 'ͣ', 'ͤ', 'ͥ', 'ͦ', 'ͧ', 'ͨ', 'ͩ',
	'ͪ', 'ͫ', 'ͬ', 'ͭ', 'ͮ', 'ͯ', '҃', '҄',
	'҅', '҆', '҇', '֒', '֓', '֔', '֕', '֗',
}

func noise(seed int64, tint color.NRGBA) []byte {
	r := rand.New(rand.NewSource(seed))
	img := image.NewNRGBA(image.Rect(0, 0, 640, 360))
	for y := 0; y < 360; y += 2 {
		for x := 0; x < 640; x += 2 {
			v := uint8(190 + r.Intn(60))
			c := color.NRGBA{R: min(v, tint.R), G: min(v, tint.G), B: min(v, tint.B), A: 255}
			for d := range 4 {
				img.SetNRGBA(x+d%2, y+d/2, c)
			}
		}
	}
	var b bytes.Buffer
	if err := png.Encode(&b, img); err != nil {
		panic(err)
	}
	return b.Bytes()
}

// transmit sends a PNG under id with a virtual placement of cols x rows,
// in 4096-byte chunks.
func transmit(id int, data []byte) string {
	p := base64.StdEncoding.EncodeToString(data)
	var b strings.Builder
	for i := 0; i < len(p); i += 4096 {
		end := min(i+4096, len(p))
		more := 0
		if end < len(p) {
			more = 1
		}
		if i == 0 {
			fmt.Fprintf(&b, "\x1b_Ga=T,f=100,t=d,i=%d,U=1,c=%d,r=%d,q=2,m=%d;%s\x1b\\", id, cols, rows, more, p[i:end])
		} else {
			fmt.Fprintf(&b, "\x1b_Gq=2,m=%d;%s\x1b\\", more, p[i:end])
		}
	}
	return b.String()
}

// grid draws the placeholder cells for id below the title line.
func grid(title string, id int) string {
	var b strings.Builder
	fmt.Fprintf(&b, "\x1b[H\x1b[2K%s\r\n", title)
	for r := range rows {
		fmt.Fprintf(&b, "\x1b[38;2;%d;%d;%dm", (id>>16)&0xff, (id>>8)&0xff, id&0xff)
		for c := range cols {
			b.WriteRune('\U0010EEEE')
			b.WriteRune(diacritics[r])
			b.WriteRune(diacritics[c])
		}
		b.WriteString("\x1b[0m\r\n")
	}
	return b.String()
}

func main() {
	frames := [][]byte{
		noise(1, color.NRGBA{R: 255, G: 255, B: 255}),
		noise(2, color.NRGBA{R: 255, G: 245, B: 200}),
	}
	out := os.Stdout
	tick := time.Second / 15
	fmt.Fprint(out, "\x1b[2J\x1b[?25l")
	defer fmt.Fprint(out, "\x1b_Ga=d,d=A,q=2\x1b\\\x1b[2J\x1b[H\x1b[?25h")

	fmt.Fprint(out, transmit(1, frames[0]))
	fmt.Fprint(out, grid(fmt.Sprintf("1/2: one id, each frame replaces the image on screen (%d KB per frame)", len(frames[0])/1024), 1))
	for i := 1; i < 60; i++ {
		time.Sleep(tick)
		fmt.Fprint(out, transmit(1, frames[i%2]))
	}

	fmt.Fprint(out, transmit(2, frames[0]))
	for i := 1; i < 60; i++ {
		time.Sleep(tick)
		fmt.Fprint(out, grid("2/2: two ids, the grid moves to an id a tick after its image was sent", 2+(i-1)%2))
		fmt.Fprint(out, transmit(2+i%2, frames[i%2]))
	}
	time.Sleep(tick)
}

[mitchellh]

FYI Kitty behaves the same way. The spec doesn't mandate this behavior though so I can fix it in Ghostty.

[mitchellh]

#15184