@bojackduy/opencode-telescope 0.1.20 → 0.1.22

package/README.md

@@ -1,9 +1,18 @@
 # opencode-telescope
 
-Fuzzy search across all your OpenCode conversations — grep through session and chat history, find code snippets, and jump to any chat instantly.
+OpenCode TUI plugin for fuzzy-searching local conversation history, session transcripts, and past AI coding chats.
+
+Install the npm package `@bojackduy/opencode-telescope` to grep through OpenCode chat history, find old code snippets, and jump back to any session instantly.
 
 > Inspired by [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim) — a fuzzy finder for your conversation history.
 
+## Links
+
+- Documentation: https://bojackduy.github.io/opencode-telescope/
+- npm: https://www.npmjs.com/package/@bojackduy/opencode-telescope
+- GitHub: https://github.com/bojackduy/opencode-telescope
+- Issues: https://github.com/bojackduy/opencode-telescope/issues
+
 ![Demo](./assets/demo.png)
 
 ## Use cases
@@ -19,9 +28,12 @@ Fuzzy search across all your OpenCode conversations — grep through session and
 - **Live preview** — preview the matched conversation result before opening
 - **Find & jump** — select any result and jump straight to that session
 - **Neovim Telescope-style UX** — familiar `<leader>f` keybind and `/telescope` command
+- **Local-first search** — reads your OpenCode session database without sending chat history to a remote service
 
 ## Installation
 
