feat(graph): add jump-to-HEAD button and HEAD search matching (#56)

Add a location button beside the search box that scrolls the graph to
the current HEAD commit, emphasized only when HEAD is off-screen. Also
match the HEAD keyword in search so typing HEAD navigates to it.

Author: the0807

webview-ui/src/App.svelte

@@ -54,6 +54,8 @@ import AmendModal from './components/modals/AmendModal.svelte';
   let bisectMessage = $state<string | null>(null);
   let searchMatchedHashes = $state<Set<string> | null>(null);
   let searchNavigateHash = $state<string | null>(null);
+  let headOffscreen = $state(false);
+  let headJumpNonce = $state(0);
   let remoteFilter = $state<string[]>([]);
   let branchFilter = $state<string[]>([]);
   let resizing = $state(false);
@@ -279,6 +281,10 @@ import AmendModal from './components/modals/AmendModal.svelte';
     searchNavigateHash = hash;
   }
 
+  function handleJumpToHead() {
+    headJumpNonce++;
+  }
+
   function handleFilterChange(filter: string[]) {
     remoteFilter = filter;
     if (filter.length > 0) {
@@ -448,6 +454,8 @@ import AmendModal from './components/modals/AmendModal.svelte';
           branches={branchStore.branches}
           {branchFilter}
           onBranchFilterChange={handleBranchFilterChange}
+          {headOffscreen}
+          onJumpToHead={handleJumpToHead}
         />
       {/if}
       {#if bisectMessage}
@@ -460,7 +468,7 @@ import AmendModal from './components/modals/AmendModal.svelte';
       {/if}
       {#if !uiStore.commitDetailFullscreen}
         <div class="graph-area">
-          <CommitGraph {searchMatchedHashes} {searchNavigateHash} bisectActive={bisectMessage !== null} bisectCulpritHash={bisectMessage?.includes('is the first bad commit') ? bisectMessage.match(/^([a-f0-9]{7,40})/)?.[1] ?? null : null} {remoteFilter} />
+          <CommitGraph {searchMatchedHashes} {searchNavigateHash} headJumpNonce={headJumpNonce} onHeadOffscreenChange={(v) => headOffscreen = v} bisectActive={bisectMessage !== null} bisectCulpritHash={bisectMessage?.includes('is the first bad commit') ? bisectMessage.match(/^([a-f0-9]{7,40})/)?.[1] ?? null : null} {remoteFilter} />
         </div>
       {/if}
       {#if uiStore.showBottomPanel && (uiStore.selectedCommitHash || uiStore.comparing)}

webview-ui/src/components/common/SearchBar.svelte

@@ -14,6 +14,8 @@
     branches?: BranchInfo[];
     branchFilter?: string[];
     onBranchFilterChange?: (filter: string[]) => void;
+    headOffscreen?: boolean;
+    onJumpToHead?: () => void;
   }
 
   let {
@@ -25,6 +27,8 @@
     branches = [],
     branchFilter = [],
     onBranchFilterChange = () => {},
+    headOffscreen = false,
+    onJumpToHead = () => {},
   }: Props = $props();
 
   let query = $state('');
@@ -39,6 +43,8 @@
 
   const branchFilterActive = $derived(branchFilter.length > 0);
 
+  const hasHead = $derived(commitStore.headHash !== null);
+
   const localBranches = $derived(
     (remoteFilter.length === 0 || remoteFilter.includes('local'))
       ? branches.filter(b => !b.remote)
@@ -99,6 +105,7 @@
         ...commit.refs
           .filter(r => r.type === 'branch' || r.type === 'remote-branch' || r.type === 'tag')
           .flatMap(r => r.type === 'remote-branch' && r.remote ? [r.name, `${r.remote}/${r.name}`] : [r.name]),
+        ...(commit.refs.some(r => r.type === 'head') ? ['HEAD'] : []),
       ].join(' ').toLowerCase();
 
       if (haystack.includes(q)) {
@@ -223,6 +230,17 @@
     {/if}
   </div>
 
+  <button
+    class="head-btn"
+    class:active={headOffscreen}
+    onclick={() => onJumpToHead()}
+    disabled={!hasHead}
+    aria-label={t('search.jumpToHead')}
+    use:tooltip={t('search.jumpToHead')}
+  >
+    <i class="codicon codicon-location"></i>
+  </button>
+
   <div class="filter-wrap">
     <button
       class="filter-btn"
@@ -466,6 +484,37 @@
     flex-shrink: 0;
   }
 
+  .head-btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 30px;
+    height: 30px;
+    flex-shrink: 0;
+    background: transparent;
+    color: var(--text-secondary);
+    border: 1px solid var(--border-color);
+    border-radius: 6px;
+    cursor: pointer;
+    font-size: 14px;
+    transition: color 0.1s, border-color 0.1s;
+  }
+
+  .head-btn:hover:not(:disabled) {
+    color: var(--text-primary);
+    border-color: var(--vscode-focusBorder, #007fd4);
+  }
+
+  .head-btn.active {
+    color: var(--vscode-focusBorder, #007fd4);
+    border-color: var(--vscode-focusBorder, #007fd4);
+  }
+
+  .head-btn:disabled {
+    opacity: 0.4;
+    cursor: default;
+  }
+
   .filter-btn {
     display: flex;
     align-items: center;

webview-ui/src/components/common/__tests__/SearchBar.test.ts

@@ -263,6 +263,23 @@ describe('SearchBar — filter UI', () => {
   });
 });
 
+describe('SearchBar — HEAD keyword', () => {
+  it('typing HEAD matches the commit carrying a head ref', async () => {
+    setCommits([
+      commit({ hash: 'h1', subject: 'one' }),
+      commit({ hash: 'h2', subject: 'two', refs: [{ type: 'head', name: 'HEAD' }] }),
+    ]);
+    const onResults = vi.fn();
+    const { container } = render(SearchBar, { ...baseProps, onResults });
+    const input = container.querySelector<HTMLInputElement>('.search-input')!;
+    await fireEvent.input(input, { target: { value: 'HEAD' } });
+    vi.advanceTimersByTime(150);
+    const matched = onResults.mock.calls.at(-1)![0] as Set<string>;
+    expect(matched.has('h2')).toBe(true);
+    expect(matched.has('h1')).toBe(false);
+  });
+});
+
 describe('SearchBar — branch filter', () => {
   const branches: BranchInfo[] = [
     { name: 'main', current: true, ahead: 0, behind: 0, hash: 'h' },
@@ -314,3 +331,30 @@ describe('SearchBar — branch filter', () => {
     expect(onBranchFilterChange).toHaveBeenCalledWith([]);
   });
 });
+
+describe('SearchBar — jump to HEAD button', () => {
+  it('is disabled when no commit is HEAD', () => {
+    setCommits([commit({ hash: 'h1' })]);
+    const { container } = render(SearchBar, { ...baseProps });
+    const btn = container.querySelector<HTMLButtonElement>('.head-btn')!;
+    expect(btn).toBeTruthy();
+    expect(btn.disabled).toBe(true);
+  });
+
+  it('is enabled and calls onJumpToHead when clicked', async () => {
+    setCommits([commit({ hash: 'h1', refs: [{ type: 'head', name: 'HEAD' }] })]);
+    const onJumpToHead = vi.fn();
+    const { container } = render(SearchBar, { ...baseProps, onJumpToHead });
+    const btn = container.querySelector<HTMLButtonElement>('.head-btn')!;
+    expect(btn.disabled).toBe(false);
+    await fireEvent.click(btn);
+    expect(onJumpToHead).toHaveBeenCalled();
+  });
+
+  it('has the active class when headOffscreen is true', () => {
+    setCommits([commit({ hash: 'h1', refs: [{ type: 'head', name: 'HEAD' }] })]);
+    const { container } = render(SearchBar, { ...baseProps, headOffscreen: true });
+    const btn = container.querySelector<HTMLButtonElement>('.head-btn')!;
+    expect(btn.classList.contains('active')).toBe(true);
+  });
+});

webview-ui/src/components/graph/CommitGraph.svelte

@@ -26,7 +26,7 @@
   import { tooltip } from '../../lib/actions/tooltip';
   import { getSquashChain } from '../../lib/utils/squash';
   import { resolveDrop, dragRebaseMessage, dragMergeMessage } from '../../lib/utils/dragDrop';
-  import { computeNavigationTarget, computeScrollTop, computeJumpTarget, type ScrollAlign } from '../../lib/graph-navigation';
+  import { computeNavigationTarget, computeScrollTop, computeJumpTarget, isRowOffscreen, type ScrollAlign } from '../../lib/graph-navigation';
   import LinkifiedText from '../common/LinkifiedText.svelte';
 
 
@@ -73,9 +73,11 @@
     bisectActive?: boolean;
     bisectCulpritHash?: string | null;
     remoteFilter?: string[];
+    headJumpNonce?: number;
+    onHeadOffscreenChange?: (offscreen: boolean) => void;
   }
 
-  let { searchMatchedHashes = null, searchNavigateHash = null, bisectActive = false, bisectCulpritHash = null, remoteFilter = [] }: Props = $props();
+  let { searchMatchedHashes = null, searchNavigateHash = null, bisectActive = false, bisectCulpritHash = null, remoteFilter = [], headJumpNonce = 0, onHeadOffscreenChange = () => {} }: Props = $props();
 
   const vscode = getVsCodeApi();
 
@@ -366,6 +368,39 @@
     }
   });
 
+  // HEAD's row index, recomputed only when the commit set or HEAD changes - not
+  // on every scroll - so the offscreen check below stays O(1) per scroll frame
+  // instead of re-scanning displayCommits each time scrollTop updates.
+  const headRowIndex = $derived.by(() => {
+    const headHash = commitStore.headHash;
+    return headHash ? displayCommits.findIndex(c => c.hash === headHash) : -1;
+  });
+
+  // Tell the toolbar's "jump to HEAD" button whether HEAD is currently off-screen,
+  // so it emphasizes itself only when scrolling is actually needed. Recomputed on
+  // scroll (scrollTop), resize (viewportHeight) and data changes (headRowIndex).
+  // Guarded so we only notify the parent when the boolean actually flips.
+  let lastHeadOffscreen: boolean | null = null;
+  $effect(() => {
+    const offscreen = isRowOffscreen(headRowIndex, ROW_HEIGHT, scrollTop, viewportHeight);
+    if (offscreen !== lastHeadOffscreen) {
+      lastHeadOffscreen = offscreen;
+      onHeadOffscreenChange(offscreen);
+    }
+  });
+
+  // Scroll HEAD into view (centered) when the toolbar button is clicked. The nonce
+  // (not the hash) drives this so repeated clicks re-scroll even when HEAD hasn't
+  // changed. The initial value (0) is skipped so opening the graph never jumps.
+  let lastHeadJumpNonce = 0;
+  $effect(() => {
+    if (headJumpNonce !== lastHeadJumpNonce) {
+      lastHeadJumpNonce = headJumpNonce;
+      const headHash = commitStore.headHash;
+      if (headHash) scrollHashIntoView(headHash, 'center');
+    }
+  });
+
   // A reload or repo switch replaces the commit set; drop the jump path so it can't
   // reference commits that are no longer present.
   $effect(() => {

webview-ui/src/lib/__tests__/graph-navigation.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { computeNavigationTarget, computeScrollTop, computeJumpTarget } from '../graph-navigation';
+import { computeNavigationTarget, computeScrollTop, computeJumpTarget, isRowOffscreen } from '../graph-navigation';
 
 // Newest-first list. Linear chain a <- b <- c with a merge:
 //   a (top/newest)  parents: [b]
@@ -226,3 +226,29 @@ describe('computeJumpTarget', () => {
     expect(computeJumpTarget(jg, 'a', 'up', ['a'])).toEqual({ target: null, path: ['a'] });
   });
 });
+
+describe('isRowOffscreen', () => {
+  it('row above the viewport is offscreen', () => {
+    // row 0 spans 0..30px; viewport is 300..900
+    expect(isRowOffscreen(0, 30, 300, 600)).toBe(true);
+  });
+
+  it('row below the viewport is offscreen', () => {
+    // row 40 spans 1200..1230px; viewport is 0..600
+    expect(isRowOffscreen(40, 30, 0, 600)).toBe(true);
+  });
+
+  it('row inside the viewport is on-screen', () => {
+    // row 10 spans 300..330px; viewport is 0..600
+    expect(isRowOffscreen(10, 30, 0, 600)).toBe(false);
+  });
+
+  it('a partially visible row counts as on-screen', () => {
+    // row 20 spans 600..630px; viewport is 0..610 (overlaps 600..610)
+    expect(isRowOffscreen(20, 30, 0, 610)).toBe(false);
+  });
+
+  it('a negative index (no HEAD) is never offscreen', () => {
+    expect(isRowOffscreen(-1, 30, 0, 600)).toBe(false);
+  });
+});

webview-ui/src/lib/graph-navigation.ts

@@ -143,3 +143,22 @@ export function computeJumpTarget(
   const trimmed = pushed.length > maxPath ? pushed.slice(pushed.length - maxPath) : pushed;
   return { target, path: trimmed };
 }
+
+/**
+ * True when the row at `rowIndex` is entirely outside the visible viewport
+ * (fully above the top or fully below the bottom). A row that is even partially
+ * visible counts as on-screen. Uses the real viewport - not the render buffer -
+ * so it reflects what the user can actually see. A negative `rowIndex` (e.g. no
+ * HEAD in the list) is treated as on-screen so callers don't emphasize a no-op.
+ */
+export function isRowOffscreen(
+  rowIndex: number,
+  rowHeight: number,
+  scrollTop: number,
+  viewportHeight: number,
+): boolean {
+  if (rowIndex < 0) return false;
+  const top = rowIndex * rowHeight;
+  const bottom = top + rowHeight;
+  return bottom <= scrollTop || top >= scrollTop + viewportHeight;
+}

webview-ui/src/lib/i18n/en.ts

@@ -275,6 +275,7 @@ export const en: Record<string, string> = {
   'search.noResults': 'No results',
   'search.prev': 'Previous match (Shift+Enter)',
   'search.next': 'Next match (Enter)',
+  'search.jumpToHead': 'Jump to HEAD',
   'search.filters': 'Filters',
   'search.authorFilter': 'Author filter',
   'search.sourceFilter': 'Source',

webview-ui/src/lib/i18n/ko.ts

@@ -275,6 +275,7 @@ export const ko: Record<string, string> = {
   'search.noResults': '결과 없음',
   'search.prev': '이전 결과 (Shift+Enter)',
   'search.next': '다음 결과 (Enter)',
+  'search.jumpToHead': 'HEAD로 이동',
   'search.filters': '필터',
   'search.authorFilter': '작성자 필터',
   'search.sourceFilter': '소스',

webview-ui/src/lib/i18n/zh.ts

@@ -275,6 +275,7 @@ export const zh: Record<string, string> = {
   'search.noResults': '无结果',
   'search.prev': '上一个匹配（Shift+Enter）',
   'search.next': '下一个匹配（Enter）',
+  'search.jumpToHead': '跳转到 HEAD',
   'search.filters': '筛选',
   'search.authorFilter': '作者筛选',
   'search.sourceFilter': '来源',

webview-ui/src/lib/stores/__tests__/commits.test.ts

@@ -102,3 +102,17 @@ describe('commitStore lookups', () => {
     expect(map.get('zzz')).toBeUndefined();
   });
 });
+
+describe('commitStore.headHash', () => {
+  it('returns the hash of the commit carrying a head ref', () => {
+    const head = makeCommit('h1');
+    head.refs = [{ type: 'head', name: 'HEAD' }];
+    commitStore.commits = [makeCommit('h0'), head];
+    expect(commitStore.headHash).toBe('h1');
+  });
+
+  it('returns null when no commit carries a head ref', () => {
+    commitStore.commits = [makeCommit('h0'), makeCommit('h1')];
+    expect(commitStore.headHash).toBeNull();
+  });
+});