feat(harness): agent-drivable dev harness and CI that gates

A coding agent could develop this repo's Go packages and could not
develop the application: every path to running YellowJacket ended in a
blocking GTK window, so 265 bound methods, 46 events, 33 component
directories and 13 stores had exactly one form of verification
available — `tsc --noEmit`.

The unlock is that `wails dev`'s dev server on :34115 serves the real
frontend with the real generated bindings against the same Go backend a
desktop window attaches to, so a plain Chromium under Xvfb gets a fully
functional app. Four test tiers now exist, cheapest first:

- `make ui-test` — 313 Vitest tests in a real browser in ~2 s, no app,
  no backend, no display. Works because `frontend/wailsjs/` is a pure
  passthrough to `window.go`/`window.runtime`, so faking just those two
  globals runs the real bindings and the real store code.
- `make test` — services in-process, asserting on the payload the
  frontend would receive, via a new `events.Emit` wrapper.
- `make dev-headless` + `playwright-cli` — the real app, driven
  interactively, with an event bridge on `window.__yjEvents` and a
  dev-only control surface at `/__test/`.
- `make e2e` — 19 of those flows frozen as Playwright specs.

`events.Emit(ctx, …)` replaces all 35 direct `runtime.EventsEmit` call
sites: wails' `getEvents` `log.Fatalf`s on any context without its
runtime, so those paths could not run under test and a background
worker could take the app down. Four packages had each hand-rolled the
same guard; nine more guarded on `ctx != nil`, which does not help.
`TestNoDirectRuntimeEmits` fails the build on a new one.

Fixtures are generated, not committed (`make testdata`), and seeds are
built by *running the app* — never by hand-writing config and DB rows,
which would be a second description of a valid YJ_HOME.

`.gitea/workflows/ci.yml` is the first workflow here that tests
anything; the other three only package, so `gitea_ci` reported only
packaging jobs and misled anyone asking whether a push was healthy.
Both jobs were prototyped to green in a bare ubuntu:24.04 container
before the YAML was written, which immediately caught `make lint`
linting three configurations that nothing builds: all three passes
omitted `webkit2_41`, so wails resolved webkit2gtk-4.0 — which Arch
still ships and Ubuntu 24.04 dropped.

Operational instructions live in `.pi/skills/yellowjacket-dev/`,
measured discoveries in `.planning/NOTES.md`, and architecture in
`CLAUDE.md` — split by tense, not by topic, because a topical split
gives every new fact two plausible homes. `make skill-check` fails a
commit if the skill cites a make target that does not exist.

frontend/test/components/chrome.test.ts

@@ -0,0 +1,282 @@
+/**
+ * The app chrome: sidebar navigation, the library filter dropdown and
+ * the tri-state library status indicator. All three are small, all
+ * three are on screen constantly, and the sidebar's testids and
+ * aria-current are what the e2e tier navigates by.
+ */
+import { describe, expect, it, beforeEach, vi, afterEach } from 'vitest';
+
+import '@components/sidebar/app-sidebar';
+import '@components/library-filter/library-filter';
+import '@components/library-status-indicator/library-status-indicator';
+import { Events } from '../../src/events';
+import { emit, stub, flush, calls, lastArgs } from '@test/support/harness';
+import {
+  fixture,
+  shadow,
+  shadowAll,
+  texts,
+  update,
+  visual,
+} from '@test/support/render';
+
+describe('<app-sidebar>', () => {
+  it('renders a testid per destination, which is how e2e navigates', async () => {
+    const el = await fixture('app-sidebar');
+
+    expect(
+      shadowAll(el, 'li').map((li) => li.getAttribute('data-testid')),
+    ).toEqual([
+      'nav-home',
+      'nav-playlists',
+      'nav-artists',
+      'nav-genres',
+      'nav-albums',
+      'nav-tracks',
+      'nav-explore',
+      'nav-downloads',
+      'nav-autotag',
+      'nav-jobs',
+      'nav-settings',
+    ]);
+  });
+
+  it('marks exactly one item as the current page', async () => {
+    const el = await fixture('app-sidebar');
+
+    const current = shadowAll(el, 'li').filter(
+      (li) => li.getAttribute('aria-current') === 'page',
+    );
+
+    expect(current).toHaveLength(1);
+  });
+
+  it('announces a navigation as a composed event, so the shell hears it through the shadow root', async () => {
+    const el = await fixture('app-sidebar');
+    const seen: string[] = [];
+
+    document.addEventListener('navigate', (e) => {
+      seen.push((e as CustomEvent<{ view: string }>).detail.view);
+    }, { once: true });
+
+    shadow<HTMLElement>(el, '[data-testid="nav-artists"]')?.click();
+    await el.updateComplete;
+
+    expect(seen).toEqual(['artists']);
+  });
+
+  it('moves aria-current to the clicked destination', async () => {
+    const el = await fixture('app-sidebar');
+
+    shadow<HTMLElement>(el, '[data-testid="nav-genres"]')?.click();
+    await el.updateComplete;
+
+    expect(
+      shadow(el, '[data-testid="nav-genres"]')?.getAttribute('aria-current'),
+    ).toBe('page');
+  });
+
+  it('looks the way it did last time', async () => {
+    const el = await fixture('app-sidebar');
+
+    await visual(el, 'app-sidebar');
+    expect(shadowAll(el, 'li').length).toBeGreaterThan(0);
+  });
+});
+
+describe('<library-filter>', () => {
+  beforeEach(() => {
+    stub('library.Library.GetAllLibrariesWithTrackCounts', [
+      { id: 7, name: 'Music' },
+      { id: 8, name: 'Field Recordings' },
+    ]);
+  });
+
+  it('offers every library plus the merged view', async () => {
+    const el = await fixture('library-filter');
+
+    await flush();
+    await el.updateComplete;
+
+    expect(texts(el, 'option')).toEqual([
+      'All Libraries',
+      'Music',
+      'Field Recordings',
+    ]);
+  });
+
+  it('carries an accessible name — it is a bare select otherwise', async () => {
+    const el = await fixture('library-filter');
+
+    expect(shadow(el, 'select')?.getAttribute('aria-label')).toBe(
+      'Library filter',
+    );
+  });
+
+  it('selects a library by id, and the merged view by empty string', async () => {
+    const el = await fixture('library-filter');
+
+    await flush();
+    await el.updateComplete;
+
+    const select = shadow<HTMLSelectElement>(el, 'select');
+
+    if (select) select.value = '8';
+
+    select?.dispatchEvent(new Event('change'));
+    await flush();
+
+    expect(lastArgs('library.Library.GetAllTracksByLibrary')).toEqual([8]);
+  });
+
+  it('picks up a library added while it was on screen', async () => {
+    const el = await fixture('library-filter');
+
+    await flush();
+    await el.updateComplete;
+
+    stub('library.Library.GetAllLibrariesWithTrackCounts', [
+      { id: 7, name: 'Music' },
+      { id: 8, name: 'Field Recordings' },
+      { id: 9, name: 'Podcasts' },
+    ]);
+    emit(Events.LibraryAdded, { id: 9 });
+    await flush();
+    await el.updateComplete;
+
+    expect(texts(el, 'option')).toContain('Podcasts');
+  });
+});
+
+describe('<library-status-indicator>', () => {
+  it('defaults to "not in library"', async () => {
+    const el = await fixture('library-status-indicator');
+
+    expect(shadow(el, 'wa-icon')?.getAttribute('name')).toBe('plus');
+  });
+
+  it('uses a distinct glyph per state', async () => {
+    const glyphs: (string | null | undefined)[] = [];
+
+    for (const status of ['in-library', 'queued', 'not-in-library']) {
+      const el = await fixture('library-status-indicator', { status });
+
+      glyphs.push(shadow(el, 'wa-icon')?.getAttribute('name'));
+    }
+
+    expect(glyphs).toEqual(['check', 'hourglass-half', 'plus']);
+  });
+
+  it('phrases its label around the entity it describes', async () => {
+    const el = await fixture('library-status-indicator', {
+      status: 'in-library',
+      entityType: 'album',
+      label: 'Abbey Road',
+    });
+
+    expect(shadow(el, 'button')?.getAttribute('aria-label')).toBe(
+      'Album "Abbey Road" is in your library',
+    );
+  });
+
+  it('phrases an unowned entity as an invitation', async () => {
+    const el = await fixture('library-status-indicator', {
+      entityType: 'artist',
+      label: 'Eno',
+    });
+
+    expect(shadow(el, 'button')?.getAttribute('aria-label')).toBe(
+      'Add artist "Eno" to library',
+    );
+  });
+
+  it('drops the quoted name when it has none', async () => {
+    const el = await fixture('library-status-indicator', { status: 'queued' });
+
+    expect(shadow(el, 'button')?.getAttribute('aria-label')).toBe(
+      'Track is queued for download',
+    );
+  });
+
+  it('mirrors the label into the tooltip', async () => {
+    const el = await fixture('library-status-indicator', {
+      status: 'in-library',
+    });
+
+    const button = shadow(el, 'button');
+
+    expect(button?.getAttribute('title')).toBe(
+      button?.getAttribute('aria-label'),
+    );
+  });
+
+  it('swallows the click, so it does not navigate the card it sits on', async () => {
+    const el = await fixture('library-status-indicator');
+    let bubbled = 0;
+
+    el.addEventListener('click', () => {
+      bubbled += 1;
+    });
+
+    shadow<HTMLElement>(el, 'button')?.click();
+
+    expect([bubbled, calls()]).toEqual([0, []]);
+  });
+
+  it('swallows Enter and Space for the same reason', async () => {
+    const el = await fixture('library-status-indicator');
+    let bubbled = 0;
+
+    el.addEventListener('keydown', () => {
+      bubbled += 1;
+    });
+
+    for (const key of ['Enter', ' ', 'Tab']) {
+      shadow(el, 'button')?.dispatchEvent(
+        new KeyboardEvent('keydown', { key, bubbles: true, composed: true }),
+      );
+    }
+
+    // Tab still gets through: it is navigation, not activation.
+    expect(bubbled).toBe(1);
+  });
+
+  it('honours a non-default size', async () => {
+    const el = await fixture('library-status-indicator', { size: 32 });
+
+    expect(el.style.getPropertyValue('--indicator-size')).toBe('32px');
+  });
+
+  it('looks the way it did last time', async () => {
+    const el = await fixture('library-status-indicator', {
+      status: 'in-library',
+    });
+
+    await update(el, { size: 40 });
+    await visual(el, 'library-status-indicator-in-library');
+    expect(shadow(el, 'button')).not.toBeNull();
+  });
+});
+
+describe('<library-filter> resilience', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('renders the merged view even when the library list cannot be loaded', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    stub('library.Library.GetAllLibrariesWithTrackCounts', () => {
+      throw new Error('database locked');
+    });
+    // The store caches the library list; drop it so the failing stub is
+    // actually reached.
+    emit(Events.LibraryRemoved, { id: 7 });
+
+    const el = await fixture('library-filter');
+
+    await flush();
+    await el.updateComplete;
+
+    expect(texts(el, 'option')).toEqual(['All Libraries']);
+  });
+});

frontend/test/components/now-playing.test.ts

