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:

• 01-01-PLAN.md — Vite scaffold, project structure, CSS palette, TypeScript interfaces, IndexedDB wrapper
• 01-02-PLAN.md — Screen management, welcome screen, companion/layout selection, onboarding persistence
• 01-03-PLAN.md — QWERTZ keyboard component with finger colors, level definitions 1-6
• 01-04-PLAN.md — Typing exercise engine (TDD), adaptive tempo, lesson screen UI
• 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:

• 02-01-PLAN.md — Config loader, Gemini API client (text + image), retry logic, rate-limiting (TDD)
• 02-02-PLAN.md — Fallback texts (greetings, forest comments, letter intros) and fallback SVG images
• 02-03-PLAN.md — IndexedDB store accessors, build script for asset generation, generate all character assets
• 02-04-PLAN.md — Companion text module (getGreeting, getLetterIntro, getForestComment) with API-first fallback
• 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:

• 03-01-PLAN.md — Word lists per level, Progress type extension, rate limit update
• 03-02-PLAN.md — Lesson 3-phase state machine (discover/practice/words), review + repetition logic
• 03-03-PLAN.md — Forest visual scene (SVG background, 4x3 grid, element rendering from IndexedDB)
• 03-04-PLAN.md — Reward screen with pre-generation, full flow wiring (lesson -> reward -> forest)
• 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:

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

UI hint: yes

Phase 5: Multi-Wald-System: Wald-Pagination und Navigation zwischen Wäldern

Goal: Mehrere Waldseiten mit Pagination, damit der Wald unbegrenzt wachsen kann Depends on: Phase 4 Requirements: MWLD-01, MWLD-02, MWLD-03, MWLD-04, MWLD-05, MWLD-06, MWLD-07 Success Criteria (what must be TRUE):

1. Bei mehr als 12 Waldelementen erscheinen Navigationspfeile und "Wald X von Y" Anzeige
2. Pfeiltasten navigieren zwischen Waldseiten mit sanfter Fade-Animation
3. Die aktuelle Waldseite wird in Progress gespeichert und nach Browser-Reload wiederhergestellt
4. Nach Lesson-Abschluss zeigt der Wald automatisch die Seite mit dem neuen Element Plans: 2/2 plans complete

Plans:

• 05-01-PLAN.md — Progress type extension, paginated renderForestScene, navigation DOM and CSS
• 05-02-PLAN.md — Navigation handlers, page persistence, reward flow fix, human verification

Progress

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

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	4/4	Complete	-
5. Multi-Wald-System	2/2	Complete	2026-03-29