@brimveyn/aimux 1.10.4 → 1.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.10.4",
+  "version": "1.12.1",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -60,9 +60,10 @@
     "bump": "bun run scripts/bump.ts"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.5.10",
+    "@brimveyn/aimux-config": "0.5.12",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
+    "@resvg/resvg-wasm": "^2.6.2",
     "@xterm/headless": "^6.0.0",
     "bun-pty": "^0.4.8",
     "react": "^19.2.4",

package/src/app-runtime/multi-click-clipboard-guard.ts

@@ -0,0 +1,21 @@
+// On multi-click selection mouseUp opentui's finishSelection() fires the
+// 'selection' event *after* our handleTerminalMouseUp has already written
+// the clipboard from drag.capturedLines (anchored at click time). The event
+// handler would then call computeStreamSelectedText against the *current*
+// tab.viewport.lines and overwrite our write with a value that can diverge
+// by a few rows when output landed between mouseDown and mouseUp.
+//
+// To avoid that, handleTerminalMouseUp pings the guard right after it
+// copies; handleSelection consults the guard and skips its own copy for a
+// short window.
+
+const SUPPRESS_WINDOW_MS = 100
+let lastMultiClickWriteAt = 0
+
+export function recordMultiClickClipboardWrite(): void {
+  lastMultiClickWriteAt = Date.now()
+}
+
+export function shouldSuppressSelectionCopy(): boolean {
+  return Date.now() - lastMultiClickWriteAt < SUPPRESS_WINDOW_MS
+}

package/src/app-runtime/use-mouse-handlers.ts

@@ -19,6 +19,7 @@ import {
   type MultiClickMode,
   resolveClickSelection,
 } from './click-selection-resolver'
