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: TBD 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: TBD

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: TBD 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: TBD UI hint: yes

Progress

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

Phase	Plans Complete	Status	Completed
1. Grundgerüst + Tippmechanik	0/?	Not started	-
2. Gemini-Integration + Asset-Pipeline	0/?	Not started	-
3. Komplettes Spielerlebnis	0/?	Not started	-
4. Polish + Audio	0/?	Not started	-