Zauberwald/.planning/phases/03-komplettes-spielerlebnis/03-CONTEXT.md

Phase 3: Komplettes Spielerlebnis - Context

Gathered: 2026-03-29 (assumptions mode) Status: Ready for planning

## Phase Boundary

Alle 3 Übungsphasen verbunden (Entdecken → Üben → Wörter → Belohnung), Wald wächst visuell mit KI-generierten Bildern, Stufen 1–6 vollständig spielbar mit Wortlisten, Elternbereich mit Statistik und Einstellungen. Kein Audio (Phase 4), keine erweiterten Animationen (Phase 4), kein Export/Import (Phase 4).

## Implementation Decisions

Lesson Flow Architecture

• D-01: Sub-Phasen (Entdecken, Üben, Wörter) als interne State-Machine innerhalb initLessonScreen. DOM-Content wird im bestehenden screen-lesson Container getauscht. Kein neuer Screen — ScreenName bleibt bei 5 Einträgen. Lesson-State: "discover" | "practice" | "words", Transitions via DOM-Swap im letter-area / lesson-keyboard Bereich.
• D-02: "Entdecken" Phase: Companion stellt neuen Buchstaben vor (via getLetterIntro), Taste leuchtet auf der Tastatur auf. Kind muss die Taste einmal drücken um fortzufahren. ~30 Sekunden.
• D-03: "Wörter bauen" Phase: Erweitert bestehende Typing-Engine mit mode "words". createExerciseState bekommt mode-Parameter und Wortliste. Wort wird ganz angezeigt, aktiver Buchstabe hervorgehoben. 3-4 Wörter pro Übung.

Word Lists

• D-04: Statische Wortlisten pro Stufe in src/game/words.ts. Nur Buchstaben die bis zu dieser Stufe gelernt wurden, max 5 Zeichen. Mindestens 8-10 Wörter pro Stufe damit Variation möglich.

Review Mechanic

• D-05: Jede 3. Übungseinheit ist automatisch ein Review: gemischte Buchstaben aus den letzten 2-3 Stufen. totalSessions % 3 === 0 als Trigger. Review-Einheiten generieren auch Wald-Belohnungen.
• D-06: Wiederholungs-Schutz: Nach 2× derselben Stufe hintereinander zeigt Companion Ermutigung + Neugier-Trigger ("Magst du sehen, was als Nächstes kommt?"). Tracking via neues Feld lastPlayedLevels: number[] in Progress (letzte 3 gespielten Stufen).

Forest Scene

• D-07: SVG-Hintergrund (statische Waldlandschaft) mit HTML-Overlay-Grid darüber. 4×3 CSS-Grid (12 Slots). Waldbilder als <img> mit Object URLs aus IndexedDB Blobs. Jedes neue Element bekommt nächsten freien Slot ± 10-20px Zufalls-Offset.
• D-08: Fade-in + Scale-up CSS-Animation für neue Elemente. Bestehende Elemente laden aus IndexedDB beim Forest-Screen-Init.
• D-09: Stufenkarte (Level-Map) bleibt erhalten, wird unter/neben dem Wald platziert.

Reward Flow

• D-10: Flow nach Lesson: Üben-Ende → Reward-Screen → Forest. Nicht direkt zurück zum Forest.
• D-11: Pre-Generation: Bild-Generierung startet bei Lesson-Start (startLessonFromForest). Promise wird in Variable gespeichert. Reward-Screen awaited das Promise. Platzhalter "Der Wald denkt nach..." mit animierten Blättern wenn Bild noch nicht fertig.
• D-12: Reward-Screen zeigt: neues Waldelement-Bild + Companion-Kommentar (via getForestComment) + "Weiter üben" / "Zurück zum Wald" Buttons. Bei API-Fehler: Fallback-SVG als Waldelement.

Rate Limiting

• D-13: Rate-Limit anpassen: Max 10 Text-Calls + 5 Bild-Calls pro Tag (statt je 1). Eine Übungseinheit braucht ~2 Text-Calls (Buchstaben-Vorstellung + Wald-Kommentar) + 1 Bild-Call. Kind macht max 2-3 Einheiten pro Tag.

