Skip to content

Stop a video's own frames asking the app to drop the screen - #36

Merged
m96-chan merged 2 commits into
mainfrom
ghostty-image-eviction-flicker
Sep 14, 2026
Merged

m96-chan merged 2 commits into
mainfrom
ghostty-image-eviction-flicker

Conversation

@m96-chan

Copy link
Copy Markdown
Owner

A regression from #34, found on an iPhone 17e within minutes of playing a video through the terminal: on the libghostty-vt engine, stepping through video frames put a black frame between every pair of frames. Drawing repaints without that flicker is most of what makes this engine worth selecting, so it is a straight loss against what shipped before.

What it was

onImageCacheInvalidated means "let go of the snapshot you are showing, its pixels are being taken away". ConnectionModel answers it by publishing a nil snapshot (App/ConnectionModel.swift:164), which clears the renderer's rows, so the next draw is the terminal's background colour and nothing else. That is the right trade when the memory is genuinely going away — it is what #26 added the callback for.

#34 then called it from four more places, all of them bookkeeping rather than memory pressure:

Path Runs Is the memory going away?
Reaping an entry whose image the library already dropped every snapshot no — the image is already gone from the terminal
Replacing one generation of an image's pixels with the next every redraw of an image no — the replacement is already decoded
The count cap displacing the least recently drawn entry once past 64 images no — this engine asked for the room
The shared budget reaching back into this engine once the workspace ceiling is reached no — same, it arrives through the same protocol method

Two of them could not fire before #34 at all, because nothing ever reached this engine's image cache until #34 made PNG decode.

What it is now

The announcement has one caller shape again: something outside this engine taking the memory. A memory warning, or another session's image displacing this one — the hidden-session case #26 was written for, where the last frame a session drew would otherwise keep the bytes alive indefinitely. Everything else reaps silently.

isMakingRoomForOwnImage is what tells the budget's callback which of the two it is, since both arrive through the same TerminalImageBudgetOwner.evictImage(_:).

Measurement

The frame-stepping test this adds — 80 frames at a ceiling that holds sixteen:

3092 announcements before, 0 after.

Three tests cover the paths separately (deleting an image, replacing its pixels, stepping through frames until both ceilings start displacing earlier ones). Each of the three fails against main.

What is not changed

The cost is that a published snapshot can hold one frame's pixels that the budget has already released — bounded by one frame per session, and replaced by the next frame that is already being built.

Verification status, stated plainly

The first half of this (delete, replace) is confirmed on device: the reporter's video no longer flickers with it installed. The second half (count cap, budget self-displacement) is covered by the test above but has not been observed on hardware — the content that found this did not take that path.

🤖 Generated with Claude Code

m96-chan and others added 2 commits September 14, 2026 22:57
…reen

A regression from #34, reported from a device: stepping through a video on the
libghostty-vt engine put a black frame between every pair of video frames. Not
drawing those flashes is most of why this engine is worth selecting, so this is
a straight loss against what shipped before.

`onImageCacheInvalidated` means "let go of the snapshot you are showing, its
pixels are being taken away". `ConnectionModel` answers it by publishing a nil
snapshot, which clears the renderer's rows, so the next draw is the terminal's
background colour and nothing else. That is the right trade when the memory is
genuinely going away, which is what #26 added it for.

#34 then called it from four more places, all of them bookkeeping:

- reaping the cache entry of an image the library had already dropped, which
  runs on every snapshot;
- replacing one generation of an image's pixels with the next;
- the count cap displacing the least recently drawn entry;
- the shared budget reaching back into this engine while this engine was the
  one asking it for room.

None of those is memory being taken away from a frame that has to keep it:
either the image is already gone from the terminal, or this engine has just
decoded its replacement and the snapshot carrying it is already being built.

Two of those were invisible until #34 also made PNG decode, because before that
nothing ever reached this engine's image cache to be evicted from it.

So the announcement now has one caller shape: something outside this engine
taking the memory — a memory warning, or another session's image displacing
this one, which is the hidden-session case #26 was written for. Everything else
reaps silently. `isMakingRoomForOwnImage` is what tells the budget's callback
which of the two it is, since it arrives through the same protocol method.

Measured on the frame-stepping test this adds, 80 frames at a ceiling that holds
sixteen: **3092 announcements before, 0 after**. Three tests cover the paths
separately — deleting an image, replacing its pixels, and stepping through
frames until both ceilings start displacing earlier ones — and each fails on the
code before this commit.

The budget is not relaxed anywhere: the same ceiling holds, the same bytes are
released, and the cross-session eviction test is unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`TailscaleImportPresentationTests` failed on the iPad destination of this pull
request's CI run and passed on the iPhone one, at
TailscaleImportPresentationTests.swift:127 — "The fake transport should pause
before requesting host-key confirmation". Nothing in this branch is reachable
from that test: it drives the Tailscale import sheet against a fake transport,
and `GhosttyEngine` is not constructed unless the terminal.engine default says
so, which no test sets.

It is the polling helper's deadline. Five test files have the same helper —
poll a condition every millisecond or twenty until it holds, give up after a
fixed wall-clock deadline of three or five seconds. The deadline is there so a
test that will never pass fails instead of hanging; none of these tests asserts
that something happens *within* that time as a matter of behaviour.

Three to five seconds is not a lot on a runner that has been building for
twenty-five minutes and is on its second simulator. The iPad pass runs second,
which is why this and #32's `WorkspaceLayoutTests` timeout have both landed
there. All five deadlines go to twenty seconds.

This cannot turn a passing test into a failing one: the loop exits the moment
the condition holds, so the deadline is only reachable on the path that was
already failing. Nothing else is relaxed, and no assertion changed.

Folded into this branch rather than sent separately because it is what is
keeping this branch from reporting, and main has not moved.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@m96-chan
m96-chan merged commit a3cd8a6 into main Sep 14, 2026
1 check passed
@m96-chan
m96-chan deleted the ghostty-image-eviction-flicker branch September 14, 2026 14:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant