feat(stats): speed up session maintenance and improve stats UI (#111)

stats/src/components/anime/AnilistSelector.tsx

@@ -29,7 +29,7 @@ export function AnilistSelector({
   const [loading, setLoading] = useState(false);
   const [linking, setLinking] = useState<number | null>(null);
   const inputRef = useRef<HTMLInputElement>(null);
-  const debounceRef = useRef<ReturnType<typeof setTimeout>>();
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   useEffect(() => {
     inputRef.current?.focus();
@@ -53,7 +53,7 @@ export function AnilistSelector({
 
   const handleInput = (value: string) => {
     setQuery(value);
-    clearTimeout(debounceRef.current);
+    if (debounceRef.current) clearTimeout(debounceRef.current);
     debounceRef.current = setTimeout(() => doSearch(value), 400);
   };
 

stats/src/components/anime/AnimeCard.test.tsx

@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { AnimeCard } from './AnimeCard';
+
+test('AnimeCard includes linked AniList id in cover URLs to avoid stale library covers', () => {
+  const markup = renderToStaticMarkup(
+    <AnimeCard
+      anime={{
+        animeId: 42,
+        canonicalTitle: 'Test Anime',
+        anilistId: 21699,
+        totalSessions: 1,
+        totalActiveMs: 600_000,
+        totalCards: 0,
+        totalTokensSeen: 100,
+        episodeCount: 1,
+        episodesTotal: 10,
+        lastWatchedMs: 1_000,
+      }}
+      onClick={() => {}}
+    />,
+  );
+
+  assert.match(markup, /\/api\/stats\/anime\/42\/cover\?coverRetry=21699/);
+});

stats/src/components/anime/AnimeCard.tsx

@@ -18,6 +18,7 @@ export function AnimeCard({ anime, onClick }: AnimeCardProps) {
         <AnimeCoverImage
           animeId={anime.animeId}
           title={anime.canonicalTitle}
+          coverRetryToken={anime.anilistId ?? 0}
           className="w-full aspect-[3/4] rounded-t-lg transition-transform duration-200 group-hover:scale-105"
         />
       </div>

stats/src/components/anime/AnimeCoverImage.test.tsx

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { AnimeCoverImage } from './AnimeCoverImage';
+import { AnimeHeader } from './AnimeHeader';
+
+test('AnimeCoverImage includes manual relink cover retry tokens', () => {
+  const markup = renderToStaticMarkup(
+    <AnimeCoverImage animeId={42} title="Test Anime" coverRetryToken={7} />,
+  );
+
+  assert.match(markup, /\/api\/stats\/anime\/42\/cover\?coverRetry=7/);
+});
+
+test('AnimeHeader uses the linked AniList id to avoid stale cached cover art', () => {
+  const markup = renderToStaticMarkup(
+    <AnimeHeader
+      detail={{
+        animeId: 42,
+        canonicalTitle: 'Test Anime',
+        anilistId: 21699,
+        titleRomaji: null,
+        titleEnglish: null,
+        titleNative: null,
+        description: null,
+        totalSessions: 0,
+        totalActiveMs: 0,
+        totalCards: 0,
+        totalTokensSeen: 0,
+        totalLinesSeen: 0,
+        totalLookupCount: 0,
+        totalLookupHits: 0,
+        totalYomitanLookupCount: 0,
+        episodeCount: 1,
+        lastWatchedMs: 0,
+      }}
+      anilistEntries={[]}
+    />,
+  );
+
+  assert.match(markup, /\/api\/stats\/anime\/42\/cover\?coverRetry=21699/);
+});

stats/src/components/anime/AnimeCoverImage.tsx

@@ -1,35 +1,20 @@
-import { useState } from 'react';
+import { RetryingCoverImage } from '../common/RetryingCoverImage';
 import { getStatsClient } from '../../hooks/useStatsApi';
 
 interface AnimeCoverImageProps {
   animeId: number;
   title: string;
+  coverRetryToken?: number;
   className?: string;
 }
 
-export function AnimeCoverImage({ animeId, title, className = '' }: AnimeCoverImageProps) {
-  const [failed, setFailed] = useState(false);
-  const fallbackChar = title.charAt(0) || '?';
+export function AnimeCoverImage({
+  animeId,
+  title,
+  coverRetryToken = 0,
+  className = '',
+}: AnimeCoverImageProps) {
+  const src = getStatsClient().getAnimeCoverUrl(animeId, coverRetryToken);
 
-  if (failed) {
-    return (
-      <div
-        className={`bg-ctp-surface2 flex items-center justify-center text-ctp-overlay2 text-2xl font-bold ${className}`}
-      >
-        {fallbackChar}
-      </div>
-    );
-  }
-
-  const src = getStatsClient().getAnimeCoverUrl(animeId);
-
-  return (
-    <img
-      src={src}
-      alt={title}
-      loading="lazy"
-      className={`object-cover bg-ctp-surface2 ${className}`}
-      onError={() => setFailed(true)}
-    />
-  );
+  return <RetryingCoverImage src={src} alt={title} fallbackLabel={title} className={className} />;
 }

stats/src/components/anime/AnimeDetailView.tsx

@@ -142,8 +142,13 @@ export function AnimeDetailView({
 }: AnimeDetailViewProps) {
   const { data, loading, error, reload } = useAnimeDetail(animeId);
   const [showAnilistSelector, setShowAnilistSelector] = useState(false);
+  const [coverRetryToken, setCoverRetryToken] = useState(0);
   const knownWordsSummary = useAnimeKnownWords(animeId);
 
+  useEffect(() => {
+    setCoverRetryToken(0);
+  }, [animeId]);
+
   if (loading) return <div className="text-ctp-overlay2 p-4">Loading...</div>;
   if (error) return <div className="text-ctp-red p-4">Error: {error}</div>;
   if (!data?.detail) return <div className="text-ctp-overlay2 p-4">Anime not found</div>;
@@ -161,6 +166,7 @@ export function AnimeDetailView({
       <AnimeHeader
         detail={detail}
         anilistEntries={anilistEntries ?? []}
+        coverRetryToken={coverRetryToken}
         onChangeAnilist={() => setShowAnilistSelector(true)}
       />
       <AnimeOverviewStats detail={detail} knownWordsSummary={knownWordsSummary} />
@@ -177,6 +183,7 @@ export function AnimeDetailView({
           onClose={() => setShowAnilistSelector(false)}
           onLinked={() => {
             setShowAnilistSelector(false);
+            setCoverRetryToken((value) => value + 1);
             reload();
           }}
         />

stats/src/components/anime/AnimeHeader.tsx

@@ -4,6 +4,7 @@ import type { AnimeDetailData, AnilistEntry } from '../../types/stats';
 interface AnimeHeaderProps {
   detail: AnimeDetailData['detail'];
   anilistEntries: AnilistEntry[];
+  coverRetryToken?: number;
   onChangeAnilist?: () => void;
 }
 
@@ -26,19 +27,26 @@ function AnilistButton({ entry }: { entry: AnilistEntry }) {
   );
 }
 
-export function AnimeHeader({ detail, anilistEntries, onChangeAnilist }: AnimeHeaderProps) {
+export function AnimeHeader({
+  detail,
+  anilistEntries,
+  coverRetryToken = 0,
+  onChangeAnilist,
+}: AnimeHeaderProps) {
   const altTitles = [detail.titleRomaji, detail.titleEnglish, detail.titleNative].filter(
     (t): t is string => t != null && t !== detail.canonicalTitle,
   );
   const uniqueAltTitles = [...new Set(altTitles)];
 
   const hasMultipleEntries = anilistEntries.length > 1;
+  const coverCacheToken = (detail.anilistId ?? 0) * 1_000_000 + coverRetryToken;
 
   return (
     <div className="flex gap-4">
       <AnimeCoverImage
         animeId={detail.animeId}
         title={detail.canonicalTitle}
+        coverRetryToken={coverCacheToken}
         className="w-32 h-44 rounded-lg shrink-0"
       />
       <div className="flex-1 min-w-0">

stats/src/components/anime/AnimeTab.tsx

@@ -1,13 +1,18 @@
 import { useState, useMemo, useEffect } from 'react';
 import { useAnimeLibrary } from '../../hooks/useAnimeLibrary';
 import { formatDuration } from '../../lib/formatters';
+import {
+  getLibraryCardSizeStorage,
+  readLibraryCardSizePreference,
+  type LibraryCardSize,
+  writeLibraryCardSizePreference,
+} from '../../lib/library-card-size';
 import { AnimeCard } from './AnimeCard';
 import { AnimeDetailView } from './AnimeDetailView';
 
 type SortKey = 'lastWatched' | 'watchTime' | 'cards' | 'episodes';
-type CardSize = 'sm' | 'md' | 'lg';
 
-const GRID_CLASSES: Record<CardSize, string> = {
+const GRID_CLASSES: Record<LibraryCardSize, string> = {
   sm: 'grid-cols-5 sm:grid-cols-7 md:grid-cols-9 lg:grid-cols-11',
   md: 'grid-cols-4 sm:grid-cols-5 md:grid-cols-7 lg:grid-cols-9',
   lg: 'grid-cols-3 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-7',
@@ -51,9 +56,21 @@ export function AnimeTab({
   const { anime, loading, error } = useAnimeLibrary();
   const [search, setSearch] = useState('');
   const [sortKey, setSortKey] = useState<SortKey>('lastWatched');
-  const [cardSize, setCardSize] = useState<CardSize>('md');
+  const [cardSize, setCardSize] = useState<LibraryCardSize>(() =>
+    readLibraryCardSizePreference(
+      getLibraryCardSizeStorage(typeof window === 'undefined' ? null : window),
+    ),
+  );
   const [selectedAnimeId, setSelectedAnimeId] = useState<number | null>(null);
 
+  function handleCardSizeChange(size: LibraryCardSize): void {
+    setCardSize(size);
+    writeLibraryCardSizePreference(
+      getLibraryCardSizeStorage(typeof window === 'undefined' ? null : window),
+      size,
+    );
+  }
+
   useEffect(() => {
     if (initialAnimeId != null) {
       setSelectedAnimeId(initialAnimeId);
@@ -113,7 +130,7 @@ export function AnimeTab({
           {(['sm', 'md', 'lg'] as const).map((size) => (
             <button
               key={size}
-              onClick={() => setCardSize(size)}
+              onClick={() => handleCardSizeChange(size)}
               className={`px-2 py-1 rounded-md text-xs transition-colors ${
                 cardSize === size
                   ? 'bg-ctp-surface2 text-ctp-text shadow-sm'