fix(cli): spec-compliant kitty format ids + PNG conversion for non-PNG payloads

getKittyFormat() now always returns 100 (PNG) — the only format id that
all kitty-protocol terminals guarantee. Non-PNG payloads (JPEG, WebP, GIF)
are converted to PNG via Jimp before transmission, so the bytes always
match f=100. This prevents terminals from silently dropping images due to
fabricated format ids (101-104) that don't exist in the kitty spec.

renderInlineImage() is now async to support the Jimp conversion step.
image-block.tsx and image-card.tsx updated to handle async with
useEffect + state.

New tests validate that the escape sequence uses only spec-compliant
format ids (f=24|32|100) across all media types, and that no fabricated
ids (101-104) appear in any chunk.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: smarpitm

cli/src/components/blocks/image-block.tsx

@@ -1,5 +1,5 @@
 import { TextAttributes } from '@opentui/core'
-import { memo, useMemo } from 'react'
+import { memo, useEffect, useMemo, useState } from 'react'
 
 import { useTheme } from '../../hooks/use-theme'
 import { calculateDisplaySize } from '../../utils/image-display'
@@ -27,19 +27,32 @@ export const ImageBlock = memo(({ block, availableWidth }: ImageBlockProps) => {
     [width, height, availableWidth]
   )
 
-  // Try to render inline if supported
-  const inlineSequence = useMemo(() => {
+  // renderInlineImage is async (converts non-PNG to PNG for kitty),
+  // so we render it in an effect and store the result in state.
+  const [inlineSequence, setInlineSequence] = useState<string | null>(null)
+
+  useEffect(() => {
     if (!supportsInlineImages()) {
-      return null
+      setInlineSequence(null)
+      return
     }
 
-    return renderInlineImage(image, {
+    let cancelled = false
+    renderInlineImage(image, {
       width: displaySize.width,
       height: displaySize.height,
       filename,
       mediaType,
+    }).then((seq) => {
+      if (!cancelled) {
+        setInlineSequence(seq)
+      }
     })
-  }, [image, filename, displaySize])
+
+    return () => {
+      cancelled = true
+    }
+  }, [image, filename, mediaType, displaySize])
 
   // Format file size
   const formattedSize = useMemo(() => {

cli/src/components/image-card.tsx

@@ -77,7 +77,7 @@ export const ImageCard = ({
         }
 
         if (base64Data) {
-          const sequence = renderInlineImage(base64Data, {
+          const sequence = await renderInlineImage(base64Data, {
             width: INLINE_IMAGE_WIDTH,
             height: INLINE_IMAGE_HEIGHT,
             filename: image.filename,

cli/src/utils/__tests__/terminal-images.test.ts

@@ -7,6 +7,11 @@ import {
   resetTerminalImageSupportCache,
 } from '../terminal-images'
 
+/** Helper: await renderInlineImage and return the result. */
+const render = (
+  ...args: Parameters<typeof renderInlineImage>
+): Promise<string | null> => renderInlineImage(...args)
+
 /** Detect kitty support and keep it cached so renderInlineImage uses it. */
 const useKitty = () => {
   resetTerminalImageSupportCache()
@@ -82,36 +87,30 @@ describe('detectTerminalImageSupport', () => {
 })
 
 describe('getKittyFormat', () => {
-  test('maps PNG to 100', () => {
+  test('always returns 100 (PNG) — the only spec-compatible format id', () => {
     expect(getKittyFormat('image/png')).toBe(100)
-  })
-
-  test('maps JPEG to 102', () => {
-    expect(getKittyFormat('image/jpeg')).toBe(102)
-  })
-
-  test('maps WebP to 103', () => {
-    expect(getKittyFormat('image/webp')).toBe(103)
-  })
-
-  test('maps GIF to 104', () => {
-    expect(getKittyFormat('image/gif')).toBe(104)
-  })
-
-  test('defaults unknown to PNG', () => {
+    expect(getKittyFormat('image/jpeg')).toBe(100)
+    expect(getKittyFormat('image/webp')).toBe(100)
+    expect(getKittyFormat('image/gif')).toBe(100)
     expect(getKittyFormat(undefined)).toBe(100)
     expect(getKittyFormat('application/pdf')).toBe(100)
   })
 })
 
+/**
+ * Kitty spec only defines f=24 (RGB), f=32 (RGBA), f=100 (PNG).
+ * Any other format id will be silently dropped or errored by real terminals.
+ */
+const VALID_KITTY_FORMAT_IDS = new Set([24, 32, 100])
+
 describe('generateKittyImageSequence (via renderInlineImage)', () => {
   beforeEach(() => {
     resetTerminalImageSupportCache()
   })
 
-  test('single chunk carries m=0 to close the transmission', () => {
+  test('single chunk carries m=0 to close the transmission', async () => {
     useKitty()
-    const seq = renderInlineImage('aGVsbG8=', {
+    const seq = await render('aGVsbG8=', {
       width: 4,
       height: 3,
       mediaType: 'image/png',
@@ -125,34 +124,34 @@ describe('generateKittyImageSequence (via renderInlineImage)', () => {
     expect(seq).toEndWith('aGVsbG8=\x1b\\')
   })
 
-  test('multi-chunk: full control only on first chunk; m=1 middle; m=0 last', () => {
+  test('multi-chunk: full control only on first chunk; m=1 middle; m=0 last', async () => {
     useKitty()
     // 9000 base64 chars → 3 chunks (4096 + 4096 + 808)
-    const seq = renderInlineImage('A'.repeat(9000), {
+    const seq = await render('A'.repeat(9000), {
       width: 10,
       height: 5,
-      mediaType: 'image/jpeg',
+      mediaType: 'image/png',
     })
-    expect(seq).toContain('f=102')
+    expect(seq).toContain('f=100')
     expect(seq).toContain('c=10')
 
     const parts = seq!.split('\x1b\\').filter(Boolean)
     expect(parts).toHaveLength(3)
 
     // First chunk: full control data + m=1
     expect(parts[0]).toContain('a=T')
-    expect(parts[0]).toContain('f=102')
+    expect(parts[0]).toContain('f=100')
     expect(parts[0]).toContain('m=1')
     // Middle chunk: m only — no a=, no f=, no c=, no r=
     expect(parts[1]).toMatch(/^\x1b_Gm=1;A{4096}$/)
     // Last chunk: m=0
     expect(parts[2]).toMatch(/^\x1b_Gm=0;A{808}$/)
   })
 
-  test('subsequent chunks never repeat a=T / f= / c= (kitty spec)', () => {
+  test('subsequent chunks never repeat a=T / f= / c= (kitty spec)', async () => {
     useKitty()
     // 9000 chars → 3 chunks, so index 1 is a true middle chunk.
-    const seq = renderInlineImage('B'.repeat(9000), {
+    const seq = await render('B'.repeat(9000), {
       mediaType: 'image/png',
     })
     const middle = seq!.split('\x1b\\')[1]
@@ -161,31 +160,74 @@ describe('generateKittyImageSequence (via renderInlineImage)', () => {
     expect(middle).not.toContain('c=')
     expect(middle).toMatch(/^\x1b_Gm=1;/)
   })
+
+  test('non-PNG payload is converted to PNG before transmission', async () => {
+    useKitty()
+    // 'hello' as base64 — pretending it's JPEG. The conversion will re-encode
+    // it as a tiny PNG, so the output will differ from the raw input, but
+    // f=100 must be used.
+    const seq = await render('aGVsbG8=', {
+      mediaType: 'image/jpeg',
+    })
+    expect(seq).toContain('f=100')
+    // The payload must not be the original 'aGVsbG8=' — it was re-encoded as PNG.
+    expect(seq).not.toContain('aGVsbG8=')
+  })
+
+  test.each(['image/png', 'image/jpeg', 'image/webp', 'image/gif', undefined])(
+    'escape sequence for %s uses a spec-compliant format id (f=100|24|32)',
+    async (mediaType) => {
+      useKitty()
+      const seq = await render('aGVsbG8=', { mediaType })
+      // Extract the f= value from the first chunk's control data.
+      const fMatch = seq!.match(/f=(\d+)/)
+      expect(fMatch).not.toBeNull()
+      const formatId = Number(fMatch![1])
+      expect(VALID_KITTY_FORMAT_IDS).toContain(formatId)
+    },
+  )
+
+  test('no fabricated format ids (101-104) appear in any chunk', async () => {
+    useKitty()
+    // Use a large payload to force multiple chunks and cover all code paths.
+    const seq = await render('C'.repeat(9000), { mediaType: 'image/jpeg' })
+    const allFormatIds = [...seq!.matchAll(/f=(\d+)/g)].map((m) =>
+      Number(m[1]),
+    )
+    for (const id of allFormatIds) {
+      expect(VALID_KITTY_FORMAT_IDS).toContain(id)
+    }
+    // Specifically ensure none of the fabricated ids from the old code appear.
+    expect(allFormatIds).not.toContain(101)
+    expect(allFormatIds).not.toContain(102)
+    expect(allFormatIds).not.toContain(103)
+    expect(allFormatIds).not.toContain(104)
+  })
 })
 
 describe('generateITerm2ImageSequence (via renderInlineImage)', () => {
   beforeEach(() => {
     resetTerminalImageSupportCache()
   })
 
-  test('size param is the decoded byte length, not the base64 length', () => {
+  test('size param is the decoded byte length, not the base64 length', async () => {
     useITerm2()
-    const seq = renderInlineImage('aGVsbG8=', { filename: 'x.png' })
+    const seq = await render('aGVsbG8=', { filename: 'x.png' })
     // 'hello' → 5 decoded bytes; base64 'aGVsbG8=' → 8 chars
     expect(seq).toContain('size=5')
     expect(seq).not.toContain('size=8')
     expect(seq).toContain('inline=1')
     expect(seq).toContain('name=eC5wbmc=')
   })
 
-  test('returns null when the terminal does not support inline images', () => {
+  test('returns null when the terminal does not support inline images', async () => {
     // Prime the cache with an explicit 'none' so the assertion doesn't depend
     // on whatever terminal this test happens to run inside.
     resetTerminalImageSupportCache()
     expect(
       detectTerminalImageSupport({ TERM: 'xterm-256color' } as any),
     ).toBe('none')
-    const seq = renderInlineImage('aGVsbG8=', {})
+    const seq = await render('aGVsbG8=', {})
     expect(seq).toBeNull()
   })
 })

cli/src/utils/terminal-images.ts

@@ -6,6 +6,8 @@
  * iTerm2 protocol reference: https://iterm2.com/documentation-images.html
  */
 
+import { Jimp } from 'jimp'
+
 import { getCliEnv } from './env'
 
 import type { CliEnv } from '../types/env'
@@ -96,24 +98,13 @@ function normalizeMediaType(mediaType?: string): string {
 }
 
 /**
- * Kitty graphics format ids: 100 = PNG, 101 = PNG with alpha, 102 = JPEG,
- * 103 = WebP, 104 = GIF. Anything unknown falls back to PNG (100); the
- * terminal will fail to decode a mismatched payload, so this must match the
- * actual bytes being sent.
+ * Kitty graphics format id. The spec only defines f=24 (RGB), f=32 (RGBA),
+ * and f=100 (PNG). Non-PNG payloads are converted to PNG before transmission
+ * so we always send f=100 — this is the only guaranteed-compatible format
+ * across all kitty-protocol terminals (kitty, WezTerm, Ghostty, etc.).
  */
-export function getKittyFormat(mediaType?: string): number {
-  switch (normalizeMediaType(mediaType)) {
-    case 'image/jpeg':
-    case 'image/jpg':
-      return 102
-    case 'image/webp':
-      return 103
-    case 'image/gif':
-      return 104
-    case 'image/png':
-    default:
-      return 100
-  }
+export function getKittyFormat(_mediaType?: string): number {
+  return 100
 }
 
 /**
@@ -181,6 +172,31 @@ function generateITerm2ImageSequence(
   return `\x1b]1337;File=${paramString}:${base64Data}\x07`
 }
 
+/**
+ * Check whether the payload is already PNG (f=100 compatible).
+ */
+function isPng(mediaType?: string): boolean {
+  const mt = normalizeMediaType(mediaType)
+  return mt === 'image/png'
+}
+
+/**
+ * Convert a base64-encoded image (JPEG, WebP, GIF, etc.) to PNG via Jimp.
+ * Returns the original data unchanged if it is already PNG.
+ */
+async function convertToPngIfNeeded(
+  base64Data: string,
+  mediaType?: string,
+): Promise<string> {
+  if (isPng(mediaType)) {
+    return base64Data
+  }
+  const inputBuffer = Buffer.from(base64Data, 'base64')
+  const image = await Jimp.read(inputBuffer)
+  const pngBuffer = await image.getBuffer('image/png')
+  return pngBuffer.toString('base64')
+}
+
 /**
  * Generate Kitty graphics protocol escape sequence.
  *
@@ -192,28 +208,32 @@ function generateITerm2ImageSequence(
  *     renders the image or renders a fragment)
  *   - non-final chunk payloads must be a multiple of 4 bytes of base64
  *
+ * Non-PNG payloads (JPEG, WebP, GIF) are converted to PNG before
+ * transmission because the kitty spec only defines f=100 (PNG) as a
+ * guaranteed-compatible format across all terminals.
+ *
  * @param base64Data - Base64 encoded image data
  * @param options - Display options
  */
-function generateKittyImageSequence(
+async function generateKittyImageSequence(
   base64Data: string,
   options: {
     width?: number // cells
     height?: number // cells
     id?: number
     mediaType?: string
   } = {},
-): string {
+): Promise<string> {
   const { width, height, id, mediaType } = options
 
+  // Convert non-PNG payloads to PNG so the terminal can decode them.
+  // The kitty spec only defines f=100 (PNG), f=24 (RGB), f=32 (RGBA).
+  const pngBase64 = await convertToPngIfNeeded(base64Data, mediaType)
+
   // Build key-value pairs for the control data (first chunk only)
   const kvPairs: string[] = [
     'a=T', // action: transmit and display
-    // Format must match the payload bytes. JPEG (102) is what image-handler
-    // produces after compression; kitty/WezTerm/Ghostty decode it natively.
-    // Terminals that only implement the spec's mandatory RGB/RGBA/PNG set
-    // won't render non-PNG payloads — the metadata-card fallback covers them.
-    `f=${getKittyFormat(mediaType)}`,
+    'f=100', // always PNG after conversion
     't=d', // transmission: direct (data follows)
   ]
 
@@ -236,9 +256,9 @@ function generateKittyImageSequence(
   const CHUNK_SIZE = 4096
 
   const chunks: string[] = []
-  for (let i = 0; i < base64Data.length; i += CHUNK_SIZE) {
-    const chunk = base64Data.slice(i, i + CHUNK_SIZE)
-    const isLast = i + CHUNK_SIZE >= base64Data.length
+  for (let i = 0; i < pngBase64.length; i += CHUNK_SIZE) {
+    const chunk = pngBase64.slice(i, i + CHUNK_SIZE)
+    const isLast = i + CHUNK_SIZE >= pngBase64.length
 
     // First chunk: full control data + m. Subsequent chunks: m only, so the
     // terminal continues the same transmission instead of starting a new
@@ -257,15 +277,15 @@ function generateKittyImageSequence(
  * @param options - Display options
  * @returns The escape sequence string, or null if not supported
  */
-export function renderInlineImage(
+export async function renderInlineImage(
   base64Data: string,
   options: {
     width?: number
     height?: number
     filename?: string
     mediaType?: string
   } = {},
-): string | null {
+): Promise<string | null> {
   const protocol = detectTerminalImageSupport()
 
   switch (protocol) {