docs(02-05): complete UI integration plan - avatars, greetings, companion area
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
+10
-8
@@ -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
|
||||
|
||||
@@ -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*
|
||||
Reference in New Issue
Block a user