docs(03-02): complete lesson flow plan

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.planning/REQUIREMENTS.md

@@ -36,9 +36,9 @@ Requirements for initial release (MVP). Each maps to roadmap phases.
 - [x] **TYPE-02**: Richtiger Tastendruck löst Buchstaben auf (Sternenstaub-Animation)
 - [x] **TYPE-03**: Falscher Tastendruck: Nichts passiert, richtige Taste blinkt sanft auf Tastatur
 - [x] **TYPE-04**: Adaptives Tempo: Start 3s, nach 2× richtig -200ms (min 1.5s), nach Fehler +500ms (max 4s)
-- [ ] **TYPE-05**: Phase "Entdecken": Begleitfigur stellt neuen Buchstaben vor, Taste leuchtet auf
+- [x] **TYPE-05**: Phase "Entdecken": Begleitfigur stellt neuen Buchstaben vor, Taste leuchtet auf
 - [x] **TYPE-06**: Phase "Wörter bauen": 3–4 Wörter aus gelernten Buchstaben, Buchstabe für Buchstabe tippen
-- [ ] **TYPE-07**: Alle 3 Phasen fliessend verbunden: Entdecken → Üben → Wörter → Belohnung
+- [x] **TYPE-07**: Alle 3 Phasen fliessend verbunden: Entdecken → Üben → Wörter → Belohnung
 
 ### Levels
 
@@ -46,8 +46,8 @@ Requirements for initial release (MVP). Each maps to roadmap phases.
 - [x] **LEVL-02**: Stufe gilt als abgeschlossen nach einmaligem Durchspielen (nicht perfekt)
 - [x] **LEVL-03**: Nächste Stufe sofort freigeschaltet, alle gespielten Stufen wiederholbar
 - [x] **LEVL-04**: Wortlisten pro Stufe (nur mit bereits gelernten Buchstaben, max 5 Buchstaben)
-- [ ] **LEVL-05**: Review-Mechanik: Jede 3. Einheit mischt Buchstaben der letzten 2–3 Stufen
+- [x] **LEVL-05**: Review-Mechanik: Jede 3. Einheit mischt Buchstaben der letzten 2–3 Stufen
-- [ ] **LEVL-06**: Wiederholungs-Schutz: Nach 2× gleicher Stufe Ermutigung + Neugier-Trigger
+- [x] **LEVL-06**: Wiederholungs-Schutz: Nach 2× gleicher Stufe Ermutigung + Neugier-Trigger
 
 ### Gemini API
 
@@ -187,12 +187,12 @@ Which phases cover which requirements. Updated during roadmap creation.
 | COMP-02 | Phase 2 | Complete |
 | COMP-03 | Phase 2 | Complete |
 | COMP-04 | Phase 2 | Complete |
-| TYPE-05 | Phase 3 | Pending |
+| TYPE-05 | Phase 3 | Complete |
 | TYPE-06 | Phase 3 | Complete |
-| TYPE-07 | Phase 3 | Pending |
+| TYPE-07 | Phase 3 | Complete |
 | LEVL-04 | Phase 3 | Complete |
-| LEVL-05 | Phase 3 | Pending |
+| LEVL-05 | Phase 3 | Complete |
-| LEVL-06 | Phase 3 | Pending |
+| LEVL-06 | Phase 3 | Complete |
 | FRST-01 | Phase 3 | Complete |
 | FRST-02 | Phase 3 | Complete |
 | FRST-03 | Phase 3 | Complete |

.planning/ROADMAP.md

@@ -72,7 +72,7 @@ Plans:
 
 Plans:
 - [x] 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
+- [x] 03-02-PLAN.md — Lesson 3-phase state machine (discover/practice/words), review + repetition logic
 - [x] 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)
 - [x] 03-05-PLAN.md — Parent area (access gate, stats overview, settings panel)

.planning/STATE.md

@@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: executing
-stopped_at: Completed 03-05-PLAN.md
+stopped_at: Completed 03-02-PLAN.md
-last_updated: "2026-03-29T11:47:40.577Z"
+last_updated: "2026-03-29T11:49:51.101Z"
 last_activity: 2026-03-29
 progress:
   total_phases: 4
   completed_phases: 2
   total_plans: 15
-  completed_plans: 13
+  completed_plans: 14
   percent: 0
 ---
 
@@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-03-29)
 ## Current Position
 
 Phase: 03 (komplettes-spielerlebnis) — EXECUTING
-Plan: 4 of 5
+Plan: 5 of 5
 Status: Ready to execute
 Last activity: 2026-03-29
 
@@ -65,6 +65,7 @@ Progress: [░░░░░░░░░░] 0%
 | Phase 03 P03 | 2min | 2 tasks | 3 files |
 | Phase 03 P01 | 3min | 2 tasks | 7 files |
 | Phase 03 P05 | 2min | 2 tasks | 4 files |
+| Phase 03 P02 | 4min | 2 tasks | 6 files |
 
 ## Accumulated Context
 
