@octo-cyber/trainer 0.5.2

package/data/training-items.ts

@@ -0,0 +1,217 @@
+export type Category = 'ln' | 'nasal' | 'flat-retro' | 'hf' | 'r' | 'er'
+
+export interface TrainingItem {
+  id: string
+  char: string
+  pinyin: string
+  category: Category
+  correct: string
+  options: string[]
+  tip: string
+  confusedWith: string
+}
+
+export const CATEGORY_LABELS: Record<Category, string> = {
+  ln: 'l/n 不分',
+  nasal: '前后鼻音',
+  'flat-retro': '平翘舌',
+  hf: 'h/f 不分',
+  r: 'r 声母',
+  er: '儿化音',
+}
+
+export const CATEGORY_DESCRIPTIONS: Record<Category, string> = {
+  ln: '区分声母 l 和 n',
+  nasal: '区分 an/ang, en/eng, in/ing',
+  'flat-retro': '区分 z/zh, c/ch, s/sh',
+  hf: '区分声母 h 和 f',
+  r: '正确发出 r 声母',
+  er: '正确发出儿化音 er',
+}
+
+function ln(id: number, char: string, pinyin: string, correct: 'l' | 'n', confusedWith: string, tip: string): TrainingItem {
+  return { id: `ln-${id}`, char, pinyin, category: 'ln', correct, options: ['l', 'n'], tip, confusedWith }
+}
+
+function nasal(id: number, char: string, pinyin: string, correct: 'front' | 'back', confusedWith: string, tip: string): TrainingItem {
+  return { id: `nasal-${id}`, char, pinyin, category: 'nasal', correct: correct === 'front' ? '前鼻音' : '后鼻音', options: ['前鼻音', '后鼻音'], tip, confusedWith }
+}
+
+function fr(id: number, char: string, pinyin: string, correct: 'flat' | 'retro', confusedWith: string, tip: string): TrainingItem {
+  return { id: `fr-${id}`, char, pinyin, category: 'flat-retro', correct: correct === 'flat' ? '平舌' : '翘舌', options: ['平舌', '翘舌'], tip, confusedWith }
+}
+
+function hf(id: number, char: string, pinyin: string, correct: 'h' | 'f', confusedWith: string, tip: string): TrainingItem {
+  return { id: `hf-${id}`, char, pinyin, category: 'hf', correct: correct === 'h' ? 'h 声母' : 'f 声母', options: ['h 声母', 'f 声母'], tip, confusedWith }
+}
+
+// ═══════════ l/n 不分 ═══════════
+
+const LN_ITEMS: TrainingItem[] = [
+  ln(1, '女', 'nǚ', 'n', '旅', '舌尖抵上齿龈，气流从鼻腔出'),
+  ln(2, '旅', 'lǚ', 'l', '女', '舌尖抵上齿龈，气流从舌头两侧出'),
+  ln(3, '南', 'nán', 'n', '兰', '鼻音：捏住鼻子发不出来的是 n'),
+  ln(4, '兰', 'lán', 'l', '南', '边音：捏住鼻子仍能发出的是 l'),
+  ln(5, '脑', 'nǎo', 'n', '老', '鼻腔共振'),
+  ln(6, '老', 'lǎo', 'l', '脑', '舌侧出气'),
+  ln(7, '牛', 'niú', 'n', '刘', '鼻音，舌尖抵住上齿龈'),
+  ln(8, '刘', 'liú', 'l', '牛', '边音，气流从舌侧通过'),
+  ln(9, '泥', 'ní', 'n', '离', '鼻音'),
+  ln(10, '离', 'lí', 'l', '泥', '边音'),
+  ln(11, '怒', 'nù', 'n', '路', '鼻音'),
+  ln(12, '路', 'lù', 'l', '怒', '边音'),
+  ln(13, '内', 'nèi', 'n', '类', '鼻音'),
+  ln(14, '类', 'lèi', 'l', '内', '边音'),
+  ln(15, '年', 'nián', 'n', '连', '鼻音'),
+  ln(16, '连', 'lián', 'l', '年', '边音'),
+  ln(17, '娘', 'niáng', 'n', '凉', '鼻音'),
+  ln(18, '凉', 'liáng', 'l', '娘', '边音'),
+  ln(19, '农', 'nóng', 'n', '龙', '鼻音'),
+  ln(20, '龙', 'lóng', 'l', '农', '边音'),
+  ln(21, '暖', 'nuǎn', 'n', '乱', '鼻音'),
+  ln(22, '乱', 'luàn', 'l', '暖', '边音'),
+  ln(23, '能', 'néng', 'n', '冷', '鼻音'),
+  ln(24, '冷', 'lěng', 'l', '能', '边音'),
+  ln(25, '你', 'nǐ', 'n', '里', '鼻音'),
+  ln(26, '里', 'lǐ', 'l', '你', '边音'),
+  ln(27, '奶', 'nǎi', 'n', '来', '鼻音'),
+  ln(28, '来', 'lái', 'l', '奶', '边音'),
+  ln(29, '鸟', 'niǎo', 'n', '了', '鼻音'),
+  ln(30, '了', 'le', 'l', '鸟', '边音'),
+]
+
+// ═══════════ 前后鼻音 ═══════════
+
+const NASAL_ITEMS: TrainingItem[] = [
+  // an / ang
+  nasal(1, '班', 'bān', 'front', '帮', '前鼻音 an：舌尖抵上齿龈收尾'),
+  nasal(2, '帮', 'bāng', 'back', '班', '后鼻音 ang：舌根抵软腭收尾'),
+  nasal(3, '反', 'fǎn', 'front', '方', '前鼻音 an'),
+  nasal(4, '方', 'fāng', 'back', '反', '后鼻音 ang'),
+  nasal(5, '干', 'gān', 'front', '刚', '前鼻音 an'),
+  nasal(6, '刚', 'gāng', 'back', '干', '后鼻音 ang'),
+  nasal(7, '山', 'shān', 'front', '伤', '前鼻音 an'),
+  nasal(8, '伤', 'shāng', 'back', '山', '后鼻音 ang'),
+  nasal(9, '谈', 'tán', 'front', '糖', '前鼻音 an'),
+  nasal(10, '糖', 'táng', 'back', '谈', '后鼻音 ang'),
+  nasal(11, '蓝', 'lán', 'front', '郎', '前鼻音 an'),
+  nasal(12, '郎', 'láng', 'back', '蓝', '后鼻音 ang'),
+  // en / eng
+  nasal(13, '分', 'fēn', 'front', '风', '前鼻音 en：舌尖抵上齿龈'),
+  nasal(14, '风', 'fēng', 'back', '分', '后鼻音 eng：舌根后缩'),
+  nasal(15, '门', 'mén', 'front', '猛', '前鼻音 en'),
+  nasal(16, '猛', 'měng', 'back', '门', '后鼻音 eng'),
+  nasal(17, '真', 'zhēn', 'front', '正', '前鼻音 en'),
+  nasal(18, '正', 'zhèng', 'back', '真', '后鼻音 eng'),
+  nasal(19, '身', 'shēn', 'front', '生', '前鼻音 en'),
+  nasal(20, '生', 'shēng', 'back', '身', '后鼻音 eng'),
+  nasal(21, '人', 'rén', 'front', '仍', '前鼻音 en'),
+  nasal(22, '仍', 'réng', 'back', '人', '后鼻音 eng'),
+  // in / ing
+  nasal(23, '心', 'xīn', 'front', '星', '前鼻音 in：舌尖抵上齿龈'),
+  nasal(24, '星', 'xīng', 'back', '心', '后鼻音 ing：舌根后缩，嘴微开'),
+  nasal(25, '金', 'jīn', 'front', '京', '前鼻音 in'),
+  nasal(26, '京', 'jīng', 'back', '金', '后鼻音 ing'),
+  nasal(27, '林', 'lín', 'front', '灵', '前鼻音 in'),
+  nasal(28, '灵', 'líng', 'back', '林', '后鼻音 ing'),
+  nasal(29, '民', 'mín', 'front', '明', '前鼻音 in'),
+  nasal(30, '明', 'míng', 'back', '民', '后鼻音 ing'),
+  nasal(31, '品', 'pǐn', 'front', '拼', '前鼻音 in'),
+  nasal(32, '拼', 'pīng', 'back', '品', '后鼻音 ing'),
+  nasal(33, '信', 'xìn', 'front', '姓', '前鼻音 in'),
+  nasal(34, '姓', 'xìng', 'back', '信', '后鼻音 ing'),
+]
+
+// ═══════════ 平翘舌 ═══════════
+
+const FLAT_RETRO_ITEMS: TrainingItem[] = [
+  // z / zh
+  fr(1, '租', 'zū', 'flat', '猪', '平舌 z：舌尖平伸抵上齿背'),
+  fr(2, '猪', 'zhū', 'retro', '租', '翘舌 zh：舌尖翘起抵硬腭前部'),
+  fr(3, '资', 'zī', 'flat', '知', '平舌 z'),
+  fr(4, '知', 'zhī', 'retro', '资', '翘舌 zh'),
+  fr(5, '在', 'zài', 'flat', '窄', '平舌 z'),
+  fr(6, '窄', 'zhǎi', 'retro', '在', '翘舌 zh'),
+  fr(7, '增', 'zēng', 'flat', '争', '平舌 z'),
+  fr(8, '争', 'zhēng', 'retro', '增', '翘舌 zh'),
+  fr(9, '脏', 'zāng', 'flat', '张', '平舌 z'),
+  fr(10, '张', 'zhāng', 'retro', '脏', '翘舌 zh'),
+  // c / ch
+  fr(11, '草', 'cǎo', 'flat', '吵', '平舌 c：舌尖抵上齿背送气'),
+  fr(12, '吵', 'chǎo', 'retro', '草', '翘舌 ch：舌尖翘起送气'),
+  fr(13, '才', 'cái', 'flat', '柴', '平舌 c'),
+  fr(14, '柴', 'chái', 'retro', '才', '翘舌 ch'),
+  fr(15, '从', 'cóng', 'flat', '虫', '平舌 c'),
+  fr(16, '虫', 'chóng', 'retro', '从', '翘舌 ch'),
+  fr(17, '村', 'cūn', 'flat', '春', '平舌 c'),
+  fr(18, '春', 'chūn', 'retro', '村', '翘舌 ch'),
+  // s / sh
+  fr(19, '四', 'sì', 'flat', '是', '平舌 s：舌尖平伸，不翘'),
+  fr(20, '是', 'shì', 'retro', '四', '翘舌 sh：舌尖翘起'),
+  fr(21, '三', 'sān', 'flat', '山', '平舌 s'),
+  fr(22, '山', 'shān', 'retro', '三', '翘舌 sh'),
+  fr(23, '松', 'sōng', 'flat', '双', '平舌 s'),
+  fr(24, '双', 'shuāng', 'retro', '松', '翘舌 sh'),
+  fr(25, '送', 'sòng', 'flat', '受', '平舌 s'),
+  fr(26, '受', 'shòu', 'retro', '送', '翘舌 sh'),
+  fr(27, '扫', 'sǎo', 'flat', '少', '平舌 s'),
+  fr(28, '少', 'shǎo', 'retro', '扫', '翘舌 sh'),
+  fr(29, '苏', 'sū', 'flat', '书', '平舌 s'),
+  fr(30, '书', 'shū', 'retro', '苏', '翘舌 sh'),
+]
+
+// ═══════════ h/f 不分 ═══════════
+
+const HF_ITEMS: TrainingItem[] = [
+  hf(1, '飞', 'fēi', 'f', '灰', 'f：上齿咬下唇出气'),
+  hf(2, '灰', 'huī', 'h', '飞', 'h：舌根抬起，气流从喉部出'),
+  hf(3, '花', 'huā', 'h', '发', 'h：舌根音，不咬唇'),
+  hf(4, '发', 'fā', 'f', '花', 'f：唇齿音，上齿咬下唇'),
+  hf(5, '虎', 'hǔ', 'h', '斧', 'h：舌根音'),
+  hf(6, '斧', 'fǔ', 'f', '虎', 'f：唇齿音'),
+  hf(7, '回', 'huí', 'h', '肥', 'h：舌根音'),
+  hf(8, '肥', 'féi', 'f', '回', 'f：唇齿音'),
+  hf(9, '黄', 'huáng', 'h', '房', 'h：舌根音'),
+  hf(10, '房', 'fáng', 'f', '黄', 'f：唇齿音'),
+  hf(11, '红', 'hóng', 'h', '风', 'h：舌根音'),
+  hf(12, '风', 'fēng', 'f', '红', 'f：唇齿音'),
+  hf(13, '火', 'huǒ', 'h', '佛', 'h：舌根音'),
+  hf(14, '佛', 'fó', 'f', '火', 'f：唇齿音'),
+  hf(15, '婚', 'hūn', 'h', '分', 'h：舌根音'),
+  hf(16, '分', 'fēn', 'f', '婚', 'f：唇齿音'),
+]
+
+// ═══════════ r 声母 ═══════════
+
+const R_ITEMS: TrainingItem[] = [
+  { id: 'r-1', char: '人', pinyin: 'rén', category: 'r', correct: 'r', options: ['r', '其他'], tip: 'r：舌尖翘起接近硬腭，振动声带', confusedWith: '银' },
+  { id: 'r-2', char: '肉', pinyin: 'ròu', category: 'r', correct: 'r', options: ['r', '其他'], tip: '舌尖翘起，不要发成 y 或 l', confusedWith: '又' },
+  { id: 'r-3', char: '热', pinyin: 'rè', category: 'r', correct: 'r', options: ['r', '其他'], tip: '舌尖翘起接近硬腭', confusedWith: '乐' },
+  { id: 'r-4', char: '日', pinyin: 'rì', category: 'r', correct: 'r', options: ['r', '其他'], tip: '舌尖翘起，与 zh 位置相近但不阻塞气流', confusedWith: '一' },
+  { id: 'r-5', char: '让', pinyin: 'ràng', category: 'r', correct: 'r', options: ['r', '其他'], tip: '舌尖翘起接近硬腭，振动声带', confusedWith: '样' },
+  { id: 'r-6', char: '然', pinyin: 'rán', category: 'r', correct: 'r', options: ['r', '其他'], tip: '舌尖翘起接近硬腭', confusedWith: '颜' },
+  { id: 'r-7', char: '弱', pinyin: 'ruò', category: 'r', correct: 'r', options: ['r', '其他'], tip: '舌尖翘起，不要发成 l 或 y', confusedWith: '约' },
+  { id: 'r-8', char: '入', pinyin: 'rù', category: 'r', correct: 'r', options: ['r', '其他'], tip: '舌尖翘起接近硬腭', confusedWith: '玉' },
+]
+
+// ═══════════ 儿化音 ═══════════
+
+const ER_ITEMS: TrainingItem[] = [
+  { id: 'er-1', char: '二', pinyin: 'èr', category: 'er', correct: 'er', options: ['er', 'e'], tip: 'er：发 e 后舌尖卷起', confusedWith: '鹅' },
+  { id: 'er-2', char: '耳', pinyin: 'ěr', category: 'er', correct: 'er', options: ['er', 'e'], tip: '舌尖卷起抵住硬腭', confusedWith: '额' },
+  { id: 'er-3', char: '而', pinyin: 'ér', category: 'er', correct: 'er', options: ['er', 'e'], tip: '发 e 的同时舌尖上卷', confusedWith: '鹅' },
+  { id: 'er-4', char: '儿', pinyin: 'ér', category: 'er', correct: 'er', options: ['er', 'e'], tip: '舌尖卷起是关键', confusedWith: '额' },
+]
+
+export const ALL_ITEMS: TrainingItem[] = [
+  ...LN_ITEMS,
+  ...NASAL_ITEMS,
+  ...FLAT_RETRO_ITEMS,
+  ...HF_ITEMS,
+  ...R_ITEMS,
+  ...ER_ITEMS,
+]
+
+export function getItemsByCategory(category: Category): TrainingItem[] {
+  return ALL_ITEMS.filter((item) => item.category === category)
+}

