diff --git a/.planning/phases/03-komplettes-spielerlebnis/03-CONTEXT.md b/.planning/phases/03-komplettes-spielerlebnis/03-CONTEXT.md new file mode 100644 index 0000000..574675b --- /dev/null +++ b/.planning/phases/03-komplettes-spielerlebnis/03-CONTEXT.md @@ -0,0 +1,114 @@ +# 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 `` 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`, `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 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) + + + +## 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 + + + +## Specific Ideas + +No specific requirements — open to standard approaches + + + +## Deferred Ideas + +None — analysis stayed within phase scope + diff --git a/.planning/phases/03-komplettes-spielerlebnis/03-DISCUSSION-LOG.md b/.planning/phases/03-komplettes-spielerlebnis/03-DISCUSSION-LOG.md new file mode 100644 index 0000000..79f7efb --- /dev/null +++ b/.planning/phases/03-komplettes-spielerlebnis/03-DISCUSSION-LOG.md @@ -0,0 +1,40 @@ +# Phase 3: Komplettes Spielerlebnis - Discussion Log (Assumptions Mode) + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions captured in CONTEXT.md — this log preserves the analysis. + +**Date:** 2026-03-29 +**Phase:** 03-Komplettes Spielerlebnis +**Mode:** assumptions +**Areas analyzed:** Lesson Flow Architecture, Forest Scene, Reward Flow, Parent Area, Rate Limiting + +## Assumptions Presented + +### Lesson Flow Architecture +| Assumption | Confidence | Evidence | +|------------|-----------|----------| +| Sub-phases as internal state machine in lesson screen | Confident | ScreenName has 5 entries (D-01 from Phase 1) | +| Word building extends existing typing engine with mode param | Likely | typing.ts letters array + currentLetterIndex reusable | + +### Forest Scene +| Assumption | Confidence | Evidence | +|------------|-----------|----------| +| SVG background + HTML overlay CSS grid for forest elements | Likely | ForestElement.position exists, fallback SVGs ready | + +### Reward Flow +| Assumption | Confidence | Evidence | +|------------|-----------|----------| +| Pre-generation at lesson start, await on reward screen | Likely | generateImage async, screen-reward exists but empty | + +### Parent Area +| Assumption | Confidence | Evidence | +|------------|-----------|----------| +| Extend Progress interface with stats, no DB version bump | Confident | IndexedDB schema-less for values | + +## Corrections Made + +No corrections — all assumptions confirmed. + +## External Research Flagged + +- Rate limit adequacy: current 1/1 per day needs increase to ~10 text + 5 image per day