@brimveyn/aimux 1.6.1 → 1.6.2

package/src/state/types.ts

@@ -1,4 +1,7 @@
 import type { ModeId } from '@brimveyn/aimux-config'
+import type { ThemedToken } from 'shiki'
+
+import type { FileDiffMetadata } from '../diff-parser'
 
 export type BuiltinAssistantId = 'claude' | 'codex' | 'opencode' | 'terminal'
 
@@ -148,8 +151,11 @@ export interface GitPaneState {
   ratio: number
   diffModeRatio: number
   fileListMode: GitFileListMode
+  treeCompaction: boolean
   path: GitPanePathConfig
   diffCount: GitPaneDiffCountConfig
+  /** Prefetch this many neighbours around the selection. 0 disables prefetch. */
+  prefetchRadius: number
 }
 
 export type GitFileStatus = 'M' | 'A' | 'D' | 'R' | 'C' | 'U' | '?'
@@ -195,10 +201,45 @@ export interface FoldState {
   bottom: number
 }
 
+export interface ParsedDiffEntry {
+  hash: string
+  // Stored as unknown at the state boundary; concrete type is FileDiffMetadata
+  // | null, narrowed at read sites via getParsedFile().
+  file: unknown
+}
+
+export interface HighlightsEntry {
+  hash: string
+  themeId: string
+  // See ParsedDiffEntry note — narrowed via getHighlights().
+  add: unknown
+  del: unknown
+}
+
+export function getParsedFile(entry: ParsedDiffEntry | undefined): FileDiffMetadata | null {
+  if (!entry) return null
+  return entry.file as FileDiffMetadata | null
+}
+
+export function getHighlightsTokens(entry: HighlightsEntry | undefined): {
+  add: ThemedToken[][]
+  del: ThemedToken[][]
+} | null {
+  if (!entry) return null
+  return {
+    add: entry.add as ThemedToken[][],
+    del: entry.del as ThemedToken[][],
+  }
+}
+
 export interface GitModeState {
   selectedEntryKey: string | null
   collapsedFolders: Record<string, true>
   diffs: Record<string, DiffData>
+  /** Parsed diff keyed by fileKey. Invalidated on file change or head offset shift. */
+  parsedFiles: Record<string, ParsedDiffEntry>
+  /** Tokenised highlights keyed by `${fileKey}|${themeId}`. */
+  highlights: Record<string, HighlightsEntry>
   loading: Record<string, boolean>
   pendingDeletePath: string | null
   actionMessage: string | null
@@ -473,7 +514,23 @@ export type GitModeAction =
   | { type: 'git-mode-collapse-selection' }
   | { type: 'git-mode-expand-selection' }
   | { type: 'git-mode-toggle-file-list-mode' }
-  | { type: 'git-mode-set-diff'; key: string; diff: DiffData }
+  | { type: 'git-mode-toggle-tree-compaction' }
+  | { type: 'git-mode-set-diff'; key: string; diff: DiffData; hash: string }
+  | {
+      type: 'git-mode-set-parsed'
+      key: string
+      hash: string
+      file: unknown
+    }
+  | {
+      type: 'git-mode-set-highlights'
+      key: string
+      hash: string
+      themeId: string
+      add: unknown
+      del: unknown
+    }
+  | { type: 'git-mode-invalidate-diffs'; paths: string[] }
   | { type: 'git-mode-set-loading'; key: string; loading: boolean }
   | { type: 'git-mode-set-pending-delete'; path: string | null }
   | { type: 'git-mode-clear-diff-cache'; path: string }

package/src/ui/components/diff-renderer/pierre-diff.tsx

@@ -1,20 +1,18 @@
 import type { ScrollBoxRenderable } from '@opentui/core'
 import type { ThemedToken } from 'shiki'
 
-import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react'
+import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef } from 'react'
 
-import type { FoldState } from '../../../state/types'
 import type { ThemeId } from '../../themes'
 
