docs(03-04): complete reward screen and game loop plan

- SUMMARY.md for reward module and game flow wiring - STATE.md updated with position, decisions, metrics - ROADMAP.md updated with plan progress - Requirements RWRD-01 through RWRD-04 marked complete
2026-03-29 13:54:34 +02:00
parent aaf9872f1d
commit c0f32e09a4
4 changed files with 125 additions and 17 deletions
@@ -0,0 +1,105 @@
+---
+phase: 03-komplettes-spielerlebnis
+plan: 04
+subsystem: game-flow
+tags: [reward, pre-generation, gemini-image, indexeddb, game-loop]
+
+requires:
+  - phase: 03-01
+    provides: Progress types with stats fields, level system
+  - phase: 03-02
+    provides: Lesson screen with 3-phase flow and stats callback
+  - phase: 03-03
+    provides: Forest scene rendering with element grid and animation
+provides:
+  - Reward module with image pre-generation and display
+  - Complete game loop: forest -> lesson -> reward -> forest
+  - Review mechanic (every 3rd session)
+  - Repetition protection with encouragement
+  - Stats accumulation in Progress
+affects: [03-05-parent-area]
+
+tech-stack:
+  added: []
+  patterns: [pre-generation-pattern, fire-and-forget-async, progress-migration]
+
+key-files:
+  created:
+    - src/forest/reward.ts
+  modified:
+    - src/app.ts
+    - index.html
+    - src/styles/main.css
+
+key-decisions:
+  - "Pre-generation uses fire-and-forget pattern: startPreGeneration() called at lesson start, awaited on reward screen"
+  - "Fallback images loaded from existing SVGs in src/assets/fallback-images/ when rate-limited"
+  - "Progress migration function ensures backward compatibility with older saved data"
+
+patterns-established:
+  - "Pre-generation pattern: start async work early, await result when needed, with fallback"
+  - "Progress migration: migrateProgress() ensures all fields exist before use"
+
+requirements-completed: [RWRD-01, RWRD-02, RWRD-03, RWRD-04, TYPE-07]
+
+duration: 3min
+completed: 2026-03-29
+---
+
+# Phase 03 Plan 04: Reward Screen & Game Loop Summary
+
+**Reward screen with pre-generated forest element images, companion comments, and complete game loop wiring (forest -> lesson -> reward -> forest)**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-03-29T11:50:31Z
+- **Completed:** 2026-03-29T11:53:36Z
+- **Tasks:** 2
+- **Files modified:** 4
+
+## Accomplishments
+- Complete game loop: lesson completion shows reward screen with generated/fallback image and companion comment
+- Image pre-generation starts at lesson begin, placeholder with animated leaves shown while loading
+- Review mode triggers every 3rd session, encouragement after 2x same level
+- Exercise stats (correct, errors, errorKeys) accumulated in Progress across sessions
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Reward module with pre-generation and reward screen** - `e599050` (feat)
+2. **Task 2: Wire complete flow in app.ts with review/repeat triggers** - `aaf9872` (feat)
+
+## Files Created/Modified
+- `src/forest/reward.ts` - Reward module: startPreGeneration(), initRewardScreen(), fallback image handling
+- `src/app.ts` - Updated game flow: lesson -> reward -> forest, review triggers, stats accumulation, progress migration
+- `index.html` - Reward screen HTML with image area, companion comment, action buttons
+- `src/styles/main.css` - Reward screen CSS with placeholder animation, image appear animation, button styles
+
+## Decisions Made
+- Pre-generation uses fire-and-forget pattern at lesson start, awaited on reward screen with placeholder
+- Fallback images loaded from existing static SVGs when rate-limited or API unavailable
+- Progress migration function (migrateProgress) ensures backward compatibility with older IndexedDB data
+- Grid position for new elements uses modulo 12 with random offset for natural placement
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Known Stubs
+None - all data paths are wired to real sources.
+
+## Next Phase Readiness
+- Game loop complete: forest -> lesson (3 phases) -> reward -> forest
+- Ready for Plan 05 (parent area already has Ctrl+Shift+E shortcut wired from prior plan)
+
+---
+*Phase: 03-komplettes-spielerlebnis*
+*Completed: 2026-03-29*