Zauberwald/.planning/REQUIREMENTS.md

# Requirements: Zauberwald

**Defined:** 2026-03-29
**Core Value:** Das Kind übt freiwillig weiter, weil es wissen will, was als Nächstes im Wald erscheint — nicht weil es Punkte sammelt.

## v1 Requirements

Requirements for initial release (MVP). Each maps to roadmap phases.

### Foundation

- [x] **FNDN-01**: Vite-Projekt mit vanilla-ts Template, TypeScript strict mode, Biome Lint, Vitest
- [x] **FNDN-02**: Projektstruktur gemäss Spec Abschnitt 13 (alle Verzeichnisse + Dateien)
- [x] **FNDN-03**: Alle TypeScript-Interfaces definiert (Progress, ForestElement, CompanionAssets, Level, etc.)
- [x] **FNDN-04**: IndexedDB-Wrapper mit allen Stores (progress, companionAssets, styleReference, forestElements, settings)
- [x] **FNDN-05**: Screen-Management: 5 Screens (welcome, forest, lesson, reward, parent), CSS fade Transitions

### Onboarding

- [x] **ONBD-01**: Willkommens-Screen mit Begleitfigur-Auswahl (4 Karten mit Avataren)
- [x] **ONBD-02**: Tastatur-Layout-Auswahl (DE/CH) im Willkommens-Screen
- [x] **ONBD-03**: Auswahl persistiert in IndexedDB, wird nach Reload wiederhergestellt
- [x] **ONBD-04**: "Los geht's" führt direkt zur Wald-Übersicht (kein Ladescreen)

### Keyboard

- [x] **KYBD-01**: Bildschirmtastatur rendert vollständiges QWERTZ-Layout
- [x] **KYBD-02**: Tasten zeigen Fingerfarben gemäss Farbpalette (8 Fingerfarben + Daumen)
- [x] **KYBD-03**: Aktive Taste pulsiert sanft, gedrückte Taste zeigt Press-Animation
- [x] **KYBD-04**: Noch nicht gelernte Tasten sind ausgegraut
- [x] **KYBD-05**: Beide Layouts (DE/CH) als Daten hinterlegt und umschaltbar

### Typing

- [x] **TYPE-01**: Phase "Üben": Buchstaben erscheinen einzeln (CSS-Animation fallend), 8–12 pro Übung
- [x] **TYPE-02**: Richtiger Tastendruck löst Buchstaben auf (Sternenstaub-Animation)
- [x] **TYPE-03**: Falscher Tastendruck: Nichts passiert, richtige Taste blinkt sanft auf Tastatur
- [x] **TYPE-04**: Adaptives Tempo: Start 3s, nach 2× richtig -200ms (min 1.5s), nach Fehler +500ms (max 4s)
- [ ] **TYPE-05**: Phase "Entdecken": Begleitfigur stellt neuen Buchstaben vor, Taste leuchtet auf
- [ ] **TYPE-06**: Phase "Wörter bauen": 3–4 Wörter aus gelernten Buchstaben, Buchstabe für Buchstabe tippen
- [ ] **TYPE-07**: Alle 3 Phasen fliessend verbunden: Entdecken → Üben → Wörter → Belohnung

### Levels

- [x] **LEVL-01**: Stufen 1–6 definiert gemäss Progressionstabelle (F/J bis E/I)
- [x] **LEVL-02**: Stufe gilt als abgeschlossen nach einmaligem Durchspielen (nicht perfekt)
- [x] **LEVL-03**: Nächste Stufe sofort freigeschaltet, alle gespielten Stufen wiederholbar
- [ ] **LEVL-04**: Wortlisten pro Stufe (nur mit bereits gelernten Buchstaben, max 5 Buchstaben)
- [ ] **LEVL-05**: Review-Mechanik: Jede 3. Einheit mischt Buchstaben der letzten 2–3 Stufen
- [ ] **LEVL-06**: Wiederholungs-Schutz: Nach 2× gleicher Stufe Ermutigung + Neugier-Trigger

### Gemini API

- [ ] **GAPI-01**: Config-Loader: `public/config.json` via fetch laden, typisiertes Interface
- [ ] **GAPI-02**: Text-API-Client: `generateText(prompt, systemPrompt)` mit Retry und Fehlerbehandlung
- [ ] **GAPI-03**: Bild-API-Client: `generateImage(prompt, referenceImages[])` mit Character Consistency
- [ ] **GAPI-04**: Fallback-Texte: 10 Begrüssungen, 10 Wald-Kommentare, Buchstaben-Vorstellungen Stufe 1–6
- [ ] **GAPI-05**: Fallback-Bilder: 5–10 statische SVG/PNG-Bilder als Backup
- [ ] **GAPI-06**: Rate-Limiting: Max 1 Bild + 1 Text pro Übungseinheit

