# Phase 3: Komplettes Spielerlebnis - Context

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

<domain>
## 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).
</domain>

<decisions>
## 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)
</decisions>

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

<specifics>
## Specific Ideas

No specific requirements — open to standard approaches
</specifics>

<deferred>
## Deferred Ideas

None — analysis stayed within phase scope
</deferred>