From 4538f392ef5fe7b915a35a4ab868159f72347a59 Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Sun, 29 Mar 2026 12:12:30 +0200 Subject: [PATCH] docs(02-03): complete asset generation and DB accessors plan - SUMMARY: 6 IndexedDB accessors + 9 generated assets via Gemini API - STATE: advance to plan 4/5, 90% progress - ROADMAP: update phase 02 plan progress - REQUIREMENTS: mark ASST-01, ASST-02 complete Co-Authored-By: Claude Opus 4.6 (1M context) --- .planning/REQUIREMENTS.md | 8 +- .planning/ROADMAP.md | 2 +- .planning/STATE.md | 15 +- .../02-03-SUMMARY.md | 129 ++++++++++++++++++ 4 files changed, 143 insertions(+), 11 deletions(-) create mode 100644 .planning/phases/02-gemini-integration-asset-pipeline/02-03-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 952fac7..0a4555a 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -60,8 +60,8 @@ Requirements for initial release (MVP). Each maps to roadmap phases. ### Assets -- [ ] **ASST-01**: Build-Script `scripts/generate-assets.ts` generiert 4 Character Sheets + 4 Avatare + 1 Stil-Referenz -- [ ] **ASST-02**: Generierte Assets in `src/assets/companions/` und `src/assets/style-reference/` eingecheckt +- [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 @@ -179,8 +179,8 @@ Which phases cover which requirements. Updated during roadmap creation. | GAPI-04 | Phase 2 | Complete | | GAPI-05 | Phase 2 | Complete | | GAPI-06 | Phase 2 | Complete | -| ASST-01 | Phase 2 | Pending | -| ASST-02 | Phase 2 | Pending | +| ASST-01 | Phase 2 | Complete | +| ASST-02 | Phase 2 | Complete | | ASST-03 | Phase 2 | Pending | | ASST-04 | Phase 2 | Pending | | COMP-01 | Phase 2 | Complete | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 14939ed..8038e4f 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -54,7 +54,7 @@ Plans: Plans: - [x] 02-01-PLAN.md — Config loader, Gemini API client (text + image), retry logic, rate-limiting (TDD) - [x] 02-02-PLAN.md — Fallback texts (greetings, forest comments, letter intros) and fallback SVG images -- [ ] 02-03-PLAN.md — IndexedDB store accessors, build script for asset generation, generate all character assets +- [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 diff --git a/.planning/STATE.md b/.planning/STATE.md index 5ca2c39..0e10204 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 02-04-PLAN.md -last_updated: "2026-03-29T10:06:43.421Z" +stopped_at: Completed 02-03-PLAN.md +last_updated: "2026-03-29T10:12:19.423Z" last_activity: 2026-03-29 progress: total_phases: 4 completed_phases: 1 total_plans: 10 - completed_plans: 8 + completed_plans: 9 percent: 0 --- @@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-03-29) ## Current Position Phase: 02 (gemini-integration-asset-pipeline) — EXECUTING -Plan: 4 of 5 +Plan: 5 of 5 Status: Ready to execute Last activity: 2026-03-29 @@ -60,6 +60,7 @@ Progress: [░░░░░░░░░░] 0% | Phase 02 P02 | 2min | 2 tasks | 8 files | | Phase 02 P01 | 3min | 1 tasks | 6 files | | Phase 02 P04 | 1min | 1 tasks | 2 files | +| Phase 02 P03 | 6min | 2 tasks | 12 files | ## Accumulated Context @@ -83,6 +84,8 @@ Recent decisions affecting current work: - [Phase 02]: Image generation no retry (expensive), text retries 3x exponential backoff - [Phase 02]: Config loader caches after first fetch, resetConfigCache() for testing - [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 ### Pending Todos @@ -94,6 +97,6 @@ None yet. ## Session Continuity -Last session: 2026-03-29T10:06:43.414Z -Stopped at: Completed 02-04-PLAN.md +Last session: 2026-03-29T10:12:19.416Z +Stopped at: Completed 02-03-PLAN.md Resume file: None diff --git a/.planning/phases/02-gemini-integration-asset-pipeline/02-03-SUMMARY.md b/.planning/phases/02-gemini-integration-asset-pipeline/02-03-SUMMARY.md new file mode 100644 index 0000000..56ad50d --- /dev/null +++ b/.planning/phases/02-gemini-integration-asset-pipeline/02-03-SUMMARY.md @@ -0,0 +1,129 @@ +--- +phase: 02-gemini-integration-asset-pipeline +plan: 03 +subsystem: assets +tags: [gemini, image-generation, indexeddb, tsx, character-sheets, avatars] + +# Dependency graph +requires: + - phase: 02-01 + provides: "Gemini API wrapper (generateImage, generateText) and config loader" +provides: + - "6 IndexedDB accessor methods for companionAssets, styleReference, forestElements stores" + - "Asset generation build script (scripts/generate-assets.ts)" + - "4 character sheets, 4 avatars, 1 style reference — 9 PNG files total" +affects: [02-04, 02-05, 03-companion-integration] + +# Tech tracking +tech-stack: + added: [tsx] + patterns: [build-script-asset-generation, blob-to-buffer-conversion] + +key-files: + created: + - scripts/generate-assets.ts + - src/assets/companions/fee-lila/character-sheet.png + - src/assets/companions/fee-lila/avatar.png + - src/assets/companions/einhorn-stella/character-sheet.png + - src/assets/companions/einhorn-stella/avatar.png + - src/assets/companions/fuchs-finn/character-sheet.png + - src/assets/companions/fuchs-finn/avatar.png + - src/assets/companions/eule-elsa/character-sheet.png + - src/assets/companions/eule-elsa/avatar.png + - src/assets/style-reference/initial-forest-scene.png + modified: + - src/storage/db.ts + - package.json + +key-decisions: + - "Fixed imageModel name from gemini-3.1-flash-preview-image to gemini-3.1-flash-image-preview" + - "Script skips already-generated assets for re-runnability" + - "2-second delay between API calls to avoid rate limiting" + +patterns-established: + - "Build scripts use tsx for Node.js TypeScript execution" + - "Asset generation reads config from public/config.json via fs.readFileSync" + - "Character avatars use character sheets as reference images for visual consistency" + +requirements-completed: [ASST-01, ASST-02] + +# Metrics +duration: 6min +completed: 2026-03-29 +--- + +# Phase 02 Plan 03: Asset Generation Summary + +**IndexedDB store accessors + Gemini-powered build script generating 4 character sheets, 4 avatars, and 1 style reference image** + +## Performance + +- **Duration:** 6 min +- **Started:** 2026-03-29T10:04:23Z +- **Completed:** 2026-03-29T10:10:30Z +- **Tasks:** 2 +- **Files modified:** 12 + +## Accomplishments +- Added 6 IndexedDB accessor methods (save/get for companionAssets, styleReference, forestElements) +- Created build script that calls Gemini API to generate character sheets with 3 views (front, side, face) and matching avatars +- Generated all 9 PNG assets: 4 character sheets, 4 avatars, 1 style reference (initial forest scene) +- Script is re-runnable (skips existing assets) with graceful error handling + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Add IndexedDB accessor methods for remaining stores** - `a242ce1` (feat) +2. **Task 2: Build script for asset generation + run it** - `1fa7d52` (feat) + +## Files Created/Modified +- `src/storage/db.ts` - Added saveCompanionAssets, getCompanionAssets, saveStyleReference, getStyleReference, saveForestElement, getForestElements +- `scripts/generate-assets.ts` - Build script reading config.json, calling Gemini API, saving 9 PNGs +- `package.json` - Added tsx devDependency and generate-assets npm script +- `src/assets/companions/*/character-sheet.png` - Character sheets (3-view: front, side, face) for all 4 companions +- `src/assets/companions/*/avatar.png` - Portrait avatars for all 4 companions +- `src/assets/style-reference/initial-forest-scene.png` - Watercolor forest clearing style reference + +## Decisions Made +- Fixed imageModel name in config.json (gemini-3.1-flash-preview-image was 404, corrected to gemini-3.1-flash-image-preview) +- Script skips already-generated assets (checks file existence + size > 1KB) for idempotent re-runs +- Added 2-second delay between API calls to respect rate limits +- Avatar generation uses character sheet as reference image for visual consistency + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Fixed incorrect image model name in config.json** +- **Found during:** Task 2 (running generate-assets script) +- **Issue:** Model name `gemini-3.1-flash-preview-image` returns 404; correct name is `gemini-3.1-flash-image-preview` +- **Fix:** Updated public/config.json imageModel field +- **Files modified:** public/config.json (gitignored) +- **Verification:** API returns 200 and generates images successfully +- **Committed in:** Not committed (file is gitignored), but documented for user awareness + +--- + +**Total deviations:** 1 auto-fixed (1 bug) +**Impact on plan:** Essential fix for API connectivity. No scope creep. + +## Issues Encountered +- Gemini API returned 404 for the configured imageModel name. Resolved by listing available models and correcting the name. + +## User Setup Required +None - Gemini API key already configured in public/config.json from Phase 1 setup. + +## Next Phase Readiness +- All character assets generated and committed to git +- IndexedDB store accessors ready for runtime use +- Style reference image available for consistent art direction in future forest element generation +- Ready for Plan 04 (companion integration) and Plan 05 (forest reward pipeline) + +## Self-Check: PASSED + +All 10 created files verified present. Both task commits (a242ce1, 1fa7d52) verified in git log. + +--- +*Phase: 02-gemini-integration-asset-pipeline* +*Completed: 2026-03-29*