### Assets

- [ ] **ASST-01**: Build-Script `scripts/generate-assets.ts` generiert 4 Character Sheets + 4 Avatare + 1 Stil-Referenz
- [ ] **ASST-02**: Generierte Assets in `src/assets/companions/` und `src/assets/style-reference/` eingecheckt
- [ ] **ASST-03**: Willkommens-Screen zeigt echte generierte Avatare statt Platzhalter
- [ ] **ASST-04**: Companion-Area in Übung zeigt Avatar der gewählten Figur

### Forest

- [ ] **FRST-01**: Waldszene: SVG-Hintergrund + 4×3 Grid für generierte Bilder
- [ ] **FRST-02**: Neue Elemente mit fade-in + scale-up Animation
- [ ] **FRST-03**: Alle bisherigen Elemente aus IndexedDB geladen und angezeigt
- [ ] **FRST-04**: Stufenkarte: Level-Grid mit Status (locked/current/completed)
- [ ] **FRST-05**: "Weiter üben" Button startet nächste offene Stufe

### Companion

- [ ] **COMP-01**: Begrüssungstext bei App-Start (KI-generiert, tageszeit-abhängig, oder Fallback)
- [ ] **COMP-02**: Buchstaben-Vorstellungstext (KI-generiert mit Eselsbrücke, oder Fallback)
- [ ] **COMP-03**: Waldbelohnungs-Kommentar (KI-generiert, Staunen + Freude, oder Fallback)
- [ ] **COMP-04**: Alle Texte max 25 Wörter, einfache Sprache, kein Leistungslob, kein Englisch

### Reward

- [ ] **RWRD-01**: Belohnungs-Screen nach jeder Einheit: Neues Waldelement-Bild + Companion-Kommentar
- [ ] **RWRD-02**: Pre-Generation: Bild wird während Übung im Hintergrund generiert
- [ ] **RWRD-03**: Placeholder bei Wartezeit ("Der Wald denkt nach..." mit animierten Blättern)
- [ ] **RWRD-04**: "Weiter üben" / "Zurück zum Wald" Buttons

### Parent Area

- [ ] **PRNT-01**: Zugang via Ctrl+Shift+E + Code "1234"
- [ ] **PRNT-02**: Übersicht: Aktuelle Stufe, abgeschlossene Einheiten, Übungstage (Kalender-Dots)
- [ ] **PRNT-03**: Statistik: Durchschnittliche Genauigkeit, häufigste Fehlertasten (nur hier sichtbar)
- [ ] **PRNT-04**: Einstellungen: Layout-Wechsel, Audio an/aus, Begleitfigur wechseln, API-Key
- [ ] **PRNT-05**: Export: Fortschritt als JSON (ohne Blobs)
- [ ] **PRNT-06**: Import: JSON hochladen mit Validierung
- [ ] **PRNT-07**: Reset: Alles löschen mit doppelter Bestätigung

### Audio

- [ ] **AUDI-01**: Richtiger Tastendruck: Kurzer heller Ton (800Hz, 0.1s, Web Audio API)
- [ ] **AUDI-02**: Belohnung: Aufsteigende Tonfolge (0.8s)
- [ ] **AUDI-03**: Neues Waldelement: Glitzer-Sound (weisses Rauschen gefiltert, 0.5s)
- [ ] **AUDI-04**: Mute-Button immer sichtbar, Zustand persistiert
- [ ] **AUDI-05**: Optionale Sprachausgabe via Web Speech API (Deutsch, Rate 0.9, Pitch 1.1)

### Polish

- [ ] **PLSH-01**: Fallende Buchstaben als sanft schwebende CSS-Animation (wie Blätter)
- [ ] **PLSH-02**: Erfolg-Animation: Sternenstaub/Glitzer via CSS particles
- [ ] **PLSH-03**: Begleitfigur-Avatar: Float-Animation (sanftes Schweben)
- [ ] **PLSH-04**: Responsive bis 700px Breite (Tastatur verkleinert, Fonts skalieren)
- [ ] **PLSH-05**: Globaler Error-Handler: Kindgerechte Fehlermeldung, kein Crash
- [x] **PLSH-06**: CSS-Palette + Typografie vollständig gemäss Spec (Custom Properties, Quicksand, Nunito)

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Extended Levels

- **ELVL-01**: Stufen 7–15 (untere Reihe, Grossbuchstaben, Zahlen, Sonderzeichen)
- **ELVL-02**: Ganze Sätze tippen

### Extended Features

