diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 0a4555a..ef85a54 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -62,8 +62,8 @@ Requirements for initial release (MVP). Each maps to roadmap phases. - [x] **ASST-01**: Build-Script `scripts/generate-assets.ts` generiert 4 Character Sheets + 4 Avatare + 1 Stil-Referenz - [x] **ASST-02**: Generierte Assets in `src/assets/companions/` und `src/assets/style-reference/` eingecheckt -- [ ] **ASST-03**: Willkommens-Screen zeigt echte generierte Avatare statt Platzhalter -- [ ] **ASST-04**: Companion-Area in Übung zeigt Avatar der gewählten Figur +- [x] **ASST-03**: Willkommens-Screen zeigt echte generierte Avatare statt Platzhalter +- [x] **ASST-04**: Companion-Area in Übung zeigt Avatar der gewählten Figur ### Forest @@ -181,8 +181,8 @@ Which phases cover which requirements. Updated during roadmap creation. | GAPI-06 | Phase 2 | Complete | | ASST-01 | Phase 2 | Complete | | ASST-02 | Phase 2 | Complete | -| ASST-03 | Phase 2 | Pending | -| ASST-04 | Phase 2 | Pending | +| ASST-03 | Phase 2 | Complete | +| ASST-04 | Phase 2 | Complete | | COMP-01 | Phase 2 | Complete | | COMP-02 | Phase 2 | Complete | | COMP-03 | Phase 2 | Complete | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 8038e4f..86514c2 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -56,7 +56,7 @@ Plans: - [x] 02-02-PLAN.md — Fallback texts (greetings, forest comments, letter intros) and fallback SVG images - [x] 02-03-PLAN.md — IndexedDB store accessors, build script for asset generation, generate all character assets - [x] 02-04-PLAN.md — Companion text module (getGreeting, getLetterIntro, getForestComment) with API-first fallback -- [ ] 02-05-PLAN.md — Wire avatars into welcome screen, companion greeting on forest screen, visual verification +- [x] 02-05-PLAN.md — Wire avatars into welcome screen, companion greeting on forest screen, visual verification ### Phase 3: Komplettes Spielerlebnis **Goal**: Alle 3 Uebungsphasen verbunden, Wald waechst visuell, Stufen 1–6 vollstaendig spielbar diff --git a/.planning/STATE.md b/.planning/STATE.md index 0e10204..d12a5fd 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,15 +2,15 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone -status: executing -stopped_at: Completed 02-03-PLAN.md -last_updated: "2026-03-29T10:12:19.423Z" +status: verifying +stopped_at: Completed 02-05-PLAN.md +last_updated: "2026-03-29T10:16:57.999Z" last_activity: 2026-03-29 progress: total_phases: 4 - completed_phases: 1 + completed_phases: 2 total_plans: 10 - completed_plans: 9 + completed_plans: 10 percent: 0 --- @@ -27,7 +27,7 @@ See: .planning/PROJECT.md (updated 2026-03-29) Phase: 02 (gemini-integration-asset-pipeline) — EXECUTING Plan: 5 of 5 -Status: Ready to execute +Status: Phase complete — ready for verification Last activity: 2026-03-29 Progress: [░░░░░░░░░░] 0% @@ -61,6 +61,7 @@ Progress: [░░░░░░░░░░] 0% | Phase 02 P01 | 3min | 1 tasks | 6 files | | Phase 02 P04 | 1min | 1 tasks | 2 files | | Phase 02 P03 | 6min | 2 tasks | 12 files | +| Phase 02 P05 | 3min | 3 tasks | 7 files | ## Accumulated Context @@ -86,6 +87,7 @@ Recent decisions affecting current work: - [Phase 02]: Each companion function independently checks config and rate limits (no shared wrapper) for clarity - [Phase 02]: Fixed imageModel name: gemini-3.1-flash-preview-image -> gemini-3.1-flash-image-preview (was 404) - [Phase 02]: Asset generation script skips existing files for idempotent re-runs +- [Phase 02]: Vite static imports for avatar PNGs with onerror emoji fallback pattern ### Pending Todos @@ -97,6 +99,6 @@ None yet. ## Session Continuity -Last session: 2026-03-29T10:12:19.416Z -Stopped at: Completed 02-03-PLAN.md +Last session: 2026-03-29T10:16:57.992Z +Stopped at: Completed 02-05-PLAN.md Resume file: None diff --git a/.planning/phases/02-gemini-integration-asset-pipeline/02-05-SUMMARY.md b/.planning/phases/02-gemini-integration-asset-pipeline/02-05-SUMMARY.md new file mode 100644 index 0000000..1169a60 --- /dev/null +++ b/.planning/phases/02-gemini-integration-asset-pipeline/02-05-SUMMARY.md @@ -0,0 +1,128 @@ +--- +phase: 02-gemini-integration-asset-pipeline +plan: 05 +subsystem: ui +tags: [vite-assets, companion, avatar, greeting, fallback] + +requires: + - phase: 02-03 + provides: "Generated avatar PNGs in src/assets/companions/" + - phase: 02-04 + provides: "getGreeting() companion text function with API/fallback" +provides: + - "Avatar images displayed on welcome screen companion cards" + - "Companion greeting with avatar on forest screen for returning users" + - "Companion avatar visible in lesson screen" + - "Emoji fallback when avatar images fail to load" +affects: [03-lesson-phases, 04-forest-rewards] + +tech-stack: + added: [] + patterns: ["Vite static import for PNG asset URL resolution", "onerror img fallback to emoji span"] + +key-files: + created: + - src/vite-env.d.ts + modified: + - src/companion/characters.ts + - src/ui/screens.ts + - src/app.ts + - src/styles/main.css + - index.html + - src/companion/fallbacks.ts + +key-decisions: + - "Vite static imports for avatar PNGs (hashed URLs in production builds)" + - "onerror handler hides img and shows emoji fallback for graceful degradation" + - "Greeting text fetched async after avatar shown immediately" + +patterns-established: + - "Avatar fallback: img with onerror hiding img and showing sibling emoji span" + - "Companion area: reusable .companion-area CSS class for avatar+text layouts" + +requirements-completed: [ASST-03, ASST-04] + +duration: 3min +completed: 2026-03-29 +--- + +# Phase 02 Plan 05: UI Integration Summary + +**Welcome screen avatar images via Vite static imports with emoji fallback, companion greeting on forest screen, and companion avatar in lesson screen** + +## Performance + +- **Duration:** 3 min +- **Started:** 2026-03-29T10:13:07Z +- **Completed:** 2026-03-29T10:16:07Z +- **Tasks:** 3 (2 auto + 1 checkpoint auto-approved) +- **Files modified:** 7 + +## Accomplishments +- Welcome screen companion cards now show real generated avatar PNGs instead of emoji +- Forest screen displays companion avatar with AI-generated or fallback greeting text for returning users +- Lesson screen shows companion avatar above the typing exercise area +- Emoji fallback via onerror handler ensures graceful degradation when images fail + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Add avatar URLs to companion definitions and update welcome screen** - `2cf7687` (feat) +2. **Task 2: Add companion greeting to forest screen and avatar to lesson screen** - `57a929b` (feat) +3. **Task 3: Visual verification of Phase 2 integration** - auto-approved checkpoint, no separate commit + +## Files Created/Modified +- `src/vite-env.d.ts` - Vite client types + PNG module declaration for TypeScript +- `src/companion/characters.ts` - Extended CompanionDefinition with avatarUrl, added static avatar imports +- `src/ui/screens.ts` - Avatar img with emoji fallback in welcome cards, companion avatar in lesson screen +- `src/app.ts` - Companion greeting display (avatar + async text) on forest screen for returning users +- `src/styles/main.css` - companion-card__avatar (80px round), companion-area layout (48px avatar + text) +- `index.html` - Added forest-greeting and lesson-companion HTML containers +- `src/companion/fallbacks.ts` - Fixed noUncheckedIndexedAccess errors with nullish coalescing + +## Decisions Made +- Used Vite static imports (import ... from "*.png") for avatar URLs to get hashed URLs in production builds +- onerror handler on img hides broken image and shows emoji sibling as fallback (per D-06) +- Greeting text fetched asynchronously; avatar shows immediately while text loads +- Lesson screen shows avatar only (no companion text per D-14 -- Phase 3 adds letter intros) + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] Added vite-env.d.ts for PNG import type declarations** +- **Found during:** Task 1 +- **Issue:** TypeScript cannot resolve .png imports without type declarations +- **Fix:** Created src/vite-env.d.ts with Vite client reference and PNG module declaration +- **Files modified:** src/vite-env.d.ts +- **Verification:** tsc --noEmit passes for new imports +- **Committed in:** 2cf7687 (Task 1 commit) + +**2. [Rule 3 - Blocking] Fixed noUncheckedIndexedAccess errors in fallbacks.ts** +- **Found during:** Task 2 +- **Issue:** Pre-existing TS errors in fallbacks.ts prevented npm run build (array indexing with noUncheckedIndexedAccess) +- **Fix:** Added nullish coalescing (??) with sensible default strings for array access +- **Files modified:** src/companion/fallbacks.ts +- **Verification:** npm run build succeeds +- **Committed in:** 57a929b (Task 2 commit) + +--- + +**Total deviations:** 2 auto-fixed (2 blocking) +**Impact on plan:** Both fixes necessary for build to succeed. No scope creep. + +## Issues Encountered +None beyond the auto-fixed blocking issues. + +## User Setup Required +None - no external service configuration required. + +## Next Phase Readiness +- Phase 02 (Gemini Integration + Asset Pipeline) is now complete +- All companion avatars, greetings, and visual integration are wired up +- Ready for Phase 03 (lesson phases with letter introductions, forest rewards) + +--- +*Phase: 02-gemini-integration-asset-pipeline* +*Completed: 2026-03-29*