Draw a card's picture inside the card frame

[Aduneer]

The natural sequel to audio, and the card frame absorbs it: an eleventh deck column names an image beside the deck, resolved by Deck::resolve() exactly as the audio column is, and drawn above the prompt.

Where the rows come from

The open question in the backlog was how count_frame_lines() could know how many rows a picture occupies, since an image is not a line of text. It turns out we get to say. A terminal speaking the kitty protocol scales an image into a box of cells you name — but give it both r and c and it stretches to fill them rather than fitting inside, so a 4:1 panorama comes out looking 8:1. The aspect arithmetic therefore has to happen in FlashTerm, which is what fit() is, and it needs the picture's real dimensions.

Those are free: PNG, GIF and JPEG all carry them in the header — a fixed offset for the first two, a segment walk for the third. Only the header is read, so a large photograph costs no more than a thumbnail, and the escape sequence names the file rather than carrying it: about sixty bytes whatever the picture weighs, which matters on a screen redrawn after every keypress.

Two bugs the demo GIF found, and nothing else would have

Re-rendering demo.gif caught both. Neither is visible to a unit test or a golden transcript, because both are about what a terminal does with bytes that are perfectly well-formed.

Detection read $TERM_PROGRAM. That is an ordinary environment variable, so it is inherited and outlives the terminal that set it — a session under tmux, over ssh, or inside a screen recorder still carries it. vhs inherited ghostty from the launching shell, FlashTerm believed it, reserved eight rows in a terminal that cannot draw a kitty graphic, and left a hole in the card:

Detection is now $TERM alone, which is replaced per session and so tells the truth. A hole where a picture should be is worse than no picture, so the guess is now deliberately pessimistic; terminals that can draw but do not say so in $TERM — WezTerm — want FLASHTERM_IMAGE=kitty, which is documented.

The chafa fallback forced --format=kitty, which is exactly backwards: that path exists for terminals that cannot draw one. Letting chafa choose was no better — it picks kitty astonishingly readily, doing so even with $TERM=xterm-256color and its output going down a pipe. It is now asked for symbols, the one answer that is right everywhere, which also means pictures work over ssh and inside tmux.

That makes the picture several lines of text, and text has to be placed: every line after the first would otherwise start at column zero and write straight through the frame's left border. So chafa's output is captured rather than inherited and each line is put where it belongs. Its cursor-hide/show pair is stripped — the trailing one sat on a line of its own and counted as one more row than the frame had reserved.

Both ways of drawing now leave the cursor on the row they started on, so the frame's arithmetic does not depend on which one ran.

Graceful everywhere else

A deck of pictures is still a deck. No terminal support, output in a pipe, FLASHTERM_IMAGE=none, a missing file, or a file that is not really an image — all produce an ordinary text card, byte-identical to one with no picture at all. Three golden cases prove exactly that and a fourth proves the picture appears when it should:

case	frame rows	escape
review-image	11	1
review-image-none	3	0
review-image-missing	3	0
review-image-not-an-image	3	0

A deck with no pictures also still serialises byte for byte as v0.2.0 wrote it, since columns are written only as far as the last one a card uses.

Harness

FLASHTERM_IMAGE=none is pinned for every golden case. Without it a transcript observes $TERM and whether chafa happens to be installed — the same case would have drawn a picture locally and nothing on CI, the exact failure #16 established the pinning rule for.

Transcripts were also going binary, which would have behaved differently under mawk on CI than gawk locally. Escapes are now collapsed to readable tokens, awk runs under LC_ALL=C, and binary fixtures are summarised rather than dumped. The tokens are not cosmetic — the transcript now pins the layout arithmetic:

<CURSOR A12><CR><CURSOR C20><IMAGE a=T,f=100,t=f,C=1,c=24,r=8;aW1hZ2VzL3BlcnJvLnBuZw==><CURSOR B12><CR>

<CURSOR A12> failing to match <CURSOR B12> now fails visibly.

Demo and examples

demo.gif re-rendered; el árbol carries a picture, drawn as coloured blocks — which is what a reader without a graphics terminal actually sees. The tape clears TERM_PROGRAM and KITTY_WINDOW_ID for the reason above.

examples/colores.csv is new, with swatches in examples/images/. It runs English → Spanish, against every other language deck here, and that is the point: a picture shows the meaning, so on rojo → red it hands over the answer and on red → rojo it cannot. Its ids are pre-minted so studying it does not dirty the repo.

No example audio ships and none should — --generate-audio exists precisely so recordings are rendered locally rather than committed.

Testing

680 unit checks (up from 679) and 47 golden cases (up from 42), green on gcc and clang, optimised and sanitised, and clean in an env -i clean room. Verified from a fresh clone, since this adds binary fixtures.

Visually confirmed in Ghostty across three deliberately awkward aspect ratios — 3:2, a 2:3 portrait, and a 4:1 panorama — plus a card with no picture, and in the vhs recording via the chafa path.