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