# Kids Scroll

> A lightweight, ad-free Progressive Web App (PWA) featuring 50+ educational mini-games and read-aloud animal stories designed for toddlers and preschoolers (ages 2-6).

## Public Resources
- [Home Page](index.html): Main entry point with game/story categories and trending section.
- [Games Page](game/index.html): Full game library.
- [Stories Page](story/index.html): Read-aloud stories, routines, and animal fables.
- [Wonders & Facts](question/index.html): Spoken preschool curiosity encyclopedia answering "Why?" questions.
- [OpenAPI Specification](openapi.json): OpenAPI 3.1.0 schema for ChatGPT Custom Actions and AI agent tools.
- [Games JSON API](api/games.json): Structured catalog of 50 toddler games with age ranges and developmental skills.
- [Stories JSON API](api/stories.json): Structured catalog of 60 read-aloud routine, habit, and bedtime stories.
- [Questions JSON API](api/questions.json): Structured catalog of 76 preschool science wonder topics.
- [About Page](pages/about.html): Project mission and safety information.
- [Sitemap](sitemap.xml): Full list of games and blog posts.
- [Manifest](manifest.json): PWA configuration and theme settings.

## Application Structure
- `/game/`: 50+ standalone HTML mini-games (e.g., `whack-a-mole.html`, `balloon-pop.html`).
- `/story/`: Read-aloud animal story picker and reader (`index.html`, `read.html?animal=`).
- `/blog/`: SEO-optimized parenting guides and educational articles.
- `/js/`: Vanilla JavaScript logic including `common-utils.js` (speech, celebrations, navigation).
- `/js/story/`: Story engine - curated classic tales, on-device story generation (wllama), and read-aloud playback.
- `/assets/`: Unicode emoji definitions, app iconography, and the on-device story-generation model.

## Cognitive Categories
Games are organized into five primary developmental domains:
1. **Fine Motor Skills**: Interaction-heavy games like drawing and scrubbing.
2. **Problem Solving**: Pattern matching and logic puzzles.
3. **Hand-Eye Coordination**: Reflex-based games like popping and whacking.
4. **Cognitive Skills**: Early literacy, numeracy, and time-telling.
5. **Sorting & Categorization**: Grouping by color, shape, or habitat.

## Read-Aloud Stories
- 18 animals (rabbit, elephant, lion, monkey, dog, cat, bear, duck, cow, tiger, giraffe, zebra, horse, panda, fox, pig, sheep, kangaroo), each with curated original fables plus fresh on-device story generation for variety.
- Narrated via the Web Speech API with play/pause/resume and a story history per animal.
- A tiny on-device language model (wllama/llama.cpp WASM, ~27MB GGUF) generates short new stories fully offline, with no cloud calls and no data leaving the device.

## Technical Specs for Agents
- **Stack**: HTML5, CSS3, Vanilla ES6+ JavaScript.
- **Offline Mode**: Enabled via `service-worker.js`, precaching games, stories, and core assets so the app works fully offline after first install.
- **Accessibility**: Optimized for non-readers via Web Speech API and high-contrast visuals.
- **Privacy**: No ads, no user tracking beyond Google Analytics, on-device story generation, 100% kid-safe.

## Contact
- [Contact Support](pages/contact.html)
- [Privacy Policy](pages/privacy-policy.html)