@@ -95,6 +96,8 @@ Recent decisions affecting current work:
 - [Phase 03]: Levels 1-2 use letter combos (no real German words with F/J/D/K only)
 - [Phase 03]: Rate limits raised to 10 text / 5 image per day for practical usage
 - [Phase 03]: Access code hardcoded as 1234 for single-user private app
+- [Phase 03]: Word mode uses intervalMs=0 (no timing pressure for word display)
+- [Phase 03]: Discover phase skips space key; review pulls 2 words from each of last 2-3 levels
 
 ### Pending Todos
 
@@ -106,6 +109,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-03-29T11:47:40.570Z
+Last session: 2026-03-29T11:49:51.094Z
-Stopped at: Completed 03-05-PLAN.md
+Stopped at: Completed 03-02-PLAN.md
 Resume file: None

.planning/phases/03-komplettes-spielerlebnis/03-02-SUMMARY.md

@@ -0,0 +1,108 @@
+---
+phase: 03-komplettes-spielerlebnis
+plan: 02
+subsystem: game-ui
+tags: [typing-engine, lesson-flow, state-machine, word-mode, review, companion]
+
+requires:
+  - phase: 03-komplettes-spielerlebnis
+    plan: 01
+    provides: "Word lists per level, LessonPhase type, extended Progress with accuracy fields"
+  - phase: 02-gemini-integration
+    provides: "Companion text generation via getLetterIntro"
+  - phase: 01-technische-basis
+    provides: "Typing engine, keyboard rendering, level definitions"
+provides:
+  - "3-phase lesson flow state machine (discover -> practice -> words)"
+  - "Word mode typing engine with createWordExerciseState() and getCurrentWordIndex()"
+  - "Review mode flag for mixed letter/word sessions"
+  - "Repetition encouragement messages"
+  - "Cumulative stats (correct, errors, errorKeys) passed to onComplete"
+affects: [03-03-reward-system, 03-04-parent-area, 03-05-audio]
+
+tech-stack:
+  added: []
+  patterns: ["Promise-based phase state machine", "TDD for typing engine extensions"]
+
+key-files:
+  created: []
+  modified:
+    - src/game/typing.ts
+    - src/game/typing.test.ts
+    - src/types.ts
+    - src/ui/screens.ts
+    - src/styles/main.css
+    - index.html
+
+key-decisions:
+  - "Word mode uses intervalMs=0 (no falling/timing pressure for word display)"
+  - "Discover phase skips space key (not meaningful to 'discover' spacebar)"
+  - "Review word selection: 2 words from each of last 2-3 levels, shuffled"
+
+patterns-established:
+  - "Promise-based phase state machine: each phase is an async function returning Promise<void>"
+  - "Cumulative stats tracking across exercise phases via closure variables"
+
+requirements-completed: [TYPE-05, TYPE-06, TYPE-07, LEVL-05, LEVL-06]
+
+duration: 4min
+completed: 2026-03-29
+---
+
+# Phase 03 Plan 02: Lesson Flow Summary
+
+**3-phase lesson state machine (discover -> practice -> words) with companion letter intros, word display UI, review mode, and repetition encouragement**
+
+## Performance
+
+- **Duration:** 4 min
+- **Started:** 2026-03-29T11:44:16Z
+- **Completed:** 2026-03-29T11:49:05Z
+- **Tasks:** 2
+- **Files modified:** 6
+
+## Accomplishments
+- Extended typing engine with word mode: createWordExerciseState() splits words into letters with boundary tracking
+- Lesson screen flows through 3 phases: discover (companion intro + key pulse) -> practice (letter exercise) -> words (word display with active letter)
+- Review mode skips discover, mixes content from recent 2-3 levels
+- Encouragement messages shown before lessons when repetition detected
+- Cumulative stats (correct, errors, errorKeys) tracked across all phases and passed to onComplete
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Extend typing engine with word mode** - `958f446` (test: RED), `2c0c2f2` (feat: GREEN)
+2. **Task 2: Lesson screen 3-phase state machine** - `770f566` (feat)
+
+## Files Created/Modified
+- `src/types.ts` - TypingExerciseState extended with mode, words, wordBoundaries fields
+- `src/game/typing.ts` - createWordExerciseState(), getCurrentWordIndex() functions
+- `src/game/typing.test.ts` - 12 new tests for word mode, backwards compatibility, word index helper
+- `src/ui/screens.ts` - Full rewrite of initLessonScreen with 3-phase state machine, review/encouragement params
+- `src/styles/main.css` - Phase indicator, word display, discover pulse CSS
+- `index.html` - Phase indicator div added to lesson screen
+
+## Decisions Made
+- Word mode uses intervalMs=0: no falling/timing pressure during word typing (words are typed at child's pace)
+- Discover phase skips space key: not meaningful to "discover" the spacebar
+- Review word selection pulls 2 words from each of last 2-3 levels, shuffles, takes 4
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Lesson flow complete, ready for reward system integration (03-03)
+- onComplete now passes stats for parent area tracking (03-04)
+- Phase indicator and word display UI ready for audio integration (03-05)
+
+---
+*Phase: 03-komplettes-spielerlebnis*
+*Completed: 2026-03-29*