Zauberwald/.planning/PROJECT.md

# Zauberwald

## What This Is

Zauberwald ist eine Webapplikation, die einem 7-jährigen Kind das 10-Finger-Tastaturschreiben beibringt. Die App verbindet strukturiertes Tipptraining mit einer dynamisch wachsenden, KI-generierten Waldwelt. Fester Übungsrahmen, überraschende Belohnungen — Neugier statt Leistungsdruck.

## Core Value

Das Kind übt freiwillig weiter, weil es wissen will, was als Nächstes im Wald erscheint — nicht weil es Punkte sammelt oder Sterne verdient.

## Requirements

### Validated

- [x] Bildschirmtastatur: QWERTZ-Layout (DE/CH), Fingerfarben-Zonen, aktive Taste pulsiert — *Validated in Phase 1*
- [x] Progressionssystem: Stufen 1–6 definiert und spielbar — *Validated in Phase 1*
- [x] Kein sichtbarer Leistungsdruck: Keine Scores, Timer, Fehler-Zähler in der Übung — *Validated in Phase 1*
- [x] Begleitfigur: 4 Charaktere mit KI-generierten Dialogen und generierten Avataren — *Validated in Phase 2*
- [x] Visuelle Konsistenz: Character Sheets als Referenzbilder, Stil-Referenzbild generiert — *Validated in Phase 2*
- [x] Mikro-Einheiten: 3 Phasen (Entdecken → Üben → Wörter bauen) verbunden — *Validated in Phase 3*
- [x] Waldwelt: KI-generierte Bilder als Belohnung, dauerhaft gecacht, visuell wachsend — *Validated in Phase 3*
- [x] Review-Mechanik: Jede 3. Einheit mischt Buchstaben der letzten Stufen — *Validated in Phase 3*
- [x] Elternbereich: Ctrl+Shift+E + Code, Statistik, Einstellungen — *Validated in Phase 3*

### Active

- [ ] Mikro-Einheiten: 3 Phasen (Entdecken → Üben → Wörter bauen), je 90–120 Sekunden
- [ ] Kein sichtbarer Leistungsdruck: Keine Scores, Timer, Fehler-Zähler. Fortschritt nur über wachsenden Wald
- [ ] Bildschirmtastatur: QWERTZ-Layout (DE/CH), Fingerfarben-Zonen, aktive Taste pulsiert
- [ ] Progressionssystem: 15 Stufen (Grundreihe → Ober → Unter → Sonderzeichen), Stufen 1–6 im MVP
- [ ] Begleitfigur: 4 Charaktere (Fee Lila, Einhorn Stella, Fuchs Finn, Eule Elsa) mit KI-generierten Dialogen
- [ ] Waldwelt: KI-generierte Bilder (Gemini) als Belohnung nach jeder Einheit, dauerhaft gecacht
- [ ] Visuelle Konsistenz: Character Sheets als Referenzbilder, Stil-Referenzbild für alle Generierungen
- [ ] Adaptives Tempo: Heuristik ±200/500ms, Bereich 1.5–4s, kein sichtbarer Timer
- [ ] Fehler sind unsichtbar: Falscher Tastendruck → nichts passiert, richtige Taste blinkt sanft
- [ ] Review-Mechanik: Jede 3. Einheit mischt Buchstaben der letzten 2–3 Stufen
- [ ] Perfektionismus-Schutz: Nach 2× Wiederholung Ermutigung + Neugier-Trigger
- [ ] Elternbereich: Ctrl+Shift+E + Code "1234", Fortschrittsstatistik, Export/Import, Einstellungen
- [ ] Audio: Web Audio API Sounds (Tastendruck, Belohnung, Waldelement), optionale Sprachausgabe via Web Speech API
- [ ] Pre-Generation: Belohnungsbild wird während Übung im Hintergrund generiert
- [ ] Fallback-System: Statische Bilder + Texte wenn API nicht verfügbar

