docs(03-02): complete lesson flow plan

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-29 13:50:01 +02:00
parent 770f566972
commit 4f1a2b55d6
4 changed files with 126 additions and 15 deletions
@@ -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*