A lightweight, delightful, voice-interactive web application designed to help children learn to read. Kids are presented with a flashcard and have 10 seconds to read the word out loud. When they read it correctly, the word explodes in a shower of particles and confetti, plays a celebratory fanfare, and is collected into their personal Word Chest!
- ⏱️ 10-Second Visual Timer: Dynamic countdown bar with smooth color transitions (Emerald ➔ Sunflower Amber ➔ Coral Red) and gentle audio ticks in the final 3 seconds. Adjustable speeds (5s, 10s, 15s, or Free Play) in Settings.
- 🎙️ Real-Time Voice Recognition: Built on the native Web Speech API (
SpeechRecognition/webkitSpeechRecognition). Features fuzzy matching and phonetic homophone tolerance (e.g., SUN/SON, SEE/SEA) and handles words spoken inside sentences ("It is a cat!"). - 💥 Physics Particle Explosion: Letters physically shatter and blast outward in 3D rotation, accompanied by 120+ glowing stars, confetti particles, shockwave rings, and dual confetti cannons.
- 🎵 Zero-Dependency Web Audio Synthesizer: Custom oscillator-based chords, celebratory fanfare arpeggios, and bubbly button pops synthesized in pure code—100% reliable offline without loading MP3 files.
- 👤 Multi-Reader Profiles: Supports multiple children (siblings, classrooms). Each child picks an avatar (🦁, 🚀, 🦄, 🦖, etc.) and keeps their own persistent Word Chest saved in
localStorage. - 🏆 Earned vs. Practice Logic:
- Earned into Chest: Read out loud with the child's own voice with no hints.
- Practice Mode (No Sticker): Tapping "Hear Word" (audio hint) or "I Said It! 👍" (parent override) allows kids to practice and triggers the explosion, but does not award the sticker into the chest.
- 📚 Graded Word Decks & Custom Words:
- 🏆 Top 300 Most Common Words: The complete Fry master list accounting for over 65% of all English reading material!
- 🥇 Top 100 Common Words (Tier 1): The core foundational words (THE, OF, AND, A, TO, IN, IS, YOU, THAT, IT...).
- 🥈 Second 100 Common Words (Tier 2): Expanding vocabulary and fluency (OVER, NEW, SOUND, TAKE, WORK, PLACE, YEAR...).
- 🥉 Third 100 Common Words (Tier 3): Advanced high-frequency words (EVERY, NEAR, FOOD, SCHOOL, FATHER, EARTH, LIGHT...).
- 🐱 Starter Phonics (CVC): 3-letter sounding words (CAT, DOG, SUN, PIG, BUG, HAT, FOX, CUP...).
- ⭐ Magic Sight Words: THE, SEE, YOU, CAN, LOOK, PLAY, LIKE, BIG, RED, BLUE...
- 🚀 Animals & Wonders: STAR, MOON, FROG, FISH, DUCK, TREE, LION, BEAR...
- 🔀 Deck Shuffle: One-tap shuffle button to randomize words for dynamic practice.
- ✍️ Custom Words: Parents and teachers can easily type and add custom vocabulary lists.
- 🔒 HTTPS Ready for Mobile & Tablet: Automatically bundled with
@vitejs/plugin-basic-sslso you can test on iPad or Android phones over local Wi-Fi with microphone permissions enabled.
- Node.js (v18 or higher recommended)
- npm (or pnpm / yarn)
# Clone repository
git clone https://github.com/samucospace/reading-app.git
cd reading-app
# Install dependencies
npm install
# Start development server with HTTPS & Network access
npm run dev -- --hostOnce running:
- Local PC:
https://localhost:5173/ - Phone / Tablet:
https://<YOUR-LOCAL-IP>:5173/
npm run build
npm run previewMobile browsers (iOS Safari, Android Chrome) strictly require a secure origin (https:// or localhost) before granting microphone access to web apps.
- Connect your device to the same Wi-Fi network as your computer.
- Open Safari and navigate to
https://<YOUR-COMPUTER-IP>:5173/. - Safari will show "This Connection Is Not Private" (due to the local development SSL certificate).
- Tap Show Details (or Advanced) ➔ Tap "visit this website".
- When prompted: "Would you like to use your microphone?", tap Allow!
- Direct HTTPS: Open
https://<YOUR-COMPUTER-IP>:5173/➔ tap Advanced ➔ Proceed to unsafe ➔ grant microphone access. - Developer Flag Bypass: If accessing via plain HTTP (
http://<YOUR-IP>:5173/):- In Chrome on Android, open
chrome://flags. - Search for
Insecure origins treated as secure. - Set to Enabled, enter
http://<YOUR-IP>:5173, and tap Relaunch.
- In Chrome on Android, open
| Layer | Technology |
|---|---|
| Framework | React 19 + TypeScript |
| Bundler | Vite 8 with @vitejs/plugin-basic-ssl |
| Styling | Tailwind CSS v4 + @tailwindcss/vite |
| Icons & Typography | Lucide React + Google Fonts (Fredoka, Quicksand) |
| Speech Engine | Native browser Web Speech API |
| Audio Synthesis | Native Web Audio API (Oscillators, Gain nodes) |
| Explosion Physics | HTML5 Canvas 2D + canvas-confetti |
| Storage | Browser localStorage (Profiles, Word Chests, Custom Words) |
reading-app/
├── public/
├── src/
│ ├── components/
│ │ ├── InventoryModal.tsx # Child's Word Chest & sticker collection
│ │ ├── ProfileSetupScreen.tsx # Reader profile creation & avatar picker
│ │ ├── SettingsModal.tsx # Timer speed, deck selector & custom word inputs
│ │ ├── TimerBar.tsx # Animated 10s progress bar with audio tick cues
│ │ ├── WordCard.tsx # Central flashcard, voice mic bubble, hint buttons
│ │ └── WordExplosion.tsx # HTML5 Canvas 2D letter shattering & particle burst
│ ├── data/
│ │ └── wordLists.ts # Curated phonics decks (CVC, Sight Words, Animals)
│ ├── hooks/
│ │ └── useSpeechRecognition.ts # Web Speech API manager & homophone matching
│ ├── types/
│ │ └── profile.ts # Profile and Word collection data contracts
│ ├── utils/
│ │ └── audio.ts # Web Audio API synthesizers & text-to-speech
│ ├── App.tsx # Main game coordinator & state store
│ ├── index.css # Tailwind v4 styles & bouncy animations
│ └── main.tsx # React application entry point
├── package.json
├── tsconfig.json
└── vite.config.ts
Contributions, additional phonics decks, sound effects, or translations are very welcome!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.