package/lib/storage.ts

@@ -0,0 +1,76 @@
+import type { Category } from '@/data/training-items'
+
+interface WrongPoolEntry {
+  itemId: string
+  correctStreak: number
+}
+
+export interface UserProgress {
+  history: { itemId: string; correct: boolean; timestamp: number }[]
+  streak: number
+  lastPracticeDate: string
+  wrongPool: WrongPoolEntry[]
+  categoryStats: Record<Category, { correct: number; total: number }>
+}
+
+const STORAGE_KEY = 'trainer-progress'
+
+const DEFAULT_STATS: Record<Category, { correct: number; total: number }> = {
+  ln: { correct: 0, total: 0 },
+  nasal: { correct: 0, total: 0 },
+  'flat-retro': { correct: 0, total: 0 },
+  hf: { correct: 0, total: 0 },
+  r: { correct: 0, total: 0 },
+  er: { correct: 0, total: 0 },
+}
+
+export function loadProgress(): UserProgress {
+  if (typeof window === 'undefined') return createDefault()
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    if (!raw) return createDefault()
+    const data = JSON.parse(raw) as UserProgress
+    // Ensure all categories exist
+    if (!data.categoryStats) data.categoryStats = { ...DEFAULT_STATS }
+    for (const cat of Object.keys(DEFAULT_STATS) as Category[]) {
+      if (!data.categoryStats[cat]) data.categoryStats[cat] = { correct: 0, total: 0 }
+    }
+    return data
+  } catch {
+    return createDefault()
+  }
+}
+
+export function saveProgress(progress: UserProgress): void {
+  if (typeof window === 'undefined') return
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(progress))
+}
+
+function createDefault(): UserProgress {
+  return {
+    history: [],
+    streak: 0,
+    lastPracticeDate: '',
+    wrongPool: [],
+    categoryStats: { ...DEFAULT_STATS },
+  }
+}
+
+export function getToday(): string {
+  return new Date().toISOString().slice(0, 10)
+}
+
+export function isToday(dateStr: string): boolean {
+  return dateStr === getToday()
+}
+
+export function isYesterday(dateStr: string): boolean {
+  const yesterday = new Date()
+  yesterday.setDate(yesterday.getDate() - 1)
+  return dateStr === yesterday.toISOString().slice(0, 10)
+}
+
+export function getAccuracy(stats: { correct: number; total: number }): number {
+  if (stats.total === 0) return 0
+  return Math.round((stats.correct / stats.total) * 100)
+}

