test(frontend): harness expansion + utility coverage push (F0 + F6) (#539)

* test(frontend): expand harness for store/component/contract tests

- factories: makeSubsonicSong, makeServer, makeAuthState, makeQueueState
- storeReset.ts: per-test reset for player/auth/preview/orbit stores
- mocks/subsonic.ts: realistic fixtures + stream/cover URL helpers
- mocks/browser.ts: ResizeObserver/IntersectionObserver/matchMedia/clipboard/object URLs
- mocks/tauri.ts: tauriMockListenerCount for listener-lifecycle regression tests
- renderWithProviders: pin i18n language to 'en' by default; { language } opt-out
- vitest.config: pool 'forks' + isolate to avoid module-mock + Zustand-global flake
- README: documented patterns, store-reset policy, i18n rule, isolation rationale

* test(frontend): bump utility coverage + expand hot-path gate

serverMagicString: 71→100% (encode/decode rejection branches, clipboard
fallback paths). shareLink: 69→97% (all entity kinds, queue trim, orbit
decoder, findServerIdForShareUrl). dynamicColors: 44→100% (extractCoverColors
DOM paths via Image / canvas / fetch mocks).

Gate adds shareLink.ts and dynamicColors.ts — both stable above 95%.
Comments updated for the new floor and the M4 hard-gate handoff.

src/test/README.md

@@ -1,20 +1,29 @@
 # Frontend test framework
 
 Vitest + jsdom + @testing-library/react. Existing util tests in
-`src/utils/*.test.ts` keep working; this folder adds the harness for store,
+`src/utils/*.test.ts` keep working; this folder hosts the harness for store,
 hook, component and (eventually) integration tests.
 
 ## Layout
 
 ```
 src/test/
-  setup.ts                      # global setup: jest-dom, @testing-library cleanup,
-                                # vi.mock for @tauri-apps/api/*
+  setup.ts                      # global: jest-dom, cleanup, vi.mock for tauri/*,
+                                # localStorage polyfill, browser-mock install
   mocks/
-    tauri.ts                    # programmable invoke() + listen() helpers
+    tauri.ts                    # programmable invoke() + listen() helpers,
+                                # tauriMockListenerCount(event) for lifecycle tests
+    subsonic.ts                 # realistic Subsonic fixture data
+    browser.ts                  # ResizeObserver / IntersectionObserver /
+                                # matchMedia / clipboard / object URL mocks
   helpers/
-    factories.ts                # makeTrack / makeTracks fixtures
+    factories.ts                # makeTrack / makeTracks / makeSubsonicSong /
+                                # makeServer / makeAuthState / makeQueueState
+    storeReset.ts               # resetPlayerStore / resetAuthStore /
+                                # resetPreviewStore / resetOrbitStore /
+                                # resetAllStores
     renderWithProviders.tsx     # render() wrapped with MemoryRouter + i18n
+                                # (en-pinned by default)
   README.md                     # this file
 ```
 
@@ -37,11 +46,11 @@ npm run test:coverage          # with v8 coverage → ./coverage/
 ## Mocking Tauri
 
 `@tauri-apps/api/core` and `@tauri-apps/api/event` are mocked globally in
-`setup.ts`. To configure per-test behaviour, import the helpers in
+`setup.ts`. Configure per-test behaviour via the helpers in
 `mocks/tauri.ts`:
 
 ```ts
-import { onInvoke, emitTauriEvent, invokeMock } from '@/test/mocks/tauri';
+import { onInvoke, emitTauriEvent, invokeMock, tauriMockListenerCount } from '@/test/mocks/tauri';
 
 beforeEach(() => {
   onInvoke('audio_play', () => undefined);
@@ -51,27 +60,76 @@ it('responds to engine events', () => {
   emitTauriEvent('audio:progress', { id: 't1', currentTime: 42 });
   expect(invokeMock).toHaveBeenCalledWith('audio_play', { id: 't1' });
 });
+
+it('does not double-register listeners on re-init', () => {
+  // ... call init logic twice, assert listener count is 1
+  expect(tauriMockListenerCount('audio:progress')).toBe(1);
+});
 ```
 
 Unhandled `invoke()` calls throw a descriptive error — tests are honest about
-which commands they exercise. Handlers are auto-cleared between tests.
+which commands they exercise. Handlers + listeners are auto-cleared between
+tests.
 
-## Mocking HTTP
+## Mocking Subsonic / HTTP
 
-For Subsonic / Navidrome / Last.fm calls, prefer **module-level mocks** for
-unit tests:
+Hoist the mock in the test file (vitest limitation — factory functions can't
+import helper modules at hoist time), then inject realistic fixture data
+from `mocks/subsonic.ts`:
 
 ```ts
-vi.mock('@/api/subsonic', () => ({
-  getAlbum: vi.fn(async () => ({ id: 'a1', tracks: [] })),
-  buildStreamUrl: (id: string) => `https://mock/stream/${id}`,
-}));
+import { vi, describe, it, beforeEach, expect } from 'vitest';
+vi.mock('@/api/subsonic');
+import { getAlbum, buildStreamUrl } from '@/api/subsonic';
+import { sampleAlbumWithSongs, mockStreamUrl } from '@/test/mocks/subsonic';
+
+beforeEach(() => {
+  vi.mocked(getAlbum).mockResolvedValue(sampleAlbumWithSongs);
+  vi.mocked(buildStreamUrl).mockImplementation(mockStreamUrl);
+});
 ```
 
-For broader integration tests that touch many endpoints we can introduce
+For broader integration tests that touch many endpoints we may introduce
 **MSW** later. The framework is intentionally MSW-free right now to keep
 the dep surface small until we need it.
 
+## Resetting stores
+
+Zustand stores are module-level singletons and leak state across tests
+unless explicitly reset. setup.ts already clears localStorage between
+tests, but the in-memory `getState()` snapshot survives.
+
+Use `helpers/storeReset.ts`:
+
+```ts
+import { resetPlayerStore, resetAllStores } from '@/test/helpers/storeReset';
+
+describe('myFeature', () => {
+  beforeEach(resetPlayerStore);
+  // or, for cross-store tests:
+  beforeEach(resetAllStores);
+});
+```
+
+Each reset replaces the live state with the snapshot captured at module
+import time. Action references are preserved (they're closed over the
+original `set`/`get`, stable across `setState`).
+
+## i18n language is pinned to `en`
+
+`renderWithProviders` calls `i18n.changeLanguage('en')` synchronously before
+render, so `getByText('Settings')` finds the English label regardless of
+the developer's local language preference. Tests that want to assert
+against another translation pass `{ language: 'de' }`:
+
+```ts
+renderWithProviders(<MyComponent />, { language: 'de' });
+```
+
+Rationale: option 5a from the pre-refactor testing plan (2026-05-11). Without
+a fixed test language, every translation edit risks flipping a green test
+red on a contributor's machine.
+
 ## Patterns
 
 ### Pure utilities
@@ -82,8 +140,7 @@ needed beyond `import { describe, it, expect } from 'vitest'`.
 ### Zustand stores
 
 - Import the hook, drive it via `useFooStore.getState()`.
-- Reset state in a `beforeEach` — Zustand stores are module-level singletons
-  and leak across tests otherwise.
+- Reset state in a `beforeEach` via `storeReset.ts`.
 - Stub Tauri side effects via `onInvoke()`.
 - Use `emitTauriEvent()` to drive event-driven state transitions.
 
@@ -92,8 +149,10 @@ See `src/store/previewStore.test.ts` for the reference pattern.
 ### Components
 
 - `renderWithProviders(<MyComponent />)` from `helpers/renderWithProviders`.
-- Query by role / label / text first; fall back to `data-testid` only when
-  the DOM provides no semantic anchor.
+- Prefer `getByRole({ name: ... })` over `getByText` when a semantic role
+  exists — the role survives translation tweaks and refactors that move
+  labels into different elements.
+- Fall back to `data-testid` only when the DOM provides no semantic anchor.
 - Use `userEvent` (not `fireEvent`) for click / type / keyboard, with the
   exception of `keydown` on `window` for global shortcut paths.
 
@@ -114,12 +173,30 @@ wrappers when the hook reads from a provider.
 - **react-i18next.** `I18nextProvider` with the real `i18n.ts` instance is
   cheap and avoids tests that lie about labels.
 
+## What to NOT snapshot
+
+- Large rendered trees from `renderWithProviders`. Translation edits, CSS
+  class renames, or unrelated child-component refactors flip the snapshot
+  for reasons unrelated to the unit under test. Assert on specific
+  observable behaviour instead — a button is enabled, an aria-label is
+  present, a class is set.
+- Zustand state snapshots that include action functions. Function identity
+  changes break the snapshot without any behavioural reason.
+
 ## Coverage gates
 
 - `vitest run --coverage` writes `coverage/coverage-summary.json` which the
   hot-path gate consumes.
 - `.github/frontend-hot-path-files.txt` lists the files held to ≥70% line
   coverage by `scripts/check-frontend-hot-path-coverage.sh`.
-- CI runs both. The gate is currently soft (`continue-on-error: true`) —
-  flip to a hard PR-blocker once a few PRs run cleanly. Mirrors the backend
-  rust-tests rollout.
+- CI runs both. The gate is soft today (`continue-on-error: true`) —
+  it flips to a hard PR-blocker at the start of M4 in the pre-refactor
+  testing plan. Mirrors the backend rust-tests rollout.
+
+## Process isolation
+
+`vitest.config.ts` pins `pool: 'forks'` + `isolate: true`. Each test file
+runs in its own forked process with a fresh module graph. ~20% slower
+locally than the default thread pool but avoids the fake-timer +
+module-mock + Zustand-global flake class that surfaces around suite-size
+30+.

src/test/helpers/factories.ts

@@ -6,8 +6,12 @@
  * than on assembling boilerplate.
  */
 import type { Track } from '@/store/playerStore';
+import type { ServerProfile } from '@/store/authStore';
+import type { SubsonicSong } from '@/api/subsonic';
 
 let trackCounter = 0;
+let songCounter = 0;
+let serverCounter = 0;
 
 export function makeTrack(overrides: Partial<Track> = {}): Track {
   trackCounter += 1;
@@ -28,6 +32,56 @@ export function makeTracks(n: number, overridesFn?: (i: number) => Partial<Track
   return Array.from({ length: n }, (_, i) => makeTrack(overridesFn?.(i) ?? {}));
 }
 
+export function makeSubsonicSong(overrides: Partial<SubsonicSong> = {}): SubsonicSong {
+  songCounter += 1;
+  const id = overrides.id ?? `song-${songCounter}`;
+  return {
+    id,
+    title: `Song ${songCounter}`,
+    artist: 'Test Artist',
+    album: 'Test Album',
+    albumId: `album-${songCounter}`,
+    duration: 180,
+    coverArt: id,
+    bitRate: 320,
+    suffix: 'flac',
+    contentType: 'audio/flac',
+    size: 8_000_000,
+    ...overrides,
+  };
+}
+
+export function makeServer(overrides: Partial<ServerProfile> = {}): ServerProfile {
+  serverCounter += 1;
+  return {
+    id: `server-${serverCounter}`,
+    name: `Test Server ${serverCounter}`,
+    url: `https://server-${serverCounter}.test`,
+    username: 'tester',
+    password: 'pw',
+    ...overrides,
+  };
+}
+
+/** Minimal `useAuthStore.setState(...)` partial — extend per test. */
+export function makeAuthState(opts: { servers?: ServerProfile[]; activeServerId?: string | null } = {}) {
+  const servers = opts.servers ?? [makeServer()];
+  return {
+    servers,
+    activeServerId: opts.activeServerId === undefined ? servers[0]?.id ?? null : opts.activeServerId,
+  };
+}
+
+/** Minimal `usePlayerStore.setState(...)` partial for queue characterization tests. */
+export function makeQueueState(opts: { queue?: Track[]; currentIndex?: number; currentTrack?: Track | null } = {}) {
+  const queue = opts.queue ?? makeTracks(3);
+  const currentIndex = opts.currentIndex ?? 0;
+  const currentTrack = opts.currentTrack === undefined ? (queue[currentIndex] ?? null) : opts.currentTrack;
+  return { queue, currentIndex, currentTrack };
+}
+
 export function resetFactoryCounters(): void {
   trackCounter = 0;
+  songCounter = 0;
+  serverCounter = 0;
 }

