Zauberwald/.planning/ROADMAP.md

# Roadmap: Zauberwald

## Overview

Vier Phasen bauen die App von der spielbaren Kern-Tippmechanik (ohne API) über die Gemini-Integration und das vollständige Spielerlebnis bis hin zum Polish mit Audio. Nach Phase 4 ist die App bereit zum Testen mit dem Kind.

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [ ] **Phase 1: Grundgerüst + Tippmechanik** - Spielbare Tipp-Übung im Browser, komplett ohne API
- [ ] **Phase 2: Gemini-Integration + Asset-Pipeline** - Gemini-API für Text/Bild, generierte Character Assets eingebunden
- [ ] **Phase 3: Komplettes Spielerlebnis** - Alle 3 Übungsphasen verbunden, Wald wächst, Stufen 1–6 spielbar
- [ ] **Phase 4: Polish + Audio** - Animationen, Sounds, Export/Import — bereit fürs Kind

## Phase Details

### Phase 1: Grundgerüst + Tippmechanik
**Goal**: Eine spielbare Tipp-Übung im Browser, die ohne API funktioniert
**Depends on**: Nothing (first phase)
**Requirements**: FNDN-01, FNDN-02, FNDN-03, FNDN-04, FNDN-05, ONBD-01, ONBD-02, ONBD-03, ONBD-04, KYBD-01, KYBD-02, KYBD-03, KYBD-04, KYBD-05, TYPE-01, TYPE-02, TYPE-03, TYPE-04, LEVL-01, LEVL-02, LEVL-03, FRST-04, FRST-05, PLSH-06
**Success Criteria** (what must be TRUE):
  1. Die App startet via `npm run dev` und ist von aussen unter `http://<vps-ip>:5173` erreichbar
  2. Begleitfigur und Tastatur-Layout sind wählbar und die Auswahl bleibt nach Browser-Reload erhalten
  3. Stufe 1 (F, J, Leertaste) ist spielbar: Buchstaben erscheinen einzeln, richtiger Tastendruck loest sie auf, falscher Tastendruck tut nichts
  4. Nach 10 richtigen Buchstaben gilt die Uebung als abgeschlossen und Stufe 2 wird freigeschaltet
  5. Die Wald-Uebersicht zeigt den Stufenstatus (locked / current / completed) korrekt an
**Plans:** 5 plans

Plans:
- [x] 01-01-PLAN.md — Vite scaffold, project structure, CSS palette, TypeScript interfaces, IndexedDB wrapper
- [x] 01-02-PLAN.md — Screen management, welcome screen, companion/layout selection, onboarding persistence
- [x] 01-03-PLAN.md — QWERTZ keyboard component with finger colors, level definitions 1-6
- [x] 01-04-PLAN.md — Typing exercise engine (TDD), adaptive tempo, lesson screen UI
- [x] 01-05-PLAN.md — Forest overview with level map, full app flow integration, human verification

**UI hint**: yes

### Phase 2: Gemini-Integration + Asset-Pipeline
**Goal**: Gemini-API funktioniert fuer Text und Bild, Character Sheets sind generiert und eingebunden
**Depends on**: Phase 1
**Requirements**: GAPI-01, GAPI-02, GAPI-03, GAPI-04, GAPI-05, GAPI-06, ASST-01, ASST-02, ASST-03, ASST-04, COMP-01, COMP-02, COMP-03, COMP-04
**Success Criteria** (what must be TRUE):
  1. `npm run generate-assets` generiert alle Character Sheets und Avatare erfolgreich in `src/assets/generated/`
  2. Der Willkommens-Screen zeigt echte generierte Avatare statt Platzhalter
  3. Ein Begruessungstext der Begleitfigur wird generiert (deutsch, max 25 Woerter) oder ein Fallback-Text erscheint wenn kein API-Key vorhanden ist
  4. Ein Waldelement-Bild kann mit Stil-Referenz generiert werden; bei fehlendem API-Key zeigt die App Fallback-Bilder ohne Absturz
**Plans:** 5 plans

