feat: terse transformations of image paths in text buffer (#4924)

Co-authored-by: Jacob Richman <jacob314@gmail.com>
Co-authored-by: owenofbrien <86964623+owenofbrien@users.noreply.github.com>

packages/cli/src/ui/components/shared/text-buffer.test.ts

@@ -24,6 +24,10 @@ import {
   findWordEndInLine,
   findNextWordStartInLine,
   isWordCharStrict,
+  calculateTransformationsForLine,
+  calculateTransformedLine,
+  getTransformUnderCursor,
+  getTransformedImagePath,
 } from './text-buffer.js';
 import { cpLen } from '../../utils/textUtils.js';
 
@@ -31,6 +35,8 @@ const defaultVisualLayout: VisualLayout = {
   visualLines: [''],
   logicalToVisualMap: [[[0, 0]]],
   visualToLogicalMap: [[0, 0]],
+  transformedToLogicalMaps: [[]],
+  visualToTransformedMap: [],
 };
 
 const initialState: TextBufferState = {
@@ -44,6 +50,7 @@ const initialState: TextBufferState = {
   selectionAnchor: null,
   viewportWidth: 80,
   viewportHeight: 24,
+  transformationsByLine: [[]],
   visualLayout: defaultVisualLayout,
 };
 
@@ -2381,3 +2388,182 @@ describe('Unicode helper functions', () => {
     });
   });
 });
