From 8f6b64addc6b448f0b99525f3f07c28b6fc36ed4 Mon Sep 17 00:00:00 2001
From: Codeon <313085171+codeon89@users.noreply.github.com>
Date: Sun, 30 Aug 2026 14:18:00 -0700
Subject: [PATCH 1/2] enhancement: input debounce for library and browse

---
 CHANGELOG.md                            |   3 +
 src/App.jsx                             |  27 ++--
 src/components/search/SearchBox.jsx     |  14 +-
 src/components/search/SearchSidebar.jsx |  18 ++-
 src/hooks/useDebouncedSearch.js         |  99 ++++++++++++
 tests/search-debounce.test.jsx          | 192 ++++++++++++++++++++++++
 6 files changed, 330 insertions(+), 23 deletions(-)
 create mode 100644 src/hooks/useDebouncedSearch.js
 create mode 100644 tests/search-debounce.test.jsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 85fa4818..3edded58 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,9 @@
 - The version readout in the topnav and sidebar is now a button that opens that version's GitHub release page. The tag it builds matches what the release workflows publish -- `v<version>` for stable and `v<version>-nightly.<run>` for nightly -- so it lands on the real release rather than a 404. (#143)
 - Added a "Download Version" entry to the split-button caret on the game detail page, beside "Manual Install". It opens the same downloads modal the UPDATE button does, listing every build and mirror the thread offers, so a different version can be fetched over one already installed. Previously an installed title with no pending update had no route to that modal at all: the primary button becomes PLAY once a version is installed, and the UPDATE button only renders when an update is flagged. The entry goes straight to the downloads modal rather than through the source picker, and is shown disabled with a reason for titles with no F95zone thread linked.
 
+### Changed
+- Update debounce logic for Browse and Library: Search in Catalog Browse and Library now debounces the text input and waits for a pause before filtering. Previously every keystroke updated `activeFilters.text` and ran `filterGamesWithState` (Library) or scheduled a catalog fetch, causing input lag on large libraries and a wasted local-filter pass even while browsing the server-side catalog. The input still echoes instantly from local state; clear bypasses the delay.
+
 ### Fixed
 - Fixed `hasLocalPreviews` and `hasLocalBanners` missing already-downloaded assets, so a `missingOnly` media refresh re-downloaded images that were already on disk. Both now query `media_assets` and the `previews`/`banners` tables, which is what the delete paths already did.
 - Custom preview uploads now accept images only. The file picker filters to image types, the drop zone rejects anything else with a message, and the main process re-checks the extension before copying -- neither of the first two is a guarantee, and an unrecognised file copied into `data/images` became a preview tile that could never render. URL fetches are restricted to http(s), capped at 64 MB, throttle their progress events, and clean up the partial file if the download fails.
