fix(ui): stabilize agent note navigation

src/core/liveComments.test.ts

@@ -38,7 +38,9 @@ describe("live comment helpers", () => {
     const file = createExampleDiffFile();
 
     expect(findHunkIndexForLine(file, "old", 1)).toBe(0);
+    expect(findHunkIndexForLine(file, "old", 3)).toBe(0);
     expect(findHunkIndexForLine(file, "new", 2)).toBe(0);
+    expect(findHunkIndexForLine(file, "new", 4)).toBe(0);
     expect(findHunkIndexForLine(file, "new", 40)).toBe(-1);
   });
 
@@ -111,8 +113,8 @@ describe("live comment helpers", () => {
     const range = hunkLineRange(file.metadata.hunks[0]!);
 
     expect(range.oldRange[0]).toBeLessThanOrEqual(1);
-    expect(range.oldRange[1]).toBeGreaterThanOrEqual(2);
+    expect(range.oldRange[1]).toBeGreaterThanOrEqual(3);
     expect(range.newRange[0]).toBeLessThanOrEqual(1);
-    expect(range.newRange[1]).toBeGreaterThanOrEqual(2);
+    expect(range.newRange[1]).toBeGreaterThanOrEqual(4);
   });
 });

src/core/liveComments.ts

@@ -8,16 +8,12 @@ export interface ResolvedCommentTarget {
   line: number;
 }
 
