HanFlash v3.3.0 Release Notes

🚀 HanFlash v3.3.0 — The Deep Learning Update

This release focuses on retention science: multi-modal encoding, focused study sessions, and daily progress visibility. Every feature in v3.3.0 is grounded in second-language acquisition research and designed to make Hanzi stick — not just look familiar.

✨ New Features

🧩 Radical Decomposition Panel

Characters are no longer opaque symbols. Every flashcard and vocabulary card now shows a character component breakdown with mnemonic anchors.

• 明 = 日 (sun) + 月 (moon) → *"bright because sun and moon both shine"*
• Covers ~150 key HSK 1–4 characters with components, pinyin, and English meanings
• Compact mode on vocabulary cards — small chips that don't interrupt the reading flow
• Full mode on the flashcard back face — detailed breakdown with the mnemonic anchor
• Lazy-loaded from radical-map.json with a shared module cache — zero repeated network requests

🍅 Focused Session Mode (Pomodoro)

A dedicated /focus route that eliminates decision fatigue and keeps you in a flow state.

• Launcher — configure before every session: card count (10 / 20 / 30 / 50), HSK level (All / HSK 1–4), card pool (Due today / Favorites / Hard words / Random), and timer (None / 15 / 25 / 45 min)
• Session — distraction-free flashcard mode with a live SVG ring countdown timer, progress bar, visibility toggles, and full SRS grading (Again / Hard / Good / Easy)
• Summary — completion screen with per-grade bar chart, updated streak badge, and daily goal indicator
• Session config is persisted to localStorage so your last setup is always pre-filled
• Keyboard shortcuts active in session: Space to flip, 1–4 to grade, F to favorite, S to shuffle, ? for the overlay

✍️ Sentence Drills (/drills)

Active recall through contextual sentence practice — proven to be more effective than passive card reading.

• Fill-in-the-blank format: real HSK example sentences with the target word replaced by a blank
• Type the missing character(s) and get instant correct/incorrect feedback
• Correct: green confirmation with auto-advance after 0.9 seconds
• Incorrect: red feedback, correct answer revealed, Try again / Skip options
• "Show answer" button for when you want to reveal without a penalty
• Level filter (All HSK / HSK 1–4) with progress bar and session summary at the end
• Only uses vocabulary items that have matching example sentences — no broken drills

📊 Daily Review Dashboard

Your study progress is now visible the moment you open the app — on the home page, zero interaction needed.

• Daily goal ring — SVG arc showing cards reviewed vs. your daily goal
• Streak tracker — 🔥 flame with milestone badges at 7 days, 30 days, and 100 days
• Mastery meter — percentage of known + mastered words with a progress bar
• SRS forecast — cards due today and tomorrow, so you can plan your session
• Reads entirely from localStorage — instant render, no server roundtrip, works offline

🎨 UX & Comfort Improvements

🌙 Dark Mode

• Full dark theme via CSS custom properties ([data-theme="dark"] on the <html> element)
• Toggle button (sun ☀️ / moon 🌙) in the header — always one click away
• Respects prefers-color-scheme on first visit
• FOUC-free — an inline <script> in <head> applies your saved theme before React hydrates, so there is never a white flash on dark-mode loads
• Persists across sessions via localStorage

🔡 Hanzi Font Size Control

• A− and A+ buttons in the header to adjust the Hanzi character display size
• Scales from 0.8× to 1.6× in smooth steps using a --hanzi-scale CSS custom property
• Works across flashcards, vocabulary cards, and all character displays
• Preference persists across sessions

⌨️ Keyboard Shortcuts

Full keyboard navigation for flashcard and focus sessions:

• Space / Enter — flip card
• → / ← — next / previous card
• 1 — Again · 2 — Hard · 3 — Good · 4 — Easy (SRS grades)
• F — toggle favorite
• S — shuffle deck
• ? — open keyboard shortcuts overlay

The overlay lists all shortcuts in context (flashcard vs. global) and can be dismissed with Esc.

🔗 Navigation & Discoverability