-import { parsePatchFiles } from '../../../diff-parser'
 import { useAppStore } from '../../../state/app-store'
 import { dispatchGlobal } from '../../../state/dispatch-ref'
+import { type FoldState } from '../../../state/types'
 import { useTheme } from '../../theme'
 import { buildSplitRows, buildUnifiedRows, firstChangeRowOffset, gutterWidth } from './build-rows'
-import { filetypeFromPath } from './filetype'
-import { tokenizeSide } from './highlight'
 import { SplitView, type SplitViewHandle } from './split-view'
 import { StackedView, type StackedViewHandle } from './stacked-view'
+import { useDiffPreparation } from './use-diff-preparation'
 
 export type DiffView = 'split' | 'stacked'
 
@@ -41,7 +39,6 @@ interface Props {
   view: DiffView
 }
 
-const EMPTY_HIGHLIGHTS: DiffHighlights = { add: [], del: [] }
 const EMPTY_FOLDS: Record<string, FoldState> = {}
 
 export const PierreDiff = forwardRef<PierreDiffHandle, Props>(function PierreDiff(
@@ -49,12 +46,9 @@ export const PierreDiff = forwardRef<PierreDiffHandle, Props>(function PierreDif
   ref
 ) {
   const theme = useTheme()
-  const file = useMemo(() => {
-    const patches = parsePatchFiles(diff)
-    return patches[0]?.files[0]
-  }, [diff])
-
-  const filetype = useMemo(() => filetypeFromPath(path), [path])
+  const preparation = useDiffPreparation(cacheKey, diff, path, themeId)
+  const file = preparation.file ?? undefined
+  const highlights: DiffHighlights = preparation.highlights
 
   const terminalCols = useAppStore((s) => s.layout.terminalCols)
   const sidebarWidth = useAppStore((s) => s.sidebar.width)
@@ -78,24 +72,6 @@ export const PierreDiff = forwardRef<PierreDiffHandle, Props>(function PierreDif
     [cacheKey]
   )
 
-  const [highlights, setHighlights] = useState<DiffHighlights>(EMPTY_HIGHLIGHTS)
-
-  useEffect(() => {
-    setHighlights(EMPTY_HIGHLIGHTS)
-    if (!file || !filetype) return
-    let cancelled = false
-    void Promise.all([
-      tokenizeSide(file.additionLines, filetype, themeId),
-      tokenizeSide(file.deletionLines, filetype, themeId),
-    ]).then(([add, del]) => {
-      if (cancelled) return
-      setHighlights({ add, del })
-    })
-    return () => {
-      cancelled = true
-    }
-  }, [file, filetype, themeId])
-
   const splitRef = useRef<SplitViewHandle | null>(null)
   const stackedRef = useRef<StackedViewHandle | null>(null)
 
@@ -141,7 +117,9 @@ export const PierreDiff = forwardRef<PierreDiffHandle, Props>(function PierreDif
   if (!file) {
     return (
       <box flexGrow={1} padding={1}>
-        <text fg={theme.colors['descriptionForeground']}>(could not parse diff)</text>
+        <text fg={theme.colors['descriptionForeground']}>
+          {preparation.preparing ? 'Preparing diff…' : '(could not parse diff)'}
+        </text>
       </box>
     )
   }

package/src/ui/components/diff-renderer/prepare-diff.ts

@@ -0,0 +1,66 @@
+import type { ThemedToken } from 'shiki'
+
+import { type FileDiffMetadata, parsePatchFiles } from '../../../diff-parser'
+import { diffHash } from '../../../git/diff-hash'
+import { filetypeFromPath } from './filetype'
+import { tokenizeSide } from './highlight'
+
+export interface PreparedDiff {
+  hash: string
+  file: FileDiffMetadata | null
+  filetype: string | null
+  highlights: { add: ThemedToken[][]; del: ThemedToken[][] }
+}
+
+interface PrepareOptions {
+  signal?: AbortSignal
+  themeId: string
+  /** Skip Shiki for big files to keep prepare under a few tens of ms. */
+  skipHighlightThreshold?: number
+}
+
+const DEFAULT_SKIP_HIGHLIGHT = 2000
+
+function yieldToEventLoop(): Promise<void> {
+  return new Promise((resolve) => {
+    setImmediate(resolve)
+  })
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new DOMException('Aborted', 'AbortError')
+}
+
+// Lifts the hot path (parse → tokenize) off the synchronous render tree. The
+// parser still blocks briefly on very large diffs, but yielding between parse
+// and each tokenize side keeps other UI updates responsive.
+export async function prepareDiff(
+  diff: string,
+  path: string,
+  opts: PrepareOptions
+): Promise<PreparedDiff> {
+  const hash = diffHash(diff)
+  throwIfAborted(opts.signal)
+  const patches = parsePatchFiles(diff)
+  const file = patches[0]?.files[0] ?? null
+  const filetype = file ? (filetypeFromPath(path) ?? null) : null
+
+  const skipThreshold = opts.skipHighlightThreshold ?? DEFAULT_SKIP_HIGHLIGHT
+  const totalLines = file ? file.additionLines.length + file.deletionLines.length : 0
+  const shouldHighlight = !!file && !!filetype && totalLines <= skipThreshold
+
+  if (!shouldHighlight) {
+    return { file, filetype, hash, highlights: { add: [], del: [] } }
+  }
+
+  await yieldToEventLoop()
+  throwIfAborted(opts.signal)
+  const add = await tokenizeSide(file.additionLines, filetype, opts.themeId)
+  throwIfAborted(opts.signal)
+  await yieldToEventLoop()
+  throwIfAborted(opts.signal)
+  const del = await tokenizeSide(file.deletionLines, filetype, opts.themeId)
+  throwIfAborted(opts.signal)
+
+  return { file, filetype, hash, highlights: { add, del } }
+}

package/src/ui/components/diff-renderer/split-view.tsx

@@ -5,7 +5,7 @@ import {
   type ScrollBoxRenderable,
   TextAttributes,
 } from '@opentui/core'
-import { forwardRef, useImperativeHandle, useRef } from 'react'
+import { forwardRef, useImperativeHandle, useMemo, useRef } from 'react'
 
 import type { FileDiffMetadata } from '../../../diff-parser'
 import type { FoldState } from '../../../state/types'
@@ -18,6 +18,11 @@ import { buildSplitRows, gutterWidth, type SplitCell, type SplitRowOrHeader } fr
 import { FoldStrip } from './fold-strip'
 import { tokenToSpan } from './highlight'
 
+// Cap DOM size for extreme diffs. Rows beyond this are hidden behind a banner;
+// users scroll within the visible window. Shiki highlighting is already skipped
+// upstream in prepare-diff for similarly large diffs.
+const LARGE_ROW_CAP = 5000
+
 export interface SplitViewHandle {
   leftScroll: ScrollBoxRenderable | null
   rightScroll: ScrollBoxRenderable | null
@@ -60,8 +65,10 @@ export const SplitView = forwardRef<SplitViewHandle, Props>(function SplitView(
     []
   )
 
-  const rows = buildSplitRows(file, folds, contentWidth)
-  const gw = gutterWidth(file)
+  const rows = useMemo(() => buildSplitRows(file, folds, contentWidth), [file, folds, contentWidth])
+  const gw = useMemo(() => gutterWidth(file), [file])
+  const truncated = rows.length > LARGE_ROW_CAP
+  const displayRows = truncated ? rows.slice(0, LARGE_ROW_CAP) : rows
 
   return (
     <box flexDirection="row" flexGrow={1} overflow="hidden" onMouseScroll={handleScroll}>
@@ -74,7 +81,7 @@ export const SplitView = forwardRef<SplitViewHandle, Props>(function SplitView(
         verticalScrollbarOptions={{ visible: false }}
         onMouseScroll={handleScroll}
       >
-        {rows.map((row, i) => (
+        {displayRows.map((row, i) => (
           <SideRow
             key={i}
             cell={row.type === 'row' ? row.left : null}
@@ -85,6 +92,7 @@ export const SplitView = forwardRef<SplitViewHandle, Props>(function SplitView(
             tokens={highlights.del}
           />
         ))}
+        {truncated ? <TruncationNotice hidden={rows.length - displayRows.length} /> : null}
       </scrollbox>
       <box width={1} backgroundColor={theme.colors['editor.background']} />
       <scrollbox
@@ -95,7 +103,7 @@ export const SplitView = forwardRef<SplitViewHandle, Props>(function SplitView(
         contentOptions={{ flexDirection: 'column', gap: 0 }}
         onMouseScroll={handleScroll}
       >
-        {rows.map((row, i) => (
+        {displayRows.map((row, i) => (
           <SideRow
             key={i}
             cell={row.type === 'row' ? row.right : null}
@@ -106,11 +114,28 @@ export const SplitView = forwardRef<SplitViewHandle, Props>(function SplitView(
             tokens={highlights.add}
           />
         ))}
+        {truncated ? <TruncationNotice hidden={rows.length - displayRows.length} /> : null}
       </scrollbox>
     </box>
   )
 })
 
+function TruncationNotice({ hidden }: { hidden: number }) {
+  const theme = useTheme()
+  return (
+    <box
+      flexDirection="row"
+      backgroundColor={theme.colors['sideBarSectionHeader.background']}
+      paddingLeft={1}
+      paddingRight={1}
+    >
+      <text fg={theme.colors['editorWarning.foreground']}>
+        …diff truncated — {hidden} more rows hidden
+      </text>
+    </box>
+  )
+}
+
 function SideRow({
   cell,
   foldDispatch,

package/src/ui/components/diff-renderer/stacked-view.tsx

@@ -5,7 +5,7 @@ import {
   type ScrollBoxRenderable,
   TextAttributes,
 } from '@opentui/core'
-import { forwardRef, useImperativeHandle, useRef } from 'react'
+import { forwardRef, useImperativeHandle, useMemo, useRef } from 'react'
 
 import type { FileDiffMetadata } from '../../../diff-parser'
 import type { FoldState } from '../../../state/types'
@@ -18,6 +18,9 @@ import { buildUnifiedRows, gutterWidth, type UnifiedRowOrHeader } from './build-
 import { FoldStrip } from './fold-strip'
 import { tokenToSpan } from './highlight'
 
+// Same cap as split-view — keeps the React child count bounded.
+const LARGE_ROW_CAP = 5000
+
 export interface StackedViewHandle {
   scroll: ScrollBoxRenderable | null
 }
@@ -54,8 +57,13 @@ export const StackedView = forwardRef<StackedViewHandle, Props>(function Stacked
     []
   )
 
-  const rows = buildUnifiedRows(file, folds, contentWidth)
-  const gw = gutterWidth(file)
+  const rows = useMemo(
+    () => buildUnifiedRows(file, folds, contentWidth),
+    [file, folds, contentWidth]
+  )
+  const gw = useMemo(() => gutterWidth(file), [file])
+  const truncated = rows.length > LARGE_ROW_CAP
+  const displayRows = truncated ? rows.slice(0, LARGE_ROW_CAP) : rows
 
   return (
     <scrollbox
@@ -66,7 +74,7 @@ export const StackedView = forwardRef<StackedViewHandle, Props>(function Stacked
       contentOptions={{ flexDirection: 'column', gap: 0 }}
       onMouseScroll={handleScroll}
     >
-      {rows.map((row, i) => (
+      {displayRows.map((row, i) => (
         <UnifiedRowRender
           key={i}
           foldDispatch={foldDispatch}
@@ -75,10 +83,27 @@ export const StackedView = forwardRef<StackedViewHandle, Props>(function Stacked
           row={row}
         />
       ))}
+      {truncated ? <TruncationNotice hidden={rows.length - displayRows.length} /> : null}
     </scrollbox>
   )
 })
 
+function TruncationNotice({ hidden }: { hidden: number }) {
+  const theme = useTheme()
+  return (
+    <box
+      flexDirection="row"
+      backgroundColor={theme.colors['sideBarSectionHeader.background']}
+      paddingLeft={1}
+      paddingRight={1}
+    >
+      <text fg={theme.colors['editorWarning.foreground']}>
+        …diff truncated — {hidden} more rows hidden
+      </text>
+    </box>
+  )
+}
+
 function UnifiedRowRender({
   foldDispatch,
   gw,

package/src/ui/components/diff-renderer/use-diff-prefetch.ts

@@ -0,0 +1,191 @@
+import { useEffect, useRef } from 'react'
+
+import type { GitFileEntry } from '../../../state/types'
+
+import { diffHash } from '../../../git/diff-hash'
+import { fetchDiff } from '../../../git/git-diff'
+import { useAppStore } from '../../../state/app-store'
+import { dispatchGlobal } from '../../../state/dispatch-ref'
+import { buildGitTreeRows } from '../../../state/git-tree'
+import { prepareDiff } from './prepare-diff'
+
+interface PrefetchOptions {
+  projectPath: string | undefined
+  themeId: string
+  headOffset: number
+  enabled: boolean
+}
+
+const MAX_CONCURRENCY = 3
+
+interface Task {
+  key: string
+  file: GitFileEntry
+  distance: number
+  controller: AbortController
+}
+
+class PrefetchQueue {
+  private inflight = new Map<string, AbortController>()
+  private queue: Task[] = []
+  private running = 0
+
+  constructor(
+    private readonly execute: (task: Task) => Promise<void>,
+    private readonly maxConcurrency: number
+  ) {}
+
+  schedule(tasks: Task[]): void {
+    const keepKeys = new Set(tasks.map((t) => t.key))
+    // Cancel inflight + queued tasks that no longer sit inside the prefetch window.
+    for (const [key, controller] of this.inflight) {
+      if (!keepKeys.has(key)) {
+        controller.abort()
+        this.inflight.delete(key)
+      }
+    }
+    this.queue = this.queue.filter((t) => keepKeys.has(t.key))
+    for (const task of tasks) {
+      if (this.inflight.has(task.key)) continue
+      if (this.queue.some((t) => t.key === task.key)) continue
+      this.queue.push(task)
+    }
+    this.queue.sort((a, b) => a.distance - b.distance)
+    this.pump()
+  }
+
+  cancelAll(): void {
+    for (const [, controller] of this.inflight) controller.abort()
+    this.inflight.clear()
+    this.queue = []
+  }
+
+  private pump(): void {
+    while (this.running < this.maxConcurrency && this.queue.length > 0) {
+      const task = this.queue.shift()
+      if (!task) break
+      this.inflight.set(task.key, task.controller)
+      this.running += 1
+      void this.execute(task).finally(() => {
+        this.inflight.delete(task.key)
+        this.running -= 1
+        this.pump()
+      })
+    }
+  }
+}
+
+// Prefetches ±radius neighbours around the selected file so j/k-style navigation
+// hits the cache. Runs through the full pipeline (git → parse → tokenize) off
+// the main thread, bounded to MAX_CONCURRENCY to stay below a crowd of git
+// subprocesses. Cancels tasks that leave the window on each selection change.
+export function useDiffPrefetch(
+  selectedEntryKey: string | null,
+  radius: number,
+  opts: PrefetchOptions
+): void {
+  const files = useAppStore((s) => s.gitPanel.files)
+  const diffs = useAppStore((s) => s.gitMode.diffs)
+  const parsed = useAppStore((s) => s.gitMode.parsedFiles)
+  const loading = useAppStore((s) => s.gitMode.loading)
+  const collapsedFolders = useAppStore((s) => s.gitMode.collapsedFolders)
+  const fileListMode = useAppStore((s) => s.gitPane.fileListMode)
+  const treeCompaction = useAppStore((s) => s.gitPane.treeCompaction)
+
+  const queueRef = useRef<PrefetchQueue | null>(null)
+
+  const { enabled, headOffset, projectPath, themeId } = opts
+  const runTaskRef = useRef<(task: Task) => Promise<void>>(async () => {})
+
+  // Keep a ref to the execute function so the queue keeps the latest closure
+  // without needing to recreate the queue itself.
+  runTaskRef.current = async (task: Task) => {
+    if (!projectPath) return
+    try {
+      const diff = await fetchDiff(projectPath, task.file, headOffset)
+      if (task.controller.signal.aborted) return
+      const hash = diffHash(diff.rawDiff)
+      dispatchGlobal({ diff, hash, key: task.key, type: 'git-mode-set-diff' })
+      const prep = await prepareDiff(diff.rawDiff, task.file.path, {
+        signal: task.controller.signal,
+        themeId,
+      })
+      if (task.controller.signal.aborted) return
+      dispatchGlobal({
+        file: prep.file,
+        hash: prep.hash,
+        key: task.key,
+        type: 'git-mode-set-parsed',
+      })
+      dispatchGlobal({
+        add: prep.highlights.add,
+        del: prep.highlights.del,
+        hash: prep.hash,
+        key: task.key,
+        themeId,
+        type: 'git-mode-set-highlights',
+      })
+    } catch {
+      // Prefetch errors are non-fatal; the foreground fetch will retry on focus.
+    }
+  }
+
+  if (!queueRef.current) {
+    queueRef.current = new PrefetchQueue((task) => runTaskRef.current(task), MAX_CONCURRENCY)
+  }
+
+  useEffect(() => {
+    const queue = queueRef.current
+    if (!queue) return
+    if (!enabled || radius <= 0 || !projectPath || !selectedEntryKey) {
+      queue.cancelAll()
+      return
+    }
+    const { visibleRows } = buildGitTreeRows(files, collapsedFolders, fileListMode, treeCompaction)
+    const fileRows = visibleRows.filter((r) => r.kind === 'file')
+    const selectedIdx = fileRows.findIndex((r) => r.key === selectedEntryKey)
+    if (selectedIdx < 0) {
+      queue.cancelAll()
+      return
+    }
+    const start = Math.max(0, selectedIdx - radius)
+    const end = Math.min(fileRows.length, selectedIdx + radius + 1)
+    const tasks: Task[] = []
+    for (let i = start; i < end; i++) {
+      if (i === selectedIdx) continue
+      const row = fileRows[i]
+      if (!row || row.kind !== 'file') continue
+      const key = row.key
+      if (diffs[key]) continue
+      if (parsed[key]) continue
+      if (loading[key]) continue
+      tasks.push({
+        controller: new AbortController(),
+        distance: Math.abs(i - selectedIdx),
+        file: row.file,
+        key,
+      })
+    }
+    queue.schedule(tasks)
+  }, [
+    enabled,
+    radius,
+    projectPath,
+    selectedEntryKey,
+    files,
+    collapsedFolders,
+    fileListMode,
+    treeCompaction,
+    diffs,
+    parsed,
+    loading,
+    headOffset,
+    themeId,
+  ])
+
+  useEffect(() => {
+    return () => {
+      queueRef.current?.cancelAll()
+    }
+  }, [])
+}

package/src/ui/components/diff-renderer/use-diff-preparation.ts

@@ -0,0 +1,106 @@
+import type { ThemedToken } from 'shiki'
+
+import { useEffect, useMemo, useState } from 'react'
+
+import type { FileDiffMetadata } from '../../../diff-parser'
+
+import { useAppStore } from '../../../state/app-store'
+import { dispatchGlobal } from '../../../state/dispatch-ref'
+import { getHighlightsTokens, getParsedFile } from '../../../state/types'
+import { prepareDiff } from './prepare-diff'
+
+export interface DiffPreparation {
+  file: FileDiffMetadata | null
+  highlights: { add: ThemedToken[][]; del: ThemedToken[][] }
+  /** True while prepare is running for this cache key + hash. */
+  preparing: boolean
+  /** Available once either cache or prepare has produced a valid hash. */
+  ready: boolean
+}
+
+const EMPTY_HIGHLIGHTS = { add: [] as ThemedToken[][], del: [] as ThemedToken[][] }
+
+// Consults the parsed + highlight caches first, then falls back to an off-thread
+// prepareDiff that dispatches results into the store. Deduplicates in-flight
+// preparation per cacheKey+hash by hashing the diff string once.
+export function useDiffPreparation(
+  cacheKey: string,
+  diff: string,
+  path: string,
+  themeId: string
+): DiffPreparation {
+  const cachedParsed = useAppStore((s) => s.gitMode.parsedFiles[cacheKey])
+  const highlightKey = `${cacheKey}|${themeId}`
+  const cachedHighlights = useAppStore((s) => s.gitMode.highlights[highlightKey])
+
+  const [preparing, setPreparing] = useState(false)
+  const [localFile, setLocalFile] = useState<FileDiffMetadata | null>(null)
+  const [localHighlights, setLocalHighlights] = useState(EMPTY_HIGHLIGHTS)
+  const [localHash, setLocalHash] = useState<string | null>(null)
+
+  const { file, highlights, ready } = useMemo(() => {
+    const parsedFile = cachedParsed ? getParsedFile(cachedParsed) : null
+    const parsedMatches = !!cachedParsed
+    const tokens = cachedHighlights ? getHighlightsTokens(cachedHighlights) : null
+    const hlMatches = !!cachedHighlights && cachedHighlights.hash === cachedParsed?.hash
+
+    if (parsedMatches && hlMatches && tokens) {
+      return { file: parsedFile, highlights: tokens, ready: true }
+    }
+    if (parsedMatches && !hlMatches) {
+      return {
+        file: parsedFile,
+        highlights: tokens ?? EMPTY_HIGHLIGHTS,
+        ready: true,
+      }
+    }
+    if (localHash && localFile) {
+      return { file: localFile, highlights: localHighlights, ready: true }
+    }
+    return { file: null, highlights: EMPTY_HIGHLIGHTS, ready: false }
+  }, [cachedParsed, cachedHighlights, localFile, localHighlights, localHash])
+
+  useEffect(() => {
+    // If caches already cover both parsed and highlights for this theme, bail.
+    const parsedOk = !!cachedParsed
+    const hlOk = !!cachedHighlights && cachedParsed && cachedHighlights.hash === cachedParsed.hash
+    if (parsedOk && hlOk) return
+
+    const controller = new AbortController()
+    setPreparing(true)
+    void prepareDiff(diff, path, { signal: controller.signal, themeId })
+      .then((result) => {
+        if (controller.signal.aborted) return
+        setLocalFile(result.file)
+        setLocalHighlights(result.highlights)
+        setLocalHash(result.hash)
+        dispatchGlobal({
+          file: result.file,
+          hash: result.hash,
+          key: cacheKey,
+          type: 'git-mode-set-parsed',
+        })
+        dispatchGlobal({
+          add: result.highlights.add,
+          del: result.highlights.del,
+          hash: result.hash,
+          key: cacheKey,
+          themeId,
+          type: 'git-mode-set-highlights',
+        })
+      })
+      .catch((err: unknown) => {
+        if (err instanceof Error && err.name === 'AbortError') return
+        // Swallow — the UI falls back to "(could not parse diff)" when file stays null.
+      })
+      .finally(() => {
+        if (!controller.signal.aborted) setPreparing(false)
+      })
+
+    return () => {
+      controller.abort()
+    }
+  }, [cacheKey, diff, path, themeId, cachedParsed, cachedHighlights])
+
+  return { file, highlights, preparing, ready }
+}