feat(player-stats): local listening history tab with heatmap and summaries (#849)

* feat(player-stats): local listening history tab with heatmap and summaries

Record play sessions in library.sqlite when the library index is enabled,
add Rust read APIs and Tauri commands for year/day aggregates, and ship the
Player stats UI with session clustering, event-driven live refresh, and a
notice when some servers are excluded from indexing.

* test(player-stats): split play_session repo and expand test coverage

Move the repository into play_session/ (completion, cluster, integration tests),
add remap/purge/FK coverage in Rust, and cover ingestion gates plus live-refresh
hooks on the frontend per spec v0.3.

* docs(release): CHANGELOG and credits for player stats (PR #849)

* fix(player-stats): satisfy tsc and clippy CI gates

Use InternetRadioStation field names in the radio skip test and replace
manual month/day range checks with RangeInclusive::contains.

src/hooks/tauriBridge/useMediaAndWindowBridge.ts

@@ -4,6 +4,7 @@ import { invoke } from '@tauri-apps/api/core';
 import { getCurrentWindow } from '@tauri-apps/api/window';
 import type { NavigateFunction } from 'react-router-dom';
 import { flushPlayQueuePosition } from '../../store/queueSync';
+import { playListenSessionFinalize } from '../../store/playListenSession';
 import { getPlaybackProgressSnapshot } from '../../store/playbackProgress';
 import { usePlayerStore } from '../../store/playerStore';
 import { useAuthStore } from '../../store/authStore';
@@ -107,6 +108,10 @@ export function useMediaAndWindowBridge(navigate: NavigateFunction) {
       // server can't keep the app hanging on quit; the playback heartbeat
       // is the safety net for anything that didn't make it out in time.
       const performExit = async () => {
+        await Promise.race([
+          playListenSessionFinalize('close'),
+          new Promise(r => setTimeout(r, 1500)),
+        ]);
         await Promise.race([
           flushPlayQueuePosition(),
           new Promise(r => setTimeout(r, 1500)),

src/hooks/usePlayerStatsLiveRefresh.test.ts

@@ -0,0 +1,39 @@
+import { renderHook } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { usePlayerStatsLiveRefresh } from './usePlayerStatsLiveRefresh';
+import { emitPlaySessionRecorded } from '../store/playSessionRecorded';
+
+describe('usePlayerStatsLiveRefresh', () => {
+  it('refreshes when a play session is recorded and the tab is visible', () => {
+    Object.defineProperty(document, 'visibilityState', {
+      configurable: true,
+      get: () => 'visible',
+    });
+    const onRefresh = vi.fn();
+    renderHook(() => usePlayerStatsLiveRefresh(onRefresh));
+    emitPlaySessionRecorded({ serverId: 's1', trackId: 't1', startedAtMs: 1 });
+    expect(onRefresh).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not refresh on record while the tab is hidden', () => {
+    Object.defineProperty(document, 'visibilityState', {
+      configurable: true,
+      get: () => 'hidden',
+    });
+    const onRefresh = vi.fn();
+    renderHook(() => usePlayerStatsLiveRefresh(onRefresh));
+    emitPlaySessionRecorded({ serverId: 's1', trackId: 't1', startedAtMs: 1 });
+    expect(onRefresh).not.toHaveBeenCalled();
+  });
+
+  it('refreshes when the tab becomes visible again', () => {
+    Object.defineProperty(document, 'visibilityState', {
+      configurable: true,
+      get: () => 'visible',
+    });
+    const onRefresh = vi.fn();
+    renderHook(() => usePlayerStatsLiveRefresh(onRefresh));
+    document.dispatchEvent(new Event('visibilitychange'));
+    expect(onRefresh).toHaveBeenCalledTimes(1);
+  });
+});

src/hooks/usePlayerStatsLiveRefresh.ts

@@ -0,0 +1,32 @@
+import { useEffect, useRef } from 'react';
+import { onPlaySessionRecorded } from '../store/playSessionRecorded';
+
+/** Refresh player stats when a listen is persisted or the tab becomes visible again. */
+export function usePlayerStatsLiveRefresh(onRefresh: () => void) {
+  const onRefreshRef = useRef(onRefresh);
+  onRefreshRef.current = onRefresh;
+
+  useEffect(() => {
+    const refreshIfVisible = () => {
+      if (document.visibilityState === 'visible') {
+        onRefreshRef.current();
+      }
+    };
+
+    const unsubRecorded = onPlaySessionRecorded(() => {
+      refreshIfVisible();
+    });
+
+    const onVisibility = () => {
+      if (document.visibilityState === 'visible') {
+        onRefreshRef.current();
+      }
+    };
+    document.addEventListener('visibilitychange', onVisibility);
+
+    return () => {
+      unsubRecorded();
+      document.removeEventListener('visibilitychange', onVisibility);
+    };
+  }, []);
+}