From 280eadd2eb8723bbf58726cbdfd7b9ba83ae8976 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Sat, 5 Sep 2026 23:00:28 -0700
Subject: [PATCH] Add clarifying comments to palette ranking retention logic

- Document why capPaletteSection retains the selected match
- Explain retainedResultId's role in keeping keyboard selection visible
- Clarify secondaryMatches exposes additional match offsets
---
 src/renderer/src/components/cmd-j/palette-section-render-cap.ts | 1 +
 src/renderer/src/components/tab-bar/use-open-tab-search.ts      | 1 +
 src/renderer/src/lib/browser-palette-search.ts                  | 1 +
 3 files changed, 3 insertions(+)

diff --git a/src/renderer/src/components/cmd-j/palette-section-render-cap.ts b/src/renderer/src/components/cmd-j/palette-section-render-cap.ts
index fd46bf3f02b..29dee043a27 100644
--- a/src/renderer/src/components/cmd-j/palette-section-render-cap.ts
+++ b/src/renderer/src/components/cmd-j/palette-section-render-cap.ts
@@ -35,6 +35,7 @@ export function capPaletteSection<T>(
     return { visible: items, overflowCount: 0 }
   }
   const visible = items.slice(0, cap)
+  // Keep the selected match visible after reranking without increasing the DOM row cap.
   let retained: T | undefined
   if (retain) {
     for (let index = cap; index < items.length; index += 1) {
diff --git a/src/renderer/src/components/tab-bar/use-open-tab-search.ts b/src/renderer/src/components/tab-bar/use-open-tab-search.ts
index c1de1d4df96..a1a58d993d5 100644
--- a/src/renderer/src/components/tab-bar/use-open-tab-search.ts
+++ b/src/renderer/src/components/tab-bar/use-open-tab-search.ts
@@ -22,6 +22,7 @@ export type UseOpenTabSearchOptions = {
   enabled: boolean
   query: string
   worktreeId: string
+  /** Keyboard-selected result's `id`; keep it inside the display cap while it still matches. */
   retainedResultId?: string | null
 }
 
diff --git a/src/renderer/src/lib/browser-palette-search.ts b/src/renderer/src/lib/browser-palette-search.ts
index 7b4e143fa0a..dde92d9e881 100644
--- a/src/renderer/src/lib/browser-palette-search.ts
+++ b/src/renderer/src/lib/browser-palette-search.ts
@@ -55,6 +55,7 @@ export type BrowserPaletteSearchResult = {
   /** Raw page URL, so callers can dedupe a row against another list of destinations. */
   url: string
   secondaryText: string
+  /** Matched formatted/raw URLs with highlight offsets into each `text`; exposes hits beyond the displayed URL. */
   secondaryMatches: readonly { text: string; ranges: readonly MatchRange[] }[]
   workspaceLabel: string | null
   repoName: string