Plans:
- [x] 02-01-PLAN.md — Config loader, Gemini API client (text + image), retry logic, rate-limiting (TDD)
- [x] 02-02-PLAN.md — Fallback texts (greetings, forest comments, letter intros) and fallback SVG images
- [x] 02-03-PLAN.md — IndexedDB store accessors, build script for asset generation, generate all character assets
- [x] 02-04-PLAN.md — Companion text module (getGreeting, getLetterIntro, getForestComment) with API-first fallback
- [x] 02-05-PLAN.md — Wire avatars into welcome screen, companion greeting on forest screen, visual verification

### Phase 3: Komplettes Spielerlebnis
**Goal**: Alle 3 Uebungsphasen verbunden, Wald waechst visuell, Stufen 1–6 vollstaendig spielbar
**Depends on**: Phase 2
**Requirements**: TYPE-05, TYPE-06, TYPE-07, LEVL-04, LEVL-05, LEVL-06, FRST-01, FRST-02, FRST-03, RWRD-01, RWRD-02, RWRD-03, RWRD-04, PRNT-01, PRNT-02, PRNT-03, PRNT-04
**Success Criteria** (what must be TRUE):
  1. Eine komplette Uebungseinheit ist spielbar: Entdecken → Ueben → Woerter → Belohnung → zurueck zum Wald
  2. Nach dem Belohnungs-Screen erscheint ein neues Bild im Wald und bleibt nach Reload erhalten
  3. Alle Stufen 1–6 sind spielbar, jede mit passenden Woertern aus gelernten Buchstaben
  4. Der Elternbereich ist erreichbar (Ctrl+Shift+E + "1234") und zeigt aktuelle Stufe, Einheiten, Uebungstage sowie Einstellungen
  5. Review-Einheiten erscheinen jede 3. Uebung; nach 2× derselben Stufe zeigt die Begleitfigur Ermutigung
**Plans:** 5 plans

Plans:
- [x] 03-01-PLAN.md — Word lists per level, Progress type extension, rate limit update
- [x] 03-02-PLAN.md — Lesson 3-phase state machine (discover/practice/words), review + repetition logic
- [x] 03-03-PLAN.md — Forest visual scene (SVG background, 4x3 grid, element rendering from IndexedDB)
- [x] 03-04-PLAN.md — Reward screen with pre-generation, full flow wiring (lesson -> reward -> forest)
- [x] 03-05-PLAN.md — Parent area (access gate, stats overview, settings panel)

**UI hint**: yes

### Phase 4: Polish + Audio
**Goal**: Visuell und auditiv angenehmes Erlebnis, bereit zum Testen mit dem Kind
**Depends on**: Phase 3
**Requirements**: AUDI-01, AUDI-02, AUDI-03, AUDI-04, AUDI-05, PLSH-01, PLSH-02, PLSH-03, PLSH-04, PLSH-05, PRNT-05, PRNT-06, PRNT-07
**Success Criteria** (what must be TRUE):
  1. Sounds spielen bei richtigem Tastendruck, Belohnung und neuem Waldelement; Mute-Button funktioniert und Zustand bleibt nach Reload
  2. Buchstaben fallen sanft (keine ruckartigen Animationen), Sternenstaub-Animation erscheint bei Erfolg
  3. Sprachausgabe liest Companion-Text vor wenn aktiviert (Web Speech API, Deutsch)
  4. Export und Import funktionieren: Exportieren → Browser-Daten loeschen → Importieren → Fortschritt wiederhergestellt
  5. Keine unbehandelten Exceptions in der Browser-Konsole bei normalem Gebrauch
**Plans:** 4 plans

Plans:
- [x] 04-01-PLAN.md — Audio system (Web Audio API sounds, Web Speech API speech, mute button)
- [x] 04-02-PLAN.md — Animation polish (leaf-fall, stardust, companion float), responsive, error handler
- [x] 04-03-PLAN.md — Export/Import/Reset in parent area
- [x] 04-04-PLAN.md — Wire audio into all screens, end-to-end human verification

**UI hint**: yes

## Progress

**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Grundgerüst + Tippmechanik | 5/5 | Complete | - |
| 2. Gemini-Integration + Asset-Pipeline | 5/5 | Complete | - |
| 3. Komplettes Spielerlebnis | 5/5 | Complete | - |
| 4. Polish + Audio | 0/4 | Planning complete | - |