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

[elifarley]

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:

Delivery	Result
writeSync(1, apc) from inside the renderer	image draws
APC as first renderer row, 4096-byte payload	no image (row wraps at terminal width → sequence corrupted)
APC split into 96-byte / 64-byte row chunks, chained with m=1/m=0	still no image

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 ModApi: UI Layout & Display primitives #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

• ModApi: UI Layout & Display primitives #633 §7 — cmd.ui.image() feature request (the umbrella this bug blocks)
• Support markdown renderer in feed so mods can output formatted into #609 — adjacent: feed rendering surface limitations for mods

[elifarley]

Self-contained repro attached (kitty-graph-repro.ts): the encoder (chunked kitty APC), the capability gate, and both delivery strategies — Delivery A draws the image, Delivery B (renderer rows) never does.

// kitty-graph-repro.ts — Delivery A works, Delivery B never does
// (full file attached; excerpt here for the renderer)

export default function (cmd: any): void {
  cmd.addRenderer('kitty-graph', (data: any) => {
    // Delivery A: WORKS — image draws immediately, but anchored at the
    // cursor's current position (placement drifts relative to the feed block).
    require('node:fs').writeSync(1, data.escape);

    // Delivery B: NEVER DRAWS — same bytes returned as renderer rows:
    // const lines = [data.escape];  // + blank rows + caption
    // - 4096-byte payload: row wraps at terminal width → sequence corrupted
    // - 96/64-byte chunks chained with m=1/m=0: still no image
    // Kitty rejects silently (q=1) in every failure case.
    const rows = Math.max(2, Math.min(200, Number(data?.placeRows) || 1));
    const lines: string[] = [];
    for (let i = 1; i < rows; i++) lines.push('');
    lines.push(typeof data?.caption === 'string' ? data.caption : '');
    return lines;
  });
}

Environment: Command Code 1.37.0, kitty 0.42, interactive TTY, PNG produced by mmdc (browser-rendered, 784×62 — draw-verified over raw fd write).

[vipulgupta2048]

@elifarley Do you have a video/screenshot for this to understand what's going on?