• Drills added to the desktop header navigation
• Drills added to the mobile bottom navigation (replaces the HSK tab slot)
• Drills and Focus Mode added to the footer Study tools column and the quick-access grid
• /drills route has full SEO metadata (<title>, meta description, keywords)

🔧 Dependency Updates

All runtime and development dependencies updated to their latest stable versions:

• `next` 16.3.4 → 16.3.5
• `react` / `react-dom` 19.2.3 → 19.3.0
• `@libsql/client` 0.17.0 → 0.18.0
• `@vercel/analytics` 1.6.1 → 2.0.1
• `@types/react` / `react-dom` 19.2.x → 19.3.0
• `@types/node` 25.x → 26.6.0
• `eslint-config-next` 16.1.1 → 16.3.5
• `postcss` 8.5.23 → 8.5.28
• `autoprefixer` 10.4.x → 10.6.1
• 0 vulnerabilities after npm audit fix

> Note: tailwindcss remains at 3.x (v4 requires a full config migration), eslint at 9.x, and typescript at ~5.9 (both blocked by typescript-eslint's peer constraint <6.0.0). These will be addressed in a dedicated migration update.

🐛 Bug Fixes

• Fixed stale closure in focus session handleRate — grade counts passed to analytics now reflect the actual final state of the session
• Fixed useCallback dependency array in focus page — favoritesSet (the Set<string>) is now correctly listed instead of favoriteIds (the string[]), preventing unnecessary re-renders
• Removed stale eslint-disable-next-line directive in layout.tsx that no longer had an effect

📦 What's Included

• ✅ Radical decomposition panel (VocabularyCard + Flashcard back face)
• ✅ Focused Session Mode with Pomodoro timer at /focus
• ✅ Sentence Drills with fill-in-the-blank at /drills
• ✅ Daily Review Dashboard on the home page
• ✅ Dark mode with FOUC prevention
• ✅ Hanzi font size A− / A+ control
• ✅ Full keyboard shortcut system with overlay
• ✅ Drills in desktop nav, mobile bottom nav, and footer
• ✅ All runtime and dev dependencies updated
• ✅ 0 TypeScript errors · 0 lint errors · 0 vulnerabilities · 66/66 pages compiled

🔮 Coming Next

• HSK 5–6 vocabulary expansion
• Stroke order animation (Hanzi Writer integration)
• Tone trainer with pitch contour visualization
• Mnemonic story builder (user-generated character stories)
• Tailwind CSS v4 migration

📞 Feedback & Support

• Issues: Report bugs on GitHub Issues
• Feature Requests: Propose ideas via GitHub Discussions
• Contributions: Pull requests are welcome

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Happy Learning! 🎓

*HanFlash — Learn Chinese vocabulary with focus and efficiency.*

HanFlash v3.2.0 Release Notes

🎉 Welcome to HanFlash v3.2.0!

This release introduces the highly requested Master of Words reset feature, significant improvements to HSK 4 data quality, and a robust data migration system for versioned HSK datasets.

✨ Features

Master of Words

• 👤 Progress Reset - Added a new functionality in the profile page to reset your vocabulary mastery ("Master of Words") record with a secure confirmation step.

Learning Data & SRS

• 🔄 HSK Data Migration - Implemented a system to migrate user favorites and SRS progress across refreshed HSK datasets, ensuring your progress is never lost during updates.
• 🎯 Accurate Review Counts - Refined SRS logic to exclude mastered items from the due flashcard count, providing a more focused and realistic review experience.

Vocabulary & Quality

• 📂 HSK4 Dataset Overhaul - Enhanced HSK 4 vocabulary with corrected serial numbers, improved validation scripts, and better quality reporting.
• 🛠️ HSK 3 & 4 Updates - General fixes and updates to HSK 3 and HSK 4 vocabulary entries to improve accuracy.

📦 What’s Included

• ✅ Reset functionality for "Master of Words" progress
• ✅ Versioned HSK dataset support with progress migration
• ✅ Excluded mastered items from SRS due counts
• ✅ Refreshed HSK 4 vocabulary and improved data validation
• ✅ Updated HSK 3 and 4 vocabulary entries

📞 Feedback & Support

We’d love your feedback.

• Issues: Report bugs on GitHub Issues
• Feature Requests: Propose ideas via GitHub Discussions
• Contributions: Pull requests are welcome

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Happy Learning! 🎓

*HanFlash - Learn Chinese vocabulary with focus and efficiency.*

HanFlash v3.1.1 Release Notes

🎉 Welcome to HanFlash v3.1.1!

This release refines search and deck filtering for a smoother study flow, plus fixes how hard-word state is handled in SRS.

✨ Updates

Search & Layout

• 📱 Mobile search layout parity - Match the mobile search layout to favorites to prevent overlap

Deck Filters

• 🧩 Hard words filter - Add a hard-words deck filter and persist the hard flag in SRS state
• ✅ Single-select filters - Make deck filters single-select with an All words default
• 🎨 Filter style alignment - Match hard-words active styling to black/white
• 🔁 Mutual exclusivity - Normalize stored filter state and keep deck filters mutually exclusive

SRS Fixes

• 🛠️ Hard flag handling - Clear hard flag on good/easy and respect the latest hard status during merges

📦 What’s Included

• ✅ Mobile search layout alignment with favorites
• ✅ Hard-words filter and persisted hard state
• ✅ Single-select, mutually exclusive deck filters with normalized storage
• ✅ SRS merge logic improvements for hard status

📞 Feedback & Support

We’d love your feedback.

• Issues: Report bugs on GitHub Issues
• Feature Requests: Propose ideas via GitHub Discussions
• Contributions: Pull requests are welcome

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Happy Learning! 🎓

*HanFlash - Learn Chinese vocabulary with focus and efficiency.*

HanFlash v3.1.0 Release Notes

🎉 Welcome to HanFlash v3.1.0!

This release sharpens the core search experience, introduces a new Focus page for level-specific study, and documents the new product direction in a PRD.

✨ Major Features

Search Experience

• 🔍 Search deck front-and-center - The homepage search now appears at the top level for faster access

Focus Mode

• 🎯 Focus page - A dedicated Focus page for level-specific study sessions
• 🧭 Navigation update - Added Focus entry to the primary navigation

Product Direction

• 📄 New PRD - Added docs/New_PRD.md to document the updated product direction

📦 What’s Included

• ✅ New Focus page and nav entry
• ✅ Homepage search elevated to a top-level section
• ✅ Updated PRD documentation

🐛 Known Limitations & Future Work

• Focus flow will continue to expand with deeper analytics
• Additional search refinements and filters planned

📞 Feedback & Support

We’d love your feedback.

• Issues: Report bugs on GitHub Issues
• Feature Requests: Propose ideas via GitHub Discussions
• Contributions: Pull requests are welcome

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Happy Learning! 🎓

*HanFlash - Learn Chinese vocabulary with focus and efficiency.*

HanFlash v3.0.0 Release Notes

🎉 Welcome to HanFlash v3.0.0!

This release delivers the full authenticated study experience, deeper mastery insights, and new compliance + download pages. It also tightens security and polishes the mobile-first UI.

✨ Major Features

Authentication & Personalization

• 🔐 Full auth system - Login, registration, password reset, and secure session handling
• 🧭 Auth-gated study actions - Study workflows are protected and replay after sign-in
• 🧑‍🎓 Profile management - Manage your profile and track study preferences
• 🏷️ User badge updates - Username/avatar display with fast refresh after auth changes

Study Insights & Mastery

• 📊 Mastery tracking - Progress tracking across study ratings
• 🧩 Insights dashboard - Study insights panel with totals and breakdowns
• 🥧 Mastery pie chart - Visual mastery distribution with legend and totals
• 🎯 Daily focus panel - Goal controls and daily focus tracking for mobile
• 🔎 Deck filters - Filter mastery decks and persist your preference

UI & Experience

• 📱 Mobile-first auth flow - Designed for small screens with bottom nav UX
• 🧭 Mobile header login button - Clear entry point for unauthenticated users
• 🧱 Desktop layout upgrades - Right-rail snapshot, two-pane layouts, sticky controls
• ✨ Loading skeletons - Smoother perceived performance during data fetches

Pages & Content

• 📥 APK download page - Dedicated download page with footer link
• 👥 Contributors page - New contributors page and footer integration
• 📄 Privacy & Terms - Compliance pages with sitemap updates

🔧 Security & Stability

• 🛡️ Security hardening - WAF middleware and tightened request handling
• 🧪 Session fixes - Improved cookie handling to avoid race conditions
• ♻️ Study persistence - Flashcard review history and favorites sync on login

📦 What’s Included

• ✅ Authenticated study workflows
• ✅ Mastery tracking + insights
• ✅ Mobile-first profile and footer experience
• ✅ APK download page
• ✅ Contributors, Privacy Policy, and Terms pages
• ✅ Enhanced loading and UI responsiveness

🐛 Known Limitations & Future Work

• HSK levels 1–4 only (levels 5–6 coming later)
• Offline mode continues to evolve
• Audio pronunciation and advanced SRS tuning planned

📞 Feedback & Support

We’d love your feedback.

• Issues: Report bugs on GitHub Issues
• Feature Requests: Propose ideas via GitHub Discussions
• Contributions: Pull requests are welcome

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Happy Learning! 🎓

*HanFlash - Learn Chinese vocabulary with focus and efficiency.*

HanFlash v2.1.0 Release Notes

🎉 Welcome to HanFlash v2.1.0!

This release focuses on vocabulary data corrections and improvements, ensuring accuracy across all HSK levels 1-4.

✨ Major Features

Core Learning Experience

• 🔍 Instant Vocabulary Search - Search by Hanzi, Pinyin, or English meaning across HSK levels 1-4
• 📚 HSK Level Filtering - Browse vocabulary organized by difficulty level
• 🧠 Flashcard Mode - Hanzi-first recall with flip-to-reveal for pinyin, meanings, and usage examples
• 👁️ Hide/Reveal Controls - Toggle visibility of pinyin, meanings, and translations
• ⭐ Favorites System - Save and manage your favorite vocabulary items for quick review
• 📖 Study Mode - Dedicated interface for focused vocabulary practice

Reading Experience

• 📍 Reading Practice Hub - Continue where you left off with a dedicated dashboard
• 🧭 Focus Mode - Line-by-line reading with progress tracking and keyboard navigation
• 🎚️ Reading Preferences - Adjustable text size, line spacing, and visibility toggles
• 🏷️ Story Status & Filters - Save stories, mark completion, and filter by status or length
• 🧩 Vocabulary Bank - Key terms surfaced at the end of each story for quick review

User Experience

• 📱 Fully Responsive Design - Optimized for desktop, tablet, and mobile browsers
• ⌨️ Keyboard Navigation - Use arrow keys (←/→) to navigate through flashcards
• 🎯 Mobile-First UI - Bottom navigation bar and intuitive card-based design
• 🔄 Session Preferences - User settings persisted using localStorage
• ⚡ Fast Performance - Built with Next.js for optimal speed and user experience

PWA & Accessibility

• 🌐 Progressive Web App - Installable on mobile and desktop devices
• 📍 Service Worker - Offline-ready foundations for future offline support
• ♿ Accessibility Improvements - Focus management and keyboard controls throughout the app
• 📊 SEO Optimized - Comprehensive metadata, sitemap, robots.txt, and social share images (OpenGraph & Twitter)
• 🎨 Loading States - Skeleton screens for better perceived performance

🔧 Technical Highlights

Recent Updates

• ✅ Vocabulary Data Corrections - Fixed and validated vocabulary data for HSK levels 1-4
• ✅ Data Validation Script - Added comprehensive validation tool for vocabulary accuracy
• ✅ Hanzi Characters Verified - Ensured all characters are correct across all levels
• ✅ Pinyin Standardization - Standardized pinyin romanization throughout the database
• ✅ Meaning Improvements - Enhanced and clarified English translations
• ✅ Example Validation - Verified example sentences for clarity and relevance

Architecture

• Monolithic Design - Frontend UI, application logic, and data access in a single Next.js application
• TypeScript - Full type safety across the codebase
• Tailwind CSS - Utility-first styling for responsive design
• JSON-Based Data - Lightweight vocabulary database for HSK 1-4

📦 What's Included

• ✅ Comprehensive vocabulary database for HSK levels 1-4 (corrected)
• ✅ Responsive UI built with React and Tailwind CSS
• ✅ Flashcard interface with multiple learning modes
• ✅ Favorites and session history tracking
• ✅ Spaced Repetition System (SRS) foundations
• ✅ PWA manifest and service worker setup
• ✅ Global SEO metadata and social sharing support

🐛 Known Limitations & Future Work

Current Scope

• Supports HSK levels 1-4 only (levels 5-6 coming in future releases)
• Vocabulary dataset includes commonly taught words for each HSK level
• Data validation script available via npm run validate:data

Roadmap

• [ ] HSK levels 5-6 support
• [ ] User accounts and cloud sync
• [ ] Spaced Repetition System (SRS) refinements
• [ ] Audio pronunciation for all vocabulary
• [ ] Dark mode theme
• [ ] Offline mode with full vocabulary access
• [ ] Community contributions for vocabulary examples

📝 Release Highlights

Features

• Corrected and validated vocabulary data across all HSK levels
• Improved data accuracy for Hanzi, Pinyin, meanings, and examples
• Enhanced consistency in romanization and English translations

Fixes & Improvements

• Fixed vocabulary character accuracy issues
• Standardized pinyin romanization format
• Improved English meaning clarity and relevance
• Validated example sentences for context and usage

📞 Feedback & Support

We'd love to hear your feedback!

• Issues: Found a bug? Report it on GitHub Issues
• Feature Requests: Have an idea? Submit it as a GitHub Discussion
• Contributions: Want to help? Pull requests are welcome!

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Happy Learning! 🎓

*HanFlash - Learn Chinese vocabulary with focus and efficiency.*

HanFlash v2.0.0 Release Notes

🎉 Welcome to HanFlash v2.0.0!

This is the first stable release of HanFlash, a lightweight Chinese vocabulary learning web app for HSK levels 1-4.

✨ Major Features

Core Learning Experience

• 🔍 Instant Vocabulary Search - Search by Hanzi, Pinyin, or English meaning across HSK levels 1-4
• 📚 HSK Level Filtering - Browse vocabulary organized by difficulty level
• 🧠 Flashcard Mode - Hanzi-first recall with flip-to-reveal for pinyin, meanings, and usage examples
• 👁️ Hide/Reveal Controls - Toggle visibility of pinyin, meanings, and translations
• ⭐ Favorites System - Save and manage your favorite vocabulary items for quick review
• 📖 Study Mode - Dedicated interface for focused vocabulary practice

Reading Experience (New)

• 📍 Reading Practice Hub - Continue where you left off with a dedicated dashboard
• 🧭 Focus Mode - Line-by-line reading with progress tracking and keyboard navigation
• 🎚️ Reading Preferences - Adjustable text size, line spacing, and visibility toggles
• 🏷️ Story Status & Filters - Save stories, mark completion, and filter by status or length
• 🧩 Vocabulary Bank - Key terms surfaced at the end of each story for quick review

User Experience

• 📱 Fully Responsive Design - Optimized for desktop, tablet, and mobile browsers
• ⌨️ Keyboard Navigation - Use arrow keys (←/→) to navigate through flashcards
• 🎯 Mobile-First UI - Bottom navigation bar and intuitive card-based design
• 🔄 Session Preferences - User settings persisted using localStorage
• ⚡ Fast Performance - Built with Next.js for optimal speed and user experience

PWA & Accessibility

• 🌐 Progressive Web App - Installable on mobile and desktop devices
• 📍 Service Worker - Offline-ready foundations for future offline support
• ♿ Accessibility Improvements - Focus management and keyboard controls throughout the app
• 📊 SEO Optimized - Comprehensive metadata, sitemap, robots.txt, and social share images (OpenGraph & Twitter)
• 🎨 Loading States - Skeleton screens for better perceived performance

🔧 Technical Highlights

Recent Updates

• ✅ Resolved TypeScript compilation errors for production builds
• ✅ Fixed Turbopack build errors with route config and sitemap typing
• ✅ Added loading skeletons and sanitized search input
• ✅ Improved flashcard key handling and accessibility toggles
• ✅ Enhanced touch event handling for mobile devices
• ✅ Fixed favorites event dispatch to prevent render-phase updates
• ✅ Added comprehensive metadata and SEO improvements
• ✅ Implemented HSK level selector on home page

Architecture

• Monolithic Design - Frontend UI, application logic, and data access in a single Next.js application
• TypeScript - Full type safety across the codebase
• Tailwind CSS - Utility-first styling for responsive design
• JSON-Based Data - Lightweight vocabulary database for HSK 1-4

📦 What's Included

• ✅ Comprehensive vocabulary database for HSK levels 1-4
• ✅ Responsive UI built with React and Tailwind CSS
• ✅ Flashcard interface with multiple learning modes
• ✅ Favorites and session history tracking
• ✅ Spaced Repetition System (SRS) foundations
• ✅ PWA manifest and service worker setup
• ✅ Global SEO metadata and social sharing support

🚀 Getting Started

Installation & Development

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm build

# Validate vocabulary data
npm run validate:data

Features to Explore

1. Search - Try searching for vocabulary by Hanzi, Pinyin, or English
2. Flashcards - Visit the flashcard page and use keyboard arrows to navigate
3. Favorites - Star your favorite words to build a custom study list
4. HSK Levels - Filter by specific HSK levels to focus your learning

🐛 Known Limitations & Future Work

Current Scope

• Supports HSK levels 1-4 only (levels 5-6 coming in future releases)
• Vocabulary dataset includes commonly taught words for each HSK level
• Data validation script available via npm run validate:data

Roadmap

• [ ] HSK levels 5-6 support
• [ ] User accounts and cloud sync
• [ ] Spaced Repetition System (SRS) refinements
• [ ] Audio pronunciation for all vocabulary
• [ ] Dark mode theme
• [ ] Offline mode with full vocabulary access
• [ ] Community contributions for vocabulary examples

📝 Release Highlights

Features

• Stable release branding and versioned UI
• Updated global metadata, sitemap, robots, and social share images
• Focus-level selector for HSK 1-4 on the home page
• Mobile-first redesign with bottom nav and refreshed cards
• Study mode, favorites, and PWA foundations
• Release notes page with in-app reading experience
• Smooth flashcard transitions for flip, next, and prev

Fixes & Improvements

• Resolved build errors and TypeScript compilation issues
• Improved flashcard key handling, accessibility, and touch input
• Sanitized malformed meanings for safer rendering

📞 Feedback & Support

We'd love to hear your feedback!

• Issues: Found a bug? Report it on GitHub Issues
• Feature Requests: Have an idea? Submit it as a GitHub Discussion
• Contributions: Want to help? Pull requests are welcome!

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Happy Learning! 🎓

*HanFlash - Learn Chinese vocabulary with focus and efficiency.*

HanFlash v1.0.0-beta Release Notes

🎉 Welcome to HanFlash v1.0.0-beta!

This is the first public beta release of HanFlash, a lightweight Chinese vocabulary learning web app for HSK levels 1-4.

✨ Major Features

Core Learning Experience

• 🔍 Instant Vocabulary Search - Search by Hanzi, Pinyin, or English meaning across HSK levels 1-4
• 📚 HSK Level Filtering - Browse vocabulary organized by difficulty level
• 🧠 Flashcard Mode - Hanzi-first recall with flip-to-reveal for pinyin, meanings, and usage examples
• 👁️ Hide/Reveal Controls - Toggle visibility of pinyin, meanings, and translations
• ⭐ Favorites System - Save and manage your favorite vocabulary items for quick review
• 📖 Study Mode - Dedicated interface for focused vocabulary practice

User Experience

• 📱 Fully Responsive Design - Optimized for desktop, tablet, and mobile browsers
• ⌨️ Keyboard Navigation - Use arrow keys (←/→) to navigate through flashcards
• 🎯 Mobile-First UI - Bottom navigation bar and intuitive card-based design
• 🔄 Session Preferences - User settings persisted using localStorage
• ⚡ Fast Performance - Built with Next.js for optimal speed and user experience

PWA & Accessibility

• 🌐 Progressive Web App - Installable on mobile and desktop devices
• 📍 Service Worker - Offline-ready foundations for future offline support
• ♿ Accessibility Improvements - Focus management and keyboard controls throughout the app
• 📊 SEO Optimized - Comprehensive metadata, sitemap, robots.txt, and social share images (OpenGraph & Twitter)
• 🎨 Loading States - Skeleton screens for better perceived performance

🔧 Technical Highlights

Recent Updates

• ✅ Resolved TypeScript compilation errors for production builds
• ✅ Fixed Turbopack build errors with route config and sitemap typing
• ✅ Added loading skeletons and sanitized search input
• ✅ Improved flashcard key handling and accessibility toggles
• ✅ Enhanced touch event handling for mobile devices
• ✅ Fixed favorites event dispatch to prevent render-phase updates
• ✅ Added comprehensive metadata and SEO improvements
• ✅ Implemented HSK level selector on home page

Architecture

• Monolithic Design - Frontend UI, application logic, and data access in a single Next.js application
• TypeScript - Full type safety across the codebase
• Tailwind CSS - Utility-first styling for responsive design
• JSON-Based Data - Lightweight vocabulary database for HSK 1-4

📦 What's Included

• ✅ Comprehensive vocabulary database for HSK levels 1-4
• ✅ Responsive UI built with React and Tailwind CSS
• ✅ Flashcard interface with multiple learning modes
• ✅ Favorites and session history tracking
• ✅ Spaced Repetition System (SRS) foundations
• ✅ PWA manifest and service worker setup
• ✅ Global SEO metadata and social sharing support

🚀 Getting Started

Installation & Development

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm build

# Validate vocabulary data
npm run validate:data

Features to Explore

1. Search - Try searching for vocabulary by Hanzi, Pinyin, or English
2. Flashcards - Visit the flashcard page and use keyboard arrows to navigate
3. Favorites - Star your favorite words to build a custom study list
4. HSK Levels - Filter by specific HSK levels to focus your learning

🐛 Known Limitations & Future Work

Current Scope

• Supports HSK levels 1-4 only (levels 5-6 coming in future releases)
• Vocabulary dataset includes commonly taught words for each HSK level
• Data validation script available via npm run validate:data

Roadmap

• [ ] HSK levels 5-6 support
• [ ] User accounts and cloud sync
• [ ] Spaced Repetition System (SRS) refinements
• [ ] Audio pronunciation for all vocabulary
• [ ] Dark mode theme
• [ ] Offline mode with full vocabulary access
• [ ] Community contributions for vocabulary examples

📝 Commit Summary

Features

• a0e852a - Beta badge and release version bump
• 4f66798 - Updated global metadata
• bba58fd - Added metadata, sitemap, robots, and social share images
• e5bec02 - Added loading skeletons and sanitize search input
• 2354c79 - Added focus-level selector for HSK 1–4 on home
• abdd0dd - Mobile-first redesign with bottom nav and refreshed cards
• f908c42 - Redesigned footer with brand, explore links, and social profiles
• 54db441 - Added study mode, favorites, and PWA foundations

Fixes & Improvements

• 4b89160 - Resolved Turbopack build errors
• 36e6e98 - Fixed TypeScript compilation errors
• 9c38989 - Fixed favorites event dispatch
• 39906e7 - Improved flashcard key handling and a11y
• 4d57a54 - Sanitized malformed meanings
• 6b0571f - Fixed route params in HSK level page
• 57f8935 - Switched PostCSS config for Tailwind compatibility

📞 Feedback & Support

This is a beta release, and we'd love to hear your feedback!

• Issues: Found a bug? Report it on GitHub Issues
• Feature Requests: Have an idea? Submit it as a GitHub Discussion
• Contributions: Want to help? Pull requests are welcome!

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Happy Learning! 🎓

*HanFlash - Learn Chinese vocabulary with focus and efficiency.*