From 4f1a2b55d6495a1e9c704aa98bd10fff91272c1e Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Sun, 29 Mar 2026 13:50:01 +0200 Subject: [PATCH] docs(03-02): complete lesson flow plan Co-Authored-By: Claude Opus 4.6 (1M context) --- .planning/REQUIREMENTS.md | 16 +-- .planning/ROADMAP.md | 2 +- .planning/STATE.md | 15 ++- .../03-02-SUMMARY.md | 108 ++++++++++++++++++ 4 files changed, 126 insertions(+), 15 deletions(-) create mode 100644 .planning/phases/03-komplettes-spielerlebnis/03-02-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 45bb712..30224d4 100644 --- a/.planning/REQUIREMENTS.md +++ b/.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 -- [ ] **LEVL-06**: Wiederholungs-Schutz: Nach 2× gleicher Stufe Ermutigung + Neugier-Trigger +- [x] **LEVL-05**: Review-Mechanik: Jede 3. Einheit mischt Buchstaben der letzten 2–3 Stufen +- [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-06 | Phase 3 | Pending | +| LEVL-05 | Phase 3 | Complete | +| LEVL-06 | Phase 3 | Complete | | FRST-01 | Phase 3 | Complete | | FRST-02 | Phase 3 | Complete | | FRST-03 | Phase 3 | Complete | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index f554283..42b0105 100644 --- a/.planning/ROADMAP.md +++ b/.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) diff --git a/.planning/STATE.md b/.planning/STATE.md index c37fc94..82a9600 100644 --- a/.planning/STATE.md +++ b/.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 -last_updated: "2026-03-29T11:47:40.577Z" +stopped_at: Completed 03-02-PLAN.md +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 -Stopped at: Completed 03-05-PLAN.md +Last session: 2026-03-29T11:49:51.094Z +Stopped at: Completed 03-02-PLAN.md Resume file: None diff --git a/.planning/phases/03-komplettes-spielerlebnis/03-02-SUMMARY.md b/.planning/phases/03-komplettes-spielerlebnis/03-02-SUMMARY.md new file mode 100644 index 0000000..157bd35 --- /dev/null +++ b/.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" + - "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*