refactor: emit native image sequences after cell content with cursor hide/show

Move raw APC/DCS emission from before cell rendering to after, wrapping
with cursor-hide/show sequences to prevent cursor flicker. Remove CUP
positioning from rawWritesAtRow entries since the cursor is already at
the correct position via CR+LF or moveCursorTo. Refactor ImageShowTool
to use writeRaw via TerminalWriteContext context instead of embedding
raw sequences in Ink's virtual DOM RawAnsi.

Co-Authored-By: Claude Big Pickle <noreply@anthropic.com>

src/ink/log-update.ts

@@ -317,25 +317,6 @@ export class LogUpdate {
         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
@@ -400,6 +381,24 @@ export class LogUpdate {
           return [patches, { dx: 1, dy: 0 }]
         })
       }
+
+      // Emit cursor-hide + bare APC/DCS + cursor-show after cell content
+      // so the native image overlays cell characters with no cursor flicker.
+      // No CUP prefix — the cursor is already at the correct row/column
+      // from moveCursorTo above.
+      if (!emittedRawRows.has(y)) {
+        emittedRawRows.add(y)
+        const rw = next.screen.rawWritesAtRow.get(y)
+        if (rw) {
+          screen.diff.push({
+            type: 'stdout',
+            content: '\x1b[?25l' + rw + '\x1b[?25h',
+          })
+          screen.txn(prev => {
+            return [[], { dx: x - prev.x, dy: y - prev.y }]
+          })
+        }
+      }
     })
     if (needsFullReset) {
       return fullResetSequence_CAUSES_FLICKER(next, 'offscreen', stylePool, {
@@ -585,28 +584,6 @@ 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
 
@@ -658,6 +635,19 @@ function renderFrameSlice(
       currentHyperlink,
       undefined,
     )
+    // Emit cursor-hide + bare APC/DCS + cursor-show after cell content.
+    // The cursor is already at the CR+LF row position — no CUP needed.
+    {
+      const rw = frame.screen.rawWritesAtRow.get(y)
+      if (rw) {
+        screen.diff.push({
+          type: 'stdout',
+          content: '\x1b[?25l' + rw + '\x1b[?25h',
+        })
+        screen.txn(prev => [[], { dx: -prev.x, dy: y - prev.y }])
+      }
+    }
+
     // CR+LF at end of row — \r resets to column 0, \n moves to next line.
     // Without \r, the terminal cursor stays at whatever column content ended
     // (since we skip trailing spaces, this can be mid-row).

src/ink/output.ts

@@ -730,17 +730,15 @@ function writeLineToScreen(
             const ci = characters[i]
             if (ci) apc += ci.value
           }
-          // Append to existing entry (multi-chunk APC) or create new one.
-          // First chunk includes CUP positioning; subsequent chunks append
-          // the next \x1b_G...\x1b\\ without redundant cursor movement.
+          // Append or create raw write entry. Store the bare APC — the
+          // cursor is already at the correct screen-buffer position when
+          // this entry is emitted (via CR+LF in renderFrameSlice or
+          // moveCursorTo in diffEach).
           const existing = screen.rawWritesAtRow.get(y)
           if (existing) {
             screen.rawWritesAtRow.set(y, existing + apc)
           } else {
-            screen.rawWritesAtRow.set(
-              y,
-              `\x1b[${y + 1};${offsetX + 1}H${apc}`,
-            )
+            screen.rawWritesAtRow.set(y, apc)
           }
         } else if (
           nextChar === ']' ||
@@ -786,10 +784,7 @@ function writeLineToScreen(
               const ci = characters[i]
               if (ci) dcs += ci.value
             }
-            screen.rawWritesAtRow.set(
-              y,
-              `\x1b[${y + 1};${offsetX + 1}H${dcs}`,
-            )
+            screen.rawWritesAtRow.set(y, dcs)
             charIdx = dcsEnd
           }
         } else if (

src/tools/ImageShowTool/ImageShowTool.tsx

@@ -1,9 +1,10 @@
 import { readFile } from 'fs/promises'
 import { homedir } from 'os'
-import React from 'react'
+import React, { useContext, useEffect } from 'react'
 import { z } from 'zod/v4'
 import { RawAnsi, Text } from '../../ink.js'
 import { wrapForMultiplexer } from '../../ink/termio/osc.js'
+import { TerminalWriteContext } from '../../ink/useTerminalNotification.js'
 import { buildTool, type ToolDef } from '../../Tool.js'
 import { logForDebugging } from '../../utils/debug.js'
 import {
@@ -44,6 +45,29 @@ function getToolUseSummary(input: Partial<Input>): string | null {
   return input?.url ? `Show: ${input.url.split('/').pop() ?? input.url}` : null
 }
 
+/**
+ * Renders a Kitty-protocol image by writing the escape sequence directly
+ * to the terminal via writeRaw, bypassing Ink's virtual DOM. Reserves
+ * vertical space with empty RawAnsi lines so Ink doesn't overwrite the
+ * image area.
+ */
+function KittyImage({ kittyOutput, imageRows }: { kittyOutput: string; imageRows: number }) {
+  const writeRaw = useContext(TerminalWriteContext)
+
+  useEffect(() => {
+    if (writeRaw && kittyOutput) {
+      // After Ink renders the reserved empty lines, cursor is at the bottom.
+      // Move cursor up to the top so the image renders at the start of the
+      // reserved space.
+      writeRaw(`\x1b[${imageRows}A${kittyOutput}`)
+    }
+  }, [kittyOutput, imageRows, writeRaw])
+
+  const width = process.stdout.columns ?? 80
+  const lines = new Array<string>(imageRows).fill('')
+  return <RawAnsi lines={lines} width={width} />
+}
+
 export const ImageShowTool = buildTool({
   name: IMAGE_TOOL_NAME,
   description:
@@ -140,16 +164,15 @@ export const ImageShowTool = buildTool({
       return null
     }
 
-    // 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.
+    // Kitty protocol: bypass Ink's virtual DOM via writeRaw and reserve
+    // space with empty RawAnsi lines.
     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} />
+      return (
+        <KittyImage
+          kittyOutput={content.kittyOutput}
+          imageRows={content.imageRows}
+        />
+      )
     }
 
     // Block-mode fallback when Kitty protocol is not supported.
@@ -264,13 +287,14 @@ export const ImageShowTool = buildTool({
     if (protocol === 'kitty') {
       const rawKitty = renderImageWithTimgSync(buffer, format, undefined, undefined, 'kitty')
       if (rawKitty) {
-        kittyOutput = wrapForMultiplexer(rawKitty)
+        // Pass the raw timg output directly through writeRaw — no need to
+        // strip cursor sequences since writeRaw bypasses Ink's screen buffer.
+        kittyOutput = wrapForMultiplexer(rawKitty.trimEnd())
         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
       }