-/** Compute the inclusive old/new line spans touched by one hunk. */
+/** Compute the inclusive old/new line spans covered by one hunk. */
 export function hunkLineRange(hunk: Hunk) {
-  const newEnd = Math.max(
-    hunk.additionStart,
-    hunk.additionStart + Math.max(hunk.additionLines, 1) - 1,
-  );
-  const oldEnd = Math.max(
-    hunk.deletionStart,
-    hunk.deletionStart + Math.max(hunk.deletionLines, 1) - 1,
-  );
+  const additionSpan = hunk.additionCount ?? hunk.additionLines;
+  const deletionSpan = hunk.deletionCount ?? hunk.deletionLines;
+  const newEnd = Math.max(hunk.additionStart, hunk.additionStart + Math.max(additionSpan, 1) - 1);
+  const oldEnd = Math.max(hunk.deletionStart, hunk.deletionStart + Math.max(deletionSpan, 1) - 1);
 
   return {
     oldRange: [hunk.deletionStart, oldEnd] as [number, number],

src/ui/components/panes/DiffPane.tsx

@@ -40,7 +40,6 @@ import { VerticalScrollbar, type VerticalScrollbarHandle } from "../scrollbar/Ve
 import { prefetchHighlightedDiff } from "../../diff/useHighlightedDiff";
 
 const EMPTY_VISIBLE_AGENT_NOTES: VisibleAgentNote[] = [];
-const EMPTY_VISIBLE_AGENT_NOTES_BY_FILE = new Map<string, VisibleAgentNote[]>();
 
 /**
  * Clamp one vertical scroll target into the currently reachable review-stream extent.
@@ -270,8 +269,9 @@ export function DiffPane({
     return next;
   }, [files, showAgentNotes]);
 
-  // Keep exact row rendering for wrapped lines and the selected file's visible notes;
-  // other files can still use placeholders and viewport windowing.
+  // Keep exact row rendering for wrapped lines; other files can still use placeholders and viewport
+  // windowing. Rendered sections always include their note rows so their concrete height matches the
+  // geometry used for scroll planning.
   const windowingEnabled = !wrapLines;
   const [scrollViewport, setScrollViewport] = useState({ top: 0, height: 0 });
   const scrollbarRef = useRef<VerticalScrollbarHandle>(null);
@@ -391,35 +391,11 @@ export function DiffPane({
     return collectIntersectingFileSectionIds(baseFileSectionLayouts, minVisibleY, maxVisibleY);
   }, [baseFileSectionLayouts, scrollViewport.height, scrollViewport.top]);
 
-  const visibleAgentNotesByFile = useMemo(() => {
-    const next = new Map<string, VisibleAgentNote[]>();
-
-    if (!showAgentNotes) {
-      return EMPTY_VISIBLE_AGENT_NOTES_BY_FILE;
-    }
-
-    const fileIdsToMeasure = new Set(visibleViewportFileIds);
-    // Always measure the selected file with its real note rows so hunk navigation can compute
-    // accurate bounds even before the file scrolls into the visible viewport.
-    if (selectedFileId) {
-      fileIdsToMeasure.add(selectedFileId);
-    }
-
-    for (const fileId of fileIdsToMeasure) {
-      const visibleNotes = allAgentNotesByFile.get(fileId);
-      if (visibleNotes && visibleNotes.length > 0) {
-        next.set(fileId, visibleNotes);
-      }
-    }
-
-    return next;
-  }, [allAgentNotesByFile, selectedFileId, showAgentNotes, visibleViewportFileIds]);
-
   const sectionGeometry = useMemo(
     () =>
       files.map((file, index) => {
-        const visibleNotes = visibleAgentNotesByFile.get(file.id) ?? EMPTY_VISIBLE_AGENT_NOTES;
-        if (visibleNotes.length === 0) {
+        const agentNotes = allAgentNotesByFile.get(file.id) ?? EMPTY_VISIBLE_AGENT_NOTES;
+        if (agentNotes.length === 0) {
           return baseSectionGeometry[index]!;
         }
 
@@ -428,21 +404,21 @@ export function DiffPane({
           layout,
           showHunkHeaders,
           theme,
-          visibleNotes,
+          agentNotes,
           diffContentWidth,
           showLineNumbers,
           wrapLines,
         );
       }),
     [
       baseSectionGeometry,
+      allAgentNotesByFile,
       diffContentWidth,
       files,
       layout,
       showHunkHeaders,
       showLineNumbers,
       theme,
-      visibleAgentNotesByFile,
       wrapLines,
     ],
   );
@@ -1094,7 +1070,7 @@ export function DiffPane({
                       theme={theme}
                       viewWidth={diffContentWidth}
                       visibleAgentNotes={
-                        visibleAgentNotesByFile.get(file.id) ?? EMPTY_VISIBLE_AGENT_NOTES
+                        allAgentNotesByFile.get(file.id) ?? EMPTY_VISIBLE_AGENT_NOTES
                       }
                       onOpenAgentNotesAtHunk={(hunkIndex) =>
                         onOpenAgentNotesAtHunk(file.id, hunkIndex)

src/ui/components/ui-components.test.tsx

@@ -858,8 +858,20 @@ describe("UI components", () => {
 
   test("DiffPane lets manual scrolling move away from a bottom-clamped file-top alignment", async () => {
     const theme = resolveTheme("midnight", null);
+    const firstFile = createTallDiffFile("first", "first.ts", 30);
+    firstFile.agent = {
+      path: firstFile.path,
+      summary: "first file note",
+      annotations: [
+        {
+          newRange: [12, 12],
+          summary: "Offscreen note rows must stay in geometry.",
+          rationale: "This note is on the file above the bottom-clamped selected file.",
+        },
+      ],
+    };
     const files = [
-      createTallDiffFile("first", "first.ts", 30),
+      firstFile,
       createTestDiffFile(
         "second",
         "second.ts",
@@ -895,6 +907,7 @@ describe("UI components", () => {
             selectedHunkIndex: 0,
             selectedFileTopAlignRequestId,
             separatorWidth: 84,
+            showAgentNotes: true,
             width: 92,
           })}
         />

src/ui/hooks/useAppKeyboardShortcuts.ts

@@ -81,11 +81,16 @@ export function useAppKeyboardShortcuts({
 }: UseAppKeyboardShortcutsOptions) {
   const activeMenuIdRef = useRef(activeMenuId);
   const focusAreaRef = useRef(focusArea);
+  // Keep navigation shortcuts resilient if the keyboard hook changes how it stores callbacks.
+  const moveToAnnotatedHunkRef = useRef(moveToAnnotatedHunk);
+  const moveToHunkRef = useRef(moveToHunk);
   const pagerModeRef = useRef(pagerMode);
   const showHelpRef = useRef(showHelp);
 
   activeMenuIdRef.current = activeMenuId;
   focusAreaRef.current = focusArea;
+  moveToAnnotatedHunkRef.current = moveToAnnotatedHunk;
+  moveToHunkRef.current = moveToHunk;
   pagerModeRef.current = pagerMode;
   showHelpRef.current = showHelp;
 
@@ -362,22 +367,22 @@ export function useAppKeyboardShortcuts({
     }
 
     if (key.name === "[") {
-      runAndCloseMenu(() => moveToHunk(-1));
+      runAndCloseMenu(() => moveToHunkRef.current(-1));
       return;
     }
 
     if (key.name === "]") {
-      runAndCloseMenu(() => moveToHunk(1));
+      runAndCloseMenu(() => moveToHunkRef.current(1));
       return;
     }
 
     if (key.sequence === "{") {
-      runAndCloseMenu(() => moveToAnnotatedHunk(-1));
+      runAndCloseMenu(() => moveToAnnotatedHunkRef.current(-1));
       return;
     }
 
     if (key.sequence === "}") {
-      runAndCloseMenu(() => moveToAnnotatedHunk(1));
+      runAndCloseMenu(() => moveToAnnotatedHunkRef.current(1));
     }
   };
 

src/ui/hooks/useReviewController.ts

@@ -199,6 +199,7 @@ export function useReviewController({ files }: { files: DiffFile[] }): ReviewCon
         selectedFile?.id,
         selectedHunkIndex,
         delta,
+        hunkCursors,
       );
       if (!nextCursor) {
         return;
@@ -224,14 +225,15 @@ export function useReviewController({ files }: { files: DiffFile[] }): ReviewCon
         selectedFile?.id,
         selectedHunkIndex,
         delta,
+        hunkCursors,
       );
       if (!nextCursor) {
         return;
       }
 
       selectHunk(nextCursor.fileId, nextCursor.hunkIndex, { scrollToNote: true });
     },
-    [annotatedHunkCursors, selectHunk, selectedFile?.id, selectedHunkIndex],
+    [annotatedHunkCursors, hunkCursors, selectHunk, selectedFile?.id, selectedHunkIndex],
   );
 
   /** Cycle through only the currently visible files that carry annotations. */

src/ui/lib/agentAnnotations.ts

@@ -1,4 +1,5 @@
 import type { Hunk } from "@pierre/diffs";
+import { hunkLineRange } from "../../core/liveComments";
 import type { AgentAnnotation, DiffFile } from "../../core/types";
 import { fileLabel } from "./files";
 
@@ -17,23 +18,6 @@ function overlap(rangeA: [number, number], rangeB: [number, number]) {
   return rangeA[0] <= rangeB[1] && rangeB[0] <= rangeA[1];
 }
 
-/** Compute the old/new line ranges covered by a hunk, including single-line edge cases. */
-function hunkLineRange(hunk: Hunk) {
-  const newEnd = Math.max(
-    hunk.additionStart,
-    hunk.additionStart + Math.max(hunk.additionLines, 1) - 1,
-  );
-  const oldEnd = Math.max(
-    hunk.deletionStart,
-    hunk.deletionStart + Math.max(hunk.deletionLines, 1) - 1,
-  );
-
-  return {
-    oldRange: [hunk.deletionStart, oldEnd] as [number, number],
-    newRange: [hunk.additionStart, newEnd] as [number, number],
-  };
-}
-
 /** Check whether an annotation belongs to the visible span of a hunk. */
 function annotationOverlapsHunk(annotation: AgentAnnotation, hunk: Hunk) {
   const hunkRange = hunkLineRange(hunk);

src/ui/lib/hunks.test.ts

@@ -73,11 +73,10 @@ describe("annotated hunk navigation", () => {
   const afterB = "new\n";
 
   test("only includes hunks that have overlapping annotations", () => {
-    // Hunk 0 new range is [1,1], hunk 1 new range is [17,17].
-    // Annotate only hunk 1 in file alpha, and hunk 0 in file beta.
+    // Annotate the changed line in alpha hunk 1 and the only hunk in beta.
     const fileA = createTestFile("alpha", "alpha.ts", beforeA, afterA, {
       path: "alpha.ts",
-      annotations: [{ newRange: [17, 17], summary: "Note on hunk 1" }],
+      annotations: [{ newRange: [20, 20], summary: "Note on hunk 1" }],
     });
     const fileB = createTestFile("beta", "beta.ts", beforeB, afterB, {
       path: "beta.ts",
@@ -169,4 +168,36 @@ describe("annotated hunk navigation", () => {
       hunkIndex: 1,
     });
   });
+
+  test("uses full stream position when annotated navigation starts on an unannotated hunk", () => {
+    const streamCursors: HunkCursor[] = [
+      { fileId: "alpha", hunkIndex: 0 },
+      { fileId: "alpha", hunkIndex: 1 },
+      { fileId: "beta", hunkIndex: 0 },
+      { fileId: "gamma", hunkIndex: 0 },
+      { fileId: "gamma", hunkIndex: 1 },
+    ];
+    const annotatedCursors: HunkCursor[] = [
+      { fileId: "alpha", hunkIndex: 1 },
+      { fileId: "gamma", hunkIndex: 0 },
+      { fileId: "gamma", hunkIndex: 1 },
+    ];
+
+    expect(findNextHunkCursor(annotatedCursors, "beta", 0, 1, streamCursors)).toEqual({
+      fileId: "gamma",
+      hunkIndex: 0,
+    });
+    expect(findNextHunkCursor(annotatedCursors, "beta", 0, -1, streamCursors)).toEqual({
+      fileId: "alpha",
+      hunkIndex: 1,
+    });
+    expect(findNextHunkCursor(annotatedCursors, "alpha", 0, 1, streamCursors)).toEqual({
+      fileId: "alpha",
+      hunkIndex: 1,
+    });
+    expect(findNextHunkCursor(annotatedCursors, "gamma", 1, 1, streamCursors)).toEqual({
+      fileId: "gamma",
+      hunkIndex: 1,
+    });
+  });
 });

src/ui/lib/hunks.ts

@@ -29,6 +29,7 @@ export function findNextHunkCursor(
   currentFileId: string | undefined,
   currentHunkIndex: number,
   delta: number,
+  streamCursors: HunkCursor[] = cursors,
 ): HunkCursor | null {
   if (cursors.length === 0) {
     return null;
@@ -40,9 +41,54 @@ export function findNextHunkCursor(
   const nextIndex =
     currentIndex >= 0
       ? Math.min(Math.max(currentIndex + delta, 0), cursors.length - 1)
-      : delta >= 0
-        ? 0
-        : cursors.length - 1;
+      : findNearestCursorIndex(cursors, streamCursors, currentFileId, currentHunkIndex, delta);
 
   return cursors[nextIndex] ?? null;
 }
+
+/** Resolve relative movement when the current hunk is not in the target cursor subset. */
+function findNearestCursorIndex(
+  cursors: HunkCursor[],
+  streamCursors: HunkCursor[],
+  currentFileId: string | undefined,
+  currentHunkIndex: number,
+  delta: number,
+) {
+  if (!currentFileId) {
+    return delta >= 0 ? 0 : cursors.length - 1;
+  }
+
+  const currentStreamIndex = streamCursors.findIndex(
+    (cursor) => cursor.fileId === currentFileId && cursor.hunkIndex === currentHunkIndex,
+  );
+  if (currentStreamIndex < 0) {
+    return delta >= 0 ? 0 : cursors.length - 1;
+  }
+
+  const streamIndexByCursor = new Map(
+    streamCursors.map((cursor, index) => [`${cursor.fileId}\0${cursor.hunkIndex}`, index] as const),
+  );
+  const cursorStreamIndex = (cursor: HunkCursor) =>
+    streamIndexByCursor.get(`${cursor.fileId}\0${cursor.hunkIndex}`) ?? -1;
+  const indexedCursors = cursors
+    .map((cursor, index) => ({ index, streamIndex: cursorStreamIndex(cursor) }))
+    .filter(({ streamIndex }) => streamIndex >= 0);
+
+  if (indexedCursors.length === 0) {
+    return delta >= 0 ? 0 : cursors.length - 1;
+  }
+
+  if (delta >= 0) {
+    const nextCursor = indexedCursors.find(({ streamIndex }) => streamIndex > currentStreamIndex);
+    return nextCursor?.index ?? indexedCursors[indexedCursors.length - 1]!.index;
+  }
+
+  for (let index = indexedCursors.length - 1; index >= 0; index -= 1) {
+    const indexedCursor = indexedCursors[index]!;
+    if (indexedCursor.streamIndex < currentStreamIndex) {
+      return indexedCursor.index;
+    }
+  }
+
+  return indexedCursors[0]!.index;
+}

src/ui/lib/reviewState.ts

@@ -132,8 +132,15 @@ export function resolveReviewNavigationTarget({
 }): ReviewNavigationTarget {
   if (input.commentDirection) {
     const delta = input.commentDirection === "next" ? 1 : -1;
+    const hunkCursors = buildHunkCursors(visibleFiles);
     const annotatedCursors = buildAnnotatedHunkCursors(visibleFiles);
-    const nextCursor = findNextHunkCursor(annotatedCursors, currentFileId, currentHunkIndex, delta);
+    const nextCursor = findNextHunkCursor(
+      annotatedCursors,
+      currentFileId,
+      currentHunkIndex,
+      delta,
+      hunkCursors,
+    );
 
     if (!nextCursor) {
       throw new Error("No annotated hunks found in the current review.");