@@ -0,0 +1,254 @@
+/**
+ * `<now-playing>` and `<queue-panel>` are the two components driven
+ * entirely by store state rather than by their own properties: feeding
+ * them backend events is how they are made to render anything at all.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import '@components/now-playing/now-playing';
+import '@components/queue-panel/queue-panel';
+import { Events } from '../../src/events';
+import { emit, calls, stub, flush, lastArgs } from '@test/support/harness';
+import {
+  fixture,
+  shadow,
+  shadowAll,
+  text,
+  visual,
+} from '@test/support/render';
+import type { TrackInfo } from '@store/player-store';
+import type { QueueTrack } from '@store/queue-store';
+
+const TRACK: TrackInfo = {
+  fileName: 'ashes.mp3',
+  filePath: '/music/ashes.mp3',
+  trackLength: 215,
+  seekPosition: 0,
+  state: 'playing',
+  title: 'Ashes to Ashes',
+  artist: 'David Bowie',
+  album: 'Scary Monsters',
+  coverArt: '',
+  coverArtSmall: '',
+  coverArtMedium: '',
+  coverArtLarge: '',
+  trackChangeId: 1,
+  artistMbid: '',
+  releaseGroupMbid: '',
+  recordingMbid: '',
+};
+
+function queueTrack(n: number, title: string): QueueTrack {
+  return {
+    id: n,
+    audioFileId: n,
+    filePath: `/music/${n}.mp3`,
+    position: n,
+    title,
+    artist: 'Artist',
+    album: 'Album',
+    coverArtPath: '',
+    artistMbid: '',
+    releaseGroupMbid: '',
+    recordingMbid: '',
+  };
+}
+
+function setQueue(tracks: QueueTrack[], currentIndex = 0): void {
+  emit(Events.QueueChanged, {
+    tracks,
+    currentIndex,
+    shuffleMode: false,
+    repeatMode: 'off',
+    sourcePlaylistId: 0,
+  });
+}
+
+describe('<now-playing>', () => {
+  beforeEach(() => {
+    emit(Events.TrackChanged, null);
+  });
+
+  it('shows only a placeholder when nothing is loaded', async () => {
+    const el = await fixture('now-playing');
+
+    expect([
+      shadow(el, '.cover-placeholder'),
+      shadow(el, '[data-testid="now-playing-title"]'),
+    ]).toEqual([expect.anything(), null]);
+  });
+
+  it('renders the title and artist of the loaded track', async () => {
+    const el = await fixture('now-playing');
+
+    emit(Events.TrackChanged, TRACK);
+    await flush();
+    await el.updateComplete;
+
+    expect([
+      text(el, '[data-testid="now-playing-title"]'),
+      text(el, '[data-testid="now-playing-artist"]'),
+    ]).toEqual(['Ashes to Ashes', 'David Bowie']);
+  });
+
+  it('names an artistless track rather than leaving the line blank', async () => {
+    const el = await fixture('now-playing');
+
+    emit(Events.TrackChanged, { ...TRACK, artist: '', trackChangeId: 2 });
+    await flush();
+    await el.updateComplete;
+
+    expect(text(el, '[data-testid="now-playing-artist"]')).toBe(
+      'Unknown Artist',
+    );
+  });
+
+  it('prefers the small cover variant and falls back on error', async () => {
+    const el = await fixture('now-playing');
+
+    emit(Events.TrackChanged, {
+      ...TRACK,
+      coverArt: '/covers/big.jpg',
+      coverArtSmall: '/covers/missing.jpg',
+      trackChangeId: 3,
+    });
+    await flush();
+    await el.updateComplete;
+
+    const img = shadow<HTMLImageElement>(el, '.cover-art img');
+    const initial = img?.getAttribute('src');
+
+    img?.dispatchEvent(new Event('error'));
+
+    expect([initial, img?.src.endsWith('/covers/big.jpg')]).toEqual([
+      '/covers/missing.jpg',
+      true,
+    ]);
+  });
+
+  it('offers a favourite toggle that names the target playlist', async () => {
+    stub('playlist.Service.GetDefaultPlaylistTrackPaths', []);
+    stub('playlist.Service.GetDefaultPlaylistInfo', { Name: 'Loved' });
+    emit(Events.PlaylistRenamed, 1);
+    await flush();
+
+    const el = await fixture('now-playing');
+
+    emit(Events.TrackChanged, { ...TRACK, trackChangeId: 4 });
+    await flush();
+    await el.updateComplete;
+
+    expect(shadow(el, '.fav-btn')?.getAttribute('title')).toBe('Add to Loved');
+  });
+
+  it('toggles the favourite through the backend', async () => {
+    const el = await fixture('now-playing');
+
+    emit(Events.TrackChanged, { ...TRACK, trackChangeId: 5 });
+    await flush();
+    await el.updateComplete;
+
+    shadow<HTMLElement>(el, '.fav-btn')?.click();
+    await flush();
+
+    expect(lastArgs('playlist.Service.ToggleDefaultPlaylistTrack')).toEqual([
+      '/music/ashes.mp3',
+    ]);
+  });
+
+  it('looks the way it did last time', async () => {
+    const el = await fixture('now-playing');
+
+    emit(Events.TrackChanged, { ...TRACK, trackChangeId: 6 });
+    await flush();
+    await el.updateComplete;
+
+    await visual(el, 'now-playing');
+    expect(text(el, '[data-testid="now-playing-title"]')).toBe(
+      'Ashes to Ashes',
+    );
+  });
+});
+
+describe('<queue-panel>', () => {
+  beforeEach(() => {
+    setQueue([]);
+  });
+
+  it('says so when the queue is empty', async () => {
+    const el = await fixture('queue-panel');
+
+    expect(text(el, '.empty-state p')).toBe('Queue is empty');
+  });
+
+  it('renders a row per queued track, tagged with its file path', async () => {
+    const el = await fixture('queue-panel');
+
+    setQueue([queueTrack(1, 'First'), queueTrack(2, 'Second')]);
+    await flush();
+    await el.updateComplete;
+    await new Promise((r) => {
+      requestAnimationFrame(() => r(null));
+    });
+
+    const rows = shadowAll(el, '[data-testid="queue-row"]');
+
+    expect(rows.map((r) => r.getAttribute('data-file-path'))).toEqual([
+      '/music/1.mp3',
+      '/music/2.mp3',
+    ]);
+  });
+
+  it('marks the playing row as active', async () => {
+    const el = await fixture('queue-panel');
+
+    setQueue([queueTrack(1, 'First'), queueTrack(2, 'Second')], 1);
+    await flush();
+    await el.updateComplete;
+    await new Promise((r) => {
+      requestAnimationFrame(() => r(null));
+    });
+
+    const active = shadowAll(el, '[data-testid="queue-row"].active');
+
+    expect(active.map((r) => r.getAttribute('data-index'))).toEqual(['1']);
+  });
+
+  it('disables the clear button on an empty queue', async () => {
+    const el = await fixture('queue-panel');
+
+    const button = shadow<HTMLButtonElement>(el, '.header-action-button');
+
+    expect(button?.disabled).toBe(true);
+  });
+
+  it('clears through the backend, not locally', async () => {
+    const el = await fixture('queue-panel');
+
+    setQueue([queueTrack(1, 'First')]);
+    await flush();
+    await el.updateComplete;
+
+    shadow<HTMLButtonElement>(el, '.header-action-button')?.click();
+    await flush();
+
+    expect(calls().map((c) => c.path)).toContain('queue.Queue.Clear');
+  });
+
+  // No screenshot for the queue panel: its list is a
+  // @lit-labs/virtualizer, which keeps re-measuring, so
+  // toMatchScreenshot never gets two identical frames and fails with
+  // "could not capture a stable screenshot" rather than a real diff.
+  it('keeps rendering rows after the virtualizer settles', async () => {
+    const el = await fixture('queue-panel');
+
+    setQueue([queueTrack(1, 'First'), queueTrack(2, 'Second')], 0);
+    await flush();
+    await el.updateComplete;
+    await new Promise((r) => {
+      requestAnimationFrame(() => r(null));
+    });
+
+    expect(shadowAll(el, '[data-testid="queue-row"]').length).toBe(2);
+  });
+});

frontend/test/components/smoke.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Every custom element in the tree, mounted against an empty backend.
+ *
+ * This is deliberately shallow: it asserts each component renders
+ * *something* and logs no error, which is the state an agent's change
+ * most often breaks and which nothing else here would notice. Depth
+ * belongs in the per-component specs and in e2e; breadth belongs here,
+ * because 46 elements is more than anyone will write specs for.
+ */
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+
+// One import per component module, so a component that fails to even
+// load is a failure here rather than a silent absence.
+import '@components/artist-details/artist-details';
+import '@components/artists-view/artists-view';
+import '@components/audio-player/audio-player';
+import '@components/audio-player/controls/player-controls';
+import '@components/audio-player/seekbar/seek-bar';
+import '@components/audio-player/volume-control/volume-control';
+import '@components/autotag-view/autotag-view';
+import '@components/combobox/combobox';
+import '@components/config-page/config-page';
+import '@components/config-page/config-field';
+import '@components/config-page/config-section';
+import '@components/config-page/download-clients';
+import '@components/config-page/shortcut-capture';
+import '@components/cover-grid/cover-grid';
+import '@components/cover-grid/album-dropdown';
+import '@components/download-picker/download-picker';
+import '@components/download-picker/candidate-row';
+import '@components/downloads-view/downloads-view';
+import '@components/duplicate-tracks-dialog/duplicate-tracks-dialog';
+import '@components/explore-album-details/explore-album-details';
+import '@components/explore-artist-details/explore-artist-details';
+import '@components/explore-view/explore-view';
+import '@components/first-run-wizard/first-run-wizard';
+import '@components/genre-details/genre-details';
+import '@components/genres-view/genres-view';
+import '@components/jobs/job-details-drawer';
+import '@components/jobs/job-indicator';
+import '@components/jobs/job-log-view';
+import '@components/jobs/job-row';
+import '@components/jobs/jobs-view';
+import '@components/library-filter/library-filter';
+import '@components/library-status-indicator/library-status-indicator';
+import '@components/now-playing/now-playing';
+import '@components/phantom-resolver/phantom-resolver';
+import '@components/playlist-details/playlist-details';
+import '@components/playlist-picker/playlist-picker';
+import '@components/playlist-view/playlist-view';
+import '@components/queue-panel/queue-panel';
+import '@components/search-bar/search-bar';
+import '@components/sidebar/app-sidebar';
+import '@components/smart-playlist-details/smart-playlist-details';
+import '@components/smart-playlist-editor/smart-playlist-editor';
+import '@components/top-results-row/top-results-row';
+import '@components/track-details/track-details';
+import '@components/track-info/track-info';
+import '@components/track-list/track-list';
+
+import { flush, stub } from '@test/support/harness';
+import { fixture } from '@test/support/render';
+
+/** Every element the app registers, in registration order. */
+const TAGS = [
+  'album-dropdown',
+  'app-sidebar',
+  'artist-details',
+  'artists-view',
+  'audio-player',
+  'autotag-view',
+  'candidate-row',
+  'config-field',
+  'config-page',
+  'config-section',
+  'cover-grid',
+  'download-clients',
+  'download-picker',
+  'downloads-view',
+  'duplicate-tracks-dialog',
+  'explore-album-details',
+  'explore-artist-details',
+  'explore-view',
+  'first-run-wizard',
+  'genre-details',
+  'genres-view',
+  'job-details-drawer',
+  'job-indicator',
+  'job-log-view',
+  'job-row',
+  'jobs-view',
+  'library-filter',
+  'library-status-indicator',
+  'now-playing',
+  'phantom-resolver',
+  'player-controls',
+  'playlist-details',
+  'playlist-picker',
+  'playlist-view',
+  'queue-panel',
+  'search-bar',
+  'seek-bar',
+  'shortcut-capture',
+  'smart-playlist-details',
+  'smart-playlist-editor',
+  'top-results-row',
+  'track-details',
+  'track-info',
+  'track-list',
+  'volume-control',
+  'yj-combobox',
+];
+
+/**
+ * An empty-but-valid backend. Unstubbed bindings resolve undefined,
+ * which is not what Go sends — an empty list is.
+ */
+function stubEmptyBackend(): void {
+  const emptyLists = [
+    'library.Library.GetAllTracks',
+    'library.Library.GetAllAlbums',
+    'library.Library.GetAllArtists',
+    'library.Library.GetAllGenresWithCounts',
+    'library.Library.GetAllLibrariesWithTrackCounts',
+    'playlist.Service.GetAllPlaylists',
+    'playlist.Service.GetAllPlaylistsWithTracks',
+    'playlist.Service.GetDefaultPlaylistTrackPaths',
+    'jobs.Service.GetJobs',
+    'download.Service.ListProviders',
+    'download.Service.ListDownloads',
+    'download.Service.ListRequests',
+    'download.Service.ProviderKinds',
+  ];
+
+  for (const path of emptyLists) stub(path, []);
+
+  stub('config.Config.GetShortcuts', {});
+  stub('config.Config.GetDownloadPreferences', {});
+  stub('config.Config.GetThemeAccentColor', '#ffd43b');
+  stub('config.Config.GetThemeBackgroundShade', 'dark');
+}
+
+describe('every component mounts on an empty library', () => {
+  let errors: unknown[][] = [];
+
+  beforeEach(() => {
+    stubEmptyBackend();
+    errors = [];
+    vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => {
+      errors.push(args);
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('registers every element it defines', () => {
+    const missing = TAGS.filter((tag) => !customElements.get(tag));
+
+    expect(missing).toEqual([]);
+  });
+
+  for (const tag of TAGS) {
+    it(`<${tag}> renders without logging an error`, async () => {
+      const el = await fixture(tag);
+
+      await flush();
+      await el.updateComplete;
+
+      expect({ tag, root: el.shadowRoot !== null, errors }).toEqual({
+        tag,
+        root: true,
+        errors: [],
+      });
+    });
+  }
+});

frontend/test/components/track-info.test.ts

@@ -0,0 +1,160 @@
+/**
+ * `<track-info>` is the shared row renderer: every list that shows a
+ * track goes through it, so its fallbacks (missing title, missing
+ * cover, missing duration) are visible in half the app.
+ */
+import { describe, expect, it } from 'vitest';
+
+import '@components/track-info/track-info';
+import { fixture, shadow, text, update, visual } from '@test/support/render';
+
+describe('<track-info>', () => {
+  it('renders title, artist and album', async () => {
+    const el = await fixture('track-info', {
+      trackTitle: 'Ashes to Ashes',
+      artist: 'David Bowie',
+      album: 'Scary Monsters',
+    });
+
+    expect([text(el, '.title'), text(el, '.secondary')]).toEqual([
+      'Ashes to Ashes',
+      'David Bowie — Scary Monsters',
+    ]);
+  });
+
+  it('joins artist and album with an em dash, and omits the separator when one is missing', async () => {
+    const el = await fixture('track-info', {
+      trackTitle: 'X',
+      artist: 'Only Artist',
+    });
+
+    expect(text(el, '.secondary')).toBe('Only Artist');
+  });
+
+  it('omits the secondary line entirely when there is nothing to put in it', async () => {
+    const el = await fixture('track-info', { trackTitle: 'X' });
+
+    expect(shadow(el, '.secondary')).toBeNull();
+  });
+
+  it('falls back to the filename, without its extension, when untitled', async () => {
+    // WAV tracks currently scan in untitled, so this path is live.
+    const el = await fixture('track-info', {
+      filePath: '/music/field/01 - Dawn Chorus.wav',
+    });
+
+    expect(text(el, '.title')).toBe('01 - Dawn Chorus');
+  });
+
+  it('handles a Windows path in the same fallback', async () => {
+    const el = await fixture('track-info', {
+      filePath: 'C:\\Music\\Album\\Track.mp3',
+    });
+
+    expect(text(el, '.title')).toBe('Track');
+  });
+
+  it('prefers a real title over the filename', async () => {
+    const el = await fixture('track-info', {
+      trackTitle: 'Real Title',
+      filePath: '/music/whatever.mp3',
+    });
+
+    expect(text(el, '.title')).toBe('Real Title');
+  });
+
+  it('renders no title element at all when it has neither title nor path', async () => {
+    const el = await fixture('track-info', { artist: 'Someone' });
+
+    expect(shadow(el, '.title')).toBeNull();
+  });
+
+  it('formats a duration given in milliseconds', async () => {
+    const el = await fixture('track-info', {
+      trackTitle: 'X',
+      duration: '215000',
+    });
+
+    expect(text(el, '.duration')).toBe('03:35');
+  });
+
+  it('shows placeholder dashes for an unparseable duration', async () => {
+    const el = await fixture('track-info', {
+      trackTitle: 'X',
+      duration: 'unknown',
+    });
+
+    expect(text(el, '.duration')).toBe('--:--');
+  });
+
+  it('omits the duration column when there is no duration', async () => {
+    const el = await fixture('track-info', { trackTitle: 'X' });
+
+    expect(shadow(el, '.duration')).toBeNull();
+  });
+
+  it('shows no cover slot at all unless a cover was supplied', async () => {
+    const el = await fixture('track-info', { trackTitle: 'X' });
+
+    expect(shadow(el, '.cover-art')).toBeNull();
+  });
+
+  it('prefers the small cover variant, which is what a row needs', async () => {
+    const el = await fixture('track-info', {
+      trackTitle: 'X',
+      coverArt: '/covers/big.jpg',
+      coverArtSmall: '/covers/small.jpg',
+    });
+
+    expect(shadow<HTMLImageElement>(el, '.cover-art img')?.getAttribute('src')).toBe(
+      '/covers/small.jpg',
+    );
+  });
+
+  it('falls back to the full-size cover when the thumbnail fails to load', async () => {
+    const el = await fixture('track-info', {
+      trackTitle: 'X',
+      coverArt: '/covers/big.jpg',
+      coverArtSmall: '/covers/missing.jpg',
+    });
+
+    const img = shadow<HTMLImageElement>(el, '.cover-art img');
+
+    img?.dispatchEvent(new Event('error'));
+
+    expect(img?.src).toContain('/covers/big.jpg');
+  });
+
+  it('degrades to the music-note placeholder when both covers fail', async () => {
+    const el = await fixture('track-info', {
+      trackTitle: 'X',
+      coverArtSmall: '/covers/missing.jpg',
+    });
+
+    const img = shadow<HTMLImageElement>(el, '.cover-art img');
+
+    img?.dispatchEvent(new Event('error'));
+
+    expect(shadow(el, '.cover-placeholder wa-icon')).not.toBeNull();
+  });
+
+  it('re-renders when a property changes', async () => {
+    const el = await fixture('track-info', { trackTitle: 'Before' });
+
+    await update(el, { trackTitle: 'After' });
+
+    expect(text(el, '.title')).toBe('After');
+  });
+
+  it('looks the way it did last time', async () => {
+    const el = await fixture('track-info', {
+      trackTitle: 'Ashes to Ashes',
+      artist: 'David Bowie',
+      album: 'Scary Monsters',
+      duration: '215000',
+    });
+
+    await visual(el, 'track-info');
+    expect(el.shadowRoot).not.toBeNull();
+  });
+});

frontend/test/components/transport.test.ts

@@ -0,0 +1,312 @@
+/**
+ * The transport bar: five buttons and a seek bar, all of them driven by
+ * backend push events rather than by their own clicks. These are the
+ * controls the e2e tier drives by accessible name, so the names are as
+ * much of a contract as the behaviour.
+ */
+import { describe, expect, it, beforeEach, vi, afterEach } from 'vitest';
+
+import '@components/audio-player/controls/player-controls';
+import '@components/audio-player/seekbar/seek-bar';
+import { Events } from '../../src/events';
+import { emit, calls, lastArgs, flush } from '@test/support/harness';
+import {
+  fixture,
+  shadow,
+  shadowAll,
+  text,
+  click,
+  visual,
+} from '@test/support/render';
+import type { TrackInfo } from '@store/player-store';
+
+const TRACK: TrackInfo = {
+  fileName: 'long.mp3',
+  filePath: '/music/long.mp3',
+  trackLength: 90,
+  seekPosition: 0,
+  state: 'playing',
+  title: 'Long Player',
+  artist: 'Test Artist',
+  album: 'Fixtures',
+  coverArt: '',
+  coverArtSmall: '',
+  coverArtMedium: '',
+  coverArtLarge: '',
+  trackChangeId: 1,
+  artistMbid: '',
+  releaseGroupMbid: '',
+  recordingMbid: '',
+};
+
+/** Reset the backend-owned state both components read from. */
+function idle(): void {
+  emit(Events.TrackChanged, null);
+  emit(Events.PlaybackStateChanged, { state: 'stopped' });
+  emit(Events.QueueModeChanged, { shuffleMode: false, repeatMode: 'off' });
+}
+
+function labelOf(host: Element, index: number): string | null {
+  return shadowAll(host, 'button')[index]?.getAttribute('aria-label') ?? null;
+}
+
+describe('<player-controls>', () => {
+  beforeEach(() => {
+    idle();
+  });
+
+  it('names every button, so both a screen reader and a selector can find it', async () => {
+    const el = await fixture('player-controls');
+
+    expect(shadowAll(el, 'button').map((b) => b.getAttribute('aria-label'))).toEqual(
+      ['Shuffle', 'Previous track', 'Play', 'Next track', 'Repeat: off'],
+    );
+  });
+
+  it('becomes a pause button while playing', async () => {
+    const el = await fixture('player-controls');
+
+    emit(Events.PlaybackStateChanged, { state: 'playing' });
+    await flush();
+    await el.updateComplete;
+
+    expect([labelOf(el, 2), shadow(el, 'wa-icon[name="pause"]')]).not.toContain(
+      null,
+    );
+  });
+
+  it('asks the queue to play, not the player — the queue owns what plays next', async () => {
+    const el = await fixture('player-controls');
+
+    await click(el, 'button[aria-label="Play"]');
+
+    expect(calls().map((c) => c.path)).toEqual(['queue.Queue.Play']);
+  });
+
+  it('pauses through the player once playing', async () => {
+    const el = await fixture('player-controls');
+
+    emit(Events.PlaybackStateChanged, { state: 'playing' });
+    await flush();
+    await el.updateComplete;
+    await click(el, 'button[aria-label="Pause"]');
+
+    expect(calls().map((c) => c.path)).toEqual(['player.Player.Pause']);
+  });
+
+  it('wires skip forward and back to the queue', async () => {
+    const el = await fixture('player-controls');
+
+    await click(el, 'button[aria-label="Next track"]');
+    await click(el, 'button[aria-label="Previous track"]');
+
+    expect(calls().map((c) => c.path)).toEqual([
+      'queue.Queue.Next',
+      'queue.Queue.Previous',
+    ]);
+  });
+
+  it('reports shuffle state through aria-pressed, not just colour', async () => {
+    const el = await fixture('player-controls');
+    const before = shadow(el, 'button[aria-label="Shuffle"]')?.getAttribute(
+      'aria-pressed',
+    );
+
+    emit(Events.QueueModeChanged, { shuffleMode: true, repeatMode: 'off' });
+    await flush();
+    await el.updateComplete;
+
+    expect([
+      before,
+      shadow(el, 'button[aria-label="Shuffle"]')?.getAttribute('aria-pressed'),
+    ]).toEqual(['false', 'true']);
+  });
+
+  it('spells the repeat mode into the label, since one icon covers three states', async () => {
+    const el = await fixture('player-controls');
+
+    emit(Events.QueueModeChanged, { shuffleMode: false, repeatMode: 'one' });
+    await flush();
+    await el.updateComplete;
+
+    expect(labelOf(el, 4)).toBe('Repeat: one');
+  });
+
+  it('marks repeat-one so its badge renders', async () => {
+    const el = await fixture('player-controls');
+
+    emit(Events.QueueModeChanged, { shuffleMode: false, repeatMode: 'one' });
+    await flush();
+    await el.updateComplete;
+
+    expect(shadow(el, 'button.repeat-one')).not.toBeNull();
+  });
+
+  it('does not toggle its own state — the backend confirms it', async () => {
+    const el = await fixture('player-controls');
+
+    await click(el, 'button[aria-label="Shuffle"]');
+
+    expect([
+      calls().map((c) => c.path),
+      shadow(el, 'button[aria-label="Shuffle"]')?.getAttribute('aria-pressed'),
+    ]).toEqual([['queue.Queue.ToggleShuffle'], 'false']);
+  });
+
+  it('stops listening to the queue once removed', async () => {
+    const el = await fixture('player-controls');
+
+    el.remove();
+    emit(Events.QueueModeChanged, { shuffleMode: true, repeatMode: 'all' });
+    await flush();
+
+    // A leaked subscription would keep rendering a detached element.
+    expect(el.isConnected).toBe(false);
+  });
+
+  it('looks the way it did last time', async () => {
+    const el = await fixture('player-controls');
+
+    emit(Events.QueueModeChanged, { shuffleMode: true, repeatMode: 'one' });
+    await flush();
+    await el.updateComplete;
+
+    await visual(el, 'player-controls');
+    expect(shadowAll(el, 'button')).toHaveLength(5);
+  });
+});
+
+describe('<seek-bar>', () => {
+  beforeEach(() => {
+    idle();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('shows placeholder clocks with nothing loaded', async () => {
+    const el = await fixture('seek-bar');
+
+    expect([
+      text(el, '[data-testid="elapsed-time"]'),
+      text(el, '[data-testid="remaining-time"]'),
+    ]).toEqual(['--:--', '--:--']);
+  });
+
+  it('shows elapsed and remaining once a track is loaded', async () => {
+    const el = await fixture('seek-bar');
+
+    emit(Events.TrackChanged, TRACK);
+    await flush();
+    await el.updateComplete;
+
+    expect([
+      text(el, '[data-testid="elapsed-time"]'),
+      text(el, '[data-testid="remaining-time"]'),
+    ]).toEqual(['00:00', '01:30']);
+  });
+
+  it('resumes mid-track from the position the backend reported', async () => {
+    const el = await fixture('seek-bar');
+
+    emit(Events.TrackChanged, { ...TRACK, seekPosition: 30, trackChangeId: 2 });
+    await flush();
+    await el.updateComplete;
+
+    expect(text(el, '[data-testid="elapsed-time"]')).toBe('00:30');
+  });
+
+  it('rewinds when the same file plays again, which only the change id reveals', async () => {
+    const el = await fixture('seek-bar');
+
+    emit(Events.TrackChanged, { ...TRACK, seekPosition: 45, trackChangeId: 3 });
+    await flush();
+    await el.updateComplete;
+
+    emit(Events.TrackChanged, { ...TRACK, seekPosition: 0, trackChangeId: 4 });
+    await flush();
+    await el.updateComplete;
+
+    expect(text(el, '[data-testid="elapsed-time"]')).toBe('00:00');
+  });
+
+  it('ticks the clock forward while playing', async () => {
+    vi.useFakeTimers();
+
+    const el = await fixture('seek-bar');
+
+    emit(Events.TrackChanged, TRACK);
+    emit(Events.PlaybackStateChanged, { state: 'playing' });
+    await vi.advanceTimersByTimeAsync(0);
+    await el.updateComplete;
+
+    await vi.advanceTimersByTimeAsync(3000);
+    await el.updateComplete;
+
+    expect(text(el, '[data-testid="elapsed-time"]')).toBe('00:03');
+  });
+
+  it('stops ticking when paused', async () => {
+    vi.useFakeTimers();
+
+    const el = await fixture('seek-bar');
+
+    emit(Events.TrackChanged, TRACK);
+    emit(Events.PlaybackStateChanged, { state: 'playing' });
+    await vi.advanceTimersByTimeAsync(2000);
+    await el.updateComplete;
+
+    emit(Events.PlaybackStateChanged, { state: 'paused' });
+    await vi.advanceTimersByTimeAsync(0);
+    await el.updateComplete;
+    await vi.advanceTimersByTimeAsync(5000);
+    await el.updateComplete;
+
+    expect(text(el, '[data-testid="elapsed-time"]')).toBe('00:02');
+  });
+
+  it('seeks to the position the slider was dropped at', async () => {
+    const el = await fixture('seek-bar');
+
+    emit(Events.TrackChanged, TRACK);
+    await flush();
+    await el.updateComplete;
+
+    const slider = shadow<HTMLElement & { value: number }>(el, 'wa-slider');
+
+    if (slider) slider.value = 42;
+
+    slider?.dispatchEvent(new Event('change'));
+    await el.updateComplete;
+
+    expect(lastArgs('player.Player.Seek')).toEqual([42]);
+  });
+
+  it('bounds the slider by the track length', async () => {
+    const el = await fixture('seek-bar');
+
+    emit(Events.TrackChanged, TRACK);
+    await flush();
+    await el.updateComplete;
+
+    expect(shadow(el, 'wa-slider')?.getAttribute('max')).toBe('90');
+  });
+
+  it('carries an accessible name, since it is otherwise an unlabelled slider', async () => {
+    const el = await fixture('seek-bar');
+
+    expect(shadow(el, 'wa-slider')?.getAttribute('aria-label')).toBe('Seek');
+  });
+
+  it('looks the way it did last time', async () => {
+    const el = await fixture('seek-bar');
+
+    emit(Events.TrackChanged, { ...TRACK, seekPosition: 30, trackChangeId: 9 });
+    await flush();
+    await el.updateComplete;
+
+    await visual(el, 'seek-bar');
+    expect(text(el, '[data-testid="elapsed-time"]')).toBe('00:30');
+  });
+});

frontend/test/harness.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Self-tests for the component tier, in the spirit of e2e/specs/
+ * harness.spec.ts: prove the rig is what it claims before trusting a
+ * single assertion built on it.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { Events } from '../src/events';
+import { emit, calls, wails, flush } from '@test/support/harness';
+// Importing a store must be enough to make it start listening.
+import { queueStore } from '@store/queue-store';
+
+describe('component-tier harness', () => {
+  it('runs in a real browser with a real shadow DOM', () => {
+    const host = document.createElement('div');
+
+    host.attachShadow({ mode: 'open' }).innerHTML = '<b>x</b>';
+
+    expect(host.shadowRoot?.querySelector('b')?.textContent).toBe('x');
+  });
+
+  it('routes generated bindings through the fake, not a module mock', async () => {
+    // The import path under test is the real generated stub, which does
+    // window['go']['queue']['Queue']['GetState']().
+    const Queue = await import('@go/queue/Queue');
+
+    wails.stub('queue.Queue.GetState', { currentIndex: 4 });
+
+    await expect(Queue.GetState()).resolves.toEqual({ currentIndex: 4 });
+    expect(calls('queue.Queue.GetState')).toHaveLength(1);
+  });
+
+  it('resolves an unstubbed binding instead of hanging', async () => {
+    const Queue = await import('@go/queue/Queue');
+
+    // The real trap this pays for is the reverse: a *real* binding
+    // called with wrong argument types never settles. Here, silence is
+    // an immediate undefined so a test fails on the assertion rather
+    // than on a timeout.
+    await expect(Queue.Play()).resolves.toBeUndefined();
+  });
+
+  it('registers listeners merely by importing a store', () => {
+    expect(wails.listenerNames()).toContain(Events.QueueChanged);
+  });
+
+  it('delivers events to store listeners with their payload', () => {
+    emit(Events.QueueIndexChanged, { currentIndex: 11 });
+
+    expect(queueStore.getState().currentIndex).toBe(11);
+  });
+
+  it('expires a once-listener after a single delivery', () => {
+    let fired = 0;
+
+    wails.on('SyntheticEvent', () => {
+      fired += 1;
+    }, 1);
+
+    wails.notify('SyntheticEvent', []);
+    wails.notify('SyntheticEvent', []);
+
+    expect(fired).toBe(1);
+  });
+
+  it('notifies local listeners on a frontend-side EventsEmit', async () => {
+    // Wails' own runtime notifies JS listeners before it notifies Go
+    // (desktop/events.js), so a frontend emit is observable in-page.
+    const { EventsEmit } = await import('@runtime/runtime');
+    let seen: unknown;
+
+    wails.on('SyntheticEmit', (data) => {
+      seen = data;
+    }, -1);
+
+    EventsEmit('SyntheticEmit', 42);
+
+    expect(seen).toBe(42);
+  });
+
+  it('flushes the microtask queue stores notify on', async () => {
+    let notified = false;
+
+    const off = queueStore.subscribe(() => {
+      notified = true;
+    });
+
+    emit(Events.QueueIndexChanged, { currentIndex: 1 });
+    const beforeFlush = notified;
+
+    await flush();
+    off();
+
+    expect([beforeFlush, notified]).toEqual([false, true]);
+  });
+});

frontend/test/setup.ts

@@ -0,0 +1,69 @@
+/**
+ * Runs before every test module. Two jobs, in this order:
+ *
+ *  1. Install the Wails fake. Store singletons call `EventsOn` and load
+ *     from the backend *in their constructors*, which run when a test
+ *     module imports them — so the globals have to exist first.
+ *  2. Point Web Awesome at its assets. Without this every `<wa-icon>`
+ *     silently 404s and screenshots come out with holes in them.
+ */
+import { afterEach, beforeEach } from 'vitest';
+import { setBasePath } from '@awesome.me/webawesome/dist/webawesome.js';
+import '@awesome.me/webawesome/dist/styles/themes/default.css';
+import { installWailsFake, wails } from './support/wails-fake';
+import { resetHarness } from './support/harness';
+import { cleanupFixtures } from './support/render';
+
+installWailsFake();
+
+/**
+ * A few stores read config in their constructor, which runs when a test
+ * module imports them — before any test has had a chance to stub. An
+ * unstubbed binding resolves undefined, and `themeStore` in particular
+ * then derives a colour ramp from `undefined` and throws inside its own
+ * failure handler. These defaults keep import-time loads on the happy
+ * path; tests still stub whatever they assert on.
+ */
+const importTimeDefaults: Array<[string, unknown]> = [
+  ['config.Config.GetThemeAccentColor', '#ffd43b'],
+  ['config.Config.GetThemeBackgroundShade', 'dark'],
+  ['config.Config.GetShortcuts', {}],
+  // libraryStore and playlistStore fetch eagerly at import. Left
+  // unstubbed they would cache `undefined` — not the empty list Go
+  // sends — and every consumer would then crash on `.length`.
+  ['library.Library.GetAllTracks', []],
+  ['library.Library.GetAllAlbums', []],
+  ['library.Library.GetAllArtists', []],
+  ['library.Library.GetAllGenresWithCounts', []],
+  ['library.Library.GetAllLibrariesWithTrackCounts', []],
+  ['playlist.Service.GetAllPlaylistsWithTracks', []],
+];
+
+for (const [path, value] of importTimeDefaults) {
+  wails.stub(path, value);
+}
+
+// Vite serves the dependency's own directory, so icons resolve from
+// node_modules rather than from the built `dist/webawesome` copy the
+// app uses.
+setBasePath('/node_modules/@awesome.me/webawesome/dist');
+
+// index.ts imports the theme store for its side effect: it derives the
+// --yj-* custom properties and applies them to :root, where every
+// shadow root inherits them. Without it a component renders white text
+// on a white page and screenshots come out blank.
+await import('@store/theme-store');
+
+// The app's surface colours come from index.css, whose grid layout is
+// not wanted here — take the two declarations that matter.
+document.body.style.backgroundColor = 'var(--yj-bg-base, black)';
+document.body.style.color = 'var(--yj-text-primary, white)';
+document.body.style.margin = '0';
+
+beforeEach(() => {
+  resetHarness();
+});
+
+afterEach(() => {
+  cleanupFixtures();
+});

frontend/test/stores/download-store.test.ts

@@ -0,0 +1,344 @@
+/**
+ * The download store is mostly event-driven refreshes plus a set of
+ * pure formatters the downloads list and the picker share — they exist
+ * so those two views cannot disagree about what a state is called, and
+ * that only holds if both are tested against the same expectations.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import {
+  downloadStore,
+  isDownloadTerminal,
+  stateLabel,
+  scorePercent,
+  candidateSummary,
+  formatBytes,
+  type DownloadView,
+  type DownloadCandidate,
+  type DownloadProvider,
+  type Request,
+} from '@store/download-store';
+import { Events } from '../../src/events';
+import {
+  emit,
+  calls,
+  stub,
+  flush,
+  lastArgs,
+  resetHarness,
+} from '@test/support/harness';
+
+function view(id: string, state: string): DownloadView {
+  return { id, state } as DownloadView;
+}
+
+function provider(id: number, enabled: boolean): DownloadProvider {
+  return { id, name: `p${id}`, enabled, kind: 'test' } as DownloadProvider;
+}
+
+function request(overrides: Partial<Request>): Request {
+  return {
+    id: 1,
+    mbid: 'abc',
+    entity: 'release-group',
+    state: 'wanted',
+    ...overrides,
+  } as Request;
+}
+
+function candidate(overrides: Partial<DownloadCandidate>): DownloadCandidate {
+  return { id: 'c', totalSize: 0, origin: '', ...overrides } as DownloadCandidate;
+}
+
+describe('download formatters', () => {
+  it('treats complete, cancelled and failed as terminal', () => {
+    expect(
+      ['complete', 'cancelled', 'failed', 'grabbing'].map((s) =>
+        isDownloadTerminal(view('d', s)),
+      ),
+    ).toEqual([true, true, true, false]);
+  });
+
+  it('labels every lifecycle state in the user’s terms', () => {
+    expect([
+      stateLabel('found'),
+      stateLabel('grabbing'),
+      stateLabel('importing'),
+    ]).toEqual(['Waiting for you to choose', 'Downloading', 'Importing']);
+  });
+
+  it('passes an unknown state through rather than showing a blank', () => {
+    expect(stateLabel('teleporting')).toBe('teleporting');
+  });
+
+  it('rounds a score to whole percent', () => {
+    expect([scorePercent(0), scorePercent(0.876), scorePercent(1)]).toEqual([
+      '0%',
+      '88%',
+      '100%',
+    ]);
+  });
+
+  it('scales bytes to the largest unit that fits', () => {
+    expect([
+      formatBytes(512),
+      formatBytes(1024),
+      formatBytes(5.5 * 1024 * 1024),
+      formatBytes(20 * 1024 * 1024 * 1024),
+    ]).toEqual(['512 B', '1.0 KB', '5.5 MB', '20 GB']);
+  });
+
+  it('renders no size at all rather than "0 B"', () => {
+    expect([formatBytes(0), formatBytes(-1)]).toEqual(['', '']);
+  });
+
+  it('summarises a single-format candidate', () => {
+    expect(
+      candidateSummary(
+        candidate({
+          files: [
+            { isAudio: true, format: 'flac' },
+            { isAudio: true, format: 'flac' },
+            { isAudio: false, format: 'jpg' },
+          ],
+          totalSize: 300 * 1024 * 1024,
+          origin: 'Example',
+        } as Partial<DownloadCandidate>),
+      ),
+    ).toBe('FLAC · 2 tracks · 300 MB · Example');
+  });
+
+  it('flags a mixed-format candidate instead of naming one format', () => {
+    expect(
+      candidateSummary(
+        candidate({
+          files: [
+            { isAudio: true, format: 'flac' },
+            { isAudio: true, format: 'mp3' },
+          ],
+        } as Partial<DownloadCandidate>),
+      ),
+    ).toBe('Mixed formats · 2 tracks');
+  });
+
+  it('singularises a one-track candidate', () => {
+    expect(
+      candidateSummary(
+        candidate({
+          files: [{ isAudio: true, format: 'mp3' }],
+        } as Partial<DownloadCandidate>),
+      ),
+    ).toBe('MP3 · 1 track');
+  });
+
+  it('survives a candidate with no file list at all', () => {
+    expect(candidateSummary(candidate({}))).toBe('');
+  });
+});
+
+describe('download store: event-driven refresh', () => {
+  beforeEach(async () => {
+    stub('download.Service.ListProviders', []);
+    stub('download.Service.ListDownloads', []);
+    stub('download.Service.ListRequests', []);
+    stub('download.Service.ProviderKinds', []);
+    await downloadStore.init();
+    await flush();
+    resetHarness();
+    stub('download.Service.ListProviders', [
+      provider(1, true),
+      provider(2, false),
+    ]);
+    stub('download.Service.ListDownloads', [
+      view('a', 'grabbing'),
+      view('b', 'complete'),
+    ]);
+    stub('download.Service.ListRequests', [
+      request({ id: 1, mbid: 'abc', state: 'wanted' }),
+      request({ id: 2, mbid: 'def', state: 'satisfied' }),
+      request({ id: 3, mbid: 'ghi', entity: 'artist' }),
+    ]);
+  });
+
+  it('reloads providers when the backend says they changed', async () => {
+    emit(Events.DownloadProvidersChanged);
+    await flush();
+
+    expect(downloadStore.providers).toHaveLength(2);
+  });
+
+  it('reloads downloads on DownloadsChanged', async () => {
+    emit(Events.DownloadsChanged);
+    await flush();
+
+    expect(downloadStore.downloads.map((d) => d.id)).toEqual(['a', 'b']);
+  });
+
+  it('reloads requests, which change without the user doing anything', async () => {
+    // A background reconcile pass expands an artist or retires a want,
+    // so the list is push-driven rather than fetched on mount.
+    emit(Events.RequestsChanged);
+    await flush();
+
+    expect(downloadStore.requests).toHaveLength(3);
+  });
+
+  it('offers downloading only when a provider is enabled', async () => {
+    emit(Events.DownloadProvidersChanged);
+    await flush();
+    const withEnabled = downloadStore.available;
+
+    stub('download.Service.ListProviders', [provider(2, false)]);
+    emit(Events.DownloadProvidersChanged);
+    await flush();
+
+    expect([withEnabled, downloadStore.available]).toEqual([true, false]);
+  });
+
+  it('separates active downloads from finished ones', async () => {
+    emit(Events.DownloadsChanged);
+    await flush();
+
+    expect(downloadStore.activeDownloads.map((d) => d.id)).toEqual(['a']);
+  });
+
+  it('separates outstanding requests and artist subscriptions', async () => {
+    emit(Events.RequestsChanged);
+    await flush();
+
+    expect({
+      active: downloadStore.activeRequests.map((r) => r.id),
+      subscriptions: downloadStore.subscriptions.map((r) => r.id),
+    }).toEqual({ active: [1, 3], subscriptions: [3] });
+  });
+
+  it('survives a null list, which Go sends when nothing exists', async () => {
+    stub('download.Service.ListDownloads', null);
+    emit(Events.DownloadsChanged);
+    await flush();
+
+    expect(downloadStore.downloads).toEqual([]);
+  });
+
+  it('keeps the last good list when a refresh fails', async () => {
+    emit(Events.DownloadsChanged);
+    await flush();
+
+    stub('download.Service.ListDownloads', () => {
+      throw new Error('backend down');
+    });
+    emit(Events.DownloadsChanged);
+    await flush();
+
+    expect(downloadStore.downloads).toHaveLength(2);
+  });
+
+  it('coalesces three refreshes into one notification', async () => {
+    let notifications = 0;
+    const off = downloadStore.subscribe(() => {
+      notifications += 1;
+    });
+
+    emit(Events.DownloadProvidersChanged);
+    emit(Events.DownloadsChanged);
+    emit(Events.RequestsChanged);
+    await flush();
+    off();
+
+    expect(notifications).toBe(1);
+  });
+});
+
+describe('download store: request lookup', () => {
+  beforeEach(async () => {
+    stub('download.Service.ListRequests', [
+      request({ id: 1, mbid: 'abc-123', state: 'wanted' }),
+    ]);
+    emit(Events.RequestsChanged);
+    await flush();
+    resetHarness();
+    stub('download.Service.ListRequests', [
+      request({ id: 1, mbid: 'abc-123', state: 'wanted' }),
+    ]);
+  });
+
+  it('answers from the cached list, synchronously enough to render with', () => {
+    expect([
+      downloadStore.isRequested('abc-123'),
+      downloadStore.isRequested('nope'),
+    ]).toEqual([true, false]);
+  });
+
+  it('normalises case and whitespace in the MBID it is given', () => {
+    expect(downloadStore.isRequested('  ABC-123 ')).toBe(true);
+  });
+
+  it('returns the request itself for the caller that needs its state', () => {
+    expect(downloadStore.requestFor('abc-123')?.id).toBe(1);
+  });
+});
+
+describe('download store: writes refresh what they changed', () => {
+  beforeEach(async () => {
+    stub('download.Service.ListProviders', []);
+    stub('download.Service.ListDownloads', []);
+    stub('download.Service.ListRequests', []);
+    await flush();
+    resetHarness();
+    stub('download.Service.ListProviders', []);
+    stub('download.Service.ListDownloads', []);
+    stub('download.Service.ListRequests', []);
+  });
+
+  it('refreshes providers after adding one', async () => {
+    stub('download.Service.AddProvider', 5);
+
+    await expect(
+      downloadStore.addProvider('sab', 'Local', { url: 'http://x' }),
+    ).resolves.toBe(5);
+    expect(calls().map((c) => c.path)).toEqual([
+      'download.Service.AddProvider',
+      'download.Service.ListProviders',
+    ]);
+  });
+
+  it('refreshes downloads after picking a candidate', async () => {
+    await downloadStore.pick('d1', 'c1');
+
+    expect([
+      lastArgs('download.Service.Pick'),
+      calls('download.Service.ListDownloads'),
+    ]).toEqual([['d1', 'c1'], [{ path: 'download.Service.ListDownloads', args: [50] }]]);
+  });
+
+  it('refreshes requests after removing one', async () => {
+    await downloadStore.removeRequest(3);
+
+    expect(calls().map((c) => c.path)).toEqual([
+      'download.Service.RemoveRequest',
+      'download.Service.ListRequests',
+    ]);
+  });
+
+  it('refreshes both lists after a manual reconcile, since it can start downloads', async () => {
+    stub('download.Service.ReconcileRequests', { added: 1 });
+
+    await downloadStore.reconcileRequests();
+
+    expect(calls().map((c) => c.path).sort()).toEqual([
+      'download.Service.ListDownloads',
+      'download.Service.ListRequests',
+      'download.Service.ReconcileRequests',
+    ]);
+  });
+
+  it('propagates a provider test failure, which is the user’s only clue', async () => {
+    stub('download.Service.TestProvider', () => {
+      throw new Error('connection refused');
+    });
+
+    await expect(downloadStore.testProvider(1)).rejects.toThrow(
+      'connection refused',
+    );
+  });
+});

frontend/test/stores/favorites-store.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Favourites is the one store that updates optimistically: the heart
+ * fills before Go has agreed. So the interesting cases are the reverts,
+ * and the set of playlist events that force a reload — a default
+ * playlist edited elsewhere has to show up here.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import { favoritesStore } from '@store/favorites-store';
+import { Events } from '../../src/events';
+import {
+  emit,
+  calls,
+  stub,
+  stubFailure,
+  flush,
+  lastArgs,
+  resetHarness,
+} from '@test/support/harness';
+
+const PATHS = ['/music/a.mp3', '/music/b.mp3'];
+
+function stubReads(paths: string[] = PATHS): void {
+  stub('playlist.Service.GetDefaultPlaylistTrackPaths', paths);
+  stub('playlist.Service.GetDefaultPlaylistInfo', { Name: 'Loved' });
+  stub('config.Config.GetFavoritesPlaylistID', 3);
+  stub('config.Config.GetFavoritesIconStyle', 'star');
+  stub('config.Config.GetPinDefaultPlaylist', false);
+}
+
+/** Push a config change and let the reloads it triggers settle. */
+async function reload(paths: string[] = PATHS): Promise<void> {
+  stubReads(paths);
+  emit(Events.FavoritesConfigChanged, {
+    PlaylistID: 3,
+    IconStyle: 'star',
+    PinDefault: false,
+  });
+  await flush();
+  resetHarness();
+  stubReads(paths);
+}
+
+describe('favorites store: cached membership', () => {
+  beforeEach(async () => {
+    await reload();
+  });
+
+  it('reports membership by file path', () => {
+    expect([
+      favoritesStore.isFavorited('/music/a.mp3'),
+      favoritesStore.isFavorited('/music/z.mp3'),
+    ]).toEqual([true, false]);
+  });
+
+  it('requires every path for a multi-selection to count as favourited', () => {
+    expect([
+      favoritesStore.allFavorited(PATHS),
+      favoritesStore.allFavorited([...PATHS, '/music/z.mp3']),
+    ]).toEqual([true, false]);
+  });
+
+  it('treats an empty selection as not favourited, so the button is not lit for nothing', () => {
+    expect(favoritesStore.allFavorited([])).toBe(false);
+  });
+
+  it('adopts the config the backend pushed', () => {
+    expect([
+      favoritesStore.getPlaylistId(),
+      favoritesStore.getIconStyle(),
+      favoritesStore.getPinDefault(),
+    ]).toEqual([3, 'star', false]);
+  });
+
+  it('resolves the playlist name from the backend', () => {
+    expect(favoritesStore.getPlaylistName()).toBe('Loved');
+  });
+});
+
+describe('favorites store: optimistic writes', () => {
+  beforeEach(async () => {
+    await reload();
+  });
+
+  it('fills the heart before the backend answers', () => {
+    void favoritesStore.toggleFavorite('/music/z.mp3');
+
+    expect(favoritesStore.isFavorited('/music/z.mp3')).toBe(true);
+  });
+
+  it('reverts an add the backend rejected', async () => {
+    stubFailure('playlist.Service.ToggleDefaultPlaylistTrack');
+
+    await favoritesStore.toggleFavorite('/music/z.mp3');
+
+    expect(favoritesStore.isFavorited('/music/z.mp3')).toBe(false);
+  });
+
+  it('reverts a removal the backend rejected', async () => {
+    stubFailure('playlist.Service.ToggleDefaultPlaylistTrack');
+
+    await favoritesStore.toggleFavorite('/music/a.mp3');
+
+    expect(favoritesStore.isFavorited('/music/a.mp3')).toBe(true);
+  });
+
+  it('adds a batch optimistically and forwards the whole list', async () => {
+    await favoritesStore.addToFavorites(['/music/y.mp3', '/music/z.mp3']);
+
+    expect([
+      favoritesStore.allFavorited(['/music/y.mp3', '/music/z.mp3']),
+      lastArgs('playlist.Service.AddToDefaultPlaylist'),
+    ]).toEqual([true, [['/music/y.mp3', '/music/z.mp3']]]);
+  });
+
+  it('removes a batch optimistically', async () => {
+    await favoritesStore.removeFromFavorites(['/music/a.mp3']);
+
+    expect(favoritesStore.isFavorited('/music/a.mp3')).toBe(false);
+  });
+
+  it('resyncs from the backend when a batch write fails, rather than guessing', async () => {
+    stubFailure('playlist.Service.AddToDefaultPlaylist');
+
+    await favoritesStore.addToFavorites(['/music/z.mp3']);
+    await flush();
+
+    expect(
+      calls('playlist.Service.GetDefaultPlaylistTrackPaths'),
+    ).toHaveLength(1);
+  });
+});
+
+describe('favorites store: reacting to playlist changes', () => {
+  beforeEach(async () => {
+    await reload();
+  });
+
+  it('reloads when the default playlist itself changed', async () => {
+    emit(Events.PlaylistTracksChanged, 3);
+    await flush();
+
+    expect(
+      calls('playlist.Service.GetDefaultPlaylistTrackPaths'),
+    ).toHaveLength(1);
+  });
+
+  it('ignores changes to some other playlist', async () => {
+    emit(Events.PlaylistTracksChanged, 99);
+    await flush();
+
+    expect(
+      calls('playlist.Service.GetDefaultPlaylistTrackPaths'),
+    ).toHaveLength(0);
+  });
+
+  it('reloads after a restore, which rewrites every playlist', async () => {
+    emit(Events.PlaylistsRestored);
+    await flush();
+
+    expect(
+      calls('playlist.Service.GetDefaultPlaylistTrackPaths'),
+    ).toHaveLength(1);
+  });
+
+  it('re-reads the name when a playlist is renamed', async () => {
+    stub('playlist.Service.GetDefaultPlaylistInfo', { Name: 'Renamed' });
+    emit(Events.PlaylistRenamed, 3);
+    await flush();
+
+    expect(favoritesStore.getPlaylistName()).toBe('Renamed');
+  });
+
+  it('falls back to "Favorites" when no default playlist is configured', async () => {
+    await favoritesStore.setDefaultPlaylist(0);
+
+    expect(favoritesStore.getPlaylistName()).toBe('Favorites');
+  });
+
+  it('persists a changed icon style', async () => {
+    await favoritesStore.setIconStyle('heart');
+
+    expect([
+      favoritesStore.getIconStyle(),
+      lastArgs('config.Config.SetFavoritesIconStyle'),
+    ]).toEqual(['heart', ['heart']]);
+  });
+
+  it('persists the pin setting', async () => {
+    await favoritesStore.setPinDefault(true);
+
+    expect(lastArgs('config.Config.SetPinDefaultPlaylist')).toEqual([true]);
+  });
+});

frontend/test/stores/job-store.test.ts

@@ -0,0 +1,273 @@
+/**
+ * The job store mirrors the backend registry from full snapshots, so
+ * the derivations on top of it — which jobs count as active, whether
+ * the indicator should be up, the linger after the last job finishes —
+ * are where the behaviour lives.
+ */
+import { describe, expect, it, beforeEach, vi, afterEach } from 'vitest';
+
+import {
+  jobStore,
+  isTerminal,
+  isActive,
+  isIndeterminate,
+  progressFraction,
+  type Job,
+} from '@store/job-store';
+import { Events } from '../../src/events';
+import { emit, calls, stub, flush } from '@test/support/harness';
+
+function job(overrides: Partial<Job> & { id: string }): Job {
+  return {
+    kind: 'library-scan',
+    state: 'running',
+    title: 'Scanning',
+    current: 0,
+    total: 0,
+    ...overrides,
+  } as Job;
+}
+
+/** Push a full snapshot, which is all the backend ever sends. */
+function snapshot(jobs: Job[]): void {
+  emit(Events.JobsChanged, jobs);
+}
+
+describe('job predicates', () => {
+  it('treats complete, cancelled and error as terminal', () => {
+    const states = ['complete', 'cancelled', 'error'] as const;
+
+    expect(
+      states.map((state) => isTerminal(job({ id: state, state }))),
+    ).toEqual([true, true, true]);
+  });
+
+  it('treats every in-flight state, including paused, as active', () => {
+    const states = ['queued', 'running', 'pausing', 'paused', 'cancelling'];
+
+    expect(states.map((state) => isActive(job({ id: state, state })))).toEqual([
+      true,
+      true,
+      true,
+      true,
+      true,
+    ]);
+  });
+
+  it('calls a job with no denominator indeterminate', () => {
+    expect([
+      isIndeterminate(job({ id: 'a', total: 0 })),
+      isIndeterminate(job({ id: 'b', total: -1 })),
+      isIndeterminate(job({ id: 'c', total: 10 })),
+    ]).toEqual([true, true, false]);
+  });
+
+  it('has no progress fraction when indeterminate', () => {
+    expect(progressFraction(job({ id: 'a', total: 0, current: 5 }))).toBeNull();
+  });
+
+  it('clamps a progress fraction that overshoots its total', () => {
+    expect([
+      progressFraction(job({ id: 'a', current: 5, total: 10 })),
+      progressFraction(job({ id: 'b', current: 30, total: 10 })),
+      progressFraction(job({ id: 'c', current: -5, total: 10 })),
+    ]).toEqual([0.5, 1, 0]);
+  });
+});
+
+describe('job store: snapshots', () => {
+  beforeEach(() => {
+    snapshot([]);
+  });
+
+  it('partitions a snapshot by state', () => {
+    snapshot([
+      job({ id: 'r', state: 'running' }),
+      job({ id: 'q', state: 'queued' }),
+      job({ id: 'p', state: 'paused' }),
+      job({ id: 'e', state: 'error' }),
+      job({ id: 'c', state: 'complete' }),
+    ]);
+
+    expect({
+      working: jobStore.workingJobs.map((j) => j.id),
+      paused: jobStore.pausedJobs.map((j) => j.id),
+      failed: jobStore.failedJobs.map((j) => j.id),
+      finished: jobStore.finishedJobs.map((j) => j.id),
+      active: jobStore.activeJobs.map((j) => j.id),
+    }).toEqual({
+      working: ['r', 'q'],
+      paused: ['p'],
+      failed: ['e'],
+      finished: ['e', 'c'],
+      active: ['r', 'q', 'p'],
+    });
+  });
+
+  it('tolerates a null snapshot, which Go sends for an empty registry', () => {
+    emit(Events.JobsChanged, null);
+
+    expect(jobStore.jobs).toEqual([]);
+  });
+
+  it('replaces rather than merges, so a removed job disappears', () => {
+    snapshot([job({ id: 'a' }), job({ id: 'b' })]);
+    snapshot([job({ id: 'b' })]);
+
+    expect(jobStore.jobs.map((j) => j.id)).toEqual(['b']);
+  });
+
+  it('finds a job by id', () => {
+    snapshot([job({ id: 'a', title: 'Indexing' })]);
+
+    expect(jobStore.getJob('a')?.title).toBe('Indexing');
+  });
+
+  it('fetches the initial snapshot at most once', async () => {
+    stub('jobs.Service.GetJobs', [job({ id: 'a' })]);
+
+    await jobStore.init();
+    await jobStore.init();
+
+    expect(calls('jobs.Service.GetJobs').length).toBeLessThanOrEqual(1);
+  });
+});
+
+describe('job store: indicator linger', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    // Emptying the registry is itself "the last job finished", so it
+    // starts a linger; run it out before the test begins.
+    snapshot([]);
+    vi.advanceTimersByTime(4000);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('keeps the indicator up briefly after the last job finishes', () => {
+    snapshot([job({ id: 'a', state: 'running' })]);
+    snapshot([job({ id: 'a', state: 'complete' })]);
+
+    const immediatelyAfter = jobStore.shouldShowIndicator;
+
+    vi.advanceTimersByTime(4000);
+
+    expect([immediatelyAfter, jobStore.shouldShowIndicator]).toEqual([
+      true,
+      false,
+    ]);
+  });
+
+  it('cancels the linger when new work starts', () => {
+    snapshot([job({ id: 'a', state: 'running' })]);
+    snapshot([job({ id: 'a', state: 'complete' })]);
+    snapshot([
+      job({ id: 'a', state: 'complete' }),
+      job({ id: 'b', state: 'running' }),
+    ]);
+
+    vi.advanceTimersByTime(4000);
+
+    // Still up, because b is still working — the linger timer must not
+    // hide the indicator out from under it.
+    expect(jobStore.shouldShowIndicator).toBe(true);
+  });
+
+  it('does not linger for a snapshot that was never active', () => {
+    snapshot([job({ id: 'a', state: 'complete' })]);
+
+    expect(jobStore.shouldShowIndicator).toBe(false);
+  });
+});
+
+describe('job store: logs', () => {
+  beforeEach(() => {
+    snapshot([]);
+  });
+
+  it('is empty until a log is fetched', () => {
+    expect(jobStore.cachedLog('a')).toEqual([]);
+  });
+
+  it('caches a fetched log', async () => {
+    stub('jobs.Service.GetJobLog', [{ level: 'warn', message: 'skipped' }]);
+    snapshot([job({ id: 'a' })]);
+
+    await jobStore.loadLog('a');
+
+    expect(jobStore.cachedLog('a')).toHaveLength(1);
+  });
+
+  it('returns an empty log rather than throwing when the fetch fails', async () => {
+    stub('jobs.Service.GetJobLog', () => {
+      throw new Error('gone');
+    });
+
+    await expect(jobStore.loadLog('a')).resolves.toEqual([]);
+  });
+
+  it('drops cached logs for jobs the backend has forgotten', async () => {
+    stub('jobs.Service.GetJobLog', [{ level: 'info', message: 'x' }]);
+    snapshot([job({ id: 'a' })]);
+    await jobStore.loadLog('a');
+
+    snapshot([job({ id: 'b' })]);
+
+    expect(jobStore.cachedLog('a')).toEqual([]);
+  });
+
+  it('forgets a dismissed job log without waiting for the next snapshot', async () => {
+    stub('jobs.Service.GetJobLog', [{ level: 'info', message: 'x' }]);
+    snapshot([job({ id: 'a' })]);
+    await jobStore.loadLog('a');
+
+    await jobStore.dismiss('a');
+
+    expect(jobStore.cachedLog('a')).toEqual([]);
+  });
+});
+
+describe('job store: controls', () => {
+  beforeEach(() => {
+    snapshot([]);
+  });
+
+  it('forwards each control to its bound method with the job id', async () => {
+    await jobStore.pause('a');
+    await jobStore.resume('a');
+    await jobStore.cancel('a');
+
+    expect(calls().map((c) => [c.path, c.args])).toEqual([
+      ['jobs.Service.PauseJob', ['a']],
+      ['jobs.Service.ResumeJob', ['a']],
+      ['jobs.Service.CancelJob', ['a']],
+    ]);
+  });
+
+  it('clears logs for every finished job when they are cleared', async () => {
+    stub('jobs.Service.GetJobLog', [{ level: 'info', message: 'x' }]);
+    snapshot([job({ id: 'a', state: 'complete' })]);
+    await jobStore.loadLog('a');
+
+    await jobStore.clearFinished();
+
+    expect(jobStore.cachedLog('a')).toEqual([]);
+  });
+
+  it('coalesces a burst of snapshots into one notification', async () => {
+    let notifications = 0;
+    const off = jobStore.subscribe(() => {
+      notifications += 1;
+    });
+
+    snapshot([job({ id: 'a', current: 1, total: 10 })]);
+    snapshot([job({ id: 'a', current: 2, total: 10 })]);
+    snapshot([job({ id: 'a', current: 3, total: 10 })]);
+    await flush();
+    off();
+
+    expect(notifications).toBe(1);
+  });
+});

frontend/test/stores/keyboard-shortcuts.test.ts

@@ -0,0 +1,400 @@
+/**
+ * The keyboard shortcut service and the store behind it. This is the
+ * test that most justifies running in a real browser: the service walks
+ * shadow roots to find the deepest focused element, and no jsdom
+ * approximation of that is worth trusting.
+ */
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+
+import { buildKeyString } from '../../src/services/keyboard-shortcut-service';
+import '../../src/services/keyboard-shortcut-service';
+import { shortcutsStore } from '@store/shortcuts-store';
+import { Events } from '../../src/events';
+import { emit, calls, lastArgs, stub } from '@test/support/harness';
+
+/** Install a binding table, as the backend's config push does. */
+function bindings(table: Record<string, string>): void {
+  emit(Events.ShortcutsConfigChanged, table);
+}
+
+/** Send a keydown through the document, where the service listens. */
+function press(
+  key: string,
+  modifiers: Partial<
+    Record<'ctrlKey' | 'altKey' | 'shiftKey' | 'metaKey', boolean>
+  > = {},
+): KeyboardEvent {
+  const event = new KeyboardEvent('keydown', {
+    key,
+    bubbles: true,
+    cancelable: true,
+    ...modifiers,
+  });
+
+  document.dispatchEvent(event);
+
+  return event;
+}
+
+const mounted: HTMLElement[] = [];
+
+/** Append an element to the body and remember to remove it. */
+function mount<T extends HTMLElement>(el: T): T {
+  document.body.append(el);
+  mounted.push(el);
+
+  return el;
+}
+
+afterEach(() => {
+  while (mounted.length > 0) mounted.pop()?.remove();
+  bindings({});
+});
+
+// ===================================================================
+
+describe('buildKeyString', () => {
+  it('uppercases a bare printable key', () => {
+    expect(buildKeyString(new KeyboardEvent('keydown', { key: 'n' }))).toBe(
+      'N',
+    );
+  });
+
+  it('orders modifiers Ctrl, Alt, Shift regardless of press order', () => {
+    const e = new KeyboardEvent('keydown', {
+      key: 'f',
+      shiftKey: true,
+      altKey: true,
+      ctrlKey: true,
+    });
+
+    expect(buildKeyString(e)).toBe('Ctrl+Alt+Shift+F');
+  });
+
+  it('folds Meta into Ctrl so macOS and Linux share one binding table', () => {
+    const meta = new KeyboardEvent('keydown', { key: 'f', metaKey: true });
+    const ctrl = new KeyboardEvent('keydown', { key: 'f', ctrlKey: true });
+
+    expect(buildKeyString(meta)).toBe(buildKeyString(ctrl));
+  });
+
+  it('aliases arrows and space to their canonical names', () => {
+    const names = ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', ' '].map(
+      (key) => buildKeyString(new KeyboardEvent('keydown', { key })),
+    );
+
+    expect(names).toEqual(['Up', 'Down', 'Left', 'Right', 'Space']);
+  });
+
+  it('leaves multi-character named keys alone', () => {
+    expect(
+      buildKeyString(new KeyboardEvent('keydown', { key: 'Escape' })),
+    ).toBe('Escape');
+  });
+
+  it('returns nothing for a bare modifier press', () => {
+    const bare = ['Control', 'Alt', 'Shift', 'Meta'].map((key) =>
+      buildKeyString(new KeyboardEvent('keydown', { key })),
+    );
+
+    expect(bare).toEqual(['', '', '', '']);
+  });
+});
+
+// ===================================================================
+
+describe('shortcuts store: lookup', () => {
+  beforeEach(() => {
+    bindings({
+      'player.playPause': 'Space',
+      'player.next': 'Ctrl+Right',
+      'tracklist.play': 'Enter',
+      'tracklist.delete': 'Delete',
+    });
+  });
+
+  it('resolves an action to its key', () => {
+    expect(shortcutsStore.getKeyForAction('player.next')).toBe('Ctrl+Right');
+  });
+
+  it('reverse-resolves a key to its global action', () => {
+    expect(shortcutsStore.getActionForKey('Space')).toBe('player.playPause');
+  });
+
+  it('does not resolve a panel binding from global scope', () => {
+    // `tracklist.` is a panel prefix: Enter must do nothing unless the
+    // track list has focus.
+    expect(shortcutsStore.getActionForKey('Enter')).toBeUndefined();
+  });
+
+  it('resolves a panel binding when the matching scope is supplied', () => {
+    expect(shortcutsStore.getActionForKey('Enter', 'panel:tracklist')).toBe(
+      'tracklist.play',
+    );
+  });
+
+  it('falls back to global inside a panel scope', () => {
+    expect(shortcutsStore.getActionForKey('Space', 'panel:tracklist')).toBe(
+      'player.playPause',
+    );
+  });
+
+  it('reports a conflict, excluding the action being rebound', () => {
+    expect(
+      shortcutsStore.findConflict('Space', 'global', 'player.next'),
+    ).toEqual({ action: 'player.playPause', key: 'Space' });
+  });
+
+  it('does not report an action conflicting with itself', () => {
+    expect(
+      shortcutsStore.findConflict('Space', 'global', 'player.playPause'),
+    ).toBeNull();
+  });
+});
+
+// ===================================================================
+
+describe('shortcut dispatch: scope', () => {
+  beforeEach(() => {
+    bindings({
+      'player.playPause': 'Space',
+      'tracklist.play': 'Enter',
+    });
+  });
+
+  it('dispatches from global scope', () => {
+    press(' ');
+
+    expect(calls('queue.Queue.Play')).toHaveLength(1);
+  });
+
+  it('preventDefaults a key it handled', () => {
+    expect(press(' ').defaultPrevented).toBe(true);
+  });
+
+  it('leaves an unbound key alone', () => {
+    expect(press('q').defaultPrevented).toBe(false);
+  });
+
+  it('suppresses shortcuts while a text input has focus', () => {
+    const input = mount(document.createElement('input'));
+
+    input.type = 'text';
+    input.focus();
+    press(' ');
+
+    expect(calls('queue.Queue.Play')).toHaveLength(0);
+  });
+
+  it('suppresses shortcuts inside a contenteditable', () => {
+    const div = mount(document.createElement('div'));
+
+    div.contentEditable = 'true';
+    div.tabIndex = 0;
+    div.focus();
+    press(' ');
+
+    expect(calls('queue.Queue.Play')).toHaveLength(0);
+  });
+
+  it('lets a checkbox through — it is not a text input', () => {
+    const input = mount(document.createElement('input'));
+
+    input.type = 'checkbox';
+    input.focus();
+    press(' ');
+
+    expect(calls('queue.Queue.Play')).toHaveLength(1);
+  });
+
+  it('blurs the input on Escape, and only on Escape', () => {
+    const input = mount(document.createElement('input'));
+
+    input.type = 'search';
+    input.focus();
+    press('Escape');
+
+    expect(document.activeElement).not.toBe(input);
+  });
+
+  it('finds a text input nested in a shadow root', () => {
+    // document.activeElement stops at the shadow host, so a service
+    // that did not walk the chain would see <div> and fire the shortcut.
+    const host = mount(document.createElement('div'));
+    const root = host.attachShadow({ mode: 'open' });
+    const input = document.createElement('input');
+
+    input.type = 'text';
+    root.append(input);
+    input.focus();
+    press(' ');
+
+    expect(calls('queue.Queue.Play')).toHaveLength(0);
+  });
+
+  it('resolves a panel scope from a data-shortcut-scope ancestor', () => {
+    const panel = mount(document.createElement('div'));
+    const button = document.createElement('button');
+
+    panel.dataset['shortcutScope'] = 'tracklist';
+    panel.append(button);
+    button.focus();
+
+    let fired = 0;
+    const listener = (): void => {
+      fired += 1;
+    };
+
+    document.addEventListener('shortcut:tracklist-play', listener);
+    press('Enter');
+    document.removeEventListener('shortcut:tracklist-play', listener);
+
+    expect(fired).toBe(1);
+  });
+
+  it('crosses a shadow boundary looking for the panel scope', () => {
+    const panel = mount(document.createElement('div'));
+    const inner = document.createElement('div');
+    const root = inner.attachShadow({ mode: 'open' });
+    const button = document.createElement('button');
+
+    panel.dataset['shortcutScope'] = 'tracklist';
+    panel.append(inner);
+    root.append(button);
+    button.focus();
+
+    let fired = 0;
+    const listener = (): void => {
+      fired += 1;
+    };
+
+    document.addEventListener('shortcut:tracklist-play', listener);
+    press('Enter');
+    document.removeEventListener('shortcut:tracklist-play', listener);
+
+    expect(fired).toBe(1);
+  });
+});
+
+// ===================================================================
+
+describe('shortcut dispatch: actions', () => {
+  it('toggles between pause and play based on cached player state', () => {
+    bindings({ 'player.playPause': 'Space' });
+
+    emit(Events.PlaybackStateChanged, { state: 'playing' });
+    press(' ');
+    emit(Events.PlaybackStateChanged, { state: 'paused' });
+    press(' ');
+
+    expect(calls().map((c) => c.path)).toEqual([
+      'player.Player.Pause',
+      'queue.Queue.Play',
+    ]);
+  });
+
+  it('steps the volume by a fixed amount in each direction', () => {
+    bindings({ 'player.volumeUp': 'Up', 'player.volumeDown': 'Down' });
+
+    press('ArrowUp');
+    press('ArrowDown');
+
+    expect(calls('player.Player.ChangeVolume').map((c) => c.args)).toEqual([
+      [5],
+      [-5],
+    ]);
+  });
+
+  it('clamps a forward seek to the track length', async () => {
+    bindings({ 'player.seekForward': 'Right' });
+    stub('player.Player.CurrentPositionSeconds', 98);
+    stub('player.Player.TrackLengthInSeconds', 100);
+
+    press('ArrowRight');
+    await new Promise<void>((r) => {
+      setTimeout(r, 0);
+    });
+
+    expect(lastArgs('player.Player.Seek')).toEqual([100]);
+  });
+
+  it('clamps a backward seek at zero', async () => {
+    bindings({ 'player.seekBack': 'Left' });
+    stub('player.Player.CurrentPositionSeconds', 2);
+
+    press('ArrowLeft');
+    await new Promise<void>((r) => {
+      setTimeout(r, 0);
+    });
+
+    expect(lastArgs('player.Player.Seek')).toEqual([0]);
+  });
+
+  it('toggles the queue panel open and closed', () => {
+    bindings({ 'nav.queue': 'Q' });
+
+    const panel = mount(document.createElement('div'));
+
+    panel.id = 'queue-panel';
+
+    press('q');
+    const opened = panel.hasAttribute('open');
+
+    press('q');
+
+    expect([opened, panel.hasAttribute('open')]).toEqual([true, false]);
+  });
+
+  it('broadcasts select-all as a document event', () => {
+    bindings({ 'app.selectAll': 'Ctrl+A' });
+
+    let fired = 0;
+    const listener = (): void => {
+      fired += 1;
+    };
+
+    document.addEventListener('shortcut:select-all', listener);
+    press('a', { ctrlKey: true });
+    document.removeEventListener('shortcut:select-all', listener);
+
+    expect(fired).toBe(1);
+  });
+
+  it('ignores an action name the dispatcher does not know', () => {
+    bindings({ 'player.teleport': 'T' });
+
+    press('t');
+
+    expect(calls()).toEqual([]);
+  });
+});
+
+// ===================================================================
+
+describe('shortcuts store: writes', () => {
+  it('sends a single rebind to the backend', async () => {
+    await shortcutsStore.updateBinding('player.next', 'Ctrl+N');
+
+    expect(lastArgs('config.Config.SetShortcut')).toEqual([
+      'player.next',
+      'Ctrl+N',
+    ]);
+  });
+
+  it('sends a whole table at once', async () => {
+    await shortcutsStore.setAll({ 'player.next': 'N' });
+
+    expect(lastArgs('config.Config.SetShortcuts')).toEqual([
+      { 'player.next': 'N' },
+    ]);
+  });
+
+  it('does not update its cache optimistically', async () => {
+    bindings({ 'player.next': 'Ctrl+Right' });
+    await shortcutsStore.updateBinding('player.next', 'Ctrl+N');
+
+    // The backend is the only writer; the cache waits for the
+    // ShortcutsConfigChanged push.
+    expect(shortcutsStore.getKeyForAction('player.next')).toBe('Ctrl+Right');
+  });
+});

frontend/test/stores/library-store.test.ts

@@ -0,0 +1,287 @@
+/**
+ * The library store is the frontend's read cache for the whole
+ * catalogue: four collections, each fetched once and held until
+ * something invalidates them. The interesting behaviour is not the
+ * fetching but the caching — deduplicating concurrent readers, throwing
+ * everything away on a rescan, and swapping to the by-library bindings
+ * when a filter is active.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import { libraryStore } from '@store/library-store';
+import { Events } from '../../src/events';
+import {
+  emit,
+  calls,
+  stub,
+  flush,
+  lastArgs,
+  resetHarness,
+} from '@test/support/harness';
+
+const TRACKS = [{ ID: 1, Title: 'One' }];
+const ALBUMS = [{ ID: 1, Name: 'Album', ArtistName: 'Artist' }];
+const OTHER_ALBUMS = [{ ID: 2, Name: 'Other', ArtistName: 'Other Artist' }];
+const ARTISTS = [{ ID: 1, Name: 'Artist' }];
+const GENRES = [{ Name: 'Ambient', Count: 3 }];
+const LIBRARIES = [{ id: 7, name: 'Music' }, { id: 8, name: 'Field' }];
+
+/** Stub every read binding the store can reach. Unstubbed bindings
+ *  resolve undefined, which the store would cache as if it were data. */
+function stubReads(): void {
+  stub('library.Library.GetAllTracks', TRACKS);
+  stub('library.Library.GetAllAlbums', ALBUMS);
+  stub('library.Library.GetAllArtists', ARTISTS);
+  stub('library.Library.GetAllGenresWithCounts', GENRES);
+  stub('library.Library.GetAllTracksByLibrary', TRACKS);
+  stub('library.Library.GetAllAlbumsByLibrary', ALBUMS);
+  stub('library.Library.GetAllArtistsByLibrary', ARTISTS);
+  stub('library.Library.GetAllGenresWithCountsByLibrary', GENRES);
+  stub('library.Library.GetAlbumsByArtist', ALBUMS);
+  stub('library.Library.GetAlbumsByArtistByLibrary', ALBUMS);
+  stub('library.Library.GetAllLibrariesWithTrackCounts', LIBRARIES);
+}
+
+/**
+ * Drop the cache and let the eager refetch settle, so each test starts
+ * from the same place. The store has no reset of its own; a scan
+ * completing is how the app itself clears it.
+ */
+async function reload(): Promise<void> {
+  stubReads();
+  emit(Events.LibraryScanComplete);
+  await flush();
+  // The eager refetch the invalidation kicks off is recorded like any
+  // other call; clear it, or every count in every test is off by one.
+  resetHarness();
+  stubReads();
+}
+
+describe('library store: caching', () => {
+  beforeEach(async () => {
+    await reload();
+  });
+
+  it('serves a second read from cache without touching the backend', async () => {
+    await libraryStore.getTracks();
+
+    expect(calls('library.Library.GetAllTracks')).toHaveLength(0);
+  });
+
+  it('deduplicates concurrent first reads into one backend call', async () => {
+    emit(Events.LibraryScanComplete);
+    const [a, b] = await Promise.all([
+      libraryStore.getArtists(),
+      libraryStore.getArtists(),
+    ]);
+
+    expect([a, b, calls('library.Library.GetAllArtists').length]).toEqual([
+      ARTISTS,
+      ARTISTS,
+      1,
+    ]);
+  });
+
+  it('exposes cached collections synchronously once loaded', () => {
+    expect([
+      libraryStore.getCachedTracks(),
+      libraryStore.getCachedAlbums(),
+      libraryStore.cachedArtists,
+      libraryStore.getCachedGenres(),
+    ]).toEqual([TRACKS, ALBUMS, ARTISTS, GENRES]);
+  });
+
+  it('refetches everything when a scan completes', async () => {
+    emit(Events.LibraryScanComplete);
+    await flush();
+
+    expect(calls().map((c) => c.path).sort()).toEqual([
+      'library.Library.GetAllAlbums',
+      'library.Library.GetAllArtists',
+      'library.Library.GetAllGenresWithCounts',
+      'library.Library.GetAllTracks',
+    ]);
+  });
+
+  it('refetches when a track is retagged', async () => {
+    emit(Events.TrackMetadataChanged, { filePath: '/a.mp3' });
+    await flush();
+
+    expect(calls('library.Library.GetAllTracks')).toHaveLength(1);
+  });
+
+  it('resets scroll positions on invalidation, so a shorter list is not scrolled past its end', async () => {
+    libraryStore.setScrollPosition('albums', 4200);
+    emit(Events.LibraryScanComplete);
+    await flush();
+
+    expect(libraryStore.getScrollPosition('albums')).toBe(0);
+  });
+
+  it('bumps the change generation for data, not for loading flags', async () => {
+    const before = libraryStore.changeGeneration;
+
+    await libraryStore.getTracks(); // cached: no change
+    const afterCachedRead = libraryStore.changeGeneration;
+
+    emit(Events.LibraryScanComplete);
+    await flush();
+
+    expect([
+      afterCachedRead === before,
+      libraryStore.changeGeneration > before,
+    ]).toEqual([true, true]);
+  });
+});
+
+describe('library store: library filter', () => {
+  beforeEach(async () => {
+    libraryStore.setSelectedLibrary(null);
+    await reload();
+  });
+
+  it('switches to the by-library bindings when a filter is set', async () => {
+    libraryStore.setSelectedLibrary(7);
+    await flush();
+
+    expect(lastArgs('library.Library.GetAllTracksByLibrary')).toEqual([7]);
+  });
+
+  it('ignores a redundant selection instead of invalidating', async () => {
+    libraryStore.setSelectedLibrary(null);
+    await flush();
+
+    expect(calls()).toEqual([]);
+  });
+
+  it('answers the cached artist-albums query only when unfiltered', async () => {
+    const unfiltered = libraryStore.getAlbumsByArtistNameCached('Artist');
+
+    libraryStore.setSelectedLibrary(7);
+    await flush();
+
+    // With a filter active the cache is already library-scoped, so the
+    // store declines to answer and forces a backend query instead.
+    expect([
+      unfiltered,
+      libraryStore.getAlbumsByArtistNameCached('Artist'),
+    ]).toEqual([ALBUMS, null]);
+  });
+
+  it('scopes an artist drill-down to the selected library', async () => {
+    libraryStore.setSelectedLibrary(8);
+    await libraryStore.getAlbumsByArtist(3);
+
+    expect(lastArgs('library.Library.GetAlbumsByArtistByLibrary')).toEqual([
+      3, 8,
+    ]);
+  });
+});
+
+describe('library store: default library id', () => {
+  beforeEach(async () => {
+    libraryStore.setSelectedLibrary(null);
+    await reload();
+  });
+
+  it('prefers the active filter', async () => {
+    libraryStore.setSelectedLibrary(8);
+
+    await expect(libraryStore.getDefaultLibraryId()).resolves.toBe(8);
+  });
+
+  it('falls back to the first known library, never to zero', async () => {
+    // id 0 never exists and trips the download_requests foreign key.
+    await expect(libraryStore.getDefaultLibraryId()).resolves.toBe(7);
+  });
+
+  it('returns null when there are no libraries at all', async () => {
+    stub('library.Library.GetAllLibrariesWithTrackCounts', []);
+    emit(Events.LibraryRemoved, { id: 7 });
+
+    await expect(libraryStore.getDefaultLibraryId()).resolves.toBeNull();
+  });
+
+  it('caches the library list until a library is added or renamed', async () => {
+    const fetched = (): number =>
+      calls('library.Library.GetAllLibrariesWithTrackCounts').length;
+
+    // The list survives a rescan — only library CRUD changes it.
+    emit(Events.LibraryAdded, { id: 9 });
+    await libraryStore.getLibraries();
+    const afterAdd = fetched();
+
+    await libraryStore.getLibraries();
+    const afterCachedRead = fetched();
+
+    emit(Events.LibraryRenamed, { id: 7, name: 'Renamed' });
+    await libraryStore.getLibraries();
+
+    expect([afterAdd, afterCachedRead, fetched()]).toEqual([1, 1, 2]);
+  });
+});
+
+describe('library store: cover size', () => {
+  beforeEach(() => {
+    localStorage.removeItem('cover-grid-size');
+    libraryStore.setCoverSize(176);
+  });
+
+  it('clamps below the minimum card width', () => {
+    libraryStore.setCoverSize(10);
+
+    expect(libraryStore.getCoverSize()).toBe(100);
+  });
+
+  it('clamps above the maximum card width', () => {
+    libraryStore.setCoverSize(9000);
+
+    expect(libraryStore.getCoverSize()).toBe(350);
+  });
+
+  it('rounds a fractional size, since it becomes a CSS pixel value', () => {
+    libraryStore.setCoverSize(180.6);
+
+    expect(libraryStore.getCoverSize()).toBe(181);
+  });
+
+  it('persists the size for the next session', () => {
+    libraryStore.setCoverSize(200);
+
+    expect(localStorage.getItem('cover-grid-size')).toBe('200');
+  });
+
+  it('does not notify when the clamped size is unchanged', async () => {
+    libraryStore.setCoverSize(300);
+    await flush();
+
+    let notifications = 0;
+    const off = libraryStore.subscribe(() => {
+      notifications += 1;
+    });
+
+    libraryStore.setCoverSize(400); // clamps back to 350 ≠ 300
+    libraryStore.setCoverSize(9999); // clamps to 350, unchanged
+    await flush();
+    off();
+
+    expect(notifications).toBe(1);
+  });
+});
+
+describe('library store: albums by artist name', () => {
+  beforeEach(async () => {
+    libraryStore.setSelectedLibrary(null);
+    await reload();
+  });
+
+  it('filters the album cache by artist name', () => {
+    stub('library.Library.GetAllAlbums', [...ALBUMS, ...OTHER_ALBUMS]);
+
+    expect(libraryStore.getAlbumsByArtistNameCached('Artist')).toEqual(ALBUMS);
+  });
+
+  it('returns an empty list, not null, for an artist with no albums', () => {
+    expect(libraryStore.getAlbumsByArtistNameCached('Nobody')).toEqual([]);
+  });
+});

frontend/test/stores/player-store.test.ts

@@ -0,0 +1,136 @@
+/**
+ * The player store is a pure projection of backend push events. Its
+ * whole job is to be a truthful cache, so the tests are about what it
+ * derives (`isPlaying` from a state string) and what it refuses to
+ * invent (it never predicts the result of an action).
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import { playerStore, type TrackInfo } from '@store/player-store';
+import { Events } from '../../src/events';
+import { emit, calls, lastArgs, flush } from '@test/support/harness';
+
+const TRACK: TrackInfo = {
+  fileName: 'one.mp3',
+  filePath: '/music/one.mp3',
+  trackLength: 180,
+  seekPosition: 0,
+  state: 'playing',
+  title: 'One',
+  artist: 'Artist',
+  album: 'Album',
+  coverArt: '',
+  coverArtSmall: '',
+  coverArtMedium: '',
+  coverArtLarge: '',
+  trackChangeId: 1,
+  artistMbid: '',
+  releaseGroupMbid: '',
+  recordingMbid: '',
+};
+
+describe('player store: playback state', () => {
+  beforeEach(() => {
+    emit(Events.PlaybackStateChanged, { state: 'stopped' });
+    emit(Events.TrackChanged, null);
+  });
+
+  it('is playing only for the literal "playing" state', () => {
+    const seen: boolean[] = [];
+
+    for (const state of ['playing', 'paused', 'stopped', 'buffering']) {
+      emit(Events.PlaybackStateChanged, { state });
+      seen.push(playerStore.getState().isPlaying);
+    }
+
+    expect(seen).toEqual([true, false, false, false]);
+  });
+
+  it('stops playing when the track finishes', () => {
+    emit(Events.PlaybackStateChanged, { state: 'playing' });
+    emit(Events.PlaybackFinished);
+
+    expect(playerStore.getState().isPlaying).toBe(false);
+  });
+
+  it('caches the current track', () => {
+    emit(Events.TrackChanged, TRACK);
+
+    expect(playerStore.getState().currentTrack).toEqual(TRACK);
+  });
+
+  it('normalises an absent track to null rather than undefined', () => {
+    emit(Events.TrackChanged, TRACK);
+    emit(Events.TrackChanged, undefined);
+
+    expect(playerStore.getState().currentTrack).toBeNull();
+  });
+
+  it('keeps the cached track across a pause', () => {
+    emit(Events.TrackChanged, TRACK);
+    emit(Events.PlaybackStateChanged, { state: 'paused' });
+
+    expect(playerStore.getState().currentTrack).toEqual(TRACK);
+  });
+
+  it('tracks volume pushed back from Go', () => {
+    emit(Events.VolumeChanged, 42);
+
+    expect(playerStore.getState().volume).toBe(42);
+  });
+
+  it('replaces state rather than mutating it, so a saved reference is stable', () => {
+    emit(Events.VolumeChanged, 10);
+    const before = playerStore.getState();
+
+    emit(Events.VolumeChanged, 20);
+
+    expect(before.volume).toBe(10);
+  });
+
+  it('coalesces a burst into a single notification', async () => {
+    let notifications = 0;
+    const off = playerStore.subscribe(() => {
+      notifications += 1;
+    });
+
+    emit(Events.VolumeChanged, 1);
+    emit(Events.VolumeChanged, 2);
+    emit(Events.PlaybackStateChanged, { state: 'playing' });
+    await flush();
+    off();
+
+    expect(notifications).toBe(1);
+  });
+});
+
+describe('player store: actions', () => {
+  it('forwards each action to its bound method', () => {
+    playerStore.pause();
+    playerStore.loadTrack('/music/one.mp3');
+    playerStore.seek(30);
+    playerStore.setVolume(60);
+
+    expect(calls().map((c) => c.path)).toEqual([
+      'player.Player.Pause',
+      'player.Player.LoadFile',
+      'player.Player.Seek',
+      'player.Player.SetVolume',
+    ]);
+  });
+
+  it('sends the volume as an integer percentage, not a fraction', () => {
+    // player.UserVolume is an int in Go; a float never settles its
+    // callback. See .planning/NOTES.md.
+    playerStore.setVolume(42);
+
+    expect(lastArgs('player.Player.SetVolume')).toEqual([42]);
+  });
+
+  it('does not optimistically change cached volume', () => {
+    emit(Events.VolumeChanged, 50);
+    playerStore.setVolume(80);
+
+    expect(playerStore.getState().volume).toBe(50);
+  });
+});

frontend/test/stores/playlist-store.test.ts

@@ -0,0 +1,108 @@
+/**
+ * The playlist store caches one list and invalidates it on six
+ * different events. The distinction worth testing is `invalidate` vs
+ * `refetch`: one drops the cache (consumers render empty until the
+ * fetch lands), the other holds the stale list until the new one
+ * arrives. Using the wrong one shows up as a flash of empty list.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import { playlistStore } from '@store/playlist-store';
+import { Events } from '../../src/events';
+import { emit, calls, stub, flush, resetHarness } from '@test/support/harness';
+
+const PLAYLISTS = [
+  { ID: 1, Name: 'Morning', Tracks: [] },
+  { ID: 2, Name: 'Evening', Tracks: [] },
+];
+
+async function reload(): Promise<void> {
+  stub('playlist.Service.GetAllPlaylistsWithTracks', PLAYLISTS);
+  playlistStore.invalidate();
+  await flush();
+  resetHarness();
+  stub('playlist.Service.GetAllPlaylistsWithTracks', PLAYLISTS);
+}
+
+describe('playlist store: caching', () => {
+  beforeEach(async () => {
+    await reload();
+  });
+
+  it('serves a second read from cache', async () => {
+    await playlistStore.getPlaylists();
+
+    expect(calls()).toEqual([]);
+  });
+
+  it('deduplicates concurrent first reads', async () => {
+    playlistStore.invalidate();
+    await Promise.all([
+      playlistStore.getPlaylists(),
+      playlistStore.getPlaylists(),
+    ]);
+
+    expect(calls('playlist.Service.GetAllPlaylistsWithTracks')).toHaveLength(1);
+  });
+
+  it('exposes the cache synchronously for render', () => {
+    expect(playlistStore.getCachedPlaylists()).toEqual(PLAYLISTS);
+  });
+
+  it('normalises a null list to an empty one', async () => {
+    stub('playlist.Service.GetAllPlaylistsWithTracks', null);
+    playlistStore.invalidate();
+    await flush();
+
+    expect(playlistStore.getCachedPlaylists()).toEqual([]);
+  });
+
+  it('holds the stale list across a refetch, so the view does not flash empty', async () => {
+    const pending = playlistStore.refetch();
+    const during = playlistStore.getCachedPlaylists();
+
+    await pending;
+
+    expect(during).toEqual(PLAYLISTS);
+  });
+
+  it('drops the cache on invalidate, which is the difference from refetch', () => {
+    playlistStore.invalidate();
+
+    expect(playlistStore.getCachedPlaylists()).toBeNull();
+  });
+
+  it('resets the scroll position when the list is invalidated', async () => {
+    playlistStore.setScrollPosition(900);
+    playlistStore.invalidate();
+    await flush();
+
+    expect(playlistStore.getScrollPosition()).toBe(0);
+  });
+});
+
+describe('playlist store: invalidating events', () => {
+  beforeEach(async () => {
+    await reload();
+  });
+
+  it('refetches for every event that can change a playlist', async () => {
+    const events = [
+      Events.PlaylistCreated,
+      Events.PlaylistDeleted,
+      Events.PlaylistRenamed,
+      Events.PlaylistTracksChanged,
+      Events.PlaylistsRestored,
+      Events.LibraryScanComplete,
+    ];
+
+    for (const name of events) {
+      emit(name, 1);
+      await flush();
+    }
+
+    expect(
+      calls('playlist.Service.GetAllPlaylistsWithTracks'),
+    ).toHaveLength(events.length);
+  });
+});

frontend/test/stores/queue-store.test.ts

@@ -0,0 +1,284 @@
+/**
+ * The queue store's delta reducer is the most intricate pure logic in
+ * the frontend: four mutation actions arriving as events, applied to a
+ * cached array that must stay identical to the Go queue's own. `move` in
+ * particular adjusts its insertion index for elements removed before it,
+ * and gets that wrong silently.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import { queueStore, type QueueTrack } from '@store/queue-store';
+import { Events } from '../../src/events';
+import { emit, flush, lastArgs, calls } from '@test/support/harness';
+
+function track(n: number): QueueTrack {
+  return {
+    id: n,
+    audioFileId: n,
+    filePath: `/music/${n}.mp3`,
+    position: n,
+    title: `Track ${n}`,
+    artist: 'Artist',
+    album: 'Album',
+    coverArtPath: '',
+    artistMbid: '',
+    releaseGroupMbid: '',
+    recordingMbid: '',
+  };
+}
+
+/** Titles of the cached queue, the cheapest readable assertion. */
+function titles(): string[] {
+  return queueStore.getState().tracks.map((t) => t.title);
+}
+
+/** Push an authoritative full-state sync, as the backend does on
+ *  startup and after SetQueue. */
+function sync(tracks: QueueTrack[], currentIndex = 0): void {
+  emit(Events.QueueChanged, {
+    tracks,
+    currentIndex,
+    shuffleMode: false,
+    repeatMode: 'off',
+    sourcePlaylistId: 0,
+  });
+}
+
+describe('queue store: full-state sync', () => {
+  beforeEach(() => {
+    sync([]);
+  });
+
+  it('replaces cached state wholesale', () => {
+    sync([track(1), track(2)], 1);
+
+    expect(queueStore.getState()).toEqual({
+      tracks: [track(1), track(2)],
+      currentIndex: 1,
+      shuffleMode: false,
+      repeatMode: 'off',
+      sourcePlaylistId: 0,
+    });
+  });
+
+  it('tolerates a null track list, which Go sends for an empty queue', () => {
+    emit(Events.QueueChanged, {
+      tracks: null,
+      currentIndex: -1,
+      shuffleMode: false,
+      repeatMode: 'off',
+      sourcePlaylistId: 0,
+    });
+
+    expect(queueStore.getState().tracks).toEqual([]);
+  });
+});
+
+describe('queue store: track deltas', () => {
+  beforeEach(() => {
+    sync([track(1), track(2), track(3)], 0);
+  });
+
+  it('appends on add', () => {
+    emit(Events.QueueTracksModified, {
+      action: 'add',
+      tracks: [track(4)],
+      index: 0,
+      currentIndex: 0,
+    });
+
+    expect(titles()).toEqual(['Track 1', 'Track 2', 'Track 3', 'Track 4']);
+  });
+
+  it('splices at the index on insert', () => {
+    emit(Events.QueueTracksModified, {
+      action: 'insert',
+      tracks: [track(9)],
+      index: 1,
+      currentIndex: 0,
+    });
+
+    expect(titles()).toEqual(['Track 1', 'Track 9', 'Track 2', 'Track 3']);
+  });
+
+  it('removes every listed position at once, not one at a time', () => {
+    // Removing 0 then 2 sequentially would take the wrong second track;
+    // the reducer must treat the positions as indices into the original.
+    emit(Events.QueueTracksModified, {
+      action: 'remove',
+      positions: [0, 2],
+      index: 0,
+      currentIndex: 0,
+    });
+
+    expect(titles()).toEqual(['Track 2']);
+  });
+
+  it('adopts the backend current index from every delta', () => {
+    emit(Events.QueueTracksModified, {
+      action: 'remove',
+      positions: [0],
+      index: 0,
+      currentIndex: 1,
+    });
+
+    expect(queueStore.getState().currentIndex).toBe(1);
+  });
+});
+
+describe('queue store: move', () => {
+  beforeEach(() => {
+    sync([track(1), track(2), track(3), track(4)], 0);
+  });
+
+  it('moves a track forward, compensating for its own removal', () => {
+    // Move index 0 to index 2. After removing it, the target shifts
+    // down by one, so track 1 lands between 2 and 3 — not after 3.
+    emit(Events.QueueTracksModified, {
+      action: 'move',
+      tracks: [track(1)],
+      positions: [0],
+      index: 2,
+      currentIndex: 1,
+    });
+
+    expect(titles()).toEqual(['Track 2', 'Track 1', 'Track 3', 'Track 4']);
+  });
+
+  it('moves a track backward without compensating', () => {
+    emit(Events.QueueTracksModified, {
+      action: 'move',
+      tracks: [track(4)],
+      positions: [3],
+      index: 1,
+      currentIndex: 0,
+    });
+
+    expect(titles()).toEqual(['Track 1', 'Track 4', 'Track 2', 'Track 3']);
+  });
+
+  it('moves a multi-selection, compensating once per element before the target', () => {
+    emit(Events.QueueTracksModified, {
+      action: 'move',
+      tracks: [track(1), track(2)],
+      positions: [0, 1],
+      index: 3,
+      currentIndex: 0,
+    });
+
+    expect(titles()).toEqual(['Track 3', 'Track 1', 'Track 2', 'Track 4']);
+  });
+
+  it('clamps a target past the end of the shortened list', () => {
+    emit(Events.QueueTracksModified, {
+      action: 'move',
+      tracks: [track(1)],
+      positions: [0],
+      index: 99,
+      currentIndex: 3,
+    });
+
+    expect(titles()).toEqual(['Track 2', 'Track 3', 'Track 4', 'Track 1']);
+  });
+});
+
+describe('queue store: mode deltas', () => {
+  beforeEach(() => {
+    sync([track(1)], 0);
+  });
+
+  it('applies shuffle and repeat together', () => {
+    emit(Events.QueueModeChanged, { shuffleMode: true, repeatMode: 'one' });
+
+    const state = queueStore.getState();
+
+    expect([state.shuffleMode, state.repeatMode]).toEqual([true, 'one']);
+  });
+
+  it('leaves the track list untouched', () => {
+    emit(Events.QueueModeChanged, { shuffleMode: true, repeatMode: 'all' });
+
+    expect(titles()).toEqual(['Track 1']);
+  });
+
+  it('applies an index-only delta', () => {
+    emit(Events.QueueIndexChanged, { currentIndex: 7 });
+
+    expect(queueStore.getState().currentIndex).toBe(7);
+  });
+});
+
+describe('queue store: subscriber notification', () => {
+  beforeEach(() => {
+    sync([]);
+  });
+
+  it('coalesces a burst of events into one notification', async () => {
+    let notifications = 0;
+    const unsubscribe = queueStore.subscribe(() => {
+      notifications += 1;
+    });
+
+    emit(Events.QueueIndexChanged, { currentIndex: 1 });
+    emit(Events.QueueIndexChanged, { currentIndex: 2 });
+    emit(Events.QueueIndexChanged, { currentIndex: 3 });
+    await flush();
+
+    unsubscribe();
+
+    expect(notifications).toBe(1);
+  });
+
+  it('stops notifying after unsubscribe', async () => {
+    let notifications = 0;
+    const unsubscribe = queueStore.subscribe(() => {
+      notifications += 1;
+    });
+
+    unsubscribe();
+    emit(Events.QueueIndexChanged, { currentIndex: 1 });
+    await flush();
+
+    expect(notifications).toBe(0);
+  });
+});
+
+describe('queue store: actions reach the backend', () => {
+  it('forwards setQueue with its default shuffleStart', () => {
+    queueStore.setQueue(['/a.mp3', '/b.mp3'], 1);
+
+    expect(lastArgs('queue.Queue.SetQueue')).toEqual([
+      ['/a.mp3', '/b.mp3'],
+      1,
+      false,
+    ]);
+  });
+
+  it('maps each mutation onto its own bound method', () => {
+    queueStore.addToQueue('/a.mp3');
+    queueStore.playNext('/b.mp3');
+    queueStore.removeFromQueue(2);
+    queueStore.moveTracksInQueue([0, 1], 3);
+    queueStore.toggleShuffle();
+    queueStore.cycleRepeat();
+    queueStore.clearQueue();
+
+    expect(calls().map((c) => c.path)).toEqual([
+      'queue.Queue.AddTrack',
+      'queue.Queue.InsertNext',
+      'queue.Queue.RemoveTrack',
+      'queue.Queue.MoveQueueTracks',
+      'queue.Queue.ToggleShuffle',
+      'queue.Queue.CycleRepeat',
+      'queue.Queue.Clear',
+    ]);
+  });
+
+  it('does not optimistically mutate cached state', () => {
+    sync([track(1)], 0);
+    queueStore.clearQueue();
+
+    // The backend is the only writer; the cache waits for the event.
+    expect(titles()).toEqual(['Track 1']);
+  });
+});

frontend/test/stores/theme-store.test.ts

@@ -0,0 +1,147 @@
+/**
+ * The theme store is the only store that writes to the document: it
+ * derives a whole custom-property ramp from two settings and applies it
+ * to :root, where every shadow root inherits it. Asserting on the
+ * computed values of the real document is the point of running in a
+ * browser at all.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import { themeStore } from '@store/theme-store';
+import { Events } from '../../src/events';
+import { emit, lastArgs } from '@test/support/harness';
+
+/** Push a theme, as the backend's config change event does. */
+function applyTheme(AccentColor: string, BackgroundShade: string): void {
+  emit(Events.ThemeConfigChanged, { AccentColor, BackgroundShade });
+}
+
+function cssVar(name: string): string {
+  return document.documentElement.style.getPropertyValue(name).trim();
+}
+
+describe('theme store: derived variables', () => {
+  beforeEach(() => {
+    applyTheme('#ffd43b', 'dark');
+  });
+
+  it('caches the pushed theme', () => {
+    expect(themeStore.getState()).toEqual({
+      accentColor: '#ffd43b',
+      backgroundShade: 'dark',
+    });
+  });
+
+  it('sets the accent verbatim', () => {
+    expect(cssVar('--yj-accent')).toBe('#ffd43b');
+  });
+
+  it('derives a lighter hover accent and a darker muted one', () => {
+    expect([cssVar('--yj-accent-hover'), cssVar('--yj-accent-muted')]).toEqual([
+      '#ffda58',
+      '#806a1e',
+    ]);
+  });
+
+  it('derives translucent accent backgrounds as rgba, for layering', () => {
+    expect(cssVar('--yj-accent-bg')).toBe('rgba(255, 212, 59, 0.1)');
+  });
+
+  it('expands a three-digit hex before deriving from it', () => {
+    applyTheme('#fff', 'dark');
+
+    expect(cssVar('--yj-accent-hover')).toBe('#ffffff');
+  });
+
+  it('swaps the whole background ramp with the shade', () => {
+    applyTheme('#ffd43b', 'darker');
+    const darker = cssVar('--yj-bg-surface');
+
+    applyTheme('#ffd43b', 'light');
+
+    expect([darker, cssVar('--yj-bg-surface')]).toEqual(['#121212', '#f8f9fa']);
+  });
+
+  it('keeps semantic colours fixed across shades', () => {
+    const dark = cssVar('--yj-error');
+
+    applyTheme('#ffd43b', 'light');
+
+    expect([dark, cssVar('--yj-error')]).toEqual(['#e03131', '#e03131']);
+  });
+});
+
+describe('theme store: document integration', () => {
+  it('flags dark shades to Web Awesome, which otherwise renders white surfaces', () => {
+    applyTheme('#ffd43b', 'dark');
+    const darkFlagged = document.documentElement.classList.contains('wa-dark');
+
+    applyTheme('#ffd43b', 'light');
+
+    expect([
+      darkFlagged,
+      document.documentElement.classList.contains('wa-dark'),
+    ]).toEqual([true, false]);
+  });
+
+  it('sets color-scheme so native controls and scrollbars match', () => {
+    applyTheme('#ffd43b', 'light');
+    const light = document.documentElement.style.colorScheme;
+
+    applyTheme('#ffd43b', 'darker');
+
+    expect([light, document.documentElement.style.colorScheme]).toEqual([
+      'light',
+      'dark',
+    ]);
+  });
+
+  it('bridges the surface ramp onto Web Awesome custom properties', () => {
+    applyTheme('#ffd43b', 'darker');
+
+    expect([
+      cssVar('--wa-color-surface-default'),
+      cssVar('--wa-color-surface-raised'),
+      cssVar('--wa-color-surface-lowered'),
+    ]).toEqual(['#000000', '#121212', '#1e1e1e']);
+  });
+
+  it('is inherited through a shadow root', () => {
+    applyTheme('#ff0000', 'dark');
+
+    const host = document.createElement('div');
+    const root = host.attachShadow({ mode: 'open' });
+    const inner = document.createElement('span');
+
+    inner.style.color = 'var(--yj-accent)';
+    root.append(inner);
+    document.body.append(host);
+
+    const colour = getComputedStyle(inner).color;
+
+    host.remove();
+
+    expect(colour).toBe('rgb(255, 0, 0)');
+  });
+});
+
+describe('theme store: writes', () => {
+  it('sends a new accent to the backend rather than applying it locally', async () => {
+    applyTheme('#ffd43b', 'dark');
+    await themeStore.setAccentColor('#00ff00');
+
+    // The backend is the writer; the store waits for ThemeConfigChanged.
+    expect([
+      lastArgs('config.Config.SetThemeAccentColor'),
+      themeStore.getState().accentColor,
+    ]).toEqual([['#00ff00'], '#ffd43b']);
+  });
+
+  it('sends a new shade to the backend', async () => {
+    await themeStore.setBackgroundShade('light');
+
+    expect(lastArgs('config.Config.SetThemeBackgroundShade')).toEqual([
+      'light',
+    ]);
+  });
+});

frontend/test/stores/view-stores.test.ts

@@ -0,0 +1,189 @@
+/**
+ * The three small stores behind view chrome: the global search term,
+ * the track list's column set, and the explore cache that keeps detail
+ * pages from re-fetching what a search already returned.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import { searchStore } from '@store/search-store';
+import { trackListStore } from '@store/tracklist-store';
+import { exploreCache } from '@store/explore-cache';
+import { Events } from '../../src/events';
+import { emit, lastCall, flush } from '@test/support/harness';
+
+describe('search store', () => {
+  beforeEach(() => {
+    searchStore.setTerm('');
+    searchStore.setCurrentView('tracks');
+  });
+
+  it('holds the term', () => {
+    searchStore.setTerm('bowie');
+
+    expect(searchStore.getTerm()).toBe('bowie');
+  });
+
+  it('does not notify when the term is unchanged', () => {
+    let notifications = 0;
+    const off = searchStore.subscribe(() => {
+      notifications += 1;
+    });
+
+    searchStore.setTerm('bowie');
+    searchStore.setTerm('bowie');
+    off();
+
+    expect(notifications).toBe(1);
+  });
+
+  it('notifies synchronously — the search box has no batching to hide behind', () => {
+    let notified = false;
+    const off = searchStore.subscribe(() => {
+      notified = true;
+    });
+
+    searchStore.setTerm('x');
+    off();
+
+    expect(notified).toBe(true);
+  });
+
+  it('knows which views the search box applies to', () => {
+    const searchable = [
+      'tracks',
+      'albums',
+      'playlists',
+      'playlist-details',
+      'artists',
+      'genres',
+    ].map((view) => {
+      searchStore.setCurrentView(view);
+
+      return searchStore.isSearchableView();
+    });
+
+    expect(searchable.every(Boolean)).toBe(true);
+  });
+
+  it('hides the search box on views it cannot filter', () => {
+    const results = ['settings', 'explore', 'jobs', 'downloads'].map((view) => {
+      searchStore.setCurrentView(view);
+
+      return searchStore.isSearchableView();
+    });
+
+    expect(results).toEqual([false, false, false, false]);
+  });
+});
+
+describe('track list store', () => {
+  it('starts from the default column set', () => {
+    expect(trackListStore.getState().columnIds.length).toBeGreaterThan(0);
+  });
+
+  it('adopts the column order the backend pushes', () => {
+    emit(Events.TrackListConfigChanged, {
+      columns: [{ id: 'title' }, { id: 'artist' }],
+    });
+
+    expect(trackListStore.getState().columnIds).toEqual(['title', 'artist']);
+  });
+
+  it('sends columns back as objects, the shape the Go binding expects', async () => {
+    await trackListStore.setColumns(['title', 'album']);
+
+    // A bare string array would be a type mismatch, and a Wails binding
+    // called with wrong argument types never settles its callback.
+    expect(lastCall('config.Config.SetTrackListColumns')?.args).toEqual([
+      [{ id: 'title' }, { id: 'album' }],
+    ]);
+  });
+
+  it('does not apply a column change until the backend confirms it', async () => {
+    emit(Events.TrackListConfigChanged, { columns: [{ id: 'title' }] });
+    await trackListStore.setColumns(['title', 'album', 'year']);
+    await flush();
+
+    expect(trackListStore.getState().columnIds).toEqual(['title']);
+  });
+});
+
+describe('explore cache', () => {
+  it('round-trips an artist by mbid', () => {
+    exploreCache.setArtist('mbid-1', { mbid: 'mbid-1', name: 'Bowie' });
+
+    expect(exploreCache.getArtist('mbid-1')?.name).toBe('Bowie');
+  });
+
+  it('misses cleanly for an unknown mbid', () => {
+    expect(exploreCache.getArtist('nothing-here')).toBeUndefined();
+  });
+
+  it('refuses to key anything under an empty mbid', () => {
+    // An empty key would collide across every unidentified entity.
+    exploreCache.setArtist('', { mbid: '', name: 'Unknown' });
+    exploreCache.setAlbum('', { mbid: '', title: 'X', artistName: 'Y' });
+
+    expect([exploreCache.getArtist(''), exploreCache.getAlbum('')]).toEqual([
+      undefined,
+      undefined,
+    ]);
+  });
+
+  it('overwrites an entry with richer data from a later fetch', () => {
+    exploreCache.setArtist('mbid-2', { mbid: 'mbid-2', name: 'Eno' });
+    exploreCache.setArtist('mbid-2', {
+      mbid: 'mbid-2',
+      name: 'Eno',
+      imageURL: 'http://x/eno.jpg',
+    });
+
+    expect(exploreCache.getArtist('mbid-2')?.imageURL).toBe('http://x/eno.jpg');
+  });
+
+  it('caches an artist’s release groups and top tracks separately', () => {
+    exploreCache.setArtistAlbums('mbid-3', [{ mbid: 'rg-1' }] as never);
+    exploreCache.setArtistTopTracks('mbid-3', [{ mbid: 'rec-1' }] as never);
+
+    expect([
+      exploreCache.getArtistAlbums('mbid-3')?.length,
+      exploreCache.getArtistTopTracks('mbid-3')?.length,
+    ]).toEqual([1, 1]);
+  });
+
+  it('populates artists and albums from one search result', () => {
+    exploreCache.populateFromSearch(
+      [{ mbid: 'a-1', name: 'Artist', _imageSmall: 's.jpg' }],
+      [
+        {
+          mbid: 'rg-1',
+          title: 'Album',
+          artistCredit: 'Artist',
+          _coverArt: 'c.jpg',
+          firstReleaseDate: '1977',
+        },
+      ],
+    );
+
+    expect([
+      exploreCache.getArtist('a-1')?.imageSmall,
+      exploreCache.getAlbum('rg-1')?.year,
+      exploreCache.getAlbum('rg-1')?.artistName,
+    ]).toEqual(['s.jpg', '1977', 'Artist']);
+  });
+
+  it('defaults a missing artist credit to empty rather than undefined', () => {
+    exploreCache.populateFromSearch([], [{ mbid: 'rg-2', title: 'Untitled' }]);
+
+    expect(exploreCache.getAlbum('rg-2')?.artistName).toBe('');
+  });
+
+  it('skips search entries that carry no mbid', () => {
+    exploreCache.populateFromSearch(
+      [{ name: 'Nameless' }],
+      [{ title: 'Nameless' }],
+    );
+
+    expect(exploreCache.getArtist('')).toBeUndefined();
+  });
+});

frontend/test/support/harness.ts

@@ -0,0 +1,71 @@
+/**
+ * Helpers on top of the Wails fake: pushing backend events, stubbing
+ * bound methods, and inspecting what the frontend called back.
+ */
+import { wails, type BindingCall } from './wails-fake';
+
+export { wails } from './wails-fake';
+
+/**
+ * Push a backend event into the page, exactly as `runtime.EventsEmit`
+ * on the Go side would. Extra arguments become the event's data array.
+ */
+export function emit(name: string, ...data: unknown[]): void {
+  wails.notify(name, data);
+}
+
+/**
+ * Register the return value of a bound method. The path is the one the
+ * generated bindings use — `service.Type.Method`, e.g.
+ * `config.Config.GetShortcuts`.
+ *
+ * A function value is called with the invocation's arguments, so a stub
+ * can vary by input.
+ */
+export function stub(path: string, value: unknown): void {
+  wails.stub(path, value);
+}
+
+/**
+ * Make a bound method fail, as a Go method returning an error does:
+ * the promise rejects, it does not throw into the caller.
+ */
+export function stubFailure(path: string, message = 'backend error'): void {
+  wails.stub(path, () => {
+    throw new Error(message);
+  });
+}
+
+/** Every call made to a bound method, in order. */
+export function calls(path?: string): BindingCall[] {
+  if (path === undefined) return wails.calls.slice();
+
+  return wails.calls.filter((c) => c.path === path);
+}
+
+/** The most recent call to `path`, or undefined. */
+export function lastCall(path: string): BindingCall | undefined {
+  return calls(path).at(-1);
+}
+
+/** The argument list of the most recent call to `path`. */
+export function lastArgs(path: string): unknown[] | undefined {
+  return lastCall(path)?.args;
+}
+
+/**
+ * Flush pending microtasks. Stores coalesce subscriber notification
+ * through `queueMicrotask`, so state is observable immediately but
+ * subscribers are not — anything asserting on a subscriber must await
+ * this first.
+ */
+export async function flush(): Promise<void> {
+  await new Promise<void>((resolve) => {
+    setTimeout(resolve, 0);
+  });
+}
+
+/** Clears recorded calls and stubs between tests. */
+export function resetHarness(): void {
+  wails.reset();
+}

frontend/test/support/render.ts

@@ -0,0 +1,123 @@
+/**
+ * Mounting helpers for component tests.
+ *
+ * Components are mounted into a real document and queried through their
+ * real (open) shadow roots — nothing here approximates the DOM, which
+ * is the whole reason this tier runs in a browser.
+ */
+import type { LitElement } from 'lit';
+import { expect } from 'vitest';
+
+const mounted: HTMLElement[] = [];
+
+/**
+ * Create an element, apply properties, mount it and wait for Lit's
+ * first render. Properties are set as *properties*, not attributes, so
+ * non-string values survive.
+ */
+export async function fixture<T extends LitElement>(
+  tag: string,
+  props: Record<string, unknown> = {},
+): Promise<T> {
+  const el = document.createElement(tag) as T;
+
+  Object.assign(el, props);
+  document.body.append(el);
+  mounted.push(el);
+
+  await el.updateComplete;
+
+  return el;
+}
+
+/** Apply properties to a mounted element and wait for the re-render. */
+export async function update<T extends LitElement>(
+  el: T,
+  props: Record<string, unknown>,
+): Promise<T> {
+  Object.assign(el, props);
+  el.requestUpdate();
+  await el.updateComplete;
+
+  return el;
+}
+
+/** Remove everything mounted by this module. Called from setup. */
+export function cleanupFixtures(): void {
+  while (mounted.length > 0) mounted.pop()?.remove();
+}
+
+// ===================================================================
+// SHADOW DOM QUERIES
+// ===================================================================
+
+/** Query one element inside a component's shadow root. */
+export function shadow<E extends Element = Element>(
+  host: Element,
+  selector: string,
+): E | null {
+  return host.shadowRoot?.querySelector<E>(selector) ?? null;
+}
+
+/** Query all matching elements inside a component's shadow root. */
+export function shadowAll<E extends Element = Element>(
+  host: Element,
+  selector: string,
+): E[] {
+  return [...(host.shadowRoot?.querySelectorAll<E>(selector) ?? [])];
+}
+
+/** Trimmed text content of the first match, or null if absent. */
+export function text(host: Element, selector: string): string | null {
+  return shadow(host, selector)?.textContent?.trim() ?? null;
+}
+
+/** Trimmed text content of every match. */
+export function texts(host: Element, selector: string): string[] {
+  return shadowAll(host, selector).map((el) => el.textContent?.trim() ?? '');
+}
+
+/** The accessible names of every match, for assertions that mirror
+ *  what a screen reader — and a Playwright selector — would see. */
+export function labels(host: Element, selector: string): string[] {
+  return shadowAll(host, selector).map(
+    (el) => el.getAttribute('aria-label') ?? '',
+  );
+}
+
+/** Click something inside a shadow root and let the update settle. */
+export async function click(
+  host: LitElement,
+  selector: string,
+): Promise<void> {
+  const target = shadow<HTMLElement>(host, selector);
+
+  if (!target) throw new Error(`no element matching ${selector}`);
+
+  target.click();
+  await host.updateComplete;
+}
+
+// ===================================================================
+// VISUAL REGRESSION
+// ===================================================================
+
+/**
+ * Visual regression is opt-in: `toMatchScreenshot` baselines depend on
+ * font hinting and compositing, so a baseline taken on one machine
+ * fails on another for reasons that have nothing to do with the
+ * component. `make ui-visual` sets YJ_VISUAL=1; the default run
+ * asserts behaviour only.
+ */
+export const visualEnabled = import.meta.env['YJ_VISUAL'] === '1';
+
+/**
+ * Screenshot a component against its baseline, when visual regression
+ * is enabled. A no-op otherwise — deliberately not a skipped test, so
+ * the behavioural assertions around it still run.
+ */
+export async function visual(el: Element, name: string): Promise<void> {
+  if (!visualEnabled) return;
+
+  await expect(el).toMatchScreenshot(name);
+}

frontend/test/support/wails-fake.ts

@@ -0,0 +1,243 @@
+/**
+ * A fake of the two globals the Wails runtime installs: `window.runtime`
+ * and `window.go`.
+ *
+ * Everything in `frontend/wailsjs/` is a pure passthrough — every binding
+ * is `window['go'][svc][Type][Method](args)` and every runtime call is
+ * `window.runtime.X(...)`. So faking the globals means tests exercise the
+ * *real* generated bindings and the *real* store code, and there is no
+ * second description of the Wails layer free to drift from the first.
+ *
+ * The event dispatcher mirrors wails v2's
+ * `internal/frontend/runtime/desktop/events.js` exactly, including
+ * `maxCallbacks` expiry and the fact that `EventsEmit` notifies local JS
+ * listeners *before* it notifies Go.
+ */
+
+// ===================================================================
+// EVENT DISPATCH  (mirrors desktop/events.js)
+// ===================================================================
+
+type Callback = (...data: unknown[]) => void;
+
+class Listener {
+  private remaining: number;
+
+  constructor(
+    readonly eventName: string,
+    private readonly callback: Callback,
+    maxCallbacks: number,
+  ) {
+    this.remaining = maxCallbacks || -1;
+  }
+
+  /** Invokes the callback; returns true if this listener is spent. */
+  fire(data: unknown[]): boolean {
+    this.callback(...data);
+
+    if (this.remaining === -1) return false;
+
+    this.remaining -= 1;
+
+    return this.remaining === 0;
+  }
+}
+
+/** Records one bound-method invocation. */
+export interface BindingCall {
+  /** Dotted path, e.g. `queue.Queue.SetQueue`. */
+  path: string;
+  args: unknown[];
+}
+
+type StubValue = unknown | ((...args: unknown[]) => unknown);
+
+class WailsFake {
+  private listeners = new Map<string, Listener[]>();
+  private stubs = new Map<string, StubValue>();
+
+  /** Every bound-method call made since the last `reset()`. */
+  readonly calls: BindingCall[] = [];
+
+  /** Every runtime (non-binding) call, e.g. `WindowSetTitle`. */
+  readonly runtimeCalls: BindingCall[] = [];
+
+  // -- listener registry --
+
+  on(eventName: string, callback: Callback, maxCallbacks: number): () => void {
+    const listener = new Listener(eventName, callback, maxCallbacks);
+    const existing = this.listeners.get(eventName);
+
+    if (existing) {
+      existing.push(listener);
+    } else {
+      this.listeners.set(eventName, [listener]);
+    }
+
+    return () => this.off(eventName, listener);
+  }
+
+  private off(eventName: string, listener: Listener): void {
+    const list = this.listeners.get(eventName);
+
+    if (!list) return;
+
+    const idx = list.indexOf(listener);
+
+    if (idx >= 0) list.splice(idx, 1);
+    if (list.length === 0) this.listeners.delete(eventName);
+  }
+
+  offNamed(eventName: string, ...more: string[]): void {
+    for (const name of [eventName, ...more]) {
+      this.listeners.delete(name);
+    }
+  }
+
+  offAll(): void {
+    this.listeners.clear();
+  }
+
+  /**
+   * Deliver an event exactly as the backend push does. Iterates in
+   * reverse and drops spent listeners, like `notifyListeners`.
+   */
+  notify(eventName: string, data: unknown[]): void {
+    const list = this.listeners.get(eventName);
+
+    if (!list || list.length === 0) return;
+
+    const snapshot = list.slice();
+
+    for (let i = snapshot.length - 1; i >= 0; i -= 1) {
+      const listener = snapshot[i];
+
+      if (!listener) continue;
+
+      if (listener.fire(data)) snapshot.splice(i, 1);
+    }
+
+    if (snapshot.length === 0) {
+      this.listeners.delete(eventName);
+    } else {
+      this.listeners.set(eventName, snapshot);
+    }
+  }
+
+  /** Names with at least one live listener — useful for assertions. */
+  listenerNames(): string[] {
+    return [...this.listeners.keys()].sort();
+  }
+
+  // -- binding stubs --
+
+  stub(path: string, value: StubValue): void {
+    this.stubs.set(path, value);
+  }
+
+  invoke(path: string, args: unknown[]): Promise<unknown> {
+    this.calls.push({ path, args });
+
+    const stub = this.stubs.get(path);
+
+    if (typeof stub === 'function') {
+      // A throwing stub becomes a rejected promise, matching the real
+      // bridge: a Go method returning an error rejects, it does not
+      // throw synchronously into the caller.
+      try {
+        return Promise.resolve(
+          (stub as (...a: unknown[]) => unknown)(...args),
+        );
+      } catch (err) {
+        return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+
+    return Promise.resolve(stub);
+  }
+
+  recordRuntime(path: string, args: unknown[]): void {
+    this.runtimeCalls.push({ path, args });
+  }
+
+  /** Clears recorded calls and stubs. Listeners survive — the store
+   *  singletons that registered them are never re-imported. */
+  reset(): void {
+    this.calls.length = 0;
+    this.runtimeCalls.length = 0;
+    this.stubs.clear();
+  }
+}
+
+// ===================================================================
+// GLOBAL INSTALLATION
+// ===================================================================
+
+export const wails = new WailsFake();
+
+/** A `window.go` that materialises `svc.Type.Method` lazily. */
+function makeGoProxy(): unknown {
+  const level = (prefix: string): unknown =>
+    new Proxy(function () {} as unknown as Record<string, unknown>, {
+      get(_target, prop: string | symbol) {
+        if (typeof prop !== 'string') return undefined;
+
+        return level(prefix ? `${prefix}.${prop}` : prop);
+      },
+      apply(_target, _thisArg, args: unknown[]) {
+        return wails.invoke(prefix, args);
+      },
+    });
+
+  return level('');
+}
+
+/** A `window.runtime` with real event plumbing and recorded no-ops
+ *  for everything else (window, clipboard, browser, log). */
+function makeRuntimeProxy(): unknown {
+  const real: Record<string, unknown> = {
+    EventsOnMultiple: (name: string, cb: Callback, max: number) =>
+      wails.on(name, cb, max),
+    EventsOn: (name: string, cb: Callback) => wails.on(name, cb, -1),
+    EventsOnce: (name: string, cb: Callback) => wails.on(name, cb, 1),
+    EventsOff: (name: string, ...more: string[]) =>
+      wails.offNamed(name, ...more),
+    EventsOffAll: () => wails.offAll(),
+    // The real runtime notifies local JS listeners first, then Go.
+    EventsEmit: (name: string, ...data: unknown[]) => {
+      wails.recordRuntime(`EventsEmit:${name}`, data);
+      wails.notify(name, data);
+    },
+  };
+
+  return new Proxy(real, {
+    get(target, prop: string | symbol) {
+      if (typeof prop !== 'string') return undefined;
+      if (prop in target) return target[prop];
+
+      return (...args: unknown[]) => {
+        wails.recordRuntime(prop, args);
+
+        return undefined;
+      };
+    },
+  });
+}
+
+declare global {
+  interface Window {
+    go: unknown;
+    runtime: unknown;
+  }
+}
+
+/**
+ * Installs the fake. Must run before any module that imports a store,
+ * because the store singletons call `EventsOn` in their constructors at
+ * import time. `setupFiles` runs before test modules, which is exactly
+ * the window we need.
+ */
+export function installWailsFake(): void {
+  window.go = makeGoProxy();
+  window.runtime = makeRuntimeProxy();
+}