diff --git a/src/App.jsx b/src/App.jsx
index aba0343e..282f5ced 100644
--- a/src/App.jsx
+++ b/src/App.jsx
@@ -149,6 +149,7 @@ const App = () => {
   const [wishlistIdentityKeys, setWishlistIdentityKeys] = useState(new Set())
   const [activeSavedFilterId, setActiveSavedFilterId] = useState('')
   const [savedFilterDeleteStateById, setSavedFilterDeleteStateById] = useState({})
+  const [resetInputSignal, setResetInputSignal] = useState(0)
   // Banner card dimensions for Grid sizing — derived from the same
   // resolved template BannerTemplateProvider already computed once for
   // <GameBanner> (see src/theme/BannerTemplateProvider.jsx), rather than
@@ -1214,6 +1215,7 @@ const App = () => {
     setActiveSavedFilterId('')
     pendingLibraryScrollTopRestoreRef.current = 0
     libraryScrollTopRef.current = 0
+    setResetInputSignal((n) => n + 1)
     if (libraryMode === 'catalog') {
       // "Reset" in Browse mode should mean the whole catalog, not the
       // local library's installed-only default — otherwise resetting
@@ -1889,7 +1891,11 @@ const App = () => {
     }
   }, [filterSidebarMode, selectedGame])
 
-  const catalogResetDebounceRef = useRef(null)
+  // Search input already debounces via useDebouncedSearch (SearchBox/
+  // SearchSidebar) before activeFilters updates, so debouncing again here
+  // would stack an extra delay before the spinner shows. Fetch immediately
+  // once the debounced filters arrive; the paramsKey guard still prevents
+  // the catalogTotal/enter-mode re-runs from wiping correct data.
   useEffect(() => {
     if (libraryMode !== 'catalog' || !browseAvailable) return
     const paramsKey = catalogParamsKey(catalogSearch, catalogQueryFilters)
@@ -1902,18 +1908,8 @@ const App = () => {
       // the "banners flash, spinner, banners reload" sequence this fixes.
       return
     }
-    if (catalogResetDebounceRef.current) clearTimeout(catalogResetDebounceRef.current)
-    catalogResetDebounceRef.current = setTimeout(() => {
-      catalogResetDebounceRef.current = null
-      lastFetchedCatalogParamsKeyRef.current = paramsKey
-      fetchCatalogGames({ reset: true, search: catalogSearch, filters: catalogQueryFilters })
-    }, 300)
-    return () => {
-      if (catalogResetDebounceRef.current) {
-        clearTimeout(catalogResetDebounceRef.current)
-        catalogResetDebounceRef.current = null
-      }
-    }
+    lastFetchedCatalogParamsKeyRef.current = paramsKey
+    fetchCatalogGames({ reset: true, search: catalogSearch, filters: catalogQueryFilters })
   }, [browseAvailable, catalogQueryFilters, catalogSearch, catalogTotal, fetchCatalogGames, libraryMode])
 
   // When the catalog index finishes building, anything already on screen in
@@ -2106,7 +2102,7 @@ const App = () => {
               // layout there is no search box here and Collections is a nav
               // button instead (see TopNav's LEFT_ORDER).
               <div className="flex justify-center w-full">
-                <SearchBox value={activeFilters.text} onSearchChange={handleSearchChange} onToggleSidebar={toggleSearchSidebar} />
+                <SearchBox value={activeFilters.text} onSearchChange={handleSearchChange} onToggleSidebar={toggleSearchSidebar} resetInputSignal={resetInputSignal} />
               </div>
             )}
           </div>
@@ -2244,6 +2240,7 @@ const App = () => {
               savedFilterDeleteStateById={savedFilterDeleteStateById}
               onApplySavedFilter={applySavedFilter}
               onDeleteSavedFilter={deleteSavedFilter}
+              resetInputSignal={resetInputSignal}
               onClose={() => setShowSearchSidebar(false)}
             />
           </div>
@@ -2579,6 +2576,7 @@ const App = () => {
             savedFilterDeleteStateById={savedFilterDeleteStateById}
             onApplySavedFilter={applySavedFilter}
             onDeleteSavedFilter={deleteSavedFilter}
+            resetInputSignal={resetInputSignal}
             onClose={() => setShowSearchSidebar(false)}
           />
         )}
@@ -2601,6 +2599,7 @@ const App = () => {
             savedFilterDeleteStateById={savedFilterDeleteStateById}
             onApplySavedFilter={applySavedFilter}
             onDeleteSavedFilter={deleteSavedFilter}
+            resetInputSignal={resetInputSignal}
             onClose={() => setShowSearchSidebar(false)}
           />
         )}
