error

src/ink/log-update.ts

@@ -302,10 +302,40 @@ export class LogUpdate {
     let currentStyleId = stylePool.none
     let currentHyperlink: Hyperlink = undefined
 
+    // Track which rows had raw writes emitted to avoid duplicates
+    const emittedRawRows = new Set<number>()
+
     // First pass: render changes to existing rows (rows < prev.screen.height)
     let needsFullReset = false
     let resetTriggerY = -1
     diffEach(prev.screen, next.screen, (x, y, removed, added) => {
+      // If the cell outside the viewport range has changed, we need to reset
+      // because we can't move the cursor there to draw.
+      if (y < viewportY) {
+        needsFullReset = true
+        resetTriggerY = y
+        return true // early exit
+      }
+
+      // Emit raw write (APC/DCS) with viewport-adjusted CUP so native
+      // images appear at the correct scroll position within the viewport.
+      if (!emittedRawRows.has(y)) {
+        emittedRawRows.add(y)
+        const rawWrite = next.screen.rawWritesAtRow.get(y)
+        if (rawWrite) {
+          const vpRow = y - viewportY
+          const adjusted = rawWrite.replace(
+            /^\x1b\[(\d+);(\d+)H/,
+            (_, __, col) => `\x1b[${vpRow + 1};${col}H`,
+          )
+          screen.diff.push({ type: 'stdout', content: adjusted })
+          // Sync virtual cursor to screen-buffer row so the cell
+          // loop's moveCursorTo computes correct deltas.
+          screen.txn(prev => {
+            return [[], { dx: x - prev.x, dy: y - prev.y }]
+          })
+        }
+      }
       // Skip new rows - we'll render them directly after
       if (growing && y >= prev.screen.height) {
         return
@@ -340,14 +370,6 @@ export class LogUpdate {
         return
       }
 
-      // If the cell outside the viewport range has changed, we need to reset
-      // because we can't move the cursor there to draw.
-      if (y < viewportY) {
-        needsFullReset = true
-        resetTriggerY = y
-        return true // early exit
-      }
-
       moveCursorTo(screen, x, y)
 
       if (added) {
@@ -408,23 +430,10 @@ export class LogUpdate {
         prev.screen.height,
         next.screen.height,
         stylePool,
+        viewportY,
       )
     }
 
-    // Emit raw writes (APC/DCS) at viewport-adjusted positions so native
-    // images appear at the correct scroll position every frame, even when
-    // the diff loop skips unchanged rows. The CUP is rewritten to target
-    // a viewport-relative row instead of an absolute screen-buffer row.
-    for (const [row, rawWrite] of next.screen.rawWritesAtRow) {
-      if (row < viewportY) continue
-      const vpRow = row - viewportY
-      const adjusted = rawWrite.replace(
-        /^\x1b\[(\d+);(\d+)H/,
-        (_, __, col) => `\x1b[${vpRow + 1};${col}H`,
-      )
-      screen.diff.push({ type: 'stdout', content: adjusted })
-    }
-
     // Restore cursor. Skipped in alt-screen: the cursor is hidden, its
     // position only matters as the starting point for the NEXT frame's
     // relative moves, and in alt-screen the next frame always begins with
@@ -532,17 +541,13 @@ function renderFrame(
   stylePool: StylePool,
 ): void {
   renderFrameSlice(screen, frame, 0, frame.screen.height, stylePool)
-  // Emit raw writes (APC/DCS) after cells so native images are drawn at
-  // the correct viewport position. Full reset always starts from (0,0),
-  // so the original CUP row (screen-buffer row + 1) is already correct.
-  for (const [, rawWrite] of frame.screen.rawWritesAtRow) {
-    screen.diff.push({ type: 'stdout', content: rawWrite })
-  }
 }
 
 /**
  * Render a slice of rows from the frame's screen.
  * Each row is rendered followed by a newline. Cursor ends at (0, endY).
+ * @param viewportY Number of rows above the viewport (scrollback), for
+ *   viewport-adjusted raw write (APC/DCS) CUP positioning.
  */
 function renderFrameSlice(
   screen: VirtualScreen,
@@ -550,6 +555,7 @@ function renderFrameSlice(
   startY: number,
   endY: number,
   stylePool: StylePool,
+  viewportY = 0,
 ): VirtualScreen {
   let currentStyleId = stylePool.none
   let currentHyperlink: Hyperlink = undefined
@@ -579,6 +585,28 @@ function renderFrameSlice(
       })
     }
 
+    // Emit raw write (APC/DCS) with viewport-adjusted CUP so native
+    // images appear at the correct scroll position within the viewport.
+    const rawWrite = frame.screen.rawWritesAtRow.get(y)
+    if (rawWrite) {
+      const vpRow = y - viewportY
+      const adjusted = rawWrite.replace(
+        /^\x1b\[(\d+);(\d+)H/,
+        (_, __, col) => `\x1b[${vpRow + 1};${col}H`,
+      )
+      screen.diff.push({ type: 'stdout', content: adjusted })
+      // Sync virtual cursor to screen-buffer row so the cell
+      // loop's moveCursorTo computes correct deltas.
+      const cupMatch = rawWrite.match(/^\x1b\[(\d+);(\d+)H/)
+      if (cupMatch) {
+        const targetY = parseInt(cupMatch[1], 10) - 1
+        const targetX = parseInt(cupMatch[2], 10) - 1
+        screen.txn(prev => {
+          return [[], { dx: targetX - prev.x, dy: targetY - prev.y }]
+        })
+      }
+    }
+
     // Reset at start of each line — no cell rendered yet
     lastRenderedStyleId = -1
 

src/tools/ImageShowTool/ImageShowTool.tsx

@@ -8,6 +8,7 @@ import { buildTool, type ToolDef } from '../../Tool.js'
 import { logForDebugging } from '../../utils/debug.js'
 import {
   detectImageProtocol,
+  getImageRowsCount,
   renderImageWithTimgSync,
 } from '../../utils/terminalImage.js'
 
@@ -130,6 +131,7 @@ export const ImageShowTool = buildTool({
       message: string
       kittyOutput?: string
       timgOutput?: string
+      imageRows?: number
     },
     _progressMessages,
     _options,
@@ -138,26 +140,23 @@ export const ImageShowTool = buildTool({
       return null
     }
 
-    // Block-mode placeholder rendered in-band via RawAnsi so Ink knows the
-    // image dimensions and its virtual cursor stays in sync. When Kitty
-    // protocol is available, visible block characters are replaced with
-    // spaces so the native image shows through transparently, while the
-    // line structure (row count, per-row visual width) is preserved for
-    // Ink DOM cursor tracking.
+    // When Kitty protocol is available, reserve image-height rows of spaces
+    // in Ink's virtual DOM for layout, while the native image is rendered
+    // directly via the APC escape sequence (stored in rawWritesAtRow). This
+    // avoids the issue of block-mode overlay characters interfering with the
+    // native image display.
+    if (content.kittyOutput && content.imageRows && content.imageRows > 0) {
+      const width = process.stdout.columns ?? 80
+      const lines = Array.from({ length: content.imageRows }, () => ' '.repeat(width))
+      lines[0] = content.kittyOutput + lines[0]
+      return <RawAnsi lines={lines} width={width} />
+    }
+
+    // Block-mode fallback when Kitty protocol is not supported.
     if (content.timgOutput) {
       const cleaned = content.timgOutput.replace(/\x1b\[\?25[hl]/g, '')
-      let lines = cleaned.split('\n').filter(l => l.length > 0)
+      const lines = cleaned.split('\n').filter(l => l.length > 0)
       if (lines.length > 0) {
-        if (content.kittyOutput) {
-          // Strip ANSI SGR codes and replace non-space visible chars with
-          // spaces. The native Kitty image will show through these spaces.
-          lines = lines.map(l =>
-            l.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '').replace(/[^\s]/g, ' '),
-          )
-          const width = Math.max(...lines.map(l => l.length))
-          lines[0] = content.kittyOutput + lines[0]
-          return <RawAnsi lines={lines} width={width} />
-        }
         const ansiStrip = (s: string) => s.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
         const width = Math.max(...lines.map(l => ansiStrip(l).length))
         return <RawAnsi lines={lines} width={width} />
@@ -254,24 +253,34 @@ export const ImageShowTool = buildTool({
 
     logForDebugging(`ImageShow: loaded ${buffer.length} byte ${format} image`)
 
-    // Hybrid rendering:
-    // 1. Kitty protocol via timg for native-quality overlay (when supported)
-    // 2. Block-mode via timg for Ink DOM cursor tracking (always, as fallback)
+    // Rendering approach:
+    // 1. Kitty protocol via timg for native-quality display (when supported)
+    // 2. Block-mode via timg as fallback for terminals without Kitty support
     const protocol = detectImageProtocol()
     let kittyOutput: string | undefined
     let timgOutput: string | undefined
+    let imageRows = 0
 
     if (protocol === 'kitty') {
       const rawKitty = renderImageWithTimgSync(buffer, format, undefined, undefined, 'kitty')
       if (rawKitty) {
         kittyOutput = wrapForMultiplexer(rawKitty)
-        logForDebugging('ImageShow: generated Kitty protocol output via timg')
+        imageRows = getImageRowsCount(buffer, format)
+        logForDebugging(
+          `ImageShow: generated Kitty protocol output, image rows = ${imageRows}`,
+        )
+      }
+      // If we couldn't determine image rows, fall back to block-mode layout
+      if (imageRows === 0) {
+        kittyOutput = undefined
       }
     }
 
-    timgOutput = renderImageWithTimgSync(buffer, format, undefined, undefined, 'blocks') ?? undefined
-    if (timgOutput) {
-      logForDebugging('ImageShow: generated block-mode output via timg')
+    if (!kittyOutput) {
+      timgOutput = renderImageWithTimgSync(buffer, format, undefined, undefined, 'blocks') ?? undefined
+      if (timgOutput) {
+        logForDebugging('ImageShow: generated block-mode output via timg')
+      }
     }
 
     return {
@@ -286,6 +295,7 @@ export const ImageShowTool = buildTool({
         format,
         kittyOutput,
         timgOutput,
+        imageRows,
       },
     }
   },

src/utils/terminalImage.ts

@@ -232,6 +232,63 @@ export async function renderImageWithTimg(
   }
 }
 
+/**
+ * Determine the number of terminal rows an image occupies when rendered.
+ * Runs `timg -p q` (block-mode) and counts the output lines.
+ * Used to reserve layout space in Ink's virtual DOM when the Kitty
+ * protocol is used for native-quality rendering.
+ *
+ * @param buffer - The raw image buffer
+ * @param format - Image format (png, jpeg, gif, webp)
+ * @param columns - Optional terminal width in character columns (default: stdout.columns)
+ * @returns Number of terminal rows, or 0 on failure
+ */
+export function getImageRowsCount(
+  buffer: Buffer,
+  format: string,
+  columns?: number,
+): number {
+  try {
+    const timgPath = whichSync('timg')
+    if (!timgPath) return 0
+
+    const cols = columns ?? process.stdout.columns ?? 80
+    const termRows = process.stdout.rows ?? 40
+    const maxRows = Math.max(10, Math.floor(termRows * 0.5))
+    const tmpDir = mkdtempSync(join(tmpdir(), 'versperclaw-timg-rows-'))
+    const ext = format === 'jpeg' ? 'jpg' : format
+    const tmpFile = join(tmpDir, `image.${ext}`)
+
+    try {
+      writeFileSync(tmpFile, buffer)
+
+      const stdout = execFileSync(
+        timgPath,
+        ['-p', 'q', '-g', `${cols}x${maxRows}`, tmpFile],
+        { encoding: 'utf8', timeout: 15000, maxBuffer: 10 * 1024 * 1024 },
+      )
+
+      // Count non-empty lines; strip ANSI escape sequences first so we
+      // only count lines that actually contain block-mode content.
+      const lines = stdout
+        .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
+        .replace(/\x1b\[?25[hl]/g, '')
+        .split('\n')
+        .filter(l => l.trim().length > 0)
+
+      return lines.length
+    } finally {
+      try {
+        rmSync(tmpDir, { recursive: true, force: true })
+      } catch {
+        // ignore cleanup errors
+      }
+    }
+  } catch {
+    return 0
+  }
+}
+
 /**
  * Synchronous version of renderImageWithTimg. Blocks the event loop while
  * spawning timg, which prevents Ink from rendering between the tool call