package/lib/tts.ts

@@ -0,0 +1,34 @@
+let supported: boolean | null = null
+
+export function isTtsAvailable(): boolean {
+  if (supported !== null) return supported
+  supported = typeof window !== 'undefined' && 'speechSynthesis' in window
+  return supported
+}
+
+export function speak(text: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!isTtsAvailable()) {
+      reject(new Error('TTS not supported'))
+      return
+    }
+
+    // Cancel any ongoing speech
+    window.speechSynthesis.cancel()
+
+    const utterance = new SpeechSynthesisUtterance(text)
+    utterance.lang = 'zh-CN'
+    utterance.rate = 0.8 // Slower for clarity
+    utterance.pitch = 1
+
+    // Try to find a Chinese voice
+    const voices = window.speechSynthesis.getVoices()
+    const zhVoice = voices.find((v) => v.lang.startsWith('zh'))
+    if (zhVoice) utterance.voice = zhVoice
+
+    utterance.onend = () => resolve()
+    utterance.onerror = (e) => reject(e)
+
+    window.speechSynthesis.speak(utterance)
+  })
+}

package/lib/use-practice.ts

@@ -0,0 +1,186 @@
+'use client'
+
+import { useState, useCallback, useEffect } from 'react'
+import { ALL_ITEMS, getItemsByCategory, type Category, type TrainingItem } from '@/data/training-items'
+import { loadProgress, saveProgress, getToday, isToday, isYesterday, type UserProgress } from './storage'
+
+export type PracticeState = 'idle' | 'question' | 'feedback' | 'done'
+
+export interface PracticeSession {
+  state: PracticeState
+  items: TrainingItem[]
+  currentIndex: number
+  answers: { itemId: string; selected: string; correct: boolean }[]
+  progress: UserProgress
+}
+
+function shuffle<T>(arr: T[]): T[] {
+  const a = [...arr]
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1))
+    ;[a[i], a[j]] = [a[j], a[i]]
+  }
+  return a
+}
+
+function pickItems(progress: UserProgress, category?: Category, count = 10): TrainingItem[] {
+  const pool = category ? getItemsByCategory(category) : ALL_ITEMS
+
+  // Priority 1: wrong pool items
+  const wrongIds = new Set(progress.wrongPool.map((w) => w.itemId))
+  const wrongItems = pool.filter((item) => wrongIds.has(item.id))
+
+  // Priority 2: weakest category items (if no specific category)
+  let remaining = pool.filter((item) => !wrongIds.has(item.id))
+  if (!category) {
+    const categories = Object.entries(progress.categoryStats)
+      .filter(([, stats]) => stats.total > 0)
+      .sort(([, a], [, b]) => {
+        const accA = a.total > 0 ? a.correct / a.total : 1
+        const accB = b.total > 0 ? b.correct / b.total : 1
+        return accA - accB // Weakest first
+      })
+
+    if (categories.length > 0) {
+      const weakest = categories[0][0] as Category
+      const weakItems = remaining.filter((item) => item.category === weakest)
+      const others = remaining.filter((item) => item.category !== weakest)
+      remaining = [...weakItems, ...others]
+    }
+  }
+
+  const selected = [...shuffle(wrongItems), ...shuffle(remaining)].slice(0, count)
+  return shuffle(selected)
+}
+
+export function usePractice() {
+  const [session, setSession] = useState<PracticeSession>({
+    state: 'idle',
+    items: [],
+    currentIndex: 0,
+    answers: [],
+    progress: loadProgress(),
+  })
+
+  // Load progress on mount
+  useEffect(() => {
+    setSession((s) => ({ ...s, progress: loadProgress() }))
+  }, [])
+
+  const startPractice = useCallback((category?: Category) => {
+    const progress = loadProgress()
+    const items = pickItems(progress, category)
+    setSession({
+      state: 'question',
+      items,
+      currentIndex: 0,
+      answers: [],
+      progress,
+    })
+  }, [])
+
+  const submitAnswer = useCallback((selected: string) => {
+    setSession((prev) => {
+      const item = prev.items[prev.currentIndex]
+      if (!item) return prev
+
+      const isCorrect = selected === item.correct
+      const newProgress = { ...prev.progress }
+
+      // Update category stats
+      const catStats = { ...newProgress.categoryStats[item.category] }
+      catStats.total++
+      if (isCorrect) catStats.correct++
+      newProgress.categoryStats = { ...newProgress.categoryStats, [item.category]: catStats }
+
+      // Update wrong pool
+      const wrongIdx = newProgress.wrongPool.findIndex((w) => w.itemId === item.id)
+      if (isCorrect) {
+        if (wrongIdx >= 0) {
+          const entry = { ...newProgress.wrongPool[wrongIdx] }
+          entry.correctStreak++
+          if (entry.correctStreak >= 3) {
+            // Remove from wrong pool
+            newProgress.wrongPool = newProgress.wrongPool.filter((_, i) => i !== wrongIdx)
+          } else {
+            newProgress.wrongPool = [...newProgress.wrongPool]
+            newProgress.wrongPool[wrongIdx] = entry
+          }
+        }
+      } else {
+        if (wrongIdx < 0) {
+          newProgress.wrongPool = [...newProgress.wrongPool, { itemId: item.id, correctStreak: 0 }]
+        } else {
+          // Reset streak
+          newProgress.wrongPool = [...newProgress.wrongPool]
+          newProgress.wrongPool[wrongIdx] = { itemId: item.id, correctStreak: 0 }
+        }
+      }
+
+      // Update history
+      newProgress.history = [
+        ...newProgress.history,
+        { itemId: item.id, correct: isCorrect, timestamp: Date.now() },
+      ]
+
+      const answer = { itemId: item.id, selected, correct: isCorrect }
+      saveProgress(newProgress)
+
+      return {
+        ...prev,
+        state: 'feedback',
+        answers: [...prev.answers, answer],
+        progress: newProgress,
+      }
+    })
+  }, [])
+
+  const nextQuestion = useCallback(() => {
+    setSession((prev) => {
+      const nextIdx = prev.currentIndex + 1
+      if (nextIdx >= prev.items.length) {
+        // Session complete — update streak
+        const newProgress = { ...prev.progress }
+        const today = getToday()
+
+        if (!isToday(newProgress.lastPracticeDate)) {
+          if (isYesterday(newProgress.lastPracticeDate)) {
+            newProgress.streak++
+          } else {
+            newProgress.streak = 1
+          }
+          newProgress.lastPracticeDate = today
+          saveProgress(newProgress)
+        }
+
+        return { ...prev, state: 'done', progress: newProgress }
+      }
+      return { ...prev, state: 'question', currentIndex: nextIdx }
+    })
+  }, [])
+
+  const reset = useCallback(() => {
+    setSession({
+      state: 'idle',
+      items: [],
+      currentIndex: 0,
+      answers: [],
+      progress: loadProgress(),
+    })
+  }, [])
+
+  const currentItem = session.items[session.currentIndex] ?? null
+  const lastAnswer = session.answers[session.answers.length - 1] ?? null
+  const todayDone = isToday(session.progress.lastPracticeDate)
+
+  return {
+    ...session,
+    currentItem,
+    lastAnswer,
+    todayDone,
+    startPractice,
+    submitAnswer,
+    nextQuestion,
+    reset,
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@octo-cyber/trainer",
+  "version": "0.5.2",
+  "description": "普通话纠音训练器 — 解决 l/n、前后鼻音、平翘舌等发音混淆",
+  "exports": {
+    "./web": {
+      "types": "./web/index.ts",
+      "import": "./web/index.ts",
+      "default": "./web/index.ts"
+    },
+    "./web/pages/*": {
+      "types": "./web/pages/*.tsx",
+      "import": "./web/pages/*.tsx",
+      "default": "./web/pages/*.tsx"
+    }
+  },
+  "dependencies": {
+    "@octo-cyber/core": "^0.5.4",
+    "@octo-cyber/ui": "^0.5.3"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "next-intl": ">=3",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jefflower/octo-trainer.git"
+  },
+  "publishMeta": {
+    "repository": "jefflower/octo-trainer",
+    "branch": "main",
+    "commitHash": "7df0d224921fed88b879a69d0119dca56a300dac",
+    "publishedAt": "2026-03-27T15:20:23.785Z",
+    "publishedFrom": "monorepo:packages/trainer"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/*.test.tsx", "**/*.spec.tsx"]
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "noEmit": true
+  },
+  "include": ["lib/**/*", "data/**/*", "web/**/*"]
+}

package/web/index.ts

@@ -0,0 +1,9 @@
+// Manifest
+export { trainerFrontendManifest } from './manifest'
+
+// i18n Messages
+export { default as trainerMessagesZhCN } from './messages/zh-CN.json'
+export { default as trainerMessagesEnUS } from './messages/en-US.json'
+
+// Pages
+export { default as TrainerPage } from './pages/TrainerPage'

package/web/manifest.ts

@@ -0,0 +1,18 @@
+import type { IFrontendManifest } from '@octo-cyber/core'
+
+export const trainerFrontendManifest: IFrontendManifest = {
+  moduleId: 'trainer',
+  icon: 'Mic',
+  color: 'violet',
+  position: 'main',
+  titleKey: 'trainer.title',
+  descriptionKey: 'trainer.description',
+  pages: [
+    {
+      path: '/trainer',
+      titleKey: 'trainer.pages.home',
+      icon: 'Mic',
+      component: '@octo-cyber/trainer/web/pages/TrainerPage',
+    },
+  ],
+}

package/web/messages/en-US.json

@@ -0,0 +1,46 @@
+{
+  "nav": {
+    "trainer": {
+      "title": "Pronunciation",
+      "description": "Mandarin pronunciation training",
+      "pages": {
+        "home": "Pronunciation"
+      }
+    }
+  },
+  "trainer": {
+    "home": {
+      "title": "Mandarin Pronunciation Trainer",
+      "subtitle": "5 minutes a day, fix pronunciation confusion",
+      "startPractice": "Start Daily Practice",
+      "todayDone": "Completed Today",
+      "categoryTitle": "Category Practice",
+      "notPracticed": "Not practiced",
+      "accuracy": "Accuracy {value}%",
+      "streak": "{count} day streak"
+    },
+    "quiz": {
+      "playAudio": "Play pronunciation",
+      "playing": "Playing...",
+      "nextQuestion": "Next",
+      "correct": "Correct!",
+      "wrong": "You chose \"{selected}\", correct answer is \"{correct}\"",
+      "confusedWith": "Confused with: {char}"
+    },
+    "result": {
+      "accuracy": "Accuracy {value}%",
+      "streak": "{count} day streak",
+      "needsWork": "Needs improvement",
+      "retry": "Practice again",
+      "backHome": "Back to home"
+    },
+    "categories": {
+      "ln": "l/n confusion",
+      "nasal": "Nasal finals",
+      "flat-retro": "Flat/Retroflex",
+      "hf": "h/f confusion",
+      "r": "r initial",
+      "er": "er sound"
+    }
+  }
+}

package/web/messages/zh-CN.json

@@ -0,0 +1,46 @@
+{
+  "nav": {
+    "trainer": {
+      "title": "纠音训练",
+      "description": "普通话发音纠正训练",
+      "pages": {
+        "home": "纠音训练"
+      }
+    }
+  },
+  "trainer": {
+    "home": {
+      "title": "普通话纠音训练",
+      "subtitle": "每天 5 分钟，告别发音混淆",
+      "startPractice": "开始今日练习",
+      "todayDone": "今日已完成",
+      "categoryTitle": "专项练习",
+      "notPracticed": "未练习",
+      "accuracy": "准确率 {value}%",
+      "streak": "连续打卡 {count} 天"
+    },
+    "quiz": {
+      "playAudio": "点击听发音",
+      "playing": "播放中...",
+      "nextQuestion": "下一题",
+      "correct": "正确！",
+      "wrong": "你选了「{selected}」，正确答案是「{correct}」",
+      "confusedWith": "易混字：{char}"
+    },
+    "result": {
+      "accuracy": "正确率 {value}%",
+      "streak": "连续打卡 {count} 天",
+      "needsWork": "需要加强",
+      "retry": "再练一组",
+      "backHome": "回到首页"
+    },
+    "categories": {
+      "ln": "l/n 不分",
+      "nasal": "前后鼻音",
+      "flat-retro": "平翘舌",
+      "hf": "h/f 不分",
+      "r": "r 声母",
+      "er": "儿化音"
+    }
+  }
+}

package/web/pages/TrainerPage.tsx

@@ -0,0 +1,388 @@
+'use client'
+
+import { useState, useCallback, useEffect, useRef } from 'react'
+import { useTranslations } from 'next-intl'
+import { Card, CardContent } from '@octo-cyber/ui/components/ui/card'
+import { Button } from '@octo-cyber/ui/components/ui/button'
+import { Badge } from '@octo-cyber/ui/components/ui/badge'
+import { Volume2 } from 'lucide-react'
+import {
+  ALL_ITEMS, getItemsByCategory, CATEGORY_LABELS,
+  type Category, type TrainingItem,
+} from '../../data/training-items'
+import {
+  loadProgress, saveProgress, getToday, isToday, isYesterday, getAccuracy,
+  type UserProgress,
+} from '../../lib/storage'
+import { speak, isTtsAvailable } from '../../lib/tts'
+
+// ── Types ──
+
+type ViewState = 'home' | 'question' | 'feedback' | 'done'
+
+interface Answer {
+  itemId: string
+  selected: string
+  correct: boolean
+}
+
+// ── Helpers ──
+
+function shuffle<T>(arr: T[]): T[] {
+  const a = [...arr]
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1))
+    ;[a[i], a[j]] = [a[j], a[i]]
+  }
+  return a
+}
+
+function pickItems(progress: UserProgress, category?: Category, count = 10): TrainingItem[] {
+  const pool = category ? getItemsByCategory(category) : ALL_ITEMS
+  const wrongIds = new Set(progress.wrongPool.map((w) => w.itemId))
+  const wrongItems = pool.filter((item) => wrongIds.has(item.id))
+  let remaining = pool.filter((item) => !wrongIds.has(item.id))
+
+  if (!category) {
+    const categories = Object.entries(progress.categoryStats)
+      .filter(([, stats]) => stats.total > 0)
+      .sort(([, a], [, b]) => {
+        const accA = a.total > 0 ? a.correct / a.total : 1
+        const accB = b.total > 0 ? b.correct / b.total : 1
+        return accA - accB
+      })
+    if (categories.length > 0) {
+      const weakest = categories[0][0] as Category
+      const weakItems = remaining.filter((item) => item.category === weakest)
+      const others = remaining.filter((item) => item.category !== weakest)
+      remaining = [...weakItems, ...others]
+    }
+  }
+
+  return shuffle([...shuffle(wrongItems), ...shuffle(remaining)].slice(0, count))
+}
+
+// ── Constants ──
+
+const CATEGORIES: Category[] = ['ln', 'nasal', 'flat-retro', 'hf', 'r', 'er']
+
+// ── Main Component ──
+
+export default function TrainerPage() {
+  const t = useTranslations('trainer')
+  const [view, setView] = useState<ViewState>('home')
+  const [items, setItems] = useState<TrainingItem[]>([])
+  const [currentIndex, setCurrentIndex] = useState(0)
+  const [answers, setAnswers] = useState<Answer[]>([])
+  const [progress, setProgress] = useState<UserProgress>(loadProgress)
+  const [isPlaying, setIsPlaying] = useState(false)
+  const mountedRef = useRef(false)
+
+  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true
+      setProgress(loadProgress())
+    }
+  }, [])
+
+  const todayDone = isToday(progress.lastPracticeDate)
+  const currentItem = items[currentIndex] ?? null
+  const lastAnswer = answers[answers.length - 1] ?? null
+
+  // ── Actions ──
+
+  const startPractice = useCallback((category?: Category) => {
+    const p = loadProgress()
+    setProgress(p)
+    setItems(pickItems(p, category))
+    setCurrentIndex(0)
+    setAnswers([])
+    setView('question')
+  }, [])
+
+  const submitAnswer = useCallback((selected: string) => {
+    if (!currentItem) return
+    const isCorrect = selected === currentItem.correct
+
+    setProgress((prev) => {
+      const np = { ...prev }
+      const cs = { ...np.categoryStats[currentItem.category] }
+      cs.total++
+      if (isCorrect) cs.correct++
+      np.categoryStats = { ...np.categoryStats, [currentItem.category]: cs }
+
+      const wrongIdx = np.wrongPool.findIndex((w) => w.itemId === currentItem.id)
+      if (isCorrect) {
+        if (wrongIdx >= 0) {
+          const entry = { ...np.wrongPool[wrongIdx] }
+          entry.correctStreak++
+          if (entry.correctStreak >= 3) {
+            np.wrongPool = np.wrongPool.filter((_, i) => i !== wrongIdx)
+          } else {
+            np.wrongPool = [...np.wrongPool]
+            np.wrongPool[wrongIdx] = entry
+          }
+        }
+      } else {
+        if (wrongIdx < 0) {
+          np.wrongPool = [...np.wrongPool, { itemId: currentItem.id, correctStreak: 0 }]
+        } else {
+          np.wrongPool = [...np.wrongPool]
+          np.wrongPool[wrongIdx] = { itemId: currentItem.id, correctStreak: 0 }
+        }
+      }
+
+      np.history = [...np.history, { itemId: currentItem.id, correct: isCorrect, timestamp: Date.now() }]
+      saveProgress(np)
+      return np
+    })
+
+    setAnswers((prev) => [...prev, { itemId: currentItem.id, selected, correct: isCorrect }])
+    setView('feedback')
+  }, [currentItem])
+
+  const nextQuestion = useCallback(() => {
+    const nextIdx = currentIndex + 1
+    if (nextIdx >= items.length) {
+      setProgress((prev) => {
+        const np = { ...prev }
+        const today = getToday()
+        if (!isToday(np.lastPracticeDate)) {
+          np.streak = isYesterday(np.lastPracticeDate) ? np.streak + 1 : 1
+          np.lastPracticeDate = today
+          saveProgress(np)
+        }
+        return np
+      })
+      setView('done')
+    } else {
+      setCurrentIndex(nextIdx)
+      setView('question')
+    }
+  }, [currentIndex, items.length])
+
+  const playAudio = useCallback(async () => {
+    if (!currentItem) return
+    setIsPlaying(true)
+    try { await speak(currentItem.char) } catch { /* TTS unavailable */ }
+    setIsPlaying(false)
+  }, [currentItem])
+
+  // ── Render ──
+
+  if (view === 'home') {
+    return (
+      <div className="mx-auto max-w-md space-y-6 py-6">
+        <div className="text-center">
+          <h1 className="text-2xl font-bold tracking-tight">{t('home.title')}</h1>
+          <p className="mt-1 text-sm text-muted-foreground">{t('home.subtitle')}</p>
+        </div>
+
+        {progress.streak > 0 && (
+          <Card className="bg-primary/5 border-primary/20">
+            <CardContent className="py-4 text-center">
+              <div className="text-3xl">🔥</div>
+              <div className="mt-1 text-lg font-bold">
+                {t('home.streak', { count: progress.streak })}
+              </div>
+            </CardContent>
+          </Card>
+        )}
+
+        <Button
+          onClick={() => startPractice()}
+          disabled={todayDone}
+          className="w-full py-6 text-lg"
+          size="lg"
+        >
+          {todayDone ? `✅ ${t('home.todayDone')}` : `▶ ${t('home.startPractice')}`}
+        </Button>
+
+        <div>
+          <h2 className="mb-3 text-sm font-semibold text-muted-foreground">
+            {t('home.categoryTitle')}
+          </h2>
+          <div className="grid grid-cols-2 gap-3">
+            {CATEGORIES.map((cat) => {
+              const stats = progress.categoryStats[cat]
+              const acc = getAccuracy(stats)
+              return (
+                <Card
+                  key={cat}
+                  className="cursor-pointer transition-shadow hover:shadow-md active:scale-[0.98]"
+                  onClick={() => startPractice(cat)}
+                >
+                  <CardContent className="p-3">
+                    <div className="text-sm font-medium">{t(`categories.${cat}`)}</div>
+                    <div className="mt-1 text-xs text-muted-foreground">
+                      {stats.total > 0 ? t('home.accuracy', { value: acc }) : t('home.notPracticed')}
+                    </div>
+                  </CardContent>
+                </Card>
+              )
+            })}
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  if ((view === 'question' || view === 'feedback') && currentItem) {
+    const progressValue = ((currentIndex + 1) / items.length) * 100
+    const ttsOk = isTtsAvailable()
+
+    return (
+      <div className="mx-auto max-w-md space-y-6 py-6">
+        {/* Progress */}
+        <div className="space-y-1">
+          <div className="flex justify-between text-xs text-muted-foreground">
+            <span>{CATEGORY_LABELS[currentItem.category]}</span>
+            <span>{currentIndex + 1}/{items.length}</span>
+          </div>
+          <div className="h-2 overflow-hidden rounded-full bg-muted">
+            <div className="h-full rounded-full bg-primary transition-all duration-300" style={{ width: `${progressValue}%` }} />
+          </div>
+        </div>
+
+        {/* Question card */}
+        <Card>
+          <CardContent className="py-12 text-center">
+            {view === 'question' && (
+              <>
+                <div className="font-bold" style={{ fontSize: '6rem', lineHeight: 1 }}>{currentItem.char}</div>
+                {ttsOk && (
+                  <Button
+                    onClick={playAudio}
+                    disabled={isPlaying}
+                    className="mt-4"
+                    variant="default"
+                  >
+                    <Volume2 className="mr-2 h-4 w-4" />
+                    {isPlaying ? t('quiz.playing') : t('quiz.playAudio')}
+                  </Button>
+                )}
+                {!ttsOk && (
+                  <div className="mt-4 font-mono text-lg text-muted-foreground">
+                    {currentItem.pinyin}
+                  </div>
+                )}
+              </>
+            )}
+
+            {view === 'feedback' && lastAnswer && (
+              <>
+                <div className="font-bold" style={{ fontSize: '5rem', lineHeight: 1 }}>{currentItem.char}</div>
+                <div className="mt-3 font-mono text-muted-foreground" style={{ fontSize: '1.25rem' }}>{currentItem.pinyin}</div>
+                <div className={`mt-4 rounded-xl px-4 py-3 ${lastAnswer.correct ? 'bg-green-50 dark:bg-green-950/30' : 'bg-red-50 dark:bg-red-950/30'}`}>
+                  {lastAnswer.correct ? (
+                    <div className="text-base font-semibold text-green-600 dark:text-green-400">
+                      ✅ {t('quiz.correct')}
+                    </div>
+                  ) : (
+                    <div>
+                      <div className="text-base font-semibold text-red-600 dark:text-red-400">
+                        ❌ {t('quiz.wrong', { selected: lastAnswer.selected, correct: currentItem.correct })}
+                      </div>
+                      <div className="mt-2 text-sm text-muted-foreground">
+                        💡 {currentItem.tip}
+                      </div>
+                      {currentItem.confusedWith && (
+                        <div className="mt-1 text-xs text-muted-foreground">
+                          {t('quiz.confusedWith', { char: currentItem.confusedWith })}
+                        </div>
+                      )}
+                    </div>
+                  )}
+                </div>
+              </>
+            )}
+          </CardContent>
+        </Card>
+
+        {/* Options / Next */}
+        {view === 'question' && (
+          <div className="grid grid-cols-2 gap-4">
+            {currentItem.options.map((opt) => (
+              <Button
+                key={opt}
+                variant="outline"
+                style={{ height: 'auto', padding: '2rem 0', fontSize: '1.25rem', fontWeight: 600 }}
+                className="hover:border-primary hover:bg-primary/5 hover:text-primary active:scale-[0.97] transition-all"
+                onClick={() => submitAnswer(opt)}
+              >
+                {opt}
+              </Button>
+            ))}
+          </div>
+        )}
+
+        {view === 'feedback' && (
+          <Button onClick={nextQuestion} className="w-full py-3" size="lg">
+            {t('quiz.nextQuestion')} →
+          </Button>
+        )}
+      </div>
+    )
+  }
+
+  if (view === 'done') {
+    const correct = answers.filter((a) => a.correct).length
+    const total = answers.length
+    const pct = total > 0 ? Math.round((correct / total) * 100) : 0
+
+    return (
+      <div className="mx-auto max-w-md space-y-6 py-6 text-center">
+        <Card>
+          <CardContent className="py-8">
+            <div style={{ fontSize: '4rem' }}>{pct >= 80 ? '🎉' : pct >= 60 ? '💪' : '📚'}</div>
+            <div className="mt-4 font-bold" style={{ fontSize: '3rem' }}>{correct}/{total}</div>
+            <div className="mt-1 text-sm text-muted-foreground">
+              {t('result.accuracy', { value: pct })}
+            </div>
+            {progress.streak > 0 && (
+              <Badge variant="secondary" className="mt-4">
+                🔥 {t('result.streak', { count: progress.streak })}
+              </Badge>
+            )}
+          </CardContent>
+        </Card>
+
+        {answers.some((a) => !a.correct) && (
+          <div className="text-left">
+            <h3 className="mb-2 text-sm font-semibold text-muted-foreground">
+              {t('result.needsWork')}
+            </h3>
+            <div className="space-y-2">
+              {answers.filter((a) => !a.correct).map((a) => {
+                const item = items.find((i) => i.id === a.itemId)
+                if (!item) return null
+                return (
+                  <Card key={a.itemId} className="bg-red-50 dark:bg-red-950/20 border-red-200 dark:border-red-900">
+                    <CardContent className="flex items-center gap-3 p-3">
+                      <span className="text-xl font-bold">{item.char}</span>
+                      <div className="flex-1">
+                        <span className="font-mono text-sm">{item.pinyin}</span>
+                        <span className="ml-2 text-xs text-muted-foreground">{item.tip}</span>
+                      </div>
+                    </CardContent>
+                  </Card>
+                )
+              })}
+            </div>
+          </div>
+        )}
+
+        <div className="flex gap-3">
+          <Button onClick={() => startPractice()} className="flex-1" size="lg">
+            {t('result.retry')}
+          </Button>
+          <Button onClick={() => setView('home')} variant="outline" className="flex-1" size="lg">
+            {t('result.backHome')}
+          </Button>
+        </div>
+      </div>
+    )
+  }
+
+  return null
+}