+
+describe('Transformation Utilities', () => {
+  describe('getTransformedImagePath', () => {
+    it('should transform a simple image path', () => {
+      expect(getTransformedImagePath('@test.png')).toBe('[Image test.png]');
+    });
+
+    it('should handle paths with directories', () => {
+      expect(getTransformedImagePath('@path/to/image.jpg')).toBe(
+        '[Image image.jpg]',
+      );
+    });
+
+    it('should truncate long filenames', () => {
+      expect(getTransformedImagePath('@verylongfilename1234567890.png')).toBe(
+        '[Image ...1234567890.png]',
+      );
+    });
+
+    it('should handle different image extensions', () => {
+      expect(getTransformedImagePath('@test.jpg')).toBe('[Image test.jpg]');
+      expect(getTransformedImagePath('@test.jpeg')).toBe('[Image test.jpeg]');
+      expect(getTransformedImagePath('@test.gif')).toBe('[Image test.gif]');
+      expect(getTransformedImagePath('@test.webp')).toBe('[Image test.webp]');
+      expect(getTransformedImagePath('@test.svg')).toBe('[Image test.svg]');
+      expect(getTransformedImagePath('@test.bmp')).toBe('[Image test.bmp]');
+    });
+
+    it('should handle POSIX-style forward-slash paths on any platform', () => {
+      const input = '@C:/Users/foo/screenshots/image2x.png';
+      expect(getTransformedImagePath(input)).toBe('[Image image2x.png]');
+    });
+
+    it('should handle Windows-style backslash paths on any platform', () => {
+      const input = '@C:\\Users\\foo\\screenshots\\image2x.png';
+      expect(getTransformedImagePath(input)).toBe('[Image image2x.png]');
+    });
+
+    it('should handle escaped spaces in paths', () => {
+      const input = '@path/to/my\\ file.png';
+      expect(getTransformedImagePath(input)).toBe('[Image my file.png]');
+    });
+  });
+
+  describe('getTransformationsForLine', () => {
+    it('should find transformations in a line', () => {
+      const line = 'Check out @test.png and @another.jpg';
+      const result = calculateTransformationsForLine(line);
+
+      expect(result).toHaveLength(2);
+      expect(result[0]).toMatchObject({
+        logicalText: '@test.png',
+        collapsedText: '[Image test.png]',
+      });
+      expect(result[1]).toMatchObject({
+        logicalText: '@another.jpg',
+        collapsedText: '[Image another.jpg]',
+      });
+    });
+
+    it('should handle no transformations', () => {
+      const line = 'Just some regular text';
+      const result = calculateTransformationsForLine(line);
+      expect(result).toEqual([]);
+    });
+
+    it('should handle empty line', () => {
+      const result = calculateTransformationsForLine('');
+      expect(result).toEqual([]);
+    });
+
+    it('should keep adjacent image paths as separate transformations', () => {
+      const line = '@a.png@b.png@c.png';
+      const result = calculateTransformationsForLine(line);
+      expect(result).toHaveLength(3);
+      expect(result[0].logicalText).toBe('@a.png');
+      expect(result[1].logicalText).toBe('@b.png');
+      expect(result[2].logicalText).toBe('@c.png');
+    });
+
+    it('should handle multiple transformations in a row', () => {
+      const line = '@a.png @b.png @c.png';
+      const result = calculateTransformationsForLine(line);
+      expect(result).toHaveLength(3);
+    });
+  });
+
+  describe('getTransformUnderCursor', () => {
+    const transformations = [
+      {
+        logStart: 5,
+        logEnd: 14,
+        logicalText: '@test.png',
+        collapsedText: '[Image @test.png]',
+      },
+      {
+        logStart: 20,
+        logEnd: 31,
+        logicalText: '@another.jpg',
+        collapsedText: '[Image @another.jpg]',
+      },
+    ];
+
+    it('should find transformation when cursor is inside it', () => {
+      const result = getTransformUnderCursor(0, 7, [transformations]);
+      expect(result).toEqual(transformations[0]);
+    });
+
+    it('should find transformation when cursor is at start', () => {
+      const result = getTransformUnderCursor(0, 5, [transformations]);
+      expect(result).toEqual(transformations[0]);
+    });
+
+    it('should find transformation when cursor is at end', () => {
+      const result = getTransformUnderCursor(0, 14, [transformations]);
+      expect(result).toEqual(transformations[0]);
+    });
+
+    it('should return null when cursor is not on a transformation', () => {
+      const result = getTransformUnderCursor(0, 2, [transformations]);
+      expect(result).toBeNull();
+    });
+
+    it('should handle empty transformations array', () => {
+      const result = getTransformUnderCursor(0, 5, []);
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('calculateTransformedLine', () => {
+    it('should transform a line with one transformation', () => {
+      const line = 'Check out @test.png';
+      const transformations = calculateTransformationsForLine(line);
+      const result = calculateTransformedLine(line, 0, [0, 0], transformations);
+
+      expect(result.transformedLine).toBe('Check out [Image test.png]');
+      expect(result.transformedToLogMap).toHaveLength(27); // Length includes all characters in the transformed line
+
+      // Test that we have proper mappings
+      expect(result.transformedToLogMap[0]).toBe(0); // 'C'
+      expect(result.transformedToLogMap[9]).toBe(9); // ' ' before transformation
+    });
+
+    it('should handle cursor inside transformation', () => {
+      const line = 'Check out @test.png';
+      const transformations = calculateTransformationsForLine(line);
+      // Cursor at '@' (position 10 in the line)
+      const result = calculateTransformedLine(
+        line,
+        0,
+        [0, 10],
+        transformations,
+      );
+
+      // Should show full path when cursor is on it
+      expect(result.transformedLine).toBe('Check out @test.png');
+      // When expanded, each character maps to itself
+      expect(result.transformedToLogMap[10]).toBe(10); // '@'
+    });
+
+    it('should handle line with no transformations', () => {
+      const line = 'Just some text';
+      const result = calculateTransformedLine(line, 0, [0, 0], []);
+
+      expect(result.transformedLine).toBe(line);
+      // Each visual position should map directly to logical position + trailing
+      expect(result.transformedToLogMap).toHaveLength(15); // 14 chars + 1 trailing
+      expect(result.transformedToLogMap[0]).toBe(0);
+      expect(result.transformedToLogMap[13]).toBe(13);
+      expect(result.transformedToLogMap[14]).toBe(14); // Trailing position
+    });
+
+    it('should handle empty line', () => {
+      const result = calculateTransformedLine('', 0, [0, 0], []);
+      expect(result.transformedLine).toBe('');
+      expect(result.transformedToLogMap).toEqual([0]); // Just the trailing position
+    });
+  });
+});

packages/cli/src/ui/components/shared/text-buffer.ts

@@ -8,8 +8,9 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import pathMod from 'node:path';
+import * as path from 'node:path';
 import { useState, useCallback, useEffect, useMemo, useReducer } from 'react';
-import { coreEvents, CoreEvent } from '@google/gemini-cli-core';
+import { coreEvents, CoreEvent, unescapePath } from '@google/gemini-cli-core';
 import {
   toCodePoints,
   cpLen,
@@ -669,13 +670,182 @@ export function logicalPosToOffset(
 
   return offset;
 }
+/**
+ * Transformations allow for the CLI to render terse representations of things like file paths
+ * (e.g., "@some/path/to/an/image.png" to "[Image image.png]")
+ * When the cursor enters a transformed representation, it expands to reveal the logical representation.
+ * (e.g., "[Image image.png]" to "@some/path/to/an/image.png")
+ */
+export interface Transformation {
+  logStart: number;
+  logEnd: number;
+  logicalText: string;
+  collapsedText: string;
+}
+export const imagePathRegex =
+  /@((?:\\.|[^\s\r\n\\])+?\.(?:png|jpg|jpeg|gif|webp|svg|bmp))\b/gi;
 
+export function getTransformedImagePath(filePath: string): string {
+  const raw = filePath;
+
+  // Ignore leading @ when stripping directories, but keep it for simple '@file.png'
+  const withoutAt = raw.startsWith('@') ? raw.slice(1) : raw;
+
+  // Unescape the path to handle escaped spaces and other characters
+  const unescaped = unescapePath(withoutAt);
+
+  // Find last directory separator, supporting both POSIX and Windows styles
+  const lastSepIndex = Math.max(
+    unescaped.lastIndexOf('/'),
+    unescaped.lastIndexOf('\\'),
+  );
+
+  // If we saw a separator, take the segment after it; otherwise fall back to the unescaped string
+  const fileName =
+    lastSepIndex >= 0 ? unescaped.slice(lastSepIndex + 1) : unescaped;
+
+  const extension = path.extname(fileName);
+  const baseName = path.basename(fileName, extension);
+  const maxBaseLength = 10;
+
+  const truncatedBase =
+    baseName.length > maxBaseLength
+      ? `...${baseName.slice(-maxBaseLength)}`
+      : baseName;
+
+  return `[Image ${truncatedBase}${extension}]`;
+}
+
+export function calculateTransformationsForLine(
+  line: string,
+): Transformation[] {
+  const transformations: Transformation[] = [];
+  let match: RegExpExecArray | null;
+
+  // Reset regex state to ensure clean matching from start of line
+  imagePathRegex.lastIndex = 0;
+
+  while ((match = imagePathRegex.exec(line)) !== null) {
+    const logicalText = match[0];
+    const logStart = cpLen(line.substring(0, match.index));
+    const logEnd = logStart + cpLen(logicalText);
+
+    transformations.push({
+      logStart,
+      logEnd,
+      logicalText,
+      collapsedText: getTransformedImagePath(logicalText),
+    });
+  }
+
+  return transformations;
+}
+
+export function calculateTransformations(lines: string[]): Transformation[][] {
+  return lines.map((ln) => calculateTransformationsForLine(ln));
+}
+
+export function getTransformUnderCursor(
+  row: number,
+  col: number,
+  spansByLine: Transformation[][],
+): Transformation | null {
+  const spans = spansByLine[row];
+  if (!spans || spans.length === 0) return null;
+  for (const span of spans) {
+    if (col >= span.logStart && col <= span.logEnd) {
+      return span;
+    }
+    if (col < span.logStart) break;
+  }
+  return null;
+}
+
+export function calculateTransformedLine(
+  logLine: string,
+  logIndex: number,
+  logicalCursor: [number, number],
+  transformations: Transformation[],
+): { transformedLine: string; transformedToLogMap: number[] } {
+  let transformedLine = '';
+  const transformedToLogMap: number[] = [];
+  let lastLogPos = 0;
+
+  const cursorIsOnThisLine = logIndex === logicalCursor[0];
+  const cursorCol = logicalCursor[1];
+
+  for (const transform of transformations) {
+    const textBeforeTransformation = cpSlice(
+      logLine,
+      lastLogPos,
+      transform.logStart,
+    );
+    transformedLine += textBeforeTransformation;
+    for (let i = 0; i < cpLen(textBeforeTransformation); i++) {
+      transformedToLogMap.push(lastLogPos + i);
+    }
+
+    const isExpanded =
+      cursorIsOnThisLine &&
+      cursorCol >= transform.logStart &&
+      cursorCol <= transform.logEnd;
+    const transformedText = isExpanded
+      ? transform.logicalText
+      : transform.collapsedText;
+    transformedLine += transformedText;
+
+    // Map transformed characters back to logical characters
+    const transformedLen = cpLen(transformedText);
+    if (isExpanded) {
+      for (let i = 0; i < transformedLen; i++) {
+        transformedToLogMap.push(transform.logStart + i);
+      }
+    } else {
+      // Collapsed: distribute transformed positions monotonically across the raw span.
+      // This preserves ordering across wrapped slices so logicalToVisualMap has
+      // increasing startColInLogical and visual cursor mapping remains consistent.
+      const logicalLength = Math.max(0, transform.logEnd - transform.logStart);
+      for (let i = 0; i < transformedLen; i++) {
+        // Map the i-th transformed code point into [logStart, logEnd)
+        const transformationToLogicalOffset =
+          logicalLength === 0
+            ? 0
+            : Math.floor((i * logicalLength) / transformedLen);
+        const transformationToLogicalIndex =
+          transform.logStart +
+          Math.min(
+            transformationToLogicalOffset,
+            Math.max(logicalLength - 1, 0),
+          );
+        transformedToLogMap.push(transformationToLogicalIndex);
+      }
+    }
+    lastLogPos = transform.logEnd;
+  }
+
+  // Append text after last transform
+  const remainingUntransformedText = cpSlice(logLine, lastLogPos);
+  transformedLine += remainingUntransformedText;
+  for (let i = 0; i < cpLen(remainingUntransformedText); i++) {
+    transformedToLogMap.push(lastLogPos + i);
+  }
+
+  // For a cursor at the very end of the transformed line
+  transformedToLogMap.push(cpLen(logLine));
+
+  return { transformedLine, transformedToLogMap };
+}
 export interface VisualLayout {
   visualLines: string[];
   // For each logical line, an array of [visualLineIndex, startColInLogical]
   logicalToVisualMap: Array<Array<[number, number]>>;
   // For each visual line, its [logicalLineIndex, startColInLogical]
   visualToLogicalMap: Array<[number, number]>;
+  // Image paths are transformed (e.g., "@some/path/to/an/image.png" to "[Image image.png]")
+  // For each logical line, an array that maps each transformedCol to a logicalCol
+  transformedToLogicalMaps: number[][];
+  // For each visual line, its [startColInTransformed]
+  visualToTransformedMap: number[];
 }
 
 // Calculates the visual wrapping of lines and the mapping between logical and visual coordinates.
@@ -683,22 +853,34 @@ export interface VisualLayout {
 function calculateLayout(
   logicalLines: string[],
   viewportWidth: number,
+  logicalCursor: [number, number],
 ): VisualLayout {
   const visualLines: string[] = [];
   const logicalToVisualMap: Array<Array<[number, number]>> = [];
   const visualToLogicalMap: Array<[number, number]> = [];
+  const transformedToLogicalMaps: number[][] = [];
+  const visualToTransformedMap: number[] = [];
 
   logicalLines.forEach((logLine, logIndex) => {
     logicalToVisualMap[logIndex] = [];
-    if (logLine.length === 0) {
+    const transformations = calculateTransformationsForLine(logLine);
+    const { transformedLine, transformedToLogMap } = calculateTransformedLine(
+      logLine,
+      logIndex,
+      logicalCursor,
+      transformations,
+    );
+    transformedToLogicalMaps[logIndex] = transformedToLogMap;
+    if (transformedLine.length === 0) {
       // Handle empty logical line
       logicalToVisualMap[logIndex].push([visualLines.length, 0]);
       visualToLogicalMap.push([logIndex, 0]);
+      visualToTransformedMap.push(0);
       visualLines.push('');
     } else {
       // Non-empty logical line
       let currentPosInLogLine = 0; // Tracks position within the current logical line (code point index)
-      const codePointsInLogLine = toCodePoints(logLine);
+      const codePointsInLogLine = toCodePoints(transformedLine);
 
       while (currentPosInLogLine < codePointsInLogLine.length) {
         let currentChunk = '';
@@ -787,11 +969,13 @@ function calculateLayout(
           numCodePointsInChunk = 1;
         }
 
+        const logicalStartCol = transformedToLogMap[currentPosInLogLine] ?? 0;
         logicalToVisualMap[logIndex].push([
           visualLines.length,
-          currentPosInLogLine,
+          logicalStartCol,
         ]);
-        visualToLogicalMap.push([logIndex, currentPosInLogLine]);
+        visualToLogicalMap.push([logIndex, logicalStartCol]);
+        visualToTransformedMap.push(currentPosInLogLine);
         visualLines.push(currentChunk);
 
         const logicalStartOfThisChunk = currentPosInLogLine;
@@ -822,6 +1006,7 @@ function calculateLayout(
       if (!logicalToVisualMap[0]) logicalToVisualMap[0] = [];
       logicalToVisualMap[0].push([0, 0]);
       visualToLogicalMap.push([0, 0]);
+      visualToTransformedMap.push(0);
     }
   }
 
@@ -829,6 +1014,8 @@ function calculateLayout(
     visualLines,
     logicalToVisualMap,
     visualToLogicalMap,
+    transformedToLogicalMaps,
+    visualToTransformedMap,
   };
 }
 
@@ -838,7 +1025,7 @@ function calculateVisualCursorFromLayout(
   layout: VisualLayout,
   logicalCursor: [number, number],
 ): [number, number] {
-  const { logicalToVisualMap, visualLines } = layout;
+  const { logicalToVisualMap, visualLines, transformedToLogicalMaps } = layout;
   const [logicalRow, logicalCol] = logicalCursor;
 
   const segmentsForLogicalLine = logicalToVisualMap[logicalRow];
@@ -873,14 +1060,35 @@ function calculateVisualCursorFromLayout(
 
   const [visualRow, startColInLogical] =
     segmentsForLogicalLine[targetSegmentIndex];
-  const visualCol = logicalCol - startColInLogical;
 
-  // The visual column should not exceed the length of the visual line.
+  // Find the coordinates in transformed space in order to conver to visual
+  const transformedToLogicalMap = transformedToLogicalMaps[logicalRow] ?? [];
+  let transformedCol = 0;
+  for (let i = 0; i < transformedToLogicalMap.length; i++) {
+    if (transformedToLogicalMap[i] > logicalCol) {
+      transformedCol = Math.max(0, i - 1);
+      break;
+    }
+    if (i === transformedToLogicalMap.length - 1) {
+      transformedCol = transformedToLogicalMap.length - 1;
+    }
+  }
+  let startColInTransformed = 0;
+  while (
+    startColInTransformed < transformedToLogicalMap.length &&
+    transformedToLogicalMap[startColInTransformed] < startColInLogical
+  ) {
+    startColInTransformed++;
+  }
+  const clampedTransformedCol = Math.min(
+    transformedCol,
+    Math.max(0, transformedToLogicalMap.length - 1),
+  );
+  const visualCol = clampedTransformedCol - startColInTransformed;
   const clampedVisualCol = Math.min(
-    visualCol,
+    Math.max(visualCol, 0),
     cpLen(visualLines[visualRow] ?? ''),
   );
-
   return [visualRow, clampedVisualCol];
 }
 
@@ -890,6 +1098,7 @@ export interface TextBufferState {
   lines: string[];
   cursorRow: number;
   cursorCol: number;
+  transformationsByLine: Transformation[][];
   preferredCol: number | null; // This is the logical character offset in the visual line
   undoStack: UndoHistoryEntry[];
   redoStack: UndoHistoryEntry[];
@@ -1210,15 +1419,27 @@ function textBufferReducerLogic(
         }
 
         if (visualToLogicalMap[newVisualRow]) {
-          const [logRow, logStartCol] = visualToLogicalMap[newVisualRow];
+          const [logRow, logicalStartCol] = visualToLogicalMap[newVisualRow];
+          const transformedToLogicalMap =
+            visualLayout.transformedToLogicalMaps?.[logRow] ?? [];
+          let transformedStartCol = 0;
+          while (
+            transformedStartCol < transformedToLogicalMap.length &&
+            transformedToLogicalMap[transformedStartCol] < logicalStartCol
+          ) {
+            transformedStartCol++;
+          }
+          const clampedTransformedCol = Math.min(
+            transformedStartCol + newVisualCol,
+            Math.max(0, transformedToLogicalMap.length - 1),
+          );
+          const newLogicalCol =
+            transformedToLogicalMap[clampedTransformedCol] ??
+            cpLen(lines[logRow] ?? '');
           return {
             ...state,
             cursorRow: logRow,
-            cursorCol: clamp(
-              logStartCol + newVisualCol,
-              0,
-              cpLen(lines[logRow] ?? ''),
-            ),
+            cursorCol: newLogicalCol,
             preferredCol: newPreferredCol,
           };
         }
@@ -1543,13 +1764,43 @@ export function textBufferReducer(
 ): TextBufferState {
   const newState = textBufferReducerLogic(state, action, options);
 
+  const newTransformedLines =
+    newState.lines !== state.lines
+      ? calculateTransformations(newState.lines)
+      : state.transformationsByLine;
+
+  const oldTransform = getTransformUnderCursor(
+    state.cursorRow,
+    state.cursorCol,
+    state.transformationsByLine,
+  );
+  const newTransform = getTransformUnderCursor(
+    newState.cursorRow,
+    newState.cursorCol,
+    newTransformedLines,
+  );
+  const oldInside = oldTransform !== null;
+  const newInside = newTransform !== null;
+  const movedBetweenTransforms =
+    oldTransform !== newTransform &&
+    (oldTransform !== null || newTransform !== null);
+
   if (
     newState.lines !== state.lines ||
-    newState.viewportWidth !== state.viewportWidth
+    newState.viewportWidth !== state.viewportWidth ||
+    oldInside !== newInside ||
+    movedBetweenTransforms
   ) {
+    const shouldResetPreferred =
+      oldInside !== newInside || movedBetweenTransforms;
     return {
       ...newState,
-      visualLayout: calculateLayout(newState.lines, newState.viewportWidth),
+      preferredCol: shouldResetPreferred ? null : newState.preferredCol,
+      visualLayout: calculateLayout(newState.lines, newState.viewportWidth, [
+        newState.cursorRow,
+        newState.cursorCol,
+      ]),
+      transformationsByLine: newTransformedLines,
     };
   }
 
@@ -1576,14 +1827,19 @@ export function useTextBuffer({
       lines.length === 0 ? [''] : lines,
       initialCursorOffset,
     );
+    const transformationsByLine = calculateTransformations(
+      lines.length === 0 ? [''] : lines,
+    );
     const visualLayout = calculateLayout(
       lines.length === 0 ? [''] : lines,
       viewport.width,
+      [initialCursorRow, initialCursorCol],
     );
     return {
       lines: lines.length === 0 ? [''] : lines,
       cursorRow: initialCursorRow,
       cursorCol: initialCursorCol,
+      transformationsByLine,
       preferredCol: null,
       undoStack: [],
       redoStack: [],
@@ -1607,6 +1863,7 @@ export function useTextBuffer({
     preferredCol,
     selectionAnchor,
     visualLayout,
+    transformationsByLine,
   } = state;
 
   const text = useMemo(() => lines.join('\n'), [lines]);
@@ -1616,7 +1873,12 @@ export function useTextBuffer({
     [visualLayout, cursorRow, cursorCol],
   );
 
-  const { visualLines, visualToLogicalMap } = visualLayout;
+  const {
+    visualLines,
+    visualToLogicalMap,
+    transformedToLogicalMaps,
+    visualToTransformedMap,
+  } = visualLayout;
 
   const [visualScrollRow, setVisualScrollRow] = useState<number>(0);
 
@@ -2035,7 +2297,12 @@ export function useTextBuffer({
 
   const moveToVisualPosition = useCallback(
     (visRow: number, visCol: number): void => {
-      const { visualLines, visualToLogicalMap } = visualLayout;
+      const {
+        visualLines,
+        visualToLogicalMap,
+        transformedToLogicalMaps,
+        visualToTransformedMap,
+      } = visualLayout;
       // Clamp visRow to valid range
       const clampedVisRow = Math.max(
         0,
@@ -2044,8 +2311,15 @@ export function useTextBuffer({
       const visualLine = visualLines[clampedVisRow] || '';
 
       if (visualToLogicalMap[clampedVisRow]) {
-        const [logRow, logStartCol] = visualToLogicalMap[clampedVisRow];
+        const [logRow] = visualToLogicalMap[clampedVisRow];
+        const transformedToLogicalMap =
+          transformedToLogicalMaps?.[logRow] ?? [];
 
+        // Where does this visual line begin within the transformed line?
+        const startColInTransformed =
+          visualToTransformedMap?.[clampedVisRow] ?? 0;
+
+        // Handle wide characters: convert visual X position to character offset
         const codePoints = toCodePoints(visualLine);
         let currentVisX = 0;
         let charOffset = 0;
@@ -2067,8 +2341,15 @@ export function useTextBuffer({
         // Clamp charOffset to length
         charOffset = Math.min(charOffset, codePoints.length);
 
+        // Map character offset through transformations to get logical position
+        const transformedCol = Math.min(
+          startColInTransformed + charOffset,
+          Math.max(0, transformedToLogicalMap.length - 1),
+        );
+
         const newCursorRow = logRow;
-        const newCursorCol = logStartCol + charOffset;
+        const newCursorCol =
+          transformedToLogicalMap[transformedCol] ?? cpLen(lines[logRow] ?? '');
 
         dispatch({
           type: 'set_cursor',
@@ -2080,7 +2361,7 @@ export function useTextBuffer({
         });
       }
     },
-    [visualLayout],
+    [visualLayout, lines],
   );
 
   const getOffset = useCallback(
@@ -2101,7 +2382,9 @@ export function useTextBuffer({
       visualCursor,
       visualScrollRow,
       visualToLogicalMap,
-
+      transformedToLogicalMaps,
+      visualToTransformedMap,
+      transformationsByLine,
       setText,
       insert,
       newline,
@@ -2167,6 +2450,10 @@ export function useTextBuffer({
       renderedVisualLines,
       visualCursor,
       visualScrollRow,
+      visualToLogicalMap,
+      transformedToLogicalMaps,
+      visualToTransformedMap,
+      transformationsByLine,
       setText,
       insert,
       newline,
@@ -2218,7 +2505,6 @@ export function useTextBuffer({
       vimMoveToLastLine,
       vimMoveToLine,
       vimEscapeInsertMode,
-      visualToLogicalMap,
     ],
   );
   return returnValue;
@@ -2249,6 +2535,18 @@ export interface TextBuffer {
    * begins within the logical buffer. Indices are code-point based.
    */
   visualToLogicalMap: Array<[number, number]>;
+  /**
+   * For each logical line, an array mapping transformed positions (in the transformed
+   * line) back to logical column indices.
+   */
+  transformedToLogicalMaps: number[][];
+  /**
+   * For each visual line (absolute index across all visual lines), the start index
+   * within that logical line's transformed content.
+   */
+  visualToTransformedMap: number[];
+  /** Cached transformations per logical line */
+  transformationsByLine: Transformation[][];
 
   // Actions
 

packages/cli/src/ui/components/shared/vim-buffer-actions.test.ts

@@ -12,6 +12,8 @@ const defaultVisualLayout: VisualLayout = {
   visualLines: [''],
   logicalToVisualMap: [[[0, 0]]],
   visualToLogicalMap: [[0, 0]],
+  transformedToLogicalMaps: [[]],
+  visualToTransformedMap: [],
 };
 
 // Helper to create test state
@@ -30,6 +32,7 @@ const createTestState = (
   selectionAnchor: null,
   viewportWidth: 80,
   viewportHeight: 24,
+  transformationsByLine: [[]],
   visualLayout: defaultVisualLayout,
 });