+import { recordMultiClickClipboardWrite } from './multi-click-clipboard-guard'
 import { requestRenderUpTree } from './render-invalidation'
 import {
   type AnchoredRatioDragState,
@@ -540,6 +541,7 @@ export function useMouseHandlers({
     const text = extractStreamText(lines, anchorIdx, anchorCol, focusIdx, drag.focusCol)
     if (text.length > 0) {
       copyToSystemClipboard(text)
+      recordMultiClickClipboardWrite()
     }
 
     multiClickDragRef.current = null

package/src/app-runtime/use-renderer-bindings.ts

@@ -8,6 +8,7 @@ import type { AppAction, FocusMode, TabSession } from '../state/types'
 import { INPUT_DEBUG_LOG_PATH, logInputDebug } from '../debug/input-log'
 import { createRawInputHandler } from '../input/raw-input-handler'
 import { copyToSystemClipboard } from '../platform/clipboard'
+import { shouldSuppressSelectionCopy } from './multi-click-clipboard-guard'
 import { writePasteToTab, writeToTab } from './pty-write'
 import { type OtuiSelection, resolveSelectionClipboardText } from './selection-clipboard'
 import { applyViewportObservation, type ViewportObservation } from './selection-scroll'
@@ -118,6 +119,16 @@ export function useRendererBindings({
         return
       }
 
+      // After a multi-click drag, handleTerminalMouseUp has just copied the
+      // authoritative text built from drag.capturedLines (anchored at click
+      // time). opentui's finishSelection() then re-fires this 'selection'
+      // event, but the recomputed text can drift by a few rows when output
+      // landed between mouseDown and mouseUp. Skip the redundant write.
+      if (shouldSuppressSelectionCopy()) {
+        logInputDebug('app.selection.suppressed', { textLength: selectedText.length })
+        return
+      }
+
       renderer.copyToClipboardOSC52(selectedText)
       copyToSystemClipboard(selectedText)
     }

package/src/git/git-diff.ts

@@ -2,6 +2,8 @@ import { $ } from 'bun'
 
 import type { DiffData, DiffFileStatus, GitFileEntry } from '../state/types'
 
+import { imageFormatLabel, imageMimeFromPath, isImagePath } from './image-detect'
+
 function resolveStatus(entry: GitFileEntry): { status: DiffFileStatus; oldPath?: string } {
   if (entry.renamedFrom) return { oldPath: entry.renamedFrom, status: 'renamed' }
   if (entry.section === 'untracked' || entry.status === '?') return { status: 'new' }
@@ -35,6 +37,28 @@ async function readWorkingSize(cwd: string, path: string): Promise<number> {
   return 0
 }
 
+async function readHeadBlob(
+  cwd: string,
+  ref: string,
+  path: string
+): Promise<Uint8Array | undefined> {
+  // `git cat-file blob` writes raw bytes to stdout — binary-safe, unlike `git show`.
+  const result = await $`git -C ${cwd} cat-file blob ${ref}:${path}`.quiet().nothrow()
+  if (result.exitCode !== 0) return undefined
+  const bytes = result.stdout
+  return bytes.byteLength > 0 ? new Uint8Array(bytes) : undefined
+}
+
+async function readWorkingBytes(cwd: string, path: string): Promise<Uint8Array | undefined> {
+  try {
+    const file = Bun.file(`${cwd}/${path}`)
+    if (!(await file.exists())) return undefined
+    return await file.bytes()
+  } catch {
+    return undefined
+  }
+}
+
 async function rawUnifiedDiff(
   cwd: string,
   ref: string,
@@ -69,6 +93,29 @@ export async function fetchDiff(
   const { oldPath, status } = resolveStatus(file)
   const ref = headOffset > 0 ? `HEAD~${headOffset}` : 'HEAD'
 
+  if (isImagePath(file.path)) {
+    const headPath = oldPath ?? file.path
+    const wantsBefore = status !== 'new'
+    const wantsAfter = status !== 'deleted'
+    const [imageBytesBefore, imageBytesAfter] = await Promise.all([
+      wantsBefore ? readHeadBlob(cwd, ref, headPath) : Promise.resolve(undefined),
+      wantsAfter ? readWorkingBytes(cwd, file.path) : Promise.resolve(undefined),
+    ])
+    const data: DiffData = {
+      binarySizeAfter: imageBytesAfter?.byteLength ?? 0,
+      binarySizeBefore: imageBytesBefore?.byteLength ?? 0,
+      imageFormatLabel: imageFormatLabel(file.path),
+      imageMime: imageMimeFromPath(file.path),
+      path: file.path,
+      rawDiff: '',
+      status: 'image',
+    }
+    if (imageBytesBefore) data.imageBytesBefore = imageBytesBefore
+    if (imageBytesAfter) data.imageBytesAfter = imageBytesAfter
+    if (oldPath) data.oldPath = oldPath
+    return data
+  }
+
   if (await isBinary(cwd, ref, file.path)) {
     const [binarySizeBefore, binarySizeAfter] = await Promise.all([
       readHeadSize(cwd, ref, file.path),

package/src/git/image-detect.ts

@@ -0,0 +1,34 @@
+const MIME_BY_EXT: Record<string, string> = {
+  avif: 'image/avif',
+  bmp: 'image/bmp',
+  gif: 'image/gif',
+  ico: 'image/x-icon',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  png: 'image/png',
+  svg: 'image/svg+xml',
+  tif: 'image/tiff',
+  tiff: 'image/tiff',
+  webp: 'image/webp',
+}
+
+function extOf(path: string): string {
+  const slash = path.lastIndexOf('/')
+  const dot = path.lastIndexOf('.')
+  if (dot < 0 || dot < slash) return ''
+  return path.slice(dot + 1).toLowerCase()
+}
+
+export function isImagePath(path: string): boolean {
+  return extOf(path) in MIME_BY_EXT
+}
+
+export function imageMimeFromPath(path: string): string {
+  return MIME_BY_EXT[extOf(path)] ?? 'application/octet-stream'
+}
+
+export function imageFormatLabel(path: string): string {
+  const ext = extOf(path)
+  if (ext === 'jpg') return 'jpeg'
+  return ext || 'image'
+}

package/src/state/types.ts

@@ -202,7 +202,7 @@ export interface GitPanelState {
   error: GitPanelError | null
 }
 
-export type DiffFileStatus = 'modified' | 'new' | 'deleted' | 'binary' | 'renamed'
+export type DiffFileStatus = 'modified' | 'new' | 'deleted' | 'binary' | 'renamed' | 'image'
 
 export interface DiffData {
   path: string
@@ -212,6 +212,10 @@ export interface DiffData {
   binarySizeBefore?: number
   binarySizeAfter?: number
   errorMessage?: string
+  imageBytesBefore?: Uint8Array
+  imageBytesAfter?: Uint8Array
+  imageMime?: string
+  imageFormatLabel?: string
 }
 
 export type GitDiffView = 'split' | 'stacked'

package/src/ui/components/git/git-view.tsx

@@ -16,6 +16,7 @@ import { useTheme } from '../../theme'
 import { PierreDiff, type PierreDiffHandle } from './diff-renderer'
 import { useDiffPrefetch } from './diff-renderer/use-diff-prefetch'
 import { GitPanel } from './git-panel'
+import { ImageDiffView } from './image-diff'
 
 interface DiffStageProps {
   diff: DiffData | undefined
@@ -71,6 +72,10 @@ const DiffStage = memo(function DiffStage({
     )
   }
 
+  if (diff.status === 'image') {
+    return <ImageDiffView diff={diff} />
+  }
+
   const placeholder = placeholderText(diff)
   if (placeholder) {
     return (

package/src/ui/components/git/image-diff/dimensions.ts

@@ -0,0 +1,96 @@
+// Lightweight pure-JS dimension extraction. Handles only the headers we care
+// about (PNG, JPEG, GIF, WebP, BMP); other formats return null and the UI
+// shows just the byte size.
+
+export interface ImageDimensions {
+  height: number
+  width: number
+}
+
+function readPng(b: Uint8Array): ImageDimensions | null {
+  if (b.length < 24) return null
+  // PNG signature + IHDR chunk type at offset 12.
+  if (b[12] !== 0x49 || b[13] !== 0x48 || b[14] !== 0x44 || b[15] !== 0x52) return null
+  const view = new DataView(b.buffer, b.byteOffset)
+  return { height: view.getUint32(20, false), width: view.getUint32(16, false) }
+}
+
+function readGif(b: Uint8Array): ImageDimensions | null {
+  if (b.length < 10) return null
+  if (b[0] !== 0x47 || b[1] !== 0x49 || b[2] !== 0x46) return null
+  const view = new DataView(b.buffer, b.byteOffset)
+  return { height: view.getUint16(8, true), width: view.getUint16(6, true) }
+}
+
+function readBmp(b: Uint8Array): ImageDimensions | null {
+  if (b.length < 26) return null
+  if (b[0] !== 0x42 || b[1] !== 0x4d) return null
+  const view = new DataView(b.buffer, b.byteOffset)
+  return { height: Math.abs(view.getInt32(22, true)), width: view.getInt32(18, true) }
+}
+
+function readWebp(b: Uint8Array): ImageDimensions | null {
+  if (b.length < 30) return null
+  if (b[0] !== 0x52 || b[1] !== 0x49 || b[2] !== 0x46 || b[3] !== 0x46) return null
+  if (b[8] !== 0x57 || b[9] !== 0x45 || b[10] !== 0x42 || b[11] !== 0x50) return null
+  // VP8X chunk
+  if (b[12] === 0x56 && b[13] === 0x50 && b[14] === 0x38 && b[15] === 0x58) {
+    const view = new DataView(b.buffer, b.byteOffset)
+    const w = (view.getUint32(24, true) & 0xffffff) + 1
+    const h = ((view.getUint32(27, true) >> 8) & 0xffffff) + 1
+    return { height: h, width: w }
+  }
+  // VP8L (lossless)
+  if (b[12] === 0x56 && b[13] === 0x50 && b[14] === 0x38 && b[15] === 0x4c) {
+    const view = new DataView(b.buffer, b.byteOffset)
+    const bits = view.getUint32(21, true)
+    return { height: ((bits >> 14) & 0x3fff) + 1, width: (bits & 0x3fff) + 1 }
+  }
+  // VP8 (lossy)
+  if (b[12] === 0x56 && b[13] === 0x50 && b[14] === 0x38 && b[15] === 0x20) {
+    const view = new DataView(b.buffer, b.byteOffset)
+    return { height: view.getUint16(28, true) & 0x3fff, width: view.getUint16(26, true) & 0x3fff }
+  }
+  return null
+}
+
+function readJpeg(b: Uint8Array): ImageDimensions | null {
+  if (b.length < 4 || b[0] !== 0xff || b[1] !== 0xd8) return null
+  let i = 2
+  while (i + 9 < b.length) {
+    if (b[i] !== 0xff) {
+      i++
+      continue
+    }
+    // Skip padding 0xFF bytes
+    while (i < b.length && b[i] === 0xff) i++
+    if (i >= b.length) return null
+    const marker = b[i] ?? 0
+    i++
+    // SOF markers: 0xC0..0xCF except 0xC4, 0xC8, 0xCC
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      if (i + 7 >= b.length) return null
+      const view = new DataView(b.buffer, b.byteOffset)
+      const height = view.getUint16(i + 3, false)
+      const width = view.getUint16(i + 5, false)
+      return { height, width }
+    }
+    // Standalone markers without length
+    if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) continue
+    if (i + 1 >= b.length) return null
+    const view = new DataView(b.buffer, b.byteOffset)
+    const len = view.getUint16(i, false)
+    i += len
+  }
+  return null
+}
+
+export function readImageDimensions(bytes: Uint8Array): ImageDimensions | null {
+  return readPng(bytes) ?? readJpeg(bytes) ?? readGif(bytes) ?? readWebp(bytes) ?? readBmp(bytes)
+}
+
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+  return `${(n / (1024 * 1024)).toFixed(2)} MB`
+}

package/src/ui/components/git/image-diff/image-diff-view.tsx

@@ -0,0 +1,113 @@
+import { useRenderer } from '@opentui/react'
+import { memo } from 'react'
+
+import type { DiffData } from '../../../../state/types'
+
+import {
+  detectGraphicsProtocol,
+  isInsideTmux,
+  terminalLabel,
+} from '../../../terminal-graphics/capabilities'
+import { useTheme } from '../../../theme'
+import { formatBytes, readImageDimensions } from './dimensions'
+import { TerminalImagePane } from './terminal-image-pane'
+
+interface ImageDiffViewProps {
+  diff: DiffData
+}
+
+interface PaneProps {
+  bytes: Uint8Array | undefined
+  formatLabel: string
+  label: string
+  mime: string
+  protocol: 'kitty' | 'iterm' | 'none'
+}
+
+const Pane = memo(function Pane({ bytes, formatLabel, label, mime, protocol }: PaneProps) {
+  const t = useTheme()
+  if (!bytes) {
+    return (
+      <box flexDirection="column" flexGrow={1} padding={1}>
+        <text fg={t.textMuted}>{label}</text>
+        <text fg={t.textMuted}>(absent)</text>
+      </box>
+    )
+  }
+  const dims = readImageDimensions(bytes)
+  const meta = [
+    formatLabel,
+    formatBytes(bytes.byteLength),
+    dims ? `${dims.width}×${dims.height}` : null,
+  ]
+    .filter((s) => s !== null)
+    .join(' · ')
+  return (
+    <box flexDirection="column" flexGrow={1} padding={1}>
+      <text fg={t.text}>{label}</text>
+      {protocol === 'kitty' ? (
+        <TerminalImagePane bytes={bytes} mime={mime} />
+      ) : (
+        <box flexGrow={1} alignItems="center" justifyContent="center">
+          <text fg={t.textMuted}>(no preview)</text>
+        </box>
+      )}
+      <text fg={t.textMuted}>{meta}</text>
+    </box>
+  )
+})
+
+export const ImageDiffView = memo(function ImageDiffView({ diff }: ImageDiffViewProps) {
+  const t = useTheme()
+  const renderer = useRenderer()
+  const protocol = detectGraphicsProtocol(renderer)
+  const before = diff.imageBytesBefore
+  const after = diff.imageBytesAfter
+  const mime = diff.imageMime ?? 'application/octet-stream'
+  const formatLabel = diff.imageFormatLabel ?? 'image'
+
+  const banner = (() => {
+    if (protocol === 'kitty') return isInsideTmux() ? 'tmux: requires allow-passthrough on' : null
+    if (protocol === 'iterm')
+      return 'Image preview unavailable in iTerm2 (open externally to view).'
+    return `Image preview requires a Kitty-compatible terminal (Kitty, Ghostty, WezTerm). Detected: ${terminalLabel()}.`
+  })()
+
+  const showBoth = before && after
+  return (
+    <box flexDirection="column" flexGrow={1} overflow="hidden" backgroundColor={t.background}>
+      {diff.oldPath ? (
+        <box paddingLeft={1} paddingRight={1}>
+          <text fg={t.textMuted}>
+            renamed: {diff.oldPath} → {diff.path}
+          </text>
+        </box>
+      ) : null}
+      {banner ? (
+        <box paddingLeft={1} paddingRight={1}>
+          <text fg={protocol === 'kitty' ? t.textMuted : t.warning}>{banner}</text>
+        </box>
+      ) : null}
+      <box flexDirection="row" flexGrow={1}>
+        {showBoth || before ? (
+          <Pane
+            bytes={before}
+            formatLabel={formatLabel}
+            label="old (HEAD)"
+            mime={mime}
+            protocol={protocol}
+          />
+        ) : null}
+        {showBoth || after ? (
+          <Pane
+            bytes={after}
+            formatLabel={formatLabel}
+            label="new (working)"
+            mime={mime}
+            protocol={protocol}
+          />
+        ) : null}
+      </box>
+    </box>
+  )
+})

package/src/ui/components/git/image-diff/index.ts

@@ -0,0 +1 @@
+export { ImageDiffView } from './image-diff-view'

package/src/ui/components/git/image-diff/terminal-image-pane.tsx

@@ -0,0 +1,99 @@
+import { type BoxRenderable } from '@opentui/core'
+import { memo, useEffect, useRef, useState } from 'react'
+
+import { convertToPng, isPng } from '../../../terminal-graphics/format-fallback'
+import {
+  deleteImageEscape,
+  imageIdToRgb,
+  nextImageId,
+  uploadPngEscape,
+  writeRaw,
+} from '../../../terminal-graphics/kitty'
+import { useTheme } from '../../../theme'
+
+interface TerminalImagePaneProps {
+  bytes: Uint8Array
+  mime: string
+}
+
+interface PaneState {
+  imageId: number | null
+  lastKey: string | null
+  uploaded: boolean
+}
+
+// Move-cursor + Kitty placement escape, sent via process.nextTick so it lands
+// AFTER opentui's native cell flush for the same frame. Otherwise the cell
+// writes overwrite the image overlay.
+function buildPlacement(id: number, screenX: number, screenY: number): string {
+  const [r, g, b] = imageIdToRgb(id)
+  const move = `\x1b[${screenY + 1};${screenX + 1}H`
+  const color = `\x1b[38;2;${r};${g};${b}m`
+  const reset = `\x1b[39m`
+  // a=p (put placement), C=1 (cursor stays put), q=2 (quiet).
+  const place = `\x1b_Ga=p,i=${id},C=1,q=2;\x1b\\`
+  return `${move}${color}${place}${reset}`
+}
+
+export const TerminalImagePane = memo(function TerminalImagePane({
+  bytes,
+  mime,
+}: TerminalImagePaneProps) {
+  const t = useTheme()
+  const stateRef = useRef<PaneState>({ imageId: null, lastKey: null, uploaded: false })
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    stateRef.current = { imageId: null, lastKey: null, uploaded: false }
+    setError(null)
+    ;(async () => {
+      let pngBytes: Uint8Array | null = null
+      if (mime === 'image/png' || isPng(bytes)) {
+        pngBytes = bytes
+      } else {
+        const result = await convertToPng(bytes, mime)
+        if (cancelled) return
+        if (result.kind === 'error') {
+          setError(result.reason)
+          return
+        }
+        pngBytes = result.png
+      }
+      if (cancelled || !pngBytes) return
+      const id = nextImageId()
+      writeRaw(uploadPngEscape(pngBytes, id))
+      stateRef.current.imageId = id
+      stateRef.current.uploaded = true
+      // Force re-placement on the next render.
+      stateRef.current.lastKey = null
+    })()
+    return () => {
+      cancelled = true
+      const id = stateRef.current.imageId
+      if (id !== null) writeRaw(deleteImageEscape(id))
+      stateRef.current = { imageId: null, lastKey: null, uploaded: false }
+    }
+  }, [bytes, mime])
+
+  if (error) {
+    return (
+      <box flexGrow={1} alignItems="center" justifyContent="center" padding={1}>
+        <text fg={t.warning}>({error})</text>
+      </box>
+    )
+  }
+
+  function renderAfter(this: BoxRenderable): void {
+    const state = stateRef.current
+    if (!state.uploaded || state.imageId === null) return
+    const key = `${this.screenX},${this.screenY},${this.width},${this.height}`
+    if (state.lastKey === key) return
+    state.lastKey = key
+    const seq = buildPlacement(state.imageId, this.screenX, this.screenY)
+    // Queue write to land AFTER opentui's native cell flush in this frame.
+    process.nextTick(() => writeRaw(seq))
+  }
+
+  return <box flexGrow={1} renderAfter={renderAfter} />
+})

package/src/ui/terminal-graphics/capabilities.ts

@@ -0,0 +1,32 @@
+import type { CliRenderer } from '@opentui/core'
+
+export type GraphicsProtocol = 'kitty' | 'iterm' | 'none'
+
+interface RendererWithCapabilities {
+  capabilities?: { kitty_graphics?: boolean } | null
+}
+
+let cached: GraphicsProtocol | null = null
+
+export function detectGraphicsProtocol(renderer: CliRenderer): GraphicsProtocol {
+  if (cached !== null) return cached
+  const caps = (renderer as RendererWithCapabilities).capabilities
+  if (caps?.kitty_graphics) {
+    cached = 'kitty'
+    return cached
+  }
+  if (Bun.env.TERM_PROGRAM === 'iTerm.app') {
+    cached = 'iterm'
+    return cached
+  }
+  cached = 'none'
+  return cached
+}
+
+export function isInsideTmux(): boolean {
+  return Boolean(Bun.env.TMUX)
+}
+
+export function terminalLabel(): string {
+  return Bun.env.TERM_PROGRAM ?? Bun.env.TERM ?? 'unknown terminal'
+}

package/src/ui/terminal-graphics/format-fallback.ts

@@ -0,0 +1,143 @@
+// Convert non-PNG image bytes to PNG. SVGs go through @resvg/resvg-wasm
+// (zero-install). Everything else tries the system converter chain. Results
+// are cached per byte-source so we don't retry on every render.
+
+import { isSvg, renderSvgToPng } from './svg-render'
+
+export type ConvertResult = { kind: 'ok'; png: Uint8Array } | { kind: 'error'; reason: string }
+
+const cache = new Map<string, ConvertResult>()
+
+function cacheKey(bytes: Uint8Array): string {
+  return new Bun.CryptoHasher('sha1').update(bytes).digest('hex')
+}
+
+async function tryConverter(
+  cmd: string[],
+  bytes: Uint8Array,
+  timeoutMs: number
+): Promise<Uint8Array | null> {
+  try {
+    const proc = Bun.spawn(cmd, {
+      stderr: 'ignore',
+      stdin: 'pipe',
+      stdout: 'pipe',
+    })
+    const writer = proc.stdin
+    if (writer) {
+      writer.write(bytes)
+      await writer.end()
+    }
+    const timer = setTimeout(() => proc.kill(), timeoutMs)
+    const [out, code] = await Promise.all([new Response(proc.stdout).bytes(), proc.exited])
+    clearTimeout(timer)
+    if (code !== 0 || out.byteLength === 0) return null
+    return out
+  } catch {
+    return null
+  }
+}
+
+// For sips (macOS) we must write to a temp file because it doesn't accept stdin.
+async function trySips(bytes: Uint8Array): Promise<Uint8Array | null> {
+  const tmpIn = `${(Bun.env.TMPDIR ?? '/tmp').replace(/\/$/, '')}/aimux-img-in-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  const tmpOut = `${tmpIn}.png`
+  try {
+    await Bun.write(tmpIn, bytes)
+    const proc = Bun.spawn(['sips', '-s', 'format', 'png', tmpIn, '--out', tmpOut], {
+      stderr: 'ignore',
+      stdout: 'ignore',
+    })
+    const timer = setTimeout(() => proc.kill(), 1500)
+    const code = await proc.exited
+    clearTimeout(timer)
+    if (code !== 0) return null
+    const file = Bun.file(tmpOut)
+    if (!(await file.exists())) return null
+    return await file.bytes()
+  } catch {
+    return null
+  } finally {
+    await Promise.all([
+      Bun.file(tmpIn)
+        .delete()
+        .catch(() => {}),
+      Bun.file(tmpOut)
+        .delete()
+        .catch(() => {}),
+    ])
+  }
+}
+
+function mimeLabel(mime: string): string {
+  const slash = mime.indexOf('/')
+  if (slash < 0) return mime
+  return mime.slice(slash + 1).toUpperCase()
+}
+
+export async function convertToPng(bytes: Uint8Array, mime: string): Promise<ConvertResult> {
+  const key = cacheKey(bytes)
+  const hit = cache.get(key)
+  if (hit !== undefined) return hit
+
+  let result: ConvertResult
+  if (isSvg(bytes)) {
+    const png = await renderSvgToPng(bytes)
+    result = png ? { kind: 'ok', png } : { kind: 'error', reason: 'failed to render SVG' }
+  } else {
+    const attempts: Array<() => Promise<Uint8Array | null>> = [
+      () => tryConverter(['magick', '-', 'png:-'], bytes, 1500),
+      () => tryConverter(['convert', '-', 'png:-'], bytes, 1500),
+      () => trySips(bytes),
+      () =>
+        tryConverter(
+          [
+            'ffmpeg',
+            '-loglevel',
+            'error',
+            '-i',
+            'pipe:0',
+            '-f',
+            'image2',
+            '-vcodec',
+            'png',
+            'pipe:1',
+          ],
+          bytes,
+          2500
+        ),
+    ]
+
+    let converted: Uint8Array | null = null
+    for (const attempt of attempts) {
+      const out = await attempt()
+      if (out && out.byteLength > 0) {
+        converted = out
+        break
+      }
+    }
+    result = converted
+      ? { kind: 'ok', png: converted }
+      : {
+          kind: 'error',
+          reason: `no converter could decode this ${mimeLabel(mime)} (install ImageMagick or cwebp)`,
+        }
+  }
+
+  cache.set(key, result)
+  return result
+}
+
+export function isPng(bytes: Uint8Array): boolean {
+  return (
+    bytes.length >= 8 &&
+    bytes[0] === 0x89 &&
+    bytes[1] === 0x50 &&
+    bytes[2] === 0x4e &&
+    bytes[3] === 0x47 &&
+    bytes[4] === 0x0d &&
+    bytes[5] === 0x0a &&
+    bytes[6] === 0x1a &&
+    bytes[7] === 0x0a
+  )
+}

package/src/ui/terminal-graphics/kitty.ts

@@ -0,0 +1,79 @@
+// Kitty graphics protocol — pixel placement (a=p) with quiet, cursor-preserving
+// placements. The image is uploaded once (a=t) with `f=100` (PNG), then placed
+// at the cursor's current position.
+// Spec: https://sw.kovidgoyal.net/kitty/graphics-protocol/
+
+import { isInsideTmux } from './capabilities'
+
+const ESC = '\x1b'
+const ST = `${ESC}\\`
+const MAX_BASE64_CHUNK = 4096
+
+// Image IDs use the 24-bit RGB foreground color of placeholder cells. We start
+// from 0x100000 to avoid collisions with embedded PTYs that may also emit
+// graphics commands (Kitty namespaces images per-window but the spec is loose).
+let nextId = 0x100000
+
+export function nextImageId(): number {
+  const id = nextId++
+  // Wrap at 24-bit; we don't expect to leak more than ~16M IDs per session but
+  // be safe in case of a long-running daemon.
+  if (nextId > 0xffffff) nextId = 0x100000
+  return id
+}
+
+function idToRgb(id: number): [number, number, number] {
+  return [(id >> 16) & 0xff, (id >> 8) & 0xff, id & 0xff]
+}
+
+function wrapForTmux(seq: string): string {
+  if (!isInsideTmux()) return seq
+  // tmux passthrough: wrap in DCS tmux; ... ST, and double every ESC inside.
+  return `${ESC}Ptmux;${seq.split(ESC).join(`${ESC}${ESC}`)}${ESC}\\`
+}
+
+function encodeBase64(bytes: Uint8Array): string {
+  // Bun supports btoa for binary strings, but Buffer is faster for large blobs.
+  return Buffer.from(bytes).toString('base64')
+}
+
+function chunkString(s: string, size: number): string[] {
+  if (s.length <= size) return [s]
+  const out: string[] = []
+  for (let i = 0; i < s.length; i += size) out.push(s.slice(i, i + size))
+  return out
+}
+
+// Build the upload escape(s) for a PNG (f=100) image. Chunked per Kitty spec
+// recommendation (≤ 4096 base64 bytes per escape).
+export function uploadPngEscape(pngBytes: Uint8Array, id: number): string {
+  const b64 = encodeBase64(pngBytes)
+  const chunks = chunkString(b64, MAX_BASE64_CHUNK)
+  const parts: string[] = []
+  for (let i = 0; i < chunks.length; i++) {
+    const isLast = i === chunks.length - 1
+    const m = isLast ? 0 : 1
+    let header: string
+    if (i === 0) {
+      // a=t (transmit), t=d (direct), f=100 (PNG), q=2 (quiet).
+      header = `q=2,a=t,t=d,f=100,i=${id},m=${m}`
+    } else {
+      header = `m=${m},q=2`
+    }
+    parts.push(`${ESC}_G${header};${chunks[i]}${ST}`)
+  }
+  return wrapForTmux(parts.join(''))
+}
+
+export function deleteImageEscape(id: number): string {
+  return wrapForTmux(`${ESC}_Ga=d,d=I,i=${id},q=2;${ST}`)
+}
+
+export function imageIdToRgb(id: number): [number, number, number] {
+  return idToRgb(id)
+}
+
+export function writeRaw(seq: string): void {
+  // Synchronous write so we don't interleave with opentui frames.
+  process.stdout.write(seq)
+}

package/src/ui/terminal-graphics/svg-render.ts

@@ -0,0 +1,48 @@
+// SVG → PNG rendering via @resvg/resvg-wasm. WASM is loaded once per process
+// from the package's bundled `index_bg.wasm`; subsequent renders reuse it.
+
+import { initWasm, Resvg } from '@resvg/resvg-wasm'
+
+let initPromise: Promise<void> | null = null
+
+async function ensureInit(): Promise<void> {
+  if (!initPromise) {
+    initPromise = (async () => {
+      const wasmUrl = import.meta.resolve('@resvg/resvg-wasm/index_bg.wasm')
+      const bytes = await Bun.file(new URL(wasmUrl)).bytes()
+      await initWasm(bytes)
+    })()
+  }
+  await initPromise
+}
+
+export async function renderSvgToPng(svgBytes: Uint8Array): Promise<Uint8Array | null> {
+  try {
+    await ensureInit()
+    // 1024px wide is plenty for any TUI cell grid; Kitty scales to fit.
+    const resvg = new Resvg(svgBytes, { fitTo: { mode: 'width', value: 1024 } })
+    const rendered = resvg.render()
+    const png = rendered.asPng()
+    rendered.free()
+    resvg.free()
+    return png
+  } catch {
+    return null
+  }
+}
+
+export function isSvg(bytes: Uint8Array): boolean {
+  // Accept files that open with an XML prolog or whitespace before <svg.
+  const max = Math.min(bytes.length, 256)
+  for (let i = 0; i + 3 < max; i++) {
+    if (
+      bytes[i] === 0x3c && // <
+      bytes[i + 1] === 0x73 && // s
+      bytes[i + 2] === 0x76 && // v
+      bytes[i + 3] === 0x67 // g
+    ) {
+      return true
+    }
+  }
+  return false
+}