feat: scroll to inline note card on comment-to-comment navigation

elucid · elucid · commit d65533097fd1 · 2026-03-26T12:10:44.000-04:00
When navigating via {/} or --next-comment/--prev-comment, scroll the
viewport so the inline note card is positioned near the top (with 25%
padding) rather than scrolling to the hunk top. This keeps the review
note visible without requiring the user to scroll down through large
hunks to find it.

- Add scrollToNote prop to DiffPane that switches the scroll anchor
  from hunk bounds to the first inline-note row offset
- Set scrollToNote in moveAnnotatedHunk, clear it on other navigation
- Find the note row offset via section metrics row key prefix match
- Add TDD-style component test verifying note visibility with and
  without the flag on a large hunk with a deep annotation
diff --git a/src/ui/App.tsx b/src/ui/App.tsx
@@ -126,6 +126,7 @@ function AppShell({
   const [resizeStartWidth, setResizeStartWidth] = useState<number | null>(null);
   const [selectedFileId, setSelectedFileId] = useState(bootstrap.changeset.files[0]?.id ?? "");
   const [selectedHunkIndex, setSelectedHunkIndex] = useState(0);
+  const [scrollToNote, setScrollToNote] = useState(false);
   const deferredFilter = useDeferredValue(filter);
 
   const pagerMode = Boolean(bootstrap.input.options.pager);
@@ -135,6 +136,7 @@ function AppShell({
     filesScrollRef.current?.scrollChildIntoView(fileRowId(fileId));
     setSelectedFileId(fileId);
     setSelectedHunkIndex(nextHunkIndex);
+    setScrollToNote(false);
   }, []);
 
   const openAgentNotes = useCallback(() => {
@@ -285,6 +287,7 @@ function AppShell({
     filesScrollRef.current?.scrollChildIntoView(fileRowId(nextCursor.fileId));
     setSelectedFileId(nextCursor.fileId);
     setSelectedHunkIndex(nextCursor.hunkIndex);
+    setScrollToNote(false);
   };
 
   /** Move the review focus to the next or previous annotated hunk. */
@@ -302,6 +305,7 @@ function AppShell({
     filesScrollRef.current?.scrollChildIntoView(fileRowId(nextCursor.fileId));
     setSelectedFileId(nextCursor.fileId);
     setSelectedHunkIndex(nextCursor.hunkIndex);
+    setScrollToNote(true);
   };
 
   /** Scroll the main review pane by line steps, viewport fractions, or whole-content jumps. */
@@ -986,6 +990,7 @@ function AppShell({
           scrollRef={diffScrollRef}
           selectedFileId={selectedFile?.id}
           selectedHunkIndex={selectedHunkIndex}
+          scrollToNote={scrollToNote}
           separatorWidth={diffSeparatorWidth}
           showAgentNotes={showAgentNotes}
           showLineNumbers={showLineNumbers}
diff --git a/src/ui/components/panes/DiffPane.tsx b/src/ui/components/panes/DiffPane.tsx
@@ -129,6 +129,7 @@ export function DiffPane({
   scrollRef,
   selectedFileId,
   selectedHunkIndex,
+  scrollToNote = false,
   separatorWidth,
   pagerMode = false,
   showAgentNotes,
@@ -149,6 +150,7 @@ export function DiffPane({
   scrollRef: RefObject<ScrollBoxRenderable | null>;
   selectedFileId?: string;
   selectedHunkIndex: number;
+  scrollToNote?: boolean;
   separatorWidth: number;
   pagerMode?: boolean;
   showAgentNotes: boolean;
@@ -439,9 +441,37 @@ export function DiffPane({
       height: hunkBounds.height,
       startRowId: hunkBounds.startRowId,
       endRowId: hunkBounds.endRowId,
+      sectionTop,
     };
   }, [estimatedBodyHeights, sectionMetrics, selectedFile, selectedFileIndex, selectedHunkIndex]);
 
+  /** Absolute scroll offset and height of the first inline note in the selected hunk, if any. */
+  const selectedNoteBounds = useMemo(() => {
+    if (!scrollToNote || !selectedEstimatedHunkBounds || selectedFileIndex < 0) {
+      return null;
+    }
+
+    const metrics = sectionMetrics[selectedFileIndex];
+    if (!metrics) {
+      return null;
+    }
+
+    const noteRow = metrics.rowMetrics.find(
+      (row) =>
+        row.key.startsWith("inline-note:") &&
+        row.offset >= selectedEstimatedHunkBounds.top - selectedEstimatedHunkBounds.sectionTop,
+    );
+
+    if (!noteRow) {
+      return null;
+    }
+
+    return {
+      top: selectedEstimatedHunkBounds.sectionTop + noteRow.offset,
+      height: noteRow.height,
+    };
+  }, [scrollToNote, sectionMetrics, selectedEstimatedHunkBounds, selectedFileIndex]);
+
   // Track the previous selected anchor to detect actual selection changes.
   const prevSelectedAnchorIdRef = useRef<string | null>(null);
 
@@ -520,6 +550,21 @@ export function DiffPane({
       const viewportHeight = Math.max(scrollViewport.height, scrollBox.viewport.height ?? 0);
       const preferredTopPadding = Math.max(2, Math.floor(viewportHeight * 0.25));
 
+      // When navigating comment-to-comment, scroll the inline note card near the viewport top
+      // instead of positioning the entire hunk. Uses the same reveal function so the padding
+      // behavior matches regular hunk navigation.
+      if (selectedNoteBounds) {
+        scrollBox.scrollTo(
+          computeHunkRevealScrollTop({
+            hunkTop: selectedNoteBounds.top,
+            hunkHeight: selectedNoteBounds.height,
+            preferredTopPadding,
+            viewportHeight,
+          }),
+        );
+        return;
+      }
+
       if (selectedEstimatedHunkBounds) {
         const viewportTop = scrollBox.viewport.y;
         const currentScrollTop = scrollBox.scrollTop;
@@ -564,7 +609,13 @@ export function DiffPane({
     return () => {
       timeouts.forEach((timeout) => clearTimeout(timeout));
     };
-  }, [scrollRef, scrollViewport.height, selectedAnchorId, selectedEstimatedHunkBounds]);
+  }, [
+    scrollRef,
+    scrollViewport.height,
+    selectedAnchorId,
+    selectedEstimatedHunkBounds,
+    selectedNoteBounds,
+  ]);
 
   // Configure scroll step size to scroll exactly 1 line per step
   useEffect(() => {
diff --git a/test/ui-components.test.tsx b/test/ui-components.test.tsx
@@ -590,6 +590,104 @@ describe("UI components", () => {
     }
   });
 
+  test("DiffPane scrollToNote positions the inline note near the viewport top instead of the hunk top", async () => {
+    const theme = resolveTheme("midnight", null);
+
+    // Build a file with two distant hunks so the second hunk is far below the first when scrolled
+    // to the hunk top. The annotation anchors on the second hunk.
+    const beforeLines = Array.from(
+      { length: 80 },
+      (_, index) => `export const line${index + 1} = ${index + 1};`,
+    );
+    const afterLines = [...beforeLines];
+    // Hunk 0: change at line 1
+    afterLines[0] = "export const line1 = 100;";
+    // Hunk 1: changes at lines 60-65 to make a multi-line hunk
+    afterLines[59] = "export const line60 = 6000;";
+    afterLines[60] = "export const line61 = 6100;";
+    afterLines[61] = "export const line62 = 6200;";
+    afterLines[62] = "export const line63 = 6300;";
+    afterLines[63] = "export const line64 = 6400;";
+    afterLines[64] = "export const line65 = 6500;";
+
+    const file = createDiffFile(
+      "deep-note",
+      "deep-note.ts",
+      lines(...beforeLines),
+      lines(...afterLines),
+    );
+    file.agent = {
+      path: file.path,
+      summary: "file note",
+      annotations: [
+        {
+          newRange: [63, 63],
+          summary: "Note anchored on second hunk.",
+        },
+      ],
+    };
+
+    // Without scrollToNote: hunk top (context before line 60) is near viewport top,
+    // but the note card (anchored at line 63) may be below the visible area.
+    const propsWithoutFlag = createDiffPaneProps([file], theme, {
+      diffContentWidth: 96,
+      headerLabelWidth: 48,
+      selectedFileId: "deep-note",
+      selectedHunkIndex: 1,
+      separatorWidth: 92,
+      showAgentNotes: true,
+      showHunkHeaders: true,
+      width: 100,
+    });
+    const setupWithout = await testRender(<DiffPane {...propsWithoutFlag} />, {
+      width: 104,
+      height: 12,
+    });
+
+    try {
+      await settleDiffPane(setupWithout);
+      const frameWithout = setupWithout.captureCharFrame();
+
+      // Hunk context (lines near 57-59) should be visible at the top.
+      expect(frameWithout).toContain("line57");
+      // Note card should NOT be visible — it's below the 12-row viewport.
+      expect(frameWithout).not.toContain("Note anchored on second hunk.");
+    } finally {
+      await act(async () => {
+        setupWithout.renderer.destroy();
+      });
+    }
+
+    // With scrollToNote: note card should be near the viewport top.
+    const propsWithFlag = createDiffPaneProps([file], theme, {
+      diffContentWidth: 96,
+      headerLabelWidth: 48,
+      selectedFileId: "deep-note",
+      selectedHunkIndex: 1,
+      scrollToNote: true,
+      separatorWidth: 92,
+      showAgentNotes: true,
+      showHunkHeaders: true,
+      width: 100,
+    });
+    const setupWith = await testRender(<DiffPane {...propsWithFlag} />, {
+      width: 104,
+      height: 12,
+    });
+
+    try {
+      await settleDiffPane(setupWith);
+      const frameWith = setupWith.captureCharFrame();
+
+      // Note should be visible.
+      expect(frameWith).toContain("Note anchored on second hunk.");
+    } finally {
+      await act(async () => {
+        setupWith.renderer.destroy();
+      });
+    }
+  });
+
   test("AgentCard removes top and bottom padding while keeping the footer inside the frame", async () => {
     const theme = resolveTheme("midnight", null);
     const frame = await captureFrame(
