Persist stats exclusions in DB and fix word metrics filtering

- Stats vocabulary exclusions stored in `imm_stats_excluded_words` (schema v18); seeded from localStorage on first load
- Session, overview, trends, and library word metrics use filtered persisted occurrences with raw fallback
- Session known-word % chart uses filtered persisted totals as denominator for both known and total
- JLPT subtitle styling changed to underline-only; no longer overrides text color

stats/src/components/sessions/SessionDetail.tsx

@@ -53,18 +53,31 @@ function formatTime(ms: number): string {
   });
 }
 
-/** Build a lookup: linesSeen → knownWordsSeen */
-function buildKnownWordsLookup(knownWordsTimeline: KnownWordsTimelinePoint[]): Map<number, number> {
-  const map = new Map<number, number>();
+type KnownWordsLineCounts = {
+  knownWordsSeen: number;
+  totalWordsSeen: number;
+};
+
+/** Build a lookup: linesSeen -> filtered known/total word counts */
+function buildKnownWordsLookup(
+  knownWordsTimeline: KnownWordsTimelinePoint[],
+): Map<number, KnownWordsLineCounts> {
+  const map = new Map<number, KnownWordsLineCounts>();
   for (const pt of knownWordsTimeline) {
-    map.set(pt.linesSeen, pt.knownWordsSeen);
+    map.set(pt.linesSeen, {
+      knownWordsSeen: pt.knownWordsSeen,
+      totalWordsSeen: pt.totalWordsSeen,
+    });
   }
   return map;
 }
 
-/** For a given linesSeen value, find the closest known words count (floor lookup). */
-function lookupKnownWords(map: Map<number, number>, linesSeen: number): number {
-  if (map.size === 0) return 0;
+/** For a given linesSeen value, find the closest filtered word counts (floor lookup). */
+function lookupKnownWordCounts(
+  map: Map<number, KnownWordsLineCounts>,
+  linesSeen: number,
+): KnownWordsLineCounts {
+  if (map.size === 0) return { knownWordsSeen: 0, totalWordsSeen: 0 };
   if (map.has(linesSeen)) return map.get(linesSeen)!;
   let best = 0;
   for (const k of map.keys()) {
@@ -72,7 +85,7 @@ function lookupKnownWords(map: Map<number, number>, linesSeen: number): number {
       best = k;
     }
   }
-  return best > 0 ? map.get(best)! : 0;
+  return best > 0 ? map.get(best)! : { knownWordsSeen: 0, totalWordsSeen: 0 };
 }
 
 interface RatioChartPoint {
@@ -93,6 +106,32 @@ type TimelineEntry = {
   tokensSeen: number;
 };
 
+export function buildKnownWordsRatioChartData(
+  sorted: TimelineEntry[],
+  knownWordsMap: Map<number, KnownWordsLineCounts>,
+): RatioChartPoint[] {
+  const chartData: RatioChartPoint[] = [];
+  for (const t of sorted) {
+    const counts = lookupKnownWordCounts(knownWordsMap, t.linesSeen);
+    const totalWords = counts.totalWordsSeen;
+    if (totalWords === 0) continue;
+    const knownWords = Math.min(counts.knownWordsSeen, totalWords);
+    const unknownWords = totalWords - knownWords;
+    chartData.push({
+      tsMs: t.sampleMs,
+      knownWords,
+      unknownWords,
+      totalWords,
+    });
+  }
+  return chartData;
+}
+
+export function getKnownPctAxisMax(values: number[]): number {
+  const max = Math.max(0, ...values.filter((value) => Number.isFinite(value)));
+  return Math.min(100, Math.ceil((max + 5) / 10) * 10);
+}
+
 function SessionChartOffsetProbe({
   offset,
   onPlotAreaChange,
@@ -291,7 +330,7 @@ function RatioView({
   session,
 }: {
   sorted: TimelineEntry[];
-  knownWordsMap: Map<number, number>;
+  knownWordsMap: Map<number, KnownWordsLineCounts>;
   cardEvents: SessionEvent[];
   yomitanLookupEvents: SessionEvent[];
   pauseRegions: Array<{ startMs: number; endMs: number }>;
@@ -309,19 +348,7 @@ function RatioView({
   session: SessionSummary;
 }) {
   const [plotArea, setPlotArea] = useState<SessionChartPlotArea | null>(null);
-  const chartData: RatioChartPoint[] = [];
-  for (const t of sorted) {
-    const totalWords = getSessionDisplayWordCount(t);
-    if (totalWords === 0) continue;
-    const knownWords = Math.min(lookupKnownWords(knownWordsMap, t.linesSeen), totalWords);
-    const unknownWords = totalWords - knownWords;
-    chartData.push({
-      tsMs: t.sampleMs,
-      knownWords,
-      unknownWords,
-      totalWords,
-    });
-  }
+  const chartData = buildKnownWordsRatioChartData(sorted, knownWordsMap);
 
   if (chartData.length === 0) {
     return <div className="text-ctp-overlay2 text-xs p-2">No word data for this session.</div>;

stats/src/hooks/useExcludedWords.test.ts

@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  getExcludedWordsSnapshot,
+  initializeExcludedWordsStore,
+  resetExcludedWordsStoreForTests,
+  setExcludedWords,
+} from './useExcludedWords';
+import { BASE_URL } from '../lib/api-client';
+
+const STORAGE_KEY = 'subminer-excluded-words';
+
+function installLocalStorage(initial: Record<string, string> = {}) {
+  const values = new Map(Object.entries(initial));
+  Object.defineProperty(globalThis, 'localStorage', {
+    configurable: true,
+    value: {
+      getItem: (key: string) => values.get(key) ?? null,
+      setItem: (key: string, value: string) => values.set(key, value),
+      removeItem: (key: string) => values.delete(key),
+    },
+  });
+  return values;
+}
+
+test('initializeExcludedWordsStore seeds empty database exclusions from localStorage', async () => {
+  resetExcludedWordsStoreForTests();
+  const localRows = [{ headword: '猫', word: '猫', reading: 'ねこ' }];
+  const storage = installLocalStorage({ [STORAGE_KEY]: JSON.stringify(localRows) });
+  const originalFetch = globalThis.fetch;
+  const requests: Array<{ url: string; method: string; body: string }> = [];
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    requests.push({
+      url: String(input),
+      method: init?.method ?? 'GET',
+      body: String(init?.body ?? ''),
+    });
+    if (!init?.method) {
+      return new Response(JSON.stringify([]), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    return new Response(JSON.stringify({ ok: true }), { status: 200 });
+  }) as typeof globalThis.fetch;
+
+  try {
+    await initializeExcludedWordsStore();
+
+    assert.deepEqual(getExcludedWordsSnapshot(), localRows);
+    assert.deepEqual(requests, [
+      { url: `${BASE_URL}/api/stats/excluded-words`, method: 'GET', body: '' },
+      {
+        url: `${BASE_URL}/api/stats/excluded-words`,
+        method: 'PUT',
+        body: JSON.stringify({ words: localRows }),
+      },
+    ]);
+    assert.equal(storage.get(STORAGE_KEY), JSON.stringify(localRows));
+  } finally {
+    globalThis.fetch = originalFetch;
+    resetExcludedWordsStoreForTests();
+  }
+});
+
+test('setExcludedWords updates the database-backed exclusion list', async () => {
+  resetExcludedWordsStoreForTests();
+  const storage = installLocalStorage();
+  const originalFetch = globalThis.fetch;
+  let seenBody = '';
+  globalThis.fetch = (async (_input: RequestInfo | URL, init?: RequestInit) => {
+    seenBody = String(init?.body ?? '');
+    return new Response(JSON.stringify({ ok: true }), { status: 200 });
+  }) as typeof globalThis.fetch;
+
+  try {
+    const rows = [{ headword: 'する', word: 'する', reading: 'する' }];
+    await setExcludedWords(rows);
+
+    assert.deepEqual(getExcludedWordsSnapshot(), rows);
+    assert.equal(seenBody, JSON.stringify({ words: rows }));
+    assert.equal(storage.get(STORAGE_KEY), JSON.stringify(rows));
+  } finally {
+    globalThis.fetch = originalFetch;
+    resetExcludedWordsStoreForTests();
+  }
+});

stats/src/hooks/useExcludedWords.ts

@@ -1,10 +1,8 @@
-import { useCallback, useSyncExternalStore } from 'react';
+import { useCallback, useEffect, useSyncExternalStore } from 'react';
+import { apiClient } from '../lib/api-client';
+import type { StatsExcludedWord } from '../types/stats';
 
-export interface ExcludedWord {
-  headword: string;
-  word: string;
-  reading: string;
-}
+export type ExcludedWord = StatsExcludedWord;
 
 const STORAGE_KEY = 'subminer-excluded-words';
 
@@ -14,16 +12,37 @@ function toKey(w: ExcludedWord): string {
 
 let cached: ExcludedWord[] | null = null;
 let cachedKeys: Set<string> | null = null;
+let initialized: Promise<void> | null = null;
+let revision = 0;
 const listeners = new Set<() => void>();
 
+function readLocalStorage(): ExcludedWord[] {
+  if (typeof localStorage === 'undefined') return [];
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    const parsed: unknown = raw ? JSON.parse(raw) : [];
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (row): row is ExcludedWord =>
+        row !== null &&
+        typeof row === 'object' &&
+        typeof (row as ExcludedWord).headword === 'string' &&
+        typeof (row as ExcludedWord).word === 'string' &&
+        typeof (row as ExcludedWord).reading === 'string',
+    );
+  } catch {
+    return [];
+  }
+}
+
+function writeLocalStorage(words: ExcludedWord[]): void {
+  if (typeof localStorage === 'undefined') return;
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(words));
+}
+
 function load(): ExcludedWord[] {
   if (cached) return cached;
-  try {
-    const raw = localStorage.getItem(STORAGE_KEY);
-    cached = raw ? JSON.parse(raw) : [];
-  } catch {
-    cached = [];
-  }
+  cached = readLocalStorage();
   return cached!;
 }
 
@@ -33,24 +52,73 @@ function getKeySet(): Set<string> {
   return cachedKeys;
 }
 
-function persist(words: ExcludedWord[]) {
+function applyWords(words: ExcludedWord[]): void {
   cached = words;
   cachedKeys = new Set(words.map(toKey));
-  localStorage.setItem(STORAGE_KEY, JSON.stringify(words));
+  writeLocalStorage(words);
   for (const fn of listeners) fn();
 }
 
-function getSnapshot(): ExcludedWord[] {
+export function getExcludedWordsSnapshot(): ExcludedWord[] {
   return load();
 }
 
+export async function setExcludedWords(words: ExcludedWord[]): Promise<void> {
+  revision += 1;
+  applyWords(words);
+  try {
+    await apiClient.setExcludedWords(words);
+  } catch (error) {
+    console.error('Failed to persist excluded words to stats database', error);
+  }
+}
+
+export function initializeExcludedWordsStore(): Promise<void> {
+  if (initialized) return initialized;
+  const startRevision = revision;
+  initialized = (async () => {
+    const localWords = load();
+    let dbWords: ExcludedWord[];
+    try {
+      dbWords = await apiClient.getExcludedWords();
+    } catch (error) {
+      console.error('Failed to load excluded words from stats database', error);
+      return;
+    }
+
+    if (revision !== startRevision) return;
+    if (dbWords.length > 0) {
+      applyWords(dbWords);
+      return;
+    }
+    if (localWords.length > 0) {
+      await setExcludedWords(localWords);
+      return;
+    }
+    applyWords([]);
+  })();
+  return initialized;
+}
+
+export function resetExcludedWordsStoreForTests(): void {
+  cached = null;
+  cachedKeys = null;
+  initialized = null;
+  revision = 0;
+  listeners.clear();
+}
+
 function subscribe(fn: () => void): () => void {
   listeners.add(fn);
   return () => listeners.delete(fn);
 }
 
 export function useExcludedWords() {
-  const excluded = useSyncExternalStore(subscribe, getSnapshot);
+  const excluded = useSyncExternalStore(subscribe, getExcludedWordsSnapshot);
+
+  useEffect(() => {
+    void initializeExcludedWordsStore();
+  }, []);
 
   const isExcluded = useCallback(
     (w: { headword: string; word: string; reading: string }) => getKeySet().has(toKey(w)),
@@ -61,17 +129,19 @@ export function useExcludedWords() {
     const key = toKey(w);
     const current = load();
     if (getKeySet().has(key)) {
-      persist(current.filter((e) => toKey(e) !== key));
+      void setExcludedWords(current.filter((e) => toKey(e) !== key));
     } else {
-      persist([...current, w]);
+      void setExcludedWords([...current, w]);
     }
   }, []);
 
   const removeExclusion = useCallback((w: ExcludedWord) => {
-    persist(load().filter((e) => toKey(e) !== toKey(w)));
+    void setExcludedWords(load().filter((e) => toKey(e) !== toKey(w)));
   }, []);
 
-  const clearAll = useCallback(() => persist([]), []);
+  const clearAll = useCallback(() => {
+    void setExcludedWords([]);
+  }, []);
 
   return { excluded, isExcluded, toggleExclusion, removeExclusion, clearAll };
 }

stats/src/hooks/useSessions.ts

@@ -42,6 +42,7 @@ export function useSessions(limit = 50) {
 export interface KnownWordsTimelinePoint {
   linesSeen: number;
   knownWordsSeen: number;
+  totalWordsSeen: number;
 }
 
 export function useSessionDetail(sessionId: number | null) {

stats/src/lib/api-client.test.ts

@@ -172,6 +172,50 @@ test('getSessionEvents can request only specific event types', async () => {
   }
 });
 
+test('getExcludedWords requests database-backed exclusions', async () => {
+  const originalFetch = globalThis.fetch;
+  let seenUrl = '';
+  globalThis.fetch = (async (input: RequestInfo | URL) => {
+    seenUrl = String(input);
+    return new Response(JSON.stringify([{ headword: '猫', word: '猫', reading: 'ねこ' }]), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }) as typeof globalThis.fetch;
+
+  try {
+    const words = await apiClient.getExcludedWords();
+    assert.equal(seenUrl, `${BASE_URL}/api/stats/excluded-words`);
+    assert.deepEqual(words, [{ headword: '猫', word: '猫', reading: 'ねこ' }]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('setExcludedWords replaces database-backed exclusions', async () => {
+  const originalFetch = globalThis.fetch;
+  let seenUrl = '';
+  let seenMethod = '';
+  let seenBody = '';
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    seenUrl = String(input);
+    seenMethod = init?.method ?? 'GET';
+    seenBody = String(init?.body ?? '');
+    return new Response(null, { status: 200 });
+  }) as typeof globalThis.fetch;
+
+  try {
+    await apiClient.setExcludedWords([{ headword: '猫', word: '猫', reading: 'ねこ' }]);
+    assert.equal(seenUrl, `${BASE_URL}/api/stats/excluded-words`);
+    assert.equal(seenMethod, 'PUT');
+    assert.deepEqual(JSON.parse(seenBody), {
+      words: [{ headword: '猫', word: '猫', reading: 'ねこ' }],
+    });
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 test('getSessionTimeline requests full session history when limit is omitted', async () => {
   const originalFetch = globalThis.fetch;
   let seenUrl = '';

stats/src/lib/api-client.ts

@@ -22,6 +22,7 @@ import type {
   KanjiDetailData,
   EpisodeDetailData,
   StatsAnkiNoteInfo,
+  StatsExcludedWord,
 } from '../types/stats';
 
 type StatsLocationLike = Pick<Location, 'protocol' | 'origin' | 'search'>;
@@ -85,11 +86,19 @@ export const apiClient = {
     return fetchJson<SessionEvent[]>(`/api/stats/sessions/${id}/events?${params.toString()}`);
   },
   getSessionKnownWordsTimeline: (id: number) =>
-    fetchJson<Array<{ linesSeen: number; knownWordsSeen: number }>>(
+    fetchJson<Array<{ linesSeen: number; knownWordsSeen: number; totalWordsSeen: number }>>(
       `/api/stats/sessions/${id}/known-words-timeline`,
     ),
   getVocabulary: (limit = 100) =>
     fetchJson<VocabularyEntry[]>(`/api/stats/vocabulary?limit=${limit}`),
+  getExcludedWords: () => fetchJson<StatsExcludedWord[]>('/api/stats/excluded-words'),
+  setExcludedWords: async (words: StatsExcludedWord[]): Promise<void> => {
+    await fetchResponse('/api/stats/excluded-words', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ words }),
+    });
+  },
   getWordOccurrences: (headword: string, word: string, reading: string, limit = 50, offset = 0) =>
     fetchJson<VocabularyOccurrenceEntry[]>(
       `/api/stats/vocabulary/occurrences?headword=${encodeURIComponent(headword)}&word=${encodeURIComponent(word)}&reading=${encodeURIComponent(reading)}&limit=${limit}&offset=${offset}`,

stats/src/lib/session-detail.test.tsx

@@ -1,7 +1,11 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { renderToStaticMarkup } from 'react-dom/server';
-import { SessionDetail, getKnownPctAxisMax } from '../components/sessions/SessionDetail';
+import {
+  SessionDetail,
+  buildKnownWordsRatioChartData,
+  getKnownPctAxisMax,
+} from '../components/sessions/SessionDetail';
 import { buildSessionChartEvents } from './session-events';
 import { EventType } from '../types/stats';
 
@@ -69,3 +73,21 @@ test('getKnownPctAxisMax adds headroom above the highest known percentage', () =
 test('getKnownPctAxisMax caps the chart top at 100%', () => {
   assert.equal(getKnownPctAxisMax([97.1, 98.6]), 100);
 });
+
+test('buildKnownWordsRatioChartData uses filtered known-word timeline totals', () => {
+  const chartData = buildKnownWordsRatioChartData(
+    [
+      { sampleMs: 1_000, linesSeen: 1, tokensSeen: 10 },
+      { sampleMs: 2_000, linesSeen: 2, tokensSeen: 20 },
+    ],
+    new Map([
+      [1, { knownWordsSeen: 2, totalWordsSeen: 3 }],
+      [2, { knownWordsSeen: 3, totalWordsSeen: 4 }],
+    ]),
+  );
+
+  assert.deepEqual(chartData, [
+    { tsMs: 1_000, knownWords: 2, unknownWords: 1, totalWords: 3 },
+    { tsMs: 2_000, knownWords: 3, unknownWords: 1, totalWords: 4 },
+  ]);
+});

stats/src/types/stats.ts

@@ -76,6 +76,12 @@ export interface VocabularyEntry {
   lastSeen: number;
 }
 
+export interface StatsExcludedWord {
+  headword: string;
+  word: string;
+  reading: string;
+}
+
 export interface KanjiEntry {
   kanjiId: number;
   kanji: string;