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