Parent Area

• D-14: Zugang: Ctrl+Shift+E öffnet Code-Eingabe, Code "1234" schaltet frei. Eigener Screen screen-parent (existiert als leere Section).
• D-15: Progress-Interface erweitern mit: totalCorrect: number, totalErrors: number, errorKeyCounts: Record<string, number>, lastPlayedLevels: number[]. Kein DB-Version-Bump nötig.
• D-16: handleLessonComplete muss Exercise-State (Genauigkeit, Fehler-Tasten) zusammen mit completedLevel übergeben, damit Stats persistiert werden.
• D-17: Elternbereich zeigt: aktuelle Stufe, abgeschlossene Einheiten (totalSessions), Übungstage (sessionDates als Kalender-Dots), durchschnittliche Genauigkeit, häufigste Fehlertasten.
• D-18: Einstellungen im Elternbereich: Layout-Wechsel (DE/CH), Audio an/aus (Platzhalter für Phase 4), Begleitfigur wechseln, API-Key Eingabe (Fallback wenn config.json fehlt).

Claude's Discretion

• SVG-Waldlandschaft Design (Farben, Elemente, Stil)
• Exact CSS-Grid Layout für Forest-Elemente (Gap, Padding)
• Platzhalter-Animation ("Der Wald denkt nach...")
• Kalender-Dots Visualisierung im Elternbereich
• Word-Display UI (wie Wörter und aktiver Buchstabe dargestellt werden)

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

• SPEC.md — Full specification, THE authoritative source
• SPEC.md section 3.1 — Mikro-Einheiten: 3 Phasen (Entdecken, Üben, Wörter)
• SPEC.md section 3.2 — Frustrations- und Perfektionismus-Handling
• SPEC.md section 4 — Progressionssystem, Freischaltung, Review-Mechanik
• SPEC.md section 5 — Waldwelt: visuelles Wachstum, Bild-Platzierung, Konsistenz
• SPEC.md section 7.1 — Screen-Struktur (Elternbereich Details)
• src/game/typing.ts — Typing engine (extend for word mode)
• src/ui/screens.ts — Lesson screen (extend for 3 sub-phases)
• src/app.ts — App flow (extend lesson-complete → reward → forest)
• src/forest/scene.ts — Forest screen (add visual grid)
• src/companion/companion.ts — Companion text functions
• src/api/gemini.ts — Image/text generation + rate limiting
• src/storage/db.ts — IndexedDB accessors
• src/types.ts — TypeScript interfaces (extend Progress) </canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• src/game/typing.ts: TypingExerciseState with letters array, currentLetterIndex, adaptive tempo — extend for word mode
• src/api/gemini.ts: generateText(), generateImage() with retry + rate-limiting — ready to use
• src/companion/companion.ts: getGreeting(), getLetterIntro(), getForestComment() — ready to use
• src/companion/fallbacks.ts: 10 greetings, 10 forest comments, 13 letter intros, getRandomFallbackImage()
• src/storage/db.ts: saveForestElement(), getForestElements(), saveStyleReference(), getStyleReference() — ready
• src/assets/fallback-images/: 7 SVG fallback images (blume, pilz, vogel, schmetterling, reh, baum, bach)
• src/assets/style-reference/initial-forest-scene.png: Style reference for image generation

Established Patterns

• Screen toggling via showScreen() + CSS classes
• IndexedDB Promise wrappers with typed results
• Companion text: API-first + fallback pattern
• BEM CSS naming, pastel color palette via custom properties

Integration Points

• app.ts handleLessonComplete — change flow: lesson → reward → forest, pass exercise stats
• app.ts startLessonFromForest — add pre-generation trigger
• screens.ts initLessonScreen — extend with sub-phase state machine
• scene.ts initForestScreen — add visual forest grid alongside level map
• index.html screen-reward — currently empty, needs content
• index.html screen-parent — currently empty, needs content
• types.ts Progress — add stats fields </code_context>

## Specific Ideas

No specific requirements — open to standard approaches

## Deferred Ideas

None — analysis stayed within phase scope