diff --git a/src/components/search/SearchBox.jsx b/src/components/search/SearchBox.jsx
index ad17d12f..a1c1f301 100644
--- a/src/components/search/SearchBox.jsx
+++ b/src/components/search/SearchBox.jsx
@@ -1,4 +1,8 @@
-export default function SearchBox({ value = "", onSearchChange, onToggleSidebar }) {
+import { useDebouncedSearch } from '../../hooks/useDebouncedSearch.js'
+
+export default function SearchBox({ value = "", onSearchChange, onToggleSidebar, resetInputSignal }) {
+  const { localValue, handleChange, handleClear } = useDebouncedSearch({ value, onSearchChange, resetInputSignal })
+
   const handleInputKeyDown = (event) => {
     event.stopPropagation()
   }
@@ -10,15 +14,15 @@ export default function SearchBox({ value = "", onSearchChange, onToggleSidebar
         <input
           type="text"
           placeholder="Search Atlas"
-          value={value}
-          onChange={(e) => onSearchChange?.(e.target.value)}
+          value={localValue}
+          onChange={(e) => handleChange(e.target.value)}
           onKeyDown={handleInputKeyDown}
           className="bg-transparent outline-none text-text flex-1 px-2 focus:outline-none -webkit-app-region-no-drag"
         />
-        {value && (
+        {localValue && (
           <button
             type="button"
-            onClick={() => onSearchChange?.("")}
+            onClick={handleClear}
             title="Clear search"
             aria-label="Clear search"
             className="w-6 h-6 flex items-center justify-center text-muted hover:text-text focus:outline-none -webkit-app-region-no-drag"
diff --git a/src/components/search/SearchSidebar.jsx b/src/components/search/SearchSidebar.jsx
index 752f04cf..d1faeed8 100644
--- a/src/components/search/SearchSidebar.jsx
+++ b/src/components/search/SearchSidebar.jsx
@@ -1,5 +1,6 @@
 import { useState, useEffect, useMemo } from 'react'
 import { builtInSavedFilters, getDefaultSortDirectionForSort, normalizeFilterState } from '../../hooks/useFilters.js'
+import { useDebouncedSearch } from '../../hooks/useDebouncedSearch.js'
 import SavedFiltersPanel from './SavedFiltersPanel.jsx'
 import SearchScopePicker from './SearchScopePicker.jsx'
 import { PLAYSTATE_OPTIONS } from '../../utils/playstates.js'
@@ -84,6 +85,7 @@ const SearchSidebar = ({
   savedFilterDeleteStateById = {},
   onApplySavedFilter,
   onDeleteSavedFilter,
+  resetInputSignal,
   // mode: 'overlay' (default, original behavior) floats fixed on top of
   // the library grid without affecting its layout. 'inline' instead
   // renders as a normal block — App.jsx places it as a flex sibling of
@@ -102,6 +104,14 @@ const SearchSidebar = ({
   const [saveBusy, setSaveBusy] = useState(false);
   const [tagError, setTagError] = useState("");
   const [showSavedView, setShowSavedView] = useState(false);
+  // The sidebar's search field is debounced the same way the header
+  // SearchBox is: keystrokes echo instantly from local state while the
+  // parent filter (Library's in-memory filter and Browse's catalog fetch)
+  // waits for a pause. See useDebouncedSearch.js for why the delay lives
+  // before setActiveFilters rather than only before the fetch.
+  const { localValue: debouncedSearchText, handleChange: handleDebouncedSearchChange, handleClear: handleDebouncedSearchClear } =
+    useDebouncedSearch({ value: searchText, onSearchChange, resetInputSignal })
+
   const selectedFilters = normalizeFilterState(activeFilters);
   const [options, setOptions] = useState({
     categories: [],
@@ -455,17 +465,17 @@ const SearchSidebar = ({
             <input
               type="text"
               placeholder="Search Atlas"
-              value={searchText}
+              value={debouncedSearchText}
               onChange={(e) => {
-                onSearchChange?.(e.target.value);
+                handleDebouncedSearchChange(e.target.value);
               }}
               onKeyDown={handleInputKeyDown}
               className="bg-transparent outline-none text-text flex-1 px-3 py-2 focus:outline-none -webkit-app-region-no-drag"
             />
-            {searchText && (
+            {debouncedSearchText && (
               <button
                 type="button"
-                onClick={() => onSearchChange?.("")}
+                onClick={handleDebouncedSearchClear}
                 title="Clear search"
                 aria-label="Clear search"
                 className="w-8 h-8 flex items-center justify-center text-muted hover:text-text focus:outline-none -webkit-app-region-no-drag"
diff --git a/src/hooks/useDebouncedSearch.js b/src/hooks/useDebouncedSearch.js
new file mode 100644
index 00000000..d648b12a
--- /dev/null
+++ b/src/hooks/useDebouncedSearch.js
@@ -0,0 +1,99 @@
+import { useState, useEffect, useRef, useCallback } from 'react'
+
+// Keeps the search input visually instant while the expensive work waits
+// for a pause in typing.
+//
+// Originally SearchBox/SearchSidebar called onSearchChange per keystroke, so
+// Library filtered and Browse fetched per character. Even though Browse had
+// a fetch-side debounce, activeFilters still updated per keystroke, forcing
+// a full App re-render and a wasted local-filter pass via useFilters.js
+// when Browse was showing. Debouncing before setActiveFilters fixes both at
+// the source and the input still echoes from local state.
+export function useDebouncedSearch({ value = '', onSearchChange, delay = 300, resetInputSignal } = {}) {
+  const [localValue, setLocalValue] = useState(value)
+  const timeoutRef = useRef(null)
+  const onSearchChangeRef = useRef(onSearchChange)
+  const lastSentRef = useRef(null)
+  const prevResetInputSignalRef = useRef(resetInputSignal)
+
+  useEffect(() => {
+    onSearchChangeRef.current = onSearchChange
+  }, [onSearchChange])
+
+  // Reset signal bails out the pending debounce even when `value` hasn't
+  // changed (e.g. committed text already '' on fresh load, user types then
+  // hits Reset within the debounce window). The normal [value] effect below
+  // never runs in that case because the prop is still ''. The parent
+  // (App.jsx) increments resetInputSignal on resetFilters so both SearchBox and
+  // SearchSidebar cancel their pending timers and sync to the authoritative
+  // value. Without this, the stale timer fires and re-applies the typed
+  // text after the grid was already reset.
+  useEffect(() => {
+    if (resetInputSignal === undefined) return
+    if (prevResetInputSignalRef.current === resetInputSignal) return
+    prevResetInputSignalRef.current = resetInputSignal
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = null
+    }
+    lastSentRef.current = value
+    setLocalValue((prev) => (prev === value ? prev : value))
+  }, [resetInputSignal, value])
+
+  // Adopt external `value` changes (resetFilters, applySavedFilter, clear
+  // from the other search box) but do not overwrite active typing with the
+  // echo of our own debounce. While a debounce is pending, `value` is still
+  // the previous committed filter; when the timeout fires we send the new
+  // local value and the parent echoes it back. That echo must not clobber a
+  // more recent local edit. Tracking `lastSent` lets us distinguish an echo
+  // (value === lastSent) from a genuine external change.
+  // Deps is [value] only — adding localValue would run the effect on every
+  // keystroke.
+  useEffect(() => {
+    setLocalValue((prev) => {
+      if (value === lastSentRef.current) {
+        // Echo of our own debounced emit. If we have already typed ahead
+        // (timeout pending), keep the ahead value; otherwise sync.
+        if (timeoutRef.current) return prev
+        return prev === value ? prev : value
+      }
+      if (timeoutRef.current) {
+        // External change while typing (e.g. saved filter applied) — cancel
+        // the pending local emit and adopt the authoritative value.
+        clearTimeout(timeoutRef.current)
+        timeoutRef.current = null
+      }
+      return prev === value ? prev : value
+    })
+  }, [value])
+
+  useEffect(() => () => {
+    if (timeoutRef.current) clearTimeout(timeoutRef.current)
+  }, [])
+
+  const schedule = useCallback((next) => {
+    if (timeoutRef.current) clearTimeout(timeoutRef.current)
+    timeoutRef.current = setTimeout(() => {
+      timeoutRef.current = null
+      lastSentRef.current = next
+      onSearchChangeRef.current?.(next)
+    }, delay)
+  }, [delay])
+
+  const handleChange = useCallback((next) => {
+    setLocalValue(next)
+    schedule(next)
+  }, [schedule])
+
+  // Clear is user-intent to see "all" again; bypass the delay so the grid
+  // updates without waiting for the trailing edge.
+  const handleClear = useCallback(() => {
+    if (timeoutRef.current) clearTimeout(timeoutRef.current)
+    timeoutRef.current = null
+    lastSentRef.current = ''
+    setLocalValue('')
+    onSearchChangeRef.current?.('')
+  }, [])
+
+  return { localValue, handleChange, handleClear, setLocalValue }
+}
diff --git a/tests/search-debounce.test.jsx b/tests/search-debounce.test.jsx
new file mode 100644
index 00000000..c9b55fb7
--- /dev/null
+++ b/tests/search-debounce.test.jsx
@@ -0,0 +1,192 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, screen, cleanup, fireEvent, act } from '@testing-library/react'
+import { renderHook } from '@testing-library/react'
+
+import SearchBox from '../src/components/search/SearchBox.jsx'
+import { useDebouncedSearch } from '../src/hooks/useDebouncedSearch.js'
+
+// ── Search debounce ──────────────────────────────────────────────────────────
+//
+// Catalog Browse and Library both share the same text filter. Before this
+// change SearchBox/SearchSidebar called onSearchChange per keystroke, so
+// Library paid a full filterGamesWithState pass and Browse paid a catalog
+// fetch schedule per character — visible as input lag and a flicker when the
+// debounced catalog refetch cleared the grid.
+//
+// The fix keeps the input visually instant (localValue) while the expensive
+// parent update waits 300ms after the last keystroke; clear bypasses the
+// delay.
+
+beforeEach(() => {
+  vi.useFakeTimers({ shouldAdvanceTime: true })
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+})
+
+describe('SearchBox debounces typing', () => {
+  it('does not call onSearchChange per keystroke, only after the delay with the final value', async () => {
+    const onSearchChange = vi.fn()
+    render(<SearchBox value="" onSearchChange={onSearchChange} onToggleSidebar={() => {}} />)
+    const input = screen.getByPlaceholderText('Search Atlas')
+
+    // Simulate fast typing: "ab" with <300ms between keystrokes.
+    fireEvent.change(input, { target: { value: 'a' } })
+    expect(input.value).toBe('a')
+    expect(onSearchChange).not.toHaveBeenCalled()
+
+    fireEvent.change(input, { target: { value: 'ab' } })
+    expect(input.value).toBe('ab')
+    expect(onSearchChange).not.toHaveBeenCalled()
+
+    // Still within debounce window (300ms).
+    await act(async () => { vi.advanceTimersByTime(200) })
+    expect(onSearchChange).not.toHaveBeenCalled()
+
+    // Trailing edge fires once with coalesced value.
+    await act(async () => { vi.advanceTimersByTime(150) })
+    expect(onSearchChange).toHaveBeenCalledTimes(1)
+    expect(onSearchChange).toHaveBeenCalledWith('ab')
+  })
+
+  it('coalesces rapid typing into a single call', async () => {
+    const onSearchChange = vi.fn()
+    render(<SearchBox value="" onSearchChange={onSearchChange} onToggleSidebar={() => {}} />)
+    const input = screen.getByPlaceholderText('Search Atlas')
+
+    fireEvent.change(input, { target: { value: 'm' } })
+    await act(async () => { vi.advanceTimersByTime(50) })
+    fireEvent.change(input, { target: { value: 'mi' } })
+    await act(async () => { vi.advanceTimersByTime(50) })
+    fireEvent.change(input, { target: { value: 'min' } })
+    await act(async () => { vi.advanceTimersByTime(50) })
+    fireEvent.change(input, { target: { value: 'mine' } })
+
+    expect(onSearchChange).not.toHaveBeenCalled()
+    await act(async () => { vi.advanceTimersByTime(300) })
+    expect(onSearchChange).toHaveBeenCalledTimes(1)
+    expect(onSearchChange).toHaveBeenCalledWith('mine')
+  })
+
+  it('clear button bypasses debounce and fires immediately', async () => {
+    const onSearchChange = vi.fn()
+    const { rerender } = render(<SearchBox value="hello" onSearchChange={onSearchChange} onToggleSidebar={() => {}} />)
+    // Need localValue to reflect prop for clear button to show; SearchBox syncs from props.
+    // The initial prop "hello" seeds localValue, so clear button is visible.
+    const clear = screen.getByTitle('Clear search')
+    fireEvent.click(clear)
+    expect(onSearchChange).toHaveBeenCalledTimes(1)
+    expect(onSearchChange).toHaveBeenCalledWith('')
+    // Pending typing must not overwrite the clear.
+    await act(async () => { vi.advanceTimersByTime(400) })
+    expect(onSearchChange).toHaveBeenCalledTimes(1)
+  })
+
+  it('input echoes keystrokes instantly while parent lags', async () => {
+    const onSearchChange = vi.fn()
+    render(<SearchBox value="" onSearchChange={onSearchChange} onToggleSidebar={() => {}} />)
+    const input = screen.getByPlaceholderText('Search Atlas')
+    fireEvent.change(input, { target: { value: 'x' } })
+    expect(input.value).toBe('x')
+    expect(onSearchChange).not.toHaveBeenCalled()
+    await act(async () => { vi.advanceTimersByTime(300) })
+    expect(onSearchChange).toHaveBeenCalledWith('x')
+  })
+})
+
+describe('useDebouncedSearch hook', () => {
+  it('adopts external value and cancels pending debounce (e.g. resetFilters)', async () => {
+    const onSearchChange = vi.fn()
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedSearch({ value, onSearchChange, delay: 300 }),
+      { initialProps: { value: 'initial' } }
+    )
+
+    act(() => { result.current.handleChange('typed') })
+    expect(result.current.localValue).toBe('typed')
+    expect(onSearchChange).not.toHaveBeenCalled()
+
+    // Parent resets (e.g. applySavedFilter, resetFilters) before debounce fires.
+    await act(async () => { rerender({ value: '' }) })
+    expect(result.current.localValue).toBe('')
+
+    await act(async () => { vi.advanceTimersByTime(400) })
+    // Stale "typed" must not fire after the reset adopted ''.
+    expect(onSearchChange).not.toHaveBeenCalled()
+  })
+
+  it('handleClear fires immediately and cancels pending typing', async () => {
+    const onSearchChange = vi.fn()
+    const { result } = renderHook(() => useDebouncedSearch({ value: 'hello', onSearchChange, delay: 300 }))
+    expect(result.current.localValue).toBe('hello')
+
+    act(() => { result.current.handleChange('hello world') })
+    act(() => { result.current.handleClear() })
+    expect(result.current.localValue).toBe('')
+    expect(onSearchChange).toHaveBeenCalledWith('')
+    expect(onSearchChange).toHaveBeenCalledTimes(1)
+
+    await act(async () => { vi.advanceTimersByTime(400) })
+    expect(onSearchChange).toHaveBeenCalledTimes(1)
+  })
+
+  it('unmount cancels pending timer (no call after unmount)', async () => {
+    const onSearchChange = vi.fn()
+    const { result, unmount } = renderHook(() => useDebouncedSearch({ value: '', onSearchChange, delay: 300 }))
+    act(() => { result.current.handleChange('a') })
+    unmount()
+    await act(async () => { vi.advanceTimersByTime(400) })
+    expect(onSearchChange).not.toHaveBeenCalled()
+  })
+
+  it('resetInputSignal cancels pending even when value unchanged (fresh-load reset edge case)', async () => {
+    const onSearchChange = vi.fn()
+    const { result, rerender } = renderHook(
+      ({ value, resetInputSignal }) => useDebouncedSearch({ value, onSearchChange, delay: 300, resetInputSignal }),
+      { initialProps: { value: '', resetInputSignal: 0 } }
+    )
+
+    // User types while committed text is still '' (fresh load).
+    act(() => { result.current.handleChange('typed') })
+    expect(result.current.localValue).toBe('typed')
+    expect(onSearchChange).not.toHaveBeenCalled()
+
+    // Parent hits Reset filters within debounce window: value stays '' but
+    // resetInputSignal bumps. Without the signal the pending timer would survive
+    // and re-apply 'typed' after the grid was already reset.
+    await act(async () => { rerender({ value: '', resetInputSignal: 1 }) })
+    expect(result.current.localValue).toBe('')
+
+    await act(async () => { vi.advanceTimersByTime(400) })
+    expect(onSearchChange).not.toHaveBeenCalled()
+  })
+
+  it('resetInputSignal clears pending even when lastSent is empty string (post-clear reset)', async () => {
+    const onSearchChange = vi.fn()
+    const { result, rerender } = renderHook(
+      ({ value, resetInputSignal }) => useDebouncedSearch({ value, onSearchChange, delay: 300, resetInputSignal }),
+      { initialProps: { value: '', resetInputSignal: 0 } }
+    )
+
+    // Establish lastSent = '' via a clear, then type again.
+    act(() => { result.current.handleChange('first') })
+    act(() => { result.current.handleClear() })
+    expect(result.current.localValue).toBe('')
+    expect(onSearchChange).toHaveBeenCalledWith('')
+    onSearchChange.mockClear()
+
+    act(() => { result.current.handleChange('typed-again') })
+    expect(result.current.localValue).toBe('typed-again')
+
+    // Reset while value is still '' and lastSent is '' — the old echo
+    // heuristic (value === lastSent) would have kept the pending timer.
+    await act(async () => { rerender({ value: '', resetInputSignal: 1 }) })
+    expect(result.current.localValue).toBe('')
+
+    await act(async () => { vi.advanceTimersByTime(400) })
+    expect(onSearchChange).not.toHaveBeenCalled()
+  })
+})

From 07e98075f6b39d477c18ce4975f63517ca8dd214 Mon Sep 17 00:00:00 2001
From: Codeon <313085171+codeon89@users.noreply.github.com>
Date: Tue, 1 Sep 2026 14:12:06 -0700
Subject: [PATCH 2/2] PATCHED: CHANGELOG - #398

---
 CHANGELOG.PATCHED.md | 1 +
 CHANGELOG.md         | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.PATCHED.md b/CHANGELOG.PATCHED.md
index f87e2812..925a91de 100644
--- a/CHANGELOG.PATCHED.md
+++ b/CHANGELOG.PATCHED.md
@@ -2,6 +2,7 @@
 
 ## Fork's Nightly Changes
 *Changes that's already on the fork and waiting to be reviewed for merge into original Atlas*
+- Update debounce logic for Browse and Library: Search in Catalog Browse and Library now debounces the text input and waits for a pause before filtering. Previously every keystroke updated `activeFilters.text` and ran `filterGamesWithState` (Library) or scheduled a catalog fetch, causing input lag on large libraries and a wasted local-filter pass even while browsing the server-side catalog. The input still echoes instantly from local state; clear bypasses the delay.[PR#398](https://github.com/towerwatchman/Atlas/pull/398)
 
 ## Independent Changes
 *Any fork-only changes that is not accepted for merged but valid, or independent changes to make the fork repo releasable (e.g. custom version or preventing updates)*
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 596a441a..f8d5da7d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,7 +15,7 @@
 - Added a "Download Version" entry to the split-button caret on the game detail page, beside "Manual Install". It opens the same downloads modal the UPDATE button does, listing every build and mirror the thread offers, so a different version can be fetched over one already installed. Previously an installed title with no pending update had no route to that modal at all: the primary button becomes PLAY once a version is installed, and the UPDATE button only renders when an update is flagged. The entry goes straight to the downloads modal rather than through the source picker, and is shown disabled with a reason for titles with no F95zone thread linked.
 
 ### Changed
-- Update debounce logic for Browse and Library: Search in Catalog Browse and Library now debounces the text input and waits for a pause before filtering. Previously every keystroke updated `activeFilters.text` and ran `filterGamesWithState` (Library) or scheduled a catalog fetch, causing input lag on large libraries and a wasted local-filter pass even while browsing the server-side catalog. The input still echoes instantly from local state; clear bypasses the delay.
+
 
 ### Fixed
 - Catalog tag filtering now matches Library. Library already did exact-token filtering via `splitListText`/`normalizeTagText`/`includesTag` `src/hooks/useFilters.js`; Catalog used substring `LOWER(col) LIKE '%tag%'`. Fix copies those Library helpers into shared `src/utils/tagTokens.js` ↔ `electron/db/tagTokens.js` and adds a stored `tags_filter` column plus an indexed `catalog_index_tags` table (`catalog_key, tag` + `idx_catalog_index_tags_tag`). Browse now filters via `EXISTS (SELECT 1 FROM catalog_index_tags WHERE tag=?)` hitting the index instead of `LIKE '%,token,%'` with leading wildcard on `tags_filter` (full scan, a few seconds per tag click). `COALESCE`/`ESCAPE`/`REPLACE` remain only for the union fallback path when the index is not ready.