Renderer rows silently corrupt Kitty APC graphics escapes — blocks inline images from mods

Summary

Mod renderer rows silently corrupt Kitty Graphics Protocol (APC) escape sequences, making inline images impossible from mods even though the docs promise row styling with raw codes (api.md: "style them with ansi escapes — picocolors, @commandcode/tui helpers, or raw codes"). SGR escapes survive; multi-line APC payloads do not. This bug blocks any cmd.ui.image()-style feature (see #633 §7) and any mod that talks to a terminal graphics protocol.

Repro (mod-side, minimal)

A mod registers a renderer whose first row is a complete kitty APC (\x1b_Gf=100,q=1,a=T,...;<base64>\x1b\\). The same bytes written directly to fd 1 draw the image; the same bytes returned as a renderer row never draw. Verified today on kitty 0.42 with a browser-rendered PNG (784×62), all in a live session:

Root cause (two layers)

1. Wrap corruption: a KB-scale APC cannot fit one terminal line; the feed wraps long rows at the column width, splitting the sequence mid-payload. Kitty silently drops malformed graphics sequences when q=1 — no error reaches the mod or the user.
2. Chunk-chain interleaving: splitting into line-sized chunks per the protocol's own m= continuation mechanism doesn't help either — the feed joins rows with \n and full-screen repaints can split the chain across writes, and interleaved bytes between continuation chunks invalidate the transmission (again silently).

The SGR-red-caption probe proved the pipe itself passes escapes — the chain specifically dies between chunks.

What would fix it

Either of:

1. APC passthrough in the row pipeline — treat \x1b_G…\x1b\\ as an atomic zero-width unit in the width calculator and row sanitizer (the same allowance SGR already gets), so a chain of line-sized APCs rides the row stream intact. Mod-side we already chunk to 64-byte rows precisely for this.
2. A first-class image API — e.g. cmd.ui.image({ path, rows }) that owns protocol detection, chunking, placement, and repaint behavior (would supersede/fold into #633 §7 cmd.ui.image(); this issue supplies the pipeline groundwork it needs).

Until then, mods must fall back to writing directly to fd 1, which draws the image but anchors it to whatever the cursor happens to be at render time — placement drifts relative to the feed block (phantom padding), and it breaks under scroll.

Environment

• Command Code 1.37.0 (npm global)
• kitty 0.42, TERM=xterm-kitty, interactive TTY (graphics protocol verified working via raw fd write)
• Repro mod: kitty-graph-repro.ts (attached to this issue) — encoder, capability gate, and both delivery strategies; the Delivery A/B switch is a one-line change in the renderer

Related

• #633 §7 — cmd.ui.image() feature request (the umbrella this bug blocks)
• #609 — adjacent: feed rendering surface limitations for mods

Bắt đầu với kitty-graph-repro.ts được đính kèm và kiểm tra pipeline hàng của renderer, bao gồm bộ tính chiều rộng và bộ làm sạch hàng của nó. So sánh việc ghi trực tiếp vào fd với các APC được trả về dưới dạng hàng, sau đó xác minh trong môi trường kitty đã nêu rằng các chuỗi APC hoàn chỉnh và được chia thành chunk vẫn vượt qua quá trình repaint mà không bị hỏng hoặc xen kẽ.