fix(vim): keep the j/k cursor clear of the HUD bands when scrolling

.github/workflows/test.yml

@@ -49,6 +49,7 @@ jobs:
           packages/ui/codeAnnotationDraftPersistence.test.tsx
           packages/ui/components/html-viewer/srcdoc.test.ts
           packages/ui/utils/clipboard.test.ts
+          packages/ui/utils/vimScroll.test.ts
           packages/ui/components/InlineMarkdown.resolveLinkedDoc.test.tsx
           packages/ui/components/MarkdownDiff.frozen.test.tsx
           packages/ui/components/MarkdownEditor.extensions.test.tsx

packages/ui/components/Viewer.tsx

@@ -248,6 +248,9 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     }
   };
   const containerRef = useRef<HTMLDivElement>(null);
+  // The element that actually scrolls; shared by the Vim scroll math, the
+  // sticky-header observer, and the reticle geometry.
+  const scrollViewport = useScrollViewport();
   // The badge cluster (repo chips / diff badge) is absolutely positioned in the
   // card's top padding. One row fits; a second row (diff badge) or mobile
   // wrapping outgrows the padding and lands on the document's first heading.
@@ -461,6 +464,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   }, []);
   const vim = useVimSelection({
     containerRef,
+    scrollViewport,
     enabled: vimModeActive,
     hudEnabled: vimHudEnabled,
     blocked: vimBlocked,
@@ -535,16 +539,15 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   // Detect when sticky action bar is "stuck" to show card background.
   // The IntersectionObserver root must be the actual scroll element — the
   // OverlayScrollArea viewport — not the <main> host, which doesn't scroll.
-  const stickyScrollViewport = useScrollViewport();
   useEffect(() => {
-    if (!stickyActions || !stickySentinelRef.current || !stickyScrollViewport) return;
+    if (!stickyActions || !stickySentinelRef.current || !scrollViewport) return;
     const observer = new IntersectionObserver(
       ([entry]) => setIsStuck(!entry.isIntersecting),
-      { root: stickyScrollViewport, threshold: 0 }
+      { root: scrollViewport, threshold: 0 }
     );
     observer.observe(stickySentinelRef.current);
     return () => observer.disconnect();
-  }, [stickyActions, stickyScrollViewport]);
+  }, [stickyActions, scrollViewport]);
 
   useEffect(() => {
     const handleHashChange = () => {
@@ -561,7 +564,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     if (!anchor) return false;
 
     const container = containerRef.current;
-    if (!container || !stickyScrollViewport) return false;
+    if (!container || !scrollViewport) return false;
 
     const target = document.getElementById(anchor);
     if (!target || !container.contains(target)) return false;
@@ -573,27 +576,27 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     const headerOffset = stickyActionsEl
       ? stickyActionsEl.getBoundingClientRect().height + stickyTop
       : 0;
-    const containerRect = stickyScrollViewport.getBoundingClientRect();
+    const containerRect = scrollViewport.getBoundingClientRect();
     const targetRect = target.getBoundingClientRect();
     const relativeTop = targetRect.top - containerRect.top;
-    const offsetPosition = stickyScrollViewport.scrollTop + relativeTop - headerOffset;
+    const offsetPosition = scrollViewport.scrollTop + relativeTop - headerOffset;
 
-    stickyScrollViewport.scrollTo({
+    scrollViewport.scrollTo({
       top: Math.max(0, offsetPosition),
       behavior: 'smooth',
     });
     return true;
-  }, [stickyScrollViewport]);
+  }, [scrollViewport]);
 
   useEffect(() => {
-    if (!stickyScrollViewport || !locationHash || lastAutoScrolledHashRef.current === locationHash) return;
+    if (!scrollViewport || !locationHash || lastAutoScrolledHashRef.current === locationHash) return;
     const timer = window.setTimeout(() => {
       if (scrollToAnchor(locationHash)) {
         lastAutoScrolledHashRef.current = locationHash;
       }
     }, 0);
     return () => window.clearTimeout(timer);
-  }, [blocks, locationHash, scrollToAnchor, stickyScrollViewport]);
+  }, [blocks, locationHash, scrollToAnchor, scrollViewport]);
 
   // Use the native copy event so clipboard writes are synchronous (Safari
   // rejects the async navigator.clipboard API outside the user-gesture window).