- **EXTF-01**: "Freies Schreiben"-Modus (Brief an Begleitfigur)
- **EXTF-02**: Saisonale Wald-Themen
- **EXTF-03**: Begleitfigur reagiert auf längere Abwesenheit
- **EXTF-04**: Druckbare Urkunden

## Out of Scope

| Feature | Reason |
|---------|--------|
| Mobile Support | Desktop-only, Kind nutzt Linux-Laptop |
| OAuth/Social Login | Einzelnutzerin, kein Nutzersystem |
| Backend/Server | Rein clientseitig, IndexedDB für Persistenz |
| Echtzeit-Chat | Irrelevant für Einzelnutzung |
| Video-Inhalte | Storage/Bandwidth, unnötig |
| Canvas/WebGL Rendering | DOM-basiert einfacher für generierte PNGs |
| CSS Framework (Tailwind etc.) | Einzelne main.css ausreichend |
| Google SDK | Eigener typisierter REST-Client via fetch |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| FNDN-01 | Phase 1 | Complete |
| FNDN-02 | Phase 1 | Complete |
| FNDN-03 | Phase 1 | Complete |
| FNDN-04 | Phase 1 | Complete |
| FNDN-05 | Phase 1 | Complete |
| ONBD-01 | Phase 1 | Complete |
| ONBD-02 | Phase 1 | Complete |
| ONBD-03 | Phase 1 | Complete |
| ONBD-04 | Phase 1 | Complete |
| KYBD-01 | Phase 1 | Complete |
| KYBD-02 | Phase 1 | Complete |
| KYBD-03 | Phase 1 | Complete |
| KYBD-04 | Phase 1 | Complete |
| KYBD-05 | Phase 1 | Complete |
| TYPE-01 | Phase 1 | Complete |
| TYPE-02 | Phase 1 | Complete |
| TYPE-03 | Phase 1 | Complete |
| TYPE-04 | Phase 1 | Complete |
| LEVL-01 | Phase 1 | Complete |
| LEVL-02 | Phase 1 | Complete |
| LEVL-03 | Phase 1 | Complete |
| FRST-04 | Phase 1 | Pending |
| FRST-05 | Phase 1 | Pending |
| PLSH-06 | Phase 1 | Complete |
| GAPI-01 | Phase 2 | Pending |
| GAPI-02 | Phase 2 | Pending |
| GAPI-03 | Phase 2 | Pending |
| GAPI-04 | Phase 2 | Pending |
| GAPI-05 | Phase 2 | Pending |
| GAPI-06 | Phase 2 | Pending |
| ASST-01 | Phase 2 | Pending |
| ASST-02 | Phase 2 | Pending |
| ASST-03 | Phase 2 | Pending |
| ASST-04 | Phase 2 | Pending |
| COMP-01 | Phase 2 | Pending |
| COMP-02 | Phase 2 | Pending |
| COMP-03 | Phase 2 | Pending |
| COMP-04 | Phase 2 | Pending |
| TYPE-05 | Phase 3 | Pending |
| TYPE-06 | Phase 3 | Pending |
| TYPE-07 | Phase 3 | Pending |
| LEVL-04 | Phase 3 | Pending |
| LEVL-05 | Phase 3 | Pending |
| LEVL-06 | Phase 3 | Pending |
| FRST-01 | Phase 3 | Pending |
| FRST-02 | Phase 3 | Pending |
| FRST-03 | Phase 3 | Pending |
| RWRD-01 | Phase 3 | Pending |
| RWRD-02 | Phase 3 | Pending |
| RWRD-03 | Phase 3 | Pending |
| RWRD-04 | Phase 3 | Pending |
| PRNT-01 | Phase 3 | Pending |
| PRNT-02 | Phase 3 | Pending |
| PRNT-03 | Phase 3 | Pending |
| PRNT-04 | Phase 3 | Pending |
| AUDI-01 | Phase 4 | Pending |
| AUDI-02 | Phase 4 | Pending |
| AUDI-03 | Phase 4 | Pending |
| AUDI-04 | Phase 4 | Pending |
| AUDI-05 | Phase 4 | Pending |
| PLSH-01 | Phase 4 | Pending |
| PLSH-02 | Phase 4 | Pending |
| PLSH-03 | Phase 4 | Pending |
| PLSH-04 | Phase 4 | Pending |
| PLSH-05 | Phase 4 | Pending |
| PRNT-05 | Phase 4 | Pending |
| PRNT-06 | Phase 4 | Pending |
| PRNT-07 | Phase 4 | Pending |

**Coverage:**
- v1 requirements: 68 total
- Mapped to phases: 68
- Unmapped: 0 ✓

---
*Requirements defined: 2026-03-29*
*Last updated: 2026-03-29 after roadmap creation (coverage confirmed: 68/68)*