src/test/helpers/renderWithProviders.tsx

@@ -5,6 +5,12 @@
  *
  * Tests that don't need a specific route can call `renderWithProviders(<X />)`.
  * Tests that need a specific URL pass `{ route: '/album/42' }`.
+ *
+ * **i18n language is pinned to `en` by default.** This keeps `getByText` /
+ * `getByRole({ name })` selectors stable regardless of the developer's local
+ * language preference. A test that wants to assert against a non-English
+ * translation can pass `{ language: 'de' }`. See `src/test/README.md` for
+ * the rationale (rule 5a from the pre-refactor testing plan, 2026-05-11).
  */
 import type { ReactElement, ReactNode } from 'react';
 import { render, type RenderOptions, type RenderResult } from '@testing-library/react';
@@ -14,9 +20,15 @@ import i18n from '@/i18n';
 
 interface WrapperOptions {
   route?: string;
+  language?: string;
 }
 
-function makeWrapper({ route = '/' }: WrapperOptions) {
+function makeWrapper({ route = '/', language = 'en' }: WrapperOptions) {
+  if (i18n.language !== language) {
+    // Translations are bundled inline in `src/i18n.ts`, so changeLanguage
+    // resolves synchronously — safe to ignore the returned promise.
+    void i18n.changeLanguage(language);
+  }
   return function Wrapper({ children }: { children: ReactNode }) {
     return (
       <I18nextProvider i18n={i18n}>
@@ -30,6 +42,6 @@ export function renderWithProviders(
   ui: ReactElement,
   options: WrapperOptions & Omit<RenderOptions, 'wrapper'> = {},
 ): RenderResult {
-  const { route, ...rest } = options;
-  return render(ui, { wrapper: makeWrapper({ route }), ...rest });
+  const { route, language, ...rest } = options;
+  return render(ui, { wrapper: makeWrapper({ route, language }), ...rest });
 }

src/test/helpers/storeReset.ts

@@ -0,0 +1,54 @@
+/**
+ * Per-test Zustand store reset helpers.
+ *
+ * Zustand stores are module-level singletons and leak state across tests
+ * unless explicitly reset. setup.ts already clears localStorage between
+ * tests, but the in-memory `getState()` snapshot survives — a mutation in
+ * test A is visible to test B unless we reset.
+ *
+ * Strategy: capture each store's initial state at module-import time (when
+ * persist hydration runs against the empty MemoryStorage polyfill in
+ * setup.ts, so we get the static defaults). Each reset replaces the live
+ * state with that captured snapshot, preserving the original action
+ * references (functions are stable across `setState` since they're closed
+ * over `set`/`get` from the original factory call).
+ *
+ * Usage in a test file:
+ *
+ *   import { resetPlayerStore, resetAllStores } from '@/test/helpers/storeReset';
+ *   beforeEach(resetPlayerStore);
+ *   // or for cross-store tests:
+ *   beforeEach(resetAllStores);
+ */
+import { usePlayerStore } from '@/store/playerStore';
+import { useAuthStore } from '@/store/authStore';
+import { usePreviewStore } from '@/store/previewStore';
+import { useOrbitStore } from '@/store/orbitStore';
+
+const INITIAL_PLAYER_STATE = usePlayerStore.getState();
+const INITIAL_AUTH_STATE = useAuthStore.getState();
+const INITIAL_PREVIEW_STATE = usePreviewStore.getState();
+const INITIAL_ORBIT_STATE = useOrbitStore.getState();
+
+export function resetPlayerStore(): void {
+  usePlayerStore.setState(INITIAL_PLAYER_STATE, true);
+}
+
+export function resetAuthStore(): void {
+  useAuthStore.setState(INITIAL_AUTH_STATE, true);
+}
+
+export function resetPreviewStore(): void {
+  usePreviewStore.setState(INITIAL_PREVIEW_STATE, true);
+}
+
+export function resetOrbitStore(): void {
+  useOrbitStore.setState(INITIAL_ORBIT_STATE, true);
+}
+
+export function resetAllStores(): void {
+  resetPlayerStore();
+  resetAuthStore();
+  resetPreviewStore();
+  resetOrbitStore();
+}

src/test/mocks/browser.ts

@@ -0,0 +1,114 @@
+/**
+ * Browser API mocks for jsdom.
+ *
+ * jsdom ships partial implementations of some Web APIs and stubs others
+ * entirely. Components that legitimately call `ResizeObserver`,
+ * `IntersectionObserver`, `matchMedia`, `navigator.clipboard`, or
+ * `URL.createObjectURL` need test-time implementations to avoid `is not a
+ * function` failures.
+ *
+ * `installBrowserMocks()` is idempotent — calling it twice is harmless.
+ * It is wired into setup.ts so every test file inherits the mocks; per-test
+ * overrides remain possible via `vi.spyOn` on the specific mock instance.
+ */
+import { vi } from 'vitest';
+
+// ─── ResizeObserver ──────────────────────────────────────────────────────────
+class MockResizeObserver implements ResizeObserver {
+  observe = vi.fn<(target: Element) => void>();
+  unobserve = vi.fn<(target: Element) => void>();
+  disconnect = vi.fn<() => void>();
+}
+
+// ─── IntersectionObserver ────────────────────────────────────────────────────
+class MockIntersectionObserver implements IntersectionObserver {
+  readonly root: Element | Document | null = null;
+  readonly rootMargin: string = '0px';
+  readonly scrollMargin: string = '0px';
+  readonly thresholds: ReadonlyArray<number> = [];
+  observe = vi.fn<(target: Element) => void>();
+  unobserve = vi.fn<(target: Element) => void>();
+  disconnect = vi.fn<() => void>();
+  takeRecords = vi.fn<() => IntersectionObserverEntry[]>(() => []);
+}
+
+// ─── matchMedia ──────────────────────────────────────────────────────────────
+function makeMockMediaQueryList(query: string): MediaQueryList {
+  const listeners = new Set<(e: MediaQueryListEvent) => void>();
+  const list = {
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn((cb: (e: MediaQueryListEvent) => void) => listeners.add(cb)),
+    removeListener: vi.fn((cb: (e: MediaQueryListEvent) => void) => listeners.delete(cb)),
+    addEventListener: vi.fn((_type: string, cb: EventListenerOrEventListenerObject) =>
+      listeners.add(cb as (e: MediaQueryListEvent) => void),
+    ),
+    removeEventListener: vi.fn((_type: string, cb: EventListenerOrEventListenerObject) =>
+      listeners.delete(cb as (e: MediaQueryListEvent) => void),
+    ),
+    dispatchEvent: vi.fn(() => true),
+  } as unknown as MediaQueryList;
+  return list;
+}
+
+// ─── Clipboard ───────────────────────────────────────────────────────────────
+let clipboardContents = '';
+const clipboardMock = {
+  writeText: vi.fn(async (text: string) => {
+    clipboardContents = String(text);
+  }),
+  readText: vi.fn(async () => clipboardContents),
+};
+
+export function getMockClipboardContents(): string {
+  return clipboardContents;
+}
+
+// ─── URL.createObjectURL / revokeObjectURL ───────────────────────────────────
+let objectUrlCounter = 0;
+const createObjectUrlMock = vi.fn((_blob: Blob | MediaSource) => {
+  objectUrlCounter += 1;
+  return `blob:mock://obj-${objectUrlCounter}`;
+});
+const revokeObjectUrlMock = vi.fn<(url: string) => void>();
+
+// ─── Install ─────────────────────────────────────────────────────────────────
+let installed = false;
+
+export function installBrowserMocks(): void {
+  if (installed) return;
+  installed = true;
+
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver = MockIntersectionObserver as unknown as typeof IntersectionObserver;
+
+  if (typeof window !== 'undefined') {
+    Object.defineProperty(window, 'matchMedia', {
+      configurable: true,
+      writable: true,
+      value: vi.fn((query: string) => makeMockMediaQueryList(query)),
+    });
+    Object.defineProperty(window.navigator, 'clipboard', {
+      configurable: true,
+      writable: true,
+      value: clipboardMock,
+    });
+  }
+
+  if (typeof URL !== 'undefined') {
+    URL.createObjectURL = createObjectUrlMock as unknown as typeof URL.createObjectURL;
+    URL.revokeObjectURL = revokeObjectUrlMock as unknown as typeof URL.revokeObjectURL;
+  }
+}
+
+export function resetBrowserMocks(): void {
+  clipboardContents = '';
+  objectUrlCounter = 0;
+  clipboardMock.writeText.mockClear();
+  clipboardMock.readText.mockClear();
+  createObjectUrlMock.mockClear();
+  revokeObjectUrlMock.mockClear();
+}
+
+export { clipboardMock, createObjectUrlMock, revokeObjectUrlMock };

src/test/mocks/subsonic.ts

@@ -0,0 +1,101 @@
+/**
+ * Subsonic API mock fixtures.
+ *
+ * `vi.mock('@/api/subsonic')` is hoisted in the test file itself (vitest
+ * limitation — factory functions can't reach helper modules at hoist time).
+ * This module supplies the *data* the test injects into those mocks:
+ *
+ *   // In the test:
+ *   vi.mock('@/api/subsonic');
+ *   import { getAlbum, buildStreamUrl } from '@/api/subsonic';
+ *   import { sampleAlbumWithSongs, mockStreamUrl } from '@/test/mocks/subsonic';
+ *
+ *   beforeEach(() => {
+ *     vi.mocked(getAlbum).mockResolvedValue(sampleAlbumWithSongs);
+ *     vi.mocked(buildStreamUrl).mockImplementation(mockStreamUrl);
+ *   });
+ *
+ * Realistic shape matters more than perfect coverage — these fixtures
+ * mirror what Navidrome actually returns for common queries.
+ */
+import type { SubsonicSong, SubsonicAlbum, SubsonicPlaylist } from '@/api/subsonic';
+import { makeSubsonicSong } from '@/test/helpers/factories';
+
+export const sampleSubsonicSong: SubsonicSong = makeSubsonicSong({
+  id: 'song-1',
+  title: 'Sample Song',
+  artist: 'Sample Artist',
+  album: 'Sample Album',
+  albumId: 'album-1',
+  artistId: 'artist-1',
+});
+
+export const sampleEmptyAlbum: SubsonicAlbum = {
+  id: 'album-empty',
+  name: 'Empty Album',
+  artist: 'Sample Artist',
+  artistId: 'artist-1',
+  songCount: 0,
+  duration: 0,
+};
+
+export const sampleAlbumWithSong: SubsonicAlbum & { song: SubsonicSong } = {
+  id: 'album-single',
+  name: 'Single-Song Album',
+  artist: 'Sample Artist',
+  artistId: 'artist-1',
+  coverArt: 'album-single',
+  songCount: 1,
+  duration: 180,
+  year: 2024,
+  song: sampleSubsonicSong,
+};
+
+export const sampleAlbumWithSongs: SubsonicAlbum & { song: SubsonicSong[] } = {
+  id: 'album-multi',
+  name: 'Multi-Track Album',
+  artist: 'Sample Artist',
+  artistId: 'artist-1',
+  coverArt: 'album-multi',
+  songCount: 3,
+  duration: 540,
+  year: 2024,
+  genre: 'Rock',
+  song: [
+    makeSubsonicSong({ id: 'song-m1', title: 'Track 1', album: 'Multi-Track Album', albumId: 'album-multi', track: 1 }),
+    makeSubsonicSong({ id: 'song-m2', title: 'Track 2', album: 'Multi-Track Album', albumId: 'album-multi', track: 2 }),
+    makeSubsonicSong({ id: 'song-m3', title: 'Track 3', album: 'Multi-Track Album', albumId: 'album-multi', track: 3 }),
+  ],
+};
+
+export const samplePlaylist: SubsonicPlaylist = {
+  id: 'pl-1',
+  name: 'Sample Playlist',
+  songCount: 2,
+  duration: 360,
+  created: '2026-01-01T00:00:00Z',
+  changed: '2026-01-15T00:00:00Z',
+  owner: 'tester',
+  public: false,
+  coverArt: 'pl-1',
+};
+
+export function mockStreamUrl(id: string): string {
+  return `https://mock.subsonic.test/rest/stream.view?id=${encodeURIComponent(id)}`;
+}
+
+export function mockCoverArtUrl(id: string, size = 256): string {
+  return `https://mock.subsonic.test/rest/getCoverArt.view?id=${encodeURIComponent(id)}&size=${size}`;
+}
+
+export function mockCoverArtCacheKey(id: string, size = 256): string {
+  return `mock-server:cover:${id}:${size}`;
+}
+
+/** Generic Subsonic error shape for tests asserting failure paths. */
+export class MockSubsonicError extends Error {
+  constructor(message: string, public readonly code = 40) {
+    super(message);
+    this.name = 'MockSubsonicError';
+  }
+}

src/test/mocks/tauri.ts

@@ -69,6 +69,17 @@ export function emitTauriEvent(event: string, payload: unknown): void {
   for (const cb of eventListeners.get(event) ?? []) cb(payload);
 }
 
+/**
+ * How many `listen()` callbacks are currently registered for `<event>`.
+ *
+ * Use for regression tests of listener lifecycle — e.g. re-initializing a
+ * store should not double-register `audio:progress` handlers. See
+ * `feedback_global_shortcut_double_fire` for the canonical motivating bug.
+ */
+export function tauriMockListenerCount(event: string): number {
+  return eventListeners.get(event)?.length ?? 0;
+}
+
 /** Clear all handlers + listeners + call counts. Wired to `beforeEach` below. */
 export function resetTauriMocks(): void {
   invokeHandlers.clear();

src/test/setup.ts

@@ -1,6 +1,7 @@
 import '@testing-library/jest-dom/vitest';
-import { afterEach, vi } from 'vitest';
+import { afterEach, beforeEach, vi } from 'vitest';
 import { cleanup } from '@testing-library/react';
+import { installBrowserMocks, resetBrowserMocks } from './mocks/browser';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Node 25 ships a native `localStorage` global that is broken on this
@@ -65,6 +66,10 @@ function installStorage(globalKey: 'localStorage' | 'sessionStorage', store: Sto
 installStorage('localStorage', memLocal);
 installStorage('sessionStorage', memSession);
 
+// Install jsdom-gap browser API mocks (ResizeObserver / IntersectionObserver /
+// matchMedia / clipboard / object URLs) so components don't crash on import.
+installBrowserMocks();
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Global Tauri mocks.
 //
@@ -93,6 +98,10 @@ vi.mock('@tauri-apps/plugin-shell', () => ({
   open: vi.fn(async () => {}),
 }));
 
+beforeEach(() => {
+  resetBrowserMocks();
+});
+
 afterEach(() => {
   cleanup();
   memLocal.clear();