372 lines
13 KiB
Markdown
372 lines
13 KiB
Markdown
---
|
|
phase: 01-grundger-st-tippmechanik
|
|
plan: 05
|
|
type: execute
|
|
wave: 4
|
|
depends_on: ["01-02", "01-04"]
|
|
files_modified:
|
|
- src/ui/screens.ts
|
|
- src/forest/scene.ts
|
|
- index.html
|
|
- src/styles/main.css
|
|
- src/app.ts
|
|
autonomous: false
|
|
requirements:
|
|
- FRST-04
|
|
- FRST-05
|
|
|
|
must_haves:
|
|
truths:
|
|
- "Wald-Uebersicht zeigt Stufenkarte mit Status locked/current/completed"
|
|
- "Weiter-ueben-Button startet die naechste offene Stufe"
|
|
- "Nach Lesson-Abschluss kehrt die App zur Wald-Uebersicht zurueck und zeigt aktualisierten Status"
|
|
- "Gesamter Flow funktioniert: Welcome -> Forest -> Lesson -> Forest (mit Fortschritt)"
|
|
artifacts:
|
|
- path: "src/forest/scene.ts"
|
|
provides: "Forest overview with level map"
|
|
exports: ["initForestScreen", "renderLevelMap"]
|
|
key_links:
|
|
- from: "src/forest/scene.ts"
|
|
to: "src/storage/db.ts"
|
|
via: "loads progress to determine level statuses"
|
|
pattern: "getProgress"
|
|
- from: "src/forest/scene.ts"
|
|
to: "src/game/levels.ts"
|
|
via: "reads level definitions for the map"
|
|
pattern: "import.*levels"
|
|
- from: "src/forest/scene.ts"
|
|
to: "src/app.ts"
|
|
via: "calls startLesson when user clicks a level or continue button"
|
|
pattern: "startLesson|navigateTo"
|
|
---
|
|
|
|
<objective>
|
|
Build the forest overview screen with the level map (Stufenkarte) showing locked/current/completed states, and wire together the complete app flow: welcome -> forest -> lesson -> forest.
|
|
|
|
Purpose: This is the final integration plan that connects all pieces into a playable app. The user can see their progress and start lessons from the forest screen.
|
|
Output: Complete playable Phase 1 app with the core loop working end-to-end.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
|
|
@$HOME/.claude/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/PROJECT.md
|
|
@.planning/phases/01-grundger-st-tippmechanik/01-CONTEXT.md
|
|
@.planning/phases/01-grundger-st-tippmechanik/01-01-SUMMARY.md
|
|
@.planning/phases/01-grundger-st-tippmechanik/01-02-SUMMARY.md
|
|
@.planning/phases/01-grundger-st-tippmechanik/01-03-SUMMARY.md
|
|
@.planning/phases/01-grundger-st-tippmechanik/01-04-SUMMARY.md
|
|
@SPEC.md (section 7.1 for screen structure)
|
|
|
|
<interfaces>
|
|
From src/types.ts:
|
|
```typescript
|
|
export type LevelStatus = 'locked' | 'current' | 'completed';
|
|
export type ScreenName = 'welcome' | 'forest' | 'lesson' | 'reward' | 'parent';
|
|
export interface Progress {
|
|
id: 1;
|
|
currentLevel: number;
|
|
completedLevels: number[];
|
|
totalSessions: number;
|
|
sessionDates: string[];
|
|
selectedCharacter: CompanionType;
|
|
selectedLayout: KeyboardLayout;
|
|
}
|
|
```
|
|
|
|
From src/game/levels.ts:
|
|
```typescript
|
|
export const levels: Level[];
|
|
```
|
|
|
|
From src/app.ts:
|
|
```typescript
|
|
export function showScreen(name: ScreenName): void;
|
|
export function getDB(): IDBDatabase;
|
|
```
|
|
|
|
From src/storage/db.ts:
|
|
```typescript
|
|
export async function getProgress(db: IDBDatabase): Promise<Progress | null>;
|
|
```
|
|
</interfaces>
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Forest screen with level map and continue button</name>
|
|
<files>
|
|
src/forest/scene.ts, index.html, src/styles/main.css
|
|
</files>
|
|
<read_first>
|
|
src/types.ts
|
|
src/game/levels.ts
|
|
src/storage/db.ts
|
|
src/app.ts
|
|
src/ui/screens.ts
|
|
index.html
|
|
src/styles/main.css
|
|
</read_first>
|
|
<action>
|
|
1. Update index.html — populate forest screen:
|
|
```html
|
|
<section id="screen-forest" class="screen">
|
|
<div class="forest">
|
|
<h1 class="forest__title">Dein Zauberwald</h1>
|
|
<div class="forest__level-map" id="level-map">
|
|
<!-- Level cards rendered dynamically -->
|
|
</div>
|
|
<button class="forest__continue-btn" id="continue-btn">Weiter ueben</button>
|
|
</div>
|
|
</section>
|
|
```
|
|
|
|
2. Create src/forest/scene.ts:
|
|
```typescript
|
|
import type { Progress, LevelStatus, ScreenName } from '../types';
|
|
import { levels } from '../game/levels';
|
|
import { getProgress } from '../storage/db';
|
|
|
|
export function getLevelStatus(levelNum: number, progress: Progress): LevelStatus {
|
|
if (progress.completedLevels.includes(levelNum)) return 'completed';
|
|
if (levelNum === progress.currentLevel) return 'current';
|
|
return 'locked';
|
|
}
|
|
|
|
export function renderLevelMap(
|
|
container: HTMLElement,
|
|
progress: Progress,
|
|
onLevelClick: (level: number) => void
|
|
): void {
|
|
container.innerHTML = '';
|
|
|
|
levels.forEach(level => {
|
|
const status = getLevelStatus(level.level, progress);
|
|
const card = document.createElement('button');
|
|
card.className = `level-card level-card--${status}`;
|
|
card.dataset.level = String(level.level);
|
|
|
|
const statusEmoji = status === 'completed' ? '✓' : status === 'current' ? '→' : '🔒';
|
|
const keysDisplay = level.newKeys
|
|
.filter(k => k !== ' ')
|
|
.map(k => k.toUpperCase())
|
|
.join(' ');
|
|
|
|
card.innerHTML = `
|
|
<span class="level-card__number">Stufe ${level.level}</span>
|
|
<span class="level-card__keys">${keysDisplay}${level.newKeys.includes(' ') ? ' + Leertaste' : ''}</span>
|
|
<span class="level-card__status">${statusEmoji}</span>
|
|
`;
|
|
|
|
// Only current and completed levels are clickable
|
|
if (status !== 'locked') {
|
|
card.addEventListener('click', () => onLevelClick(level.level));
|
|
} else {
|
|
card.disabled = true;
|
|
}
|
|
|
|
container.appendChild(card);
|
|
});
|
|
}
|
|
|
|
export async function initForestScreen(
|
|
db: IDBDatabase,
|
|
onStartLesson: (level: number) => void
|
|
): Promise<void> {
|
|
const mapContainer = document.getElementById('level-map')!;
|
|
const continueBtn = document.getElementById('continue-btn') as HTMLButtonElement;
|
|
const progress = await getProgress(db);
|
|
if (!progress) return;
|
|
|
|
renderLevelMap(mapContainer, progress, onStartLesson);
|
|
|
|
// Continue button starts the current level
|
|
continueBtn.onclick = () => onStartLesson(progress.currentLevel);
|
|
}
|
|
```
|
|
|
|
3. Update src/app.ts to wire the complete flow:
|
|
- Import `initForestScreen` from `./forest/scene`
|
|
- Import `initLessonScreen` from `./ui/screens`
|
|
- In `initApp()`: after checking progress, if user exists, call `initForestScreen(db, startLesson)` before showing forest screen
|
|
- `startLesson(level)` function: show lesson screen, call initLessonScreen with onComplete callback
|
|
- `onComplete` callback: update progress (add to completedLevels, increment currentLevel if applicable, increment totalSessions, add today's date), save to DB, re-init forest screen, show forest screen
|
|
- After welcome screen's "Los geht's" navigates to forest: also call initForestScreen
|
|
|
|
The full flow is:
|
|
- First visit: Welcome -> select companion/layout -> "Los geht's" -> Forest (level 1 = current)
|
|
- Click "Weiter ueben" or level 1 card -> Lesson screen (type letters)
|
|
- Complete lesson -> Forest (level 1 = completed, level 2 = current)
|
|
- Reload -> Forest (skips welcome, shows current state)
|
|
|
|
4. Add CSS for forest and level map to src/styles/main.css:
|
|
```css
|
|
.forest {
|
|
display: flex;
|
|
flex-direction: column;
|
|
align-items: center;
|
|
padding: 2rem;
|
|
min-height: 100vh;
|
|
background: var(--bg-forest);
|
|
}
|
|
|
|
.forest__title {
|
|
font-family: 'Quicksand', sans-serif;
|
|
font-size: 2rem;
|
|
color: var(--text-dark);
|
|
margin-bottom: 1.5rem;
|
|
}
|
|
|
|
.forest__level-map {
|
|
display: grid;
|
|
grid-template-columns: repeat(3, 1fr);
|
|
gap: 1rem;
|
|
max-width: 500px;
|
|
width: 100%;
|
|
margin-bottom: 2rem;
|
|
}
|
|
|
|
.level-card {
|
|
display: flex;
|
|
flex-direction: column;
|
|
align-items: center;
|
|
gap: 0.3rem;
|
|
padding: 1rem;
|
|
border-radius: 12px;
|
|
border: 2px solid transparent;
|
|
font-family: 'Nunito', sans-serif;
|
|
cursor: pointer;
|
|
transition: transform 0.2s ease, border-color 0.2s ease;
|
|
background: white;
|
|
}
|
|
|
|
.level-card:hover:not(:disabled) {
|
|
transform: scale(1.05);
|
|
}
|
|
|
|
.level-card--current {
|
|
border-color: var(--accent-gold);
|
|
background: #FFF8E0;
|
|
box-shadow: 0 2px 8px rgba(232, 184, 75, 0.3);
|
|
}
|
|
|
|
.level-card--completed {
|
|
border-color: var(--accent-green);
|
|
background: #E8F5E4;
|
|
}
|
|
|
|
.level-card--locked {
|
|
opacity: 0.5;
|
|
cursor: not-allowed;
|
|
background: #f0f0f0;
|
|
}
|
|
|
|
.level-card__number {
|
|
font-weight: 700;
|
|
font-size: 0.9rem;
|
|
color: var(--text-dark);
|
|
}
|
|
|
|
.level-card__keys {
|
|
font-family: 'Quicksand', sans-serif;
|
|
font-weight: 600;
|
|
font-size: 1.1rem;
|
|
color: var(--accent-purple);
|
|
}
|
|
|
|
.level-card__status {
|
|
font-size: 1.2rem;
|
|
}
|
|
|
|
.forest__continue-btn {
|
|
padding: 1rem 3rem;
|
|
border-radius: 12px;
|
|
background: var(--accent-green);
|
|
color: white;
|
|
border: none;
|
|
font-family: 'Quicksand', sans-serif;
|
|
font-weight: 700;
|
|
font-size: 1.3rem;
|
|
cursor: pointer;
|
|
transition: transform 0.2s ease;
|
|
}
|
|
|
|
.forest__continue-btn:hover {
|
|
transform: scale(1.05);
|
|
}
|
|
```
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/dev/workspace/zauberwald && npx tsc --noEmit && npx vitest run</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- src/forest/scene.ts exports `initForestScreen`, `renderLevelMap`, `getLevelStatus`
|
|
- src/forest/scene.ts contains `getLevelStatus` returning 'completed', 'current', or 'locked'
|
|
- src/forest/scene.ts creates 6 level cards with class `level-card`
|
|
- src/forest/scene.ts contains `level-card--${status}` for dynamic CSS class
|
|
- index.html contains `id="level-map"` and `id="continue-btn"`
|
|
- src/app.ts calls `initForestScreen` and `initLessonScreen` in the correct flow
|
|
- src/app.ts has lesson completion handler that calls `saveProgress` with updated `completedLevels` and `currentLevel`
|
|
- src/styles/main.css contains `.level-card--current`, `.level-card--completed`, `.level-card--locked`
|
|
- src/styles/main.css contains `.forest__continue-btn`
|
|
- `npx tsc --noEmit` exits 0
|
|
- `npx vitest run` exits 0
|
|
</acceptance_criteria>
|
|
<done>Forest screen shows 6-level map with correct statuses, continue button starts current level, level cards are clickable for completed/current levels, complete app flow works end-to-end</done>
|
|
</task>
|
|
|
|
<task type="checkpoint:human-verify" gate="blocking">
|
|
<name>Task 2: Verify complete Phase 1 app flow</name>
|
|
<files>no files modified (verification only)</files>
|
|
<action>
|
|
Human verifies the complete Phase 1 app flow in the browser. No code changes in this task.
|
|
|
|
Open the app at http://vps-ip:5173 and verify these 7 steps:
|
|
|
|
1. Welcome screen: 4 companion cards with emojis and DE/CH toggle visible. Select a companion, click "Los geht's".
|
|
2. Forest overview: Level map shows Stufe 1 as current (gold border), Stufen 2-6 as locked (grayed). "Weiter ueben" button visible.
|
|
3. Click "Weiter ueben": Lesson screen appears with a large letter (F, J, or space symbol) and QWERTZ keyboard below. Target key pulses on keyboard.
|
|
4. Type the shown letter: Letter dissolves, next letter appears. Type all 8-12 letters correctly.
|
|
5. After completion: Returns to forest. Stufe 1 now shows checkmark, Stufe 2 is current (gold).
|
|
6. Reload the page: Skips welcome, goes directly to forest with preserved state.
|
|
7. Wrong key test: During a lesson, press a wrong key — nothing happens to the letter, correct key continues pulsing.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/dev/workspace/zauberwald && npx tsc --noEmit && npx vitest run && echo "ALL AUTOMATED CHECKS PASS"</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- All 7 manual verification steps pass in browser
|
|
- `npx tsc --noEmit` exits 0
|
|
- `npx vitest run` exits 0
|
|
</acceptance_criteria>
|
|
<done>Human confirmed all 7 verification steps pass: welcome flow, forest map, lesson typing, level progression, persistence across reload, correct error handling</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
- Complete flow: Welcome -> Forest -> Lesson -> Forest works
|
|
- Level map shows correct statuses after completing a level
|
|
- Typing exercise handles correct/wrong input per spec
|
|
- Progress persists across page reloads
|
|
- Keyboard shows finger colors for learned keys, gray for unlearned
|
|
- All tests pass: `npx vitest run`
|
|
- TypeScript compiles: `npx tsc --noEmit`
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
- Forest overview shows 6 levels with locked/current/completed states
|
|
- "Weiter ueben" button starts the current level's typing exercise
|
|
- After completing a lesson, level status updates correctly
|
|
- Full app loop is playable from fresh start through at least level 1 completion
|
|
- Progress survives browser reload
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/01-grundger-st-tippmechanik/01-05-SUMMARY.md`
|
|
</output>
|