fix(stats): refresh vocabulary aggregates after exclusion edits

- Refetch vocabulary summary/charts once the exclusion list write is server-acknowledged, and retry failed aggregate loads with backoff before showing an inline error with a Retry control
- Coalesce concurrent getVocabularySummary calls into a single worker task
- Scan imm_words in id-keyed batches to bound memory for large vocabularies

stats/src/components/vocabulary/VocabularyTab.tsx

@@ -34,7 +34,18 @@ export function VocabularyTab({
   onRemoveExclusion,
   onClearExclusions,
 }: VocabularyTabProps) {
-  const { words, kanji, knownWords, summary, charts, loading, error, reload } = useVocabulary();
+  const {
+    words,
+    kanji,
+    knownWords,
+    summary,
+    charts,
+    loading,
+    error,
+    aggregatesError,
+    refreshAggregates,
+    reload,
+  } = useVocabulary();
   const [selectedKanjiId, setSelectedKanjiId] = useState<number | null>(null);
   const [hideNames, setHideNames] = useState(false);
   const [showExclusionManager, setShowExclusionManager] = useState(false);
@@ -49,21 +60,21 @@ export function VocabularyTab({
   }, [words, hideNames, excluded, isExcluded]);
   const chartData = useMemo(
     () => ({
-      topWords:
-        ((hideNames ? charts?.topWordsWithoutNames : charts?.topWords) ?? []).map((word) => ({
+      topWords: ((hideNames ? charts?.topWordsWithoutNames : charts?.topWords) ?? []).map(
+        (word) => ({
           label: word.headword,
           value: word.frequency,
-        })) ?? [],
-      newWordsTimeline:
-        ((hideNames ? charts?.newWordsTimelineWithoutNames : charts?.newWordsTimeline) ?? []).map(
-          (point) => ({
-            label: epochDayToDate(point.epochDay).toLocaleDateString(undefined, {
-              month: 'short',
-              day: 'numeric',
-            }),
-            value: point.wordCount,
-          }),
-        ) ?? [],
+        }),
+      ),
+      newWordsTimeline: (
+        (hideNames ? charts?.newWordsTimelineWithoutNames : charts?.newWordsTimeline) ?? []
+      ).map((point) => ({
+        label: epochDayToDate(point.epochDay).toLocaleDateString(undefined, {
+          month: 'short',
+          day: 'numeric',
+        }),
+        value: point.wordCount,
+      })),
     }),
     [charts, hideNames],
   );
@@ -139,6 +150,19 @@ export function VocabularyTab({
         />
       </div>
 
+      {aggregatesError && (
+        <p className="text-xs text-ctp-red" role="alert">
+          {aggregatesError}{' '}
+          <button
+            type="button"
+            onClick={refreshAggregates}
+            className="underline hover:text-ctp-text"
+          >
+            Retry
+          </button>
+        </p>
+      )}
+
       <div className="flex items-center justify-end gap-3">
         {hasNames && (
           <button

stats/src/hooks/useExcludedWords.ts

@@ -44,6 +44,16 @@ let cachedKeys: Set<string> | null = null;
 let initialized: Promise<void> | null = null;
 let revision = 0;
 const listeners = new Set<() => void>();
+// Fires only after the stats server acknowledged an exclusion write, so
+// subscribers can refetch server-computed aggregates without racing the POST.
+const serverSyncListeners = new Set<() => void>();
+
+export function subscribeExcludedWordsServerSync(fn: () => void): () => void {
+  serverSyncListeners.add(fn);
+  return () => {
+    serverSyncListeners.delete(fn);
+  };
+}
 
 function readLocalStorage(): ExcludedWord[] {
   if (typeof localStorage === 'undefined') return [];
@@ -104,6 +114,7 @@ export async function setExcludedWords(words: ExcludedWord[]): Promise<void> {
   applyWords(normalized);
   try {
     await apiClient.setExcludedWords(normalized);
+    for (const fn of serverSyncListeners) fn();
   } catch (error) {
     if (revision === writeRevision) {
       revision = previousRevision;
@@ -155,6 +166,7 @@ export function resetExcludedWordsStoreForTests(): void {
   initialized = null;
   revision = 0;
   listeners.clear();
+  serverSyncListeners.clear();
 }
 
 function subscribe(fn: () => void): () => void {

stats/src/hooks/useVocabulary.ts

@@ -1,5 +1,6 @@
 import { useState, useEffect, useCallback } from 'react';
 import { getStatsClient } from './useStatsApi';
+import { subscribeExcludedWordsServerSync } from './useExcludedWords';
 import type {
   VocabularyEntry,
   KanjiEntry,
@@ -7,6 +8,17 @@ import type {
   StatsVocabularySummary,
 } from '../types/stats';
 
+const AGGREGATE_RETRY_BASE_MS = 1_000;
+const AGGREGATE_RETRY_MAX_MS = 30_000;
+const AGGREGATE_RETRY_LIMIT = 5;
+const CHART_BACKFILL_POLL_MS = 1_000;
+const CHART_BACKFILL_SLOW_POLL_MS = 5_000;
+const CHART_BACKFILL_FAST_POLLS = 30;
+
+function aggregateRetryDelayMs(attempt: number): number {
+  return Math.min(AGGREGATE_RETRY_BASE_MS * 2 ** attempt, AGGREGATE_RETRY_MAX_MS);
+}
+
 export function useVocabulary() {
   const [words, setWords] = useState<VocabularyEntry[]>([]);
   const [kanji, setKanji] = useState<KanjiEntry[]>([]);
@@ -15,16 +27,24 @@ export function useVocabulary() {
   const [charts, setCharts] = useState<StatsVocabularyCharts | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
+  const [aggregatesError, setAggregatesError] = useState<string | null>(null);
   // Bumped by `reload` after maintenance rewrites the vocabulary tables.
   const [reloadToken, setReloadToken] = useState(0);
-  const reload = useCallback(() => setReloadToken((token) => token + 1), []);
+  // Bumped independently when only the server-computed summary/charts are
+  // stale, e.g. after the exclusion list changes on the server.
+  const [aggregatesToken, setAggregatesToken] = useState(0);
+  const refreshAggregates = useCallback(() => setAggregatesToken((token) => token + 1), []);
+  const reload = useCallback(() => {
+    setReloadToken((token) => token + 1);
+    setAggregatesToken((token) => token + 1);
+  }, []);
+
+  useEffect(() => subscribeExcludedWordsServerSync(refreshAggregates), [refreshAggregates]);
 
   useEffect(() => {
     let cancelled = false;
     setLoading(true);
     setError(null);
-    setSummary(null);
-    setCharts(null);
     const client = getStatsClient();
     Promise.allSettled([client.getVocabulary(500), client.getKanji(200), client.getKnownWords()])
       .then(([wordsResult, kanjiResult, knownResult]) => {
@@ -55,36 +75,85 @@ export function useVocabulary() {
         if (cancelled) return;
         setLoading(false);
       });
-    void client
-      .getVocabularySummary()
-      .then((nextSummary) => {
-        if (!cancelled) setSummary(nextSummary);
-      })
-      .catch((summaryError: unknown) => {
-        console.error('Failed to load vocabulary summary', summaryError);
-      });
-    let chartRetryTimer: ReturnType<typeof setTimeout> | null = null;
-    const loadCharts = (): void => {
+    return () => {
+      cancelled = true;
+    };
+  }, [reloadToken]);
+
+  useEffect(() => {
+    let cancelled = false;
+    setAggregatesError(null);
+    const client = getStatsClient();
+    const timers = new Set<ReturnType<typeof setTimeout>>();
+    const schedule = (fn: () => void, delayMs: number): void => {
+      const timer = setTimeout(() => {
+        timers.delete(timer);
+        fn();
+      }, delayMs);
+      timers.add(timer);
+    };
+
+    const loadSummary = (attempt: number): void => {
+      void client
+        .getVocabularySummary()
+        .then((nextSummary) => {
+          if (!cancelled) setSummary(nextSummary);
+        })
+        .catch((summaryError: unknown) => {
+          console.error('Failed to load vocabulary summary', summaryError);
+          if (cancelled) return;
+          if (attempt + 1 < AGGREGATE_RETRY_LIMIT) {
+            schedule(() => loadSummary(attempt + 1), aggregateRetryDelayMs(attempt));
+          } else {
+            setAggregatesError((previous) => previous ?? 'Vocabulary totals failed to load.');
+          }
+        });
+    };
+
+    const loadCharts = (attempt: number, readyPolls: number): void => {
       void client
         .getVocabularyCharts()
         .then((nextCharts) => {
           if (cancelled) return;
           setCharts(nextCharts);
           if (!nextCharts.ready) {
-            chartRetryTimer = setTimeout(loadCharts, 1_000);
+            schedule(
+              () => loadCharts(0, readyPolls + 1),
+              readyPolls < CHART_BACKFILL_FAST_POLLS
+                ? CHART_BACKFILL_POLL_MS
+                : CHART_BACKFILL_SLOW_POLL_MS,
+            );
           }
         })
         .catch((chartError: unknown) => {
           console.error('Failed to load vocabulary charts', chartError);
-          if (!cancelled) chartRetryTimer = setTimeout(loadCharts, 1_000);
+          if (cancelled) return;
+          if (attempt + 1 < AGGREGATE_RETRY_LIMIT) {
+            schedule(() => loadCharts(attempt + 1, readyPolls), aggregateRetryDelayMs(attempt));
+          } else {
+            setAggregatesError((previous) => previous ?? 'Vocabulary charts failed to load.');
+          }
         });
     };
-    loadCharts();
+
+    loadSummary(0);
+    loadCharts(0, 0);
     return () => {
       cancelled = true;
-      if (chartRetryTimer) clearTimeout(chartRetryTimer);
+      for (const timer of timers) clearTimeout(timer);
     };
-  }, [reloadToken]);
+  }, [aggregatesToken]);
 
-  return { words, kanji, knownWords, summary, charts, loading, error, reload };
+  return {
+    words,
+    kanji,
+    knownWords,
+    summary,
+    charts,
+    loading,
+    error,
+    aggregatesError,
+    refreshAggregates,
+    reload,
+  };
 }

stats/src/lib/vocabulary-tab.test.ts

@@ -24,10 +24,7 @@ test('VocabularyTab declares all hooks before loading and error early returns',
 test('VocabularyTab uses uncapped server-side data for its charts and card totals', () => {
   const source = fs.readFileSync(VOCABULARY_TAB_PATH, 'utf8');
 
-  assert.match(
-    source,
-    /const \{ words, kanji, knownWords, summary, charts, loading, error, reload \} = useVocabulary\(\);/,
-  );
+  assert.match(source, /\} = useVocabulary\(\);/);
   assert.match(source, /charts\?\.topWordsWithoutNames/);
   assert.match(source, /charts\?\.newWordsTimelineWithoutNames/);
   assert.doesNotMatch(source, /buildVocabularySummary\(/);
@@ -36,6 +33,13 @@ test('VocabularyTab uses uncapped server-side data for its charts and card total
   assert.match(source, /value=\{summary \? formatNumber\(summary\.uniqueKanji\) : '…'\}/);
 });
 
+test('VocabularyTab surfaces aggregate failures with a retry control', () => {
+  const source = fs.readFileSync(VOCABULARY_TAB_PATH, 'utf8');
+
+  assert.match(source, /aggregatesError/);
+  assert.match(source, /onClick=\{refreshAggregates\}/);
+});
+
 test('useVocabulary loads exact card totals without holding up the vocabulary tables', () => {
   const source = fs.readFileSync(VOCABULARY_HOOK_PATH, 'utf8');
 
@@ -43,6 +47,20 @@ test('useVocabulary loads exact card totals without holding up the vocabulary ta
     source,
     /Promise\.allSettled\(\[\s*client\.getVocabulary\(500\),\s*client\.getKanji\(200\),\s*client\.getKnownWords\(\),?\s*\]\)/,
   );
-  assert.match(source, /void client\s*\.getVocabularySummary\(\)\s*\.then\(/);
+  assert.match(source, /client\s*\.getVocabularySummary\(\)\s*\.then\(/);
   assert.match(source, /client\s*\.getVocabularyCharts\(\)/);
 });
+
+test('useVocabulary refetches aggregates after server-acknowledged exclusion edits', () => {
+  const source = fs.readFileSync(VOCABULARY_HOOK_PATH, 'utf8');
+
+  assert.match(source, /subscribeExcludedWordsServerSync\(refreshAggregates\)/);
+});
+
+test('useVocabulary bounds aggregate retries instead of polling failures forever', () => {
+  const source = fs.readFileSync(VOCABULARY_HOOK_PATH, 'utf8');
+
+  assert.match(source, /AGGREGATE_RETRY_LIMIT/);
+  assert.match(source, /aggregateRetryDelayMs\(attempt\)/);
+  assert.match(source, /CHART_BACKFILL_SLOW_POLL_MS/);
+});