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)

src/store/albumBrowseSessionStore.test.ts

@@ -7,6 +7,8 @@ import {
   albumBrowseSurfaceForPath,
   clearGenreDetailReturnStash,
   isAlbumDetailPath,
+  isAlbumsBrowsePath,
+  isNewReleasesBrowsePath,
   isGenreDetailPath,
   genreDetailGenreFromPath,
   peekAlbumBrowseScrollRestore,
@@ -144,6 +146,11 @@ describe('isGenreDetailPath', () => {
 describe('albumBrowseSurfaceForPath', () => {
   it('maps album grid browse routes', () => {
     expect(albumBrowseSurfaceForPath('/albums')).toBe('albums');
+    expect(isAlbumsBrowsePath('/albums')).toBe(true);
+    expect(isAlbumsBrowsePath('/albums/')).toBe(true);
+    expect(isAlbumsBrowsePath('/new-releases')).toBe(false);
+    expect(isNewReleasesBrowsePath('/new-releases')).toBe(true);
+    expect(isNewReleasesBrowsePath('/new-releases/')).toBe(true);
     expect(albumBrowseSurfaceForPath('/new-releases')).toBe('new-releases');
     expect(albumBrowseSurfaceForPath('/random/albums')).toBe('random-albums');
     expect(albumBrowseSurfaceForPath('/artists')).toBeNull();

src/store/albumBrowseSessionStore.ts

@@ -17,6 +17,8 @@ export interface AlbumBrowseReturnFilters {
   compFilter: AlbumBrowseCompFilter;
   starredOnly: boolean;
   losslessOnly: boolean;
+  /** Header live search query when leaving for album detail (All Albums scope). */
+  searchQuery?: string;
   /** In-page grid scroll position when leaving the browse surface. */
   scrollTop?: number;
   /** Row count at leave time — preload at least this many rows before scroll. */
@@ -77,6 +79,7 @@ function cloneReturnFilters(filters: AlbumBrowseReturnFilters): AlbumBrowseRetur
     compFilter: filters.compFilter,
     starredOnly: filters.starredOnly,
     losslessOnly: filters.losslessOnly,
+    ...(typeof filters.searchQuery === 'string' ? { searchQuery: filters.searchQuery } : {}),
     ...(typeof filters.scrollTop === 'number' ? { scrollTop: filters.scrollTop } : {}),
     ...(typeof filters.displayCount === 'number' ? { displayCount: filters.displayCount } : {}),
     ...(filters.albums ? { albums: [...filters.albums] } : {}),
@@ -194,6 +197,16 @@ export function albumBrowseSortForServer(
 }
 
 /** Map pathname to album grid browse surface, if any. */
+/** All Albums browse route (`/albums`) — scoped live search target. */
+export function isAlbumsBrowsePath(pathname: string): boolean {
+  return albumBrowseSurfaceForPath(pathname) === 'albums';
+}
+
+/** New Releases browse route (`/new-releases`) — scoped live search target. */
+export function isNewReleasesBrowsePath(pathname: string): boolean {
+  return albumBrowseSurfaceForPath(pathname) === 'new-releases';
+}
+
 export function albumBrowseSurfaceForPath(pathname: string): AlbumBrowseSurface | null {
   const path = pathname.split('?')[0]?.replace(/\/$/, '') || pathname;
   if (path === '/albums') return 'albums';
@@ -224,6 +237,11 @@ export function isArtistDetailPath(pathname: string): boolean {
   return /^\/artist\/[^/]+\/?$/.test(pathname);
 }
 
-export function isAdvancedSearchLeaveTargetPath(pathname: string): boolean {
-  return isAlbumDetailPath(pathname) || isArtistDetailPath(pathname);
+/** True when pathname is a single composer detail route (`/composer/:id`). */
+export function isComposerDetailPath(pathname: string): boolean {
+  return /^\/composer\/[^/]+\/?$/.test(pathname);
+}
+
+export function isAdvancedSearchLeaveTargetPath(pathname: string): boolean {
+  return isAlbumDetailPath(pathname) || isArtistDetailPath(pathname) || isComposerDetailPath(pathname);
 }

src/store/composerBrowseSessionStore.ts

@@ -0,0 +1,87 @@
+import { create } from 'zustand';
+import { ALL_SENTINEL } from '../utils/componentHelpers/artistsHelpers';
+
+export type ComposerBrowseViewMode = 'grid' | 'list';
+
+/** Browse state restored when returning to Composers via back from composer detail. */
+export interface ComposerBrowseReturnState {
+  filter: string;
+  letterFilter: string;
+  starredOnly: boolean;
+  viewMode: ComposerBrowseViewMode;
+  scrollTop?: number;
+  visibleCount?: number;
+}
+
+export const DEFAULT_COMPOSER_BROWSE_RETURN_STATE: ComposerBrowseReturnState = {
+  filter: '',
+  letterFilter: ALL_SENTINEL,
+  starredOnly: false,
+  viewMode: 'grid',
+};
+
+interface ComposerBrowseSessionStore {
+  returnStashByServer: Record<string, ComposerBrowseReturnState>;
+  stashReturnState: (serverId: string, state: ComposerBrowseReturnState) => void;
+  clearReturnStash: (serverId: string) => void;
+  peekReturnStash: (serverId: string) => ComposerBrowseReturnState | null;
+}
+
+export const useComposerBrowseSessionStore = create<ComposerBrowseSessionStore>((set, get) => ({
+  returnStashByServer: {},
+
+  stashReturnState: (serverId, state) => {
+    if (!serverId) return;
+    set((s) => ({
+      returnStashByServer: {
+        ...s.returnStashByServer,
+        [serverId]: {
+          filter: state.filter,
+          letterFilter: state.letterFilter,
+          starredOnly: state.starredOnly,
+          viewMode: state.viewMode,
+          ...(typeof state.scrollTop === 'number' ? { scrollTop: state.scrollTop } : {}),
+          ...(typeof state.visibleCount === 'number' ? { visibleCount: state.visibleCount } : {}),
+        },
+      },
+    }));
+  },
+
+  clearReturnStash: (serverId) => {
+    if (!serverId) return;
+    const next = { ...get().returnStashByServer };
+    delete next[serverId];
+    set({ returnStashByServer: next });
+  },
+
+  peekReturnStash: (serverId) => {
+    if (!serverId) return null;
+    const stash = get().returnStashByServer[serverId];
+    if (!stash) return null;
+    return {
+      filter: stash.filter,
+      letterFilter: stash.letterFilter,
+      starredOnly: stash.starredOnly,
+      viewMode: stash.viewMode,
+      ...(typeof stash.scrollTop === 'number' ? { scrollTop: stash.scrollTop } : {}),
+      ...(typeof stash.visibleCount === 'number' ? { visibleCount: stash.visibleCount } : {}),
+    };
+  },
+}));
+
+export function peekComposerBrowseScrollRestore(
+  serverId: string,
+): { scrollTop: number; visibleCount: number } | null {
+  const stash = useComposerBrowseSessionStore.getState().peekReturnStash(serverId);
+  if (!stash) return null;
+  if (typeof stash.scrollTop !== 'number' || typeof stash.visibleCount !== 'number') return null;
+  return {
+    scrollTop: Math.max(0, stash.scrollTop),
+    visibleCount: Math.max(0, stash.visibleCount),
+  };
+}
+
+/** True when pathname is the Composers browse route (`/composers`). */
+export function isComposersBrowsePath(pathname: string): boolean {
+  return pathname === '/composers';
+}

src/store/liveSearchScopeStore.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it, beforeEach } from 'vitest';
+import {
+  scopedBrowseSearchQuery,
+  useLiveSearchScopeStore,
+} from './liveSearchScopeStore';
+
+describe('liveSearchScopeStore', () => {
+  beforeEach(() => {
+    useLiveSearchScopeStore.setState({ query: '', scope: null, undoStack: [] });
+  });
+
+  it('returns browse query only when the expected scope is active', () => {
+    useLiveSearchScopeStore.setState({ query: 'beatles', scope: 'artists' });
+    expect(scopedBrowseSearchQuery('beatles', 'artists', 'artists')).toBe('beatles');
+    expect(scopedBrowseSearchQuery('beatles', null, 'artists')).toBe('');
+    useLiveSearchScopeStore.setState({ query: 'abbey', scope: 'albums' });
+    expect(scopedBrowseSearchQuery('abbey', 'albums', 'albums')).toBe('abbey');
+    expect(scopedBrowseSearchQuery('abbey', 'artists', 'albums')).toBe('');
+    useLiveSearchScopeStore.setState({ query: 'jazz', scope: 'newReleases' });
+    expect(scopedBrowseSearchQuery('jazz', 'newReleases', 'newReleases')).toBe('jazz');
+    useLiveSearchScopeStore.setState({ query: 'track', scope: 'tracks' });
+    expect(scopedBrowseSearchQuery('track', 'tracks', 'tracks')).toBe('track');
+    expect(scopedBrowseSearchQuery('track', 'albums', 'tracks')).toBe('');
+    useLiveSearchScopeStore.setState({ query: 'bach', scope: 'composers' });
+    expect(scopedBrowseSearchQuery('bach', 'composers', 'composers')).toBe('bach');
+    expect(scopedBrowseSearchQuery('bach', 'artists', 'composers')).toBe('');
+  });
+
+  it('undoes query and scope badge changes', () => {
+    useLiveSearchScopeStore.getState().setScope('artists');
+    useLiveSearchScopeStore.getState().setQuery('ab', { recordUndo: true });
+    useLiveSearchScopeStore.getState().setQuery('a', { recordUndo: true });
+    useLiveSearchScopeStore.getState().clearScope({ recordUndo: true });
+
+    expect(useLiveSearchScopeStore.getState().scope).toBeNull();
+    expect(useLiveSearchScopeStore.getState().undo()).toBe(true);
+    expect(useLiveSearchScopeStore.getState().scope).toBe('artists');
+    expect(useLiveSearchScopeStore.getState().query).toBe('a');
+    expect(useLiveSearchScopeStore.getState().undo()).toBe(true);
+    expect(useLiveSearchScopeStore.getState().query).toBe('ab');
+  });
+
+  it('does not record undo for programmatic setQuery by default', () => {
+    useLiveSearchScopeStore.getState().setQuery('test');
+    expect(useLiveSearchScopeStore.getState().undo()).toBe(false);
+  });
+});

src/store/liveSearchScopeStore.ts

@@ -0,0 +1,87 @@
+import { create } from 'zustand';
+
+/** Page-scoped live search mode — badge in the header search field. */
+export type LiveSearchScope = 'artists' | 'albums' | 'newReleases' | 'tracks' | 'composers';
+
+export type LiveSearchSnapshot = {
+  query: string;
+  scope: LiveSearchScope | null;
+};
+
+type LiveSearchMutationOpts = {
+  /** Push the current field state onto the search-local undo stack. */
+  recordUndo?: boolean;
+};
+
+interface LiveSearchScopeStore {
+  query: string;
+  scope: LiveSearchScope | null;
+  undoStack: LiveSearchSnapshot[];
+  setQuery: (query: string, options?: LiveSearchMutationOpts) => void;
+  setScope: (scope: LiveSearchScope | null, options?: LiveSearchMutationOpts) => void;
+  clearScope: (options?: LiveSearchMutationOpts) => void;
+  recordUndoSnapshot: () => void;
+  undo: () => boolean;
+}
+
+const MAX_UNDO = 50;
+
+function snapshotsEqual(a: LiveSearchSnapshot, b: LiveSearchSnapshot): boolean {
+  return a.query === b.query && a.scope === b.scope;
+}
+
+export const useLiveSearchScopeStore = create<LiveSearchScopeStore>((set, get) => ({
+  query: '',
+  scope: null,
+  undoStack: [],
+
+  recordUndoSnapshot: () => {
+    const snap: LiveSearchSnapshot = { query: get().query, scope: get().scope };
+    set((s) => {
+      const last = s.undoStack[s.undoStack.length - 1];
+      if (last && snapshotsEqual(last, snap)) return s;
+      return { undoStack: [...s.undoStack, snap].slice(-MAX_UNDO) };
+    });
+  },
+
+  setQuery: (query, options) => {
+    if (get().query === query) return;
+    if (options?.recordUndo) get().recordUndoSnapshot();
+    set({ query });
+  },
+
+  setScope: (scope, options) => {
+    if (get().scope === scope) return;
+    if (options?.recordUndo) get().recordUndoSnapshot();
+    set({ scope });
+  },
+
+  clearScope: (options) => {
+    if (get().scope == null) return;
+    if (options?.recordUndo) get().recordUndoSnapshot();
+    set({ scope: null });
+  },
+
+  undo: () => {
+    const stack = get().undoStack;
+    if (stack.length === 0) return false;
+    const prev = stack[stack.length - 1]!;
+    set({ query: prev.query, scope: prev.scope, undoStack: stack.slice(0, -1) });
+    return true;
+  },
+}));
+
+/** Browse filter text when the header scope badge matches the page. */
+export function scopedBrowseSearchQuery(
+  query: string,
+  activeScope: LiveSearchScope | null,
+  expectedScope: LiveSearchScope,
+): string {
+  return activeScope === expectedScope ? query : '';
+}
+
+export function useScopedBrowseSearchQuery(expectedScope: LiveSearchScope): string {
+  const query = useLiveSearchScopeStore(s => s.query);
+  const scope = useLiveSearchScopeStore(s => s.scope);
+  return scopedBrowseSearchQuery(query, scope, expectedScope);
+}