packages/ui/hooks/useVimSelection.ts

@@ -47,11 +47,14 @@ import {
   type VimVisualBlockState,
   type VimVisualState,
 } from '../utils/vimNavigation';
+import { scrollVimTargetIntoView } from '../utils/vimScroll';
 import { useVimDocumentFocus } from './useVimDocumentFocus';
 
 /** Inputs required by the Markdown semantic Vim controller. */
 export interface UseVimSelectionOptions {
   readonly containerRef: RefObject<HTMLElement | null>;
+  /** The element that actually scrolls (ScrollViewportContext value). */
+  readonly scrollViewport?: HTMLElement | null;
   readonly enabled: boolean;
   readonly hudEnabled: boolean;
   readonly blocked: boolean;
@@ -234,6 +237,7 @@ function applyVisualBlockSelection(
  */
 export function useVimSelection({
   containerRef,
+  scrollViewport,
   enabled,
   hudEnabled,
   blocked,
@@ -257,6 +261,11 @@ export function useVimSelection({
   const pointerFocusRef = useRef(false);
   const restoringFocusRef = useRef(false);
 
+  // Read the live scroll viewport without adding a dependency to every
+  // navigation callback below.
+  const scrollViewportRef = useRef(scrollViewport);
+  scrollViewportRef.current = scrollViewport;
+
   const setState = useCallback((next: VimSelectionState) => {
     stateRef.current = next;
     setStateValue(next);
@@ -283,7 +292,7 @@ export function useVimSelection({
     const next: VimBlockState = { phase: 'block', targetKey: initial.key };
     setState(next);
     window.getSelection()?.removeAllRanges();
-    initial.element.scrollIntoView({ block: 'nearest' });
+    scrollVimTargetIntoView(initial.element, scrollViewportRef.current);
     return next;
   }, [containerRef, setState]);
 
@@ -358,7 +367,7 @@ export function useVimSelection({
   const setSemanticTarget = useCallback((target: SemanticTarget) => {
     setState(semanticStateForTarget(target));
     window.getSelection()?.removeAllRanges();
-    target.element.scrollIntoView({ block: 'nearest' });
+    scrollVimTargetIntoView(target.element, scrollViewportRef.current);
   }, [setState]);
 
   const updateTextState = useCallback((
@@ -373,9 +382,9 @@ export function useVimSelection({
       normalized.cursor,
       normalized.phase === 'visual' ? normalized.anchor : null,
     );
-    resolveTextPosition(graph.container, normalized.cursor)
-      ?.node.parentElement
-      ?.scrollIntoView({ block: 'nearest' });
+    const cursorParent = resolveTextPosition(graph.container, normalized.cursor)
+      ?.node.parentElement;
+    if (cursorParent) scrollVimTargetIntoView(cursorParent, scrollViewportRef.current);
   }, [setState]);
 
   const enterTextAtTarget = useCallback((
@@ -420,7 +429,7 @@ export function useVimSelection({
     if (!getTextElementBounds(graph.container, block.element)) return false;
     setState(next);
     applyVisualBlockSelection(graph, next);
-    block.element.scrollIntoView({ block: 'nearest' });
+    scrollVimTargetIntoView(block.element, scrollViewportRef.current);
     return true;
   }, [setState]);
 
@@ -730,7 +739,7 @@ export function useVimSelection({
       };
       setState(nextState);
       applyVisualBlockSelection(graph, nextState);
-      next.element.scrollIntoView({ block: 'nearest' });
+      scrollVimTargetIntoView(next.element, scrollViewportRef.current);
       return true;
     }
     if (key === 'o') {