feat(search): scoped live search on browse pages (#938)

* feat(artists): scoped live search badge replaces page filter Move Artists browse text search into the header Live Search with a page scope badge (Users icon), field-local undo, and double-click/backspace to clear scope. Block the live-search dropdown while scoped so results only filter the Artists grid; mobile overlay follows the same rules. * fix(artists): plain grid for scoped search fixes broken card layout Route the browse grid through VirtualCardGrid, switch to non-virtual CSS grid when live search filters the catalog, reset scroll on filter changes, and skip content-visibility on plain tiles to avoid blank/black cards. * fix(search): scope badge double-Backspace and single clear control Require two Backspaces on an empty scoped field after prior text input; one Backspace still clears the badge when the field was never filled. Move live-search clear/advanced controls inside the field pill, drop the extra outer clear button, and use type=text to avoid native search clears. * fix(search): drop duplicate outer live-search clear button Keep the native in-field clear on type=search and the original pill layout; remove only the extra × control outside the search border. Reset dropdown state when the query is cleared via the native control. * refactor(search): generic scoped browse query helper, drop dead code Rename artistsBrowseSearchQuery to scopedBrowseSearchQuery with an expectedScope argument; wire Artists via useScopedBrowseSearchQuery. Remove unused liveSearchScoped dropdown helper (scoped mode blocks it). * feat(search): ghost scope badge and single-click badge remove After clearing the artists scope on /artists, show a faded ghost chip to restore page-only search while keeping the global search placeholder. Active badge removes on one click; tooltips and styles updated. * feat(search): scoped live search for All Albums and New Releases Wire albums and newReleases scope badges with debounced album title search (local index title-only FTS + filtered search3). Plain grid, scroll reset, and session query restore on album grid browse pages. * fix(browse): preserve scroll restore after album/artist detail back Only reset in-page scroll when filter resetKey changes, not when isScrollRestorePending clears after session restore. * feat(search): scoped live search for Tracks browse Wire /tracks to header live search with wide title/artist/album FTS, hide hero and discovery rails while search is active, and remove the inline search field from the browse list. * fix(search): clear header query when leaving scoped browse pages Prevent global live search from firing on album/detail routes after a scoped browse query; browse session stashes still restore on back. * fix(tracks): restore scroll after back from detail during scoped search Hold stashed song results across fetchSongPage churn, defer leave-stash teardown past AppShell scroll reset, restore tracks scroll after the list is ready, and save scroll snapshot when opening artist from song context menu. * fix(tracks): hide discovery headings during scoped search Hide the page subtitle and "Browse all tracks" section title when tracks search is active, matching hero/rails chrome behavior. * feat(search): scoped live search for Composers browse Wire /composers to header live search with composers scope badge, session stash, scroll restore, and plain grid/list during text filter. Remove the in-page filter input; add i18n and navigation helpers. * docs: CHANGELOG and credits for scoped browse live search (PR #938)
2026-07-21 23:05:46 +00:00 · 2026-06-01 13:04:36 +03:00
parent ddf10ee01d
commit 4ac373a65b
59 changed files with 2301 additions and 392 deletions
@@ -21,7 +21,7 @@ import {
  logLibrarySearch,
 } from '../utils/library/libraryDevLog';
 import React, { useState, useEffect, useRef, useCallback, useMemo } from 'react';
-import { useNavigate } from 'react-router-dom';
+import { useNavigate, useLocation } from 'react-router-dom';
 import { useNavigateToAlbum } from '../hooks/useNavigateToAlbum';
 import { Search, Disc3, Users, Music, TextSearch, Database, Globe } from 'lucide-react';
 import { usePlayerStore } from '../store/playerStore';
@@ -38,6 +38,19 @@ import { albumCoverRefForSong } from '../cover/ref';
 import { showToast } from '../utils/ui/toast';
 import { useShareSearch } from '../hooks/useShareSearch';
 import ShareSearchResults from './search/ShareSearchResults';
+import {
+  LiveSearchScopeBadge,
+  LiveSearchScopeGhostBadge,
+  createLiveSearchScopeBackspaceState,
+  handleLiveSearchScopeBackspace,
+  handleLiveSearchScopeUndo,
+  isLiveSearchDropdownBlocked,
+  liveSearchScopePlaceholderKey,
+  noteLiveSearchScopeQueryInput,
+  resetLiveSearchScopeBackspaceState,
+  resolveLiveSearchScopeGhost,
+} from './search/liveSearchScopeUi';
+import { useLiveSearchScopeStore } from '../store/liveSearchScopeStore';
 import { resolveIndexKey } from '../utils/server/serverIndexKey';

 type LiveSearchSource = 'local' | 'network';
@@ -98,7 +111,15 @@ function LiveSearchArtistThumb({ artist }: { artist: Pick<SubsonicArtist, 'id' |

 export default function LiveSearch() {
  const { t } = useTranslation();
-  const [query, setQuery] = useState('');
+  const query = useLiveSearchScopeStore(s => s.query);
+  const setQuery = useLiveSearchScopeStore(s => s.setQuery);
+  const scope = useLiveSearchScopeStore(s => s.scope);
+  const setScope = useLiveSearchScopeStore(s => s.setScope);
+  const clearScope = useLiveSearchScopeStore(s => s.clearScope);
+  const undoLiveSearch = useLiveSearchScopeStore(s => s.undo);
+  const scopeBackspaceRef = useRef(createLiveSearchScopeBackspaceState());
+  const location = useLocation();
+  const ghostScope = resolveLiveSearchScopeGhost(location.pathname, scope);
  const [results, setResults] = useState<SearchResults | null>(null);
  const [open, setOpen] = useState(false);
  const [loading, setLoading] = useState(false);
@@ -136,6 +157,14 @@ export default function LiveSearch() {
    void refreshLocalReady();
  }, [refreshLocalReady, musicLibraryFilterVersion]);

+  useEffect(() => {
+    resetLiveSearchScopeBackspaceState(scopeBackspaceRef.current);
+  }, [scope]);
+
+  useEffect(() => {
+    noteLiveSearchScopeQueryInput(scopeBackspaceRef.current, query);
+  }, [query]);
+
  useEffect(() => {
    if (!indexEnabled || !serverId) return;
    let unlistenProgress: (() => void) | undefined;
@@ -161,7 +190,16 @@ export default function LiveSearch() {
    setOpen(false);
    setQuery('');
    setSearchSource(null);
-  }, []);
+  }, [setQuery]);
+
+  const handleQueryChange = useCallback((value: string) => {
+    setQuery(value, { recordUndo: true });
+    if (!value) {
+      setResults(null);
+      setOpen(false);
+      setSearchSource(null);
+    }
+  }, [setQuery]);

  /** Leave live search for a full-page route — cancel in-flight queries and reset overlay state. */
  const leaveLiveSearchFor = useCallback((path: string) => {
@@ -175,11 +213,19 @@ export default function LiveSearch() {
    setIsFocused(false);
    inputRef.current?.blur();
    navigate(path);
-  }, [navigate]);
+  }, [navigate, setQuery]);

  const share = useShareSearch(query, closeSearch);

  useEffect(() => {
+    if (isLiveSearchDropdownBlocked(scope)) {
+      setResults(null);
+      setOpen(false);
+      setSearchSource(null);
+      setLoading(false);
+      return;
+    }
+
    if (share.shareMatch) {
      setResults(null);
      setLoading(false);
@@ -338,9 +384,9 @@ export default function LiveSearch() {
      abort.abort();
      liveSearchGenRef.current += 1;
    };
-  }, [query, share.shareMatch, serverId, indexEnabled, musicLibraryFilterVersion, t]);
+  }, [query, scope, share.shareMatch, serverId, indexEnabled, musicLibraryFilterVersion, t]);

-  const isSearchActive = isFocused || open || query.trim().length > 0;
+  const isSearchActive = isFocused || open || query.trim().length > 0 || scope != null;

  useEffect(() => {
    const root = ref.current;
@@ -485,6 +531,9 @@ export default function LiveSearch() {
  ] : [];

  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (handleLiveSearchScopeUndo(e, undoLiveSearch)) return;
+    if (handleLiveSearchScopeBackspace(e, query, scope, clearScope, scopeBackspaceRef.current)) return;
+    if (isLiveSearchDropdownBlocked(scope)) return;
    if (share.shareMatch) {
      if (e.key === 'Enter') {
        e.preventDefault();
@@ -547,46 +596,50 @@ export default function LiveSearch() {
          requestAnimationFrame(() => inputRef.current?.focus());
        }}
      >
-        {loading ? (
-          <span className="live-search-icon animate-spin" style={{ opacity: 0.6 }}>
-            <div style={{ width: 16, height: 16, border: '2px solid var(--border)', borderTopColor: 'var(--accent)', borderRadius: '50%' }} />
-          </span>
-        ) : (
-          <Search size={16} className="live-search-icon" />
-        )}
-        <input
-          ref={inputRef}
-          id="live-search-input"
-          className="input live-search-field"
-          type="search"
-          placeholder={t('search.placeholder')}
-          value={query}
-          onChange={e => setQuery(e.target.value)}
-          onFocus={() => {
-            setIsFocused(true);
-            if (results) setOpen(true);
-          }}
-          onBlur={() => setIsFocused(false)}
-          onKeyDown={handleKeyDown}
-          aria-autocomplete="list"
-          aria-controls="search-results"
-          aria-expanded={open}
-          autoComplete="off"
-        />
-        {query && (
-          <button
-            className="live-search-clear"
-            onClick={() => {
-              setQuery('');
-              setResults(null);
-              setOpen(false);
-              setSearchSource(null);
+        <div className="live-search-field-cluster">
+          {loading ? (
+            <span className="live-search-leading-icon animate-spin" style={{ opacity: 0.6 }}>
+              <div style={{ width: 16, height: 16, border: '2px solid var(--border)', borderTopColor: 'var(--accent)', borderRadius: '50%' }} />
+            </span>
+          ) : (
+            <Search size={16} className="live-search-leading-icon" aria-hidden />
+          )}
+          {scope && (
+            <LiveSearchScopeBadge
+              scope={scope}
+              className="live-search-scope-badge"
+              clearScope={clearScope}
+            />
+          )}
+          {ghostScope && (
+            <LiveSearchScopeGhostBadge
+              scope={ghostScope}
+              className="live-search-scope-badge live-search-scope-badge--ghost"
+              setScope={setScope}
+            />
+          )}
+          <input
+            ref={inputRef}
+            id="live-search-input"
+            className="input live-search-field"
+            type="search"
+            placeholder={t(liveSearchScopePlaceholderKey(scope))}
+            data-tooltip={scope ? t(liveSearchScopePlaceholderKey(scope)) : undefined}
+            data-tooltip-pos="bottom"
+            value={query}
+            onChange={e => handleQueryChange(e.target.value)}
+            onFocus={() => {
+              setIsFocused(true);
+              if (!isLiveSearchDropdownBlocked(scope) && results) setOpen(true);
            }}
-            aria-label={t('search.clearLabel')}
-          >
-            ×
-          </button>
-        )}
+            onBlur={() => setIsFocused(false)}
+            onKeyDown={handleKeyDown}
+            aria-autocomplete="list"
+            aria-controls="search-results"
+            aria-expanded={open && !isLiveSearchDropdownBlocked(scope)}
+            autoComplete="off"
+          />
+        </div>
        <button
          className="live-search-adv-btn"
          type="button"
@@ -607,7 +660,7 @@ export default function LiveSearch() {
        </button>
      </div>

-      {open && (
+      {open && !isLiveSearchDropdownBlocked(scope) && (
        <div className="live-search-dropdown" id="search-results" role="listbox" ref={dropdownRef}>
          {searchSource && !share.shareMatch && (
            <div
@@ -1,6 +1,7 @@
 import { search } from '../api/subsonicSearch';
 import type { SearchResults, SubsonicArtist } from '../api/subsonicTypes';
 import { songToTrack } from '../utils/playback/songToTrack';
+import { useLiveSearchScopeStore } from '../store/liveSearchScopeStore';
 import React, { useState, useEffect, useRef, useCallback, useMemo } from 'react';
 import { createPortal } from 'react-dom';
 import { useLocation, useNavigate } from 'react-router-dom';
@@ -17,6 +18,18 @@ import { albumCoverRefForSong } from '../cover/ref';
 import { showToast } from '../utils/ui/toast';
 import { useShareSearch } from '../hooks/useShareSearch';
 import ShareSearchResults from './search/ShareSearchResults';
+import {
+  LiveSearchScopeBadge,
+  LiveSearchScopeGhostBadge,
+  createLiveSearchScopeBackspaceState,
+  handleLiveSearchScopeBackspace,
+  handleLiveSearchScopeUndo,
+  isLiveSearchDropdownBlocked,
+  liveSearchScopePlaceholderKey,
+  noteLiveSearchScopeQueryInput,
+  resetLiveSearchScopeBackspaceState,
+  resolveLiveSearchScopeGhost,
+} from './search/liveSearchScopeUi';

 const STORAGE_KEY = 'psysonic_recent_searches';
 const MAX_RECENT = 6;
@@ -31,9 +44,12 @@ function saveRecent(q: string, prev: string[]): string[] {
  return updated;
 }

-function debounce(fn: (q: string) => void, ms: number): (q: string) => void {
+function debounce<A extends unknown[]>(
+  fn: (...args: A) => void,
+  ms: number,
+): (...args: A) => void {
  let timer: ReturnType<typeof setTimeout>;
-  return (q: string) => { clearTimeout(timer); timer = setTimeout(() => fn(q), ms); };
+  return (...args: A) => { clearTimeout(timer); timer = setTimeout(() => fn(...args), ms); };
 }

 /** Mobile search row thumb — larger than desktop live search (32px). */
@@ -93,7 +109,14 @@ export default function MobileSearchOverlay({ onClose }: { onClose: () => void }
  const location = useLocation();
  const enqueue = usePlayerStore(s => s.enqueue);

-  const [query, setQuery] = useState('');
+  const query = useLiveSearchScopeStore(s => s.query);
+  const setQuery = useLiveSearchScopeStore(s => s.setQuery);
+  const scope = useLiveSearchScopeStore(s => s.scope);
+  const setScope = useLiveSearchScopeStore(s => s.setScope);
+  const clearScope = useLiveSearchScopeStore(s => s.clearScope);
+  const undoLiveSearch = useLiveSearchScopeStore(s => s.undo);
+  const scopeBackspaceRef = useRef(createLiveSearchScopeBackspaceState());
+  const ghostScope = resolveLiveSearchScopeGhost(location.pathname, scope);
  const [results, setResults] = useState<SearchResults | null>(null);
  const [loading, setLoading] = useState(false);
  const [recentSearches, setRecentSearches] = useState<string[]>(loadRecent);
@@ -103,6 +126,14 @@ export default function MobileSearchOverlay({ onClose }: { onClose: () => void }

  useEffect(() => { inputRef.current?.focus(); }, []);

+  useEffect(() => {
+    resetLiveSearchScopeBackspaceState(scopeBackspaceRef.current);
+  }, [scope]);
+
+  useEffect(() => {
+    noteLiveSearchScopeQueryInput(scopeBackspaceRef.current, query);
+  }, [query]);
+
  useEffect(() => {
    const prev = document.body.style.overflow;
    document.body.style.overflow = 'hidden';
@@ -113,20 +144,26 @@ export default function MobileSearchOverlay({ onClose }: { onClose: () => void }
    debounce(async (q: string) => {
      if (!q.trim()) { setResults(null); setLoading(false); return; }
      setLoading(true);
-      try { setResults(await search(q)); }
-      finally { setLoading(false); }
+      try {
+        setResults(await search(q));
+      } finally { setLoading(false); }
    }, 300),
-    [musicLibraryFilterVersion]
+    [musicLibraryFilterVersion],
  );

  useEffect(() => {
+    if (isLiveSearchDropdownBlocked(scope)) {
+      setResults(null);
+      setLoading(false);
+      return;
+    }
    if (share.shareMatch) {
      setResults(null);
      setLoading(false);
      return;
    }
    doSearch(query);
-  }, [query, doSearch, share.shareMatch]);
+  }, [query, scope, doSearch, share.shareMatch]);

  const commit = (q: string) => {
    if (q.trim()) setRecentSearches(prev => saveRecent(q, prev));
@@ -146,7 +183,7 @@ export default function MobileSearchOverlay({ onClose }: { onClose: () => void }
    onClose();
  };
  const useRecent = (term: string) => {
-    setQuery(term);
+    setQuery(term, { recordUndo: true });
    inputRef.current?.focus();
  };
  const removeRecent = (term: string, e: React.MouseEvent) => {
@@ -159,27 +196,50 @@ export default function MobileSearchOverlay({ onClose }: { onClose: () => void }
  };

  const hasResults =
-    !!share.shareMatch ||
-    (results && (results.artists.length || results.albums.length || results.songs.length));
-  const showEmpty = !query;
+    !isLiveSearchDropdownBlocked(scope)
+    && (
+      !!share.shareMatch
+      || (results && (results.artists.length || results.albums.length || results.songs.length))
+    );
+  const showEmpty = !query && !scope;

  return createPortal(
    <div className="mobile-search-overlay">
      {/* ── Search bar ── */}
      <div className="mobile-search-bar">
-        <div className="mobile-search-field">
+        <div className={`mobile-search-field${scope ? ' mobile-search-field--scoped' : ''}`}>
          {loading ? (
            <div className="mobile-search-spinner" />
          ) : (
            <Search size={16} className="mobile-search-icon" />
          )}
+          {scope && (
+            <LiveSearchScopeBadge
+              scope={scope}
+              className="mobile-search-scope-badge"
+              clearScope={clearScope}
+            />
+          )}
+          {ghostScope && (
+            <LiveSearchScopeGhostBadge
+              scope={ghostScope}
+              className="mobile-search-scope-badge mobile-search-scope-badge--ghost"
+              setScope={setScope}
+            />
+          )}
          <input
            ref={inputRef}
            className="mobile-search-input"
            type="search"
-            placeholder={t('search.placeholder')}
+            placeholder={t(liveSearchScopePlaceholderKey(scope))}
+            data-tooltip={scope ? t(liveSearchScopePlaceholderKey(scope)) : undefined}
+            data-tooltip-pos="bottom"
            value={query}
-            onChange={e => setQuery(e.target.value)}
+            onChange={e => setQuery(e.target.value, { recordUndo: true })}
+            onKeyDown={(e) => {
+              if (handleLiveSearchScopeUndo(e, undoLiveSearch)) return;
+              if (handleLiveSearchScopeBackspace(e, query, scope, clearScope, scopeBackspaceRef.current)) return;
+            }}
            autoComplete="off"
            autoCorrect="off"
            autoCapitalize="off"
@@ -187,7 +247,7 @@ export default function MobileSearchOverlay({ onClose }: { onClose: () => void }
          {query && (
            <button
              className="mobile-search-clear"
-              onClick={() => { setQuery(''); setResults(null); inputRef.current?.focus(); }}
+              onClick={() => { setQuery('', { recordUndo: true }); setResults(null); inputRef.current?.focus(); }}
              aria-label={t('search.clearLabel')}
            >
              <X size={15} />
@@ -249,7 +309,7 @@ export default function MobileSearchOverlay({ onClose }: { onClose: () => void }
        )}

        {/* ── No results ── */}
-        {!loading && query && !hasResults && (
+        {!loading && query && !hasResults && !isLiveSearchDropdownBlocked(scope) && (
          <div className="mobile-search-noresults">
            {t('search.noResults', { query })}
          </div>
@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useState } from 'react';
 import { useSongBrowseList } from '../hooks/useSongBrowseList';
 import SongBrowseSection from './tracks/SongBrowseSection';

@@ -9,14 +9,13 @@ interface Props {

 /** @deprecated Use SongBrowseSection via SearchBrowsePage (`/tracks`). */
 export default function VirtualSongList({ title, emptyBrowseText }: Props) {
-  const browse = useSongBrowseList({ enabled: true });
+  const [searchQuery] = useState('');
+  const browse = useSongBrowseList({ enabled: true, searchQuery });

  return (
    <SongBrowseSection
      title={title}
      emptyBrowseText={emptyBrowseText}
-      query={browse.query}
-      onQueryChange={browse.setQuery}
      songs={browse.songs}
      hasMore={browse.hasMore}
      loading={browse.loading}
@@ -1,16 +1,12 @@
 import React from 'react';
-import type { Virtualizer } from '@tanstack/react-virtual';
 import { Check } from 'lucide-react';
 import type { TFunction } from 'i18next';
 import type { SubsonicArtist } from '../../api/subsonicTypes';
 import type { PlayerState } from '../../store/playerStoreTypes';
+import { ARTISTS_INPAGE_SCROLL_VIEWPORT_ID } from '../../constants/appScroll';
+import { VirtualCardGrid } from '../VirtualCardGrid';
 import { ArtistCardAvatar } from './ArtistAvatars';

-export type ArtistsGridVirtualization = {
-  virtualizer: Virtualizer<HTMLElement, Element>;
-  scrollMargin: number;
-};
-
 interface TileProps {
  artist: SubsonicArtist;
  selectionMode: boolean;
@@ -68,11 +64,10 @@ function ArtistGridTile({ artist, ...rest }: TileProps) {

 interface Props {
  visible: SubsonicArtist[];
-  /** Column count from layout (capped at six in parent); drives `repeat(n, minmax(0,1fr))`. */
-  gridCols: number;
-  /** ResizeObserver target — same node for plain and virtual grid. */
-  measureRef: React.RefObject<HTMLDivElement | null>;
-  virtualization?: ArtistsGridVirtualization | null;
+  /** Plain CSS grid (canonical card layout) vs row virtualization for large catalogs. */
+  disableVirtualization: boolean;
+  /** Remount grid when browse filters change so virtualizer state cannot go stale. */
+  layoutKey: string;
  selectionMode: boolean;
  selectedIds: Set<string>;
  selectedArtists: SubsonicArtist[];
@@ -84,14 +79,12 @@ interface Props {
 }

 /**
- * Card grid for the artists page. Optional row virtualization (TanStack) for
- * large libraries; column count and `measureRef` always come from the parent.
+ * Card grid for the artists page — same VirtualCardGrid path as Albums/Composers.
 */
 export function ArtistsGridView({
  visible,
-  gridCols,
-  measureRef,
-  virtualization,
+  disableVirtualization,
+  layoutKey,
  selectionMode,
  selectedIds,
  selectedArtists,
@@ -112,67 +105,19 @@ export function ArtistsGridView({
    t,
  };

-  const cols = Math.max(1, gridCols);
-
-  if (virtualization) {
-    const { virtualizer, scrollMargin } = virtualization;
-    const rowCount = Math.ceil(visible.length / cols);
-    return (
-      <div
-        ref={measureRef}
-        className="album-grid-wrap"
-        style={{ display: 'block', position: 'relative', width: '100%' }}
-      >
-        <div
-          style={{
-            height: rowCount === 0 ? 0 : virtualizer.getTotalSize(),
-            width: '100%',
-            position: 'relative',
-          }}
-        >
-          {virtualizer.getVirtualItems().map(vRow => {
-            const start = vRow.index * cols;
-            const rowArtists = visible.slice(start, start + cols);
-            return (
-              <div
-                key={vRow.key}
-                style={{
-                  position: 'absolute',
-                  top: 0,
-                  left: 0,
-                  width: '100%',
-                  transform: `translateY(${vRow.start - scrollMargin}px)`,
-                  display: 'grid',
-                  gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))`,
-                  gap: 'var(--space-4)',
-                  alignItems: 'start',
-                }}
-              >
-                {rowArtists.map(artist => (
-                  <ArtistGridTile key={artist.id} artist={artist} {...tilePropsShared} />
-                ))}
-              </div>
-            );
-          })}
-        </div>
-      </div>
-    );
-  }
-
  return (
-    <div
-      ref={measureRef}
-      className="album-grid-wrap"
-      style={{
-        display: 'grid',
-        gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))`,
-        gap: 'var(--space-4)',
-        alignItems: 'start',
-      }}
-    >
-      {visible.map(artist => (
+    <VirtualCardGrid
+      key={layoutKey}
+      items={visible}
+      itemKey={(artist) => artist.id}
+      rowVariant="artist"
+      disableVirtualization={disableVirtualization}
+      layoutSignal={visible.length}
+      scrollRootId={ARTISTS_INPAGE_SCROLL_VIEWPORT_ID}
+      wrapClassName={disableVirtualization ? 'album-grid-wrap album-grid-wrap--plain' : 'album-grid-wrap'}
+      renderItem={artist => (
        <ArtistGridTile key={artist.id} artist={artist} {...tilePropsShared} />
-      ))}
-    </div>
+      )}
+    />
  );
 }
@@ -1,7 +1,7 @@
 import { useTranslation } from 'react-i18next';
 import { Play, ListPlus, Radio, Heart, ChevronRight, ChevronsRight, User, Disc3, ListMusic, Info, Sparkles, Star, Trash2, HeartCrack, Share2, Orbit as OrbitIcon } from 'lucide-react';
-import { useNavigate } from 'react-router-dom';
 import { useNavigateToAlbum } from '../../hooks/useNavigateToAlbum';
+import { useNavigateToArtist } from '../../hooks/useNavigateToArtist';
 import { getAlbum } from '../../api/subsonicLibrary';
 import { queueSongStar } from '../../store/pendingStarSync';
 import { lastfmLoveTrack, lastfmUnloveTrack } from '../../api/lastfm';
@@ -30,8 +30,8 @@ export default function SongContextItems(props: ContextMenuItemsProps) {
  } = props;
  const { t } = useTranslation();
  const auth = useAuthStore();
-  const navigate = useNavigate();
  const navigateToAlbum = useNavigateToAlbum();
+  const navigateToArtist = useNavigateToArtist();

  return (
    <>
@@ -108,7 +108,7 @@ export default function SongContextItems(props: ContextMenuItemsProps) {
                </div>
              )}
              {song.artistId && (
-                <div className="context-menu-item" onClick={() => handleAction(() => navigate(`/artist/${song.artistId}`))}>
+                <div className="context-menu-item" onClick={() => handleAction(() => navigateToArtist(song.artistId!))}>
                  <User size={14} /> {t('contextMenu.goToArtist')}
                </div>
              )}
@@ -251,7 +251,7 @@ export default function SongContextItems(props: ContextMenuItemsProps) {
                </div>
              )}
              {song.artistId && (
-                <div className="context-menu-item" onClick={() => handleAction(() => navigate(`/artist/${song.artistId}`))}>
+                <div className="context-menu-item" onClick={() => handleAction(() => navigateToArtist(song.artistId!))}>
                  <User size={14} /> {t('contextMenu.goToArtist')}
                </div>
              )}
@@ -0,0 +1,156 @@
+import type { KeyboardEvent, MouseEvent } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createLiveSearchScopeBackspaceState,
+  handleLiveSearchScopeBackspace,
+  handleLiveSearchScopeBadgeClick,
+  handleLiveSearchScopeGhostClick,
+  handleLiveSearchScopeUndo,
+  isLiveSearchDropdownBlocked,
+  liveSearchScopePlaceholderKey,
+  noteLiveSearchScopeQueryInput,
+  resetLiveSearchScopeBackspaceState,
+  resolveLiveSearchScopeGhost,
+} from './liveSearchScopeUi';
+
+function keyEvent(
+  key: string,
+  mods: Partial<KeyboardEvent<HTMLInputElement>> & { code?: string } = {},
+) {
+  const { code, ...rest } = mods;
+  return {
+    key,
+    code: code ?? key,
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    preventDefault: vi.fn(),
+    ...rest,
+  } as unknown as KeyboardEvent<HTMLInputElement>;
+}
+
+describe('resolveLiveSearchScopeGhost', () => {
+  it('offers artists ghost on artists browse when scope was cleared', () => {
+    expect(resolveLiveSearchScopeGhost('/artists', null)).toBe('artists');
+    expect(resolveLiveSearchScopeGhost('/artists', 'artists')).toBeNull();
+    expect(resolveLiveSearchScopeGhost('/albums', null)).toBe('albums');
+    expect(resolveLiveSearchScopeGhost('/albums', 'albums')).toBeNull();
+    expect(resolveLiveSearchScopeGhost('/new-releases', null)).toBe('newReleases');
+    expect(resolveLiveSearchScopeGhost('/new-releases', 'newReleases')).toBeNull();
+    expect(resolveLiveSearchScopeGhost('/tracks', null)).toBe('tracks');
+    expect(resolveLiveSearchScopeGhost('/tracks', 'tracks')).toBeNull();
+    expect(resolveLiveSearchScopeGhost('/composers', null)).toBe('composers');
+    expect(resolveLiveSearchScopeGhost('/composers', 'composers')).toBeNull();
+  });
+});
+
+describe('handleLiveSearchScopeBadgeClick', () => {
+  it('clears scope with undo', () => {
+    const clearScope = vi.fn();
+    const e = { preventDefault: vi.fn(), stopPropagation: vi.fn() } as unknown as MouseEvent<HTMLElement>;
+    handleLiveSearchScopeBadgeClick(e, clearScope);
+    expect(clearScope).toHaveBeenCalledWith({ recordUndo: true });
+  });
+});
+
+describe('handleLiveSearchScopeGhostClick', () => {
+  it('restores scope with undo', () => {
+    const setScope = vi.fn();
+    const e = { preventDefault: vi.fn(), stopPropagation: vi.fn() } as unknown as MouseEvent<HTMLElement>;
+    handleLiveSearchScopeGhostClick(e, 'artists', setScope);
+    expect(setScope).toHaveBeenCalledWith('artists', { recordUndo: true });
+  });
+});
+
+describe('handleLiveSearchScopeBackspace', () => {
+  it('clears scope on first Backspace when the field was never filled', () => {
+    const clearScope = vi.fn();
+    const state = createLiveSearchScopeBackspaceState();
+    const e = keyEvent('Backspace');
+    expect(handleLiveSearchScopeBackspace(e, '', 'artists', clearScope, state)).toBe(true);
+    expect(clearScope).toHaveBeenCalledWith({ recordUndo: true });
+  });
+
+  it('requires two Backspaces on empty after prior input', () => {
+    const clearScope = vi.fn();
+    const state = createLiveSearchScopeBackspaceState();
+    noteLiveSearchScopeQueryInput(state, 'ab');
+
+    const first = keyEvent('Backspace');
+    expect(handleLiveSearchScopeBackspace(first, '', 'artists', clearScope, state)).toBe(true);
+    expect(clearScope).not.toHaveBeenCalled();
+
+    const second = keyEvent('Backspace');
+    expect(handleLiveSearchScopeBackspace(second, '', 'artists', clearScope, state)).toBe(true);
+    expect(clearScope).toHaveBeenCalledWith({ recordUndo: true });
+  });
+
+  it('does not clear scope while text remains', () => {
+    const clearScope = vi.fn();
+    const state = createLiveSearchScopeBackspaceState();
+    expect(handleLiveSearchScopeBackspace(keyEvent('Backspace'), 'a', 'artists', clearScope, state)).toBe(false);
+    expect(clearScope).not.toHaveBeenCalled();
+  });
+
+  it('resets empty streak when deleting characters', () => {
+    const clearScope = vi.fn();
+    const state = createLiveSearchScopeBackspaceState();
+    noteLiveSearchScopeQueryInput(state, 'a');
+    handleLiveSearchScopeBackspace(keyEvent('Backspace'), '', 'artists', clearScope, state);
+    expect(state.emptyBackspaceStreak).toBe(1);
+    handleLiveSearchScopeBackspace(keyEvent('Backspace'), 'x', 'artists', clearScope, state);
+    expect(state.emptyBackspaceStreak).toBe(0);
+  });
+});
+
+describe('resetLiveSearchScopeBackspaceState', () => {
+  it('clears hadQueryInput and streak', () => {
+    const state = createLiveSearchScopeBackspaceState();
+    noteLiveSearchScopeQueryInput(state, 'x');
+    state.emptyBackspaceStreak = 1;
+    resetLiveSearchScopeBackspaceState(state);
+    expect(state.hadQueryInput).toBe(false);
+    expect(state.emptyBackspaceStreak).toBe(0);
+  });
+});
+
+describe('isLiveSearchDropdownBlocked', () => {
+  it('blocks dropdown when a browse scope badge is active', () => {
+    expect(isLiveSearchDropdownBlocked('artists')).toBe(true);
+    expect(isLiveSearchDropdownBlocked(null)).toBe(false);
+  });
+});
+
+describe('liveSearchScopePlaceholderKey', () => {
+  it('uses scoped placeholders when a browse scope badge is active', () => {
+    expect(liveSearchScopePlaceholderKey('artists')).toBe('search.scopeArtistsPlaceholder');
+    expect(liveSearchScopePlaceholderKey('albums')).toBe('search.scopeAlbumsPlaceholder');
+    expect(liveSearchScopePlaceholderKey('newReleases')).toBe('search.scopeNewReleasesPlaceholder');
+    expect(liveSearchScopePlaceholderKey('tracks')).toBe('search.scopeTracksPlaceholder');
+    expect(liveSearchScopePlaceholderKey('composers')).toBe('search.scopeComposersPlaceholder');
+    expect(liveSearchScopePlaceholderKey(null)).toBe('search.placeholder');
+  });
+});
+
+describe('handleLiveSearchScopeUndo', () => {
+  it('calls undo on Ctrl+Z (English layout)', () => {
+    const undo = vi.fn(() => true);
+    const e = keyEvent('z', { ctrlKey: true, code: 'KeyZ' });
+    expect(handleLiveSearchScopeUndo(e, undo)).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(undo).toHaveBeenCalled();
+  });
+
+  it('calls undo on Ctrl+Z with non-Latin key label (e.g. Russian Я)', () => {
+    const undo = vi.fn(() => true);
+    const e = keyEvent('я', { ctrlKey: true, code: 'KeyZ' });
+    expect(handleLiveSearchScopeUndo(e, undo)).toBe(true);
+    expect(undo).toHaveBeenCalled();
+  });
+
+  it('ignores plain z', () => {
+    const undo = vi.fn();
+    expect(handleLiveSearchScopeUndo(keyEvent('z'), undo)).toBe(false);
+    expect(undo).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,237 @@
+import type { KeyboardEvent, MouseEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+import { ALL_NAV_ITEMS } from '../../config/navItems';
+import type { LiveSearchScope } from '../../store/liveSearchScopeStore';
+import { isAlbumsBrowsePath, isNewReleasesBrowsePath } from '../../store/albumBrowseSessionStore';
+import { isTracksBrowsePath } from '../../store/advancedSearchSessionStore';
+import { isArtistsBrowsePath } from '../../store/artistBrowseSessionStore';
+import { isComposersBrowsePath } from '../../store/composerBrowseSessionStore';
+
+const SCOPE_NAV_ITEM: Record<LiveSearchScope, keyof typeof ALL_NAV_ITEMS> = {
+  artists: 'artists',
+  albums: 'allAlbums',
+  newReleases: 'newReleases',
+  tracks: 'tracks',
+  composers: 'composers',
+};
+
+/** Scope to restore when on a browse route but the badge was cleared (global search mode). */
+export function resolveLiveSearchScopeGhost(
+  pathname: string,
+  activeScope: LiveSearchScope | null,
+): LiveSearchScope | null {
+  if (activeScope != null) return null;
+  if (isArtistsBrowsePath(pathname)) return 'artists';
+  if (isAlbumsBrowsePath(pathname)) return 'albums';
+  if (isNewReleasesBrowsePath(pathname)) return 'newReleases';
+  if (isTracksBrowsePath(pathname)) return 'tracks';
+  if (isComposersBrowsePath(pathname)) return 'composers';
+  return null;
+}
+
+export function liveSearchScopePlaceholderKey(scope: LiveSearchScope | null): string {
+  switch (scope) {
+    case 'artists':
+      return 'search.scopeArtistsPlaceholder';
+    case 'albums':
+      return 'search.scopeAlbumsPlaceholder';
+    case 'newReleases':
+      return 'search.scopeNewReleasesPlaceholder';
+    case 'tracks':
+      return 'search.scopeTracksPlaceholder';
+    case 'composers':
+      return 'search.scopeComposersPlaceholder';
+    default:
+      return 'search.placeholder';
+  }
+}
+
+/** Scoped browse mode filters the page only — no live-search dropdown. */
+export function isLiveSearchDropdownBlocked(scope: LiveSearchScope | null): boolean {
+  return scope != null;
+}
+
+export function liveSearchScopeBadgeTooltipKey(scope: LiveSearchScope): string {
+  switch (scope) {
+    case 'artists':
+      return 'search.scopeArtistsBadgeTooltip';
+    case 'albums':
+      return 'search.scopeAlbumsBadgeTooltip';
+    case 'newReleases':
+      return 'search.scopeNewReleasesBadgeTooltip';
+    case 'tracks':
+      return 'search.scopeTracksBadgeTooltip';
+    case 'composers':
+      return 'search.scopeComposersBadgeTooltip';
+    default:
+      return 'search.scopeArtistsBadgeTooltip';
+  }
+}
+
+export function liveSearchScopeGhostTooltipKey(scope: LiveSearchScope): string {
+  switch (scope) {
+    case 'artists':
+      return 'search.scopeArtistsGhostTooltip';
+    case 'albums':
+      return 'search.scopeAlbumsGhostTooltip';
+    case 'newReleases':
+      return 'search.scopeNewReleasesGhostTooltip';
+    case 'tracks':
+      return 'search.scopeTracksGhostTooltip';
+    case 'composers':
+      return 'search.scopeComposersGhostTooltip';
+    default:
+      return 'search.scopeArtistsGhostTooltip';
+  }
+}
+
+type LiveSearchScopeIconProps = {
+  scope: LiveSearchScope;
+  size?: number;
+};
+
+/** Sidebar nav icon for the scoped browse page (e.g. Users for Artists). */
+export function LiveSearchScopeIcon({ scope, size = 14 }: LiveSearchScopeIconProps) {
+  const Icon = ALL_NAV_ITEMS[SCOPE_NAV_ITEM[scope]].icon;
+  return <Icon size={size} aria-hidden />;
+}
+
+/** Tracks Backspace-on-empty badge removal (double after prior text input). */
+export type LiveSearchScopeBackspaceState = {
+  hadQueryInput: boolean;
+  emptyBackspaceStreak: number;
+};
+
+export function createLiveSearchScopeBackspaceState(): LiveSearchScopeBackspaceState {
+  return { hadQueryInput: false, emptyBackspaceStreak: 0 };
+}
+
+export function resetLiveSearchScopeBackspaceState(state: LiveSearchScopeBackspaceState): void {
+  state.hadQueryInput = false;
+  state.emptyBackspaceStreak = 0;
+}
+
+/** Call when the scoped field query changes (typing, paste, clear button, undo). */
+export function noteLiveSearchScopeQueryInput(
+  state: LiveSearchScopeBackspaceState,
+  query: string,
+): void {
+  if (query !== '') state.hadQueryInput = true;
+}
+
+/**
+ * Backspace on an empty scoped field removes the badge.
+ * After the user typed text (even if cleared), two consecutive Backspaces on empty are required.
+ */
+export function handleLiveSearchScopeBackspace(
+  e: KeyboardEvent<HTMLInputElement>,
+  query: string,
+  scope: LiveSearchScope | null,
+  clearScope: (options?: { recordUndo?: boolean }) => void,
+  state: LiveSearchScopeBackspaceState,
+): boolean {
+  if (e.key !== 'Backspace' || !scope) return false;
+
+  if (query !== '') {
+    state.emptyBackspaceStreak = 0;
+    return false;
+  }
+
+  e.preventDefault();
+
+  if (!state.hadQueryInput) {
+    clearScope({ recordUndo: true });
+    resetLiveSearchScopeBackspaceState(state);
+    return true;
+  }
+
+  state.emptyBackspaceStreak += 1;
+  if (state.emptyBackspaceStreak >= 2) {
+    clearScope({ recordUndo: true });
+    resetLiveSearchScopeBackspaceState(state);
+    return true;
+  }
+  return true;
+}
+
+/** Single click removes the scope badge. */
+export function handleLiveSearchScopeBadgeClick(
+  e: MouseEvent<HTMLElement>,
+  clearScope: (options?: { recordUndo?: boolean }) => void,
+): void {
+  e.preventDefault();
+  e.stopPropagation();
+  clearScope({ recordUndo: true });
+}
+
+/** Single click restores scope after the user cleared the badge on this browse route. */
+export function handleLiveSearchScopeGhostClick(
+  e: MouseEvent<HTMLElement>,
+  scope: LiveSearchScope,
+  setScope: (scope: LiveSearchScope, options?: { recordUndo?: boolean }) => void,
+): void {
+  e.preventDefault();
+  e.stopPropagation();
+  setScope(scope, { recordUndo: true });
+}
+
+type LiveSearchScopeBadgeProps = {
+  scope: LiveSearchScope;
+  className: string;
+  clearScope: (options?: { recordUndo?: boolean }) => void;
+};
+
+export function LiveSearchScopeBadge({ scope, className, clearScope }: LiveSearchScopeBadgeProps) {
+  const { t } = useTranslation();
+  const tooltip = t(liveSearchScopeBadgeTooltipKey(scope));
+  return (
+    <span
+      className={className}
+      role="button"
+      tabIndex={-1}
+      data-tooltip={tooltip}
+      data-tooltip-pos="bottom"
+      aria-label={tooltip}
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={(e) => handleLiveSearchScopeBadgeClick(e, clearScope)}
+    >
+      <LiveSearchScopeIcon scope={scope} size={14} />
+    </span>
+  );
+}
+
+type LiveSearchScopeGhostBadgeProps = {
+  scope: LiveSearchScope;
+  className: string;
+  setScope: (scope: LiveSearchScope, options?: { recordUndo?: boolean }) => void;
+};
+
+export function LiveSearchScopeGhostBadge({ scope, className, setScope }: LiveSearchScopeGhostBadgeProps) {
+  const { t } = useTranslation();
+  const tooltip = t(liveSearchScopeGhostTooltipKey(scope));
+  return (
+    <span
+      className={className}
+      role="button"
+      tabIndex={-1}
+      data-tooltip={tooltip}
+      data-tooltip-pos="bottom"
+      aria-label={tooltip}
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={(e) => handleLiveSearchScopeGhostClick(e, scope, setScope)}
+    >
+      <LiveSearchScopeIcon scope={scope} size={14} />
+    </span>
+  );
+}
+
+/** Field-local undo (Ctrl/Cmd+Z) for live search query and scope badge. */
+export function handleLiveSearchScopeUndo(
+  e: KeyboardEvent<HTMLInputElement>,
+  undo: () => boolean,
+): boolean {
+  const isUndoKey = e.code === 'KeyZ' || e.key.toLowerCase() === 'z';
+  if (!isUndoKey || !(e.ctrlKey || e.metaKey) || e.shiftKey) return false;
+  e.preventDefault();
+  return undo();
+}
@@ -1,14 +1,12 @@
 import type { SubsonicSong } from '../../api/subsonicTypes';
 import React from 'react';
-import { Search as SearchIcon, X } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import PagedSongList from '../PagedSongList';

 interface Props {
  title?: string;
  emptyBrowseText?: string;
-  query: string;
-  onQueryChange: (value: string) => void;
+  searchActive?: boolean;
  songs: SubsonicSong[];
  hasMore: boolean;
  loading: boolean;
@@ -16,12 +14,11 @@ interface Props {
  onLoadMore: () => void;
 }

-/** Tracks hub toolbar + paginated song list (shared chrome with Search song results). */
+/** Tracks hub toolbar + paginated song list (search lives in the header live search field). */
 export default function SongBrowseSection({
  title,
  emptyBrowseText,
-  query,
-  onQueryChange,
+  searchActive = false,
  songs,
  hasMore,
  loading,
@@ -29,31 +26,15 @@ export default function SongBrowseSection({
  onLoadMore,
 }: Props) {
  const { t } = useTranslation();
-  const showEmptyBrowse = !loading && songs.length === 0 && query.trim() === '' && (browseUnsupported || !hasMore);
+  const showEmptyBrowse =
+    !loading && songs.length === 0 && !searchActive && (browseUnsupported || !hasMore);

  return (
    <section className="virtual-song-list-section">
-      {title && <h2 className="section-title virtual-song-list-title">{title}</h2>}
+      {title && !searchActive && (
+        <h2 className="section-title virtual-song-list-title">{title}</h2>
+      )}
      <div className="virtual-song-list-toolbar">
-        <div className="virtual-song-list-search">
-          <SearchIcon size={16} className="virtual-song-list-search-icon" />
-          <input
-            type="text"
-            className="input virtual-song-list-search-input"
-            placeholder={t('tracks.searchPlaceholder')}
-            value={query}
-            onChange={e => onQueryChange(e.target.value)}
-          />
-          {query && (
-            <button
-              className="virtual-song-list-search-clear"
-              onClick={() => onQueryChange('')}
-              aria-label={t('search.clearLabel')}
-            >
-              <X size={14} />
-            </button>
-          )}
-        </div>
        <div className="virtual-song-list-meta">
          {songs.length > 0 && (
            <span>{t('tracks.count', { count: songs.length })}{hasMore ? '+' : ''}</span>
@@ -24,9 +24,12 @@ const TRACKS_SONG_RAIL_INITIAL_ARTWORK_BUDGET = 14;
 /** Tracks hub hero + song rails (above the browse-all list). */
 export default function TracksPageChrome({
  onLayoutReady,
+  hideDiscoveryChrome = false,
 }: {
  /** Fires once when hero + rails finish their initial load (or fail). */
  onLayoutReady?: () => void;
+  /** When true, skip hero and song rails (active scoped search). */
+  hideDiscoveryChrome?: boolean;
 }) {
  const perfFlags = usePerfProbeFlags();
  const { t } = useTranslation();
@@ -79,15 +82,15 @@ export default function TracksPageChrome({
  }, []);

  useEffect(() => {
-    if (!activeServerId) return;
+    if (!activeServerId || hideDiscoveryChrome) return;
    rerollHero();
    rerollRandom();
    reloadRated();
-  }, [activeServerId, rerollHero, rerollRandom, reloadRated]);
+  }, [activeServerId, hideDiscoveryChrome, rerollHero, rerollRandom, reloadRated]);

  useEffect(() => {
    if (!onLayoutReady || layoutReadyNotifiedRef.current) return;
-    if (!activeServerId) {
+    if (hideDiscoveryChrome || !activeServerId) {
      layoutReadyNotifiedRef.current = true;
      onLayoutReady();
      return;
@@ -95,7 +98,7 @@ export default function TracksPageChrome({
    if (heroLoading || randomLoading || ratedLoading) return;
    layoutReadyNotifiedRef.current = true;
    onLayoutReady();
-  }, [activeServerId, onLayoutReady, heroLoading, randomLoading, ratedLoading]);
+  }, [activeServerId, hideDiscoveryChrome, onLayoutReady, heroLoading, randomLoading, ratedLoading]);

  const railSongs = useMemo(
    () => (hero ? random.filter(s => s.id !== hero.id) : random),
@@ -108,12 +111,14 @@ export default function TracksPageChrome({
        <header className="tracks-header">
          <div className="tracks-header-text">
            <h1 className="page-title">{t('tracks.title')}</h1>
-            <p className="tracks-subtitle">{t('tracks.subtitle')}</p>
+            {!hideDiscoveryChrome && (
+              <p className="tracks-subtitle">{t('tracks.subtitle')}</p>
+            )}
          </div>
        </header>
      )}

-      {!perfFlags.disableMainstageHero && hero && (
+      {!perfFlags.disableMainstageHero && !hideDiscoveryChrome && hero && (
        <section className="tracks-hero">
          <div className="tracks-hero-cover">
            {hero.albumId && hero.coverArt ? (
@@ -173,7 +178,7 @@ export default function TracksPageChrome({
        </section>
      )}

-      {!perfFlags.disableMainstageRails && ratedSupported && (ratedLoading || rated.length > 0) && (
+      {!perfFlags.disableMainstageRails && !hideDiscoveryChrome && ratedSupported && (ratedLoading || rated.length > 0) && (
        <SongRail
          title={t('tracks.railHighlyRated')}
          songs={rated}
@@ -184,7 +189,7 @@ export default function TracksPageChrome({
        />
      )}

-      {!perfFlags.disableMainstageRails && (
+      {!perfFlags.disableMainstageRails && !hideDiscoveryChrome && (
        <SongRail
          title={t('tracks.railRandom')}
          songs={railSongs}