+Install from npm as `@bojackduy/opencode-telescope`.
+
 Add the plugin to your `tui.json`:
 
 ```jsonc
@@ -88,4 +100,8 @@ Key strings support simple names like `j`, `k`, `down`, `up`, `enter`, `return`,
 
 Reads the OpenCode local SQLite session database in read-only mode, parses conversations into searchable text, and opens the selected session through the existing TUI route.
 
+## Keywords
+
+OpenCode plugin, OpenCode TUI, fuzzy finder, conversation search, chat history search, AI coding session search, LLM history, local session search, Telescope-style picker.
+
 ![Demo animation](./assets/demo.gif)

package/package.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@bojackduy/opencode-telescope",
-  "version": "0.1.20",
-  "description": "Fuzzy search across all OpenCode conversations — grep session and chat history, find code snippets, and jump to any chat instantly",
+  "version": "0.1.22",
+  "description": "OpenCode TUI plugin for fuzzy-searching local conversation history, session transcripts, and past AI coding chats",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Duyyy123/opencode-telescope.git"
+    "url": "git+https://github.com/bojackduy/opencode-telescope.git"
   },
-  "homepage": "https://github.com/Duyyy123/opencode-telescope#readme",
+  "homepage": "https://bojackduy.github.io/opencode-telescope/",
   "bugs": {
-    "url": "https://github.com/Duyyy123/opencode-telescope/issues"
+    "url": "https://github.com/bojackduy/opencode-telescope/issues"
   },
   "keywords": [
     "opencode",
@@ -21,11 +21,15 @@
     "search",
     "session",
     "conversation",
+    "conversation-search",
     "history",
+    "ai-chat-history",
+    "llm-history",
     "fuzzy",
     "fuzzy-finder",
     "grep",
     "finder",
+    "opencode-tui",
     "neovim",
     "chat-history"
   ],

package/telescope.tsx

@@ -53,7 +53,7 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
   const MIN_RECENT_BATCH_SIZE = 15
   const RESULT_OVERSCAN_MULTIPLIER = 2
   const RESULT_BATCH_VIEWPORTS = 4
-  const RESULT_PREFETCH_VIEWPORTS = 3
+  const RESULT_PREFETCH_VIEWPORTS = 5
   const RESULT_CACHE_BEHIND_VIEWPORTS = 6
   const INITIAL_PREVIEW_BEFORE = 20
   const INITIAL_PREVIEW_AFTER = 30
@@ -93,10 +93,26 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
   let resultNavigationStarted = false
   let resultPrefetchTimer: ReturnType<typeof setTimeout> | undefined
   let resultPreviousTimer: ReturnType<typeof setTimeout> | undefined
+  let searchTimer: ReturnType<typeof setTimeout> | undefined
+  let lastFiredQuery = ""
+  const SEARCH_DEBOUNCE_MS = 200
+  type PreviewBeforeIntent = "passive-prefetch" | "explicit-scroll"
+  type PendingPreviewBefore = {
+    id: number
+    previousContentHeight: number
+    previousScrollTop: number
+    requestedAmount: number
+    intent: PreviewBeforeIntent
+    visibleLoad: boolean
+  }
+  let previewBeforeLoadID = 0
   let previewBeforeTimer: ReturnType<typeof setTimeout> | undefined
   let previewAfterTimer: ReturnType<typeof setTimeout> | undefined
-  let pendingPreviewBefore: { previousContentHeight: number; preserveScroll: boolean; visibleLoad: boolean } | undefined
+  let pendingPreviewBefore: PendingPreviewBefore | undefined
   let pendingPreviewAfterVisible = false
+  let previewBeforeAdjusting = false
+  let pendingCoalescedExplicit: { requestedAmount: number } | undefined
+  let pendingPreviewAnchorCorrection: { anchorPartID: string; visualOffset: number; createdAt: number; expiresAt: number } | undefined
   const previewMeasuredHeights = new Map<string, number>()
   const cancelPreviewPrefetch = () => {
     if (previewBeforeTimer) clearTimeout(previewBeforeTimer)
@@ -105,6 +121,9 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     previewAfterTimer = undefined
     pendingPreviewBefore = undefined
     pendingPreviewAfterVisible = false
+    previewBeforeAdjusting = false
+    pendingCoalescedExplicit = undefined
+    pendingPreviewAnchorCorrection = undefined
     setPrefetchingPreviewBefore(false)
     setPrefetchingPreviewAfter(false)
     setLoadingPreviewMore(false)
@@ -151,6 +170,12 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     return { start: base + cachedStart, end: base + cachedEnd, items: cached.slice(cachedStart, cachedEnd) }
   })
 
+  const resultTopSpacerHeight = () =>
+    Math.max(0, resultRenderWindow().start - resultBaseOffset()) * resultRowHeight()
+
+  const resultBottomSpacerHeight = () =>
+    Math.max(0, resultBaseOffset() + results().length - resultRenderWindow().end) * resultRowHeight()
+
   let lastResultRenderWindow = ""
   createEffect(() => {
     const window = resultRenderWindow()
@@ -171,6 +196,51 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     })
   })
 
+  const executeSearch = (q: string, role: SearchRole | undefined, db: string, dir: string) => {
+    lastFiredQuery = q
+    const limit = q ? Math.min(searchBatchSize(), 80) : recentBatchSize()
+    setLoading(true)
+    if (q) setBusy(true)
+    debug.time("query:search")
+    try {
+      debug.log("bootstrap:search:start", { limit, directory: dir, role, query: q || "(all recent)" })
+      const batch = q
+        ? searchSessionMessages(q, { limit, offset: 0, dbPath: db, directory: dir, role })
+        : recentSessionMessages({ limit, offset: 0, dbPath: db, directory: dir, role })
+      debug.log("bootstrap:search:done", { rows: batch.length, limit })
+      solidBatch(() => {
+        setResults(batch)
+        setResultBaseOffset(0)
+        setNextResultOffset(batch.length)
+        setHasMore(batch.length >= limit)
+        setResultPageInfo({ loadedUntil: batch.length, hasMore: batch.length >= limit, pageSize: limit, lastOffset: 0, lastAdded: batch.length })
+        setSelected(0)
+      })
+    } catch (err) {
+      debug.log("bootstrap:search:error", err instanceof Error ? err.message : String(err))
+      solidBatch(() => {
+        setResults([])
+        setResultBaseOffset(0)
+        setNextResultOffset(0)
+        setResultPageInfo({ loadedUntil: 0, hasMore: false, pageSize: limit, lastOffset: 0, lastAdded: 0 })
+      })
+      setError(err instanceof Error ? err.message : String(err))
+    } finally {
+      debug.timeEnd("query:search")
+      setBusy(false)
+      setLoading(false)
+    }
+  }
+
+  const scheduleSearch = (q: string, role: SearchRole | undefined, db: string, dir: string) => {
+    if (searchTimer) clearTimeout(searchTimer)
+    if (q === lastFiredQuery && results().length > 0) return
+    searchTimer = setTimeout(() => {
+      searchTimer = undefined
+      executeSearch(q, role, db, dir)
+    }, q ? SEARCH_DEBOUNCE_MS : 1)
+  }
+
   createEffect(() => {
     const q = query().trim()
     const role = ownerRole()
@@ -189,73 +259,11 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     const db = dbPath()
     const dir = directory
 
-    if (!q) {
-      setLoading(true)
-      const limit = recentBatchSize()
-      const timer = setTimeout(() => {
-        debug.log("bootstrap:recent:start", { limit, directory: dir, role })
-        debug.time("query:recent")
-        try {
-          const batch = recentSessionMessages({ limit, offset: 0, dbPath: db, directory: dir, role })
-          debug.log("bootstrap:recent:done", { rows: batch.length, limit })
-          solidBatch(() => {
-            setResults(batch)
-            setResultBaseOffset(0)
-            setNextResultOffset(batch.length)
-            setHasMore(batch.length >= limit)
-            setResultPageInfo({ loadedUntil: batch.length, hasMore: batch.length >= limit, pageSize: limit, lastOffset: 0, lastAdded: batch.length })
-            setSelected(0)
-          })
-        } catch (err) {
-          debug.log("bootstrap:recent:error", err instanceof Error ? err.message : String(err))
-          solidBatch(() => {
-            setResults([])
-            setResultBaseOffset(0)
-            setNextResultOffset(0)
-            setResultPageInfo({ loadedUntil: 0, hasMore: false, pageSize: limit, lastOffset: 0, lastAdded: 0 })
-          })
-          setError(err instanceof Error ? err.message : String(err))
-        }
-        debug.timeEnd("query:recent")
-        setLoading(false)
-        debug.log("component:interactive")
-      }, 1)
-      onCleanup(() => clearTimeout(timer))
-      return
-    }
-
-    setLoading(true)
-    setBusy(true)
-    const limit = searchBatchSize()
-    const timer = setTimeout(() => {
-      debug.time("query:search")
-      try {
-        debug.log("bootstrap:search:start", { limit, directory: dir, role, query: q })
-        const batch = searchSessionMessages(q, { limit, offset: 0, dbPath: db, directory: dir, role })
-        debug.log("bootstrap:search:done", { rows: batch.length, limit })
-        solidBatch(() => {
-          setResults(batch)
-          setResultBaseOffset(0)
-          setNextResultOffset(batch.length)
-          setHasMore(batch.length >= limit)
-          setResultPageInfo({ loadedUntil: batch.length, hasMore: batch.length >= limit, pageSize: limit, lastOffset: 0, lastAdded: batch.length })
-          setSelected(0)
-        })
-      } catch (err) {
-        solidBatch(() => {
-          setResults([])
-          setResultBaseOffset(0)
-          setNextResultOffset(0)
-          setResultPageInfo({ loadedUntil: 0, hasMore: false, pageSize: limit, lastOffset: 0, lastAdded: 0 })
-        })
-        setError(err instanceof Error ? err.message : String(err))
-      } finally {
-        debug.timeEnd("query:search")
-        setBusy(false)
-        setLoading(false)
-      }
-    }, 180)
-    onCleanup(() => clearTimeout(timer))
+    scheduleSearch(q, role, db, dir)
+    onCleanup(() => {
+      if (searchTimer) clearTimeout(searchTimer)
+      searchTimer = undefined
+    })
   })
 
   const loadMoreResults = (advance = false) => {
@@ -446,6 +454,31 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     onCleanup(() => clearTimeout(timer))
   })
 
+  createEffect(() => {
+    if (!resultNavigationStarted || !hasMore()) return
+    const interval = setInterval(() => {
+      if (!hasMore() || loadingMore() || loadingPreviousResults() || prefetchingResults() || busy() || loading()) return
+      const scroll = resultScroll
+      if (!scroll) return
+      const children = scroll.getChildren()
+      if (!children || children.length === 0) return
+      const lastChild = children[children.length - 1] as { y: number; height: number }
+      const contentHeight = lastChild.y + lastChild.height
+      const scrollThreshold = Math.max(2, Math.floor(scroll.height * RESULT_PREFETCH_VIEWPORTS))
+      if (scroll.scrollTop + scroll.height >= contentHeight - scrollThreshold) {
+        debug.log("results:scroll-prefetch", {
+          scrollTop: scroll.scrollTop,
+          height: scroll.height,
+          contentHeight,
+          scrollThreshold,
+          rowsAhead: resultPrefetchState().rowsAhead,
+        })
+        scheduleResultPrefetch(false)
+      }
+    }, 200)
+    onCleanup(() => clearInterval(interval))
+  })
+
   const estimatePreviewPartHeight = (part: ConversationPreviewPart) => {
     if (part.type === "tool") {
       if (!part.target) return 2
@@ -459,15 +492,31 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
 
   const previewPartHeight = (part: ConversationPreviewPart) => previewMeasuredHeights.get(part.id) ?? estimatePreviewPartHeight(part)
 
-  const previewVirtualLayout = createMemo(() => {
-    previewHeightVersion()
+  const buildPreviewLayout = (parts: ConversationPreviewPart[]) => {
     let offset = 0
-    return previewParts().map((part) => {
+    return parts.map((part) => {
       const height = previewPartHeight(part)
       const row = { part, top: offset, bottom: offset + height, height }
       offset += height
       return row
     })
+  }
+
+  const previewWindowForLayout = (layout: ReturnType<typeof buildPreviewLayout>, scrollTop: number, viewportHeight: number) => {
+    if (layout.length === 0) return { start: 0, end: 0 }
+    const overscan = Math.max(viewportHeight * 2, 40)
+    const from = Math.max(0, scrollTop - overscan)
+    const to = scrollTop + viewportHeight + overscan
+    const foundStart = layout.findIndex((row) => row.bottom >= from)
+    const start = foundStart === -1 ? Math.max(0, layout.length - 1) : Math.max(0, foundStart)
+    const foundEnd = layout.findIndex((row) => row.top > to)
+    const end = foundEnd === -1 ? layout.length : foundEnd
+    return { start, end: Math.min(layout.length, Math.max(start + 1, end)) }
+  }
+
+  const previewVirtualLayout = createMemo(() => {
+    previewHeightVersion()
+    return buildPreviewLayout(previewParts())
   })
 
   const previewContentHeight = () => previewVirtualLayout().at(-1)?.bottom ?? 0
@@ -486,14 +535,7 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
       return
     }
 
-    const overscan = Math.max(scroll.height * 2, 40)
-    const from = Math.max(0, scroll.scrollTop - overscan)
-    const to = scroll.scrollTop + scroll.height + overscan
-    const foundStart = layout.findIndex((row) => row.bottom >= from)
-    const start = foundStart === -1 ? Math.max(0, layout.length - 1) : Math.max(0, foundStart)
-    const foundEnd = layout.findIndex((row) => row.top > to)
-    const end = foundEnd === -1 ? layout.length : foundEnd
-    const next = { start, end: Math.min(layout.length, Math.max(start + 1, end)) }
+    const next = previewWindowForLayout(layout, scroll.scrollTop, scroll.height)
     const current = previewWindow()
     if (current.start !== next.start || current.end !== next.end) setPreviewWindow(next)
   }
@@ -558,6 +600,29 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
         totalMeasured: previewMeasuredHeights.size,
         window: previewWindow(),
       })
+      const anchorCorrection = pendingPreviewAnchorCorrection
+      if (anchorCorrection && scroll) {
+        const now = Date.now()
+        const shouldCorrect = now <= anchorCorrection.expiresAt && lastPreviewScrollKeyMs <= anchorCorrection.createdAt
+        if (shouldCorrect) {
+          const nextLayout = buildPreviewLayout(previewParts())
+          const anchor = nextLayout.find((row) => row.part.id === anchorCorrection.anchorPartID)
+          if (anchor) {
+            const correctedScrollTop = Math.max(0, anchor.top + anchorCorrection.visualOffset)
+            const correctedWindow = previewWindowForLayout(nextLayout, correctedScrollTop, scroll.height)
+            setPreviewWindow(correctedWindow)
+            scroll.scrollTo(correctedScrollTop)
+            debug.log("preview:measure:anchor-correct", {
+              anchorPartID: anchorCorrection.anchorPartID,
+              visualOffset: anchorCorrection.visualOffset,
+              correctedScrollTop,
+              window: correctedWindow,
+            })
+          }
+        } else {
+          pendingPreviewAnchorCorrection = undefined
+        }
+      }
       setPreviewHeightVersion((value) => value + 1)
       setTimeout(updatePreviewWindow, 1)
     }
@@ -576,75 +641,166 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     onCleanup(() => clearTimeout(timer))
   })
 
-  const loadPreviewBefore = (previousContentHeight = previewContentHeight(), preserveScroll = true, visibleLoad = false) => {
+  const loadPreviewBefore = (pending: PendingPreviewBefore) => {
     const item = selectedResult()
     const first = previewParts()[0]
     if (!item || !first || loadingPreviewMore() || prefetchingPreviewBefore()) {
       debug.log("preview:load-before:skip", {
+        loadID: pending.id,
         reason: !item ? "no-item" : !first ? "no-first-part" : loadingPreviewMore() ? "loading-preview-more" : "prefetching-before",
-        previousContentHeight,
-        preserveScroll,
-        visibleLoad,
+        pending,
         state: previewScrollState(),
       })
       return
     }
     const beforeState = previewScrollState()
-    visibleLoad ? setLoadingPreviewMore(true) : setPrefetchingPreviewBefore(true)
+    const beforeLayout = previewVirtualLayout()
+    const scrollTop = previewScroll?.scrollTop ?? pending.previousScrollTop
+    const anchor = beforeLayout.find((row) => row.bottom >= scrollTop) ?? beforeLayout[0]
+    const anchorPartID = anchor?.part.id ?? first.id
+    const offsetInAnchor = anchor ? scrollTop - anchor.top : 0
+    pending.visibleLoad ? setLoadingPreviewMore(true) : setPrefetchingPreviewBefore(true)
     debug.time("preview:load-before")
     try {
       debug.log("preview:load-before:start", {
-        item: item.id,
+        loadID: pending.id,
+        intent: pending.intent,
         cursor: { id: first.id, timeCreated: first.timeCreated },
-        previousContentHeight,
-        preserveScroll,
-        visibleLoad,
+        previousContentHeight: pending.previousContentHeight,
+        previousScrollTop: pending.previousScrollTop,
+        anchorPartID,
+        offsetInAnchor,
+        requestedAmount: pending.requestedAmount,
+        visibleLoad: pending.visibleLoad,
         state: beforeState,
       })
       const page = loadConversationBefore(item, { id: first.id, timeCreated: first.timeCreated }, { limit: PREVIEW_PAGE_SIZE, dbPath: dbPath() })
-      debug.log("preview:load-before", {
-        item: item.id,
+      debug.log("preview:load-before:query-done", {
+        loadID: pending.id,
         added: page.parts.length,
         hasMoreBefore: page.hasMoreBefore,
-        preserveScroll,
-        visibleLoad,
         first: page.parts[0]?.id,
         last: page.parts.at(-1)?.id,
       })
       if (page.parts.length > 0) {
-        setPreviewParts((prev) => [...page.parts, ...prev])
-        if (preserveScroll) {
-          setTimeout(() => {
-            const beforeAdjust = previewScrollState()
-            const delta = previewContentHeight() - previousContentHeight
-            if (delta > 0) previewScroll?.scrollBy(delta)
-            updatePreviewWindow()
-            debug.log("preview:load-before:adjust", {
-              delta,
-              previousContentHeight,
-              newContentHeight: previewContentHeight(),
-              scrolled: delta > 0,
-              beforeAdjust,
-              afterAdjust: previewScrollState(),
+        const currentParts = previewParts()
+        const nextParts = [...page.parts, ...currentParts]
+        const nextLayout = buildPreviewLayout(nextParts)
+        const anchorPredicted = nextLayout.find((row) => row.part.id === anchorPartID)
+        const anchorPredictedTop = anchorPredicted?.top ?? 0
+        const visualOffset = offsetInAnchor - (pending.intent === "explicit-scroll" ? pending.requestedAmount : 0)
+        const targetScrollTop = pending.intent === "explicit-scroll"
+          ? Math.max(0, anchorPredictedTop + offsetInAnchor - pending.requestedAmount)
+          : anchorPredictedTop + offsetInAnchor
+        const nextWindow = previewWindowForLayout(nextLayout, targetScrollTop, previewScroll?.height ?? Math.max(8, height() - 7))
+
+        solidBatch(() => {
+          setPreviewParts(nextParts)
+          setPreviewWindow(nextWindow)
+        })
+
+        previewScroll?.scrollTo(targetScrollTop)
+        const anchorCorrectionCreatedAt = Date.now()
+        pendingPreviewAnchorCorrection = {
+          anchorPartID,
+          visualOffset,
+          createdAt: anchorCorrectionCreatedAt,
+          expiresAt: anchorCorrectionCreatedAt + 300,
+        }
+
+        debug.log("preview:load-before:commit", {
+          loadID: pending.id,
+          anchorPartID,
+          anchorPredictedTop,
+          offsetInAnchor,
+          visualOffset,
+          targetScrollTop,
+          window: nextWindow,
+          intent: pending.intent,
+          newParts: page.parts.length,
+          totalParts: nextParts.length,
+        })
+
+        previewBeforeAdjusting = true
+        setTimeout(() => {
+          const newLayout = previewVirtualLayout()
+          const anchorNew = newLayout.find(e => e.part.id === anchorPartID)
+          const actualAnchorTop = anchorNew?.top ?? anchorPredictedTop
+          const drift = actualAnchorTop - anchorPredictedTop
+
+          if (Math.abs(drift) >= 1 && previewScroll) {
+            const correctedScrollTop = targetScrollTop + drift
+            const correctedWindow = previewWindowForLayout(newLayout, correctedScrollTop, previewScroll.height)
+            setPreviewWindow(correctedWindow)
+            previewScroll.scrollTo(correctedScrollTop)
+            debug.log("preview:load-before:drift-correct", {
+              loadID: pending.id,
+              drift,
+              anchorPredictedTop,
+              actualAnchorTop,
+              correctedScrollTop,
+              window: correctedWindow,
             })
-          }, 1)
-        } else {
-          setTimeout(() => {
+          } else {
             updatePreviewWindow()
-            debug.log("preview:load-before:no-adjust", {
-              previousContentHeight,
-              newContentHeight: previewContentHeight(),
-              state: previewScrollState(),
-            })
-          }, 1)
-        }
+          }
+
+          previewBeforeAdjusting = false
+
+          const coalesced = pendingCoalescedExplicit
+          if (coalesced) {
+            pendingCoalescedExplicit = undefined
+            const scroll = previewScroll
+            if (scroll) {
+              debug.log("preview:before:coalesce-replay", {
+                requestedAmount: coalesced.requestedAmount,
+                state: previewScrollState(),
+              })
+              schedulePreviewBefore({
+                intent: "explicit-scroll",
+                visibleLoad: true,
+                requestedAmount: coalesced.requestedAmount,
+                previousScrollTop: scroll.scrollTop,
+              })
+            }
+          }
+
+          if (pending.intent === "passive-prefetch") {
+            const matchItem = selectedResult()
+            const scroll = previewScroll
+            if (matchItem && scroll) {
+              const layout = previewVirtualLayout()
+              const matchRow = layout.find((r) => r.part.id === matchItem.id)
+              if (matchRow) {
+                const viewportHeight = scroll.height
+                const desiredScrollTop = Math.max(0, matchRow.top - Math.floor(viewportHeight / 3))
+                const msSinceManual = Date.now() - lastPreviewScrollKeyMs
+                if (Math.abs(scroll.scrollTop - desiredScrollTop) >= 2 && msSinceManual > 700) {
+                  const correctedWindow = previewWindowForLayout(layout, desiredScrollTop, viewportHeight)
+                  setPreviewWindow(correctedWindow)
+                  scroll.scrollTo(desiredScrollTop)
+                  debug.log("preview:load-before:recenter", {
+                    matchPartID: matchItem.id,
+                    matchTop: matchRow.top,
+                    scrollTop: scroll.scrollTop,
+                    desiredScrollTop,
+                    viewportHeight,
+                    window: correctedWindow,
+                  })
+                }
+              }
+            }
+          }
+        }, 1)
       }
       setHasMorePreviewBefore(page.hasMoreBefore)
     } catch (err) {
       debug.log("preview:load-before:error", err instanceof Error ? err.message : String(err))
+      previewBeforeAdjusting = false
     } finally {
       debug.timeEnd("preview:load-before")
-      visibleLoad ? setLoadingPreviewMore(false) : setPrefetchingPreviewBefore(false)
+      lastBeforeLoadMs = Date.now()
+      pending.visibleLoad ? setLoadingPreviewMore(false) : setPrefetchingPreviewBefore(false)
     }
   }
 
@@ -690,46 +846,104 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     }
   }
 
-  const schedulePreviewBefore = (previousContentHeight = previewContentHeight(), preserveScroll = true, visibleLoad = false) => {
+  const schedulePreviewBefore = (opts: {
+    intent: PreviewBeforeIntent
+    visibleLoad?: boolean
+    previousContentHeight?: number
+    requestedAmount?: number
+    previousScrollTop?: number
+  }) => {
+    const id = ++previewBeforeLoadID
+    const previousContentHeight = opts.previousContentHeight ?? previewContentHeight()
+    const previousScrollTop = opts.previousScrollTop ?? previewScroll?.scrollTop ?? 0
+    const requestedAmount = opts.requestedAmount ?? 0
+    const visibleLoad = opts.visibleLoad ?? false
+    const source = opts.intent === "explicit-scroll" ? "key" : "edge"
     if (!hasMorePreviewBefore() || loadingPreviewMore() || prefetchingPreviewBefore()) {
-      debug.log("preview:prefetch-before:skip", {
-        reason: !hasMorePreviewBefore() ? "no-more-before" : loadingPreviewMore() ? "loading-preview-more" : "prefetching-before",
+      debug.log("preview:before:schedule-skip", {
+        loadID: id,
+        reason: !hasMorePreviewBefore() ? "no-more-before" : loadingPreviewMore() ? "loading" : "prefetching",
+        source,
+        intent: opts.intent,
         previousContentHeight,
-        preserveScroll,
+        previousScrollTop,
+        requestedAmount,
         visibleLoad,
         state: previewScrollState(),
       })
       return
     }
+    if (previewBeforeAdjusting) {
+      if (opts.intent === "explicit-scroll") {
+        pendingCoalescedExplicit = { requestedAmount }
+        debug.log("preview:before:coalesce-explicit", {
+          loadID: id,
+          requestedAmount,
+          state: previewScrollState(),
+        })
+      } else {
+        debug.log("preview:before:schedule-skip", {
+          loadID: id,
+          reason: "adjusting",
+          source,
+          intent: opts.intent,
+          previousContentHeight,
+          previousScrollTop,
+          requestedAmount,
+          visibleLoad,
+          state: previewScrollState(),
+        })
+      }
+      return
+    }
     if (previewBeforeTimer) {
       if (pendingPreviewBefore) {
         const previousPending = { ...pendingPreviewBefore }
-        pendingPreviewBefore.preserveScroll = pendingPreviewBefore.preserveScroll && preserveScroll
         pendingPreviewBefore.visibleLoad = pendingPreviewBefore.visibleLoad || visibleLoad
-        debug.log("preview:prefetch-before:merge", {
+        if (opts.intent === "explicit-scroll" && pendingPreviewBefore.intent === "passive-prefetch") {
+          pendingPreviewBefore.intent = "explicit-scroll"
+          pendingPreviewBefore.requestedAmount = requestedAmount
+          pendingPreviewBefore.previousScrollTop = previousScrollTop
+        }
+        debug.log("preview:before:schedule-merge", {
+          loadID: id,
           previousPending,
           nextPending: pendingPreviewBefore,
-          requested: { previousContentHeight, preserveScroll, visibleLoad },
-          state: previewScrollState(),
+          requested: { source, intent: opts.intent, previousContentHeight, previousScrollTop, requestedAmount, visibleLoad },
         })
       } else {
-        debug.log("preview:prefetch-before:skip", {
+        debug.log("preview:before:schedule-skip", {
+          loadID: id,
           reason: "timer-already-set",
+          source,
+          intent: opts.intent,
           previousContentHeight,
-          preserveScroll,
+          previousScrollTop,
+          requestedAmount,
           visibleLoad,
           state: previewScrollState(),
         })
       }
       return
     }
-    pendingPreviewBefore = { previousContentHeight, preserveScroll, visibleLoad }
-    debug.log("preview:prefetch-before-scheduled", { previousContentHeight, preserveScroll, visibleLoad, state: previewScrollState() })
+    pendingPreviewBefore = { id, previousContentHeight, previousScrollTop, requestedAmount, intent: opts.intent, visibleLoad }
+    debug.log("preview:before:schedule", {
+      loadID: id,
+      source,
+      intent: opts.intent,
+      previousContentHeight,
+      previousScrollTop,
+      requestedAmount,
+      visibleLoad,
+      firstPart: previewParts()[0]?.id,
+      partCount: previewParts().length,
+      state: previewScrollState(),
+    })
     previewBeforeTimer = setTimeout(() => {
       const pending = pendingPreviewBefore
       previewBeforeTimer = undefined
       pendingPreviewBefore = undefined
-      if (pending) loadPreviewBefore(pending.previousContentHeight, pending.preserveScroll, pending.visibleLoad)
+      if (pending) loadPreviewBefore(pending)
     }, 1)
   }
 
@@ -770,7 +984,24 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     debug.log("preview:target-scroll:estimated", { targetID, targetTop: row.top, scrollTop: scroll.scrollTop, nextScrollTop: top, window: previewWindow() })
     scroll.scrollTo(top)
     updatePreviewWindow()
-    setTimeout(() => scrollPreviewToTarget(scroll, targetID), 1)
+    const scrollTopBeforeReal = scroll.scrollTop
+    setTimeout(() => {
+      scrollPreviewToTarget(scroll, targetID)
+      const now = Date.now()
+      const adjustmentMs = lastPreviewScrollKeyMs
+      if (adjustmentMs > 0 && now - adjustmentMs > 300) {
+        const targetTopReal = row.top
+        const expectedScrollTop = Math.max(0, targetTopReal - Math.max(1, Math.floor(scroll.height / 3)))
+        const drift = scroll.scrollTop - expectedScrollTop
+        if (Math.abs(drift) >= 2) {
+          const correctedScrollTop = scroll.scrollTop - drift
+          const correctedWindow = previewWindowForLayout(previewVirtualLayout(), correctedScrollTop, scroll.height)
+          setPreviewWindow(correctedWindow)
+          scroll.scrollTo(correctedScrollTop)
+          debug.log("preview:target-scroll:real-correct", { targetID, drift, scrollTopAfterReal: scroll.scrollTop, correctedScrollTop, window: correctedWindow })
+        }
+      }
+    }, 1)
   }
 
   let lastPreviewItemId = ""
@@ -815,11 +1046,14 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     debug.timeEnd("preview:load")
   })
 
+  let lastBeforeLoadMs = 0
+  let lastPreviewScrollKeyMs = 0
   createEffect(() => {
     const item = selectedResult()
     if (!item) return
     const interval = setInterval(() => {
       if (loadingPreviewMore() || prefetchingPreviewBefore() || prefetchingPreviewAfter()) return
+      if (previewBeforeAdjusting) return
       const scroll = previewScroll
       const children = scroll?.getChildren()
       if (!scroll || !children || children.length === 0) return
@@ -829,26 +1063,28 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
       const nearTop = scroll.scrollTop <= prefetchDistance
       const atBottom = scroll.scrollTop + scroll.height >= totalContentHeight - 1
       const nearBottom = scroll.scrollTop + scroll.height >= totalContentHeight - prefetchDistance
-      if (nearTop || nearBottom) {
-        debug.log("preview:scroll-edge", {
-          y: scroll.y,
-          scrollTop: scroll.scrollTop,
-          height: scroll.height,
-          contentHeight: totalContentHeight,
-          childContentHeight: previewScrollState().childContentHeight,
-          prefetchDistance,
-          atTop,
-          nearTop,
-          atBottom,
-          nearBottom,
-          hasMoreBefore: hasMorePreviewBefore(),
-          hasMoreAfter: hasMorePreviewAfter(),
-          prefetchingBefore: prefetchingPreviewBefore(),
-          prefetchingAfter: prefetchingPreviewAfter(),
-          children: children.length,
-        })
+      const msSinceManualScroll = Date.now() - lastPreviewScrollKeyMs
+      const willLoadBefore = atTop && hasMorePreviewBefore() && (Date.now() - lastBeforeLoadMs) > 100 && msSinceManualScroll > 700
+      debug.log("preview:edge:decision", {
+        scrollTop: scroll.scrollTop,
+        height: scroll.height,
+        contentHeight: totalContentHeight,
+        prefetchDistance,
+        atTop,
+        nearTop,
+        atBottom,
+        nearBottom,
+        hasMoreBefore: hasMorePreviewBefore(),
+        hasMoreAfter: hasMorePreviewAfter(),
+        loadingBefore: loadingPreviewMore(),
+        pendingBefore: Boolean(previewBeforeTimer),
+        willLoadBefore,
+        msSinceLastLoad: Date.now() - lastBeforeLoadMs,
+        msSinceManualScroll,
+      })
+      if (willLoadBefore) {
+        schedulePreviewBefore({ intent: "passive-prefetch", previousContentHeight: totalContentHeight, previousScrollTop: scroll.scrollTop })
       }
-      if (atTop && hasMorePreviewBefore()) schedulePreviewBefore(totalContentHeight, true, false)
       if (nearBottom && hasMorePreviewAfter()) schedulePreviewAfter(atBottom)
     }, 400)
     onCleanup(() => clearInterval(interval))
@@ -883,11 +1119,14 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     }
 
     const beforeState = previewScrollState()
+    lastPreviewScrollKeyMs = Date.now()
     debug.log("preview:scroll-key", { direction, state: beforeState })
 
+    const requestedAmount = previewScrollAmount(scroll)
+
     if (direction < 0 && scroll.scrollTop <= 0 && hasMorePreviewBefore()) {
-      debug.log("preview:scroll-key:load-before", { direction, state: beforeState })
-      schedulePreviewBefore(previewContentHeight(), true, true)
+      debug.log("preview:scroll-key:load-before", { direction, requestedAmount, state: beforeState })
+      schedulePreviewBefore({ intent: "explicit-scroll", visibleLoad: true, requestedAmount, previousScrollTop: scroll.scrollTop })
       return
     }
 
@@ -898,7 +1137,7 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
       return
     }
 
-    const amount = direction * previewScrollAmount(scroll)
+    const amount = direction * requestedAmount
     scroll.scrollBy(amount)
     updatePreviewWindow()
     debug.log("preview:scroll-key:scroll", { direction, amount, before: beforeState, after: previewScrollState() })
@@ -1027,6 +1266,7 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
                   >
                     <Show when={!loading()}>
                       <Show when={results().length > 0} fallback={<EmptyState query={query()} owner={ownerLabel()} theme={theme()} />}>
+                        <box height={resultTopSpacerHeight()} flexShrink={0} />
                         <For each={resultRenderWindow().items}>
                           {(item, index) => {
                             const absoluteIndex = () => resultRenderWindow().start + index()
@@ -1043,6 +1283,7 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
                             )
                           }}
                         </For>
+                        <box height={resultBottomSpacerHeight()} flexShrink={0} />
                         <Show when={loadingMore()}>
                           <SkeletonRow theme={theme()} />
                         </Show>

package/ui/render-target.ts

@@ -31,18 +31,20 @@ export function scrollPreviewToTarget(scroll: ScrollBoxRenderable | undefined, t
     })
     return
   }
-  const delta = target.y - scroll.y - Math.max(1, Math.floor(scroll.height / 3))
+  const contentY = target.y + scroll.scrollTop - scroll.y
+  const desiredScrollTop = Math.max(0, contentY - Math.max(1, Math.floor(scroll.height / 3)))
   debug.log("preview:target-scroll", {
     targetID,
     targetY: target.y,
     scrollY: scroll.y,
     scrollTop: scroll.scrollTop,
+    contentY,
+    desiredScrollTop,
     scrollHeight: scroll.height,
     contentHeight: scroll.scrollHeight,
-    delta,
   })
-  scroll.scrollBy(delta)
-  debug.log("preview:target-scroll:after", { targetID, scrollY: scroll.y, scrollTop: scroll.scrollTop })
+  scroll.scrollTo(desiredScrollTop)
+  debug.log("preview:target-scroll:after", { targetID, scrollY: scroll.y, scrollTop: scroll.scrollTop, desiredScrollTop })
 }
 
 export function jumpToRenderedTarget(root: unknown, targetID: string) {