### Out of Scope

- Stufen 7–15 (untere Reihe, Grossbuchstaben, Zahlen, Sonderzeichen) — MVP fokussiert auf Stufen 1–6
- Ganze Sätze tippen — erst relevant nach allen Buchstaben
- "Freies Schreiben"-Modus — späterer Milestone
- Saisonale Wald-Themen — nice-to-have, nicht MVP
- Begleitfigur reagiert auf längere Abwesenheit — späterer Milestone
- Druckbare Urkunden — nicht MVP
- Mobile Support — Desktop-only, Kind nutzt Linux-Laptop
- OAuth/Social Login — kein Nutzersystem nötig, eine Nutzerin
- Echtzeit-Chat — irrelevant für Einzelnutzung
- Video-Inhalte — Storage/Bandwidth, unnötig

## Context

- **Primäre Nutzerin**: 7 Jahre, 1. Klasse, vermuteter ADHS-Hintergrund (nicht diagnostiziert). Niedrige Frustrationstoleranz, impulsiv, Perfektionismus-Neigung. Max. 5 Min. Übungsdauer. Interessen: Tiere, Feen, Einhörner, Magie, Natur.
- **Technischer Kontext**: Linux-Laptop, Desktop-Browser, stabile Internetverbindung. Einzige Nutzerin.
- **Entwicklungsumgebung**: VPS (kein lokaler Rechner). Vite Dev-Server muss auf 0.0.0.0 lauschen, Port 5173. Papa testet via `http://<vps-ip>:5173`.
- **Pädagogisches Prinzip**: Genauigkeit vor Geschwindigkeit. Kein negatives Feedback jeglicher Art. Neugier als Motor.
- **Gemini API**: Key in `public/config.json` (nicht in Git). Text: gemini-2.5-flash. Bild: gemini-3.1-flash-image-preview (Nano Banana 2). Character Consistency via Referenzbilder.
- **Asset-Pipeline**: Character Sheets + Avatare werden vorab per Build-Script generiert und eingecheckt. Kein Onboarding-Warten.

## Constraints

- **Tech Stack**: Vanilla TypeScript, Vite 6.x, kein Framework. Einzelne main.css mit CSS Custom Properties. Biome für Lint. Vitest für Tests.
- **API**: Gemini REST via fetch(), kein Google SDK. Key im Frontend akzeptabel (private Nutzung).
- **Datenhaltung**: IndexedDB (Bilder als Blobs). Kein Backend, kein Server.
- **Layout**: QWERTZ DE + CH. Unterschiede erst ab Stufe 14+ relevant.
- **Styling**: Pastellfarben, Aquarell-Stil, Quicksand + Nunito Fonts, min. 16px. Sanfte Animationen.
- **VPS-Deployment**: `--host 0.0.0.0`, Port 5173 (dev) / 4173 (preview). Kein HTTPS nötig.

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Vanilla TypeScript statt Framework | Minimale Komplexität, kein Framework-Overhead | — Pending |
| DOM-basierte Waldszene (img über SVG) | Einfachste Lösung für generierte PNGs, kein Canvas/WebGL | — Pending |
| Raster 4×3 mit ±20px Variation für Bildplatzierung | Vorhersehbar, kein Overlap | — Pending |
| Gemini 3.1 Flash Image Preview für Bilder | Neuestes Modell, Character Consistency, wird nicht abgeschaltet | — Pending |
| Web Speech API statt Gemini TTS | Gratis, offline-fähig, kein extra API-Call | — Pending |
| Vorab-generierte Character Assets | Kein Onboarding-Warten, volle Kontrolle über Qualität | — Pending |
| Adaptives Tempo Heuristik statt ML | Einfach implementierbar, ausreichend für den Zweck | — Pending |

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition** (via `/gsd:transition`):
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone** (via `/gsd:complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---
*Last updated: 2026-03-29 after Phase 3 completion — Komplettes Spielerlebnis*