[glitch-cmyk658]

Two commits that together make the APC image path work against a real page reader.

The transfer a reader sends is refused before it is stored

A reader marks "nothing to undo" with z=-1 in the header of the crop it is about to place. z only describes payload packing when o=z is present, which this terminal does not implement, so that value must not decide whether a transfer is accepted. Parsing it is also wrong here: every other numeric key is unsigned, while this one carries -1, so z=-1 failed as a parse error and the page was dropped before it reached storage. The field is now ignored; the payload length is still checked when the transfer is decoded.

The rest of the protocol the reader expects

• f=100 containers. The terminal keeps the file as sent and reads the geometry from its IHDR header; the frontend inflates it on the decode thread, so a page never has to travel as raw pixels. Bounded by a 64 MiB container budget and the existing pixel cap.
• Feature queries. a=q,e=<action> answers with the keys this terminal honours (e=T,C=1,f=100,...) instead of ENOTSUP. That answer is how a client discovers the container format before sending one, and it can downgrade otherwise.
• Payload tolerance. Base64 without canonical padding decodes, and whitespace inside a payload is stripped instead of dropping the whole sequence silently.
• Deletes. d=p, d=c, d=x, d=y, d=r and d=n in addition to d=a/d=i; the uppercase form still frees the pixel data.
• Encoded staging budget. 24 MiB to 64 MiB: a 4K page is 33 MiB of base64 while it streams, and the old cap refused it mid-transfer.

Tests

• cargo test -p nebula_terminal --lib - 384 passed, 2 failed; the two failures are the pre-existing tty::windows::proxy_tests, which need a real console
• the graphics tests inside that run - 38 matched, twelve of them new: the container header, a malformed container, an unpadded payload, the feature answers, and each new delete selector
• cargo test -p nebula --features gpui-shell --bin pebrel inline_image::tests - 19 passed
• cargo test -p nebula_terminal --test grid_images - 12 passed
• cargo fmt --all and python scripts/check_architecture.py - both clean
• live, on the built binary: a real PNG sent as a=T,f=100 renders inside its 20x10 cell box; a 584 page PDF still renders through the same reader; the three feature-query replies were captured from a raw pty:

a=q,i=31,e=T,U=1,C=1         -> i=31,e=T,C=1;OK
a=q,i=32,e=f                 -> i=32;ENOTSUP
a=q,i=33,e=T,f=100,c=20,r=10 -> i=33,e=T,c=20,r=10,f=100;OK

U=1 is omitted because it is not implemented, which is what the protocol asks for: echo the queried keys that are supported and non-default.

Not implemented here: t=f/t=t/t=s transport, U= placeholders, o=z, placeholder reuse through I= and animation frames.

[glitch-cmyk658]

Cost of the image path

Numbers from this branch (8ff0d574) on Windows 11, release build, one machine — they are for order of magnitude, not a benchmark suite.

Where the time goes

A page goes through three stages: parse+decode in the terminal, hand-off, then create the texture and draw in the app. Only the first and third are ours; the middle is a weak reference to the same buffer, so there is no copy and no round trip.

stage	what it covers
ingest	base64 decode, container inflate, size checks, placement
hand-off	Weak<Vec<u8>> to the app — no copy
upload	decoded pixels → texture, one row loop per frame

Measured, isolated (release, --release, median of 10)

Terminal side, raw payload in one call:

case	payload	ingest
A4 page, RGB 1060×1500	4.77 MB → 6.36 MB base64	3.96 ms
A4 page, RGBA 1060×1500	6.36 MB → 8.48 MB base64	5.66 ms
4K frame, RGB 3840×2160	24.9 MB → 33.2 MB base64	20.68 ms
A4 container (PNG), staging only	2.1 MB	1.56 ms

App side:

case	decode	decode + repack to BGRA
A4 container 1060×1500	19.41 ms	21.98 ms
4K container 3840×2160	105.4 ms	115.04 ms
4K raw → BGRA	—	13.69 ms

So the expensive case is a container that has to be inflated and then repacked: ~115 ms for a 4K page. A raw transfer of the same page is ~35 ms total (20.7 ingest + 13.7 repack).

Measured end to end, one real reader

bookokrat paging 计算机组成结构化方法 (A4, 1060×1500, raw RGB, ~6.4 MB of base64 per page), 20 page turns, timestamps taken inside the app:

• enqueue → draw: 2.9 ms, 3.2 ms, 3.5 ms, 3.5 ms, 3.7 ms, 4.7 ms (six consecutive turns; the rest were re-placements of an already decoded page and produce no new work)
• the page is visible in the frame that follows the decode, so the perceived cost is one frame plus the work above.

The wall-clock from the pty write to the first byte of the app's frame was not measured reliably: the terminal tags the transfer with the client's image id while the app tracks its own placement id, so the two logs do not join without extra plumbing. What is known is the ingest number above and that the app never re-decodes the same page twice (re-placements reuse the cached texture).

Memory

budget	before	after
app cache	16 images / 128 MiB	32 images / 256 MiB
terminal store	16 images / 128 MiB	16 images / 128 MiB
staging for one transfer	24 MiB	64 MiB
worst case resident	≈ 280 MiB	≈ 448 MiB

An A4 page costs ≈ 11 MB resident (4.77 MB in the terminal, 6.36 MB as a BGRA texture), so the terminal's store is what caps first at ≈ 26 pages / ≈ 290 MB. A 4K transfer peaks at ≈ 58 MB transient (33 MB of base64 plus 25 MB decoded) and the staging cap is what makes it possible at all — before this branch a 4K page failed with E2BIG before it was ever stored.

What I would do next, if the 115 ms container case matters

Inflate straight into the texture format the app draws (BGRA), which removes the repack pass and roughly halves the container cost. That is a separate change and not part of this PR.