# Kids Scroll - Full Documentation for AI Agents

This document provides a detailed catalog of the games, read-aloud stories, blog topics, and technical utilities available on Kids Scroll.

## Catalog of Educational Games
All games are standalone PWA-enabled experiences designed for toddlers (ages 2-6).

### 1. Fine Motor Skills & Coordination
1. **Avatar Scroll**: Infinite scrolling with magic!
2. **Drawing Canvas**: Creative drawing space for kids
3. **Scrub the Mud**: Find hidden friends!
4. **Emoji Jigsaw**: Put halves together!
5. **Garden Growing**: Plant seeds and water flowers!
6. **Finger Painting**: Free-hand drawing with colors!
7. **Bubble Wrap Pop**: Pop the bubbles!
8. **Connect the Dots**: Connect the numbered stars!
9. **Trace the Path**: Drag the emoji along a winding path!

### 2. Problem Solving & Logic
1. **Shadow Match**: Match emojis to their shadows
2. **Spot the Pair**: Spot pairs of emojis
3. **Shape Sorter**: Match the shapes!
4. **Build the Zoo**: Match animals to their groups!
5. **What is it?**: Guess who or what is it!
6. **Pattern Maker**: Complete the sequence!
7. **Size Sorter**: Sort by size!
8. **Selective Bubble Pop**: Pop the correct category of bubbles!
9. **Bake a Cake**: Mix ingredients and bake a cake!

### 3. Hand-Eye Coordination & Reflexes
1. **Rocket Burst**: Pop rockets with explosions!
2. **Make Fruit Salad**: Slash fruits to make a salad!
3. **Balloon Pop**: Pop colorful balloons!
4. **Whack-a-Mole**: Hit the moles as they pop up!
5. **Traffic Light**: Control the traffic!
6. **Odd One Out**: Find the different emoji!
7. **Catch the Treats**: Catch falling treats!
8. **Bouncing Buddy**: Tap the bouncing friend!

### 4. Cognitive Skills & Early Literacy
1. **Guess the Time**: Learn to tell time with clocks!
2. **Learn Letters**: Trace letters and learn words!
3. **Learn Numbers**: Trace numbers and count!
4. **Hidden Friend**: Peek-a-boo discovery!
5. **Build a Face**: Learn about emotions!
6. **Day and Night**: Change the sky!
7. **Animal Fight**: Make animals battle it out!
8. **Emotion Explorer**: Learn about feelings!
9. **Count with Me**: Tap to count colorful emojis!
10. **Who Makes This Sound?**: Match the sound to the animal!

### 5. Sorting & Categorization
1. **Sort the Groceries**: Sort groceries into correct baskets!
2. **Color Train**: Sort items by color!
3. **Feed the Animals**: What do they want to eat?
4. **Color Mixture**: Mix colors to discover new ones
5. **Where Do They Live?**: Match animals to their homes!
6. **Hot & Cold Sorter**: Sort hot and cold items!
7. **Land, Sea, or Air**: Where do they travel?

### 6. Music & Rhythm
1. **Musical Instruments**: Learn instrument names!
2. **Emoji Xylophone**: Play musical notes!
3. **Animal Beatbox**: Create a musical beat!

### 7. Sensory & Relaxation
1. **Breathing Bubble**: Relax and breathe!
2. **Magic Sand**: Swirl beautiful particles!
3. **Flashlight Explorer**: Use a flashlight to find hidden animals!
4. **Egg Hatching**: Tap the egg to reveal a surprise friend!

## Catalog of Read-Aloud Stories
Available at `/story/index.html`. A child picks an animal and hears a gentle, narrated story with a playground scene animation. 18 animals are supported: rabbit, elephant, lion, monkey, dog, cat, bear, duck, cow, tiger, giraffe, zebra, horse, panda, fox, pig, sheep, kangaroo.

- **Curated classic tales**: Original, hand-written Panchatantra/Aesop-style fables (not verbatim copies of public-domain text), gentle and safe for 1-6yo listeners, each ending in a friendship/sharing moral. Most animals have 1-2 tales.
- **On-device generation**: A small on-device language model (wllama/llama.cpp WASM binding, ~27MB GGUF) generates short new stories per animal, entirely offline with no server calls. Generated text is screened against a blocked-word safety filter before being shown.
- **Narration**: Web Speech API read-aloud with play/pause/resume, a per-animal story history, and a parent-facing "flag this story" feedback control.

## Blog Categories & Topics
The blog section focuses on parent education regarding safe screen time and offline activities.

- **Offline Play**: Guides for long drives, airplane trips, and internet-free entertainment.
- **Safety & Privacy**: Tips for identifying ad-free apps and managing screen time.
- **Educational Value**: How memory and matching games improve toddler focus and cognitive development.
- **Game Guides**: Specific advice on teaching colors, animals, and habitats through digital play.
- **Literacy & Reading**: Expert book recommendations for age 1, 2, and 3, plus guides to free digital libraries.
- **Read-Aloud Stories**: The role of animal fables and read-aloud storytelling in toddler development, as an alternative to passive screen time.

## Developer Utility API (js/common-utils.js)
Key functions available for integration:
- `triggerCelebration()`: Launches full-screen confetti.
- `playCelebrationSound()`: Pronounces random encouraging phrases via Speech Synthesis.
- `speakText(text)`: Wrapper for Web Speech API with kid-optimized pitch and rate.
- `saveToRecent(gameId)`: Manually updates the "Recently Played" list in localStorage.
- `handleGameNavigation()`: Manages the back-button trap and header navigation arrows.

## Technical Configuration
- **Host**: www.offlinekidsgames.com
- **PWA Manifest**: manifest.json (Icons, Theme: #6a11cb, Display: fullscreen, start_url: /launch/index.html)
- **Service Worker**: service-worker.js (Pre-caches all games, stories, and core assets for full offline use after first install)
- **Analytics**: Google Analytics (G-1VGQKH21ZW)
- **Security**: 100% Ad-Free, Offline-First, On-Device Story Generation, No User Data Collection.