Add Kitty graphics protocol support on top of this branch

[kotamat]

Summary

This PR implements the Kitty graphics protocol (termux#5068) by wiring up the APC (ESC _ G ... ESC \) parsing path that already exists on this branch but is inert — doApc() is a no-op and the call from receiveApcEsc() is commented out ("Eat APC sequences silently for now").

This PR is based directly on sixel4 and adds a second front-end that shares the same backend your image work introduced here — the same image registry, bitmap storage, and rendering path. It does not modify your Sixel or iTerm2 code paths, aside from three independent bug fixes described below. The diff against sixel4 is purely additive: 9 files changed, 3,459 lines added, across 7 commits.

I've opened the same underlying change against termux/termux-app's master branch as well, as termux#5238. That copy necessarily also carries this branch's own commits along with it, since master doesn't have this work yet, so the diff there is larger and includes code that isn't mine. You only need to look at one of the two, whichever is more convenient — they're the same change.

Relationship to this branch and to the maintainer's stated direction

In issue termux#5068 on termux/termux-app, @robertkirkman noted that Sixel should be prioritized for merge ahead of Kitty support, since Termux isn't in the position kitty.js is in and shouldn't drop Sixel. I agree with that ordering, and this PR is written on that basis: it assumes your Sixel/iTerm2 work (termux#2973) merges to master first, and adds Kitty as a second, independent front-end on top of it, without touching your Sixel/iTerm2 code paths.

I'm opening this directly against sixel4 rather than waiting for termux#2973 to land on master, so it's visible and reviewable in parallel, and so the bug fixes below (which apply to this branch directly, independent of Kitty) aren't lost in the meantime. I'm not asking for this to be merged ahead of your work — this is offered as something to pick up if and when it's useful, entirely on your timeline. As I see it, the options are: take this whole PR once termux#2973 merges to master, leave it separate/deferred while termux#2973 is reviewed on its own, or take just the three independent bug fixes described below now and set the Kitty front-end aside for later (or not at all). Whatever's most convenient for you is fine with me.

What's implemented

Feature	Status
Action a=t (transmit)	Supported
Action a=T (transmit + display)	Supported
Action a=p (put / placement)	Supported
Action a=q (capability query)	Supported
Action a=d (delete: all, d=a/d=A, d=i/d=I)	Supported
Transmission medium t=d (direct, base64)	Supported
Format f=100 (PNG)	Supported
Format f=24 (RGB raw)	Supported
Format f=32 (RGBA raw)	Supported
Chunked transmission m=1/m=0	Supported (payload decoded incrementally per chunk, not buffered)
Image id i= (full 32-bit unsigned range)	Supported
Placement id p=	Supported, keyed by (image_id, placement_id)
Cell sizing c=/r=	Supported
Pixel sizing s=/v=	Supported
Source rectangle x=/y=/w=/h=	Supported (crop, then scale)
Response control q= (0/1/2)	Supported
Success/error responses (OK, <CODE>:<msg>)	Supported
C=1 (don't move cursor after placement)	Supported
Transmission media t=f/t=t/t=s (file, temp file, shared memory)	Not supported — returns ENOTSUP
Compression o=z (zlib)	Not supported — returns ENOTSUP
Animation actions a=f/a=a/a=c	Not supported — returns ENOTSUP
Unicode placeholder placement (U=1)	Not supported. The key is parsed but ignored — no placeholder-based placement is implemented
z= (z-index)	Parsed, ignored
X=/Y= (sub-cell pixel offset)	Parsed, ignored — can cause up to a 1-cell visual offset compared to a fully compliant renderer

On U=1: some clients (e.g. yazi) can use the Unicode placeholder path, but since Termux advertises Sixel support in DA1, yazi selects Sixel instead of Kitty's placeholder mechanism in that case, so this gap does not affect yazi in practice. It would matter for a client that requires Unicode placeholders specifically.

Reuse of this branch's infrastructure

This PR does not introduce a parallel image system. It reuses, unmodified in behavior:

• The 64-bit packing of image coordinates into TextStyle
• TerminalBuffer's image registry and scroll-driven garbage collection
• TerminalBitmap's cell-splitting and size-limiting logic
• TerminalRenderer's existing bitmap draw branch

Your Sixel and iTerm2 code paths (build(byte[]...), build(TerminalSixel...), addTerminalBitmapForImage()) are structurally unchanged by this PR — Kitty parsing produces the same intermediate bitmap representation that Sixel/iTerm2 already produce, and goes through the same storage/rendering code from there.

Tests

• Baseline: 145 existing terminal-emulator tests, all passing on sixel4, unmodified.
• Added: 74 new tests for the Kitty parsing/action/response path, for a total of 219, with zero regressions in the existing baseline. ./gradlew :terminal-emulator:test reports 219 tests / 0 failures / 0 errors for both testDebugUnitTest and testReleaseUnitTest.
• These 74 new tests exercise the shared image infrastructure (registry, bitmap storage, GC) in addition to the Kitty parsing itself, since Kitty runs through that same backend.
• Error-path coverage includes: unterminated sequences, malformed base64 (invalid characters, len % 4 == 1, excess padding, data after padding, padding in a non-final chunk), unknown actions/keys, interruption mid-chunk-transfer, sequences left open with m=1 and never closed, oversized dimensions, deletion of nonexistent ids, out-of-scope keys for a given action, very large i= values, and response suppression behavior for each q= level.
• Chunk-boundary base64 decoding is cross-checked against java.util.Base64 as an independent reference implementation, across a range of chunk split points, to confirm the incremental decoder produces byte-identical output to decoding the same payload in one piece.
• Two end-to-end tests reproduce specific byte sequences captured from disassembling real client output, rather than only hand-constructed protocol messages.

Verification on emulator

All of the following was verified by running the build on an Android emulator (API 35, AOSP system image, arm64-v8a, headless, software rendering) and inspecting the result — not just by reading the code. Verification consisted of pixel measurements on captured screenshots, dumpsys meminfo readings, and adb logcat -b crash checks, unless noted otherwise:

• End-to-end draw pipeline for raw RGB (f=24), raw RGBA (f=32), and PNG (f=100), at sizes from 1×1 up to 64×64.
• Repeated placement via a=p: one transmit followed by five separate put commands, all five renders confirmed present.
• Channel order is R,G,B[,A], non-premultiplied: confirmed by sending pure red, pure green, pure blue, and white, and confirmed that alpha = 128 produces the same on-screen result for both raw and PNG input.
• Source rectangle selects the correct quadrant: tested against a four-quadrant test image for all four quadrants, for both raw and PNG input, confirming the crop-before-scale ordering.
• c=/r= cell-based scaling is pixel-accurate against a 19×38px cell size: both dimensions specified matches exactly, one dimension specified preserves aspect ratio, neither specified renders at native size.
• C=1 leaves the cursor position unchanged, confirmed via DSR cursor-position queries before and after placement.
• Deletion actually clears the affected pixels, with no leftover image data on screen afterward.
• 20 malformed/edge-case sequences produce no crash and no visible display corruption; subsequent text and SGR colors continue to render correctly afterward.
• A full-screen 1080×2400 RGBA frame (10.4MB payload, sent across 3375 chunks) renders without an out-of-memory error.
• Sixel and iTerm2 output is pixel-identical to their behavior before this PR (no regression). Sixel output was checked row-by-row against expected RGB values.
• The crash log buffer remained empty and the process PID stayed constant across the full verification run (roughly 30 minutes).

Verification on physical device

The above was also verified on a physical device: Samsung SM-F966Q (Galaxy Z Fold7-generation), Android 16 / SDK 36, arm64-v8a, 10.85GB RAM. Measured terminal calibration: origin at (7,119), cell size 19×38px, 56 columns × 56 rows. A 1-cell image renders as exactly 19×38 = 722px of solid color with zero bleed into neighboring cells; this was reproduced twice.

Verified items (each backed by a pixel measurement or a DSR-based numeric check):

• Sixel/iTerm2 regression check. An iTerm2 4×2 quad image measures 76×76px, with each of the four quadrants covering exactly 1,369px. A sixel image measures exactly 120px (spanning two cells: 114 + 6), pixel-identical to its pre-existing output.
• Text on the same row as an image (the effect of bug fix Add Kitty graphics protocol support on top of this branch #2, below). Verified across seven mixed-content cases, including: two images on one row (L2_A / image / L2_B / image / L2_C), three adjacent segments (text in columns 0–3, a 6-cell-wide bitmap in columns 4–9, text in columns 10–13), and a case where styled text spans a renderer flush boundary — L7_RED_ rendered in (205,0,0) before an image, L7_GRN rendered in (0,205,0) after it — confirming that the flush correctly carries lastRunStyle across the boundary.
• Alpha handling. α=255 → (255,0,0); α=128 → exactly (128,0,0); α=0 → fully invisible (0 of 1,444px show any trace, with no bleed of the green background); α=128 on white → (128,128,128). Raw RGBA and PNG produce identical results in every case, which rules out premultiplied-alpha handling differences on the real GPU.
• Formats. 1×1 / 2×2 / 19×38 images sent as f=24, f=32, and f=100, with histograms matching exactly across formats (no channel-order drift).
• Error paths. The existing 20 malformed-input cases, plus 5 additional boundary cases, plus a single oversized command sent as one unchunked payload (262,144 characters). No crash, no display corruption, no corruption of subsequent text.
• Memory — see below.
• Crash monitoring. PID 23641 remained constant over a 27-minute run, the crash log buffer stayed empty, and no OutOfMemoryError or ANR occurred.
• Reflow via fold/unfold. cmd device_state state 3 was used to force a column-count change (56×56 → 102×48), exercising the terminal's reflow path. No crash. iTerm2, sixel, and Kitty images all produce identical reflow artifacts — see the corresponding entry in Known Limitations below.

Memory under sustained placement load

Measured under a streaming workload (one a=t transmit followed by 200 a=p re-placements of the same image), sampled 1,738 times:

	Native heap PSS	Total PSS
Baseline	15.5 MB	90.2 MB
Peak (t=8s)	90.7 MB	170.8 MB
Shortly after (t=18–22s)	18.9 MB	104.3 MB
After 120s idle	18.9 MB	103.4 MB

Memory returns to baseline+13MB within roughly 10 seconds and stays flat from there; the residual is consistent with the single displayed 1064×760×4 = 3.2MB bitmap. This was checked against a false-pass: the on-screen marker === HEAVY DONE 200 frames === confirmed the full run completed, the rendered image area measured 1064×760 with each of the four quadrants at exactly 200,870px, and there were no KittyImage/TerminalBitmap error log lines during the run.

Why this matters: a=p re-places an already-cached image with a command of roughly 30 bytes, so placements can happen at a much higher rate than Sixel/iTerm2 allow, since those protocols require re-sending the full image on every frame and are bandwidth-bound as a result. A naive implementation could accumulate orphaned bitmaps under that kind of load. This implementation performs targeted collection at placement time: it collects the bitmapNums referenced by the cells being overwritten, scans only the rows with mHasTerminalBitmap set, and exits early once a reference to a given bitmap is found elsewhere. It does not call recycle() — references are simply dropped and left to the GC, since the renderer may hold a reference from a different thread. The existing throttled doTerminalBitmapsGC on this branch is unmodified.

Included bug fixes (independent of Kitty, directly applicable to this branch)

While building the Kitty front-end on top of this branch's image pipeline, I found and fixed three pre-existing issues unrelated to the Kitty protocol itself. Each is isolated into its own commit on top of sixel4, so any of them can be reviewed, taken, or set aside independently of the rest of this PR — you don't need to take the Kitty commits to take these.

1. Infinite loop in TerminalBitmap.build(). When BitmapFactory fails to decode bounds for the input, outWidth/outHeight come back as 0, and the aspect-ratio-preserving scaleFactor loop condition 0 >= 0 never terminates. In testing, scaleFactor overflows and pins at 0 after 201 iterations, so the loop spins indefinitely rather than overflowing into a crash. On the current state of sixel4, this is reachable directly, with no Kitty involvement, from OSC 1337;File=inline=1;width=10:<garbage> — a malformed iTerm2 image sequence can hang the JVM.

2. Text preceding an image on the same row is dropped. In TerminalRenderer.java (lines 106–121), the bitmap-drawing branch discards a pending text run instead of calling drawTextRun for it, and separately has an off-by-one in lastRunStartColumn (column + 1). This reproduces identically with this branch's existing iTerm2 (OSC 1337) images, so it isn't Kitty-specific — it's a pre-existing rendering issue in the shared renderer path that this PR's tests happened to surface.

3. Cursor position when an image ends exactly in the last column. The bounds check used col < mColumns - 1, which treats an image that ends exactly at the last column as "didn't fit," consuming one more row than the image actually covers and leaving the cursor at the start of the following row. col < mColumns is the correct condition.

   The evidence for this one comes specifically from the existing iTerm2 (OSC 1337) path, not from a Kitty-vs-Kitty comparison — on a pristine sixel4 checkout, Kitty's APC sequences are still parsed and discarded, so no Kitty image is ever displayed and there is nothing to compare against there. To isolate the bug from anything Kitty-related, I built a pristine sixel4 checkout in a separate git worktree and compared it directly against this PR's tree using an iTerm2 image, both built and run the same way:

   • Pristine sixel4, a 2×1 iTerm2 image placed in columns 54–55 (1-based) of a 56-column screen: cursor-position DSR reports [7;1 (wrapped to the next row, column 1).
   • This PR (same image, same placement): DSR reports [6;56 (the image's last row, column 56 — the next empty cell after the image, so subsequent characters do not overlap it).

   Because this changes existing Sixel/iTerm2 cursor behavior, not just Kitty, it's kept as its own commit so it can be evaluated, taken, or dropped independently of the rest of this PR. If you consider the current behavior intentional, this commit can be dropped without affecting the Kitty support — the only consequence would be that a Kitty image ending exactly in the last column would keep consuming one extra row, same as iTerm2/Sixel currently do. Three unit tests are included (image ending exactly in the last column, image that genuinely doesn't fit, and the normal case).

Known limitations / honest caveats

• For PNG payloads, the client-declared s=/v= values are used as the primary input to source-rectangle validation. The decoded bitmap dimensions remain the ground truth for rendering, so this is safe in the sense that it can't produce out-of-bounds reads, but a client that declares dimensions inconsistent with the actual PNG could get a legitimate crop request rejected with EINVAL.
• d=a/d=A deletes all Kitty placements regardless of current on-screen visibility; the spec describes this action as scoped to placements "visible on screen."
• TextStyle encodes bitmapNum in 16 bits while TERMINAL_BITMAP__NUM_END is defined as Integer.MAX_VALUE. This mismatch predates this PR — it's already present on sixel4 — and is not touched here.
• TerminalBuffer.resize() does not remap bitmap-bearing cells. This is existing behavior already present on sixel4, not changed by this PR.
• Multi-row images split apart on reflow. When the column count changes (e.g. folding/unfolding a foldable device), an image spanning multiple rows can end up separated into two fragments with a gap row between them, because the wrap-continuation rows move independently of the image. I verified on-device that this happens identically for iTerm2, Sixel, and Kitty images — it's pre-existing behavior from this branch's resize/reflow handling, not something this PR introduces or changes. Noting it here explicitly so it isn't mistaken for a regression caused by this PR.
• Minor bilinear seam at scaled quadrant boundaries. When scaling, there's a roughly 0.6% strip of blended pixels at internal quadrant boundaries. This showed up on the physical device's GPU-accelerated rendering path but not on the emulator's software renderer; it's expected behavior of hardware bilinear filtering, not a bug in the scaling logic.

Emulator vs. physical device: notable differences

• The transient memory peak is roughly 4x larger on the physical device: 73.6MB above baseline on the emulator vs. 170.8MB above baseline on the device (baseline+80.6MB is roughly consistent with 25 still-live 3.2MB bitmaps awaiting collection). The device's GC appears to reclaim memory later than the emulator's. This is harmless at 10.85GB of RAM, but worth knowing about for lower-RAM or larger-screen devices, since the transient peak could matter there even though the steady state is fine.
• Fold/unfold-driven reflow could only be exercised on the physical device — the emulator has no equivalent state transition to reproduce it.

What I'd like reviewers to look at

• Whether you'd rather take this whole PR once Add graphics in terminal support: - Sixel and iTerm2 protocols termux/termux-app#2973 lands on master, keep it separate/deferred while Add graphics in terminal support: - Sixel and iTerm2 protocols termux/termux-app#2973 is under review, or just take the three bug fixes below independent of the Kitty front-end — happy to go whichever way is most useful to you.
• The APC parsing and base64/chunking logic in isolation, since that's the only genuinely new parsing surface this PR adds.
• Whether the three included bug fixes should be split out as their own small PR against sixel4 instead of riding along here — in particular bug fix [FR] option to read password with termux-api? termux/termux-app#3, since it changes existing Sixel/iTerm2 cursor behavior and you may want to weigh in on whether the current behavior was intentional.
• The U=1 / Unicode-placeholder gap — whether that's an acceptable scope cut for a first pass, or a blocker.
• Error code/message choices for the ENOTSUP paths (file/shared-memory transmission, zlib, animation), in case there's a preferred convention already used elsewhere in the codebase.