/navigation-scroll

name: claude-devtools:navigation-scroll
description: Navigation and scroll orchestration — tab navigation, error highlights, search scrolling, auto-scroll coordination, and common bug patterns. Use when working on useTabNavigationController, scroll restore, or navigation requests.

Navigation & Scroll Orchestration

How tab navigation (error highlights, search scrolling, auto-scroll) works end-to-end.

Architecture

Navigation Request Model (Nonce-Based)

// src/renderer/types/tabs.ts
interface TabNavigationRequest {
  id: string;          // crypto.randomUUID() — fresh nonce per click
  kind: 'error' | 'search' | 'autoBottom';
  highlight: 'red' | 'yellow' | 'none';
  payload: ErrorNavigationPayload | SearchNavigationPayload | {};
  source: 'notification' | 'triggerPreview' | 'commandPalette' | 'sessionOpen';
}

// Stored on Tab:
interface Tab {
  pendingNavigation?: TabNavigationRequest;      // Set by enqueue, cleared by consume
  lastConsumedNavigationId?: string;             // Tracks last processed request
}

Store Actions (tabSlice.ts)

| Action | Purpose | |--------|---------| | `enqueueTabNavigation(tabId, request)` | Set `pendingNavigation` on a tab | | `consumeTabNavigation(tabId, requestId)` | Clear `pendingNavigation`, record `lastConsumedNavigationId` |

Navigation Sources

| Source | Slice | Creates | |--------|-------|---------| | Notification click / test trigger | `notificationSlice.navigateToError()` | `ErrorNavigationRequest` (red) | | CommandPalette search result | `tabSlice.navigateToSession()` | `SearchNavigationRequest` (yellow) |

Controller Hook: `useTabNavigationController`

**Location:** `src/renderer/hooks/useTabNavigationController.ts`

Phase state machine:

idle → pending → expanding → scrolling → highlighting → complete → idle

Key behaviors:

• **Active-tab-only:** Ignores `!isActiveTab` to prevent cross-tab races
• **Nonce dedup:** `activeRequestIdRef.current === pendingNavigation.id` prevents reprocessing
• **Failure debounce:** 500ms cooldown after failed navigation (`lastFailureAtRef`)
• **Abort support:** New navigation aborts in-progress one via `AbortController`
• **Highlight-first:** Highlight is set BEFORE scroll (best-effort scroll, guaranteed highlight)

Scroll Precedence (ChatHistory.tsx)

Three scroll systems compete — navigation wins:

| System | Guard | Priority | |--------|-------|----------| | Navigation scroll | Controller's `executeNavigation` | Highest | | Scroll restore (tab switch) | `!shouldDisableAutoScroll` | Medium | | Auto-scroll to bottom | `disabled: shouldDisableAutoScroll` | Lowest |

`shouldDisableAutoScroll` is `true` during ANY navigation phase or when `pendingNavigation` exists.

Key Files

| File | Role | |------|------| | `src/renderer/hooks/useTabNavigationController.ts` | Unified navigation controller | | `src/renderer/hooks/navigation/utils.ts` | Shared helpers (scroll calc, element lookup, visibility) | | `src/renderer/components/chat/ChatHistory.tsx` | Scroll restore + auto-scroll coordination | | `src/renderer/store/slices/tabSlice.ts` | `enqueueTabNavigation`, `consumeTabNavigation`, `navigateToSession` | | `src/renderer/store/slices/notificationSlice.ts` | `navigateToError` | | `src/renderer/store/slices/sessionDetailSlice.ts` | `fetchSessionDetail` (sets `conversationLoading`) | | `src/renderer/types/tabs.ts` | `TabNavigationRequest` types + factory helpers |

Common Bug Patterns

1. Scroll Restore Overrides Navigation

**Symptom:** Scrolls to target, then snaps back to top/previous position.

**Root cause:** The scroll restore effect fires after `consumeTabNavigation` clears `pendingNavigation`. If the guard only checks `!pendingNavigation`, it triggers while navigation highlight is still active.

**Fix pattern:** Guard scroll restore with `!shouldDisableAutoScroll` instead of `!pendingNavigation`. The controller's `shouldDisableAutoScroll` covers the FULL lifecycle (pending → complete), not just while `pendingNavigation` exists.

**Additional:** Save scroll position when `shouldDisableAutoScroll` transitions true→false (navigation completed) to prevent stale `savedScrollTop` from being restored later.

// ChatHistory.tsx — scroll restore effect
useEffect(() => {
  const wasDisabled = prevShouldDisableRef.current;
  prevShouldDisableRef.current = shouldDisableAutoScroll;
  // Navigation just completed — save current position, skip restore
  if (wasDisabled && !shouldDisableAutoScroll && scrollContainerRef.current) {
    saveScrollPosition(scrollContainerRef.current.scrollTop);
    return;
  }
  if (isThisTabActive && savedScrollTop !== undefined && !conversationLoading && !shouldDisableAutoScroll) {
    // ... restore logic
  }
}, [isThisTabActive, savedScrollTop, conversationLoading, shouldDisableAutoScroll, saveScrollPosition]);

2. Redundant `fetchSessionDetail` Unmounts ChatHistory

**Symptom:** Navigation doesn't scroll at all, or session "reloads" unnecessarily.

**Root cause:** `navigateToSession` or `navigateToError` calls `fetchSessionDetail` even when the session is already loaded in an existing tab. This sets `conversationLoading: true`, causing ChatHistory to unmount (show loading spinner) and remount — losing scroll container and controller state.

**Fix pattern:** Only call `fetchSessionDetail` for NEW tabs. For existing tabs, `setActiveTab` already handles the fetch when `sessionChanged` is true.

// tabSlice.ts — navigateToSession
if (existingTab) {
  state.setActiveTab(existingTab.id);
  // NO fetchSessionDetail — setActiveTab handles it
} else {
  state.openTab({ ... });
  void state.fetchSessionDetail(projectId, sessionId); // Only for new tabs
}

3. Highlight Not Showing (Strict Post-Scroll Gates)

**Symptom:** Scrolls to correct location but no red/yellow highlight ring appears.

**Root cause:** `executeErrorNavigation` / `executeSearchNavigation` returns `false` after scroll due